signal-bot/signal_bot/pack_ledger.py

# Copyright (c) 2026 Krzysztof Rudnicki. MIT licence.
"""What the album has already seen, so importing the same folder twice is free.

Two hashes per stored file, because stripping changes the bytes:

* ``source`` -- SHA-256 of the file as it arrived, *before* metadata was
  removed. This is the one that answers "have I imported this photo before?"
  when the same export folder is pointed at the album a second time.
* ``stored`` -- SHA-256 of the bytes on disk now. This is the one that answers
  "is the photo somebody just uploaded from the chat already here?", because
  ``!add_photo`` hashes *after* stripping (pack_store.content_name).

Neither alone is enough. A photo that arrived through ``--import`` and the same
photo re-sent through Signal have different source bytes -- the phone re-encodes
-- but strip to the same output; a photo re-imported from the same folder has
identical source bytes but restripping is not guaranteed byte-for-byte across
exiftool versions. Recording both makes each case a lookup.

``source`` is None when the original bytes are unrecoverable, which is exactly
the ``!add_photo`` files: their stored name is a hash of the *stripped* payload
and the upload was never kept.

Unlike pack_load, nothing here ever raises on a bad file. This ledger is an
optimisation and a safety net, not a manifest: ``pack_load`` failing at startup
is a restart loop under ``Restart=always`` (see pack_holder.reload, which
deliberately never raises), and a corrupt ledger degrading to "I have seen
nothing" costs a duplicate photo, while a corrupt ledger taking startup down
costs the bot.
"""

from __future__ import annotations

import hashlib
import json
from dataclasses import dataclass
from typing import TYPE_CHECKING, Any, Final

from signal_bot.pack import MEDIA_DIR
from signal_bot.pack_store import ADDS_FILE, write_json

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

LEDGER_FILE: Final = "sources.json"


@dataclass(frozen=True, slots=True)
class Entry:
    """The two hashes one stored file is known by."""

    # The bytes as they arrived, or None when they were never kept.
    source: str | None
    # The bytes on disk now.
    stored: str


def digest(payload: bytes) -> str:
    """The hash this module identifies bytes by."""
    return hashlib.sha256(payload).hexdigest()


def read(directory: Path) -> dict[str, Entry]:
    """The ledger, or an empty one for anything unreadable or malformed.

    Args:
        directory: The album directory.

    Returns:
        Stored filename to its entry. Malformed individual entries are
        dropped rather than failing the whole read: a hand-edited file
        should cost the entries somebody broke, not all of them.
    """
    entries: dict[str, Entry] = {}
    for name, value in _document(directory / LEDGER_FILE).items():
        entry = _entry(value)
        if entry is not None:
            entries[name] = entry
    return entries


def write(directory: Path, entries: Mapping[str, Entry]) -> None:
    """Replace the ledger atomically, 0600, the way every manifest is written."""
    document = {
        name: {"source": entry.source, "stored": entry.stored}
        for name, entry in sorted(entries.items())
    }
    write_json(directory / LEDGER_FILE, document)


def source_hashes(entries: Mapping[str, Entry]) -> set[str]:
    """Every known pre-strip hash, for "did this file arrive here before?"."""
    return {entry.source for entry in entries.values() if entry.source is not None}


def stored_hashes(entries: Mapping[str, Entry]) -> set[str]:
    """Every known on-disk hash, for "is this photo already in the album?"."""
    return {entry.stored for entry in entries.values()}


def backfill(directory: Path) -> dict[str, Entry]:
    """Record every file already in media/ that the ledger does not know.

    Run this **before** any retroactive strip. The files that arrived through
    ``tool/tagger.py --import`` were copied verbatim (shutil.copy2), so their
    current bytes *are* their source bytes -- the one and only moment that
    fact is recoverable. Strip first and it is gone, and re-importing the
    same export folder next year silently re-adds all of them.

    The ``!add_photo`` files are told apart by ``adds.json``, which is the
    exact record of what came in through the chat. Those were stripped on the
    way in, so their source bytes never existed on disk and stay None.

    Args:
        directory: The album directory.

    Returns:
        The merged ledger, already written.
    """
    entries = read(directory)
    from_chat = set(_document(directory / ADDS_FILE))
    album = directory / MEDIA_DIR
    for path in sorted(album.iterdir()) if album.is_dir() else ():
        if not path.is_file() or path.name in entries:
            continue
        stored = digest(path.read_bytes())
        entries[path.name] = Entry(
            source=None if path.name in from_chat else stored,
            stored=stored,
        )
    write(directory, entries)
    return entries


def _entry(value: object) -> Entry | None:
    """One ledger row, or None when it is not shaped like one."""
    if not isinstance(value, dict):
        return None
    stored = value.get("stored")
    source = value.get("source")
    if not isinstance(stored, str) or not isinstance(source, str | None):
        return None
    return Entry(source=source, stored=stored)


def _document(path: Path) -> dict[str, Any]:
    """One JSON object, or an empty one for anything unreadable.

    Forgiving on purpose -- see the module docstring. This is the same policy
    pack_store._document has for adds.json, and the opposite of pack_load's.
    """
    try:
        raw = path.read_bytes()
    except OSError:
        return {}
    try:
        document = json.loads(raw)
    except json.JSONDecodeError:
        return {}
    return document if isinstance(document, dict) else {}