induscode 0.1.0__py3-none-any.whl

induscode/channels/framer.py

@@ -0,0 +1,132 @@
+"""NDJSON framer — the concrete, separator-safe line transport
+(port of TS ``src/channels/framer.ts``).
+
+Implements the :class:`~induscode.channels.contract.NdjsonFramer` surface
+declared in the contract: a pure encoder (:func:`encode_line`) and a
+pull-model async-generator decoder (:func:`decode_lines`). Both halves are
+I/O-free seams over an injected stream, so the server, the driver, and the
+oneshot channel share one correct framing implementation.
+
+The correctness pin: U+2028 (LINE SEPARATOR) and U+2029 (PARAGRAPH SEPARATOR)
+are legal inside a JSON string but a downstream splitter that treats them as
+line boundaries corrupts the frame. :func:`encode_line` escapes both to their
+backslash-u forms, and :func:`decode_lines` splits strictly on the line feed
+(U+000A) only — so any value the encoder emits round-trips through the
+decoder unchanged regardless of payload content.
+
+Port notes
+----------
+- Python's ``json.dumps`` does **not** escape U+2028/U+2029 (plan rule 7;
+  with ``ensure_ascii=False`` they pass through raw, exactly like TS
+  ``JSON.stringify``) — the explicit escape is kept verbatim. ``separators``
+  are the compact ``(",", ":")`` pair so the wire bytes match
+  ``JSON.stringify``.
+- Byte chunks are decoded with ``codecs.getincrementaldecoder("utf-8")``
+  (plan rule 8) so a multi-byte rune split across two chunks is reassembled
+  rather than corrupted — the analogue of the TS streaming ``TextDecoder``.
+  Each :func:`decode_lines` call creates a **fresh** decoder (the TS
+  module-level shared decoder was safe only because one reader owns a
+  stream; the per-call decoder removes even that coupling).
+"""
+
+from __future__ import annotations
+
+import codecs
+import json
+from collections.abc import AsyncGenerator
+from typing import Any, Final
+
+from induscode.channels.contract import NdjsonFramer, ReadableChunks
+
+__all__ = [
+    "decode_lines",
+    "encode_line",
+    "ndjson_framer",
+]
+
+
+#: Line feed (U+000A): the one and only frame boundary.
+_LINE_FEED: Final[str] = "\n"
+
+#: LINE SEPARATOR (U+2028) — legal in a JSON string, breaks naive splitters.
+_LINE_SEPARATOR: Final[str] = "\u2028"
+
+#: PARAGRAPH SEPARATOR (U+2029) — legal in a JSON string, breaks splitters.
+_PARAGRAPH_SEPARATOR: Final[str] = "\u2029"
+
+#: The escaped form of U+2028 that survives line splitting.
+_LINE_SEPARATOR_ESCAPE: Final[str] = "\\u2028"
+
+#: The escaped form of U+2029 that survives line splitting.
+_PARAGRAPH_SEPARATOR_ESCAPE: Final[str] = "\\u2029"
+
+
+def _escape_separators(json_text: str) -> str:
+    """Replace each U+2028 / U+2029 with its backslash-u escape.
+
+    Operates on the already-serialized JSON text, so the two separators only
+    ever appear inside string literals; rewriting them to their escape
+    sequences yields an equivalent JSON document with no raw line/paragraph
+    separators left.
+    """
+    return json_text.replace(_LINE_SEPARATOR, _LINE_SEPARATOR_ESCAPE).replace(
+        _PARAGRAPH_SEPARATOR, _PARAGRAPH_SEPARATOR_ESCAPE
+    )
+
+
+def encode_line(value: Any) -> str:
+    """Encode one value as a single, separator-safe NDJSON line.
+
+    Serializes ``value`` with ``json.dumps`` (compact separators, non-ASCII
+    left raw — the ``JSON.stringify`` wire shape), escapes the two Unicode
+    line separators, and appends exactly one line feed. The result contains
+    no raw U+2028 / U+2029 and exactly one terminating ``\\n``, so a
+    strictly-newline splitter recovers it intact.
+
+    :param value: any JSON-serializable value (a request, a reply, a signal)
+    :returns: the encoded line, terminated by a single ``\\n``
+    """
+    return _escape_separators(json.dumps(value, ensure_ascii=False, separators=(",", ":"))) + _LINE_FEED
+
+
+async def decode_lines(stream: ReadableChunks) -> AsyncGenerator[Any, None]:
+    """Decode a chunk stream into a stream of parsed JSON values.
+
+    Pull model: buffers incoming text, splits on ``\\n`` only, parses each
+    complete line, and yields the parsed value. A partial trailing line is
+    held until its newline arrives; an empty (or whitespace-only) line is
+    skipped. A trailing unterminated line at end-of-stream is parsed if it
+    carries content, so a non-newline-terminated final frame is not silently
+    dropped. Byte chunks flow through an incremental UTF-8 decoder so a rune
+    split across chunk boundaries is reassembled.
+
+    :param stream: the raw chunk stream (stdin, a child pipe, an in-memory pipe)
+    """
+    decoder = codecs.getincrementaldecoder("utf-8")()
+    buffer = ""
+
+    async for chunk in stream:
+        buffer += chunk if isinstance(chunk, str) else decoder.decode(chunk)
+
+        newline_at = buffer.find(_LINE_FEED)
+        while newline_at != -1:
+            line = buffer[:newline_at]
+            buffer = buffer[newline_at + 1 :]
+            if len(line.strip()) > 0:
+                yield json.loads(line)
+            newline_at = buffer.find(_LINE_FEED)
+
+    # Flush any decoder-internal state, then emit a final unterminated frame.
+    buffer += decoder.decode(b"", final=True)
+    if len(buffer.strip()) > 0:
+        yield json.loads(buffer)
+
+
+#: The bundled framer pair: the canonical :class:`NdjsonFramer` instance.
+#: Frozen so consumers share one implementation by reference rather than
+#: re-deriving framing at each call site; an embedder may still inject an
+#: alternate framer via the driver / server options.
+ndjson_framer: Final[NdjsonFramer] = NdjsonFramer(
+    encode_line=encode_line,
+    decode_lines=decode_lines,
+)

