Skip to content

Latest commit

 

History

History
367 lines (272 loc) · 11 KB

README.adoc

File metadata and controls

367 lines (272 loc) · 11 KB

uProtocol Messages

Table of Contents

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)

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.

1. Message Attributes

The following section will elaborate on the uProtocol message header attributes.

1.1. Common

Common attributes apply to all message types.

Table 3. Common Message Header Attributes
Attribute Type RFC2119 Description

specversion

String

R

CloudEvent specification version. This is NOT the uProtocol version

  • MUST be set to "1.0"

id

String

R

Unique identifier for the CE

source

Uri-Reference

R

The Source (address) of the message per source Description

Table 1. source Description
Type Description

Publish & Notification

The Producers topic

Request

The calling uE response topic

Response

Method URI

  • * MUST be either a short form or long form URI per URI Specifications

  • MUST include the authority, UE_NAME, UE_VERSION

  • UE_VERSION

    • MUST include MAJOR

    • MAY include MINOR

    • MUST NOT include PATCH

type

String

R

uProtocol CE type

Table 2. Message Types
Type Value

Publish

pub.v1

Notification

notif.v1

Request

req.v1

Response

res.v1

sink

Uri-Reference

R|O

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 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

datacontenttype

String

O

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 RFC 2046

  • MUST be application/octet-stream for binary encoded data that is not protobuf

  • SHALL be application/protobuf if attribute is missing

dataschema

Uri-Reference

O|R

Identifies the schema that data adheres to. The dataschema is required only when the data is not of type google.protobuf.Any:

  • MUST be a valid URI Reference per RFC 3986 section 4.1

hash

Binary

O

HMAC generated on the data portion of the message using a device key

priority

String

0

uProtocol Prioritization classifications per QoS. When this field is missing, CS0 is assumed. When the message type is req.v1:

  • MUST be set to CS4 or greater

ttl

Uint32

R|O

How long this event should live for after it was generated (in milliseconds). Event expires when:

\(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

1.2. 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

1.2.1. Request

Table 4. Common Message Header Attributes
Attribute Type RFC2119 Description

token

String

R|O

permission_level

Integer

R|O

Source (senders) uE permission level as defined in Code-Based uE Access Permissions (CAPs)

1.2.2. Response

Table 5. RPC Response Message
Attribute Type RFC 2119 Description Requirements

reqid

String

R

Request Identifier a.k.a correlation ID between this response and the original request

  • MUST be the uProtocol UUID from the original Request message (req.v1) that this response is for

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 google.rpc.Code

  • MUST only be populated by Dispatchers when a deivery error has occured. See Dispatchers for more information.

2. Data (Payload)

Data portion of the CE contains the application layer (uP-L2) message. the format of the data varies slightly depending on the CloudEvent format that we will describe in the next section.

3. Formats

In this section we will explain both the message format and the message payload (data) formats building upon uProtocol CloudEvent (CE) specifications.

Note
 data in the following section refers to the message payload. please see uProtocol Layers for more information.
Table 6. Formats
CE Format Encoding Data Format Considerations

Protobuf

Binary

If data is a protobuf message:

  • MUST be packed as google.protobuf.Any and stored in field proto_data

  • MAY set datacontenttype to "application/protobuf"

  • MAY 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 data is binary and NOT a protobuf message:

  • MUST be stored in the field binary_data

  • MUST set datacontenttype to "application/octet-stream"

  • MUST set dataschema to the URI-Reference schema of the data

JSON

Text

If data is a protobuf message:

  • MUST be packed as google.protobuf.Any and stored in field data_base64 attribute,

  • MAY set datacontenttype to "application/protobuf"

  • MAY 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 data is binary and NOT a protobuf message:

  • MUST be base64 encoded and stored in data_base64 attribute

  • MUST set datacontenttype to "application/octet-stream"

  • MUST set dataschema to the URI-Reference schema of the data

The following are additional recommendations when implementing the protocol:

  • Data and CE MUST only be serialized once when it is to be transported over a uP-L1 transport

  • CE MUST be serialized to the event format per uP-L1 transport requirements

4. Examples

The following examples are using the JSON CE format

4.1. Publish Message

{
    "specversion": "1.0",
    "id" : "cf8b1bcd-30bd-43be-a8d3-ad1cde652e10",
    "source": "up://VCU.VIN.veh.up.gm.com/body.access/1/door.front_left#Door",
    "type": "pub.v1",
    "datacontenttype" : "application/protobuf",
    "dataschema": "/org.eclipse.uprotocol.vehicle.body.access.v1.Door",
    "priority" : "CS1",
    "ttl" : 10000,
    "data": /* Protobuf serialized Door Message*/
}

4.2. Notification Message

{
    "specversion": "1.0",
    "id" : "5b9fe861-8c1c-4899-9b07-ad1cde652e10",
    "source": "up://VCU.VIN.veh.up.gm.com/body.access/1/rpc.UpdateDoor",
    "sink": "up://VCU.VIN.veh.up.gm.com/MyAppp/1/rpc.response",
    "type": "res.v1",
    "datacontenttype" : "application/protobuf",
    "dataschema": "/google.rpc.Status",
    "priority" : "CS4",
    "reqid" : "cf8b1bcd-30bd-43be-a8d3-ad1cde652e10",
    "ttl" : 50000,
    "data": /* Protobuf serialized google.rpc.Status Message*/
}

4.3. Request Message

{
    "specversion": "1.0",
    "id" : "cf8b1bcd-30bd-43be-a8d3-ad1cde652e10",
    "source": "up://VCU.VIN.veh.up.gm.com/MyAppp/1/rpc.response",
    "sink": "up://VCU.VIN.veh.up.gm.com/body.access/1/rpc.UpdateDoor",
    "type": "req.v1",
    "datacontenttype" : "application/protobuf",
    "dataschema": "/org.eclipse.uprotocol.vehicle.body.access.v1.UpdateDoorRequest",
    "priority" : "CS4",
    "ttl" : 50000,
    "data": /* Protobuf serialized UpdateDoorRequest Message*/
}

4.4. Response Message

{
    "specversion": "1.0",
    "id" : "5b9fe861-8c1c-4899-9b07-ad1cde652e10",
    "source": "up://VCU.VIN.veh.up.gm.com/body.access/1/rpc.UpdateDoor",
    "sink": "up://VCU.VIN.veh.up.gm.com/MyAppp/1/rpc.response",
    "type": "res.v1",
    "datacontenttype" : "application/protobuf",
    "dataschema": "/google.rpc.Status",
    "priority" : "CS4",
    "reqid" : "cf8b1bcd-30bd-43be-a8d3-ad1cde652e10",
    "ttl" : 50000,
    "data": /* Protobuf serialized google.rpc.Status Message*/
}