CloudEvents Binding for CDEvents - Draft

Abstract

The CloudEvents Binding for CDEvents defines how CDEvents are mapped to CloudEvents headers and body.

Table Of Contents

• Context
  • specversion
  • id
  • source
  • type
  • subject
  • time
  • datacontenttype
  • dataschema
• Event Data
• Example

Context

The CloudEvents context is built by the event producer using some of the data from the CDEvents context.

specversion

The CloudEvents specversion MUST be set to 1.0.

id

The CloudEvents id MUST be set to the CDEvents id.

source

The CloudEvents source MUST be set to the CDEvents source.

type

The CloudEvents type MUST be set to the type of the CDEvent.

subject

The CloudEvents subject MUST be set to the subject id of the CDEvent. Note: since the subject is mandatory in CDEvents, the subject in the CloudEvents format will always be set - even if it’s not mandated by the CloudEvents specification.

time

The CloudEvents time MUST be set to the timestamp of the CDEvent. The CloudEvents specification allows for time to be set to either the current time or the time of the occurrence, but it requires all producers to be chose the same option. CDEvents requires all producers to use the timestamp from the CDEvent to meet the CloudEvents specification.

datacontenttype

The CloudEvents datacontenttype is optional, its use depends on the specific CloudEvents binding and mode in use. See the event data section for more details.

dataschema

The CloudEvents dataschema is MAY be set to a URL that points to the event data schema included in this specification.

Events Data

The content and format of the event data depends on the specific CloudEvents binding in use. All the example, unless otherwise stated, refer to the HTTP binding in binary content mode. In this format, the CloudEvents context is stored in HTTP headers.

Content Modes

This specification defines two content modes for transferring events: structured and binary. The structured mode can be used in all cases, the binary mode may only be used in conjunction with the HTTP CloudEvent binding in binary mode:

Structured Content Mode

In structured content mode, the CloudEvents Event Data MUST include the full CDEvents context rendered as JSON in the format specified by the schema for the event type.

In CloudEvents HTTP binary mode, the Content-Type HTTP header MUST be set to application/cdevents+json. In CloudEvents HTTP structured mode, the same information is carried in the CloudEvents context field datacontenttype.

Structured Mode Examples

Full example of a CDEvents in structured content mode, transported through a CloudEvent in HTTP binary mode:

POST /sink HTTP/1.1
Host: cdevents.example.com
ce-specversion: 1.0
ce-type: dev.cdevents.taskrun.started
ce-time: 2018-04-05T17:31:00Z
ce-id: A234-1234-1234
ce-source: /staging/tekton/
ce-subject: /namespace/taskrun-123
Content-Type: application/cdevents+json; charset=utf-8
Content-Length: nnnn

{
   "context": {
      "version" : "draft",
      "id" : "A234-1234-1234",
      "source" : "/staging/tekton/",
      "type" : "dev.cdevents.taskrun.started",
      "timestamp" : "2018-04-05T17:31:00Z",
   }
   "subject" : {
      "id": "/namespace/taskrun-123",
      "type": "taskRun",
      "content": {
         "task": "my-task",
         "url": "/apis/tekton.dev/v1beta1/namespaces/default/taskruns/my-taskrun-123"
         "pipelineRun": {
            "id": "/somewherelse/pipelinerun-123",
            "source": "/staging/jenkins/"
         }
      }
   }
}

Binary Content Mode

TBD

Binary Mode Examples

TBD