deft-subspace-kernel 0.1.0a1__py3-none-any.whl

deft_subspace/kernel/__init__.py

@@ -0,0 +1,93 @@
+"""Protocol-neutral kernel: channels, NDJSON framing, a JSON-RPC peer, traces, and supervised processes."""
+
+from .abort import AbortController, AbortError, AbortSignal
+from .channel import (
+    Channel,
+    ChannelClosed,
+    EndOfChannel,
+    MemoryChannel,
+    StreamChannel,
+    Transform,
+    channel_pair,
+    iterate,
+    pipe_channel,
+    stream_channel,
+)
+from .clock import Clock, SystemClock, system_clock
+from .errors import ErrorCode, LocalError, LocalErrorKind, RpcError, SubspaceError
+from .framing import EncodeError, FramingDiagnostic, NdjsonDecoder, NdjsonEncoder, ndjson, ndjson_decoder, ndjson_encoder
+from .process import ExitInfo, SpawnError, SupervisedProcess, spawn_process
+from .rpc import (
+    NO_ID,
+    Call,
+    CancelInbound,
+    CancelOutbound,
+    CloseInfo,
+    InboundContext,
+    InboundMiddleware,
+    JsonRpcId,
+    NotificationHandler,
+    OutboundMiddleware,
+    PeerDiagnostic,
+    PeerState,
+    RequestHandler,
+    RpcPeer,
+    cancel_request,
+)
+from .trace import TRACE_VERSION, TraceRecord, TraceTap, format_trace, parse_trace, trace_tap
+
+__all__ = [
+    "SubspaceError",
+    "AbortController",
+    "AbortError",
+    "AbortSignal",
+    "Call",
+    "CancelInbound",
+    "CancelOutbound",
+    "Channel",
+    "ChannelClosed",
+    "Clock",
+    "CloseInfo",
+    "EncodeError",
+    "EndOfChannel",
+    "ErrorCode",
+    "ExitInfo",
+    "FramingDiagnostic",
+    "InboundContext",
+    "InboundMiddleware",
+    "JsonRpcId",
+    "LocalError",
+    "LocalErrorKind",
+    "MemoryChannel",
+    "NO_ID",
+    "NdjsonDecoder",
+    "NdjsonEncoder",
+    "NotificationHandler",
+    "OutboundMiddleware",
+    "PeerDiagnostic",
+    "PeerState",
+    "RequestHandler",
+    "RpcError",
+    "RpcPeer",
+    "SpawnError",
+    "StreamChannel",
+    "SupervisedProcess",
+    "SystemClock",
+    "TRACE_VERSION",
+    "TraceRecord",
+    "TraceTap",
+    "Transform",
+    "cancel_request",
+    "channel_pair",
+    "format_trace",
+    "iterate",
+    "ndjson",
+    "ndjson_decoder",
+    "ndjson_encoder",
+    "parse_trace",
+    "pipe_channel",
+    "spawn_process",
+    "stream_channel",
+    "system_clock",
+    "trace_tap",
+]

deft_subspace/kernel/abort.py

