Loop/Architecture/Rooms

Based on early user feedback, we will be adding a "rooms" metaphor to the Loop product. Initially, this will be based on a "link as a room" model, although we will likely explore link-free rooms experiences for logged-in users in the future.

Many of the network operations required for rooms are very similar to those we currently use for link-based calling (that is, the "/call-url" and "/calls" endpoints). However, the parameters and behaviors are sufficiently different that re-using those codepaths would have caused more confusion and work than simply defining new ones. However, the conceptual model that developers have around how these endpoints work can be useful in understanding the rooms design.

Also in the case of Rooms there is no such thing as a call, rooms are always open so that people can enter them at any times.

Consequently, the network API for rooms uses the "/rooms" endpoint. Note, however, that no websockets connection is necessary, as call progress information is not conveyed.

Similar to the call-url design, users can generate rooms both when logged in to FxA and when not logged in.

Note that we do not want to remove the link-based calling functionality from the server at this point. Potential future use-cases include things like "click to call" URLs associated with small and medium businesses. The existing link-based calling functions will be important for implementing this and similar use cases.

Date	Author	Changes
Wed Sep 10 16:07:58 CDT 2014	Adam Roach	Initial version
Thu Sep 11 19:28:32 UTC 2014	Adam Roach	Updates after initial feedback: now uses multiple push URLs. Renamed "operation" to "action" to be consistent with other loop-server endpoints.
Tue Sep 23 16:23:51 CEST 2014	Rémy Hubscher	Merge /rooms and /room-url endpoints since they describe the same /rooms concept. i.e: We don't have multiple rooms for the same /room-url as we have multiple /calls for the same /call-url
Thu Sep 25 16:07:42 CEST 2014	Alexis Métaireau	Rename PUT /rooms/:token into PATCH /rooms/:token.
Wed Oct 1 14:55:42 CEST 2014	Rémy Hubscher	Add the ctime parameter on GET /rooms/:token.
Thu Oct 2 16:32:42 CEST 2014	Rémy Hubscher	Improve the notification description.
Thu Oct 3 16:32:42 CEST 2014	Alexis Métaireau	Use Numbers instead of Strings in JSON outputs / inputs.
Mon Oct 6 14:51:52 UTC 2014	Adam Roach	Added room URL to GET /rooms and GET /rooms/:token
Thu Oct 9 15:40:15 UTC 2014	Adam Roach	Added sessionToken to "action: refresh" and "action: leave" operations for correlation and auth.
Wed Oct 22 15:16:38 UTC 2014	Adam Roach	Modifications based on discussion in bug 1074665: list of rooms now contains the same information as is indicated when retrieving a single room directly. Additionally, when getting a versioned list of rooms, any rooms that have been deleted since the indicated version will be listed, with a "deleted: true" field.
Mon Dec 29 16:55:10 UTC 2014	Rémy Hubscher	Proposal to handle bug 1106562: Multiple rooms deletion in one HTTP call.

Mapping to TokBox Concepts

The TokBox toolkit is based on a model of indestructible sessions (identified by a Session ID), which clients join by being issued session tokens, which expire after a predetermined period of time. API-wise, sessions are designed to support an arbitrary number of participants.

The rooms implementation will map each Loop room to a single session, which is created when the room is first created. Once a room is created, this room-to-session binding will remain constant throughout the lifetime of the room.

Each time a user joins a room, he will be issued a new session token to do so. If a user leaves a room and re-joins, he is issued a new token.

User Identification in a Room

When the Loop server generates a new token for a user, it optionally includes a "data" field. This field is then communicated to other participants in the room when the corresponding user joins the room: the ConnectionEvent on Session contains a Connection object, which includes a "data" field. This is the same "data" as was provided by the server when the token was created.

The Loop server, when generating a token for a user in a room, will set the contents of the "data" field to a JSON string, containing the following information:

{
    "displayName": "Alexis",
    "account": "alexis@example.com",
    "roomConnectionId": "2a1787a6-4a73-43b5-ae3e-906ec1e763cb"
}

• displayName - The user-friendly name that should be displayed for this participant
• account - If the user is logged in, this is the FxA account name or MSISDN that was used to authenticate the user for this session
• roomConnectionId - An id, unique within the room for the lifetime of the room, used to identify a participant for the duration of one instance of joining the room. If the user departs and re-joins, this id will change. Note that this document uses a UUID in its examples, since they can be used in this fashion without having to store additional state; however, anything that is unique within a room for its entire lifetime (e.g., a constantly increasing integer) would be suitable as well.

Room Size Handling

For the initial release of room, clients are expected to handle only two participants per room. However, to allow for a smooth transition to multiparty rooms, this interface is being designed to accommodate rooms with an arbitrary number of participants.

When rooms are initially created, the creator will specify the maximum number of participants supported by the room at any given time. The Loop server is responsible for tracking the number of users in a room, and for declining to issue new tokens once the room has reached capacity.

Additionally, due to device constraints (as well as due to the potential to have multiple versions of the client deployed simultaneously), it is possible in the future to have clients that support fewer participants in a room than the room has been configured to support. To deal with this situation, when a client attempts to join a room, it includes the maximum number of participants it is capable of handling at one time. When determining whether to admit a new user, the Loop server takes into consideration both the configured room maximum size and the client capabilities of those clients currently in (and attempting to join) the session.

For example: consider a server configured to support up to 4 users.

1. A first user joins with a client that supports up to 3 users. His presence temporarily reduces the room capacity to 3.
2. A second user joins with a client that supports up to 3 clients. The server admits this user, since the room is not yet full.
3. A third user attempts to join, but indicates the ability to support only two users. The third user is refused entry, since his joining would reduce the supported capacity to two, but result in a total of three users.
4. The second user departs, leaving only the first user in the room.
5. The third user reattempts joining. His presence temporarily reduces the room capacity to 2. He is admitted, and the room now contains two users.
6. The second user attempts to rejoin. Since the room capacity is temporarily reduced to 2, he is refused entry.
7. The third user departs, and the room capacity returns to 3.
8. The first user departs. The room is empty, so its capacity returns to the configured value of 4.

When communicating room sizes to clients, we indicate these values as "maxSize" (for the configured maximum), and "clientMaxSize" (for the largest value that can be currently supported due to the capabilities of the clients participating in the room).

Room Membership and Soft State

In order to track the number of users in a session, the Loop server needs to be kept up-to-date with the list of current participants. This means that client will explicitly indicate to the server when they are departing a session (and whenever they experience a detectable failure locally). The server will add users to the list of room participants as they join, and remove them as they depart.

However, to avoid circumstances in which clients depart unexpectedly (e.g. crashes, loss of network connectivity) from keeping them in the list of room participants, we need to employ a soft-state mechanism. Once a client joins a room, it need to periodically contact the Loop server to indicate that it is still a member of that room. If the client goes significantly longer than expected to perform this periodic action, they are considered to be no longer part of the session, and are removed from the participant list.

This scheme works as follows: when a user initially joins a room (using "POST /rooms/{token}"), the response indicates an expiration time, measured in seconds, during which the client must perform another POST to the same "/rooms/{token}" endpoint. If this number of seconds (plus some grace period, on the order of 30 seconds) passes without a subsequent POST, then the user is removed from the list of participants.

This refresh period is communicated by the server each time it receives a POST. The duration selected for this refresh period is a trade-off between server load and responsiveness to users departing unexpectedly. While it is initially anticipated that the value will be a static configuration, the server may choose to adjust it dynamically based on server load (thus providing rapid recovery when it has the capacity to do so, but shedding load when necessary during periods of heavy use).

The suggested period for this timer for initial deployment is 600 seconds (10 minutes).

Note that the server does not need to proactively track timeouts to make this scheme work. The following would work just fine:

1. When a user joins, store a "must refresh by" time (say, 10 minutes in the future) after which they are no longer considered part of the conference.
2. Every time a user does a refresh, update this time.
3. Whenever someone performs an action that relies on the list of (or number of) users in the room, check whether any have a "must refresh by" time in the past. If so, remove them from the room before producing the result.

Removing Participants from a Room

When the server generates a session participant token, it can also select a participant role. When creating a token for the room owner, the server must include a "role" of "moderator," which will allow the room owner to remove participants from rooms.

To remove a user from a room, the owner then uses the forceDisconnect method on the Sessionto remove a user from the room. Upon receiving a disconnection event for their own connection with a reason of "forceDisconnect," the removed client will remove himself from the session by calling POST /rooms/{token}.

Room Owner Notification

When the status of a room changes (e.g., a user joins or leaves, a room is created or deleted), the Loop server will cause a notification to be sent to the room owner by way of a push notification. This will helps to have a consistent room list on the owner devices.

The room owners' client can then retrieve a list of the users' rooms (that is, all those rooms that have changed on or after the indicated version), and take appropriate action. For the current UX, these actions include an unobtrusive audio notification when a user joins a room as well as a count of users and rooms waiting for the owner to join.

Note: The push notification needs to be sent whenever the output of GET /rooms would be different. This includes operations such as: user joins a room, user leaves a room, new room is created, and existing room is deleted.

To avoid performing a slew of queries whenever a push notification arrives, transitioning to a rooms model will also necessitate storing different push server endpoints for different events. Otherwise, for a logged in user, arrival of a push notification would result in four separate HTTP operations towards the Loop server:

1. A request to GET /calls?version=<version> for non-account-associated calls (although note that these will be going away shortly)
2. A request to GET /calls?version=<version> for FxA calls
3. A request to GET /rooms?version=<version> for non-account-associated calls
4. A request to GET /rooms?version=<version> for FxA calls

This necessitates a small handful of changes on the client side; in particular:

MozLoopPushHandler needs to be updated to store an array of channelIDs, and turn any per-channel attributes into objects keyed on the channel ID. At the class level:

 FXA_CALLS:   "25389583-921f-4169-a426-a4673658944b",
 FXA_ROOMS:   "6add272a-d316-477c-8335-f00f73dfde71",
 GUEST_CALLS: "801f754b-686b-43ec-bd83-1419bbf58388",
 GUEST_ROOMS: "19d3f799-a8f3-4328-9822-b7cd02765832",
 channelIDs: [this.FXA_CALLS, this.FXA_ROOMS, this.GUEST_CALLS, this.GUEST_ROOMS],
 pushUrls: {},
 registered: {},

_onRegister needs to update the handling of successful channel registrations:

 this.registered[msg.channelID] = true;
 if (this.pushUrl[msg.channelID] !== msg.pushEndpoint) {
   this.pushUrls[msg.channelID] = msg.pushEndpoint;
   this._registerCallback(null, this.pushUrl, msg.channelID);
 }

And the handling of "notification" events needs to include the channel id:

 case "notification":
   msg.updates.forEach((update) => {
     if (update.channelID in this.channelIDs) {
       this._notificationCallback(update.version, update.channelID);
     }
   });
   break;

Of course, the MozLoopService needs to be adapted to handle multiple calls to its registration callback, and needs to check the channelID parameter on its notification callback to determine which of the four possible states it should check.

This also means that calls to POST /registration need to be modified to include multiple URLs. See below.

Loop Server API Changes

Because we will be using different push server endpoints for rooms than we do for calls, it is necessary to convey more than one push server endpoint in the registration message:

POST /registration HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
Host: localhost:5000

{
    "simplePushURL": "https://example.org/wg0asg83t_74s",
    "simplePushURLs": {
        "calls": "https://example.org/wg0asg83t_74s",
        "rooms": "https://example.org/vnd7a85ls9gh"
     }
}

