everscribe 0.1.0__py3-none-any.whl

everscribe/__init__.py

@@ -0,0 +1,49 @@
+"""Everscribe Python SDK.
+
+Python SDK for the Everscribe audit-log API. Two coordinated surfaces:
+
+- :mod:`everscribe.recorder` - append-only event ingest.
+- :mod:`everscribe.minter` - short-lived embed tokens for frontend audit views.
+
+Bind credentials once with :func:`new` (or :func:`new_from_env`) and create
+per-surface subclients from the returned :class:`Client`::
+
+    import everscribe
+
+    es = everscribe.new(project_id, api_key)
+    rec = es.new_recorder()
+    rec.record(everscribe.Event("user.login"))
+
+The core is zero-dependency (standard library only). The optional ASGI adapter
+lives in :mod:`everscribe.asgi` (install the ``fastapi`` extra).
+"""
+
+from __future__ import annotations
+
+from . import event, minter, recorder
+from .client import (
+    EVERSCRIBE_API_KEY,
+    EVERSCRIBE_PROJECT_ID,
+    Client,
+    new,
+    new_from_env,
+)
+from .event import Event
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # Root client
+    "Client",
+    "new",
+    "new_from_env",
+    "EVERSCRIBE_PROJECT_ID",
+    "EVERSCRIBE_API_KEY",
+    # Event model
+    "Event",
+    # Subpackages
+    "event",
+    "recorder",
+    "minter",
+]

everscribe/asgi.py

