# Copyright (c) 2026 Krzysztof Rudnicki. MIT licence. """The command history's own tables, kept apart from the rest of the schema. Split out of ``schema.py`` so both stay under the 250-line cap, the same reason ``schema.py`` was split out of ``store.py``. It is applied straight after ``SCHEMA`` and by the same method, so this is a filing decision and not a second schema: there is one database and one ``PRAGMA user_version``. Neither table is ever dropped -- see ``PERMANENT_TABLES``. The whole point of them is answering questions about a past that nothing can recompute. """ from __future__ import annotations from typing import Final COMMAND_SCHEMA: Final = """ -- One row per command *attempt*, including the ones that never ran. The two -- tables above it are aggregates a rate limiter reads; this is the history, -- and nothing recomputes it. -- -- Keyed on the envelope's own timestamp for the reason unknown_commands is: -- signal-cli replays undelivered frames on reconnect, and a clock reading is -- fresh on every replay. invoked_at_ms is message.timestamp, so a replay -- collides with the row it already wrote instead of adding a second one. -- -- source is part of the key because a backfilled row and a live row can -- describe the same invocation from two sources that disagree about the -- hour, and neither may overwrite the other. CREATE TABLE IF NOT EXISTS command_events ( group_id TEXT NOT NULL, user_uuid TEXT NOT NULL, command TEXT NOT NULL, -- Never free text. A pack pseudonym key the registry already resolved -- ('p1', 'add', 'random'), or '' / '+args'. See registry.resolve_with_args. args TEXT NOT NULL DEFAULT '', -- A public identifier for what was served -- a Wikidata QID, a Commons -- page id, a Wolne Lektury slug, a content-addressed filename. Never a -- title, a caption or a name: an identifier cannot carry one. item_id TEXT, outcome TEXT NOT NULL, -- The exception's class name when outcome is 'error', '' otherwise. -- A name, never a message: an exception's str() carries whatever was -- being processed, which for this bot is somebody's message. error_class TEXT NOT NULL DEFAULT '', invoked_at_ms INTEGER NOT NULL, day TEXT NOT NULL, local_hour INTEGER NOT NULL, weekday INTEGER NOT NULL, handler_ms INTEGER, send_ms INTEGER, source TEXT NOT NULL DEFAULT 'live', PRIMARY KEY (group_id, user_uuid, command, invoked_at_ms, source) ); CREATE INDEX IF NOT EXISTS idx_command_events_group_day ON command_events (group_id, day); CREATE INDEX IF NOT EXISTS idx_command_events_group_command_day ON command_events (group_id, command, day); CREATE INDEX IF NOT EXISTS idx_command_events_group_user_day ON command_events (group_id, user_uuid, day); -- One row per outbound HTTP call made while a command was running, joined to -- command_events by (group_id, invoked_at_ms). seq orders the calls within -- one invocation and keeps two calls to the same host distinct. CREATE TABLE IF NOT EXISTS upstream_calls ( group_id TEXT NOT NULL, invoked_at_ms INTEGER NOT NULL, command TEXT NOT NULL, host TEXT NOT NULL, -- 0 means the request never got a reply at all: DNS, connect, timeout. -- Distinguishable from a 5xx, which is upstream answering badly. status INTEGER NOT NULL, duration_ms INTEGER NOT NULL, seq INTEGER NOT NULL, PRIMARY KEY (group_id, invoked_at_ms, seq) ); CREATE INDEX IF NOT EXISTS idx_upstream_calls_host ON upstream_calls (group_id, host); """