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
UAttributes contain meta data describing a particular message’s purpose, content and processing requirements.
The diagram below shows the UAttributes class and its properties using UML2 notation.
|
Note
|
The UCode, UUri and UUID classes are defined in detail in Error Model Specification, UUri Specification and UUID Specification respectively. |
classDiagram
class UAttributes {
id: UUID
source: UUri
sink: UUri [0..1]
ttl : UInt32 [0..1]
commstatus: UCode [0..1]
permissionLevel: UInt32 [0..1]
requestId: UUID [0..1]
token: String [0..1]
traceparent: String [0..1]
}
class UMessageType {
<<Enumeration>>
Publish
Notification
RPC Request
RPC Response
}
class UPriority {
<<Enumeration>>
CS0
CS1
CS2
CS3
CS4
CS5
CS6
}
class UPayloadFormat {
<<Enumeration>>
UPAYLOAD_FORMAT_UNSPECIFIED
UPAYLOAD_FORMAT_PROTOBUF_WRAPPED_IN_ANY
UPAYLOAD_FORMAT_PROTOBUF
UPAYLOAD_FORMAT_JSON
UPAYLOAD_FORMAT_SOMEIP
UPAYLOAD_FORMAT_SOMEIP_TLV
UPAYLOAD_FORMAT_RAW
UPAYLOAD_FORMAT_TEXT
UPAYLOAD_FORMAT_SHM
}
UAttributes-->UMessageType : type
UAttributes--> "0..1" UPriority : priority
UAttributes--> "0..1" UPayloadFormat : payloadFormat
-
MUST implement the UAttributes Data Model using the language specific type system.
-
MUST support writing and reading of an instance of the UAttributes Data Model to/from a protobuf as defined in uattributes.proto.
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.
The following table defines attributes that are used for all message types:
| Name | Type | Mandatory | Description |
|---|---|---|---|
|
yes |
Every message MUST have a unique message identifier. The timestamp contained in the UUID is used as the message’s creation time. |
|
|
no |
The level of priority that this message should be processed/delivered with. A consumer MUST assume a message to have the default priority if not set explicitly. |
|
|
|
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 > \(expired := t_{current} > t_{id} + ttl\) A consumer MUST not consider a message expired if it has a TTL value of |
|
no |
A tracing identifier to use for correlating messages across the system. Intended to be compatible with CloudEvents distributed tracing extension.
|
|
|
no |
The format of the payload (data).
|
The following table defines attributes that are used for publish messages in addition to the common attributes:
| Attribute | Type | Mandatory | Description |
|---|---|---|---|
|
yes |
MUST be set to |
|
|
yes |
The topic that this message is published to.
|
|
|
no |
A uStreamer can set this property to indicate to an underlying transport implementation the authority of remote uEntities that have subscribed to the message’s topic. For this purpose, the streamer may add a UUri that:
|
The following table defines attributes that are used for notification messages in addition to the common attributes:
| Attribute | Type | Mandatory | Description |
|---|---|---|---|
|
yes |
MUST be set to |
|
|
yes |
A UUri representing the component that this notification originates from.
|
|
|
yes |
A UUri representing the receiver of this notification.
|
The following table defines attributes that are used for RPC request messages in addition to the common attributes:
| Attribute | Type | Mandatory | Description |
|---|---|---|---|
|
yes |
MUST be set to |
|
|
yes |
The UUri that the service consumer expects to receive the response message at.
|
|
|
yes |
A UUri identifying the service provider’s method to invoke.
|
|
|
yes |
The level of priority that this message should be processed/delivered with.
|
|
|
|
yes |
The amount of time (in milliseconds) after which this request message should no longer be delivered to or processed by a service provider.
|
|
|
no |
The service consumer’s permission level.
|
|
|
no |
The service consumer’s access token.
|
The following table defines attributes that are used for RPC response messages in addition to the common attributes:
| Attribute | Type | Mandatory | Description |
|---|---|---|---|
|
yes |
MUST be set to |
|
|
yes |
The UUri identifying the method that has been invoked and which this message is the outcome of.
|
|
|
yes |
The UUri that the service consumer expects to receive this response message at.
|
|
|
yes |
|
|
|
yes |
The level of priority that this message should be processed/delivered with.
|
|
|
|
yes |
The amount of time after which this response message should no longer be delivered to or processed by the service consumer.
|
|
no |
The outcome of the RPC. No value or |
The following table provides an overview of the payload formats supported by uProtocol.
| UPayloadFormat | MIME Type | Payload encoding |
|---|---|---|
|
N/A |
The payload format is unknown. Clients will need to have gained knowledge about the concrete encoding and semantics of the payload by means of an out-of-band mechanism. |
|
|
The network byte order serialization of a |
|
|
The network byte order serialization of the protobuf structure representing the payload data. |
|
|
The network byte order UTF-8 encoding of a JSON structure representing the payload data. |
|
|
The network byte order serialization of SOME/IP payload data. |
|
|
The network byte order serialization of SOME/IP TLV payload data. |
|
|
A byte array representing the payload data. |
|
|
The network byte order UTF-8 encoding of a unicode string representing the payload data. |
|
|
The network byte order address of a shared memory segment. |