tlgr-cli 2.0.1__py3-none-any.whl

tlgr/daemon/transfers.py

@@ -0,0 +1,219 @@
+"""The Downloads panel: transfers the daemon is running, or just ran.
+
+There is no server-side list of a user's transfers, in tlgr or in any official
+client — the GUI's Downloads section is client-local state too. What the
+daemon adds over "just await the coroutine" is the three things a long
+transfer needs and a request/response cycle cannot give it:
+
+* **a name for it while it runs.** `--background` returns a job id
+  immediately, and `media transfer list` is how you find out how far it got.
+* **cancellation between chunks.** A download stops cleanly and keeps its
+  `.part` file, so `--resume` continues it; an upload cannot be resumed at
+  all (saved parts expire server-side), so it restarts with a fresh file id.
+* **a retry that re-fetches first.** A transfer that sat in the failed queue
+  for an hour is holding an expired `file_reference`; retrying with the stale
+  one fails identically, so the factory is re-run rather than the task.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import secrets
+import time
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+log = logging.getLogger("tlgr.daemon.transfers")
+
+__all__ = ["TransferRecord", "TransferStore"]
+
+#: How many finished transfers stay visible. The panel is a recent history,
+#: not an archive; keeping every transfer forever would make the daemon's
+#: memory a function of how much the user has ever downloaded.
+KEEP_FINISHED = 100
+
+
+@dataclass
+class TransferRecord:
+    job_id: str
+    direction: str
+    name: str = ""
+    chat_id: int | None = None
+    msg_id: int | None = None
+    bytes_done: int = 0
+    bytes_total: int = 0
+    state: str = "queued"
+    path: str | None = None
+    error: str | None = None
+    started: float = field(default_factory=time.monotonic)
+    started_at: str = ""
+    task: asyncio.Task[Any] | None = None
+    factory: Callable[[], Awaitable[Any]] | None = None
+    result: Any = None
+
+    @property
+    def pct(self) -> float:
+        if not self.bytes_total:
+            return 0.0
+        return round(100.0 * self.bytes_done / self.bytes_total, 1)
+
+    @property
+    def bps(self) -> int:
+        elapsed = max(1e-6, time.monotonic() - self.started)
+        return int(self.bytes_done / elapsed)
+
+    @property
+    def eta_s(self) -> int | None:
+        rate = self.bps
+        if not rate or not self.bytes_total or self.bytes_done >= self.bytes_total:
+            return None
+        return int((self.bytes_total - self.bytes_done) / rate)
+
+    def progress(self, done: int, total: int) -> None:
+        self.bytes_done = done
+        self.bytes_total = total or self.bytes_total
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "job_id": self.job_id,
+            "direction": self.direction,
+            "chat_id": self.chat_id,
+            "msg_id": self.msg_id,
+            "name": self.name,
+            "bytes_done": self.bytes_done,
+            "bytes_total": self.bytes_total,
+            "pct": self.pct,
+            "bps": self.bps,
+            "eta_s": self.eta_s,
+            "state": self.state,
+            "path": self.path,
+            "error": self.error,
+            "started": self.started_at or None,
+        }
+
+
+class TransferStore:
+    """Every transfer this daemon started, keyed by job id."""
+
+    def __init__(self) -> None:
+        self._records: dict[str, TransferRecord] = {}
+
+    # -- writing -----------------------------------------------------------
+
+    def submit(
+        self,
+        *,
+        direction: str,
+        name: str,
+        factory: Callable[[], Awaitable[Any]],
+        chat_id: int | None = None,
+        msg_id: int | None = None,
+    ) -> TransferRecord:
+        """Register a transfer and start it in the background."""
+        from datetime import datetime, timezone
+
+        record = TransferRecord(
+            job_id=secrets.token_hex(3),
+            direction=direction,
+            name=name,
+            chat_id=chat_id,
+            msg_id=msg_id,
+            factory=factory,
+            started_at=datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        )
+        self._records[record.job_id] = record
+        self._start(record)
+        self._trim()
+        return record
+
+    def _start(self, record: TransferRecord) -> None:
+        record.state = "running"
+        record.error = None
+        record.started = time.monotonic()
+
+        async def run() -> None:
+            try:
+                record.result = await record.factory()  # type: ignore[misc]
+            except asyncio.CancelledError:
+                record.state = "cancelled"
+                raise
+            except Exception as exc:
+                record.state = "failed"
+                record.error = f"{type(exc).__name__}: {exc}"
+                log.warning("transfer %s failed: %s", record.job_id, exc)
+            else:
+                record.state = "done"
+                path = getattr(record.result, "path", None)
+                if isinstance(path, str):
+                    record.path = path
+
+        record.task = asyncio.get_event_loop().create_task(run(), name=f"tlgr-tx-{record.job_id}")
+
+    def _trim(self) -> None:
+        finished = [r for r in self._records.values() if r.state in ("done", "failed", "cancelled")]
+        for record in sorted(finished, key=lambda r: r.started)[:-KEEP_FINISHED]:
+            self._records.pop(record.job_id, None)
+
+    async def cancel(self, job_ids: list[str], *, keep_partial: bool = True) -> int:
+        """Stop the named transfers, and forget their `.part` when asked to."""
+        cancelled = 0
+        for job_id in job_ids:
+            record = self._records.get(job_id)
+            if record is None or record.state not in ("queued", "running"):
+                continue
+            if record.task is not None:
+                record.task.cancel()
+                with contextlib.suppress(asyncio.CancelledError, Exception):
+                    await record.task
+            record.state = "cancelled"
+            cancelled += 1
+            if not keep_partial and record.path:
+                from pathlib import Path
+
+                with contextlib.suppress(OSError):
+                    Path(record.path + ".part").unlink()
+        return cancelled
+
+    def retry(self, job_ids: list[str], *, from_scratch: bool = False) -> tuple[int, int]:
+        """Re-run the factory, which re-fetches the source before it reads bytes."""
+        restarted = 0
+        resumed_from = 0
+        for job_id in job_ids:
+            record = self._records.get(job_id)
+            if record is None or record.factory is None:
+                continue
+            if record.state in ("queued", "running"):
+                continue
+            resumed_from = max(resumed_from, 0 if from_scratch else record.bytes_done)
+            record.bytes_done = 0 if from_scratch else record.bytes_done
+            self._start(record)
+            restarted += 1
+        return restarted, resumed_from
+
+    # -- reading -----------------------------------------------------------
+
+    def get(self, job_id: str) -> TransferRecord | None:
+        return self._records.get(job_id)
+
+    def snapshot(self, *, active: bool = False, failed: bool = False) -> list[dict[str, Any]]:
+        records = list(self._records.values())
+        if active:
+            records = [r for r in records if r.state in ("queued", "running")]
+        if failed:
+            records = [r for r in records if r.state == "failed"]
+        return [record.to_dict() for record in sorted(records, key=lambda r: -r.started)]
+
+    async def settle(self, *, timeout: float = 30.0) -> None:
+        """Wait for the running transfers, so `--watch` can report the end."""
+        tasks = [r.task for r in self._records.values() if r.task is not None and not r.task.done()]
+        if not tasks:
+            return
+        with contextlib.suppress(TimeoutError, asyncio.TimeoutError, Exception):
+            await asyncio.wait_for(asyncio.gather(*tasks, return_exceptions=True), timeout)
+
+    async def stop_all(self) -> None:
+        """Cancel everything still running, at shutdown."""
+        await self.cancel([r.job_id for r in self._records.values()], keep_partial=True)

tlgr/daemon/webhook.py

@@ -0,0 +1,390 @@
+"""Outbound webhook delivery — a bus subscriber, not an update handler.
+
+Four things were wrong with v1 and all four are structural:
+
+* **COR-07.** The payload was built with `json.dumps(..., default=str)` over
+  a raw Telethon `to_dict()`. A `datetime` became a string in one place and a
+  `bytes` blew up in another, so a message with media could fail to serialise
+  *at delivery time*, be counted as a delivery failure, and be retried three
+  times before being dead-lettered. Payloads are now models encoded with
+  msgspec, and a serialisation failure is logged as a bug — never retried.
+* **ROB-02.** The POST happened inside the Telethon handler. One unreachable
+  endpoint with three retries and exponential backoff held the update loop for
+  ~97 s, during which every account was deaf. Delivery now happens on the
+  bus's worker lanes, behind a bounded queue.
+* **SEC-08.** There was no signature: any process that learned the URL could
+  forge events. Every delivery now carries `X-Tlgr-Signature: sha256=<hmac of
+  the exact body>` and a monotonic `seq`, so a receiver can both authenticate
+  and order what it gets.
+* **SEC-06.** Dead letters were appended to a world-readable file that grew
+  forever, with full message text in it. They are 0600, rotated, and capped.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import logging
+import os
+import random
+import time
+import uuid
+from pathlib import Path
+from typing import Any
+
+import msgspec
+
+from tlgr.core.config import CONFIG_DIR, WebhookConfig
+from tlgr.core.paths import write_private
+from tlgr.core.signing import sign_body
+from tlgr.models.event import EventEnvelope
+
+log = logging.getLogger("tlgr.webhook")
+
+__all__ = ["WebhookPusher", "sign_body"]
+
+DEAD_LETTER_FILE = CONFIG_DIR / "dead_letter.jsonl"
+
+#: 16 MB across four files is enough to diagnose an outage and small enough
+#: that an endpoint that has been down for a week cannot fill a disk.
+_DEAD_LETTER_MAX_BYTES = 16 * 1024 * 1024
+_DEAD_LETTER_BACKUPS = 3
+
+
+class WebhookPusher:
+    """Bounded queue + worker pool + HMAC + dead letter."""
+
+    def __init__(self, config: WebhookConfig, base: Path | None = None) -> None:
+        self.config = config
+        self.base = Path(base) if base is not None else CONFIG_DIR
+        self._session: Any = None
+        self._resolved_chat_ids: set[int] = set()
+        self._dead_letter_path = self.base / "dead_letter.jsonl"
+        self._queue: asyncio.Queue[tuple[bytes, dict[str, str]]] | None = None
+        self._workers: list[asyncio.Task[None]] = []
+        self._filter_node: Any = None
+        self.delivered = 0
+        self.failed = 0
+        self.dead_letters = 0
+        self.dropped = 0
+        if config.filters.raw:
+            from tlgr.filters.compose import parse_filter_config
+
+            self._filter_node = parse_filter_config(config.filters.raw)
+
+    # -- lifecycle ---------------------------------------------------------
+
+    async def start(self) -> None:
+        if not self.config.enabled:
+            return
+        import aiohttp
+
+        self._session = aiohttp.ClientSession()
+        self._queue = asyncio.Queue(maxsize=max(16, self.config.queue_size))
+        self._workers = [
+            asyncio.create_task(self._worker(), name=f"tlgr-webhook-{index}")
+            for index in range(max(1, self.config.workers))
+        ]
+        if self.config.url.startswith("http://") and not _is_loopback(self.config.url):
+            log.warning(
+                "webhook URL is plain http:// to a non-loopback host; "
+                "event payloads and the signature travel in clear text",
+            )
+        log.info("webhook pusher started")
+
+    async def stop(self, *, drain: float = 10.0) -> None:
+        """Flush what we can, dead-letter the rest (§6.11 step 4)."""
+        if self._queue is not None:
+            deadline = time.monotonic() + drain
+            while not self._queue.empty() and time.monotonic() < deadline:
+                await asyncio.sleep(0.05)
+            while not self._queue.empty():
+                body, headers = self._queue.get_nowait()
+                self._dead_letter(body, headers, "daemon shutting down")
+        for worker in self._workers:
+            worker.cancel()
+        for worker in self._workers:
+            with contextlib.suppress(asyncio.CancelledError, Exception):
+                await worker
+        self._workers = []
+        if self._session is not None:
+            await self._session.close()
+            self._session = None
+
+    # -- filtering ---------------------------------------------------------
+
+    def set_resolved_chats(self, chat_ids: set[int]) -> None:
+        self._resolved_chat_ids = chat_ids
+
+    def should_push(
+        self, event_type: str, chat_id: int | None = None, tg_event: Any = None
+    ) -> bool:
+        if not self.config.enabled:
+            return False
+        if event_type not in self.config.events:
+            return False
+        if self.config.filters.chats and chat_id is not None:
+            if chat_id not in self._resolved_chat_ids:
+                return False
+        if self._filter_node is not None and tg_event is not None:
+            from tlgr.filters.compose import evaluate
+            from tlgr.gateway.event import Event
+
+            envelope = Event(source="telegram", raw=tg_event, event_type=event_type)
+            ok, _ = evaluate(self._filter_node, envelope)
+            if not ok:
+                return False
+        return True
+
+    # -- the bus handler ---------------------------------------------------
+
+    async def on_event(self, event: EventEnvelope, raw: Any = None) -> None:
+        """The bus handler. Encodes, signs and enqueues; never sends inline."""
+        if not self.should_push(event.type, event.chat_id, raw):
+            return
+        self.enqueue(event)
+
+    def enqueue(self, event: EventEnvelope) -> None:
+        delivery_id = uuid.uuid4().hex
+        try:
+            body = msgspec.json.encode({"event": event, "delivery_id": delivery_id})
+        except (TypeError, msgspec.EncodeError) as exc:
+            # A payload we cannot encode is a *bug in tlgr*, not a delivery
+            # failure: retrying it three times and dead-lettering it hides the
+            # defect behind an endpoint that looks flaky (COR-07).
+            log.error(
+                "BUG: webhook payload for %s could not be encoded (%s): %s",
+                event.type,
+                type(exc).__name__,
+                exc,
+                extra={"event_type": event.type, "account": event.account},
+            )
+            return
+
+        headers = {
+            "Content-Type": "application/json",
+            "X-Tlgr-Delivery": delivery_id,
+            "X-Tlgr-Seq": str(event.seq),
+            "X-Tlgr-Event": event.type,
+            "X-Tlgr-Account": event.account,
+        }
+        secret = self.config.signing_key
+        if secret:
+            headers["X-Tlgr-Signature"] = sign_body(secret, body)
+        if self.config.token:
+            headers["Authorization"] = f"Bearer {self.config.token}"
+
+        if self._queue is None:
+            self._dead_letter(body, headers, "webhook is not running")
+            return
+        try:
+            self._queue.put_nowait((body, headers))
+        except asyncio.QueueFull:
+            self.dropped += 1
+            self._dead_letter(body, headers, "webhook queue is full")
+
+    # -- delivery ----------------------------------------------------------
+
+    async def _worker(self) -> None:
+        assert self._queue is not None
+        while True:
+            body, headers = await self._queue.get()
+            await self._deliver(body, headers)
+
+    async def _deliver(self, body: bytes, headers: dict[str, str]) -> None:
+        import aiohttp
+
+        retry = self.config.retry
+        attempts = retry.max_attempts if retry.enabled else 1
+        last = ""
+        for attempt in range(attempts):
+            try:
+                assert self._session is not None
+                async with self._session.post(
+                    self.config.url,
+                    data=body,
+                    headers=headers,
+                    timeout=aiohttp.ClientTimeout(total=self.config.timeout),
+                ) as response:
+                    if response.status < 400:
+                        self.delivered += 1
+                        return
+                    last = f"HTTP {response.status}"
+            except asyncio.CancelledError:
+                raise
+            except Exception as exc:
+                last = f"{type(exc).__name__}: {exc}"
+            self.failed += 1
+            if attempt + 1 < attempts:
+                # Jittered, so a restarted endpoint is not hit by every
+                # pending delivery in the same millisecond.
+                delay = (retry.backoff_base**attempt) * (1.0 + random.uniform(-0.2, 0.2))
+                await asyncio.sleep(delay)
+        self._dead_letter(body, headers, last or "delivery failed")
+
+    # -- dead letters ------------------------------------------------------
+
+    def _dead_letter(self, body: bytes, headers: dict[str, str], reason: str) -> None:
+        self.dead_letters += 1
+        now = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+        record = {
+            "ts": now,
+            "reason": reason,
+            # `source` names the consumer that failed. One store is shared by
+            # the pusher and the gateway actions, and an operator draining it
+            # has to be able to re-drive one without the other.
+            "source": "webhook",
+            "attempts": max(1, self.config.retry.max_attempts if self.config.retry.enabled else 1),
+            "first_failed_at": now,
+            "delivery_id": headers.get("X-Tlgr-Delivery", ""),
+            "seq": headers.get("X-Tlgr-Seq", ""),
+            "event": headers.get("X-Tlgr-Event", ""),
+            "account": headers.get("X-Tlgr-Account", ""),
+            "body": body.decode("utf-8", errors="replace"),
+        }
+        try:
+            self._rotate_if_needed()
+            path = self._dead_letter_path
+            if not path.exists():
+                write_private(path, "")
+            with open(os.open(str(path), os.O_WRONLY | os.O_APPEND | os.O_CREAT, 0o600), "a") as fh:
+                fh.write(json.dumps(record, ensure_ascii=False) + "\n")
+        except OSError as exc:
+            log.error("could not write a dead letter: %s", exc)
+
+    def _rotate_if_needed(self) -> None:
+        path = self._dead_letter_path
+        try:
+            if not path.exists() or path.stat().st_size < _DEAD_LETTER_MAX_BYTES:
+                return
+        except OSError:
+            return
+        for index in range(_DEAD_LETTER_BACKUPS, 0, -1):
+            older = path.with_suffix(path.suffix + f".{index}")
+            newer = path if index == 1 else path.with_suffix(path.suffix + f".{index - 1}")
+            if newer.exists():
+                with contextlib.suppress(OSError):
+                    newer.replace(older)
+        with contextlib.suppress(OSError):
+            write_private(path, "")
+
+    def read_dead_letters(self) -> list[dict[str, Any]]:
+        if not self._dead_letter_path.exists():
+            return []
+        entries: list[dict[str, Any]] = []
+        for line in self._dead_letter_path.read_text(errors="replace").splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                entries.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue
+        return entries
+
+    @property
+    def dead_letter_path(self) -> Path:
+        return self._dead_letter_path
+
+    def write_dead_letters(self, entries: list[dict[str, Any]]) -> None:
+        """Replace the store. Private mode, one write, no partial file."""
+        body = "".join(json.dumps(entry, ensure_ascii=False) + "\n" for entry in entries)
+        write_private(self._dead_letter_path, body)
+        self.dead_letters = len(entries)
+
+    async def deliver_once(self, entry: dict[str, Any], *, url: str = "") -> tuple[bool, str]:
+        """One delivery attempt for a stored entry. Returns `(ok, error)`.
+
+        Re-delivery reuses the original `X-Tlgr-Delivery` id, so a receiver
+        keyed on it sees a duplicate rather than a new event — which is the
+        difference between a safe replay and a double-processed message.
+        """
+        import aiohttp
+
+        target = url or self.config.url
+        if not target:
+            return False, "no webhook URL is configured"
+        body = str(entry.get("body", "")).encode("utf-8")
+        headers = {
+            "Content-Type": "application/json",
+            "X-Tlgr-Delivery": str(entry.get("delivery_id", "")),
+            "X-Tlgr-Seq": str(entry.get("seq", "")),
+            "X-Tlgr-Event": str(entry.get("event", "")),
+            "X-Tlgr-Account": str(entry.get("account", "")),
+            "X-Tlgr-Redelivery": "1",
+        }
+        secret = self.config.signing_key
+        if secret:
+            headers["X-Tlgr-Signature"] = sign_body(secret, body)
+        if self.config.token:
+            headers["Authorization"] = f"Bearer {self.config.token}"
+        session = self._session
+        close_after = session is None
+        if session is None:
+            session = aiohttp.ClientSession()
+        try:
+            async with session.post(
+                target,
+                data=body,
+                headers=headers,
+                timeout=aiohttp.ClientTimeout(total=self.config.timeout),
+            ) as response:
+                if response.status < 400:
+                    self.delivered += 1
+                    return True, ""
+                return False, f"HTTP {response.status}"
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            return False, f"{type(exc).__name__}: {exc}"
+        finally:
+            if close_after:
+                await session.close()
+
+    def purge_dead_letters(self) -> int:
+        if not self._dead_letter_path.exists():
+            return 0
+        count = len(self.read_dead_letters())
+        self._dead_letter_path.unlink(missing_ok=True)
+        self.dead_letters = 0
+        return count
+
+    # -- v1 compatibility --------------------------------------------------
+
+    async def push(self, event_type: str, data: dict[str, Any], account: str = "") -> None:
+        """v1's entry point, kept for the gateway jobs that still call it.
+
+        It builds an envelope and hands it to the same queue, so a legacy
+        caller gets the signature, the bounded queue and the dead-letter
+        handling without being rewritten.
+        """
+        if not self.config.enabled:
+            return
+        self.enqueue(
+            EventEnvelope(
+                seq=0,
+                ts=time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+                account=account,
+                type=event_type,
+                payload=data,
+                chat_id=data.get("chat_id") if isinstance(data, dict) else None,
+            )
+        )
+
+    def snapshot(self) -> dict[str, Any]:
+        return {
+            "enabled": self.config.enabled,
+            "queued": self._queue.qsize() if self._queue is not None else 0,
+            "delivered": self.delivered,
+            "failed": self.failed,
+            "dead_letters": self.dead_letters,
+            "dropped": self.dropped,
+        }
+
+
+def _is_loopback(url: str) -> bool:
+    from urllib.parse import urlparse
+
+    host = (urlparse(url).hostname or "").lower()
+    return host in ("localhost", "127.0.0.1", "::1")