From e185390ea283652e9d4022dd7edcf48ac98e89e0 Mon Sep 17 00:00:00 2001 From: Abhyudaya Baiju Tharakan Date: Fri, 9 Oct 2026 04:29:53 +0530 Subject: [PATCH] feat(gateway): add opt-in source-scoped protocol extras Carry reviewed per-protocol fields outside the Chat pivot behind PROTOCOL_EXTRAS_ENABLED (default off), restore them only for providers that admit each field, and report retained versus re-emitted fields without values. --- docs/protocol-extras.md | 105 +++++++ routes/protocol_bridge.py | 11 +- services/protocol_extras.py | 268 +++++++++++++++++ services/protocol_translation/anthropic.py | 12 + services/protocol_translation/common.py | 17 ++ services/protocol_translation/responses.py | 12 + tests/test_protocol_extras.py | 321 +++++++++++++++++++++ worker/container-env.mjs | 1 + 8 files changed, 744 insertions(+), 3 deletions(-) create mode 100644 docs/protocol-extras.md create mode 100644 services/protocol_extras.py create mode 100644 tests/test_protocol_extras.py diff --git a/docs/protocol-extras.md b/docs/protocol-extras.md new file mode 100644 index 00000000..3de4faf5 --- /dev/null +++ b/docs/protocol-extras.md @@ -0,0 +1,105 @@ +# Source-scoped protocol extras + +`PROTOCOL_EXTRAS_ENABLED` defaults to `false`. An empty value also disables the +feature. Invalid values disable it and produce one warning containing the +variable name, without its value. When disabled, existing strict translation, +namespace handling and raw request and response bytes remain unchanged. + +Enable the option with `PROTOCOL_EXTRAS_ENABLED=true`. Managed callers can supply +the following namespace on a Messages request: + +```json +{ + "model": "provider:model", + "messages": [{"role": "user", "content": "Hello"}], + "max_tokens": 128, + "_multillm": { + "protocol_extras": { + "source_protocol": "messages", + "fields": {"top_k": 7} + } + } +} +``` + +The gateway validates the source against the originating managed protocol and +holds approved extras separately from the Chat pivot body. The namespace is +internal metadata and must never be serialized to a provider. Returning to +Messages can restore `top_k` only when the selected provider explicitly admits +that field. A Responses target omits it. Provider admission defaults to an empty +set; a protocol name alone does not establish model support. + +With the feature disabled, omit `_multillm` and send ordinary protocol fields: + +```json +{ + "model": "provider:model", + "messages": [{"role": "user", "content": "Hello"}], + "max_tokens": 128 +} +``` + +## Reviewed fields and bounds + +Request extras allow only these scalar members: + +| Source | Fields | Values | +| --- | --- | --- | +| `messages` | `top_k` | Integer from 0 to 2,147,483,647 | +| `responses` | `truncation` | `"disabled"` only | +| `chat` | `seed` | Signed 64-bit integer | +| `chat` | `logprobs` | Boolean | +| `chat` | `top_logprobs` | Integer from 0 to 20 | + +Native JSON response extras allow Messages `stop_sequence` (null or a string up +to 1,024 characters), Chat `system_fingerprint` (null or an identifier up to 256 +characters), and Responses `service_tier` (`auto`, `default`, `flex`, `priority`, +or `scale`). These response observations do not select a billing tier. Response +fields require the same source and explicit admission before restoration. + +The namespace allows only `protocol_extras`, with exactly `source_protocol` and +`fields`. At most 32 fields and 16 KiB of compact UTF-8 JSON are accepted. The +reviewed allowlist is smaller than the field-count ceiling. Nested objects, +executable payloads, credentials, unknown fields and unknown namespace options +are rejected. Conflicting values in the body and extras are rejected. Automatic +truncation, containers, stored response identifiers, reasoning controls and +other lifecycle semantics cannot be smuggled through extras. Existing strict +translator lifecycle checks also remain active. + +## Errors, fidelity and retention + +Invalid managed extras raise an HTTP 400 translation error with parameter +`_multillm.protocol_extras`. Error messages do not echo names or values from +untrusted fields. An upstream response attempting to supply the internal +namespace fails with HTTP 502 on a translated JSON path. Raw passthrough remains +unchanged. + +Content-free conversion reports distinguish IR retention from output fidelity. +An approved field omitted from a foreign or nonadmitting target is `lossy`, with +`retained_in_ir: true` and `re_emitted: false`. A restored approved field is +`exact`. Required extras that the selected target cannot admit are rejected; +required-field policy is supplied by trusted dispatch code, not client metadata. +Reports contain fixed allowlisted paths and no field values. + +The carrier lasts only for its managed operation. There is no new database, +cache, prompt logging or durable retention. Discarding the carrier discards its +extras. SSE event translation remains strict and does not retain or restore +extras. No usage, cost, retry or provider capability guarantee is added. Sampling +and log-probability settings may affect output or provider charges under the +provider's existing contract. + +## Managed integration interface + +`services.protocol_extras.request_to_ir` constructs a typed carrier; +`request_from_ir` emits a provider body using trusted `admitted_fields` and +`required_fields`. Keep the carrier separate while dispatch copies or optimizes +the body. `translate_managed_request` is the single-hop equivalent, including +same-protocol namespace validation. `managed_request_report` composes the same +validation and extra-field observations with conversion diagnostics. + +Use these hooks at authenticated managed dispatch and conversion-report entry +points. Native managed emission must use explicit provider admission, and Chat +serialization must receive only the emitted body. Raw provider endpoints use +their existing transport. `response_to_ir` and `response_from_ir` provide the +corresponding JSON response interface; the Flask response bridge uses managed +JSON translation while preserving raw same-protocol responses. diff --git a/routes/protocol_bridge.py b/routes/protocol_bridge.py index 94c3edd2..0524652a 100644 --- a/routes/protocol_bridge.py +++ b/routes/protocol_bridge.py @@ -13,7 +13,8 @@ from route_helpers import stream_upstream_response from services import protocol_translation as translation from services.protocol_translation import TranslationError, UpstreamFailure -from services.conversion_diagnostics import response_report +from services.conversion_diagnostics import combine_reports, response_report +from services import protocol_extras ENDPOINT_PROTOCOLS = { CHAT_COMPLETIONS: translation.CHAT, @@ -169,7 +170,7 @@ def translate_downstream_response( headers=[*headers, *STREAM_HEADERS.items()], content_type="text/event-stream", ) - payload = translation.translate_response( + payload = protocol_extras.translate_managed_response( decoded, source, target, model=model, request=request_payload ) except UpstreamFailure as failure: @@ -181,4 +182,8 @@ def _record_response_conversion(payload, source, target) -> None: from routes.unified_bridge import diagnostics_requested, record_conversion if diagnostics_requested(): - record_conversion(response_report(payload, source, target)) + report = response_report(payload, source, target) + if protocol_extras.enabled() and isinstance(payload, Mapping): + extras = protocol_extras.capture_response_extras(payload, source) + report = combine_reports(report, protocol_extras.extras_report(extras, target)) + record_conversion(report) diff --git a/services/protocol_extras.py b/services/protocol_extras.py new file mode 100644 index 00000000..e2dd6c53 --- /dev/null +++ b/services/protocol_extras.py @@ -0,0 +1,268 @@ +"""Bounded, source-scoped extras kept outside serialized protocol bodies.""" + +from __future__ import annotations + +import json +import logging +import os +import re +from collections.abc import Collection, Mapping +from threading import Lock +from typing import Any + +from services.protocol_translation.common import ( + CHAT, + MESSAGES, + PROTOCOLS, + RESPONSES, + ProtocolExtras, + ProtocolIR, + TranslationError, + UpstreamFailure, +) + +MAX_FIELDS = 32 +MAX_BYTES = 16 * 1024 +_PARAM = "_multillm.protocol_extras" +_REQUEST_FIELDS = { + CHAT: frozenset({"seed", "logprobs", "top_logprobs"}), + MESSAGES: frozenset({"top_k"}), + RESPONSES: frozenset({"truncation"}), +} +_RESPONSE_FIELDS = { + CHAT: frozenset({"system_fingerprint"}), + MESSAGES: frozenset({"stop_sequence"}), + RESPONSES: frozenset({"service_tier"}), +} +logger = logging.getLogger(__name__) +_warned = False +_warning_lock = Lock() + + +def enabled() -> bool: + global _warned + flag = os.environ.get("PROTOCOL_EXTRAS_ENABLED", "").strip().lower() + if flag in {"", "0", "false", "no", "off"}: + return False + if flag in {"1", "true", "yes", "on"}: + return True + with _warning_lock: + if not _warned: + _warned = True + logger.warning("Invalid PROTOCOL_EXTRAS_ENABLED; protocol extras disabled") + return False + + +def _invalid(message: str) -> TranslationError: + return TranslationError(message, param=_PARAM) + + +def _bounded(value: Any) -> None: + try: + encoded = json.dumps(value, ensure_ascii=False, allow_nan=False, + separators=(",", ":")).encode("utf-8") + except (TypeError, ValueError, OverflowError, RecursionError, UnicodeError) as error: + raise _invalid("Protocol extras must contain bounded JSON values") from error + if len(encoded) > MAX_BYTES: + raise _invalid("Protocol extras exceed the 16 KiB limit") + + +def _valid_value(key: str, value: Any, kind: str) -> bool: + if kind == "response": + if key == "stop_sequence": + return value is None or (isinstance(value, str) and len(value) <= 1024) + if key == "system_fingerprint": + return value is None or (isinstance(value, str) and + re.fullmatch(r"[A-Za-z0-9_.:-]{1,256}", value) is not None) + return isinstance(value, str) and value in {"auto", "default", "flex", "priority", "scale"} + if key == "logprobs": + return type(value) is bool + if key == "truncation": + # Automatic truncation changes required input semantics across protocols. + return value == "disabled" + bounds = {"seed": (-(2**63), 2**63 - 1), "top_k": (0, 2**31 - 1), "top_logprobs": (0, 20)} + low, high = bounds[key] + return type(value) is int and low <= value <= high + + +def _fields(source: str, fields: Any, kind: str) -> tuple[tuple[str, Any], ...]: + if not isinstance(fields, Mapping) or len(fields) > MAX_FIELDS: + raise _invalid("Protocol extras must be an object with at most 32 fields") + _bounded(fields) + allowed = (_REQUEST_FIELDS if kind == "request" else _RESPONSE_FIELDS)[source] + if any(key not in allowed for key in fields): + raise _invalid("Protocol extras contain an unreviewed or unsupported field") + if any(not _valid_value(key, value, kind) for key, value in fields.items()): + raise _invalid("Protocol extras contain an unsupported field value") + return tuple(sorted(fields.items())) + + +def capture_request_extras(payload: Mapping[str, Any], source: str) -> ProtocolExtras | None: + """Validate client namespace only for managed traffic with the flag enabled.""" + if not enabled() or "_multillm" not in payload: + return None + namespace = payload["_multillm"] + if not isinstance(namespace, Mapping): + raise _invalid("The managed namespace must be an object") + if any(key != "protocol_extras" for key in namespace): + raise _invalid("The managed namespace contains an unknown option") + if not namespace: + return None + _bounded(namespace) + extra = namespace["protocol_extras"] + if not isinstance(extra, Mapping) or set(extra) != {"source_protocol", "fields"}: + raise _invalid("Protocol extras require source_protocol and fields only") + recorded = extra["source_protocol"] + if not isinstance(recorded, str) or recorded not in PROTOCOLS or recorded != source: + raise _invalid("Protocol extras source must match the originating protocol") + fields = _fields(recorded, extra["fields"], "request") + if any(key in payload and payload[key] != value for key, value in fields): + raise _invalid("Protocol extras conflict with an explicit request field") + return ProtocolExtras(recorded, fields) + + +def validate_request_extras(payload: Mapping[str, Any], source: str) -> None: + """Small strict-translator call site; never add the namespace to its output.""" + capture_request_extras(payload, source) + + +def _without_extras(payload: Mapping[str, Any], extras: ProtocolExtras | None) -> dict: + excluded = {key for key, _ in extras.fields} if extras else set() + excluded.add("_multillm") + return {key: value for key, value in payload.items() if key not in excluded} + + +def request_to_ir(payload: Mapping[str, Any], source: str) -> ProtocolIR: + """Create an explicit carrier independent of the client or provider body.""" + from services.protocol_translation import translate_request + + extras = capture_request_extras(payload, source) + clean = _without_extras(payload, extras) if enabled() else dict(payload) + return ProtocolIR(translate_request(clean, source, CHAT), extras) + + +def _emitted(extras: ProtocolExtras | None, target: str, admitted_fields: Collection[str], + required_fields: Collection[str], kind: str) -> dict: + if target not in PROTOCOLS: + raise ValueError("Unknown target protocol") + if extras is None: + if required_fields: + raise _invalid("Required protocol extras are unavailable") + return {} + if extras.source_protocol not in PROTOCOLS or extras.kind != kind or kind not in {"request", "response"}: + raise _invalid("Protocol extras carrier has an invalid source or body kind") + fields = dict(extras.fields) + _fields(extras.source_protocol, fields, kind) + emitted = {key: value for key, value in fields.items() + if target == extras.source_protocol and key in admitted_fields} + if any(key not in emitted for key in required_fields): + raise _invalid("The target provider cannot represent required protocol extras") + return emitted + + +def request_from_ir(ir: ProtocolIR, target: str, *, admitted_fields: Collection[str] = (), + required_fields: Collection[str] = ()) -> dict: + """Emit only fields explicitly admitted by the selected provider contract.""" + from services.protocol_translation import translate_request + + fields = _emitted(ir.extras, target, admitted_fields, required_fields, "request") if enabled() else {} + body = translate_request(ir.body, CHAT, target) + return {**body, **fields} + + +def translate_managed_request(payload: Mapping[str, Any], source: str, target: str, *, + admitted_fields: Collection[str] = (), + required_fields: Collection[str] = ()) -> dict: + """Named dispatch hook; raw callers continue to use the existing transport.""" + from services.protocol_translation import translate_request + + if not enabled(): + return translate_request(payload, source, target) + if source == target: + extras = capture_request_extras(payload, source) + fields = _emitted(extras, target, admitted_fields, required_fields, "request") + return {**_without_extras(payload, extras), **fields} + ir = request_to_ir(payload, source) + return request_from_ir(ir, target, admitted_fields=admitted_fields, required_fields=required_fields) + + +def validate_response_extras(payload: Mapping[str, Any]) -> None: + """Upstream bodies cannot manufacture a trusted source namespace.""" + if enabled() and "_multillm" in payload: + raise UpstreamFailure("The upstream response contains an internal protocol namespace") + + +def capture_response_extras(payload: Mapping[str, Any], source: str) -> ProtocolExtras | None: + """Retain reviewed native response members, never an upstream carrier.""" + if source not in PROTOCOLS: + raise ValueError("Unknown source protocol") + validate_response_extras(payload) + if enabled(): + fields = {key: payload[key] for key in _RESPONSE_FIELDS[source] if key in payload} + try: + return ProtocolExtras(source, _fields(source, fields, "response"), "response") if fields else None + except TranslationError as error: + raise UpstreamFailure("The upstream protocol extras have an invalid shape") from error + return None + + +def response_to_ir(payload: Mapping[str, Any], source: str) -> ProtocolIR: + from services.protocol_translation import translate_response + + extras = capture_response_extras(payload, source) + clean = _without_extras(payload, extras) if enabled() else payload + return ProtocolIR(translate_response(clean, source, CHAT), extras) + + +def response_from_ir(ir: ProtocolIR, target: str, *, admitted_fields: Collection[str] = (), + model: str | None = None, request: Mapping[str, Any] | None = None) -> dict: + from services.protocol_translation import translate_response + + try: + fields = _emitted(ir.extras, target, admitted_fields, (), "response") if enabled() else {} + except TranslationError as error: + raise UpstreamFailure("The upstream protocol extras have an invalid shape") from error + return {**translate_response(ir.body, CHAT, target, model=model, request=request), **fields} + + +def translate_managed_response(payload: Mapping[str, Any], source: str, target: str, *, + model: str | None = None, + request: Mapping[str, Any] | None = None) -> dict: + from services.protocol_translation import translate_response + + if not enabled(): + return translate_response(payload, source, target, model=model, request=request) + ir = response_to_ir(payload, source) + return response_from_ir(ir, target, model=model, request=request) + + +def extras_report(extras: ProtocolExtras | None, target: str, *, + admitted_fields: Collection[str] = ()) -> dict: + """Fixed field paths describe IR retention separately from egress loss.""" + if extras is None: + return {"fidelity": "exact", "fields": []} + emitted = _emitted(extras, target, admitted_fields, (), extras.kind) + fields = [{"path": f"{extras.kind}.protocol_extras.{key}", + "classification": "exact" if key in emitted else "lossy", + "reason": "Approved field re-emitted." if key in emitted else + "Approved field retained in IR and omitted from the target body.", + "retained_in_ir": True, "re_emitted": key in emitted} + for key, _ in extras.fields] + return {"fidelity": "lossy" if any(f["classification"] == "lossy" for f in fields) else "exact", + "fields": fields} + + +def managed_request_report(payload: Mapping[str, Any], source: str, target: str, *, + admitted_fields: Collection[str] = ()) -> dict: + """Augment conversion diagnostics using the same validation as dispatch.""" + from services.conversion_diagnostics import combine_reports, request_report + + if not enabled(): + return request_report(payload, source, target) + try: + extras = capture_request_extras(payload, source) + base = request_report(_without_extras(payload, extras), source, target) + return combine_reports(base, extras_report(extras, target, admitted_fields=admitted_fields)) + except TranslationError: + return {"fidelity": "unsupported", "fields": [{"path": "request.protocol_extras", + "classification": "unsupported", "reason": "Protocol extras cannot be represented."}]} diff --git a/services/protocol_translation/anthropic.py b/services/protocol_translation/anthropic.py index 64b0bd58..ff45a584 100644 --- a/services/protocol_translation/anthropic.py +++ b/services/protocol_translation/anthropic.py @@ -86,8 +86,11 @@ def messages_request_to_chat(payload: Mapping[str, Any]) -> dict: + from services.protocol_extras import validate_request_extras + if not isinstance(payload, Mapping): raise TranslationError("The request body must be a JSON object") + validate_request_extras(payload, "messages") for field, feature in _STATEFUL_FIELDS.items(): if payload.get(field): raise TranslationError( @@ -439,8 +442,11 @@ def _output_format(payload: Mapping[str, Any]) -> dict | None: def chat_request_to_messages(payload: Mapping[str, Any]) -> dict: + from services.protocol_extras import validate_request_extras + if not isinstance(payload, Mapping): raise TranslationError("The request body must be a JSON object") + validate_request_extras(payload, "chat") if payload.get("n") not in (None, 1): raise TranslationError("Anthropic Messages returns one choice; n must be 1", param="n") if payload.get("audio") or "audio" in (payload.get("modalities") or []): @@ -745,6 +751,9 @@ def _apply_thinking(body: dict, payload: Mapping[str, Any]) -> None: def messages_response_to_chat( payload: Mapping[str, Any], *, model: str | None = None, **_: Any ) -> dict: + from services.protocol_extras import validate_response_extras + + validate_response_extras(payload) texts: list[str] = [] reasoning: list[str] = [] calls: list[dict] = [] @@ -797,6 +806,9 @@ def messages_response_to_chat( def chat_response_to_messages( payload: Mapping[str, Any], *, model: str | None = None, **_: Any ) -> dict: + from services.protocol_extras import validate_response_extras + + validate_response_extras(payload) message, finish = first_chat_choice(payload) content: list[dict] = [] reasoning = message_reasoning(message) diff --git a/services/protocol_translation/common.py b/services/protocol_translation/common.py index 7a68d3a7..761b1c37 100644 --- a/services/protocol_translation/common.py +++ b/services/protocol_translation/common.py @@ -51,6 +51,23 @@ def __init__(self, message: str, *, error_type: str = "api_error", code: str | N self.code = code +@dataclass(frozen=True) +class ProtocolExtras: + """Reviewed scalar fields bound to their source protocol and body kind.""" + + source_protocol: str + fields: tuple[tuple[str, Any], ...] + kind: str = "request" + + +@dataclass(frozen=True) +class ProtocolIR: + """Chat pivot body and separate extras; serialize only the emitted body.""" + + body: dict[str, Any] + extras: ProtocolExtras | None = None + + @dataclass(frozen=True) class StreamComment: """An SSE comment such as a provider keep-alive, forwarded as a comment.""" diff --git a/services/protocol_translation/responses.py b/services/protocol_translation/responses.py index b79fae50..2ecd7218 100644 --- a/services/protocol_translation/responses.py +++ b/services/protocol_translation/responses.py @@ -47,8 +47,11 @@ def responses_request_to_chat(payload: Mapping[str, Any]) -> dict: + from services.protocol_extras import validate_request_extras + if not isinstance(payload, Mapping): raise TranslationError("The request body must be a JSON object") + validate_request_extras(payload, "responses") for field, feature in _STATEFUL_FIELDS.items(): if payload.get(field): raise TranslationError( @@ -314,8 +317,11 @@ def _text_format_to_chat(fmt: Any) -> dict | None: def chat_request_to_responses(payload: Mapping[str, Any]) -> dict: + from services.protocol_extras import validate_request_extras + if not isinstance(payload, Mapping): raise TranslationError("The request body must be a JSON object") + validate_request_extras(payload, "chat") if payload.get("n") not in (None, 1): raise TranslationError("The Responses API returns one output; n must be 1", param="n") if payload.get("audio") or "audio" in (payload.get("modalities") or []): @@ -492,6 +498,9 @@ def _chat_content_to_input(content: Any, index: int) -> Any: def responses_response_to_chat( payload: Mapping[str, Any], *, model: str | None = None, **_: Any ) -> dict: + from services.protocol_extras import validate_response_extras + + validate_response_extras(payload) status = payload.get("status") if status == "failed" or (payload.get("error") and status not in ("completed", "incomplete")): reason, error_type, code = error_details({"error": payload.get("error") or {}}) @@ -562,6 +571,9 @@ def chat_response_to_responses( request: Mapping[str, Any] | None = None, **_: Any, ) -> dict: + from services.protocol_extras import validate_response_extras + + validate_response_extras(payload) message, finish = first_chat_choice(payload) output: list[dict] = [] reasoning = message_reasoning(message) diff --git a/tests/test_protocol_extras.py b/tests/test_protocol_extras.py new file mode 100644 index 00000000..c58e1ad4 --- /dev/null +++ b/tests/test_protocol_extras.py @@ -0,0 +1,321 @@ +"""Source-bound metadata, conservative provider admission and managed route checks.""" + +import copy +import importlib +import json +from unittest.mock import patch + +import pytest +from flask import Flask, Response + +from services import protocol_extras as extras +from services import protocol_translation as translation +from tests.test_protocol_routes import CHAT_COMPLETION, json_upstream +from tests.unified_api_test_case import UnifiedApiTestCase + + +@pytest.fixture(autouse=True) +def configured(monkeypatch): + global extras, translation + extras = importlib.import_module("services.protocol_extras") + translation = importlib.import_module("services.protocol_translation") + monkeypatch.setenv("PROTOCOL_EXTRAS_ENABLED", "true") + monkeypatch.setenv("PROMPT_CACHE_USAGE_BUCKETS_ENABLED", "false") + requests = importlib.import_module("requests") + + def no_http(*args, **kwargs): + raise AssertionError("unexpected external HTTP call") + + monkeypatch.setattr(requests.sessions.Session, "request", no_http) + + +def body(protocol="messages", fields=None): + result = {"model": "opencode:kimi-k2.6"} + result["input" if protocol == "responses" else "messages"] = ( + "private" if protocol == "responses" else [{"role": "user", "content": "private"}]) + result["_multillm"] = {"protocol_extras": { + "source_protocol": protocol, "fields": fields if fields is not None else {"top_k": 7}}} + return result + + +def test_round_trip_retains_only_with_source_and_provider_admission(): + request = body() + original = copy.deepcopy(request) + ir = extras.request_to_ir(request, "messages") + assert ir.extras.source_protocol == "messages" + assert "_multillm" not in ir.body + foreign = extras.request_from_ir(ir, "responses", admitted_fields={"top_k"}) + assert "top_k" not in foreign and "_multillm" not in foreign + restored = extras.request_from_ir(ir, "messages", admitted_fields={"top_k"}) + assert restored["top_k"] == 7 + denied = extras.request_from_ir(ir, "messages") + assert "top_k" not in denied + assert request == original + + +@pytest.mark.parametrize("protocol,fields", [ + ("responses", {"truncation": "disabled"}), + ("chat", {"seed": 3, "logprobs": True, "top_logprobs": 2}), +]) +def test_other_source_contracts(protocol, fields): + ir = extras.request_to_ir(body(protocol, fields), protocol) + restored = extras.request_from_ir(ir, protocol, admitted_fields=set(fields)) + assert all(restored[key] == value for key, value in fields.items()) + assert "_multillm" not in restored + + +def test_duplicate_native_field_is_owned_by_the_carrier(): + request = {**body("chat", {"seed": 3}), "seed": 3} + ir = extras.request_to_ir(request, "chat") + assert "seed" not in ir.body + assert "seed" not in extras.request_from_ir(ir, "chat") + assert extras.request_from_ir(ir, "chat", admitted_fields={"seed"})["seed"] == 3 + + +def test_chat_response_field_needs_explicit_admission_after_round_trip(): + ir = extras.response_to_ir({**CHAT_COMPLETION, "system_fingerprint": "fp_1"}, "chat") + assert "system_fingerprint" not in ir.body + assert "system_fingerprint" not in extras.response_from_ir(ir, "chat") + assert extras.response_from_ir(ir, "chat", admitted_fields={"system_fingerprint"})["system_fingerprint"] == "fp_1" + + +@pytest.mark.parametrize("fields", [ + {"container": "private"}, {"reasoning": {"encrypted_content": "private"}}, + {"thinking": {"type": "enabled"}}, {"previous_response_id": "private"}, + {"background": True}, {"tools": [{"type": "bash"}]}, + {"authorization": "private"}, {"api_key": "private"}, + {"metadata": {"api_key": "private"}}, {"top_k": {"code": "private"}}, + {"top_k": True}, {"top_k": -1}, +]) +def test_unsafe_or_unreviewed_fields_fail_without_echo(fields): + with pytest.raises(translation.TranslationError) as caught: + extras.request_to_ir(body(fields=fields), "messages") + assert "private" not in str(caught.value) + assert caught.value.param == "_multillm.protocol_extras" + + +@pytest.mark.parametrize("namespace", [ + None, [], {"unknown-private": {}}, {"protocol_extras": []}, + {"protocol_extras": {"source_protocol": "private", "fields": {}}}, + {"protocol_extras": {"source_protocol": "responses", "fields": {}}}, + {"protocol_extras": {"source_protocol": "messages", "fields": {}, "private": True}}, +]) +def test_namespace_rejected(namespace): + request = body() + request["_multillm"] = namespace + with pytest.raises(translation.TranslationError): + extras.request_to_ir(request, "messages") + + +@pytest.mark.parametrize("fields", [ + {str(index): 1 for index in range(33)}, {"top_k": "x" * 16384}, + {"top_k": float("nan")}, {"top_k": [object()]}, +]) +def test_field_and_serialized_byte_bounds(fields): + with pytest.raises(translation.TranslationError): + extras.request_to_ir(body(fields=fields), "messages") + + +def test_empty_namespace_and_null_fields_are_not_silently_accepted(): + assert extras.request_to_ir({**body(), "_multillm": {}}, "messages").extras is None + with pytest.raises(translation.TranslationError): + extras.request_to_ir(body(fields={"top_k": None}), "messages") + + +def test_disabled_translators_namespace_and_raw_bytes_unchanged(monkeypatch): + request = body(fields={"container": "private"}) + monkeypatch.setenv("PROTOCOL_EXTRAS_ENABLED", "false") + expected = translation.translate_request(request, "messages", "chat") + for flag in ("", "false", "0", "malformed-private"): + monkeypatch.setenv("PROTOCOL_EXTRAS_ENABLED", flag) + assert extras.translate_managed_request(request, "messages", "chat") == expected + assert translation.translate_request(request, "chat", "chat") == request + app = Flask(__name__) + with app.test_request_context(): + bridge = importlib.import_module("routes.protocol_bridge") + raw = Response(b' {"_multillm":{"private":true}} \n', content_type="application/json") + result = bridge.translate_downstream_response(raw, source="messages", target="messages", stream=False) + assert result is raw + assert result.data == b' {"_multillm":{"private":true}} \n' + + +def test_enabled_raw_stream_is_unchanged_and_not_consumed(): + bridge = importlib.import_module("routes.protocol_bridge") + seen = [] + + def raw_stream(): + seen.append(True) + yield b'data: {"_multillm":{"unreviewed":true}}\n\n' + + raw = Response(raw_stream(), content_type="text/event-stream", headers={"X-Provider": "native"}) + result = bridge.translate_downstream_response(raw, source="messages", target="messages", stream=True) + assert result is raw and not seen + assert result.headers["X-Provider"] == "native" + assert result.get_data() == b'data: {"_multillm":{"unreviewed":true}}\n\n' + + +@pytest.mark.parametrize("protocol", ["chat", "messages", "responses"]) +def test_same_protocol_managed_hook_rejects_unknown_namespace(protocol): + request = body(protocol, {}) + request["_multillm"]["unreviewed"] = True + with pytest.raises(translation.TranslationError): + extras.translate_managed_request(request, protocol, protocol) + + +def test_native_managed_body_without_extras_keeps_existing_controls(): + request = {"model": "m", "input": "private", "previous_response_id": "existing"} + assert extras.translate_managed_request(request, "responses", "responses") == request + + +def test_invalid_flag_logs_once_without_value(monkeypatch, caplog): + monkeypatch.setattr(extras, "_warned", False) + monkeypatch.setenv("PROTOCOL_EXTRAS_ENABLED", "private-invalid") + assert extras.enabled() is False and extras.enabled() is False + assert len([r for r in caplog.records if "PROTOCOL_EXTRAS_ENABLED" in r.message]) == 1 + assert "private-invalid" not in caplog.text + + +def test_fidelity_reports_retention_and_egress_loss_without_values(): + ir = extras.request_to_ir(body(), "messages") + retained = extras.extras_report(ir.extras, "messages", admitted_fields={"top_k"}) + foreign = extras.extras_report(ir.extras, "responses", admitted_fields={"top_k"}) + denied = extras.extras_report(ir.extras, "messages") + assert retained["fidelity"] == "exact" + assert foreign["fidelity"] == denied["fidelity"] == "lossy" + assert foreign["fields"][0]["retained_in_ir"] is True + assert foreign["fields"][0]["re_emitted"] is False + assert "private" not in json.dumps(foreign) + assert "7" not in json.dumps(foreign) + + +def test_provider_admission_rejects_required_missing_semantics(): + ir = extras.request_to_ir(body(), "messages") + with pytest.raises(translation.TranslationError): + extras.request_from_ir(ir, "responses", required_fields={"top_k"}) + with pytest.raises(translation.TranslationError): + extras.request_from_ir(ir, "messages", required_fields={"top_k"}) + assert extras.request_from_ir(ir, "messages", admitted_fields={"top_k"}, + required_fields={"top_k"})["top_k"] == 7 + + +@pytest.mark.parametrize("protocol,fields", [ + ("messages", {"container": "private"}), + ("responses", {"previous_response_id": "private"}), +]) +def test_lifecycle_body_controls_still_fail(protocol, fields): + request = body(protocol, {}) + request.update(fields) + with pytest.raises(translation.TranslationError): + extras.request_to_ir(request, protocol) + + +def test_response_round_trip_preserves_native_stop_sequence_and_usage(): + native = {"id": "msg_1", "type": "message", "model": "m", "role": "assistant", + "content": [{"type": "text", "text": "answer"}], "stop_reason": "stop_sequence", + "stop_sequence": "END", "usage": {"input_tokens": 4, "output_tokens": 2}} + ir = extras.response_to_ir(native, "messages") + foreign = extras.response_from_ir(ir, "responses", admitted_fields={"stop_sequence"}) + assert "stop_sequence" not in foreign + same = extras.response_from_ir(ir, "messages", admitted_fields={"stop_sequence"}) + assert same["stop_sequence"] == "END" + assert same["usage"]["input_tokens"] == 4 + assert "_multillm" not in same + + +def test_response_namespace_is_never_trusted(): + with pytest.raises(translation.UpstreamFailure): + extras.response_to_ir({**CHAT_COMPLETION, "_multillm": { + "protocol_extras": {"source_protocol": "messages", "fields": {"stop_sequence": "END"}}}}, "chat") + + +def test_small_translator_call_sites_validate_and_strip_enabled_namespace(): + for protocol in ("messages", "responses"): + request = body(protocol, {"top_k": 7} if protocol == "messages" else {"truncation": "disabled"}) + converted = translation.translate_request(request, protocol, "chat") + assert "_multillm" not in converted + request["_multillm"]["private-unknown"] = True + with pytest.raises(translation.TranslationError): + translation.translate_request(request, protocol, "chat") + + +def test_managed_report_labels_same_source_and_foreign_source(): + report = extras.managed_request_report(body(), "messages", "messages", admitted_fields={"top_k"}) + assert report["fidelity"] == "exact" + assert report["fields"][0]["re_emitted"] is True + report = extras.managed_request_report(body(), "messages", "responses") + field = next(f for f in report["fields"] if f["path"] == "request.protocol_extras.top_k") + assert field["classification"] == "lossy" and field["retained_in_ir"] is True + assert "private" not in json.dumps(report) + invalid = body() + invalid["_multillm"]["private-unknown"] = True + assert extras.managed_request_report(invalid, "messages", "messages")["fidelity"] == "unsupported" + + +def test_extras_do_not_override_conflicting_body_fields(): + request = {**body(), "top_k": 9} + with pytest.raises(translation.TranslationError): + extras.request_to_ir(request, "messages") + + +def test_response_bridge_reports_reviewed_extras_loss(): + bridge = importlib.import_module("routes.protocol_bridge") + unified_bridge = importlib.import_module("routes.unified_bridge") + app = Flask(__name__) + native = {**CHAT_COMPLETION, "system_fingerprint": "fp_1"} + seen = [] + with app.test_request_context(headers={"X-MultiLLM-Conversion-Report": "1"}), \ + patch.object(unified_bridge, "record_conversion", side_effect=seen.append): + result = bridge.translate_downstream_response( + Response(json.dumps(native), content_type="application/json"), + source="chat", target="messages", stream=False) + assert result.status_code == 200 + assert "system_fingerprint" not in result.json + field = next(f for f in seen[0]["fields"] if f["path"] == "response.protocol_extras.system_fingerprint") + assert field["retained_in_ir"] is True and field["re_emitted"] is False + + +def test_prompt_cache_usage_glue_still_works_when_extras_enabled(monkeypatch): + monkeypatch.setenv("PROMPT_CACHE_USAGE_BUCKETS_ENABLED", "true") + monkeypatch.setenv("PROMPT_CACHE_PRICE_METADATA_JSON", "") + native = {"type": "message", "content": [], "usage": { + "input_tokens": 4, "cache_read_input_tokens": 3, + "cache_creation_input_tokens": 2, "output_tokens": 1}} + ir = extras.response_to_ir(native, "messages") + assert ir.body["usage"]["prompt_tokens"] == 9 + same = extras.response_from_ir(ir, "messages") + assert same["usage"]["cache_read_input_tokens"] == 3 + assert same["usage"]["cache_creation_input_tokens"] == 2 + + +class TestManagedExtrasRoutes(UnifiedApiTestCase): + def setUp(self): + self.loader = patch("env_loader.load_runtime_env") + self.loader.start() + self.addCleanup(self.loader.stop) + with patch("config.load_runtime_env"): + super().setUp() + self.http_patch = patch.object(self.app_module.ProxyService, "make_request", + side_effect=AssertionError("unexpected provider call")) + self.http = self.http_patch.start() + self.addCleanup(self.http_patch.stop) + + def test_registered_messages_rejects_namespace_before_dispatch(self): + request = body() + request["_multillm"]["private-unknown"] = True + result = self.client.post("/v1/messages", json=request, + headers={"Authorization": "Bearer admin-test-key"}) + assert result.status_code == 400 + assert "private-unknown" not in result.get_data(as_text=True) + self.http.assert_not_called() + + def test_registered_messages_keeps_metadata_out_of_provider_body(self): + self.http.side_effect = None + self.http.return_value = json_upstream(CHAT_COMPLETION) + result = self.client.post("/v1/messages", json=body(), + headers={"Authorization": "Bearer admin-test-key", + "X-MultiLLM-Conversion-Report": "1"}) + assert result.status_code == 200 + sent = json.loads(self.http.call_args.kwargs["data"]) + assert "_multillm" not in sent and "top_k" not in sent + assert result.headers["X-MultiLLM-Conversion-Fidelity"] == "lossy" + assert "private" not in str(result.headers) diff --git a/worker/container-env.mjs b/worker/container-env.mjs index 241cf668..9cbeb9ef 100644 --- a/worker/container-env.mjs +++ b/worker/container-env.mjs @@ -65,6 +65,7 @@ const DIRECT_ENV_KEYS = [ "PROMPT_CACHE_ENABLED", "PROMPT_CACHE_USAGE_BUCKETS_ENABLED", "PROMPT_CACHE_PRICE_METADATA_JSON", + "PROTOCOL_EXTRAS_ENABLED", "TOOL_CALL_REPAIR_DEFAULT", "PROMPT_CACHE_MIN_TOKENS", "PROMPT_TEMPLATES_ENABLED",