tlgr-cli 2.0.1__py3-none-any.whl

tlgr/transport/ndjson.py

@@ -0,0 +1,44 @@
+"""NDJSON framing — bytes in, bytes out, one object per line.
+
+Kept separate from the client because both ends need it and because framing
+bugs are easier to see when the framing is thirty lines with no sockets in it.
+
+Two invariants:
+
+* a frame is written as compact UTF-8 JSON followed by `\\n`, and never
+  contains a raw newline (msgspec's encoder escapes them), so a reader can
+  split on `\\n` without a state machine;
+* the reader works on **bytes**. Decoding the stream to `str` first is how v1
+  corrupted a Persian message split across two TCP reads.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator
+from typing import Any
+
+import msgspec
+
+__all__ = ["dump_frame", "iter_frames", "parse_frame"]
+
+
+def dump_frame(value: Any) -> bytes:
+    """Encode one frame, newline-terminated."""
+    return msgspec.json.encode(value) + b"\n"
+
+
+def parse_frame(line: bytes) -> dict[str, Any]:
+    """Decode one frame. A frame that is not a JSON object is a protocol error."""
+    decoded = msgspec.json.decode(line)
+    if not isinstance(decoded, dict):
+        raise msgspec.DecodeError("NDJSON frame is not an object")
+    return decoded
+
+
+def iter_frames(lines: Iterable[bytes]) -> Iterator[dict[str, Any]]:
+    """Decode a stream of lines, skipping the blank ones a flush can produce."""
+    for line in lines:
+        stripped = line.strip()
+        if not stripped:
+            continue
+        yield parse_frame(stripped)

tlgr/version.py

@@ -0,0 +1,31 @@
+"""Version and protocol constants — the numbers the handshake compares.
+
+`VERSION` is the human-facing release. `PROTOCOL` is the wire contract of
+§5: it changes when a field's meaning changes, not when a version does, and
+it is what the CLI and the daemon actually compare. `MIN_DAEMON_PROTOCOL` is
+the oldest daemon this CLI will talk to rather than restart.
+"""
+
+from __future__ import annotations
+
+from tlgr import __version__
+
+VERSION = __version__
+PROTOCOL = 2
+MIN_DAEMON_PROTOCOL = 2
+
+#: The header names the two ends agree on (§5.1).
+HEADER_CLIENT = "X-Tlgr-Client"
+HEADER_PROTOCOL = "X-Tlgr-Protocol"
+HEADER_REQUEST_ID = "X-Request-Id"
+HEADER_TOKEN = "X-Tlgr-Token"
+
+__all__ = [
+    "HEADER_CLIENT",
+    "HEADER_PROTOCOL",
+    "HEADER_REQUEST_ID",
+    "HEADER_TOKEN",
+    "MIN_DAEMON_PROTOCOL",
+    "PROTOCOL",
+    "VERSION",
+]