Upstream Session Lifecycle
Relevant source files
The following files were used as context for generating this wiki page:
The Upstream Session Lifecycle manages the acquisition, reuse, and release of paid sessions from the Freebuff service. In this architecture, a session represents a one-hour purchase of a specific model's quota, where the first admission (admit) buys the full hour and subsequent requests within that hour incur no additional marginal cost.
Sources: README_EN.md:120-125, src/session/state.ts:15-20
Session State and Management
The system tracks the state of each upstream session using a dedicated SessionState container. This state manages session identifiers, expiry times, quota information, and billing metrics known as Freebucks (FB).
Key State Components
The SessionState structure maintains the following critical data points for every active upstream account:
| Field | Description |
|---|---|
instanceId | The unique UUID identifying the current session instance. |
desktopPurchases | A snapshot of active purchases returned by the upstream. |
session | The local SessionHandle containing status, model, and expiration. |
freebucks | The primary billing metric for upstream quota. |
admitCount / reuseCount | Counters for new session creations versus sticky reuse. |
Sources: src/session/state.ts:68-125
The state also includes specialized timers for idle releases, refund retries, and session polling to keep local states synchronized with the upstream inventory.
Sources: src/session/state.ts:130-140
Admission and Lifecycle Flow
The session lifecycle begins when a downstream request requires an upstream model. The system evaluates existing sessions before attempting to purchase new ones.
Session Acquisition Flow
- Model Resolution: The system maps the requested model name to the upstream model key.
- Inventory Check: It verifies if an active session for that model already exists in
desktopPurchases. - Admission (POST /session/admission): If no session exists, it performs an admission request to buy an hour of model access.
- Sticky Reuse: If a "hot" session is available, the system reuses it to avoid additional Freebucks expenditure.
The diagram shows the logic for selecting between reusing an existing session or admitting a new one.
Sources: src/session/state.ts:114-118, src/upstream/upstream-contract.ts:31-35, src/proxy/transport/forward.ts:110-120
Upstream Contract and Endpoints
Interaction with the upstream session lifecycle is governed by a strict contract of endpoints and business headers. All components must use these centralized constants to ensure compatibility with the upstream's desktop client protocol.
Critical Lifecycle Endpoints
| Endpoint Constant | Path | Purpose |
|---|---|---|
EP_SESSION_ADMISSION | /api/v1/freebuff/session/admission | Purchases a new session slot. |
EP_SESSION | /api/v1/freebuff/session | Manages active session state. |
EP_CHAT | /api/v1/chat/completions | Executes requests within an admitted session. |
EP_STREAK | /api/v1/freebuff/streak | Reports daily bonus and reset status. |
Sources: src/upstream/upstream-contract.ts:28-60
Instance Identification
Every chat request within a session must include the x-freebuff-instance-id header or metadata. This identifier links the request to the specific hour of model access purchased during the admission step. Missing this identifier typically results in a 428 Precondition Required error from the upstream.
Sources: src/proxy/transport/forward.ts:65-75, src/upstream/upstream-contract.ts:85-87
Quota and Billing Protection
The system implements "Quota Protection" for Freebucks. Because the upstream bills for a full hour upon admission and does not refund for early disconnection, the proxy service maintains the session even if idle until the hour expires or the daily limit is reached.
Billing Logic
- Hourly Buy-in: Admission buys exactly 60 minutes.
- Marginal Cost: Requests within that hour cost 0 Freebucks.
- Refund Semantics:
DELETErequests do not immediately refund Freebucks; they are marked asfreebucksRefundPending. - Rate Limits: Sessions per model are capped (typically 6 per model per day).
This sequence illustrates how a single admission covers multiple requests and the behavior of the refund mechanism.
Sources: README_EN.md:120-130, src/session/state.ts:34-45, src/upstream/client.ts:40-45
Error Handling and Recovery
Session lifecycle management includes specific handling for account and model-level failures.
- Account Ban: If the upstream returns a ban signal, the account is removed from the active pool.
- Rate Limited / IP Capped: Triggers a cooldown for the specific account.
- Model Unavailable (503): This is treated as a model-side issue; the system skips the model but does not necessarily cool down the entire account.
- Recoverable Gates: Certain gate errors allow for immediate re-admission within the same account.
Sources: src/upstream/client.ts:30-40, src/proxy/transport/forward.ts:150-165
Technical wiki page generated based on repository context. Use src/session/manager.ts and related files for implementation details of the SessionManager class.