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/batch): honor x-headroom-bypass on the batch paths (#2570)

Omar Gerardo9b26a49c14ea
diff --git a/headroom/proxy/handlers/batch.py b/headroom/proxy/handlers/batch.py
index 91c23f640..dd98cb7bf 100644
--- a/headroom/proxy/handlers/batch.py
+++ b/headroom/proxy/handlers/batch.py
@@ -15,7 +15,11 @@ if TYPE_CHECKING:
from fastapi.responses import Response
from headroom.proxy.auth_mode import classify_client
-from headroom.proxy.helpers import COMPRESSION_TIMEOUT_SECONDS, extract_tags
+from headroom.proxy.helpers import (
+ COMPRESSION_TIMEOUT_SECONDS,
+ _headroom_bypass_enabled,
+ extract_tags,
+)
from headroom.proxy.outcome import RequestOutcome
logger = logging.getLogger("headroom.proxy")
@@ -94,6 +98,22 @@ class BatchHandlerMixin:
requests_wrapper = input_config.get("requests", {})
requests_list = requests_wrapper.get("requests", [])
+ # Same bypass contract as the OpenAI batch path below, and it has to sit
+ # above the empty-requests return — a file-input batch carries no inline
+ # `requests`, and that return hands the helper the parsed dict, which
+ # re-serializes canonically. Kept below the extraction so a later
+ # CompressionDecision migration can pass `requests_list` as messages.
+ # Skipping the compression loop also skips the CCR context store, which
+ # is correct: that store only exists to resolve markers left BY
+ # compression, and handle_google_batch_results already passes through on
+ # a missing one.
+ if _headroom_bypass_enabled(request.headers):
+ logger.info(f"[{request_id}] Compression skipped: reason=bypass_header")
+ # Pass body=None so the helper forwards the original wire bytes.
+ # Handing it the parsed dict would re-serialize canonically and log
+ # body_mutated=True, which is the opposite of what bypass promises.
+ return await self._google_batch_passthrough(request, model, None, "bypass_header")
+
if not requests_list:
# No inline requests - might be using file input, pass through
logger.debug(f"[{request_id}] Google batch: No inline requests, passing through")
@@ -116,6 +136,17 @@ class BatchHandlerMixin:
request_id=request_id,
)
+ # Commercial gate — the other half of the conjunction the shared decision
+ # factory applies. Fails open: no reporter configured, or no license info
+ # yet, both mean compress. `is not None` rather than truthiness so this
+ # cannot drift from compression_decision.py:120, which spells it that way.
+ license_ok = (
+ self.usage_reporter.should_compress if self.usage_reporter is not None else True
+ )
+ if not license_ok:
+ logger.info(f"[{request_id}] Compression skipped: reason=license_denied")
+ tags["passthrough_reason"] = "license_denied"
+
# Track compression stats
total_original_tokens = 0
total_optimized_tokens = 0
@@ -129,8 +160,8 @@ class BatchHandlerMixin:
metadata = batch_req.get("metadata", {})
contents = req_content.get("contents", [])
- if not contents or not self.config.optimize:
- # No contents or optimization disabled - pass through unchanged
+ if not contents or not self.config.optimize or not license_ok:
+ # No contents, optimization disabled, or license denied
compressed_requests.append(batch_req)
continue
@@ -377,6 +408,7 @@ class BatchHandlerMixin:
request: Request,
model: str,
body: dict | None = None,
+ passthrough_reason: str | None = None,
) -> Response:
"""Pass through Google batch request without modification."""
from fastapi.responses import Response
@@ -388,6 +420,9 @@ class BatchHandlerMixin:
headers.pop("content-length", None)
client = classify_client(headers)
tags = extract_tags(headers)
+ # Same slice label the non-batch handlers get from apply_to_tags.
+ if passthrough_reason:
+ tags["passthrough_reason"] = passthrough_reason
# PR-A5 (P5-49): strip internal x-headroom-* before forwarding upstream.
from headroom.proxy.helpers import _strip_internal_headers, log_outbound_headers
@@ -466,6 +501,7 @@ class BatchHandlerMixin:
request_id=request_id_files,
provider="google",
model=f"passthrough:batch:{model}",
+ status_code=response.status_code,
original_tokens=0,
optimized_tokens=0,
output_tokens=0,
@@ -858,6 +894,14 @@ class BatchHandlerMixin:
# Pass through for other endpoints
return await self._batch_passthrough(request, body)
+ # The client's explicit "don't touch my bytes" contract. Compressing
+ # would re-serialize every JSONL line and upload a NEW file id, so
+ # skipping compression alone isn't enough — route to the byte-faithful
+ # passthrough before the download/upload pair runs.
+ if _headroom_bypass_enabled(request.headers):
+ logger.info(f"[{request_id}] Compression skipped: reason=bypass_header")
+ return await self._batch_passthrough(request, body, "bypass_header")
+
headers = dict(request.headers.items())
headers.pop("host", None)
headers.pop("content-length", None)
@@ -894,6 +938,8 @@ class BatchHandlerMixin:
# Step 2: Parse and compress each line
logger.info(f"[{request_id}] Batch: Compressing JSONL content")
compressed_lines, stats = await self._compress_batch_jsonl(file_content, request_id)
+ if stats.get("passthrough_reason"):
+ tags["passthrough_reason"] = stats["passthrough_reason"]
if stats["total_requests"] == 0:
return JSONResponse(
@@ -1089,6 +1135,14 @@ class BatchHandlerMixin:
from headroom.tokenizers import get_tokenizer
from headroom.utils import extract_user_query
+ # Same commercial gate as handle_google_batch_create — see there for why
+ # it fails open and why `is not None` matches the decision factory.
+ license_ok = (
+ self.usage_reporter.should_compress if self.usage_reporter is not None else True
+ )
+ if not license_ok:
+ logger.info(f"[{request_id}] Compression skipped: reason=license_denied")
+
lines = content.strip().split("\n")
compressed_lines = []
total_original_tokens = 0
@@ -1126,7 +1180,7 @@ class BatchHandlerMixin:
continue
# Compress messages using the OpenAI pipeline
- if self.config.optimize:
+ if self.config.optimize and license_ok:
try:
context_limit = self.openai_provider.get_context_limit(model)
# Offload off the event loop (#1701); timeouts fall to
@@ -1204,11 +1258,19 @@ class BatchHandlerMixin:
"total_tokens_saved": total_tokens_saved,
"savings_percent": savings_percent,
"errors": errors,
+ # Surfaced so the caller can tag the outcome — the license is read
+ # here, but only the caller holds the tags the funnel sees.
+ "passthrough_reason": None if license_ok else "license_denied",
}
return compressed_lines, stats
- async def _batch_passthrough(self, request: Request, body: dict) -> Response:
+ async def _batch_passthrough(
+ self,
+ request: Request,
+ body: dict,
+ passthrough_reason: str | None = None,
+ ) -> Response:
"""Pass through batch request to OpenAI without compression.
Byte-faithful (PR-A3, fixes P0-2). The original request bytes are
@@ -1224,9 +1286,18 @@ class BatchHandlerMixin:
log_outbound_request,
)
+ start_time = time.time()
+
headers = dict(request.headers.items())
headers.pop("host", None)
headers.pop("content-length", None)
+ client = classify_client(headers)
+ tags = extract_tags(headers)
+ # What CompressionDecision.apply_to_tags stamps everywhere else, so the
+ # dashboard can slice passthrough traffic by cause instead of guessing
+ # why a batch reported zero savings.
+ if passthrough_reason:
+ tags["passthrough_reason"] = passthrough_reason
# PR-A5 (P5-49): strip internal x-headroom-* before forwarding upstream.
_pre_strip_count_obp = sum(1 for k in headers if k.lower().startswith("x-headroom-"))
headers = _strip_internal_headers(headers)
@@ -1266,6 +1337,28 @@ class BatchHandlerMixin:
url, content=outbound_bytes, headers=outbound_headers
)
+ # No compression here, just an upstream forward. Funnel records via
+ # zero defaults so the request still shows up in dashboards, matching
+ # _google_batch_passthrough — otherwise a bypassed batch create
+ # disappears from the funnel entirely.
+ latency_ms = (time.time() - start_time) * 1000
+ await self._record_request_outcome(
+ RequestOutcome(
+ request_id=await self._next_request_id(),
+ provider="openai",
+ model="passthrough:batch",
+ status_code=response.status_code,
+ original_tokens=0,
+ optimized_tokens=0,
+ output_tokens=0,
+ tokens_saved=0,
+ attempted_input_tokens=0,
+ total_latency_ms=latency_ms,
+ tags=tags,
+ client=client,
+ )
+ )
+
response_headers = dict(response.headers)
response_headers.pop("content-encoding", None)
response_headers.pop("content-length", None)
diff --git a/tests/test_proxy_handlers_batch.py b/tests/test_proxy_handlers_batch.py
index 4d1383a09..74d979bd5 100644
--- a/tests/test_proxy_handlers_batch.py
+++ b/tests/test_proxy_handlers_batch.py
@@ -97,6 +97,9 @@ class DummyBatchHandler(batch_module.BatchHandlerMixin, GeminiHandlerMixin):
)
self.openai_provider = SimpleNamespace(get_context_limit=lambda model: 8192)
self.openai_pipeline = SimpleNamespace(apply=lambda **kwargs: None)
+ # Mirror of HeadroomProxy.usage_reporter (server.py), which is always
+ # set, None when no licensing system is configured.
+ self.usage_reporter = None
self._request_counter = 0
self._retry_response = FakeResponse()
@@ -669,6 +672,8 @@ async def test_compress_batch_jsonl_without_optimization_handles_invalid_lines(
"total_tokens_saved": 0,
"savings_percent": 0.0,
"errors": 1,
+ # No reporter configured, so the license half fails open — no reason to tag.
+ "passthrough_reason": None,
}
@@ -1454,6 +1459,7 @@ async def test_handle_google_batch_create_preserves_functioncall_response_order(
optimize=True, ccr_inject_tool=False, ccr_inject_system_instructions=False
)
self.openai_provider = SimpleNamespace(get_context_limit=lambda m: 8192)
+ self.usage_reporter = None
# No-op pipeline: return the messages unchanged, no token inflation.
self.openai_pipeline = SimpleNamespace(
apply=lambda **kw: SimpleNamespace(
@@ -1543,6 +1549,7 @@ async def test_handle_google_batch_create_preserves_sibling_tools(
optimize=True, ccr_inject_tool=False, ccr_inject_system_instructions=False
)
self.openai_provider = SimpleNamespace(get_context_limit=lambda m: 8192)
+ self.usage_reporter = None
self.openai_pipeline = SimpleNamespace(
apply=lambda **kw: SimpleNamespace(
messages=kw["messages"], timing={}, tokens_before=100, tokens_after=100
@@ -1754,3 +1761,592 @@ async def test_compress_batch_jsonl_skips_blank_lines_and_preserves_tools_when_n
assert body["tools"] == [{"name": "orig"}]
assert stats["total_requests"] == 1
assert stats["errors"] == 0
+
+
+# ── x-headroom-bypass: the client's "don't touch my bytes" contract ──────
+# batch.py was never migrated onto CompressionDecision (see that module's
+# docstring: the same omission on the Gemini paths was "a real bug"), so
+# these lock the contract in on both batch surfaces.
+
+
+ "bypass_headers",
+ [
+ {"x-headroom-bypass": "true"},
+ {"x-headroom-mode": "passthrough"},
+ ],
+)
+async def test_handle_batch_create_bypass_skips_compression_entirely(
+ monkeypatch: pytest.MonkeyPatch,
+ bypass_headers: dict[str, str],
+) -> None:
+ """Bypass must reach the byte-faithful passthrough without rewriting the file.
+
+ Compressing would re-serialize every JSONL line and upload a NEW file id,
+ so "skip compression" is not enough — the download/upload pair must not run.
+ """
+ handler = DummyBatchHandler()
+ handler.config.optimize = True
+
+ async def request_payload(request): # noqa: ANN001
+ return {"input_file_id": "file-1", "endpoint": "/v1/chat/completions"}
+
+ monkeypatch.setattr("headroom.proxy.helpers._read_request_json", request_payload)
+
+ called: list[str] = []
+
+ async def fail_download(file_id, headers): # noqa: ANN001
+ called.append("download")
+ return "downloaded"
+
+ async def fail_upload(content, filename, headers): # noqa: ANN001
+ called.append("upload")
+ return "file-2"
+
+ # Records rather than raising. handle_batch_create wraps its whole body in
+ # `except Exception`, which swallows an AssertionError and books a 500 — so
+ # that message never reached anyone, and `called` below is the real guard.
+ # The zero-request stats short-circuit the reverted path at the
+ # total_requests==0 check, before it can reach the upload.
+ async def fail_compress(content, request_id): # noqa: ANN001
+ called.append("compress")
+ return [], {"total_requests": 0}
+
+ monkeypatch.setattr(handler, "_download_openai_file", fail_download)
+ monkeypatch.setattr(handler, "_upload_openai_file", fail_upload)
+ monkeypatch.setattr(handler, "_compress_batch_jsonl", fail_compress)
+
+ passthrough_response = SimpleNamespace(marker="passthrough")
+
+ # Accepts the reason but does not assert on it: handle_batch_create wraps its
+ # body in `except Exception`, so a raise here would be swallowed. The
+ # dedicated *_tags_the_outcome_with_its_reason tests cover the value.
+ async def fake_passthrough(request, body, passthrough_reason=None): # noqa: ANN001
+ called.append("passthrough")
+ return passthrough_response
+
+ monkeypatch.setattr(handler, "_batch_passthrough", fake_passthrough)
+
+ response = await handler.handle_batch_create(FakeRequest("{}", headers=bypass_headers))
+
+ assert response is passthrough_response
+ assert called == ["passthrough"]
+
+
+async def test_handle_google_batch_create_bypass_skips_compression(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """Same contract on the Google inline-batch path (batch.py's other gate)."""
+ handler = DummyBatchHandler()
+ handler.config.optimize = True
+ install_batch_support_modules(monkeypatch)
+
+ async def request_payload(request): # noqa: ANN001
+ return {
+ "batch": {
+ "input_config": {
+ "requests": {
+ "requests": [
+ {
+ "request": {"contents": [{"parts": [{"text": "hello"}]}]},
+ "metadata": {"key": "request-1"},
+ }
+ ]
+ }
+ }
+ }
+ }
+
+ monkeypatch.setattr("headroom.proxy.helpers._read_request_json", request_payload)
+
+ # Count invocations rather than raising: the Google compression loop
+ # swallows exceptions per request, so a raise here would be masked.
+ applied: list[dict] = []
+
+ def apply(**kwargs): # noqa: ANN003
+ applied.append(kwargs)
+ return SimpleNamespace(
+ messages=[{"role": "user", "content": "hi"}],
+ tokens_before=50,
+ tokens_after=10,
+ timing={},
+ )
+
+ handler.openai_pipeline = SimpleNamespace(apply=apply)
+
+ passthrough_response = SimpleNamespace(marker="google-passthrough")
+ called: list[str] = []
+
+ async def fake_passthrough(request, model, body=None, passthrough_reason=None): # noqa: ANN001
+ called.append("passthrough")
+ return passthrough_response
+
+ monkeypatch.setattr(handler, "_google_batch_passthrough", fake_passthrough)
+
+ response = await handler.handle_google_batch_create(
+ FakeRequest("{}", headers={"x-headroom-bypass": "true"}),
+ "gemini-2.0-flash",
+ )
+
+ assert response is passthrough_response
+ assert called == ["passthrough"]
+ assert applied == []
+
+
+async def test_handle_batch_create_without_bypass_still_compresses(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """The bypass guard must not misfire on an ordinary request.
+
+ Gating the handler on ``CompressionDecision.decide(messages=None)`` looks
+ right and is wrong: ``None`` hits the ``no_messages`` precedence step and
+ returns ``should_compress=False``, sending every batch to passthrough.
+ This test turns red on that shortcut.
+
+ Scope: the handler-level guard only. ``_compress_batch_jsonl`` is stubbed
+ here, so the same mistake made *inside* that method would sail past this
+ test. ``test_compress_batch_jsonl_*`` cover the per-line gates.
+ """
+ handler = DummyBatchHandler()
+ handler.config.optimize = True
+
+ async def request_payload(request): # noqa: ANN001
+ return {"input_file_id": "file-1", "endpoint": "/v1/chat/completions"}
+
+ monkeypatch.setattr("headroom.proxy.helpers._read_request_json", request_payload)
+
+ async def fake_download(file_id, headers): # noqa: ANN001
+ return "downloaded"
+
+ compressed_calls: list[str] = []
+
+ async def fake_compress(content, request_id): # noqa: ANN001
+ compressed_calls.append(content)
+ return ['{"body":{}}'], {
+ "total_requests": 1,
+ "total_original_tokens": 20,
+ "total_compressed_tokens": 10,
+ "total_tokens_saved": 10,
+ "savings_percent": 50.0,
+ "errors": 0,
+ }
+
+ async def fake_upload(content, filename, headers): # noqa: ANN001
+ return "file-compressed"
+
+ monkeypatch.setattr(handler, "_download_openai_file", fake_download)
+ monkeypatch.setattr(handler, "_compress_batch_jsonl", fake_compress)
+ monkeypatch.setattr(handler, "_upload_openai_file", fake_upload)
+
+ handler.http_client.post_response = FakeResponse(content=b'{"id":"batch_123","object":"batch"}')
+
+ response = await handler.handle_batch_create(
+ FakeRequest("{}", headers={"authorization": "Bearer test"})
+ )
+
+ assert response.status_code == 200
+ assert compressed_calls == ["downloaded"]
+ assert dict(response.headers)["x-headroom-tokens-saved"] == "10"
+
+
+async def test_compress_batch_jsonl_skips_when_license_denied(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """License denial gates compression, the other half of the conjunction.
+
+ Unlike bypass this is not a byte-fidelity contract, so it gates the
+ pipeline in place rather than rerouting to the passthrough forwarder.
+ """
+ handler = DummyBatchHandler()
+ handler.config.optimize = True
+ handler.usage_reporter = SimpleNamespace(should_compress=False)
+ install_batch_support_modules(monkeypatch, tokenizer_count=7)
+
+ # Count invocations rather than raising: _compress_batch_jsonl wraps the
+ # pipeline call in `except Exception`, which would swallow an AssertionError
+ # and let this pass via the fallback path even with the gate removed.
+ applied: list[dict] = []
+
+ def apply(**kwargs): # noqa: ANN003
+ applied.append(kwargs)
+ return SimpleNamespace(
+ messages=[{"role": "user", "content": "hi"}],
+ tokens_before=50,
+ tokens_after=10,
+ )
+
+ handler.openai_pipeline = SimpleNamespace(apply=apply)
+
+ line = json.dumps(
+ {"body": {"model": "gpt-4o", "messages": [{"role": "user", "content": "hello"}]}}
+ )
+ lines, stats = await handler._compress_batch_jsonl(line, "req-license")
+
+ assert applied == []
+ assert stats["total_requests"] == 1
+ assert stats["total_tokens_saved"] == 0
+ assert json.loads(lines[0])["body"]["messages"] == [{"role": "user", "content": "hello"}]
+
+
+async def test_compress_batch_jsonl_compresses_when_no_usage_reporter(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """Fails open: no reporter configured means compress, not passthrough."""
+ handler = DummyBatchHandler()
+ handler.config.optimize = True
+ install_batch_support_modules(monkeypatch)
+
+ applied: list[dict] = []
+
+ def apply(**kwargs): # noqa: ANN003
+ applied.append(kwargs)
+ return SimpleNamespace(
+ messages=[{"role": "user", "content": "hi"}],
+ tokens_before=50,
+ tokens_after=10,
+ )
+
+ handler.openai_pipeline = SimpleNamespace(apply=apply)
+
+ assert handler.usage_reporter is None
+
+ line = json.dumps(
+ {"body": {"model": "gpt-4o", "messages": [{"role": "user", "content": "hello"}]}}
+ )
+ _lines, stats = await handler._compress_batch_jsonl(line, "req-nolicense")
+
+ assert len(applied) == 1
+ assert stats["total_tokens_saved"] == 40
+
+
+async def test_batch_passthrough_records_request_outcome(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """A bypassed batch create must still reach the funnel.
+
+ Routing bypass to the passthrough forwarder would otherwise drop the
+ request from dashboards entirely — the compressed path records at the
+ end of handle_batch_create, and _google_batch_passthrough records too.
+ """
+ handler = DummyBatchHandler()
+ handler.config.optimize = True
+
+ async def request_payload(request): # noqa: ANN001
+ return {"input_file_id": "file-1", "endpoint": "/v1/chat/completions"}
+
+ monkeypatch.setattr("headroom.proxy.helpers._read_request_json", request_payload)
+
+ response = await handler.handle_batch_create(
+ FakeRequest("{}", headers={"x-headroom-bypass": "true", "x-headroom-client": "test"})
+ )
+
+ assert response.status_code == 200
+ assert len(handler.metrics.record_calls) == 1
+ recorded = handler.metrics.record_calls[0]
+ assert recorded["provider"] == "openai"
+ assert recorded["tokens_saved"] == 0
+
+
+async def test_google_batch_bypass_forwards_original_bytes(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """Bypass on the Google path must forward the wire bytes untouched.
+
+ The sibling bypass test stubs _google_batch_passthrough, so it proves
+ routing but not the contract. This one lets the real helper run: handing
+ it the parsed dict re-serializes canonically (dropping the client's
+ whitespace) and logs body_mutated=True, which is what bypass forbids.
+ """
+ handler = DummyBatchHandler()
+ handler.config.optimize = True
+ handler.http_client.post_response = FakeResponse(content=b"ok")
+
+ raw = (
+ '{"batch": {"input_config": {"requests": {"requests": '
+ '[{"request": {"contents": [{"parts": [{"text": "hi"}]}]}, '
+ '"metadata": {"key": "r1"}}]}}}, "spaced": true}'
+ )
+
+ async def request_payload(request): # noqa: ANN001
+ return json.loads(raw)
+
+ monkeypatch.setattr("headroom.proxy.helpers._read_request_json", request_payload)
+
+ await handler.handle_google_batch_create(
+ FakeRequest(raw, headers={"x-headroom-bypass": "true"}),
+ "gemini-2.0-flash",
+ )
+
+ assert handler.http_client.posts[-1]["content"] == raw.encode("utf-8")
+
+
+async def test_batch_passthrough_records_upstream_failure_as_failed(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """A 5xx on a bypassed batch create must not land in the success funnel.
+
+ RequestOutcome.status_code defaults to 200, and emit_request_outcome only
+ diverts to record_failed at >= 500, so omitting it books a failed upstream
+ call as a success and inflates the save-rate.
+ """
+ handler = DummyBatchHandler()
+ handler.config.optimize = True
+ handler.http_client.post_response = FakeResponse(status_code=503, content=b'{"error":"busy"}')
+
+ async def request_payload(request): # noqa: ANN001
+ return {"input_file_id": "file-1", "endpoint": "/v1/chat/completions"}
+
+ monkeypatch.setattr("headroom.proxy.helpers._read_request_json", request_payload)
+
+ response = await handler.handle_batch_create(
+ FakeRequest("{}", headers={"x-headroom-bypass": "true"})
+ )
+
+ assert response.status_code == 503
+ assert handler.metrics.record_calls == []
+ assert len(handler.metrics.failed_calls) == 1
+ assert handler.metrics.failed_calls[0]["provider"] == "openai"
+
+
+async def test_google_batch_passthrough_records_upstream_failure_as_failed(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """Same 5xx contract as the OpenAI passthrough, on the Google path.
+
+ The bypass guard routes traffic into this helper, so an omitted
+ status_code books a failed Gemini call as a served request.
+ """
+ handler = DummyBatchHandler()
+ handler.config.optimize = True
+ handler.http_client.post_response = FakeResponse(status_code=503, content=b'{"error":"busy"}')
+
+ raw = (
+ '{"batch": {"input_config": {"requests": {"requests": '
+ '[{"request": {"contents": [{"parts": [{"text": "hi"}]}]}, '
+ '"metadata": {"key": "r1"}}]}}}}'
+ )
+
+ async def request_payload(request): # noqa: ANN001
+ return json.loads(raw)
+
+ monkeypatch.setattr("headroom.proxy.helpers._read_request_json", request_payload)
+
+ response = await handler.handle_google_batch_create(
+ FakeRequest(raw, headers={"x-headroom-bypass": "true"}),
+ "gemini-2.0-flash",
+ )
+
+ assert response.status_code == 503
+ assert handler.metrics.record_calls == []
+ assert len(handler.metrics.failed_calls) == 1
+ assert handler.metrics.failed_calls[0]["provider"] == "google"
+
+
+async def test_google_batch_create_skips_compression_when_license_denied(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """The license gate's third disjunct at the Google per-item guard.
+
+ Arc coverage marks that line hit via the other two disjuncts, so
+ without this the `not license_ok` branch never actually decides.
+ """
+ handler = DummyBatchHandler()
+ handler.config.optimize = True
+ handler.usage_reporter = SimpleNamespace(should_compress=False)
+ install_batch_support_modules(monkeypatch)
+
+ applied: list[dict] = []
+
+ def apply(**kwargs): # noqa: ANN003
+ applied.append(kwargs)
+ return SimpleNamespace(
+ messages=[{"role": "user", "content": "hi"}],
+ tokens_before=50,
+ tokens_after=10,
+ timing={},
+ )
+
+ handler.openai_pipeline = SimpleNamespace(apply=apply)
+ handler.http_client.post_response = FakeResponse(content=b'{"name":"batches/b1"}')
+
+ raw = (
+ '{"batch": {"input_config": {"requests": {"requests": '
+ '[{"request": {"contents": [{"parts": [{"text": "hello"}]}]}, '
+ '"metadata": {"key": "r1"}}]}}}}'
+ )
+
+ async def request_payload(request): # noqa: ANN001
+ return json.loads(raw)
+
+ monkeypatch.setattr("headroom.proxy.helpers._read_request_json", request_payload)
+
+ await handler.handle_google_batch_create(FakeRequest(raw), "gemini-2.0-flash")
+
+ assert applied == []
+ assert handler.metrics.record_calls[-1]["tokens_saved"] == 0
+
+
+async def test_google_batch_bypass_beats_the_empty_requests_return(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """Bypass must be checked above the empty-`requests` early return.
+
+ A file-input batch carries no inline `requests`, so it takes that return —
+ which hands `_google_batch_passthrough` the parsed dict and re-serializes
+ canonically, dropping the client's whitespace. Below the return, bypass
+ silently mutated exactly the bodies it promised not to touch.
+ """
+ handler = DummyBatchHandler()
+ handler.config.optimize = True
+ handler.http_client.post_response = FakeResponse(content=b"ok")
+
+ # No inline requests (file input), and deliberately non-canonical spacing:
+ # a canonical re-serialize collapses it, so the byte compare catches it.
+ raw = '{"batch": {"input_config": {"file_name": "files/abc"}}, "spaced": true}'
+
+ async def request_payload(request): # noqa: ANN001
+ return json.loads(raw)
+
+ monkeypatch.setattr("headroom.proxy.helpers._read_request_json", request_payload)
+
+ await handler.handle_google_batch_create(
+ FakeRequest(raw, headers={"x-headroom-bypass": "true"}),
+ "gemini-2.0-flash",
+ )
+
+ assert handler.http_client.posts[-1]["content"] == raw.encode("utf-8")
+
+
+# ── passthrough_reason: the slice label apply_to_tags gives every other handler ──
+# batch.py calls apply_to_tags zero times (the non-batch handlers call it at nine
+# sites), so a bypassed or license-denied batch reached the funnel indistinguishable
+# from an ordinary zero-savings one. Tags only reach RequestLog, not record_request,
+# so these assert through a logger double.
+
+
+def _tag_recorder(handler: DummyBatchHandler) -> list[dict]:
+ """Attach a logger double and return the list its RequestLog tags land in."""
+ seen: list[dict] = []
+ handler.logger = SimpleNamespace(log=lambda entry: seen.append(dict(entry.tags)))
+ return seen
+
+
+async def test_batch_bypass_tags_the_outcome_with_its_reason(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """A bypassed OpenAI batch must be sliceable as bypass_header, not just zero-savings."""
+ handler = DummyBatchHandler()
+ handler.config.optimize = True
+ tags_seen = _tag_recorder(handler)
+
+ async def request_payload(request): # noqa: ANN001
+ return {"input_file_id": "file-1", "endpoint": "/v1/chat/completions"}
+
+ monkeypatch.setattr("headroom.proxy.helpers._read_request_json", request_payload)
+
+ await handler.handle_batch_create(FakeRequest("{}", headers={"x-headroom-bypass": "true"}))
+
+ assert tags_seen[-1]["passthrough_reason"] == "bypass_header"
+
+
+async def test_google_batch_bypass_tags_the_outcome_with_its_reason(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """Same slice label on the Google bypass path."""
+ handler = DummyBatchHandler()
+ handler.config.optimize = True
+ handler.http_client.post_response = FakeResponse(content=b"ok")
+ tags_seen = _tag_recorder(handler)
+
+ raw = (
+ '{"batch": {"input_config": {"requests": {"requests": '
+ '[{"request": {"contents": [{"parts": [{"text": "hi"}]}]}, '
+ '"metadata": {"key": "r1"}}]}}}}'
+ )
+
+ async def request_payload(request): # noqa: ANN001
+ return json.loads(raw)
+
+ monkeypatch.setattr("headroom.proxy.helpers._read_request_json", request_payload)
+
+ await handler.handle_google_batch_create(
+ FakeRequest(raw, headers={"x-headroom-bypass": "true"}),
+ "gemini-2.0-flash",
+ )
+
+ assert tags_seen[-1]["passthrough_reason"] == "bypass_header"
+
+
+async def test_google_batch_license_denied_tags_the_outcome(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """License denial is the other cause this PR introduced — tag it too."""
+ handler = DummyBatchHandler()
+ handler.config.optimize = True
+ handler.usage_reporter = SimpleNamespace(should_compress=False)
+ handler.http_client.post_response = FakeResponse(content=b'{"name":"batches/b1"}')
+ install_batch_support_modules(monkeypatch)
+ tags_seen = _tag_recorder(handler)
+
+ raw = (
+ '{"batch": {"input_config": {"requests": {"requests": '
+ '[{"request": {"contents": [{"parts": [{"text": "hello"}]}]}, '
+ '"metadata": {"key": "r1"}}]}}}}'
+ )
+
+ async def request_payload(request): # noqa: ANN001
+ return json.loads(raw)
+
+ monkeypatch.setattr("headroom.proxy.helpers._read_request_json", request_payload)
+
+ await handler.handle_google_batch_create(FakeRequest(raw), "gemini-2.0-flash")
+
+ assert tags_seen[-1]["passthrough_reason"] == "license_denied"
+
+
+async def test_batch_license_denied_tags_the_outcome(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """The OpenAI license gate lives inside _compress_batch_jsonl, which holds no
+ tags — so the reason rides back on its stats dict. Runs the real method rather
+ than stubbing it, or the assertion would only be testing the stub."""
+ handler = DummyBatchHandler()
+ handler.config.optimize = True
+ handler.usage_reporter = SimpleNamespace(should_compress=False)
+ handler.http_client.post_response = FakeResponse(content=b'{"id":"batch_123","object":"batch"}')
+ install_batch_support_modules(monkeypatch, tokenizer_count=7)
+ tags_seen = _tag_recorder(handler)
+
+ async def request_payload(request): # noqa: ANN001
+ return {"input_file_id": "file-1", "endpoint": "/v1/chat/completions"}
+
+ async def fake_download(file_id, headers): # noqa: ANN001
+ return json.dumps(
+ {"body": {"model": "gpt-4o", "messages": [{"role": "user", "content": "hello"}]}}
+ )
+
+ async def fake_upload(content, filename, headers): # noqa: ANN001
+ return "file-2"
+
+ monkeypatch.setattr("headroom.proxy.helpers._read_request_json", request_payload)
+ monkeypatch.setattr(handler, "_download_openai_file", fake_download)
+ monkeypatch.setattr(handler, "_upload_openai_file", fake_upload)
+
+ await handler.handle_batch_create(FakeRequest("{}", headers={"authorization": "Bearer t"}))
+
+ assert tags_seen[-1]["passthrough_reason"] == "license_denied"