Sessions

Each session is assigned a unique session identity.

Creating a session

To create a session, a client opens an initial connection to the server. The session attributes set through the client API determine the transport protocol to use for the connection and the host name and port of the server. All Diffusion client libraries support the WebSocket transport protocol, with the option of Transport Layer Security (TLS, more commonly known as SSL). The Java and JavaScript client libraries also support an HTTP long polling (XHR) transport; again, this can be protected with TLS. The HTTP long polling transport can be configured as a fallback if a WebSocket connection cannot be established.

Once a connection has been established, the client sends the server the authentication details that have been set by the application. These may be empty if the application is connecting anonymously, or a principal name and credentials such as a password. The server assigns a session identity, and passes the connection and authentication details to the configured authentication handlers, including those registered by other sessions that have the `AUTHENTICATE` security permission. If the authentication details are accepted by one of the handlers, the server creates a session.

Disconnection and reconnection

Connections between clients and servers are long-lived, but a session can outlive individual connections. A client can become disconnected from the server, and reconnect to the server without loss of the session. Reconnection must occur within the reconnection timeout configured for the server. The default reconnection timeout is 5 minutes.

Diffusion reconnection is precise and lossless. If a client reconnects successfully, no data will have been lost and the only effect visible to the application is the delay while the connection is reestablished. The lossless behavior is achieved by storing the latest network messages sent to and from the client in recovery buffers. On reconnection, the client and server re-send the messages that each other has not received. In some cases, for example if there was a lot of in-flight data buffered in a network router, the recovery buffer size can be insufficient (the sizes can be tuned through configuration), and recovery is not possible. The server reliably detects this and closes the session.

While a session is disconnected, the server continues to queue topic updates for the session's subscriptions and will forward them to the session on reconnection. Queuing the updates requires server memory, and if the queue exceeds configurable limits the session will be closed. Conflation can be used to combine updates for the same topic, with the benefits of reducing the server memory required by the queue, the likelihood of the queue overflowing, and the work required to bring the session back up to speed.

Session properties

Each session has a set of properties that describe various attributes of the session. They provide a way to classify sessions into groups. There are two types of session property. Fixed session properties are assigned by the server and include the session id; the client library type; the network protocol and network address; if enabled on the server, location information derived from the network address; the name of the server the session is connected to; the security principal and roles; and more. User-defined session properties are arbitrary key/value pairs assigned by the application.

Session properties are closely integrated with Diffusion security. Only privileged sessions can modify session properties. This is either achieved directly using the `setSessionProperties` operation or by registering an `Authenticator` implementation and participating in the authentication of sessions. A client may propose session properties when creating the session, but these are only suggestions that the authentication handler can modify or ignore entirely.

A session filter is an expression that selects sessions by their session properties. Many control operations in the API allow a session filter to be provided. For example, the `subscribeByFilter` operation allows a session with the `MODIFY_SESSION` security permission to subscribe all sessions satisfying a session filter to a set of topics.

A session with `REGISTER_HANDLER` and `VIEW_SESSION` permissions can register a session properties listener with the server. The server will notify the session when other sessions are opened, closed, or the session properties are changed.

Control clients

A control client is an application client that performs back-end tasks such as creating topics and updating topics or managing other sessions. The Diffusion client API provides many control operations. The wide range of features that allow a session to monitor and control other sessions is particularly unusual. We have mentioned some of these above: authenticating sessions; setting session properties; monitoring session activity with session properties listeners; subscribing other sessions to topics.

The term "control client" describes the role of a client in the application system and distinguishes it from other clients running on web browsers, mobile devices, or IoT devices. Control clients authenticate to the server using accounts with elevated security permissions.

Sessions opened by control clients are referred to as control sessions.

Messaging and asynchronous application services

Messaging is an alternative way to pass information between sessions without using topics. One session sends a request message, and one or more other sessions reply with a response message. Unlike data published through topics, messages are transient and not stored on the server.

Messages are sent to a message path, which provides a delivery context. Message paths are arbitrary and can be chosen freely by the application. Just like topic paths, a message path is a string of parts separated by the `/` character. This segmented structure allows a recipient session to register a common handler for requests for paths that share a common prefix. Also like topic paths, security permissions assigned to a path are inherited by sub-paths unless a more specific permission assignment is found.

Each request and response message carries a single value. Values belong to one of the standard Diffusion data types. Applications should be written so that the sending and receiving sessions agree on the data types to use for a particular message path.

You can think of a message path as the name of an application service. For example, an application might implement a message handler that receives requests on the message path `account/23237` and returns details of the customer account `23237`. The request/reply facility provided by messaging shares similarities with REST services.

Three distinct messaging patterns are supported by Diffusion. Each routes request and response messages via the server. The three patterns are as follows.

• A session sends a request to the server, for a message path. If one or more control clients has registered a message handler for the message path, the server will select one of the handlers to respond to the request. If there are no registered handlers, the request will fail. The requesting session must have the `SEND_TO_MESSAGE_HANDLER` security permission for the message path. The control clients must have `REGISTER_HANDLER` permission. A control client that has `VIEW_SESSION` permission can additionally instruct the server to forward a subset of the sender's session properties with the request.
• A control client sends a request to a session, addressed by its session identity, for a message path. The session responds. The control client must have `SEND_TO_SESSION` permission for the message path.
• A control client sends a request to many sessions, addressed by a session filter, for a message path. Each session responds. The control client must have `SEND_TO_SESSION` permission for the message path.

After sending a request, the sender will receive either a response or a failure from each recipient.

Session replication

Session replication keeps redundant copies of session data within a cluster of peer servers. This improves system availability as a session can survive the loss of an individual server or failure of the network path to its current server.

If a session is connected to a server that belongs to a session replication enabled cluster, and then becomes disconnected, it will attempt to reconnect to the original server. A properly configured load balancer can detect that the original server is unavailable and re-route the reconnection request to a second server in the cluster. The second server can recover session data and continue the session. This process is known as "fail over". Unlike with reconnection, in-flight messages can be lost during fail over, and the application will be unsubscribed and re-subscribed to topics.