spanforge 2.0.0__py3-none-any.whl

spanforge/export/webhook.py

@@ -0,0 +1,302 @@
+"""Webhook exporter for spanforge events.
+
+Delivers events (or batches) as JSON HTTP POST requests to a configurable
+URL with optional HMAC-SHA256 request signing.
+
+Security
+--------
+* If ``secret`` is provided every request is signed with
+  ``X-SpanForge-Signature: hmac-sha256:<hex>`` so the receiver can verify
+  authenticity.
+* The ``secret`` value is **never** included in repr, logs, or exception
+  messages.
+* Retry logic uses truncated exponential back-off to avoid amplifying load on a
+  degraded endpoint.
+
+Transport
+---------
+Uses :func:`urllib.request.urlopen` in a thread-pool executor so the async
+event loop is never blocked.  No external HTTP library is required.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextvars
+import hashlib
+import hmac
+import ipaddress
+import socket
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import TYPE_CHECKING
+
+from spanforge.exceptions import ExportError
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from spanforge.event import Event
+
+__all__ = ["WebhookExporter"]
+
+# Header name for the HMAC-SHA256 request signature.
+# Note: kept as the legacy value for backwards-compatibility with existing receivers.
+_SIGNATURE_HEADER = "X-SpanForge-Signature"
+
+# Maximum retry sleep (seconds) — hard ceiling regardless of attempt count.
+_MAX_SLEEP: float = 30.0
+
+
+def _is_private_ip_literal(host: str) -> bool:
+    """Return ``True`` if *host* is a private/loopback/link-local **literal** IP.
+
+    .. warning::
+        **SSRF limitation** — DNS hostnames are **not** resolved.  A hostname
+        such as ``"localhost"`` or ``"internal.corp"`` is *not* caught here.
+        The caller is responsible for additional DNS-based validation if needed.
+        Only dotted-decimal IPv4 or bracketed IPv6 **literals** are evaluated.
+
+    Set ``allow_private_addresses=True`` (config: ``allow_private_endpoints``)
+    to permit private IP literals in non-production environments.
+    """
+    try:
+        addr = ipaddress.ip_address(host)
+    except ValueError:
+        return False  # not an IP literal — treat as safe
+    return addr.is_private or addr.is_loopback or addr.is_link_local or addr.is_multicast
+
+
+def _validate_http_url(
+    url: str,
+    param_name: str = "url",
+    *,
+    allow_private_addresses: bool = False,
+) -> None:
+    """Raise *ValueError* if *url* is not a valid ``http://`` or ``https://`` URL.
+
+    When *allow_private_addresses* is ``False`` (default), also rejects URLs
+    whose host is a literal private/loopback/link-local IP address.  DNS
+    hostnames are **not** resolved so ``http://localhost/`` still passes.
+    """
+    parsed = urllib.parse.urlparse(url)
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+        raise ValueError(
+            f"{param_name} must be a valid http:// or https:// URL; got {url!r}"
+        )
+    if not allow_private_addresses:
+        host = parsed.hostname or ""
+        if _is_private_ip_literal(host):
+            raise ValueError(
+                f"{param_name} resolves to a private/loopback/link-local IP address "
+                f"({host!r}).  Set allow_private_addresses=True to permit this in "
+                f"non-production environments."
+            )
+        # DNS-based SSRF check — best-effort; DNS failure is non-fatal.
+        if host and not _is_private_ip_literal(host):
+            try:
+                resolved = socket.gethostbyname(host)
+                addr = ipaddress.ip_address(resolved)
+                if addr.is_private or addr.is_loopback or addr.is_link_local:
+                    raise ValueError(
+                        f"{param_name} hostname {host!r} resolves to a private/loopback/"
+                        f"link-local address ({resolved}).  "
+                        "Set allow_private_addresses=True to permit this."
+                    )
+            except OSError:  # DNS failure — allow through
+                pass
+
+
+def _sign_body(body: bytes, secret: str) -> str:
+    """Compute ``hmac-sha256:<hex>`` signature for *body*.
+
+    Args:
+        body:   Raw request body bytes.
+        secret: HMAC secret string (UTF-8 encoded internally).
+
+    Returns:
+        Signature string in the form ``"hmac-sha256:<hexdigest>"``.
+    """
+    mac = hmac.new(
+        secret.encode("utf-8"),
+        msg=body,
+        digestmod=hashlib.sha256,
+    )
+    return f"hmac-sha256:{mac.hexdigest()}"
+
+
+class WebhookExporter:
+    """Async exporter that sends spanforge events to an HTTP webhook endpoint.
+
+    Each :meth:`export` call delivers a single event as the JSON body.
+    :meth:`export_batch` delivers a JSON array.
+
+    Args:
+        url:         Destination webhook URL.
+        secret:      Optional HMAC-SHA256 signing secret.  When provided, the
+                     request includes an ``X-SpanForge-Signature`` header.
+        headers:     Optional extra HTTP request headers.
+        timeout:     Per-request timeout in seconds (default 10.0).
+        max_retries: Maximum retry attempts on transient failures (default 3).
+                     Retries are attempted only for network errors and 5xx
+                     responses.  4xx errors are not retried.
+
+    Security:
+        The ``secret`` is never included in ``repr()``, log messages, or
+        exception strings.
+
+    Example::
+
+        exporter = WebhookExporter(
+            url="https://hooks.example.com/events",
+            secret="my-hmac-secret",
+        )
+        await exporter.export(event)
+    """
+
+    def __init__(  # noqa: PLR0913
+        self,
+        url: str,
+        *,
+        secret: str | None = None,
+        headers: dict[str, str] | None = None,
+        timeout: float = 10.0,
+        max_retries: int = 3,
+        allow_private_addresses: bool = False,
+    ) -> None:
+        if not url:
+            raise ValueError("url must be a non-empty string")
+        _validate_http_url(url, "url", allow_private_addresses=allow_private_addresses)
+        if timeout <= 0:
+            raise ValueError("timeout must be positive")
+        if max_retries < 0:
+            raise ValueError("max_retries must be >= 0")
+        self._url = url
+        self._secret: str | None = secret
+        self._headers: dict[str, str] = dict(headers) if headers else {}
+        self._timeout = timeout
+        self._max_retries = max_retries
+
+    # ------------------------------------------------------------------
+    # Public async API
+    # ------------------------------------------------------------------
+
+    async def export(self, event: Event) -> None:
+        """Export a single event as a JSON-encoded HTTP POST.
+
+        Args:
+            event: The event to deliver.
+
+        Raises:
+            ExportError: If all retry attempts fail.
+        """
+        body = event.to_json().encode("utf-8")
+        await self._post(body, event_id=event.event_id)
+
+    async def export_batch(self, events: Sequence[Event]) -> int:
+        """Export multiple events as a JSON array in a single HTTP POST.
+
+        Args:
+            events: Sequence of events to deliver.
+
+        Returns:
+            Number of events sent.
+
+        Raises:
+            ExportError: If all retry attempts fail.
+        """
+        if not events:
+            return 0
+        array_json = (
+            "["
+            + ",".join(e.to_json() for e in events)
+            + "]"
+        )
+        body = array_json.encode("utf-8")
+        await self._post(body, event_id="")
+        return len(events)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _do_http_post(url: str, body: bytes, headers: dict[str, str], timeout: float, event_id: str) -> None:
+        """Execute a single HTTP POST; raises ExportError on failure."""
+        req = urllib.request.Request(  # noqa: S310  # NOSONAR
+            url=url,
+            data=body,
+            headers=headers,
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310  # NOSONAR
+                resp.read()
+        except urllib.error.HTTPError as exc:
+            raise ExportError("webhook", f"HTTP {exc.code}: {exc.reason}", event_id) from exc
+        except OSError as exc:
+            raise ExportError("webhook", str(exc), event_id) from exc
+
+    async def _post(self, body: bytes, event_id: str) -> None:
+        """POST *body* to :attr:`_url` with retry and optional signing.
+
+        Args:
+            body:     Raw request body bytes.
+            event_id: Event ID for error context (empty string for batches).
+
+        Raises:
+            ExportError: After exhausting all retry attempts.
+            EgressViolationError: If the endpoint is blocked by egress policy.
+        """
+        from spanforge.egress import check_egress  # noqa: PLC0415
+
+        check_egress(self._url, backend="webhook")
+
+        request_headers: dict[str, str] = {
+            "Content-Type": "application/json",
+            **self._headers,
+        }
+        if self._secret is not None:
+            request_headers[_SIGNATURE_HEADER] = _sign_body(body, self._secret)
+
+        url = self._url
+        timeout = self._timeout
+        last_exc: ExportError | None = None
+
+        for attempt in range(self._max_retries + 1):
+            if attempt > 0:
+                # Truncated exponential back-off: 1s, 2s, 4s … capped at 30s.
+                sleep_secs = min(2 ** (attempt - 1), _MAX_SLEEP)
+                await asyncio.sleep(sleep_secs)
+
+            loop = asyncio.get_running_loop()
+            # Capture the current contextvars context so it is propagated into
+            # the executor thread (fixes contextvar loss via run_in_executor).
+            ctx = contextvars.copy_context()
+            try:
+                await loop.run_in_executor(
+                    None,
+                    lambda: ctx.run(self._do_http_post, url, body, request_headers, timeout, event_id),
+                )
+            except ExportError as exc:
+                last_exc = exc
+                if exc.reason.startswith("HTTP 4"):
+                    raise
+            else:
+                return  # success
+
+        assert last_exc is not None  # always set when we reach here
+        raise last_exc
+
+    # ------------------------------------------------------------------
+    # Repr — secret intentionally omitted
+    # ------------------------------------------------------------------
+
+    def __repr__(self) -> str:
+        has_secret = self._secret is not None
+        return (
+            f"WebhookExporter(url={self._url!r}, "
+            f"signed={has_secret!r}, "
+            f"max_retries={self._max_retries!r})"
+        )

spanforge/exporters/__init__.py

@@ -0,0 +1,29 @@
+"""spanforge.exporters — Synchronous export backends for the SpanForge SDK.
+
+This package provides the sync exporter implementations used by the internal
+:mod:`spanforge._stream` module.  All exporters expose the same minimal
+interface::
+
+    class SomeExporter:
+        def export(self, event: Event) -> None: ...
+        def flush(self) -> None: ...
+        def close(self) -> None: ...
+
+Available exporters
+-------------------
+* :class:`~spanforge.exporters.jsonl.SyncJSONLExporter` — append events as
+  newline-delimited JSON to a file.
+* :class:`~spanforge.exporters.console.SyncConsoleExporter` — pretty-print
+  events to stdout during development.
+
+Additional backends (OTLP, Webhook, Datadog, Grafana Loki) are implemented in
+later phases; they live in :mod:`spanforge.export` (the async-based backends) until
+synchronous wrappers are added here.
+"""
+
+from __future__ import annotations
+
+from spanforge.exporters.console import SyncConsoleExporter
+from spanforge.exporters.jsonl import SyncJSONLExporter
+
+__all__ = ["SyncConsoleExporter", "SyncJSONLExporter"]

spanforge/exporters/console.py

@@ -0,0 +1,271 @@
+"""spanforge.exporters.console — Human-readable development console exporter.
+
+Prints a formatted summary box to ``sys.stdout`` each time a span or agent
+event is emitted.  Designed for rapid development feedback — no file is written,
+no external dependencies are required.
+
+Example output (with colour support)::
+
+    ╔══ span: chat [gpt-4o] ══════════════════════════════╗
+    ║  event_id   : 01JXXXXXXXXXXXXXXXXXXXXXXX
+    ║  trace_id   : 01JXXXXXXXXXXXXXXXXXXXXXXX
+    ║  duration   : 142.3ms
+    ║  tokens     : in=512  out=128  total=640
+    ║  cost        : $0.00096
+    ║  status     : ok
+    ╚═════════════════════════════════════════════════════╝
+
+Colour is enabled automatically when stdout is a TTY.  Set the ``NO_COLOR``
+environment variable (any value) to force plain text output per the
+`no-color.org <https://no-color.org>`_ convention.
+
+Usage::
+
+    from spanforge import configure
+    configure(exporter="console")
+
+Zero external dependencies — stdlib only (``os``, ``sys``).
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from collections.abc import Mapping
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from spanforge.event import Event
+
+__all__ = ["SyncConsoleExporter"]
+
+# ---------------------------------------------------------------------------
+# Colour helpers
+# ---------------------------------------------------------------------------
+
+# ANSI escape codes
+_RESET = "\x1b[0m"
+_BOLD = "\x1b[1m"
+_DIM = "\x1b[2m"
+_CYAN = "\x1b[36m"
+_GREEN = "\x1b[32m"
+_RED = "\x1b[31m"
+_YELLOW = "\x1b[33m"
+_MAGENTA = "\x1b[35m"
+_BLUE = "\x1b[34m"
+_WHITE = "\x1b[97m"
+
+
+def _use_colour() -> bool:
+    """Return ``True`` if ANSI colour should be emitted."""
+    if os.environ.get("NO_COLOR"):
+        return False
+    return hasattr(sys.stdout, "isatty") and sys.stdout.isatty()
+
+
+def _c(text: str, *codes: str) -> str:
+    """Wrap *text* with ANSI *codes* if colour is enabled, else return plain."""
+    if not _use_colour():
+        return text
+    return "".join(codes) + text + _RESET
+
+
+# ---------------------------------------------------------------------------
+# Box-drawing characters
+# ---------------------------------------------------------------------------
+
+_BOX_WIDTH = 56  # inner width (chars between ╔ and ╗)
+_MIN_NAMESPACE_PARTS = 2  # minimum dot-separated parts for namespace extraction
+
+_TL = "╔"  # top-left corner
+_TR = "╗"  # top-right corner
+_BL = "╚"  # bottom-left corner
+_BR = "╝"  # bottom-right corner
+_H = "═"   # horizontal
+_V = "║"   # vertical
+_TJ = "╤"  # top T-junction (unused, reserved)
+
+
+def _hline(char: str = _H) -> str:
+    return char * _BOX_WIDTH
+
+
+def _top_bar(title: str) -> str:
+    """``╔══ <title> ═════╗`` with padding."""
+    inner = f"══ {title} "
+    pad = _BOX_WIDTH - len(inner)
+    pad = max(pad, 2)
+    return _c(_TL + inner + _H * pad + _TR, _CYAN, _BOLD)
+
+
+def _bottom_bar() -> str:
+    return _c(_BL + _hline() + _BR, _CYAN, _BOLD)
+
+
+def _row(label: str, value: str, value_colour: str = "") -> str:
+    label_part = _c(f"  {label:<12}", _DIM)
+    colon = _c(": ", _DIM)
+    val_part = _c(value, value_colour) if value_colour else value
+    return _c(_V, _CYAN, _BOLD) + label_part + colon + val_part
+
+
+# ---------------------------------------------------------------------------
+# Payload extractors
+# ---------------------------------------------------------------------------
+
+
+def _get(payload: dict, *keys: str, default: str = "") -> str:
+    """Safely retrieve a nested value from *payload* as a string.
+
+    Works with both plain ``dict`` and read-only ``MappingProxyType`` objects
+    (the latter is how :class:`~spanforge.event.Event` stores its payload).
+    """
+    obj: object = payload
+    for key in keys:
+        if not isinstance(obj, Mapping):
+            return default
+        obj = obj.get(key)  # type: ignore[union-attr]
+    if obj is None:
+        return default
+    return str(obj)
+
+
+def _format_tokens(payload: dict) -> str | None:
+    tu = payload.get("token_usage")
+    if not isinstance(tu, dict):
+        return None
+    i = tu.get("input_tokens", "?")
+    o = tu.get("output_tokens", "?")
+    t = tu.get("total_tokens", "?")
+    return f"in={i}  out={o}  total={t}"
+
+
+def _format_cost(payload: dict) -> str | None:
+    cost = payload.get("cost")
+    if not isinstance(cost, dict):
+        return None
+    total = cost.get("total_cost_usd")
+    if total is None:
+        return None
+    currency = cost.get("currency", "USD")
+    if currency == "USD":
+        return f"${total:.5f}"
+    return f"{total:.5f} {currency}"
+
+
+def _format_duration(payload: dict) -> str | None:
+    ms = payload.get("duration_ms")
+    if ms is None:
+        return None
+    return f"{float(ms):.1f}ms"
+
+
+def _status_colour(status: str) -> str:
+    if status == "ok":
+        return _GREEN
+    if status in ("error", "timeout"):
+        return _RED
+    return _YELLOW
+
+
+# ---------------------------------------------------------------------------
+# Main formatter
+# ---------------------------------------------------------------------------
+
+
+def _format_event_rows(event: Event, payload: dict[str, object], lines: list[str]) -> None:
+    """Append formatted detail rows to *lines* for the given event."""
+    et = event.event_type
+
+    lines.append(_row("event_id", event.event_id, _BLUE))
+    lines.append(_row("event_type", et))
+
+    trace_id = event.trace_id or _get(payload, "trace_id")
+    if trace_id:
+        lines.append(_row("trace_id", trace_id, _MAGENTA))
+    span_id = event.span_id or _get(payload, "span_id")
+    if span_id:
+        lines.append(_row("span_id", span_id, _MAGENTA))
+
+    dur = _format_duration(payload)
+    if dur:
+        lines.append(_row("duration", dur, _CYAN))
+
+    tokens = _format_tokens(payload)
+    if tokens:
+        lines.append(_row("tokens", tokens, _WHITE))
+
+    cost_str = _format_cost(payload)
+    if cost_str:
+        lines.append(_row("cost", cost_str, _YELLOW))
+
+    status = payload.get("status", "ok")
+    if isinstance(status, str):
+        lines.append(_row("status", status, _status_colour(status)))
+
+    error_msg = payload.get("error")
+    if error_msg:
+        lines.append(_row("error", str(error_msg), _RED))
+
+    if "total_steps" in payload:
+        lines.append(_row("steps", str(payload["total_steps"])))
+    if "step_index" in payload:
+        lines.append(_row("step_index", str(payload["step_index"])))
+
+
+def _format_event(event: Event) -> str:
+    """Render *event* as a multi-line console box string."""
+    payload = event.payload or {}
+    et = event.event_type  # e.g. "llm.trace.span.completed"
+
+    namespace_part = et.split(".")[2] if et.count(".") >= _MIN_NAMESPACE_PARTS else "trace"
+    span_name = (
+        payload.get("span_name")
+        or payload.get("agent_name")
+        or payload.get("step_name")
+        or "unknown"
+    )
+    model_name = _get(payload, "model", "name")
+    model_suffix = f" [{model_name}]" if model_name else ""
+    title = f"{namespace_part}: {span_name}{model_suffix}"
+
+    lines: list[str] = [_top_bar(title)]
+    _format_event_rows(event, payload, lines)
+    lines.append(_bottom_bar())
+    return "\n".join(lines) + "\n"
+
+
+# ---------------------------------------------------------------------------
+# Exporter class
+# ---------------------------------------------------------------------------
+
+
+class SyncConsoleExporter:
+    """Synchronous exporter that pretty-prints events to ``sys.stdout``.
+
+    No file is written; output goes to ``sys.stdout`` only.  ANSI colour
+    codes are emitted when stdout is a TTY and ``NO_COLOR`` is not set.
+
+    This exporter is the default when ``configure(exporter="console")`` is
+    used, which is the default if ``SPANFORGE_EXPORTER`` is not set.
+    """
+
+    def export(self, event: Event) -> None:
+        """Print *event* as a formatted box to ``sys.stdout``.
+
+        Args:
+            event: A :class:`~spanforge.event.Event` instance.
+        """
+        formatted = _format_event(event)
+        sys.stdout.write(formatted)
+        sys.stdout.flush()
+
+    def flush(self) -> None:
+        """Flush stdout."""
+        sys.stdout.flush()
+
+    def close(self) -> None:
+        """No-op — console exporter has no resources to release."""
+
+    def __repr__(self) -> str:
+        return "SyncConsoleExporter()"