signal-bot/signal_bot/pack_pending.py

# Copyright (c) 2026 Krzysztof Rudnicki. MIT licence.
"""The approval queue: where a photo sent to the chat waits until somebody looks at it.

``!add_photo`` used to write straight into the album. Since 2026-09-04 it
writes here instead -- ``<album>/pending/``, one stripped file plus one JSON
sidecar per upload -- and nothing reaches ``media/`` until the management
page approves it. Rejecting deletes both files; approving moves the file
into the album with the same four writes and the same roll-back the direct
path used, then proves the album still loads.

The sidecar holds the album keys the sender asked for and the *labels* that
matched nothing, as typed. The labels are kept rather than minted at send
time because a key minted for a photo nobody approves would sit in
``custom.json`` for ever, and because two people can send two new labels at
once; minting at approval, one photo at a time, cannot collide. Everything
here lives inside the album directory, which is 0700 and outside the
repository, so the sidecar is subject to exactly the same handling as the
photograph it describes.
"""

from __future__ import annotations

import json
import logging
from dataclasses import asdict, dataclass
from typing import TYPE_CHECKING, Any, Final

from signal_bot.groups import ConfigError
from signal_bot.pack import TAGS_FILE
from signal_bot.pack_custom import FILE_MODE
from signal_bot.pack_custom import write as write_custom
from signal_bot.pack_load import load
from signal_bot.pack_store import record_adds, restore, snapshot, write_json, write_media
from signal_bot.pack_tags import document

if TYPE_CHECKING:
    from collections.abc import Sequence
    from pathlib import Path

logger = logging.getLogger(__name__)

PENDING_DIR: Final = "pending"
SIDECAR_SUFFIX: Final = ".json"


@dataclass(frozen=True, slots=True)
class Pending:
    """One upload waiting for a decision."""

    name: str
    """The content-hash filename, the same one it will have in the album."""
    keys: tuple[str, ...]
    """Album keys the sender's labels resolved to: people, and custom tags that exist."""
    labels: tuple[str, ...]
    """Labels that matched nothing, as typed; minted as custom tags on approval."""
    by: str
    """The sender's uuid, for adds.json."""
    at: int
    """When it was sent, unix seconds."""
    group: str
    """The group it was sent in."""


def names(directory: Path) -> frozenset[str]:
    """Every file waiting in the queue, so a second send of it is reported as such."""
    return frozenset(entry.name for entry in listing(directory))


def queue(directory: Path, body: bytes, entry: Pending) -> None:
    """Put one stripped upload and its sidecar into the queue, atomically."""
    folder = directory / PENDING_DIR
    folder.mkdir(parents=True, exist_ok=True)
    _write_bytes(folder / entry.name, body)
    write_json(folder / f"{entry.name}{SIDECAR_SUFFIX}", asdict(entry))


def listing(directory: Path) -> list[Pending]:
    """Everything waiting, oldest first.

    A sidecar that cannot be read, or whose file is gone, is skipped with a
    warning rather than raised: the page must still show the other photos,
    and the broken pair is visible in the directory to whoever looks.
    """
    folder = directory / PENDING_DIR
    if not folder.is_dir():
        return []
    entries = []
    for sidecar in folder.glob(f"*{SIDECAR_SUFFIX}"):
        entry = _entry(sidecar)
        if entry is None or not (folder / entry.name).is_file():
            logger.warning("skipping unreadable or orphaned queue entry %s", sidecar.name)
            continue
        entries.append(entry)
    return sorted(entries, key=lambda entry: (entry.at, entry.name))


def discard(directory: Path, name: str) -> None:
    """Take one upload out of the queue: the file and its sidecar."""
    folder = directory / PENDING_DIR
    (folder / name).unlink(missing_ok=True)
    (folder / f"{name}{SIDECAR_SUFFIX}").unlink(missing_ok=True)


def approve(
    directory: Path, name: str, keys: Sequence[str], labels: Sequence[str], now: int
) -> tuple[str, ...]:
    """Move one queued upload into the album under ``keys`` plus minted ``labels``.

    The approver may have unticked people or labels the sender proposed;
    what arrives here is the decision. A label not on the sidecar is refused
    outright, because labels are the one thing this path lets free text into
    ``custom.json`` through, and the chat side already refused the ones that
    are command words.

    Returns:
        The keys the file is now tagged with.

    Raises:
        KeyError: Nothing by that name is waiting.
        ValueError: A label the sender never proposed.
        ConfigError: The album does not load -- before the write, or with
            this file in it, in which case every write is rolled back.
    """
    entry = _find(directory, name)
    strangers = set(labels) - set(entry.labels)
    if strangers:
        msg = f"labels not proposed for {name}: {sorted(strangers)}"
        raise ValueError(msg)
    pack = load(directory)
    custom = pack.custom
    final = list(keys)
    for label in labels:
        key = custom.resolve(label)
        if key is None:
            key = custom.next_key()
            custom = custom.with_label(key, label)
        final.append(key)
    tagged = tuple(dict.fromkeys(final))

    previous = snapshot(directory)
    tags_path = directory / TAGS_FILE
    tags = document(tags_path) if tags_path.exists() else {}
    write_media(directory, name, (directory / PENDING_DIR / name).read_bytes())
    write_json(tags_path, {**tags, name: sorted(tagged)})
    write_custom(directory, custom)
    record_adds(directory, {name: {"by": entry.by, "at": entry.at, "approved_at": now}})
    try:
        load(directory)
    except ConfigError:
        restore(directory, previous, (name,))
        raise
    discard(directory, name)
    return tagged


def _find(directory: Path, name: str) -> Pending:
    """The queue entry by that name, or KeyError."""
    for entry in listing(directory):
        if entry.name == name:
            return entry
    msg = f"{name} is not waiting for approval"
    raise KeyError(msg)


def _entry(sidecar: Path) -> Pending | None:
    """One sidecar parsed, or None when it is not the shape this file writes.

    The name has to be a bare filename: the page opens whatever the listing
    says, so a sidecar naming a path would be a way out of the album.
    """
    try:
        raw: dict[str, Any] = json.loads(sidecar.read_text(encoding="utf-8"))
        name = str(raw["name"])
        if name != sidecar.name.removesuffix(SIDECAR_SUFFIX):
            return None
        return Pending(
            name=name,
            keys=tuple(str(key) for key in raw["keys"]),
            labels=tuple(str(label) for label in raw["labels"]),
            by=str(raw["by"]),
            at=int(raw["at"]),
            group=str(raw["group"]),
        )
    except OSError, ValueError, KeyError, TypeError:
        return None


def _write_bytes(path: Path, payload: bytes) -> None:
    """Temp-then-replace, 0600, like every other file the album holds."""
    temporary = path.with_name(f"{path.name}.tmp")
    temporary.write_bytes(payload)
    temporary.chmod(FILE_MODE)
    temporary.replace(path)