Durable Long-Poll Delivery

Long-poll fallback survives backpressure and gateway restarts with at-least-once delivery

Long-poll clients get the same at-least-once guarantee as WebSocket clients — a full queue overflows to the durable store instead of silently dropping.

A client polling over HTTP receives every event even when its queue backs up or the gateway restarts mid-delivery — the overflow lands in the durable store and replays on the next poll.

Quick Start

1. Run an agent behind the gateway

   Any agent hosted on the gateway can push to poll clients — no code change needed:

   from praisonaiagents import Agent
   
   agent = Agent(
       name="alerts-agent",
       instructions="Summarise incoming alert events in one sentence",
   )
   agent.start("Ready to push alerts to polling clients")

2. Bound the poll queue in gateway.yaml

   Set a per-client queue bound; overflow persists to the durable store:

   # gateway.yaml
   push:
     enabled: true
     polling:
       max_queue_size: 1000   # default; overflow persists to the durable store

3. Enable a delivery store for durability

   A delivery backend makes the overflow at-least-once and survives restarts:

   # gateway.yaml
   push:
     enabled: true
     delivery:
       store_backend: sqlite   # "sqlite" (default) | "redis" | "memory"

How It Works

An event that arrives for a poll client whose in-memory queue is full is persisted to the shared push store, then replayed on the next poll and held until the client acks.

Configuration Options

PollingConfig controls the poll transport. Every field is extracted from the SDK dataclass.

# gateway.yaml — full push block
push:
  enabled: true
  polling:
    enabled: true
    long_poll_timeout: 30
    max_batch_size: 100
    max_queue_size: 1000
  delivery:
    enabled: true
    store_backend: sqlite

Compatibility Note

import httpx

resp = httpx.post(
    "http://localhost:8765/api/push/poll/ack",
    json={"poll_token": token, "event_id": event_id},
)
if resp.status_code == 503:
    # Delivery guarantees are off — the ack was a no-op by design.
    logger.warning("Poll ack skipped: delivery guarantee not enabled")
else:
    resp.raise_for_status()

Common Patterns

Choose a max_queue_size and store that matches your durability needs.

# Durable, single-instance (default) — survives restarts
push:
  polling:
    max_queue_size: 1000
  delivery:
    store_backend: sqlite

# Durable, multi-instance — shared store across replicas
push:
  polling:
    max_queue_size: 1000
  delivery:
    store_backend: redis

# Legacy unbounded — no overflow, no durability (not recommended)
push:
  polling:
    max_queue_size: 0

Best Practices

Related