From d36ce773d2927a5aeb7675290b61e6a5d2dbf89a Mon Sep 17 00:00:00 2001 From: Joel Unzain Date: Thu, 13 Aug 2020 19:19:07 -0700 Subject: [PATCH 1/3] Update spec --- content/docs/wrp/simple-messages.md | 32 ++++++++++++++++++----------- 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/content/docs/wrp/simple-messages.md b/content/docs/wrp/simple-messages.md index cfb6c9ba..7eb67e3f 100644 --- a/content/docs/wrp/simple-messages.md +++ b/content/docs/wrp/simple-messages.md @@ -12,15 +12,21 @@ To make the document easier to read, the msgpack is written out in a bit more human readable format. One design goal for the message definition is to make sure it can be translated -to and from JSON and HTTP headers as well as it's native msgpack format. +to and from JSON and HTTP headers as well as its native msgpack format. +Messages currently flow in two directions: +- Inbound: API requests to devices. +- Outbound: responses from devices for corresponding inbound requests as well as + events related to device activity (rebooting, updating, offline). + ## Simple Request-Response Definition This is one of the primary message definitions used. This provides a point to -point (request, response) semantic. An example of where this message is used is -between Webpa's `Tr1d1um` machine and the `Parodus2ccsp` client that interprets -the request, gathers data and responds back. Both requests and responses use -the same message type. +point (request, response) semantic between an API user that makes requests and +a device client which responds to them. An example of where this message is used is +between Webpa's `Tr1d1um` which sends requests on behalf of API users and the + `Parodus2ccsp` client that interprets such requests, gathers data and responds back. + Both requests and responses use the same message type. #### Schema ~~~~~ @@ -28,6 +34,7 @@ the same message type. Integer msg_type = 3 String source String dest + String device_id String content_type String accept String transaction_uuid @@ -47,9 +54,10 @@ the same message type. 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. +source | The device_id name of the device originating the request or response (i.e. dns:tr1d1um.example.net for inbound messages). +dest | The device_id name of the target device of the request or response (i.e. mac:112233445566/config for inbound messages). +device_id | The canonical device ID (i.e. mac:112233445566) involved in this envelope. It defers from source or dest in that no further parsing is required to extract the ID from the value. +content_type | (optional) The media type of the payload. If not specified on inbound messages, `application/octet-stream` is used as default. 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 to the originating service. Not included in the during the request. @@ -83,7 +91,6 @@ great at sending metrics, publishing a report, sending an SOS. { Integer msg_type = 4 String source - String dest String content_type Array.String partner_ids Array.String headers @@ -96,9 +103,10 @@ great at sending metrics, publishing a report, sending an SOS. 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. +source | The device_id name of the device originating the event (i.e. mac:112233445566/config) +dest | A value of the form: `event:{event-type}`. The main use case is the ability to listeners to register only for events they care about. +device_id | The canonical device ID (i.e. mac:112233445566) involved in this message. It defers from source as no further parsing is needed to extract the ID. +content_type | (optional) The media type of the payload. If not specified on inbound messages, `application/octet-stream` is used as default. 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. From 5df70e1e8da409aadd437126c42b6a7f300e9ef4 Mon Sep 17 00:00:00 2001 From: Joel Unzain Date: Thu, 13 Aug 2020 19:20:10 -0700 Subject: [PATCH 2/3] add back dest field --- content/docs/wrp/simple-messages.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/docs/wrp/simple-messages.md b/content/docs/wrp/simple-messages.md index 7eb67e3f..cda3d49f 100644 --- a/content/docs/wrp/simple-messages.md +++ b/content/docs/wrp/simple-messages.md @@ -91,6 +91,7 @@ great at sending metrics, publishing a report, sending an SOS. { Integer msg_type = 4 String source + String dest String content_type Array.String partner_ids Array.String headers From 7700f5b12996fc32a753fda61022cc9f2ca53bf6 Mon Sep 17 00:00:00 2001 From: Weston Schmidt Date: Tue, 22 Mar 2022 00:46:50 -0700 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Kristina Pathak --- content/docs/wrp/simple-messages.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/content/docs/wrp/simple-messages.md b/content/docs/wrp/simple-messages.md index cda3d49f..883eae3c 100644 --- a/content/docs/wrp/simple-messages.md +++ b/content/docs/wrp/simple-messages.md @@ -54,9 +54,9 @@ between Webpa's `Tr1d1um` which sends requests on behalf of API users and the 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 (i.e. dns:tr1d1um.example.net for inbound messages). -dest | The device_id name of the target device of the request or response (i.e. mac:112233445566/config for inbound messages). -device_id | The canonical device ID (i.e. mac:112233445566) involved in this envelope. It defers from source or dest in that no further parsing is required to extract the ID from the value. +source | The locator information of the creator of the request or response (i.e. dns:tr1d1um.example.net for inbound messages). +dest | The locator information of the target device of the request or response (i.e. mac:112233445566/config for inbound messages). +device_id | The canonical device ID (i.e. mac:112233445566) that this message is related to. It differs from source or dest in that no further parsing is required to extract the ID from various fields. content_type | (optional) The media type of the payload. If not specified on inbound messages, `application/octet-stream` is used as default. 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. @@ -104,9 +104,9 @@ great at sending metrics, publishing a report, sending an SOS. Name | Description -----|-------------- msg_type | The message type for the simple event. (**SHALL** be 4.) -source | The device_id name of the device originating the event (i.e. mac:112233445566/config) -dest | A value of the form: `event:{event-type}`. The main use case is the ability to listeners to register only for events they care about. -device_id | The canonical device ID (i.e. mac:112233445566) involved in this message. It defers from source as no further parsing is needed to extract the ID. +source | The locator information of the creator of the event (i.e. mac:112233445566/config) +dest | An event locator of the form: `event:{event identifier}/{ignored}`. The main use case is for listeners to register only for events they care about. +device_id | The canonical device ID (i.e. mac:112233445566) that this message is about. The source may not always be or include the device ID (for example, if talaria creates an event about a device connecting to it). content_type | (optional) The media type of the payload. If not specified on inbound messages, `application/octet-stream` is used as default. 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.