termwright 0.2.0__py3-none-any.whl

termwright/debug.py

@@ -0,0 +1,169 @@
+"""Opt-in diagnostic log for the adapter side, written to a file.
+
+The driver has its own live log (`TERMWRIGHT_DEBUG=1`, stderr, see
+`packages/driver/src/debug.ts`). This is the other half: what the *adapter*
+inside the application decided, which is the half that goes missing when a
+conformance run reports skips and nobody can say why the app never attached.
+
+**Never stderr.** The application under test owns the terminal; a stray line on
+stderr lands in the middle of a render and corrupts the very screen the driver
+is asserting on. So this log goes to a file the caller names, or nowhere.
+
+**Never fatal.** Every failure here — an unwritable path, a full disk, a closed
+file — leaves the application running and the log silently off. A diagnostic
+that can break the thing it diagnoses is worse than no diagnostic.
+
+Enable it with either variable::
+
+    TERMWRIGHT_DEBUG_FILE=/tmp/adapter.log     # preferred
+    TERMWRIGHT_DEBUG=/tmp/adapter.log          # path, not 1/true/all
+
+The second form is a convenience, and it is deliberately restricted to values
+that are *not* the driver's own switches: `TERMWRIGHT_DEBUG=1` reaches the
+child process too, and if that turned this log on it would have to invent a
+destination for it. So `1`, `true`, `on`, `api`, `all`, `0`, `false` and `off`
+all leave the adapter silent, and only a path enables it.
+
+The line format matches the driver's so one reader can take both::
+
+      tw:diag [p41207]   0.004s dormant: TERMWRIGHT_ENDPOINT is not set
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import threading
+import time
+from typing import Mapping, Optional
+
+#: Names the file this log is written to. Preferred over `TERMWRIGHT_DEBUG`
+#: because it cannot collide with the driver's stderr switch.
+ENV_DEBUG_FILE = "TERMWRIGHT_DEBUG_FILE"
+
+#: The driver's switch, honoured here only when it carries a path.
+ENV_DEBUG = "TERMWRIGHT_DEBUG"
+
+#: Values of `TERMWRIGHT_DEBUG` that mean "driver-side logging" and must not be
+#: mistaken for a filename.
+_DRIVER_SWITCHES = frozenset({"", "0", "1", "true", "false", "on", "off", "api", "all"})
+
+#: Categories, borrowed from the driver so a reader greps one vocabulary.
+#: `diag` is a decision or a failure, `sem` the semantic session, `io` traffic.
+_CATEGORIES = ("diag", "sem", "io", "app")
+
+_MAX_MESSAGE = 400
+
+
+def debug_path(env: Optional[Mapping[str, str]] = None) -> Optional[str]:
+    """The file this process should log to, or ``None`` to stay silent."""
+    source: Mapping[str, str] = os.environ if env is None else env
+    explicit = (source.get(ENV_DEBUG_FILE) or "").strip()
+    if explicit:
+        return explicit
+    raw = (source.get(ENV_DEBUG) or "").strip()
+    if not raw or raw.lower() in _DRIVER_SWITCHES:
+        return None
+    return raw
+
+
+class DebugLog:
+    """Appends diagnostic lines to one file.
+
+    Instances are cheap but not free — they hold an open file — so build one
+    per process and pass it down, which is what :func:`from_env` encourages.
+    """
+
+    def __init__(self, handle, *, label: str, now=time.monotonic) -> None:
+        self._handle = handle
+        self._label = label
+        self._now = now
+        self._started = now()
+        self._lock = threading.Lock()
+
+    # -- construction ------------------------------------------------------
+
+    @classmethod
+    def from_env(
+        cls,
+        env: Optional[Mapping[str, str]] = None,
+        *,
+        adapter: str = "adapter",
+    ) -> Optional["DebugLog"]:
+        """Open the log named by the environment, or return ``None``.
+
+        Returns ``None`` for every failure, including an unwritable path: a
+        diagnostic that refuses to start must not stop the application.
+        """
+        path = debug_path(env)
+        if path is None:
+            return None
+        try:
+            handle = open(path, "a", encoding="utf-8", errors="replace")
+        except OSError:
+            return None
+        log = cls(handle, label=f"p{os.getpid()}")
+        log.line(
+            "diag",
+            f"open adapter={adapter} pid={os.getpid()} platform={sys.platform} "
+            f"python={sys.version_info[0]}.{sys.version_info[1]} argv0={_short(sys.argv[0] if sys.argv else '')}",
+        )
+        return log
+
+    # -- writing -----------------------------------------------------------
+
+    @property
+    def label(self) -> str:
+        """The bracketed identifier on every line."""
+        return self._label
+
+    @label.setter
+    def label(self, value: str) -> None:
+        """Adopt the driver's session id once the handshake supplies one."""
+        self._label = value[:8] if value else self._label
+
+    def line(self, category: str, message: str) -> None:
+        """Write one line. Silently does nothing once the file is gone."""
+        if category not in _CATEGORIES:
+            category = "diag"
+        if len(message) > _MAX_MESSAGE:
+            message = f"{message[:_MAX_MESSAGE]}…"
+        seconds = f"{self._now() - self._started:.3f}".rjust(7)
+        text = f"  tw:{category.ljust(4)} [{self._label}] {seconds}s {message}\n"
+        with self._lock:
+            handle = self._handle
+            if handle is None:
+                return
+            try:
+                handle.write(text)
+                handle.flush()
+            except (OSError, ValueError):
+                # ValueError covers a file closed underneath us. Either way the
+                # log is over; the application is not.
+                self._handle = None
+
+    def close(self) -> None:
+        """Close the file. Safe to call more than once."""
+        with self._lock:
+            handle, self._handle = self._handle, None
+        if handle is not None:
+            try:
+                handle.close()
+            except OSError:
+                pass
+
+
+def _short(value: str, limit: int = 60) -> str:
+    """A path or argument shortened for one log line."""
+    return value if len(value) <= limit else f"…{value[-(limit - 1):]}"
+
+
+def describe_endpoint(endpoint: str) -> str:
+    """How an endpoint reads in the log: its transport and its path.
+
+    The endpoint is not a secret — the token is, and the token never appears
+    here — but it is long, so it is shortened from the left, keeping the tail
+    that distinguishes one session's socket from another's.
+    """
+    kind = "pipe" if endpoint.startswith("\\\\") else "unix"
+    return f"{kind}:{_short(endpoint)}"

