From 9e99d68c63081775d0648a309296b2755a7e6901 Mon Sep 17 00:00:00 2001 From: amtiYo Date: Mon, 5 Oct 2026 20:19:31 +0200 Subject: [PATCH] feat(vido): broadcast outbox (migration 014) vido.broadcasts holds one row per campaign: its fingerprint and the photo's Telegram file id once uploaded. vido.broadcast_deliveries holds one row per destination chat with the localized message, lease, retry state, Telegram evidence and an outcome saying why the chat was or was not reached, which is what Vido's broadcast report counts. Same delivery contract as 007, with two differences. chat_id is a bare id with a sign check instead of a foreign key, because private chats last seen before July 2026 have no core.chat row. The outcome checks spell out IS NOT NULL, since a NULL inside IN (...) makes a CHECK pass; the contract test covers both statuses without an outcome. vido_core can select, insert and update, never delete. The changelog entry for 014 already landed with 015; this adds the operator line for applying it, including by hand on vido_test. Co-Authored-By: Claude Opus 5.5 (1M context) --- CHANGELOG.md | 6 +- migrations/014_vido_broadcasts.sql | 88 +++++++++++++++++++ tests/014_vido_broadcasts.sql | 135 +++++++++++++++++++++++++++++ 3 files changed, 227 insertions(+), 2 deletions(-) create mode 100644 migrations/014_vido_broadcasts.sql create mode 100644 tests/014_vido_broadcasts.sql diff --git a/CHANGELOG.md b/CHANGELOG.md index 872f8b7..0200fe9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,8 +13,10 @@ See [`docs/versioning.md`](docs/versioning.md) for what the numbers mean and Use this section for changes that are merged but not released yet. -**Operators: apply migrations `013` and `015`.** Nothing needs restarting. Apply -`015` before enabling the group archive in Vido. +**Operators: apply migrations `013`, `014` and `015`.** Nothing needs restarting. +Apply `015` before enabling the group archive in Vido. `vido_test` is not built +by these migrations: run `014` there by hand, granting to `vido_test` instead of +`vido_core`, before the test bot sends a broadcast. ### Added diff --git a/migrations/014_vido_broadcasts.sql b/migrations/014_vido_broadcasts.sql new file mode 100644 index 0000000..53c80a2 --- /dev/null +++ b/migrations/014_vido_broadcasts.sql @@ -0,0 +1,88 @@ +-- core :: 014 - Vido broadcasts: one durable outbox row per destination chat +-- The central migrator owns the transaction; do not add BEGIN/COMMIT here. +-- +-- A broadcast goes to every private chat and group Vido has seen. Private chats +-- last seen before July 2026 were recorded with presence chat_id 0 and have no +-- core.chat row, so chat_id is a bare Telegram id here, not a foreign key; the +-- sign check below keeps private and group ids apart instead. +-- +-- Same delivery contract as 007: a row handed to Telegram without an answer +-- becomes delivery_unknown and is never replayed. outcome records why a chat +-- was or was not reached, which is what the operator report counts. The +-- outcome checks spell out IS NOT NULL: a NULL inside IN (...) would make the +-- whole CHECK NULL, and PostgreSQL accepts a NULL check. + +SET LOCAL lock_timeout = '5s'; +SET LOCAL statement_timeout = '30s'; + +CREATE TABLE IF NOT EXISTS vido.broadcasts ( + broadcast_key text PRIMARY KEY, + manifest_sha256 text NOT NULL, + photo_sha256 text, + photo_file_id text, + prepared_at timestamptz NOT NULL DEFAULT now(), + updated_at timestamptz NOT NULL DEFAULT now(), + CHECK (broadcast_key <> ''), + CHECK (manifest_sha256 ~ '^[0-9a-f]{64}$'), + CHECK (photo_sha256 IS NULL OR photo_sha256 ~ '^[0-9a-f]{64}$'), + CHECK (photo_file_id IS NULL OR photo_sha256 IS NOT NULL) +); + +CREATE TABLE IF NOT EXISTS vido.broadcast_deliveries ( + broadcast_key text NOT NULL REFERENCES vido.broadcasts(broadcast_key), + chat_id bigint NOT NULL, + chat_type text NOT NULL, + language text NOT NULL, + message_html text NOT NULL, + status text NOT NULL DEFAULT 'pending', + outcome text, + attempts integer NOT NULL DEFAULT 0, + next_attempt_at timestamptz NOT NULL DEFAULT now(), + lease_owner text, + lease_expires_at timestamptz, + last_error text, + delivered_chat_id bigint, + telegram_message_id bigint, + prepared_at timestamptz NOT NULL DEFAULT now(), + updated_at timestamptz NOT NULL DEFAULT now(), + last_attempt_at timestamptz, + sent_at timestamptz, + PRIMARY KEY (broadcast_key, chat_id), + CHECK (chat_type IN ('private', 'group', 'supergroup')), + CHECK ((chat_type = 'private' AND chat_id > 0) OR (chat_type <> 'private' AND chat_id < 0)), + CHECK (language <> ''), + CHECK (message_html <> ''), + CHECK (status IN ( + 'pending', 'sending', 'sent', 'failed', 'unreachable', 'delivery_unknown' + )), + CHECK (attempts >= 0), + CHECK ( + (status = 'sending' AND lease_owner IS NOT NULL AND lease_expires_at IS NOT NULL) + OR status <> 'sending' + ), + CHECK ( + (status = 'sent' + AND outcome IS NOT NULL + AND outcome IN ('delivered', 'text_only') + AND telegram_message_id IS NOT NULL + AND delivered_chat_id IS NOT NULL + AND sent_at IS NOT NULL) + OR status <> 'sent' + ), + CHECK ( + (status = 'unreachable' AND outcome IS NOT NULL AND outcome IN ( + 'blocked', 'deactivated', 'not_started', 'removed', 'no_rights', 'not_found' + )) + OR status <> 'unreachable' + ), + CHECK (status IN ('sent', 'unreachable') OR outcome IS NULL) +); + +CREATE INDEX IF NOT EXISTS ix_broadcast_deliveries_ready + ON vido.broadcast_deliveries (broadcast_key, next_attempt_at, prepared_at) + WHERE status = 'pending'; + +CREATE INDEX IF NOT EXISTS ix_broadcast_deliveries_status + ON vido.broadcast_deliveries (broadcast_key, status); + +GRANT SELECT, INSERT, UPDATE ON vido.broadcasts, vido.broadcast_deliveries TO vido_core; diff --git a/tests/014_vido_broadcasts.sql b/tests/014_vido_broadcasts.sql new file mode 100644 index 0000000..2bff6a4 --- /dev/null +++ b/tests/014_vido_broadcasts.sql @@ -0,0 +1,135 @@ +\set ON_ERROR_STOP on + +SET ROLE vido_core; +INSERT INTO vido.broadcasts(broadcast_key, manifest_sha256, photo_sha256) +VALUES ('test-broadcast', repeat('a', 64), repeat('b', 64)); + +-- A private chat with no core.chat row: the outbox must still accept it. +INSERT INTO vido.broadcast_deliveries( + broadcast_key, chat_id, chat_type, language, message_html +) VALUES + ('test-broadcast', 7101, 'private', 'en', 'Test'), + ('test-broadcast', 7102, 'private', 'ru', 'Тест'), + ('test-broadcast', -1007103, 'supergroup', 'en', 'Test'); + +UPDATE vido.broadcast_deliveries + SET status = 'sending', + attempts = attempts + 1, + lease_owner = 'test-worker', + lease_expires_at = now() + interval '1 minute', + last_attempt_at = now() + WHERE broadcast_key = 'test-broadcast' AND chat_id = 7101; + +UPDATE vido.broadcast_deliveries + SET status = 'sent', + outcome = 'delivered', + delivered_chat_id = 7101, + telegram_message_id = 71001, + sent_at = now(), + lease_owner = NULL, + lease_expires_at = NULL + WHERE broadcast_key = 'test-broadcast' AND chat_id = 7101; + +UPDATE vido.broadcast_deliveries + SET status = 'unreachable', + outcome = 'blocked', + attempts = 1, + last_error = 'Forbidden: bot was blocked by the user' + WHERE broadcast_key = 'test-broadcast' AND chat_id = 7102; + +UPDATE vido.broadcasts + SET photo_file_id = 'photo-file-id' + WHERE broadcast_key = 'test-broadcast'; + +SELECT ( + SELECT count(*) FROM vido.broadcast_deliveries + WHERE broadcast_key = 'test-broadcast' + AND ((chat_id = 7101 AND status = 'sent' AND outcome = 'delivered') + OR (chat_id = 7102 AND status = 'unreachable' AND outcome = 'blocked') + OR (chat_id = -1007103 AND status = 'pending' AND outcome IS NULL)) +) = 3 AS lifecycle_recorded \gset +\if :lifecycle_recorded +\else + DO $$ BEGIN RAISE EXCEPTION 'contract failed: 014_vido_broadcasts.sql: expected lifecycle_recorded to be true'; END $$; +\endif + +DO $$ +BEGIN + INSERT INTO vido.broadcast_deliveries( + broadcast_key, chat_id, chat_type, language, message_html, status, outcome + ) VALUES ( + 'test-broadcast', 7104, 'private', 'en', 'Invalid', 'sent', 'delivered' + ); + RAISE EXCEPTION 'sent broadcast without Telegram evidence was accepted'; +EXCEPTION WHEN check_violation THEN + NULL; +END $$; + +DO $$ +BEGIN + INSERT INTO vido.broadcast_deliveries( + broadcast_key, chat_id, chat_type, language, message_html, status + ) VALUES ( + 'test-broadcast', 7105, 'private', 'en', 'Invalid', 'unreachable' + ); + RAISE EXCEPTION 'unreachable broadcast without an outcome was accepted'; +EXCEPTION WHEN check_violation THEN + NULL; +END $$; + +DO $$ +BEGIN + INSERT INTO vido.broadcast_deliveries( + broadcast_key, chat_id, chat_type, language, message_html, status, + delivered_chat_id, telegram_message_id, sent_at + ) VALUES ( + 'test-broadcast', 7107, 'private', 'en', 'Invalid', 'sent', + 7107, 71007, now() + ); + RAISE EXCEPTION 'sent broadcast without an outcome was accepted'; +EXCEPTION WHEN check_violation THEN + NULL; +END $$; + +DO $$ +BEGIN + INSERT INTO vido.broadcast_deliveries( + broadcast_key, chat_id, chat_type, language, message_html + ) VALUES ( + 'test-broadcast', -7106, 'private', 'en', 'Invalid' + ); + RAISE EXCEPTION 'private broadcast target with a group id was accepted'; +EXCEPTION WHEN check_violation THEN + NULL; +END $$; +RESET ROLE; + +SELECT has_table_privilege('vido_core', 'vido.broadcasts', 'SELECT,INSERT,UPDATE') + AND has_table_privilege('vido_core', 'vido.broadcast_deliveries', 'SELECT,INSERT,UPDATE') + AS vido_can_use_outbox \gset +\if :vido_can_use_outbox +\else + DO $$ BEGIN RAISE EXCEPTION 'contract failed: 014_vido_broadcasts.sql: expected vido_can_use_outbox to be true'; END $$; +\endif + +SELECT NOT has_table_privilege('vido_core', 'vido.broadcast_deliveries', 'DELETE') + AS vido_cannot_erase_evidence \gset +\if :vido_cannot_erase_evidence +\else + DO $$ BEGIN RAISE EXCEPTION 'contract failed: 014_vido_broadcasts.sql: expected vido_cannot_erase_evidence to be true'; END $$; +\endif + +SELECT NOT has_table_privilege('searchy_core', 'vido.broadcast_deliveries', 'SELECT') + AND NOT has_table_privilege('searchy_core', 'vido.broadcasts', 'SELECT') + AS searchy_isolated \gset +\if :searchy_isolated +\else + DO $$ BEGIN RAISE EXCEPTION 'contract failed: 014_vido_broadcasts.sql: expected searchy_isolated to be true'; END $$; +\endif + +SELECT NOT has_table_privilege('public', 'vido.broadcast_deliveries', 'SELECT') + AS public_isolated \gset +\if :public_isolated +\else + DO $$ BEGIN RAISE EXCEPTION 'contract failed: 014_vido_broadcasts.sql: expected public_isolated to be true'; END $$; +\endif