superlocalmemory 3.5.7 → 3.6.0

package/src/superlocalmemory/optimize/proxy/anthropic_surface.py

@@ -0,0 +1,171 @@
+"""anthropic_surface.py — Anthropic Messages + count_tokens + models surfaces."""
+
+from __future__ import annotations
+
+import json
+import logging
+
+from fastapi.requests import Request
+from fastapi.responses import Response
+
+from superlocalmemory.optimize.proxy._helpers import (
+    _ANTHROPIC_FORWARD_HEADERS,
+    _MAX_REQUEST_BODY_BYTES,
+    _body_has_tools,
+    _build_forward_headers,
+    _fail_open_forward,
+    _filter_response_headers,
+    _redact_headers,
+    _safe_cache_check,
+    _safe_cache_hit_callbacks,
+    _safe_cache_store,
+    _stream_forward,
+)
+from superlocalmemory.optimize.proxy.lifecycle import ProviderResponse, ProxyRequest
+
+logger = logging.getLogger("slm.optimize.proxy.anthropic")
+
+_UPSTREAM_BASE = "https://api.anthropic.com"
+
+
+async def handle_messages(proxy: object, request: Request) -> Response:
+    request_id = await proxy.next_request_id()
+    upstream_url = f"{_UPSTREAM_BASE}/v1/messages"
+
+    cl_header = request.headers.get("content-length")
+    if cl_header is not None:
+        try:
+            if int(cl_header) > _MAX_REQUEST_BODY_BYTES:
+                return Response(
+                    content=b'{"type":"error","error":{"type":"invalid_request_error",'
+                            b'"message":"Request body too large (max 10 MB)"}}',
+                    status_code=413,
+                    media_type="application/json",
+                )
+        except ValueError:
+            pass
+
+    try:
+        body_bytes = await request.body()
+        if len(body_bytes) > _MAX_REQUEST_BODY_BYTES:
+            return Response(
+                content=b'{"type":"error","error":{"type":"invalid_request_error",'
+                        b'"message":"Request body too large (max 10 MB)"}}',
+                status_code=413,
+                media_type="application/json",
+            )
+
+        try:
+            body = json.loads(body_bytes)
+        except json.JSONDecodeError as exc:
+            logger.warning("[%s] body parse failed, raw forward: %s", request_id, exc)
+            return await _fail_open_forward(proxy, request, upstream_url)
+
+        stream = bool(body.get("stream", False))
+        has_tools = _body_has_tools(body)
+        ctx = ProxyRequest(
+            provider="anthropic",
+            method="POST",
+            path="/v1/messages",
+            headers=_redact_headers(dict(request.headers)),
+            body=body,
+            body_bytes=body_bytes,
+            request_id=request_id,
+            stream=stream,
+            has_tools=has_tools,
+        )
+
+        if stream:
+            fwd_headers = _build_forward_headers(request, _ANTHROPIC_FORWARD_HEADERS)
+            fwd_headers["content-length"] = str(len(body_bytes))
+            return await _stream_forward(
+                proxy, request_id, fwd_headers, body_bytes, upstream_url
+            )
+
+        cache_result = None
+        if not has_tools and proxy.hooks.cache:
+            cache_result = await _safe_cache_check(proxy.hooks, ctx)
+            if cache_result.hit and cache_result.data:
+                logger.debug("[%s] cache HIT key=%s", request_id, cache_result.cache_key)
+                await _safe_cache_hit_callbacks(
+                    proxy.hooks, ctx, cache_result.data, tokens_saved=0
+                )
+                return Response(
+                    content=cache_result.data,
+                    status_code=200,
+                    media_type="application/json",
+                )
+
+        outbound_bytes = body_bytes
+        if proxy.hooks.compress:
+            compress_result = await _safe_compress(proxy.hooks, ctx)
+            if compress_result.body_bytes != body_bytes:
+                outbound_bytes = compress_result.body_bytes
+
+        fwd_headers = _build_forward_headers(request, _ANTHROPIC_FORWARD_HEADERS)
+        fwd_headers["content-length"] = str(len(outbound_bytes))
+
+        upstream_resp = await proxy.http_client.post(
+            upstream_url, content=outbound_bytes, headers=fwd_headers,
+        )
+        resp_bytes = upstream_resp.content
+
+        if (
+            upstream_resp.status_code == 200
+            and not has_tools
+            and proxy.hooks.cache
+            and cache_result is not None
+            and cache_result.cache_key
+        ):
+            _prov_resp = ProviderResponse(
+                modified=False, body={}, body_bytes=resp_bytes,
+                tokens_before=0, tokens_after=0, strategy="none",
+            )
+            await _safe_cache_store(proxy.hooks, ctx, _prov_resp)
+
+        return Response(
+            content=resp_bytes,
+            status_code=upstream_resp.status_code,
+            media_type="application/json",
+            headers=_filter_response_headers(dict(upstream_resp.headers)),
+        )
+
+    except Exception as exc:
+        logger.error("[%s] handle_messages unhandled exc=%r — fail-open", request_id, exc)
+        return await _fail_open_forward(proxy, request, upstream_url)
+
+
+async def handle_count_tokens(proxy: object, request: Request) -> Response:
+    request_id = await proxy.next_request_id()
+    upstream_url = f"{_UPSTREAM_BASE}/v1/messages/count_tokens"
+    try:
+        body_bytes = await request.body()
+        fwd_headers = _build_forward_headers(request, _ANTHROPIC_FORWARD_HEADERS)
+        fwd_headers["content-length"] = str(len(body_bytes))
+        upstream_resp = await proxy.http_client.post(
+            upstream_url, content=body_bytes, headers=fwd_headers,
+        )
+        return Response(
+            content=upstream_resp.content,
+            status_code=upstream_resp.status_code,
+            media_type="application/json",
+        )
+    except Exception as exc:
+        logger.error("[%s] handle_count_tokens exc=%r — fail-open", request_id, exc)
+        return await _fail_open_forward(proxy, request, upstream_url)
+
+
+async def handle_models(proxy: object, request: Request) -> Response:
+    request_id = await proxy.next_request_id()
+    upstream_url = f"{_UPSTREAM_BASE}/v1/models"
+    try:
+        fwd_headers = _build_forward_headers(request, _ANTHROPIC_FORWARD_HEADERS)
+        upstream_resp = await proxy.http_client.get(upstream_url, headers=fwd_headers)
+        return Response(
+            content=upstream_resp.content,
+            status_code=upstream_resp.status_code,
+            media_type="application/json",
+        )
+    except Exception as exc:
+        logger.error("[%s] handle_models exc=%r — fail-open", request_id, exc)
+        return await _fail_open_forward(proxy, request, upstream_url)

