coding-client 1.21.2__py3-none-any.whl

coding_client/telemetry.py

@@ -0,0 +1,195 @@
+"""OpenTelemetry trace setup for coding-* services.
+
+One implementation, called once per service at **application-construction time**.
+
+Why this lives in the SDK rather than a per-repo ``telemetry.py``: the wider fleet
+copies a ``src/telemetry.py`` into every repo, and those copies drift. Three
+coding services each grew their own version of this block and **all three emitted
+nothing**, for three different reasons, for months — while logging that tracing
+was enabled.
+
+The trap that made them silent is the reason ``setup_tracing`` refuses rather than
+returns:
+
+    ``FastAPIInstrumentor.instrument_app(app)`` called inside a FastAPI lifespan
+    produces **zero spans and raises nothing**. By the time the lifespan runs,
+    Starlette has already built the middleware stack, so the instrumentation is
+    discarded silently.
+
+So a late call is a hard error here, named at the call site. Every other failure
+mode (no endpoint, SDK disabled, packages absent) is a quiet ``False`` — those are
+legitimate local/test configurations, and none of them can be mistaken for
+working tracing, because they emit no success log either.
+
+Configuration, matching the fleet convention already provisioned in
+``clusters/strato``:
+
+- ``OTLP_TRACES_ENDPOINT`` — full URL including ``/v1/traces``. Unset ⇒ no exporter.
+- ``OTEL_SDK_DISABLED`` — ``"true"`` ⇒ no tracing at all.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from fastapi import FastAPI
+
+logger = logging.getLogger(__name__)
+
+#: Probe and scrape paths, excluded so kubelet traffic does not dominate the
+#: trace store. Substring-matched by the instrumentation, not anchored.
+#: Nine services probed every ~10s would otherwise outweigh every real request
+#: the coding fleet serves.
+DEFAULT_EXCLUDED_URLS = "health,healthz,metrics,ready,readyz,live,livez"
+
+#: The single span attribute that carries the raw query string. Stripped so a
+#: future ``?token=`` parameter cannot reach the trace store. No coding-*
+#: route declares a sensitive query parameter today (105 scanned across the
+#: fleet); this keeps it that way by construction rather than by review.
+_URL_ATTRIBUTES = ("http.url", "url.full")
+
+
+def _strip_query(url: str) -> str:
+    """Drop everything from the first ``?``, keeping scheme/host/path."""
+    head, sep, _ = url.partition("?")
+    return head if sep else url
+
+
+def _server_request_hook(span: Any, scope: dict[str, Any]) -> None:
+    """Redact the query string from the server span while it is still writable.
+
+    Runs inside the instrumentation with a recording span, which is the only
+    point where these attributes can still be overwritten — once the span has
+    ended its attributes are frozen.
+    """
+    if span is None or not getattr(span, "is_recording", lambda: False)():
+        return
+    for key in _URL_ATTRIBUTES:
+        value = (span.attributes or {}).get(key)
+        if isinstance(value, str) and "?" in value:
+            span.set_attribute(key, _strip_query(value))
+
+
+def _already_started(app: FastAPI) -> bool:
+    """True once Starlette has built the middleware stack.
+
+    After that point ``instrument_app`` is a silent no-op, which is the exact
+    failure this module exists to make impossible.
+    """
+    return getattr(app, "middleware_stack", None) is not None
+
+
+def _instrument_httpx(provider: Any) -> bool:
+    """Instrument outbound httpx calls against ``provider``, best-effort.
+
+    Client spans are what Tempo's ``service_graphs`` processor turns into edges —
+    a server-span-only service appears in the graph as a node nothing points at.
+    This SDK's own outbound helpers use httpx, so instrumenting it here covers
+    every coding-to-coding call without per-service work.
+
+    ``HTTPXClientInstrumentor`` is a process-wide singleton that binds its tracer
+    at ``instrument()`` time, so the provider is passed explicitly rather than
+    resolved from the global — the same reason it is passed to the FastAPI
+    instrumentation. Re-instrumenting an already-instrumented process is a no-op
+    in OpenTelemetry, so this rebinds first to guarantee spans reach *this*
+    service's provider.
+    """
+    try:
+        from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor
+    except ImportError:
+        logger.debug("httpx tracing skipped: opentelemetry-instrumentation-httpx not installed")
+        return False
+
+    instrumentor = HTTPXClientInstrumentor()
+    if getattr(instrumentor, "is_instrumented_by_opentelemetry", False):
+        instrumentor.uninstrument()
+    instrumentor.instrument(tracer_provider=provider)
+    return True
+
+
+def setup_tracing(
+    app: FastAPI,
+    service_name: str,
+    *,
+    excluded_urls: str | None = None,
+    instrument_httpx: bool = True,
+) -> bool:
+    """Install OTLP tracing on ``app``. Returns True only if spans will be exported.
+
+    Must be called at construction time, before the app serves its first request
+    (so: module scope or an app factory — never inside ``lifespan`` or a startup
+    handler).
+
+    Args:
+        app: The FastAPI application, not yet started.
+        service_name: ``service.name`` in Tempo. Use the Kubernetes service name.
+        excluded_urls: Comma-separated substrings; defaults to probe/scrape paths.
+        instrument_httpx: Also trace outbound httpx calls, so this service becomes
+            a *source* of service-graph edges and not only a target. Best-effort:
+            a missing ``opentelemetry-instrumentation-httpx`` is not an error.
+
+    Returns:
+        True when a tracer provider and OTLP exporter were installed. False when
+        tracing is deliberately off (``OTEL_SDK_DISABLED``), unconfigured (no
+        ``OTLP_TRACES_ENDPOINT``), or the OpenTelemetry packages are absent.
+
+    Raises:
+        RuntimeError: if called after the app has started, because the
+            instrumentation would be discarded without any error of its own.
+    """
+    if _already_started(app):
+        raise RuntimeError(
+            f"setup_tracing({service_name!r}) was called after the application "
+            "started — FastAPIInstrumentor.instrument_app() is a silent no-op at "
+            "that point and would export ZERO spans. Move this call to "
+            "application-construction time (module scope or the app factory), "
+            "not the lifespan or a startup handler."
+        )
+
+    if os.getenv("OTEL_SDK_DISABLED", "false").strip().lower() == "true":
+        logger.info("tracing disabled: OTEL_SDK_DISABLED=true")
+        return False
+
+    endpoint = (os.getenv("OTLP_TRACES_ENDPOINT") or "").strip()
+    if not endpoint:
+        logger.info("tracing disabled: OTLP_TRACES_ENDPOINT is not set")
+        return False
+
+    try:
+        from opentelemetry import trace
+        from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+        from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
+        from opentelemetry.sdk.resources import Resource
+        from opentelemetry.sdk.trace import TracerProvider
+        from opentelemetry.sdk.trace.export import BatchSpanProcessor
+    except ImportError as exc:
+        logger.info("tracing disabled: OpenTelemetry packages not installed (%s)", exc)
+        return False
+
+    provider = TracerProvider(resource=Resource.create({"service.name": service_name}))
+    provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter(endpoint=endpoint)))
+
+    # Register globally: FastAPIInstrumentor resolves the provider lazily through
+    # the global proxy, so an unregistered provider yields non-recording spans and
+    # nothing is ever exported.
+    trace.set_tracer_provider(provider)
+
+    FastAPIInstrumentor.instrument_app(
+        app,
+        tracer_provider=provider,
+        excluded_urls=DEFAULT_EXCLUDED_URLS if excluded_urls is None else excluded_urls,
+        server_request_hook=_server_request_hook,
+    )
+
+    httpx_traced = _instrument_httpx(provider) if instrument_httpx else False
+
+    logger.info(
+        "tracing enabled: service=%s endpoint=%s httpx=%s",
+        service_name,
+        endpoint,
+        httpx_traced,
+    )
+    return True

coding_client/testing.py

@@ -0,0 +1,180 @@
+"""Test-side helpers for neutralising this SDK's identity dependencies.
+
+This module is the supported replacement for ``SKIP_AUTH=true``, which was
+deleted in 1.16.0. The two do the same job for a test suite and differ in the
+only way that matters:
+
+    SKIP_AUTH             ambient, global, ENV-triggered, compiled into the
+                          production wheel. Anything that could set an
+                          environment variable could disable authentication for
+                          the whole process, and the branch sat ABOVE every
+                          credential path in require_tenant.
+
+    override_tenant_auth  per-app-object, explicit, CALL-triggered. There is no
+                          environment variable, no import-time side effect, and
+                          no way to reach it except by calling it against a
+                          specific FastAPI instance.
+
+That is the entire security delta, and it is enforced rather than asserted:
+``tests/unit/test_auth/test_no_auth_bypass.py`` fails if this file ever gains an
+``os.getenv``/``os.environ`` read or imports ``pytest``.
+
+WHY THIS IS SHIPPED HERE RATHER THAN WRITTEN PER REPO
+-----------------------------------------------------
+Because the KEY SET drifts, and it has already drifted. Before 1.16.0,
+``coding-testing/tests/integration/conftest.py`` hand-rolled overrides for
+``get_current_user``, ``requires_read_permission`` and
+``requires_write_permission`` — and NOT ``require_tenant``. That list was
+incomplete and nobody knew, because the same conftest also set
+``SKIP_AUTH=true`` two lines earlier and covered the gap.
+
+Four repos maintaining that list by hand is four chances to miss the next
+dependency this SDK adds. Centralised, adding one is a single edit to
+``_TENANT_DEPENDENCIES`` that every consumer picks up at its next pin bump. This
+fleet has already been burned twice by forked auth helpers; a third fork, living
+in test code where nobody reviews it as security-relevant, is not a good trade
+for avoiding one import.
+
+USAGE
+-----
+    from coding_client.testing import override_tenant_auth
+
+    @pytest.fixture
+    def client(app):
+        undo = override_tenant_auth(app)
+        yield TestClient(app)
+        undo()                      # or use the context manager below
+
+    # a service whose own dependency objects differ from the SDK's, or which
+    # needs a service-specific return shape:
+    undo = override_tenant_auth(
+        app,
+        tenant_id="tenant-a",
+        extra={my_module.create_tenant_context: lambda: MyContext("tenant-a")},
+    )
+
+``undo()`` restores the PREVIOUS mapping exactly. It does not call
+``.clear()`` — several suites yield a module-level ``main.app`` singleton, and
+clearing would silently drop overrides the caller installed itself.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from typing import Any
+
+from .auth.dependencies import get_current_user
+from .auth.models import User
+from .auth.tenant import (
+    create_tenant_context,
+    get_current_user_with_tenant,
+    optional_tenant,
+    require_tenant,
+    require_tenant_context,
+)
+
+__all__ = ["override_tenant_auth", "tenant_auth_override"]
+
+# Every identity dependency this SDK exposes. A route that depends on ANY of
+# these must be neutralised, or a suite bypasses auth on some routes and 401s on
+# others — which is exactly the half-configured state that made the old
+# coding-testing conftest look correct.
+#
+# ⚠️ Adding a dependency to auth/tenant.py means adding it HERE. That is the
+# whole point of this tuple existing.
+_TENANT_DEPENDENCIES = (
+    require_tenant,
+    optional_tenant,
+    get_current_user_with_tenant,
+    create_tenant_context,
+    require_tenant_context,
+    get_current_user,
+)
+
+DEFAULT_TEST_TENANT = "test-tenant"
+DEFAULT_TEST_USER = "test-user"
+
+
+def override_tenant_auth(
+    app: Any,
+    *,
+    tenant_id: str = DEFAULT_TEST_TENANT,
+    user: User | None = None,
+    extra: dict[Callable[..., Any], Callable[..., Any]] | None = None,
+) -> Callable[[], None]:
+    """Neutralise this SDK's identity dependencies on ``app``.
+
+    Args:
+        app: the FastAPI application whose ``dependency_overrides`` to install
+            into. Per-app, so two apps in one test session cannot interfere.
+        tenant_id: what the tenant-returning dependencies resolve to.
+        user: what the user-returning dependencies resolve to. Defaults to a
+            ``User`` whose ``tenant_id`` matches ``tenant_id`` — they must agree,
+            or a route reading both sees two different tenants.
+        extra: additional ``{dependency: replacement}`` pairs, merged last so a
+            caller can override one of the defaults. Use for a service's own
+            forked dependency object (coding-ai's ``require_tenant`` is a
+            different object from this SDK's) or for a service-specific return
+            shape (coding-analysis's ``create_tenant_context`` returns its own
+            ``TenantContext``, not this SDK's dict).
+
+    Returns:
+        A zero-argument callable that restores the previous overrides exactly.
+    """
+    resolved_user = user or User(
+        sub=DEFAULT_TEST_USER,
+        preferred_username=DEFAULT_TEST_USER,
+        tenant_id=tenant_id,
+    )
+
+    replacements: dict[Callable[..., Any], Callable[..., Any]] = {
+        require_tenant: lambda: tenant_id,
+        optional_tenant: lambda: tenant_id,
+        get_current_user_with_tenant: lambda: resolved_user,
+        create_tenant_context: lambda: {"tenant_id": tenant_id},
+        require_tenant_context: lambda: {"tenant_id": tenant_id},
+        get_current_user: lambda: resolved_user,
+    }
+    if extra:
+        replacements.update(extra)
+
+    overrides = app.dependency_overrides
+    # Snapshot only the keys we touch. Restoring the whole dict would clobber
+    # anything installed between our install and undo.
+    previous: dict[Callable[..., Any], Any] = {}
+    absent: list[Callable[..., Any]] = []
+    for dependency, replacement in replacements.items():
+        if dependency in overrides:
+            previous[dependency] = overrides[dependency]
+        else:
+            absent.append(dependency)
+        overrides[dependency] = replacement
+
+    def undo() -> None:
+        for dependency, original in previous.items():
+            overrides[dependency] = original
+        for dependency in absent:
+            overrides.pop(dependency, None)
+
+    return undo
+
+
+@contextmanager
+def tenant_auth_override(
+    app: Any,
+    *,
+    tenant_id: str = DEFAULT_TEST_TENANT,
+    user: User | None = None,
+    extra: dict[Callable[..., Any], Callable[..., Any]] | None = None,
+) -> Iterator[None]:
+    """Context-manager form of :func:`override_tenant_auth`.
+
+    Restores on the way out even when the body raises — which a bare
+    ``undo()`` after ``yield`` in a fixture does not.
+    """
+    undo = override_tenant_auth(app, tenant_id=tenant_id, user=user, extra=extra)
+    try:
+        yield
+    finally:
+        undo()

