uattributes.adoc

uProtocol Attributes (uAttributes)

Table of Contents

• 1. Overview
• 2. Common Message Attributes
• 3. Publish Message Attributes
• 4. Notification Message Attributes
• 5. RPC Request Message Attributes
• 6. RPC Response Message Attributes

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in IETF BCP14 (RFC2119 & RFC8174)

SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation

See the NOTICE file(s) distributed with this work for additional
information regarding copyright ownership.

This program and the accompanying materials are made available under
the terms of the Apache License Version 2.0 which is available at
https://www.apache.org/licenses/LICENSE-2.0

SPDX-FileType: DOCUMENTATION
SPDX-License-Identifier: Apache-2.0

1. Overview

UAttributes contain metadata describing a particular message’s purpose, content and processing requirements.

Note	Please refer to uattributes.proto for the latest version of the UAttributes data model.

uProtocol defines four types of messages:

Type	Description
Publish	A message that is used to notify all interested consumers about an event that has occurred.
Notification	A message that is used to inform a specific consumer about an event that has occurred.
RPC Request	A message that is used by a service consumer to invoke one of a service provider’s methods with some input data, expecting the service provider to reply with a response message.
RPC Response	A message that is used by a service provider to send the outcome of processing a request message from a service consumer.

Each type of message is described by a set of mandatory and optional attributes.

2. Common Message Attributes

The following table defines attributes that are used for all message types:

Name	Type	Mandatory	Description
id	UUID	yes	Every message MUST have a unique message identifier. The timestamp contained in the UUID is used as the message’s creation time.
priority	UPriority	no	The QoS level that this message should be processed/delivered with. A consumer MUST assume a message to have the default priority if not set explicitly.
ttl	unsigned integer	no	The amount of time (in milliseconds) after which this message is no longer delivered/processed. 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. A consumer MUST not consider a message expired if it has a TTL value of 0. \(t_{current} > t_{id} + ttl\)
traceparent	W3C Trace Context Level 3, traceparent	no	A tracing identifier to use for correlating messages across the system. Intended to be compatible with CloudEvents distributed tracing extension. MAY contain traceparent attribute.
payload format	UPayloadFormat	no	The format of the payload (data). MAY contain payload format attribute.

3. Publish Message Attributes

The following table defines attributes that are used for publish messages in addition to the common attributes:

Attribute	Mandatory	Description
type	yes	MUST be set to UMESSAGE_TYPE_PUBLISH.
source	yes	A UUri representing the topic that this message is published to. The UUri’s resource_id MUST be set to a value in range [0x8000, 0xFFFE].
sink	no (see Description)	A 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. MAY be present in the message. If present, the UUri MUST only contain the authority_name field.

4. Notification Message Attributes

The following table defines attributes that are used for notification messages in addition to the common attributes:

Attribute	Mandatory	Description
type	yes	MUST be set to UMESSAGE_TYPE_NOTIFICATION.
source	yes	A UUri representing the component that this notification originates from. The UUri’s resource_id MUST be set to a value in range [0x8000, 0xFFFE].
sink	yes	A UUri representing the receiver of this notification. The UUri’s resource_id MUST be set to 0.

5. RPC Request Message Attributes

The following table defines attributes that are used for RPC request messages in addition to the common attributes:

Attribute	Mandatory	Description
type	yes	MUST be set to UMESSAGE_TYPE_REQUEST.
source	yes	The UUri that the service consumer expects to receive the response message at. The UUri’s resource_id MUST be set to 0.
sink	yes	A UUri identifying the service provider’s method to invoke. The UUri’s resource_id MUST be set to a value in range [1, 0x7FFF].
priority	yes	The QoS level that this message should be processed/delivered with. MUST be set to UPRIORITY_CS4 or higher.
ttl	yes	The amount of time (in milliseconds) after which this request message should no longer be delivered to or processed by a service provider. MUST be set to a value > 0
permission_level	no	The service consumer’s permission level as defined in Code-Based uE Access Permissions (CAPs). MAY contain permission level attribute.
token	no	The service consumer’s access token as defined in Token-Based uE Access Permissions (TAPs). MAY contain token attribute.

6. RPC Response Message Attributes

The following table defines attributes that are used for RPC response messages in addition to the common attributes:

Attribute	Mandatory	Description
type	yes	MUST be set to UMESSAGE_TYPE_RESPONSE.
source	yes	The UUri identifying the method that has been invoked and which this message is the outcome of. The UUri’s resource_id MUST be set to a value in range [1, 0x7FFF].
sink	yes	The UUri that the service consumer expects to receive this response message at. 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 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.
ttl	no	The amount of time after which this response message should no longer be delivered to or processed by the service consumer. MUST be the same value as that of the corresponding request message’s ttl attribute.
commstatus	no	A 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. MUST contain commstatus attribute if the request message was not delivered successfully or the server was unable to process the request.