tan-cli 0.7.0__py3-none-any.whl

tan/core/serial_capture.py

@@ -0,0 +1,185 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Headless serial capture: pure logic for `tan monitor --capture`
+(tan-cli#1324).
+
+Reads from an already-open port-like object (`read(size) -> bytes`, optional
+`in_waiting`) for a fixed duration or until a regex matches, optionally
+teeing the raw bytes to a binary sink. No TTY, no miniterm, no port opening;
+the caller owns the port and the sink. The clock is injected so the timing is
+testable without sleeping.
+
+`--until` semantics: the regex is searched in every COMPLETE line (CR/LF
+stripped) exactly once, and in the current UNTERMINATED line (so a prompt such
+as `=> ` matches before any newline arrives), at most the last
+`MAX_SEARCH_CHARS` of it per read. Long complete lines are searched on their
+LAST `MAX_SEARCH_CHARS` too, the same window as the partial line. The deadline is checked between lines, so a
+read that delivers thousands of lines cannot overrun `--duration`. Python's
+`re` cannot be interrupted, so a pathological (catastrophic-backtracking)
+pattern can still stall inside ONE search; the cap on the searched text and
+the per-line deadline check bound the damage, they do not remove it.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, BinaryIO, Protocol
+
+if TYPE_CHECKING:
+    from tan.core.serial_actions import CaptureActions
+
+TAIL_BYTES = 256
+#: No single `re.search` is given more than this many characters.
+MAX_SEARCH_CHARS = 4096
+#: A partial (unterminated) line longer than this is truncated from the left
+#: so a binary stream with no newline cannot grow memory without bound.
+_MAX_PENDING = 65536
+#: Duration used when `--until` is given without `--duration`.
+DEFAULT_UNTIL_DURATION_S = 30.0
+
+
+class ReadPort(Protocol):
+    def read(self, size: int = 1, /) -> bytes: ...
+
+
+class SinkError(Exception):
+    """Writing the log failed (kept apart from serial I/O errors)."""
+
+
+@dataclass(frozen=True)
+class CaptureResult:
+    matched: bool
+    matched_line: str | None
+    elapsed_s: float
+    bytes_seen: int
+    tail: str
+
+
+def compile_until(pattern: str) -> re.Pattern[str]:
+    """Compile `--until`; `ValueError` (with the regex error) if malformed or
+    empty, so the caller can map it to one validation issue."""
+    if not pattern:
+        raise ValueError("--until must not be empty")
+    try:
+        return re.compile(pattern)
+    except re.error as err:
+        raise ValueError(f"--until is not a valid regex: {err}") from err
+
+
+def _text(b: bytes) -> str:
+    return b.decode("utf-8", errors="replace")
+
+
+def _tail_text(buf: bytes) -> str:
+    if len(buf) > TAIL_BYTES:
+        buf = buf[-TAIL_BYTES:]
+        while buf and 0x80 <= buf[0] < 0xC0:  # do not start mid-character
+            buf = buf[1:]
+    return _text(buf)
+
+
+def capture(
+    port: ReadPort,
+    *,
+    duration_s: float,
+    until: re.Pattern[str] | None = None,
+    sink: BinaryIO | None = None,
+    initial: bytes = b"",
+    clock: Callable[[], float] = time.monotonic,
+    actions: "CaptureActions | None" = None,
+) -> CaptureResult:
+    """Read until `until` matches, or `duration_s` elapses.
+
+    On a match the capture stops at the end of the matched line: the rest of
+    the same read is not logged or counted. `initial` is data already received before this call (the `--break-uboot`
+    tail): it is logged and searched like any other chunk, so a prompt that
+    ended the break-in can satisfy `--until`. At least one read happens even
+    with a zero duration. A sink failure raises `SinkError`; a port failure
+    propagates as the port's own `OSError`.
+
+    `actions` (tan-cli#1451, `tan.core.serial_actions`): ticked every loop
+    iteration and offered each complete line and the current partial line
+    BEFORE `until` is tested. A reopen replaces the port, so the loop reads
+    `actions.port` rather than `port` when given. Lines are scanned when
+    either `until` or a line-triggered action is present.
+    """
+    start = clock()
+    deadline = start + duration_s
+    pending = b""
+    tail = b""
+    seen = 0
+    first = True
+
+    def commit(part: bytes) -> None:
+        """Count, tail and log `part`: what the capture reports as received."""
+        nonlocal seen, tail
+        seen += len(part)
+        tail = (tail + part)[-TAIL_BYTES:]
+        if sink is not None and part:
+            try:
+                sink.write(part)
+                sink.flush()
+            except OSError as err:
+                raise SinkError(str(err)) from err
+
+    def done(matched: bool, line: str | None) -> CaptureResult:
+        return CaptureResult(matched, line, clock() - start, seen, _tail_text(tail))
+
+    while True:
+        if first and initial:
+            chunk = initial
+        else:
+            if actions is not None:
+                actions.tick()
+            src = actions.port if actions is not None else port
+            n = max(1, int(getattr(src, "in_waiting", 0) or 0))
+            chunk = src.read(n) or b""
+        first = False
+        scan = until is not None or (actions is not None and actions.spec.watches_lines)
+        if chunk and not scan:
+            commit(chunk)
+        elif chunk:
+            before = len(pending)
+            *lines, pending = (pending + chunk).split(b"\n")
+            pending = pending[-_MAX_PENDING:]
+            # A read that returns at or after the deadline is still searched
+            # whole (tan-cli#1515). Its size is bounded by `in_waiting` (and
+            # each line by MAX_SEARCH_CHARS), so it needs no flood guard. Only
+            # scanning that itself overruns the deadline stops, and then only
+            # the lines already searched are committed, so the log never holds
+            # a line the result says was not searched.
+            late = clock() >= deadline
+            end = -before  # offset of the current line's end within `chunk`
+            for raw in lines:  # each complete line is new data: search it once
+                end += len(raw) + 1
+                line = _text(raw).rstrip("\r")[-MAX_SEARCH_CHARS:]
+                if actions is not None:
+                    actions.line(line)
+                if until is not None and until.search(line):
+                    # Stop at the END OF THE MATCHED LINE: bytes after it in the
+                    # same read are neither logged nor reported.
+                    commit(chunk[: max(0, end)])
+                    return done(True, line)
+                if not late and clock() >= deadline:
+                    commit(chunk[: max(0, end)])
+                    return done(False, None)
+                if actions is not None and actions.take_flush():
+                    # Baud changed: the rest of this read and the partial line
+                    # are old-baud garbage; keep only up to the matched line.
+                    commit(chunk[: max(0, end)])
+                    pending, flushed = b"", True
+                    break
+            else:
+                flushed = False
+            if flushed:
+                continue
+            commit(chunk)
+            partial = _text(pending).rstrip("\r")[-MAX_SEARCH_CHARS:]
+            if partial and actions is not None:
+                actions.line(partial, partial=True)
+            if partial and until is not None and until.search(partial):
+                return done(True, partial)
+        if clock() >= deadline:
+            return done(False, None)

tan/core/serial_url.py

@@ -0,0 +1,45 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Up-front validation of a `--port` that is a pyserial URL (tan-cli#1448).
+
+`rfc2217://100.64.0.1:` (an empty port number) used to reach pyserial, which
+failed deep inside with `'<=' not supported between instances of 'int' and
+'NoneType'`, reported as `monitor.capture-open-failed`. This names the problem
+instead. A plain device path (no `://`) is not a URL and is never judged here.
+"""
+from __future__ import annotations
+
+from urllib.parse import urlsplit
+
+#: pyserial's `serial.urlhandler` schemes (3.5). A scheme outside this set is
+#: refused rather than handed to pyserial to fail obscurely.
+KNOWN_SCHEMES = frozenset({"alt", "cp2110", "hwgrep", "loop", "rfc2217", "socket", "spy"})
+#: The schemes that name a TCP endpoint and so need `host:port`.
+NETWORK_SCHEMES = frozenset({"rfc2217", "socket"})
+
+
+def port_url_problem(port: str) -> str | None:
+    """What is wrong with `port` as a serial URL, or `None` if it is fine or not a URL."""
+    if "://" not in port:
+        return None
+    scheme = port.split("://", 1)[0].lower()
+    if scheme not in KNOWN_SCHEMES:
+        return (
+            f"unknown serial URL scheme '{scheme}://' in '{port}' "
+            f"(known: {', '.join(sorted(s + '://' for s in KNOWN_SCHEMES))})"
+        )
+    if scheme not in NETWORK_SCHEMES:
+        return None
+    try:
+        parts = urlsplit(port)
+        host, number = parts.hostname, parts.port
+    except ValueError as err:
+        return f"'{port}' is not a valid {scheme}:// URL: {err}"
+    if not host:
+        return f"'{port}' has no host; use {scheme}://HOST:PORT"
+    if number is None:
+        netloc = parts.netloc
+        why = "the port number is empty" if netloc.endswith(":") else "the port number is missing"
+        return f"'{port}': {why}; use {scheme}://{host}:PORT (1-65535)"
+    if not 1 <= number <= 65535:
+        return f"'{port}': port {number} is outside 1-65535"
+    return None