mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
fix(proxy)!: read HEADROOM_LICENSE and make usage reporting opt-in (#3857)
## Why Core read its licence from `HEADROOM_LICENSE_KEY`, while every licensed extension reads `HEADROOM_LICENSE`. Core's cloud usage reporter also started whenever a key was present: it posts the licence to the Headroom cloud for validation and then sends aggregate usage every 5 minutes. Renaming the variable on its own would have switched the reporter on for every deployment that already sets `HEADROOM_LICENSE` for its extensions. So this PR renames the variable and makes reporting opt-in in the same change. ## What changes - New `headroom/license_env.py` holds the rules: - `HEADROOM_LICENSE` is the variable. - `HEADROOM_LICENSE_KEY` is still read as a deprecated alias for one release and logs `event=license_env_deprecated`. - If both are set to different values, `HEADROOM_LICENSE` wins and `event=license_env_conflict` is logged. - `HEADROOM_USAGE_REPORTING=1` (also `true`, `yes`, `on`) is the only way to turn reporting on. - `ProxyConfig.usage_reporting` (default `False`) carries the opt-in. Multi-worker children get it automatically. - `HeadroomProxy` starts `UsageReporter` only when a licence is set, `usage_reporting` is true and offline mode is off. - The startup banner no longer prints the first 8 characters of the licence. It shows `OSS (no licence)` or `LICENSED (usage reporting off | ON | suppressed by HEADROOM_OFFLINE)`. - Docs: two new rows in the proxy environment table. The comment in `run-all-plugins.sh` is corrected. Compression gating is unchanged: with no reporter running, the licence is treated as OK, which is the current OSS behaviour. ## Behaviour change (breaking) - A licence on its own no longer starts the cloud usage reporter. Deployments that relied on it must set `HEADROOM_USAGE_REPORTING=1`. - `HEADROOM_LICENSE` is the variable. `HEADROOM_LICENSE_KEY` still works for one release with a deprecation warning; rename it. The alias is removed in the next release. ## Tests `tests/test_license_env_and_usage_reporting.py`: - Variable rules: precedence, the alias warning, the conflict warning, the same value under both names staying quiet, blank values treated as unset. - Opt-in values: which values count as on and off. - The real app lifespan with every outbound `httpx.AsyncClient.send` captured: a licence alone sends nothing; with the opt-in, the first outbound call is `/v1/license/validate`; offline mode beats the opt-in. The first test fails on `main`, and the other two cannot run there because the opt-in does not exist. Manual runs of `headroom proxy` with nothing set, with `HEADROOM_LICENSE`, with only `HEADROOM_LICENSE_KEY`, and with licence plus opt-in plus `HEADROOM_OFFLINE=1` all served `/livez`, showed the expected banner, did not start the reporter and printed no licence text. Not tested live: opted in and online against the real cloud. That path is covered by the in-process test with the network captured. ## Follow-ups, not in this repo Several licensed extensions still fall back to core's `config.license_key`. It now carries the same `HEADROOM_LICENSE` token, so the fallback is redundant and can be removed. Revised 2026-10-01 after self-review: merged main to refresh CI; no code change. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: JD Davis <mxjerrett@gmail.com>
This commit is contained in:
co-authored by
Claude Opus 5.5
JD Davis
parent
7287589d23
commit
746038991c
@@ -341,6 +341,8 @@ with a privileged job.
|
||||
| `HEADROOM_PROXY_TOKEN` | none | Require a bearer token (`X-Headroom-Proxy-Token`) from non-loopback callers. |
|
||||
| `HEADROOM_COMPRESS_ALLOW_REMOTE` | `false` | Allow non-loopback callers to reach [`POST /v1/compress`](#post-v1compress) and `POST /v1/usage`. Required to run Headroom as a remote gateway/sidecar; without it remote callers get `404`. |
|
||||
| `--offline` / `HEADROOM_OFFLINE` | `false` | Air-gap mode: hard-disable **all** egress (telemetry, update checks, license reporting, model downloads). |
|
||||
| `HEADROOM_LICENSE` | unset | Licence token, read by core and every licensed extension. `HEADROOM_LICENSE_KEY` is a deprecated alias for one release and logs a warning. A licence on its own sends nothing to Headroom. |
|
||||
| `HEADROOM_USAGE_REPORTING` | `false` | Set `1` to let the proxy validate the licence and post aggregate usage counts (no content) to the Headroom cloud. Off unless set; `HEADROOM_OFFLINE` still overrides it. |
|
||||
| `--stateless` / `HEADROOM_STATELESS` | `false` | Keep all state in memory; no filesystem writes (disables logs, memory, TOIN). |
|
||||
| `HEADROOM_STRIP_INTERNAL_HEADERS` | `enabled` | Strip internal `x-headroom-*` headers before forwarding upstream. |
|
||||
| `HEADROOM_TLS_STRICT` | strict | Set `0` to relax CA-constraint checks behind a corporate TLS-inspection proxy. |
|
||||
|
||||
+17
-4
@@ -1304,8 +1304,13 @@ def proxy(
|
||||
if is_stateless:
|
||||
os.environ["HEADROOM_TOIN_BACKEND"] = "none"
|
||||
|
||||
# License key for managed/enterprise deployments (optional)
|
||||
license_key = os.environ.get("HEADROOM_LICENSE_KEY")
|
||||
# Licence token (HEADROOM_LICENSE; HEADROOM_LICENSE_KEY is a deprecated
|
||||
# alias). Having one set never enables outbound usage reporting: that
|
||||
# needs the explicit HEADROOM_USAGE_REPORTING=1 opt-in.
|
||||
from headroom.license_env import resolve_license_token, usage_reporting_enabled
|
||||
|
||||
license_key = resolve_license_token()
|
||||
usage_reporting = usage_reporting_enabled()
|
||||
|
||||
# Qdrant connection for the qdrant-neo4j backend. CLI flags default
|
||||
# to None; when omitted we let ProxyConfig's default_factory resolve
|
||||
@@ -1478,6 +1483,7 @@ def proxy(
|
||||
anyllm_provider=effective_anyllm_provider,
|
||||
# License / Usage Reporting (managed/enterprise)
|
||||
license_key=license_key,
|
||||
usage_reporting=usage_reporting,
|
||||
# Stateless mode: disable all filesystem writes
|
||||
stateless=is_stateless,
|
||||
# Unit 4: bounded pre-upstream concurrency on the Anthropic HTTP
|
||||
@@ -1503,9 +1509,16 @@ def proxy(
|
||||
if config.memory_enabled:
|
||||
memory_status = "ENABLED (multi-provider)"
|
||||
|
||||
license_status = "OSS (no license key)"
|
||||
license_status = "OSS (no licence)"
|
||||
if license_key:
|
||||
license_status = f"MANAGED (key={license_key[:8]}...)"
|
||||
# Never print licence material, not even a prefix.
|
||||
if not usage_reporting:
|
||||
reporting = "off"
|
||||
elif config.offline:
|
||||
reporting = "suppressed by HEADROOM_OFFLINE"
|
||||
else:
|
||||
reporting = "ON"
|
||||
license_status = f"LICENSED (usage reporting {reporting})"
|
||||
|
||||
provider_api_targets = resolve_api_targets(config.provider_api_overrides)
|
||||
anthropic_url = provider_api_targets.anthropic
|
||||
|
||||
@@ -0,0 +1,73 @@
|
||||
"""One licence variable, and an explicit switch for usage reporting.
|
||||
|
||||
Headroom reads its licence token from ``HEADROOM_LICENSE``. Every licensed
|
||||
extension reads the same variable, so core does too.
|
||||
|
||||
``HEADROOM_LICENSE_KEY`` was the older name read only by core's cloud usage
|
||||
reporter. It is still honoured for one release as a deprecated alias, with a
|
||||
warning, so existing managed deployments keep their licence while they rename.
|
||||
|
||||
Having a licence set never turns on outbound reporting by itself. The usage
|
||||
reporter validates the licence against the Headroom cloud and posts aggregate
|
||||
usage counts; it runs only when the operator also sets
|
||||
``HEADROOM_USAGE_REPORTING=1``. ``HEADROOM_OFFLINE`` still suppresses it.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
import os
|
||||
from collections.abc import Mapping
|
||||
|
||||
logger = logging.getLogger("headroom.license_env")
|
||||
|
||||
LICENSE_ENV = "HEADROOM_LICENSE"
|
||||
DEPRECATED_LICENSE_ENV = "HEADROOM_LICENSE_KEY"
|
||||
USAGE_REPORTING_ENV = "HEADROOM_USAGE_REPORTING"
|
||||
|
||||
_TRUE = frozenset({"1", "true", "yes", "on"})
|
||||
|
||||
|
||||
def _clean(value: str | None) -> str | None:
|
||||
if value is None:
|
||||
return None
|
||||
value = value.strip()
|
||||
return value or None
|
||||
|
||||
|
||||
def resolve_license_token(environ: Mapping[str, str] | None = None) -> str | None:
|
||||
"""Return the licence token, preferring ``HEADROOM_LICENSE``.
|
||||
|
||||
Falls back to the deprecated ``HEADROOM_LICENSE_KEY`` with a warning. When
|
||||
both are set to different values, ``HEADROOM_LICENSE`` wins and a warning
|
||||
says so, because silently picking one would hide a misconfiguration.
|
||||
"""
|
||||
env = os.environ if environ is None else environ
|
||||
current = _clean(env.get(LICENSE_ENV))
|
||||
legacy = _clean(env.get(DEPRECATED_LICENSE_ENV))
|
||||
|
||||
if current and legacy and current != legacy:
|
||||
logger.warning(
|
||||
"event=license_env_conflict using=%s ignored=%s hint=unset_%s_it_is_deprecated",
|
||||
LICENSE_ENV,
|
||||
DEPRECATED_LICENSE_ENV,
|
||||
DEPRECATED_LICENSE_ENV,
|
||||
)
|
||||
return current
|
||||
if current:
|
||||
return current
|
||||
if legacy:
|
||||
logger.warning(
|
||||
"event=license_env_deprecated variable=%s replacement=%s "
|
||||
"hint=rename_it_the_alias_is_removed_in_the_next_release",
|
||||
DEPRECATED_LICENSE_ENV,
|
||||
LICENSE_ENV,
|
||||
)
|
||||
return legacy
|
||||
return None
|
||||
|
||||
|
||||
def usage_reporting_enabled(environ: Mapping[str, str] | None = None) -> bool:
|
||||
"""True only when the operator explicitly opted in to usage reporting."""
|
||||
env = os.environ if environ is None else environ
|
||||
return (env.get(USAGE_REPORTING_ENV) or "").strip().lower() in _TRUE
|
||||
@@ -466,8 +466,11 @@ class ProxyConfig:
|
||||
memory_bridge_auto_import: bool = False
|
||||
memory_bridge_export_path: str = ""
|
||||
|
||||
# License / Usage Reporting
|
||||
# Licence / usage reporting. ``license_key`` holds the HEADROOM_LICENSE
|
||||
# token. The cloud usage reporter runs only when ``usage_reporting`` is
|
||||
# also true (HEADROOM_USAGE_REPORTING=1); a licence alone sends nothing.
|
||||
license_key: str | None = None
|
||||
usage_reporting: bool = False
|
||||
license_cloud_url: str = "https://app.headroomlabs.ai"
|
||||
license_report_interval: int = 300
|
||||
|
||||
|
||||
@@ -1425,11 +1425,13 @@ class HeadroomProxy(
|
||||
"hint=bridge_syncs_only_the_legacy_DB_today_per-project_bridge_follow-up_planned"
|
||||
)
|
||||
|
||||
# Usage Reporter (license validation + phone-home for managed/enterprise).
|
||||
# Usage Reporter (licence validation + phone-home for managed deployments).
|
||||
# Explicit opt-in only: a licence being present must not start outbound
|
||||
# reporting on its own (HEADROOM_USAGE_REPORTING=1 is required).
|
||||
# Suppressed entirely in offline mode — the air-gap switch must stop all
|
||||
# egress, including license phone-home, even when a key is configured.
|
||||
# egress, including licence phone-home, even when opted in.
|
||||
self.usage_reporter: UsageReporter | None = None
|
||||
if config.license_key and not (config.offline or is_offline()):
|
||||
if config.license_key and config.usage_reporting and not (config.offline or is_offline()):
|
||||
from headroom.telemetry.reporter import UsageReporter
|
||||
|
||||
self.usage_reporter = UsageReporter(
|
||||
|
||||
+3
-3
@@ -69,9 +69,9 @@ set -a; # shellcheck disable=SC1090
|
||||
source "$ENV_TXT"; set +a
|
||||
|
||||
# ── 4. plugin license (Ed25519, offline, wildcard) ────────────────────────────
|
||||
# HEADROOM_LICENSE + HEADROOM_LICENSE_PUBKEY. This is SEPARATE from the OSS cloud
|
||||
# key (HEADROOM_LICENSE_KEY) — the banner will still say "OSS (no license key)",
|
||||
# but each plugin prints "license accepted". Fallback: skip verification entirely.
|
||||
# HEADROOM_LICENSE + HEADROOM_LICENSE_PUBKEY. Core and every plugin read the same
|
||||
# HEADROOM_LICENSE; the banner says "LICENSED (usage reporting off)" unless
|
||||
# HEADROOM_USAGE_REPORTING=1 is also set. Fallback: skip verification entirely.
|
||||
if [ -f "$PLUGINS_ENV" ]; then
|
||||
set -a; # shellcheck disable=SC1090
|
||||
source "$PLUGINS_ENV"; set +a
|
||||
|
||||
@@ -0,0 +1,142 @@
|
||||
"""D-12: one licence variable, and usage reporting only on explicit opt-in.
|
||||
|
||||
Before this change core read ``HEADROOM_LICENSE_KEY`` while every extension
|
||||
read ``HEADROOM_LICENSE``, and the cloud usage reporter started whenever a key
|
||||
was present. Unifying the variable without the opt-in would have switched the
|
||||
reporter on in every licensed enterprise deployment. These tests pin both
|
||||
halves: the variable is ``HEADROOM_LICENSE`` (old name is a warned alias), and
|
||||
nothing is sent to the Headroom cloud unless ``HEADROOM_USAGE_REPORTING=1``.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
|
||||
import httpx
|
||||
import pytest
|
||||
|
||||
pytest.importorskip("fastapi")
|
||||
|
||||
from fastapi.testclient import TestClient # noqa: E402
|
||||
|
||||
from headroom.license_env import ( # noqa: E402
|
||||
resolve_license_token,
|
||||
usage_reporting_enabled,
|
||||
)
|
||||
from headroom.proxy.models import ProxyConfig # noqa: E402
|
||||
from headroom.proxy.server import create_app # noqa: E402
|
||||
|
||||
CLOUD = "https://cloud.headroom.test"
|
||||
|
||||
|
||||
class _Capture(logging.Handler):
|
||||
def __init__(self) -> None:
|
||||
super().__init__(level=logging.DEBUG)
|
||||
self.messages: list[str] = []
|
||||
|
||||
def emit(self, record: logging.LogRecord) -> None:
|
||||
self.messages.append(record.getMessage())
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def license_log():
|
||||
# Attach directly: headroom.* loggers are not reliably visible to caplog.
|
||||
logger = logging.getLogger("headroom.license_env")
|
||||
handler = _Capture()
|
||||
logger.addHandler(handler)
|
||||
try:
|
||||
yield handler
|
||||
finally:
|
||||
logger.removeHandler(handler)
|
||||
|
||||
|
||||
# --- variable resolution -------------------------------------------------
|
||||
|
||||
|
||||
def test_headroom_license_is_the_variable(license_log):
|
||||
assert resolve_license_token({"HEADROOM_LICENSE": "tok-new"}) == "tok-new"
|
||||
assert license_log.messages == []
|
||||
|
||||
|
||||
def test_legacy_name_is_an_alias_with_a_warning(license_log):
|
||||
assert resolve_license_token({"HEADROOM_LICENSE_KEY": "tok-old"}) == "tok-old"
|
||||
assert any("license_env_deprecated" in m for m in license_log.messages)
|
||||
|
||||
|
||||
def test_new_name_wins_on_conflict_and_says_so(license_log):
|
||||
env = {"HEADROOM_LICENSE": "tok-new", "HEADROOM_LICENSE_KEY": "tok-old"}
|
||||
assert resolve_license_token(env) == "tok-new"
|
||||
assert any("license_env_conflict" in m for m in license_log.messages)
|
||||
|
||||
|
||||
def test_same_value_under_both_names_is_quiet(license_log):
|
||||
env = {"HEADROOM_LICENSE": "tok", "HEADROOM_LICENSE_KEY": "tok"}
|
||||
assert resolve_license_token(env) == "tok"
|
||||
assert license_log.messages == []
|
||||
|
||||
|
||||
def test_blank_values_mean_unset():
|
||||
assert resolve_license_token({"HEADROOM_LICENSE": " ", "HEADROOM_LICENSE_KEY": ""}) is None
|
||||
|
||||
|
||||
@pytest.mark.parametrize("value", ["1", "true", "YES", " on "])
|
||||
def test_usage_reporting_opt_in_values(value):
|
||||
assert usage_reporting_enabled({"HEADROOM_USAGE_REPORTING": value}) is True
|
||||
|
||||
|
||||
@pytest.mark.parametrize("value", [None, "", "0", "false", "no", "off", "maybe"])
|
||||
def test_usage_reporting_is_off_unless_opted_in(value):
|
||||
env = {} if value is None else {"HEADROOM_USAGE_REPORTING": value}
|
||||
assert usage_reporting_enabled(env) is False
|
||||
|
||||
|
||||
# --- outbound traffic ----------------------------------------------------
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def cloud_calls(monkeypatch):
|
||||
"""Record every request any httpx.AsyncClient sends to the fake cloud."""
|
||||
calls: list[httpx.Request] = []
|
||||
real_send = httpx.AsyncClient.send
|
||||
|
||||
async def send(self, request, *args, **kwargs):
|
||||
if str(request.url).startswith(CLOUD):
|
||||
calls.append(request)
|
||||
return httpx.Response(200, json={"status": "active"}, request=request)
|
||||
return await real_send(self, request, *args, **kwargs)
|
||||
|
||||
monkeypatch.setattr(httpx.AsyncClient, "send", send)
|
||||
monkeypatch.delenv("HEADROOM_OFFLINE", raising=False)
|
||||
return calls
|
||||
|
||||
|
||||
def _config(**overrides) -> ProxyConfig:
|
||||
return ProxyConfig(
|
||||
license_key="tok-licensed",
|
||||
license_cloud_url=CLOUD,
|
||||
license_report_interval=3600,
|
||||
optimize=False,
|
||||
**overrides,
|
||||
)
|
||||
|
||||
|
||||
def test_licence_alone_sends_nothing(cloud_calls):
|
||||
app = create_app(_config())
|
||||
with TestClient(app) as client:
|
||||
client.get("/livez")
|
||||
assert cloud_calls == []
|
||||
|
||||
|
||||
def test_opt_in_reports_to_the_cloud(cloud_calls):
|
||||
app = create_app(_config(usage_reporting=True))
|
||||
with TestClient(app) as client:
|
||||
client.get("/livez")
|
||||
assert [c.url.path for c in cloud_calls][:1] == ["/v1/license/validate"]
|
||||
|
||||
|
||||
def test_offline_beats_opt_in(cloud_calls, monkeypatch):
|
||||
monkeypatch.setenv("HEADROOM_OFFLINE", "1")
|
||||
app = create_app(_config(usage_reporting=True))
|
||||
with TestClient(app) as client:
|
||||
client.get("/livez")
|
||||
assert cloud_calls == []
|
||||
Reference in New Issue
Block a user