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.

chore(proxy): add third-party extension point

chopratejas3373dabce01e
diff --git a/headroom/proxy/extensions.py b/headroom/proxy/extensions.py
new file mode 100644
index 000000000..15f2d2044
--- /dev/null
+++ b/headroom/proxy/extensions.py
@@ -0,0 +1,74 @@
+"""Third-party proxy extension point.
+
+External packages hook into the Headroom proxy at startup by declaring an
+entry point in the ``headroom.proxy_extension`` group in their ``pyproject.toml``:
+
+ [project.entry-points."headroom.proxy_extension"]
+ my_extension = "my_pkg.extension:install"
+
+Each ``install`` callable is invoked with the FastAPI ``app`` and the
+``ProxyConfig`` at app creation time, and is free to:
+
+ * register ASGI middleware (``app.add_middleware(...)``)
+ * add routes or health endpoints
+ * mutate config
+ * raise on license / environment failure to abort startup
+
+OSS makes no assumptions about what extensions do. The interface is
+deliberately minimal; extensions own the complexity behind it.
+
+Stability contract: this module is load-bearing for the Enterprise build and
+any third-party extensions. Changes to the signature of ``install(app, config)``
+or the entry-point group name require a deprecation cycle.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+import logging
+from collections.abc import Callable, Iterator
+from typing import Any
+
+log = logging.getLogger(__name__)
+
+ENTRY_POINT_GROUP = "headroom.proxy_extension"
+
+ProxyExtension = Callable[[Any, Any], None]
+"""Signature: ``install(app: FastAPI, config: ProxyConfig) -> None``."""
+
+
+def discover() -> Iterator[tuple[str, ProxyExtension]]:
+ """Yield ``(name, install_callable)`` pairs for every registered extension.
+
+ Entry-point load failures are logged and skipped — a broken third-party
+ package must not prevent the proxy from starting. An extension that wants
+ to fail-closed can raise from its ``install()``.
+ """
+ try:
+ entries = importlib.metadata.entry_points(group=ENTRY_POINT_GROUP)
+ except Exception as exc: # noqa: BLE001 — importlib.metadata can raise varied types
+ log.debug("proxy extensions: entry-point enumeration failed: %s", exc)
+ return
+ for entry in entries:
+ try:
+ install = entry.load()
+ except Exception as exc: # noqa: BLE001
+ log.warning("proxy extension %r failed to load: %s", entry.name, exc)
+ continue
+ yield entry.name, install
+
+
+def install_all(app: Any, config: Any) -> list[str]:
+ """Run every discovered extension's ``install(app, config)``.
+
+ Returns the names of successfully installed extensions. If an extension
+ raises inside ``install()``, the exception propagates — this is the
+ documented fail-closed signal (e.g., a Shield Enterprise license check
+ failing should abort startup rather than silently run without protection).
+ """
+ installed: list[str] = []
+ for name, install in discover():
+ install(app, config)
+ installed.append(name)
+ log.info("proxy extension installed: %s", name)
+ return installed
diff --git a/headroom/proxy/server.py b/headroom/proxy/server.py
index 2d6fa60ea..757364e16 100644
--- a/headroom/proxy/server.py
+++ b/headroom/proxy/server.py
@@ -1189,6 +1189,13 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
allow_headers=["*"],
)
+ # Third-party proxy extensions (Enterprise, custom plugins). Discovered via
+ # the `headroom.proxy_extension` entry-point group. An extension that raises
+ # from its install() is a deliberate fail-closed signal and aborts startup.
+ from headroom.proxy.extensions import install_all as _install_extensions
+
+ _install_extensions(app, config)
+
# Health & Metrics
@app.get("/livez")
async def livez():
diff --git a/pyproject.toml b/pyproject.toml
index 3bf123616..2960eb209 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -306,6 +306,10 @@ python_files = ["test_*.py"]
python_functions = ["test_*"]
addopts = "-v --tb=short"
asyncio_mode = "auto"
+markers = [
+ "slow: slow tests (model loads, large fixtures)",
+ "real_llm: tests that hit real LLM APIs; skipped unless explicitly enabled",
+]
[tool.coverage.run]
source = ["headroom"]