chrono-daemon 0.1.0__py3-none-any.whl

chrono_daemon/__init__.py

@@ -0,0 +1,53 @@
+"""Tiny anyio-based concurrency primitives.
+
+Public surface:
+
+- :class:`Channel`, :class:`SendStream`, :class:`ReceiveStream`, :func:`open_channel`,
+  :exc:`EndOfStream`, :exc:`ChannelClosed`, :exc:`ChannelInUse`
+- :class:`Clock`, :class:`WallClock`, :class:`SimClock`
+- :class:`Context`
+- :class:`Daemon`, :func:`daemon`
+- :class:`Supervisor`, :class:`RestartPolicy`, :data:`OnError`
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version as _package_version
+
+from chrono_daemon._types import ChannelClosed, ChannelInUse, DaemonError, EndOfStream, OnError, WouldBlock
+from chrono_daemon.channel import Channel, ChannelStats, ReceiveStream, SendStream, open_channel
+from chrono_daemon.clock import Clock, SimClock, WallClock
+from chrono_daemon.context import Context
+from chrono_daemon.daemon import Daemon, daemon
+from chrono_daemon.supervisor import DaemonFailurePhase, DaemonHealth, DaemonState, RestartPolicy, Supervisor
+
+try:
+    __version__ = _package_version("chrono-daemon")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "Channel",
+    "ChannelClosed",
+    "ChannelInUse",
+    "ChannelStats",
+    "Clock",
+    "Context",
+    "Daemon",
+    "DaemonError",
+    "DaemonFailurePhase",
+    "DaemonHealth",
+    "DaemonState",
+    "EndOfStream",
+    "OnError",
+    "ReceiveStream",
+    "RestartPolicy",
+    "SendStream",
+    "SimClock",
+    "Supervisor",
+    "WallClock",
+    "WouldBlock",
+    "__version__",
+    "daemon",
+    "open_channel",
+]

chrono_daemon/_logging.py

@@ -0,0 +1,32 @@
+"""Internal: clock-aware logging adapter."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import MutableMapping
+
+    from chrono_daemon.clock import Clock
+
+
+__all__ = ["ClockAwareLoggerAdapter"]
+
+
+class ClockAwareLoggerAdapter(logging.LoggerAdapter):
+    """LoggerAdapter that adds ``clock.now()`` as ``sim_time``."""
+
+    def __init__(self, logger: logging.Logger, clock: Clock) -> None:
+        super().__init__(logger, {})
+        self._clock = clock
+
+    def process(
+        self,
+        msg: Any,
+        kwargs: MutableMapping[str, Any],
+    ) -> tuple[Any, MutableMapping[str, Any]]:
+        extra = kwargs.setdefault("extra", {})
+        # Don't overwrite an explicit sim_time the user already passed.
+        extra.setdefault("sim_time", self._clock.now())
+        return msg, kwargs

chrono_daemon/_types.py

