tlgr-cli 2.0.1__py3-none-any.whl

tlgr/filters/temporal.py

@@ -0,0 +1,87 @@
+"""Time-based filters — date ranges and time-of-day."""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+from tlgr.filters import register_filter
+from tlgr.gateway.event import Event
+
+
+def _parse_date(date_str: str) -> datetime:
+    date_str = date_str.strip()
+    rel = re.match(r"^(\d+)([dwmh])$", date_str.lower())
+    if rel:
+        val, unit = int(rel.group(1)), rel.group(2)
+        now = datetime.now(timezone.utc)
+        deltas = {
+            "h": timedelta(hours=val),
+            "d": timedelta(days=val),
+            "w": timedelta(weeks=val),
+            "m": timedelta(days=val * 30),
+        }
+        return now - deltas[unit]
+    for fmt in ("%Y-%m-%d %H:%M:%S", "%Y-%m-%d %H:%M", "%Y-%m-%d"):
+        try:
+            return datetime.strptime(date_str, fmt).replace(tzinfo=timezone.utc)
+        except ValueError:
+            continue
+    raise ValueError(f"Invalid date: {date_str}")
+
+
+def _msg_date(event: Event) -> datetime | None:
+    if event.source == "telegram":
+        return event.raw.message.date
+    return event.timestamp
+
+
+@register_filter("after")
+def filter_after(event: Event, value: Any) -> tuple[bool, str]:
+    """Message date must be at or after *value*.  Value: date string."""
+    msg_date = _msg_date(event)
+    if msg_date is None:
+        return True, "no date"
+    cutoff = _parse_date(str(value))
+    a = cutoff.replace(tzinfo=timezone.utc) if cutoff.tzinfo is None else cutoff
+    d = msg_date.replace(tzinfo=timezone.utc) if msg_date.tzinfo is None else msg_date
+    if d >= a:
+        return True, "after cutoff"
+    return False, "before cutoff"
+
+
+@register_filter("before")
+def filter_before(event: Event, value: Any) -> tuple[bool, str]:
+    """Message date must be at or before *value*.  Value: date string."""
+    msg_date = _msg_date(event)
+    if msg_date is None:
+        return True, "no date"
+    cutoff = _parse_date(str(value))
+    b = cutoff.replace(tzinfo=timezone.utc) if cutoff.tzinfo is None else cutoff
+    d = msg_date.replace(tzinfo=timezone.utc) if msg_date.tzinfo is None else msg_date
+    if d <= b:
+        return True, "before cutoff"
+    return False, "after cutoff"
+
+
+@register_filter("time_of_day")
+def filter_time_of_day(event: Event, value: Any) -> tuple[bool, str]:
+    """Message time must fall within a range.  Value: ``"HH:MM-HH:MM"``."""
+    msg_date = _msg_date(event)
+    if msg_date is None:
+        return True, "no date"
+    d = msg_date.replace(tzinfo=timezone.utc) if msg_date.tzinfo is None else msg_date
+    current = d.strftime("%H:%M")
+
+    if isinstance(value, str) and "-" in value:
+        start, end = value.split("-", 1)
+        start, end = start.strip(), end.strip()
+        if start <= end:
+            ok = start <= current <= end
+        else:
+            ok = current >= start or current <= end
+        if ok:
+            return True, "time_of_day matched"
+        return False, f"time {current} not in {value}"
+    return False, "time_of_day expects 'HH:MM-HH:MM'"

tlgr/filters/user.py