induscode/channels/link/__init__.py

@@ -0,0 +1,50 @@
+"""Link channel — public barrel (port of TS ``src/channels/link/index.ts``).
+
+The link channel is the long-lived, bidirectional half of the channels
+subsystem: a JSON-RPC 2.0 server that dispatches framed requests through an
+op registry as concurrent tasks (``server``), a generated client built from a
+``__getattr__`` trap rather than hand-written methods (``driver``), and the
+ask / tell dialog bridge that both ends share (``dialog``). Consumers import
+the link surface from ``induscode.channels.link`` rather than the individual
+modules.
+"""
+
+from __future__ import annotations
+
+from induscode.channels.link.dialog import (
+    DIALOG_TABLE,
+    DialogBridgeDeps,
+    DialogSpec,
+    LinkedDialogBridge,
+    create_dialog_bridge,
+    make_dialog_methods,
+)
+from induscode.channels.link.driver import (
+    LinkClient,
+    LinkDriverHandle,
+    LinkDriverIo,
+    LinkRequestError,
+    create_link_driver,
+)
+from induscode.channels.link.server import (
+    LinkServer,
+    LinkServerIo,
+    create_link_server,
+)
+
+__all__ = [
+    "DIALOG_TABLE",
+    "DialogBridgeDeps",
+    "DialogSpec",
+    "LinkClient",
+    "LinkDriverHandle",
+    "LinkDriverIo",
+    "LinkRequestError",
+    "LinkServer",
+    "LinkServerIo",
+    "LinkedDialogBridge",
+    "create_dialog_bridge",
+    "create_link_driver",
+    "create_link_server",
+    "make_dialog_methods",
+]

induscode/channels/link/dialog.py