@@ -0,0 +1,38 @@
+"""Internal type aliases and exceptions for chrono_daemon."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+__all__ = [
+    "ChannelClosed",
+    "ChannelInUse",
+    "DaemonError",
+    "EndOfStream",
+    "OnError",
+    "WouldBlock",
+]
+
+
+class EndOfStream(Exception):
+    """Raised after the send side is closed and the buffer is drained."""
+
+
+class ChannelClosed(Exception):
+    """Raised after the receive side has closed."""
+
+
+class ChannelInUse(Exception):
+    """Raised when a channel endpoint is used concurrently."""
+
+
+class WouldBlock(Exception):
+    """Raised when a nowait operation cannot complete immediately."""
+
+
+class DaemonError(Exception):
+    """Wraps an exception that escaped a daemon lifecycle method."""
+
+
+OnError = Literal["shutdown", "restart", "ignore"]
+"""Supervisor policy for uncaught daemon exceptions."""

chrono_daemon/channel.py

@@ -0,0 +1,212 @@
+"""Typed single-producer / single-consumer channel."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from typing import Generic, Protocol, TypeVar
+
+import anyio
+from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
+
+from chrono_daemon._types import ChannelClosed, ChannelInUse, EndOfStream, WouldBlock
+
+__all__ = ["Channel", "ChannelStats", "ReceiveStream", "SendStream", "open_channel"]
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class ChannelStats:
+    """Transport-agnostic channel diagnostics."""
+
+    current_buffer_used: int
+    """Items currently buffered in the channel."""
+
+    max_buffer_size: float
+    """Configured buffer capacity. ``math.inf`` if unbounded; ``0`` for rendezvous."""
+
+    open_send_streams: int
+    """How many ``SendStream`` instances are still open."""
+
+    open_receive_streams: int
+    """How many ``ReceiveStream`` instances are still open."""
+
+    waiters_send: int
+    """Tasks currently blocked in ``send()`` waiting for buffer space."""
+
+    waiters_receive: int
+    """Tasks currently blocked in ``receive()`` waiting for an item."""
+
+
+class SendStream(Protocol[T]):
+    """Sender side of a channel. Intended to be owned by one active producer."""
+
+    async def send(self, item: T) -> None:
+        """Send an item. Blocks (under the channel's backpressure) until a slot is free.
+
+        Raises ``ChannelClosed`` if the receive side has been closed.
+        """
+        ...
+
+    def send_nowait(self, item: T) -> None:
+        """Send an item without blocking. Raises ``WouldBlock`` if the buffer is full.
+
+        Raises ``ChannelClosed`` if the receive side has been closed.
+        """
+        ...
+
+    async def aclose(self) -> None:
+        """Close the send side. Waiting receivers get ``EndOfStream`` after the buffer drains."""
+        ...
+
+    def statistics(self) -> ChannelStats:
+        """Snapshot the channel's runtime state for diagnostics. Read-only and cheap."""
+        ...
+
+
+class ReceiveStream(Protocol[T]):
+    """Receiver side of a channel. Intended to be owned by one active consumer."""
+
+    async def receive(self) -> T:
+        """Receive one item. Blocks until an item is available.
+
+        Raises ``EndOfStream`` if the send side has been closed and the buffer is drained.
+        """
+        ...
+
+    def receive_nowait(self) -> T:
+        """Receive one item without blocking. Raises ``WouldBlock`` if the buffer is empty.
+
+        Raises ``EndOfStream`` if the send side has closed and the buffer is
+        drained.
+        """
+        ...
+
+    def __aiter__(self) -> AsyncIterator[T]:
+        """Iterate until ``EndOfStream`` (which is swallowed by the iterator protocol)."""
+        ...
+
+    async def aclose(self) -> None:
+        """Close the receive side. Producers calling ``send()`` get ``ChannelClosed``."""
+        ...
+
+    def statistics(self) -> ChannelStats:
+        """Snapshot the channel's runtime state for diagnostics. Read-only and cheap."""
+        ...
+
+
+@dataclass
+class Channel(Generic[T]):
+    """A typed bounded channel.
+
+    The ``send`` and ``recv`` attributes are independent endpoints; you typically pass
+    one into a producer daemon and the other into a consumer daemon.
+    """
+
+    send: SendStream[T]
+    recv: ReceiveStream[T]
+
+
+def _stats_from_anyio(inner: MemoryObjectSendStream[T] | MemoryObjectReceiveStream[T]) -> ChannelStats:
+    s = inner.statistics()
+    return ChannelStats(
+        current_buffer_used=s.current_buffer_used,
+        max_buffer_size=s.max_buffer_size,
+        open_send_streams=s.open_send_streams,
+        open_receive_streams=s.open_receive_streams,
+        waiters_send=s.tasks_waiting_send,
+        waiters_receive=s.tasks_waiting_receive,
+    )
+
+
+class _Send(Generic[T]):
+    """In-process ``SendStream`` wrapping an anyio memory object send stream."""
+
+    def __init__(self, inner: MemoryObjectSendStream[T]) -> None:
+        self._inner = inner
+        self._busy = False
+
+    async def send(self, item: T) -> None:
+        if self._busy:
+            raise ChannelInUse("send endpoint already has an active sender")
+        self._busy = True
+        try:
+            await self._inner.send(item)
+        except anyio.BrokenResourceError as e:
+            raise ChannelClosed("receive side closed") from e
+        except anyio.ClosedResourceError as e:
+            raise ChannelClosed("send side already closed") from e
+        finally:
+            self._busy = False
+
+    def send_nowait(self, item: T) -> None:
+        try:
+            self._inner.send_nowait(item)
+        except anyio.WouldBlock as e:
+            raise WouldBlock("channel buffer full") from e
+        except anyio.BrokenResourceError as e:
+            raise ChannelClosed("receive side closed") from e
+        except anyio.ClosedResourceError as e:
+            raise ChannelClosed("send side already closed") from e
+
+    async def aclose(self) -> None:
+        await self._inner.aclose()
+
+    def statistics(self) -> ChannelStats:
+        return _stats_from_anyio(self._inner)
+
+
+class _Recv(Generic[T]):
+    """In-process ``ReceiveStream`` wrapping an anyio memory object receive stream."""
+
+    def __init__(self, inner: MemoryObjectReceiveStream[T]) -> None:
+        self._inner = inner
+        self._busy = False
+
+    async def receive(self) -> T:
+        if self._busy:
+            raise ChannelInUse("receive endpoint already has an active receiver")
+        self._busy = True
+        try:
+            return await self._inner.receive()
+        except anyio.EndOfStream as e:
+            raise EndOfStream from e
+        except anyio.ClosedResourceError as e:
+            raise EndOfStream from e
+        finally:
+            self._busy = False
+
+    def receive_nowait(self) -> T:
+        try:
+            return self._inner.receive_nowait()
+        except anyio.WouldBlock as e:
+            raise WouldBlock("channel empty") from e
+        except anyio.EndOfStream as e:
+            raise EndOfStream from e
+        except anyio.ClosedResourceError as e:
+            raise EndOfStream from e
+
+    async def __aiter__(self) -> AsyncIterator[T]:  # type: ignore[override]
+        # Route through receive() for our EndOfStream conversion.
+        while True:
+            try:
+                yield await self.receive()
+            except EndOfStream:
+                return
+
+    async def aclose(self) -> None:
+        await self._inner.aclose()
+
+    def statistics(self) -> ChannelStats:
+        return _stats_from_anyio(self._inner)
+
+
+def open_channel(maxsize: int = 0) -> Channel[T]:
+    """Open a new in-process channel.
+
+    ``maxsize=0`` is rendezvous. Positive values allow buffering. Concurrent
+    blocking use of one endpoint raises ``ChannelInUse``.
+    """
+    send_inner, recv_inner = anyio.create_memory_object_stream[T](max_buffer_size=maxsize)
+    return Channel(send=_Send(send_inner), recv=_Recv(recv_inner))

