rotorcore 0.0.1__py3-none-any.whl

rotor/__init__.py

@@ -0,0 +1,150 @@
+"""Durable process runtime for Python."""
+
+from .backends import Backends
+from .blob import Blob, BlobStore, FileBlobStore, MemoryBlobStore, S3BlobStore, VercelBlobStore
+from .client import Client, Handle
+from .context import (
+    PendingHook,
+    current_context,
+    idempotency_key,
+    meter,
+    record,
+    stream,
+)
+from .engine import TickResult
+from .errors import (
+    CallConflict,
+    CallFailed,
+    CallTimeout,
+    ConfigurationError,
+    ForgedFact,
+    HookError,
+    HookNotFound,
+    HookNotPending,
+    MailboxClosed,
+    MailboxOverflow,
+    NoReply,
+    NotAnActivation,
+    ProcessConflict,
+    ProcessNotFound,
+    RotorError,
+    StaleDeployment,
+    StaleLease,
+    UnknownType,
+    UnmigratablePayload,
+)
+from .journal import Journal
+from .limits import Ceiling, Limits, per, per_day, per_hour, total
+from .live import (
+    Chunk,
+    Gap,
+    LiveTransport,
+    MemoryLiveTransport,
+    PostgresLiveTransport,
+    RedisLiveTransport,
+    Settled,
+)
+from .maintenance import JanitorResult, ReconcileResult
+from .messages import (
+    Cancelled,
+    ChildDone,
+    ChildFailed,
+    EmptyState,
+    ErrorInfo,
+    HandlingFailed,
+    HookExpired,
+    HookResolved,
+    LimitExceeded,
+    ProcessRef,
+    Resolution,
+    Start,
+    TerminalFailure,
+    message,
+    state,
+)
+from .process import DurableProcess, child_id, on, query, singleton_id
+from .worker import Worker
+
+__version__ = "0.0.1"
+
+__all__ = [
+    # the process
+    "DurableProcess",
+    "ProcessRef",
+    "EmptyState",
+    "child_id",
+    "singleton_id",
+    "on",
+    "query",
+    # messages & facts
+    "message",
+    "Resolution",
+    "state",
+    "Start",
+    "ChildDone",
+    "ChildFailed",
+    "HookResolved",
+    "HookExpired",
+    "HandlingFailed",
+    "LimitExceeded",
+    "Cancelled",
+    "ErrorInfo",
+    "TerminalFailure",
+    # ambient context
+    "current_context",
+    "meter",
+    "record",
+    "stream",
+    "idempotency_key",
+    "PendingHook",
+    "Chunk",
+    "Settled",
+    "Gap",
+    "LiveTransport",
+    "MemoryLiveTransport",
+    "PostgresLiveTransport",
+    "RedisLiveTransport",
+    # limits
+    "Limits",
+    "Ceiling",
+    "per",
+    "per_day",
+    "per_hour",
+    "total",
+    # blobs & journals
+    "Blob",
+    "BlobStore",
+    "FileBlobStore",
+    "MemoryBlobStore",
+    "S3BlobStore",
+    "VercelBlobStore",
+    "Journal",
+    # the two halves
+    "Client",
+    "Handle",
+    "Worker",
+    "TickResult",
+    "ReconcileResult",
+    "JanitorResult",
+    "Backends",
+    # errors
+    "RotorError",
+    "ConfigurationError",
+    "ProcessNotFound",
+    "ProcessConflict",
+    "MailboxClosed",
+    "MailboxOverflow",
+    "NoReply",
+    "CallFailed",
+    "CallTimeout",
+    "CallConflict",
+    "ForgedFact",
+    "NotAnActivation",
+    "HookError",
+    "HookNotFound",
+    "HookNotPending",
+    "StaleLease",
+    "StaleDeployment",
+    "UnknownType",
+    "UnmigratablePayload",
+]

rotor/_time.py

@@ -0,0 +1,114 @@
+"""Durations, cron, and the injectable clock.
+
+One duration grammar everywhere: ``"30s"``, ``"5m"``, ``"2h"``, ``"1d"`` —
+shared by timers, limits windows, retention, and lease settings. Cron is the
+standard 5-field grammar with an optional IANA timezone, because a daemon's
+"7am brief" lives in the user's morning, not UTC's.
+"""
+
+from __future__ import annotations
+
+import re
+import time as _time
+from datetime import UTC, datetime, timedelta
+from zoneinfo import ZoneInfo
+
+from .errors import ConfigurationError
+
+_DURATION = re.compile(r"^(\d+(?:\.\d+)?)(s|m|h|d)$")
+_UNIT = {"s": 1.0, "m": 60.0, "h": 3600.0, "d": 86400.0}
+
+
+def parse_duration(value: str | int | float) -> float:
+    """``"90s"`` → 90.0. Bare numbers are seconds."""
+    if isinstance(value, (int, float)):
+        return float(value)
+    m = _DURATION.match(value.strip())
+    if not m:
+        raise ConfigurationError(f"bad duration {value!r} — expected e.g. '30s', '5m', '2h', '1d'")
+    return float(m.group(1)) * _UNIT[m.group(2)]
+
+
+class Clock:
+    """Wall clock. Tests substitute VirtualClock; everything asks the clock."""
+
+    def now(self) -> float:
+        return _time.time()
+
+
+class VirtualClock(Clock):
+    """A clock that only moves when told to. The testing harness's heart."""
+
+    def __init__(self, start: float = 1_700_000_000.0) -> None:
+        self._now = start
+
+    def now(self) -> float:
+        return self._now
+
+    def advance(self, duration: str | int | float) -> None:
+        self._now += parse_duration(duration)
+
+
+def _parse_field(field: str, lo: int, hi: int) -> set[int]:
+    values: set[int] = set()
+    for part in field.split(","):
+        step = 1
+        if "/" in part:
+            part, step_s = part.split("/", 1)
+            step = int(step_s)
+        if part == "*":
+            lo_, hi_ = lo, hi
+        elif "-" in part:
+            a, b = part.split("-", 1)
+            lo_, hi_ = int(a), int(b)
+        else:
+            lo_ = hi_ = int(part)
+        if not (lo <= lo_ <= hi_ <= hi):
+            raise ConfigurationError(f"cron field {field!r} out of range {lo}-{hi}")
+        values.update(range(lo_, hi_ + 1, step))
+    return values
+
+
+class Cron:
+    """Five fields: minute hour day-of-month month day-of-week (0=Sunday)."""
+
+    def __init__(self, expr: str, tz: str | None = None) -> None:
+        fields = expr.split()
+        if len(fields) != 5:
+            raise ConfigurationError(f"bad cron {expr!r} — expected 5 fields")
+        self.expr = expr
+        self.tz = tz
+        self.minute = _parse_field(fields[0], 0, 59)
+        self.hour = _parse_field(fields[1], 0, 23)
+        self.dom = _parse_field(fields[2], 1, 31)
+        self.month = _parse_field(fields[3], 1, 12)
+        # accept 7 as Sunday, normalize to 0
+        self.dow = {d % 7 for d in _parse_field(fields[4], 0, 7)}
+
+    def next_after(self, ts: float) -> float:
+        """The first matching minute strictly after ``ts``, as a unix timestamp."""
+        zone = ZoneInfo(self.tz) if self.tz else UTC
+        start = datetime.fromtimestamp(ts, zone).replace(second=0, microsecond=0)
+        start += timedelta(minutes=1)
+        day = start.date()
+        for _ in range(28 * 366):  # leap-day + weekday combinations repeat within 28 years
+            if day.day in self.dom and day.month in self.month and day.weekday() in self._py_dow():
+                for hour in sorted(self.hour):
+                    for minute in sorted(self.minute):
+                        candidate = datetime(
+                            day.year, day.month, day.day, hour, minute, tzinfo=zone
+                        )
+                        if candidate < start or candidate.timestamp() <= ts:
+                            continue
+                        # Nonexistent local times during a DST jump normalize
+                        # to another wall time and therefore are not matches.
+                        actual = datetime.fromtimestamp(candidate.timestamp(), zone)
+                        if (actual.date(), actual.hour, actual.minute) != (day, hour, minute):
+                            continue
+                        return candidate.timestamp()
+            day += timedelta(days=1)
+        raise ConfigurationError(f"cron {self.expr!r} never fires")
+
+    def _py_dow(self) -> set[int]:
+        # cron: 0=Sunday..6=Saturday; python weekday(): 0=Monday..6=Sunday
+        return {(d - 1) % 7 for d in self.dow}

rotor/backends.py

@@ -0,0 +1,311 @@
+"""Backend resolution for the durable database and blob storage."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from collections.abc import Callable
+from pathlib import Path
+from urllib.parse import urlparse
+
+from ._time import Clock
+from .blob import (
+    BlobStore,
+    FileBlobStore,
+    MemoryBlobStore,
+    S3BlobStore,
+    UnconfiguredBlobStore,
+    VercelBlobStore,
+)
+from .errors import ConfigurationError
+from .live import (
+    LiveTransport,
+    MemoryLiveTransport,
+    PostgresLiveTransport,
+    RedisLiveTransport,
+    UnconfiguredLiveTransport,
+)
+from .spool import RedisSpoolStore, SpoolStore
+from .stores.base import Store
+from .stores.sql import PostgresStore, SqliteStore
+
+DEV_DB = "sqlite:///.rotor/dev.db"
+
+# Environment names set by platform database integrations, in priority order.
+_DB_ENV_VARS = ("POSTGRES_URL", "DATABASE_URL")
+_VERCEL_BLOB_ENV = "BLOB_READ_WRITE_TOKEN"
+
+
+class Backends:
+    """The database/blob pair both halves take. A Client and a Worker built
+    from the same Backends share one store instance in-process — which is
+    also what makes ``sqlite:///:memory:`` work for tests.
+
+    With no arguments, resolution is: platform-integration environment
+    variables (``POSTGRES_URL``/``DATABASE_URL`` for the database,
+    ``BLOB_READ_WRITE_TOKEN`` for blobs), then the local dev tier. Anything
+    else is configured explicitly in code."""
+
+    def __init__(
+        self,
+        db: str | Store | None = None,
+        *,
+        blobs: str | BlobStore | None = None,
+        blob_threshold: int = 64 * 1024,
+        clock: Clock | None = None,
+        live: str | LiveTransport | None = None,
+        record_message_activity: bool = True,
+    ) -> None:
+        if not isinstance(record_message_activity, bool):
+            raise ConfigurationError("record_message_activity must be a bool")
+        self.clock = clock or getattr(db, "clock", None) or Clock()
+        self.blob_threshold = blob_threshold
+        self._db_url = None
+        if db is not None and not isinstance(db, str):
+            self.store: Store = db  # bring-your-own conformant store
+            if isinstance(db, SqliteStore):
+                self._db_url = f"sqlite:///{db.path}"
+            elif isinstance(db, PostgresStore):
+                self._db_url = db.dsn
+        else:
+            url = db or _discovered_db_url() or DEV_DB
+            self._db_url = url
+            self.store = self._store_for(url)
+        self.store.record_message_activity = record_message_activity
+        self.live = self._resolve_live(live)
+        self.spool = self._resolve_spool()
+        if isinstance(blobs, str):
+            self.blob_store: BlobStore = self._blobs_for(blobs)
+            self._blobs_desc = blobs
+        elif blobs is not None:
+            self.blob_store = blobs
+            self._blobs_desc = type(blobs).__name__
+        else:
+            self.blob_store = self._default_blobs()
+            self._blobs_desc = self._default_blobs_desc()
+        self._ready = False
+        self._setup_lock = asyncio.Lock()
+
+    def _store_for(self, url: str) -> Store:
+        if url.startswith("sqlite:///"):
+            path = url[len("sqlite:///") :]
+            return SqliteStore(path, clock=self.clock)
+        if url.startswith(("postgres://", "postgresql://")):
+            return PostgresStore(url, clock=self.clock)
+        raise ConfigurationError(f"unsupported db URL {url!r} — expected sqlite:/// or postgres://")
+
+    def _blobs_for(self, url: str) -> BlobStore:
+        if url.startswith("file://"):
+            return FileBlobStore(url[len("file://") :])
+        if url.startswith("memory://"):
+            return MemoryBlobStore()
+        if url.startswith("s3://"):
+            parsed = urlparse(url)
+            return S3BlobStore(parsed.netloc, prefix=parsed.path.strip("/"))
+        raise ConfigurationError(
+            f"unsupported blobs URL {url!r} — expected file://, memory://, or s3://"
+        )
+
+    def _resolve_live(self, live: str | LiveTransport | None) -> LiveTransport:
+        if live is not None and not isinstance(live, str):
+            return live
+        url = live or os.getenv("KV_URL") or os.getenv("REDIS_URL")
+        if url:
+            if url.startswith(("redis://", "rediss://")):
+                return RedisLiveTransport(url)
+            if url.startswith(("postgres://", "postgresql://")):
+                return PostgresLiveTransport(url)
+            raise ConfigurationError(
+                f"unsupported live URL {url!r} — expected redis:// or postgres://"
+            )
+        direct = os.getenv("POSTGRES_URL_NON_POOLING")
+        if direct:
+            return PostgresLiveTransport(direct)
+        if isinstance(self.store, SqliteStore):
+            return MemoryLiveTransport()
+        if isinstance(self.store, PostgresStore):
+            return PostgresLiveTransport(self.store.dsn)
+        return UnconfiguredLiveTransport(
+            "live streaming is not configured: pass Backends(live='redis://...') "
+            "or a direct PostgreSQL URL"
+        )
+
+    def _resolve_spool(self) -> SpoolStore:
+        """The spool follows the live tier: a deployment that bought Redis
+        to take per-chunk traffic off Postgres gets the spool's per-chunk
+        writes there too; everyone else rides the SQL store, whose commit
+        clears the buffer transactionally for free.
+
+        Correctness never depends on this choice. Validity is anchored
+        solely in the main store's facts (lease, activation, mailbox row);
+        the spool and the live channel are both payload planes, and the
+        reader degrades any divergence between them to a Gap."""
+        if isinstance(self.live, RedisLiveTransport):
+            return RedisSpoolStore(self.live.url)
+        # the payload plane is part of the Store protocol: a bring-your-own
+        # store that omits it fails loudly at first use, the same way it
+        # would for any other missing protocol method
+        return self.store
+
+    def _default_blobs(self) -> BlobStore:
+        token = os.getenv(_VERCEL_BLOB_ENV)
+        if token:
+            return VercelBlobStore(token)
+        if deployed_on_vercel():
+            # Boot without blob storage; large values fail loudly at first use.
+            return UnconfiguredBlobStore(
+                "blob storage is not configured: add a Vercel Blob store to this project "
+                f"(sets {_VERCEL_BLOB_ENV}) or pass Backends(blobs=...) explicitly"
+            )
+        if isinstance(self.store, SqliteStore):
+            if self.store.path == ":memory:":
+                return MemoryBlobStore()
+            return FileBlobStore(Path(self.store.path).parent / "blobs")
+        return FileBlobStore(".rotor/blobs")
+
+    def _default_blobs_desc(self) -> str:
+        if isinstance(self.blob_store, MemoryBlobStore):
+            return "memory (dev)"
+        if isinstance(self.blob_store, FileBlobStore):
+            return f"file://{self.blob_store.root}"
+        if isinstance(self.blob_store, VercelBlobStore):
+            return f"vercel blob ({_VERCEL_BLOB_ENV})"
+        if isinstance(self.blob_store, UnconfiguredBlobStore):
+            return "unconfigured (fails on first use)"
+        return type(self.blob_store).__name__
+
+    @property
+    def in_memory(self) -> bool:
+        return self._db_url == "sqlite:///:memory:"
+
+    def thread_store_factory(self) -> Callable[[], Store] | None:
+        """A fresh store for the lease keeper's thread — its own connection,
+        same database, same clock. None when the database can't be duplicated:
+        a bring-your-own store object, or sqlite ``:memory:`` (a second
+        connection would see a different empty database)."""
+        if self._db_url is None or self._db_url == "sqlite:///:memory:":
+            return None
+        url: str = self._db_url
+        clock = getattr(self.store, "clock", self.clock)
+        record_message_activity = self.store.record_message_activity
+
+        def make() -> Store:
+            if url.startswith("sqlite:///"):
+                store: Store = SqliteStore(url[len("sqlite:///") :], clock=clock)
+            else:
+                store = PostgresStore(
+                    url,
+                    clock=clock,
+                    pool_min=1,
+                    pool_max=2,
+                    deployment_id=getattr(self.store, "deployment_id", None),
+                )
+            store.record_message_activity = record_message_activity
+            return store
+
+        return make
+
+    async def setup(self) -> None:
+        self.validate_vercel()
+        if self._ready:
+            return
+        async with self._setup_lock:
+            if self._ready:
+                return
+            await self.store.setup()
+            try:
+                namespace = self.runtime_namespace()
+                if namespace is not None:
+                    await self.store.bind_runtime(namespace)
+                await self.live.setup()
+                if self.spool is not self.store:
+                    await self.spool.setup()
+            except BaseException:
+                await self.store.close()
+                raise
+            self._ready = True
+
+    @staticmethod
+    def runtime_namespace() -> str | None:
+        """``project/environment`` this deployment binds its database to, or
+        None off deployed Vercel. Setup rejects a database bound elsewhere;
+        only explicit activation may rebind one (see the store's deployment fence)."""
+        if not deployed_on_vercel():
+            return None
+        project = os.getenv("VERCEL_PROJECT_ID")
+        if not project or not os.getenv("VERCEL_DEPLOYMENT_ID"):
+            raise ConfigurationError("Rotor needs VERCEL_PROJECT_ID and VERCEL_DEPLOYMENT_ID")
+        environment = os.getenv("VERCEL_TARGET_ENV") or os.environ["VERCEL_ENV"]
+        return f"{project}/{environment}"
+
+    def validate_vercel(self) -> None:
+        """Reject process-local backends before either half uses them.
+
+        Enforced only on deployed Vercel (production or preview): a function's
+        filesystem is ephemeral, so local backends there mean silent state
+        loss. ``vercel dev`` sets ``VERCEL_ENV=development`` and local
+        backends work with no configuration."""
+        if not deployed_on_vercel():
+            return
+        if isinstance(self.store, SqliteStore):
+            raise ConfigurationError(
+                "Rotor on Vercel requires a shared durable database: add a Postgres "
+                "integration (sets POSTGRES_URL) or pass Backends(db=...) explicitly"
+            )
+        if isinstance(self.blob_store, (FileBlobStore, MemoryBlobStore)):
+            raise ConfigurationError(
+                "Rotor on Vercel requires durable shared blob storage: add a Vercel Blob "
+                f"store (sets {_VERCEL_BLOB_ENV}) or pass Backends(blobs=...) explicitly"
+            )
+
+    async def close(self) -> None:
+        if self._ready:
+            if self.spool is not self.store:
+                await self.spool.close()
+            await self.live.close()
+            await self.store.close()
+            self._ready = False
+
+    def banner(self, role: str, extra: dict[str, str] | None = None) -> str:
+        if isinstance(self.store, SqliteStore):
+            tier = "dev tier" if self.store.path == ":memory:" else "durable ✓ (fsync)"
+            db = f"sqlite:///{self.store.path}  {tier}"
+        elif isinstance(self.store, PostgresStore):
+            db = f"{_redact(self.store.dsn)}  durable ✓ (WAL)"
+        else:
+            db = type(self.store).__name__
+        lines = [
+            f"rotor · {role}",
+            f"  db      {db}",
+            f"  blobs   {self._blobs_desc}",
+        ]
+        for key, value in (extra or {}).items():
+            lines.append(f"  {key:<7} {value}")
+        return "\n".join(lines)
+
+
+def _discovered_db_url() -> str | None:
+    for name in _DB_ENV_VARS:
+        url = os.getenv(name)
+        if url:
+            return url
+    return None
+
+
+def _redact(dsn: str) -> str:
+    if "@" in dsn and "://" in dsn:
+        scheme, rest = dsn.split("://", 1)
+        _creds, _, host = rest.rpartition("@")
+        return f"{scheme}://…@{host}"
+    return dsn
+
+
+def deployed_on_vercel() -> bool:
+    """Deployed means production or preview; ``vercel dev`` is development."""
+    return os.getenv("VERCEL_ENV") in ("production", "preview")
+
+
+def resolve(backends: Backends | str | None) -> Backends:
+    if isinstance(backends, Backends):
+        return backends
+    return Backends(backends)