2.1.1 Requirements for Core Protocol

Topic Version	1	Published	10/31/2016	Topic Change History
For Standard	ETP v1.1

Requirement	Type	Description
Message IDs	Behavior	Message IDs MUST be: Unique within a session, and for a given agent (i.e., client/server). Generated increasingly from 1 for a session and agent type. Increasing within a multi-part response such that message ID order can be used to determine the order of the response. The IDs used by clients and servers are completely independent of one another. Put another way, the 'primary key' of any given message could be thought of as the sessionId + agentType + messageId. Note also that there is specifically no requirement for message IDs to be sequential or for any correlation between message IDs and any particular sub protocol.
Protocol Negotiation	Behavior	In the RequestSession message, the client specifies the protocols, versions, and roles which it expects the server to support for this session. If the server supports at least one of the requested protocols, then the server MUST respond to this message using the OpenSession message, indicating which of the requested protocols and roles it can support. If the server supports none of the requested protocols, it MUST send a 3.4.1.4 Message: ProtocolException with the ENOSUPPORTEDPROTOCOLS error code. The server MAY offer to support only some of the requested protocols. It MUST not offer to support any additional protocols. The server MUST NOT change the requested roles in its response. The server MAY change the supported version of a protocol. If the server is able to support the version the client requests, it MUST do so. If the server response does not provide adequate functionality, then the Client MAY CloseSession immediately.
Session State	Behavior	The definition of a session is all messages associated with a given session UUID, including the original RequestSession. Clients and servers are responsible for maintaining session state, as defined by each supported subprotocol. For protocol 0, the session state includes: a) The session UUID. b) The current highest-valued message IDs (for client and server). c) The state of currently-active multi-part messages. d) All of the SupportedProtocols information from Open Message.
Session Survivability	Behavior	The following applies to all servers that are capable of maintaining history. Server MUST maintain Session state if the WebSocket connection is dropped without a CloseSession message being received. Specific information included in session state MAY be define at the subprotocol level. Server MUST maintain this state for 1hr, +/- 1 minute after disconnect. On reconnection, the client MAY include the etp-sessionid HTTP header in the upgrade request. This effectively is a request to re-activate that session. In this instance, the RequestSession messageId MUST be valid (i.e., a continuation of the ID sequence) from that session. If the session is valid, the server MUST include the identical etp-sessionid HTTP header in the upgrade response. If the session is not valid, the server MUST deny the upgrade request with HTTP error code 404 (not found). It is the server’s responsibility, using HTTP/S authentication to ensure that a request to re-activate a session is coming from an authorized agent.
Token Expiry	Behavior	As discussed in Section 4.2 of this specification.
URIs	Behavior	All URIs MUST be URL-encoded.

This interaction diagram describes the normal sequence of message for an ETP session:

A client begins with the standard WebSocket handshake and the server responds by doing the upgrade from HTTP to WebSocket. For more information on the handshake, see RFC 6455 (https://tools.ietf.org/html/rfc6455 ).

Specific to ETP, the client MUST specify the Sec-Websocket-Protocol header value of energistics-tp, and the server MUST reply with the same. The client MAY also supply the custom header of etp-encoding with a value of binary or json, which specifies the Avro encoding style to be used for the life of the connection.

If this header is not present, the encoding is assumed to be binary.

All protocol header names and values are case-insensitive.

HTML5 Web browser clients cannot currently add custom headers to a WebSocket request, and thus may include the etp-encoding header as a query request parameter. Servers MUST accept and process this value. In the example below, instead of GET / HTTP/1.1 the first line of the request would read GET /?exp-encoding=binary HTTP/1.1. If the server does not support the requested encoding, it MUST reject the upgrade request with HTTP status code 412 (Precondition Failed) and the client can try again (if it wishes) with the alternate etp-encoding value.

A client then sends a RequestSession message. This message consists of a list of subprotocols that the client intends to use on this connection, along with a key/value map of configuration parameters for each subprotocol. The names of allowable keys are strictly controlled by this specification and defined for each subprotocol.
The requested protocols are started and message passing begins. The sequence and interaction diagrams for each are in the subprotocol sections below.
If the server cannot support all of the requested protocols, it MUST respond with a list of the requested protocols that it does support, leaving it up to the client to decide whether to continue with the session.