obsforge 0.1.1__py3-none-any.whl

obsforge/instrumentation/http/engine.py

@@ -0,0 +1,516 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import SplitResult, urlsplit
+
+from obsforge.api.events import EventClient
+from obsforge.config.settings import HTTPInstrumentationSettings, ObsforgeSettings
+from obsforge.core.models import (
+    BusinessContext,
+    CanonicalEvent,
+    CorrelationContext,
+    DatabaseContext,
+    DependencyContext,
+    Event,
+    EventKind,
+    Outcome,
+    PerformanceContext,
+    RequestContext,
+    ResponseContext,
+    RetryContext,
+    Severity,
+    SpanKind,
+    TelemetryContext,
+    TraceContext,
+)
+from obsforge.instrumentation.exceptions.engine import ExceptionIntelligenceEngine
+from obsforge.instrumentation.http.classification import (
+    classify_response,
+    merge_anomalies,
+    status_class,
+)
+from obsforge.instrumentation.http.dependency import DependencyHealthTracker
+from obsforge.instrumentation.http.sanitization import PayloadSanitizer
+from obsforge.propagation.correlation import CorrelationManager, CorrelationSnapshot
+from obsforge.propagation.distributed import DistributedCorrelationEngine
+
+
+@dataclass(slots=True)
+class RequestCapture:
+    started_at: float
+    request: RequestContext
+    dependency: DependencyContext | None
+    trace: TraceContext
+    correlation: CorrelationContext
+    baggage: dict[str, str]
+    restore_snapshot: CorrelationSnapshot | None = None
+    exception_snapshot: Any | None = None
+
+
+class APIRuntimeEngine:
+    def __init__(
+        self,
+        *,
+        event_client: EventClient,
+        correlation_manager: CorrelationManager,
+        settings: ObsforgeSettings,
+        exception_engine: ExceptionIntelligenceEngine | None = None,
+        distributed_engine: DistributedCorrelationEngine | None = None,
+    ) -> None:
+        self._event_client = event_client
+        self._correlation_manager = correlation_manager
+        self._settings = settings
+        self._http_settings: HTTPInstrumentationSettings = settings.http
+        self._sanitizer = PayloadSanitizer(settings.http)
+        self._dependencies = DependencyHealthTracker(settings.http)
+        self._exception_engine = exception_engine
+        self._distributed = distributed_engine or DistributedCorrelationEngine(
+            correlation_manager=correlation_manager,
+            settings=settings,
+        )
+
+    @property
+    def settings(self) -> ObsforgeSettings:
+        return self._settings
+
+    def inject_distributed_headers(self, headers: dict[str, str]) -> TraceContext:
+        envelope = self._distributed.inject_http_headers(headers)
+        return envelope.trace
+
+    def capture_server_request(
+        self,
+        *,
+        method: str,
+        url: str,
+        headers: dict[str, str],
+        route_template: str | None,
+        client_address: str | None,
+        request_body: bytes | str | dict[str, object] | None,
+    ) -> RequestCapture:
+        parsed = urlsplit(url)
+        envelope = self._distributed.extract_http_headers(headers)
+        correlation = envelope.correlation
+        trace = envelope.trace
+        request = RequestContext(
+            protocol="http",
+            method=method.upper(),
+            scheme=parsed.scheme or "http",
+            host=parsed.hostname,
+            server_address=parsed.hostname,
+            server_port=parsed.port,
+            route_template=route_template,
+            path=parsed.path or "/",
+            query_redacted=self._sanitizer.sanitize_query(parsed.query),
+            client_address=client_address,
+            user_agent=headers.get("user-agent"),
+            content_type=headers.get("content-type"),
+            body_size_bytes=_payload_size(request_body),
+            headers_allowlist=self._sanitizer.sanitize_headers(headers),
+            payload_summary=self._sanitizer.summarize_payload(
+                request_body,
+                content_type=headers.get("content-type"),
+            ),
+        )
+        self._bind_correlation_inheritance(correlation)
+        if self._exception_engine is not None:
+            self._exception_engine.state.bind_request_context(request)
+        return RequestCapture(
+            started_at=time.perf_counter(),
+            request=request,
+            dependency=None,
+            trace=trace,
+            correlation=correlation,
+            baggage=envelope.baggage,
+        )
+
+    def capture_client_request(
+        self,
+        *,
+        method: str,
+        url: str,
+        headers: dict[str, str],
+        request_body: bytes | str | dict[str, object] | None,
+        timeout_ms: float | None = None,
+        destination_service: str | None = None,
+    ) -> RequestCapture:
+        parsed = urlsplit(url)
+        parent_snapshot = self._distributed.snapshot()
+        exception_snapshot = None
+        if self._exception_engine is not None:
+            exception_snapshot = self._exception_engine.snapshot_context()
+        envelope = self._distributed.inject_http_headers(headers)
+        trace = envelope.trace
+        correlation = envelope.correlation
+        request = RequestContext(
+            protocol="http",
+            method=method.upper(),
+            scheme=parsed.scheme or "http",
+            host=parsed.hostname,
+            server_address=parsed.hostname,
+            server_port=parsed.port,
+            path=parsed.path or "/",
+            query_redacted=self._sanitizer.sanitize_query(parsed.query),
+            content_type=headers.get("content-type"),
+            body_size_bytes=_payload_size(request_body),
+            timeout_ms=timeout_ms,
+            headers_allowlist=self._sanitizer.sanitize_headers(headers),
+            payload_summary=self._sanitizer.summarize_payload(
+                request_body,
+                content_type=headers.get("content-type"),
+            ),
+        )
+        dependency = self._dependency_from_url(parsed, destination_service=destination_service)
+        self._bind_correlation_inheritance(correlation)
+        if self._exception_engine is not None:
+            self._exception_engine.state.bind_request_context(request)
+            self._exception_engine.state.bind_dependency_context(dependency)
+        return RequestCapture(
+            started_at=time.perf_counter(),
+            request=request,
+            dependency=dependency,
+            trace=trace,
+            correlation=correlation,
+            baggage=envelope.baggage,
+            restore_snapshot=parent_snapshot,
+            exception_snapshot=exception_snapshot,
+        )
+
+    async def emit_client_event(
+        self,
+        capture: RequestCapture,
+        *,
+        response_status_code: int | None = None,
+        response_headers: dict[str, str] | None = None,
+        response_body: bytes | str | dict[str, object] | None = None,
+        exception: BaseException | None = None,
+        retry_attempt: int | None = None,
+        max_attempts: int | None = None,
+        malformed_response: bool = False,
+    ) -> Event:
+        event = self._finalize_event(
+            capture,
+            response_status_code=response_status_code,
+            response_headers=response_headers,
+            response_body=response_body,
+            exception=exception,
+            retry_attempt=retry_attempt,
+            max_attempts=max_attempts,
+            malformed_response=malformed_response,
+            source_kind="client",
+        )
+        try:
+            await self._event_client.emit(event)
+            return event
+        finally:
+            self._restore_client_context(capture)
+
+    def emit_client_event_sync(
+        self,
+        capture: RequestCapture,
+        *,
+        response_status_code: int | None = None,
+        response_headers: dict[str, str] | None = None,
+        response_body: bytes | str | dict[str, object] | None = None,
+        exception: BaseException | None = None,
+        retry_attempt: int | None = None,
+        max_attempts: int | None = None,
+        malformed_response: bool = False,
+    ) -> Event:
+        event = self._finalize_event(
+            capture,
+            response_status_code=response_status_code,
+            response_headers=response_headers,
+            response_body=response_body,
+            exception=exception,
+            retry_attempt=retry_attempt,
+            max_attempts=max_attempts,
+            malformed_response=malformed_response,
+            source_kind="client",
+        )
+        try:
+            self._event_client.emit_sync(event)
+            return event
+        finally:
+            self._restore_client_context(capture)
+
+    async def emit_server_event(
+        self,
+        capture: RequestCapture,
+        *,
+        response_status_code: int | None = None,
+        response_headers: dict[str, str] | None = None,
+        response_body: bytes | str | dict[str, object] | None = None,
+        exception: BaseException | None = None,
+        malformed_response: bool = False,
+    ) -> Event:
+        event = self._finalize_event(
+            capture,
+            response_status_code=response_status_code,
+            response_headers=response_headers,
+            response_body=response_body,
+            exception=exception,
+            malformed_response=malformed_response,
+            source_kind="server",
+        )
+        await self._event_client.emit(event)
+        return event
+
+    def emit_server_event_sync(
+        self,
+        capture: RequestCapture,
+        *,
+        response_status_code: int | None = None,
+        response_headers: dict[str, str] | None = None,
+        response_body: bytes | str | dict[str, object] | None = None,
+        exception: BaseException | None = None,
+        malformed_response: bool = False,
+    ) -> Event:
+        event = self._finalize_event(
+            capture,
+            response_status_code=response_status_code,
+            response_headers=response_headers,
+            response_body=response_body,
+            exception=exception,
+            malformed_response=malformed_response,
+            source_kind="server",
+        )
+        self._event_client.emit_sync(event)
+        return event
+
+    def clear_context(self) -> None:
+        self._distributed.clear()
+        if self._exception_engine is not None:
+            self._exception_engine.clear_context()
+
+    def response_propagation_headers(self, capture: RequestCapture) -> dict[str, str]:
+        return {
+            key.lower(): value
+            for key, value in self._distributed.response_headers().items()
+        }
+
+    def update_capture_request_body(
+        self,
+        capture: RequestCapture,
+        body: bytes | str | dict[str, object] | None,
+    ) -> None:
+        if body is None:
+            return
+        capture.request.body_size_bytes = _payload_size(body)
+        capture.request.payload_summary = self._sanitizer.summarize_payload(
+            body,
+            content_type=capture.request.content_type,
+        )
+
+    def _finalize_event(
+        self,
+        capture: RequestCapture,
+        *,
+        response_status_code: int | None,
+        response_headers: dict[str, str] | None,
+        response_body: bytes | str | dict[str, object] | None,
+        exception: BaseException | None,
+        retry_attempt: int | None = None,
+        max_attempts: int | None = None,
+        malformed_response: bool = False,
+        source_kind: str,
+    ) -> Event:
+        duration_ms = (time.perf_counter() - capture.started_at) * 1000
+        response = ResponseContext(
+            status_code=response_status_code,
+            status_class=status_class(response_status_code),
+            content_type=(response_headers or {}).get("content-type"),
+            body_size_bytes=_payload_size(response_body),
+            malformed=malformed_response,
+            headers_allowlist=self._sanitizer.sanitize_headers(response_headers),
+            payload_summary=self._sanitizer.summarize_payload(
+                response_body,
+                content_type=(response_headers or {}).get("content-type"),
+            ),
+        )
+        if (
+            not response.malformed
+            and response.content_type is not None
+            and "json" in response.content_type.lower()
+            and response.payload_summary is not None
+            and response.payload_summary.kind != "json"
+        ):
+            response.malformed = True
+        outcome, response_anomalies = classify_response(response)
+        exception_context = None
+        if exception is not None:
+            if self._exception_engine is not None:
+                exception_context = self._exception_engine.capture_exception_context(
+                    exception,
+                    request=capture.request,
+                    dependency=capture.dependency,
+                    handled=source_kind == "client",
+                    escaped=source_kind == "server",
+                )
+            else:
+                from obsforge.instrumentation.http.classification import classify_exception
+
+                exception_context = classify_exception(exception)
+        if exception_context is not None and exception_context.failure_class is not None:
+            if exception_context.failure_class.value == "timeout":
+                outcome = Outcome.TIMEOUT
+            else:
+                outcome = Outcome.FAILED
+
+        retry = RetryContext(
+            attempt=retry_attempt,
+            max_attempts=max_attempts,
+            retriable=(retry_attempt or 1) < (max_attempts or retry_attempt or 1),
+            exhausted=(retry_attempt or 1) >= (max_attempts or retry_attempt or 1),
+            storm_detected=(retry_attempt or 1) >= self._http_settings.retry_storm_threshold,
+        )
+
+        performance = PerformanceContext(
+            duration_ms=duration_ms,
+            payload_in_bytes=capture.request.body_size_bytes,
+            payload_out_bytes=response.body_size_bytes,
+            slow_threshold_ms=self._http_settings.slow_request_threshold_ms,
+            sampled=True,
+        )
+
+        event_name = "api.request.completed" if source_kind == "server" else "dependency.http.completed"
+        severity = Severity.INFO
+        if outcome in {Outcome.FAILED, Outcome.TIMEOUT}:
+            severity = Severity.ERROR
+        elif outcome in {Outcome.REJECTED, Outcome.DEGRADED}:
+            severity = Severity.WARNING
+
+        event = CanonicalEvent(
+            severity=severity,
+            event_name=event_name,
+            event_kind=EventKind.API if source_kind == "server" else EventKind.DEPENDENCY,
+            event_domain="http" if source_kind == "server" else "dependency",
+            operation=capture.request.method.lower() if capture.request.method else "request",
+            outcome=outcome,
+            message=self._message_for(source_kind, capture.request, response_status_code, exception_context),
+            correlation=capture.correlation,
+            telemetry=TelemetryContext(
+                trace=capture.trace,
+                baggage=dict(capture.baggage),
+                span_kind=_span_kind_for(source_kind),
+                otel_status_code="ERROR" if outcome in {Outcome.FAILED, Outcome.TIMEOUT} else "OK",
+            ),
+            request=capture.request,
+            response=response,
+            exception=exception_context,
+            database=self._bound_database_context(),
+            business=self._bound_business_context(),
+            dependency=capture.dependency,
+            retry=retry,
+            performance=performance,
+            tags={"source_kind": source_kind},
+            attributes={
+                "source.service.name": self._settings.service_name,
+                "source.service.namespace": self._settings.namespace,
+                "destination.service.name": (
+                    capture.dependency.remote_service_name
+                    if capture.dependency is not None
+                    else self._settings.service_name
+                ),
+                "dependency.graph.edge": (
+                    f"{self._settings.service_name}->{capture.dependency.remote_service_name}"
+                    if capture.dependency is not None and capture.dependency.remote_service_name is not None
+                    else f"{self._settings.service_name}->{self._settings.service_name}"
+                ),
+            },
+        )
+
+        dependency_anomalies = self._dependencies.record(event)
+        anomalies = merge_anomalies(response_anomalies, dependency_anomalies)
+        if malformed_response:
+            anomalies = merge_anomalies(anomalies, ["malformed_response"])
+        if anomalies:
+            event.ai_hints.extend(anomalies)
+            event.investigation_keys.extend(
+                [
+                    event.runtime.service_name,
+                    event.event_name,
+                    capture.request.route_template or capture.request.host or "unknown",
+                ]
+            )
+            if "upstream_degradation" in anomalies or "dependency_saturation" in anomalies:
+                event.outcome = Outcome.DEGRADED
+                if event.severity == Severity.INFO:
+                    event.severity = Severity.WARNING
+        if exception_context is not None:
+            event.ai_hints.extend(
+                hint for hint in exception_context.ai_hints if hint not in event.ai_hints
+            )
+        return event
+
+    @staticmethod
+    def _dependency_from_url(parsed: SplitResult, *, destination_service: str | None) -> DependencyContext:
+        remote_name = destination_service or parsed.hostname or "unknown-remote"
+        return DependencyContext(
+            dependency_type="http",
+            dependency_name=remote_name,
+            operation=parsed.path or "/",
+            target_namespace=parsed.hostname,
+            remote_service_name=remote_name,
+            upstream=True,
+        )
+
+    @staticmethod
+    def _message_for(
+        source_kind: str,
+        request: RequestContext,
+        status_code: int | None,
+        exception: object | None,
+    ) -> str:
+        target = request.route_template or request.path or request.host or "unknown"
+        if exception is not None:
+            return f"{source_kind} {request.method} {target} failed"
+        return f"{source_kind} {request.method} {target} -> {status_code}"
+
+    def _bound_business_context(self) -> BusinessContext | None:
+        if self._exception_engine is None:
+            return None
+        return self._exception_engine.state.get_business_context()
+
+    def _bound_database_context(self) -> DatabaseContext | None:
+        if self._exception_engine is None:
+            return None
+        return self._exception_engine.state.get_database_context()
+
+    def _bind_correlation_inheritance(self, correlation: CorrelationContext) -> None:
+        if self._exception_engine is None:
+            return
+        current = self._exception_engine.state.get_business_context()
+        if (
+            current is not None
+            and current.tenant_id == correlation.tenant_id
+            and current.transaction_id == correlation.transaction_id
+        ):
+            return
+        merged = current.model_copy() if current is not None else BusinessContext()
+        if correlation.tenant_id is not None and merged.tenant_id is None:
+            merged.tenant_id = correlation.tenant_id
+        if correlation.transaction_id is not None and merged.transaction_id is None:
+            merged.transaction_id = correlation.transaction_id
+        self._exception_engine.state.bind_business_context(merged)
+
+    def _restore_client_context(self, capture: RequestCapture) -> None:
+        if capture.restore_snapshot is not None:
+            self._distributed.restore(capture.restore_snapshot)
+        if self._exception_engine is not None and capture.exception_snapshot is not None:
+            self._exception_engine.restore_context(capture.exception_snapshot)
+
+
+def _payload_size(payload: bytes | str | dict[str, object] | None) -> int | None:
+    if payload is None:
+        return None
+    if isinstance(payload, bytes):
+        return len(payload)
+    if isinstance(payload, str):
+        return len(payload.encode("utf-8", errors="replace"))
+    return len(str(payload).encode("utf-8", errors="replace"))
+
+
+def _span_kind_for(source_kind: str) -> SpanKind:
+    return SpanKind.SERVER if source_kind == "server" else SpanKind.CLIENT

