Zetta Server to Server Protocol (Z2Z) [DRAFT]

Zetta Server-to-Server Protocol (DRAFT)

Table of Contents

1. Overview
2. Establishing a Peer Connection
  2.1 Handshake Request
    2.1.1 Request
    2.1.2 Successful Response
  2.2 Upgrading the Connection
  2.3 Acknowledging the Upgrade
    2.3.1 Request
    2.3.2 Successful Response
3. State Requests
  3.1 Request
  3.2 Response
4. Transition Requests
  4.1 Request
  4.2 Response
5. Stream Requests
  5.1 Subscribing to a Stream
    5.1.1 Subscription Request
    5.1.2 Successful Subscription Response
  5.2 Stream Data Response
  5.3 Unsubscribing from a Stream
    5.3.1 Subscription Cancellation Request
    5.3.2 Successful Subscription Cancellation Response
6. Ping Requests

1. Overview

The Zetta server-to-server protocol allows instances of Zetta to peer with one another. An initiating peer begins a connection request. Once the receiving peer has accepted, the receiving peer can see the devices connected to the initiating peer. This allows Zetta apps and API clients to access these devices across network boundaries.

2. Establishing a Peer Connection

2.1 Handshake Request

An initiating peer, alice, starts a WebSocket handshake request to a receiving peer, bob. The path template for this request is /peers/{name}?connectionId={connectionId}, where {name} corresponds to the unique name assigned to the initiating peer and {connectionId} corresponds to a unique connection identifier for the request.

2.1.1 Request

POST /peers/alice?connectionId=635712d6-03e7-4147-b33d-f80e14e4f74d HTTP/1.1
Connection: Upgrade
Host: bob.example.com
Sec-WebSocket-Key: /3f6p5Yox7c7DwCUZGhSyw==
Sec-WebSocket-Version: 13
Upgrade: websocket

2.1.2 Successful Response

HTTP/1.1 101 Switching Protocols
Connection: Upgrade
Sec-Websocket-Accept: xl25ZO2sm/ejbX8qKZlpX7PCXr8=
Upgrade: websocket

// TODO: Handle errors on handshakes.

Note: After this handshake completes, the server-to-server protocol no longer uses WebSocket protocol framing when sending messages.

2.2 Upgrading the Connection

Once the handshake is complete, each peer upgrades its side of the connection.

1. The initiating peer upgrades its WebSocket client connection to a SPDY server connection.
2. The accepting peer upgrades its WebSocket server connection to a SPDY client connection.

This allows SPDY requests to flow from the accepting peer to the initiating peer over the established connection.

// TODO: Why SPDY? Talk about HTTP/2.

2.3 Acknowledging the Upgrade

After upgrading each side of the peer connection, the accepting peer sends a SPDY request to the initiating peer. The SPDY request uses a path template of /_initate_peer/{connectionId} where {connectionId} matches the connectionId query string parameter value sent in the handshake request.

After this acknowledgement, state, transition, and stream requests may follow.

2.3.1 Request

The request should contain a host value of {{server-id}}.unreachable.zettajs.io.

:host: alice.unreachable.zettajs.io
:method: GET
:path: /_initiate_peer/635712d6-03e7-4147-b33d-f80e14e4f74d
:scheme: http
:version: HTTP/1.1

2.3.2 Successful Response

:status: 200 OK
:version: HTTP/1.1

3. State Requests

Requests for device state over the server-to-server protocol should semantically match state requests as defined by the client-to-server protocol. State requests over the server-to-server protocol are sent using the SPDY connection established after a successful peer acknowledgement.

State requests should contain a host value of {{server-id}}.unreachable.zettajs.io.

3.1 Request

Note: Values associated with this request will be provided in a hypermedia response. This example exists only for illustration.

:host: alice.unreachable.zettajs.io
:method: GET
:path: /servers/alice/devices/9fca64e9-460a-488f-bf43-e1362a8e3b71
:scheme: http
:version: HTTP/1.1
Accept: application/vnd.siren+json

3.2 Response

See the client-to-server documentation on state responses.

4. Transition Requests

Requests for device transitions over the server-to-server protocol should semantically match transition requests as defined by the client-to-server protocol. Transition requests over the server-to-server protocol are sent using the SPDY connection established after a successful peer acknowledgement.

Transition requests should contain a host value of {{server-id}}.unreachable.zettajs.io.

4.1 Request

Note: Values associated with this request will be provided in a hypermedia response. This example exists only for illustration.

:host: alice.unreachable.zettajs.io
:method: POST
:path: /servers/alice/devices/9fca64e9-460a-488f-bf43-e1362a8e3b71
:scheme: http
:version: HTTP/1.1
Content-Length: 14
Content-Type: application/x-www-form-urlencoded

action=turn-on

4.2 Response

See the client-to-server documentation on state responses.

5. Stream Requests

Stream requests make use of SPDY's Server Push feature. When a stream request is made, the stream is opened. Stream data will flow as SPDY Server Push messages.

Stream requests should contain a host value of {{server-id}}.unreachable.zettajs.io.

5.1 Subscribing to a Stream

5.1.1 Subscription Request

Note: Values associated with this request will be provided in a hypermedia response. This example exists only for illustration.

:host: alice.unreachable.zettajs.io
:method: GET
:path: /servers/alice/events?topic=light%2F9fca64e9-460a-488f-bf43-e1362a8e3b71%2Fluminosity
:scheme: http
:version: HTTP/1.1

5.1.2 Successful Subscription Response

Upon sending a successful response, the stream will be held open until an unsubscribe request is made or the connection is terminated.

:status 200 OK
:version: HTTP/1.1

5.2 Stream Data Response

The Content-Type header is used to determine the content type of the data response. Valid event encoding values are application/json and application/octet-stream. JSON data will have an application/json value. Binary data uses the application/octet-stream value.

:host: alice.unreachable.zettajs.io
:scheme: http
:status: 200 OK
:version: HTTP/1.1
Content-Length: 102
Content-Type: application/json

{"topic":"light/9fca64e9-460a-488f-bf43-e1362a8e3b71/luminosity","timestamp":1430158874339,"data":768}

5.3 Unsubscribing from a Stream

5.3.1 Subscription Cancellation Request

Note: Values associated with this request will be provided in a hypermedia response. This example exists only for illustration.

:host: alice.unreachable.zettajs.io
:method: POST
:path: /servers/alice/events/unsubscribe
:scheme: http
:version: HTTP/1.1
Content-Length: 63
Content-Type: application/x-www-form-urlencoded

topic=light%2F9fca64e9-460a-488f-bf43-e1362a8e3b71%2Fluminosity

5.3.2 Successful Subscription Cancellation Response

Closes the stream associated with the SPDY Server Push.

:status: 202 Accepted
:version: HTTP/1.1

6. Ping Requests

To keep the peer connection alive, ping requests are sent periodically from the accepting peer to the initiating peer. This method is described by the PING control frame section of the SPDY specification.