signal-bot/signal_bot/decorators.py
Krzysztof kuhy Rudnicki 405541be9b
Some checks are pending
CI / check (push) Waiting to run
CI / web (push) Waiting to run
release: 0.2.6 «Stephanus I» — dodano !analityka
One row per command attempt, not two aggregates written only on success.

command_uses holds last-use only and daily_uses counts successes; both are
rate-limiter state and both are written by store.record_use, which the
dispatcher calls only when a handler returns cleanly. A gate refusal and a
crash returned before it, so a command that failed every time looked exactly
like one nobody ran, and nothing knew which command a counted message was.

command_events now takes every attempt with its outcome, its duration and
the item it served; upstream_calls takes every outbound request made while
serving one. The two writes stay separate on purpose -- recording a refusal
as a use is what slid the cooldown window forward every time somebody was
told to wait -- and test_dispatcher_outcomes asserts last_used does not move.

Backfilled from journald joined against message_events, with daily_uses
filling the residual so the two sources cannot double-count. Two things were
wrong on the first attempt and both were found by measuring rather than by
reasoning: the window has to be symmetric, because sent_at_ms comes from the
sender's phone and the journal stamp from this host (194 of 299 lines landed
*before* their own message, by up to 3.2 s); and matching has to be a global
closest-pair assignment, because per-row greedy cannot separate two commands
seconds apart. Together those took the dropped rows from 137 to zero, and
recovered 418 invocations back to 29 August.

Also: !analityka in the group, twelve Polish lines, naming at most three
people and only ones whose display name has been seen; an Analytics tab with
Nivo charts; and continuous latency measurement, which answers the open
question in DOCS-latency.md -- a text send is 235 ms and an image send about
2.2 s, so the upload really is where the time goes.

EPHEMERAL_TABLES was doing two unrelated jobs and is now two tuples: what a
schema bump rebuilds, and what leaving a group clears. daily_uses left the
first (it is a backfill source now) and stayed in the second, and
_drop_reshaped took over the repair a bump used to do for it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T4QTp3h5Q3MvfrwGV8xqPf
2026-08-31 23:19:51 +02:00

128 lines
4.9 KiB
Python

# Copyright (c) 2026 Krzysztof Rudnicki. MIT licence.
"""Reusable gates that wrap a command handler.
These are the mechanisms salvaged from the unmerged vote and rate-limit
branches, detached from the command they were originally written for.
They only decide whether a handler may run; recording a successful use is the
dispatcher's job, so stacking two gates cannot double-count one invocation.
A gate that refuses raises ``CommandRefusedError`` rather than returning, which
is what tells the dispatcher no use took place. Returning quietly used to look
identical to a successful run.
"""
from __future__ import annotations
import functools
import logging
import math
from collections.abc import Callable
from typing import TYPE_CHECKING, Final
from signal_bot.registry import CommandRefusedError, Handler
from signal_bot.stats.text import plural
if TYPE_CHECKING:
from signal_bot.context import CommandContext
logger = logging.getLogger(__name__)
Decorator = Callable[[Handler], Handler]
# Which gate said no. These are the analytics outcomes minus their prefix, so
# a refusal names the gate that caused it rather than arriving as one
# undifferentiated "refused" -- a command whose cooldown bites half the time
# is mis-tuned, and one whose vote never carries is unwanted, and the raw
# count cannot tell those apart.
GATE_COOLDOWN: Final = "cooldown"
GATE_DAILY: Final = "daily"
GATE_VOTE: Final = "vote"
# Padding on the *displayed* wait only, never on the gate itself. A number that
# is a second short sends somebody back for another refusal, which reads as the
# bot lying; a number that is a second long costs nothing.
DISPLAY_MARGIN_SECONDS = 2
def wait_display(remaining: float) -> tuple[int, str]:
"""Round a remaining wait up (plus margin) and pick its Polish noun form.
Three forms, not two: 1 sekundę, 2-4 sekundy, 5+ sekund -- and the rule
reads the last two digits, so 12-14 take the many-form and 22-24 do not.
"""
seconds = math.ceil(remaining) + DISPLAY_MARGIN_SECONDS
return seconds, plural(seconds, "SEKUNDĘ", "SEKUNDY", "SEKUND")
def cooldown(seconds: float, message: str) -> Decorator:
"""Refuse a command until `seconds` have passed since that user's last use.
The original bot shared one cooldown window across every user and every
command, so one person's cat picture silenced everybody.
"""
def decorate(handler: Handler) -> Handler:
@functools.wraps(handler)
async def wrapper(ctx: CommandContext) -> None:
last = ctx.store.last_used(ctx.group_id, ctx.message.source_uuid, ctx.command_name)
if last is not None and ctx.now - last < seconds:
shown, unit = wait_display(seconds - (ctx.now - last))
# Logged with the number the group was given: when this said
# one thing and the gate did another, nothing recorded either.
logger.info(
"cooldown refused %s for %s: told them %d %s",
ctx.command_name,
ctx.message.source_name,
shown,
unit,
)
await ctx.reply(message.format(seconds=shown, unit=unit))
raise CommandRefusedError(GATE_COOLDOWN)
await handler(ctx)
return wrapper
return decorate
def daily_limit(max_uses: int, message: str) -> Decorator:
"""Allow a command at most `max_uses` times per user per calendar day."""
def decorate(handler: Handler) -> Handler:
@functools.wraps(handler)
async def wrapper(ctx: CommandContext) -> None:
used = ctx.store.uses_today(
ctx.group_id, ctx.message.source_uuid, ctx.command_name, ctx.day
)
if used >= max_uses:
await ctx.reply(message.format(max_uses=max_uses, used=used))
raise CommandRefusedError(GATE_DAILY)
await handler(ctx)
return wrapper
return decorate
def vote_gated(required: int, window_seconds: float, message: str) -> Decorator:
"""Run a command only once `required` distinct people ask within a window.
A repeat vote from the same person is ignored, and the tally is cleared
once the command fires so the next run starts from zero.
"""
def decorate(handler: Handler) -> Handler:
@functools.wraps(handler)
async def wrapper(ctx: CommandContext) -> None:
ctx.store.add_vote(ctx.group_id, ctx.command_name, ctx.message.source_uuid, ctx.now)
votes = ctx.store.count_votes(ctx.group_id, ctx.command_name, ctx.now - window_seconds)
if votes < required:
await ctx.reply(message.format(votes=votes, required=required))
raise CommandRefusedError(GATE_VOTE)
ctx.store.clear_votes(ctx.group_id, ctx.command_name)
await handler(ctx)
return wrapper
return decorate