Loop/Architecture/Rooms

This is still under construction, is missing important details, and may change substantially as scenarios are fleshed out further. Do not implement.

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. Consequently, the network API for rooms uses "/room-url" and "/rooms" endpoints in a way that is congruent with the "/call-url" and "/calls" endpoints. 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 09:11:58 CDT 2014	Adam Roach	Initial version

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 toke 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",
    "id": "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
• id - 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.

Removing Participants from a Room

Because user is moderator, can use forceUnpublish and forceUnsubscribe to remove user from room.

Loop Server API Additions

POST /room-url

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

POST /room-url 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 -
• expiresIn -
• roomOwner -
• maxSize -

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/room/_nxD4V4FflQ",
    "expiresAt": 1405534180
}

• roomToken -
• roomUrl -
• expiresAt -

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.

PUT /room-url/{token}

The "PUT /room-url/{token}" endpoint is used to update information about an existing room.

PUT /room-url 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 /room-url".

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 -

DELETE /room-url/{token}

Destroys a previously-created room.

DELETE /room-url/_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: client should check room membership and forceUnpublish() all current participants

GET /rooms/{token}

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

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

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

{
    "roomName": "UX Discussion",
    "roomOwner": "Alexis",
    "maxSize": "2",
    "urlCreationDate": 1405517546,
    "expiresAt": 1405534180,
    "participants": [
       { "displayName": "Alexis", "account": "alexis@example.com", "id": "2a1787a6-4a73-43b5-ae3e-906ec1e763cb" },
       { "displayName": "Adam", "id": "781f012b-f1ea-4ce1-9105-7cfc36fb4ec7" }
     ]
}

• roomName -
• roomOwner -
• maxSize -
• urlCreationDate -
• expiresAt -
• participants -

Each participant is formatted with the same fields as described in #User Identification in a Room

POST /rooms/{token}

The "POST /rooms/{token}" endpoint is used for a variety of purposes. The JSON object in its body contains an "operation" 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.

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

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

• operation -
• displayName -
• clientMaxSize -

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 -
• sessionId -
• expires -

Refreshing Membership in a Room

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

{
    "operation": "refresh"
}

• operation -

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 -

Leaving a Room

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

{
    "operation": "leave"
}

• operation -

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 -

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",
        "maxSize": "2",
        "currSize": "0",
        "lastUsed": "1405517546"
    },
    {
        "roomToken": "QzBbvGmIZWU",
        "roomName": "Second Room Name",
        "maxSize": "2",
        "currSize": "0",
        "lastUsed": "1405517418"
    },
    {   
        "roomToken": "3jKS_Els9IU",
        "roomName": "Third Room Name",
        "maxSize": "3",
        "clientMaxSize": "2",
        "currSize": "1",
        "lastUsed": "1405518241"
    }
]

• roomToken -
• roomName -
• maxSize -
• clientMaxSize -
• currSize -
• lastUsed -