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.context import CommandContext
from signal_bot.counting import should_count, watched_group
from signal_bot.envelope_shape import shape_of
from signal_bot.models import parse_envelope
from signal_bot.registry import CommandRefusedError, CommandRegistry
from signal_bot.stats.recorder import record_message

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."""
        # Keys and types only, never values -- see envelope_shape. This is
        # how "what does a frame with an attachment look like?" gets answered
        # without a code change and a lucky moment.
        logger.debug("envelope shape: %s", shape_of(frame))
        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

        # Resolved before recording, not after: is_command is part of the
        # row, so "was this a command" has to be known at write time. It is
        # the same lookup the handler below uses, not a second one.
        #
        # Scoped to this group, and that is the whole enforcement: a command
        # a group is not allowed comes back as None here, so it is not
        # answered, not recorded as a command and never named in a log line
        # outside the groups it belongs to.
        resolved = self.registry.resolve_with_args(message.text, group)
        command = resolved.command if resolved is not None else None
        if should_count(message):
            record_message(
                self.store.events,
                group,
                message,
                self.clock(),
                is_command=command is not None,
            )

        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(),
            args=resolved.args if resolved is not None else (),
        )
        try:
            await command.handler(ctx)
        except CommandRefusedError:
            # A gate said no and already answered. Nothing ran, so nothing is
            # recorded -- otherwise every "wait N seconds" reply would push the
            # cooldown window N seconds further away and the wait never ended.
            logger.debug("command %s refused by a gate", command.name)
            return
        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)