> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Gateway Drain Trigger
> Port-less, restart-safe external drain signal for hosted / containerised gateway deployments
The gateway now ships in the `praisonai-bot` package. `praisonai serve gateway` still works exactly as documented here; for a standalone install see [praisonai-bot Migration](/docs/guides/praisonai-bot-migration).
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
agent = Agent(name="drain-agent", instructions="Drain the gateway queue gracefully.")
agent.start("Drain all pending messages before shutting down the gateway.")
```
Ask a running gateway to finish in-flight turns and exit — without exposing any inbound port, and without a left-over signal wedging a restarted instance.
The user drops a drain marker file; the gateway finishes in-flight turns and exits without exposing an inbound drain port.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "Port-less Drain Trigger"
OP[👤 Operator] --> MARK[📄 .drain_request.json
epoch-stamped marker]
MARK --> WATCH[👁️ Marker watcher]
WATCH --> POL[🛡️ DrainMarkerPolicy]
POL --> STOP[🛑 gateway.stop drain_timeout]
STOP --> DONE[✅ Clean exit]
end
classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef policy fill:#189AB4,stroke:#7C90A0,color:#fff
classDef result fill:#10B981,stroke:#7C90A0,color:#fff
class OP,MARK input
class WATCH process
class POL policy
class STOP,DONE result
```
## Quick Start
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.gateway import DrainMarkerPolicy, current_epoch
```
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
policy = DrainMarkerPolicy()
epoch = current_epoch()
```
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import asyncio
import json
import os
from time import monotonic
from praisonaiagents.gateway import DrainMarkerPolicy, current_epoch
policy = DrainMarkerPolicy()
last_handled = None
path = os.path.expanduser("~/.praisonai/gateway/.drain_request.json")
async def watch(gateway):
global last_handled
while True:
if os.path.exists(path):
with open(path) as f:
marker = json.load(f)
else:
marker = None
if policy.drain_requested(
marker,
current_epoch(),
monotonic(),
last_handled_epoch=last_handled,
):
last_handled = marker.get("epoch")
await gateway.stop(drain_timeout=30)
return
await asyncio.sleep(1)
```
The built-in marker watcher and `praisonai gateway drain` CLI are not yet merged — write your own watcher loop for now (pattern above). This page will be updated when the follow-up PR ships.
***
## How It Works
### Restart-Safety Story
The entire point of this feature: a marker stamped with `current_epoch()` is silently ignored by any *other* instance of the gateway — even if the marker file survives a reboot on a durable volume.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant OldInst as Gateway v1
(epoch=E1)
participant Disk as Durable volume
.drain_request.json
participant NewInst as Gateway v2
(epoch=E2 after reboot)
participant Policy as DrainMarkerPolicy
OldInst->>Disk: write {epoch: E1, action: drain}
Note over OldInst: drains, exits
Note over Disk: marker survives reboot
NewInst->>Disk: read marker on startup
NewInst->>Policy: drain_requested(marker, E2)
Policy-->>NewInst: False (foreign epoch — ignored)
Note over NewInst: starts cleanly, no wedge
```
### Decision Tree — When Is a Marker Honoured?
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
Q{"marker present?"}
Q -->|no / None| IGNORE1[Ignore]
Q -->|yes, dict| EP{"epoch matches
current_epoch()?"}
EP -->|missing & require_epoch=True| IGNORE2[Ignore — fail-safe]
EP -->|missing & require_epoch=False| ACT1[Honour]
EP -->|foreign| IGNORE3[Ignore — stale]
EP -->|matches| DEDUP{"last_handled_epoch
same as marker?"}
DEDUP -->|yes| IGNORE4[Ignore — already handled]
DEDUP -->|no| ACTION{"action in drain or empty
and string-typed?"}
ACTION -->|no| IGNORE5[Ignore — malformed]
ACTION -->|yes| ACT2[Honour drain]
classDef question fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef ignore fill:#8B0000,stroke:#7C90A0,color:#fff
classDef act fill:#10B981,stroke:#7C90A0,color:#fff
class Q,EP,DEDUP,ACTION question
class IGNORE1,IGNORE2,IGNORE3,IGNORE4,IGNORE5 ignore
class ACT1,ACT2 act
```
***
## The Drain Marker Contract
Write this JSON to the marker path:
```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
"epoch": "