# Copyright (c) 2026 Krzysztof Rudnicki. MIT licence. """Telling a group that the bot has been upgraded. A group is told about every release it has not seen, and a group that has never been told anything has not seen any of them -- so the first announcement starts at 0.0.0 "Petrus" rather than skipping straight to whatever is current. Watching the ladder start at Peter is the point of naming releases after popes at all. That does mean a group added years from now would be handed the whole backlog, so the message is capped at MAX_RELEASES and says how many older versions it left out. The announcement carries the same three things `!papiez` does: the pope's portrait, his Latin name and his Polish Wikipedia article. Only for the pope in the header -- ten attachments is the wall MAX_RELEASES exists to avoid. The version is recorded *before* the message is sent. `Restart=always` with `RestartSec=5` means a crash between the two would otherwise re-announce on every restart, and a missed announcement is far cheaper than a looping one. That is also why a portrait that will not download costs the photo and not the announcement: the marker is already written, so a Commons outage at boot would otherwise eat that group's release notes permanently. """ from __future__ import annotations import logging from typing import TYPE_CHECKING, Final from signal_bot.changelog import since from signal_bot.versioning import article_url, latin_name, pope_line, version_for if TYPE_CHECKING: from collections.abc import Iterable from signal_bot.changelog import Release from signal_bot.portraits import PortraitCache from signal_bot.store import Store from signal_bot.transport_base import Transport from signal_bot.versioning import Pope logger = logging.getLogger(__name__) ANNOUNCED_KEY: Final = "announced_version" # How many releases one announcement may list before it becomes a wall. MAX_RELEASES: Final = 10 def render(pope: Pope, releases: Iterable[Release]) -> str: """Return the message announcing a new version, in Polish. One release is rendered flat, because the header already names it. Several get a block each, so the group can see the ladder it is climbing. Pure on purpose: whether this text travels as a caption or as a plain message is announce_to's call, not this function's. """ shown = list(releases) header = f"Wersja {version_for(pope.ordinal)} \u00ab{latin_name(pope)}\u00bb wydana" header = f"{header}\n{pope_line(pope)}\n{article_url(pope)}" omitted = max(0, len(shown) - MAX_RELEASES) shown = shown[-MAX_RELEASES:] if len(shown) == 1: body = "\n".join(f"- {line}" for line in shown[0].lines) return f"{header}\nChangelog:\n{body}" blocks = [ "\n".join( [ f"{release.version} \u00ab{latin_name(release.pope_entry)}\u00bb", pope_line(release.pope_entry), *(f"- {x}" for x in release.lines), ] ) for release in shown ] tail = f"\n\n(pominieto {omitted} starszych wersji)" if omitted else "" return f"{header}\nChangelog:\n\n" + "\n\n".join(blocks) + tail async def announce_to( transport: Transport, store: Store, group_id: str, releases: tuple[Release, ...], pope: Pope, portraits: PortraitCache, ) -> None: """Announce the current version to one group, if it has not seen it.""" version = version_for(pope.ordinal) previous = store.meta(group_id, ANNOUNCED_KEY) if previous == version: return # No record at all means the group has seen nothing, not that it should be # skipped: that is how Petrus gets announced rather than silently assumed. pending = releases if previous is None else since(releases, previous) store.set_meta(group_id, ANNOUNCED_KEY, version) if not pending: logger.info("group %s recorded at %s with nothing to announce", group_id, version) return text = render(pope, pending) try: image = await portraits.get_base64(pope) await transport.send_image(image, group_id, caption=text) except Exception: # Both the download and the send are inside this: the marker is # already written, so either failing would otherwise cost the group # its release notes permanently. The attachment turns a 2 KB text # post into a megabyte of base64, which signal-cli can refuse on its # own terms while it is perfectly able to take the text -- and a # duplicate post, if the send failed after delivery, is far cheaper # than release notes nobody ever sees. logger.exception("photo announcement of %s failed for %s; sending text", version, group_id) await transport.send_text(text, group_id) async def announce_all( transport: Transport, store: Store, group_ids: Iterable[str], releases: tuple[Release, ...], pope: Pope, portraits: PortraitCache, ) -> None: """Announce to every watched group; one failure must not silence the rest.""" for group_id in group_ids: try: await announce_to(transport, store, group_id, releases, pope, portraits) except Exception: logger.exception("release announcement failed for group %s", group_id)