signal-bot/signal_bot/dispatcher.py

# Copyright (c) 2026 Krzysztof Rudnicki. MIT licence.
"""Routes one inbound frame: scope it, count it, maybe run a command."""

from __future__ import annotations

import datetime as dt
import logging
from collections.abc import Callable
from dataclasses import dataclass
from typing import TYPE_CHECKING

from signal_bot.counting import should_count, watched_group
from signal_bot.models import parse_envelope
from signal_bot.registry import CommandContext, CommandRegistry

if TYPE_CHECKING:
    from signal_bot.config import Config
    from signal_bot.discovery import GroupDirectory
    from signal_bot.store import Store
    from signal_bot.transport_base import Transport

logger = logging.getLogger(__name__)

Clock = Callable[[], dt.datetime]


@dataclass(frozen=True, slots=True)
class Dispatcher:
    """Applies the scoping rules and dispatches commands."""

    config: Config
    directory: GroupDirectory
    registry: CommandRegistry
    store: Store
    transport: Transport
    clock: Clock

    async def handle(self, frame: str) -> None:
        """Process one raw websocket frame end to end."""
        message = parse_envelope(frame)
        if message is None:
            return

        # Before the scoping gate: a group-update frame arrives while its
        # group is still unknown, and it is what vouches for that group.
        self.directory.note_group_update(message)

        # The scoping gate. Direct messages and every other group the account
        # belongs to stop here, before counting and before any handler runs.
        # The canonical id it yields is the reply address and the key for
        # every piece of per-group state, so a message can only ever be
        # counted, rate-limited and answered in the group it came from.
        group = watched_group(message, self.directory)
        if group is None and message.group_id is not None:
            # The bot was probably just added: Signal is already delivering
            # this group's messages while our listing still predates it.
            # Refreshing here is what makes the *first* command after an add
            # work, instead of the one after the next 30-second sweep.
            group = await self.directory.refresh_for(message.group_id)
        if group is None:
            logger.debug(
                "ignoring message from group %r; watching %r",
                message.group_id,
                list(self.directory.groups),
            )
            return

        if should_count(message):
            self.store.increment(group, message.source_uuid, message.source_name)

        command = self.registry.resolve(message.text)
        if command is None:
            return

        logger.info("running command %s for %s", command.name, message.source_name)
        now = self.clock()
        ctx = CommandContext(
            message=message,
            group_id=group,
            transport=self.transport,
            store=self.store,
            config=self.config,
            command_name=command.name,
            now=now.timestamp(),
            day=now.date().isoformat(),
        )
        try:
            await command.handler(ctx)
        except Exception:
            logger.exception("command %s failed", command.name)
            return
        # Recorded once, here, so stacked gates cannot double-count a use.
        self.store.record_use(group, message.source_uuid, command.name, ctx.now, ctx.day)