Skip to content

Commit 4cc618f

Browse files
author
czfdcn
committed
Cleanup of UAttributes & CloudEvent Specs
With the completion of uProtocol 1.5 specifications, the following change moves the UAttributes documentation to proto and cleans up the CloudEvent-to-UAttributes mapping requirements
1 parent 9d5b90c commit 4cc618f

5 files changed

Lines changed: 365 additions & 589 deletions

File tree

‎basics/README.adoc‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,8 @@ The following are the foundational requirements for uProtocol specifications:
3535
* *link:versioning.adoc[Versioning]*
3636
* *link:uri.adoc[URI (Addressing)]*
3737
* *link:error_model.adoc[Error Model]*
38-
* *link:cloudevents.adoc[Common Message Format: CloudEvents]*
3938
* *link:uuid.adoc[Unique Universal Identifiers (UUIDs)]*
4039
* *link:qos.adoc[Quality of Service & Priority]*
4140
* *link:delivery.adoc[Event Delivery]*
41+
* *link:cloudevents.adoc[CloudEvents & uProtocol]*
42+

‎basics/cloudevents.adoc‎

Lines changed: 324 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
= CloudEvents
22
:toc:
33
:sectnums:
4+
:stem: latexmath
45

56
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 https://www.rfc-editor.org/info/bcp14[IETF BCP14 (RFC2119 & RFC8174)]
67

@@ -54,7 +55,7 @@ Cloud Events answers the following in the metadata:
5455

5556
The specification is transport agnostic (can run over HTTP, MQTT, AMQP, NATS, Kafka), and comes with SDK in most common languages.
5657

57-
== CloudEvent Format vs Data Format
58+
=== CloudEvent Format vs Data Format
5859

5960
CloudEvents can be represented as objects (in the programming language of choice) as well as serialized to any binary or text encoding formats such as protobuf, JSON, AVRO, XML, etc.... CloudEvent are often referred to as "the envelope for data" as it holds the data and metadata.
6061

@@ -63,3 +64,325 @@ https://cloudevents.io/[CloudEvents] has defined a set of specifications for the
6364
NOTE: Additional formats and transports not covered by https://cloudevents.io/[CloudEvents.io] shall be covered in link:../up-l1/README.adoc[uP-L1 Specifications]
6465

6566

