mirror of
https://github.com/kuhyx/signal-bot.git
synced 2026-11-22 21:32:28 +01:00
Some checks are pending
CI / check (push) Waiting to run
You asked for !add_photo in testbot without the real album being reachable there. One album cannot do that: its people.json "groups" list *is* the privacy guarantee, so making the commands exist in a second group necessarily makes the real photos postable there. So the bot now loads several albums. PHOTO_PACK_DIR takes a comma-separated list, the spelling GROUP_IDS and TRUSTED_INVITERS already use. Each album carries its own group scope, its own people, its own tags and its own custom labels; they share nothing but the process they run in. That makes trigger collisions between albums legal for the first time, and the registry had to learn it. Two albums are two different sets of people and both may reasonably call somebody "!alfa" -- no message can ever mean both, because a command a group is not scoped to is not a command there at all. So a trigger may be claimed more than once, and DuplicateTriggerError now fires only where the group sets *overlap*. Overlapping albums are refused at startup rather than resolved by registration order: a coin toss about which private album receives a photo is the outcome this whole design exists to prevent. Two consequences worth naming: - registry.resolve() takes an optional group. Without one it still answers "does anything claim this word", which is what pack_add's mint check wants; with one it answers "what runs here", which is what the dispatcher wants. resolve_with_args no longer resolves-then-checks, because with two claimants the first one found may be the wrong group's. - CommandContext moved to signal_bot/context.py to keep registry.py under the 250-line cap. A filing change: that file is "which word runs what", this one is "what the thing that runs may do". DOCS-add-photo.md is likewise a split, not new prose -- DOCS-photo-pack.md had grown past the cap and the ingest path is its own subject now. Verified live: the unit serves both albums, the real group resolves its 13 album commands and testbot its 7, and !losowe / !alfa / !dodaj all fire in testbot through the live dispatcher. 997 tests, 100% branch coverage, 28 e2e scenarios. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JqqE22jp94B1ypwxppdr1o
176 lines
7.6 KiB
Markdown
176 lines
7.6 KiB
Markdown
# The photo pack
|
||
|
||
A pack is a private album the bot posts from: `!alfa` returns a random photo
|
||
of alfa, and `!alfa beta` returns one with both of them on it.
|
||
|
||
**Nothing about a real pack is in this repository, and nothing ever will be.**
|
||
Who the people are, what somebody types to get their photo and which file
|
||
shows whom live in one directory outside the repo. This document, the tests
|
||
and the offline end-to-end run all use the same invented people — alfa, beta,
|
||
gamma — so the mechanism can be public while the album stays private.
|
||
|
||
## Where it lives
|
||
|
||
```
|
||
~/.local/share/signal-bot/pack/
|
||
people.json # the commands, and the only place names exist
|
||
tags.json # which file shows whom
|
||
custom.json # labels !add_photo minted (optional)
|
||
adds.json # who added what, read by nothing (optional)
|
||
media/ # the photos and videos themselves
|
||
```
|
||
|
||
Found in this order: `PHOTO_PACK_DIR`, then `$STATE_DIRECTORY/pack` (what
|
||
systemd hands a **system** unit), then `$XDG_DATA_HOME/signal-bot/pack`.
|
||
`StateDirectory=` is deliberately **not** in the unit this repo installs:
|
||
for a *user* unit systemd resolves it below `$XDG_STATE_HOME`, which is not
|
||
where the album is. Discovery finds the same directory, and leaving
|
||
`PHOTO_PACK_DIR` unset is what keeps a not-yet-filled-in pack from turning
|
||
`Restart=always` into a restart loop.
|
||
|
||
Two absences, deliberately different:
|
||
|
||
- a pack **nobody named** that is not there, or that has no `people.json`
|
||
yet, is an installation without an album: the commands do not exist, and
|
||
that is the normal case on every machine and in the whole test suite;
|
||
- a pack named in `PHOTO_PACK_DIR` that is missing, or whose manifest cannot
|
||
be honoured, **fails startup**. `load_config` raising is an answer, and a
|
||
bot that came up healthy and said "no such photo" forever would not be.
|
||
|
||
### More than one album
|
||
|
||
`PHOTO_PACK_DIR` takes a **comma-separated list**, the same spelling
|
||
`GROUP_IDS` and `TRUSTED_INVITERS` use:
|
||
|
||
```sh
|
||
PHOTO_PACK_DIR=~/.local/share/signal-bot/pack,~/.local/share/signal-bot/pack-testbot
|
||
```
|
||
|
||
Each album carries its own group scope in its own `people.json`, and the two
|
||
share nothing but the process: separate people, separate tags, separate
|
||
custom labels. That is what lets a test group have working `!add_photo` and
|
||
`!losowe` over invented people while the real album does not exist there at
|
||
all — which one album cannot do, because its `groups` list *is* the privacy
|
||
guarantee.
|
||
|
||
Trigger collisions between albums are therefore legal. Two albums are two
|
||
sets of people and both may call somebody `!alfa`; no message can ever mean
|
||
both, because a command a group is not scoped to is not a command there.
|
||
`!dodaj` and `!losowe` are registered once per album for exactly this reason.
|
||
|
||
**Two albums whose groups overlap are refused at startup** with
|
||
`DuplicateTriggerError`. Overlapping scopes would make "which album does
|
||
`!dodaj` write to?" a coin toss, and a coin toss about which private album
|
||
receives a photo is the outcome this whole design exists to prevent.
|
||
|
||
## people.json
|
||
|
||
```json
|
||
{
|
||
"groups": ["group.WlRKbExYZGhkR05vWldRdA=="],
|
||
"people": [
|
||
{"key": "p1", "triggers": ["!alfa", "!alfka"]},
|
||
{"key": "p2", "triggers": ["!beta"]}
|
||
],
|
||
"combos": [
|
||
{"key": "c1", "triggers": ["!oboje"], "all_of": ["p1", "p2"]},
|
||
{"key": "c2", "triggers": ["!ktokolwiek"], "any_of": ["p1", "p2"]}
|
||
]
|
||
}
|
||
```
|
||
|
||
- **`groups` is the whole privacy guarantee.** In any other group these are
|
||
not commands at all: not answered, not counted as a command, not named in a
|
||
log line. A handler that quietly returned would still leak all three, which
|
||
is why the *dispatcher* enforces it — `registry.resolve_with_args` takes the
|
||
group and gives back nothing outside it.
|
||
- **`key` is a pseudonym**, and the only identifier that reaches the journal
|
||
or the `command_uses` table. A command is `pack:p1`; reading either says
|
||
somebody asked for a photo and nothing about whose.
|
||
- **`all_of` means one photo with all of them; `any_of` means either**, and
|
||
where a choice exists the bot picks among the readings that actually have a
|
||
photo, so a combination that could be answered is not refused.
|
||
- Triggers may not contain a digit — `folding.py` maps `0134578` onto letters,
|
||
so `!alfa7` is not what you typed. Two spellings that fold the same are fine
|
||
*within one entry* (`!celina`/`!celiną` is one person written twice) and
|
||
refused across two.
|
||
|
||
## tags.json
|
||
|
||
```json
|
||
{"alfa.png": ["p1"], "both.png": ["p1", "p2"], "clip.mp4": ["p1"]}
|
||
```
|
||
|
||
A tag naming a file that is not in `media/` fails startup: a renamed file
|
||
would otherwise drop out of the album in silence. An empty list means "seen,
|
||
nobody in it", which is how the tagger records a photo you skipped.
|
||
|
||
Videos work. The attachment goes out as
|
||
`data:video/mp4;filename=<name>;base64,<data>` — the spelling is the
|
||
container's own, from its `/swagger/doc.json` — because told it is a photo,
|
||
Signal renders a clip as a file nobody can play.
|
||
|
||
## custom.json
|
||
|
||
```json
|
||
{"t1": ["wakacje2019"], "t2": ["gorybieszczady"]}
|
||
```
|
||
|
||
Labels `!add_photo` learned from the chat that match no person. The key is a
|
||
pseudonym in the same family as `p1` — it is what reaches `tags.json`, a log
|
||
line and a reply — and the label is the only place the typed word is kept.
|
||
Custom tags define **no commands**: `!random <label>` is the only door to one.
|
||
That is deliberate, and it is what makes a live album swap safe — a swap
|
||
replaces pack *data* only, and can never register a trigger or widen a
|
||
command's groups.
|
||
|
||
A label that folds onto a person's trigger, or onto another key's label, fails
|
||
startup rather than shadowing the command it collides with.
|
||
|
||
## adds.json
|
||
|
||
```json
|
||
{"a3ae52c7….jpg": {"by": "<uuid>", "at": 1756600000}}
|
||
```
|
||
|
||
Who added which file. **Nothing reads it** — `pack_load` ignores the file
|
||
entirely — and it exists only so `!undo_photo` can be built later without a
|
||
gap in its history; the adder has to be recorded at add time or not at all.
|
||
It lives inside the album, which is `0700` and outside this repository, so it
|
||
is handled exactly like the photos.
|
||
|
||
## Adding from the chat: !add_photo
|
||
|
||
A member of one of the album's groups can send a photo captioned
|
||
`!add_photo alfa wakacje` and have it land in that album, tagged, stripped
|
||
and retrievable immediately. That path has its own document, because the
|
||
metadata handling and the privacy invariants it has to keep are longer than
|
||
the album format itself: **`DOCS-add-photo.md`**.
|
||
|
||
## Filling it in: tool/tagger.py
|
||
|
||
```sh
|
||
python tool/tagger.py --import ~/photos # copy the files in, then tag
|
||
python tool/tagger.py # carry on where you left off
|
||
```
|
||
|
||
It serves one page on `127.0.0.1:8140`: the item, a numbered button per
|
||
person, `1`–`9` to toggle, `→`/`←` to move. Every toggle rewrites `tags.json`
|
||
atomically, so closing the tab loses nothing. Names are typed **into the
|
||
page**, never as arguments — an argument would land in the shell history —
|
||
and the group is picked from the live `/v1/groups` listing rather than pasted.
|
||
|
||
When you stop it, it prints how many items were never opened and how many
|
||
photos each command would have. **A command showing `0` is dead on arrival**;
|
||
that is the number to check before restarting the bot, not after somebody in
|
||
the group tries it.
|
||
|
||
## Running the mechanism without an album
|
||
|
||
`scripts/e2e.sh` writes a synthetic pack with `tool/e2e_pack.py` and proves,
|
||
offline and with no Signal account, that one name posts a photo, two names
|
||
intersect, an impossible combination gets one line and no attachment, a video
|
||
leaves as a video, and the same command in another group produces **zero**
|
||
sends. It also drives `!add_photo` against the real exiftool, on media it
|
||
generates at run time, so no photo enters this repository.
|