@@ -0,0 +1,173 @@
+"""Cancellation as a value, like the Web's AbortController and AbortSignal.
+
+asyncio cancels tasks; Subspace also needs to say *why* something stopped and
+to let many waiters see one cancel (a turn's cancel answers every open
+permission question). A signal fires once, keeps its reason, and runs its
+listeners synchronously, in the order they were added.
+
+    controller = AbortController()
+    remove = controller.signal.add_listener(lambda reason: print("stopped", reason))
+    controller.abort("user pressed stop")
+    await controller.signal.wait()   # returns at once now
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable, Iterable
+from typing import Any
+
+from .errors import SubspaceError
+
+
+class AbortError(SubspaceError):
+    """The default reason of a signal aborted without one."""
+
+    def __init__(self, message: str = "This operation was aborted") -> None:
+        super().__init__(message)
+
+
+Listener = Callable[[Any], None]
+
+
+class AbortSignal:
+    __slots__ = ("_aborted", "_reason", "_listeners", "_dispose", "__weakref__")
+
+    def __init__(self) -> None:
+        self._aborted = False
+        self._reason: Any = None
+        self._listeners: list[Listener] = []
+        #: For a signal from `any`: removes its listeners from the source signals.
+        self._dispose: Callable[[], None] | None = None
+
+    @property
+    def aborted(self) -> bool:
+        return self._aborted
+
+    @property
+    def reason(self) -> Any:
+        return self._reason
+
+    def add_listener(self, listener: Listener) -> Callable[[], None]:
+        """Call `listener(reason)` once, when the signal fires. Returns a function that removes it.
+
+        On a signal that has already fired, the listener is not called (as on the Web).
+        """
+        if self._aborted:
+            return lambda: None
+        self._listeners.append(listener)
+
+        def remove() -> None:
+            try:
+                self._listeners.remove(listener)
+            except ValueError:
+                pass
+
+        return remove
+
+    def dispose(self) -> None:
+        """Stop following the source signals (a signal from `any`): its listeners on them
+        are removed, so a long-lived source does not keep it alive. It will not fire after
+        this. A no-op for any other signal, and once it fired."""
+        dispose, self._dispose = self._dispose, None
+        if dispose is not None:
+            dispose()
+
+    def __enter__(self) -> AbortSignal:
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.dispose()
+
+    def throw_if_aborted(self) -> None:
+        if self._aborted:
+            reason = self._reason
+            raise reason if isinstance(reason, BaseException) else AbortError(str(reason))
+
+    async def wait(self) -> Any:
+        """Wait until the signal fires; returns its reason."""
+        if self._aborted:
+            return self._reason
+        future: asyncio.Future[Any] = asyncio.get_running_loop().create_future()
+
+        def done(reason: Any) -> None:
+            if not future.done():
+                future.set_result(reason)
+
+        remove = self.add_listener(done)
+        try:
+            return await future
+        finally:
+            remove()
+
+    def _fire(self, reason: Any) -> None:
+        if self._aborted:
+            return
+        self._aborted = True
+        self._reason = AbortError() if reason is None else reason
+        listeners, self._listeners = self._listeners, []
+        for listener in listeners:
+            try:
+                listener(self._reason)
+            except Exception:  # noqa: BLE001 - a listener must not stop the others
+                pass
+
+    @staticmethod
+    def abort(reason: Any = None) -> AbortSignal:
+        """A signal that has already fired."""
+        signal = AbortSignal()
+        signal._fire(reason)
+        return signal
+
+    @staticmethod
+    def any(signals: Iterable[AbortSignal | None]) -> AbortSignal:
+        """A signal that fires when the first of `signals` fires, with its reason.
+
+        It listens on every source until one fires. When you are done with it before
+        then, `dispose()` it (or use it as a context manager) so a long-lived source
+        does not keep it, and whatever listens on it, alive:
+
+            with AbortSignal.any([turn_signal, connection_signal]) as signal:
+                ...
+        """
+        combined = AbortSignal()
+        live = [s for s in signals if s is not None]
+        for signal in live:
+            if signal.aborted:
+                combined._fire(signal.reason)
+                return combined
+        removers: list[Callable[[], None]] = []
+
+        def dispose() -> None:
+            for remove in removers:
+                remove()
+            removers.clear()
+
+        def fire(reason: Any) -> None:
+            combined.dispose()
+            combined._fire(reason)
+
+        for signal in live:
+            removers.append(signal.add_listener(fire))
+        combined._dispose = dispose
+        return combined
+
+    @staticmethod
+    def timeout(ms: float) -> AbortSignal:
+        """A signal that fires after `ms` milliseconds (needs a running loop)."""
+        signal = AbortSignal()
+        asyncio.get_running_loop().call_later(ms / 1000, lambda: signal._fire(TimeoutError(f"timed out after {ms} ms")))
+        return signal
+
+    def __repr__(self) -> str:
+        return f"AbortSignal(aborted={self._aborted})"
+
+
+class AbortController:
+    __slots__ = ("signal",)
+
+    def __init__(self) -> None:
+        self.signal = AbortSignal()
+
+    def abort(self, reason: Any = None) -> None:
+        self.signal._fire(reason)

deft_subspace/kernel/channel.py

@@ -0,0 +1,244 @@
+"""Channels: read what the other side sent, send what you send.
+
+Bytes on the edges (stdio, sockets), structured messages in process.
+
+    message = await channel.receive()   # raises EndOfChannel when the other side has ended
+    await channel.send(message)
+    await channel.close()               # end our side; the other side reads EndOfChannel
+
+A channel may also have `abort()`: close at once, dropping unsent data. The
+peer uses it when a write is stuck; without it, it calls `close()`.
+
+`channel_pair()` connects two in-process ends; `stream_channel()` wraps
+asyncio streams; `pipe_channel()` applies a transform to each direction (that
+is how `ndjson()` turns bytes into JSON values).
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections import deque
+from collections.abc import AsyncIterator, Iterable
+from typing import Any, Generic, Protocol, TypeVar
+
+from .errors import SubspaceError
+
+T = TypeVar("T")
+A = TypeVar("A")
+B = TypeVar("B")
+In = TypeVar("In", contravariant=True)
+Out = TypeVar("Out", covariant=True)
+
+
+class EndOfChannel(SubspaceError):
+    """The other side ended its stream: nothing more will arrive."""
+
+
+class ChannelClosed(SubspaceError):
+    """Sending on a channel whose sending side was closed (or whose reader went away)."""
+
+
+class Channel(Protocol[T]):
+    async def receive(self) -> T:
+        """The next item. Raises `EndOfChannel` once the other side has ended."""
+        ...
+
+    async def send(self, item: T) -> None:
+        """Send an item, in order with earlier sends. Raises `ChannelClosed` when it cannot."""
+        ...
+
+    async def close(self) -> None:
+        """End this side's stream. Idempotent."""
+        ...
+
+
+async def iterate(channel: Channel[T]) -> AsyncIterator[T]:
+    """Every item until the other side ends."""
+    while True:
+        try:
+            yield await channel.receive()
+        except EndOfChannel:
+            return
+
+
+class _Pipe(Generic[T]):
+    """One direction: items in order, then the end."""
+
+    def __init__(self) -> None:
+        self.items: deque[T] = deque()
+        self.ended = False
+        # Every receive() waiting for an item. All are woken; each takes one or waits again.
+        self.waiters: list[asyncio.Future[None]] = []
+
+    def put(self, item: T) -> None:
+        if self.ended:
+            raise ChannelClosed("channel closed")
+        self.items.append(item)
+        self._wake()
+
+    def end(self) -> None:
+        self.ended = True
+        self._wake()
+
+    def _wake(self) -> None:
+        waiters, self.waiters = self.waiters, []
+        for waiter in waiters:
+            if not waiter.done():
+                waiter.set_result(None)
+
+    async def get(self) -> T:
+        while not self.items:
+            if self.ended:
+                raise EndOfChannel()
+            waiter = asyncio.get_running_loop().create_future()
+            self.waiters.append(waiter)
+            try:
+                await waiter
+            finally:
+                if waiter in self.waiters:
+                    self.waiters.remove(waiter)
+        return self.items.popleft()
+
+
+class MemoryChannel(Generic[T]):
+    """One end of an in-process pair."""
+
+    def __init__(self, inbox: _Pipe[T], outbox: _Pipe[T]) -> None:
+        self._inbox = inbox
+        self._outbox = outbox
+
+    async def receive(self) -> T:
+        return await self._inbox.get()
+
+    async def send(self, item: T) -> None:
+        self._outbox.put(item)
+
+    async def close(self) -> None:
+        self._outbox.end()
+
+    async def abort(self) -> None:
+        self._outbox.end()
+
+
+def channel_pair() -> tuple[MemoryChannel[Any], MemoryChannel[Any]]:
+    """Two connected channels in one process: what `a` sends, `b` receives, and the other way round.
+
+    No bytes, no JSON. Use it to run a client and an agent together in tests or in one app.
+    """
+    a_to_b: _Pipe[Any] = _Pipe()
+    b_to_a: _Pipe[Any] = _Pipe()
+    return MemoryChannel(b_to_a, a_to_b), MemoryChannel(a_to_b, b_to_a)
+
+
+class StreamChannel:
+    """asyncio streams (a socket, a child's stdio) as a byte channel."""
+
+    def __init__(self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter | Any, *, chunk_size: int = 65536) -> None:
+        self._reader = reader
+        self._writer = writer
+        self._chunk = chunk_size
+        self._closed = False
+
+    async def receive(self) -> bytes:
+        data = await self._reader.read(self._chunk)
+        if not data:
+            raise EndOfChannel()
+        return data
+
+    async def send(self, item: bytes) -> None:
+        if self._closed or self._writer.is_closing():
+            raise ChannelClosed("stream closed")
+        try:
+            self._writer.write(item)
+            await self._writer.drain()
+        except (ConnectionError, RuntimeError) as error:  # BrokenPipe, reset, closed transport
+            raise ChannelClosed(str(error)) from error
+
+    async def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        try:
+            if self._writer.can_write_eof():
+                self._writer.write_eof()
+            else:
+                self._writer.close()
+        except (OSError, RuntimeError):
+            pass
+
+    async def abort(self) -> None:
+        """Close at once, dropping anything not yet written."""
+        self._closed = True
+        transport = getattr(self._writer, "transport", None)
+        try:
+            if transport is not None:
+                transport.abort()
+            else:
+                self._writer.close()
+        except (OSError, RuntimeError):
+            pass
+
+
+def stream_channel(reader: asyncio.StreamReader, writer: asyncio.StreamWriter | Any) -> StreamChannel:
+    return StreamChannel(reader, writer)
+
+
+class Transform(Protocol[In, Out]):
+    """Turns items into items, keeping state between them (a decoder, a re-chunker)."""
+
+    def feed(self, item: In, /) -> Iterable[Out]: ...
+
+    def flush(self) -> Iterable[Out]:
+        """What is left once the input has ended."""
+        ...
+
+
+class _Piped(Generic[A, B]):
+    def __init__(self, channel: Channel[A], read: Transform[A, B], write: Transform[B, A]) -> None:
+        self._channel = channel
+        self._read = read
+        self._write = write
+        self._ready: deque[B] = deque()
+        self._ended = False
+
+    async def receive(self) -> B:
+        while not self._ready:
+            if self._ended:
+                raise EndOfChannel()
+            try:
+                item = await self._channel.receive()
+            except EndOfChannel:
+                self._ended = True
+                self._ready.extend(self._read.flush())
+                continue
+            self._ready.extend(self._read.feed(item))
+        return self._ready.popleft()
+
+    async def send(self, item: B) -> None:
+        for out in self._write.feed(item):
+            await self._channel.send(out)
+
+    async def close(self) -> None:
+        try:
+            for out in self._write.flush():
+                await self._channel.send(out)
+        except ChannelClosed:
+            pass
+        await self._channel.close()
+
+    async def abort(self) -> None:
+        abort = getattr(self._channel, "abort", None)
+        await (abort() if abort is not None else self._channel.close())
+
+
+def pipe_channel(channel: Channel[A], *, read: Transform[A, B], write: Transform[B, A]) -> Channel[B]:
+    """Apply a transform to each direction of a channel."""
+    return _Piped(channel, read, write)
+
+
+class Identity(Generic[T]):
+    def feed(self, item: T) -> Iterable[T]:
+        return (item,)
+
+    def flush(self) -> Iterable[T]:
+        return ()