coding_client/types/__init__.py

@@ -0,0 +1,130 @@
+"""Type definitions for coding-client.
+
+Provides:
+- Core Literal types for type safety (SupportedLanguage, ContainerState, etc.)
+- Constraint types with Pydantic Annotated validators (ContainerName, CodeContent, etc.)
+- State machine implementation for lifecycle management
+"""
+
+from .constraint_types import (
+    SAFE_STRING_PATTERN,
+    AbsolutePath,
+    AnalysisID,
+    CodeContent,
+    CodeSnippet,
+    ColumnNumber,
+    Confidence,
+    ContainerName,
+    CPUCores,
+    FileSizeBytes,
+    FutureTimestamp,
+    GitHubRepoUrl,
+    LineNumber,
+    MemoryMB,
+    Percentage,
+    PortNumber,
+    RelativePath,
+    RequestID,
+    SafeCodeString,
+    SafeString,
+    SafeStringLong,
+    SafeStringMedium,
+    SafeStringMediumOptional,
+    SafeStringOptional,
+    SafeStringShort,
+    SafeStringShortOptional,
+    Score,
+    TimeoutSeconds,
+    UserIdentifier,
+    ValidTimestamp,
+)
+from .core_types import (
+    AnalysisState,
+    AnalysisType,
+    CacheOperationType,
+    ContainerState,
+    DatabaseState,
+    ErrorCategory,
+    ExecutionMode,
+    ExitCode,
+    FileOperationType,
+    GitHubEventType,
+    GitHubEventTypeEnum,
+    HealthState,
+    NetworkOperationType,
+    PRState,
+    QualityLevel,
+    ResponseState,
+    SecurityLevel,
+    SupportedLanguage,
+    TestState,
+    TestType,
+    TransactionState,
+    ValidationResult,
+)
+from .state_machine import (
+    ContainerStateMachine,
+    StateMachine,
+    StateTransition,
+)
+
+__all__ = [
+    # Core Literal types
+    "AnalysisState",
+    "AnalysisType",
+    "CacheOperationType",
+    "ContainerState",
+    "DatabaseState",
+    "ErrorCategory",
+    "ExecutionMode",
+    "ExitCode",
+    "FileOperationType",
+    "GitHubEventType",
+    "GitHubEventTypeEnum",
+    "HealthState",
+    "NetworkOperationType",
+    "PRState",
+    "QualityLevel",
+    "ResponseState",
+    "SecurityLevel",
+    "SupportedLanguage",
+    "TestState",
+    "TestType",
+    "TransactionState",
+    "ValidationResult",
+    # Constraint types
+    "AbsolutePath",
+    "AnalysisID",
+    "CodeContent",
+    "CodeSnippet",
+    "ColumnNumber",
+    "Confidence",
+    "ContainerName",
+    "CPUCores",
+    "FileSizeBytes",
+    "FutureTimestamp",
+    "GitHubRepoUrl",
+    "LineNumber",
+    "MemoryMB",
+    "Percentage",
+    "PortNumber",
+    "RelativePath",
+    "RequestID",
+    "SAFE_STRING_PATTERN",
+    "SafeCodeString",
+    "SafeString",
+    "SafeStringLong",
+    "SafeStringMedium",
+    "SafeStringMediumOptional",
+    "SafeStringOptional",
+    "SafeStringShort",
+    "SafeStringShortOptional",
+    "Score",
+    "TimeoutSeconds",
+    "UserIdentifier",
+    "ValidTimestamp",
+    # State machine
+    "ContainerStateMachine",
+    "StateMachine",
+    "StateTransition",
+]