pinboard-sdk 0.18.0__tar.gz

pinboard_sdk-0.18.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+.ruff_cache/
+uv.lock

pinboard_sdk-0.18.0/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.5
+Name: pinboard-sdk
+Version: 0.18.0
+Summary: One live instance of your class per id, with an HTTP surface
+Project-URL: Repository, https://github.com/assistant-ui/harness-sdk
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.115
+Requires-Dist: httpx>=0.27
+Requires-Dist: starlette>=0.37
+Requires-Dist: statepatch<0.4,>=0.3.0
+Provides-Extra: postgres
+Requires-Dist: psycopg>=3.1; extra == 'postgres'
+Provides-Extra: psutil
+Requires-Dist: psutil>=5.9; extra == 'psutil'
+Description-Content-Type: text/markdown
+
+# pinboard-sdk
+
+Durable objects for Python: one live instance of your class per id across a fleet, activated on the first request, with its own HTTP surface. Imports as `pinboard`. Part of [harness-sdk](https://github.com/assistant-ui/harness-sdk), with `statewire` and `harness-sdk`.
+
+## Install
+
+```sh
+uv add pinboard-sdk
+```
+
+Extras: `uv add "pinboard-sdk[postgres]"`, `uv add "pinboard-sdk[psutil]"`.
+
+## Use
+
+```python
+from fastapi import FastAPI
+from pinboard import PinboardAPI, Worker, route
+from pinboard.durability import MemoryStateStore
+
+class Counter(PinboardAPI):
+    async def lifespan(self):
+        self.count = 0
+        yield
+
+    @route.post("/increment")
+    async def increment(self):
+        self.count += 1
+        return {"id": self.id, "count": self.count}
+
+worker = Worker(hosts={"/counters": Counter}, state_store=MemoryStateStore())
+app = FastAPI()
+app.include_router(worker)
+```
+
+## Docs
+
+- Get started: https://github.com/assistant-ui/harness-sdk/blob/main/apps/docs/src/app/pinboard/docs/get-started/durable-host/page.mdx
+- Guide: https://github.com/assistant-ui/harness-sdk/blob/main/apps/docs/src/app/pinboard/docs/guides/python/authoring/page.mdx
+- Reference: https://github.com/assistant-ui/harness-sdk/blob/main/apps/docs/src/app/pinboard/docs/reference/pinboard-python/page.mdx
+- Spec: https://github.com/assistant-ui/harness-sdk/blob/main/apps/docs/src/app/pinboard/docs/spec/gateway-registry/page.mdx

pinboard_sdk-0.18.0/README.md

@@ -0,0 +1,40 @@
+# pinboard-sdk
+
+Durable objects for Python: one live instance of your class per id across a fleet, activated on the first request, with its own HTTP surface. Imports as `pinboard`. Part of [harness-sdk](https://github.com/assistant-ui/harness-sdk), with `statewire` and `harness-sdk`.
+
+## Install
+
+```sh
+uv add pinboard-sdk
+```
+
+Extras: `uv add "pinboard-sdk[postgres]"`, `uv add "pinboard-sdk[psutil]"`.
+
+## Use
+
+```python
+from fastapi import FastAPI
+from pinboard import PinboardAPI, Worker, route
+from pinboard.durability import MemoryStateStore
+
+class Counter(PinboardAPI):
+    async def lifespan(self):
+        self.count = 0
+        yield
+
+    @route.post("/increment")
+    async def increment(self):
+        self.count += 1
+        return {"id": self.id, "count": self.count}
+
+worker = Worker(hosts={"/counters": Counter}, state_store=MemoryStateStore())
+app = FastAPI()
+app.include_router(worker)
+```
+
+## Docs
+
+- Get started: https://github.com/assistant-ui/harness-sdk/blob/main/apps/docs/src/app/pinboard/docs/get-started/durable-host/page.mdx
+- Guide: https://github.com/assistant-ui/harness-sdk/blob/main/apps/docs/src/app/pinboard/docs/guides/python/authoring/page.mdx
+- Reference: https://github.com/assistant-ui/harness-sdk/blob/main/apps/docs/src/app/pinboard/docs/reference/pinboard-python/page.mdx
+- Spec: https://github.com/assistant-ui/harness-sdk/blob/main/apps/docs/src/app/pinboard/docs/spec/gateway-registry/page.mdx

pinboard_sdk-0.18.0/examples/durable_tray_app.py

@@ -0,0 +1,69 @@
+"""Durable tray worker: the minimal gateway + tray durability config.
+
+Each ``/lanes/{id}`` instance owns one tray. ``POST /enqueue`` returns once the
+item is durably admitted; the handler records the item in ``executed`` when it runs.
+The gateway's durability sweep (``PINBOARD_DURABILITY_POSTGRES_URL`` on the
+pinboard side, pointing at the same database) resurrects lanes with pending
+work after any combination of worker crashes and pinboard/redis wipes.
+
+Env: POSTGRES_DSN, PINBOARD_URL, PINBOARD_TOKEN, ADVERTISE_URL,
+HEARTBEAT_INTERVAL (default 3).
+Run: uv run uvicorn examples.durable_tray_app:app --port 8000
+"""
+
+import asyncio
+import contextlib
+import os
+
+from fastapi import FastAPI
+
+from pinboard import PinboardAPI, Worker, Tray, inbox, route, tray
+from pinboard.durability.postgres import PostgresStateStore
+from pinboard.trays import persistent_queue
+
+
+class WorkTray(Tray):
+    queue = persistent_queue()
+
+    def items(self):
+        while self.queue.value:
+            yield self.queue.peek()
+            self.queue.popleft()
+
+    @inbox
+    def add(self, item: dict) -> None:
+        self.kick()
+        self.queue.append(item)
+
+
+class Lane(PinboardAPI):
+    @tray(WorkTray)
+    async def work(self, item: dict, ctx) -> None:
+        if ctx.attempts == 1 and item.get("hold"):
+            await asyncio.Event().wait()  # chaos: first delivery completes only by kill
+        executed = ctx.tray.storage.get("executed", {})
+        ctx.tray.storage.set("executed", {**executed, item["id"]: ctx.attempts})
+
+    @route.post("/enqueue")
+    async def enqueue(self, item: dict) -> dict:
+        lane = await self.work.get()
+        await lane.add(item)  # the durable-admission receipt
+        return {"admitted": item["id"]}
+
+
+store = PostgresStateStore(dsn=os.environ["POSTGRES_DSN"])
+worker = Worker(
+    hosts={"/lanes": Lane},
+    heartbeat_interval=float(os.environ.get("HEARTBEAT_INTERVAL", "3")),
+    state_store=store,
+)
+
+
+@contextlib.asynccontextmanager
+async def lifespan(app: FastAPI):
+    await store.setup()
+    yield
+
+
+app = FastAPI(lifespan=lifespan)
+app.include_router(worker)

pinboard_sdk-0.18.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pinboard-sdk"
+version = "0.18.0"
+description = "One live instance of your class per id, with an HTTP surface"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+dependencies = ["fastapi>=0.115", "starlette>=0.37", "httpx>=0.27", "statepatch>=0.3.0,<0.4"]
+
+[tool.uv.sources]
+statepatch = { workspace = true }
+
+[project.optional-dependencies]
+psutil = ["psutil>=5.9"]
+postgres = ["psycopg>=3.1"]
+
+[project.urls]
+Repository = "https://github.com/assistant-ui/harness-sdk"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pinboard"]
+
+[tool.ruff]
+extend = "../../pyproject.toml"
+
+[tool.ruff.lint.flake8-tidy-imports.banned-api]
+"time.time".msg = "read the clock through a Domain (pinboard.domain)"
+"time.monotonic".msg = "read the clock through a Domain (pinboard.domain)"
+"time.perf_counter".msg = "read the clock through a Domain (pinboard.domain)"
+"time.time_ns".msg = "read the clock through a Domain (pinboard.domain)"
+"time.monotonic_ns".msg = "read the clock through a Domain (pinboard.domain)"
+"time.perf_counter_ns".msg = "read the clock through a Domain (pinboard.domain)"
+"time.sleep".msg = "sleep through a Domain (pinboard.domain)"
+"asyncio.sleep".msg = "sleep through a Domain (pinboard.domain)"
+"asyncio.wait_for".msg = "wait through a Domain (pinboard.domain)"
+"asyncio.timeout".msg = "wait through a Domain (pinboard.domain)"
+"asyncio.create_task".msg = "spawn through a Domain (pinboard.domain)"
+"asyncio.ensure_future".msg = "spawn through a Domain (pinboard.domain)"
+"asyncio.gather".msg = "gather turns coroutines into ambient tasks; spawn through a Domain (pinboard.domain) and gather the tasks"
+"datetime.datetime.now".msg = "read the clock through a Domain (pinboard.domain)"
+"datetime.datetime.utcnow".msg = "read the clock through a Domain (pinboard.domain)"
+"datetime.date.today".msg = "read the clock through a Domain (pinboard.domain)"
+"random".msg = "draw from a Domain rng stream (pinboard.domain)"
+"secrets".msg = "mint tokens through a Domain (pinboard.domain)"
+"uuid.uuid4".msg = "mint tokens through a Domain (pinboard.domain)"
+"uuid.uuid1".msg = "mint tokens through a Domain (pinboard.domain)"
+"os.urandom".msg = "mint tokens through a Domain (pinboard.domain)"
+
+[tool.ruff.lint.per-file-ignores]
+"src/pinboard/domain.py" = ["TID251"]
+"src/pinboard/sim/__init__.py" = ["TID251"]
+"src/pinboard/sim/harness.py" = ["TID251"]
+"src/pinboard/testing.py" = ["TID251"]
+"tests/**" = ["TID251"]
+"examples/**" = ["TID251"]

pinboard_sdk-0.18.0/src/pinboard/__init__.py

@@ -0,0 +1,74 @@
+from .api import AuthRejected, PinboardAPI, PinboardContext, auth_result
+from .domain import Domain, RealDomain
+from .durability import (
+    FenceLost,
+    Frontier,
+    InstanceDurability,
+    Receipt,
+    StateStore,
+)
+from statepatch import Observable, observable
+
+from .hosting.host import PinboardHost
+from .trays import (
+    Tray,
+    TrayCtx,
+    TrayDescriptor,
+    TrayMapNamespace,
+    TrayNamespace,
+    TrayStorage,
+    inbox,
+    persistent,
+    persistent_outbox,
+    persistent_queue,
+    tray,
+)
+from .hosting.hostable import Hostable, HostableContext
+from .hosting.routing import route
+from .worker import (
+    Attestation,
+    EvictionRequested,
+    Host,
+    InstanceLease,
+    Lease,
+    Worker,
+    attestation,
+)
+
+__all__ = [
+    "Attestation",
+    "attestation",
+    "AuthRejected",
+    "Domain",
+    "RealDomain",
+    "auth_result",
+    "PinboardAPI",
+    "PinboardContext",
+    "Host",
+    "PinboardHost",
+    "Worker",
+    "Hostable",
+    "HostableContext",
+    "InstanceLease",
+    "EvictionRequested",
+    "Lease",
+    "route",
+    "StateStore",
+    "FenceLost",
+    "InstanceDurability",
+    "Frontier",
+    "Receipt",
+    "Observable",
+    "observable",
+    "Tray",
+    "TrayCtx",
+    "TrayDescriptor",
+    "TrayMapNamespace",
+    "TrayNamespace",
+    "tray",
+    "inbox",
+    "TrayStorage",
+    "persistent",
+    "persistent_queue",
+    "persistent_outbox",
+]

pinboard_sdk-0.18.0/src/pinboard/api.py

@@ -0,0 +1,178 @@
+import asyncio
+from typing import TYPE_CHECKING, Any, AsyncIterator, Callable, Coroutine, Literal
+
+from starlette.requests import HTTPConnection
+
+from .domain import Domain
+from .durability import Frontier, InstanceDurability
+from .worker.lease import EvictionRequested, InstanceLease
+
+if TYPE_CHECKING:
+    import httpx
+
+    from .hostable import Hostable, HostableContext
+
+
+AUTH_RESULT_SCOPE_KEY = "pinned.auth_result"
+
+
+class AuthRejected(Exception):
+    """Deliberate route denial with an exact optional transport payload."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Literal[401, 403] = 401,
+        payload: Any = None,
+        code: str | None = None,
+    ):
+        if type(status_code) is not int or status_code not in (401, 403):
+            raise ValueError("AuthRejected status_code must be 401 or 403")
+        if not isinstance(message, str):
+            raise TypeError("AuthRejected message must be a string")
+        if code is not None and not isinstance(code, str):
+            raise TypeError("AuthRejected code must be a string")
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.payload = payload
+        self.code = code
+
+
+async def auth_result(conn: HTTPConnection) -> Any:
+    """The current route resolver's return value, for ``Depends(auth_result)``."""
+    if AUTH_RESULT_SCOPE_KEY not in conn.scope:
+        raise RuntimeError("auth_result resolves only inside a pinned route")
+    return conn.scope[AUTH_RESULT_SCOPE_KEY]
+
+
+class PinboardContext:
+    def __init__(
+        self,
+        id: str,
+        *,
+        lease: InstanceLease,
+        abort: Callable[[], None],
+        create_task: Callable[[Coroutine[Any, Any, Any]], "asyncio.Task[Any]"],
+        durability: InstanceDurability | None = None,
+        cluster: "httpx.AsyncClient | None" = None,
+        domain: Domain,
+        create_durable_task: Callable[[Coroutine[Any, Any, Any]], "asyncio.Task[Any]"]
+        | None = None,
+    ) -> None:
+        self.id = id
+        self.lease = lease
+        self.durability = durability
+        self.cluster = cluster
+        self.domain = domain
+        self._abort = abort
+        self._create_task = create_task
+        if durability is not None:
+            durability.frontier = Frontier(
+                durability, self.abort, create_durable_task or self.create_task
+            )
+
+    def abort(self) -> None:
+        self._abort()
+
+    def create_task(self, coro: Coroutine[Any, Any, Any]) -> "asyncio.Task[Any]":
+        return self._create_task(coro)
+
+
+class PinboardAPI:
+    # The instance base depends only on the context interface, not the concrete
+    # PinboardContext — a PinboardAPI would host unchanged under any HostableContext.
+    def __init__(self, ctx: "HostableContext") -> None:
+        self._ctx = ctx
+
+    async def authorize(self, conn: HTTPConnection) -> Any:
+        """Auth seam gating every ``@route`` handler: raise ``AuthRejected``
+        to reject. The return value is the caller's identity — any host-chosen
+        object, ``None`` for anonymous — consumed via ``Depends(auth_result)``.
+
+        Runs before ``lifespan`` on a cold instance, so a denied request never
+        activates: ``self.id`` is available, state built in ``lifespan`` is
+        not — cold and warm calls share that one contract. Runs per request; writes to ``self`` are latest-wins."""
+        return None
+
+    async def _route_failed(self, conn: HTTPConnection, message: str) -> None:
+        """Protocol notification before a failed WebSocket route closes."""
+
+    async def _route_refused(
+        self,
+        conn: HTTPConnection,
+        message: str,
+        *,
+        status: int,
+        retry_after: float,
+    ) -> None:
+        """Protocol notification before a refused (retryable) WebSocket route closes."""
+
+    def stats(self) -> "dict[str, Any] | None":
+        """Optional per-instance wire stats merged into ``/_pinned/stats`` rows."""
+        return None
+
+    @property
+    def id(self) -> str:
+        return self._ctx.id
+
+    @property
+    def lease(self) -> InstanceLease:
+        return self._ctx.lease
+
+    def abort(self) -> None:
+        self._ctx.abort()
+
+    @property
+    def domain(self) -> Domain:
+        """Ambient primitives — now/monotonic/sleep/wait/spawn/rng/token_hex — simulable under ``SimDomain``."""
+        return self._ctx.domain
+
+    @property
+    def cluster(self) -> "httpx.AsyncClient":
+        """HTTP client addressing other instances by data-plane path (``/<ns>/<id>/...``), with this instance attested as the caller."""
+        cluster = self._ctx.cluster
+        if cluster is None:
+            raise RuntimeError("self.cluster requires a PinboardHost")
+        return cluster
+
+    @property
+    def frontier(self) -> Frontier:
+        """Instance-wide ordered log of durable effects; ``await self.frontier.wait()`` is the durable receipt."""
+        durability = self._ctx.durability
+        if durability is None:
+            raise RuntimeError(
+                "durability requires a state store (Worker(state_store=...))"
+            )
+        assert durability.frontier is not None
+        return durability.frontier
+
+    @property
+    def placement_epoch(self) -> int:
+        """The placement epoch this activation writes at (the ``pinboard-epoch`` header, 0 without a pinboard); follows an in-place epoch advance."""
+        durability = self._ctx.durability
+        if durability is None:
+            raise RuntimeError(
+                "placement_epoch requires a state store (Worker(state_store=...))"
+            )
+        return durability.epoch
+
+    def create_task(self, coro: Coroutine[Any, Any, Any]) -> "asyncio.Task[Any]":
+        return self._ctx.create_task(coro)
+
+    async def eviction_checkpoint(self) -> None:
+        """Yield unfinished execution for relocation when this instance is winding down."""
+        if self.lease.winding_down:
+            raise EvictionRequested()
+
+    async def lifespan(self) -> AsyncIterator[None]:
+        yield
+
+
+if TYPE_CHECKING:
+    # The seam, proved structurally: the concrete types satisfy the Protocols a
+    # future zero-dependency host would depend on instead of these classes.
+    def _assert_conformance(ctx: PinboardContext, api: PinboardAPI) -> None:
+        _c: "HostableContext" = ctx
+        _h: "Hostable" = api

pinboard_sdk-0.18.0/src/pinboard/domain.py

@@ -0,0 +1,73 @@
+"""The ambient-primitive seam: clocks, sleep, timed waits, task spawn and randomness.
+
+Every reading of the world in pinned goes through a ``Domain``, threaded from
+the worker down. ``RealDomain`` is the process; a simulation installs its own
+to run the same code on virtual time.
+"""
+
+import asyncio
+import contextlib
+import random
+import secrets
+import time
+from typing import Any, Coroutine, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class Domain(Protocol):
+    """Ambient primitives, injected: wall clock, monotonic clock, sleep, timed waits, task spawn, seeded RNG streams, nonces."""
+
+    def now(self) -> float: ...
+
+    def monotonic(self) -> float: ...
+
+    async def sleep(self, seconds: float) -> None: ...
+
+    async def wait(self, event: asyncio.Event, timeout: float) -> bool: ...
+
+    def spawn(self, coro: Coroutine[Any, Any, Any]) -> "asyncio.Task[Any]": ...
+
+    def rng(self, label: str) -> random.Random: ...
+
+    def token_hex(self, nbytes: int) -> str: ...
+
+
+class RealDomain:
+    """The process Domain: system clocks, the running event loop, per-label RNG streams off one seed."""
+
+    def __init__(self, *, seed: int = 0) -> None:
+        if not isinstance(seed, int) or isinstance(seed, bool):
+            raise TypeError(f"seed must be an int: {seed!r}")
+        self._seed = seed
+        self._rngs: dict[str, random.Random] = {}
+
+    def now(self) -> float:
+        return time.time()
+
+    def monotonic(self) -> float:
+        return time.monotonic()
+
+    async def sleep(self, seconds: float) -> None:
+        await asyncio.sleep(seconds)
+
+    async def wait(self, event: asyncio.Event, timeout: float) -> bool:
+        # A cancel landing exactly as the timeout fires surfaces as
+        # TimeoutError; callers read the event, not the outcome of the race.
+        with contextlib.suppress(asyncio.TimeoutError):
+            await asyncio.wait_for(event.wait(), timeout)
+        return event.is_set()
+
+    def spawn(self, coro: Coroutine[Any, Any, Any]) -> "asyncio.Task[Any]":
+        return asyncio.create_task(coro)
+
+    def rng(self, label: str) -> random.Random:
+        # One substream per label: a new call site cannot shift another's draws.
+        if not label:
+            raise ValueError("an rng stream needs a non-empty label")
+        stream = self._rngs.get(label)
+        if stream is None:
+            stream = self._rngs[label] = random.Random(f"{self._seed}:{label}")
+        return stream
+
+    def token_hex(self, nbytes: int) -> str:
+        return secrets.token_hex(nbytes)

pinboard_sdk-0.18.0/src/pinboard/durability/__init__.py

@@ -0,0 +1,11 @@
+from .frontier import Frontier, InstanceDurability, Receipt
+from .store import FenceLost, MemoryStateStore, StateStore
+
+__all__ = [
+    "FenceLost",
+    "Frontier",
+    "InstanceDurability",
+    "MemoryStateStore",
+    "Receipt",
+    "StateStore",
+]