# Copyright (c) 2026 Krzysztof Rudnicki. MIT licence. """Per-group silence: the state, and the one question the dispatcher asks it. A mute is a deadline in ``group_meta``, keyed by the canonical group id, so it survives a restart and a reload alike and never leaks into another group. While it stands the bot says nothing in that group: no replies, no "did you mean", no nightly report. Messages are still counted -- silence is about talking, not about listening -- and exactly one command still runs, the one that ends it. Anyone may ask for silence, for at most ten minutes, because the worst anyone can do with that is buy ten quiet minutes. Ending it early is the operator's call: see mute_command. """ from __future__ import annotations from typing import TYPE_CHECKING, Final if TYPE_CHECKING: from signal_bot.registry import Command from signal_bot.store import Store # The group_meta key. Epoch seconds, as text, like every other value there. MUTED_UNTIL_KEY: Final = "muted_until" MAX_MINUTES: Final = 10 DEFAULT_MINUTES: Final = MAX_MINUTES # The one command that runs through a mute. By name rather than by a flag on # Command, so that the registry -- which has nothing to do with silence -- # does not grow a field only one command sets. UNMUTE_NAME: Final = "unmute" def muted_until(store: Store, group_id: str) -> float | None: """When the current mute ends, or None when there has never been one.""" raw = store.meta(group_id, MUTED_UNTIL_KEY) return None if raw is None else float(raw) def is_muted(store: Store, group_id: str, now: float) -> bool: """Whether the group is silent at this instant. An expired deadline is left in place rather than deleted: reading it costs one comparison, and deleting it would make this a write. """ until = muted_until(store, group_id) return until is not None and now < until def mute(store: Store, group_id: str, until: float) -> None: """Silence the group until the given instant, replacing any earlier deadline.""" store.set_meta(group_id, MUTED_UNTIL_KEY, repr(until)) def unmute(store: Store, group_id: str) -> None: """End the silence now. Idempotent: a group that is not muted stays not muted.""" store.set_meta(group_id, MUTED_UNTIL_KEY, "0") def allows(store: Store, group_id: str, now: float, command: Command | None) -> bool: """Whether the dispatcher may say anything in reply to this message. True whenever the group is not muted; while it is, true only for the command that ends the mute. ``None`` is a word nobody registered, whose "did you mean" reply is exactly the kind of noise a mute is for. """ if not is_muted(store, group_id, now): return True return command is not None and command.name == UNMUTE_NAME