lab-link 0.1.1__tar.gz

lab_link-0.1.1/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.3
+Name: lab-link
+Version: 0.1.1
+Summary: Generic server-authoritative sync library for FastAPI
+Author: Andrew Mueller
+Author-email: Andrew Mueller <amueller@caltech.edu>
+Requires-Dist: fastapi>=0.115
+Requires-Dist: jsonpatch>=1.33
+Requires-Dist: pydantic>=2.0
+Requires-Dist: websockets>=12.0
+Requires-Dist: pytest ; extra == 'dev'
+Requires-Dist: pytest-asyncio ; extra == 'dev'
+Requires-Dist: httpx ; extra == 'dev'
+Requires-Dist: uvicorn[standard] ; extra == 'dev'
+Requires-Dist: numpy>=1.24 ; extra == 'numpy'
+Requires-Dist: sqlmodel>=0.0.24 ; extra == 'persist'
+Requires-Python: >=3.11
+Project-URL: Homepage, https://sansseriff.github.io/lab-link/
+Project-URL: Repository, https://github.com/sansseriff/lab-link
+Project-URL: Documentation, https://sansseriff.github.io/lab-link/
+Provides-Extra: dev
+Provides-Extra: numpy
+Provides-Extra: persist
+Description-Content-Type: text/markdown
+
+# lab-link Python
+
+FastAPI/Pydantic backend runtime for `lab-link`.
+
+Use it to register authoritative state, expose a WebSocket sync endpoint, run
+commands with hardware side effects, and broadcast versioned JSON Patch updates.
+
+```bash
+uv add lab-link
+```
+
+```python
+from lab_link import LabSync
+
+sync = LabSync()
+sync.register_state(AppState, initial=state)
+app = sync.create_app()
+```
+
+Full docs: https://sansseriff.github.io/lab-link/

lab_link-0.1.1/README.md

@@ -0,0 +1,20 @@
+# lab-link Python
+
+FastAPI/Pydantic backend runtime for `lab-link`.
+
+Use it to register authoritative state, expose a WebSocket sync endpoint, run
+commands with hardware side effects, and broadcast versioned JSON Patch updates.
+
+```bash
+uv add lab-link
+```
+
+```python
+from lab_link import LabSync
+
+sync = LabSync()
+sync.register_state(AppState, initial=state)
+app = sync.create_app()
+```
+
+Full docs: https://sansseriff.github.io/lab-link/

