pyfect-dev 0.1.0__py3-none-any.whl

pyfect/persistence/persisted_cache.py

@@ -0,0 +1,159 @@
+"""A ``Cache`` in front of a persistence store (Effect's
+``effect/persistence/PersistedCache``)::
+
+    users = yield from persisted_cache.make(
+        lambda req: fetch_user(req.id),
+        store_id="users",
+        time_to_live=lambda _exit, _req: 3600,
+    )
+    user = yield from users.get(GetUser(1))
+
+``get`` answers from memory, then from the ``Persistence`` store, then by
+running ``lookup`` and storing its outcome, failures and defects too. A
+stored outcome the request's schemas no longer read is looked up again
+and replaced.
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable, Generator
+from typing import Any, Literal, Never, Protocol, cast, overload
+
+from pyfect._catch import catch_tag
+from pyfect._core import Effect
+from pyfect.batching._request import TypedRequest
+from pyfect.cache import Cache, RequireServicesAt
+from pyfect.effect import from_exit, gen, succeed, suspend
+from pyfect.persistence._error import PersistenceError
+from pyfect.persistence.persistable import AnyPersistable, HasPersistableTypes, TimeToLive
+from pyfect.persistence.persistence import Persistence, PersistenceStore
+from pyfect.schema import SchemaError
+from pyfect.scope import Scope
+
+_IN_MEMORY_TTL = 10.0
+_IN_MEMORY_CAPACITY = 1024
+
+
+class _LookupTypes[K_co, A_co, E_co](Protocol):
+    def _lookup_types(self) -> tuple[K_co, A_co, E_co]: ...
+
+
+class PersistedCache[K: AnyPersistable, R = Never, A = Any, E = Any]:
+    """Make one with ``make``. ``get``'s success and error come from the
+    request's schemas; ``R`` is what the lookup needs when
+    ``require_services_at="lookup"``; ``A`` and ``E`` are what the lookup
+    gives, which must fit the request's schemas (``get`` is a pyright
+    error otherwise)."""
+
+    __slots__ = ("_in_memory", "_store")
+
+    def __init__(self, in_memory: Cache[K, Any, Any, Any], store: PersistenceStore) -> None:
+        self._in_memory = in_memory
+        self._store = store
+
+    def _lookup_types(self) -> tuple[K, A, E]:
+        """Never called: ties the lookup's success and error to the
+        request's for ``get``."""
+        raise NotImplementedError
+
+    @property
+    def in_memory(self) -> Cache[K, Any, Any, Any]:
+        """The in-memory cache in front of the store."""
+        return self._in_memory
+
+    def get[AA, EE, RR, SA, SE](
+        self: _LookupTypes[HasPersistableTypes[SA, SE], SA, SE],
+        key: TypedRequest[AA, EE, RR, K],
+    ) -> Effect[AA, EE, RR | R]:
+        """The outcome for ``key``: from memory, from the store, or looked
+        up now and stored."""
+        cache = cast("PersistedCache[K, R]", self)
+        return cache._in_memory.get(key)  # pyright: ignore[reportArgumentType]
+
+    def invalidate(self, key: K) -> Effect[None, PersistenceError]:
+        """Forget ``key`` in the store and in memory."""
+        return self._store.remove(key).and_then(self._in_memory.invalidate(key))
+
+
+@overload
+def make[K: AnyPersistable, A, E, R = Never](
+    lookup: Callable[[K], Effect[A, E, R]],
+    *,
+    store_id: str,
+    time_to_live: TimeToLive[K, A, E],
+    in_memory_capacity: int | None = _IN_MEMORY_CAPACITY,
+    in_memory_ttl: TimeToLive[K, A, E | PersistenceError | SchemaError] | None = None,
+    require_services_at: Literal["construction"] = "construction",
+) -> Effect[PersistedCache[K, Never, A, E], Never, R | Persistence | Scope]: ...
+@overload
+def make[K: AnyPersistable, A, E, R = Never](
+    lookup: Callable[[K], Effect[A, E, R]],
+    *,
+    store_id: str,
+    time_to_live: TimeToLive[K, A, E],
+    in_memory_capacity: int | None = _IN_MEMORY_CAPACITY,
+    in_memory_ttl: TimeToLive[K, A, E | PersistenceError | SchemaError] | None = None,
+    require_services_at: Literal["lookup"],
+) -> Effect[PersistedCache[K, R, A, E], Never, Persistence | Scope]: ...
+def make(
+    lookup: Callable[[Any], Effect[Any, Any, Any]],
+    *,
+    store_id: str,
+    time_to_live: TimeToLive[Any, Any, Any],
+    in_memory_capacity: int | None = _IN_MEMORY_CAPACITY,
+    in_memory_ttl: TimeToLive[Any, Any, Any] | None = None,
+    require_services_at: RequireServicesAt = "construction",
+) -> Effect[PersistedCache[Any, Any, Any, Any], Never, Any]:
+    """A cache of ``lookup``'s outcomes in the store ``store_id``, kept
+    there for ``time_to_live`` and in memory for ``in_memory_ttl``
+    (default: 10 seconds), at most ``in_memory_capacity`` of them (default:
+    1024). ``lookup`` must give the request's success or fail with its
+    error (a pyright error at ``get`` otherwise): the store writes them by
+    the request's schemas. ``time_to_live`` sees the lookup's ``Exit``;
+    ``in_memory_ttl`` may also see the store's failures."""
+
+    def body() -> Generator[Effect[Any, Any, Any], Any, PersistedCache[Any, Any, Any, Any]]:
+        persistence = yield from Persistence()
+        store = yield from persistence.make(store_id=store_id, time_to_live=time_to_live)
+
+        def cached_lookup(key: AnyPersistable) -> Effect[Any, Any, Any]:
+            def run() -> Generator[Effect[Any, Any, Any], Any, Any]:
+                stored = yield from store.get(key).pipe(
+                    catch_tag(SchemaError, lambda _: succeed(None))
+                )
+                if stored is not None:
+                    return (yield from from_exit(stored))
+                result = yield from suspend(lambda: lookup(key)).exit()
+                yield from store.set(key, result)
+                return (yield from from_exit(result))
+
+            return gen(run)
+
+        ttl: TimeToLive[Any, Any, Any] = in_memory_ttl or _default_in_memory_ttl
+        in_memory: Cache[Any, Any, Any, Any]
+        if require_services_at == "lookup":
+            in_memory = yield from Cache.make(
+                cached_lookup,
+                capacity=in_memory_capacity,
+                time_to_live=ttl,
+                require_services_at="lookup",
+            )
+        else:
+            in_memory = yield from Cache.make(
+                cached_lookup, capacity=in_memory_capacity, time_to_live=ttl
+            )
+        return PersistedCache(in_memory, store)
+
+    return gen(body)
+
+
+def _default_in_memory_ttl(_exit: object, _key: object) -> float:
+    return _IN_MEMORY_TTL
+
+
+__all__ = [
+    "PersistedCache",
+    "PersistenceError",
+    "make",
+]

