Locking a backend to a resource using keys

A common pattern is to have one session backend for each file or document that a user has open. In these cases, it is usually desirable to ensure that only one session backend is running per document, so that the backend can persist changes without worrying that the underlying data has changed in the meantime. Jamsocket’s solution to this is keys.

In a previous version of the Jamsocket API, keys were referred to as “locks”.

A key is a string that you pass to Jamsocket when you request a connection URL with the connect endpoint. If no running backend holds the given key, a new backend will be spawned. Otherwise, the backend holding the given key will be returned.

Keys can be any (unicode) string up to 128 characters in length. Deciding how key strings are generated is up to you, but we recommend using the canonical string representation of the resource that you are attempting to “lock” to a backend. For example, if you want to give a backend exclusive access to an S3 file, the key could be the S3 URL of that file.

⚠️

Keys are namespaced by service. In other words, two backends can use the same key string if they are in separate services.

Inside a session backend, a backend’s key may be found in the SESSION_BACKEND_KEY env var.

Example

Take the following connect request, for example.

POST /v2/service/my-account/my-service/connect
{
  "key": "document-123"
}

If the my-account/my-service service does not have a backend currently running with the key document-123, a new session backend will be spawned, and you’ll receive a response that looks like this:

connect-response-example

{
  "backend_id": "knrv5",
  "spawned": true,
  "status": "scheduled",
  "token": "4ahosrz8D53AmXj-Pzs0XlGANt3yG56asVqvNVzma9s",
  "url": "https://knrv5.p.jamsocket.net/4ahosrz8D53AmXj-Pzs0XlGANt3yG56asVqvNVzma9s/",
  "secret_token": "qB9Tky7m10ym-x0w5I6eTn41odJawYwVW4EgabC4r12",
  "status_url": "https://api.jamsocket.com/v2/backend/knrv5/status",
  "ready_url": "https://ready.jamsocket.com/knrv5/4ahosrz8D53AmXj-Pzs0XlGANt3yG56asVqvNVzma9s/"
}

If, however, a running backend holds the key document-123, a new backend will not be spawned. Instead, the running backend (in this case, knrv5) will be returned, and you’ll receive a response that looks like this:

connect-response-example

{
  "backend_id": "knrv5",
  "spawned": false,
  "status": "ready",
  "token": "4ahosrz8D53AmXj-Pzs0XlGANt3yG56asVqvNVzma9s",
  "url": "https://knrv5.p.jamsocket.net/4ahosrz8D53AmXj-Pzs0XlGANt3yG56asVqvNVzma9s/",
  "secret_token": "qB9Tky7m10ym-x0w5I6eTn41odJawYwVW4EgabC4r12",
  "status_url": "https://api.jamsocket.com/v2/backend/knrv5/status",
  "ready_url": "https://ready.jamsocket.com/knrv5/4ahosrz8D53AmXj-Pzs0XlGANt3yG56asVqvNVzma9s/"
}

You can also fetch the backend currently holding a given key without spawning by passing "spawn": false in the request body:

POST /v2/service/my-account/my-service/connect
{
  "key": "document-123",
  "spawn": false
}

Persist State Y-Sweet