lab_link-0.1.1/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "lab-link"
+version = "0.1.1"
+description = "Generic server-authoritative sync library for FastAPI"
+readme = "README.md"
+authors = [
+    { name = "Andrew Mueller", email = "amueller@caltech.edu" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi>=0.115",
+    "jsonpatch>=1.33",
+    "pydantic>=2.0",
+    "websockets>=12.0",
+]
+
+[project.urls]
+Homepage = "https://sansseriff.github.io/lab-link/"
+Repository = "https://github.com/sansseriff/lab-link"
+Documentation = "https://sansseriff.github.io/lab-link/"
+
+[project.optional-dependencies]
+persist = [
+    "sqlmodel>=0.0.24",
+]
+numpy = ["numpy>=1.24"]
+dev = ["pytest", "pytest-asyncio", "httpx", "uvicorn[standard]"]
+
+[build-system]
+requires = ["uv_build>=0.9.28,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "httpx>=0.28.1",
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+    "uvicorn[standard]>=0.42.0",
+]

lab_link-0.1.1/src/lab_link/__init__.py

@@ -0,0 +1,5 @@
+from .core import CommandContext, LabSync
+from .errors import CommandError
+from .pointer import escape_pointer_part, ptr
+
+__all__ = ["CommandContext", "CommandError", "LabSync", "escape_pointer_part", "ptr"]

lab_link-0.1.1/src/lab_link/connection_manager.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import asyncio
+import uuid
+from typing import Any
+
+from fastapi import WebSocket
+
+
+class ConnectionManager:
+    def __init__(self) -> None:
+        self.connections: dict[str, WebSocket] = {}
+        self._lock = asyncio.Lock()
+
+    async def connect(
+        self,
+        websocket: WebSocket,
+        client_id: str,
+        state_snapshot: dict[str, Any],
+        state_version: int,
+        stream_snapshots: list[dict[str, Any]] | None = None,
+    ) -> None:
+        await websocket.accept()
+        async with self._lock:
+            self.connections[client_id] = websocket
+        await websocket.send_json(
+            {"type": "snapshot", "data": state_snapshot, "version": state_version}
+        )
+        for msg in (stream_snapshots or []):
+            await websocket.send_json(msg)
+
+    async def disconnect(self, client_id: str) -> None:
+        async with self._lock:
+            self.connections.pop(client_id, None)
+
+    async def broadcast_patch(
+        self,
+        patch: list[dict[str, Any]],
+        version: int,
+        *,
+        origin_client_id: str | None = None,
+        request_id: str | None = None,
+        command: str | None = None,
+    ) -> None:
+        message = {"type": "patch", "patch": patch, "version": version}
+        if origin_client_id is not None:
+            message["originClientId"] = origin_client_id
+        if request_id is not None:
+            message["requestId"] = request_id
+        if command is not None:
+            message["command"] = command
+        await self._broadcast_json(message)
+
+    async def broadcast_json(self, message: dict[str, Any]) -> None:
+        await self._broadcast_json(message)
+
+    async def broadcast_binary(self, frame: bytes) -> None:
+        async with self._lock:
+            items = list(self.connections.items())
+
+        disconnected: list[str] = []
+        for client_id, websocket in items:
+            try:
+                await websocket.send_bytes(frame)
+            except Exception:
+                disconnected.append(client_id)
+
+        if disconnected:
+            async with self._lock:
+                for cid in disconnected:
+                    self.connections.pop(cid, None)
+
+    async def send_to(self, client_id: str, message: dict[str, Any]) -> None:
+        async with self._lock:
+            ws = self.connections.get(client_id)
+        if ws:
+            try:
+                await ws.send_json(message)
+            except Exception:
+                async with self._lock:
+                    self.connections.pop(client_id, None)
+
+    async def close_all(self) -> None:
+        async with self._lock:
+            items = list(self.connections.items())
+            self.connections.clear()
+
+        for _, websocket in items:
+            try:
+                await websocket.close()
+            except Exception:
+                pass
+
+    async def _broadcast_json(self, message: dict[str, Any]) -> None:
+        async with self._lock:
+            items = list(self.connections.items())
+
+        disconnected: list[str] = []
+        for client_id, websocket in items:
+            try:
+                await websocket.send_json(message)
+            except Exception:
+                disconnected.append(client_id)
+
+        if disconnected:
+            async with self._lock:
+                for cid in disconnected:
+                    self.connections.pop(cid, None)
+
+    @staticmethod
+    def generate_client_id() -> str:
+        return str(uuid.uuid4())

lab_link-0.1.1/src/lab_link/core.py

@@ -0,0 +1,547 @@
+from __future__ import annotations
+
+import asyncio
+import contextvars
+import logging
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from inspect import Parameter, iscoroutinefunction, signature
+from typing import Any, Callable, Literal, TypeVar
+
+from fastapi import APIRouter, FastAPI, WebSocket, WebSocketDisconnect
+from pydantic import BaseModel
+
+from .connection_manager import ConnectionManager
+from .errors import CommandError
+from .persistence import PersistenceManager
+from .proxy import StateProxy, SyncState
+from .state_store import StateStore
+from .stream_buffer import AppendBuffer, DeltaBuffer, ReplaceBuffer, StreamRef
+
+T = TypeVar("T", bound=BaseModel)
+_F = TypeVar("_F", bound=Callable[..., Any])
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True, slots=True)
+class CommandContext:
+    client_id: str
+    request_id: str | None
+    command: str
+
+
+@dataclass(frozen=True, slots=True)
+class PatchMetadata:
+    origin_client_id: str | None = None
+    request_id: str | None = None
+    command: str | None = None
+
+
+_current_command_context: contextvars.ContextVar[CommandContext | None] = (
+    contextvars.ContextVar("lab_link_command_context", default=None)
+)
+
+
+class StateTransaction:
+    def __init__(self, sync: "LabSync", meta: PatchMetadata) -> None:
+        self._sync = sync
+        self._meta = meta
+        self._changes: list[tuple[str, Any]] = []
+        self._closed = False
+
+    def __enter__(self) -> "StateTransaction":
+        return self
+
+    def __exit__(self, exc_type: object, exc: object, tb: object) -> None:
+        self._closed = True
+        if exc_type is None and self._changes:
+            self._sync._commit_changes(self._changes, self._meta)
+
+    def set(self, path: str, value: Any) -> None:
+        if self._closed:
+            raise RuntimeError("transaction is already closed")
+        self._changes.append((path, value))
+
+
+class LabSync:
+    def __init__(
+        self,
+        prefix: str = "/sync",
+        persist: bool = False,
+        db_url: str = "sqlite:///lab_link.db",
+        compress: bool = False,
+    ) -> None:
+        self._prefix = prefix.rstrip("/")
+        self._persist = persist
+        self._db_url = db_url
+        self._compress = compress
+
+        self._store: StateStore | None = None
+        self._commands: dict[str, Callable[..., Any]] = {}
+        self._updaters: list[tuple[Callable[..., Any], float]] = []
+        self._streams: dict[str, StreamRef] = {}
+        self._live_buffers: dict[str, AppendBuffer | ReplaceBuffer | DeltaBuffer] = {}
+        self._conn_manager: ConnectionManager | None = None
+        self._persistence: PersistenceManager | None = None
+        self._patch_queue: asyncio.Queue | None = None
+        self._router: APIRouter | None = None
+        self._pending_patch_tasks: set[asyncio.Task[None]] = set()
+
+        # ``sync.state`` is always a SyncState instance.
+        # Before @sync.state is applied it acts as the decorator (callable).
+        # After registration it delegates attribute access to the internal StateProxy.
+        self.state = SyncState(self._register_state_model)
+
+    # ── model registration ───────────────────────────────────────────────────
+
+    def _register_state_model(
+        self,
+        cls: type[BaseModel],
+        initial: BaseModel | dict[str, Any] | None = None,
+    ) -> None:
+        if not issubclass(cls, BaseModel):
+            raise TypeError(f"{cls.__name__} must be a pydantic BaseModel subclass")
+        if initial is None:
+            initial = cls().model_dump(mode="json")
+        self._store = StateStore(cls, initial)
+        self._patch_queue = asyncio.Queue()
+        self.state._set_proxy(
+            StateProxy(self._store, self._patch_queue, self._metadata_from_current_context)
+        )
+
+    def register_state(
+        self,
+        model_class: type[T],
+        *,
+        initial: T | dict[str, Any] | None = None,
+    ) -> None:
+        self._register_state_model(model_class, initial)
+
+    # ── decorators ──────────────────────────────────────────────────────────
+
+    def command(self, fn: _F) -> _F:
+        """@sync.command — registers fn under fn.__name__. Supports sync & async."""
+        self._commands[fn.__name__] = fn
+        return fn
+
+    def updater(self, interval: float = 1.0) -> Callable[[_F], _F]:
+        """@sync.updater(interval=0.1) — registers a background polling coroutine."""
+        def decorator(fn: _F) -> _F:
+            self._updaters.append((fn, interval))
+            return fn
+        return decorator
+
+    # ── stream registration ──────────────────────────────────────────────────
+
+    def stream(
+        self,
+        id: str,
+        *,
+        mode: Literal["append", "replace", "int_delta"] = "replace",
+        capacity: int = 10_000,
+        dtype: Literal["float32", "float64", "json"] = "float32",
+    ) -> StreamRef:
+        """Register a named stream and return a StreamRef.
+
+        The ref is safe to store at module level and use in updaters — it
+        materialises the real buffer automatically when the app lifespan starts.
+        """
+        ref = StreamRef(id, mode, capacity, dtype)
+        self._streams[id] = ref
+        if self._conn_manager is not None:
+            # Already inside lifespan — materialise immediately
+            buf = self._make_buffer(id, mode, capacity, dtype)
+            ref.materialize(buf)
+            self._live_buffers[id] = buf
+        return ref
+
+    def _make_buffer(
+        self, id: str, mode: str, capacity: int, dtype: str
+    ) -> AppendBuffer | ReplaceBuffer | DeltaBuffer:
+        cm = self._conn_manager
+        if mode == "append":
+            return AppendBuffer(id, capacity, cm)
+        elif mode == "replace":
+            return ReplaceBuffer(id, capacity, dtype, cm)
+        elif mode == "int_delta":
+            return DeltaBuffer(id, capacity, cm)
+        else:
+            raise ValueError(f"Unknown stream mode: {mode!r}")
+
+    # ── state access ─────────────────────────────────────────────────────────
+
+    def get(self, path: str) -> Any:
+        """Read helper: sync.get('pump/speed') → scalar value."""
+        if self._store is None:
+            raise RuntimeError("No @sync.state model registered")
+        return self._store.get(path)
+
+    def set(self, path: str, value: Any) -> tuple[list[dict[str, Any]], int]:
+        """Set a JSON Pointer value, validate state, and broadcast one patch."""
+        return self._commit_changes([(path, value)], self._metadata_from_current_context())
+
+    def replace_state(self, state: BaseModel | dict[str, Any]) -> tuple[list[dict[str, Any]], int]:
+        if self._store is None:
+            raise RuntimeError("No sync state model registered")
+        patch, version = self._store.replace_state(state)
+        if patch:
+            self._schedule_patch_broadcast(
+                patch,
+                version,
+                self._metadata_from_current_context(),
+            )
+        return patch, version
+
+    def transaction(
+        self,
+        *,
+        origin: str | None = None,
+        request_id: str | None = None,
+        command: str | None = None,
+    ) -> StateTransaction:
+        ctx = _current_command_context.get()
+        meta = PatchMetadata(
+            origin_client_id=origin if origin is not None else (ctx.client_id if ctx else None),
+            request_id=request_id if request_id is not None else (ctx.request_id if ctx else None),
+            command=command if command is not None else (ctx.command if ctx else None),
+        )
+        return StateTransaction(self, meta)
+
+    @property
+    def streams(self) -> dict[str, AppendBuffer | ReplaceBuffer | DeltaBuffer]:
+        return self._live_buffers
+
+    # ── FastAPI integration ───────────────────────────────────────────────────
+
+    @property
+    def router(self) -> APIRouter:
+        if self._router is not None:
+            return self._router
+        router = APIRouter(prefix=self._prefix)
+
+        @router.get("/state")
+        async def get_state() -> dict[str, Any]:
+            if self._store is None:
+                return {}
+            return self._store.snapshot()
+
+        @router.websocket("/ws")
+        async def ws_endpoint(websocket: WebSocket) -> None:
+            await self._handle_ws(websocket)
+
+        self._router = router
+        return router
+
+    @asynccontextmanager
+    async def lifespan(self, app: FastAPI | None = None):
+        """Use in FastAPI lifespan to start drain task, updaters, persistence."""
+        self._conn_manager = ConnectionManager()
+
+        # Materialise all StreamRefs now that we have a conn_manager
+        for sid, ref in self._streams.items():
+            buf = self._make_buffer(sid, ref.mode, ref.capacity, ref.dtype)
+            ref.materialize(buf)
+            self._live_buffers[sid] = buf
+
+        # Recreate queue in running loop and rebind proxy
+        self._patch_queue = asyncio.Queue()
+        proxy = self.state._get_proxy()
+        if proxy is not None:
+            proxy._rebind_queue(self._patch_queue)
+
+        # Optional persistence
+        if self._persist and self._store is not None:
+            self._persistence = PersistenceManager(self._db_url)
+            saved = self._persistence.initialize()
+            if saved:
+                try:
+                    self._store.replace_state(saved)
+                except Exception:
+                    pass
+
+        tasks: list[asyncio.Task[None]] = []
+
+        if self._store is not None:
+            tasks.append(
+                asyncio.create_task(
+                    _drain_patch_queue(
+                        self._patch_queue,
+                        self._store,
+                        self._conn_manager,
+                        self._persistence,
+                    )
+                )
+            )
+
+        for fn, interval in self._updaters:
+            tasks.append(asyncio.create_task(_run_updater(fn, interval)))
+
+        yield
+
+        for task in tasks:
+            task.cancel()
+        for task in tasks:
+            try:
+                await task
+            except asyncio.CancelledError:
+                pass
+
+        if self._persistence and self._store:
+            self._persistence.save_sync(self._store.snapshot())
+
+        await self._conn_manager.close_all()
+
+    def create_app(self, **fastapi_kwargs: Any) -> FastAPI:
+        """Convenience: creates FastAPI app with lifespan + router pre-wired."""
+        @asynccontextmanager
+        async def _lifespan(app: FastAPI):
+            async with self.lifespan(app):
+                yield
+
+        app = FastAPI(lifespan=_lifespan, **fastapi_kwargs)
+        app.include_router(self.router)
+        return app
+
+    # ── internal WebSocket handler ────────────────────────────────────────────
+
+    async def _handle_ws(self, websocket: WebSocket) -> None:
+        client_id = ConnectionManager.generate_client_id()
+        snapshot = self._store.snapshot() if self._store else {}
+        version = self._store.version() if self._store else 0
+        stream_snapshots = [
+            buf.snapshot_message()
+            for buf in self._live_buffers.values()
+        ]
+        await self._conn_manager.connect(
+            websocket, client_id, snapshot, version, stream_snapshots
+        )
+        try:
+            while True:
+                data = await websocket.receive_json()
+                msg_type = data.get("type")
+                if msg_type == "command":
+                    await self._dispatch_command(
+                        websocket=websocket,
+                        client_id=client_id,
+                        command=str(data.get("command", "")),
+                        params=dict(data.get("params") or {}),
+                        request_id=data.get("requestId"),
+                    )
+                elif msg_type == "stream_resync":
+                    stream_id = data.get("id")
+                    buf = self._live_buffers.get(stream_id)
+                    if buf:
+                        await self._conn_manager.send_to(client_id, buf.snapshot_message())
+        except WebSocketDisconnect:
+            pass
+        except Exception:
+            logger.exception("Unhandled WebSocket error for client %s", client_id)
+        finally:
+            await self._conn_manager.disconnect(client_id)
+
+    async def _dispatch_command(
+        self,
+        websocket: WebSocket,
+        client_id: str,
+        command: str,
+        params: dict[str, Any],
+        request_id: str | None,
+    ) -> None:
+        handler = self._commands.get(command)
+        if handler is None:
+            if request_id:
+                await websocket.send_json(
+                    {
+                        "type": "command_error",
+                        "command": command,
+                        "requestId": request_id,
+                        "code": "unknown_command",
+                        "message": f"Unknown command: {command!r}",
+                        "severity": "error",
+                        "display": "toast",
+                        "recoverable": False,
+                        "originClientId": client_id,
+                        "version": self._store.version() if self._store else 0,
+                    }
+                )
+            return
+
+        ctx = CommandContext(client_id=client_id, request_id=request_id, command=command)
+        token = _current_command_context.set(ctx)
+        try:
+            if iscoroutinefunction(handler):
+                result = await self._call_handler(handler, ctx, params)
+            else:
+                result = self._call_handler(handler, ctx, params)
+
+            if self._patch_queue is not None:
+                await self._patch_queue.join()
+            await self._flush_pending_patch_tasks()
+
+            if request_id:
+                version = self._store.version() if self._store else 0
+                message: dict[str, Any] = {
+                    "type": "command_ack",
+                    "command": command,
+                    "requestId": request_id,
+                    "version": version,
+                }
+                if result is not None:
+                    message["result"] = result
+                await websocket.send_json(message)
+        except CommandError as exc:
+            await self._send_command_error(websocket, exc, command, request_id, client_id)
+        except Exception as exc:
+            logger.exception("Command %r failed", command)
+            if request_id:
+                await self._send_command_error(
+                    websocket,
+                    CommandError(
+                        code="command_failed",
+                        message=str(exc) or "Command failed.",
+                        detail=repr(exc),
+                        recoverable=True,
+                    ),
+                    command,
+                    request_id,
+                    client_id,
+                )
+        finally:
+            _current_command_context.reset(token)
+
+    def _call_handler(
+        self,
+        handler: Callable[..., Any],
+        ctx: CommandContext,
+        params: dict[str, Any],
+    ) -> Any:
+        sig = signature(handler)
+        call_params = dict(params)
+        for name, param in sig.parameters.items():
+            if name in call_params:
+                continue
+            if (
+                name == "ctx"
+                or param.annotation is CommandContext
+                or param.annotation == "CommandContext"
+            ):
+                call_params[name] = ctx
+                break
+            if param.kind in {Parameter.VAR_POSITIONAL, Parameter.VAR_KEYWORD}:
+                continue
+        return handler(**call_params)
+
+    async def _send_command_error(
+        self,
+        websocket: WebSocket,
+        exc: CommandError,
+        command: str,
+        request_id: str | None,
+        client_id: str,
+    ) -> None:
+        if not request_id:
+            return
+        await websocket.send_json(
+            exc.to_message(
+                command=command,
+                request_id=request_id,
+                version=self._store.version() if self._store else 0,
+                origin_client_id=client_id,
+            )
+        )
+
+    def _metadata_from_current_context(self) -> PatchMetadata:
+        ctx = _current_command_context.get()
+        if ctx is None:
+            return PatchMetadata()
+        return PatchMetadata(
+            origin_client_id=ctx.client_id,
+            request_id=ctx.request_id,
+            command=ctx.command,
+        )
+
+    def _commit_changes(
+        self,
+        changes: list[tuple[str, Any]],
+        meta: PatchMetadata,
+    ) -> tuple[list[dict[str, Any]], int]:
+        if self._store is None:
+            raise RuntimeError("No sync state model registered")
+        patch, version = self._store.apply_values(changes)
+        if patch:
+            self._schedule_patch_broadcast(patch, version, meta)
+        return patch, version
+
+    def _schedule_patch_broadcast(
+        self,
+        patch: list[dict[str, Any]],
+        version: int,
+        meta: PatchMetadata,
+    ) -> None:
+        if self._conn_manager is None:
+            return
+        task = asyncio.create_task(self._broadcast_patch(patch, version, meta))
+        self._pending_patch_tasks.add(task)
+        task.add_done_callback(self._pending_patch_tasks.discard)
+
+    async def _broadcast_patch(
+        self,
+        patch: list[dict[str, Any]],
+        version: int,
+        meta: PatchMetadata,
+    ) -> None:
+        if self._conn_manager is None:
+            return
+        await self._conn_manager.broadcast_patch(
+            patch,
+            version,
+            origin_client_id=meta.origin_client_id,
+            request_id=meta.request_id,
+            command=meta.command,
+        )
+        if self._persistence:
+            await self._persistence.save_debounced(self._store.snapshot())
+
+    async def _flush_pending_patch_tasks(self) -> None:
+        while self._pending_patch_tasks:
+            tasks = list(self._pending_patch_tasks)
+            await asyncio.gather(*tasks)
+
+
+# ── background tasks ──────────────────────────────────────────────────────────
+
+async def _drain_patch_queue(
+    queue: asyncio.Queue,
+    store: StateStore,
+    conn_manager: ConnectionManager,
+    persistence: PersistenceManager | None,
+) -> None:
+    while True:
+        item = await queue.get()
+        try:
+            if len(item) == 2:
+                path, value = item
+                meta = PatchMetadata()
+            else:
+                path, value, meta = item
+            patch, version = store.apply_value(path, value)
+            await conn_manager.broadcast_patch(
+                patch,
+                version,
+                origin_client_id=meta.origin_client_id,
+                request_id=meta.request_id,
+                command=meta.command,
+            )
+            if persistence:
+                await persistence.save_debounced(store.snapshot())
+        finally:
+            queue.task_done()
+
+
+async def _run_updater(fn: Callable[..., Any], interval: float) -> None:
+    while True:
+        await asyncio.sleep(interval)
+        if iscoroutinefunction(fn):
+            await fn()
+        else:
+            fn()