The idea behind this move, is to make it easy in the future to add new topics.

simplePushURL becomes deprecated, if set, it is used as the value for simplePushURLs.calls simplePushURLs is the topic array, omitted topics will be unset and notification on this topics will not be handled.

Loop Server API Additions

To accommodate rooms, the Loop Server API will need the following additions.

POST /rooms

This generates a new room and returns the associated URL that can be used to join the room.

POST /rooms HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Authorization: <stripped>
Content-Type: application/json; charset=utf-8
Host: localhost:5000
 
{
    "roomName": "UX Discussion",
    "expiresIn": 5,
    "roomOwner": "Alexis",
    "maxSize": 2
}

• roomName - The room-owner-assigned name used to identify this room.
• expiresIn - The number of hours for which the room will exist.
• roomOwner - The user-friendly display name indicating the name of the room's owner.
• maxSize - The maximum number of users allowed in the room at one time.

HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json; charset=utf-8
Date: Wed, 16 Jul 2014 13:09:40 GMT
Server-Authorization: <stripped>

{
    "roomToken": "_nxD4V4FflQ",
    "roomUrl": "http://localhost:3000/rooms/_nxD4V4FflQ",
    "expiresAt": 1405534180
}

• roomToken - The token used to identify this room.
• roomUrl - A URL that can be given to other users to allow them to join the room.
• expiresAt - The date after which the room will no longer be valid (in seconds since the Unix epoch).

Server implementation note: The Loop server should contact the TokBox servers and retrieve a sessionId for the room at room creation time. This sessionId should be stored persistently with rest of the information associated with the room.

PATCH /rooms/{token}

The "PATCH /rooms/{token}" endpoint is used to update information about an existing room.

PATCH /rooms/_nxD4V4FflQ HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Authorization: <stripped>
Content-Type: application/json; charset=utf-8
Host: localhost:5000
 
{
    "roomName": "Follow-up from UX Discussion",
    "expiresIn": 24
}

The parameters for this endpoint are the same as for "POST /rooms". Any omitted parameters are not updated.

HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json; charset=utf-8
Date: Wed, 16 Jul 2014 13:09:40 GMT
Server-Authorization: <stripped>

{
    "expiresAt": 1405534180
}

• expiresAt - The date after which the room will no longer be valid (in seconds since the Unix epoch).

DELETE /rooms/{token}

Destroys a previously-created room.

DELETE /rooms/_nxD4V4FflQ HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Authorization: <stripped>
Content-Length: 0
Host: localhost:5000

HTTP/1.1 204 No Content
Connection: keep-alive
Date: Wed, 16 Jul 2014 13:12:46 GMT
Server-Authorization: <stripped>

Client implementation note: Before deleting a room, the client should check room membership and forceDisconnect() all current participants

DELETE /rooms

Destroys a list of user's previously-created rooms.

DELETE /rooms HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Authorization: <stripped>
Content-Length: 0
Host: localhost:5000

{"roomTokens": ["_nxD4V4FflQ", "_xaB2Z5GdTV"]}

HTTP/1.1 204 No Content
Connection: keep-alive
Date: Wed, 16 Jul 2014 13:12:46 GMT
Server-Authorization: <stripped>

Client implementation note: Before deleting a room, the client should check room membership and forceDisconnect() all current participants

GET /rooms/{token}

This endpoint is used to retrieve information about a single room, including a list of room participants.

Because providing this information to users who are not in the room would be surprising for those in the room, we only allow the room owner and users in the room to access this method. Room owners are authenticated via their HAWK credentials, while room participants are authenticated via the sessionToken bearer token provided to them when they joined the room.

GET /rooms/3jKS_Els9IU HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Authorization: <elided>
Host: localhost:5000

• For a desktop client user, the "Authorization" header field is populated with the HAWK token (using a scheme of "Hawk"), just like it is for other requests.
• For the standalone client, the "Authorization" header field is encoded using Basic authentication. The user ID portion is the sessionToken provided to the user when they joined the room, and the password is blank.

HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 30
Content-Type: application/json; charset=utf-8
Date: Wed, 16 Jul 2014 13:23:04 GMT
ETag: W/"1e-2896316483"
Timestamp: 1405516984

{
    "roomToken": "3jKS_Els9IU",
    "roomName": "UX Discussion",
    "roomUrl": "http://localhost:3000/rooms/3jKS_Els9IU",
    "roomOwner": "Alexis",
    "maxSize": 2,
    "clientMaxSize": 2,
    "creationTime": 1405517546,
    "ctime": 1405517824,
    "expiresAt": 1405534180,
    "participants": [
       { "displayName": "Alexis", "account": "alexis@example.com", "roomConnectionId": "2a1787a6-4a73-43b5-ae3e-906ec1e763cb" },
       { "displayName": "Adam", "roomConnectionId": "781f012b-f1ea-4ce1-9105-7cfc36fb4ec7" }
     ]
}

• roomToken - The token that uniquely identifies this room
• roomName - The room-owner-assigned name used to identify this room.
• roomUrl - A URL that can be given to other users to allow them to join the room.
• roomOwner - The user-friendly display name indicating the name of the room's owner.
• maxSize - The maximum number of users allowed in the room at one time (as configured by the room owner).
• clientMaxSize - The current maximum number of users allowed in the room, as constrained by the clients currently participating in the session. If no client has a supported size smaller than "maxSize", then this will be equal to "maxSize". Under no circumstances can "clientMaxSize" be larger than "maxSize".
• creationTime - The time (in seconds since the Unix epoch) at which the room was created.
• expiresAt - The time (in seconds since the Unix epoch) at which the room goes away.
• participants - An array containing a list of the current room participants. Each participant is formatted with the same fields as described in #User Identification in a Room.
• ctime - Similar in spirit to the Unix filesystem "ctime" (change time) attribute. The time, in seconds since the Unix epoch, that any of the following happened to the room:
  • The room was created
  • The owner modified its attributes with "PATCH /rooms/{token}"
  • A user joined the room
  • A user left the room

POST /rooms/{token}

The "POST /rooms/{token}" endpoint is used for a variety of purposes. The JSON object in its body contains an "action" parameter to indicate which of these purposes the operation is being used for.

Joining a Room

Server implementation note: associate user token with sessionToken here. Room owner must have "moderator" privileges.

• For a desktop client user, the "Authorization" header field is populated with the HAWK token (using a scheme of "Hawk"), just like it is for other requests.
• For the standalone client, on this endpoint action there is no Authorization header

POST /rooms/QzBbvGmIZWU HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Content-Type: application/json; charset=utf-8
Authorization: <stripped>
Host: localhost:5000

{
    "action": "join",
    "displayName": "Adam",
    "clientMaxSize": 2
}

• action - For joining a room, will be set to "join"
• displayName - User-friendly display name for the joining user.
• clientMaxSize - Maximum number of room participants the user's client is capable of supporting.

HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json; charset=utf-8
Date: Wed, 16 Jul 2014 13:37:39 GMT
Timestamp: 1405517859

{
    "apiKey": "44669102",
    "sessionId": "1_MX40NDY2OTEwMn5-V2VkIEp1bCAxNiAwNjo",
    "sessionToken": "T1==cGFydG5lcl9pZD00NDY2OTEwMiZzaW",
    "expires": 600
}

• apiKey - The TokBox public api Key
• sessionId - The TokBox session identifier (identifies the room)
• sessionToken - The TokBox session token (identifies the room participant)
• expires - The number of seconds within which the client must send another POST to this endpoint to remain a participant in this room. See #Room Membership and Soft State

Refreshing Membership in a Room

