kollabor-rpc 0.5.5__tar.gz

kollabor_rpc-0.5.5/.gitignore

@@ -0,0 +1,231 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.env.*
+!.env.example
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be added to the global gitignore or merged into this project gitignore.  For PyCharm
+#  Community Edition, use 'pycharm-ce', for PyCharm Professional Edition, use 'pycharm'.
+.idea/
+
+# VS Code
+.vscode/
+
+# Kollabor specific files
+.kollabor/
+kollabor.log
+*.log
+*.bak
+
+
+# Demo and test files
+demo_thinking_effects.py
+
+# Temporary files
+*.tmp
+*.temp
+*~
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Project trash folder
+.trash/
+
+# Crush tool directory
+.crush/
+
+# Kollabor tool directory
+.kollabor/
+.kollabor-cli/
+*.bak
+*.deleted
+
+# Conversation logs
+convp/
+
+# Personal and development directories
+.marco/
+.marcoai/
+.claude/activity.log
+.claude/bash-commands.log
+.claude/debug-*.log
+.claude/user-*.log
+backups/
+code_audit/
+codemon/
+tools/
+docs/project-management/
+docs/archive/
+.marco
+.archive
+.dead-code-analysis
+.zkollabor-cli/
+
+# Dolt database files (added by bd init)
+.dolt/
+*.db
+.beads/.beads-credential-key
+
+# Claude Code session artifacts
+/2026-*-deploy-handoff-*.txt
+/2027-*-deploy-handoff-*.txt
+.claude/scheduled_tasks.lock

kollabor_rpc-0.5.5/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: kollabor-rpc
+Version: 0.5.5
+Summary: RPC transport for Kollabor (StateService foundation)
+License: MIT
+Requires-Python: >=3.12

kollabor_rpc-0.5.5/README.md

@@ -0,0 +1,22 @@
+# kollabor-rpc
+
+RPC transport layer for the StateService abstraction used by Kollabor's daemon
+and attach mode. Provides the request/response models, error types, server
+dispatcher, and client transport that let a detached Kollab process communicate
+with an attached TUI client.
+
+See the refactor plan at `~/.claude/plans/golden-doodling-kahan.md` (section 1)
+for design context and phase breakdown.
+
+## status
+
+  Phase 1.1 skeleton - modules are stubs. Real implementations land in
+  phases 1.2 (models + errors), 1.3 (server), and 1.4 (client).
+
+## dependencies
+
+  None - stdlib only.
+
+## license
+
+  MIT

kollabor_rpc-0.5.5/pyproject.toml

@@ -0,0 +1,14 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kollabor-rpc"
+version = "0.5.5"
+description = "RPC transport for Kollabor (StateService foundation)"
+requires-python = ">=3.12"
+license = {text = "MIT"}
+dependencies = []
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kollabor_rpc"]

kollabor_rpc-0.5.5/src/kollabor_rpc/__init__.py

@@ -0,0 +1,24 @@
+"""kollabor-rpc: RPC transport for StateService abstraction."""
+
+from .client import RpcClient
+from .errors import RpcError, RpcHandlerError, RpcMethodNotFound, RpcTimeoutError
+from .models import RpcRequest, RpcResponse, new_request_id
+from .server import RpcServer
+from .transport import (
+    LARGE_BUFFER_LIMIT,
+    open_unix_connection_with_large_buffer,
+)
+
+__all__ = [
+    "RpcRequest",
+    "RpcResponse",
+    "new_request_id",
+    "RpcError",
+    "RpcTimeoutError",
+    "RpcMethodNotFound",
+    "RpcHandlerError",
+    "RpcServer",
+    "RpcClient",
+    "LARGE_BUFFER_LIMIT",
+    "open_unix_connection_with_large_buffer",
+]

kollabor_rpc-0.5.5/src/kollabor_rpc/client.py