@@ -0,0 +1,246 @@
+"""Dialog bridge — the ask / tell seam over the link transport
+(port of TS ``src/channels/link/dialog.ts``).
+
+The agent (and the extensions it hosts) needs to interact with whoever drives
+the channel: ask a multiple-choice question, confirm a destructive action,
+prompt for free text, flash a notice, set a status line. Rather than a
+per-interaction handler ladder, the whole surface reduces to two primitives:
+
+- :meth:`LinkedDialogBridge.ask` — one generic round-trip: emit an ``ask``
+  frame, suspend until a correlated answer arrives, and resolve with its
+  value (or a caller-supplied fallback when the deadline lapses or the driver
+  dismisses the request).
+- :meth:`LinkedDialogBridge.tell` — one generic fire-and-forget: emit a
+  ``tell`` frame and return immediately.
+
+Concrete dialog methods (select / confirm / input / notify / status / title)
+are expressed as a *data table* of named entries keyed by interaction kind,
+not as bespoke method bodies. :func:`make_dialog_methods` closes that table
+over a single bridge so a caller gets named conveniences while the bridge
+keeps the lone round-trip / fire-and-forget implementation.
+
+Port notes
+----------
+- The TS promise + ``setTimeout`` pending entry becomes an
+  :class:`asyncio.Future` + ``loop.call_later`` timer; timers never keep the
+  loop alive on their own (the TS ``unref`` concern does not arise).
+- The TS closure-object bridge becomes the :class:`LinkedDialogBridge` class
+  (same four-method surface: ask / tell / deliver / drain).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Any, Callable, Final, Literal, Mapping
+
+from induscode.channels.contract import (
+    AskAnswer,
+    ChannelTimings,
+    DialogBridge,
+    NdjsonFramer,
+    WritableLine,
+    mint_wire_id,
+)
+
+__all__ = [
+    "DIALOG_TABLE",
+    "DialogBridgeDeps",
+    "DialogSpec",
+    "LinkedDialogBridge",
+    "create_dialog_bridge",
+    "make_dialog_methods",
+]
+
+
+#: The correlation-id prefix every ask frame carries (TS ``"ask-"``).
+_ASK_ID_PREFIX: Final[str] = "ask-"
+
+
+@dataclass(frozen=True, slots=True)
+class _Pending:
+    """One suspended ask, awaiting its correlated answer."""
+
+    #: Settles the awaiting future with the answer value (or the fallback).
+    future: asyncio.Future[Any]
+    #: Timer that fires the fallback if no answer arrives in time.
+    timer: asyncio.TimerHandle
+
+
+@dataclass(frozen=True, slots=True)
+class DialogBridgeDeps:
+    """Everything :func:`create_dialog_bridge` needs to emit frames and time
+    out."""
+
+    #: Sink the ask/tell frames are written to (already framed).
+    out: WritableLine
+    #: Framer used to encode each frame to a line.
+    framer: NdjsonFramer
+    #: Timings; only ``dialogMs`` is consulted here.
+    timings: ChannelTimings
+
+
+class LinkedDialogBridge:
+    """A :class:`DialogBridge` whose pending answers are fed by an external
+    reader.
+
+    The bridge itself does not read the stream — the server owns the single
+    decode loop and routes any inbound answer frame to :meth:`deliver`. This
+    keeps one reader over the transport (the server) rather than competing
+    consumers.
+
+    ``ask`` writes an ask frame, registers the pending resolver under a fresh
+    id, and arms a fallback timer; :meth:`deliver` settles the matching
+    pending resolver when the answer returns. ``tell`` writes a tell frame
+    and returns at once. No stdio, no global state — every dependency is
+    injected.
+    """
+
+    __slots__ = ("_deps", "_pending", "_seq")
+
+    def __init__(self, deps: DialogBridgeDeps) -> None:
+        self._deps = deps
+        self._pending: dict[str, _Pending] = {}
+        self._seq = 0
+
+    def _emit(self, frame: Mapping[str, Any]) -> None:
+        self._deps.out.write(self._deps.framer.encode_line(frame))
+
+    def _next_ask_id(self) -> str:
+        """Mint a fresh, process-unique correlation id for an ask."""
+        self._seq += 1
+        return mint_wire_id(_ASK_ID_PREFIX, int(time.time() * 1000), self._seq)
+
+    async def ask(self, kind: str, payload: Any, fallback: Any) -> Any:
+        """Emit an ask frame and resolve with the matching answer value, or
+        ``fallback`` when no answer arrives before ``dialogMs`` lapses."""
+        ask_id = self._next_ask_id()
+        frame: dict[str, Any] = {"type": "ask", "id": ask_id, "kind": kind}
+        if payload is not None:  # JSON.stringify dropped the undefined payload
+            frame["payload"] = payload
+
+        loop = asyncio.get_running_loop()
+        future: asyncio.Future[Any] = loop.create_future()
+
+        def on_timeout() -> None:
+            self._pending.pop(ask_id, None)
+            if not future.done():
+                future.set_result(fallback)
+
+        timer = loop.call_later(self._deps.timings.dialogMs / 1000, on_timeout)
+        self._pending[ask_id] = _Pending(future=future, timer=timer)
+        self._emit(frame)
+        return await future
+
+    def tell(self, kind: str, payload: Any = None) -> None:
+        """Emit a tell frame and return immediately."""
+        frame: dict[str, Any] = {"type": "tell", "kind": kind}
+        if payload is not None:
+            frame["payload"] = payload
+        self._emit(frame)
+
+    def deliver(self, answer: AskAnswer) -> bool:
+        """Resolve the pending ask that minted ``answer.id``.
+
+        A no-op when no ask is pending under that id (a late or duplicate
+        answer), so a misbehaving driver cannot throw into the read loop.
+
+        :param answer: the inbound answer frame
+        :returns: whether a pending ask was settled by this answer
+        """
+        entry = self._pending.pop(answer.id, None)
+        if entry is None:
+            return False
+        entry.timer.cancel()
+        if not entry.future.done():
+            entry.future.set_result(answer.value)
+        return True
+
+    def drain(self) -> None:
+        """Settle every still-pending ask with ``None`` (used on shutdown),
+        so no awaiting handler is left suspended when the link closes."""
+        for entry in self._pending.values():
+            entry.timer.cancel()
+            if not entry.future.done():
+                entry.future.set_result(None)
+        self._pending.clear()
+
+
+def create_dialog_bridge(deps: DialogBridgeDeps) -> LinkedDialogBridge:
+    """Construct a :class:`LinkedDialogBridge` over an injected sink + framer."""
+    return LinkedDialogBridge(deps)
+
+
+# ---------------------------------------------------------------------------
+# Data-driven concrete dialog methods
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class DialogSpec:
+    """One concrete dialog method expressed as data, not code.
+
+    ``kind`` is the wire interaction kind; ``mode`` selects which primitive
+    carries it (a round-trip ``ask`` or a fire-and-forget ``tell``);
+    ``fallback`` is the value a round-trip resolves with on timeout /
+    dismissal (unused for ``tell``). The whole dialog surface is this table —
+    adding an interaction is adding a row.
+    """
+
+    #: The wire interaction kind (the ``Ask.kind`` / ``Tell.kind``).
+    kind: str
+    #: Whether the method round-trips for an answer or is fire-and-forget.
+    mode: Literal["ask", "tell"]
+    #: The value an ``ask`` resolves with when no answer arrives in time.
+    fallback: Any = None
+
+
+#: The canonical dialog table: every concrete interaction the channel
+#: exposes, each one row of data over the two primitives.
+#:
+#: Replaces a copied switch of bespoke UI-context methods: the bridge has
+#: exactly one round-trip and one fire-and-forget body, and this table names
+#: the kinds.
+DIALOG_TABLE: Final[Mapping[str, DialogSpec]] = MappingProxyType(
+    {
+        "select": DialogSpec(kind="select", mode="ask", fallback=None),
+        "confirm": DialogSpec(kind="confirm", mode="ask", fallback=False),
+        "input": DialogSpec(kind="input", mode="ask", fallback=None),
+        "editor": DialogSpec(kind="editor", mode="ask", fallback=None),
+        "notify": DialogSpec(kind="notify", mode="tell"),
+        "status": DialogSpec(kind="status", mode="tell"),
+        "title": DialogSpec(kind="title", mode="tell"),
+    }
+)
+
+
+def make_dialog_methods(bridge: DialogBridge) -> dict[str, Callable[..., Any]]:
+    """Close the :data:`DIALOG_TABLE` over one :class:`DialogBridge` into
+    named convenience methods.
+
+    Each ``ask`` row becomes a thunk that round-trips through ``bridge.ask``
+    with the row fallback (call it with an optional payload and await the
+    result); each ``tell`` row becomes a thunk that fires through
+    ``bridge.tell``. There is no per-method choreography — the bodies are
+    generated from the table.
+
+    :param bridge: the round-trip / fire-and-forget primitive pair
+    :returns: the named method map projected from the table
+    """
+    methods: dict[str, Callable[..., Any]] = {}
+    for name, spec in DIALOG_TABLE.items():
+        if spec.mode == "ask":
+
+            def ask_thunk(payload: Any = None, *, _spec: DialogSpec = spec) -> Any:
+                return bridge.ask(_spec.kind, payload, _spec.fallback)
+
+            methods[name] = ask_thunk
+        else:
+
+            def tell_thunk(payload: Any = None, *, _spec: DialogSpec = spec) -> None:
+                bridge.tell(_spec.kind, payload)
+
+            methods[name] = tell_thunk
+    return methods