flowevent 1.2__py3-none-any.whl

eventflow/history.py

@@ -0,0 +1,111 @@
+"""Optional bounded in-memory history for event buses."""
+
+from __future__ import annotations
+
+import threading
+from abc import ABC, abstractmethod
+from collections import deque
+from itertools import islice
+from typing import Generic, TypeVar
+
+from .filtering import EventFilter
+
+
+T = TypeVar("T")
+
+
+def _validate_query_limit(limit: int | None) -> None:
+    if limit is not None and (isinstance(limit, bool) or not isinstance(limit, int) or limit <= 0):
+        raise ValueError("Event history query limit must be a positive integer")
+
+
+class EventHistory(Generic[T], ABC):
+    """Storage contract for custom histories used by event buses.
+
+    Implementations must make ``append``, ``latest``, ``query``, ``clear``, and
+    ``__len__`` safe under concurrent calls and return query results from a
+    consistent snapshot. A history shared by multiple buses must provide the
+    same guarantees across those buses; a bus lock only protects its own writes.
+    """
+
+    @abstractmethod
+    def append(self, event: T) -> None: ...
+
+    @abstractmethod
+    def latest(self, event_filter: EventFilter[T] | None = None) -> T | None: ...
+
+    @abstractmethod
+    def query(
+        self,
+        event_filter: EventFilter[T] | None = None,
+        *,
+        limit: int | None = None,
+    ) -> tuple[T, ...]: ...
+
+    @abstractmethod
+    def clear(self) -> None: ...
+
+    @abstractmethod
+    def __len__(self) -> int: ...
+
+
+class MemoryEventHistory(EventHistory[T]):
+    """Thread-safe bounded history preserving publication order."""
+
+    def __init__(self, capacity: int = 1_000) -> None:
+        if isinstance(capacity, bool) or not isinstance(capacity, int) or capacity <= 0:
+            raise ValueError("Event history capacity must be a positive integer")
+        self._events: deque[T] = deque(maxlen=capacity)
+        self._lock = threading.RLock()
+
+    @property
+    def capacity(self) -> int:
+        return self._events.maxlen or 0
+
+    def append(self, event: T) -> None:
+        with self._lock:
+            self._events.append(event)
+
+    def latest(self, event_filter: EventFilter[T] | None = None) -> T | None:
+        with self._lock:
+            if event_filter is None:
+                return self._events[-1] if self._events else None
+            events = tuple(self._events)
+        return next(
+            (event for event in reversed(events) if event_filter.matches(event)),
+            None,
+        )
+
+    def query(
+        self,
+        event_filter: EventFilter[T] | None = None,
+        *,
+        limit: int | None = None,
+    ) -> tuple[T, ...]:
+        _validate_query_limit(limit)
+        with self._lock:
+            if event_filter is None:
+                if limit is None:
+                    return tuple(self._events)
+                recent = list(islice(reversed(self._events), limit))
+                recent.reverse()
+                return tuple(recent)
+            events = tuple(self._events)
+        if limit is None:
+            return tuple(event for event in events if event_filter.matches(event))
+        matched: list[T] = []
+        for event in reversed(events):
+            if event_filter.matches(event):
+                matched.append(event)
+                if len(matched) == limit:
+                    break
+        matched.reverse()
+        return tuple(matched)
+
+    def clear(self) -> None:
+        with self._lock:
+            self._events.clear()
+
+    def __len__(self) -> int:
+        with self._lock:
+            return len(self._events)

eventflow/observability.py

