Skip to content

cloudevents.adoc

Latest commit

 

History

History
346 lines (257 loc) · 11.1 KB

cloudevents.adoc

File metadata and controls

346 lines (257 loc) · 11.1 KB

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.

The CloudEvents project has defined a set of 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 Transport Libraries which use CloudEvents for 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 Message Priority.

  • 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 uEntity 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 (if any). The concrete mapping rules are defined in uPayload Mapping.

2.2. uPayload Mapping

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

Note
 The custom pformat property is used to indicate the payload type instead of the standard datacontenttype property defined by CloudEvents. Its value is set to the integer value assigned to the UPayloadFormat. This helps to reduce the size of the resulting data structure.

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 Transport Libraries which use the Protobuf Event Format for the binding to a particular transport protocol.

UPayloadFormat CE pformat CE dataschema CE Property to map Payload Data to

UPAYLOAD_FORMAT_UNSPECIFIED

-

MAY be set to a URI-Reference identifying the schema that the data adheres to

binary_data

UPAYLOAD_FORMAT_PROTOBUF_WRAPPED_IN_ANY

0x01

MAY be set to type.googleapis.com/google.protobuf.Any

proto_data

UPAYLOAD_FORMAT_PROTOBUF

0x02

SHOULD be set to the protobuf’s type URL

proto_data

UPAYLOAD_FORMAT_JSON

0x03

MAY be set to a URI-Reference identifying the schema that the data adheres to

text_data

UPAYLOAD_FORMAT_SOMEIP

0x04

MAY be set to a URI-Reference identifying the schema that the data adheres to

binary_data

UPAYLOAD_FORMAT_SOMEIP_TLV

0x05

MAY be set to a URI-Reference identifying the schema that the data adheres to

binary_data

UPAYLOAD_FORMAT_RAW

0x06

MAY be set to a URI-Reference identifying the schema that the data adheres to

binary_data

UPAYLOAD_FORMAT_TEXT

0x07

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 Transport Libraries which use the JSON Event Format for the binding to a particular transport protocol.

UPayloadFormat CE pformat CE dataschema CE Property to map Payload to

UPAYLOAD_FORMAT_UNSPECIFIED

-

MAY be set to a URI-Reference identifying the schema that the data adheres to

data_base64

UPAYLOAD_FORMAT_PROTOBUF_WRAPPED_IN_ANY

0x01

MAY be set to type.googleapis.com/google.protobuf.Any

data_base64

UPAYLOAD_FORMAT_PROTOBUF

0x02

SHOULD be set to the protobuf’s type URL

data_base64

UPAYLOAD_FORMAT_JSON

0x03

MAY be set to a URI-Reference identifying the schema that the data adheres to

data

UPAYLOAD_FORMAT_SOMEIP

0x04

MAY be set to a URI-Reference identifying the schema that the data adheres to

data_base64

UPAYLOAD_FORMAT_SOMEIP_TLV

0x05

MAY be set to a URI-Reference identifying the schema that the data adheres to

data_base64

UPAYLOAD_FORMAT_RAW

0x06

MAY be set to a URI-Reference identifying the schema that the data adheres to

data_base64

UPAYLOAD_FORMAT_TEXT

0x07

MAY be set to a URI-Reference identifying the schema that the data adheres to

data

2.2.3. Additional Recommendations

CloudEvents SHOULD only be serialized when they are about to be sent via the 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": "up-pub.v1",
    "priority": "CS1",
    "ttl": 10000,
    "pformat": 7,
    "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": "up-not.v1",
    "pformat": 3,
    "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": "up-req.v1",
    "priority": "CS4",
    "ttl": 50000,
    "pformat": 1,
    "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": "up-res.v1",
    "priority": "CS4",
    "reqid": "cf8b1bcd-30bd-43be-a8d3-ad1cde652e10",
    "ttl": 50000,
    "pformat": 2,
    "dataschema": "type.googleapis.com/google.rpc.Status",
    "data_base64": "... base64 encoded serialization of google.rpc.Status ..."
}