Updates to uattributes and MQTT5 specifications (#204)

* Updates to uattributes and MQTT5 specifications The following changes adds D2D usecase for the MQTT5 transport, fixes the uE-2-uE use case, and adds OFT tags to uatributes and MQTT5 specs. #192, #169 --------- Co-authored-by: Kai Hudalla <[email protected]> Co-authored-by: Pete LeVasseur <[email protected]>
eclipse-uprotocol · Jul 25, 2024 · 3bbae37 · 3bbae37
1 parent 8801cc6
commit 3bbae37
Show file tree

Hide file tree

Showing 2 changed files with 275 additions and 116 deletions.
diff --git a/basics/uattributes.adoc b/basics/uattributes.adoc
@@ -59,29 +59,59 @@ The following table defines attributes that are used for all message types:
 |`id`
 |link:uuid.adoc[UUID]
 |yes
-|A unique message identifier. The timestamp contained in the UUID is used as the message's creation time.
+a|
+[.specitem,oft-sid="dsn~up-attributes-id~1",oft-needs="impl,utest"]
+--
+Every message *MUST* have a unique message identifier. The timestamp contained in the UUID is used as the message's creation time.
+--
 
 |`priority`
 |link:qos.adoc[UPriority]
 |no
-|The QoS level that this message should be processed/delivered with. If not specified explicitly, the link:qos.adoc#default-priority[default priority level] is assumed.
+a|
+The QoS level that this message should be processed/delivered with. 
+[.specitem,oft-sid="dsn~up-attributes-priority~1",oft-needs="impl,utest"]
+--
+A consumer *MUST* assume a message to have the link:qos.adoc#default-priority[default priority] if not set explicitly.
+--
 
 |`ttl`
 |`unsigned integer`
 |no
-a|The amount of time (in milliseconds) after which this message *MUST* no longer be delivered/processed. The message is considered expired if this attribute is set to a positive value and
+a|
+The amount of time (in milliseconds) after which this message is no longer delivered/processed.
+[.specitem,oft-sid="dsn~up-attributes-ttl-timeout~1",oft-needs="impl,utest"]
+--
+A consumer *MUST NOT* process an expired message. A message is expired if the TTL is > `0` and the consumer's current time is _after_ the message's creation time _plus_ its TTL.
+--
+[.specitem,oft-sid="dsn~up-attributes-ttl~1",oft-needs="impl,utest"]
+--
+A consumer *MUST* not consider a message expired if it has a TTL value of `0`.
+--
+
 
 stem:[t_{current} > t_{id} + ttl]
 
 |`traceparent`
 |https://w3c.github.io/trace-context/#traceparent-header[W3C Trace Context Level 3, traceparent]
 |no
-|A tracing identifier to use for correlating messages across the system. Intended to be compatible with https://github.com/cloudevents/spec/blob/main/cloudevents/extensions/distributed-tracing.md[CloudEvents distributed tracing extension].
+a|
+A tracing identifier to use for correlating messages across the system. Intended to be compatible with https://github.com/cloudevents/spec/blob/main/cloudevents/extensions/distributed-tracing.md[CloudEvents distributed tracing extension].
+
+[.specitem,oft-sid="dsn~up-attributes-traceparent~1",oft-needs="impl,utest"]
+--
+* *MAY* contain traceparent attribute.
+--
+
 
 |`payload format`
 |link:upayloadformat.adoc[UPayloadFormat]
 |no
-|The format of the payload (data).
+a|The format of the payload (data).
+[.specitem,oft-sid="dsn~up-attributes-payload-format~1",oft-needs="impl,utest"]
+--
+* *MAY* contain payload format attribute.
+--
 
 |===
 
@@ -96,13 +126,31 @@ The following table defines attributes that are used for publish messages in add
 
 |`type`
 |yes
-|*MUST* be set to `UMESSAGE_TYPE_PUBLISH`.
+a| 
+[.specitem,oft-sid="dsn~up-attributes-publish-type~1",oft-needs="impl,utest"]
+--
+*MUST* be set to `UMESSAGE_TYPE_PUBLISH`.
+--
 
 |`source`
 |yes
 a|A link:uri.adoc[UUri] representing the topic that this message is published to.
 
+[.specitem,oft-sid="dsn~up-attributes-publish-source~1",oft-needs="impl,utest"]
+--
 * The UUri's `resource_id` *MUST* be set to a value in range `[0x8000, 0xFFFE]`.
+--
+
+|`sink`
+|no (see Description)
+a|A link:uri.adoc[UUri] representing the receiver of this published message. This information is 
+only required when we are sending the published event between devices through a streamer. A uEntity sending a Publish message is not required to populate this information.
+
+[.specitem,oft-sid="dsn~up-attributes-publish-sink~1",oft-needs="impl,utest"]
+--
+* *MAY* be present in the message. If present, the UUri *MUST* only contain the `authority_name` field.
+--
+
 |===
 
 [#notification-attributes]
@@ -116,19 +164,29 @@ The following table defines attributes that are used for notification messages i
 
 |`type`
 |yes
-|*MUST* be set to `UMESSAGE_TYPE_NOTIFICATION`.
-
+a|
+[.specitem,oft-sid="dsn~up-attributes-notification-type~1",oft-needs="impl,utest"]
+--
+*MUST* be set to `UMESSAGE_TYPE_NOTIFICATION`.
+--
 |`source`
 |yes
-a|A link:uri.adoc[UUri] representing the component that this notification originates from.
+a|
+A link:uri.adoc[UUri] representing the component that this notification originates from.
 
+[.specitem,oft-sid="dsn~up-attributes-notification-source~1",oft-needs="impl,utest"]
+--
 * The UUri's `resource_id` *MUST* be set to a value in range `[0x8000, 0xFFFE]`.
+--
 
 |`sink`
 |yes
 a|A link:uri.adoc[UUri] representing the receiver of this notification.
 
+[.specitem,oft-sid="dsn~up-attributes-notification-sink~1",oft-needs="impl,utest"]
+--
 * The UUri's `resource_id` *MUST* be set to `0`.
+--
 
 |===
 
@@ -143,40 +201,67 @@ The following table defines attributes that are used for RPC request messages in
 
 |`type`
 |yes
-|*MUST* be set to `UMESSAGE_TYPE_REQUEST`.
+a|
+[.specitem,oft-sid="dsn~up-attributes-request-type~1",oft-needs="impl,utest"]
+--
+*MUST* be set to `UMESSAGE_TYPE_REQUEST`.
+--
 
 |`source`
 |yes
 a|The link:uri.adoc[UUri] that the service consumer expects to receive the response message at.
 
+[.specitem,oft-sid="dsn~up-attributes-request-source~1",oft-needs="impl,utest"]
+--
 * The UUri's `resource_id` *MUST* be set to `0`.
+--
 
 |`sink`
 |yes
 a|A link:uri.adoc[UUri] identifying the service provider's method to invoke.
 
+[.specitem,oft-sid="dsn~up-attributes-request-sink~1",oft-needs="impl,utest"]
+--
 * The UUri's `resource_id` *MUST* be set to a value in range `[1, 0x7FFF]`.
+--
 
 |`priority`
 |yes
 a|The link:qos.adoc[QoS] level that this message should be processed/delivered with.
 
+[.specitem,oft-sid="dsn~up-attributes-request-priority~1",oft-needs="impl,utest"]
+--
 * *MUST* be set to `UPRIORITY_CS4` or higher.
+--
+
 
 |`ttl`
 |yes
 a|The amount of time (in milliseconds) after which this request message should no longer be delivered to or processed by a service provider.
 
+[.specitem,oft-sid="dsn~up-attributes-request-ttl~1",oft-needs="impl,utest"]
+--
 * *MUST* be set to a value > 0
-
+--
 
 |`permission_level`
 |no
-|The service consumer's permission level as defined in link:permissions.adoc#_code_based_access_permissions_caps[Code-Based uE Access Permissions (CAPs)].
+a|The service consumer's permission level as defined in link:permissions.adoc#_code_based_access_permissions_caps[Code-Based uE Access Permissions (CAPs)].
+
+[.specitem,oft-sid="dsn~up-attributes-permission-level~1",oft-needs="impl,utest"]
+--
+* *MAY* contain permission level attribute.
+--
 
 |`token`
 |no
-|The service consumer's access token as defined in link:permissions.adoc#_token_based_access_permissionstaps[Token-Based uE Access Permissions (TAPs)].
+a|The service consumer's access token as defined in link:permissions.adoc#_token_based_access_permissionstaps[Token-Based uE Access Permissions (TAPs)].
+
+[.specitem,oft-sid="dsn~up-attributes-request-token~1",oft-needs="impl,utest"]
+--
+* *MAY* contain token attribute.
+--
+
 |===
 
 [#response-attributes]
@@ -190,39 +275,62 @@ The following table defines attributes that are used for RPC response messages i
 
 |`type`
 |yes
-|*MUST* be set to `UMESSAGE_TYPE_RESPONSE`.
+a|
+[.specitem,oft-sid="dsn~up-attributes-response-type~1",oft-needs="impl,utest"]
+--
+*MUST* be set to `UMESSAGE_TYPE_RESPONSE`.
+--
 
 |`source`
 |yes
 a|The link:uri.adoc[UUri] identifying the method that has been invoked and which this message is the outcome of.
 
+[.specitem,oft-sid="dsn~up-attributes-response-source~1",oft-needs="impl,utest"]
+--
 * The UUri's `resource_id` *MUST* be set to a value in range `[1, 0x7FFF]`.
+--
 
 |`sink`
 |yes
 a|The link:uri.adoc[UUri] that the service consumer expects to receive this response message at.
 
+[.specitem,oft-sid="dsn~up-attributes-response-sink~1",oft-needs="impl,utest"]
+--
 * The UUri's `resource_id` *MUST* be set to `0`.
+--
 
 |`reqid`
 |yes
 |The `id` property value of the request message that this is the response to.
 
 |`priority`
 |yes
-|The link:qos.adoc[QoS] level that this message should be processed/delivered with. *MUST* be the same value as that of the corresponding request message's `priority` attribute.
+a|
+The link:qos.adoc[QoS] level that this message should be processed/delivered with. 
+
+[.specitem,oft-sid="dsn~up-attributes-response-reqid~1",oft-needs="impl,utest"]
+--
+* *MUST* be the same value as that of the corresponding request message's `priority` attribute.
+--
 
 |`ttl`
 |no
-|The amount of time after which this response message should no longer be delivered to or processed by the service consumer.
+a|
+The amount of time after which this response message should no longer be delivered to or processed by the service consumer.
+
+[.specitem,oft-sid="dsn~up-attributes-response-ttl~1",oft-needs="impl,utest"]
+--
+* *MUST* be the same value as that of the corresponding request message's `ttl` attribute.
+--
 
 |`commstatus`
 |no
-|A link:../up-core-api/uprotocol/v1/ustatus.proto[UCode] indicating an error that has occurred during the delivery of either the RPC request or response message. A value of `0` or no value indicates that no communication error has occurred.
-
-|===
+a|A link:../up-core-api/uprotocol/v1/ustatus.proto[UCode] indicating an error that has occurred during the delivery of either the RPC request or response message. A value of `0` or no value indicates that no communication error has occurred.
 
+[.specitem,oft-sid="dsn~up-attributes-response-commstatus~1",oft-needs="impl,utest"]
+--
+* *MUST* contain commstatus attribute if the request message was not delivered successfully or the server was unable to process the request.
+--
 
-== Validation
+|===
 
-Each link:../languages.adoc[uProtocol Language Library] *MUST* provide means to assert the consistency of a message's attributes according to its type as defined in the sections above. The concrete implementation should follow common practices of the particular programming language.