This is a draft document. It is a work in progress.

PlaceHolder Server

Overview

The Placeholder Server provides a SERVICE to allow third-party Application Servers to notify their Web Apps that an event has occurred and action may be required. The nature of this action will be defined by the app receiving the notification.

The Placeholder Server is MINIMALIST. Setting up your own server should be a simple operation*. Because it runs over HTTP/Websockets, endpoints can be controlled by the user. (*offer of simplicity may not apply for connecting to proprietary networks, e.g. cell phones)

The Placeholder Server is HIGH-CAPACITY. Each machine can handle hundreds of thousands of connected accounts and thousands of messages a second.

The Placeholder Server is SCALABLE. Capacity can be increased in near-linear fashion by the addition of more machines.

The Placeholder Server is AGNOSTIC. It does not validate the user or the channel. Any ping sent into the system will be accepted and made available to a client listening on that channel.

The Placeholder Server is BEST EFFORT. It will do what it can to deliver the ping, and will succeed the vast majority of the time. If the ping is currently undeliverable, it will cache it for the next time the client checks in. However, if disaster strikes, it is possible an attention ping will be lost.

The Placeholder Server is TRANSIENT. Pings that have not been delivered after a configurable time (likely 36 hours) will be discarded.

The Placeholder Server is NONLINEAR. The order of pings through a channel is irrelevant and nonsequential. The client can tell that there is something that needs attention by the presence of the ping, not the contents of it. Normally, however, the value in the ping will be different from the previous value, to optimize for duplicate delivery. However, this is handled by the Application Server and is not guaranteed.

The Placeholder Server is NONACCUMULATIVE. If two pings come in for the same channel while the client is disconnected, only one of those pings will eventually be delivered. No guarantee is made as to which it is (see NONLINEAR).

The Placeholder Server is OPAQUE. Only the user will have knowledge of the UAID. The Application Server will be pushing data to an endpoint that does not allow them to divine information about a user beyond the specific endpoint channel.

Why "PlaceHolder Server"?

placeholder is a temporary name while this document is being edited in order to prevent Wiki conflicts.

In order to scale easily, a system should require the least amount of data necessary. While it would be ideal that there be no data exchanged, we realized that having a tiny amount would not alter the overall design or change the desired behaviors.

And "Version Control System" had baggage issues of it's own.

Project Contacts

Principal Point of Contact - Doug Turner dougt@mozilla

IRC - #channel

Group Email - TBD

Goals

Apps need to know when something happens on their servers. One way to do that is to poll relentlessly back to their servers. The problem with that is that with each app performing it's own poll, you can wind up with a tremendous amount of traffic, all consisting of "Anything yet?" "Nope."

In addition, an App Server may wish to notify an App of an event or action and not be able to send a message directly to the App or device.

To accomplish this, App Servers can send Version Events to Apps. A Version event is a simple, fire and forget "ping" style event that the PlaceHolder Server will make a best effort to deliver to the App.

There are a few Caveats that should be stated:

