WebSocket Mapping for Scalability Protocols

This document defines the WebSocket mapping for scalability protocols.

Copyright 2018 Staysail Systems, Inc. Copyright 2018 Capitar IT Group BV

This specification is licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the license online.

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 RFC 2119.

This mapping should be layered directly on the top of WebSocket, as defined in RFC 6455.

Additionally, implementations MUST support BINARY frame types. They SHOULD NOT send or accept TEXT frame types.

Implementations SHOULD support HTTPS as the transport, and if they do, then they MAY also choose not to support HTTP. HTTPS SHOULD be used in preference to HTTP when practical.

Client implementations MUST NOT send entity content with their request, and server implementations MUST NOT send entity content when responding with a successful HTTP 101 Switching Protocols response. (The HTTP and WebSocket RFCs permit such content payloads to be sent, but explicitly require that it be ignored if present. It is far easier to simply not send the data in the first place.) Servers receiving requests with content data MUST respond with an error code, such as 400 Bad Request.

The use of the path and query parameters in the HTTP request is not further considered here, except to note that servers SHOULD use this data to discriminate when multiple instances or applications are made available at the same host and port.

Scalability Protocols uses subprotocols that are named as the individual protocol name appeneded with .sp.nanomsg.org. For example, the PAIRv1 protocol (named pair1) has the subprotocol of pair1.sp.nanomsg.org.

Individual protocols have their own names, but here is a list of legacy subprotocol names:

Connections are established using HTTP negotiation as specified in RFC 6455. The HTTP client side MUST include a Sec-WebSocket-Protocol header that lists the desired subprotocol, which is the subprotocol corresponding to the server’s scalability protocol.

For example, a REQ client connecting to a REP server would use the subprotocol of rep.sp.nanomsg.org.

Each SP message sent over this mapping corresponds exactly to one WebSocket message. Implementations MUST properly support receive of messages consisting of multiple WebSocket frames. They MAY send messages in one or more frames, but SHOULD avoid fragmenting messages unless unavoidable. (It will often be the case that applications can receive a single message consisting of just a single frame with less effort than one consisting of multiple frames.)

The URI scheme used to represent is the same as that that used for WebSockets.

Server implementations MAY offer the ability to specify a wild card of * for a host name indicating that when listening, all interfaces of the local host should be listened to, and that the Host HTTP header sent by the client during HTTP negotiation will be ignored.

Server implementations MAY allow a port number of 0 to be specified when listening, in which case a randomly chosen ephemeral TCP port SHALL be used.^[1]

The HTTP Host header sent by clients SHALL be the same as the host and port component of the URI.

Implementations MAY support TLS, and may further support HTTP authentication mechanisms. The details of this are out of scope for this document.

Denial-of-service considerations are discussed, in particular the use of a limit on the incoming message sizes.