lab_link-0.1.1/src/lab_link/errors.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+
+Severity = Literal["info", "warning", "error"]
+DisplayHint = Literal["toast", "banner", "inline"]
+
+
+@dataclass(slots=True)
+class CommandError(Exception):
+    code: str
+    message: str
+    detail: str | None = None
+    severity: Severity = "error"
+    display: DisplayHint = "toast"
+    path: str | None = None
+    recoverable: bool = True
+
+    def __post_init__(self) -> None:
+        super().__init__(self.message)
+
+    def to_message(
+        self,
+        *,
+        command: str,
+        request_id: str | None,
+        version: int,
+        origin_client_id: str | None = None,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "type": "command_error",
+            "command": command,
+            "requestId": request_id,
+            "code": self.code,
+            "message": self.message,
+            "severity": self.severity,
+            "display": self.display,
+            "recoverable": self.recoverable,
+            "version": version,
+        }
+        if self.detail is not None:
+            payload["detail"] = self.detail
+        if self.path is not None:
+            payload["path"] = self.path
+        if origin_client_id is not None:
+            payload["originClientId"] = origin_client_id
+        return payload

lab_link-0.1.1/src/lab_link/persistence.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any
+
+
+class PersistenceManager:
+    """Optional SQLite persistence using sqlmodel. Activated when LabSync(persist=True)."""
+
+    def __init__(self, db_url: str = "sqlite:///lab_link.db") -> None:
+        self._db_url = db_url
+        self._engine = None
+        self._pending_save: asyncio.Task | None = None
+        self._debounce_seconds = 1.0
+
+    def initialize(self) -> dict[str, Any] | None:
+        """Create tables, return persisted state dict if exists, else None."""
+        from sqlmodel import Field, Session, SQLModel, create_engine, select
+
+        class LabSyncState(SQLModel, table=True):
+            id: int | None = Field(default=None, primary_key=True)
+            state_json: str
+
+        self._LabSyncState = LabSyncState
+        self._engine = create_engine(self._db_url)
+        SQLModel.metadata.create_all(self._engine)
+
+        with Session(self._engine) as session:
+            row = session.exec(select(LabSyncState)).first()
+            if row:
+                return json.loads(row.state_json)
+        return None
+
+    def save_sync(self, state: dict[str, Any]) -> None:
+        from sqlmodel import Session, select
+
+        LabSyncState = self._LabSyncState
+        with Session(self._engine) as session:
+            row = session.exec(select(LabSyncState)).first()
+            if row:
+                row.state_json = json.dumps(state)
+            else:
+                row = LabSyncState(state_json=json.dumps(state))
+                session.add(row)
+            session.commit()
+
+    async def save_debounced(self, state: dict[str, Any]) -> None:
+        """Coalesce rapid saves; only persist after debounce_seconds of inactivity."""
+        if self._pending_save and not self._pending_save.done():
+            self._pending_save.cancel()
+
+        loop = asyncio.get_event_loop()
+        self._pending_save = loop.create_task(self._debounced_save(state))
+
+    async def _debounced_save(self, state: dict[str, Any]) -> None:
+        await asyncio.sleep(self._debounce_seconds)
+        self.save_sync(state)

