Gateway Turn Lock

Serialise per-session turns across replicas so a multi-replica gateway cannot corrupt a shared transcript

The turn lock keeps only one turn running against a session at a time, and its redis backend extends that guarantee across every replica.

Quick Start

The redis backend needs the async Redis client:

pip install "praisonai-bot[redis]"   # or: pip install redis

1. Single replica — already correct, no config

   One gateway process serialises turns with the in-process default. Nothing to set.

   from praisonaiagents import Agent
   from praisonai_bot.gateway import WebSocketGateway
   
   agent = Agent(name="Support", instructions="Help users")
   WebSocketGateway(agent=agent).start()   # turn_lock backend defaults to "local"

2. Multiple replicas — switch the backend to redis

   Two or more gateway processes sharing a session need a distributed lease so two pods can’t run one session’s turns at once.

   from praisonaiagents import Agent
   from praisonaiagents.gateway import GatewayConfig, TurnLockConfig
   from praisonai_bot.gateway import WebSocketGateway
   
   agent = Agent(name="Support", instructions="Help users")
   
   gateway = WebSocketGateway(
       agent=agent,
       config=GatewayConfig(
           turn_lock=TurnLockConfig(backend="redis", ttl=60.0),
       ),
   )
   gateway.start()

3. Or configure it in gateway.yaml

   gateway:
     turn_lock:
       backend: redis   # local | redis
       ttl: 60          # lease TTL in seconds
       # url: redis://...   # optional; overrides the gateway's RedisConfig

How It Works

The lock is LockMap-compatible: one .get(session_id) call returns an async context manager that holds a cluster-wide lease for the whole async with block, and a crashed holder’s lease expires after ttl so a healthy session is never wedged.

sequenceDiagram
    participant A as Replica A
    participant B as Replica B
    participant Redis as Redis<br/>(lease: session:alice)

    A->>Redis: SET NX PX (owner=A, ttl)
    Redis-->>A: OK — lease acquired
    Note over A: Turn 1 runs; lease renews at ~ttl/3
    B->>Redis: SET NX PX (owner=B, ttl)
    Redis-->>B: nil — held by A (polls until free)
    A->>Redis: compare-and-del(owner=A)
    Redis-->>A: released
    B->>Redis: SET NX PX (owner=B, ttl)
    Redis-->>B: OK — lease acquired
    Note over B: Turn 2 runs in order

    Note over A,Redis: A crashes mid-turn?<br/>renewal stops → lease expires after ttl → B proceeds (fail-open)

Release is owner-checked and idempotent: only the exact owner token that claimed the lease may release it, so an expired or reclaimed lease is a harmless no-op, never another replica’s lease.

Fail-open on Redis outage

A live turn is never blocked by Redis being down — the lock degrades to a local asyncio.Lock for that turn and records a degraded capability you find later.

While degraded, turns serialise per-process only (cross-replica ordering pauses until Redis recovers). The lock records a degraded capability entry (owner_kind="capability", owner_id="turn_lock:redis") and clears it automatically on the first successful reconnect.

Health & observability

The fail-open behaviour surfaces through the same tools that report every other degraded gateway capability.

• praisonai gateway doctor — lists the capability / turn_lock:redis degraded owner with a redacted reason.
• Gateway health() / /health — the same degraded entry, machine-readable.
• Logs — a WARNING: Distributed turn lock degraded to local-only (Redis unavailable): … on the first outage.

Configuration Options

TurnLockConfig from praisonaiagents/gateway/config.py.

The enabled property returns True only when a distributed backend is selected (backend != "local").

When to Enable

Enable redis whenever more than one gateway process can share a session — replica count alone decides it.

You need backend: 'redis' whenever more than one gateway process shares a session — with or without an identity resolver. A single-adapter deployment with replicas > 1 still wires the distributed backend.

Backward Compatibility

local is the default and reproduces today’s in-process asyncio.Lock byte-for-byte — single-replica deployments are unchanged and add no new dependency.

Best Practices

Related