sqlspec 0.36.0__cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl

sqlspec/extensions/events/_hints.py

@@ -0,0 +1,45 @@
+"""Runtime hint registry for EventChannel defaults."""
+
+from dataclasses import dataclass
+from typing import Any, Final
+
+__all__ = ("EventRuntimeHints", "get_runtime_hints", "resolve_adapter_name")
+
+_ADAPTER_MODULE_PARTS = 3
+
+
+@dataclass(frozen=True)
+class EventRuntimeHints:
+    """Adapter-specific defaults for event polling and leases."""
+
+    poll_interval: float = 1.0
+    lease_seconds: int = 30
+    retention_seconds: int = 86_400
+    select_for_update: bool = False
+    skip_locked: bool = False
+    json_passthrough: bool = False
+
+
+_DEFAULT_HINTS: Final[EventRuntimeHints] = EventRuntimeHints()
+
+
+def get_runtime_hints(adapter: "str | None", config: "Any" = None) -> "EventRuntimeHints":
+    """Return runtime hints provided by the adapter configuration."""
+    if config is None:
+        return _DEFAULT_HINTS
+    try:
+        hints = config.get_event_runtime_hints()
+    except AttributeError:
+        return _DEFAULT_HINTS
+    if isinstance(hints, EventRuntimeHints):
+        return hints
+    return _DEFAULT_HINTS
+
+
+def resolve_adapter_name(config: Any) -> "str | None":
+    """Resolve adapter name from config module path."""
+    module_name = type(config).__module__
+    parts = module_name.split(".")
+    if len(parts) >= _ADAPTER_MODULE_PARTS and parts[0] == "sqlspec" and parts[1] == "adapters":
+        return parts[2]
+    return None

sqlspec/extensions/events/_models.py

@@ -0,0 +1,23 @@
+"""Shared data models for the events subsystem."""
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from datetime import datetime
+
+__all__ = ("EventMessage",)
+
+
+@dataclass(slots=True)
+class EventMessage:
+    """Structured payload delivered to event handlers."""
+
+    event_id: str
+    channel: str
+    payload: "dict[str, Any]"
+    metadata: "dict[str, Any] | None"
+    attempts: int
+    available_at: "datetime"
+    lease_expires_at: "datetime | None"
+    created_at: "datetime"

sqlspec/extensions/events/_payload.py

@@ -0,0 +1,69 @@
+"""Shared payload encoding/decoding utilities for event backends."""
+
+import contextlib
+from datetime import datetime, timezone
+from typing import Any
+
+from sqlspec.exceptions import EventChannelError
+from sqlspec.extensions.events._models import EventMessage
+from sqlspec.utils.serializers import from_json, to_json
+from sqlspec.utils.uuids import uuid4
+
+__all__ = ("decode_notify_payload", "encode_notify_payload", "parse_event_timestamp")
+
+MAX_NOTIFY_BYTES = 8000
+
+
+def encode_notify_payload(event_id: str, payload: "dict[str, Any]", metadata: "dict[str, Any] | None") -> str:
+    """Encode event data as JSON for NOTIFY payload.
+
+    Raises:
+        EventChannelError: If the encoded payload exceeds PostgreSQL's 8KB limit.
+    """
+    encoded = to_json(
+        {
+            "event_id": event_id,
+            "payload": payload,
+            "metadata": metadata,
+            "published_at": datetime.now(timezone.utc).isoformat(),
+        },
+        as_bytes=True,
+    )
+    if len(encoded) > MAX_NOTIFY_BYTES:
+        msg = "PostgreSQL NOTIFY payload exceeds 8 KB limit"
+        raise EventChannelError(msg)
+    return encoded.decode("utf-8")
+
+
+def decode_notify_payload(channel: str, payload: str) -> "EventMessage":
+    """Decode JSON payload from NOTIFY into an EventMessage."""
+    raw = from_json(payload)
+    data = raw if isinstance(raw, dict) else {"payload": raw}
+    payload_val = data.get("payload")
+    metadata_val = data.get("metadata")
+    timestamp = parse_event_timestamp(data.get("published_at"))
+    return EventMessage(
+        event_id=data.get("event_id", uuid4().hex),
+        channel=channel,
+        payload=payload_val if isinstance(payload_val, dict) else {"value": payload_val},
+        metadata=metadata_val if metadata_val is None or isinstance(metadata_val, dict) else {"value": metadata_val},
+        attempts=0,
+        available_at=timestamp,
+        lease_expires_at=None,
+        created_at=timestamp,
+    )
+
+
+def parse_event_timestamp(value: Any) -> "datetime":
+    """Parse a timestamp value into a timezone-aware datetime.
+
+    Handles ISO format strings, datetime objects, and falls back to
+    current UTC time for invalid or missing values.
+    """
+    if isinstance(value, datetime):
+        return value if value.tzinfo else value.replace(tzinfo=timezone.utc)
+    if isinstance(value, str):
+        with contextlib.suppress(ValueError):
+            parsed = datetime.fromisoformat(value)
+            return parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc)
+    return datetime.now(timezone.utc)