chrono_daemon/clock.py

@@ -0,0 +1,190 @@
+"""Clock abstractions for real time and deterministic replay.
+
+Daemons should use ``ctx.clock`` instead of ``anyio.sleep`` so ``SimClock`` can
+control time during tests.
+"""
+
+from __future__ import annotations
+
+import heapq
+import itertools
+import time
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from typing import Protocol
+
+import anyio
+import anyio.lowlevel
+
+__all__ = ["Clock", "SimClock", "WallClock"]
+
+# Checkpoints yielded between heap inspections so woken tasks can register
+# follow-up sleeps. anyio has no portable "run until idle" primitive.
+_DEFAULT_SETTLE_ROUNDS = 8
+
+
+class Clock(Protocol):
+    """Minimal time interface used by chrono-daemon daemons."""
+
+    def now(self) -> float:
+        """Return current time in seconds. Monotonic; the units (epoch vs zero-based) are clock-specific."""
+        ...
+
+    async def sleep(self, seconds: float) -> None:
+        """Sleep for ``seconds`` of clock-time. Non-positive values yield once and return."""
+        ...
+
+    async def wait_until(self, deadline: float) -> None:
+        """Sleep until absolute clock-time ``deadline``. Past deadlines yield once and return."""
+        ...
+
+    def every(self, period: float) -> AsyncIterator[float]:
+        """Yield clock-time stamps every ``period`` seconds.
+
+        The first tick is at ``now() + period``. If the consumer falls behind,
+        missed ticks are skipped.
+        """
+        ...
+
+
+class WallClock:
+    """Real-time clock delegating to anyio's monotonic clock and sleep."""
+
+    def now(self) -> float:
+        return time.monotonic()
+
+    async def sleep(self, seconds: float) -> None:
+        if seconds <= 0:
+            await anyio.lowlevel.checkpoint()
+            return
+        await anyio.sleep(seconds)
+
+    async def wait_until(self, deadline: float) -> None:
+        await self.sleep(deadline - self.now())
+
+    async def every(self, period: float) -> AsyncIterator[float]:
+        if period <= 0:
+            raise ValueError(f"every() period must be positive, got {period}")
+        next_t = self.now() + period
+        while True:
+            now = self.now()
+            if next_t > now:
+                await self.sleep(next_t - now)
+            yield next_t
+            # Skip missed ticks to maintain monotonic target schedule.
+            now = self.now()
+            while next_t <= now:
+                next_t += period
+
+
+@dataclass
+class _Waiter:
+    """One sleeper registered against a SimClock."""
+
+    deadline: float
+    seq: int
+    event: anyio.Event = field(compare=False)
+    cancelled: bool = field(default=False, compare=False)
+
+    def __lt__(self, other: _Waiter) -> bool:
+        return (self.deadline, self.seq) < (other.deadline, other.seq)
+
+
+class SimClock:
+    """Deterministic virtual clock.
+
+    Time only moves when a driver task calls ``advance(dt)`` or ``advance_to(t)``.
+    All sleepers are released exactly at their registered deadline, in deadline order,
+    with insertion order as the tiebreaker.
+    """
+
+    def __init__(self, t0: float = 0.0, *, settle_rounds: int = _DEFAULT_SETTLE_ROUNDS) -> None:
+        if settle_rounds < 1:
+            raise ValueError(f"settle_rounds must be >= 1, got {settle_rounds}")
+        self._t = float(t0)
+        self._settle_rounds = settle_rounds
+        # Min-heap of pending sleepers ordered by (deadline, seq). seq breaks
+        # ties stably. Cancelled entries stay in the heap with cancelled=True
+        # and are skipped on pop.
+        self._waiters: list[_Waiter] = []
+        self._seq = itertools.count()
+
+    def now(self) -> float:
+        return self._t
+
+    async def sleep(self, seconds: float) -> None:
+        # Checkpoint first so a freshly-cancelled caller exits before enqueueing.
+        await anyio.lowlevel.checkpoint()
+        if seconds <= 0:
+            return
+        await self.wait_until(self._t + seconds)
+
+    async def wait_until(self, deadline: float) -> None:
+        # Checkpoint first so a freshly-cancelled caller exits before enqueueing.
+        await anyio.lowlevel.checkpoint()
+        if deadline <= self._t:
+            return
+        waiter = _Waiter(deadline=deadline, seq=next(self._seq), event=anyio.Event())
+        heapq.heappush(self._waiters, waiter)
+        try:
+            await waiter.event.wait()
+        finally:
+            # Lazy delete: skip cancelled entries on pop instead of removing
+            # them from the middle of the heap.
+            if not waiter.event.is_set():
+                waiter.cancelled = True
+                while self._waiters and self._waiters[0].cancelled:
+                    heapq.heappop(self._waiters)
+
+    async def advance(self, dt: float) -> None:
+        """Advance virtual time by ``dt`` seconds."""
+        if dt < 0:
+            raise ValueError(f"cannot advance backwards (dt={dt})")
+        await self.advance_to(self._t + dt)
+
+    async def advance_to(self, t: float) -> None:
+        """Advance virtual time to absolute ``t``."""
+        if t < self._t:
+            return
+        while True:
+            self._drop_cancelled_tops()
+            if not self._waiters or self._waiters[0].deadline > t:
+                if not await self._poll_for_inrange(t):
+                    break
+                continue
+            waiter = heapq.heappop(self._waiters)
+            if waiter.cancelled:
+                # Raced with cancellation between top-skip and pop; just retry.
+                continue
+            self._t = waiter.deadline
+            waiter.event.set()
+            for _ in range(self._settle_rounds):
+                await anyio.lowlevel.checkpoint()
+        self._t = max(self._t, t)
+
+    def _drop_cancelled_tops(self) -> None:
+        """Pop any cancelled entries sitting at the top of the heap."""
+        while self._waiters and self._waiters[0].cancelled:
+            heapq.heappop(self._waiters)
+
+    async def _poll_for_inrange(self, t: float) -> bool:
+        """Settle woken tasks and report whether a due sleeper appeared."""
+        for _ in range(self._settle_rounds):
+            await anyio.lowlevel.checkpoint()
+        self._drop_cancelled_tops()
+        return bool(self._waiters) and self._waiters[0].deadline <= t
+
+    async def every(self, period: float) -> AsyncIterator[float]:
+        if period <= 0:
+            raise ValueError(f"every() period must be positive, got {period}")
+        next_t = self._t + period
+        while True:
+            delta = next_t - self._t
+            if delta > 0:
+                await self.wait_until(next_t)
+            yield next_t
+            # Skip missed ticks instead of catching up in a burst.
+            next_t += period
+            now = self._t
+            while next_t <= now:
+                next_t += period

chrono_daemon/context.py

@@ -0,0 +1,38 @@
+"""Per-daemon execution context."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+import anyio
+
+if TYPE_CHECKING:
+    from chrono_daemon._logging import ClockAwareLoggerAdapter
+    from chrono_daemon.clock import Clock
+    from chrono_daemon.supervisor import Supervisor
+
+__all__ = ["Context"]
+
+
+@dataclass(frozen=True, slots=True)
+class Context:
+    """Handle passed to each daemon's ``run(ctx)``.
+
+    Use ``ctx.clock`` for sleeps. ``ctx.cancel_scope`` is per-daemon; use
+    ``ctx.supervisor.signal_stop()`` to request whole-supervisor shutdown.
+    ``ctx.stopping`` and ``ctx.stop_event`` expose that stop signal.
+    """
+
+    clock: Clock
+    cancel_scope: anyio.CancelScope
+    logger: ClockAwareLoggerAdapter | logging.Logger
+    name: str
+    supervisor: Supervisor
+    stop_event: anyio.Event
+
+    @property
+    def stopping(self) -> bool:
+        """``True`` once ``supervisor.signal_stop()`` (or ``stop()``) has been called."""
+        return self.stop_event.is_set()

chrono_daemon/daemon.py

@@ -0,0 +1,80 @@
+"""Daemon lifecycle base class and decorator."""
+
+from __future__ import annotations
+
+import functools
+from abc import ABC, abstractmethod
+from collections.abc import Callable, Coroutine
+from typing import TYPE_CHECKING, Any, overload
+
+if TYPE_CHECKING:
+    from chrono_daemon.context import Context
+
+__all__ = ["Daemon", "daemon"]
+
+
+class Daemon(ABC):
+    """Abstract long-running async unit."""
+
+    name: str = ""
+
+    async def on_start(self, ctx: Context) -> None:
+        """Called once before ``run``. Defaults to no-op."""
+
+    @abstractmethod
+    async def run(self, ctx: Context) -> None:
+        """Main body. Use ``ctx.clock`` for sleeps."""
+
+    async def on_stop(self, ctx: Context) -> None:
+        """Called once after ``run`` completes (or after a final restart failure). Defaults to no-op."""
+
+
+class _FnDaemon(Daemon):
+    """Internal adapter wrapping a function into a Daemon. Returned by ``@daemon``."""
+
+    def __init__(
+        self,
+        fn: Callable[..., Coroutine[Any, Any, None]],
+        args: tuple[Any, ...],
+        kwargs: dict[str, Any],
+        name: str,
+    ) -> None:
+        self._fn = fn
+        self._args = args
+        self._kwargs = kwargs
+        self.name = name
+
+    async def run(self, ctx: Context) -> None:
+        await self._fn(ctx, *self._args, **self._kwargs)
+
+
+_AsyncFn = Callable[..., Coroutine[Any, Any, None]]
+
+
+@overload
+def daemon(fn: _AsyncFn, /) -> Callable[..., Daemon]: ...
+@overload
+def daemon(*, name: str | None = None) -> Callable[[_AsyncFn], Callable[..., Daemon]]: ...
+
+
+def daemon(  # type: ignore[misc]
+    fn: Callable[..., Coroutine[Any, Any, None]] | None = None,
+    *,
+    name: str | None = None,
+) -> Any:
+    """Turn ``async def fn(ctx, *args, **kwargs)`` into a Daemon factory."""
+
+    def wrap(f: Callable[..., Coroutine[Any, Any, None]]) -> Callable[..., Daemon]:
+        chosen_name = name or f.__name__
+
+        @functools.wraps(f)
+        def factory(*args: Any, **kwargs: Any) -> Daemon:
+            return _FnDaemon(f, args, kwargs, chosen_name)
+
+        # Marker for debug/repr tooling; not part of the public API.
+        factory._chrono_daemon_factory = True  # type: ignore[attr-defined]
+        return factory
+
+    if fn is not None:
+        return wrap(fn)
+    return wrap

chrono_daemon/recipes/__init__.py

@@ -0,0 +1,35 @@
+"""Importable helpers kept outside the core surface.
+
+- The core primitives in ``chrono_daemon`` follow strict semver: breaking changes
+  require an ADR and a major bump.
+- ``chrono_daemon.recipes`` are best-effort references. Their signatures may
+  change between minor releases without an ADR. If you depend on one in
+  production code, pin a version or vendor it.
+
+Use them by importing directly:
+
+    # Routing
+    from chrono_daemon.recipes.fanout import tee
+    from chrono_daemon.recipes.merge import merge
+    from chrono_daemon.recipes.load_balance import load_balance
+    from chrono_daemon.recipes.worker_pool import worker_pool
+
+    # Coordination
+    from chrono_daemon.recipes.select import select
+    from chrono_daemon.recipes.batcher import batcher_loop, submit
+    from chrono_daemon.recipes.cooperative_every import cooperative_every
+
+    # State and buffering
+    from chrono_daemon.recipes.latest import Latest
+    from chrono_daemon.recipes.lossy import DropOldestSend, DropNewestSend, CoalesceSend
+
+    # Hosting
+    from chrono_daemon.recipes.supervisor_host import SupervisorHost
+    from chrono_daemon.recipes.sync_bridge import host_async_dispatcher
+
+The implementation is grouped into ``routing``, ``coordination``, ``state``,
+and ``hosting`` subpackages. Top-level recipe modules remain compatibility
+imports.
+
+The corresponding design notes live in ``docs/recipes.md``.
+"""