How Sophora Cloud Delivery works
In a classical Sophora setup, a Sophora Client connects to a single Sophora Server and creates a session. This session is the basis for various functionalities like event dispatching and locking documents. However, an explicit login request and a session with a single server won't work when a load balancer sends the request to any available server.
Therefore Sophora Cloud Delivery takes a different approach by using these techniques:
1. Client requests are sessionless
A Sophora Client can send its request to any Delivery Server straight away without creating a session first. A login is not required. In order to still authorize the request, the client needs to have an access token and must send it alongside every request. The receiving server then reads the token, relates it to a regular Sophora User and authorizes the request. These tokens are UUIDs that can be configured as part of the regular Sophora user configuration in the DeskClients admin section and are therefore known to all Sophora Servers.
2. Events are polled source-time based
The classical event dispatching is closely connected to Sophora Sessions and does not work if there are no sessions in the first place. As an alternative approach Sophora Cloud Delivery uses source-time based event polling. The sourceTime is a date property of ServerEvents that is identical on all Sophora servers. If one server sends a DocumentChangedEvent with a specific source time, then all other Sophora Servers will send the same event with the same source time. This allows for an event fetching strategy that works no matter which server receives the request.
3. The Sophora Server knows if it is sufficiently up-to-date to serve a request
Individual Sophora Servers might be behind in replication. In order to prevent serving old data to a request, the server has an implicit up-to-date check. The client sends an appropriate source time describing the minimum up-to-dateness of the Sophora Server as an additional request parameter with relevant requests. The Sophora Server can use this information to check whether it is delayed in synchronization; if this is the case, it will answer with a specific exception. This exception is properly handled by the client, which will then silently retry the request. A relevant request is for example getDocumentByUUID. In this example, the client sends the last source time of an event concerning the specified document. But other requests, like searches, are not checked for their up-to-dateness, since they are actually executed in the Solr Cloud.
Instantiating a sessionless Sophora Client
An instance of a sessionless Sophora Client may be built by using the SophoraClientBuilder, or by using a special configuration for the Sophora Delivery.
Using the SophoraClientBuilder
An instance of a sessionless Sophora Client may be built by using the SophoraClientBuilder, or by using a special configuration for the Sophora Delivery.
SophoraClientBuilder.newBuilder()
.withHost("<loadbalancer-url>")
.withAccessToken("<accesstoken>")
.sessionless()
.build();
Using a Delivery Configuration
sophora.delivery.client.sessionless=true
sophora.delivery.client.accesstoken=<accesstoken>
Using a sessionless Sophora Client
An invocation of the ISophoraClient#login() method is not necessary if this feature is used. But in order to release local resources, the ISophoraClient#close() method should be used once a client is no longer needed.
A client in a sessionless setup supports reading requests in a regular way.
Restrictions
This sessionless feature is only available when using a http or https connection. RMI is not supported. Sophora Cloud Delivery furthermore only supports connections to Sophora Delivery Servers.
Due to the HTTP keepalive connections of the Sophora Client, a layer 7 load balancer is required for the Sophora Cloud Delivery to balance the load on a per request basis. Examples include a simple Nginx reverse proxy or any load balancing capable Kubernetes service mesh. Kubernetes' build-in services do not load balance on layer 7.
Configuration of Access Tokens
Access tokens are an extension to the Sophora User. Just open a user in your DeskClient's Admin View and add tokens to this user. A token must be a valid UUID and may have a validUntil date. These tokens are hashed before getting stored. In order to use these tokens on stages, the corresponding user has to be available on Sophora Delivery Servers.
Clients using such a token will be authenticated as the user the token belongs to. This affects audit logs and permission checks.