@@ -0,0 +1,36 @@
+"""Sender/user filters — allow-list and block-list by user ID."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from tlgr.filters import register_filter
+from tlgr.gateway.event import Event
+
+
+def _sender_id(event: Event) -> int | None:
+    if event.source == "telegram":
+        return event.raw.message.sender_id
+    if isinstance(event.raw, dict):
+        return event.raw.get("sender_id")
+    return None
+
+
+@register_filter("from_users")
+def filter_from_users(event: Event, value: Any) -> tuple[bool, str]:
+    """Sender must be in the given list of user IDs.  Value: list[int]."""
+    sid = _sender_id(event)
+    allowed = value if isinstance(value, list) else [value]
+    if sid in allowed:
+        return True, "sender allowed"
+    return False, "sender not allowed"
+
+
+@register_filter("exclude_users")
+def filter_exclude_users(event: Event, value: Any) -> tuple[bool, str]:
+    """Sender must NOT be in the given list of user IDs.  Value: list[int]."""
+    sid = _sender_id(event)
+    excluded = value if isinstance(value, list) else [value]
+    if sid in excluded:
+        return False, "sender excluded"
+    return True, "sender allowed"

tlgr/gateway/__init__.py

@@ -0,0 +1 @@
+"""Gateway — generic event-driven pipeline engine."""

tlgr/gateway/config.py

@@ -0,0 +1,161 @@
+"""YAML-based job configuration for the Gateway pipeline.
+
+Parses ``~/.tlgr/jobs.yaml`` into :class:`GatewayConfig` objects that the
+:class:`~tlgr.gateway.engine.Gateway` consumes.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from tlgr.core.config import CONFIG_DIR
+from tlgr.core.errors import ConfigurationError
+from tlgr.filters.compose import FilterNode, parse_filter_config
+from tlgr.processors import ProcessorChain, create_chain_from_list
+
+
+@dataclass
+class ActionConfig:
+    """A single action in a job's action list."""
+
+    name: str = ""
+    config: Any = None
+    filters: FilterNode | None = None
+    processors: ProcessorChain | None = None
+
+
+ALL_EVENT_TYPES = frozenset(
+    {
+        "new_message",
+        "message_edited",
+        "message_deleted",
+        "chat_action",
+        "user_joined",
+        "message_read",
+    }
+)
+
+
+@dataclass
+class GatewayConfig:
+    """Parsed configuration for one Gateway job."""
+
+    name: str = ""
+    account: str = ""
+    enabled: bool = True
+    events: list[str] = field(default_factory=lambda: ["new_message"])
+    filters: FilterNode | None = None
+    processors: ProcessorChain | None = None
+    actions: list[ActionConfig] = field(default_factory=list)
+
+
+def _parse_action(raw: dict[str, Any]) -> ActionConfig:
+    """Parse a concise action entry.
+
+    Concise syntax: the action name is the dict key, the value is its config.
+
+    Examples::
+
+        {"reply": "hello"}              -> ActionConfig(name="reply", config="hello")
+        {"forward": {"to": "@chan"}}     -> ActionConfig(name="forward", config={"to": "@chan"})
+    """
+    for key, value in raw.items():
+        ac = ActionConfig(name=key)
+
+        if isinstance(value, str):
+            ac.config = value
+        elif isinstance(value, dict):
+            ac.config = {k: v for k, v in value.items() if k not in ("filters", "processors")}
+            if len(ac.config) == 1 and "text" in ac.config:
+                ac.config = ac.config["text"]
+            ac.filters = parse_filter_config(value.get("filters"))
+            procs = value.get("processors")
+            if procs:
+                ac.processors = create_chain_from_list(procs) if isinstance(procs, list) else None
+        else:
+            ac.config = value
+
+        return ac
+
+    return ActionConfig()
+
+
+def _parse_job(raw: dict[str, Any]) -> GatewayConfig:
+    cfg = GatewayConfig(
+        name=raw.get("name", ""),
+        account=raw.get("account", ""),
+        enabled=raw.get("enabled", True),
+    )
+
+    raw_events = raw.get("events")
+    if raw_events and isinstance(raw_events, list):
+        cfg.events = [str(e) for e in raw_events if str(e) in ALL_EVENT_TYPES]
+    elif raw_events and isinstance(raw_events, str):
+        cfg.events = [raw_events] if raw_events in ALL_EVENT_TYPES else ["new_message"]
+
+    cfg.filters = parse_filter_config(raw.get("filters"))
+
+    procs = raw.get("processors")
+    if procs and isinstance(procs, list):
+        cfg.processors = create_chain_from_list(procs)
+
+    actions_raw = raw.get("actions", [])
+    for action_raw in actions_raw:
+        if isinstance(action_raw, dict):
+            cfg.actions.append(_parse_action(action_raw))
+
+    return cfg
+
+
+def load_gateway_configs(base: Path | None = None) -> list[GatewayConfig]:
+    """Load all gateway jobs from ``jobs.yaml``."""
+    base = base or CONFIG_DIR
+    jobs_path = base / "jobs.yaml"
+    if not jobs_path.exists():
+        return []
+
+    try:
+        import yaml
+    except ModuleNotFoundError as e:
+        raise ConfigurationError(
+            "PyYAML is required for jobs.yaml support. Install with: pip install pyyaml"
+        ) from e
+
+    with open(jobs_path) as f:
+        data = yaml.safe_load(f)
+
+    if not data or "jobs" not in data:
+        return []
+
+    return [_parse_job(j) for j in data["jobs"] if isinstance(j, dict)]
+
+
+def save_gateway_configs(configs: list[GatewayConfig], base: Path | None = None) -> None:
+    """Serialize gateway configs back to ``jobs.yaml`` (minimal round-trip)."""
+    base = base or CONFIG_DIR
+    base.mkdir(parents=True, exist_ok=True)
+    jobs_path = base / "jobs.yaml"
+
+    try:
+        import yaml
+    except ModuleNotFoundError as e:
+        raise ConfigurationError(
+            "PyYAML is required for jobs.yaml support. Install with: pip install pyyaml"
+        ) from e
+
+    jobs_list: list[dict[str, Any]] = []
+    for cfg in configs:
+        d: dict[str, Any] = {"name": cfg.name}
+        if cfg.account:
+            d["account"] = cfg.account
+        if not cfg.enabled:
+            d["enabled"] = False
+        # filters and processors are not round-tripped here;
+        # users edit the YAML directly.
+        jobs_list.append(d)
+
+    with open(jobs_path, "w") as f:
+        yaml.dump({"jobs": jobs_list}, f, default_flow_style=False, sort_keys=False)
+    jobs_path.chmod(0o600)

