coding-client 1.21.2__py3-none-any.whl

coding_client/__init__.py

@@ -0,0 +1 @@
+"""coding-client: Shared library for coding-* microservices."""

coding_client/api/__init__.py

@@ -0,0 +1,19 @@
+"""KAG-standard API utilities: error handling, request logging, OpenAPI config, root-logger setup."""
+
+from .exception_handlers import register_exception_handlers
+from .logging_setup import configure_logging
+from .metrics import add_process_time_header
+from .openapi_config import configure_openapi
+from .request_logging import HealthCheckFilter, RequestLoggingMiddleware
+from .validation import SecurityValidationException, ValidationMiddleware
+
+__all__ = [
+    "HealthCheckFilter",
+    "RequestLoggingMiddleware",
+    "SecurityValidationException",
+    "ValidationMiddleware",
+    "add_process_time_header",
+    "configure_logging",
+    "configure_openapi",
+    "register_exception_handlers",
+]

coding_client/api/exception_handlers.py

@@ -0,0 +1,158 @@
+"""KAG-standard exception handlers.
+
+Produces the nested ``{error: {code, message, timestamp, request_id, details}}``
+response envelope used across all KAG and coding-* services.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+import traceback
+import uuid
+from collections.abc import Mapping
+
+from fastapi import FastAPI, Request
+from fastapi.exceptions import RequestValidationError
+from starlette.exceptions import HTTPException
+from starlette.responses import JSONResponse
+
+logger = logging.getLogger(__name__)
+
+
+def _get_request_id(request: Request) -> str:
+    """Get request_id from state (set by RequestLoggingMiddleware) or generate one."""
+    return getattr(request.state, "request_id", None) or str(uuid.uuid4())
+
+
+def _timestamp() -> str:
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+
+def _error_response(
+    status_code: int,
+    *,
+    code: str,
+    message: str,
+    request_id: str,
+    details: object = None,
+    headers: dict[str, str] | Mapping[str, str] | None = None,
+) -> JSONResponse:
+    body: dict = {
+        "code": code,
+        "message": message,
+        "timestamp": _timestamp(),
+        "request_id": request_id,
+    }
+    if details is not None:
+        body["details"] = details
+    return JSONResponse(
+        status_code=status_code,
+        content={"error": body},
+        headers=headers,
+    )
+
+
+def register_exception_handlers(app: FastAPI, *, debug: bool = False) -> None:
+    """Register KAG-standard exception handlers on *app*."""
+
+    async def _handle_http(request: Request, exc: Exception) -> JSONResponse:
+        http_exc = exc if isinstance(exc, HTTPException) else HTTPException(status_code=500)
+        request_id = _get_request_id(request)
+        if isinstance(http_exc.detail, dict):
+            message = http_exc.detail.get("message", str(http_exc.detail))
+        else:
+            message = str(http_exc.detail)
+        return _error_response(
+            http_exc.status_code,
+            code=f"HTTP_{http_exc.status_code}",
+            message=message,
+            request_id=request_id,
+            details=http_exc.detail.get("details") if isinstance(http_exc.detail, dict) else None,
+            headers=http_exc.headers if hasattr(http_exc, "headers") else None,
+        )
+
+    app.add_exception_handler(HTTPException, _handle_http)
+
+    @app.exception_handler(Exception)
+    async def _global(request: Request, exc: Exception) -> JSONResponse:
+        request_id = _get_request_id(request)
+
+        # HTTPException (includes BaseAPIException subclasses)
+        if isinstance(exc, HTTPException):
+            # Extract message from structured detail dicts
+            if isinstance(exc.detail, dict):
+                message = exc.detail.get("message", str(exc.detail))
+            else:
+                message = str(exc.detail)
+
+            return _error_response(
+                exc.status_code,
+                code=f"HTTP_{exc.status_code}",
+                message=message,
+                request_id=request_id,
+                details=exc.detail.get("details") if isinstance(exc.detail, dict) else None,
+                headers=exc.headers if hasattr(exc, "headers") else None,
+            )
+
+        # BaseExceptionGroup wrapping HTTPException (Python 3.11+ TaskGroups)
+        if isinstance(exc, BaseExceptionGroup):
+            for sub_exc in exc.exceptions:
+                if isinstance(sub_exc, HTTPException):
+                    if isinstance(sub_exc.detail, dict):
+                        message = sub_exc.detail.get("message", str(sub_exc.detail))
+                    else:
+                        message = str(sub_exc.detail)
+                    return _error_response(
+                        sub_exc.status_code,
+                        code=f"HTTP_{sub_exc.status_code}",
+                        message=message,
+                        request_id=request_id,
+                        headers=sub_exc.headers if hasattr(sub_exc, "headers") else None,
+                    )
+                if isinstance(sub_exc, BaseExceptionGroup):
+                    for nested in sub_exc.exceptions:
+                        if isinstance(nested, HTTPException):
+                            msg = str(nested.detail)
+                            return _error_response(
+                                nested.status_code,
+                                code=f"HTTP_{nested.status_code}",
+                                message=msg,
+                                request_id=request_id,
+                                headers=nested.headers if hasattr(nested, "headers") else None,
+                            )
+
+        # Unhandled exception
+        logger.error(
+            "Unhandled exception [%s]: %s\n%s",
+            request_id,
+            exc,
+            traceback.format_exc(),
+        )
+        return _error_response(
+            500,
+            code="INTERNAL_SERVER_ERROR",
+            message="An unexpected error occurred",
+            request_id=request_id,
+            details=str(exc) if debug else None,
+        )
+
+    @app.exception_handler(RequestValidationError)
+    async def _validation(request: Request, exc: RequestValidationError) -> JSONResponse:
+        request_id = _get_request_id(request)
+        validation_errors = [
+            {
+                "field": ".".join(str(loc) for loc in err.get("loc", [])),
+                "message": err.get("msg", ""),
+                "type": err.get("type", ""),
+                "input": err.get("input"),
+            }
+            for err in exc.errors()
+        ]
+        return _error_response(
+            422,
+            code="HTTP_422",
+            message="Request validation failed",
+            request_id=request_id,
+            details=validation_errors,
+        )

coding_client/api/logging_setup.py

@@ -0,0 +1,44 @@
+"""Root logger configuration for coding-* microservices.
+
+Without ``logging.basicConfig()``, application module loggers
+(``logger = logging.getLogger(__name__)``) get no handler from uvicorn's
+default ``LOGGING_CONFIG`` -- which only configures the ``uvicorn.*`` loggers,
+not the root. The result is that every ``logger.info(...)`` call from app
+code is silently dropped (Python's "last resort" handler emits only WARNING+).
+
+This module provides a single entry point that all services should call
+before lifespan emits its first log line, so log format and level handling
+stay consistent across the fleet.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+
+__all__ = ["configure_logging"]
+
+_DEFAULT_FORMAT = "%(asctime)s %(levelname)s [%(name)s] %(message)s"
+
+
+def configure_logging(default_level: str = "INFO") -> None:
+    """Configure the root logger so ALL module loggers get a handler.
+
+    Reads ``LOG_LEVEL`` from the environment (defaulting to ``default_level``),
+    installs a stream handler with a consistent format, and uses
+    ``force=True`` to overwrite any handler uvicorn or another framework may
+    have already attached.
+
+    Call this once at startup, before any application code emits log records:
+
+    - For module-level FastAPI apps, call it at the top of ``main.py``,
+      before ``logger = logging.getLogger(__name__)``.
+    - For factory-style apps, call it as the first statement inside
+      ``create_app()``.
+    """
+    log_level = os.getenv("LOG_LEVEL", default_level).upper()
+    logging.basicConfig(
+        level=getattr(logging, log_level, logging.INFO),
+        format=_DEFAULT_FORMAT,
+        force=True,
+    )

coding_client/api/metrics.py

@@ -0,0 +1,40 @@
+"""Request timing middleware for coding-* services.
+
+Measures request duration, sets an ``X-Process-Time`` header, and emits a
+structured ``request_complete`` log line for downstream aggregation. Uses
+structured-log timing rather than Prometheus counters; an OpenTelemetry
+metrics SDK can be wired in here if counter/histogram exports are needed.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+
+from fastapi import Request, Response
+from starlette.middleware.base import RequestResponseEndpoint
+
+logger = logging.getLogger(__name__)
+
+
+async def add_process_time_header(
+    request: Request,
+    call_next: RequestResponseEndpoint,
+) -> Response:
+    """Measure request duration and add ``X-Process-Time`` header."""
+    start = time.perf_counter()
+    response: Response = await call_next(request)
+    duration = time.perf_counter() - start
+    response.headers["X-Process-Time"] = f"{duration:.4f}"
+
+    # Structured log for downstream aggregation
+    logger.info(
+        "request_complete",
+        extra={
+            "method": request.method,
+            "path": request.url.path,
+            "status": getattr(response, "status_code", 0),
+            "duration_s": round(duration, 4),
+        },
+    )
+    return response

coding_client/api/openapi_config.py

@@ -0,0 +1,124 @@
+"""KAG-standard OpenAPI schema customization.
+
+Adds Bearer token security scheme and X-Tenant-ID header parameter
+to the OpenAPI specification.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Set
+
+from fastapi import FastAPI
+from fastapi.openapi.utils import get_openapi
+
+
+def configure_openapi(
+    app: FastAPI,
+    *,
+    protected_prefixes: Set[str] | None = None,
+    public_endpoints: Set[str] | None = None,
+    default_tenant_id: str | None = None,
+) -> None:
+    """Replace app.openapi with a KAG-standard schema generator.
+
+    Args:
+        app: FastAPI application instance.
+        protected_prefixes: Route prefixes requiring Bearer auth (e.g. {"/api/graphs"}).
+        public_endpoints: Exact paths that are always public (e.g. {"/", "/health"}).
+        default_tenant_id: Default tenant ID shown in docs. When omitted it is
+            read from the ``DEFAULT_TENANT_ID`` env var; if that is unset too,
+            the header is documented as **required** with no default, because
+            there is none. It must not advertise a literal the service was never
+            configured with — the docs previously showed ``n8n-dev``, the stale
+            pre-uuid7 label form of a real tenant (see
+            ``coding_client.auth._default_tenant``).
+    """
+    if protected_prefixes is None:
+        protected_prefixes = set()
+    if public_endpoints is None:
+        public_endpoints = {
+            "/",
+            "/health",
+            "/health/ready",
+            "/health/live",
+            "/docs",
+            "/redoc",
+            "/openapi.json",
+        }
+    if default_tenant_id is None:
+        default_tenant_id = os.getenv("DEFAULT_TENANT_ID", "").strip() or None
+
+    app.openapi_schema = None  # Reset to force regeneration
+
+    def custom_openapi():
+        if app.openapi_schema:
+            return app.openapi_schema
+
+        openapi_schema = get_openapi(
+            title=app.title,
+            version=app.version,
+            description=app.description,
+            routes=app.routes,
+        )
+
+        components = openapi_schema.setdefault("components", {})
+
+        # Bearer token security scheme
+        security_schemes = components.setdefault("securitySchemes", {})
+        security_schemes["BearerAuth"] = {
+            "type": "http",
+            "scheme": "bearer",
+            "bearerFormat": "JWT",
+            "description": "Enter your Bearer JWT token",
+        }
+
+        # Reusable tenant header parameter
+        parameters = components.setdefault("parameters", {})
+        tenant_header: dict = {
+            "name": "X-Tenant-ID",
+            "in": "header",
+            "required": default_tenant_id is None,
+            "description": (
+                "Tenant identifier (defaults to configured DEFAULT_TENANT_ID)."
+                if default_tenant_id is not None
+                else "Tenant identifier. Required: this service has no "
+                "DEFAULT_TENANT_ID configured, so there is no fallback tenant."
+            ),
+            "schema": {"type": "string"},
+        }
+        if default_tenant_id is not None:
+            tenant_header["schema"]["default"] = default_tenant_id
+            tenant_header["example"] = default_tenant_id
+        parameters.setdefault("TenantIdHeader", tenant_header)
+
+        # Apply security only to protected prefixes
+        for path, path_item in openapi_schema.get("paths", {}).items():
+            normalized_path = path.rstrip("/") or "/"
+            requires_auth = (
+                any(normalized_path.startswith(prefix) for prefix in protected_prefixes)
+                and normalized_path not in public_endpoints
+            )
+
+            for operation in path_item.values():
+                if not isinstance(operation, dict):
+                    continue
+
+                if requires_auth:
+                    operation.setdefault("security", [{"BearerAuth": []}])
+                else:
+                    operation.pop("security", None)
+
+                # Add tenant header parameter to all operations
+                op_params = operation.setdefault("parameters", [])
+                has_tenant = any(
+                    p.get("name", "").lower() == "x-tenant-id" and p.get("in") == "header"
+                    for p in op_params
+                )
+                if not has_tenant:
+                    op_params.append({"$ref": "#/components/parameters/TenantIdHeader"})
+
+        app.openapi_schema = openapi_schema
+        return app.openapi_schema
+
+    setattr(app, "openapi", custom_openapi)

coding_client/api/request_logging.py

@@ -0,0 +1,60 @@
+"""Request Logging Middleware (KAG standard).
+
+Generates unique request IDs, logs request start/end with timing,
+and adds X-Request-ID + X-Processing-Time response headers.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+import uuid
+from collections.abc import Callable
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+
+logger = logging.getLogger(__name__)
+
+_SKIP_LOG_PATHS = frozenset({"/health", "/healthz", "/ready", "/readyz"})
+
+
+class HealthCheckFilter(logging.Filter):
+    """Filter out health check requests from uvicorn access logs."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        return "/health" not in record.getMessage()
+
+
+class RequestLoggingMiddleware(BaseHTTPMiddleware):
+    """Log requests and add tracking headers (KAG standard)."""
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        if request.url.path in _SKIP_LOG_PATHS:
+            return await call_next(request)
+
+        request_id: str = str(uuid.uuid4())
+        request.state.request_id = request_id
+
+        start_time: float = time.time()
+
+        logger.info("Request started: %s %s [%s]", request.method, request.url.path, request_id)
+
+        response: Response = await call_next(request)
+
+        process_time: float = (time.time() - start_time) * 1000
+
+        response.headers["X-Request-ID"] = request_id
+        response.headers["X-Processing-Time"] = f"{process_time:.2f}ms"
+
+        logger.info(
+            "Request completed: %s %s [%s] - Status: %s - Time: %.2fms",
+            request.method,
+            request.url.path,
+            request_id,
+            response.status_code,
+            process_time,
+        )
+
+        return response

coding_client/api/validation.py

@@ -0,0 +1,150 @@
+"""Request validation middleware for coding-* services.
+
+Provides URL normalisation, control-character detection, and structured
+error responses. Shared across services so each consumer can mount the
+middleware via a thin re-export rather than maintaining its own copy.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import traceback
+import uuid
+from urllib.parse import unquote
+
+from fastapi import HTTPException, Request, Response
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.responses import JSONResponse
+
+logger = logging.getLogger(__name__)
+
+
+class SecurityValidationException(HTTPException):
+    """HTTPException subclass for security validation failures."""
+
+    def __init__(
+        self,
+        status_code: int = 400,
+        detail: str = "Security validation failed",
+        is_security_error: bool = True,
+        error_code: str = "SECURITY_VALIDATION_ERROR",
+    ) -> None:
+        super().__init__(status_code=status_code, detail=detail)
+        self.is_security_error = is_security_error
+        self.error_code = error_code
+
+
+# Paths excluded from deep validation (health checks, etc.)
+_EXCLUDE_PATHS: frozenset[str] = frozenset(
+    {
+        "/health",
+        "/healthz",
+        "/ready",
+        "/readyz",
+        "/",
+    }
+)
+
+# Regex for dangerous control characters (NULL, 0x01-0x08, VT, FF, 0x0E-0x1F, DEL)
+_CONTROL_CHAR_RE = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]")
+
+
+class ValidationMiddleware(BaseHTTPMiddleware):
+    """Pre-processes and validates incoming requests."""
+
+    def __init__(self, app, exclude_paths: frozenset[str] | None = None, **kwargs):
+        super().__init__(app, **kwargs)
+        self._exclude_paths = exclude_paths or _EXCLUDE_PATHS
+
+    async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
+        path = request.url.path
+
+        # Skip validation for excluded paths
+        if path in self._exclude_paths:
+            return await call_next(request)
+
+        try:
+            # Normalise URL path
+            normalised = self._preprocess_request(path)
+            if normalised != path:
+                request.scope["path"] = normalised
+
+            # Check for dangerous control characters in URL
+            self._validate_request_security(request)
+
+            return await call_next(request)
+
+        except SecurityValidationException as exc:
+            return self._create_validation_error_response(exc)
+
+        except HTTPException as exc:
+            return self._create_http_error_response(exc)
+
+        except Exception as exc:
+            logger.error("Unexpected validation error: %s", exc, exc_info=True)
+            return self._create_system_error_response(exc)
+
+    # ── Helpers ────────────────────────────────────────────────────
+
+    @staticmethod
+    def _preprocess_request(path: str) -> str:
+        """Normalise the URL path (collapse slashes, decode, strip trailing slash)."""
+        path = re.sub(r"/+", "/", path)
+        try:
+            path = unquote(path)
+        except Exception:
+            logger.debug("URL unquote failed for path")
+        if len(path) > 1 and path.endswith("/"):
+            path = path.rstrip("/")
+        return path
+
+    def _validate_request_security(self, request: Request) -> None:
+        """Reject requests with dangerous control characters in the URL."""
+        raw_url = str(request.url)
+        if _CONTROL_CHAR_RE.search(raw_url):
+            raise SecurityValidationException(
+                status_code=400,
+                detail="Request contains invalid control characters",
+                error_code="CONTROL_CHAR_DETECTED",
+            )
+
+    @staticmethod
+    def _create_validation_error_response(exc: SecurityValidationException) -> JSONResponse:
+        return JSONResponse(
+            status_code=exc.status_code,
+            content={
+                "error": exc.detail,
+                "error_code": exc.error_code,
+                "status_code": exc.status_code,
+            },
+        )
+
+    @staticmethod
+    def _create_http_error_response(exc: HTTPException) -> JSONResponse:
+        return JSONResponse(
+            status_code=exc.status_code,
+            content={
+                "error": str(exc.detail),
+                "status_code": exc.status_code,
+            },
+        )
+
+    @staticmethod
+    def _create_system_error_response(exc: Exception) -> JSONResponse:
+        request_id = str(uuid.uuid4())
+        logger.error(
+            "System error [%s]: %s\n%s",
+            request_id,
+            exc,
+            traceback.format_exc(),
+        )
+        return JSONResponse(
+            status_code=500,
+            content={
+                "error": "Internal server error",
+                "error_code": "INTERNAL_ERROR",
+                "request_id": request_id,
+                "status_code": 500,
+            },
+        )

coding_client/auth/__init__.py

@@ -0,0 +1,78 @@
+"""Authentication, authorization, and tenant isolation for coding-client.
+
+Provides:
+- User model and auth dependencies for FastAPI routes
+- Auth middleware for Istio header-based authentication
+- RBAC helpers (require_role, require_access_coding)
+- Tenant isolation middleware and dependencies
+"""
+
+from ._header_trust import trust_tenant_header
+from ._onbehalf import (
+    may_vouch,
+    onbehalf_subjects,
+    tenant_license_verified,
+    tenant_was_vouched,
+)
+from .dependencies import get_current_user
+from .middleware import AuthMiddleware
+from .models import User
+from .outbound import (
+    LICENSE_ID_HEADER,
+    TENANT_ID_HEADER,
+    TenantMissingError,
+    optional_tenant_headers,
+    tenant_headers,
+)
+from .rbac import require_access_coding, require_role
+from .tenant import (
+    TenantMiddleware,
+    check_tenant_access,
+    create_tenant_context,
+    get_current_user_with_tenant,
+    get_tenant_id,
+    optional_tenant,
+    require_same_tenant,
+    require_tenant,
+    require_tenant_context,
+)
+from .websocket import Outcome, WebSocketIdentity, resolve_websocket_identity
+
+__all__ = [
+    # Models
+    "User",
+    # Dependencies
+    "get_current_user",
+    # Middleware
+    "AuthMiddleware",
+    # Header-trust posture (TRUST_TENANT_HEADER)
+    "trust_tenant_header",
+    # On-behalf-of vouching (CODING_ONBEHALF_SUBJECTS)
+    "may_vouch",
+    "onbehalf_subjects",
+    "tenant_license_verified",
+    "tenant_was_vouched",
+    # WebSocket identity (middleware never runs on a websocket scope)
+    "Outcome",
+    "WebSocketIdentity",
+    "resolve_websocket_identity",
+    # Outbound identity headers
+    "LICENSE_ID_HEADER",
+    "TENANT_ID_HEADER",
+    "TenantMissingError",
+    "optional_tenant_headers",
+    "tenant_headers",
+    "TenantMiddleware",
+    # RBAC
+    "require_access_coding",
+    "require_role",
+    # Tenant
+    "check_tenant_access",
+    "create_tenant_context",
+    "get_current_user_with_tenant",
+    "get_tenant_id",
+    "optional_tenant",
+    "require_same_tenant",
+    "require_tenant",
+    "require_tenant_context",
+]