backend-distributed-locking

Backend Distributed Locking

Purpose

Coordinate access to shared resources across multiple service instances using distributed locks with guaranteed safety properties.

Agent Protocol

Trigger

Exact user phrases: "distributed lock", "Redis lock", "Redlock", "ZooKeeper lock", "advisory lock", "PostgreSQL lock", "pg_advisory_lock", "lease", "distributed mutex", "fencing token", "lock timeout".

Input Context

• Resource being protected.
• Available infrastructure (Redis, PostgreSQL, ZooKeeper, etcd).
• Number of competing instances.
• Duration of the critical section.

Output Artifact

Lock configuration or implementation code. No file unless requested.

Response Format

Provider: {Redis|PostgreSQL|ZooKeeper|etcd}
Strategy: {Redlock|Advisory|Ephemeral|Lease}
TTL: {duration}
Safety: {fencing?}

Completion Criteria

• Lock acquisition and release implemented correctly.
• Lock timeout (TTL) configured.
• Fencing token mechanism in place for critical resources.
• Deadlock prevention: no nested locks.
• Graceful degradation: lock acquisition failure does not crash the service.

Max Response Length

4 lines per lock configuration. 20 lines for implementation.

Architecture Decision Tree

Which Lock Provider?

What infrastructure is already available?
  ├── Redis → High throughput, short locks, needs Redlock for failover
  ├── PostgreSQL → Same DB as data, simple setup, lock contention impacts DB
  ├── ZooKeeper/etcd → Strong consistency, leader election, operational complexity
  └── In-memory → Single instance only, NOT distributed

Which Lock Strategy?

Is the critical section short (< 1 second)?
  ├── Yes → Redis simple lock or PostgreSQL advisory lock
  └── No → Is the critical section a resource write?
            ├── Yes → Lease-based lock with fencing token
            └── No → Redlock (Redis with multi-node failover)

Is strong consistency required?
  ├── Yes → ZooKeeper/etcd (sequential consistency, fencing built-in)
  └── No → Is failover safety required?
            ├── Yes → Redlock (Redis, 3+ nodes)
            └── No → Single Redis lock or PG advisory lock