pyfect/persistence/persisted_queue/__init__.py

@@ -0,0 +1,75 @@
+"""Durable queues of schema-typed values (Effect's
+``effect/persistence/PersistedQueue``)::
+
+    queue = yield from persisted_queue.make(name="emails", schema=Email)
+    yield from queue.offer(Email(to="ada@example.com"), id="welcome-ada")
+    yield from queue.take(lambda email, meta: send(email))
+
+``offer`` stores a value (an id the queue already has is not stored
+again); ``take`` runs a handler on the next value: success completes it,
+failure retries it on the queue's schedule until its attempts run out
+(then it is failed, the dead letter), interruption releases it. Delivery
+is at-least-once: a crash between a handler's success and its
+acknowledgement delivers the value again, so handlers must be idempotent.
+
+Queues come from ``PersistedQueueFactory`` (``layer``) over a
+``PersistedQueueStore``: ``layer_store_memory``, ``layer_store_sql`` (any
+``SqlClient``) or ``layer_store_redis``. ``layer_cleanup`` removes old
+completed (and, optionally, failed) elements.
+"""
+
+from pyfect._public import publish
+from pyfect.persistence.persisted_queue._error import PersistedQueueError
+from pyfect.persistence.persisted_queue._memory import layer_store_memory, make_store_memory
+from pyfect.persistence.persisted_queue._queue import (
+    DEFAULT_MAX_ATTEMPTS,
+    DEFAULT_RETRY_SCHEDULE,
+    Metadata,
+    PersistedQueue,
+    PersistedQueueFactory,
+    PersistedQueueFactoryService,
+    RetrySchedule,
+    layer,
+    layer_cleanup,
+    make,
+    make_factory,
+)
+from pyfect.persistence.persisted_queue._redis import layer_store_redis, make_store_redis
+from pyfect.persistence.persisted_queue._sql import layer_store_sql, make_store_sql
+from pyfect.persistence.persisted_queue._store import (
+    Cleanup,
+    Offer,
+    PersistedQueueStore,
+    PersistedQueueStoreService,
+    TakenElement,
+    TakeOptions,
+)
+
+__all__ = [
+    "DEFAULT_MAX_ATTEMPTS",
+    "DEFAULT_RETRY_SCHEDULE",
+    "Cleanup",
+    "Metadata",
+    "Offer",
+    "PersistedQueue",
+    "PersistedQueueError",
+    "PersistedQueueFactory",
+    "PersistedQueueFactoryService",
+    "PersistedQueueStore",
+    "PersistedQueueStoreService",
+    "RetrySchedule",
+    "TakeOptions",
+    "TakenElement",
+    "layer",
+    "layer_cleanup",
+    "layer_store_memory",
+    "layer_store_redis",
+    "layer_store_sql",
+    "make",
+    "make_factory",
+    "make_store_memory",
+    "make_store_redis",
+    "make_store_sql",
+]
+
+publish(globals())

