Skip to content

Instantly share code, notes, and snippets.

@stuartpb

stuartpb/gist:6929423

Last active December 25, 2015 06:09
Show Gist options
  • Save stuartpb/6929423 to your computer and use it in GitHub Desktop.
Save stuartpb/6929423 to your computer and use it in GitHub Desktop.
Download ZIP
An example of two clients connecting via the proposed Chatphrase RESTful signaling flow.
Raw
gistfile1.md

This document is (very) obsolete

Since this example was written, the connection flow used by caress evolved in several ways (not necessarily in this order):

  • POSTs for updating were replaced with PUTs, in closer accordance with the verbs' meanings in HTTP.
  • The multiple layers of UUID were reduced to one, with each UUID containing all its associations on the back end.
  • The Offer-To and Answer-At locations were consolidated into one location that acts as both depending on the method used (and suggested for use with query string differentiation to get around browser concurrency restrictions).
  • Multiple "Answer-To" endpoints for each party reading the offer were consolidated into a single "winner-first" endpoint presented to any inquiring parties (and invalidated after the first response).
  • The "Chatphrase-*" headers were replaced with "Location" (for paths expected to be used with GET) and "Reply-Location" (for paths expected to be exclusively POSTed to).
  • "Chatphrase-Ice-Gathering-State" was (somewhat unintentionally) replaced with a final message posted as "null" to signify the last update. Since waiting parties need to be informed when the other end has timed out, neither end stops requesting additional messages during signaling, even after they've received the last message. This way, a client will know to retry the connection if the other end has disappeared.
  • As an implementation detail, the weak incrementing Etag scheme described here was replaced with strong SHA-1 Etags.
  • As you're not allowed to setLocalDescription multiple times in WebRTC, POSTs were brought back, with successive POSTs creating new messages, which are retrieved by appending '/:number' to the path.
  • For practical reasons, the flow was changed so that, rather than posting an Offer or Answer that may be rejected, offers are POSTed blindly, the first party's offer is discarded, and then the first party gets the second party's offer in polling (the Start flow in caress).
  • '/phrases/' was changed to '/offers/' and '/start/' (depending on the connection initiation scheme in use), and UUIDs were brought from '/sdp/' to the root.

The example detailed in this document should not be read as anything more than a historical insight into the evolution of the design of caress. To see the modern flows in action, read caress's test suites (which are not comprehensive beyond initial negotiation), or see its use in the signaling.js file in chatphrase.

BEGIN OBSOLETE EXAMPLE

Alice begins the phrase "example" and, after acquiring a media stream through getUserMedia, makes a request to "/phrases/example".

The server replies with a 200 OK status and the header "Chatphrase-Offer-To: /sdp/4b352f23-9849-4e6a-a673-ba6dd9f77081/a69c8fd9-306d-4864-8021-cd00b4ed85ed".

(From this point forward, "/sdp/4b352f23-9849-4e6a-a673-ba6dd9f77081/a69c8fd9-306d-4864-8021-cd00b4ed85ed" will be referred to as the Offer-To Path.)

Alice creates an SDP Offer, sets it as her Local Description, and POSTs it to the Offer-To Path, with the header "Chatphrase-Ice-Gathering-State: gathering".

The server replies with a 200 OK status and the header "Chatphrase-Answer-At: /sdp/4b352f23-9849-4e6a-a673-ba6dd9f77081/f0073ab2-8483-45c3-a998-a7c9d36793d3".

(From this point forward, "/sdp/4b352f23-9849-4e6a-a673-ba6dd9f77081/f0073ab2-8483-45c3-a998-a7c9d36793d3" will be referred to as the Answer-At Path.)

Alice makes a GET request to the Answer-At Path.

The server replies with a 204 No Content status and the header "ETag: 0".

Alice makes another GET request to the Answer-At Path, this time with the header "If-None-Match: 0".

Alice's ICE Agent gathers an ICE candidate. Alice POSTs the SDP of her new Local Description to the Offer-To Path, with the header "Chatphrase-Ice-Gathering-State: gathering". The server responds with a 200 OK status and the same Chatphrase-Answer-At header as before.

Alice's ICE Agent gathers another ICE candidate. Alice POSTs the SDP of her new Local Description to the Offer-To Path, with the header "Chatphrase-Ice-Gathering-State: gathering". The server responds with a 200 OK status and the same Chatphrase-Answer-At header as before.

The server, after an implementation-determined amount of time, responds to Alice's earlier GET request to the Answer-At path with a 304 Not Modified status.

Alice makes another GET request to the Answer-At path, again with the header "If-None-Match: 0".

Alice's ICE Agent gathers another ICE candidate. Alice POSTs her new Local Description to the Offer-To Path, with the header "Chatphrase-Ice-Gathering-State: gathering". The server responds with a 200 OK status and the same Chatphrase-Answer-At header as before.

Bob begins the phrase "example" and, after acquiring a media stream through getUserMedia, makes a request to "/phrases/example".

