universal-audit-logs 1.0.2__py3-none-any.whl

audit_sdk/__init__.py

@@ -0,0 +1,67 @@
+"""
+Universal Audit Framework (UAF) SDK
+====================================
+
+A production-ready, framework-agnostic audit logging SDK for Python 3.12+.
+
+Quick-start — REST transport::
+
+    from audit_sdk import AuditClient, AuditSettings
+
+    settings = AuditSettings(endpoint="https://audit.example.com/api/v1/events")
+    audit = AuditClient(settings=settings)
+
+Quick-start — Database transport::
+
+    from audit_sdk import AuditClient
+    from audit_sdk.transport.database import DatabaseTransport
+
+    transport = DatabaseTransport.for_postgres(
+        host="localhost", database="audit_db",
+        username="user", password="pass",
+    )
+    audit = AuditClient(transport=transport)
+
+Quick-start — FastAPI middleware::
+
+    from audit_sdk.middleware.fastapi import AuditMiddleware, AuditMiddlewareConfig
+
+    app.add_middleware(AuditMiddleware, audit_client=audit, config=AuditMiddlewareConfig(...))
+"""
+
+from audit_sdk.audit import AuditClient
+from audit_sdk.config.settings import AuditSettings
+from audit_sdk.core.exceptions import QueueFullError, TransportError
+from audit_sdk.models.audit_event import AuditEvent
+from audit_sdk.utils.retry_manager import RetryManager, RetryMetrics
+
+__all__: list[str] = [
+    # Core
+    "AuditClient",
+    "AuditSettings",
+    "AuditEvent",
+    # Retry
+    "RetryManager",
+    "RetryMetrics",
+    # Exceptions
+    "QueueFullError",
+    "TransportError",
+]
+
+# Optional: FastAPI middleware (requires `pip install universal-audit-logs[fastapi]`)
+try:
+    from audit_sdk.middleware.fastapi import AuditMiddleware, AuditMiddlewareConfig
+
+    __all__ += ["AuditMiddleware", "AuditMiddlewareConfig"]
+except ImportError:
+    pass
+
+# Optional: Database transport (requires `pip install universal-audit-logs[postgres]` or `[sqlite]`)
+try:
+    from audit_sdk.transport.database import DatabaseTransport
+
+    __all__ += ["DatabaseTransport"]
+except ImportError:
+    pass
+
+__version__: str = "1.0.2"

audit_sdk/audit.py