sqlspec/extensions/events/_protocols.py

@@ -0,0 +1,134 @@
+"""Protocols for EventChannel handlers and backends."""
+
+from typing import TYPE_CHECKING, Any, ClassVar, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from sqlspec.extensions.events._models import EventMessage
+
+__all__ = ("AsyncEventBackendProtocol", "AsyncEventHandler", "SyncEventBackendProtocol", "SyncEventHandler")
+
+
+class AsyncEventHandler(Protocol):
+    """Protocol describing async event handler callables."""
+
+    async def __call__(self, message: "EventMessage") -> Any:  # pragma: no cover - typing only
+        """Process a queued event message asynchronously."""
+
+
+class SyncEventHandler(Protocol):
+    """Protocol describing sync event handler callables."""
+
+    def __call__(self, message: "EventMessage") -> Any:  # pragma: no cover - typing only
+        """Process a queued event message synchronously."""
+
+
+@runtime_checkable
+class AsyncEventBackendProtocol(Protocol):
+    """Protocol for async event backends.
+
+    All async event backends (native or queue-based) must implement these methods.
+    """
+
+    supports_async: ClassVar[bool]
+    backend_name: ClassVar[str]
+
+    async def publish(self, channel: str, payload: "dict[str, Any]", metadata: "dict[str, Any] | None" = None) -> str:
+        """Publish an event to a channel.
+
+        Args:
+            channel: Target channel name.
+            payload: Event payload (must be JSON-serializable).
+            metadata: Optional metadata dict.
+
+        Returns:
+            The event ID.
+        """
+        ...
+
+    async def dequeue(self, channel: str, poll_interval: float) -> "EventMessage | None":
+        """Dequeue an event from the channel.
+
+        Args:
+            channel: Channel name to listen on.
+            poll_interval: Timeout in seconds to wait for a notification.
+
+        Returns:
+            EventMessage if a notification was received, None otherwise.
+        """
+        ...
+
+    async def ack(self, event_id: str) -> None:
+        """Acknowledge an event.
+
+        Args:
+            event_id: ID of the event to acknowledge.
+        """
+        ...
+
+    async def nack(self, event_id: str) -> None:
+        """Return an event to the queue for redelivery.
+
+        Args:
+            event_id: ID of the event to return.
+        """
+        ...
+
+    async def shutdown(self) -> None:
+        """Shutdown the backend and release resources."""
+        ...
+
+
+@runtime_checkable
+class SyncEventBackendProtocol(Protocol):
+    """Protocol for sync event backends.
+
+    All sync event backends (native or queue-based) must implement these methods.
+    """
+
+    supports_sync: ClassVar[bool]
+    backend_name: ClassVar[str]
+
+    def publish(self, channel: str, payload: "dict[str, Any]", metadata: "dict[str, Any] | None" = None) -> str:
+        """Publish an event to a channel.
+
+        Args:
+            channel: Target channel name.
+            payload: Event payload (must be JSON-serializable).
+            metadata: Optional metadata dict.
+
+        Returns:
+            The event ID.
+        """
+        ...
+
+    def dequeue(self, channel: str, poll_interval: float) -> "EventMessage | None":
+        """Dequeue an event from the channel.
+
+        Args:
+            channel: Channel name to listen on.
+            poll_interval: Timeout in seconds to wait for a notification.
+
+        Returns:
+            EventMessage if a notification was received, None otherwise.
+        """
+        ...
+
+    def ack(self, event_id: str) -> None:
+        """Acknowledge an event.
+
+        Args:
+            event_id: ID of the event to acknowledge.
+        """
+        ...
+
+    def nack(self, event_id: str) -> None:
+        """Return an event to the queue for redelivery.
+
+        Args:
+            event_id: ID of the event to return.
+        """
+        ...
+
+    def shutdown(self) -> None:
+        """Shutdown the backend and release resources."""
+        ...