Connection Health & Cleanup
Relevant source files
The following files were used as context for generating this wiki page:
Connection Health & Cleanup manages the lifecycle of sessions between downstream agents, the Freebuff Proxy, and the official upstream endpoints. It ensures that ghost connections are terminated, idle sessions are handled according to billing logic, and resources are released upon client disconnect or service restart. The system maintains connection stability by implementing a sticky-first scheduling policy and protecting bought quota (Freebucks) from unnecessary releases.
Sources: README_EN.md, src/AGENTS.md
Session Lifecycle and Quota Protection
The proxy manages upstream sessions by balancing cost efficiency with connection health. Because the upstream bills in Freebucks (FB) where one admit buys a full hour, the service does not release a session just because it is idle during that hour. Early deletion does not result in a refund of Freebucks, so the system holds the session for the duration of the paid window to provide zero marginal cost for subsequent requests.
Sources: README_EN.md, src/AGENTS.md:58-65
Scheduling and Failover Logic
The system uses a sticky-first scheduling policy to maintain session stability. It prioritizes reusing hot sessions over creating new ones to minimize costs and avoid being flagged as an automated "account farm" by the upstream.
Sources: src/AGENTS.md:66-72
Connection Termination and Cleanup
The proxy implements specific cleanup behaviors to prevent resource leaks and ensure downstream clients receive appropriate status codes.
- Client Disconnect: The service releases upstream sessions when a downstream client disconnects to free up account slots.
- Idle Timeout: A background process monitors for ghost connections and cuts them if they exceed the idle threshold.
- Restart Fallback: During service startup, the system performs a cleanup scan to settle pending upstream session handles, ensuring no stale sessions block account capacity.
Sources: README_EN.md, src/AGENTS.md:52-57
Connection Routing Table
The route-table.ts defines how incoming paths are categorized to ensure proper handling and error reporting. Unrecognized paths are directed to a static handler to avoid returning HTML errors to API clients, which can cause SDK parsing failures.
| Path Pattern | Target Face | Purpose |
|---|---|---|
/healthz | proxy | Liveness probe for monitoring systems |
/v1/chat/completions | proxy | Main API path for session passthrough |
/api/* | console | Internal management and dashboard endpoints |
/* (Fallback) | static | Static asset hosting and 404 responses |
Sources: scripts/gates/checks/guard/route-table.ts:32-48
Upstream Contract & Heartbeats
The proxy maintains connection health by adhering to a strict upstream contract. It uses designated headers to signal connection status and session continuity to the official Freebuff API.
Relevant Upstream Headers for Health
The proxy utilizes specific headers defined in the upstream-contract.ts to manage session state and connection identity.
| Header Identifier | Header Name | Description |
|---|---|---|
H_INSTANCE_ID | x-freebuff-instance-id | Identifies a specific session instance for deletion |
H_HEARTBEAT | x-freebuff-heartbeat | Signals that the connection is active during long streams |
H_MULTI_SESSION | x-freebuff-multi-session | Manages multiple sessions under a single account |
H_PURCHASE_CONTINUITY | x-freebuff-purchase-continuity | Signals continuity of a bought time window |
Sources: src/upstream/upstream-contract.ts:79-110
Summary
Connection Health & Cleanup prioritizes session reuse and quota protection within the constraints of Freebuff's hourly billing model. By strictly following the upstream contract and implementing robust cleanup procedures for client disconnects and service restarts, the system ensures high availability and stable performance for downstream agents.