pinned 0.1.0__tar.gz

pinned-0.1.0/.gitignore

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

pinned-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: pinned
+Version: 0.1.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
+Provides-Extra: psutil
+Requires-Dist: psutil>=5.9; extra == 'psutil'
+Description-Content-Type: text/markdown
+
+# Pinned
+
+Durable Objects for Python.
+
+A PinnedAPI instance for a given id will exist exactly once in your fleet. It acts as a singleton webserver.
+
+## PinnedAPI
+
+```python
+from pinned import PinnedAPI, route
+
+class MyAPI(PinnedAPI):
+    async def lifespan(self):
+        # setup
+        yield
+        # teardown
+
+    @route.get("/hello")
+    async def hello(self):
+        return {"hello": self.id}
+```
+
+- Handlers must be `async def`.
+- Ids are client-generated; the first request activates.
+- `@route.get/post/websocket` see the path remainder after the id.
+- `self.create_task(coro)` runs background work bound to the instance: it blocks idle eviction while running, teardown waits for it, `abort()` cancels it.
+
+## PinnedHost
+
+```python
+from pinned import PinnedHost
+
+app = FastAPI()
+app.include_router(
+    PinnedHost(
+        MyAPI,
+        pinboard_url="https://pinboard.internal",    # omit -> local mode
+        advertise_url="http://10.0.3.7:8000/myapi",  # must uniquely address THIS process
+        namespace="/myapi",
+    ),
+    prefix="/myapi",
+)
+```
+
+- `PinnedHost` is an APIRouter carrying `/{id}` that dispatches to the instance.
+- Local mode uses an in-memory directory and speaks the same external API.
+
+## Pinboard
+
+A reverse proxy that routes each request to the backend holding the instance, placing instances on registered backends as needed. Requires Redis and a deployment token shared with the backends.
+
+### Protocol
+
+All registry calls carry `Authorization: Bearer <deployment token>`.
+
+- `POST /registry/register` at boot — `{ clientId, secret, namespaces, advertiseUrl, headroom, draining }`. Response: `{ sessionId, expiresInMs }`.
+- `POST /registry/heartbeat` every 3s — `{ sessionId, headroom, draining, drainDeadline? }`. Response: ack `{ expiresInMs }`, or a 409 NACK: `reregister` (unknown session — abort local instances, register fresh) or `superseded`.
+- `POST /registry/release` — `{ clientId, namespace, id }` frees a placement when an instance closes.
+- Pinboard → backend: `POST <advertiseUrl>/_pinned/drain` `{ deadline? }`, `/_pinned/wind_down` `{ id, deadline? }`, and `/_pinned/resume` `{ id? }`, authenticated with `x-pinned-proxy-secret`.
+- Operator: `POST /registry/push` delivers a drain/wind_down/resume to a worker; `GET /registry/workers` and `GET /registry/overview` introspect; `GET /healthz` is unauthenticated.
+- `clientId` and `secret` are minted once at process start. `sessionId` is the per-registration lease token: placements belong to the session, and the backend aborts all local instances before serving under a new one.
+- Data-plane requests go over plain HTTP to `<advertiseUrl>/<id><rest>`. The proxy sets `x-pinned-proxy-secret` to the worker's secret; the backend rejects a mismatch with 403.
+- Placement is per `(namespace, id)`: first claim wins (Redis `SET NX`) among live, undrained backends, biased toward headroom. Redis keys and body shapes are documented in pinboard's source (`packages/pinned/pinboard`).
+
+## Lifecycle
+
+- Activation on first request; deactivation by idle sweep. In-flight requests and open streams block eviction.
+- `self.abort()` force-ends an instance: cancels in-flight work and tears down.
+- Streams are pull-based: the response generator advances only as the client reads — a slow client backpressures its own stream and nothing else, with no per-connection buffer.
+- Draining workers answer new activations with 503 + Retry-After while existing requests keep serving; freed ids activate on the new deployment.
+- While an instance's close and `/registry/release` are in flight, requests for that id answer 503 + Retry-After so the proxy re-resolves the placement instead of re-activating locally.
+
+**Instance memory is ephemeral.** Idle eviction, deploys, lease loss, and crashes all discard it; a re-activation starts from `lifespan` with nothing. Anything that must survive belongs in the app's own store, written before the response that claims it.
+
+## Leases and fencing
+
+- Each acked heartbeat anchors the lease at send time: `self.lease.expires_at` = send time + `expiresInMs` (10s by default, pinboard-supplied) — the moment pinboard may re-place this worker's ids, matching the worker record's Redis TTL.
+- When `expires_at - buffer` passes without an ack, the worker quits: aborts every local instance and stops registering before the ids can move; the host app keeps running. The buffer (default 5s) is the worker's local safety margin; `self.lease.configure(...)` changes it and the handlers.
+- A frozen process (VM pause, long GC) that wakes after its lease lapsed fails its next heartbeat (unknown session) and aborts everything before serving again.
+- Guarantee: at most one live instance per id outside a lease-bounded failure window.
+
+## Observability
+
+Lifecycle events (activation, eviction/abort, drain, lease health, registration) log on the stdlib `pinned.*` logger hierarchy with instance/namespace fields; configure it like any library logger. When `prometheus_client` is importable, `pinned.metrics` registers `pinned_*` counters, gauges, and a per-namespace request duration histogram on the default registry — a host app exposing `/metrics` picks them up automatically. Without the package they are no-ops. No Sentry or OpenTelemetry wiring; that stays in the host app.