package/src/superlocalmemory/optimize/proxy/gemini_surface.py

@@ -0,0 +1,121 @@
+"""gemini_surface.py — Gemini native and OpenAI-compat surfaces."""
+
+from __future__ import annotations
+
+import logging
+import re
+import urllib.parse
+
+from fastapi.requests import Request
+from fastapi.responses import Response
+
+from superlocalmemory.optimize.proxy._helpers import (
+    _GEMINI_NATIVE_FORWARD_HEADERS,
+    _GEMINI_OPENAI_COMPAT_FORWARD_HEADERS,
+    _fail_open_forward,
+    _filter_response_headers,
+    _stream_forward,
+)
+
+logger = logging.getLogger("slm.optimize.proxy.gemini")
+
+_GEMINI_UPSTREAM_BASE = "https://generativelanguage.googleapis.com"
+
+# SSRF guard: accept BOTH `models/<name>:<method>` AND `<name>:<method>`
+# (FastAPI's `:path` converter may strip the `models/` segment depending on
+# route declaration; we normalize on the server side either way).
+_GEMINI_PATH_RE = re.compile(
+    r"^(?:models/)?[a-zA-Z0-9._\-]{1,128}:(generateContent|streamGenerateContent|countTokens)$"
+)
+
+_GEMINI_ALLOWED_QUERY_PARAMS = frozenset(["pagesize", "pagetoken"])
+
+
+def _validate_gemini_path(model_and_method: str) -> bool:
+    return bool(_GEMINI_PATH_RE.match(model_and_method))
+
+
+async def handle_gemini_native(
+    proxy: object,
+    request: Request,
+    model_and_method: str,
+) -> Response:
+    request_id = await proxy.next_request_id()
+
+    if not _validate_gemini_path(model_and_method):
+        logger.warning(
+            "[%s] handle_gemini_native: rejected invalid path param=%r (SSRF guard)",
+            request_id, model_and_method,
+        )
+        return Response(
+            content=b'{"error":{"code":400,"message":"Invalid model/method path",'
+                    b'"status":"INVALID_ARGUMENT"}}',
+            status_code=400,
+            media_type="application/json",
+        )
+
+    upstream_url = f"{_GEMINI_UPSTREAM_BASE}/v1beta/{model_and_method}"
+
+    try:
+        body_bytes = await request.body()
+        fwd_headers = {
+            k: v for k, v in request.headers.items()
+            if k.lower() in _GEMINI_NATIVE_FORWARD_HEADERS
+        }
+        fwd_headers["content-length"] = str(len(body_bytes))
+
+        stream = "streamGenerateContent" in model_and_method
+        if stream:
+            allowed = {
+                k: v for k, v in request.query_params.items()
+                if k.lower() in _GEMINI_ALLOWED_QUERY_PARAMS
+            }
+            allowed["alt"] = "sse"
+            upstream_url = f"{upstream_url}?{urllib.parse.urlencode(allowed)}"
+            return await _stream_forward(
+                proxy, request_id, fwd_headers, body_bytes, upstream_url
+            )
+
+        upstream_resp = await proxy.http_client.post(
+            upstream_url, content=body_bytes, headers=fwd_headers,
+        )
+        return Response(
+            content=upstream_resp.content,
+            status_code=upstream_resp.status_code,
+            media_type="application/json",
+            headers=_filter_response_headers(dict(upstream_resp.headers)),
+        )
+    except Exception as exc:
+        logger.error("[%s] handle_gemini_native exc=%r — fail-open", request_id, exc)
+        return await _fail_open_forward(proxy, request, upstream_url)
+
+
+async def handle_gemini_openai_compat(proxy: object, request: Request) -> Response:
+    local_path = request.url.path
+    upstream_url = f"{_GEMINI_UPSTREAM_BASE}{local_path}"
+    request_id = await proxy.next_request_id()
+    try:
+        body_bytes = await request.body()
+        fwd_headers = {
+            k: v for k, v in request.headers.items()
+            if k.lower() in _GEMINI_OPENAI_COMPAT_FORWARD_HEADERS
+        }
+        if body_bytes:
+            fwd_headers["content-length"] = str(len(body_bytes))
+        upstream_resp = await proxy.http_client.request(
+            method=request.method,
+            url=upstream_url,
+            content=body_bytes if body_bytes else None,
+            headers=fwd_headers,
+        )
+        return Response(
+            content=upstream_resp.content,
+            status_code=upstream_resp.status_code,
+            media_type="application/json",
+            headers=_filter_response_headers(dict(upstream_resp.headers)),
+        )
+    except Exception as exc:
+        logger.error(
+            "[%s] handle_gemini_openai_compat exc=%r — fail-open", request_id, exc
+        )
+        return await _fail_open_forward(proxy, request, upstream_url)