deft_subspace/kernel/clock.py

@@ -0,0 +1,39 @@
+"""Time, as something tests can control.
+
+Every timer in the kernel goes through a Clock, so a test can fake it and
+check timeout behaviour without waiting. Times are milliseconds.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Callable
+from typing import Any, Protocol
+
+
+class Clock(Protocol):
+    def now(self) -> float:
+        """Milliseconds since the epoch."""
+        ...
+
+    def set_timeout(self, callback: Callable[[], None], ms: float) -> Any:
+        """Run `callback` after `ms`; returns a handle for `clear_timeout`."""
+        ...
+
+    def clear_timeout(self, handle: Any) -> None: ...
+
+
+class SystemClock:
+    def now(self) -> float:
+        return time.time() * 1000
+
+    def set_timeout(self, callback: Callable[[], None], ms: float) -> asyncio.TimerHandle:
+        return asyncio.get_running_loop().call_later(max(0.0, ms) / 1000, callback)
+
+    def clear_timeout(self, handle: Any) -> None:
+        if handle is not None:
+            handle.cancel()
+
+
+system_clock: Clock = SystemClock()

deft_subspace/kernel/errors.py

@@ -0,0 +1,114 @@
+"""Two kinds of failure, kept apart on purpose.
+
+- `RpcError` crosses the wire. The other side sent it (or we send it).
+- `LocalError` never crosses the wire. It says why *this* side stopped
+  waiting: the caller aborted, a deadline passed, the connection closed, ...
+
+Code that cares should look at `error.kind`, never at message text.
+
+Every exception class the Subspace packages define is a `SubspaceError`, so `except SubspaceError`
+catches all of them. Built-in errors still come through as they are: `TypeError` and `ValueError` for
+wrong arguments or malformed input (such as `parse_trace()`), `OSError` from the file system.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+
+class SubspaceError(Exception):
+    """The base of every exception class the Subspace packages define."""
+
+
+class ErrorCode:
+    """Standard JSON-RPC 2.0 codes, plus the ones ACP and LSP use."""
+
+    PARSE_ERROR = -32700
+    INVALID_REQUEST = -32600
+    METHOD_NOT_FOUND = -32601
+    INVALID_PARAMS = -32602
+    INTERNAL_ERROR = -32603
+    #: ACP: the session (or other resource) does not exist.
+    RESOURCE_NOT_FOUND = -32002
+    #: ACP: authentication required.
+    AUTH_REQUIRED = -32000
+    #: LSP / ACP `$/cancel_request`: the request was cancelled.
+    REQUEST_CANCELLED = -32800
+
+
+_MISSING: Any = object()
+
+
+class RpcError(SubspaceError):
+    """An error the remote side returned, or one a handler raises to return."""
+
+    kind: Literal["remote"] = "remote"
+
+    def __init__(self, code: int, message: str, data: Any = _MISSING) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self._data = data
+
+    @property
+    def data(self) -> Any:
+        return None if self._data is _MISSING else self._data
+
+    @property
+    def has_data(self) -> bool:
+        return self._data is not _MISSING
+
+    @classmethod
+    def method_not_found(cls, method: str) -> RpcError:
+        return cls(ErrorCode.METHOD_NOT_FOUND, f"Method not found: {method}")
+
+    @classmethod
+    def invalid_params(cls, message: str, data: Any = _MISSING) -> RpcError:
+        return cls(ErrorCode.INVALID_PARAMS, message, data)
+
+    @classmethod
+    def not_found(cls, message: str, data: Any = _MISSING) -> RpcError:
+        return cls(ErrorCode.RESOURCE_NOT_FOUND, message, data)
+
+    @classmethod
+    def internal(cls, message: str, data: Any = _MISSING) -> RpcError:
+        return cls(ErrorCode.INTERNAL_ERROR, message, data)
+
+    def to_json(self) -> dict[str, Any]:
+        out: dict[str, Any] = {"code": self.code, "message": self.message}
+        if self._data is not _MISSING:
+            out["data"] = self._data
+        return out
+
+    def __repr__(self) -> str:
+        return f"RpcError({self.code}, {self.message!r})"
+
+
+LocalErrorKind = Literal["aborted", "timeout", "closed", "invalid-response", "send-failed"]
+"""Why this side gave up on a request.
+
+- `aborted`: the caller's AbortSignal fired (or its task was cancelled).
+- `timeout`: the request's deadline passed.
+- `closed`: the connection closed before an answer arrived.
+- `invalid-response`: the answer was not a valid JSON-RPC response.
+- `send-failed`: the request could not be written.
+"""
+
+
+class LocalError(SubspaceError):
+    def __init__(self, kind: LocalErrorKind, message: str, *, cause: Any = None, method: str | None = None) -> None:
+        super().__init__(message)
+        self.kind: LocalErrorKind = kind
+        self.message = message
+        self.method = method
+        self.cause = cause
+        if isinstance(cause, BaseException):
+            self.__cause__ = cause
+
+    @staticmethod
+    def is_(value: object, kind: LocalErrorKind | None = None) -> bool:
+        """Whether `value` is a LocalError (of `kind`, if given)."""
+        return isinstance(value, LocalError) and (kind is None or value.kind == kind)
+
+    def __repr__(self) -> str:
+        return f"LocalError({self.kind!r}, {self.message!r})"