rotorcore 0.0.1__tar.gz

rotorcore-0.0.1/.gitignore

@@ -0,0 +1,60 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Packaging and environments
+build/
+dist/
+node_modules/
+*.egg-info/
+.eggs/
+.hatch/
+.venv/
+.python-version
+
+# Tests, coverage, and tool caches
+.cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.hypothesis/
+.mypy_cache/
+.nox/
+.pytest_cache/
+.ruff_cache/
+.tox/
+
+# Rotor and local data
+.rotor/
+*.db
+*.db-journal
+*.db-shm
+*.db-wal
+*.sqlite
+*.sqlite3
+
+# Generated sites and platform state
+docs/_site/
+.vercel/
+
+# Local configuration and editors
+.DS_Store
+.env
+.env.*
+!.env.example
+!.env.*.example
+.idea/
+.vscode/
+.zed/
+*.swp
+*.swo
+notes/
+.vercel
+.claude
+.mcp.json
+.cursor
+.opencode
+.codex

rotorcore-0.0.1/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2026 Vercel, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

rotorcore-0.0.1/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.5
+Name: rotorcore
+Version: 0.0.1
+Summary: A durable process runtime for Python.
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.11
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.29; extra == 'postgres'
+Provides-Extra: redis
+Requires-Dist: redis>=5; extra == 'redis'
+Provides-Extra: s3
+Requires-Dist: boto3>=1.34; extra == 's3'
+Provides-Extra: vercel
+Requires-Dist: asyncpg>=0.29; extra == 'vercel'
+Requires-Dist: vercel-queue>=0.8.0; extra == 'vercel'
+Provides-Extra: web
+Requires-Dist: fastapi>=0.110; extra == 'web'
+Requires-Dist: uvicorn>=0.29; extra == 'web'
+Description-Content-Type: text/markdown
+
+# rotor
+
+**A durable process runtime for Python.**
+
+> [!WARNING]
+> Rotor is experimental and unstable. APIs, storage formats, and behavior may change
+> without notice. Do not use it for production workloads.
+
+A process is persisted as a checkpoint and mailbox. A worker leases it for one or
+more messages, committing each transition independently.
+
+```python
+from dataclasses import field
+from rotor import DurableProcess, Start, message, on
+
+@message
+class Ask:
+    question: str
+
+class State:
+    asked: list = field(default_factory=list)
+
+class Oracle(DurableProcess[State]):
+    @on
+    async def start(self, msg: Start):
+        self.state.asked.append(f"born knowing: {msg.input}")
+
+    @on
+    async def ask(self, msg: Ask):
+        self.state.asked.append(msg.question)
+        if len(self.state.asked) > 3:
+            self.stop(output=self.state.asked)
+```
+
+Timers, child completion, approvals, and limit notifications all arrive as messages.
+Application code defines their meaning in handlers.
+
+## Install
+
+```bash
+pip install rotorcore              # SQLite tier: zero dependencies
+pip install "rotorcore[postgres]"  # + asyncpg for production
+pip install "rotorcore[vercel]"    # Queue SDK + Postgres + S3 adapter
+```

rotorcore-0.0.1/README.md

@@ -0,0 +1,44 @@
+# rotor
+
+**A durable process runtime for Python.**
+
+> [!WARNING]
+> Rotor is experimental and unstable. APIs, storage formats, and behavior may change
+> without notice. Do not use it for production workloads.
+
+A process is persisted as a checkpoint and mailbox. A worker leases it for one or
+more messages, committing each transition independently.
+
+```python
+from dataclasses import field
+from rotor import DurableProcess, Start, message, on
+
+@message
+class Ask:
+    question: str
+
+class State:
+    asked: list = field(default_factory=list)
+
+class Oracle(DurableProcess[State]):
+    @on
+    async def start(self, msg: Start):
+        self.state.asked.append(f"born knowing: {msg.input}")
+
+    @on
+    async def ask(self, msg: Ask):
+        self.state.asked.append(msg.question)
+        if len(self.state.asked) > 3:
+            self.stop(output=self.state.asked)
+```
+
+Timers, child completion, approvals, and limit notifications all arrive as messages.
+Application code defines their meaning in handlers.
+
+## Install
+
+```bash
+pip install rotorcore              # SQLite tier: zero dependencies
+pip install "rotorcore[postgres]"  # + asyncpg for production
+pip install "rotorcore[vercel]"    # Queue SDK + Postgres + S3 adapter
+```

rotorcore-0.0.1/pyproject.toml

@@ -0,0 +1,109 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "rotorcore"
+version = "0.0.1"
+description = "A durable process runtime for Python."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+dependencies = []
+
+[project.optional-dependencies]
+postgres = ["asyncpg>=0.29"]
+redis = ["redis>=5"]
+s3 = ["boto3>=1.34"]
+vercel = ["asyncpg>=0.29", "vercel-queue>=0.8.0"]
+web = ["fastapi>=0.110", "uvicorn>=0.29"]
+
+[dependency-groups]
+dev = [
+  "ruff>=0.5.0,<1",
+  "pytest>=8",
+  "pytest-asyncio>=0.23",
+  "httpx>=0.27",
+  "fastapi>=0.110",
+  "uvicorn>=0.29",
+  "mypy>=1.20.2,<2",
+  "poethepoet>=0.48,<1",
+]
+
+[tool.uv]
+default-groups = ["dev"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/rotor"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["src/rotor"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.mypy]
+ignore_missing_imports = true
+explicit_package_bases = true
+mypy_path = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+  "E",  # pycodestyle errors
+  "W",  # pycodestyle warnings
+  "F",  # pyflakes
+  "I",  # isort
+  "B",  # flake8-bugbear
+  "C4", # flake8-comprehensions
+  "UP", # pyupgrade
+]
+isort = { combine-as-imports = true, known-first-party = ["rotor"] }
+
+[tool.ruff.lint.pyupgrade]
+keep-runtime-typing = false
+
+[tool.ruff.lint.per-file-ignores]
+"examples/**/*.py" = ["E501"]
+
+[tool.poe.tasks.lint]
+sequence = ["lint-ruff", "lint-format"]
+
+[tool.poe.tasks.lint-ruff]
+cmd = "ruff check src tests examples"
+
+[tool.poe.tasks.lint-format]
+cmd = "ruff format --check src tests examples"
+
+[tool.poe.tasks.typecheck]
+cmd = "mypy src tests"
+
+[tool.poe.tasks.test]
+cmd = "pytest"
+
+[tool.poe.tasks.schema]
+cmd = "python -m rotor.check rotor.patterns"
+
+[tool.poe.tasks.schema-write]
+cmd = "python -m rotor.check rotor.patterns --write"
+
+[tool.poe.tasks.docs]
+cmd = "npm run docs:build"
+
+[tool.poe.tasks.fix]
+sequence = ["fix-ruff", "fix-format"]
+
+[tool.poe.tasks.fix-ruff]
+cmd = "ruff check --fix src tests examples"
+
+[tool.poe.tasks.fix-format]
+cmd = "ruff format src tests examples"
+
+[tool.poe.tasks.qa]
+sequence = ["lint", "typecheck", "schema", "test", "docs"]

rotorcore-0.0.1/src/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",
+]

rotorcore-0.0.1/src/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}