@@ -0,0 +1,178 @@
+"""Async RPC client that sends requests over an asyncio StreamWriter and resolves
+responses via ``on_reply``.
+
+The caller is responsible for wiring ``on_reply`` into whatever reads the
+underlying transport (e.g. the attach client's read loop). Multiple in-flight
+calls are supported -- each has its own future keyed by ``request_id``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from typing import Any
+
+from .errors import RpcError, RpcHandlerError, RpcMethodNotFound, RpcTimeoutError
+from .models import RpcRequest, new_request_id
+
+logger = logging.getLogger(__name__)
+
+
+class RpcClient:
+    """Async RPC client multiplexed over a single asyncio StreamWriter.
+
+    Usage pattern: the caller constructs the client with an already-connected
+    writer, then arranges for incoming lines from the matching reader to be
+    decoded and passed to :meth:`on_reply`. Each :meth:`call` returns when the
+    matching reply arrives or raises on timeout/error.
+
+    IMPORTANT: The underlying StreamReader/Writer pair MUST be created
+    with a buffer large enough for the largest expected response. The
+    default asyncio.open_unix_connection() uses a 64KB buffer which is
+    too small for real state payloads. Use kollabor_rpc's
+    open_unix_connection_with_large_buffer() helper to get a 16MB limit.
+
+    The caller (not RpcClient) is responsible for creating the reader
+    and writer -- RpcClient only holds a writer reference for sending
+    requests and receives replies via on_reply() which is called by
+    the caller's read loop.
+    """
+
+    def __init__(
+        self,
+        writer: asyncio.StreamWriter,
+        *,
+        default_timeout: float = 30.0,
+    ) -> None:
+        """Initialize the client.
+
+        Args:
+            writer: An already-connected asyncio StreamWriter. The client does
+                not own the writer and will not close it on :meth:`close`.
+            default_timeout: Fallback timeout (seconds) used when
+                :meth:`call` is invoked without an explicit ``timeout``.
+        """
+        self._writer: asyncio.StreamWriter = writer
+        self._default_timeout: float = default_timeout
+        self._pending: dict[str, asyncio.Future[Any]] = {}
+        self._lock: asyncio.Lock = asyncio.Lock()
+        self._closed: bool = False
+
+    async def call(
+        self,
+        method: str,
+        params: dict[str, Any] | None = None,
+        *,
+        timeout: float | None = None,
+    ) -> Any:
+        """Send an RPC request and wait for the response.
+
+        Concurrent calls are supported -- each has its own future keyed by the
+        generated ``request_id``. The writer is guarded by an ``asyncio.Lock``
+        so that interleaved bytes from concurrent writes cannot corrupt the
+        NDJSON stream.
+
+        Args:
+            method: Remote method name.
+            params: JSON-serializable parameter dict. Defaults to an empty dict.
+            timeout: Per-call timeout (seconds). When ``None`` the client's
+                ``default_timeout`` is used.
+
+        Returns:
+            The decoded ``result`` field from the matching RPC reply.
+
+        Raises:
+            RpcError: The client has been closed.
+            RpcTimeoutError: No reply arrived before the effective timeout.
+            RpcMethodNotFound: The server reported ``error_kind == "not_found"``.
+            RpcHandlerError: The server reported ``error_kind in {"handler",
+                "serialization"}``.
+        """
+        if self._closed:
+            raise RpcError("client closed")
+
+        params = params or {}
+        effective_timeout = timeout if timeout is not None else self._default_timeout
+        request_id = new_request_id()
+
+        loop = asyncio.get_running_loop()
+        fut: asyncio.Future[Any] = loop.create_future()
+        self._pending[request_id] = fut
+
+        req = RpcRequest(
+            request_id=request_id,
+            method=method,
+            params=params,
+            timeout=effective_timeout,
+        )
+        line = json.dumps(req.to_wire(), default=str) + "\n"
+
+        try:
+            async with self._lock:
+                self._writer.write(line.encode("utf-8"))
+                await self._writer.drain()
+            try:
+                return await asyncio.wait_for(fut, effective_timeout)
+            except asyncio.TimeoutError:
+                raise RpcTimeoutError(
+                    f"rpc call {method!r} timed out after {effective_timeout}s"
+                )
+        finally:
+            self._pending.pop(request_id, None)
+
+    def on_reply(self, msg_data: dict[str, Any]) -> None:
+        """Route an incoming ``rpc_reply`` dict to the waiting future.
+
+        Called by the attach client's read loop. Unknown ``request_id``s are
+        logged and discarded (likely stale after timeout). Synchronous;
+        returns immediately after scheduling the future resolution.
+        """
+        request_id = msg_data.get("request_id")
+        if not request_id:
+            logger.warning("rpc reply missing request_id: %r", msg_data)
+            return
+
+        fut = self._pending.get(request_id)
+        if fut is None or fut.done():
+            logger.debug("stale rpc reply for request_id=%s", request_id)
+            return
+
+        error = msg_data.get("error")
+        error_kind = msg_data.get("error_kind")
+
+        if error_kind == "not_found":
+            fut.set_exception(RpcMethodNotFound(error or "method not found"))
+        elif error_kind == "handler":
+            fut.set_exception(
+                RpcHandlerError(
+                    error or "remote handler raised",
+                    remote_message=error,
+                )
+            )
+        elif error_kind == "serialization":
+            fut.set_exception(
+                RpcHandlerError(
+                    error or "remote result not serializable",
+                    remote_message=error,
+                )
+            )
+        elif error:
+            fut.set_exception(RpcError(error))
+        else:
+            fut.set_result(msg_data.get("result"))
+
+    def close(self) -> None:
+        """Cancel all pending calls with ``RpcError('rpc client closed')``.
+
+        Safe to call multiple times. Does NOT close the underlying writer --
+        the caller owns that. After ``close()`` any subsequent :meth:`call`
+        raises ``RpcError`` immediately without touching the writer.
+        """
+        if self._closed:
+            return
+        self._closed = True
+        for _request_id, fut in list(self._pending.items()):
+            if not fut.done():
+                fut.set_exception(RpcError("rpc client closed"))
+        self._pending.clear()

kollabor_rpc-0.5.5/src/kollabor_rpc/errors.py

@@ -0,0 +1,35 @@
+"""RPC exception hierarchy. Raised by RpcClient when calls fail."""
+
+from __future__ import annotations
+
+__all__ = [
+    "RpcError",
+    "RpcTimeoutError",
+    "RpcMethodNotFound",
+    "RpcHandlerError",
+]
+
+
+class RpcError(Exception):
+    """Base class for all RPC failures."""
+
+
+class RpcTimeoutError(RpcError):
+    """Raised when no response arrives before the timeout."""
+
+
+class RpcMethodNotFound(RpcError):
+    """Raised when the server has no handler registered for the requested method."""
+
+
+class RpcHandlerError(RpcError):
+    """Raised when a remote handler raised an exception or returned non-serializable data.
+
+    ``remote_message`` carries the server-side error string when available,
+    so callers can surface the original failure reason without losing the
+    client-side context in ``args[0]``.
+    """
+
+    def __init__(self, message: str, remote_message: str | None = None) -> None:
+        super().__init__(message)
+        self.remote_message = remote_message

kollabor_rpc-0.5.5/src/kollabor_rpc/models.py

@@ -0,0 +1,96 @@
+"""Wire-safe RPC request/response models.
+
+All types round-trip through JSON via to_wire/from_wire. These are plain
+dataclasses with no external serialization library dependency.
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from typing import Any
+
+
+def new_request_id() -> str:
+    """Generate a new RPC request id.
+
+    Returns a stateless 32-character hex string derived from uuid4. Collision
+    probability is negligible in practice, so callers can treat each id as
+    globally unique without coordination.
+    """
+    return uuid.uuid4().hex
+
+
+@dataclass(slots=True)
+class RpcRequest:
+    """A single RPC call from client to server."""
+
+    request_id: str
+    method: str
+    params: dict[str, Any] = field(default_factory=dict)
+    timeout: float = 30.0
+
+    def to_wire(self) -> dict[str, Any]:
+        """Serialize to the wire dict carried over the hub socket."""
+        return {
+            "action": "rpc_request",
+            "request_id": self.request_id,
+            "method": self.method,
+            "params": self.params,
+            "timeout": self.timeout,
+        }
+
+    @classmethod
+    def from_wire(cls, data: dict[str, Any]) -> RpcRequest:
+        """Reconstruct from a wire dict.
+
+        Tolerant of missing ``action`` field (the dispatcher usually strips
+        it before calling this). ``params`` and ``timeout`` fall back to
+        empty dict and 30.0 respectively.
+        """
+        return cls(
+            request_id=data["request_id"],
+            method=data["method"],
+            params=data.get("params") or {},
+            timeout=float(data.get("timeout", 30.0)),
+        )
+
+
+@dataclass(slots=True)
+class RpcResponse:
+    """A single RPC reply from server to client.
+
+    ``error_kind`` is one of the literal strings "not_found", "handler",
+    or "serialization", or None for successful replies. Kept as plain str
+    (not typing.Literal) to avoid python-version-specific type hint issues.
+    """
+
+    request_id: str
+    result: Any | None = None
+    error: str | None = None
+    error_kind: str | None = None
+
+    def to_wire(self) -> dict[str, Any]:
+        """Serialize to the wire dict carried over the hub socket."""
+        return {
+            "action": "rpc_reply",
+            "request_id": self.request_id,
+            "result": self.result,
+            "error": self.error,
+            "error_kind": self.error_kind,
+        }
+
+    @classmethod
+    def from_wire(cls, data: dict[str, Any]) -> RpcResponse:
+        """Reconstruct from a wire dict. Only ``request_id`` is required."""
+        return cls(
+            request_id=data["request_id"],
+            result=data.get("result"),
+            error=data.get("error"),
+            error_kind=data.get("error_kind"),
+        )
+
+    @property
+    def is_success(self) -> bool:
+        """True when both ``error`` and ``error_kind`` are None."""
+        return self.error is None and self.error_kind is None