@@ -0,0 +1,544 @@
+"""
+audit — Public-facing AuditClient: the SDK's primary entry point.
+
+:class:`AuditClient` is the single object developers interact with.
+It orchestrates the full audit event lifecycle:
+
+    1. **Build** — assemble an :class:`~audit_sdk.models.audit_event.AuditEvent`
+       from caller-supplied parameters (with auto-populated ``event_id`` / ``timestamp``).
+    2. **Validate** — Pydantic v2 validates the event; invalid events raise
+       :class:`~audit_sdk.core.exceptions.ValidationError` immediately.
+    3. **Enrich** — ``on_before_send`` plugin hooks may add metadata.
+    4. **Secure** — signing and/or encryption are applied when enabled.
+    5. **Dispatch** — the transport delivers the event (with retry).
+    6. **Observe** — ``on_after_send`` plugin hooks are called with the result.
+
+Design:
+  - No global state. Every AuditClient holds its own configuration,
+    transport, serializer, plugin registry, and optional security components.
+  - AuditClient is an async context manager for clean resource management.
+  - All dependencies are injected; the client does not create its own transport
+    unless a factory helper (``AuditClient.create()``) is used.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from audit_sdk.config.settings import AuditSettings
+from audit_sdk.core.event_bus import AuditEventBus
+from audit_sdk.core.exceptions import ConfigurationError, TransportError, ValidationError
+from audit_sdk.core.interfaces import (
+    AbstractEncryptor,
+    AbstractSerializer,
+    AbstractSigner,
+    AbstractTransport,
+)
+from audit_sdk.models.audit_event import AuditEvent
+from audit_sdk.plugins.registry import PluginRegistry
+from audit_sdk.utils.retry_manager import RetryManager
+
+log = logging.getLogger(__name__)
+
+
+class AuditClient:
+    """The primary SDK entry point for emitting structured audit events.
+
+    Args:
+        settings: SDK configuration object (endpoint, API key, retry settings, etc.).
+        transport: The delivery transport (REST, Kafka, etc.). If ``None``, a
+            :class:`~audit_sdk.transport.rest.RestTransport` is created automatically.
+        serializer: Event serializer. Defaults to
+            :class:`~audit_sdk.utils.serializer.AuditEventSerializer`.
+        signer: Optional HMAC signer. Created automatically if
+            ``settings.signing_enabled`` is ``True``.
+        encryptor: Optional field encryptor. Created automatically if
+            ``settings.encryption_enabled`` is ``True``.
+        plugin_registry: Plugin registry. A fresh empty registry is used if not supplied.
+        event_bus: Internal event bus. A fresh bus is used if not supplied.
+
+    Example::
+
+        from audit_sdk import AuditClient, AuditSettings
+
+        settings = AuditSettings(endpoint="https://audit.example.com/api/v1/events")
+        audit = AuditClient(settings=settings)
+
+        await audit.log(
+            action="CREATE",
+            entity="Employee",
+            entity_id="100",
+            user={"id": "1", "name": "Admin"},
+            old_value=None,
+            new_value={"name": "John"},
+        )
+    """
+
+    def __init__(
+        self,
+        settings: AuditSettings | None = None,
+        transport: AbstractTransport | None = None,
+        serializer: AbstractSerializer | None = None,
+        signer: AbstractSigner | None = None,
+        encryptor: AbstractEncryptor | None = None,
+        plugin_registry: PluginRegistry | None = None,
+        event_bus: AuditEventBus | None = None,
+        retry_manager: RetryManager | None = None,
+    ) -> None:
+        # settings is optional when a transport is supplied directly
+        # (e.g. DatabaseTransport / MongoDBTransport — no endpoint needed).
+        if settings is None and transport is None:
+            raise ConfigurationError(
+                "AuditClient requires either 'settings' (for HTTP/REST transport) "
+                "or 'transport' (for direct DB/MongoDB transport)."
+            )
+        self._settings = settings
+        self._transport = transport  # lazy-initialized in _get_transport()
+        self._serializer = serializer  # lazy-initialized in _get_serializer()
+        self._signer = signer
+        self._encryptor = encryptor
+        self._plugin_registry = plugin_registry or PluginRegistry()
+        self._event_bus = event_bus or AuditEventBus()
+        self._retry_manager = retry_manager
+        self._closed = False
+
+    # ------------------------------------------------------------------
+    # Primary public API
+    # ------------------------------------------------------------------
+
+    async def log(
+        self,
+        action: str,
+        entity: str,
+        entity_id: str,
+        user: dict[str, Any],
+        old_value: Any = None,
+        new_value: Any = None,
+        metadata: dict[str, Any] | None = None,
+        tenant_id: str | None = None,
+        application: str | None = None,
+        module: str | None = None,
+        service: str | None = None,
+        event_type: str | None = None,
+        status: str | None = None,
+        request: dict[str, Any] | None = None,
+        device: dict[str, Any] | None = None,
+    ) -> AuditEvent:
+        """Build and validate a single structured audit event.
+
+        Constructs an :class:`~audit_sdk.models.audit_event.AuditEvent` from
+        the supplied parameters, merging caller-provided values with context
+        drawn from :attr:`settings` (e.g. ``service_name``). Pydantic v2
+        validates every field at construction time.
+
+        The event is returned immediately — no transport, retry, or plugin
+        hooks are invoked at this stage.
+
+        Args:
+            action: The action performed (e.g. ``"CREATE"``, ``"UPDATE"``).
+                Accepts any :class:`~audit_sdk.models.enums.AuditAction` value
+                or a custom non-empty string.
+            entity: Entity type acted upon (e.g. ``"Employee"``, ``"Invoice"``).
+            entity_id: Unique identifier of the specific entity instance.
+            user: Actor who performed the action. Must contain at least
+                ``"id"`` and ``"name"`` keys.
+            old_value: State of the entity *before* the action.
+                Pass ``None`` for CREATE operations.
+            new_value: State of the entity *after* the action.
+                Pass ``None`` for DELETE operations.
+            metadata: Arbitrary key-value pairs for custom enrichment
+                (tags, batch IDs, feature flags, etc.).
+            tenant_id: Tenant / organisation identifier for multi-tenant
+                deployments (e.g. ``"tenant-acme"``).
+            application: Top-level application name (e.g. ``"HRPortal"``).
+            module: Sub-module or feature area (e.g. ``"Payroll"``).
+            service: Emitting service name. Falls back to
+                ``settings.service_name`` when not supplied.
+            event_type: High-level event category. Use
+                :class:`~audit_sdk.models.audit_event.EventType` values or any
+                custom string. Defaults to ``EventType.GENERIC`` when omitted.
+            status: Outcome of the audited operation. Use
+                :class:`~audit_sdk.models.audit_event.AuditOutcome` values or
+                any custom string. Defaults to ``AuditOutcome.SUCCESS`` when
+                omitted.
+            request: HTTP request context dict. Accepted keys match
+                :class:`~audit_sdk.models.audit_event.RequestModel`.
+            device: Client device context dict. Accepted keys match
+                :class:`~audit_sdk.models.audit_event.DeviceModel`.
+
+        Returns:
+            A fully validated :class:`~audit_sdk.models.audit_event.AuditEvent`
+            instance. ``correlation_id`` and ``timestamp`` are auto-populated.
+
+        Raises:
+            ValidationError: If any field fails Pydantic v2 validation.
+            AuditSDKError: For any other SDK-level error.
+
+        Example::
+
+            event = await audit.log(
+                action="UPDATE",
+                entity="Invoice",
+                entity_id="INV-9999",
+                user={"id": "42", "name": "Finance Bot"},
+                tenant_id="tenant-001",
+                application="FinanceSystem",
+                module="Invoicing",
+                event_type="BUSINESS",
+                status="SUCCESS",
+                old_value={"status": "draft"},
+                new_value={"status": "approved"},
+                metadata={"approved_by": "cfo@example.com"},
+            )
+        """
+        return self._build_event(
+            action=action,
+            entity=entity,
+            entity_id=entity_id,
+            user=user,
+            old_value=old_value,
+            new_value=new_value,
+            metadata=metadata,
+            tenant_id=tenant_id,
+            application=application,
+            module=module,
+            service=service,
+            event_type=event_type,
+            status=status,
+            request=request,
+            device=device,
+        )
+
+    async def log_event(self, event: AuditEvent) -> None:
+        """Dispatch a pre-built :class:`AuditEvent` directly.
+
+        Attempts to deliver *event* via the configured transport. On a
+        retryable failure (network error, timeout, HTTP 5xx/429) the event
+        is handed off to the :class:`~audit_sdk.utils.retry_manager.RetryManager`
+        if one is configured and ``settings.retry_enabled`` is ``True``.
+        On a non-retryable failure (HTTP 4xx) the :class:`TransportError`
+        is re-raised immediately.
+
+        Args:
+            event: A fully validated :class:`~audit_sdk.models.audit_event.AuditEvent`.
+
+        Raises:
+            ConfigurationError: If no transport has been injected.
+            TransportError: For non-retryable HTTP errors, or retryable errors
+                when no :class:`RetryManager` is configured.
+            QueueFullError: If the retry queue is at capacity.
+        """
+        if self._transport is None:
+            raise ConfigurationError(
+                "No transport configured. "
+                "Pass transport= when constructing AuditClient."
+            )
+
+        try:
+            await self._transport.send(event)
+
+        except TransportError as exc:
+            is_retryable = (
+                exc.status_code is None  # network / timeout
+                or exc.status_code in RetryManager.RETRYABLE_STATUS_CODES
+            )
+
+            retry_enabled = self._settings.retry_enabled if self._settings is not None else True
+            if is_retryable and self._retry_manager is not None and retry_enabled:
+                log.warning(
+                    "Transport delivery failed (retryable). "
+                    "Enqueuing event for retry. "
+                    "correlation_id=%s, status=%s",
+                    event.correlation_id,
+                    exc.status_code,
+                )
+                await self._retry_manager.enqueue(event)
+                return  # caller is not blocked; retry proceeds in background
+
+            raise  # non-retryable or no retry manager
+
+    async def publish(
+        self,
+        action: str,
+        entity: str,
+        entity_id: str,
+        user: dict[str, Any],
+        old_value: Any = None,
+        new_value: Any = None,
+        metadata: dict[str, Any] | None = None,
+        tenant_id: str | None = None,
+        application: str | None = None,
+        module: str | None = None,
+        service: str | None = None,
+        event_type: str | None = None,
+        status: str | None = None,
+        request: dict[str, Any] | None = None,
+        device: dict[str, Any] | None = None,
+    ) -> AuditEvent:
+        """Build, validate, and dispatch a single audit event in one call.
+
+        Convenience method that combines :meth:`log` (build + validate) and
+        :meth:`log_event` (transport dispatch + retry hand-off).
+
+        On a **retryable** transport failure the event is enqueued in the
+        :class:`~audit_sdk.utils.retry_manager.RetryManager` (if configured)
+        and this method returns normally — the caller is not blocked.
+
+        On a **non-retryable** failure the :class:`TransportError` is
+        propagated immediately.
+
+        Args:
+            action:      Action verb (e.g. ``"CREATE"``, ``"UPDATE"``).
+            entity:      Entity type acted upon (e.g. ``"Employee"``).
+            entity_id:   Unique identifier of the entity instance.
+            user:        Actor dict — must contain ``"id"`` and ``"name"``.
+            old_value:   Entity state *before* the action (``None`` for CREATE).
+            new_value:   Entity state *after* the action (``None`` for DELETE).
+            metadata:    Arbitrary key-value enrichment.
+            tenant_id:   Tenant / organisation identifier.
+            application: Top-level application name.
+            module:      Sub-module or feature area.
+            service:     Emitting service name (falls back to
+                         ``settings.service_name``).
+            event_type:  High-level event category (default: ``GENERIC``).
+            status:      Outcome of the audited operation (default: ``SUCCESS``).
+            request:     HTTP request context dict.
+            device:      Client device context dict.
+
+        Returns:
+            The fully validated :class:`~audit_sdk.models.audit_event.AuditEvent`
+            that was dispatched (or queued for retry).
+
+        Raises:
+            ValidationError:     If the event parameters fail Pydantic validation.
+            ConfigurationError:  If no transport has been injected.
+            TransportError:      For non-retryable delivery failures.
+            QueueFullError:      If the retry queue is at capacity.
+
+        Example::
+
+            event = await audit.publish(
+                action="CREATE",
+                entity="Employee",
+                entity_id="EMP-001",
+                user={"id": "u1", "name": "Alice"},
+                tenant_id="tenant-acme",
+                application="HRPortal",
+                new_value={"name": "Alice", "department": "Engineering"},
+            )
+        """
+        event = await self.log(
+            action=action,
+            entity=entity,
+            entity_id=entity_id,
+            user=user,
+            old_value=old_value,
+            new_value=new_value,
+            metadata=metadata,
+            tenant_id=tenant_id,
+            application=application,
+            module=module,
+            service=service,
+            event_type=event_type,
+            status=status,
+            request=request,
+            device=device,
+        )
+        await self.log_event(event)
+        return event
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def close(self) -> None:
+        """Flush pending retries, then release all held resources.
+
+        Stops the :class:`~audit_sdk.utils.retry_manager.RetryManager`
+        (waiting for in-flight retry tasks to complete) before closing the
+        transport connection.
+
+        After calling this method, the client must not be used.
+
+        This method is idempotent: calling it multiple times is safe.
+        """
+        if self._closed:
+            return
+        self._closed = True
+        if self._retry_manager is not None:
+            await self._retry_manager.stop()
+        if self._transport is not None:
+            await self._transport.close()
+        log.debug("AuditClient closed.")
+
+    async def __aenter__(self) -> AuditClient:
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.close()
+
+    # ------------------------------------------------------------------
+    # Lazy component initialization (stubs)
+    # ------------------------------------------------------------------
+
+    def _get_transport(self) -> AbstractTransport:
+        """Return the configured transport, creating a default RestTransport if needed.
+
+        Returns:
+            The active :class:`~audit_sdk.core.interfaces.AbstractTransport`.
+
+        Raises:
+            NotImplementedError: Until factory logic is implemented.
+        """
+        # TODO: Auto-create RestTransport / KafkaTransport based on settings.transport.
+        raise NotImplementedError("AuditClient._get_transport() is not yet implemented.")
+
+    def _get_serializer(self) -> AbstractSerializer:
+        """Return the configured serializer, defaulting to AuditEventSerializer.
+
+        Returns:
+            The active :class:`~audit_sdk.core.interfaces.AbstractSerializer`.
+
+        Raises:
+            NotImplementedError: Until factory logic is implemented.
+        """
+        # TODO: Return self._serializer or instantiate AuditEventSerializer().
+        raise NotImplementedError("AuditClient._get_serializer() is not yet implemented.")
+
+    def _build_event(
+        self,
+        action: str,
+        entity: str,
+        entity_id: str,
+        user: Any,
+        old_value: Any,
+        new_value: Any,
+        metadata: dict[str, Any] | None,
+        tenant_id: str | None,
+        application: str | None,
+        module: str | None,
+        service: str | None,
+        event_type: str | None,
+        status: str | None,
+        request: Any,
+        device: Any,
+    ) -> AuditEvent:
+        """Construct a validated :class:`AuditEvent` from individual parameters.
+
+        Merges caller-supplied values with context drawn from :attr:`_settings`:
+
+        - ``service`` falls back to ``settings.service_name`` when not supplied.
+        - All other optional fields fall back to :class:`AuditEvent`'s own
+          defaults (``None``, ``EventType.GENERIC``, ``AuditOutcome.SUCCESS``)
+          when the caller passes ``None``.
+
+        Only non-``None`` optional values are forwarded to the model, keeping
+        AuditEvent's own defaults intact for anything the caller did not supply.
+
+        Args:
+            action: The action verb.
+            entity: Entity type name.
+            entity_id: Entity instance ID.
+            user: Actor dict or :class:`~audit_sdk.models.audit_event.ActorModel`.
+            old_value: Pre-action entity state (``None`` for CREATE).
+            new_value: Post-action entity state (``None`` for DELETE).
+            metadata: Arbitrary key-value enrichment dict.
+            tenant_id: Tenant / organisation identifier.
+            application: Top-level application name.
+            module: Sub-module or feature area name.
+            service: Emitting service name (falls back to ``settings.service_name``).
+            event_type: High-level event category string.
+            status: Outcome string of the audited operation.
+            request: HTTP request context (dict or RequestModel).
+            device: Client device context (dict or DeviceModel).
+
+        Returns:
+            A fully validated :class:`~audit_sdk.models.audit_event.AuditEvent`.
+
+        Raises:
+            ValidationError: Wraps any Pydantic v2 ``ValidationError`` raised
+                during model construction so callers only need to handle SDK
+                exception types.
+        """
+        from pydantic import ValidationError as PydanticValidationError
+
+        from audit_sdk.core.exceptions import ValidationError as SDKValidationError
+
+        # Required fields — always forwarded.
+        kwargs: dict[str, Any] = {
+            "action": action,
+            "entity": entity,
+            "entity_id": entity_id,
+            "user": user,
+            "old_value": old_value,
+            "new_value": new_value,
+            # Fall back to the settings service_name when the caller does not
+            # explicitly pass a service name.
+            "service": service if service is not None else (
+                self._settings.service_name if self._settings is not None else "unknown-service"
+            ),
+        }
+
+        # Optional fields — only injected when the caller provided a value,
+        # so AuditEvent's own defaults remain in effect for omitted fields.
+        if tenant_id is not None:
+            kwargs["tenant_id"] = tenant_id
+        if application is not None:
+            kwargs["application"] = application
+        if module is not None:
+            kwargs["module"] = module
+        if event_type is not None:
+            kwargs["event_type"] = event_type
+        if status is not None:
+            kwargs["status"] = status
+        if metadata is not None:
+            kwargs["metadata"] = metadata
+        if request is not None:
+            kwargs["request"] = request
+        if device is not None:
+            kwargs["device"] = device
+
+        try:
+            return AuditEvent(**kwargs)
+        except PydanticValidationError as exc:
+            raise SDKValidationError(
+                f"AuditEvent validation failed: {exc}",
+                errors=exc.errors(),
+            ) from exc
+
+    # ------------------------------------------------------------------
+    # Properties
+    # ------------------------------------------------------------------
+
+    @property
+    def settings(self) -> AuditSettings | None:
+        """The SDK configuration object (``None`` when using direct transport)."""
+        return self._settings
+
+    @property
+    def plugin_registry(self) -> PluginRegistry:
+        """The plugin registry for this client instance."""
+        return self._plugin_registry
+
+    @property
+    def is_closed(self) -> bool:
+        """Return ``True`` if the client has been closed."""
+        return self._closed
+
+    @property
+    def retry_manager(self) -> RetryManager | None:
+        """The injected :class:`~audit_sdk.utils.retry_manager.RetryManager`, if any."""
+        return self._retry_manager
+
+    def __repr__(self) -> str:
+        svc = self._settings.service_name if self._settings else "direct-transport"
+        env = self._settings.environment if self._settings else "n/a"
+        tpt = str(self._settings.transport) if self._settings else type(self._transport).__name__
+        return (
+            f"AuditClient(service={svc!r}, "
+            f"env={env!r}, "
+            f"transport={tpt!r}, "
+            f"retry={'enabled' if self._retry_manager else 'disabled'}, "
+            f"closed={self._closed})"
+        )

audit_sdk/config/__init__.py

@@ -0,0 +1,10 @@
+"""
+config — SDK-wide configuration management.
+
+All configuration is expressed as a single :class:`~audit_sdk.config.settings.AuditSettings`
+Pydantic model that reads values from environment variables with the ``AUDIT_``
+prefix (e.g. ``AUDIT_ENDPOINT``, ``AUDIT_API_KEY``).
+
+No defaults require external services; the SDK is always safe to import even
+when environment variables are absent (except for required fields like ``endpoint``).
+"""