Version Compatibility Checking

As Synapse evolves, compatibility issues will arise for the various analytical clients. This document describes a simple architecture for providing information about version compatibility. There are two parts to the approach: (1) Determining whether a client upgrade is available, (2) determining whether a client is dangerously incompatible with the server and, if so, black listing the client. (The hope is that the blacklist will be used sparingly.)

Key design considerations:

The Synapse server should not have embedded information about, or otherwise have dependencies on, its clients. (E.g. if a new client version is released, nothing should have to change in the server.)
We *do* need a black list of denied clients, not just notification about the latest version of each client.
Although compatibility testing ought to be done client side, we should have a server-side capability to block clients, as a 'last ditch' defense against dangerous behavior (e.g. destroying data) due to a client incompatibility or bug. It may be insufficient to expect an buggy client to deny itself. (Aside: If we become heavily dependent on this mechanism we need to revisit our quality control processes!)

The Version Service

The version service will provide version information to its client applications: A request to

http://versions.synapse.sagebase.org/synapseRClient

will return a response of the form:

{
    "client":"synapseRClient",
    "latestVersion":"0.19-0",
    "releaseNotes":"This version includes new provenance features.",
    "message":"On January 1, all clients will be required to upgrade to the latest version.",
    "blacklist":[
        {"server":"*","client":"0.0.0"},
        {"server":"1.15.0-8-ge79db7a","client":"0.10"},
        {"server":"1.14.0-1-f84egda0","client":"<0.70"},
        {"server":"1.13.0-2-vj474hdh","client":">0.10-0"},
        {"server":"1.12.0-7-ch24528f","client":"0.05"},
        {"server":"1.12.0-7-ch24528f","client":"0.19-0"}
    ]
}

Such documents will be provided for synapseRClient, synapsePythonClient, and other client that may arise.

The version information will take the form of static files on cloud storage, e.g. in Amazon S3.

Client Deployment

Each client should have a deployment system which does the following: (1) builds a new version of the client, (2) tests that it works, (3) deploys (in the case of the R client, pushes to CRAN), (4) automatically updates the 'lastest version' information described above. Additionally, information can be added to the black list as developers determine that certain older versions of the client are dangerously incompatible with the server.

Synapse Server Behavior

The server logs requests it receives, including request headers and therefore records what versions of its clients are actively being used.

Repository Service Requests

Requests to the Synapse repository service may specify the client type and version in the User-Agent header. If the type and version are on the black list, the repository service will return 403 Forbidden and an informative message.

Note: If the User-Agent header is missing or unrecognized, then the request proceeds as usual. This is because the feature is provided as a tool for clients and is not meant to be a security mechanism.

Client Behavior

Upon start up or periodically during operation, each client may retrieve the version information and compare to its own version.

If its version is not the latest version, the client is to display a message suggesting that the user upgrade to the latest version, including the 'release notes' for the latest version and continue to run.

The client retrieves the black list for that version (if any) from the version service. If the client's own version is on the black list, the client is to display a message informing the user of the incompatibility of client and server and print instructions for upgrading the client and then exit or run but not make web service calls.

If the version is the latest version, the client is to continue to run.

Regardless of the client version, any "message" string in the version information file is to be displayed.

Requests to the Synapse respository service may specify the client type and version in the User-Agent header, e.g. "synapseRClient/2.0".

Development

For development purposes, test version information will be made available at:

http://dev-versions.synapse.sagebase.org/synapseRClient