pinned-0.1.0/README.md

@@ -0,0 +1,84 @@
+# Pinned
+
+Durable Objects for Python.
+
+A PinnedAPI instance for a given id will exist exactly once in your fleet. It acts as a singleton webserver.
+
+## PinnedAPI
+
+```python
+from pinned import PinnedAPI, route
+
+class MyAPI(PinnedAPI):
+    async def lifespan(self):
+        # setup
+        yield
+        # teardown
+
+    @route.get("/hello")
+    async def hello(self):
+        return {"hello": self.id}
+```
+
+- Handlers must be `async def`.
+- Ids are client-generated; the first request activates.
+- `@route.get/post/websocket` see the path remainder after the id.
+- `self.create_task(coro)` runs background work bound to the instance: it blocks idle eviction while running, teardown waits for it, `abort()` cancels it.
+
+## PinnedHost
+
+```python
+from pinned import PinnedHost
+
+app = FastAPI()
+app.include_router(
+    PinnedHost(
+        MyAPI,
+        pinboard_url="https://pinboard.internal",    # omit -> local mode
+        advertise_url="http://10.0.3.7:8000/myapi",  # must uniquely address THIS process
+        namespace="/myapi",
+    ),
+    prefix="/myapi",
+)
+```
+
+- `PinnedHost` is an APIRouter carrying `/{id}` that dispatches to the instance.
+- Local mode uses an in-memory directory and speaks the same external API.
+
+## Pinboard
+
+A reverse proxy that routes each request to the backend holding the instance, placing instances on registered backends as needed. Requires Redis and a deployment token shared with the backends.
+
+### Protocol
+
+All registry calls carry `Authorization: Bearer <deployment token>`.
+
+- `POST /registry/register` at boot — `{ clientId, secret, namespaces, advertiseUrl, headroom, draining }`. Response: `{ sessionId, expiresInMs }`.
+- `POST /registry/heartbeat` every 3s — `{ sessionId, headroom, draining, drainDeadline? }`. Response: ack `{ expiresInMs }`, or a 409 NACK: `reregister` (unknown session — abort local instances, register fresh) or `superseded`.
+- `POST /registry/release` — `{ clientId, namespace, id }` frees a placement when an instance closes.
+- Pinboard → backend: `POST <advertiseUrl>/_pinned/drain` `{ deadline? }`, `/_pinned/wind_down` `{ id, deadline? }`, and `/_pinned/resume` `{ id? }`, authenticated with `x-pinned-proxy-secret`.
+- Operator: `POST /registry/push` delivers a drain/wind_down/resume to a worker; `GET /registry/workers` and `GET /registry/overview` introspect; `GET /healthz` is unauthenticated.
+- `clientId` and `secret` are minted once at process start. `sessionId` is the per-registration lease token: placements belong to the session, and the backend aborts all local instances before serving under a new one.
+- Data-plane requests go over plain HTTP to `<advertiseUrl>/<id><rest>`. The proxy sets `x-pinned-proxy-secret` to the worker's secret; the backend rejects a mismatch with 403.
+- Placement is per `(namespace, id)`: first claim wins (Redis `SET NX`) among live, undrained backends, biased toward headroom. Redis keys and body shapes are documented in pinboard's source (`packages/pinned/pinboard`).
+
+## Lifecycle
+
+- Activation on first request; deactivation by idle sweep. In-flight requests and open streams block eviction.
+- `self.abort()` force-ends an instance: cancels in-flight work and tears down.
+- Streams are pull-based: the response generator advances only as the client reads — a slow client backpressures its own stream and nothing else, with no per-connection buffer.
+- Draining workers answer new activations with 503 + Retry-After while existing requests keep serving; freed ids activate on the new deployment.
+- While an instance's close and `/registry/release` are in flight, requests for that id answer 503 + Retry-After so the proxy re-resolves the placement instead of re-activating locally.
+
+**Instance memory is ephemeral.** Idle eviction, deploys, lease loss, and crashes all discard it; a re-activation starts from `lifespan` with nothing. Anything that must survive belongs in the app's own store, written before the response that claims it.
+
+## Leases and fencing
+
+- Each acked heartbeat anchors the lease at send time: `self.lease.expires_at` = send time + `expiresInMs` (10s by default, pinboard-supplied) — the moment pinboard may re-place this worker's ids, matching the worker record's Redis TTL.
+- When `expires_at - buffer` passes without an ack, the worker quits: aborts every local instance and stops registering before the ids can move; the host app keeps running. The buffer (default 5s) is the worker's local safety margin; `self.lease.configure(...)` changes it and the handlers.
+- A frozen process (VM pause, long GC) that wakes after its lease lapsed fails its next heartbeat (unknown session) and aborts everything before serving again.
+- Guarantee: at most one live instance per id outside a lease-bounded failure window.
+
+## Observability
+
+Lifecycle events (activation, eviction/abort, drain, lease health, registration) log on the stdlib `pinned.*` logger hierarchy with instance/namespace fields; configure it like any library logger. When `prometheus_client` is importable, `pinned.metrics` registers `pinned_*` counters, gauges, and a per-namespace request duration histogram on the default registry — a host app exposing `/metrics` picks them up automatically. Without the package they are no-ops. No Sentry or OpenTelemetry wiring; that stays in the host app.