lab_link-0.1.1/src/lab_link/pointer.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+
+def escape_pointer_part(part: object) -> str:
+    return str(part).replace("~", "~0").replace("/", "~1")
+
+
+def ptr(*parts: object) -> str:
+    if not parts:
+        return ""
+    return "/" + "/".join(escape_pointer_part(part) for part in parts)

lab_link-0.1.1/src/lab_link/proxy.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Any, Callable, TypeVar
+
+if TYPE_CHECKING:
+    from .state_store import StateStore
+
+T = TypeVar("T")
+
+
+class NestedProxy:
+    """Accumulates path segments for nested attribute access. Write-only for mutations."""
+
+    __slots__ = ("_root", "_path")
+
+    def __init__(self, root: "StateProxy", path: list[str]) -> None:
+        object.__setattr__(self, "_root", root)
+        object.__setattr__(self, "_path", path)
+
+    def __getattr__(self, name: str) -> "NestedProxy":
+        if name.startswith("_"):
+            raise AttributeError(name)
+        path = object.__getattribute__(self, "_path")
+        root = object.__getattribute__(self, "_root")
+        return NestedProxy(root, path + [name])
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        path = object.__getattribute__(self, "_path")
+        root = object.__getattribute__(self, "_root")
+        full_path = "/" + "/".join(path + [name])
+        root._enqueue(full_path, value)
+
+
+class StateProxy:
+    """
+    Internal proxy held by SyncState. Enqueues ``(json_path, value)`` onto the drain queue
+    on every attribute write. Not exposed directly — use ``sync.state`` instead.
+    """
+
+    __slots__ = ("_store", "_queue", "_metadata_getter")
+
+    def __init__(
+        self,
+        store: "StateStore",
+        queue: asyncio.Queue,
+        metadata_getter: Callable[[], Any] | None = None,
+    ) -> None:
+        object.__setattr__(self, "_store", store)
+        object.__setattr__(self, "_queue", queue)
+        object.__setattr__(self, "_metadata_getter", metadata_getter)
+
+    def __getattr__(self, name: str) -> Any:
+        if name.startswith("_"):
+            raise AttributeError(name)
+        store: "StateStore" = object.__getattribute__(self, "_store")
+        val = store.snapshot().get(name)
+        if isinstance(val, dict):
+            return NestedProxy(self, [name])
+        return val
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        self._enqueue(f"/{name}", value)
+
+    def _enqueue(self, path: str, value: Any) -> None:
+        queue: asyncio.Queue = object.__getattribute__(self, "_queue")
+        metadata_getter: Callable[[], Any] | None = object.__getattribute__(
+            self,
+            "_metadata_getter",
+        )
+        if metadata_getter is None:
+            queue.put_nowait((path, value))
+        else:
+            queue.put_nowait((path, value, metadata_getter()))
+
+    def _rebind_queue(self, queue: asyncio.Queue) -> None:
+        object.__setattr__(self, "_queue", queue)
+
+
+class SyncState:
+    """
+    The object behind ``sync.state``. Dual-purpose:
+
+    - ``@sync.state`` — callable; registers a Pydantic BaseModel class and returns it.
+    - ``sync.state.x = 5`` — after registration, delegates to the internal StateProxy
+      which enqueues ``("/x", 5)`` onto the drain queue.
+
+    Having a single concrete type for both roles lets type checkers (Pylance, mypy)
+    understand ``@sync.state`` as a normal callable decorator that returns the class.
+    """
+
+    __slots__ = ("_proxy", "_on_register")
+
+    def __init__(self, on_register: Callable[[type], None]) -> None:
+        object.__setattr__(self, "_proxy", None)
+        object.__setattr__(self, "_on_register", on_register)
+
+    def __call__(self, cls: type[T]) -> type[T]:
+        """Register ``cls`` as the sync state model. Used as ``@sync.state``."""
+        on_reg: Callable[[type], None] = object.__getattribute__(self, "_on_register")
+        on_reg(cls)
+        return cls
+
+    def __getattr__(self, name: str) -> Any:
+        if name.startswith("_"):
+            raise AttributeError(name)
+        proxy: StateProxy | None = object.__getattribute__(self, "_proxy")
+        if proxy is None:
+            raise RuntimeError("No @sync.state model registered yet")
+        return getattr(proxy, name)
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        proxy: StateProxy | None = object.__getattribute__(self, "_proxy")
+        if proxy is None:
+            raise RuntimeError("No @sync.state model registered yet")
+        setattr(proxy, name, value)
+
+    def _set_proxy(self, proxy: StateProxy) -> None:
+        object.__setattr__(self, "_proxy", proxy)
+
+    def _get_proxy(self) -> StateProxy | None:
+        return object.__getattribute__(self, "_proxy")

