Gateway State Durability

The gateway's webhook idempotency and session history are durable by default — a restart no longer re-processes webhooks or drops history

Next

The gateway’s webhook idempotency and session history are durable by default — a restart no longer re-processes webhooks or drops history.

from praisonaiagents import Agent
from praisonai.gateway import Gateway

agent = Agent(name="assistant", instructions="Be helpful.")
gw = Gateway(agents=[agent])
gw.register_hook({"path": "alerts", "agent": "assistant", "auth": "secret"})
gw.start()   # webhook idempotency + session history are durable by default

When a durable store cannot initialise, the gateway logs, records a redacted gateway / durability:* degraded owner, and keeps serving in-memory so inbound delivery never stops.

What’s Durable, Out of the Box

Both survive a routine gateway restart. Webhook dedup keys persist across a redelivery window, and session history is not dropped when the process cycles.

Quick Start

1. Start the gateway — durable by default

   from praisonaiagents import Agent
   from praisonai.gateway import Gateway
   
   agent = Agent(name="assistant", instructions="Be helpful.")
   gw = Gateway(agents=[agent])
   gw.register_hook({"path": "alerts", "agent": "assistant", "auth": "secret"})
   gw.start()   # webhook idempotency + session history are durable by default

   No configuration is required — the SQLite idempotency store and the configured session store are used automatically.

2. Opt out for tests / ephemeral runs

   hooks:
     idempotency:
       store_backend: memory   # explicit opt-out — tests / ephemeral runs only
     hooks:
       - path: alerts
         agent: assistant
         # ...

   "memory" keeps the old in-memory behaviour when you don’t want an on-disk store.

3. See a degraded fallback

   If a durable store cannot initialise, the boundary keeps serving in-memory and records a degraded owner:

   {
     "owner_kind": "gateway",
     "owner_id": "durability:idempotency",
     "state": "cold",
     "reason": "durable idempotency store unavailable (running in-memory)",
     "retry_hint": "praisonai gateway doctor --fix"
   }

   It surfaces in praisonai gateway status under Degraded: and in GET /health under degraded_owners.

4. Recover

   praisonai gateway doctor --fix

   Run the sanctioned repair, or hot-reload a config that fixes the store path — either clears the degraded entry automatically on the next successful build.

What Happens on Init Failure

When a durable store genuinely cannot initialise, the boundary that owns it (the praisonai-bot wrapper, praisonai_bot.bots._session):

1. Logs the failure with the raw store path (log only).
2. Records a gateway / durability:* degraded owner with a redacted reason and the praisonai gateway doctor --fix hint.
3. Continues serving in-memory so inbound delivery keeps working.
4. Auto-clears the degraded owner on the next successful (re)build of the durable store.

The two owners:

On the healthy path — store_backend: redis with Redis reachable — there is no durability:idempotency fact: the cross-replica store gives cluster-wide exactly-once admission. The owner only appears when the store degrades, carrying one of three reasons:

How to See It

$ praisonai gateway status
...
  Degraded:
    ✗ gateway:durability:idempotency — durable idempotency store unavailable (running in-memory)  fix: praisonai gateway doctor --fix

curl http://127.0.0.1:8765/health

{
  "degraded_owners": [
    {
      "owner_kind": "gateway",
      "owner_id": "durability:idempotency",
      "state": "cold",
      "reason": "durable idempotency store unavailable (running in-memory)",
      "retry_hint": "praisonai gateway doctor --fix"
    }
  ]
}

from praisonaiagents import Agent
from praisonaiagents.tools import gateway_status

agent = Agent(
    name="assistant",
    instructions="Call gateway_status; warn if a durability owner is degraded.",
    tools=[gateway_status],
)

Best Practices

Related