Project: CloudEvents (App Definition and Development / Streaming & Messaging)
File: websockets-protocol-binding.md

The WebSockets Protocol Binding for CloudEvents defines how to establish and use full-duplex CloudEvents streams using . 1.1. 1.2. 1.3. 1.4. 1.5. 1.6. 3.1. 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 , 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 . This specification does not prescribe rules constraining the use or handling of specific 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][ce-event-format]. The defines three content modes for transferring events: structured, binary and batch. 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 . The to be used in a full-duplex WebSocket stream is agreed during the and cannot change during the same stream. The MUST follow the set of rules specified in the . In addition, the client MUST include, in the opening handshake, the . The client MUST include in this header one or more , 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: ```text 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: ```text 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 . For each subprotocol, senders MUST use the specified WebSocket frame type: | Subprotocol | Event format | Frame Type | | | -- | - | | `cloudevents.json` | | Text | | `cloudevents.avro` | | Binary | | `cloudevents.proto` | | Binary | All implementations of this specification MUST support the [JSON event format][json-format]. This specification does not support the [JSON batch format][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 event attributes. Because the content mode is always structured, a WebSocket message just contains a CloudEvent serialized using the agreed event format. The chosen 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. Key words for use in RFCs to Indicate Requirement Levels The WebSocket Protocol