termwright/diffing.py

@@ -0,0 +1,118 @@
+"""Turning two consecutive trees into the delta between them.
+
+The driver asks for `subscribe: 'diffs'` when it wants patches instead of whole
+trees. Producing one is the mirror of composing one, and it has to agree with
+:func:`termwright.validate.apply_tree_delta` exactly: whatever this emits, the
+driver will apply, and any disagreement shows up as a tree that silently drifts
+from the screen.
+
+Two rules here are easy to get wrong and both are load-bearing:
+
+* A node that *survives* under a parent being removed must be re-sent in
+  ``changed``, even when nothing about it changed, because the removal cascades
+  through it first.
+* ``rootIds`` must be sent whenever the inherited list — the base's roots minus
+  whatever the removals took — is not the list the new tree wants.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Mapping, Optional, Sequence, Set, Tuple
+
+#: Beyond this share of the tree, a delta stops paying for itself and the whole
+#: snapshot is cheaper to send and cheaper to reason about.
+DELTA_SHARE_CEILING = 0.5
+
+
+def _canonical(node: Mapping[str, Any]) -> str:
+    """Stable text for a node, so two nodes compare by value."""
+    return json.dumps(node, sort_keys=True, ensure_ascii=False, separators=(",", ":"))
+
+
+def diff_trees(
+    base: Mapping[str, Any], next_tree: Mapping[str, Any]
+) -> Tuple[List[Dict[str, Any]], List[str], Optional[List[str]], bool]:
+    """Compute ``(changed, removed, root_ids, cursor_changed)``.
+
+    ``root_ids`` is ``None`` when the inherited list already matches, which
+    keeps the delta smaller by the most common amount.
+    """
+    base_nodes: Dict[str, Any] = {node["id"]: node for node in base["nodes"]}
+    next_nodes: Dict[str, Any] = {node["id"]: node for node in next_tree["nodes"]}
+
+    children_of: Dict[str, List[str]] = {}
+    for node in base["nodes"]:
+        parent = node.get("parentId")
+        if parent is not None:
+            children_of.setdefault(parent, []).append(node["id"])
+
+    gone = {node_id for node_id in base_nodes if node_id not in next_nodes}
+
+    # Only the topmost id of each removed subtree needs sending: the cascade
+    # takes the rest, which is what makes a delta small.
+    removal_roots: List[str] = []
+    for node_id in gone:
+        parent = base_nodes[node_id].get("parentId")
+        if parent is None or parent not in gone:
+            removal_roots.append(node_id)
+
+    # Everything the cascade will take, so survivors underneath can be re-sent.
+    swept: Set[str] = set()
+    pending = list(removal_roots)
+    while pending:
+        current = pending.pop()
+        if current in swept:
+            continue
+        swept.add(current)
+        pending.extend(children_of.get(current, ()))
+
+    changed: List[Dict[str, Any]] = []
+    for node_id, node in next_nodes.items():
+        previous = base_nodes.get(node_id)
+        if previous is None or _canonical(previous) != _canonical(node) or node_id in swept:
+            changed.append(dict(node))
+
+    survivors = (set(base_nodes) - swept) | set(next_nodes)
+    inherited = [node_id for node_id in base["rootIds"] if node_id in survivors]
+    root_ids = None if inherited == list(next_tree["rootIds"]) else list(next_tree["rootIds"])
+
+    cursor_changed = base.get("cursor") != next_tree.get("cursor")
+    return changed, sorted(removal_roots), root_ids, cursor_changed
+
+
+def build_delta(
+    base: Mapping[str, Any], next_tree: Mapping[str, Any]
+) -> Optional[Dict[str, Any]]:
+    """Build the `tree-delta` body, or ``None`` when a full tree is cheaper.
+
+    Returning ``None`` is not a failure: past roughly half the tree a delta
+    costs more to send and far more to reason about than the snapshot it
+    replaces.
+    """
+    changed, removed, root_ids, cursor_changed = diff_trees(base, next_tree)
+
+    node_count = max(1, len(next_tree["nodes"]))
+    if len(changed) > node_count * DELTA_SHARE_CEILING:
+        return None
+
+    if base.get("cursor") is not None and next_tree.get("cursor") is None:
+        # A delta can replace a cursor but never remove one, and an absent
+        # cursor is inherited — so the only honest way to drop it is a whole
+        # tree. Sending the delta anyway would leave the driver holding a
+        # cursor the application no longer reports.
+        return None
+
+    delta: Dict[str, Any] = {
+        "type": "tree-delta",
+        "baseRevision": base["revision"],
+        "revision": next_tree["revision"],
+        "changed": changed,
+        "removed": removed,
+    }
+    if root_ids is not None:
+        delta["rootIds"] = root_ids
+    # An absent cursor means unchanged, so it is sent only when it moved.
+    if cursor_changed and next_tree.get("cursor") is not None:
+        delta["cursor"] = next_tree["cursor"]
+    return delta

termwright/errors.py

@@ -0,0 +1,20 @@
+"""Error types shared by the protocol modules."""
+
+from __future__ import annotations
+
+
+class TermwrightError(Exception):
+    """Base class for every error raised across this package's public surface."""
+
+
+class ProtocolViolation(TermwrightError):
+    """Untrusted input broke a wire invariant.
+
+    ``code`` mirrors the reference implementation's ``ProtocolViolation.code``
+    so the cross-language vectors can assert on it.
+    """
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(f"{code}: {message}")
+        self.code = code
+        self.detail = message

