ctxoptimizer 0.4.1__py3-none-any.whl

ctxoptimizer/routing.py

@@ -0,0 +1,259 @@
+"""Request classification and upstream selection (SPEC section 8).
+
+Pure functions: no Starlette, no I/O. Given method/path/query/headers and the
+config, produce a :class:`Route` describing where the request goes and how it
+should be treated. The server layer decides what to do with it.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from ctxoptimizer.config import Config
+from ctxoptimizer.models import Endpoint, Mode, Provider
+from ctxoptimizer.profiles import (
+    ResolvedUpstream,
+    UnknownUpstream,
+    UpstreamProfile,
+    resolve_upstream,
+)
+
+ADMIN_PREFIX = "/_ctxoptimizer"
+PROJECT_PREFIX = "/p/"
+UPSTREAM_PREFIX = "/u/"
+
+_MODE_HEADERS = ("x-ctxoptimizer-mode", "x-ctxoptimizer-bypass")
+_LOOPBACK_MODES = frozenset({"passthrough", "shadow", "active"})
+
+
+@dataclass(frozen=True, slots=True)
+class Route:
+    """Where one request is forwarded and how it is classified."""
+
+    provider: Provider
+    endpoint: Endpoint
+    upstream_name: str
+    upstream_base: str
+    profile: UpstreamProfile
+    path: str
+    query: str
+    project: str | None
+    mode: Mode
+    session_id: str
+    client_name: str | None
+
+    def upstream_url(self) -> str:
+        """Build the absolute upstream URL, preserving path and raw query."""
+        base = self.upstream_base.rstrip("/")
+        path = self.path if self.path.startswith("/") else f"/{self.path}"
+        if self.query:
+            return f"{base}{path}?{self.query}"
+        return f"{base}{path}"
+
+
+def is_absolute_target(raw_target: str) -> bool:
+    """Return True for absolute-form request targets (SEC-11)."""
+    lowered = raw_target.lower()
+    return lowered.startswith("http://") or lowered.startswith("https://")
+
+
+def classify(
+    method: str,
+    path: str,
+    query: str,
+    headers: Mapping[str, str],
+    config: Config,
+) -> Route:
+    """Classify one request. Raises UnknownUpstream for unknown ``/u/`` names."""
+    lowered = {name.lower(): value for name, value in headers.items()}
+    project = lowered.get("x-ctxoptimizer-project") or None
+    remaining = path
+
+    if remaining.startswith(PROJECT_PREFIX):
+        project_part, _, tail = remaining[len(PROJECT_PREFIX) :].partition("/")
+        if project_part:
+            project = project or project_part
+            remaining = f"/{tail}"
+
+    if remaining.startswith(UPSTREAM_PREFIX):
+        name, _, tail = remaining[len(UPSTREAM_PREFIX) :].partition("/")
+        if not name:
+            raise UnknownUpstream("missing upstream name after /u/")
+        upstream = resolve_upstream(name, config)
+        remaining = _normalise_path(tail)
+        provider, endpoint = _detect_for_kind(upstream.profile.kind, method, remaining, lowered)
+        return _route(
+            provider=provider,
+            endpoint=endpoint,
+            upstream=upstream,
+            path=remaining,
+            query=query,
+            project=project,
+            headers=lowered,
+            config=config,
+        )
+
+    provider, endpoint, upstream_name = detect(method, remaining, lowered)
+    upstream = resolve_upstream(upstream_name, config)
+    return _route(
+        provider=provider,
+        endpoint=endpoint,
+        upstream=upstream,
+        path=remaining,
+        query=query,
+        project=project,
+        headers=lowered,
+        config=config,
+    )
+
+
+def detect(method: str, path: str, headers: Mapping[str, str]) -> tuple[Provider, Endpoint, str]:
+    """Auto-detect provider/endpoint from the path (SPEC section 8.2)."""
+    if _is_anthropic_messages(path, method):
+        return Provider.ANTHROPIC, Endpoint.MESSAGES, Provider.ANTHROPIC.value
+    if _is_anthropic_passthrough(path):
+        return Provider.ANTHROPIC, Endpoint.PASSTHROUGH, Provider.ANTHROPIC.value
+    if _is_openai_chat(path, method):
+        return Provider.OPENAI, Endpoint.CHAT, Provider.OPENAI.value
+    if _is_openai_responses(path, method):
+        return Provider.OPENAI, Endpoint.RESPONSES, Provider.OPENAI.value
+    if _is_openai_passthrough(path, method):
+        return Provider.OPENAI, Endpoint.PASSTHROUGH, Provider.OPENAI.value
+    if _is_gemini(path, method):
+        return Provider.GEMINI, Endpoint.GENERATE, Provider.GEMINI.value
+    if _is_ollama(path, method):
+        endpoint = Endpoint.CHAT if path.endswith("/chat") else Endpoint.GENERATE
+        return Provider.OLLAMA, endpoint, Provider.OLLAMA.value
+    if path.startswith("/v1/models"):
+        anthropic = "anthropic-version" in headers or "x-api-key" in headers
+        provider = Provider.ANTHROPIC if anthropic else Provider.OPENAI
+        return provider, Endpoint.PASSTHROUGH, provider.value
+    return Provider.OPENAI, Endpoint.PASSTHROUGH, Provider.OPENAI.value
+
+
+def _detect_for_kind(
+    kind: str | None, method: str, path: str, headers: Mapping[str, str]
+) -> tuple[Provider, Endpoint]:
+    if kind == "anthropic":
+        provider = Provider.ANTHROPIC
+        if _is_anthropic_messages(path, method):
+            return provider, Endpoint.MESSAGES
+        return provider, Endpoint.PASSTHROUGH
+    if kind == "openai":
+        provider = Provider.OPENAI
+        if _is_openai_chat(path, method):
+            return provider, Endpoint.CHAT
+        if _is_openai_responses(path, method):
+            return provider, Endpoint.RESPONSES
+        return provider, Endpoint.PASSTHROUGH
+    if kind == "gemini":
+        return Provider.GEMINI, Endpoint.GENERATE
+    if kind == "ollama":
+        endpoint = Endpoint.CHAT if path.endswith("/chat") else Endpoint.GENERATE
+        return Provider.OLLAMA, endpoint
+    provider, endpoint, _ = detect(method, path, headers)
+    return provider, endpoint
+
+
+def _route(
+    *,
+    provider: Provider,
+    endpoint: Endpoint,
+    upstream: ResolvedUpstream,
+    path: str,
+    query: str,
+    project: str | None,
+    headers: Mapping[str, str],
+    config: Config,
+) -> Route:
+    return Route(
+        provider=provider,
+        endpoint=endpoint,
+        upstream_name=upstream.name,
+        upstream_base=upstream.url,
+        profile=upstream.profile,
+        path=path,
+        query=query,
+        project=project,
+        mode=_mode(headers, config),
+        session_id=headers.get("x-ctxoptimizer-session", ""),
+        client_name=_client_name(headers.get("user-agent", "")),
+    )
+
+
+def _mode(headers: Mapping[str, str], config: Config) -> Mode:
+    bypass = headers.get("x-ctxoptimizer-bypass", "").lower()
+    if bypass in {"1", "true", "yes"}:
+        return Mode.PASSTHROUGH
+    requested = headers.get("x-ctxoptimizer-mode", "").lower()
+    if requested in _LOOPBACK_MODES:
+        return Mode(requested)
+    return Mode(config.mode.default)
+
+
+def _client_name(user_agent: str) -> str | None:
+    lowered = user_agent.lower()
+    if "claude" in lowered:
+        return "claude-code"
+    if "aider" in lowered:
+        return "aider"
+    if "opencode" in lowered:
+        return "opencode"
+    if "codex" in lowered:
+        return "codex"
+    if "openai" in lowered:
+        return "openai-sdk"
+    if "anthropic" in lowered:
+        return "anthropic-sdk"
+    if "httpx" in lowered:
+        return "python-httpx"
+    return None
+
+
+def _normalise_path(tail: str) -> str:
+    if not tail:
+        return "/"
+    return tail if tail.startswith("/") else f"/{tail}"
+
+
+def _is_anthropic_messages(path: str, method: str) -> bool:
+    return method == "POST" and path.rstrip("/").endswith("/messages")
+
+
+def _is_anthropic_passthrough(path: str) -> bool:
+    return (
+        "/messages/count_tokens" in path
+        or "/messages/batches" in path
+        or "/files" in path
+        or "/skills" in path
+    )
+
+
+def _is_openai_chat(path: str, method: str) -> bool:
+    return method == "POST" and path.rstrip("/").endswith("/chat/completions")
+
+
+def _is_openai_responses(path: str, method: str) -> bool:
+    return method == "POST" and path.rstrip("/").endswith("/responses")
+
+
+def _is_openai_passthrough(path: str, method: str) -> bool:
+    if method != "POST":
+        return False
+    return any(
+        path.rstrip("/").endswith(suffix) for suffix in ("/embeddings", "/moderations")
+    ) or any(segment in path for segment in ("/audio/", "/images/"))
+
+
+def _is_gemini(path: str, method: str) -> bool:
+    return method == "POST" and (":generateContent" in path or ":streamGenerateContent" in path)
+
+
+def _is_ollama(path: str, method: str) -> bool:
+    if method != "POST":
+        return False
+    return path.rstrip("/").endswith("/api/chat") or path.rstrip("/").endswith("/api/generate")
+
+
+__all__ = ["Route", "UnknownUpstream", "classify", "detect", "is_absolute_target"]

ctxoptimizer/server.py

@@ -0,0 +1,319 @@
+"""Starlette application, ingress and health endpoint (SPEC section 4.2).
+
+P1-1 wires classification and health. The forwarding core is injected, so the
+server can be tested without a live upstream and P1-2 can supply the real one.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import AsyncIterator, Awaitable, Callable
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+import httpx
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+from starlette.routing import Route as StarletteRoute
+
+from ctxoptimizer import __version__
+from ctxoptimizer.admin_security import AdminSecurityMiddleware, admin_credentials
+from ctxoptimizer.analysis.state import AnalysisState
+from ctxoptimizer.config import Config, data_dir
+from ctxoptimizer.dashboard.api import (
+    admin_config,
+    apply_recommendation,
+    dismiss_recommendation,
+    drift,
+    expand_usage,
+    export,
+    guard_action,
+    guard_status,
+    live,
+    purge,
+    put_pricing,
+    recent_requests,
+    recommendations_api,
+    reload,
+    request_detail,
+    request_diff,
+    session_detail,
+    set_mode,
+    stale_estimate,
+    summary,
+    timeseries,
+    transform_stats,
+    update_config,
+    waste,
+    waste_status,
+)
+from ctxoptimizer.dashboard.api import (
+    pricing as pricing_api,
+)
+from ctxoptimizer.dashboard.api import (
+    sessions as sessions_api,
+)
+from ctxoptimizer.dashboard.api import (
+    transforms as transforms_api,
+)
+from ctxoptimizer.dashboard.views import (
+    doctor_view,
+    live_view,
+    overview,
+    pricing_view,
+    request_view,
+    requests_view,
+    session_view,
+    sessions_view,
+    settings_view,
+    transforms_view,
+    waste_view,
+)
+from ctxoptimizer.guard import Guard
+from ctxoptimizer.routing import Route, UnknownUpstream, classify, is_absolute_target
+from ctxoptimizer.telemetry.blobs import BlobStore
+from ctxoptimizer.telemetry.store import Store, default_db_path
+from ctxoptimizer.transforms.cache_serve import CacheServeState
+
+Forwarder = Callable[[Request, Route, Config], Awaitable[Response]]
+
+_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]
+
+
+def create_app(
+    config: Config,
+    forwarder: Forwarder | None = None,
+    *,
+    config_path: Path | None = None,
+) -> Starlette:
+    """Build the ASGI app. ``forwarder`` overrides the real proxy core in tests."""
+
+    @asynccontextmanager
+    async def lifespan(app: Starlette) -> AsyncIterator[None]:
+        app.state.client = _make_client(config)
+        app.state.store = _make_store(config)
+        app.state.blobs = _make_blobs(config)
+        if app.state.store is not None:
+            app.state.guard.bind_store(app.state.store)
+        try:
+            yield
+        finally:
+            await app.state.client.aclose()
+            if app.state.store is not None:
+                app.state.store.close()
+
+    async def health(request: Request) -> Response:
+        state = request.app.state
+        current = state.config
+        counters = state.counters
+        last = state.last_request or {}
+        usage = last.get("usage")
+        store = getattr(state, "store", None)
+        return JSONResponse(
+            {
+                "status": "ok",
+                "version": __version__,
+                "mode": current.mode.default,
+                "uptime_s": round(time.monotonic() - state.started, 3),
+                "upstreams": sorted(current.upstreams),
+                "capture_payloads": current.telemetry.capture_payloads,
+                "requests": counters["requests"],
+                "completed": counters["completed"],
+                "client_disconnect": counters["client_disconnect"],
+                "upstream_errors": counters["upstream_errors"],
+                "dropped_telemetry": (
+                    store.stats()["dropped_events"]
+                    if store is not None
+                    else counters["dropped_telemetry"]
+                ),
+                "stored_requests": (store.count_requests() if store is not None else 0),
+                "last_model": last.get("model"),
+                "last_cost_usd": last.get("cost_usd"),
+                "last_priced": last.get("priced", False),
+                "last_usage_source": getattr(usage, "source", None),
+                "last_mutated": last.get("mutated", False),
+                "last_fallback": last.get("fallback_used", False),
+                "last_transforms": last.get("transform_ids", []),
+                "last_drift": last.get("drift"),
+                "last_marker_coverage": (last.get("marker_quality") or {}).get("coverage"),
+                "findings": (
+                    len(state.analysis.findings())
+                    if getattr(state, "analysis", None) is not None
+                    else 0
+                ),
+                "blob_count": (
+                    state.blobs.count() if getattr(state, "blobs", None) is not None else 0
+                ),
+            }
+        )
+
+    async def handler(request: Request) -> Response:
+        raw_target = request.scope.get("raw_path", b"").decode("latin-1")
+        if is_absolute_target(raw_target):
+            return JSONResponse(
+                {"error": "absolute-form request targets are not supported"},
+                status_code=400,
+            )
+        path = request.url.path
+        if path.startswith("/_ctxoptimizer"):
+            return JSONResponse({"error": "not found"}, status_code=404)
+        current = request.app.state.config
+        try:
+            route = classify(request.method, path, request.url.query, request.headers, current)
+        except UnknownUpstream as exc:
+            return JSONResponse({"error": str(exc)}, status_code=404)
+        except ValueError as exc:
+            return JSONResponse({"error": str(exc)}, status_code=400)
+        active = forwarder or _default_forwarder
+        return await active(request, route, current)
+
+    app = Starlette(
+        routes=[
+            StarletteRoute("/_ctxoptimizer/health", health, methods=["GET"]),
+            StarletteRoute("/_ctxoptimizer/api/health", health, methods=["GET"]),
+            StarletteRoute("/_ctxoptimizer", overview, methods=["GET"]),
+            StarletteRoute("/_ctxoptimizer/", overview, methods=["GET"]),
+            StarletteRoute("/_ctxoptimizer/api/summary", summary, methods=["GET"]),
+            StarletteRoute("/_ctxoptimizer/api/requests", recent_requests, methods=["GET"]),
+            StarletteRoute("/_ctxoptimizer/api/waste", waste, methods=["GET"]),
+            StarletteRoute("/_ctxoptimizer/api/recommend", recommendations_api, methods=["GET"]),
+            StarletteRoute("/_ctxoptimizer/api/sessions", sessions_api, methods=["GET"]),
+            StarletteRoute(
+                "/_ctxoptimizer/api/sessions/{session_id}", session_detail, methods=["GET"]
+            ),
+            StarletteRoute(
+                "/_ctxoptimizer/api/requests/{request_id}", request_detail, methods=["GET"]
+            ),
+            StarletteRoute("/_ctxoptimizer/api/transforms", transforms_api, methods=["GET"]),
+            StarletteRoute("/_ctxoptimizer/api/pricing", pricing_api, methods=["GET"]),
+            StarletteRoute("/_ctxoptimizer/api/pricing", put_pricing, methods=["PUT"]),
+            StarletteRoute("/_ctxoptimizer/api/guard", guard_status, methods=["GET"]),
+            StarletteRoute("/_ctxoptimizer/api/guard", guard_action, methods=["POST"]),
+            StarletteRoute("/_ctxoptimizer/api/config", admin_config, methods=["GET"]),
+            StarletteRoute("/_ctxoptimizer/api/config", update_config, methods=["POST"]),
+            StarletteRoute("/_ctxoptimizer/api/reload", reload, methods=["POST"]),
+            StarletteRoute("/_ctxoptimizer/api/mode", set_mode, methods=["POST"]),
+            StarletteRoute("/_ctxoptimizer/api/purge", purge, methods=["POST"]),
+            StarletteRoute("/_ctxoptimizer/api/export", export, methods=["GET"]),
+            StarletteRoute("/_ctxoptimizer/api/timeseries", timeseries, methods=["GET"]),
+            StarletteRoute(
+                "/_ctxoptimizer/api/stale-elision/estimate",
+                stale_estimate,
+                methods=["GET"],
+            ),
+            StarletteRoute("/_ctxoptimizer/api/drift", drift, methods=["GET"]),
+            StarletteRoute("/_ctxoptimizer/api/expand/stats", expand_usage, methods=["GET"]),
+            StarletteRoute("/_ctxoptimizer/api/transforms/stats", transform_stats, methods=["GET"]),
+            StarletteRoute(
+                "/_ctxoptimizer/api/requests/{request_id}/diff",
+                request_diff,
+                methods=["GET"],
+            ),
+            StarletteRoute("/_ctxoptimizer/api/live", live, methods=["GET"]),
+            StarletteRoute(
+                "/_ctxoptimizer/api/waste/{finding_id}/status",
+                waste_status,
+                methods=["POST"],
+            ),
+            StarletteRoute(
+                "/_ctxoptimizer/api/recommend/{recommendation_id}/apply",
+                apply_recommendation,
+                methods=["POST"],
+            ),
+            StarletteRoute(
+                "/_ctxoptimizer/api/recommend/{recommendation_id}/dismiss",
+                dismiss_recommendation,
+                methods=["POST"],
+            ),
+            StarletteRoute("/_ctxoptimizer/waste", waste_view, methods=["GET"]),
+            StarletteRoute("/_ctxoptimizer/live", live_view, methods=["GET"]),
+            StarletteRoute("/_ctxoptimizer/sessions", sessions_view, methods=["GET"]),
+            StarletteRoute("/_ctxoptimizer/sessions/{session_id}", session_view, methods=["GET"]),
+            StarletteRoute("/_ctxoptimizer/requests", requests_view, methods=["GET"]),
+            StarletteRoute("/_ctxoptimizer/requests/{request_id}", request_view, methods=["GET"]),
+            StarletteRoute("/_ctxoptimizer/transforms", transforms_view, methods=["GET"]),
+            StarletteRoute("/_ctxoptimizer/pricing", pricing_view, methods=["GET"]),
+            StarletteRoute("/_ctxoptimizer/settings", settings_view, methods=["GET"]),
+            StarletteRoute("/_ctxoptimizer/doctor", doctor_view, methods=["GET"]),
+            StarletteRoute("/{path:path}", handler, methods=_METHODS),
+        ],
+        lifespan=lifespan,
+    )
+    app.state.config = config
+    app.state.config_path = config_path
+    app.state.started = time.monotonic()
+    admin_token, csrf_token = admin_credentials()
+    if config.server.admin_token:
+        admin_token = config.server.admin_token
+    app.state.admin_token = admin_token
+    app.state.csrf_token = csrf_token
+    app.add_middleware(
+        AdminSecurityMiddleware,
+        config=config,
+        admin_token=admin_token,
+        csrf_token=csrf_token,
+    )
+    app.state.analysis = AnalysisState()
+    app.state.guard = Guard(config)
+    app.state.cache_serve = CacheServeState(
+        config.transforms.cache_serve.max_state_sessions,
+        config.transforms.cache_serve.max_entries_per_session,
+    )
+    app.state.counters = {
+        "requests": 0,
+        "completed": 0,
+        "client_disconnect": 0,
+        "upstream_error": 0,
+        "upstream_errors": 0,
+        "dropped_telemetry": 0,
+    }
+    app.state.last_request = None
+    return app
+
+
+async def _default_forwarder(request: Request, route: Route, config: Config) -> Response:
+    from ctxoptimizer.proxy import forward
+
+    return await forward(request, route, config)
+
+
+def _make_client(config: Config) -> httpx.AsyncClient:
+    http = config.http
+    timeout = httpx.Timeout(
+        connect=http.connect_timeout_s,
+        read=None if http.read_timeout_s == 0 else http.read_timeout_s,
+        write=http.write_timeout_s,
+        pool=http.pool_timeout_s,
+    )
+    return httpx.AsyncClient(
+        http2=http.http2,
+        trust_env=True,
+        follow_redirects=False,
+        timeout=timeout,
+        limits=httpx.Limits(max_connections=http.max_connections),
+    )
+
+
+def _make_store(config: Config) -> Store | None:
+    try:
+        path = Path(config.telemetry.db_path) if config.telemetry.db_path else default_db_path()
+        return Store(
+            path,
+            queue_max=config.telemetry.writer_queue_max,
+            retention_days=config.telemetry.retention_days,
+        )
+    except Exception:
+        return None
+
+
+def _make_blobs(config: Config) -> BlobStore | None:
+    if config.telemetry.capture_payloads == "off":
+        return None
+    try:
+        return BlobStore(data_dir() / "blobs")
+    except Exception:
+        return None
+
+
+__all__ = ["Forwarder", "create_app"]