Gateway Cross-Replica Idempotency

Exactly-once webhook admission across every gateway replica via a Redis-backed idempotency store

Turn on store_backend: redis and every replica of your gateway admits the same webhook exactly once, so a duplicate delivery never runs your agent twice.

Quick Start

1. Single replica — nothing to do

   One gateway process dedups with the durable SQLite 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()   # store_backend defaults to durable sqlite

2. Multiple replicas — set store_backend: redis

   Two or more gateway processes need a shared claim so the same webhook fanned to both is admitted only once. Set it in gateway.yaml and make sure a Redis URL is configured — the store reuses the gateway’s push RedisConfig.

   gateway:
     push:
       redis:
         url: redis://localhost:6379   # reused for the idempotency store
   hooks:
     idempotency:
       store_backend: redis            # cluster-wide exactly-once admission
     hooks:
       - path: gmail
         agent: assistant

3. Or wire it in Python

   Pass the same store_backend through the gateway’s hooks config where you construct it.

   from praisonaiagents import Agent
   from praisonai_bot.gateway import WebSocketGateway
   
   agent = Agent(name="Support", instructions="Help users")
   
   gateway = WebSocketGateway(
       agent=agent,
       config={
           "push": {"redis": {"url": "redis://localhost:6379"}},
           "hooks": {"idempotency": {"store_backend": "redis"}},
       },
   )
   gateway.start()

How It Works

Each replica claims the key (platform, account, channel_id, message_id) with a single SET NX PX; the first wins and the duplicate is rejected.

Fail-Open on Redis Outage

The store never wedges inbound delivery — it degrades to best-effort and surfaces the fact, never a silent green.

Two failure modes, both surfaced under the durability:idempotency degraded owner:

When to Enable

Configuration Options

The operator selects the backend and the store reuses the gateway’s push RedisConfig — no separate idempotency Redis knob.

Best Practices

Related