Search docs ⌘K
esc
Type to search across all documentation pages
Locks

Locks

Distributed mutexes backed by Durable Objects. Use locks to guarantee mutually exclusive access to a critical section for a given key across stateless workers.

Lease-based locking: Every acquisition includes a TTL. Renew the lease while work is in progress, and rely on expiration to recover automatically if a worker crashes mid-flight.

Acquire Lock

POST
/infra/locks/{key}/acquire
locks:write0.0000053 tokens

Acquire a distributed lock on an arbitrary key. Lock TTL must be between 1 and 60,000 ms.

curl
curl -X POST https://api.saasignal.saastemly.com/infra/locks/{key}/acquire \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"ttl_ms":1}'
json — 200 OK
{ "status": "ok" }
typescript
const lock = await ss.infra.locks.acquire('invoice:ord_123', {
  ttl_ms: 15000,
  holder_id: 'worker-1',
})
// lock.token, lock.expires_at
  1. Open Dashboard → Locks and select your project
  2. Enter the lock key, optional holder ID, and TTL
  3. Click Acquire to lease the key and capture the token in the dashboard
Locks are key-driven leases, so the dashboard works from a known key instead of a global list.
Path param
Type
Description
key required
string
1–512 charspattern ^(?!.*\.\.)[^\x00-\x1f\x7f]+$
Body field
Type
Description
ttl_ms required
integer
range ≥1 .. ≤60000
holder_id
string
max 256 chars
Error responses
401 Unauthorized
402 Insufficient tokens
409 Conflict
429 Rate limited

Release Lock

POST
/infra/locks/{key}/release
locks:write0.0000053 tokens

Release a lock using the token returned during acquisition.

curl
curl -X POST https://api.saasignal.saastemly.com/infra/locks/{key}/release \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"token":"..."}'
json — 200 OK
{ "status": "ok" }
typescript
await ss.infra.locks.release('invoice:ord_123', {
  token: lock.token,
})
  1. Open Dashboard → Locks and select your project
  2. Enter the same lock key and paste the token from acquisition
  3. Click Release to free the lease
The dashboard gives you direct control over a known lock key, even though the runtime does not expose a browsable lock index.
Path param
Type
Description
key required
string
1–512 charspattern ^(?!.*\.\.)[^\x00-\x1f\x7f]+$
Body field
Type
Description
token required
string
1–256 chars
Error responses
401 Unauthorized
402 Insufficient tokens
409 Conflict
429 Rate limited

Renew Lock

POST
/infra/locks/{key}/renew
locks:write0.0000053 tokens

Extend a held lock's TTL. TTL must be between 1 and 60,000 ms.

curl
curl -X POST https://api.saasignal.saastemly.com/infra/locks/{key}/renew \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"token":"...","ttl_ms":1}'
json — 200 OK
{ "status": "ok" }
typescript
await ss.infra.locks.renew('invoice:ord_123', {
  token: lock.token,
  ttl_ms: 15000,
})
  1. Open Dashboard → Locks and select your project
  2. Enter the lock key, current token, and the new TTL
  3. Click Renew before the current lease expires
Renew is still designed for long-running workers, but the dashboard is useful for manual recovery and debugging.
Path param
Type
Description
key required
string
1–512 charspattern ^(?!.*\.\.)[^\x00-\x1f\x7f]+$
Body field
Type
Description
token required
string
1–256 chars
ttl_ms required
integer
range ≥1 .. ≤60000
Error responses
401 Unauthorized
402 Insufficient tokens
409 Conflict
429 Rate limited

Get Lock Status

GET
/infra/locks/{key}
locks:read0.0000008 tokens

Inspect whether a lock is currently held.

curl
curl https://api.saasignal.saastemly.com/infra/locks/{key} \
  -H "Authorization: Bearer sk_live_..."
json — 200 OK
{ "status": "ok" }
typescript
const status = await ss.infra.locks.status('invoice:ord_123')
// status.locked, status.expires_at, status.holder_id
  1. Open Dashboard → Locks and select your project
  2. Enter the exact lock key you want to inspect
  3. Click Status or Inspect key to view the lease state
There is still no global lock listing, so inspection is intentionally key-by-key.
Path param
Type
Description
key required
string
1–512 charspattern ^(?!.*\.\.)[^\x00-\x1f\x7f]+$
Error responses
401 Unauthorized
402 Insufficient tokens
429 Rate limited