# 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)