Skip to content

Latest commit

 

History

History
166 lines (120 loc) · 5.92 KB

websockets-protocol-binding.md

File metadata and controls

166 lines (120 loc) · 5.92 KB

WebSockets Protocol Binding for CloudEvents - Version 1.0.3-wip

Abstract

The WebSockets Protocol Binding for CloudEvents defines how to establish and use full-duplex CloudEvents streams using WebSockets.

Table of Contents

  1. Introduction
  1. Use of CloudEvents Attributes

  2. WebSocket Message Mapping

  1. References

1. Introduction

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.

1.1. Conformance

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.

1.2. Relation to WebSockets

This specification does not prescribe rules constraining the use or handling of specific HTTP target resource to establish the WebSocket upgrade.

This specification prescribes rules constraining the WebSockets Subprotocols 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.

1.3. Content Modes

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.

1.4. Handshake

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.

1.4.1 Example

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

1.5. CloudEvents Subprotocols

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.

1.6. Security

This specification does not introduce any new security features for WebSockets, or mandate specific existing features to be used.

2. Use of CloudEvents Attributes

This specification does not further define any of the CloudEvents event attributes.

3. WebSocket Message Mapping

Because the content mode is always structured, a WebSocket message just contains a CloudEvent serialized using the agreed event format.

3.1 Event Data Encoding

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.

4. References

  • RFC2119 Key words for use in RFCs to Indicate Requirement Levels
  • RFC6455 The WebSocket Protocol