Push Delivery Store

Durable, at-least-once push delivery that survives gateway restarts

Push delivery persists pending, un-acknowledged events to disk so a gateway restart never silently drops a message.

Quick Start

1. Default (durable, zero config)

   Enable push and delivery is durable out of the box — no flags, no external services.

   from praisonaiagents import Agent
   from praisonaiagents.gateway import GatewayConfig, PushConfig
   
   agent = Agent(name="Notifier", instructions="Push updates to subscribed clients")
   
   gateway = GatewayConfig(
       push=PushConfig(enabled=True)   # durable-by-default SQLite backend
   )

   Pending events are written to ~/.praisonai/state/push_delivery.sqlite and replayed on restart.

2. Explicit ephemeral (opt-out for tests)

   Switch to memory when durability is unwanted, such as throwaway test runs.

   from praisonaiagents.gateway import GatewayConfig, PushConfig, DeliveryConfig
   
   gateway = GatewayConfig(
       push=PushConfig(
           enabled=True,
           delivery=DeliveryConfig(store_backend="memory"),
       )
   )

3. Redis for horizontal scaling

   Point delivery at Redis to fan out across multiple gateway processes.

   from praisonaiagents.gateway import GatewayConfig, PushConfig, DeliveryConfig, RedisConfig
   
   gateway = GatewayConfig(
       push=PushConfig(
           enabled=True,
           redis=RedisConfig(url="redis://localhost:6379/0"),
           delivery=DeliveryConfig(store_backend="redis"),
       )
   )

The same settings load from gateway.yaml:

gateway:
  push:
    enabled: true
    delivery:
      store_backend: sqlite   # default; also: redis | memory
      ack_timeout: 30
      max_retries: 3
      message_ttl: 86400

How It Works

The store persists each pending event, replays it after a restart, and evicts the row once the client acknowledges.

Choosing a Backend

Pick the backend that matches your durability and scaling needs.

Configuration Options

DeliveryConfig controls the at-least-once guarantee.

An invalid store_backend raises ValueError at construction time — the closed set is validated in __post_init__.

Where State Lives

Common Patterns

Three setups cover most deployments.

from praisonaiagents.gateway import GatewayConfig, PushConfig

gateway = GatewayConfig(push=PushConfig(enabled=True))

from praisonaiagents.gateway import GatewayConfig, PushConfig, DeliveryConfig, RedisConfig

gateway = GatewayConfig(
    push=PushConfig(
        enabled=True,
        redis=RedisConfig(url="redis://localhost:6379/0"),
        delivery=DeliveryConfig(store_backend="redis"),
    )
)

from praisonaiagents.gateway import GatewayConfig, PushConfig, DeliveryConfig

gateway = GatewayConfig(
    push=PushConfig(
        enabled=True,
        delivery=DeliveryConfig(store_backend="memory"),
    )
)

Best Practices

Related