@@ -0,0 +1,155 @@
+"""ASGI middleware for FastAPI / Starlette (and any ASGI app).
+
+This adapter supplies only ASGI-specific transport bindings; the record
+lifecycle itself (the request-scoped current event, dedupe, idempotency-key
+stamping, and the final-outcome rule) lives in :mod:`everscribe.event` so
+other framework adapters (Flask, Django, gRPC) can reuse it identically.
+
+It:
+
+1. Builds an Event template (actor from ``resolve_actor``, origin from the
+   request) and installs it, via :func:`everscribe.event.request_scope`, in
+   the request-scoped context so handlers can pull fresh events with
+   :func:`everscribe.event.new_from_context`.
+2. Installs a status capture so :func:`everscribe.event.prepare_event` can
+   auto-populate the event's ``result`` from the final HTTP status when the
+   handler hasn't set one explicitly.
+3. Exposes a single per-request mutable Event via :func:`everscribe.event.current_event`
+   (re-exported here as :func:`current_event`, and available at
+   ``request.state.everscribe_event``) for handlers to enrich (action,
+   target, metadata, optionally result).
+4. If a ``recorder`` was configured, records that event once when the response
+   finishes via :func:`everscribe.event.end_event` - but only when the handler
+   set ``action`` (empty action is a no-op), and only if nothing already
+   claimed the dedupe flag. Auto-record failures are logged, never raised: an
+   audit failure must not break the user-facing response.
+
+Mount it AFTER any session/auth middleware, since ``resolve_actor`` typically
+reads identity off the request.
+
+Requires Starlette (``pip install "everscribe[fastapi]"``).
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+
+try:
+    from starlette.requests import Request
+    from starlette.types import ASGIApp, Message, Receive, Scope, Send
+except ImportError as e:  # pragma: no cover - exercised via install extras
+    raise ImportError(
+        "everscribe.asgi requires Starlette. Install it with: "
+        'pip install "everscribe[fastapi]"'
+    ) from e
+
+from .event import (
+    Event,
+    current_event,
+    end_event,
+    origin_from_request,
+    request_scope,
+    result_from_http_status,
+)
+from .event.types import Actor, Logger, Result
+from .recorder import Recorder
+
+ActorResolver = Callable[[Request], Actor]
+"""Derives the :class:`Actor` for a request. Typically reads session/auth
+state off the Starlette ``Request``. Must not consume the request body."""
+
+_ANONYMOUS = Actor(type="anonymous")
+
+
+def event_from_request(request: Request) -> Event:
+    """Return the per-request event from ``request.state``, falling back to
+    :func:`current_event`."""
+    e = getattr(request.state, "everscribe_event", None)
+    return e if isinstance(e, Event) else current_event()
+
+
+class _StatusCapture:
+    """Captures the response status from the ASGI ``http.response.start``
+    message and translates it into a :class:`Result` on demand, satisfying
+    :class:`everscribe.event.OutcomeCapture`.
+
+    Status 0 (nothing written yet) maps to ``outcome`` being ``None`` -
+    :func:`result_from_http_status` is only consulted once a status has
+    actually been captured.
+    """
+
+    def __init__(self) -> None:
+        self._status = 0
+
+    def set_status(self, status: int) -> None:
+        self._status = status
+
+    @property
+    def outcome(self) -> Result | None:
+        if self._status == 0:
+            return None
+        return result_from_http_status(self._status)
+
+
+class EverscribeMiddleware:
+    """ASGI middleware that installs a per-request audit event and (optionally)
+    auto-records it on response finish.
+
+    Add it to a Starlette/FastAPI app::
+
+        app.add_middleware(
+            EverscribeMiddleware,
+            recorder=rec,
+            resolve_actor=lambda req: Actor(type="user", id=req.state.user_id),
+        )
+    """
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        *,
+        recorder: Recorder | None = None,
+        resolve_actor: ActorResolver | None = None,
+        logger: Logger | None = None,
+    ) -> None:
+        self.app = app
+        self.recorder = recorder
+        self.resolve_actor: ActorResolver = resolve_actor or (lambda req: _ANONYMOUS)
+        self.logger: Logger = logger or logging.getLogger("everscribe.asgi")
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        request = Request(scope, receive=receive)
+        template = Event()
+        template.actor = self.resolve_actor(request)
+        remote = request.client.host if request.client else ""
+        template.origin = origin_from_request(dict(request.headers), remote)
+
+        capture = _StatusCapture()
+
+        async def send_wrapper(message: Message) -> None:
+            if message["type"] == "http.response.start":
+                capture.set_status(int(message["status"]))
+            await send(message)
+
+        with request_scope(template, capture) as user_event:
+            scope.setdefault("state", {})["everscribe_event"] = user_event
+            try:
+                await self.app(scope, receive, send_wrapper)
+            finally:
+                # end_event applies the final outcome (including the "no
+                # response written" sentinel) and records user_event once,
+                # skipping it if a handler already recorded it manually.
+                end_event(user_event, self.recorder, self.logger)
+
+
+__all__ = [
+    "ActorResolver",
+    "EverscribeMiddleware",
+    "current_event",
+    "event_from_request",
+]

everscribe/client.py

@@ -0,0 +1,102 @@
+"""The top-level Everscribe client: binds a project's credentials once and
+hands out per-surface subclients (recorder for ingest, minter for read-side
+embed tokens) that share the same auth.
+
+Typical usage::
+
+    import everscribe
+
+    es = everscribe.new(project_id, api_key)      # or new_from_env()
+    rec = es.new_recorder()
+    try:
+        ...
+    finally:
+        rec.close()
+
+    m = es.new_minter()
+    token = m.mint_token(everscribe.minter.TokenOptions(...))
+
+Customers who only need one surface can call its constructor directly -
+``everscribe.recorder.new(project_id, api_key)`` and
+``everscribe.minter.Client(project_id, api_key)`` both work and skip the
+client step.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from .minter import Client as MinterClient
+from .recorder import BufferedRecorder
+from .recorder import new as _recorder_new
+
+#: Environment-variable names read by :func:`new_from_env`.
+EVERSCRIBE_PROJECT_ID = "EVERSCRIBE_PROJECT_ID"
+EVERSCRIBE_API_KEY = "EVERSCRIBE_API_KEY"
+
+
+class Client:
+    """Credential-bearing handle to an Everscribe project. Holds no network
+    state itself; the subclient constructors build per-surface clients that own
+    their own connections. Reuse a single Client for the lifetime of the
+    process - safe for concurrent use."""
+
+    def __init__(self, project_id: str, api_key: str) -> None:
+        """Validate and trim credentials. Raises :class:`ValueError` if either
+        is empty or whitespace-only, so configuration bugs surface at
+        construction rather than at the first network call."""
+        project_id = project_id.strip()
+        if not project_id:
+            raise ValueError("everscribe: project_id is empty")
+        api_key = api_key.strip()
+        if not api_key:
+            raise ValueError("everscribe: api_key is empty")
+        self.project_id = project_id
+        self._api_key = api_key
+
+    @classmethod
+    def from_env(cls) -> Client:
+        """Construct a Client from ``EVERSCRIBE_PROJECT_ID`` and
+        ``EVERSCRIBE_API_KEY``. Raises :class:`ValueError` naming the missing
+        variable if either is unset or empty after trimming."""
+        project_id = os.environ.get(EVERSCRIBE_PROJECT_ID, "").strip()
+        if not project_id:
+            raise ValueError(f"everscribe: {EVERSCRIBE_PROJECT_ID} is not set or empty")
+        api_key = os.environ.get(EVERSCRIBE_API_KEY, "").strip()
+        if not api_key:
+            raise ValueError(f"everscribe: {EVERSCRIBE_API_KEY} is not set or empty")
+        return cls(project_id, api_key)
+
+    def new_recorder(self, **opts: Any) -> BufferedRecorder:
+        """Return a buffered recorder for the bound project. Keyword options
+        forward to :func:`everscribe.recorder.new` (buffer_size, flush_interval,
+        base_url, ...)."""
+        return _recorder_new(self.project_id, self._api_key, **opts)
+
+    def new_minter(self, **opts: Any) -> MinterClient:
+        """Return a minter client for the bound project. Keyword options
+        forward to :class:`everscribe.minter.Client` (base_url,
+        request_timeout, ...)."""
+        return MinterClient(self.project_id, self._api_key, **opts)
+
+
+def new(project_id: str, api_key: str) -> Client:
+    """Construct a :class:`Client`. Raises :class:`ValueError` on
+    empty/whitespace credentials."""
+    return Client(project_id, api_key)
+
+
+def new_from_env() -> Client:
+    """Construct a :class:`Client` from environment variables. See
+    :meth:`Client.from_env`."""
+    return Client.from_env()
+
+
+__all__ = [
+    "EVERSCRIBE_API_KEY",
+    "EVERSCRIBE_PROJECT_ID",
+    "Client",
+    "new",
+    "new_from_env",
+]

