openframe-core 1.0.0__py3-none-any.whl

openframe/__init__.py

@@ -0,0 +1 @@
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)

openframe/core/__init__.py

@@ -0,0 +1 @@
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)

openframe/core/config/__init__.py

@@ -0,0 +1,17 @@
+"""
+openframe/core/config/
+=======================
+Base configuration primitives for all OpenFrame adapter packages.
+
+Every adapter config class subclasses ``BaseAdapterSettings``, which reads
+field values from environment variables via Pydantic Settings.
+
+Usage::
+
+    from openframe.core.config import BaseAdapterSettings
+"""
+from __future__ import annotations
+
+from openframe.core.config.settings import BaseAdapterSettings
+
+__all__ = ["BaseAdapterSettings"]

openframe/core/config/settings.py

@@ -0,0 +1,70 @@
+"""
+openframe/core/config/settings.py
+====================================
+Base settings class for all OpenFrame adapter packages.
+
+Every adapter config (e.g. ``PostgresSettings``, ``RedisSettings``) must
+subclass ``BaseAdapterSettings`` and declare its adapter-specific fields.
+Pydantic Settings reads field values from environment variables automatically
+— the field name maps directly to the env var name (case-insensitive).
+
+Missing required fields raise ``pydantic_core.ValidationError`` at
+instantiation time, not at first use. This means misconfigured deployments
+fail fast on startup rather than at the first request.
+
+Dependency order: this module imports only from pydantic-settings (external).
+No openframe.core imports.
+"""
+from __future__ import annotations
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+__all__ = ["BaseAdapterSettings"]
+
+
+class BaseAdapterSettings(BaseSettings):
+    """
+    Base settings for all OpenFrame adapter packages.
+
+    Subclass in each adapter's ``config/settings.py`` and declare
+    adapter-specific fields. All fields are read from environment variables
+    automatically by Pydantic Settings.
+
+    Configuration:
+        - ``env_prefix = ""`` — field names map directly to env var names.
+        - ``case_sensitive = False`` — ``DATABASE_URL`` maps to ``database_url``.
+        - ``extra = "ignore"`` — unknown env vars are silently ignored.
+
+    Example::
+
+        class PostgresSettings(BaseAdapterSettings):
+            database_url: str          # reads DATABASE_URL — required
+            pool_size: int = 10        # reads POOL_SIZE — optional, default 10
+            pool_max_overflow: int = 5 # reads POOL_MAX_OVERFLOW
+
+        # Missing DATABASE_URL raises ValidationError immediately:
+        settings = PostgresSettings()
+
+    Common fields available on every adapter settings instance:
+
+    Attributes:
+        adapter_name:        Identifies the adapter in logs and traces.
+                             Reads ``ADAPTER_NAME`` env var.
+        connection_timeout:  Seconds to wait when establishing a connection.
+                             Reads ``CONNECTION_TIMEOUT``. Default: 30.0.
+        operation_timeout:   Seconds to wait for a single operation to complete.
+                             Reads ``OPERATION_TIMEOUT``. Default: 10.0.
+        max_retries:         Maximum number of retry attempts on transient failure.
+                             Reads ``MAX_RETRIES``. Default: 3.
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    adapter_name: str = "openframe"
+    connection_timeout: float = 30.0
+    operation_timeout: float = 10.0
+    max_retries: int = 3

openframe/core/exceptions/__init__.py

@@ -0,0 +1,39 @@
+"""
+openframe/core/exceptions/
+============================
+Structured exception hierarchy for all OpenFrame adapter packages.
+
+All adapter packages raise only these exceptions — never raw driver
+exceptions. Services catch ``AdapterError`` as a single catch point
+regardless of which adapter is wired in.
+
+Usage::
+
+    from openframe.core.exceptions import (
+        AdapterError,
+        AdapterConnectionError,
+        AdapterQueryError,
+        AdapterNotFoundError,
+        AdapterConfigurationError,
+        AdapterTimeoutError,
+    )
+"""
+from __future__ import annotations
+
+from openframe.core.exceptions.errors import (
+    AdapterConfigurationError,
+    AdapterConnectionError,
+    AdapterError,
+    AdapterNotFoundError,
+    AdapterQueryError,
+    AdapterTimeoutError,
+)
+
+__all__ = [
+    "AdapterError",
+    "AdapterConnectionError",
+    "AdapterQueryError",
+    "AdapterNotFoundError",
+    "AdapterConfigurationError",
+    "AdapterTimeoutError",
+]

openframe/core/exceptions/errors.py

@@ -0,0 +1,189 @@
+"""
+openframe/core/exceptions/errors.py
+=====================================
+Structured exception hierarchy for all OpenFrame adapter packages.
+
+Every adapter package raises only AdapterError subclasses — never raw
+driver exceptions (psycopg errors, aioredis errors, aiokafka errors, etc.).
+Services catch AdapterError at a single point regardless of which adapter
+is wired in.
+
+Raise with cause chaining at the raise site::
+
+    try:
+        result = await conn.execute(query)
+    except SomeDriverError as exc:
+        raise AdapterQueryError(
+            message="Query failed",
+            adapter="postgres",
+            operation="get",
+            cause=exc,
+        ) from exc
+
+Dependency order: this module has no imports from openframe.core.
+"""
+from __future__ import annotations
+
+__all__ = [
+    "AdapterError",
+    "AdapterConnectionError",
+    "AdapterQueryError",
+    "AdapterNotFoundError",
+    "AdapterConfigurationError",
+    "AdapterTimeoutError",
+]
+
+
+class AdapterError(Exception):
+    """
+    Base exception for all OpenFrame adapter packages.
+
+    All adapter packages raise only AdapterError subclasses — never raw
+    driver exceptions. Services catch AdapterError for a single catch
+    point regardless of which adapter is wired in.
+
+    Attributes:
+        message:   Human-readable description of what went wrong.
+        adapter:   Adapter identifier, e.g. "postgres", "redis", "kafka".
+        operation: Operation that failed, e.g. "get", "create", "publish".
+        cause:     Underlying driver exception, if any. Always chain at
+                   the raise site: ``raise AdapterXError(...) from exc``.
+
+    The ``__str__`` format is::
+
+        [adapter.operation] message
+        [adapter.operation] message — caused by: <cause>
+    """
+
+    def __init__(
+        self,
+        message: str,
+        adapter: str,
+        operation: str,
+        cause: Exception | None = None,
+    ) -> None:
+        """
+        Initialise the exception.
+
+        Args:
+            message:   Human-readable description of the failure.
+            adapter:   Adapter identifier (e.g. "postgres", "redis").
+            operation: Operation that failed (e.g. "get", "create").
+            cause:     Underlying driver exception, or None.
+        """
+        super().__init__(message)  # only message → self.args = (message,)
+        self.message = message
+        self.adapter = adapter
+        self.operation = operation
+        self.cause = cause
+
+    def __str__(self) -> str:
+        """
+        Return a human-readable string including adapter, operation, and message.
+
+        If a cause is present it is appended after \" — caused by: \".
+        """
+        base = f"[{self.adapter}.{self.operation}] {self.message}"
+        if self.cause:
+            return f"{base} — caused by: {self.cause}"
+        return base
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}("
+            f"message={self.message!r}, "
+            f"adapter={self.adapter!r}, "
+            f"operation={self.operation!r}, "
+            f"cause={self.cause!r})"
+        )
+
+
+class AdapterConnectionError(AdapterError):
+    """
+    Raised when the adapter cannot establish a connection to its backend.
+
+    Typical causes: network unreachable, wrong host/port, TLS handshake
+    failure, authentication rejected before a connection is established.
+
+    Raise with cause chaining::
+
+        raise AdapterConnectionError(
+            "Cannot reach Postgres at localhost:5432",
+            adapter="postgres",
+            operation="connect",
+            cause=original_exc,
+        ) from original_exc
+    """
+
+
+class AdapterQueryError(AdapterError):
+    """
+    Raised when an operation fails after a connection is established.
+
+    Typical causes: constraint violation, syntax error, permission denied
+    on a specific table or topic, partial failure mid-batch.
+
+    Raise with cause chaining::
+
+        raise AdapterQueryError(
+            "INSERT violated unique constraint on items.slug",
+            adapter="postgres",
+            operation="create",
+            cause=original_exc,
+        ) from original_exc
+    """
+
+
+class AdapterNotFoundError(AdapterError):
+    """
+    Raised when the requested entity does not exist in the backend.
+
+    This is a semantic "not found" — the adapter successfully queried
+    the backend but the entity is absent. Distinct from AdapterQueryError
+    (which means the query itself failed).
+
+    Raise without a cause when the backend returns a definitive empty
+    result::
+
+        raise AdapterNotFoundError(
+            f"Item {item_id!r} not found",
+            adapter="postgres",
+            operation="get",
+        )
+    """
+
+
+class AdapterConfigurationError(AdapterError):
+    """
+    Raised when required configuration is missing or invalid.
+
+    Typical causes: required env var absent, value fails validation
+    (wrong type, out of range), conflicting options.
+
+    Raise at adapter initialisation time (not at first query) so
+    misconfigured deployments fail fast on startup::
+
+        raise AdapterConfigurationError(
+            "DATABASE_URL must be set",
+            adapter="postgres",
+            operation="init",
+        )
+    """
+
+
+class AdapterTimeoutError(AdapterError):
+    """
+    Raised when an operation exceeds its configured timeout.
+
+    Distinct from AdapterConnectionError — the connection was established
+    but the operation did not complete within the allowed window.
+
+    Raise with cause chaining when wrapping an asyncio.TimeoutError::
+
+        raise AdapterTimeoutError(
+            "Query exceeded 10s operation_timeout",
+            adapter="postgres",
+            operation="get",
+            cause=original_exc,
+        ) from original_exc
+    """

openframe/core/health/__init__.py

@@ -0,0 +1,19 @@
+"""
+openframe/core/health/
+=======================
+Health check port for all OpenFrame adapter packages.
+
+Every adapter implements ``HealthCheck`` so the application layer can
+verify liveness and readiness without knowing which adapter is wired in.
+
+Usage::
+
+    from openframe.core.health import HealthCheck
+
+    assert isinstance(my_adapter, HealthCheck)
+"""
+from __future__ import annotations
+
+from openframe.core.health.protocol import HealthCheck
+
+__all__ = ["HealthCheck"]

openframe/core/health/protocol.py

@@ -0,0 +1,94 @@
+"""
+openframe/core/health/protocol.py
+====================================
+Health check port for all OpenFrame adapter packages.
+
+Every adapter implements ``HealthCheck`` so the application layer can verify
+adapter liveness and readiness without knowing which adapter is wired in.
+
+Two levels of check:
+- ``ping()`` — cheap liveness. Used by load balancers and watchdogs. Should
+  complete in milliseconds (TCP connect, ``SELECT 1``).
+- ``is_ready()`` — full readiness. Used at startup. More expensive — verifies
+  schema migrations applied, connection pool healthy, etc.
+
+Runtime isinstance check::
+
+    isinstance(adapter, HealthCheck)   # ✓ works
+    isinstance(obj, HealthCheck)       # checks for ping and is_ready methods
+
+Dependency order: this module imports only from Python stdlib typing.
+No openframe.core imports.
+"""
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+__all__ = ["HealthCheck"]
+
+
+@runtime_checkable
+class HealthCheck(Protocol):
+    """
+    Health check port. Every adapter implements ``ping()`` and ``is_ready()``.
+
+    Adapters satisfy this protocol structurally — no inheritance needed.
+    Any class with both async method signatures satisfies ``HealthCheck``.
+
+    ``ping()`` vs ``is_ready()``:
+
+    - ``ping()`` is a low-cost liveness check. Verify a TCP connection can be
+      opened, or run ``SELECT 1``. Should complete within milliseconds.
+      Called frequently by load balancers and watchdog processes.
+
+    - ``is_ready()`` is a full readiness check. Verify the connection pool is
+      healthy, required schemas exist, pending migrations have been applied,
+      etc. More expensive — called once at application startup and on
+      scheduled readiness probes.
+
+    Usage::
+
+        class PostgresRepository:
+            async def ping(self) -> bool:
+                try:
+                    await self._pool.fetchval("SELECT 1")
+                    return True
+                except Exception:
+                    return False
+
+            async def is_ready(self) -> bool:
+                try:
+                    await self._pool.fetchval("SELECT COUNT(*) FROM pg_tables")
+                    return True
+                except Exception:
+                    return False
+
+        assert isinstance(PostgresRepository(), HealthCheck)
+    """
+
+    async def ping(self) -> bool:
+        """
+        Low-cost liveness check.
+
+        Verify the adapter can reach its backend. Should be fast and cheap —
+        a TCP connect attempt or ``SELECT 1`` is appropriate.
+
+        Returns:
+            True if the backend is reachable, False otherwise.
+            Must not raise — return False on any failure.
+        """
+        ...
+
+    async def is_ready(self) -> bool:
+        """
+        Full readiness check.
+
+        Verify the adapter is fully ready to serve requests. More thorough
+        than ``ping()`` — check that the schema is correct, migrations are
+        applied, and the connection pool has healthy connections.
+
+        Returns:
+            True if the adapter is ready to serve, False otherwise.
+            Must not raise — return False on any failure.
+        """
+        ...

openframe/core/middleware/__init__.py

@@ -0,0 +1,55 @@
+"""
+openframe/core/middleware/
+===========================
+Pure ASGI telemetry middleware and shared ASGI type aliases for the
+OpenFrame ecosystem.
+
+The middleware is framework-agnostic — it works with FastAPI, Starlette,
+Litestar, or any bare ASGI application.
+
+Usage::
+
+    from openframe.core.middleware import TelemetryMiddleware
+
+    app = TelemetryMiddleware(app)
+
+ASGI type aliases::
+
+    from openframe.core.middleware import ASGIApp, ASGIScope, ASGIMessage, Receive, Send
+
+    def my_middleware(app: ASGIApp) -> ASGIApp:
+        async def wrapped(scope: ASGIScope, receive: Receive, send: Send) -> None:
+            ...
+        return wrapped
+
+Note on ``isinstance`` with type aliases:
+    ``ASGIScope = MutableMapping[str, Any]`` is a subscripted generic alias.
+    ``isinstance({}, ASGIScope)`` raises ``TypeError`` — use the origin type::
+
+        from collections.abc import MutableMapping
+        isinstance({}, MutableMapping)  # ✓ works
+
+    To inspect the alias::
+
+        from typing import get_origin
+        get_origin(ASGIScope) is MutableMapping  # ✓ True
+"""
+from __future__ import annotations
+
+from openframe.core.middleware.telemetry import TelemetryMiddleware
+from openframe.core.middleware.types import (
+    ASGIApp,
+    ASGIMessage,
+    ASGIScope,
+    Receive,
+    Send,
+)
+
+__all__ = [
+    "TelemetryMiddleware",
+    "ASGIApp",
+    "ASGIScope",
+    "ASGIMessage",
+    "Receive",
+    "Send",
+]