After two years operating and maintaining the open source core of Jamsocket called Plane, we released a new version of Plane that simplified the architecture, improved stability and added new features. Read about these changes in our article, A Whole New Plane.

To bring the improvements in Plane to Jamsocket, we are releasing our HTTP API v2.

Here's a brief overview of what this new API introduces:

Connecting to session backends

In this new version of the API, the old spawn endpoint is now called the connect endpoint. The new name better reflects what the endpoint does: returns a URL that connects you to a session backend, only spawning a new session backend if one isn't already running with the provided key.

The most exciting changes to the connect endpoint, however, are the more granular configuration options that allow you to associate user metadata with connection URLs, add new kinds of resource and lifetime limits on backends, and specify image tags and VM clusters to use when spawning.

Custom authentication

You can now generate multiple connection tokens for the same backend. This means that you can associate user metadata in your request that is proxied to a session backend.

When user and auth fields are provided in the connect request, Jamsocket will return a connection token that is associated with the user and auth values you provided, passing them along to the session backend in request headers.

Setting backend limits

You can now set specific resource limits with the connect endpoint to prevent overutilizing compute and memory resources for a specific backend.

You also can set a limit on how long a backend can run in total or how long it can remain idle before being swept, ensuring that resources aren't wasted.

Better backend statuses and controls

We now provide more detailed backend statuses, making it easier to understand where a backend is in its lifecycle.

We've also made it easier to determine whether a backend is running by consolidating error or terminal statuses into a single terminated status. This terminated status includes extra metadata that explains why a backend is terminated and if there was an exit code.

API v2 supports two types of termination: hard termination, which terminates the backend immediately (equivalent to SIGKILL), and soft termination, which sends a SIGINT that the backend can capture to initiate its own shutdown process.

Keys, formerly known as Locks

With the new release of Plane, we renamed locks to be more technically accurate. Alongside semantic accuracy, we also rewrote key management internally to provide better guarantees.

Keys ensure that two users who simultaneously access the same document are routed to the same session backend. This is what makes session backends an authoritative server for mulitiplayer applications.

These new API changes are also supported in our client libraries and by our local dev CLI.

With this, we invite you to try a whole new Jamsocket. To get started, check out our Javascript and Python quickstarts.