Managing asynchronous workflows, deployment pipelines, or system-level processes often requires coordination mechanisms to prevent conflicts or race conditions. Enter Lock State Service (LSS) — a lightweight, API-first solution for managing locks effortlessly.

Introducing Lock State Service (LSS)

With LSS, you can create, check, and modify locks using simple API calls. Whether you’re working with GitHub Actions, CRON jobs, or custom scripts, LSS offers a straightforward way to ensure process synchronization.

Why LSS?

Some common use cases include:

• [*] GitHub Actions Pipelines
  Prevent QA branch deployments during E2E tests by locking processes until the tests are complete.
• [*] System CRON Jobs
  Ensure a job doesn’t start if another critical process is running.
• [*] Ad-Hoc Locking for System Operations
  Use curl to block the execution flow when necessary conditions aren’t met.

And best of all, LSS is free to use for low workloads, making it ideal for personal projects, small teams, and lightweight systems.

How It Works

Create a Lock

To create a new lock:

HTTP POST https://lock-states.deno.dev/locks

Optional URL Parameters:

• l=true|1|T — Initialize the lock in a locked state.
• e=ttl_in_seconds — Set a Time-To-Live (TTL) for the lock.
• k=custom_auth_key — Use a custom authorization key.

Response:

{
    "lockId": "01hvkab4t422rap18rwjs2prnm",
    "lockKey": "b749f750-fbe3-11ee-9224-d7fd2399170d"
}

Example: Create a locked state with a 60-second TTL:

curl -X POST https://lock-states.deno.dev/locks?l=t&e=60

Check Lock State

To check a lock’s status:

HTTP GET https://lock-states.deno.dev/locks/:lockId

Responses:

• 204 — Unlocked
• 423 — Locked
• 404 — Lock not found

Example:

curl -X GET https://lock-states.deno.dev/locks/01hvkab4t422rap18rwjs2prnm -I

Lock or Unlock a Lock

Lock a Lock

HTTP PATCH https://lock-states.deno.dev/locks/:lockId/lock

Parameters:

• k=lockKey — Required for authentication.
• e=ttl_in_seconds — Optional TTL.

Example: Lock forever:

curl -X PATCH "https://lock-states.deno.dev/locks/:lockId/lock?k=:lockKey" -I

Unlock a Lock

HTTP PATCH https://lock-states.deno.dev/locks/:lockId/unlock

Example: Unlock the lock:

curl -X PATCH "https://lock-states.deno.dev/locks/:lockId/unlock?k=:lockKey" -I

Real-World Use Cases

Pipeline Synchronization

In my deployment pipeline, I have an asynchronous task running on a cluster. The next step in the pipeline waits for this task to complete by checking the lock status. Once the lock is released, the pipeline resumes seamlessly.

- name: wait for lock
  run: |
    curl --head -X GET --fail \
         --retry 300 --retry-connrefused --retry-all-errors \
         --retry-delay 30 \
         https://lock-states.deno.dev/locks/:lockId

QA Environment Protection

When the QA team is running tests, they lock the QA environment. This prevents automated redeployments. A simple “resolve state lock” step in the pipeline ensures everything stays coordinated.

Try LSS Today!

LSS is designed to make lock management simple, effective, and accessible. With just a few API calls, you can avoid common workflow issues and ensure smooth operations across your systems.

Get started for free at LSS! 🚀