Skip to content

Latest commit

 

History

History
338 lines (248 loc) · 10.5 KB

cloudevents.adoc

File metadata and controls

338 lines (248 loc) · 10.5 KB
Raw

CloudEvents

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)

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

CloudEvents is a specification hosted by the 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
Figure 1. CloudEvents envelope

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.

1.1. Event Format and Transport Binding

The CloudEvents project has defined a set Formats which describe how events can be expressed using JSON, Protobuf or Apache Avro.

The accompanying Bindings describe how events can be sent via well-known transport protocols like HTTP, MQTT etc.

2. uMessage Mapping

uProtocol uses UMessages to exchange information between uEntities. The following sections define the mapping between UMessages and CloudEvents.

2.1. uAttributes Mapping

The table below defines the mapping of uAttributes to CloudEvent attributes. This mapping MUST be used by uProtocol Client Libraries which use CloudEvents for the binding to a particular transport protocol.

Table 1. Mapping of uAttributes to CloudEvent properties
uAttributes Property CloudEvent Attribute CE Type Description

N/A

specversion

String

CloudEvent specification version. This is NOT the uProtocol version

  • MUST be set to 1.0

type

type

String

The type of the message

  • MUST be set to the value of the uprotocol.ce_name option defined for the UMessageType enum.

id

id

String

Unique identifier for the message

source

source

Uri-Reference

The origin (address) of the message

sink

sink

Uri-Reference

The destination (address) of the message

priority

priority

String

The message’s priority as defined by QoS.

  • MUST be set to the value of the uprotocol.ce_name option defined for the UPriority enum.

ttl

ttl

Integer

The amount of time (in milliseconds) after which this message MUST no longer be delivered/processed.

token

token

String

The service consumer’s access token.

permission_level

plevel

Integer

The service consumer’s permission level as defined in Code-Based uE Access Permissions (CAPs)

reqid

reqid

String

The identifier that a service consumer can use to correlate an RPC Repsonse message with its RPC Request.

commstatus

commstatus

Integer

A code indicating an error that has occurred during the delivery of either an RPC Request or Response message.

  • MUST be set to the UCode's integer value

traceparent

traceparent

String

A tracing identifier to use for correlating messages across the system.

payload_format

pformat

Integer

The value of the UPayloadFormat that is used to indicate the encoding of the payload

2.2. uPayload Mapping

The sections below define the mapping of uPayload to CloudEvent attributes.

2.2.1. Mapping to CloudEvent Protobuf Format

The rules defined in 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 uProtocol Client Libraries which use the Protobuf Event Format for the binding to a particular transport protocol.

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

2.2.2. Mapping to CloudEvent JSON Format

The rules defined in 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 uProtocol Client Libraries which use the JSON Event Format for the binding to a particular transport protocol.

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

2.2.3. Additional Recommendations

Data and CloudEvents SHOULD only be serialized once when it is to be transported over UTransport Interface

3. Examples

The following examples are using the CloudEvent JSON Format.

3.1. Publish

{
    "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"
}

3.2. Notification

{
    "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"
    }
}

3.3. Request

{
    "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 ..."
}

3.4. Response

{
    "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 ..."
}