@@ -0,0 +1,133 @@
+"""Opt-in pipeline measurements; no logging setup or global collectors."""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Literal, Protocol
+
+ObservationKind = Literal["run", "stage", "middleware"]
+ExecutionStatus = Literal["success", "error", "cancelled"]
+__all__ = [
+    "ExecutionMetrics",
+    "PipelineObservation",
+    "PipelineObserver",
+    "PipelineStats",
+    "PipelineStatsSnapshot",
+    "ExecutionStatus",
+    "ObservationKind",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class PipelineObservation:
+    """One completed execution; elapsed time is measured in seconds."""
+
+    kind: ObservationKind
+    name: str | None
+    elapsed: float
+    status: ExecutionStatus
+    correlation_id: str | None = None
+    error: BaseException | None = None
+
+
+class PipelineObserver(Protocol):
+    """Synchronous, fast notification callable, also used by AsyncPipeline."""
+
+    def __call__(self, observation: PipelineObservation) -> None: ...
+
+
+@dataclass(frozen=True, slots=True)
+class ExecutionMetrics:
+    """Aggregate counts and durations, without retained payloads or errors."""
+
+    calls: int = 0
+    successful: int = 0
+    failed: int = 0
+    cancelled: int = 0
+    total_seconds: float = 0.0
+    max_seconds: float = 0.0
+
+
+@dataclass(frozen=True, slots=True)
+class PipelineStatsSnapshot:
+    """Immutable aggregate view; disabled stages have no measurements."""
+
+    runs: ExecutionMetrics
+    stages: Mapping[str, ExecutionMetrics]
+    middleware: Mapping[str, ExecutionMetrics]
+
+
+@dataclass(slots=True)
+class _MetricTotals:
+    calls: int = 0
+    successful: int = 0
+    failed: int = 0
+    cancelled: int = 0
+    total_seconds: float = 0.0
+    max_seconds: float = 0.0
+
+    def record(self, observation: PipelineObservation) -> None:
+        self.calls += 1
+        self.successful += observation.status == "success"
+        self.failed += observation.status == "error"
+        self.cancelled += observation.status == "cancelled"
+        self.total_seconds += observation.elapsed
+        self.max_seconds = max(self.max_seconds, observation.elapsed)
+
+    def freeze(self) -> ExecutionMetrics:
+        return ExecutionMetrics(
+            self.calls,
+            self.successful,
+            self.failed,
+            self.cancelled,
+            self.total_seconds,
+            self.max_seconds,
+        )
+
+
+class PipelineStats:
+    """Thread-safe observer collecting per-run, stage and middleware aggregates."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._metrics: dict[tuple[ObservationKind, str | None], _MetricTotals] = {}
+
+    def __call__(self, observation: PipelineObservation) -> None:
+        key = (observation.kind, observation.name)
+        with self._lock:
+            totals = self._metrics.get(key)
+            if totals is None:
+                totals = _MetricTotals()
+                self._metrics[key] = totals
+            totals.record(observation)
+
+    @property
+    def snapshot(self) -> PipelineStatsSnapshot:
+        """Copy aggregate counters; the returned mappings cannot be changed."""
+        with self._lock:
+            runs = self._metrics.get(("run", None))
+            return PipelineStatsSnapshot(
+                ExecutionMetrics() if runs is None else runs.freeze(),
+                MappingProxyType(
+                    {
+                        name: totals.freeze()
+                        for (kind, name), totals in self._metrics.items()
+                        if kind == "stage" and name is not None
+                    }
+                ),
+                MappingProxyType(
+                    {
+                        name: totals.freeze()
+                        for (kind, name), totals in self._metrics.items()
+                        if kind == "middleware" and name is not None
+                    }
+                ),
+            )
+
+    def reset(self) -> None:
+        """Reset counters; in-flight operations contribute when they finish."""
+        with self._lock:
+            self._metrics.clear()

eventflow/pipeline/__init__.py

@@ -0,0 +1,7 @@
+"""Independent typed pipelines, stage decorators and around middleware."""
+
+from .async_ import AsyncPipeline
+from .contracts import PipelineExecutionError
+from .sync import Pipeline
+
+__all__ = ["AsyncPipeline", "Pipeline", "PipelineExecutionError"]

eventflow/pipeline/async_.py

@@ -0,0 +1,129 @@
+"""Asyncio pipeline execution using the same registry and observer contracts."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+from collections.abc import Awaitable, Callable, Coroutine
+from time import perf_counter
+from typing import Any, Generic, Literal, TypeVar
+
+from .._callbacks import synchronous_result
+from ..observability import PipelineObserver
+from .base import _PipelineBase
+from .registry import _Entry
+
+T = TypeVar("T")
+Stage = Callable[[T], Awaitable[T]]
+Middleware = Callable[[T, Callable[[T], Awaitable[T]]], Awaitable[T]]
+
+
+class AsyncPipeline(_PipelineBase[Stage[T], Middleware[T]], Generic[T]):
+    """Same-type async transformations on one owning event loop.
+
+    Concurrent runs share configuration but have independent continuations and
+    caller-owned payloads. Cancellation propagates directly into the active stage.
+    """
+
+    _asynchronous = True
+
+    def __init__(self, *, observer: PipelineObserver | None = None) -> None:
+        self._loop: asyncio.AbstractEventLoop | None = None
+        super().__init__(observer=observer)
+
+    async def _invoke(
+        self,
+        name: str,
+        phase: Literal["stage", "middleware"],
+        callback: Callable[..., Awaitable[T]],
+        context: T,
+        continuation: Callable[[T], Awaitable[T]] | None = None,
+    ) -> T:
+        started = perf_counter() if self._observer is not None else 0.0
+        try:
+            operation = (
+                callback(context) if continuation is None else callback(context, continuation)
+            )
+            if not inspect.isawaitable(operation):
+                raise TypeError("Async pipeline callbacks must return awaitables")
+            result = synchronous_result(await operation)
+        except BaseException as error:
+            self._raise(error, self._observe(phase, name, started, error), name, phase, context)
+        diagnostic = self._observe(phase, name, started)
+        if diagnostic is not None:
+            self._raise(diagnostic, None, name, "observer", context)
+        return result
+
+    def _compile(self) -> None:
+        stages = self._stages.plan
+
+        async def execute(context: T) -> T:
+            for entry in stages:
+                context = await self._invoke(entry.name, "stage", entry.callback, context)
+            return context
+
+        chain = execute
+        for entry in reversed(self._middleware.plan):
+            chain = self._layer(entry, chain)
+        self._execution = chain
+
+    def _layer(
+        self, entry: _Entry[Middleware[T]], following: Callable[[T], Awaitable[T]]
+    ) -> Callable[[T], Awaitable[T]]:
+        async def execute(context: T) -> T:
+            used = False
+            active = True
+            owner = asyncio.current_task()
+            continuation: Coroutine[Any, Any, T] | None = None
+
+            def next_(value: T) -> Coroutine[Any, Any, T]:
+                nonlocal continuation
+
+                if (
+                    continuation is not None
+                    and inspect.getcoroutinestate(continuation) is inspect.CORO_CREATED
+                ):
+                    continuation.close()
+
+                async def continue_pipeline() -> T:
+                    nonlocal used
+                    if used or not active or asyncio.current_task() is not owner:
+                        raise RuntimeError(
+                            "Middleware continuation is single-use and owned by its call"
+                        )
+                    used = True
+                    return await following(value)
+
+                continuation = continue_pipeline()
+                return continuation
+
+            try:
+                return await self._invoke(entry.name, "middleware", entry.callback, context, next_)
+            finally:
+                active = False
+                if (
+                    continuation is not None
+                    and inspect.getcoroutinestate(continuation) is inspect.CORO_CREATED
+                ):
+                    continuation.close()
+
+        return execute
+
+    async def run(self, context: T) -> T:
+        """Execute a snapshot without starting worker tasks or swallowing cancellation."""
+        loop = asyncio.get_running_loop()
+        with self._lock:
+            if self._loop is None:
+                self._loop = loop
+            elif self._loop is not loop:
+                raise RuntimeError("AsyncPipeline belongs to a different event loop")
+            execute = self._execution
+        started = perf_counter() if self._observer is not None else 0.0
+        try:
+            result = await execute(context)
+        except BaseException as error:
+            self._raise(error, self._observe("run", None, started, error), None, "run", context)
+        diagnostic = self._observe("run", None, started)
+        if diagnostic is not None:
+            self._raise(diagnostic, None, None, "observer", context)
+        return result

eventflow/pipeline/base.py

@@ -0,0 +1,203 @@
+"""Shared registry, decorators, snapshots and observer error policy."""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+from collections.abc import Callable
+from time import perf_counter
+from typing import Generic, Literal, NoReturn, TypeVar
+
+from .._callbacks import is_async_callable, synchronous_result
+from ..context import current_correlation_id
+from ..observability import ObservationKind, PipelineObservation, PipelineObserver
+from .contracts import PipelineExecutionError
+from .registry import _Registry
+
+C = TypeVar("C")
+M = TypeVar("M")
+_MAX_MIDDLEWARE_COUNT = 64
+
+
+class _PipelineBase(Generic[C, M]):
+    _asynchronous = False
+
+    def __init__(self, *, observer: PipelineObserver | None = None) -> None:
+        if observer is not None and (not callable(observer) or is_async_callable(observer)):
+            raise TypeError("Pipeline observer must be a synchronous callable")
+        self._observer = observer
+        self._lock = threading.RLock()
+        self._stages: _Registry[C] = _Registry()
+        self._middleware: _Registry[M] = _Registry()
+        self._compile()
+
+    def _compile(self) -> None:
+        raise NotImplementedError
+
+    def _validate(self, callback: object) -> None:
+        if not callable(callback):
+            raise TypeError("Pipeline callback must be callable")
+        if not self._asynchronous and is_async_callable(callback):
+            raise TypeError("Synchronous pipeline requires synchronous callbacks")
+
+    @property
+    def stage_names(self) -> tuple[str, ...]:
+        """Names in execution order, including disabled stages."""
+        with self._lock:
+            return tuple(entry.name for entry in self._stages.ordered)
+
+    @property
+    def middleware_names(self) -> tuple[str, ...]:
+        """Names from outermost to innermost, including disabled middleware."""
+        with self._lock:
+            return tuple(entry.name for entry in self._middleware.ordered)
+
+    def add(
+        self, name: str, callback: C, *, before: str | None = None, after: str | None = None
+    ) -> None:
+        """Add a stage atomically; references must already exist and be acyclic."""
+        self._validate(callback)
+        with self._lock:
+            self._stages.add(name, callback, before, after)
+            self._compile()
+
+    def stage(
+        self, name: str, *, before: str | None = None, after: str | None = None
+    ) -> Callable[[C], C]:
+        """Register a stage while returning the original callable unchanged."""
+
+        def register(callback: C) -> C:
+            self.add(name, callback, before=before, after=after)
+            return callback
+
+        return register
+
+    def remove(self, name: str) -> C:
+        """Remove a stage and references to it; return its original callback."""
+        with self._lock:
+            callback = self._stages.remove(name)
+            self._compile()
+            return callback
+
+    def replace(self, name: str, callback: C) -> None:
+        """Replace a callback, retaining its name, order and enabled state."""
+        self._validate(callback)
+        with self._lock:
+            self._stages.replace(name, callback)
+            self._compile()
+
+    def enable(self, name: str) -> None:
+        """Enable a stage for future runs."""
+        with self._lock:
+            self._stages.enable(name, True)
+            self._compile()
+
+    def disable(self, name: str) -> None:
+        """Disable a stage for future runs; ordering constraints remain intact."""
+        with self._lock:
+            self._stages.enable(name, False)
+            self._compile()
+
+    def add_middleware(
+        self, name: str, callback: M, *, before: str | None = None, after: str | None = None
+    ) -> None:
+        """Register around middleware in a separate, ordered registry."""
+        self._validate(callback)
+        with self._lock:
+            if len(self._middleware.ordered) >= _MAX_MIDDLEWARE_COUNT:
+                raise ValueError(
+                    f"Pipeline supports at most {_MAX_MIDDLEWARE_COUNT} middleware entries"
+                )
+            self._middleware.add(name, callback, before, after)
+            self._compile()
+
+    def middleware(
+        self, name: str, *, before: str | None = None, after: str | None = None
+    ) -> Callable[[M], M]:
+        """Register middleware and return its original callable unchanged."""
+
+        def register(callback: M) -> M:
+            self.add_middleware(name, callback, before=before, after=after)
+            return callback
+
+        return register
+
+    def remove_middleware(self, name: str) -> M:
+        """Remove middleware and its ordering references."""
+        with self._lock:
+            callback = self._middleware.remove(name)
+            self._compile()
+            return callback
+
+    def replace_middleware(self, name: str, callback: M) -> None:
+        """Replace middleware without changing its position."""
+        self._validate(callback)
+        with self._lock:
+            self._middleware.replace(name, callback)
+            self._compile()
+
+    def enable_middleware(self, name: str) -> None:
+        """Enable middleware for future runs."""
+        with self._lock:
+            self._middleware.enable(name, True)
+            self._compile()
+
+    def disable_middleware(self, name: str) -> None:
+        """Disable middleware for future runs."""
+        with self._lock:
+            self._middleware.enable(name, False)
+            self._compile()
+
+    def _observe(
+        self,
+        kind: ObservationKind,
+        name: str | None,
+        started: float,
+        error: BaseException | None = None,
+    ) -> Exception | None:
+        if self._observer is None:
+            return None
+        status: Literal["success", "error", "cancelled"] = (
+            "cancelled"
+            if isinstance(error, asyncio.CancelledError)
+            else "error"
+            if error is not None
+            else "success"
+        )
+        try:
+            synchronous_result(
+                self._observer(
+                    PipelineObservation(
+                        kind,
+                        name,
+                        perf_counter() - started,
+                        status,
+                        current_correlation_id(),
+                        error,
+                    )
+                )
+            )
+        except Exception as observer_error:
+            return observer_error
+        return None
+
+    @staticmethod
+    def _raise(
+        error: BaseException,
+        diagnostic: Exception | None,
+        name: str | None,
+        phase: Literal["stage", "middleware", "run", "observer"],
+        context: object,
+    ) -> NoReturn:
+        if isinstance(error, PipelineExecutionError):
+            if diagnostic is not None:
+                error.observer_errors += (diagnostic,)
+            raise error
+        if isinstance(error, Exception):
+            failure = PipelineExecutionError(name, context, phase=phase)
+            if diagnostic is not None:
+                failure.observer_errors = (diagnostic,)
+            raise failure from error
+        if diagnostic is not None:
+            raise error from diagnostic
+        raise error

eventflow/pipeline/contracts.py

@@ -0,0 +1,24 @@
+"""Pipeline execution errors shared by sync and async implementations."""
+
+from typing import Literal
+
+
+class PipelineExecutionError(RuntimeError):
+    """Fail-fast error with component, input and the original exception as cause.
+
+    Observer failures during an existing failure are retained separately so
+    instrumentation cannot replace the original cause.
+    """
+
+    def __init__(
+        self,
+        name: str | None,
+        context: object,
+        *,
+        phase: Literal["stage", "middleware", "run", "observer"] = "stage",
+    ) -> None:
+        self.name = name
+        self.context = context
+        self.phase = phase
+        self.observer_errors: tuple[Exception, ...] = ()
+        super().__init__(f"Pipeline {phase} failed: {name or '<run>'}")