signal-bot/signal_bot/pack_random.py

# Copyright (c) 2026 Krzysztof Rudnicki. MIT licence.
"""``!random``: a photo from the album, optionally narrowed by custom tags.

Custom tags define no commands of their own -- that is what keeps a hot-swap
a data swap -- so this is the only door to a label ``!add_photo`` minted.

Its resolver is deliberately **not** the one ``!add_photo`` uses. That one
mints a key for a label nobody has; if ``!random`` shared it, every typo here
would quietly create a tag, and the album would fill with keys nobody can
reach. An unknown label resolves to a sentinel instead and is answered with
the same line as a combination nobody photographed -- from the group's side
those are the same question.

Labels only, never people: ``!alfa`` already exists for those, and a second
entrance with an unscoped argument list is one too many.
"""

from __future__ import annotations

import base64
from typing import TYPE_CHECKING, Final

from signal_bot.pack import MAX_NAMES, media_type
from signal_bot.pack_command import NAME_PREFIX, NO_PHOTO, UNKNOWN, pick

if TYPE_CHECKING:
    from signal_bot.decorators import Decorator
    from signal_bot.pack_holder import PackHolder
    from signal_bot.registry import ArgResolver, CommandContext, CommandRegistry, Handler

COMMAND_NAME: Final = f"{NAME_PREFIX}random"

DESCRIPTION: Final = "losowe zdjęcie z albumu, opcjonalnie po etykiecie"


def random_resolver(holder: PackHolder) -> ArgResolver:
    """Turn typed labels into custom-tag keys, minting nothing.

    Reads through the holder rather than closing over a Pack, so a tag
    minted at 12:00 resolves at 12:01 without a restart.
    """

    def resolve(words: tuple[str, ...]) -> tuple[str, ...]:
        custom = holder.pack.custom
        return tuple(custom.resolve(word) or UNKNOWN for word in words)

    return resolve


def random_handler(holder: PackHolder) -> Handler:
    """Build the handler that answers ``!random``."""

    async def handler(ctx: CommandContext) -> None:
        keys = ctx.args
        # The ceiling is applied to the label list directly rather than
        # through candidate_keysets, whose ">=" is written against a
        # head-plus-tail shape that !random does not have.
        if len(keys) > MAX_NAMES or UNKNOWN in keys:
            await ctx.reply(NO_PHOTO)
            return
        pack = holder.pack
        # An empty frozenset is a superset test that every file passes, so
        # bare !random needs no separate path through here.
        viable = pack.matching(frozenset(keys))
        if not viable:
            await ctx.reply(NO_PHOTO)
            return
        filename = pick(viable)
        payload = base64.b64encode(pack.media_path(filename).read_bytes()).decode("ascii")
        await ctx.reply_media(payload, media_type(filename), filename)

    return handler


def register_random_command(
    registry: CommandRegistry,
    holder: PackHolder,
    triggers: tuple[str, ...],
    *,
    decorate: Decorator | None = None,
) -> None:
    """Register ``!random``, scoped to the album's own groups."""
    handler = random_handler(holder)
    if decorate is not None:
        handler = decorate(handler)
    registry.register(
        COMMAND_NAME,
        triggers,
        handler,
        DESCRIPTION,
        groups=holder.pack.groups,
        takes_args=True,
        arg_resolver=random_resolver(holder),
    )