Protocol

Client-Server Protocol

In order for the LogUI client to effectively communicate with the LogUI server, we need to have some ground rules, or a protocol in place. This page provides a high-level overview of the protocol in place, as well as providing an explanation of any errors you may see during the connection process.

It should be noted that the vast majority of the protocol deals with establishing the connection at the application level. While the LogUI client uses WebSockets to connect to the LogUI server, we must undertake a series of steps once this initial connection is established to verify that we should be logging interactions from a given instance of the LogUI client.

The Protocol — Main Steps

The following steps provide high level detail of the interactions that take place between the LogUI client and LogUI server.

1. To establish a connection, the LogUI client always makes the first move. It attempts to initiate a WebSocket connection to the LogUI server.

2. If accepted at the network level, the connection is then fully established.

3. The first message must be a handshake message from the LogUI client to the LogUI server. For an example handshake message, see the example below (for error 4001). This message will contain information such as the browser's agent string, and the authorisation token to use.

   • If no errors are found in the handshake, we proceed to step 4.
     • If the LogUI client handshake does not specify a sessionID, the LogUI server assumes that a new session is to be created. It responds with the sessionID that the LogUI client must then store. Any subsequent reconnects that are required by the LogUI client will also provide the sessionID in the handshake to ensure continuance of the session.
   • If an error is found within the handshake message, the connection is terminated. A error code is sent as part of the disconnection, which occurs from the LogUI server. The client must then be able to gracefully handle the rejection.

4. The server now knows the application, flight, and session to track interactions for. The server will wait for any logEvent messages, and dutifully store these messages (containing events to log) as they come in.

5. The client and/or server can then disconnect at any point. Typically, the LogUI client will have awareness that it is being terminated, and flush its cache with a final logEvent message before disconnecting. Disconnections caused by network issues are handled gracefully by the LogUI client; if a reconnection is not possible after five attempts (by default), the LogUI client will discard and stored events in its cache and give up.

Handshake Error Codes

When connecting, the LogUI client may find that the LogUI server sends back an error code, and abruptly closes the connection. In this instance, the LogUI client will raise an Error in the browser, reporting what the problem is. For reference, the possible error codes are listed below, with an explanation of each.

Why do the error codes start at 400x? Because HTTP 4xx error codes denote bad requests. All of the errors below pertain to the client issuing a request which the server cannot respond to. When more error codes are included in the future, they'll pertain to the type of error, so a server error would start with 5xxx.

You may assume that a WebSocket connection has been established between the client and the server for all of these errors to happen. These errors pertain to the application layer, not the network layer.

Error 4000 (Unused)

This error code is currently unused by the LogUI server. It was used for debugging purposes.

Error 4001 (Bad Message Request)

If the LogUI client sends a message to the LogUI server that is malformed (is not valid JSON, or does not contain the expected fields), the LogUI server will respond with a 4001 error code. At this point, the underlying WebSocket connection will be closed.

For a message to be considered valid, the message must meet the following criteria.

• The message must be valid JSON.
• The message must have a sender field, with a value of logUIClient.
• The message must have a type field, with the value set to one of the following.
  • handshake for an initial handshake initiation message.
  • logEvents for the sending of events to be stored.
  • closedown for a message alerting the LogUI server that the client will terminate the connection.

If the LogUI client connects to the LogUI server without first initiating a handshake (i.e., it attempts to send logEvents straight away), the connection will be closed with error 4001.

closedown is a valid type, but is however not currently used. For the connection to be closed, the LogUI client at present simply needs to send a logEvents message with the final batch of events to log, and then simply closes the connection.

Error 4002 (Bad Handshake)

When attempting a handshake, the LogUI server can respond with error 4002 if the handshake request is invalid. A sample, well-formed handshake message is shown below for reference.

{
    "clientVersion": "0.5.4d",
    "authorisationToken": "AUTHORISATION_TOKEN",
    "pageOrigin": "https://hostname",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.212 Safari/537.36",
    "clientTimestamp": "Wed May 26 2021 20:29:15 GMT+0100 (British Summer Time)",
}

For a valid handshake, all of the above key/value pairs must be present. In particular:

• the clientVersion must be supported by the instance of LogUI server running;
• a valid authorisation token must be provided as the value of authorisationToken;
• the page origin must be supplied (which host is the page loaded from?);
• the browser's user agent string must be supplied; and
• the client's timestamp at the time the handshake object was created must be supplied.

Optionally, for continuance of a given session, the LogUI client can also supply a sessionID key. The value for this should be the previously established session that was being tracked on a previous page load.

At present, the clientTimestamp format is the string representation of the JavaScript Date() object; this may be changed to a more formalised value in the future (such as the UNIX timestamp).

Failure for any of these fields to be supplied will result in a 4002 error; more descript errors relating to the handshake process are also defined (see below).

Error 4003 (Unsupported LogUI Client Version)

See error 4002 above. Error 4003 is a descriptive handshake error. This error is raised if a valid handshake message is sent from the LogUI client, but the advertised LogUI client version sending the message is not supported by the version of the LogUI server running.

To fix this issue, we recommend that you change the LogUI client version to one supported by the LogUI server instance running.

When this error is raised, the LogUI server will disconnect after returning the error code.

Error 4004 (Bad Authorisation Token)

See error 4002 above. Error 4004 is a descriptive handshake error. This error is raised if a valid handshake message is sent from the LogUI client, but the authorisation token (provided by authorisationToken) is invalid for some reason.

Possible reasons include:

• an invalid encrypted string is provided; or
• when decrypted, the serialised object does not contain the necessary information.

When this error is raised, the LogUI server will disconnect after returning the error code.

Error 4005 (Unrecognised Domain)

See error 4002 above. Error 4005 is a descriptive handshake error. This error is raised if a valid handshake message is sent from the LogUI client, but the domain provided by the pageOrigin property does not match the expected domain for the flight in question.

This check is in place to prevent individuals 'hijacking' a given configuration, and injecting the LogUI client into a webpage hosted on a server other than the one the application that you wish to track interactions for is stored.

This feature is still a prototype; we are evaluating its effectiveness.

When this error is raised, the LogUI server will disconnect after returning the error code.

This check can be bypassed by providing the domain value of bypass when setting up a new flight.

Error 4006 (Bad Session ID)

See error 4002 above. Error 4005 is a descriptive handshake error. This error is raised if a valid handshake message is sent from the LogUI client, but the sessionID that is provided is unrecognised by the LogUI server. This property is provided if you wish to track interactions in a single session across multiple page loads. A unique sessionID is supplied to the LogUI client when establishing a new session; this should be stored by the client for the duration of the session.

When this error is raised, the LogUI server will disconnect after returning the error code.

Error 4007 (Not Accepting New Sessions)

Error 4007 is raised when a valid handshake has occurred, but the given flight interactions are to be tracked for has been explicitly disabled by the administrator. In this instance, the LogUI server will disconnect from the LogUI client.