pyfect/persistence/persisted_queue/_error.py

@@ -0,0 +1,42 @@
+"""``PersistedQueueError``, and ``DeadLetter``: how the factory tells a
+store that a taken element can never be processed."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pyfect import schema as S
+from pyfect.cause import Cause, Fail
+
+
+class PersistedQueueError(
+    S.TaggedError, identifier="effect/persistence/PersistedQueue/PersistedQueueError"
+):
+    """A queue store could not offer, take, settle or clean up; ``cause``
+    is what its backend raised."""
+
+    message: str
+    cause: object = S.field(S.Union(S.Null, S.Defect()), default=None)
+
+
+class DeadLetter:
+    """A taken element whose stored payload fails to decode: the store
+    marks it failed instead of retrying it, and the factory takes the next
+    one."""
+
+    __slots__ = ("cause",)
+
+    def __init__(self, cause: Cause[Any]) -> None:
+        self.cause = cause
+
+
+def is_dead_letter(error: object) -> bool:
+    return isinstance(error, DeadLetter)
+
+
+def dead_letter_from_cause(cause: Cause[Any]) -> DeadLetter | None:
+    """The ``DeadLetter`` a take's exit failed with, if any."""
+    for reason in cause.reasons:
+        if isinstance(reason, Fail) and isinstance(reason.error, DeadLetter):
+            return reason.error
+    return None

pyfect/persistence/persisted_queue/_mailbox.py