67+
== uProtocol CloudEvents
68+
The following section we shall elaborate how map link:uattrbutes.adoc[uProtocol Header Attributes (uAttributes)] to CloudEvents attributes.
69+
70+
71+
=== Common Attributes
72+
Common attributes apply to all message types.
73+
74+
.Common Message Header Attributes
75+
[width="100%",cols="12%,8%,12%,10%,54%",options="header",]
76+
[#common-message-attributes]
77+
|===
78+
|CE Attribute
79+
|https://github.com/eclipse-uprotocol/uprotocol-core-api/blob/main/src/main/proto/uattributes.proto[uProtocol Attribute]
80+
|CE Type
81+
|RFC2119
82+
|Description
83+
84+
85+
|https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#specversion[`specversion`]
86+
| N/A
87+
|String
88+
|*R*
89+
a|CloudEvent specification version. This is *NOT* the uProtocol version
90+
91+
* *MUST* be set to "1.0"
92+
93+
94+
|https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#id[`id`]
95+
|`id`
96+
|String
97+
|*R*
98+
a|Unique identifier for the CE
99+
100+
* *MUST* adhere to link:../basics/uuid.adoc[uProtocol UUID] requirements
101+
102+
103+
|https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#source-1[source]
104+
|N/A
105+
|https://www.rfc-editor.org/rfc/rfc3986#section-4.1[Uri-Reference]
106+
|*R*
107+
a|The Source (address) of the message per table below
108+
109+
.`source` Description
110+
[#message-source]
111+
!===
112+
!Type !Description
113+
114+
!*Publish & Notification*
115+
! The Producers topic
116+
117+
!*Request*
118+
!The calling uE response topic
119+
120+
!*Response*
121+
!Method URI
122+
!===
123+
124+
125+
* * *MUST* be long form URI per link:../basics/uri.adoc[URI Specifications]
126+
* *MUST* include the `authority`, `UE_NAME`, `UE_VERSION`
127+
* UE_VERSION
128+
** *MUST* include MAJOR
129+
** *MAY* include MINOR
130+
** *MUST NOT* include PATCH
131+
132+
133+
|https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#type[`type`]
134+
|`type`
135+
|String
136+
|*R*
137+
a|uProtocol CE type
138+
139+
* *MUST* be value defined in <<message-types>> table below
140+
141+
.Message Types
142+
[#message-types]
143+
!===
144+
!UMessageType !CE Value
145+
146+
!*`PUBLISH`*
147+
! `pub.v1`
148+
149+
!*`REQUEST`*
150+
!`req.v1`
151+
152+
!*`RESPONSE`*
153+
!`res.v1`
154+
155+
!===
156+
157+
158+
|https://github.com/cloudevents/spec/blob/main/subscriptions/spec.md#sink[`sink`]
159+
|link:README.adoc#_sink[`sink`]
160+
|https://www.rfc-editor.org/rfc/rfc3986#section-4.1[Uri-Reference]
161+
|*R\|O*
162+
a|URI pointing to the method to be invoked
163+
164+
* *MUST* be present if message type is *NOT* `pub.v1`
165+
* *MUST* be either a short form or long form URI per link:../basics/uri.adoc[URI Specifications]
166+
* *MUST* include destination authority (UDEVICE.UDOMAIN)
167+
* *MUST* contain destination UE_NAME and UE_VERSION and METHOD
168+
* METHOD
169+
** *MUST* be prepended with rpc.
170+
** *MUST* include method NAME
171+
* UE_VERSION
172+
** *MUST* include MAJOR
173+
** *MAY* include MINOR
174+
** *MUST NOT* include PATCH
175+
176+
|https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#datacontenttype[datacontenttype]
177+
|https://github.com/eclipse-uprotocol/uprotocol-core-api/blob/main/src/main/proto/upayload.proto[UPayloadFormat] (not part of UAttributes)
178+
|String
179+
|*O*
180+
a|Content type of data value. This attribute enables data to carry any type of content, whereby format and encoding might differ from that of the chosen event format
181+
182+
* *MUST* adhere to the format specified in https://tools.ietf.org/html/rfc2046[RFC 2046]
183+
* *MUST* be application/octet-stream for binary encoded data that is not protobuf
184+
* *SHALL* be application/x-protobuf if attribute is missing
185+
186+
187+
|`hash`
188+
|N/A. (Transport specific)
189+
|Binary
190+
|*O*
191+
|HMAC generated on the data portion of the message using a device key
192+
193+
194+
|`priority`
195+
|`priority`
196+
|String
197+
|*O*
198+
a| uProtocol Prioritization classifications per link:../../basics/qos.adoc[QoS]. When this field is missing, `CS0` is assumed.
199+
When the message _type_ is `req.v1`:
200+
201+
* *MUST* be set to `CS4` or greater
202+
203+
204+
|`ttl`
205+
|`ttl`
206+
|Uint32
207+
a|*R\|O*
208+
a|How long this event should live for after it was generated (in milliseconds). Event expires when:
209+
210+
stem:[t_current > t_{ce_id} + ce_ttl]
211+
212+
When the message _type_ is `req.v1`:
213+
214+
* Attribute *MUST* be present and value greater than 0
215+
216+
otherwise:
217+
218+
* Attribute *MAY* be present
219+
* When not present, or value is 0, message *MUST NOT* time out
220+
221+
222+
|===
223+
224+
225+
=== RPC Attributes
226+
Additional attributes are included for RPC for correlation, access control, and more.
227+
228+
NOTE: RPC response RESOURCE portion of a topic is: `rpc.response`
229+
230+
==== Request
231+
.Common Message Header Attributes
232+
[width="100%",cols="12%,18%,8%,8%,53%",options="header",]
233+
|===
234+
|CE Attribute
235+
|https://github.com/eclipse-uprotocol/uprotocol-core-api/blob/main/src/main/proto/uattributes.proto[uProtocol Attribute]
236+
|CE Type
237+
|RFC2119
238+
|Description
239+
240+
|`*token*`
241+
|`token`
242+
|String
243+
|*R\|O*
244+
a|Access token per link:../up-l2/permissions.adoc#_token_based_access_permissionstaps[Token-Based uE Access Permissions (TAPs)]
245+
246+
|`*plevel*`
247+
|`permission_level`
248+
|Integer
249+
|*R\|O*
250+
|Source (senders) uE permission level as defined in link:../up-l2/permissions.adoc#_code_based_access_permissions_caps[Code-Based uE Access Permissions (CAPs)]
251+
252+
|===
253+
254+
255+
==== Response
256+
257+
.RPC Response Message
258+
[width="100%",cols="13%,10%,13%,8%,25%,32%",options="header",]
259+
|===
260+
|CE Attribute
261+
|https://github.com/eclipse-uprotocol/uprotocol-core-api/blob/main/src/main/proto/uattributes.proto[uProtocol Attribute]
262+
| CE Type
263+
|RFC 2119
264+
|Description
265+
|Requirements
266+
267+
|`*reqid*`
268+
|`reqid`
269+
|String
270+
|*R*
271+
|Request Identifier a.k.a correlation ID between this response and the original request
272+
a|
273+
* *MUST* be the link:../basics/uuid.adoc[uProtocol UUID] from the original Request message (req.v1) that this response is for
274+
275+
|`*commstatus*`
276+
|`commstatus`
277+
|Integer
278+
|*O*
279+
|Communication error attribute populated by uP-L2 dispatchers only when an error has occurred in the delivery of RPC request or response events. +
280+
The contents of this attribute, if present, is the integer representation of https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto[google.rpc.Code]
281+
a|* *MUST* only be populated by Dispatchers when a deivery error has occured. See link:../../dispatchers/README.adoc[Dispatchers] for more information.
282+
283+
|===
284+
285+
286+
287+
== Data (Payload)
288+
289+
Data portion of the CE contains the application layer (uP-L2) message also known as the link:README.adoc#_upayload[UPayload].
290+
291+
292+
== CloudEvent Format
293+
In this section we will explain the format (encoding) for CloudEvent message and the impacts on the payload formats.
294+
295+
296+
.Formats
297+
[#ce-formats]
298+
[width="100%",cols="20%,15%,65%",options="header",]
299+
|===
300+
|CE Format |Encoding |Data Format Considerations
301+
302+
|https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/formats/protobuf-format.md[*Protobuf*]
303+
|Binary
304+
a|* *MUST* adhere to the https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/formats/protobuf-format.md[Protobuf Event Format for CloudEvents - Version 1.0.2] specifications
305+
306+
If link:README.adoc#_upayload[UPayload] is a protobuf message:
307+
308+
* *MUST* be packed as google.protobuf.Any and stored in field proto_data
309+
* *MUST NOT* set datacontenttype to "application/x-protobuf"
310+
* *MUST NOT* set dataschema to the URI of the protobuf message, this is optional as this information is already stored in the google.protobuf.Any
311+
312+
If the link:/README.adoc#_upayload[UPayload] is binary and _NOT_ a protobuf message:
313+
314+
* *MUST* be stored in the field binary_data
315+
* *MUST* set datacontenttype to "application/octet-stream"
316+
* *MAY* set dataschema to the URI-Reference schema of the data
317+
318+
|https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/formats/json-format.md[*JSON*]
319+
|Text
320+
a|* *MUST* adhere to https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/formats/json-format.md[JSON Event Format for CloudEvents - Version 1.0.2] specifications
321+
322+
If link:README.adoc#_upayload[UPayload] is a protobuf message:
323+
324+
* *MUST* be packed as google.protobuf.Any and stored in field data_base64 attribute,
325+
* *MUST NOT* set datacontenttype to "application/x-protobuf"
326+
* *MUST NOT* set dataschema to the URI of the protobuf message, this is optional as this information is already stored in the google.protobuf.Any
327+
328+
If link:README.adoc#_upayload[UPayload] is binary and _NOT_ a protobuf message:
329+
330+
* *MUST* be base64 encoded and stored in data_base64 attribute
331+
* *MUST* set datacontenttype to "application/octet-stream"
332+
* *MAY* set dataschema to the URI-Reference schema of the data
333+
334+
|===
335+
336+
337+
The following are additional recommendations when implementing the protocol:
338+
339+
* Data and CE *SHOULD* only be serialized once when it is to be transported over link:README.adoc#_utransport_interface[UTransport Interface]
340+
341+
342+
== Examples
343+
The following examples are using the JSON CE format
344+
345+
=== Publish
346+
[source]
347+
----
348+
{
349+
"specversion": "1.0",
350+
"id": "cf8b1bcd-30bd-43be-a8d3-ad1cde652e10",
351+
"source": "//VCU.VIN/body.access/1/door.front_left#Door",
352+
"type": "pub.v1",
353+
"priority": "CS1",
354+
"ttl": 10000,
355+
"data": /* Protobuf serialized Door Message*/
356+
}
357+
----
358+
359+
=== Request
360+
[source]
361+
----
362+
{
363+
"specversion": "1.0",
364+
"id": "cf8b1bcd-30bd-43be-a8d3-ad1cde652e10",
365+
"source": "//VCU.VIN/MyAppp/1/rpc.response",
366+
"sink": "//VCU.VIN/body.access/1/rpc.UpdateDoor",
367+
"type": "req.v1",
368+
"priority": "CS4",
369+
"ttl": 50000,
370+
"data": /* Protobuf serialized UpdateDoorRequest Message*/
371+
}
372+
----
373+
374+
=== Response
375+
[source]
376+
----
377+
{
378+
"specversion": "1.0",
379+
"id": "5b9fe861-8c1c-4899-9b07-ad1cde652e10",
380+
"source": "//VCU.VIN/body.access/1/rpc.UpdateDoor",
381+
"sink": "//VCU.VIN/MyAppp/1/rpc.response",
382+
"type": "res.v1",
383+
"priority": "CS4",
384+
"reqid": "cf8b1bcd-30bd-43be-a8d3-ad1cde652e10",
385+
"ttl": 50000,
386+
"data": /* Protobuf serialized google.rpc.Status Message*/
387+
}
388+
----

‎basics/uattributes.adoc‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
= uProtocol Attributes (uAttributes)
2+
:toc:
3+
:sectnums:
4+
5+
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 https://www.rfc-editor.org/info/bcp14[IETF BCP14 (RFC2119 & RFC8174)]
6+
7+
----
8+
Copyright (c) 2023 General Motors GTO LLC
9+
10+
Licensed to the Apache Software Foundation (ASF) under one
11+
or more contributor license agreements. See the NOTICE file
12+
distributed with this work for additional information
13+
regarding copyright ownership. The ASF licenses this file
14+
to you under the Apache License, Version 2.0 (the
15+
"License"); you may not use this file except in compliance
16+
with the License. You may obtain a copy of the License at
17+
18+
http://www.apache.org/licenses/LICENSE-2.0
19+
20+
Unless required by applicable law or agreed to in writing,
21+
software distributed under the License is distributed on an
22+
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
23+
KIND, either express or implied. See the License for the
24+
specific language governing permissions and limitations
25+
under the License.
26+
27+
SPDX-FileType: DOCUMENTATION
28+
SPDX-FileCopyrightText: 2023 General Motors GTO LLC
29+
SPDX-License-Identifier: Apache-2.0
30+
----
31+
32+
== Overview
33+
34+
uProtocol Header attributes that are common for all transports. The UAttributes message holds routing and UMessage attributes such as priority, permission, communication status and more
35+
36+
NOTE: Please refer to https://github.com/eclipse-uprotocol/uprotocol-core-api/blob/main/src/main/proto/uattributes.proto[uattributes.proto] for the latest version of the UAttributes data model

0 commit comments

Comments
 (0)