-
Notifications
You must be signed in to change notification settings - Fork 73
Web Routing Protocol
Web Routing Protocol
This document specifies the web routing protocol design. The goal of this layer is to enable devices to interact with a centralized web router (cluster) that routes the messages to/from various services on the other side. From the service perspective, this layer provides a centralized mechanism to directly interact with millions of authorized devices in the field in a scalable manor.
Higher level protocols (GET/SET or event payloads) may be built on this layer, but are outside the scope of this specification.
. Scope of this document . .
~50M . .
Devices . .
. __--__ +---------+
+-----+ . ( ) | |
| STB |<----------( )--------->+ | +------------+ +-----+
+-----+ . ( ) | Web +<---->| REST Proxy |<--->| XPC |
. . ( Untrusted ) | Router | +------------+ +-----+
. . ( ) | Cluster | ^
. . ( Network ) | | |
+-----+ . ( ) | | +---------------+ |
| XB6 |<----------( )--------->+ +----->| Notification | |
+--+--+ . ( ) | | | Proxy Service |-----/ (example)
| . --__-- +---------+ +---------------+
| . .
| . . . . . . . . . . . . . .
|
| +-----+
+-->| STB |
| +-----+
|
| +------------+
+-->| Thermostat |
| +------------+
|
| +------------------+
\-->| other IoT device |
+------------------+
If the system implementing this protocol layer is compromised, then the potential attacker(s) could gain control of many/all devices downstream. This is highly undesirable and all measures SHALL be taken to prevent this possibility.
The entire time a device is present on our network, we want to be able to communicate with it. As such, it is important to be able to work efficiently across networks, IP version (4 or 6) or limitations of small devices.
Given an estimated 1B transactions a day, the design be as efficient as possible to reduce the need to scale horizontally more then needed.
The devices (set top boxes, gateways, etc) will originate the connection to the web router over secure websockets (WSS). The web router does not establish any connection directly with any other components in the system with the possible exceptions:
- DNS
- Authorization Policy Service (Billing or similar)
Servers wishing to communicate with devices shall also establish (and maintain) connections to the web router.
The web router SHALL NOT permit direct device to device (so mac:{mac address} or serial:{serial number} names for example). Additionally, it is encouraged to direct server to server messages through channels outside the web router to reduce the possible load on the server.
Messages that are not able to be routed SHALL be dropped.
If "something bad" happens and nodes of the web router fail, messages WILL be lost. In this case clients and servers that discover they are disconnected are responsible for re-establishing the connection.
Message types that are not understood SHALL be discarded.
Any additional parameters (to the ones listed) for known message types SHALL be passed without alteration.
| Name | Description |
|---|---|
| web router | the server cluster that implements the WRP protocol |
| WRP | web routing protocol |
| WS | Websockets |
| WSS | Secure Websockets |
Messages in the document are defined and shall be implemented using MsgPack.
WRP
WS
HTTP
TLS/SSL
TCP
IP
Physical
A UTF-8 case insensitive string of one of the following:
uuid:{the uuid}/{service}/{ignored}dns:{host name}/{service}/{ignored}mac:{mac address}/{service}/{ignored}serial:{serial number}/{service}/{ignored}
There can be a number of possible ways a device may become identified. The name of the device depends mainly on how it needs to be known. Set top boxes (X1 or legacy for example) will likely choose to follow the mac:{mac address}/{service} or serial:{serial number}/{service} convention. A service (such as the web router, XPC or an adapter) would likely choose dns:{host name}/{service}. Other devices that perform application layer discovery may choose uuid:{the uuid}.
The identifiers are not resolved or verified except for routing purposes.
Note that if the mac:{mac address} or serial:{serial number} formats are used, the name of the device must be a known value or the routing will not make it to the device as there is not other registration messages.
For device identification describing services, there is an additional {service} path that allows multiple services to reside on a single server or node and get routed correctly. Any data past the {service}/ is ignored by the web router.
The following HTTP headers describe the device name and group membership in the WSS establishment:
| Name | Description |
|---|---|
X-WebPA-Device-Name |
(Required) The device name to refer to the device by. SHOULD be serial-{serial number}
|
X-WebPA-Group-Membership |
(Optional) The comma separated list of groups to which the device is a member. |
This API uses HTTP redirection where appropriate. Clients should assume that any connection request may result in a redirection. Clients should follow the redirect as this is not an error.
Redirections are limited to 5 redirects.
{
Integer msg_type = 2
Integer status
}
| Name | Description |
|---|---|
| msg_type | The message type for the authorization status message. (SHALL be 2.) |
| status | The status of the device to which the message is sent. |
Status Codes:
* 200 - Authorized
* 401 - Unauthorized - The service is not authorized for this account.
* 402 - Payment Required - The associated account needs payment.
* 406 - Not Acceptable - The certificate is not accepted.
{
Integer msg_type = 3
String source
String dest
String content_type
String accept
String transaction_uuid
Integer status
Integer rdr
Array.String partner_ids
Array.String headers
Map[String] metadata
Array.Array spans
String span_parent
Boolean include_spans
Binary payload
}
| Name | Description |
|---|---|
| msg_type | The message type for the request-response. (SHALL be 3.) |
| source | The device_id name of the device originating the request or response. |
| dest | The device_id name of the target device of the request or response. |
| content_type | (optional) The media type of the payload. |
| accept | (optional) The media type accepted in the response. |
| transaction_uuid | The transaction key for the request and response. The requester may have several outstanding transactions, but must ensure that each transaction is unique per destination. This SHOULD be a UUID, but the web router SHALL NOT validate this data. The web router SHALL treat this data as opaque. |
| status | (optional) The response status from the originating service. Not included in the during the request. |
| rdr | (optional) The request delivery response is the delivery result of the previous (implied request) message with a matching transaction_uuid. |
| partner_ids | (optional) The list of partner ids the message is meant to target. If the item is missing and the device has a partner id or the device does not find a match, the request shall be disregarded & a response with status of 403 sent back to the sender. |
| headers | (optional) The headers associated with the payload. |
| metadata | (optional) The map of name/value pairs used by consumers of WRP messages for filtering & other purposes. |
| spans | (optional) An array of arrays of timing values as a list in the format: "parent" (string), "name" (string), "start time" (int), "duration" (int), "status" (int) |
| span_parent | (optional) If the spans should be included, this field is included in the request. This string is the root parent for the spans below to link to. |
| include_spans | (optional) (Deprecated) If the timing values should be included in the response. |
| payload | The MsgPack bin format packed data. |
Request Delivery Response (rdr) Codes:
* 0 - Delivered
* The rest are TBD today.
{
Integer msg_type = 4
String source
String dest
String content_type
Array.String partner_ids
Array.String headers
Map[String] metadata
Binary payload
}
| Name | Description |
|---|---|
| msg_type | The message type for the simple event. (SHALL be 4.) |
| source | The device_id name of the device originating the request or response. |
| dest | The device_id name of the target device of the request or response. |
| content_type | (optional) The media type of the payload. |
| partner_ids | (optional) The list of partner ids the message is meant to target. If the item is missing and the device has a partner id or the device does not find a match, the request shall be disregarded. |
| headers | (optional) The headers associated with the payload. |
| metadata | (optional) The map of name/value pairs used by consumers of WRP messages for filtering & other purposes. |
| payload | The bin format packed data. |
{
Integer msg_type = ( 5 | 6 | 7 | 8 )
String source
String dest
String transaction_uuid
Array.String partner_ids
Array.String headers
Map[String] metadata
Array.Array spans
Boolean include_spans
Integer status
Integer rdr
String path
Binary payload
}
| Name | Description |
|---|---|
| msg_type | The message type for the CRUD interface. (5 = Create, 6 = Retrieve, 7 = Update, 8 = Delete) |
| source | The originating point of the request or response. |
| dest | The destination point of the request or response. |
| partner_ids | (optional) The list of partner ids the message is meant to target. If the item is missing and the device has a partner id or the device does not find a match, the request shall be disregarded & a response with status of 403 sent back to the sender. |
| headers | (optional) The headers associated with the payload. |
| metadata | (optional) The map of name/value pairs used by consumers of WRP messages for filtering & other purposes. |
| spans | (optional) An array of arrays of timing values as a list in the format: "parent" (string), "name" (string), "start time" (int), "duration" (int), "status" (int) |
| span_parent | (optional) If the spans should be included, this field is included in the request. This string is the root parent for the spans below to link to. |
| include_spans | (optional) (Deprecated) If the timing values should be included in the response. |
| status | (optional) The response status from the originating service. Not included in the during the request. |
| rdr | (optional) The request delivery response is the delivery result of the previous (implied request) message with a matching transaction_uuid. |
| path | The path to which to apply the payload. |
| payload | (optional) The json encoded string representing the objects. |
| Method | Request | Response |
|---|---|---|
| Create | Name/value pairs for the new object | Resulting object |
| Retrieve | Ignored | Requested object |
| Update | Name/value pair to update | Ignored |
| Delete | Ignored | Ignored |
{
Integer msg_type = 9
String service_name
String url
}
| Name | Description |
|---|---|
| msg_type | The message type for the on-device service registration |
| service_name | The originating point of the request or response |
| url | The url to use when connecting to the nanomsg pipeline |
This message is used by on device services that wish to register for messages from the webpa cluster. This message is not able to be routed off device.
{
Integer msg_type = 10
}
| Name | Description |
|---|---|
| msg_type | The message type for the on-device service alive update |
This message is used by on device services to indicate that a service is still alive.
The following messages have been deprecated and shall not be used.
- 0
- 1
The device establishes the secure websocket connection to the web router shortly after the device boots. During the secure websocket connection is established, the web router SHALL authorization checks the device before any user messages are routed to or from the device.
If the web router is satisfied with the authorization available for the device the web router SHALL send the message with the status of 200 set. It SHALL then proceed to route messages to and from the device. The routing continues until a device is no longer authorized. If the web router is not pleased with the certification or authorization provided by the device, it SHALL send the response message with the appropriate status set and MAY disconnect the session. If a device fails an authorization, the web router SHALL respond to the device with the authorization response message with the status of 401 set.
At any time, either party may disconnect the session for any reason.
The connection request MAY result in a HTTP redirect to the device, so the device MUST be prepared to support that request.
Once a session is established, websocket ping messages MUST be sent from the device to the web router periodically. The web router MUST respond with a websocket pong.
The device SHALL NOT listen for any connection initiated by the web router. All session initiation originates from the device.
| Name | Type | CRUD Supported | Description |
|---|---|---|---|
/hw-model |
string | R | The hardware model name. |
/hw-serial-number |
string | R | The serial number. |
/hw-manufacturer |
string | R | The device manufacturer. |
/hw-mac |
string | R | The MAC address used to manage the device. |
/hw-last-reboot-reason |
string | R | The last known reboot reason. |
/fw-name |
string | R | The firmware name. |
/boot-time |
number | R | The boot time in unix time. |
/local-url |
string | R | The local nanomsg URL for parodus. Defaults to tcp://127.0.0.1:6665 if not specified. |
/service-discovery-url |
string | R | The local service discovery agent URL Parodus should use. Defaults to empty and is not used if not specified. |
/webpa-last-reconnect-reason |
string | R | The reason for the last reconnection. |
/webpa-protocol |
string | R | The webpa protocol supported. |
/webpa-url |
string | RU | The URL that the WRP client should reach out to. |
/webpa-uuid |
string | RU | The UUID the device is assigned. |
/webpa-backoff-max |
number | R | The maximum value of c in the binary backoff algorithm. |
/webpa-ping-timeout |
number | R | The maximum time to wait between pings before assuming the connection is broken. |
/webpa-inteface-used |
string | R | The device interface being used to connect to the cloud. |
/tags |
map | R | The list of tags. |
/tag/${name} |
object | CRUD | The name of the tag to apply to each outgoing message. The object contains the attribute expires which is a number representing the unix time the tag object expires and is automatically removed. Each object name is unique and is not duplicated. Creation of existing tags is an error. Updating a non-existing tag is allowed & an implied creation. |
Authorization is a key component in the protocol because it reduces the risk of unintended user(s) or use(s) of this message routing service. Authorization status can change at any time. (Accounts can be revoked, cancelled, bills not payed, customers added, etc.) The protocol provides a mechanism for the web router to indicate the authorization status of the device to the device.
A key value of the authorization challenge model design is that the authorization only happens at the establishment of a websocket session and "periodically" afterwards. This important because often network protocols get bogged down re-validating credentials for each request or event and cannot horizontally scale to accommodate very large device populations.
The authorization checks happen at the server's discretion and may take place at any time.
Authorization checks may result in a status message sent to the device, disconnection of the device, or both.
Device Web Router Server
------------------------------------------------------------------------------------------
| | |
Boot | |
| | |
|--------- Open WSS --------->| |
| | +----------------------+ |
| | | Validate credentials | |
| | +----------------------+ |
| | |
| | (optional and for example) |
| ....|...............................|....................
| . | | .
| . |--- Check Account Status ----->| .
| . | | +---------------+ .
| . | | | Authorization | .
| . | | | Policy | .
| . | | | Service | .
| . | | +---------------+ .
| . |<--- Device is authorized -----| .
| . | | .
| ....|...............................|....................
| | |
|<---- Session Established ---| |
| | |
|<----- Auth Status ----------| |
| | |
. . .
. . .
| | |
|------ Websocket Ping ------>| |
|<----- Websocket Pong -------| |
| | |
Device Web Router REST Server
------------------------------------------------------------------------------------------
| | |
| | |
| | |
| | |<-- Incoming
| | | Request
| | |
| |<---- Send Request to device --|
| | |
| | +--------------------+ |
| | | Look up device | |
| | | based on unique_id | |
| | | of open sessions | |
| | +--------------------+ |
| | |
|<---- Request from REST -----| |
| | |
|----- Response to REST ----->| |
| | |
| | +--------------------+ |
| | | Look up service | |
| | | based on unique_id | |
| | | of open sessions | |
| | +--------------------+ |
| | |
| |------ Response to REST ------>|
| | |
| | |--> Response
| | |
| | |
Device Web Router Listening Server
------------------------------------------------------------------------------------------
| | |
|---- Event ----------------->| |
| | |
| | +--------------------+ |
| | | Look up service | |
| | | based on unique_id | |
| | | of open sessions | |
| | +--------------------+ |
| | |
| |----- Webhook call to -------->|
| | listener(s) |
| | |
This document is based on the 0.12 release of the internal spec.