@@ -0,0 +1,101 @@
+"""The local mailbox of a polled store (Redis, SQL): one poller per queue
+claims as many elements as there are waiting takers and hands them out
+through an in-memory queue."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Generator, Sequence
+from dataclasses import dataclass, field
+from typing import Any, Never
+
+from pyfect._core import Effect, Restore, uninterruptible_mask
+from pyfect.clock import sleep
+from pyfect.duration import Seconds
+from pyfect.effect import gen, sync, yield_now
+from pyfect.latch import Latch
+from pyfect.logger import log_warning
+from pyfect.queue import Queue
+from pyfect.rc_map import RcMap
+from pyfect.schedule import spaced
+from pyfect.scope import Scope, scoped
+
+
+@dataclass(slots=True)
+class Mailbox[T]:
+    """Elements claimed for this process's takers, ``takers`` of them
+    waiting. The poller runs while ``poll_latch`` is open, and after
+    handing out a batch waits at ``taken_latch`` until every taker of the
+    batch has its element."""
+
+    queue: Queue[T] = field(default_factory=Queue[T])
+    takers: int = 0
+    poll_latch: Latch = field(default_factory=Latch)
+    taken_latch: Latch = field(default_factory=Latch)
+
+
+def run_poller[T](
+    mailbox: Mailbox[T],
+    *,
+    poll: Callable[[int], Effect[Sequence[T], Any]],
+    nudge: Latch,
+    poll_interval: Seconds,
+) -> Effect[None, Never, Scope]:
+    """Fork the mailbox's poller into the scope: while takers wait it
+    claims up to that many elements with ``poll``, and when there are none
+    waits ``poll_interval`` or until ``nudge`` opens. A failed poll is
+    logged and the poller restarts after 500 ms."""
+
+    def body() -> Generator[Any, Any]:
+        while True:
+            yield from mailbox.poll_latch.wait()
+            yield from yield_now()
+            nudge.close_unsafe()
+            results: Sequence[T] = [] if mailbox.takers == 0 else (yield from poll(mailbox.takers))
+            if not results:
+                yield from sleep(poll_interval).race(nudge.wait())
+                continue
+            mailbox.taken_latch.close_unsafe()
+            yield from mailbox.queue.offer_all(results)
+            yield from mailbox.taken_latch.wait()
+            yield from yield_now()
+
+    return (
+        gen(body)
+        .tap_cause(log_warning)
+        .sandbox()
+        .retry(spaced(0.5))
+        .interruptible()
+        .fork_scoped()
+        .as_void()
+    )
+
+
+def take_from[K, T, A, E](
+    mailboxes: RcMap[K, Mailbox[T], Any],
+    key: K,
+    then: Callable[[T], Effect[A, E, Scope]],
+) -> Effect[A, E, Scope]:
+    """Wait for the next element of ``key``'s mailbox and run ``then`` on
+    it uninterruptibly, so no interruption loses a claimed element. The
+    taker is counted while it waits (an interrupted wait stops counting
+    too, so the poller never fetches for a taker that left)."""
+
+    def body(restore: Restore) -> Effect[A, E, Scope]:
+        def wait(mailbox: Mailbox[T]) -> Effect[T, Never]:
+            mailbox.takers += 1
+            if mailbox.takers == 1:
+                mailbox.poll_latch.open_unsafe()
+
+            def leave() -> None:
+                mailbox.takers -= 1
+                if mailbox.takers == 0:
+                    mailbox.poll_latch.close_unsafe()
+                    mailbox.taken_latch.open_unsafe()
+                elif mailbox.queue.size_unsafe() == 0:
+                    mailbox.taken_latch.open_unsafe()
+
+            return restore(mailbox.queue.take()).on_exit(lambda _: sync(leave))
+
+        return scoped(mailboxes.get(key).flat_map(wait)).flat_map(then)
+
+    return uninterruptible_mask(body)

pyfect/persistence/persisted_queue/_memory.py

@@ -0,0 +1,182 @@
+"""``layer_store_memory``: queues in process memory."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Generator
+from dataclasses import dataclass, field
+from typing import Any, Literal, Never
+
+from pyfect._core import Effect
+from pyfect.clock import ClockService, clock_with, sleep
+from pyfect.duration import Seconds, to_millis
+from pyfect.effect import gen, succeed, sync, void
+from pyfect.exit import Exit, Success
+from pyfect.latch import Latch
+from pyfect.layer import Layer
+from pyfect.layer import effect as layer_effect
+from pyfect.persistence._seconds import millis
+from pyfect.persistence.persisted_queue._error import PersistedQueueError, dead_letter_from_cause
+from pyfect.persistence.persisted_queue._store import (
+    PersistedQueueStore,
+    PersistedQueueStoreService,
+    TakenElement,
+    TakeOptions,
+)
+from pyfect.persistence.persistence._service import now_millis
+from pyfect.scope import Scope, add_finalizer
+
+type _State = Literal["pending", "processing", "completed", "failed"]
+
+
+@dataclass(eq=False, slots=True)
+class _Entry:
+    id: str
+    element: object
+    attempts: int
+    state: _State
+    visible_at: float
+    state_changed_at: float
+
+
+@dataclass(slots=True)
+class _Queue:
+    latch: Latch = field(default_factory=Latch)
+    entries: dict[str, _Entry] = field(default_factory=dict[str, _Entry])
+    """Every entry offered, for de-duplication."""
+    pending: dict[_Entry, None] = field(default_factory=dict[_Entry, None])
+    """The deliverable entries, in offer order, so a take does not scan the
+    completed backlog."""
+
+
+class _MemoryStore:
+    __slots__ = ("_clock", "_queues")
+
+    def __init__(self, clock: ClockService) -> None:
+        self._clock = clock
+        self._queues: dict[str, _Queue] = {}
+
+    def _queue(self, name: str) -> _Queue:
+        queue = self._queues.get(name)
+        if queue is None:
+            queue = self._queues[name] = _Queue()
+        return queue
+
+    def offer(
+        self,
+        *,
+        name: str,
+        id: str,
+        element: object,
+        is_custom_id: bool,
+        delay: Seconds | None = None,
+    ) -> Effect[None, PersistedQueueError]:
+        def run() -> None:
+            now = now_millis(self._clock)
+            queue = self._queue(name)
+            if id in queue.entries:
+                return
+            visible_at = now if delay is None else now + to_millis(delay)
+            entry = _Entry(id, element, 0, "pending", visible_at, now)
+            queue.entries[id] = entry
+            queue.pending[entry] = None
+            queue.latch.open_unsafe()
+
+        return sync(run)
+
+    def _settle(
+        self, queue: _Queue, entry: _Entry, options: TakeOptions, exit_: Exit[Any, Any]
+    ) -> Effect[None]:
+        now = now_millis(self._clock)
+
+        def finish(state: _State) -> Effect[None]:
+            entry.state = state
+            entry.state_changed_at = now
+            return void
+
+        def requeue() -> None:
+            entry.state = "pending"
+            queue.pending[entry] = None
+            queue.latch.open_unsafe()
+
+        def retry_after(delay: Seconds) -> None:
+            entry.visible_at = now + to_millis(delay)
+            requeue()
+
+        if isinstance(exit_, Success):
+            return finish("completed")
+        if dead_letter_from_cause(exit_.cause) is not None:
+            return finish("failed")
+        if exit_.cause.has_interrupts_only:
+            entry.attempts -= 1
+            return sync(requeue)
+        if entry.attempts >= options.max_attempts:
+            return finish("failed")
+        return options.retry_delay(entry.attempts).map(retry_after)
+
+    def _claim(
+        self, queue: _Queue, entry: _Entry, options: TakeOptions
+    ) -> Effect[TakenElement, Never, Scope]:
+        entry.state = "processing"
+        entry.attempts += 1
+        del queue.pending[entry]
+        queue.latch.open_unsafe()
+        return add_finalizer(lambda exit_: self._settle(queue, entry, options, exit_)).as_(
+            TakenElement(entry.id, entry.attempts, entry.element)
+        )
+
+    def take(self, options: TakeOptions) -> Effect[TakenElement, PersistedQueueError, Scope]:
+        def body() -> Generator[Any, Any, TakenElement]:
+            queue = self._queue(options.name)
+            while True:
+                # close before scanning, so a change after the scan reopens it
+                queue.latch.close_unsafe()
+                now = now_millis(self._clock)
+                next_visible_at = math.inf
+                item: _Entry | None = None
+                for entry in queue.pending:
+                    if entry.attempts >= options.max_attempts:
+                        continue
+                    if entry.visible_at <= now:
+                        item = entry
+                        break
+                    next_visible_at = min(next_visible_at, entry.visible_at)
+                if item is not None:
+                    return (yield from self._claim(queue, item, options))
+                if math.isinf(next_visible_at):
+                    yield from queue.latch.wait()
+                else:
+                    yield from queue.latch.wait().race(sleep(millis(next_visible_at - now)))
+
+        return gen(body)
+
+    def cleanup(
+        self, *, time_to_live: Seconds, failed_time_to_live: Seconds | None
+    ) -> Effect[None, PersistedQueueError]:
+        def run() -> None:
+            now = now_millis(self._clock)
+            cutoffs: dict[_State, float] = {"completed": now - to_millis(time_to_live)}
+            if failed_time_to_live is not None:
+                cutoffs["failed"] = now - to_millis(failed_time_to_live)
+            for queue in self._queues.values():
+                for id, entry in list(queue.entries.items()):
+                    cutoff = cutoffs.get(entry.state)
+                    if cutoff is not None and entry.state_changed_at <= cutoff:
+                        del queue.entries[id]
+
+        return sync(run)
+
+
+def make_store_memory(clock: ClockService) -> PersistedQueueStoreService:
+    """A store whose queues live in dicts, timed by ``clock``. Delayed
+    entries are scanned on every take, so it is for development and tests
+    rather than large delayed backlogs."""
+    store = _MemoryStore(clock)
+    return PersistedQueueStoreService(offer=store.offer, take=store.take, cleanup=store.cleanup)
+
+
+layer_store_memory: Layer[PersistedQueueStore] = layer_effect(
+    PersistedQueueStore, clock_with(lambda clock: succeed(make_store_memory(clock)))
+)
+"""Queues in process memory, fresh each time the layer is built: failed
+takes are retried on the queue's schedule until its attempts run out."""