pinned-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pinned"
+version = "0.1.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"]
+
+[project.optional-dependencies]
+psutil = ["psutil>=5.9"]
+
+[project.urls]
+Repository = "https://github.com/assistant-ui/harness-sdk"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pinned"]

pinned-0.1.0/src/pinned/__init__.py

@@ -0,0 +1,16 @@
+from .api import PinnedAPI, PinnedContext
+from .host import PinnedHost
+from .hostable import Hostable, HostableContext
+from .lease import InstanceLease, Lease
+from .routing import route
+
+__all__ = [
+    "PinnedAPI",
+    "PinnedContext",
+    "PinnedHost",
+    "Hostable",
+    "HostableContext",
+    "InstanceLease",
+    "Lease",
+    "route",
+]

pinned-0.1.0/src/pinned/api.py

@@ -0,0 +1,83 @@
+import asyncio
+from typing import TYPE_CHECKING, Any, AsyncIterator, Callable, Coroutine
+
+from .lease import InstanceLease
+
+if TYPE_CHECKING:
+    from .hostable import Hostable, HostableContext
+
+
+class PinnedContext:
+    def __init__(
+        self,
+        id: str,
+        *,
+        lease: InstanceLease,
+        placement_token: str,
+        abort: Callable[[], None],
+        create_task: Callable[[Coroutine[Any, Any, Any]], "asyncio.Task[Any]"] | None = None,
+        unref: Callable[["asyncio.Task[Any]"], None] | None = None,
+    ) -> None:
+        self.id = id
+        self.lease = lease
+        self.placement_token = placement_token
+        self._abort = abort
+        self._create_task = create_task
+        self._unref = unref
+
+    def abort(self) -> None:
+        self._abort()
+
+    def create_task(self, coro: Coroutine[Any, Any, Any]) -> "asyncio.Task[Any]":
+        if self._create_task is None:
+            return asyncio.create_task(coro)
+        return self._create_task(coro)
+
+    def unref(self, task: "asyncio.Task[Any]") -> None:
+        if self._unref is not None:
+            self._unref(task)
+
+
+class PinnedAPI:
+    # The instance base depends only on the context interface, not the concrete
+    # PinnedContext — a PinnedAPI would host unchanged under any HostableContext.
+    def __init__(self, ctx: "HostableContext") -> None:
+        self.ctx = ctx
+
+    @property
+    def id(self) -> str:
+        return self.ctx.id
+
+    @property
+    def lease(self) -> InstanceLease:
+        return self.ctx.lease
+
+    @property
+    def placement_token(self) -> str:
+        """Random token minted at activation, stable until deactivation. Use it
+        as an activation lock in external systems: write on activate, compare
+        on every guarded write, treat an overwrite as loss of the placement."""
+        return self.ctx.placement_token
+
+    def abort(self) -> None:
+        self.ctx.abort()
+
+    def create_task(self, coro: Coroutine[Any, Any, Any]) -> "asyncio.Task[Any]":
+        return self.ctx.create_task(coro)
+
+    def unref(self, task: "asyncio.Task[Any]") -> "asyncio.Task[Any]":
+        """Mark background work as non-idle-blocking: the task keeps running
+        but no longer counts against idleness, and is cancelled at close."""
+        self.ctx.unref(task)
+        return task
+
+    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: PinnedContext, api: PinnedAPI) -> None:
+        _c: "HostableContext" = ctx
+        _h: "Hostable" = api