diff --git a/basics/README.adoc b/basics/README.adoc index c665bd4..b5dcba0 100644 --- a/basics/README.adoc +++ b/basics/README.adoc @@ -5,7 +5,7 @@ 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)] ---- -Copyright (c) 2023 General Motors GTO LLC +SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file @@ -25,7 +25,6 @@ specific language governing permissions and limitations under the License. SPDX-FileType: DOCUMENTATION -SPDX-FileCopyrightText: 2023 General Motors GTO LLC SPDX-License-Identifier: Apache-2.0 ---- @@ -41,6 +40,5 @@ The following are the foundational requirements for uProtocol specifications: * *link:umessage.adoc[uProtocol Message (UMessage)]* * *link:upayload.adoc[uProtocol Payload (UPayload)]* * *link:delivery.adoc[Event Delivery]* -* *link:cloudevents.adoc[CloudEvents]* * *link:permissions.adoc[Permissions]* diff --git a/basics/cloudevents.adoc b/basics/cloudevents.adoc deleted file mode 100644 index 95275fe..0000000 --- a/basics/cloudevents.adoc +++ /dev/null @@ -1,393 +0,0 @@ -= CloudEvents -:toc: -:sectnums: -:stem: latexmath - -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)] - ----- -Copyright (c) 2023 General Motors GTO LLC - -Licensed to the Apache Software Foundation (ASF) under one -or more contributor license agreements. See the NOTICE file -distributed with this work for additional information -regarding copyright ownership. The ASF licenses this file -to you under the Apache License, Version 2.0 (the -"License"); you may not use this file except in compliance -with the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, -software distributed under the License is distributed on an -"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -KIND, either express or implied. See the License for the -specific language governing permissions and limitations -under the License. - -SPDX-FileType: DOCUMENTATION -SPDX-FileCopyrightText: 2023 General Motors GTO LLC -SPDX-License-Identifier: Apache-2.0 ----- - -== Overview - -https://cloudevents.io/[CloudEvents] is a CNCF specification for describing events in a common way. We will use CloudEvents to formulate all kinds of uProtocol messages that will be sent to and from uEs. - -.CloudEvents -image::cloudevents.drawio.svg[CloudEvents] - -CloudEvents are: - -* An envelope for information about the occurrence of change in a system, it has a "from" address (source) with the "to" address is optional (sink) -* carry facts in metadata with standard attributes -* Self-contained & unique (you don't need to attach data to an event) -* Can be encoded/decoded into different formats without losing/modifying information - -Cloud Events answers the following in the metadata: - -* What kind of event?--> *type* -* When was it sent? --> *time* -* Who sent it? -->**source** -* What is the event unique identifier? --> *id* -* What is the shape of the data event? --> *dataschema* -* What is the event data? --> *data* - -The specification is transport agnostic (can run over HTTP, MQTT, AMQP, NATS, Kafka), and comes with SDK in most common languages. - -=== CloudEvent Format vs Data Format - -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. - -https://cloudevents.io/[CloudEvents] has defined a set of specifications for the well know formats (ex. https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/formats/json-format.md[JSON], https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/formats/protobuf-format.md[Protobuf], etc..) as well as how to send these messages over well-known transports (ex. https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/http-protocol-binding.md[HTTP], https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/mqtt-protocol-binding.md[MQTT], etc..). - -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] - - -== uProtocol CloudEvents -The following section we shall elaborate how map link:uattributes.adoc[uProtocol Header Attributes (uAttributes)] to CloudEvents attributes. - - -=== Common Attributes -Common attributes apply to all message types. - -.Common Message Header Attributes -[width="100%",cols="12%,8%,12%,10%,54%",options="header",] -[#common-message-attributes] -|=== -|CE Attribute -|uProtocol Attribute -|CE Type -|RFC2119 -|Description - - -|https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#specversion[`specversion`] -| N/A -|String -|*R* -a|CloudEvent specification version. This is *NOT* the uProtocol version - -* *MUST* be set to "1.0" - - -|https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#id[`id`] -|`id` -|String -|*R* -a|Unique identifier for the CE - -* *MUST* adhere to link:../basics/uuid.adoc[uProtocol UUID] requirements - - -|https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#source-1[source] -|N/A -|https://www.rfc-editor.org/rfc/rfc3986#section-4.1[Uri-Reference] -|*R* -a|The Source (address) of the message per table below - -.`source` Description -[#message-source] -!=== -!Type !Description - -!*Publish & Notification* -! The Producers topic - -!*Request* -!The calling uE response topic - -!*Response* -!Method URI -!=== - - -* * *MUST* be long form URI per link:../basics/uri.adoc[URI Specifications] -* *MUST* include the `authority`, `UE_NAME`, `UE_VERSION` -* UE_VERSION -** *MUST* include MAJOR -** *MAY* include MINOR -** *MUST NOT* include PATCH - - -|https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#type[`type`] -|`type` -|String -|*R* -a|uProtocol CE type - -* *MUST* be value defined in <> table below - -.Message Types -[#message-types] -!=== -!UMessageType !CE Value - -!*`PUBLISH`* -! `pub.v1` - -!*`REQUEST`* -!`req.v1` - -!*`RESPONSE`* -!`res.v1` - -!=== - - -|https://github.com/cloudevents/spec/blob/main/subscriptions/spec.md#sink[`sink`] -|link:README.adoc#_sink[`sink`] -|https://www.rfc-editor.org/rfc/rfc3986#section-4.1[Uri-Reference] -|*R\|O* -a|URI pointing to the method to be invoked - -* *MUST* be present if message type is *NOT* `pub.v1` -* *MUST* be either a short form or long form URI per link:../basics/uri.adoc[URI Specifications] -* *MUST* include destination authority (UDEVICE.UDOMAIN) -* *MUST* contain destination UE_NAME and UE_VERSION and METHOD -* METHOD -** *MUST* be prepended with rpc. -** *MUST* include method NAME -* UE_VERSION -** *MUST* include MAJOR -** *MAY* include MINOR -** *MUST NOT* include PATCH - -|https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#datacontenttype[datacontenttype] -|https://github.com/eclipse-uprotocol/up-core-api/blob/main/uprotocol/upayload.proto[UPayloadFormat] (not part of UAttributes) -|String -|*O* -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 - -* *MUST* adhere to the format specified in https://tools.ietf.org/html/rfc2046[RFC 2046] -* *MUST* be application/octet-stream for binary encoded data that is not protobuf -* *SHALL* be application/x-protobuf if attribute is missing - - -|`hash` -|N/A. (Transport specific) -|Binary -|*O* -|HMAC generated on the data portion of the message using a device key - - -|`priority` -|`priority` -|String -|*O* -a| uProtocol Prioritization classifications per link:../../basics/qos.adoc[QoS]. When this field is missing, `CS0` is assumed. -When the message _type_ is `req.v1`: - -* *MUST* be set to `CS4` or greater - - -|`ttl` -|`ttl` -|Uint32 -a|*R\|O* -a|How long this event should live for after it was generated (in milliseconds). Event expires when: - -stem:[t_current > t_{ce_id} + ce_ttl] - -When the message _type_ is `req.v1`: - -* Attribute *MUST* be present and value greater than 0 - -otherwise: - -* Attribute *MAY* be present -* When not present, or value is 0, message *MUST NOT* time out - -|`traceparent` -|`traceparent` -|String -|*O* -| Contains a version, trace ID, span ID, and trace options as defined in https://w3c.github.io/trace-context/#traceparent-header[section 3.2]. Intended to be compatible with https://github.com/cloudevents/spec/blob/main/cloudevents/extensions/distributed-tracing.md[CloudEvents distributed tracing extension]. - -|=== - - -=== RPC Attributes -Additional attributes are included for RPC for correlation, access control, and more. - -NOTE: RPC response RESOURCE portion of a topic is: `rpc.response` - -==== Request -.Common Message Header Attributes -[width="100%",cols="12%,18%,8%,8%,53%",options="header",] -|=== -|CE Attribute -|https://github.com/eclipse-uprotocol/up-core-api/blob/main/uprotocol/uattributes.proto[uProtocol Attribute] -|CE Type -|RFC2119 -|Description - -|`*token*` -|`token` -|String -|*R\|O* -a|Access token per link:../up-l2/permissions.adoc#_token_based_access_permissionstaps[Token-Based uE Access Permissions (TAPs)] - -|`*plevel*` -|`permission_level` -|Integer -|*R\|O* -|Source (senders) uE permission level as defined in link:../up-l2/permissions.adoc#_code_based_access_permissions_caps[Code-Based uE Access Permissions (CAPs)] - -|=== - - -==== Response - -.RPC Response Message -[width="100%",cols="13%,10%,13%,8%,25%,32%",options="header",] -|=== -|CE Attribute -|https://github.com/eclipse-uprotocol/up-core-api/blob/main/uprotocol/uattributes.proto[uProtocol Attribute] -| CE Type -|RFC 2119 -|Description -|Requirements - -|`*reqid*` -|`reqid` -|String -|*R* -|Request Identifier a.k.a correlation ID between this response and the original request -a| -* *MUST* be the link:../basics/uuid.adoc[uProtocol UUID] from the original Request message (req.v1) that this response is for - -|`*commstatus*` -|`commstatus` -|Integer -|*O* -|Communication error attribute populated by uP-L2 dispatchers only when an error has occurred in the delivery of RPC request or response events. + -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] -a|* *MUST* only be populated by Dispatchers when a deivery error has occured. See link:../../dispatchers/README.adoc[Dispatchers] for more information. - -|=== - - - -== Data (Payload) - -Data portion of the CE contains the application layer (uP-L2) message also known as the link:README.adoc#_upayload[UPayload]. - - -== CloudEvent Format -In this section we will explain the format (encoding) for CloudEvent message and the impacts on the payload formats. - - -.Formats -[#ce-formats] -[width="100%",cols="20%,15%,65%",options="header",] -|=== -|CE Format |Encoding |Data Format Considerations - -|https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/formats/protobuf-format.md[*Protobuf*] -|Binary -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 - -If link:README.adoc#_upayload[UPayload] is a protobuf message: - -* *MUST* be packed as google.protobuf.Any and stored in field proto_data -* *MUST NOT* set datacontenttype to "application/x-protobuf" -* *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 - -If the link:/README.adoc#_upayload[UPayload] is binary and _NOT_ a protobuf message: - -* *MUST* be stored in the field binary_data -* *MUST* set datacontenttype to "application/octet-stream" -* *MAY* set dataschema to the URI-Reference schema of the data - -|https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/formats/json-format.md[*JSON*] -|Text -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 - -If link:README.adoc#_upayload[UPayload] is a protobuf message: - -* *MUST* be packed as google.protobuf.Any and stored in field data_base64 attribute, -* *MUST NOT* set datacontenttype to "application/x-protobuf" -* *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 - -If link:README.adoc#_upayload[UPayload] is binary and _NOT_ a protobuf message: - -* *MUST* be base64 encoded and stored in data_base64 attribute -* *MUST* set datacontenttype to "application/octet-stream" -* *MAY* set dataschema to the URI-Reference schema of the data - -|=== - - -The following are additional recommendations when implementing the protocol: - -* Data and CE *SHOULD* only be serialized once when it is to be transported over link:README.adoc#_utransport_interface[UTransport Interface] - - -== Examples -The following examples are using the JSON CE format - -=== Publish -[source] ----- -{ - "specversion": "1.0", - "id": "cf8b1bcd-30bd-43be-a8d3-ad1cde652e10", - "source": "//VCU.VIN/body.access/1/door.front_left#Door", - "type": "pub.v1", - "priority": "CS1", - "ttl": 10000, - "data": /* Protobuf serialized Door Message*/ -} ----- - -=== Request -[source] ----- -{ - "specversion": "1.0", - "id": "cf8b1bcd-30bd-43be-a8d3-ad1cde652e10", - "source": "//VCU.VIN/MyAppp/1/rpc.response", - "sink": "//VCU.VIN/body.access/1/rpc.UpdateDoor", - "type": "req.v1", - "priority": "CS4", - "ttl": 50000, - "data": /* Protobuf serialized UpdateDoorRequest Message*/ -} ----- - -=== Response -[source] ----- -{ - "specversion": "1.0", - "id": "5b9fe861-8c1c-4899-9b07-ad1cde652e10", - "source": "//VCU.VIN/body.access/1/rpc.UpdateDoor", - "sink": "//VCU.VIN/MyAppp/1/rpc.response", - "type": "res.v1", - "priority": "CS4", - "reqid": "cf8b1bcd-30bd-43be-a8d3-ad1cde652e10", - "ttl": 50000, - "data": /* Protobuf serialized google.rpc.Status Message*/ -} ----- diff --git a/basics/qos.adoc b/basics/qos.adoc index 0795a2c..265d5a2 100644 --- a/basics/qos.adoc +++ b/basics/qos.adoc @@ -5,7 +5,7 @@ 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)] ---- -Copyright (c) 2023 General Motors GTO LLC +SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file @@ -25,28 +25,33 @@ specific language governing permissions and limitations under the License. SPDX-FileType: DOCUMENTATION -SPDX-FileCopyrightText: 2023 General Motors GTO LLC SPDX-License-Identifier: Apache-2.0 ---- -Prioritization is used to control QoS at uP-L1 between devices. This document will follow https://datatracker.ietf.org/doc/html/rfc4594[RFC4594] _Configuration Guidelines for DiffServ Service Classes_. +uProtocol allows messages to be exchanged between uEntities on the same and/or different devices. The network bandwidth and/or CPU cycles available for performing this task may be limited, though. uProtocol therefore supports priority based message processing at the link:../up-l1/README.adoc[Transport] and link:../up-l2/README.adoc[Communication Layer] based on https://datatracker.ietf.org/doc/html/rfc4594[RFC4594 - Configuration Guidelines for DiffServ Service Classes]. -* All messages *MUST* be assigned a priority -* Every topic *MUST* have a priority code associated with it. -* Default priority when not assigned *MUST* be CS1 +For this purpose, each link:umessage.adoc[UMessage] is assigned to one of the following service classes: .QoS Classifications [width="100%",cols="8%,49%,43%",options="header",] |=== -|Class |Description |Use Case +|Class |Description |Typical Use Case |*CS0* |Low Priority. No bandwidth assurance |File Transfer |*CS1* |Standard, undifferentiated application |General (unclassified) |*CS2* |Operations, Administration, and Management |Streamer messages (sub, connect, etc…) |*CS3* |Multimedia streaming |Video Streaming -|*CS4* |Real-time interactive |High priority (rpc events) +|*CS4* |Real-time interactive |High priority (RPC events) |*CS5* |Signaling |Important |*CS6* |Network control |Safety Critical |=== -NOTE: Please see link:../up-l2/README.adoc[uP-L2 Specifications] for values used per message type. +These classes are represented by the values of the link:../up-core-api/uprotocol/uattributes.proto[UPriority protobuf enum]. + +* A UMessage *MAY* be assigned _explicitly_ to a service class by setting its `attributes.priority` property to the desired value. +[#default-priority] +* A UMessage *MUST* be considered to belong to class `CS1`, if its priority is not set explicitly. +* Every topic *MUST* have a priority code associated with it. +* link:../upclient.adoc[uProtocol Client Libraries] *SHOULD* map the message's service class to a corresponding mechanism of the underlying transport protocol, if available. +* link:../up-l2/dispatchers/README.adoc[uProtocol Dispatchers] *SHOULD* consider the message's service class as part of their message scheduling strategy. + diff --git a/basics/uattributes.adoc b/basics/uattributes.adoc index 7570f03..ff929f8 100644 --- a/basics/uattributes.adoc +++ b/basics/uattributes.adoc @@ -1,11 +1,12 @@ = uProtocol Attributes (uAttributes) :toc: :sectnums: +:stem: latexmath 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)] ---- -Copyright (c) 2023 General Motors GTO LLC +SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file @@ -25,12 +26,190 @@ specific language governing permissions and limitations under the License. SPDX-FileType: DOCUMENTATION -SPDX-FileCopyrightText: 2023 General Motors GTO LLC SPDX-License-Identifier: Apache-2.0 ---- == Overview -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 +UAttributes contain metadata describing a particular message's purpose, content and processing requirements. -NOTE: Please refer to hlink:../../up-core-api/uprotocol/uattributes.proto[uattributes.proto] for the latest version of the UAttributes data model +NOTE: Please refer to link:../up-core-api/uprotocol/uattributes.proto[uattributes.proto] for the latest version of the UAttributes data model. + +uProtocol defines four types of messages: + +[%autowidth] +|=== +|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 servcice consumer. +|=== + +Each type of message is described by a set of mandatory and optional attributes. + +[#common-attributes] +== Common Message Attributes + +The following table defines attributes that are used for all message types: + +[%autowidth] +|=== +|Name |Type |Mandatory |Description + +|`id` +|link:uuid.adoc[UUID] +|yes +|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. + +|`ttl` +|`unsigned integer` +|no +|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 + +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]. + +|=== + +[#publish-attributes] +== Publish Message Attributes + +The following table defines attributes that are used for publish messages in addition to the common attributes: + +[%autowidth] +|=== +|Attribute |Mandatory |Description + +|`type` +|yes +|*MUST* be set to `UMESSAGE_TYPE_PUBLISH`. + +|`source` +|yes +|A link:uri.adoc[UUri] representing the topic that this message is published to. + +|=== + +[#notification-attributes] +== Notification Message Attributes + +The following table defines attributes that are used for notification messages in addition to the common attributes: + +[%autowidth] +|=== +|Attribute |Mandatory |Description + +|`type` +|yes +|*MUST* be set to `UMESSAGE_TYPE_NOTIFICATION`. + +|`source` +|yes +|A link:uri.adoc[UUri] representing the component that this notification originates from. + +|`sink` +|yes +|A link:uri.adoc[UUri] representing the receiver of this notification. + +|=== + +[#request-attributes] +== RPC Request Message Attributes + +The following table defines attributes that are used for RPC request messages in addition to the common attributes: + +[%autowidth] +|=== +|Attribute |Mandatory |Description + +|`type` +|yes +|*MUST* be set to `UMESSAGE_TYPE_REQUEST`. + +|`source` +|yes +|The link:uri.adoc[UUri] that the service consumer expects to receive the response message at. + +|`sink` +|yes +|A link:uri.adoc[UUri] identifying the service provider's method to invoke. + +|`priority` +|yes +a|The link:qos.adoc[QoS] level that this message should be processed/delivered with. + +* *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. + +* *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)]. + +|`token` +|no +|The service consumer's access token as defined in link:permissions.adoc#_token_based_access_permissionstaps[Token-Based uE Access Permissions (TAPs)]. +|=== + +[#response-attributes] +== RPC Response Message Attributes + +The following table defines attributes that are used for RPC response messages in addition to the common attributes: + +[%autowidth] +|=== +|Attribute |Mandatory |Description + +|`type` +|yes +|*MUST* be set to `UMESSAGE_TYPE_RESPONSE`. + +|`source` +|yes +|The link:uri.adoc[UUri] identifying the method that has been invoked and which this message is the outcome of. + +|`sink` +|yes +|The link:uri.adoc[UUri] that the service consumer expects to receive this response message at. + +|`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. + +|`ttl` +|no +|The amount of time after which this response message should no longer be delivered to or processed by the service consumer. + +|`commstatus` +|no +|A link:../up-core-api/uprotocol/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. + +|=== diff --git a/basics/umessage.adoc b/basics/umessage.adoc index 2dd4f22..5fe74cb 100644 --- a/basics/umessage.adoc +++ b/basics/umessage.adoc @@ -5,7 +5,7 @@ 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)] ---- -Copyright (c) 2024 General Motors GTO LLC +SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file @@ -25,12 +25,11 @@ specific language governing permissions and limitations under the License. SPDX-FileType: DOCUMENTATION -SPDX-FileCopyrightText: 2024 General Motors GTO LLC SPDX-License-Identifier: Apache-2.0 ---- == Overview -UMessage is the top-level message type for the uProtocol. It contains a link:uri.adoc[UUri] (source address), link:uattributes.adoc[UAttributes] (uProtocol header), and link:upayload.adoc[UPayload] (the message payload). UMessage is the common way to represent messages sent between uEs over any communication protocol/middleware. +UMessage is the top-level message type for the uProtocol. It consists of link:uattributes.adoc[message metadata] and (optional) link:upayload.adoc[payload]. UMessage is the common way to represent messages sent between uEntities over any communication protocol/middleware. -NOTE: Please refer to link:../../up-core-api/uprotocol/umessage.proto[umessage.proto] for more details. +NOTE: Please refer to link:../up-core-api/uprotocol/umessage.proto[umessage.proto] for more details. diff --git a/basics/upayload.adoc b/basics/upayload.adoc index c44bc31..a86d0e8 100644 --- a/basics/upayload.adoc +++ b/basics/upayload.adoc @@ -5,7 +5,7 @@ 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)] ---- -Copyright (c) 2024 General Motors GTO LLC +SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file @@ -25,11 +25,49 @@ specific language governing permissions and limitations under the License. SPDX-FileType: DOCUMENTATION -SPDX-FileCopyrightText: 2024 General Motors GTO LLC SPDX-License-Identifier: Apache-2.0 ---- == Overview -UPayload contains the actual message payload (either by value or reference) as well as metadata such as the format, size, etc... -NOTE: Please refer to link:../../up-core-api/uprotocol/upayload.proto[upayload.proto] for more details +UPayload is a wrapper around a message's payload data, either by value or reference, as well as some metadata describing the payload like format, size, etc. + +NOTE: Please refer to link:../up-core-api/uprotocol/upayload.proto[upayload.proto] for more details + +== Payload Format + +The following table provides an overview of the payload formats supported by uProtocol. + +[%autowidth] +|=== +|UPayloadFormat |MIME Type |Payload encoding + +|`UPAYLOAD_FORMAT_PROTOBUF_WRAPPED_IN_ANY` +|`application/x-protobuf` +|The message payload *MUST* be the network byte order serialization of a `google.protobuf.Any` structure that contains the payload itself along with the schema URI indicating the (protobuf) type of the payload. + +|`UPAYLOAD_FORMAT_PROTOBUF` +|`application/protobuf` +|The message payload *MUST* be the network byte order serialization of the protobuf structure representing the payload data. + +|`UPAYLOAD_FORMAT_JSON` +|`application/json` +|The message payload *MUST* be the network byte order UTF-8 encoding of a JSON structure representing the payload data. + +|`UPAYLOAD_FORMAT_SOMEIP` +|`application/x-someip` +|The message payload *MUST* be the network byte order serialization of SOME/IP payload data. + +|`UPAYLOAD_FORMAT_SOMEIP_TLV` +|`application/x-someip_tlv` +|The message payload *MUST* be the network byte order serialization of SOME/IP TLV payload data. + +|`UPAYLOAD_FORMAT_RAW` +|`application/octet-stream` +|The message payload *MUST* be a byte array representing the payload data. + +|`UPAYLOAD_FORMAT_TEXT` +|`text/plain` +|The message payload *MUST* be the network byte order UTF-8 encoding of a unicode string representing the payload data. + +|=== diff --git a/up-core-api/uprotocol/uattributes.proto b/up-core-api/uprotocol/uattributes.proto index 1e3d8fd..7e1a98e 100644 --- a/up-core-api/uprotocol/uattributes.proto +++ b/up-core-api/uprotocol/uattributes.proto @@ -1,5 +1,5 @@ /* - * Copyright (c) 2023 General Motors GTO LLC + * SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation * * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file @@ -19,7 +19,6 @@ * under the License. * * SPDX-FileType: SOURCE - * SPDX-FileCopyrightText: 2023 General Motors GTO LLC * SPDX-License-Identifier: Apache-2.0 */ syntax = "proto3"; @@ -38,70 +37,39 @@ option java_multiple_files = true; // Metadata describing a particular message's purpose, content and processing requirements. // Each type of message is described by a set of mandatory and optional attributes. message UAttributes { - // A unique message identifier as defined by https://github.com/eclipse-uprotocol/uprotocol-spec/blob/main/basics/uuid.adoc[uProtocol UUID]. - // The timestamp contained in the UUID indicates the message's creation time. + // A unique message identifier. UUID id = 1; // This message's type which also indicates its purpose and determines contraints on the other properties. UMessageType type = 2; // The origin (address) of this message. - // - // Publish messages MUST have this property set to a URI representing the topic that this message is published to. - // Notification messages MUST have this property set to a URI representing the component that this notification originates from. - // RPC Request messages MUST have this property set to the URI that the service consumer expects to receive the response message at. - // RPC Response messages MUST have this property set to a URI identifying the method that has been invoked and which this message is the outcome of. UUri source = 3; // The destination (address) of this message. - // - // Publish messages MUST NOT have this property set to any value. - // Notification messages MUST have this property set to a URI representing the receiver of this notification. - // RPC Request messages MUST have this property set to a URI identifying the service provider's method to invoke. - // RPC Response messages MUST have this property set to the URI that the service consumer expects to receive this response message at. UUri sink = 4; - // The QoS level that this message should be processed/delivered with. If not specified explicitly, the - // https://github.com/eclipse-uprotocol/up-spec/blob/main/basics/qos.adoc#default-priority[default priority level] is assumed. - // - // RPC Request messages MUST have this property set to a value of `UPRIORITY_CS4` or higher. - // RPC Response messages MUST have this property set to the same value as that of the corresponding RPC Request message. + // The QoS level that this message should be processed/delivered with. UPriority priority = 5; // The amount of time (in milliseconds) after which this message MUST NOT be delivered/processed anymore. - // A message MUST be considered expired, if this attribute is set to a positive value and - // \$t_{current} > t_{id} + ttl\$ - // - // RPC Request messages MUST have this property set to a value > 0. optional uint32 ttl = 6; - // The service consumer's permission level as defined in - // https://github.com/eclipse-uprotocol/up-spec/blob/main/basics/permissions.adoc[Permissions]. - // - // Publish, Notification and RPC Response messages MUST NOT have this property set to any value. + // The service consumer's permission level. optional uint32 permission_level = 7; // A UCode indicating an error that has occurred // during the delivery of either an RPC Request or Response message. - // A value of `0` or no value indicates that there was no communication error. - // - // Publish, Notification and RPC Request messages MUST NOT have this property set to any value. optional UCode commstatus = 8; // The identifier that a service consumer can use to correlate an RPC Repsonse message with its RPC Request. - // - // RPC Response messages MUST have this property set to the value of the `id` property of the request message - // that this is the response to. - // Publish, Notification and RPC Request messages MUST NOT have this property set to any value. UUID reqid = 9; - // The service consumer's access token as defined in - // https://github.com/eclipse-uprotocol/up-spec/blob/main/basics/permissions.adoc[Permissions]. - // - // Publish, Notification and RPC Response messages MUST NOT have this property set to any value. + // The service consumer's access token. optional string token = 10; - // A tracing identifier to be used for correlating messages across the system. + // 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 optional string traceparent = 11; } @@ -109,19 +77,12 @@ message UAttributes { // A subset of UAttributes used for RPC method invocation. message CallOptions { // The QoS level that this request should be processed/delivered with. - // - // MUST be set to a value of `UPRIORITY_CS4` or higher. UPriority priority = 1; // The amount of time (in milliseconds) after which this request MUST NOT be delivered/processed anymore. - // A request MUST be considered expired, if this attribute is set to a positive value and - // \$t_{current} > t_{id} + ttl\$ - // - // MUST be set to a value > 0. uint32 ttl = 2; - // The service consumer's access token as defined in - // https://github.com/eclipse-uprotocol/up-spec/blob/main/basics/permissions.adoc[Permissions]. + // The service consumer's access token. optional string token = 3; } diff --git a/up-l1/README.adoc b/up-l1/README.adoc index 759b6b3..fbdbfd2 100644 --- a/up-l1/README.adoc +++ b/up-l1/README.adoc @@ -5,7 +5,7 @@ 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)] ---- -Copyright (c) 2023 General Motors GTO LLC +SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file @@ -25,7 +25,6 @@ specific language governing permissions and limitations under the License. SPDX-FileType: DOCUMENTATION -SPDX-FileCopyrightText: 2023 General Motors GTO LLC SPDX-License-Identifier: Apache-2.0 ---- @@ -70,7 +69,7 @@ NOTE: uProtocol data model used by the uTransport interface are declared in http * *MUST* contain the method `void onReceive(UMessage&)` that is called by the Transport to notify (callback) the client -== uTransport +== UTransport The transport layer API responsible for point-2-point communication. The interface provides common functionality across all transport implementations. @@ -220,12 +219,16 @@ NOTE: Delivery method advertising shall be defined later == Transport Specifics -Below is an non-exhausted list of transport specific requirements to ensure consistency across implementations of the same or different languages: +Below is an non-exhaustive list of transport specific requirements to ensure consistency across implementations of the same or different languages: -* link:sommr.adoc[*SommR*] * link:binder.adoc[*Android Binder*] -* link:zenoh.adoc[*Zenoh*] -* link:ecal.adoc[*ECAL*] -* link:p3comm.adoc[*P3Comm*] +* link:zenoh.adoc[*Eclipse Zenoh*] +* link:ecal.adoc[*Eclipse ECAL*] +* link:p3comm.adoc[*Eclipse P3Comm*] * link:mqtt.adoc[*MQTT*] -* link:https.adoc[*HTTP*] +* link:http.adoc[*HTTP*] +* link:someip/README.adoc[*SOME/IP*] + +Implementers of `UTransport` *MAY* choose to employ link:https://cloudevents.io/[CloudEvents] as a means to map UMessages to the underlying transport's Packet Data Unit (PDU). In order to provide for consistency across implementations, such transport implementations *MUST* adhere to + +* link:cloudevents.adoc[*UMessage mapping to CloudEvents*] diff --git a/up-l1/cloudevents.adoc b/up-l1/cloudevents.adoc new file mode 100644 index 0000000..db93970 --- /dev/null +++ b/up-l1/cloudevents.adoc @@ -0,0 +1,343 @@ += CloudEvents +:toc: +:sectnums: + +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)] + +---- +SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation + +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. + +SPDX-FileType: DOCUMENTATION +SPDX-License-Identifier: Apache-2.0 +---- + +== Overview + +https://cloudevents.io/[CloudEvents] is a specification hosted by the https://cncf.io/[Cloud Native Computing Foundation] (CNCF) for describing events in a common way. + +The CloudEvents specification defines an envelope for carrying information about the occurrence of a noteworthy event in a system. + +.CloudEvents envelope +image::cloudevents.drawio.svg[CloudEvents] + +CloudEvents + +* are self-contained & unique, +* contain standardized metadata in the header, +* contain optional context information in its data section, +* can be represented using different formats without losing/modifying information. + +The metadata contained in an event covers questions like + +* What kind of event has occurred? +* When did it occur? +* Where did it occur? +* What context did the event occur in? + +Support for using CloudEvents is available for many programming languages by means of corresponding SDKs. + +=== Event Format and Transport Binding + +The https://cloudevents.io/[CloudEvents] project has defined a set *Formats* which describe how events can be expressed using https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/formats/json-format.md[JSON], https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/formats/protobuf-format.md[Protobuf] or https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/formats/avro-format.md[Apache Avro]. + +The accompanying *Bindings* describe how events can be sent via well-known transport protocols like https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/http-protocol-binding.md[HTTP], https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/mqtt-protocol-binding.md[MQTT] etc. + + +== uMessage Mapping + +uProtocol uses link:umessage.adoc[UMessages] to exchange information between uEntities. +The following sections define the mapping between UMessages and CloudEvents. + +=== uAttributes Mapping + +The table below defines the mapping of uAttributes to CloudEvent attributes. +This mapping MUST be used by link:../upclient.adoc[uProtocol Client Libraries] which use CloudEvents for the binding to a particular transport protocol. + +.Mapping of uAttributes to CloudEvent properties +[width="100%",cols="12%,8%,10%,70%",options="header",] +|=== +|uAttributes Property +|CloudEvent Attribute +|CE Type +|Description + + +| N/A +|https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#specversion[`specversion`] +|String +a|CloudEvent specification version. This is *NOT* the uProtocol version + +* MUST be set to `1.0` + + +|`type` +|https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#type[`type`] +|String +a|The type of the message + +* MUST be set to the value of the `uprotocol.ce_name` option defined for the +link:../up-core-api/uprotocol/uattributes.proto[UMessageType enum]. + + +|`id` +|https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#id[`id`] +|String +a|Unique identifier for the message + +* MUST be set to the https://www.rfc-editor.org/rfc/rfc4122.html#section-3[hyphenated string representation] of the UUID. + + +|`source` +|https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#source-1[source] +|Uri-Reference +a|The origin (address) of the message + +* MUST be set to either the long or short form link:uri.adoc[serialization of the URI] + + +|`sink` +|`sink` +|Uri-Reference +a|The destination (address) of the message + +* MUST be set to either the long or short form link:uri.adoc[serialization of the URI] + + +|`priority` +|`priority` +|String +a| The message's priority as defined by link:qos.adoc[QoS]. + +* MUST be set to the value of the `uprotocol.ce_name` option defined for the +link:../up-core-api/uprotocol/uattributes.proto[UPriority enum]. + + +|`ttl` +|`ttl` +|Integer +a|The amount of time (in milliseconds) after which this message MUST no longer be delivered/processed. + + +|`token` +|`token` +|String +a|The service consumer's access token. + +|`permission_level` +|`plevel` +|Integer +|The service consumer's permission level as defined in link:../up-l2/permissions.adoc#_code_based_access_permissions_caps[Code-Based uE Access Permissions (CAPs)] + + +|`reqid` +|`reqid` +|String +a|The identifier that a service consumer can use to correlate an RPC Repsonse message with its RPC Request. + +* MUST be set to the https://www.rfc-editor.org/rfc/rfc4122.html#section-3[hyphenated string representation] of the UUID. + +|`commstatus` +|`commstatus` +|Integer +a|A code indicating an error that has occurred during the delivery of either an RPC Request or Response message. + +* MUST be set to the link:../up-core-api/uprotocol/ustatus.proto[UCode]'s integer value + +|`traceparent` +|https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/extensions/distributed-tracing.md#traceparent[traceparent] +|String +|A tracing identifier to use for correlating messages across the system. + +|=== + +[#ce-formats] +=== uPayload Mapping + +The sections below define the mapping of uPayload to CloudEvent attributes. + +==== Mapping to CloudEvent Protobuf Format + +The rules defined in https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/formats/protobuf-format.md[Protobuf Event Format for CloudEvents, Version 1.0.2] MUST be applied when mapping UPayload to CloudEvents using the Protobuf Format. The table below defines specific values to use for the different UMessage payload types. + +This mapping MUST be used by link:../upclient.adoc[uProtocol Client Libraries] which use the Protobuf Event Format for the binding to a particular transport protocol. + +[%autowidth] +|=== +|UPayload Type |CE `datacontenttype` |CE `dataschema` |CE Property to map Payload Data to + +|`UPAYLOAD_FORMAT_PROTOBUF_WRAPPED_IN_ANY` +|`-` +|`-` +|`proto_data` + +|`UPAYLOAD_FORMAT_PROTOBUF` +|`application/protobuf` +|*SHOULD* be set to a URI-Reference identifying the schema that the data adheres to +|`proto_data` + +|`UPAYLOAD_FORMAT_JSON` +|`application/json` +|*MAY* be set to a URI-Reference identifying the schema that the data adheres to +|`text_data` + +|`UPAYLOAD_FORMAT_SOMEIP` +|`application/x-someip` +|*MAY* be set to a URI-Reference identifying the schema that the data adheres to +|`binary_data` + +|`UPAYLOAD_FORMAT_SOMEIP_TLV` +|`application/x-someip_tlv` +|*MAY* be set to a URI-Reference identifying the schema that the data adheres to +|`binary_data` + +|`UPAYLOAD_FORMAT_RAW` +|`application/octet-stream` +|*MAY* be set to a URI-Reference identifying the schema that the data adheres to +|`binary_data` + +|`UPAYLOAD_FORMAT_TEXT` +|`text/plain` +|*MAY* be set to a URI-Reference identifying the schema that the data adheres to +|`text_data` + +|=== + + +==== Mapping to CloudEvent JSON Format + +The rules defined in https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/formats/json-format.md[JSON Event Format for CloudEvents, Version 1.0.2] MUST be applied when mapping UPayload to CloudEvents using the JSON Format. The table below defines specific values to use for the different UMessage payload types. + +This mapping MUST be used by link:../upclient.adoc[uProtocol Client Libraries] which use the JSON Event Format for the binding to a particular transport protocol. + +[%autowidth] +|=== +|UPayloadFormat |CE `datacontenttype` |CE `dataschema` |CE Property to map Payload to + +|`UPAYLOAD_FORMAT_PROTOBUF_WRAPPED_IN_ANY` +|`-` +|`-` +|`data_base64` + +|`UPAYLOAD_FORMAT_PROTOBUF` +|`application/protobuf` +|*SHOULD* be set to a URI-Reference identifying the schema that the data adheres to +|`data_base64` + +|`UPAYLOAD_FORMAT_JSON` +|`application/json` +|*MAY* be set to a URI-Reference identifying the schema that the data adheres to +|`data` + +|`UPAYLOAD_FORMAT_SOMEIP` +|`application/x-someip` +|*MAY* be set to a URI-Reference identifying the schema that the data adheres to +|`data_base64` + +|`UPAYLOAD_FORMAT_SOMEIP_TLV` +|`application/x-someip_tlv` +|*MAY* be set to a URI-Reference identifying the schema that the data adheres to +|`data_base64` + +|`UPAYLOAD_FORMAT_RAW` +|`application/octet-stream` +|*MAY* be set to a URI-Reference identifying the schema that the data adheres to +|`data_base64` + +|`UPAYLOAD_FORMAT_TEXT` +|`text/plain` +|*MAY* be set to a URI-Reference identifying the schema that the data adheres to +|`data` + +|=== + +==== Additional Recommendations + +Data and CloudEvents *SHOULD* only be serialized once when it is to be transported over link:README.adoc#_utransport_interface[UTransport Interface] + + +== Examples + +The following examples are using the CloudEvent JSON Format. + +=== Publish +[source] +---- +{ + "specversion": "1.0", + "id": "cf8b1bcd-30bd-43be-a8d3-ad1cde652e10", + "source": "//VCU.VIN/body.access/1/door.front_left#Door", + "type": "pub.v1", + "priority": "CS1", + "ttl": 10000, + "datacontenttype": "text/plain", + "data": "open" +} +---- + +=== Notification +[source] +---- +{ + "specversion": "1.0", + "id": "cf8b1bcd-30bd-43be-a8d3-ad1cde652e10", + "source": "//VCU.VIN/body.access/1/door.front_left#Door", + "sink": "//VCU.VIN/companion.app/1/status.update", + "type": "not.v1", + "datacontenttype": "application/json", + "data": { + "subject": "door.front_left", + "status": "open" + } +} +---- + +=== Request +[source] +---- +{ + "specversion": "1.0", + "id": "cf8b1bcd-30bd-43be-a8d3-ad1cde652e10", + "source": "//VCU.VIN/MyApp/1/rpc.response", + "sink": "//VCU.VIN/body.access/1/rpc.UpdateDoor", + "type": "req.v1", + "priority": "CS4", + "ttl": 50000, + "data_base64": "... base64 encoded serialization of UpdateDoorRequest packed + in google.protobuf.Any ..." +} +---- + +=== Response +[source] +---- +{ + "specversion": "1.0", + "id": "5b9fe861-8c1c-4899-9b07-ad1cde652e10", + "source": "//VCU.VIN/body.access/1/rpc.UpdateDoor", + "sink": "//VCU.VIN/MyApp/1/rpc.response", + "type": "res.v1", + "priority": "CS4", + "reqid": "cf8b1bcd-30bd-43be-a8d3-ad1cde652e10", + "ttl": 50000, + "datacontenttype": "application/protobuf", + "dataschema": "type.googleapis.com/google.rpc.Status", + "data_base64": "... base64 encoded serialization of google.rpc.Status ..." +} +---- diff --git a/basics/cloudevents.drawio.svg b/up-l1/cloudevents.drawio.svg similarity index 100% rename from basics/cloudevents.drawio.svg rename to up-l1/cloudevents.drawio.svg