Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

fix(proxy): enforce budget limits on OpenAI and Gemini routes (#3579)

Johnny Wilson Doughertyf734c5734123
diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.py
index 7edf28ad1..66c074299 100644
--- a/headroom/proxy/handlers/anthropic.py
+++ b/headroom/proxy/handlers/anthropic.py
@@ -24,6 +24,8 @@ if TYPE_CHECKING:
from fastapi import Request
from fastapi.responses import Response, StreamingResponse
+ from headroom.proxy.cost import CostTracker
+
import httpx
from headroom.agent_savings import proxy_pipeline_kwargs
@@ -278,6 +280,8 @@ def _looks_like_sse_response(response: httpx.Response) -> bool:
class AnthropicHandlerMixin:
"""Mixin providing Anthropic API handler methods for HeadroomProxy."""
+ cost_tracker: CostTracker | None = None
+
def _adapt_event_stream_to_json(
self,
response: httpx.Response,
@@ -1261,15 +1265,16 @@ class AnthropicHandlerMixin:
)
# Budget check
- if self.cost_tracker:
- allowed, remaining = self.cost_tracker.check_budget()
+ cost_tracker = self.cost_tracker
+ if cost_tracker:
+ allowed, remaining = cost_tracker.check_budget()
if not allowed:
# Unit 4: release the pre-upstream semaphore before we
# bail out of the handler via HTTPException.
await _finalize_pre_upstream()
raise HTTPException(
status_code=429,
- detail=self.cost_tracker.budget_denial_detail(),
+ detail=cost_tracker.budget_denial_detail(),
)
# Memory: Get user ID when memory is enabled (fallback to "default" for simple DevEx).
diff --git a/headroom/proxy/handlers/gemini.py b/headroom/proxy/handlers/gemini.py
index 79463c579..3f82145be 100644
--- a/headroom/proxy/handlers/gemini.py
+++ b/headroom/proxy/handlers/gemini.py
@@ -15,6 +15,8 @@ if TYPE_CHECKING:
from fastapi import Request
from fastapi.responses import JSONResponse, Response, StreamingResponse
+ from headroom.proxy.cost import CostTracker
+
from headroom.agent_savings import proxy_pipeline_kwargs
from headroom.copilot_auth import build_copilot_upstream_url
from headroom.proxy.auth_mode import classify_client
@@ -47,6 +49,8 @@ class _GeminiContinuationError(Exception):
class GeminiHandlerMixin:
"""Mixin providing Gemini API handler methods for HeadroomProxy."""
+ cost_tracker: CostTracker | None = None
+
async def _count_tokens_offloaded(self, model, messages): # noqa: ANN001, ANN201
from headroom.proxy.token_counting import count_tokens_offloaded
@@ -404,6 +408,16 @@ class GeminiHandlerMixin:
detail=f"Rate limited. Retry after {wait_seconds:.1f}s",
)
+ # Budget check
+ cost_tracker = self.cost_tracker
+ if cost_tracker:
+ allowed, remaining = cost_tracker.check_budget()
+ if not allowed:
+ raise HTTPException(
+ status_code=429,
+ detail=cost_tracker.budget_denial_detail(),
+ )
+
# Convert Gemini format to messages for optimization
system_instruction = body.get("systemInstruction")
messages, preserved_indices = self._gemini_contents_to_messages(
@@ -1004,6 +1018,7 @@ class GeminiHandlerMixin:
request: Request,
) -> StreamingResponse | JSONResponse:
"""Handle Pi/OpenClaw Google Cloud Code Assist and Antigravity streaming requests."""
+ from fastapi import HTTPException
from fastapi.responses import JSONResponse
from headroom.proxy.helpers import _read_request_json
@@ -1062,6 +1077,16 @@ class GeminiHandlerMixin:
request_id=request_id,
)
+ # Budget check
+ cost_tracker = self.cost_tracker
+ if cost_tracker:
+ allowed, remaining = cost_tracker.check_budget()
+ if not allowed:
+ raise HTTPException(
+ status_code=429,
+ detail=cost_tracker.budget_denial_detail(),
+ )
+
system_instruction = request_payload.get("systemInstruction")
optimization_system_instruction = None if is_antigravity else system_instruction
messages, preserved_indices = self._gemini_contents_to_messages(
@@ -1173,6 +1198,7 @@ class GeminiHandlerMixin:
model: str,
) -> StreamingResponse | JSONResponse:
"""Handle Gemini streaming endpoint /v1beta/models/{model}:streamGenerateContent."""
+ from fastapi import HTTPException
from fastapi.responses import JSONResponse
from headroom.proxy.helpers import _read_request_json
@@ -1216,6 +1242,16 @@ class GeminiHandlerMixin:
request_id=request_id,
)
+ # Budget check
+ cost_tracker = self.cost_tracker
+ if cost_tracker:
+ allowed, remaining = cost_tracker.check_budget()
+ if not allowed:
+ raise HTTPException(
+ status_code=429,
+ detail=cost_tracker.budget_denial_detail(),
+ )
+
# Token counting (offloaded off the event loop — GH #1701). Reuse the
# shared _dict_parts coercion and keep only str text values: count_text
# raises on a non-str part value and the fail-open path re-runs the same
diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.py
index 15f2d545e..fc6d1a464 100644
--- a/headroom/proxy/handlers/openai.py
+++ b/headroom/proxy/handlers/openai.py
@@ -46,6 +46,8 @@ if TYPE_CHECKING:
from fastapi import Request, WebSocket
from fastapi.responses import JSONResponse, Response, StreamingResponse
+ from headroom.proxy.cost import CostTracker
+
import httpx
from headroom.agent_savings import proxy_pipeline_kwargs
@@ -1724,6 +1726,8 @@ def _prefers_http1_passthrough(base_url: str) -> bool:
class OpenAIHandlerMixin:
"""Mixin providing OpenAI API handler methods for HeadroomProxy."""
+ cost_tracker: CostTracker | None = None
+
async def _count_tokens_offloaded(self, model, messages): # noqa: ANN001, ANN201
from headroom.proxy.token_counting import count_tokens_offloaded
@@ -3544,6 +3548,16 @@ class OpenAIHandlerMixin:
detail=f"Rate limited. Retry after {wait_seconds:.1f}s",
)
+ # Budget check
+ cost_tracker = self.cost_tracker
+ if cost_tracker:
+ allowed, remaining = cost_tracker.check_budget()
+ if not allowed:
+ raise HTTPException(
+ status_code=429,
+ detail=cost_tracker.budget_denial_detail(),
+ )
+
# Snapshot cache-key fields ONCE here (pre-upstream), reused verbatim
# at the cache.set site below — re-reading body at set risks a mutated
# body (e.g. tools reassigned) and a key mismatch (#327). OpenAI's
@@ -5656,6 +5670,16 @@ class OpenAIHandlerMixin:
detail=f"Rate limited. Retry after {wait_seconds:.1f}s",
)
+ # Budget check
+ cost_tracker = self.cost_tracker
+ if cost_tracker:
+ allowed, remaining = cost_tracker.check_budget()
+ if not allowed:
+ raise HTTPException(
+ status_code=429,
+ detail=cost_tracker.budget_denial_detail(),
+ )
+
# Token counting on converted messages (offloaded off the event loop — GH #1701)
tokenizer, original_tokens = await self._count_tokens_offloaded(model, messages)
# Messages-only count, preserved for the output shaper's turn/size
@@ -6801,6 +6825,22 @@ class OpenAIHandlerMixin:
)
await websocket.close(code=1008, reason="origin not allowed")
return
+
+ # Budget check
+ cost_tracker = self.cost_tracker
+ if cost_tracker:
+ allowed, _ = cost_tracker.check_budget()
+ if not allowed:
+ logger.warning(
+ "event=websocket_budget_exceeded request_id=%s session_id=%s",
+ request_id,
+ session_id,
+ )
+ await websocket.close(
+ code=1008,
+ reason=cost_tracker.budget_denial_detail()[:120],
+ )
+ return
# WS sessions bypass the HTTP middleware that stamps X-Client: codex on
# the Responses endpoint, so apply the same path-based stamp here before
# classify_client runs (parallels server.py / should_stamp_codex_client).
@@ -7975,6 +8015,24 @@ class OpenAIHandlerMixin:
)
if ws_connected:
+ cost_tracker = self.cost_tracker
+ if cost_tracker:
+ allowed, _ = cost_tracker.check_budget()
+ if not allowed:
+ logger.warning(
+ "event=websocket_budget_exceeded request_id=%s session_id=%s frame=1",
+ request_id,
+ session_id,
+ )
+ termination_cause = "budget_exceeded"
+ with contextlib.suppress(Exception):
+ await websocket.close(
+ code=1008,
+ reason=cost_tracker.budget_denial_detail()[:120],
+ )
+ with contextlib.suppress(Exception):
+ await upstream.close()
+ return
async with upstream:
await upstream.send(_strip_codex_lite_metadata(first_msg_raw))
@@ -8298,6 +8356,7 @@ class OpenAIHandlerMixin:
nonlocal ws_last_client_frame_type, ws_client_disconnect_seen
nonlocal current_response_input
nonlocal current_response_template
+ nonlocal termination_cause
client_frame_index = 1
try:
while True:
@@ -8349,6 +8408,25 @@ class OpenAIHandlerMixin:
isinstance(_inbound_frame_body, dict)
and _inbound_frame_body.get("type") == "response.create"
):
+ cost_tracker = self.cost_tracker
+ if cost_tracker:
+ allowed, _ = cost_tracker.check_budget()
+ if not allowed:
+ logger.warning(
+ "event=websocket_budget_exceeded request_id=%s session_id=%s frame=%d",
+ request_id,
+ session_id,
+ client_frame_index,
+ )
+ termination_cause = "budget_exceeded"
+ with contextlib.suppress(Exception):
+ await websocket.close(
+ code=1008,
+ reason=cost_tracker.budget_denial_detail()[
+ :120
+ ],
+ )
+ return
ws_response_create_frames += 1
inbound_response = _inbound_frame_body.get(
"response", _inbound_frame_body
@@ -9013,7 +9091,9 @@ class OpenAIHandlerMixin:
exc = t.exception()
task_name = t.get_name() or ""
if t is client_task:
- if client_relay_error is not None:
+ if termination_cause == "budget_exceeded":
+ pass
+ elif client_relay_error is not None:
termination_cause = "client_error"
elif exc is None:
termination_cause = "client_disconnect"
@@ -9080,6 +9160,22 @@ class OpenAIHandlerMixin:
ws_last_upstream_frame_type,
)
else:
+ cost_tracker = self.cost_tracker
+ if cost_tracker:
+ allowed, _ = cost_tracker.check_budget()
+ if not allowed:
+ logger.warning(
+ "event=websocket_budget_exceeded request_id=%s session_id=%s fallback=1",
+ request_id,
+ session_id,
+ )
+ termination_cause = "budget_exceeded"
+ with contextlib.suppress(Exception):
+ await websocket.close(
+ code=1008,
+ reason=cost_tracker.budget_denial_detail()[:120],
+ )
+ return
# WS upgrade failed (HTTP 500 from OpenAI is common).
# Fall back to HTTP POST streaming and relay SSE events
# back over the client WebSocket transparently.
diff --git a/headroom/proxy/ws_session_registry.py b/headroom/proxy/ws_session_registry.py
index b28324cf2..d36c694e6 100644
--- a/headroom/proxy/ws_session_registry.py
+++ b/headroom/proxy/ws_session_registry.py
@@ -53,6 +53,7 @@ TerminationCause = Literal[
"client_cancel",
"response_completed",
"client_timeout",
+ "budget_exceeded",
"unknown",
]
diff --git a/tests/test_proxy_budget.py b/tests/test_proxy_budget.py
new file mode 100644
index 000000000..38ac92ce0
--- /dev/null
+++ b/tests/test_proxy_budget.py
@@ -0,0 +1,739 @@
+"""Integration tests for proxy budget enforcement (Issue #3374).
+
+Verifies that `--budget` limits are enforced on these generation routes:
+- OpenAI chat completions (`/v1/chat/completions`)
+- OpenAI responses (`/v1/responses` HTTP and WebSocket: handshake, first frame,
+ later `response.create` frames, and the HTTP fallback)
+- Gemini generate content (`/v1beta/models/{model}:generateContent`)
+- Gemini stream generate content (`/v1beta/models/{model}:streamGenerateContent`)
+- Google Cloud Code Assist stream (`/v1internal:streamGenerateContent`)
+- Anthropic messages (`/v1/messages`) for parity
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import httpx
+import pytest
+
+pytest.importorskip("fastapi")
+
+from fastapi.testclient import TestClient
+from starlette.websockets import WebSocketDisconnect
+
+from headroom.proxy.server import ProxyConfig, create_app
+
+
+class _CountingMockTransport(httpx.AsyncBaseTransport):
+ """Mock transport that tracks calls and returns valid mock LLM responses."""
+
+ def __init__(self) -> None:
+ self.call_count = 0
+ self.captured_requests: list[httpx.Request] = []
+
+ async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+ self.call_count += 1
+ self.captured_requests.append(request)
+
+ url_str = str(request.url)
+
+ if "chat/completions" in url_str:
+ return httpx.Response(
+ 200,
+ headers={"content-type": "application/json"},
+ json={
+ "id": "chatcmpl-mock",
+ "object": "chat.completion",
+ "created": 1234567890,
+ "model": "gpt-4o",
+ "choices": [
+ {
+ "index": 0,
+ "message": {"role": "assistant", "content": "Hello!"},
+ "finish_reason": "stop",
+ }
+ ],
+ "usage": {
+ "prompt_tokens": 10,
+ "completion_tokens": 5,
+ "total_tokens": 15,
+ },
+ },
+ )
+
+ if "responses" in url_str:
+ return httpx.Response(
+ 200,
+ headers={"content-type": "application/json"},
+ json={
+ "id": "resp-mock",
+ "object": "response",
+ "created": 1234567890,
+ "model": "gpt-4o",
+ "output": [
+ {
+ "type": "message",
+ "role": "assistant",
+ "content": [{"type": "text", "text": "Hello!"}],
+ }
+ ],
+ "usage": {
+ "input_tokens": 10,
+ "output_tokens": 5,
+ "total_tokens": 15,
+ },
+ },
+ )
+
+ if "generateContent" in url_str:
+ return httpx.Response(
+ 200,
+ headers={"content-type": "application/json"},
+ json={
+ "candidates": [
+ {
+ "content": {
+ "parts": [{"text": "Hello from Gemini!"}],
+ "role": "model",
+ },
+ "finishReason": "STOP",
+ }
+ ],
+ "usageMetadata": {
+ "promptTokenCount": 10,
+ "candidatesTokenCount": 5,
+ "totalTokenCount": 15,
+ },
+ },
+ )
+
+ # Anthropic messages
+ return httpx.Response(
+ 200,
+ headers={"content-type": "application/json"},
+ json={
+ "id": "msg_mock",
+ "type": "message",
+ "role": "assistant",
+ "content": [{"type": "text", "text": "Hello from Claude!"}],
+ "usage": {
+ "input_tokens": 10,
+ "output_tokens": 5,
+ },
+ },
+ )
+
+
+def _build_proxy_client(
+ *,
+ budget_limit_usd: float | None = None,
+ budget_period: str = "daily",
+ cost_tracking_enabled: bool = True,
+) -> tuple[TestClient, _CountingMockTransport]:
+ config = ProxyConfig(
+ optimize=False,
+ cache_enabled=False,
+ rate_limit_enabled=False,
+ cost_tracking_enabled=cost_tracking_enabled,
+ budget_limit_usd=budget_limit_usd,
+ budget_period=budget_period, # type: ignore[arg-type]
+ log_requests=False,
+ ccr_inject_tool=False,
+ ccr_handle_responses=False,
+ ccr_context_tracking=False,
+ image_optimize=False,
+ anthropic_api_url="https://api.anthropic.test",
+ openai_api_url="https://api.openai.test",
+ gemini_api_url="https://api.gemini.test",
+ )
+ app = create_app(config)
+ transport = _CountingMockTransport()
+ proxy = app.state.proxy
+ proxy.http_client = httpx.AsyncClient(transport=transport)
+ return TestClient(app), transport
+
+
+def test_zero_budget_blocks_openai_chat_completions() -> None:
+ client, transport = _build_proxy_client(budget_limit_usd=0.0)
+
+ response = client.post(
+ "/v1/chat/completions",
+ headers={"authorization": "Bearer sk-test"},
+ json={
+ "model": "gpt-4o",
+ "messages": [{"role": "user", "content": "Hello"}],
+ },
+ )
+
+ assert response.status_code == 429
+ assert response.json()["detail"] == "Budget exceeded for daily period"
+ assert transport.call_count == 0
+
+
+def test_zero_budget_blocks_openai_responses() -> None:
+ client, transport = _build_proxy_client(budget_limit_usd=0.0)
+
+ response = client.post(
+ "/v1/responses",
+ headers={"authorization": "Bearer sk-test"},
+ json={
+ "model": "gpt-4o",
+ "input": "Hello",
+ },
+ )
+
+ assert response.status_code == 429
+ assert response.json()["detail"] == "Budget exceeded for daily period"
+ assert transport.call_count == 0
+
+
+def test_zero_budget_blocks_gemini_generate_content() -> None:
+ client, transport = _build_proxy_client(budget_limit_usd=0.0)
+
+ response = client.post(
+ "/v1beta/models/gemini-1.5-pro:generateContent",
+ headers={"x-goog-api-key": "test-gemini-key"},
+ json={
+ "contents": [{"role": "user", "parts": [{"text": "Hello"}]}],
+ },
+ )
+
+ assert response.status_code == 429
+ assert response.json()["detail"] == "Budget exceeded for daily period"
+ assert transport.call_count == 0
+
+
+def test_zero_budget_blocks_gemini_stream_generate_content() -> None:
+ client, transport = _build_proxy_client(budget_limit_usd=0.0)
+
+ response = client.post(
+ "/v1beta/models/gemini-1.5-pro:streamGenerateContent",
+ headers={"x-goog-api-key": "test-gemini-key"},
+ json={
+ "contents": [{"role": "user", "parts": [{"text": "Hello"}]}],
+ },
+ )
+
+ assert response.status_code == 429
+ assert response.json()["detail"] == "Budget exceeded for daily period"
+ assert transport.call_count == 0
+
+
+def test_zero_budget_blocks_google_cloudcode_stream() -> None:
+ client, transport = _build_proxy_client(budget_limit_usd=0.0)
+
+ response = client.post(
+ "/v1internal:streamGenerateContent",
+ json={
+ "model": "gemini-2.5-pro",
+ "request": {"contents": [{"role": "user", "parts": [{"text": "Hello"}]}]},
+ },
+ )
+
+ assert response.status_code == 429
+ assert response.json()["detail"] == "Budget exceeded for daily period"
+ assert transport.call_count == 0
+
+
+def test_zero_budget_blocks_anthropic_messages_parity() -> None:
+ client, transport = _build_proxy_client(budget_limit_usd=0.0)
+
+ response = client.post(
+ "/v1/messages",
+ headers={
+ "x-api-key": "sk-ant-test",
+ "anthropic-version": "2023-06-01",
+ },
+ json={
+ "model": "claude-3-5-sonnet-20241022",
+ "messages": [{"role": "user", "content": "Hello"}],
+ "max_tokens": 100,
+ },
+ )
+
+ assert response.status_code == 429
+ assert response.json()["detail"] == "Budget exceeded for daily period"
+ assert transport.call_count == 0
+
+
+def test_unlimited_budget_allows_all_generation_routes() -> None:
+ client, transport = _build_proxy_client(budget_limit_usd=None)
+
+ # OpenAI chat
+ resp_chat = client.post(
+ "/v1/chat/completions",
+ headers={"authorization": "Bearer sk-test"},
+ json={"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]},
+ )
+ assert resp_chat.status_code == 200
+
+ # OpenAI responses
+ resp_resp = client.post(
+ "/v1/responses",
+ headers={"authorization": "Bearer sk-test"},
+ json={"model": "gpt-4o", "input": "Hello"},
+ )
+ assert resp_resp.status_code == 200
+
+ # Gemini generateContent
+ resp_gem = client.post(
+ "/v1beta/models/gemini-1.5-pro:generateContent",
+ headers={"x-goog-api-key": "test-key"},
+ json={"contents": [{"role": "user", "parts": [{"text": "Hello"}]}]},
+ )
+ assert resp_gem.status_code == 200
+
+ assert transport.call_count == 3
+
+
+def test_zero_budget_websocket_preflight_rejected() -> None:
+ client, _ = _build_proxy_client(budget_limit_usd=0.0)
+
+ with pytest.raises(WebSocketDisconnect) as exc_info:
+ with client.websocket_connect("/v1/responses"):
+ pass
+
+ assert exc_info.value.code == 1008
+
+
+def test_dynamic_budget_exhaustion_blocks_all_providers() -> None:
+ client, transport = _build_proxy_client(budget_limit_usd=0.05)
+
+ # First request succeeds
+ resp1 = client.post(
+ "/v1/chat/completions",
+ headers={"authorization": "Bearer sk-test"},
+ json={"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]},
+ )
+ assert resp1.status_code == 200
+ assert transport.call_count == 1
+
+ # Simulate accumulated spend that exceeds the $0.05 budget
+ proxy = client.app.state.proxy # type: ignore[attr-defined]
+ assert proxy.cost_tracker is not None
+ proxy.cost_tracker.record_tokens(
+ model="gpt-4o",
+ tokens_saved=0,
+ tokens_sent=100_000,
+ output_tokens=50_000,
+ )
+
+ allowed, _ = proxy.cost_tracker.check_budget()
+ assert not allowed
+
+ # Now all provider generation routes must reject with 429
+ routes_and_payloads = [
+ (
+ "/v1/chat/completions",
+ {"authorization": "Bearer sk-test"},
+ {"model": "gpt-4o", "messages": [{"role": "user", "content": "Hi"}]},
+ ),
+ (
+ "/v1/responses",
+ {"authorization": "Bearer sk-test"},
+ {"model": "gpt-4o", "input": "Hi"},
+ ),
+ (
+ "/v1beta/models/gemini-1.5-pro:generateContent",
+ {"x-goog-api-key": "test-key"},
+ {"contents": [{"role": "user", "parts": [{"text": "Hi"}]}]},
+ ),
+ (
+ "/v1/messages",
+ {"x-api-key": "sk-ant-test", "anthropic-version": "2023-06-01"},
+ {
+ "model": "claude-3-5-sonnet-20241022",
+ "messages": [{"role": "user", "content": "Hi"}],
+ "max_tokens": 10,
+ },
+ ),
+ ]
+
+ for route, headers, body in routes_and_payloads:
+ resp = client.post(route, headers=headers, json=body)
+ assert resp.status_code == 429
+ assert "Budget exceeded for daily period" in resp.json()["detail"]
+
+ # Upstream should not have received any additional calls after budget exhaustion
+ assert transport.call_count == 1
+
+
+class _FakeWebSocketDisconnect(Exception):
+ """Exception matching WebSocketDisconnect type-name check."""
+
+
+_FakeWebSocketDisconnect.__name__ = "WebSocketDisconnect_Fake"
+
+
+class _FakeUpstream:
+ """Fake upstream connection that records frames sent by Headroom."""
+
+ def __init__(self, events: list[str]) -> None:
+ self._events = list(events)
+ self.sent: list[str] = []
+ self.closed = False
+ self.response = SimpleNamespace(headers=[])
+
+ async def __aenter__(self) -> _FakeUpstream:
+ return self
+
+ async def __aexit__(self, exc_type, exc, tb) -> None:
+ self.closed = True
+
+ async def send(self, payload: str) -> None:
+ self.sent.append(payload)
+
+ async def close(self) -> None:
+ self.closed = True
+
+ def __aiter__(self):
+ return self._iter()
+
+ async def _iter(self):
+ for ev in self._events:
+ yield ev
+ await asyncio.Event().wait()
+
+
+class _ScriptedClientWS:
+ """Scripted client WebSocket delivering frames and tracking close state."""
+
+ def __init__(self, frames: list[str], *, on_frame2_callback=None) -> None:
+ self.headers = {"authorization": "Bearer test"}
+ self._frames = list(frames)
+ self.sent_text: list[str] = []
+ self.sent_bytes: list[bytes] = []
+ self.closed = False
+ self.close_code: int | None = None
+ self.close_reason: str | None = None
+ self.client = SimpleNamespace(host="127.0.0.1", port=12345)
+ self._on_frame2_callback = on_frame2_callback
+
+ async def accept(self, subprotocol=None, headers=None) -> None:
+ pass
+
+ async def receive_text(self) -> str:
+ if not self._frames:
+ raise _FakeWebSocketDisconnect("client closed")
+ frame = self._frames.pop(0)
+ if len(self._frames) == 0 and self._on_frame2_callback is not None:
+ self._on_frame2_callback()
+ return frame
+
+ async def send_text(self, text: str) -> None:
+ self.sent_text.append(text)
+
+ async def send_bytes(self, data: bytes) -> None:
+ self.sent_bytes.append(data)
+
+ async def close(self, code: int | None = None, reason: str | None = None) -> None:
+ self.closed = True
+ if code is not None or self.close_code is None:
+ self.close_code = code
+ if reason is not None or self.close_reason is None:
+ self.close_reason = reason
+
+
+def test_websocket_per_turn_budget_enforcement_blocks_late_response_create() -> None:
+ """A long-lived /v1/responses WebSocket opened under budget must reject subsequent
+
+ response.create frames once the budget is exhausted, and not forward them upstream.
+ """
+
+ async def _run() -> None:
+ config = ProxyConfig(
+ optimize=False,
+ cache_enabled=False,
+ rate_limit_enabled=False,
+ cost_tracking_enabled=True,
+ budget_limit_usd=0.05,
+ log_requests=False,
+ ccr_inject_tool=False,
+ ccr_handle_responses=False,
+ ccr_context_tracking=False,
+ image_optimize=False,
+ )
+ app = create_app(config)
+ proxy = app.state.proxy
+ assert proxy.cost_tracker is not None
+
+ # Verify initial state opens under budget
+ allowed, _ = proxy.cost_tracker.check_budget()
+ assert allowed
+
+ first_frame = json.dumps(
+ {
+ "type": "response.create",
+ "response": {"model": "gpt-4o", "input": "first turn"},
+ }
+ )
+ second_frame = json.dumps(
+ {
+ "type": "response.create",
+ "response": {"model": "gpt-4o", "input": "second turn"},
+ }
+ )
+
+ upstream_events = [
+ json.dumps({"type": "response.created", "response": {"id": "r_1"}}),
+ json.dumps(
+ {
+ "type": "response.completed",
+ "response": {
+ "id": "r_1",
+ "model": "gpt-4o",
+ "usage": {"input_tokens": 10, "output_tokens": 1},
+ },
+ }
+ ),
+ ]
+ upstream = _FakeUpstream(upstream_events)
+
+ mod = MagicMock()
+
+ async def _fake_connect(*args, **kwargs):
+ return upstream
+
+ mod.connect = _fake_connect
+ mod.Subprotocol = str
+
+ def _exhaust_budget() -> None:
+ proxy.cost_tracker.record_tokens(
+ model="gpt-4o",
+ tokens_saved=0,
+ tokens_sent=100_000,
+ output_tokens=50_000,
+ )
+
+ client_ws = _ScriptedClientWS(
+ [first_frame, second_frame],
+ on_frame2_callback=_exhaust_budget,
+ )
+ deregister_spy = MagicMock(side_effect=proxy.ws_sessions.deregister_and_count)
+ proxy.ws_sessions.deregister_and_count = deregister_spy
+
+ with patch.dict(sys.modules, {"websockets": mod}):
+ await asyncio.wait_for(
+ proxy.handle_openai_responses_ws(client_ws),
+ timeout=3.0,
+ )
+
+ # Proves:
+ # 1. First frame was allowed and forwarded upstream
+ assert len(upstream.sent) == 1
+ assert json.loads(upstream.sent[0])["response"]["input"] == "first turn"
+
+ # 2. Budget is exhausted after turn 1 spend
+ allowed, _ = proxy.cost_tracker.check_budget()
+ assert not allowed
+
+ # 3. Subsequent response.create on same socket was rejected with 1008
+ assert client_ws.closed is True
+ assert client_ws.close_code == 1008
+ assert "Budget exceeded for daily period" in (client_ws.close_reason or "")
+
+ # 4. Subsequent response.create was NOT forwarded upstream
+ assert len(upstream.sent) == 1
+
+ # 5. Session teardown records the budget rejection as the termination cause
+ deregister_spy.assert_called_once()
+ assert deregister_spy.call_args.kwargs["cause"] == "budget_exceeded"
+
+ asyncio.run(_run())
+
+
+def test_websocket_turn_completion_usage_exhausts_budget_and_blocks_next_turn() -> None:
+ """When turn 1 usage naturally exhausts the daily budget via the outcome funnel,
+
+ a subsequent response.create turn on the same socket is rejected and not forwarded.
+ """
+
+ async def _run() -> None:
+ config = ProxyConfig(
+ optimize=False,
+ cache_enabled=False,
+ rate_limit_enabled=False,
+ cost_tracking_enabled=True,
+ budget_limit_usd=0.05,
+ log_requests=False,
+ ccr_inject_tool=False,
+ ccr_handle_responses=False,
+ ccr_context_tracking=False,
+ image_optimize=False,
+ )
+ app = create_app(config)
+ proxy = app.state.proxy
+ assert proxy.cost_tracker is not None
+
+ allowed, _ = proxy.cost_tracker.check_budget()
+ assert allowed
+
+ first_frame = json.dumps(
+ {
+ "type": "response.create",
+ "response": {"model": "gpt-4o", "input": "turn 1"},
+ }
+ )
+ second_frame = json.dumps(
+ {
+ "type": "response.create",
+ "response": {"model": "gpt-4o", "input": "turn 2"},
+ }
+ )
+
+ upstream_events = [
+ json.dumps({"type": "response.created", "response": {"id": "r_1"}}),
+ json.dumps(
+ {
+ "type": "response.completed",
+ "response": {
+ "id": "r_1",
+ "model": "gpt-4o",
+ "usage": {"input_tokens": 100_000, "output_tokens": 50_000},
+ },
+ }
+ ),
+ ]
+ upstream = _FakeUpstream(upstream_events)
+
+ mod = MagicMock()
+
+ async def _fake_connect(*args, **kwargs):
+ return upstream
+
+ mod.connect = _fake_connect
+ mod.Subprotocol = str
+
+ class _DelayedClientWS(_ScriptedClientWS):
+ async def receive_text(self) -> str:
+ if not self._frames:
+ raise _FakeWebSocketDisconnect("client closed")
+ # Hold turn 2 until turn 1's response.completed usage is booked,
+ # rather than sleeping for a fixed wall-clock interval.
+ if len(self._frames) == 1:
+ for _ in range(400):
+ if not proxy.cost_tracker.check_budget()[0]:
+ break
+ await asyncio.sleep(0.005)
+ return self._frames.pop(0)
+
+ client_ws = _DelayedClientWS([first_frame, second_frame])
+
+ with patch.dict(sys.modules, {"websockets": mod}):
+ await asyncio.wait_for(
+ proxy.handle_openai_responses_ws(client_ws),
+ timeout=3.0,
+ )
+
+ assert client_ws.closed is True
+ assert client_ws.close_code == 1008
+ assert "Budget exceeded" in (client_ws.close_reason or "")
+ assert len(upstream.sent) == 1
+ assert json.loads(upstream.sent[0])["response"]["input"] == "turn 1"
+
+ allowed, _ = proxy.cost_tracker.check_budget()
+ assert not allowed
+
+ asyncio.run(_run())
+
+
+def _ws_budget_proxy(**overrides):
+ config = ProxyConfig(
+ optimize=False,
+ cache_enabled=False,
+ rate_limit_enabled=False,
+ cost_tracking_enabled=True,
+ budget_limit_usd=0.05,
+ log_requests=False,
+ ccr_inject_tool=False,
+ ccr_handle_responses=False,
+ ccr_context_tracking=False,
+ image_optimize=False,
+ **overrides,
+ )
+ proxy = create_app(config).state.proxy
+ assert proxy.cost_tracker is not None
+ assert proxy.cost_tracker.check_budget()[0]
+ return proxy
+
+
+def _spend_past_budget(proxy) -> None:
+ proxy.cost_tracker.record_tokens(
+ model="gpt-4o",
+ tokens_saved=0,
+ tokens_sent=100_000,
+ output_tokens=50_000,
+ )
+
+
+def _fake_websockets_module(connect):
+ mod = MagicMock()
+ mod.connect = connect
+ mod.Subprotocol = str
+ return mod
+
+
+def _response_create_frame(text: str) -> str:
+ return json.dumps({"type": "response.create", "response": {"model": "gpt-4o", "input": text}})
+
+
+def test_websocket_first_frame_blocked_when_budget_exhausted_after_handshake() -> None:
+ """Budget spent between the handshake preflight and the first frame must stop
+ that frame before it reaches the already-connected upstream socket.
+ """
+
+ async def _run() -> None:
+ proxy = _ws_budget_proxy()
+ upstream = _FakeUpstream([])
+
+ async def _fake_connect(*args, **kwargs):
+ _spend_past_budget(proxy)
+ return upstream
+
+ client_ws = _ScriptedClientWS([_response_create_frame("hi")])
+
+ with patch.dict(sys.modules, {"websockets": _fake_websockets_module(_fake_connect)}):
+ await asyncio.wait_for(
+ proxy.handle_openai_responses_ws(client_ws),
+ timeout=3.0,
+ )
+
+ assert upstream.sent == []
+ assert upstream.closed is True
+ assert client_ws.close_code == 1008
+ assert "Budget exceeded for daily period" in (client_ws.close_reason or "")
+
+ asyncio.run(_run())
+
+
+def test_websocket_http_fallback_blocked_when_budget_exhausted() -> None:
+ """When the upstream WebSocket upgrade fails, the HTTP fallback must not
+ dispatch a paid request once the budget is exhausted.
+ """
+
+ async def _run() -> None:
+ proxy = _ws_budget_proxy(retry_max_attempts=1)
+ proxy._ws_http_fallback = AsyncMock(return_value=(0, 0, 0, 0, 0))
+
+ async def _fake_connect(*args, **kwargs):
+ _spend_past_budget(proxy)
+ raise OSError("upstream websocket unavailable")
+
+ client_ws = _ScriptedClientWS([_response_create_frame("hi")])
+
+ with patch.dict(sys.modules, {"websockets": _fake_websockets_module(_fake_connect)}):
+ await asyncio.wait_for(
+ proxy.handle_openai_responses_ws(client_ws),
+ timeout=3.0,
+ )
+
+ proxy._ws_http_fallback.assert_not_awaited()
+ assert client_ws.close_code == 1008
+ assert "Budget exceeded for daily period" in (client_ws.close_reason or "")
+
+ asyncio.run(_run())