The WebSockets Protocol Binding for CloudEvents defines how to establish and use full-duplex CloudEvents streams using WebSockets.
- 1.1. Conformance
- 1.2. Relation to WebSockets
- 1.3. Content Modes
- 1.4. Handshake
- 1.5. CloudEvents Subprotocols
- 1.6. Security
- 3.1. Event Data Encoding
CloudEvents is a standardized and protocol-agnostic definition of the structure and metadata description of events. This specification defines how the elements defined in the CloudEvents specification are to be used in WebSockets, in order to establish and use a full-duplex CloudEvents stream.
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 RFC2119.
This specification does not prescribe rules constraining the use or handling of specific [HTTP target resource][rfc7230-section-5-1] to establish the WebSocket upgrade.
This specification prescribes rules constraining the [WebSockets Subprotocols][rfc6455-section-5-1] in order to reach agreement on the event format to use when sending and receiving serialized CloudEvents.
Events are sent as WebSocket messages, serialized using an event format.
The CloudEvents specification defines two content modes for transferring events: structured and binary.
Because of the nature of WebSockets messages, this specification supports only structured data mode, hence event metadata attributes and event data are sent in WebSocket messages using an event format.
The event format to be used in a full-duplex WebSocket stream is agreed during the handshake and cannot change during the same stream.
The opening handshake MUST follow the set of rules specified in the RFC6455.
In addition, the client MUST include, in the opening handshake, the
Sec-WebSocket-Protocol header. The client MUST include
in this header one or more
CloudEvents subprotocols, depending on the
subprotocols the client supports.
The server MUST reply with the chosen CloudEvents subprotocol using the
Sec-WebSocket-Protocol header. If the server doesn't support any of the
subprotocols included in the opening handshake, the server response SHOULD NOT
contain any Sec-WebSocket-Protocol header.
Example client request to begin the opening handshake:
GET /events HTTP/1.1
Host: server.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==
Sec-WebSocket-Protocol: cloudevents.json, cloudevents.avro
Sec-WebSocket-Version: 13
Origin: http://example.com
Example server response:
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: HSmrc0sMlYUkAGmm5OPpG2HaGWk=
Sec-WebSocket-Protocol: cloudevents.json
This specification maps a WebSocket subprotocol to each defined event format in the CloudEvents specification, following the guidelines discussed in the RFC6455. For each subprotocol, senders MUST use the specified WebSocket frame type:
| Subprotocol | Event format | Frame Type |
|---|---|---|
cloudevents.json |
JSON event format | Text |
cloudevents.avro |
AVRO event format | Binary |
cloudevents.proto |
Protobuf event format | Binary |
All implementations of this specification MUST support the JSON event format. This specification does not support the JSON batch format.
This specification does not introduce any new security features for WebSockets, or mandate specific existing features to be used.
This specification does not further define any of the CloudEvents event attributes.
Because the content mode is always structured, a WebSocket message just contains a CloudEvent serialized using the agreed event format.
The chosen event format defines how all attributes, including the payload, are represented.
The event metadata and data MUST be rendered in accordance with the event format specification and the resulting data becomes the payload.