Version Events are lossy.
- A Version Event may expire before reaching the App. (You probably don't care about a traffic accident that happened a week ago.)
- A Version Event may be lost due to intermediary server error.
- The App should reconnect with the App Server in order to provide positive confirmation of an Event, the App Server may retry sending an Event to the App if this confirmation does not occur.
- While best effort will be made to reduce the possibility, an App may receive the same or only slightly different Version Event in rapid succession. It is advised that the App and App Server use a method to only act on the highest Version.
Version Events, and the information around them are not encrypted. Since this is a low information system, it is strongly encouraged that information that requires security ONLY be exchanged between the App and the App Server using properly secure methods.
Endpoints may be used to identify individual users. Since the service's role is to alert apps to connect back to the AppServer (and thus expose additional info such as the IP address, MAC, and any account info), it was felt that this is should not surprise users and implementers.

Use Cases

An App wishes to be notified when new email arrives. A User installs an App on a mobile device which notifies her when someone adds a note to her bulletin board. The App calls the Registration function, which returns an EndPoint. The App sends the EndPoint to the AppServer using the magic of "Not-Part-Of-This-Protocol". The AppServer stores the EndPoint in the User's information. When a new note is added, the AppServer fetches the EndPoint and PUTs a new version value to it. This alerts PlaceHolderServer Client, which wakes the App and sends a version event via a registered callback. This causes the App to refresh it's messages (again using the magical "Not-Part-Of-This-Protocol" system), and User gets a screen full of adorable kittens.

An AppServer wishes to notify Apps of an update. Since a server doesn't want to be deluged by millions of pings from devices every hour, the developers wisely decide to opt for a Push mechanism. Much like the other example, an App registers with PlaceHolderServer, gets an EndPoint which it relays to AppServer. AppServer then PUTs a '000' version to the EndPoint which triggers an "update" event for the App, which silently acknowledges that all is well. At some later time, AppServer PUTs '001' to the EndPoint which PlaceHolderServer relays to App which then updates itself using "Not-Part-Of-This-Protocol-Either".

An incoming request from a WebRTC . Bob uses Ringo’s STAR webrtc service. Bob is using the Desktop browser, but the tab/window isn't open to the Ringo service. Alice makes a webrtc call from work to Bob. Bob sees a notification about an incoming call.

Additional potential scenarios to consider

Kenji works at a powerplant located on the Eastern Shore of an island country. He has set up a service that sends him alerts when the wave levels have increased above a certain threshold. His vacation home is located in a section of town supported by only two cell towers, and is constructed using Stucco walls and a steel roof, which greatly impedes the level of signal that he can receive. His phone may be 4G in his living room, but step down to 3g in the hallway, and only 1x in his office. It's rather important that he receive the alerts indicating that wave levels have begun increasing.

Alice is traveling from Brazil to America. An unexpected storm delays her connections forcing her to overnight in a location with no network or cell access. When she lands, she turns on her phone and connects to the first available network that provides data. Unfortunately, this network routes traffic to an authorization server until she agrees to the network terms, then provides minimal connection capacities. While connecting back to her home server, the connection is proxied and limited to only well known TCP ports, slow and routinely drops providing only partial results to the client.

Definitions

ACK: An acknowledgement message.
APP SERVER: A possibly third party provided server that provides information to the APP. The originator of VERSION EVENTS.
APP: A possibly third party provided Web Application located on a remote User Agent. The end consumer of VERSION EVENTS.
APPID: A globally unique identifier for a given App.
PLACEHOLDER CLIENT: The application or library that acts as the intermediary between the APP and the PLACEHOLDER SERVER. This provides the APP with VERSION EVENT callbacks.
PLACEHOLDER SERVER: The application or library that acts as the intermediary between the APP SERVER and the PLACEHOLDER CLIENT. This provides ENDPOINTs for the APP SERVER.
ENDPOINT: A URL which accepts VERSION updates to trigger eventual APP VERSION EVENT.
UAID: A globally unique identifier for a given User Agent.
VERSION EVENT: A request from APP SERVER to notify an APP to take action.

Requirements

File:EditionServerDiagram.pdf A diagram of the PlaceHolderServer interaction points.

APP requests an ENDPOINT from the PLACEHOLDER CLIENT and shall register two callback functions, one for receipt of the ENDPOINT, and a second for handling of a VERSION EVENT
If not already present, PLACEHOLDER CLIENT shall generate a unique UUID4 Identifier for the UserAgent (UAID)
PLACEHOLDER CLIENT shall generate a unique UUID4 Identifier for the APP (APPID)
PLACEHOLDER CLIENT shall send UAID, APPID and any additional information required for proprietary KICK to the PLACEHOLDER SERVER
PLACEHOLDER SERVER shall create an ENDPOINT for the UAID and APPID and return it to the PLACEHOLDER CLIENT.
If a KICK driver is present, PLACEHOLDER SERVER shall relay appropriate PLACEHOLDER CLIENT provided information to the KICK driver.
PLACEHOLDER CLIENT tenders the ENDPOINT to APP via callback.
APP is responsible for sending ENDPOINT to the APP SERVER via out of protocol specified means.
On VERSION EVENT, APP SERVER PUTs to the ENDPOINT
1. VERSION values are NOT transmitted through the system and only act as a trigger.
If a PLACEHOLDER CLIENT is currently connected to APP SERVER, APP SERVER relays an UPDATE containing currently pending VERSION EVENTS.
1. Version data commits and possible publication through the server must be performed in less than 5 seconds.
If a PLACEHOLDER CLIENT is NOT currently connected, an optional, proprietary KICK driver may be called to wake devices associated with the corresponding ENDPOINT UAID.
If a PLACEHOLDER SERVER is unable to immediately deliver a VERSION EVENT, the VERSION EVENT is logged to short term storage.
PLACEHOLDER CLIENT connects to the PLACEHOLDER SERVER and shall identify a list of one or more UAIDs it is responsible for.
If there are VERSION EVENTS pending for requested UAIDs, PLACEHOLDER SERVER sends an UPDATE packet
If no VERSION EVENTS are pending for the requested UAIDs, PLACEHOLDER SERVER may return a status indicating no data available (for REST implementations) or simply not return content (for WebSocket)
During the transmission of the UPDATE, a PLACEHOLDER SERVER may wish to return a 503 (Service Unavailable) error to APP SERVERS for any VERSION EVENT associated with an in progress UAID, so as to prevent potential race conditions.
On receipt of UPDATE, PLACEHOLDER CLIENT shall return an ACK to the PLACEHOLDER SERVER.
1. The ACK shall contain a list of UAIDs for which all APPIDs have been properly received.
2. Version information associated with a non-expired User Agent record is not discarded until acknowledged by the client.
The PLACEHOLDER CLIENT shall then notify APPs of the VERSION EVENT using the appropriate callback
User Agent record (including associated channels and version information) that have not been accessed during an "active use" period, may be dropped by the PLACEHOLDER SERVER
1. An unknown (or garbage collected) user agent record would need to re-register with PLACEHOLDER SERVER as if this is an initial connection.
Clients are the source of truth for the associated channels.
1. Channel discrepancies between the client and the server result in the server sending a request to client to reset.
  1. TODO: Details on what a reset entails needed
UAIDs may be a globally unique 128 bit number
APPIDs are unique per UAID namespace
ENDPOINTs are Globally Unique
Data must be stored and managed in a highly responsive manner (low read/write latency)
PLACEHOLDER SERVER should support 1MM+ number of simultaneously connected clients
Connections should maintain as long as possible. A server should not break a connection because it's gone idle.
A PLACEHOLDER SERVER should attempt to retry a failed transmission to the client every 60 seconds.

NOTE: a PLACEHOLDER RELAY may be created by combining the polling aspects of the PLACEHOLDER CLIENT with the data management and KICK driver of the PLACEHOLDER SERVER. This would allow a VERSION EVENT system to enter protected networks or use restricted means to communicate to USER AGENTs. It is important to note that once a PLACEHOLDER SERVER has received an ACK for a given UAID, the PLACEHOLDER SERVER is under no obligation to retain that data, and proper relay of the VERSION EVENT is the PLACEHOLDER RELAY's problem.

Get Involved

Call to action for folks who want to help.

Design

Points of Contact

Server Engineer - JR Conlin jrconlin@mozilla Client Engineer -

API Reference/Documentation

Data Schema

Local storage is best determined by the implementation.

For Mozilla, we are considering using Memcache and keeping the version information as simple key/value pairs,

UAID => APPID:VERSION,...

API

How to call the data

method URI

description

Arguments argument descriptions
Returns: returned contents

Platform Requirements

What are the things this needs (OS, language, databases, etc.)?

Libraries Required

<i> List of external project dependencies. (Stuff that's not pulled in via the installation script)

Code Repository

Links to the published code bases

Release Schedule

Predicted code delivery dates

QA

Points of Contact

Engineer - Name contact@info

Test Framework

Security and Privacy

Fill out the security & privacy bug template: https://bugzilla.mozilla.org/form.moz-project-review (https://wiki.mozilla.org/Websites/Kick-Off_Form)

CloudServices/Roadmaps/EditionServer

Contents

PlaceHolder Server

Overview

Why "PlaceHolder Server"?

Project Contacts

Goals

Use Cases

Definitions

Requirements

Get Involved

Design

Points of Contact

API Reference/Documentation

Data Schema

API

method URI

Platform Requirements

Libraries Required

Code Repository

Release Schedule

QA

Points of Contact

Test Framework

Security and Privacy

Points of Contact

Questionnaire Answers

1.1 Goal of Feature

2. Potential Threat Vectors and Mitigation Points

Review Status

Issues and Resolutions

Operations

Points of Contact

Deployment Architecture

Escalation Paths

Lifespan Support Plans

Logging and Metrics

Points of Contact

Tracking Element Definitions

Data Retention Plans

Dashboard URL

Customer Support

Points of Contact

Sumo Tags

Review Meeting

Navigation menu

Search