mutex.uno

A Mutex is a primitive which allows you to coordinate access to a some shared resource by flagging when one actor is interacting with the shared resource.

If two actors are trying to access a shared resource, the process is as follows:

  1. An actor wishes to use the shared resource. The actor attempts to acquire a Mutex with a key it shares with the other actors.
  2. If successfully acquired, the actor proceeds to interact with the shared resource. If unsuccessful, the actor waits a period of time before trying again.
  3. Once actor is finished with the shared resource, it releases the Mutex. This allows other actors to now access the shared resource.

Further reading:

mutex.uno is a free API providing access to Mutexes. Please note that all access is unauthenticated and anyone can lock and release any Mutex. Do not use this for anything where you need to guarantee a lock from outside interference. Contact Greg Brimble if you are interested in an authenticated service.

Backed by Cloudflare Workers Durable Objects.

API

Any endpoint may additionaly return, at any time, two other responses:

429 Too Many Requests
Returned when a Mutex could not be queried. This is usually due to too many requests for a single Mutex key.
502 Bad Gateway
Returned when a Mutex could not be queried because of an upstream isssue.

POST /api/:mutex-key

Attempts to acquire a Mutex with a given :mutex-key.

Returns a 201 Created response when a Mutex has been successfully acquired and a 409 Conflict when the Mutex was already locked.

In advanced use, you can specify an If-Match header to override the default behavior. If the value of the If-Match header is equal to the current Mutex's ETag header, or if there is no current Mutex, the existing Mutex is overwritten with a new Mutex for the current request. This is an alternative to releasing the Mutex with a DELETE /:mutex-key request and then subsequently acquiring a new one with a POST /:mutex-key request, which doesn't risk the possibility of another actor acquiring a Mutex between the two requests. If the If-Match header is not equal to the current Mutex's ETag header, the request will fail with a 412 Precondition Failed response.

201 Created

Returns an application/json response body.

id
A string of a UUID v4 which uniquely identifies the Mutex.
timestamp
A string in simplified extended ISO format (ISO 8601) of when the Mutex was acquired.

Example

{
  "id": "00000000-0000-4000-0000-000000000000",
  "timestamp": "1970-01-01T00:00:00.000Z"
}

Includes an ETag response header which can be used in subsequent advanced requests, and a Last-Modified header, equivalent to the timestamp value found in the response body.

409 Conflict

Returns an application/json response body.

id
A string of a UUID v4 which uniquely identifies the original Mutex.
timestamp
A string in simplified extended ISO format (ISO 8601) of when the Mutex was previously acquired.

Example

{
  "id": "00000000-0000-4000-0000-000000000000",
  "timestamp": "1970-01-01T00:00:00.000Z"
}

Includes an ETag response header which can be used in subsequent advanced requests, and a Last-Modified header, equivalent to the timestamp value found in the response body.

412 Precondition Failed

Returns an application/json response body.

id
A string of a UUID v4 which uniquely identifies the original Mutex.
timestamp
A string in simplified extended ISO format (ISO 8601) of when the Mutex was previously acquired.

Example

{
  "id": "00000000-0000-4000-0000-000000000000",
  "timestamp": "1970-01-01T00:00:00.000Z"
}

Includes an ETag response header which can be used in subsequent advanced requests, and a Last-Modified header, equivalent to the timestamp value found in the response body.

DELETE /api/:mutex-key

Attempts to release a Mutex with a given :mutex-key.

Returns a 204 No Content response when the Mutex has been successfully released and a 404 Not Found response when there was no Mutex to release.

In advanced use, you can specify an If-Match header to override the default behavior. If the value of the If-Match header is equal to the current Mutex's ETag header, the existing Mutex is released, as above. If the If-Match header is not equal to the current Mutex's ETag header, the request will fail with a 412 Precondition Failed response. This can be used to ensure that only a specific given Mutex is released.

204 No Content

No body.

404 Not Found

No body.

412 Precondition Failed

Returns an application/json response body.

id
A string of a UUID v4 which uniquely identifies the original Mutex.
timestamp
A string in simplified extended ISO format (ISO 8601) of when the Mutex was previously acquired.

Example

{
  "id": "00000000-0000-4000-0000-000000000000",
  "timestamp": "1970-01-01T00:00:00.000Z"
}

Includes an ETag response header which can be used in subsequent advanced requests, and a Last-Modified header, equivalent to the timestamp value found in the response body.

GET /api/:mutex-key

Reports the status of a Mutex with a given :mutex-key.

Returns a 200 OK response when the Mutex was locked and a 404 Not Found response when there was no Mutex.

200 OK

Returns an application/json response body.

id
A string of a UUID v4 which uniquely identifies the Mutex.
timestamp
A string in simplified extended ISO format (ISO 8601) of when the Mutex was acquired.

Example

{
  "id": "00000000-0000-4000-0000-000000000000",
  "timestamp": "1970-01-01T00:00:00.000Z"
}

Includes an ETag response header which can be used in subsequent advanced requests, and a Last-Modified header, equivalent to the timestamp value found in the response body.

404 Not Found

No body.