• For a desktop client user, the "Authorization" header field is populated with the HAWK token (using a scheme of "Hawk"), just like it is for other requests.
• For the standalone client, the "Authorization" header field is encoded using Basic authentication. The user ID portion is the sessionToken provided to the user when they joined the room, and the password is blank.

POST /rooms/QzBbvGmIZWU HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Content-Type: application/json; charset=utf-8
Authorization: <stripped>
Host: localhost:5000

{
    "action": "refresh"
}

• action - For refreshing the soft state relationship, this will be "refresh".
• sessionToken - The session token received when joining the room. Used to identify the session to be refreshed as well as to authorize the user to perform the refresh.

HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json; charset=utf-8
Date: Wed, 16 Jul 2014 13:47:39 GMT
Timestamp: 1405517859

{
    "expires": 600
}

• expires - The number of seconds within which the client must send another POST to this endpoint to remain a participant in this room. See #Room Membership and Soft State

Leaving a Room

• For a desktop client user, the "Authorization" header field is populated with the HAWK token (using a scheme of "Hawk"), just like it is for other requests.
• For the standalone client, the "Authorization" header field is encoded using Basic authentication. The user ID portion is the sessionToken provided to the user when they joined the room, and the password is blank.

POST /rooms/QzBbvGmIZWU HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Content-Type: application/json; charset=utf-8
Authorization: <stripped>
Host: localhost:5000

{
    "action": "leave"
}

• action - For leaving a room, this will be "leave".
• sessionToken - The session token received when joining the room. Used to identify the session to be left as well as to authorize the user to perform the leave.

HTTP/1.1 204 No Content
Connection: keep-alive
Server-Authorization: <stripped>

GET /rooms

List all rooms associated with account

GET /rooms?version=<version> HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Host: localhost:5000

• version - Optional; if present, indicates the version received from the simple push server; the server will limit results to those rooms that have changed on or after this time.

HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 30
Content-Type: application/json; charset=utf-8
Date: Wed, 16 Jul 2014 13:23:04 GMT
ETag: W/"1e-2896316483"
Timestamp: 1405516984

[
    {
        "roomToken": "_nxD4V4FflQ",
        "roomName": "First Room Name",
        "roomUrl": "http://localhost:3000/rooms/_nxD4V4FflQ",
        "roomOwner": "Alexis",
        "maxSize": 2,
        "creationTime": 1405517546,
        "ctime": 1405517546,
        "expiresAt": 1405534180,
        "participants": []
    },
    {
        "roomToken": "QzBbvGmIZWU",
        "roomName": "Second Room Name",
        "roomUrl": "http://localhost:3000/rooms/QzBbvGmIZWU",
        "roomOwner": "Alexis",
        "maxSize": 2,
        "creationTime": 1405517546,
        "ctime": 1405517546,
        "expiresAt": 1405534180,
        "participants": []
    },
    {   
        "roomToken": "3jKS_Els9IU",
        "roomName": "UX Discussion",
        "roomUrl": "http://localhost:3000/rooms/3jKS_Els9IU",
        "roomOwner": "Alexis",
        "maxSize": 2,
        "clientMaxSize": 2,
        "creationTime": 1405517546,
        "ctime": 1405517818,
        "expiresAt": 1405534180,
        "participants": [
           { "displayName": "Alexis", "account": "alexis@example.com", "roomConnectionId": "2a1787a6-4a73-43b5-ae3e-906ec1e763cb" },
           { "displayName": "Adam", "roomConnectionId": "781f012b-f1ea-4ce1-9105-7cfc36fb4ec7" }
         ]
    },
    {   
        "roomToken": "z9Hg4Bk19_Z",
        "deleted": true
    }
]

This body is an array of rooms, each of which is formatted as described in #GET_.2Frooms.2F.7Btoken.7D.

Additionally, if a "?version=<version>" parameter is included, then the list will include the rooms that have been deleted since that version. These entries will simply include the roomToken, plus a field "deleted" with a value of "true". None of the other fields need to be included for deleted rooms.