signal-bot/signal_bot/stats/nightly.py
Krzysztof kuhy Rudnicki 0ef2e4b021 feat: weekly, monthly and year-in-review posts, keyed off the day reported
A Sunday closes a week, a month's last day closes the month, and
31 December closes the year. Keyed off the day being *reported* rather
than off today, which is the only reading that stays right when the bot
has been offline: catching up on a week-old Sunday now also posts that
week's summary, and there is a test asserting the five messages a
three-day outage produces.

One scheduler, a date predicate. Three background tasks firing at the
same wall-clock time into the same group is three independent ways for
an evening to go wrong, for no gain over an if-statement. A failed
period summary is deliberately best-effort and runs after the day has
been marked, so it cannot make the bot re-post the daily one tomorrow.

Also: the quote frame arrived while this was being written, and it
carries a trap. `quote` has its own nested `attachments` array holding
the *quoted* message's media -- so a text reply to somebody's photo has
attachments in the payload that belong to somebody else. Reading them
would credit the replier with a photo they did not post, in a group
where people reply to photos constantly, inflating one number without
ever looking wrong.

The parser already read the top level only and is correct. It is now
pinned by a test built from the exact captured frame, and written up in
DOCS-signal-envelopes.md, because "it happens to be right" and "it
cannot silently stop being right" are different things. This is the same
wrong-nesting-level mistake that once made the bot ignore its own
stickers.

test_bot.py went past the 250-line cap on the way, so the report and
catch-up tests move into files named for what they cover.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015d48t4qsQLBJnDwDeo2Nom
2026-08-30 19:56:25 +02:00

100 lines
3.5 KiB
Python

# Copyright (c) 2026 Krzysztof Rudnicki. MIT licence.
"""Which days still owe the group a report, and posting them.
The event log already survives an outage: a message carries Signal's own send
timestamp, signal-cli keeps receiving while the bot is down, and the replay on
reconnect is absorbed by the primary key. So the *counts* come back on their
own, filed under the day they were actually sent.
The *report* did not. A bot that was down at 21:37 simply never posted that
day, and nothing ever went back for it -- the old counter merged the day into
the next one instead, which is the bug this release exists to remove. So the
last day reported is written down per group, and every day since then gets
posted when the bot comes back.
Bounded, because coming back from a fortnight offline should not open with a
fortnight of back-posts.
"""
from __future__ import annotations
import datetime as dt
import logging
from typing import TYPE_CHECKING, Final
from signal_bot.stats.periods import Period, month_of, shift, week_of, year_of
if TYPE_CHECKING:
from signal_bot.store import Store
logger = logging.getLogger(__name__)
LAST_REPORTED_KEY: Final = "last_reported_day"
# At most a week of catch-up in one go. Long enough to cover a weekend
# outage nobody noticed, short enough that a month offline is not a wall.
CATCHUP_LIMIT: Final = 7
def days_to_report(store: Store, group_id: str, latest: str) -> list[str]:
"""Every day up to ``latest`` that has not been reported yet, oldest first.
Args:
store: The open database, which holds the per-group marker.
group_id: The group being reported on.
latest: The most recent day eligible for a report, normally yesterday.
Returns:
The days to post, oldest first. A group with no marker gets only
``latest``: the marker is absent on a brand-new group and on the first
run after this release, and neither should trigger a backlog.
"""
last = store.meta(group_id, LAST_REPORTED_KEY)
if last is None:
return [latest]
if last >= latest:
return []
days = []
day = shift(last, 1)
while day <= latest:
days.append(day)
day = shift(day, 1)
return days[-CATCHUP_LIMIT:]
SUNDAY: Final = 6
LAST_DAY_OF_DECEMBER: Final = "12-31"
def closing_periods(day: str) -> list[Period]:
"""The longer periods that ended with ``day``, in the order to post them.
Keyed off the day being *reported*, not off today. The nightly post covers
yesterday, so a week is complete exactly when yesterday was a Sunday --
which is also the only reading that stays correct when the bot has been
offline and is catching up on a week-old day.
No separate scheduler for these. Three background tasks firing at the same
wall-clock time into the same group is three independent ways for the
evening to go wrong, for no gain over an if-statement.
"""
date = dt.date.fromisoformat(day)
closing = []
if date.weekday() == SUNDAY:
closing.append(week_of(day))
if shift(day, 1)[8:] == "01":
closing.append(month_of(day))
if day.endswith(LAST_DAY_OF_DECEMBER):
closing.append(year_of(day))
return closing
def mark_reported(store: Store, group_id: str, day: str) -> None:
"""Record that a day no longer owes this group a report.
Called for a day that was posted *and* for a day nobody spoke on -- an
empty day is settled, not pending, and leaving it unmarked would make the
bot reconsider it every night forever.
"""
store.set_meta(group_id, LAST_REPORTED_KEY, day)