lab_link-0.1.1/src/lab_link/state_store.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+import copy
+import json
+import threading
+from collections.abc import Sequence
+from typing import Any, Generic, TypeVar
+
+import jsonpatch
+from pydantic import BaseModel, ValidationError
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class StateStore(Generic[T]):
+    def __init__(self, model_class: type[T], initial: BaseModel | dict[str, Any]) -> None:
+        self._model_class = model_class
+        self._lock = threading.RLock()
+        self._state: dict[str, Any] = {}
+        self._version: int = 0
+        self._replace_internal(initial)
+
+    def _replace_internal(self, state: BaseModel | dict[str, Any]) -> None:
+        validated = self._model_class.model_validate(state)
+        self._state = validated.model_dump(mode="json")
+
+    def snapshot(self) -> dict[str, Any]:
+        with self._lock:
+            return json.loads(json.dumps(self._state))
+
+    def version(self) -> int:
+        with self._lock:
+            return self._version
+
+    def get(self, path: str) -> Any:
+        with self._lock:
+            keys = _parse_pointer(path)
+            current: Any = self._state
+            for key in keys:
+                current = _get_child(current, key, path)
+            return copy.deepcopy(current)
+
+    def apply_value(self, json_path: str, value: Any) -> tuple[list[dict[str, Any]], int]:
+        return self.apply_values([(json_path, value)])
+
+    def apply_values(
+        self,
+        changes: Sequence[tuple[str, Any]],
+    ) -> tuple[list[dict[str, Any]], int]:
+        with self._lock:
+            if not changes:
+                raise ValueError("at least one change is required")
+
+            old_state = json.loads(json.dumps(self._state))
+            next_state = json.loads(json.dumps(self._state))
+
+            for json_path, value in changes:
+                _set_pointer_value(next_state, json_path, value)
+
+            validated = self._validate_state(next_state)
+            self._state = validated
+            self._version += 1
+            patch = jsonpatch.make_patch(old_state, self._state)
+            return list(patch), self._version
+
+    def replace_state(self, state: BaseModel | dict[str, Any]) -> tuple[list[dict[str, Any]], int]:
+        with self._lock:
+            old_state = json.loads(json.dumps(self._state))
+            self._replace_internal(state)
+            self._version += 1
+            patch = jsonpatch.make_patch(old_state, self._state)
+            return list(patch), self._version
+
+    def _validate_current_state(self) -> None:
+        self._state = self._validate_state(self._state)
+
+    def _validate_state(self, state: Any) -> dict[str, Any]:
+        try:
+            validated = self._model_class.model_validate(state)
+        except ValidationError as exc:
+            raise ValueError(f"state validation failed: {exc}") from exc
+        return validated.model_dump(mode="json")
+
+
+def _parse_pointer(path: str) -> list[str]:
+    if path == "":
+        return []
+    if not path.startswith("/"):
+        path = "/" + path
+    return [_unescape_pointer_part(part) for part in path.split("/")[1:]]
+
+
+def _unescape_pointer_part(part: str) -> str:
+    result = []
+    i = 0
+    while i < len(part):
+        char = part[i]
+        if char == "~":
+            if i + 1 >= len(part) or part[i + 1] not in {"0", "1"}:
+                raise ValueError(f"invalid JSON Pointer escape in segment {part!r}")
+            result.append("~" if part[i + 1] == "0" else "/")
+            i += 2
+        else:
+            result.append(char)
+            i += 1
+    return "".join(result)
+
+
+def _get_child(current: Any, key: str, full_path: str) -> Any:
+    if isinstance(current, dict):
+        if key not in current:
+            raise KeyError(f"path {full_path!r} does not exist")
+        return current[key]
+    if isinstance(current, list):
+        index = _parse_list_index(key, len(current), full_path)
+        return current[index]
+    raise TypeError(f"path {full_path!r} traverses non-container value")
+
+
+def _set_pointer_value(state: Any, path: str, value: Any) -> None:
+    keys = _parse_pointer(path)
+    if not keys:
+        raise ValueError("path must not be empty; use replace_state() for root replacement")
+
+    current = state
+    for key in keys[:-1]:
+        current = _get_child(current, key, path)
+
+    last = keys[-1]
+    if isinstance(current, dict):
+        if last not in current:
+            raise KeyError(f"path {path!r} does not exist")
+        current[last] = value
+        return
+
+    if isinstance(current, list):
+        if last == "-":
+            current.append(value)
+            return
+        index = _parse_list_index(last, len(current), path)
+        current[index] = value
+        return
+
+    raise TypeError(f"path {path!r} targets non-container value")
+
+
+def _parse_list_index(segment: str, length: int, full_path: str) -> int:
+    if not segment.isdecimal():
+        raise TypeError(f"path {full_path!r} uses non-numeric list index {segment!r}")
+    index = int(segment)
+    if index >= length:
+        raise IndexError(f"path {full_path!r} list index {index} out of range")
+    return index