tlgr/gateway/engine.py

@@ -0,0 +1,215 @@
+"""Gateway engine — generic event-driven pipeline.
+
+    event -> filters -> processors -> actions
+
+Where the events come from changed in v2. A job used to register its own
+Telethon handlers, so a rule whose action posted to a slow endpoint ran
+*inside* the update loop and, with `sequential_updates=True`, made every
+account deaf until it returned (ROB-02). A job now subscribes to the daemon's
+event bus, which runs handlers on bounded worker lanes keyed by chat: per-chat
+order is preserved, the update loop is never blocked, and a job that falls
+behind is bounded rather than unbounded.
+
+The pipeline itself is unchanged, and filters still read the raw Telethon
+event, which is why the bus carries it beside the normalised envelope. The
+full move to model-based filters belongs to the updates group (PR-4).
+
+Without a bus — a unit test, or a daemon that has not started one — the job
+falls back to registering Telethon handlers exactly as v1 did.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+
+from telethon import events
+
+from tlgr.actions import get_action
+from tlgr.filters.compose import evaluate
+from tlgr.gateway.config import ActionConfig, GatewayConfig
+from tlgr.gateway.event import Event
+from tlgr.jobs.base import BaseJob
+from tlgr.jobs.client import JobClient
+
+log = logging.getLogger("tlgr.gateway")
+
+
+class _GatewayJobConfig:
+    """Minimal shim so Gateway can sit on top of BaseJob.
+
+    BaseJob expects a config object with ``.name``, ``.type``, and
+    ``.enabled`` attributes.
+    """
+
+    def __init__(self, gw: GatewayConfig) -> None:
+        self.name = gw.name
+        self.type = "gateway"
+        self.enabled = gw.enabled
+        self.account = gw.account
+
+
+#: v1's job event names → the bus taxonomy, and back for the pipeline, which
+#: still labels envelopes with v1's names. The expansion is the taxonomy's own
+#: alias table (`core.eventtypes.ALIASES`), so a job and a `watch` accept the
+#: same words; a job may also name any v2 type directly.
+def _bus_types(names: list[str]) -> set[str]:
+    from tlgr.core import eventtypes
+
+    wanted: set[str] = set()
+    for name in names:
+        wanted.update(eventtypes.ALIASES.get(name, (name,)))
+    return wanted
+
+
+_V1_TYPE_MAP = {
+    "message_new": "new_message",
+    "message_edited": "message_edited",
+    "message_deleted": "message_deleted",
+    "message_service": "chat_action",
+    "user_status": "user_joined",
+    "read_inbox": "message_read",
+    "read_outbox": "message_read",
+}
+
+_EVENT_TYPE_MAP = {
+    "new_message": (events.NewMessage, {}),
+    "message_edited": (events.MessageEdited, {}),
+    "message_deleted": (events.MessageDeleted, {}),
+    "chat_action": (events.ChatAction, {}),
+    "user_joined": (events.UserUpdate, {}),
+    "message_read": (events.MessageRead, {}),
+}
+
+
+class Gateway(BaseJob):
+    """Generic pipeline job: filters -> processors -> actions."""
+
+    def __init__(
+        self,
+        config: GatewayConfig,
+        client: JobClient,
+        webhook=None,
+        bus=None,
+    ) -> None:
+        self._gw = config
+        shim = _GatewayJobConfig(config)
+        super().__init__(shim, client, webhook)  # type: ignore[arg-type]
+        self._handlers: list = []
+        self._bus = bus
+        self._bus_handler = None
+        self._stats: dict[str, int] = {"matched": 0, "skipped": 0, "errors": 0}
+
+    async def setup(self) -> None:
+        log.info(
+            "[%s] events=%s filters=%s actions=%s",
+            self.name,
+            self._gw.events,
+            "yes" if self._gw.filters else "none",
+            [a.name for a in self._gw.actions],
+        )
+
+    async def run(self) -> None:
+        if self._bus is not None:
+            await self._run_on_bus()
+            return
+        await self._run_on_client()
+
+    async def _run_on_bus(self) -> None:
+        """Subscribe to the daemon's bus instead of the update loop (ROB-02)."""
+        wanted = _bus_types(list(self._gw.events))
+        account = self._gw.account
+
+        async def on_event(envelope, raw) -> None:
+            if envelope.type not in wanted:
+                return
+            if account and envelope.account != account:
+                return
+            if raw is None:
+                # A self-origin echo or a synthesised event: the filters read
+                # the raw Telethon object, so there is nothing to evaluate.
+                return
+            await self._handle(raw, _V1_TYPE_MAP.get(envelope.type, envelope.type))
+
+        self._bus_handler = on_event
+        self._bus.add_handler(on_event)
+        try:
+            await asyncio.Future()
+        except asyncio.CancelledError:
+            raise
+
+    async def _run_on_client(self) -> None:
+        for event_type_name in self._gw.events:
+            mapping = _EVENT_TYPE_MAP.get(event_type_name)
+            if not mapping:
+                log.warning("[%s] unknown event type: %s", self.name, event_type_name)
+                continue
+            event_cls, kwargs = mapping
+            if event_type_name == "new_message":
+                kwargs = {"incoming": True}
+
+            et = event_type_name
+
+            @self.client.client.on(event_cls(**kwargs))
+            async def handler(tg_event, _et=et):
+                await self._handle(tg_event, _et)
+
+            self._handlers.append(handler)
+
+        try:
+            await asyncio.Future()
+        except asyncio.CancelledError:
+            raise
+
+    async def teardown(self) -> None:
+        if self._bus is not None and self._bus_handler is not None:
+            self._bus.remove_handler(self._bus_handler)
+            self._bus_handler = None
+        for h in self._handlers:
+            self.client.client.remove_event_handler(h)
+        self._handlers.clear()
+        log.info(
+            "[%s] stopped — matched=%d skipped=%d errors=%d",
+            self.name,
+            self._stats["matched"],
+            self._stats["skipped"],
+            self._stats["errors"],
+        )
+
+    async def _handle(self, tg_event, event_type: str = "new_message") -> None:
+        envelope = Event(
+            source="telegram",
+            raw=tg_event,
+            account=self._gw.account,
+            event_type=event_type,
+        )
+
+        ok, reason = evaluate(self._gw.filters, envelope)
+        if not ok:
+            self._stats["skipped"] += 1
+            return
+
+        self._stats["matched"] += 1
+
+        for action_cfg in self._gw.actions:
+            await self._run_action(action_cfg, envelope)
+
+    async def _run_action(self, ac: ActionConfig, envelope: Event) -> None:
+        if ac.filters:
+            ok, reason = evaluate(ac.filters, envelope)
+            if not ok:
+                return
+
+        func = get_action(ac.name)
+        if func is None:
+            log.warning("[%s] unknown action: %s", self.name, ac.name)
+            self._stats["errors"] += 1
+            return
+
+        chain = ac.processors or self._gw.processors
+
+        try:
+            await func(envelope, ac.config, self.client, chain)
+        except Exception as e:
+            log.warning("[%s] action '%s' failed: %s", self.name, ac.name, e)
+            self._stats["errors"] += 1