package/src/superlocalmemory/optimize/proxy/lifecycle.py

@@ -0,0 +1,126 @@
+"""lifecycle.py — Hook Protocol interfaces per INTERFACE-CONTRACT §3 (FROZEN).
+
+TYPE NAME CANONICAL RULE:
+  ProxyRequest   — request DTO
+  CachedResponse — cache hit/miss result
+  ProviderResponse — compress result / passthrough body
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from typing import Any, Protocol, runtime_checkable
+
+
+# ─── Data types ──────────────────────────────────────────────────────────────
+
+
+@dataclasses.dataclass(frozen=True)
+class ProxyRequest:
+    """Immutable request snapshot passed to every hook.
+
+    headers MUST be redacted before construction (CWE-532 guard).
+    """
+    provider: str
+    method: str
+    path: str
+    headers: dict
+    body: dict
+    body_bytes: bytes
+    request_id: str
+    stream: bool
+    has_tools: bool
+
+    def __repr__(self) -> str:
+        return (
+            f"ProxyRequest(provider={self.provider!r}, method={self.method!r}, "
+            f"path={self.path!r}, request_id={self.request_id!r}, "
+            f"stream={self.stream}, has_tools={self.has_tools})"
+        )
+
+
+@dataclasses.dataclass
+class CachedResponse:
+    """Cache check result."""
+    hit: bool
+    data: bytes | None
+    cache_key: str
+    ttl_seconds: int
+
+
+@dataclasses.dataclass
+class ProviderResponse:
+    """Compress-modified body container / passthrough body shape."""
+    modified: bool
+    body: dict
+    body_bytes: bytes
+    tokens_before: int
+    tokens_after: int
+    strategy: str
+
+
+# ─── Hook Protocols — INTERFACE-CONTRACT §3 ────────────────────────────────
+
+
+@runtime_checkable
+class CacheHook(Protocol):
+    def check(self, req: ProxyRequest) -> CachedResponse | None: ...
+    def store(self, req: ProxyRequest, resp: ProviderResponse) -> None: ...
+    def on_hit(self, req: ProxyRequest, resp: bytes, tokens_saved: int) -> None: ...
+    def on_miss(self, req: ProxyRequest) -> None: ...
+
+
+@runtime_checkable
+class CompressHook(Protocol):
+    def compress(self, req: ProxyRequest) -> ProxyRequest: ...
+    def on_compress(self, before_tokens: int, after_tokens: int, lossy: bool) -> None: ...
+
+
+@dataclasses.dataclass
+class HookChain:
+    cache: CacheHook | None = None
+    compress: CompressHook | None = None
+
+    @classmethod
+    def empty(cls) -> "HookChain":
+        return cls(cache=None, compress=None)
+
+
+# ─── Lifecycle exports (INTERFACE-CONTRACT v2.2) ───────────────────────────
+
+
+def ensure_proxy_running() -> bool:
+    """Ensure the proxy is configured AND alive (liveness probe).
+
+    Checks two conditions in order:
+    1. ``proxy_enabled`` is True in optimize.json (config gate).
+    2. The proxy HTTP server responds to GET /health within 1 second (liveness
+       gate).  This verifies that ProxyApp.startup() was actually called and
+       the httpx.AsyncClient is non-None — a detail the config flag alone
+       cannot confirm.
+
+    Returns True only when both gates pass, False otherwise.
+    """
+    try:
+        from superlocalmemory.optimize.config import get_optimize_config
+        cfg = get_optimize_config()
+        if not cfg.proxy_enabled:
+            return False
+    except Exception:
+        return False
+
+    # Liveness probe — confirm the daemon is actually listening.
+    try:
+        import urllib.request
+        port = proxy_port()
+        url = f"http://127.0.0.1:{port}/health"
+        req = urllib.request.Request(url, method="GET")
+        with urllib.request.urlopen(req, timeout=1) as resp:
+            return resp.status == 200
+    except Exception:
+        return False
+
+
+def proxy_port() -> int:
+    """Returns the proxy port (always 8765 — shared with SLM daemon)."""
+    return 8765

package/src/superlocalmemory/optimize/proxy/openai_surface.py

@@ -0,0 +1,125 @@
+"""openai_surface.py — OpenAI /v1/chat/completions and /v1/embeddings."""
+
+from __future__ import annotations
+
+import json
+import logging
+
+from fastapi.requests import Request
+from fastapi.responses import Response
+
+from superlocalmemory.optimize.proxy._helpers import (
+    _OPENAI_FORWARD_HEADERS,
+    _body_has_tools,
+    _build_forward_headers,
+    _fail_open_forward,
+    _filter_response_headers,
+    _redact_headers,
+    _safe_cache_check,
+    _safe_cache_hit_callbacks,
+    _safe_cache_store,
+    _stream_forward,
+)
+from superlocalmemory.optimize.proxy.lifecycle import ProviderResponse, ProxyRequest
+
+logger = logging.getLogger("slm.optimize.proxy.openai")
+
+_UPSTREAM_BASE = "https://api.openai.com"
+
+
+async def handle_chat_completions(proxy: object, request: Request) -> Response:
+    request_id = await proxy.next_request_id()
+    upstream_url = f"{_UPSTREAM_BASE}/v1/chat/completions"
+    try:
+        body_bytes = await request.body()
+        try:
+            body = json.loads(body_bytes)
+        except json.JSONDecodeError:
+            return await _fail_open_forward(proxy, request, upstream_url)
+
+        stream = bool(body.get("stream", False))
+        has_tools = _body_has_tools(body)
+        ctx = ProxyRequest(
+            provider="openai", method="POST", path="/v1/chat/completions",
+            headers=_redact_headers(dict(request.headers)),
+            body=body, body_bytes=body_bytes,
+            request_id=request_id, stream=stream, has_tools=has_tools,
+        )
+
+        if stream:
+            fwd_headers = _build_forward_headers(request, _OPENAI_FORWARD_HEADERS)
+            fwd_headers["content-length"] = str(len(body_bytes))
+            return await _stream_forward(
+                proxy, request_id, fwd_headers, body_bytes, upstream_url
+            )
+
+        cache_result = None
+        if not has_tools and proxy.hooks.cache:
+            cache_result = await _safe_cache_check(proxy.hooks, ctx)
+            if cache_result.hit and cache_result.data:
+                await _safe_cache_hit_callbacks(
+                    proxy.hooks, ctx, cache_result.data, 0
+                )
+                return Response(
+                    content=cache_result.data,
+                    status_code=200,
+                    media_type="application/json",
+                )
+
+        outbound_bytes = body_bytes
+        if proxy.hooks.compress:
+            compress_result = await _safe_compress(proxy.hooks, ctx)
+            if compress_result.body_bytes != body_bytes:
+                outbound_bytes = compress_result.body_bytes
+
+        fwd_headers = _build_forward_headers(request, _OPENAI_FORWARD_HEADERS)
+        fwd_headers["content-length"] = str(len(outbound_bytes))
+
+        upstream_resp = await proxy.http_client.post(
+            upstream_url, content=outbound_bytes, headers=fwd_headers,
+        )
+        resp_bytes = upstream_resp.content
+
+        if (
+            upstream_resp.status_code == 200
+            and not has_tools
+            and proxy.hooks.cache
+            and cache_result is not None
+            and cache_result.cache_key
+        ):
+            _prov_resp = ProviderResponse(
+                modified=False, body={}, body_bytes=resp_bytes,
+                tokens_before=0, tokens_after=0, strategy="none",
+            )
+            await _safe_cache_store(proxy.hooks, ctx, _prov_resp)
+
+        return Response(
+            content=resp_bytes,
+            status_code=upstream_resp.status_code,
+            media_type="application/json",
+            headers=_filter_response_headers(dict(upstream_resp.headers)),
+        )
+
+    except Exception as exc:
+        logger.error("[%s] handle_chat_completions exc=%r — fail-open", request_id, exc)
+        return await _fail_open_forward(proxy, request, upstream_url)
+
+
+async def handle_embeddings(proxy: object, request: Request) -> Response:
+    request_id = await proxy.next_request_id()
+    upstream_url = f"{_UPSTREAM_BASE}/v1/embeddings"
+    try:
+        body_bytes = await request.body()
+        fwd_headers = _build_forward_headers(request, _OPENAI_FORWARD_HEADERS)
+        fwd_headers["content-length"] = str(len(body_bytes))
+        upstream_resp = await proxy.http_client.post(
+            upstream_url, content=body_bytes, headers=fwd_headers,
+        )
+        return Response(
+            content=upstream_resp.content,
+            status_code=upstream_resp.status_code,
+            media_type="application/json",
+        )
+    except Exception as exc:
+        logger.error("[%s] handle_embeddings exc=%r — fail-open", request_id, exc)
+        return await _fail_open_forward(proxy, request, upstream_url)

package/src/superlocalmemory/optimize/proxy/server.py

@@ -0,0 +1,151 @@
+"""server.py — ProxyApp and build_proxy_router()."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from typing import Any
+
+import httpx
+from fastapi import APIRouter
+from fastapi.requests import Request
+from fastapi.responses import Response
+
+from superlocalmemory.optimize.config.schema import OptimizeConfig
+from superlocalmemory.optimize.proxy.lifecycle import HookChain
+
+logger = logging.getLogger("slm.optimize.proxy")
+
+_PROXY_VERSION = "3.6.0"
+_REQUEST_TIMEOUT_S = 300.0
+_CONNECT_TIMEOUT_S = 10.0
+_MAX_CONNECTIONS = 100
+_MAX_KEEPALIVE = 20
+_MAX_REQUEST_BODY_BYTES = 10 * 1024 * 1024  # 10 MB
+
+
+class ProxyApp:
+    """Core proxy. Holds httpx client + hook chain.
+
+    Lifecycle:
+      create_app() → ProxyApp() → application.state.optimize_proxy = proxy
+      lifespan startup → await proxy.startup()
+      lifespan shutdown → await proxy.shutdown()
+    """
+
+    def __init__(self, config: OptimizeConfig) -> None:
+        self.config = config
+        self.hooks: HookChain = HookChain.empty()
+        self.http_client: httpx.AsyncClient | None = None
+        self._request_counter: int = 0
+        self._counter_lock = asyncio.Lock()
+
+    async def startup(self) -> None:
+        self.http_client = httpx.AsyncClient(
+            timeout=httpx.Timeout(
+                connect=_CONNECT_TIMEOUT_S,
+                read=_REQUEST_TIMEOUT_S,
+                write=_REQUEST_TIMEOUT_S,
+                pool=_CONNECT_TIMEOUT_S,
+            ),
+            limits=httpx.Limits(
+                max_connections=_MAX_CONNECTIONS,
+                max_keepalive_connections=_MAX_KEEPALIVE,
+            ),
+            follow_redirects=False,
+        )
+        self.hooks = _load_hooks(self.config)
+        logger.info(
+            "slm.optimize.proxy started version=%s port=8765 "
+            "cache_hook=%s compress_hook=%s",
+            _PROXY_VERSION,
+            type(self.hooks.cache).__name__ if self.hooks.cache else "None",
+            type(self.hooks.compress).__name__ if self.hooks.compress else "None",
+        )
+
+    async def shutdown(self) -> None:
+        if self.http_client:
+            await self.http_client.aclose()
+            self.http_client = None
+        logger.info("slm.optimize.proxy shut down")
+
+    async def next_request_id(self) -> str:
+        async with self._counter_lock:
+            self._request_counter += 1
+            return f"slm_{int(time.monotonic() * 1000)}_{self._request_counter:06d}"
+
+
+def build_proxy_router(proxy: ProxyApp) -> APIRouter:
+    """Build and return the FastAPI router for all proxy surfaces."""
+    from superlocalmemory.optimize.proxy.anthropic_surface import (
+        handle_count_tokens,
+        handle_messages,
+        handle_models,
+    )
+    from superlocalmemory.optimize.proxy.gemini_surface import (
+        handle_gemini_native,
+        handle_gemini_openai_compat,
+    )
+    from superlocalmemory.optimize.proxy.openai_surface import (
+        handle_chat_completions,
+        handle_embeddings,
+    )
+
+    router = APIRouter(tags=["slm-optimize-proxy"])
+
+    @router.post("/v1/messages")
+    async def messages_route(request: Request) -> Response:
+        return await handle_messages(proxy, request)
+
+    @router.post("/v1/messages/count_tokens")
+    async def count_tokens_route(request: Request) -> Response:
+        return await handle_count_tokens(proxy, request)
+
+    @router.get("/v1/models")
+    async def models_route(request: Request) -> Response:
+        return await handle_models(proxy, request)
+
+    @router.post("/v1/chat/completions")
+    async def chat_completions_route(request: Request) -> Response:
+        return await handle_chat_completions(proxy, request)
+
+    @router.post("/v1/embeddings")
+    async def embeddings_route(request: Request) -> Response:
+        return await handle_embeddings(proxy, request)
+
+    @router.post("/v1beta/models/{model_and_method:path}")
+    async def gemini_native_route(
+        request: Request, model_and_method: str
+    ) -> Response:
+        return await handle_gemini_native(proxy, request, model_and_method)
+
+    @router.post("/v1beta/openai/chat/completions")
+    async def gemini_openai_post_route(request: Request) -> Response:
+        return await handle_gemini_openai_compat(proxy, request)
+
+    @router.get("/v1beta/openai/models")
+    async def gemini_openai_models_route(request: Request) -> Response:
+        return await handle_gemini_openai_compat(proxy, request)
+
+    return router
+
+
+def _load_hooks(config: OptimizeConfig) -> HookChain:
+    cache_hook = None
+    compress_hook = None
+
+    if config.cache_enabled:
+        try:
+            from superlocalmemory.optimize.cache.manager import CacheManager
+            cache_hook = CacheManager.get_instance()
+        except Exception as exc:
+            logger.warning(
+                "cache hook load failed (proxy continues without cache): %s", exc
+            )
+
+    if config.compress_enabled:
+        # Compress is Phase 2; not wired in P1. P1 keeps the slot for the seam.
+        pass
+
+    return HookChain(cache=cache_hook, compress=compress_hook)