everscribe/django.py

@@ -0,0 +1,181 @@
+"""Django adapter, implemented as a standard Django middleware.
+
+This adapter supplies only Django-specific transport bindings; the record
+lifecycle itself (the request-scoped current event, dedupe, idempotency-key
+stamping, and the final-outcome rule) lives in :mod:`everscribe.event` so
+this adapter stays as thin as :mod:`everscribe.asgi` / :mod:`everscribe.flask`.
+
+Django's middleware protocol - a class instantiated once per server process
+as ``Middleware(get_response)``, whose ``__call__(request)`` wraps the rest
+of the chain - is not bare WSGI: Django itself already sits between the WSGI
+handler and the view, has already parsed ``request.user``/``request.session``
+by the time a middleware later in ``MIDDLEWARE`` runs, and already converts
+view exceptions into an ``HttpResponse`` before an outer middleware's
+``get_response(request)`` call returns (Django wraps every middleware and the
+view individually via ``convert_exception_to_response``). That is why this
+gets its own adapter instead of reusing a generic WSGI wrapper: identity
+lives on ``request.user`` rather than anything a WSGI-level wrapper could
+read, and the exception-to-response conversion already happens beneath this
+middleware, so (unlike the Flask adapter) a single ``__call__`` typically
+sees a real response even when a view raised.
+
+Mount it in ``MIDDLEWARE`` after ``AuthenticationMiddleware`` (and any other
+session/auth middleware), since ``resolve_actor`` typically reads identity
+off ``request.user``.
+
+Requires Django (``pip install "everscribe[django]"``).
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+
+try:
+    from django.conf import settings
+    from django.http import HttpRequest, HttpResponse
+except ImportError as e:  # pragma: no cover - exercised via install extras
+    raise ImportError(
+        "everscribe.django requires Django. Install it with: "
+        'pip install "everscribe[django]"'
+    ) from e
+
+from .event import (
+    Event,
+    current_event,
+    end_event,
+    origin_from_request,
+    request_scope,
+    result_from_http_status,
+)
+from .event.types import Actor, Logger, Result
+from .recorder import Recorder
+
+ActorResolver = Callable[[HttpRequest], Actor]
+"""Derives the :class:`Actor` for a request. Typically reads
+``request.user`` (populated by ``AuthenticationMiddleware``, which must run
+before this middleware) or ``request.session``. Must not consume the request
+body."""
+
+_ANONYMOUS = Actor(type="anonymous")
+
+
+class _OutcomeCapture:
+    """Captures the response status from the value ``get_response`` returns,
+    or the exception it raises, and translates either into a :class:`Result`
+    on demand, satisfying :class:`everscribe.event.OutcomeCapture`.
+
+    Django's own exception-to-response conversion (``convert_exception_to_
+    response``, applied to every middleware and the view) means
+    ``get_response`` ordinarily returns a real ``HttpResponse`` even when a
+    view raised further down the chain; the exception path here exists for
+    the same reason the Flask adapter's does - defense against whatever
+    still reaches this middleware unconverted (for example a later
+    middleware, or ASGI streaming responses, that Django's own conversion
+    doesn't cover) - so an audit event still records rather than crashing
+    silently.
+    """
+
+    def __init__(self) -> None:
+        self._status = 0
+        self._error: BaseException | None = None
+
+    def set_status(self, status: int) -> None:
+        self._status = status
+
+    def set_error(self, err: BaseException) -> None:
+        self._error = err
+
+    @property
+    def outcome(self) -> Result | None:
+        if self._error is not None:
+            return Result(status="error", code=500, message=self._error)
+        if self._status == 0:
+            return None
+        return result_from_http_status(self._status)
+
+
+class EverscribeMiddleware:
+    """Django middleware that installs a per-request audit event and
+    (optionally) auto-records it once ``get_response`` returns (or raises).
+
+    Django itself instantiates middleware as ``Middleware(get_response)``,
+    with no seam to pass extra constructor arguments, so ``recorder``,
+    ``resolve_actor``, and ``logger`` can also be supplied via Django
+    settings instead of (or in addition to) constructor keywords - whichever
+    is set wins if both are given:
+
+    - ``EVERSCRIBE_RECORDER``: a :class:`~everscribe.recorder.Recorder`
+      instance. Omit to install the per-request event without auto-recording.
+    - ``EVERSCRIBE_RESOLVE_ACTOR``: an :data:`ActorResolver`. Defaults to a
+      resolver that returns an anonymous actor.
+    - ``EVERSCRIBE_LOGGER``: a :class:`~everscribe.event.Logger` for
+      auto-record failures. Defaults to a stdlib logger.
+
+    Add to ``MIDDLEWARE``::
+
+        MIDDLEWARE = [
+            ...,
+            "django.contrib.auth.middleware.AuthenticationMiddleware",
+            "myproject.middleware.EverscribeMiddleware",  # after auth
+        ]
+    """
+
+    def __init__(
+        self,
+        get_response: Callable[[HttpRequest], HttpResponse],
+        *,
+        recorder: Recorder | None = None,
+        resolve_actor: ActorResolver | None = None,
+        logger: Logger | None = None,
+    ) -> None:
+        self.get_response = get_response
+        self.recorder: Recorder | None = (
+            recorder if recorder is not None else getattr(settings, "EVERSCRIBE_RECORDER", None)
+        )
+        self.resolve_actor: ActorResolver = (
+            resolve_actor
+            or getattr(settings, "EVERSCRIBE_RESOLVE_ACTOR", None)
+            or (lambda req: _ANONYMOUS)
+        )
+        self.logger: Logger = (
+            logger
+            or getattr(settings, "EVERSCRIBE_LOGGER", None)
+            or logging.getLogger("everscribe.django")
+        )
+
+    def __call__(self, request: HttpRequest) -> HttpResponse:
+        template = Event()
+        template.actor = self.resolve_actor(request)
+        template.origin = origin_from_request(dict(request.headers), request.META.get("REMOTE_ADDR", ""))
+
+        capture = _OutcomeCapture()
+        with request_scope(template, capture) as current:
+            request.everscribe_event = current
+            try:
+                response = self.get_response(request)
+            except Exception as exc:
+                capture.set_error(exc)
+                # end_event applies the final outcome (including the raised-
+                # exception case above) and records `current` once, skipping
+                # it if a handler already recorded it manually.
+                end_event(current, self.recorder, self.logger)
+                raise
+            capture.set_status(response.status_code)
+            end_event(current, self.recorder, self.logger)
+            return response
+
+
+def event_from_request(request: HttpRequest) -> Event:
+    """Return the per-request event stashed on ``request`` by
+    :class:`EverscribeMiddleware`, falling back to :func:`current_event`."""
+    e = getattr(request, "everscribe_event", None)
+    return e if isinstance(e, Event) else current_event()
+
+
+__all__ = [
+    "ActorResolver",
+    "EverscribeMiddleware",
+    "current_event",
+    "event_from_request",
+]

everscribe/event/__init__.py

@@ -0,0 +1,71 @@
+"""Event domain: the on-the-wire event model, redaction, and (added in a
+later step) request-context helpers.
+"""
+
+from __future__ import annotations
+
+from .context import (
+    current_event,
+    end_event,
+    event_scope,
+    new_from_context,
+    prepare_event,
+    request_scope,
+    result_from_http_status,
+    run_with_event,
+)
+from .event import Event
+from .origin import client_ip, origin_from_request
+from .redact import (
+    REDACTED,
+    DiffConfig,
+    DiffOption,
+    apply_redaction,
+    with_redacted_fields,
+)
+from .types import (
+    UNSET,
+    Actor,
+    Change,
+    Logger,
+    Origin,
+    OutcomeCapture,
+    Result,
+    Target,
+)
+from .wire import event_to_wire, result_to_wire
+
+__all__ = [
+    # Model
+    "Event",
+    "Actor",
+    "Target",
+    "Origin",
+    "Result",
+    "Change",
+    "UNSET",
+    # Protocols
+    "OutcomeCapture",
+    "Logger",
+    # Request context / lifecycle
+    "new_from_context",
+    "current_event",
+    "run_with_event",
+    "event_scope",
+    "request_scope",
+    "prepare_event",
+    "end_event",
+    "result_from_http_status",
+    # Origin
+    "origin_from_request",
+    "client_ip",
+    # Redaction
+    "with_redacted_fields",
+    "apply_redaction",
+    "DiffOption",
+    "DiffConfig",
+    "REDACTED",
+    # Wire
+    "event_to_wire",
+    "result_to_wire",
+]