The server replies with a 200 OK status and the header "Chatphrase-Offer-At: /sdp/4b352f23-9849-4e6a-a673-ba6dd9f77081".

(From this point forward, "/sdp/4b352f23-9849-4e6a-a673-ba6dd9f77081" will be referred to as the Offer-At Path.)

Bob makes a GET request to the Offer-At path.

The server replies with a 200 OK status, the headers "Chatphrase-Answer-To: /sdp/4b352f23-9849-4e6a-a673-ba6dd9f77081/0be1493a-2cd0-41f0-a2bb-161f7338e8d8", "Chatphrase-Ice-Gathering-State: gathering", and "ETag: 4", and the SDP of the last posted version of Alice’s offer in the body.

(From this point forward, "/sdp/4b352f23-9849-4e6a-a673-ba6dd9f77081/0be1493a-2cd0-41f0-a2bb-161f7338e8d8" will be referred to as the Answer-To Path.)

Bob sets the received SDP Offer as his Remote Description, and creates an SDP Answer.

Bob makes another GET request to the Offer-At Path, this time with the header "If-None-Match: 4".

Bob sets his Local Description to his new SDP Answer and POSTs it to the Answer-To Path, with the header "Chatphrase-Ice-Gathering-State: gathering". The server responds with a 200 OK status.

The server responds to Alice's earlier GET request to the Answer-At path with a 200 OK status, Bob's new SDP Answer, and the headers "Chatphrase-Ice-Gathering-State: gathering" and "ETag: 1".

Alice sets the newly-received SDP Answer as her Remote Description.

Alice makes another GET request to the Answer-At Path, this time with the header "If-None-Match: 1".

The server, after an implementation-determined amount of time, responds to Bob's GET request to the Offer-At path with a 304 Not Modified status.

Bob makes another GET request to the Offer-At Path, again with the header "If-None-Match: 4".

Bob's ICE Agent gathers an ICE candidate. Bob POSTs the SDP of his new Local Description to the Answer-To Path, with the header "Chatphrase-Ice-Gathering-State: gathering". The server responds with a 200 OK status.

The server responds to Alice's earlier GET request to the Answer-At Path with a 200 OK status, the new version of Bob's Local Description, and the headers "Chatphrase-Ice-Gathering-State: gathering" and "ETag: 2".

Alice sets the updated SDP Answer as her Remote Description and makes another GET request to the Answer-At Path, this time with the header "If-None-Match: 2".

Alice's ICE Agent gathers another ICE candidate. Alice POSTs the SDP of her new Local Description to the Offer-To Path, with the header "Chatphrase-Ice-Gathering-State: gathering". The server responds with a 200 OK status and the same Chatphrase-Answer-At header as before.

The server responds to Bob's earlier GET request to the Offer-At Path with a 200 OK status, the new version of Alice's Local Description, and the headers "Chatphrase-Ice-Gathering-State: gathering" and "ETag: 5".

Bob sets the updated SDP Offer as his Remote Description and makes another GET request to the Answer-At Path, this time with the header "If-None-Match: 5".

Bob's ICE Agent gathers another ICE candidate. Bob POSTs the SDP of his new Local Description to the Answer-To Path, with the header "Chatphrase-Ice-Gathering-State: gathering". The server responds with a 200 OK status.

The server responds to Alice's earlier GET request to the Answer-At Path with a 200 OK status, the new version of Bob's Local Description, and the headers "Chatphrase-Ice-Gathering-State: gathering" and "ETag: 3".

Alice sets the updated SDP Answer as her Remote Description and makes another GET request to the Answer-At Path, this time with the header "If-None-Match: 3".

Bob's ICE Agent gathers its last ICE candidate. Bob POSTs the SDP of his new Local Description to the Answer-To Path, with the header "Chatphrase-Ice-Gathering-State: complete". The server responds with a 200 OK status.

The server responds to Alice's earlier GET request to the Answer-At Path with a 200 OK status, Bob's finalized SDP Answer, and the headers "Chatphrase-Ice-Gathering-State: complete" and "ETag: 4".

Alice sets the updated SDP Answer as her Remote Description and does not make another GET request as Bob's SDP Answer is not expected to change after the Ice Gathering State is complete.

Alice's ICE Agent gathers its last ICE candidate. Alice POSTs the SDP of her new Local Description to the Answer-To Path, with the header "Chatphrase-Ice-Gathering-State: complete". The server responds with a 200 OK status.

The server responds to Bob's earlier GET request to the Offer-At Path with a 200 OK status, Alice's finalized SDP Offer, and the headers "Chatphrase-Ice-Gathering-State: complete" and "ETag: 6".

Bob sets the updated SDP Offer as his Remote Description and does not make another GET request as Alice's SDP Offer is not expected to change after the Ice Gathering State is complete.

After a period of time, with all the ICE Candidates collected, Alice and Bob are connected.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment