termwright 0.2.0__py3-none-any.whl

termwright/logging_bridge.py

@@ -0,0 +1,108 @@
+"""Bridge from the standard library's :mod:`logging` to the semantic channel.
+
+A TUI must not write diagnostics to the screen, so the usual advice is to send
+them to a file. Under the driver they can go somewhere better: attach this
+handler and every record the application already emits becomes assertable test
+state, with the application's own logging calls unchanged.
+
+    from termwright import client_from_env
+    from termwright.logging_bridge import install_log_handler
+
+    client = client_from_env(adapter_name="my-tui", adapter_version="1.0.0",
+                             capabilities=CAPABILITIES_WITH_LOGS)
+    if client is not None and await client.start():
+        install_log_handler(client)
+
+Dormant by construction: with no client there is no handler, so an app that
+ships this call unconditionally still logs exactly as it did before.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, Optional
+
+from .client import SemanticClient
+from .logs import flatten_attrs
+
+#: Python's ladder onto the wire's. `logging` has no `trace` or `fatal` of its
+#: own: anything below DEBUG is trace, and CRITICAL is fatal.
+_LEVEL_BY_NUMBER = (
+    (logging.CRITICAL, "fatal"),
+    (logging.ERROR, "error"),
+    (logging.WARNING, "warn"),
+    (logging.INFO, "info"),
+    (logging.DEBUG, "debug"),
+)
+
+#: Attributes every :class:`logging.LogRecord` carries; anything else on the
+#: record was put there by the application and is worth forwarding.
+_STANDARD_FIELDS = frozenset(
+    {
+        "args", "asctime", "created", "exc_info", "exc_text", "filename",
+        "funcName", "levelname", "levelno", "lineno", "message", "module",
+        "msecs", "msg", "name", "pathname", "process", "processName",
+        "relativeCreated", "stack_info", "taskName", "thread", "threadName",
+    }
+)
+
+
+def level_for(levelno: int) -> str:
+    """Map a :mod:`logging` level number onto a wire level."""
+    for threshold, name in _LEVEL_BY_NUMBER:
+        if levelno >= threshold:
+            return name
+    return "trace"
+
+
+class TermwrightLogHandler(logging.Handler):
+    """A :class:`logging.Handler` that forwards records to the driver.
+
+    Never raises into the application: a handler that threw would turn a log
+    line into a crash, so failures are counted on the client and dropped.
+    """
+
+    def __init__(self, client: SemanticClient, level: int = logging.NOTSET) -> None:
+        super().__init__(level)
+        self._client = client
+
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            self._client.log(
+                level_for(record.levelno),
+                self.format(record) if self.formatter else record.getMessage(),
+                attrs=self._attrs(record),
+                logger=record.name,
+                ts=int(record.created * 1000),
+            )
+        except Exception:  # pragma: no cover - logging must never break the app
+            self.handleError(record)
+
+    def _attrs(self, record: logging.LogRecord) -> Optional[Dict[str, Any]]:
+        """Application-supplied `extra` fields, flattened to dotted keys."""
+        extra = {
+            key: value
+            for key, value in record.__dict__.items()
+            if key not in _STANDARD_FIELDS and not key.startswith("_")
+        }
+        if record.exc_info and record.exc_info[0] is not None:
+            extra["exception"] = record.exc_info[0].__name__
+        return flatten_attrs(extra) if extra else None
+
+
+def install_log_handler(
+    client: Optional[SemanticClient],
+    logger: Optional[logging.Logger] = None,
+    level: int = logging.NOTSET,
+) -> Optional[TermwrightLogHandler]:
+    """Attach a handler to ``logger`` (the root logger by default).
+
+    :param client: A live client, or ``None`` — in which case nothing is
+        installed and ``None`` comes back, so the dormant path stays a no-op.
+    :returns: The installed handler, for later :meth:`logging.Logger.removeHandler`.
+    """
+    if client is None:
+        return None
+    handler = TermwrightLogHandler(client, level)
+    (logger or logging.getLogger()).addHandler(handler)
+    return handler

termwright/logs.py

@@ -0,0 +1,207 @@
+"""Application log records carried over the semantic channel.
+
+A TUI cannot print diagnostics to the screen without corrupting the render, so
+applications write them to a logger instead. The ``logs`` capability forwards
+those records to the driver, where they become assertable test state rather
+than invisible side effects.
+
+Records are bounded exactly like snapshots: checked against a byte ceiling and
+rejected wholesale on any violation, so a misbehaving logger degrades into
+dropped records rather than unbounded driver memory.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any, Dict, Mapping, Optional, Union
+
+from .framing import encode_json, project_dto
+from .errors import ProtocolViolation
+from .limits import DEFAULT_LIMITS, ProtocolLimits
+
+#: Severity ladder, least to most severe. The intersection of the ladders used
+#: by Python ``logging``, Go ``slog``, Rust ``tracing``, pino and winston, so
+#: every bridge maps onto it without inventing a level.
+LOG_LEVELS = ("trace", "debug", "info", "warn", "error", "fatal")
+
+LEVEL_SET = frozenset(LOG_LEVELS)
+
+#: Numeric severity; higher is more severe.
+LOG_LEVEL_SEVERITY: Dict[str, int] = {
+    "trace": 10,
+    "debug": 20,
+    "info": 30,
+    "warn": 40,
+    "error": 50,
+    "fatal": 60,
+}
+
+#: Maximum number of attribute keys on one record.
+MAX_LOG_ATTRS = 64
+
+RECORD_FIELDS = ("ts", "level", "message", "attrs", "logger", "seq", "revision")
+
+_MAX_SAFE_INTEGER = 2**53 - 1
+
+#: Values an attribute may hold. Scalars only: nested objects make record size
+#: unbounded and depth-dependent, and every bridge already flattens for its own
+#: transport.
+LogAttrValue = Union[str, int, float, bool, None]
+
+
+@dataclass(frozen=True)
+class LogRecord:
+    """One application log record.
+
+    ``ts`` is Unix epoch milliseconds, not session-relative: an adapter has no
+    reliable view of when the driver considers the session to have started, so
+    the wall clock is the only clock both sides agree on without negotiating.
+    The driver rebases it onto the session timeline.
+    """
+
+    ts: int
+    level: str
+    message: str
+    seq: int
+    attrs: Optional[Mapping[str, LogAttrValue]] = None
+    logger: Optional[str] = None
+    revision: Optional[int] = None
+
+    def to_wire(self) -> Dict[str, Any]:
+        """Serialise, dropping unset optionals: the schema is strict."""
+        wire: Dict[str, Any] = {"ts": self.ts, "level": self.level, "message": self.message}
+        if self.attrs is not None:
+            wire["attrs"] = dict(self.attrs)
+        if self.logger is not None:
+            wire["logger"] = self.logger
+        wire["seq"] = self.seq
+        if self.revision is not None:
+            wire["revision"] = self.revision
+        return wire
+
+
+@dataclass(frozen=True)
+class LogValidationResult:
+    """Outcome of :func:`validate_log_record`."""
+
+    ok: bool
+    record: Optional[Dict[str, Any]] = None
+    code: Optional[str] = None
+    detail: str = ""
+
+
+def _fail(code: str, detail: str) -> LogValidationResult:
+    return LogValidationResult(ok=False, code=code, detail=detail)
+
+
+def _utf8_len(text: str) -> int:
+    return len(text.encode("utf-8", "surrogatepass"))
+
+
+def _safe_non_negative(value: Any) -> bool:
+    return (
+        isinstance(value, int)
+        and not isinstance(value, bool)
+        and 0 <= value <= _MAX_SAFE_INTEGER
+    )
+
+
+def validate_log_record(
+    value: Any, limits: ProtocolLimits = DEFAULT_LIMITS
+) -> LogValidationResult:
+    """Validate an untrusted log record against ``limits``.
+
+    Mirrors :func:`termwright.validate.validate_snapshot`: the value is
+    projected first, then measured against ``maxLogRecordBytes``, then checked
+    field by field. Never raises.
+    """
+    try:
+        projected = project_dto(value, limits.maxDepth)
+    except ProtocolViolation as error:
+        return _fail("depth" if error.code == "dto-depth" else "schema", str(error))
+
+    try:
+        serialised = encode_json(projected)
+    except ProtocolViolation:
+        return _fail("schema", "log record is not JSON-serialisable")
+    if len(serialised) > limits.maxLogRecordBytes:
+        return _fail(
+            "bytes",
+            f"log record is {len(serialised)} bytes, ceiling is {limits.maxLogRecordBytes}",
+        )
+
+    if not isinstance(projected, dict):
+        return _fail("schema", "log record must be an object")
+    record: Dict[str, Any] = projected
+
+    for key in record:
+        if key not in RECORD_FIELDS:
+            return _fail("schema", f'unknown log record property "{key}"')
+
+    if not _safe_non_negative(record.get("ts")) or record["ts"] == 0:
+        return _fail("schema", "ts must be a positive safe integer (epoch milliseconds)")
+    if record.get("level") not in LEVEL_SET:
+        return _fail("schema", f"level must be one of {', '.join(LOG_LEVELS)}")
+    if not isinstance(record.get("message"), str):
+        return _fail("schema", "message must be a string")
+    if _utf8_len(record["message"]) > limits.maxStringBytes:
+        return _fail("string-bytes", f"message exceeds {limits.maxStringBytes} UTF-8 bytes")
+    if not _safe_non_negative(record.get("seq")):
+        return _fail("schema", "seq must be a non-negative safe integer")
+
+    if "logger" in record:
+        if not isinstance(record["logger"], str):
+            return _fail("schema", "logger must be a string")
+        if _utf8_len(record["logger"]) > limits.maxStringBytes:
+            return _fail("string-bytes", f"logger exceeds {limits.maxStringBytes} UTF-8 bytes")
+
+    if "revision" in record:
+        if not _safe_non_negative(record["revision"]) or record["revision"] == 0:
+            return _fail("revision", "revision must be a positive safe integer")
+
+    if "attrs" in record:
+        attrs = record["attrs"]
+        if not isinstance(attrs, dict):
+            return _fail("schema", "attrs must be a flat object")
+        if len(attrs) > MAX_LOG_ATTRS:
+            return _fail("count", f"attrs carries {len(attrs)} keys, ceiling is {MAX_LOG_ATTRS}")
+        for key, attr in attrs.items():
+            if _utf8_len(key) > limits.maxStringBytes:
+                return _fail("string-bytes", f'attribute key "{key}" exceeds the string ceiling')
+            if attr is not None and not isinstance(attr, (str, int, float, bool)):
+                return _fail(
+                    "schema", f'attribute "{key}" must be a string, number, boolean or null'
+                )
+            if isinstance(attr, float) and (attr != attr or attr in (float("inf"), float("-inf"))):
+                return _fail("schema", f'attribute "{key}" must be a finite number')
+            if isinstance(attr, str) and _utf8_len(attr) > limits.maxStringBytes:
+                return _fail("string-bytes", f'attribute "{key}" exceeds the string ceiling')
+
+    return LogValidationResult(ok=True, record=record)
+
+
+def flatten_attrs(
+    value: Mapping[str, Any], prefix: str = "", depth: int = 0
+) -> Dict[str, LogAttrValue]:
+    """Flatten nested context into dotted keys, as the wire format requires.
+
+    ``{"db": {"host": "x"}}`` becomes ``{"db.host": "x"}``. Values that are not
+    scalars after flattening are rendered with :func:`repr`, because losing the
+    shape of a value is better than dropping the record that carries it.
+    """
+    flat: Dict[str, LogAttrValue] = {}
+    for key, item in value.items():
+        name = f"{prefix}{key}"
+        if isinstance(item, Mapping) and depth < 4:
+            flat.update(flatten_attrs(item, f"{name}.", depth + 1))
+        elif item is None or isinstance(item, (str, bool, int)):
+            flat[name] = item
+        elif isinstance(item, float):
+            flat[name] = item if item == item and item not in (float("inf"), float("-inf")) else str(item)
+        else:
+            try:
+                flat[name] = json.dumps(item, default=repr)
+            except (TypeError, ValueError):
+                flat[name] = repr(item)
+    return flat

termwright/marker.py

@@ -0,0 +1,128 @@
+"""Render-commit marker.
+
+The adapter writes this OSC sequence to stdout *after* the last byte of the
+render belonging to revision N. It is a frame-commit signal, never a data
+carrier::
+
+    OSC 8487 ; twm;<revision>;<mac> BEL
+
+with ``mac = base64url(HMAC-SHA256(token, f"{session_id}:{revision}"))[:16]``,
+unpadded. The token is an opaque UTF-8 string end to end: whatever arrives in
+``TERMWRIGHT_TOKEN`` is fed to the HMAC as key bytes, never re-decoded.
+
+OSC rather than DCS because ConPTY rewrites the stream it forwards: a
+passthrough probe showed it dropping DCS, APC and OSC 8 while passing private
+OSC with either terminator, so a DCS marker could not reach the driver on
+Windows at all. One encoding everywhere beats negotiating per platform — the
+path used least is the one that rots unnoticed.
+"""
+
+from __future__ import annotations
+
+import base64
+import hmac
+import re
+from dataclasses import dataclass
+from hashlib import sha256
+from typing import Optional
+
+from .errors import ProtocolViolation
+
+#: The private OSC number carrying render-commit markers. Chosen clear of
+#: everything in use (xterm's allocations, OSC 8, 9, 99, 133, 633, 697, 777+):
+#: 84 and 87 are the ASCII codes of ``T`` and ``W``, for termwright.
+MARKER_OSC_CODE = 8487
+
+#: The tag opening a marker payload, immediately after ``OSC 8487;``. Kept as a
+#: self-identifying guard: if anything ever claims 8487, a marker still says
+#: what it is instead of being mistaken for that feature's payload.
+MARKER_OSC_PREFIX = "twm;"
+
+#: The terminator this implementation emits — the one ConPTY was observed to
+#: forward most reliably.
+BEL = "\x07"
+
+#: The terminator a receiver must also accept.
+ST = "\x1b\\"
+MARKER_MAC_BYTES = 16
+MARKER_MAC_CHARS = 22
+
+_MAX_SAFE_INTEGER = 2**53 - 1
+
+_REVISION_TEXT = re.compile(r"^[1-9][0-9]{0,15}$")
+_MAC_TEXT = re.compile(r"^[A-Za-z0-9_-]{%d}$" % MARKER_MAC_CHARS)
+
+
+@dataclass(frozen=True)
+class RenderMarker:
+    """A verified marker: the revision it commits and the MAC that proved it."""
+
+    revision: int
+    mac: str
+
+
+def compute_mac(token: str, session_id: str, revision: int) -> str:
+    """Return the unpadded base64url MAC bound to ``session_id`` and ``revision``."""
+    digest = hmac.new(
+        token.encode("utf-8"), f"{session_id}:{revision}".encode("utf-8"), sha256
+    ).digest()
+    return base64.urlsafe_b64encode(digest[:MARKER_MAC_BYTES]).decode("ascii").rstrip("=")
+
+
+def encode_marker(token: str, session_id: str, revision: int) -> str:
+    """Build the full escape sequence committing ``revision``.
+
+    :raises ProtocolViolation: On an empty token/session id or a revision that
+        is not a positive safe integer.
+    """
+    if not token:
+        raise ProtocolViolation("marker-argument", "token must not be empty")
+    if not session_id:
+        raise ProtocolViolation("marker-argument", "sessionId must not be empty")
+    if isinstance(revision, bool) or not isinstance(revision, int):
+        raise ProtocolViolation("marker-argument", "revision must be a positive safe integer")
+    if revision <= 0 or revision > _MAX_SAFE_INTEGER:
+        raise ProtocolViolation("marker-argument", "revision must be a positive safe integer")
+    mac = compute_mac(token, session_id, revision)
+    return f"\x1b]{MARKER_OSC_CODE};{MARKER_OSC_PREFIX}{revision};{mac}{BEL}"
+
+
+def verify_marker_payload(payload: str, token: str, session_id: str) -> Optional[RenderMarker]:
+    """Parse and verify an OSC payload — everything after ``OSC 8487;``.
+
+    Total function: hostile payloads return ``None``, never raise. Only
+    canonically formatted revisions are accepted, so ``1`` and ``01`` cannot
+    both authenticate the same commit, and the MAC compare is constant-time.
+
+    A trailing BEL or ST is tolerated: a VT parser consumes the terminator
+    before dispatching, so a handler normally passes a payload without one,
+    while a caller scanning raw output with a regex keeps it. Both must work.
+    """
+    if not token or not session_id:
+        return None
+
+    text = payload
+    if text.endswith(BEL):
+        text = text[: -len(BEL)]
+    elif text.endswith(ST):
+        text = text[: -len(ST)]
+
+    if not text.startswith(MARKER_OSC_PREFIX):
+        return None
+
+    body = text[len(MARKER_OSC_PREFIX) :]
+    separator = body.find(";")
+    if separator < 0:
+        return None
+
+    revision_text = body[:separator]
+    mac = body[separator + 1 :]
+    if not _REVISION_TEXT.match(revision_text) or not _MAC_TEXT.match(mac):
+        return None
+
+    revision = int(revision_text)
+    if revision <= 0 or revision > _MAX_SAFE_INTEGER:
+        return None
+    if not hmac.compare_digest(compute_mac(token, session_id, revision), mac):
+        return None
+    return RenderMarker(revision=revision, mac=mac)