5.2 Binding Overview

WebSocket binding may be employed for communication between any two endpoints which can be connected over the Mca, Mcc or Mcc' interface reference points supported by the oneM2M Architecture as shown in figure 6.1-1 of oneM2M TS-0001 [2].

When using the WebSocket protocol, one communication endpoint shall act as the WebSocket server. The WebSocket server listens for inbound handshake messages arriving from any WebSocket client to which a WebSocket connection is not yet established. Whether a communication endpoint takes the role of the client or the server shall depend on the registration relationship between the communicating entities as follows: the registree shall always use a WebSocket client, while the associated registrar shall always use a WebSocket server on the respective reference point.

This implies that ADN and ASN always take the role of a WebSocket client when WebSocket binding is employed. An MN-CSE uses a WebSocket server to communicate with its registrees and a WebSocket client to communicate with its own registrar (which can be another MN-CSE or an IN-CSE).

The IN-CSE provides a WebSocket server functionality to communicate with all its registrees, i.e. within a service provider's domain. On the Mcc' reference points, i.e. for communication between IN-CSEs of different Service Provider domains, the IN-CSE shall provide both WebSocket client and server functionality. This enables any IN-CSE to open a WebSocket connection to any IN-CSE of another Service Provider's domain.

Figure 5.2-1 shows some applicable example system configuration.

Figure 5.2-1: Example scenarios of WebSocket client and server configurations

There exists a maximum of one WebSocket connection between two nodes. A WebSocket connection is established for the first time when the initial registration procedure of an entity to its registrar is performed. On an established WebSocket connection, request and response primitives can be exchanged in both directions. Any connection may be closed by either the WebSocket client or the server, depending on the communication schedule of either entity. However, the connection can be reopened from the client side only.

If the connection is closed temporarily, it shall be reopened when the next request primitive is sent from the client to the server side, or when the time to become reachable configured at <schedule> resource. If the WebSocket connection with the next-hop entity is not opened, and the WebSocket connection cannot be established due to lack of pointOfAccess address for the entity, a sending CSE may enable buffering of primitives which should be sent to the entity until the connection is reopened or their expiration time is reached. See Annex H of oneM2M TS-0004 [5] about buffering of primitives by CMDH functionality.

Figure 5.2-2 shows an example message flow for a scenario where an ADN-AE registers to its registrar MN-CSE using an unsecured TCP connection without proxy and then continues exchanging non-registration request and response primitives.

Figure 5.2-2: Example message flow with WebSocket binding

1. The ADN-AE wants to register to its registrar MN-CSE. If a WebSocket connection does not exist, it is established by the following steps 2) and 3). It is assumed that the ADN-AE knows the point of access (i.e. WebSocket URI specified in IETF RFC 6455 [1]) under which the registrar CSE can be reached with WebSocket binding.
2. The WebSocket client opens handshake to the server with subprotocol name oneM2M.json following IETF RFC 6455 [1].
   If the server can be reached under the WebSocket URI ws://example.net:9000/, the client handshake may look as follows:

GET / HTTP/1.1
Host: mncse1234.net:9000
Upgrade: WebSocket
Connection: Upgrade
Sec-WebSocket-Key: ud63env87LQLd4uIV20/oQ==
Sec-WebSocket-Protocol: oneM2M.json
Sec-WebSocket-Version: 13

1. The WebSocket server replies with a handshake to the client. In the successful case, the status-line of this HTTP response may look as follow (note that text shown in brackets [...] is not sent explicitely):

[Request-Version:]  HTTP/1.1
[Status-Code:] 101
[Response-Phrase:] Switching Protocols
Upgrade: WebSocket
Connection: Upgrade
Sec-WebSocket-Protocol: oneM2M.json
Sec-WebSocket-Accept: FuSSKANnI7C/6/FrPMt70mfBY8E=

1. The ADN-AE issue a registration request primitive. The request primitive may e.g. look as follows as JSON-serialized representation (note that only mandatory parameters of the request primitive are shown in this example; the message may include any optional primitive parameters in addition, e.g. "fr"):

 {
     "op": 1,
     "to": "//example.net/mncse1234",
     "rqi": "A1234",
     "pc": {
         "m2m:ae": {
             "api": "a56",
             "apn": "app1234"
         }
     },
     "ty": 2
 }    

1. WebSocket Binding process, which transforms a single oneM2M primitive into one or more data frames of the WebSocket Framing protocol, as specified in IETF RFC 6455 [1]. When transmitting a JSON-serialized primitive in utf-8 text format, the 4-bit opcode in the WebSocket Base Framing Protocol of the first message fragment will be set to x1 ("text frame").
2. The WebSocket message (consisting of one or more frames) shall be sent to the WS server.
3. The original request primitive shall be unpacked from the WebSocket message by the WS server.
4. The request primitive is delivered to the MN-CSE.
5. The MN-CSE performs the receiver side operations of AE registration as specified in oneM2M TS-0001 [2].
6. The response primitive is issued to the WebSocket server.
7. WebSocket binding process for the response primitive is performed.
8. The WebSocket message (consisting of one or more frames) is sent to the client.
9. The response primitive is unpacked.
10. The response primitive is to the ADN-AE.
11. After successful completion of AE registration any other CRUDN requests and response primitives can be exchanged over the existing WebSocket connection in both directions. If the ADN-AE has no other requests to send, the WebSocket connection may be closed temporarily. When the WebSocket connection is closed after registration and reopened later again, the registration procedure as outlined in steps 4 to 14 is omitted. In this case any non-registration request primitives can be sent directly.