tlgr/gateway/event.py

@@ -0,0 +1,22 @@
+"""Thin event envelope for the Gateway pipeline.
+
+The envelope carries a source discriminator and the raw event payload.
+Filters extract what they need from ``raw`` directly, keeping the envelope
+protocol-agnostic so it can wrap Telethon events, inbound webhook payloads,
+or any future event source.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+
+@dataclass(slots=True)
+class Event:
+    source: str
+    raw: Any
+    account: str = ""
+    event_type: str = "new_message"
+    timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))

tlgr/jobs/base.py

@@ -0,0 +1,81 @@
+"""Base class for background jobs."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from abc import ABC, abstractmethod
+from typing import Any
+
+from tlgr.daemon.webhook import WebhookPusher
+from tlgr.jobs.client import JobClient
+
+log = logging.getLogger("tlgr.jobs")
+
+
+class BaseJob(ABC):
+    """Base class that all background jobs inherit from."""
+
+    def __init__(
+        self,
+        config: Any,
+        client: JobClient,
+        webhook: WebhookPusher | None = None,
+    ):
+        self.config = config
+        self.client = client
+        self.webhook = webhook
+        self._task: asyncio.Task | None = None
+        self.enabled = config.enabled
+
+    @property
+    def name(self) -> str:
+        return self.config.name
+
+    @property
+    def job_type(self) -> str:
+        return self.config.type
+
+    @abstractmethod
+    async def setup(self) -> None:
+        """Resolve chat IDs and prepare the job. Called once before start."""
+
+    @abstractmethod
+    async def run(self) -> None:
+        """Run the job (register event handlers, etc.). Should run indefinitely."""
+
+    @abstractmethod
+    async def teardown(self) -> None:
+        """Clean up resources."""
+
+    def start(self) -> asyncio.Task:
+        self._task = asyncio.create_task(self._run_wrapper(), name=f"job:{self.name}")
+        return self._task
+
+    async def _run_wrapper(self) -> None:
+        try:
+            await self.setup()
+            log.info("Job '%s' started", self.name)
+            await self.run()
+        except asyncio.CancelledError:
+            log.info("Job '%s' cancelled", self.name)
+        except Exception:
+            log.exception("Job '%s' crashed", self.name)
+        finally:
+            await self.teardown()
+
+    async def stop(self) -> None:
+        if self._task and not self._task.done():
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+
+    def status(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "type": self.job_type,
+            "enabled": self.enabled,
+            "running": self._task is not None and not self._task.done(),
+        }