termwright/framing.py

@@ -0,0 +1,196 @@
+"""Wire framing: 4-byte big-endian unsigned length prefix + UTF-8 JSON body.
+
+The declared length is checked against ``max_frame_bytes`` before any decoding.
+Anything oversized, partial past the ceiling, or structurally hostile fails
+closed with :class:`ProtocolViolation`, and a failed decoder never resumes:
+resynchronising on an attacker-chosen offset is worse than dropping the link.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, List, Optional
+
+from .errors import ProtocolViolation
+
+FRAME_HEADER_BYTES = 4
+
+#: Property names that carry meaning in JavaScript engines. The reference
+#: implementation rejects them, so we reject them too — a Python adapter must
+#: not be able to smuggle a payload past a JS driver's projection.
+RESERVED_KEYS = frozenset({"__proto__", "constructor", "prototype"})
+
+_LONE_SURROGATE = re.compile("[\ud800-\udfff]")
+
+_JSON_SEPARATORS = (",", ":")
+
+
+def _reject_constant(name: str) -> Any:
+    raise ProtocolViolation("dto-scalar", f"non-finite number literal {name}")
+
+
+def _check_string(value: str, path: str, what: str) -> None:
+    if _LONE_SURROGATE.search(value):
+        raise ProtocolViolation("dto-string", f"unpaired surrogate in {what} at {path}")
+
+
+def project_dto(value: Any, max_depth: int, _depth: int = 0, _path: str = "$") -> Any:
+    """Deep-check an untrusted parsed value and return a JSON-safe copy.
+
+    :param value: Untrusted input, typically the result of :func:`json.loads`.
+    :param max_depth: Maximum nesting depth; the root sits at depth 0.
+    :raises ProtocolViolation: On reserved keys, unpaired surrogates, non-finite
+        numbers, non-JSON types, or nesting beyond ``max_depth``.
+    """
+    if _depth == 0 and (not isinstance(max_depth, int) or max_depth < 0):
+        raise ProtocolViolation("dto-depth", "max_depth must be a non-negative integer")
+
+    if value is None or isinstance(value, bool):
+        return value
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        if value != value or value in (float("inf"), float("-inf")):
+            raise ProtocolViolation("dto-scalar", f"non-finite number at {_path}")
+        return value
+    if isinstance(value, str):
+        _check_string(value, _path, "string")
+        return value
+
+    if _depth > max_depth:
+        raise ProtocolViolation("dto-depth", f"nesting exceeds {max_depth} at {_path}")
+
+    if isinstance(value, list):
+        return [
+            project_dto(item, max_depth, _depth + 1, f"{_path}[{index}]")
+            for index, item in enumerate(value)
+        ]
+    if isinstance(value, dict):
+        projected = {}
+        for key, item in value.items():
+            if not isinstance(key, str):
+                raise ProtocolViolation("dto-key", f"non-string key at {_path}")
+            if key in RESERVED_KEYS:
+                raise ProtocolViolation("dto-key", f'reserved property name "{key}" at {_path}')
+            _check_string(key, _path, "key")
+            projected[key] = project_dto(item, max_depth, _depth + 1, f"{_path}.{key}")
+        return projected
+
+    raise ProtocolViolation(
+        "dto-scalar", f"value of type {type(value).__name__} is not JSON-representable at {_path}"
+    )
+
+
+def encode_json(message: Any) -> bytes:
+    """Serialise to the canonical UTF-8 JSON body (no spaces, no NaN)."""
+    try:
+        text = json.dumps(message, ensure_ascii=False, separators=_JSON_SEPARATORS, allow_nan=False)
+    except (TypeError, ValueError) as error:
+        raise ProtocolViolation("frame-malformed", "message is not JSON-serialisable") from error
+    try:
+        return text.encode("utf-8")
+    except UnicodeEncodeError as error:
+        raise ProtocolViolation("dto-string", "message contains an unpaired surrogate") from error
+
+
+def encode_frame(message: Any, max_frame_bytes: int) -> bytes:
+    """Serialise a message into a single length-prefixed frame.
+
+    :raises ProtocolViolation: If the value is not JSON-representable or the
+        encoded body exceeds ``max_frame_bytes``.
+    """
+    _assert_ceiling(max_frame_bytes)
+    body = encode_json(message)
+    if len(body) > max_frame_bytes:
+        raise ProtocolViolation(
+            "frame-oversized",
+            f"encoded frame is {len(body)} bytes, ceiling is {max_frame_bytes}",
+        )
+    return len(body).to_bytes(FRAME_HEADER_BYTES, "big") + body
+
+
+def _assert_ceiling(max_frame_bytes: int) -> None:
+    if not isinstance(max_frame_bytes, int) or isinstance(max_frame_bytes, bool) or max_frame_bytes <= 0:
+        raise ProtocolViolation("frame-malformed", "max_frame_bytes must be a positive integer")
+
+
+def decode_body(body: bytes, max_depth: int) -> Any:
+    """Decode one frame body into a projected DTO."""
+    try:
+        text = body.decode("utf-8")
+    except UnicodeDecodeError as error:
+        raise ProtocolViolation("frame-encoding", "frame body is not valid UTF-8") from error
+    try:
+        parsed = json.loads(text, parse_constant=_reject_constant)
+    except ProtocolViolation:
+        raise
+    except (ValueError, RecursionError) as error:
+        raise ProtocolViolation("frame-malformed", "frame body is not valid JSON") from error
+    return project_dto(parsed, max_depth)
+
+
+class FrameDecoder:
+    """Streaming decoder for length-prefixed JSON frames.
+
+    Feed arbitrary chunks to :meth:`push`; it returns the messages that became
+    complete. The first violation poisons the instance permanently.
+    """
+
+    def __init__(self, max_frame_bytes: int, max_depth: int) -> None:
+        _assert_ceiling(max_frame_bytes)
+        self._max_frame_bytes = max_frame_bytes
+        self._max_depth = max_depth
+        self._buffer = bytearray()
+        self._failure: Optional[ProtocolViolation] = None
+
+    @property
+    def buffered(self) -> int:
+        """Bytes held back waiting for the rest of a frame."""
+        return len(self._buffer)
+
+    def push(self, chunk: bytes) -> List[Any]:
+        """Feed raw bytes; return the frames that completed, in order."""
+        if self._failure is not None:
+            raise ProtocolViolation(
+                "decoder-poisoned",
+                f"decoder failed earlier ({self._failure.code}) and accepts no further input",
+            )
+        try:
+            return self._push_or_raise(chunk)
+        except ProtocolViolation as error:
+            self._failure = error
+            self._buffer = bytearray()
+            raise
+        except Exception as error:  # pragma: no cover - defensive
+            self._failure = ProtocolViolation("frame-malformed", "frame decoding failed")
+            self._buffer = bytearray()
+            raise self._failure from error
+
+    def _push_or_raise(self, chunk: bytes) -> List[Any]:
+        self._buffer.extend(chunk)
+        messages: List[Any] = []
+        offset = 0
+
+        while len(self._buffer) - offset >= FRAME_HEADER_BYTES:
+            length = int.from_bytes(self._buffer[offset : offset + FRAME_HEADER_BYTES], "big")
+            if length == 0:
+                raise ProtocolViolation("frame-malformed", "frame length must be non-zero")
+            if length > self._max_frame_bytes:
+                raise ProtocolViolation(
+                    "frame-oversized",
+                    f"frame declares {length} bytes, ceiling is {self._max_frame_bytes}",
+                )
+            end = offset + FRAME_HEADER_BYTES + length
+            if len(self._buffer) < end:
+                break
+            messages.append(decode_body(bytes(self._buffer[offset + FRAME_HEADER_BYTES : end]), self._max_depth))
+            offset = end
+
+        if offset:
+            del self._buffer[:offset]
+        if len(self._buffer) > self._max_frame_bytes + FRAME_HEADER_BYTES:
+            raise ProtocolViolation(
+                "frame-oversized", f"buffered {len(self._buffer)} bytes without a complete frame"
+            )
+        return messages

termwright/limits.py

@@ -0,0 +1,82 @@
+"""Protocol limits. Callers may tighten the defaults, never widen the maxima."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, fields
+from typing import Any, Dict, Mapping
+
+LIMIT_FIELDS = (
+    "maxFrameBytes",
+    "maxSnapshotBytes",
+    "maxNodes",
+    "maxDepth",
+    "maxStringBytes",
+    "maxRelationTargets",
+    "maxQueuedFrames",
+    "maxPendingWaiters",
+    "maxSessions",
+    "maxLogRecordBytes",
+    "maxLogQueue",
+)
+
+
+@dataclass(frozen=True)
+class ProtocolLimits:
+    """Per-session capacity ceilings, wire-named to match the JSON payload."""
+
+    maxFrameBytes: int
+    maxSnapshotBytes: int
+    maxNodes: int
+    maxDepth: int
+    maxStringBytes: int
+    maxRelationTargets: int
+    maxQueuedFrames: int
+    maxPendingWaiters: int
+    maxSessions: int
+    maxLogRecordBytes: int
+    maxLogQueue: int
+
+    def to_wire(self) -> Dict[str, int]:
+        """Serialise to the JSON object shape used by ``hello-ack``."""
+        return {field.name: getattr(self, field.name) for field in fields(self)}
+
+    @staticmethod
+    def from_wire(value: Mapping[str, Any]) -> "ProtocolLimits":
+        """Build limits from a validated ``hello-ack`` payload.
+
+        Only the fields this version knows are read. A newer driver may send
+        ceilings that did not exist when this client was published; ignoring
+        them is what lets an old client keep talking to a new driver.
+        """
+        return ProtocolLimits(**{name: int(value[name]) for name in LIMIT_FIELDS})
+
+
+DEFAULT_LIMITS = ProtocolLimits(
+    maxFrameBytes=1 * 1024 * 1024,
+    maxSnapshotBytes=2 * 1024 * 1024,
+    maxNodes=5_000,
+    maxDepth=64,
+    maxStringBytes=16 * 1024,
+    maxRelationTargets=64,
+    maxQueuedFrames=32,
+    maxPendingWaiters=256,
+    maxSessions=16,
+    maxLogRecordBytes=32 * 1024,
+    maxLogQueue=1_000,
+)
+
+ABSOLUTE_LIMITS = ProtocolLimits(
+    maxFrameBytes=8 * 1024 * 1024,
+    maxSnapshotBytes=8 * 1024 * 1024,
+    maxNodes=50_000,
+    maxDepth=256,
+    maxStringBytes=256 * 1024,
+    maxRelationTargets=1_024,
+    maxQueuedFrames=256,
+    maxPendingWaiters=4_096,
+    maxSessions=128,
+    maxLogRecordBytes=256 * 1024,
+    maxLogQueue=10_000,
+)
+
+DEFAULT_NEGOTIATION_MS = 250