lab_link-0.1.1/src/lab_link/stream_buffer.py

@@ -0,0 +1,191 @@
+from __future__ import annotations
+
+import struct
+from collections import deque
+from typing import TYPE_CHECKING, Any, Literal
+
+if TYPE_CHECKING:
+    from .connection_manager import ConnectionManager
+
+
+class AppendBuffer:
+    """Ring buffer for time-series streams (sensor history, logs)."""
+
+    def __init__(self, id: str, capacity: int, conn_manager: "ConnectionManager") -> None:
+        self.id = id
+        self._capacity = capacity
+        self._conn_manager = conn_manager
+        self._buffer: deque[Any] = deque(maxlen=capacity)
+        self._seq: int = 0
+
+    async def append(self, point: Any) -> None:
+        self._buffer.append(point)
+        self._seq += 1
+        await self._conn_manager.broadcast_json(
+            {"type": "stream_append", "id": self.id, "data": [point], "seq": self._seq}
+        )
+
+    async def extend(self, points: list[Any]) -> None:
+        self._buffer.extend(points)
+        self._seq += 1
+        await self._conn_manager.broadcast_json(
+            {"type": "stream_append", "id": self.id, "data": points, "seq": self._seq}
+        )
+
+    def snapshot_message(self) -> dict[str, Any]:
+        return {
+            "type": "stream_snapshot",
+            "id": self.id,
+            "data": list(self._buffer),
+            "seq": self._seq,
+        }
+
+
+class ReplaceBuffer:
+    """Full-replace buffer for float arrays (FFT, KDE, waveform)."""
+
+    def __init__(
+        self,
+        id: str,
+        capacity: int,
+        dtype: str,
+        conn_manager: "ConnectionManager",
+    ) -> None:
+        self.id = id
+        self._capacity = capacity
+        self._dtype = dtype
+        self._conn_manager = conn_manager
+        self._data: list[float] = []
+        self._seq: int = 0
+
+    async def replace(self, data: "list[float] | Any") -> None:
+        try:
+            import numpy as np
+            if isinstance(data, np.ndarray):
+                data = data.tolist()
+        except ImportError:
+            pass
+        self._data = list(data)
+        self._seq += 1
+
+        if self._dtype in ("float32", "float64"):
+            frame = self._encode_binary(self._data)
+            await self._conn_manager.broadcast_binary(frame)
+        else:
+            await self._conn_manager.broadcast_json(
+                {"type": "stream_replace", "id": self.id, "data": self._data, "seq": self._seq}
+            )
+
+    def _encode_binary(self, data: list[float]) -> bytes:
+        id_bytes = self.id.encode("utf-8")
+        header = struct.pack("<BH", 0x01, len(id_bytes)) + id_bytes + struct.pack("<I", self._seq)
+        fmt = "<" + ("f" if self._dtype == "float32" else "d") * len(data)
+        payload = struct.pack(fmt, *data)
+        return header + payload
+
+    def snapshot_message(self) -> dict[str, Any]:
+        return {
+            "type": "stream_snapshot",
+            "id": self.id,
+            "data": self._data,
+            "seq": self._seq,
+        }
+
+
+class DeltaBuffer:
+    """Sparse-delta buffer for integer-count histograms."""
+
+    def __init__(self, id: str, num_bins: int, conn_manager: "ConnectionManager") -> None:
+        self.id = id
+        self._num_bins = num_bins
+        self._conn_manager = conn_manager
+        self._bins: list[int] = [0] * num_bins
+        self._seq: int = 0
+
+    async def apply_delta(self, deltas: dict[int, int]) -> None:
+        for idx, delta in deltas.items():
+            self._bins[idx] += delta
+        self._seq += 1
+        sparse = [[idx, delta] for idx, delta in deltas.items() if delta != 0]
+        await self._conn_manager.broadcast_json(
+            {"type": "stream_delta", "id": self.id, "deltas": sparse, "seq": self._seq}
+        )
+
+    async def replace(self, bins: list[int]) -> None:
+        self._bins = list(bins)
+        self._seq += 1
+        await self._conn_manager.broadcast_json(self.snapshot_message())
+
+    def snapshot_message(self) -> dict[str, Any]:
+        return {
+            "type": "stream_snapshot",
+            "id": self.id,
+            "data": list(self._bins),
+            "seq": self._seq,
+        }
+
+
+class StreamRef:
+    """
+    Lazy reference returned by ``sync.stream()``.
+
+    Holds the stream spec (id, mode, capacity, dtype) until the app lifespan starts
+    and materialises the real buffer. After that all method calls are forwarded.
+
+    This lets user code store the return value of ``sync.stream()`` at module level
+    and call ``await buf.append(...)`` inside updaters without worrying about
+    whether the lifespan has started yet.
+    """
+
+    def __init__(
+        self,
+        id: str,
+        mode: Literal["append", "replace", "int_delta"],
+        capacity: int,
+        dtype: Literal["float32", "float64", "json"],
+    ) -> None:
+        self.id = id
+        self.mode = mode
+        self.capacity = capacity
+        self.dtype = dtype
+        self._buffer: AppendBuffer | ReplaceBuffer | DeltaBuffer | None = None
+
+    def materialize(self, buffer: AppendBuffer | ReplaceBuffer | DeltaBuffer) -> None:
+        self._buffer = buffer
+
+    def _require(self) -> AppendBuffer | ReplaceBuffer | DeltaBuffer:
+        if self._buffer is None:
+            raise RuntimeError(
+                f"Stream {self.id!r} is not yet active — "
+                "ensure it is accessed after the app lifespan has started."
+            )
+        return self._buffer
+
+    # ── AppendBuffer interface ────────────────────────────────────────────────
+
+    async def append(self, point: Any) -> None:
+        buf = self._require()
+        assert isinstance(buf, AppendBuffer)
+        await buf.append(point)
+
+    async def extend(self, points: list[Any]) -> None:
+        buf = self._require()
+        assert isinstance(buf, AppendBuffer)
+        await buf.extend(points)
+
+    # ── ReplaceBuffer interface ───────────────────────────────────────────────
+
+    async def replace(self, data: Any) -> None:
+        buf = self._require()
+        assert isinstance(buf, ReplaceBuffer)
+        await buf.replace(data)
+
+    # ── DeltaBuffer interface ─────────────────────────────────────────────────
+
+    async def apply_delta(self, deltas: dict[int, int]) -> None:
+        buf = self._require()
+        assert isinstance(buf, DeltaBuffer)
+        await buf.apply_delta(deltas)
+
+    def snapshot_message(self) -> dict[str, Any]:
+        return self._require().snapshot_message()