tlgr/jobs/client.py

@@ -0,0 +1,37 @@
+"""The narrow client view a background job is handed.
+
+v1 passed the job engine a `ClientWrapper` — a 460-line object that owned a
+Telethon client, logged in, logged out, serialised messages and answered the
+v1 IPC routes. PR-12 deleted it: the daemon owns the connection now, and a
+job has no business logging anything in or out.
+
+What a job genuinely needs is two things, and this Protocol is exactly those
+two: the raw Telethon client to attach handlers to and to send with, and a
+resolver so a YAML file can name a destination as `@channel` rather than as a
+marked id. Anything that satisfies them is a job client; the daemon's session
+supplies one (`daemon/session.py`), and a test can supply one in four lines.
+
+A Protocol rather than a base class because `jobs/` must not import
+`daemon/`: the layering lint in `tests/test_layering.py` is what keeps the
+job engine testable without a socket.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+__all__ = ["JobClient"]
+
+
+@runtime_checkable
+class JobClient(Protocol):
+    """What a background job may do with the account it runs on."""
+
+    @property
+    def client(self) -> Any:
+        """The connected Telethon client, owned by whoever supplied it."""
+        ...
+
+    async def resolve_chat(self, chat_ref: str) -> int:
+        """`@channel`, a marked id or a t.me link → the marked chat id."""
+        ...