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.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
fix(telemetry): label custom-base chat upstreams from a fixed provider set (#3759)
donjorf0ec2bb37697
diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.pyindex 525dc7dd1..06fc8150b 100644--- a/headroom/proxy/handlers/openai.py+++ b/headroom/proxy/handlers/openai.py@@ -93,10 +93,10 @@ from headroom.proxy.handlers._debug_dump import _debug_dump_mode, _redact_debug_from headroom.proxy.image_isolation import run_image_compression_isolatedfrom headroom.proxy.outcome import RequestOutcomefrom headroom.proxy.output_shaper import shaper_enabled_for, steering_allowed_for+from headroom.proxy.passthrough import CUSTOM_BASE_PROVIDER, is_opencode_zen_basefrom headroom.proxy.passthrough import (custom_base_passthrough_telemetry as _custom_base_passthrough_telemetry,)-from headroom.proxy.passthrough import is_opencode_zen_basefrom headroom.proxy.project_context import (classify_project,get_current_project,@@ -3642,7 +3642,12 @@ class OpenAIHandlerMixin:handler_path,custom_upstream_base_url or "",)- openai_chat_outcome_provider = custom_chat_provider or "openai"+ # Fixed taxonomy from the shared helper (zen, zai, meta, openai); any+ # other custom base is the shared "custom" bucket. Never derive the+ # label from the request-controlled hostname — see the review on #3759.+ openai_chat_outcome_provider = custom_chat_provider or (+ CUSTOM_BASE_PROVIDER if upstream_base_url else "openai"+ )# Memory: Get user ID when memory is enabled. Reads `request.headers`# directly because `headers` was stripped of `x-headroom-*` for thediff --git a/headroom/proxy/passthrough.py b/headroom/proxy/passthrough.pyindex 13019de1f..49a4fff70 100644--- a/headroom/proxy/passthrough.py+++ b/headroom/proxy/passthrough.py@@ -6,6 +6,19 @@ from urllib.parse import urlparseOPENCODE_ZEN_HOSTS = {"opencode.ai", "www.opencode.ai"}+# Chat upstreams we can name, keyed by exact host. Bounded by design: the+# request-controlled ``x-headroom-base-url`` must never become a telemetry+# label, or a client sending a fresh hostname per request grows the+# per-provider stores and exported series without limit (review on #3759).+CUSTOM_BASE_CHAT_PROVIDERS = {+ "api.openai.com": "openai",+ "api.z.ai": "zai",+ "api.meta.ai": "meta",+}++# Fixed label for chat traffic on any other custom base.+CUSTOM_BASE_PROVIDER = "custom"+def is_opencode_zen_base(base_url: str | None) -> bool:"""Return True when ``base_url`` targets the OpenCode Zen gateway.@@ -35,9 +48,19 @@ def custom_base_passthrough_telemetry(method: str, path: str, base_url: str) ->host = (urlparse(base_url.strip()).hostname or "").lower()except ValueError:return "", ""- if host not in OPENCODE_ZEN_HOSTS:- return "", ""normalized_path = path[1:] if path.startswith("/") else path- if normalized_path == "zen/v1/chat/completions":- return "chat/completions", "zen"+ if host in OPENCODE_ZEN_HOSTS:+ if normalized_path == "zen/v1/chat/completions":+ return "chat/completions", "zen"+ return "", ""+ # Known OpenAI-compatible chat hosts get a fixed name; chat-completions+ # traffic on any other custom base is the shared "custom" bucket and+ # everything else stays unnamed so tool traffic is not LLM telemetry.+ # Match whole path segments so ``/v1/notchat/completions`` stays unnamed.+ provider = CUSTOM_BASE_CHAT_PROVIDERS.get(host)+ is_chat_path = normalized_path == "chat/completions" or normalized_path.endswith(+ "/chat/completions"+ )+ if provider is not None and is_chat_path:+ return "chat/completions", providerreturn "", ""diff --git a/tests/test_proxy_openai_cache_stability.py b/tests/test_proxy_openai_cache_stability.pyindex fcf276c19..3985c9247 100644--- a/tests/test_proxy_openai_cache_stability.py+++ b/tests/test_proxy_openai_cache_stability.py@@ -4,6 +4,8 @@ from __future__ import annotationsimport copyimport json+import pathlib+import refrom types import SimpleNamespacefrom unittest.mock import AsyncMock, MagicMock, patch@@ -13,9 +15,13 @@ import pytestpytest.importorskip("fastapi")from fastapi.testclient import TestClient+from opentelemetry.sdk.metrics import MeterProvider+from opentelemetry.sdk.metrics.export import InMemoryMetricReaderfrom headroom.backends.base import BackendResponse+from headroom.observability import HeadroomOtelMetrics, reset_otel_metrics, set_otel_metricsfrom headroom.proxy.server import ProxyConfig, create_app+from tests.test_observability_metrics import _collect_metricsclass _FakePrefixTracker:@@ -1177,3 +1183,221 @@ def test_openai_cache_mode_forwards_last_turns_bytes_unchanged(stream: bool) ->assert sent[0][2]["content"] == "[compressed call_1]"assert sent[1][: len(sent[0])] == sent[0]assert sent[2][: len(sent[1])] == sent[1]+++def test_openai_chat_custom_base_reports_zai_as_outcome_provider(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """An OpenAI-compatible ``x-headroom-base-url`` upstream is not ``openai``."""+ # Allowlist the host so the SSRF guard does not need live DNS.+ monkeypatch.setenv("HEADROOM_ALLOWED_BASE_URLS", "api.z.ai")+ captured = {}+ with _make_proxy_client() as client:+ proxy = client.app.state.proxy++ async def _fake_stream_response(*args, **kwargs): # noqa: ANN002, ANN003+ captured.update(kwargs)+ return httpx.Response(200, text="data: [DONE]\n\n")++ proxy._stream_response = _fake_stream_response+ client.post(+ "/v1/chat/completions",+ headers={+ "authorization": "Bearer test-key",+ "x-headroom-base-url": "https://api.z.ai/api/coding/paas/v4",+ },+ json={+ "model": "glm-5",+ "stream": True,+ "messages": [{"role": "user", "content": "hi"}],+ },+ )++ assert captured.get("outcome_provider") == "zai"+++def test_openai_chat_outcome_provider_uses_the_fixed_taxonomy(+ monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path+) -> None:+ """Buffered chat labels each custom base from the fixed set, never the host."""+ # Keep the SSRF guard out of the way: these hosts are deliberately+ # unresolvable, and a DNS miss makes the handler ignore the override.+ monkeypatch.setattr("headroom.proxy.handlers.openai.is_safe_upstream_url", lambda url: True)+ # Keep the lifetime savings store out of the user's real on-disk state.+ monkeypatch.setenv("HEADROOM_SAVINGS_PATH", str(tmp_path / "savings.json"))+ with _make_proxy_client() as client:+ proxy = client.app.state.proxy++ async def _fake_retry(method, url, headers, body, stream=False, **kwargs): # noqa: ANN001, ANN002, ANN003+ return httpx.Response(+ 200,+ json={+ "id": "chatcmpl_1",+ "choices": [+ {+ "index": 0,+ "message": {"role": "assistant", "content": "ok"},+ "finish_reason": "stop",+ }+ ],+ "usage": {"prompt_tokens": 10, "completion_tokens": 1, "total_tokens": 11},+ },+ )++ proxy._retry_request = _fake_retry++ def _chat(base: str | None) -> None:+ headers = {"authorization": "Bearer test-key"}+ if base is not None:+ headers["x-headroom-base-url"] = base+ response = client.post(+ "/v1/chat/completions",+ headers=headers,+ json={"model": "glm-5", "messages": [{"role": "user", "content": "hi"}]},+ )+ assert response.status_code == 200++ _chat("https://api.meta.ai/v1")+ _chat("https://api.meta.ai/v1/sub")+ _chat("https://llm.example.internal/v1")+ # No header: the plain OpenAI path keeps its own label (control).+ _chat(None)++ by_provider = proxy.metrics.requests_by_provider+ assert by_provider["meta"] == 2+ assert by_provider["custom"] == 1+ assert by_provider["openai"] == 1+++def test_openai_chat_custom_base_flood_cannot_grow_the_provider_set(+ monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path+) -> None:+ """Regression for the #3759 review: a host flood stays inside the fixed set.++ The old code derived the outcome provider from the request-controlled+ ``x-headroom-base-url`` hostname, so one fresh hostname per request grew+ the provider stores and exported series without bound. 980 distinct flood+ hosts plus 20 z.ai requests cover success, upstream failure, local 429 and+ upstream 429, and every sink must count exactly ``zai`` and ``custom``.+ """+ fixed_providers = {"openai", "zen", "zai", "meta", "custom"}+ zai_base = "https://api.z.ai/api/coding/paas/v4"+ limited_auth = "Bearer rate-limited"+ # The flood hosts are unresolvable on purpose; without this stub the SSRF+ # guard would drop the override and relabel the flood as "openai".+ monkeypatch.setattr("headroom.proxy.handlers.openai.is_safe_upstream_url", lambda url: True)+ # Isolated sinks: a fresh lifetime store and workspace, so the exact+ # counts below are this test's traffic and nothing reaches ~/.headroom.+ monkeypatch.setenv("HEADROOM_SAVINGS_PATH", str(tmp_path / "savings.json"))+ monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path / "workspace"))+ reader = InMemoryMetricReader()+ set_otel_metrics(HeadroomOtelMetrics(meter_provider=MeterProvider(metric_readers=[reader])))++ class _LimitOneKey:+ """Headroom's own limiter, refusing only ``limited_auth``."""++ async def check_request(self, key: str = "default") -> tuple[bool, float]:+ return key != limited_auth, 1.0++ async def check_tokens(self, key: str, tokens: int) -> tuple[bool, float]:+ return True, 0.0++ async def _fake_retry(method, url, headers, body, stream=False, **kwargs): # noqa: ANN001, ANN002, ANN003+ if "flood-down-" in url:+ raise httpx.ConnectError("flood host down")+ if "flood-upstream429-" in url:+ return httpx.Response(429, json={"error": {"message": "slow down"}})+ return httpx.Response(+ 200,+ json={+ "id": "chatcmpl_flood",+ "choices": [+ {+ "index": 0,+ "message": {"role": "assistant", "content": "ok"},+ "finish_reason": "stop",+ }+ ],+ "usage": {"prompt_tokens": 5, "completion_tokens": 1, "total_tokens": 6},+ },+ )++ expected_status = {"ok": 200, "down": 502, "limited": 429, "upstream429": 429}+ sent: dict[tuple[str, str], int] = {}+ flood_hosts: set[str] = set()+ try:+ with _make_proxy_client() as client:+ proxy = client.app.state.proxy+ proxy._retry_request = _fake_retry+ proxy.rate_limiter = _LimitOneKey()++ for i in range(1000):+ if i % 50 == 0:+ provider, kind = "zai", ("ok" if i % 100 == 0 else "limited")+ base = zai_base+ else:+ provider, kind = "custom", ("limited", "upstream429", "down", "ok")[i % 4]+ host = f"flood-{kind}-{i}.example.invalid"+ flood_hosts.add(host)+ base = f"https://{host}/v1"+ sent[provider, kind] = sent.get((provider, kind), 0) + 1+ auth = limited_auth if kind == "limited" else "Bearer test-key"+ response = client.post(+ "/v1/chat/completions",+ headers={"authorization": auth, "x-headroom-base-url": base},+ json={"model": "glm-5", "messages": [{"role": "user", "content": f"turn {i}"}]},+ )+ assert response.status_code == expected_status[kind], (i, base)++ # The traffic this test sends, pinned so the claim stays exact.+ assert len(flood_hosts) == 980+ assert sent == {+ ("zai", "ok"): 10,+ ("zai", "limited"): 10,+ ("custom", "ok"): 250,+ ("custom", "down"): 240,+ ("custom", "limited"): 240,+ ("custom", "upstream429"): 250,+ }++ metrics = proxy.metrics+ # In-memory stores: exact counts; "unknown" is the seeded zero bucket.+ assert dict(metrics.requests_by_provider) == {"zai": 10, "custom": 250}+ assert dict(metrics.requests_failed_by_provider) == {"unknown": 0, "custom": 240}+ assert metrics.requests_rate_limited_by_source == {"headroom": 250, "upstream": 250}++ # Lifetime store, isolated under tmp_path.+ lifetime = metrics.savings_tracker.lifetime_response()["requests"]+ assert lifetime["by_provider"] == {"zai": 10, "custom": 250}+ assert lifetime["failed_by_provider"] == {"custom": 240}+ assert lifetime["rate_limited_by_source"] == {"headroom": 250, "upstream": 250}++ # Prometheus export: every provider series is from the fixed set.+ export = client.get("/metrics").text+ assert set(re.findall(r'provider="([^"]+)"', export)) <= fixed_providers | {"unknown"}+ assert 'headroom_requests_by_provider{provider="zai"} 10' in export+ assert 'headroom_requests_by_provider{provider="custom"} 250' in export++ # OTel: every proxy data point carries a fixed provider attribute, and+ # z.ai stays its own series on the success and local-429 paths.+ otel = _collect_metrics(reader)+ otel_points: dict[tuple[str, str, str], float] = {}+ for name, metric in otel.items():+ if not name.startswith("headroom.proxy."):+ continue+ for point in metric.data.data_points:+ label = point.attributes.get("provider")+ assert label in fixed_providers, (name, label)+ if name.startswith("headroom.proxy.requests"):+ key = (name, label, point.attributes.get("source", ""))+ otel_points[key] = otel_points.get(key, 0) + point.value+ assert otel_points == {+ ("headroom.proxy.requests", "zai", ""): 10,+ ("headroom.proxy.requests", "custom", ""): 250,+ ("headroom.proxy.requests.failed", "custom", ""): 240,+ ("headroom.proxy.requests.rate_limited", "zai", "headroom"): 10,+ ("headroom.proxy.requests.rate_limited", "custom", "headroom"): 240,+ ("headroom.proxy.requests.rate_limited", "custom", "upstream"): 250,+ }+ finally:+ reset_otel_metrics()diff --git a/tests/test_proxy_passthrough.py b/tests/test_proxy_passthrough.pyindex 63fa8e53c..08111e1ce 100644--- a/tests/test_proxy_passthrough.py+++ b/tests/test_proxy_passthrough.py@@ -49,3 +49,72 @@ def test_is_opencode_zen_base_rejects_other_or_missing_bases() -> None:assert not is_opencode_zen_base("https://custom.example")assert not is_opencode_zen_base("https://opencode.ai.evil.example")assert not is_opencode_zen_base("://bad-url")+++def test_custom_base_passthrough_telemetry_names_known_chat_hosts() -> None:+ # Exact hosts only, fixed labels: the taxonomy, not the request, decides.+ assert custom_base_passthrough_telemetry(+ "POST",+ "/v1/chat/completions",+ "https://api.z.ai/api/coding/paas/v4",+ ) == ("chat/completions", "zai")+ assert custom_base_passthrough_telemetry(+ "POST",+ "v1/chat/completions",+ "https://api.meta.ai/v1",+ ) == ("chat/completions", "meta")+ assert custom_base_passthrough_telemetry(+ "POST",+ "/v1/chat/completions",+ "https://api.openai.com/v1",+ ) == ("chat/completions", "openai")+ # Host parsing is case-insensitive; the label stays fixed.+ assert custom_base_passthrough_telemetry(+ "POST",+ "/v1/chat/completions",+ "https://API.Z.AI/api/coding/paas/v4",+ ) == ("chat/completions", "zai")+++def test_custom_base_passthrough_telemetry_keeps_everything_else_unnamed() -> None:+ # Lookalike hosts never match: an exact-host set cannot be talked into+ # naming an attacker-controlled upstream.+ assert custom_base_passthrough_telemetry(+ "POST",+ "/v1/chat/completions",+ "https://api.z.ai.evil.test/v1",+ ) == ("", "")+ # Unknown hosts, non-chat paths, non-POST methods, and bad URLs all stay+ # unnamed so nothing request-controlled becomes a telemetry label.+ assert custom_base_passthrough_telemetry(+ "POST",+ "/v1/chat/completions",+ "https://llm.example.internal/v1",+ ) == ("", "")+ assert custom_base_passthrough_telemetry(+ "POST",+ "/v1/embeddings",+ "https://api.z.ai/v1",+ ) == ("", "")+ assert custom_base_passthrough_telemetry(+ "GET",+ "/v1/chat/completions",+ "https://api.z.ai/v1",+ ) == ("", "")+ assert custom_base_passthrough_telemetry(+ "POST",+ "/v1/chat/completions",+ "://bad-url",+ ) == ("", "")+++def test_custom_base_passthrough_telemetry_requires_a_chat_path_segment() -> None:+ # A bare suffix match would also name ``notchat/completions``.+ for path in ("/v1/notchat/completions", "/v1/xchat/completions", "notchat/completions"):+ assert custom_base_passthrough_telemetry("POST", path, "https://api.z.ai/v1") == ("", "")+ # The exact segment, bare or nested, still names the host.+ for path in ("chat/completions", "/chat/completions", "/api/paas/v4/chat/completions"):+ assert custom_base_passthrough_telemetry("POST", path, "https://api.z.ai/v1") == (+ "chat/completions",+ "zai",+ )