obsforge/instrumentation/http/httpx.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from obsforge.instrumentation.http.engine import APIRuntimeEngine
+
+if TYPE_CHECKING:
+    import httpx
+
+try:  # pragma: no cover - optional dependency
+    import httpx as _httpx
+except ImportError:  # pragma: no cover - optional dependency
+    _httpx = None  # type: ignore[assignment]
+
+_HAS_HTTPX = _httpx is not None
+
+if _HAS_HTTPX:
+    _BaseTransport: Any = _httpx.BaseTransport
+    _AsyncBaseTransport: Any = _httpx.AsyncBaseTransport
+else:  # pragma: no cover - optional dependency
+    _BaseTransport = object
+    _AsyncBaseTransport = object
+
+
+class ObsforgeHTTPXTransport(_BaseTransport):  # type: ignore[misc]
+    def __init__(
+        self,
+        engine: APIRuntimeEngine,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        if not _HAS_HTTPX:  # pragma: no cover - optional dependency
+            raise RuntimeError("httpx is not installed")
+        self._engine = engine
+        self._transport = transport or _httpx.HTTPTransport()
+
+    def handle_request(self, request: httpx.Request) -> httpx.Response:
+        headers = dict(request.headers)
+        body = request.content if request.content else None
+        timeout_ms = _timeout_ext_to_ms(request.extensions.get("timeout"))
+        capture = self._engine.capture_client_request(
+            method=request.method,
+            url=str(request.url),
+            headers=headers,
+            request_body=body,
+            timeout_ms=timeout_ms,
+        )
+        request.headers.update(headers)
+
+        try:
+            response = self._transport.handle_request(request)
+        except BaseException as exc:
+            self._engine.emit_client_event_sync(capture, exception=exc)
+            raise
+
+        self._engine.emit_client_event_sync(
+            capture,
+            response_status_code=response.status_code,
+            response_headers=dict(response.headers),
+            # read() first: the transport returns an unread streaming response, so
+            # accessing .content directly raises ResponseNotRead (mirrors the async
+            # path's aread()). read() buffers the body so the caller can still use it.
+            response_body=response.read(),
+        )
+        return response
+
+
+class ObsforgeHTTPXAsyncTransport(_AsyncBaseTransport):  # type: ignore[misc]
+    def __init__(
+        self,
+        engine: APIRuntimeEngine,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        if not _HAS_HTTPX:  # pragma: no cover - optional dependency
+            raise RuntimeError("httpx is not installed")
+        self._engine = engine
+        self._transport = transport or _httpx.AsyncHTTPTransport()
+
+    async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+        headers = dict(request.headers)
+        body = request.content if request.content else None
+        timeout_ms = _timeout_ext_to_ms(request.extensions.get("timeout"))
+        capture = self._engine.capture_client_request(
+            method=request.method,
+            url=str(request.url),
+            headers=headers,
+            request_body=body,
+            timeout_ms=timeout_ms,
+        )
+        request.headers.update(headers)
+
+        try:
+            response = await self._transport.handle_async_request(request)
+        except BaseException as exc:
+            await self._engine.emit_client_event(capture, exception=exc)
+            raise
+
+        await self._engine.emit_client_event(
+            capture,
+            response_status_code=response.status_code,
+            response_headers=dict(response.headers),
+            response_body=await response.aread(),
+        )
+        return response
+
+
+def instrument_httpx_client(
+    client: httpx.Client, engine: APIRuntimeEngine
+) -> httpx.Client:
+    if not _HAS_HTTPX:  # pragma: no cover - optional dependency
+        raise RuntimeError("httpx is not installed")
+    client._transport = ObsforgeHTTPXTransport(engine, client._transport)
+    return client
+
+
+def instrument_httpx_async_client(
+    client: httpx.AsyncClient, engine: APIRuntimeEngine
+) -> httpx.AsyncClient:
+    if not _HAS_HTTPX:  # pragma: no cover - optional dependency
+        raise RuntimeError("httpx is not installed")
+    client._transport = ObsforgeHTTPXAsyncTransport(engine, client._transport)
+    return client
+
+
+def _timeout_ext_to_ms(timeout: Any) -> float | None:
+    if timeout is None:
+        return None
+    if isinstance(timeout, dict):
+        values = [value for value in timeout.values() if isinstance(value, (int, float))]
+        return max(values) * 1000 if values else None
+    return None