Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
16 KiB
Модель данных lab5
Схема: 0001_init.sql (lab2), 0002_idempotency_keys.sql и 0003_post_message_function.sql (lab3), 0004_attachments.sql (lab4), 0005_pipeline.sql (lab5: задания, outbox, попытки, варианты). Миграции применяет один раз отдельный сервис migrate до старта реплик API; миграции lab3–lab5 только добавляют объекты (0004 ослабляет CHECK длины текста, 0005 — CHECK статуса и ключа объекта), поэтому совместимы с работающей предыдущей версией. Байты вложений живут только в двух приватных bucket S3 (SeaweedFS): messenger-staging (оригинал до обработки) и messenger-attachments (опубликованный оригинал и варианты); в PostgreSQL — метаданные, задания и их история. Порядок записи и окна отказа — PIPELINE.md. Источник истины для пользователей, чатов, участников и сообщений — PostgreSQL 18. Для сессий источник истины — хранилище, выбранное через SESSION_STORE. По умолчанию это Valkey с AOF, его можно переключить на таблицу sessions в PostgreSQL.
Таблицы и ограничения
| Таблица | Ключ | Ограничения | Зачем |
|---|---|---|---|
users |
id uuid |
UNIQUE (username), CHECK формата username, длина display_name |
уникальность имени держит БД, а не код: гонку регистрации разрешает уникальный индекс |
chats |
id uuid |
FK created_by → users, длина title |
last_message_at — «часы» чата для упорядочивания сообщений |
chat_members |
(chat_id, user_id) |
FK на chats и users, UNIQUE (chat_id, position) |
position хранит порядок member_ids; chat_created_at — копия времени чата для keyset-списка чатов |
messages |
id uuid |
FK (chat_id, sender_id) → chat_members, длина text |
отправитель обязан быть участником — это гарантирует сама БД |
sessions |
token_hash bytea |
FK user_id → users, длина хеша 32 байта |
хранится SHA-256 токена; сам токен не хранится нигде |
idempotency_keys |
(user_id, chat_id, key) |
FK на users, chats; message_id → messages (DEFERRABLE, UNIQUE); CHECK формата ключа и длины SHA-256 |
общая для всех реплик идемпотентность отправки: ключ → отпечаток тела → сообщение. Хранится ≥ IDEMPOTENCY_TTL_SECONDS (24 ч), очистка — пачками раз в 10 мин под advisory-замком |
attachments (lab4, lab5) |
id uuid |
FK (chat_id, owner_id) → chat_members; UNIQUE object_key, UNIQUE staging_key (COLLATE "C"); CHECK статуса pending/queued/processing/ready/failed, формата ключей, типа, размера, пикселей ≤ 40 млн; attachments_active_has_source: у queued/processing есть опубликованный оригинал или staging present; ready ⇒ object_key и published_version; failed ⇔ error_code + failed_at |
метаданные оригинала. staging_key (s/<128 бит>) — копия в staging, staging_state none/present/deleting/deleted; object_key — опубликованный оригинал (a/<id>/<token>/original, у строк lab4 — o/<hex>). published_version — версия pipeline, чьи варианты видны, только растёт |
jobs (lab5) |
id uuid = job_id |
FK на attachments; CHECK состояния, вида (upload/replay/reprocess/migrate), attempt ≤ max_attempts, lease есть ⇔ processing, finished_at ⇔ конечное; частичный UNIQUE (attachment_id, pipeline_version) WHERE state IN ('queued','processing') |
одна логическая работа «версия V для вложения A». available_at — backoff, lease_token/lease_until/lease_owner — аренда текущей попытки (fencing). Индексы: истекающие lease, queued, failed |
job_attempts (lab5) |
token uuid |
FK на jobs; UNIQUE (job_id, attempt); CHECK исхода running/succeeded/retry/failed/abandoned/superseded; опубликованную попытку нельзя «почистить» |
один claim worker. planned_keys — ключи всех объектов попытки, записаны ДО записи в S3: уборке не нужен List. Частичный индекс — кандидаты на уборку |
attachment_variants (lab5) |
(attachment_id, pipeline_version, name) |
FK на attachments, job_attempts; UNIQUE object_key, CHECK имени, типа, размера, длины SHA-256 |
опубликованные варианты; первичный ключ — ключ эффекта контракта, дубль физически невозможен |
outbox (lab5) |
id bigint identity |
FK на jobs; attempt ≥ 1 |
намерение опубликовать сообщение; пишется в одной транзакции с изменением задания. Частичный индекс WHERE published_at IS NULL — работа relay |
job_events (lab5) |
id bigint identity |
FK на jobs |
аудит: создание, claim, retry с задержкой, lease_expired, replay/reprocess (оператор и причина), результат, внедрённые отказы. Без секретов и имён файлов. View failed_jobs — реестр failed |
message_attachments (lab4) |
(message_id, position) |
FK на messages и attachments, UNIQUE (message_id, attachment_id), индекс по attachment_id |
целостность ссылок (вложение, на которое ссылается сообщение, удалить нельзя) и обратный поиск «используется ли вложение» |
schema_migrations |
version |
checksum файла | какие миграции применены; изменённую задним числом миграцию мигратор не применит |
Почему bytea для текста. Контракт разрешает символ U+0000, а тип text в PostgreSQL не может содержать байт NUL (DataError). Поэтому display_name, title и text хранятся как байты UTF-8. Длину в code points проверяет API, а CHECK в байтах — страховка (1 code point ≤ 4 байта).
Индексы и запросы
messages_chat_keyset (chat_id, created_at, id). Первая страница —WHERE chat_id=$1 ORDER BY created_at, id LIMIT n, следующая —WHERE chat_id=$1 AND (created_at, id) > ($2, $3) ORDER BY ... LIMIT n. Сравнение строк(created_at, id) > (...)попадает вIndex Cond: поиск начинается прямо с позиции cursor и читает толькоn+1строк. Запросов два, а не один с($2 IS NULL OR ...): иначе при generic plan условие cursor уходит вFilter, и поздняя страница сканирует всю историю чата до неё.chat_members_user_keyset (user_id, chat_created_at, chat_id)— список чатов пользователя тем же keyset-способом.users_username_key— вход по username и уникальность.sessions_expires_at— очистка истёкших сессий.
Транзакционные границы
| Операция | Транзакция | Что гарантирует |
|---|---|---|
| Регистрация | один INSERT |
UniqueViolation → 409; ровно одна строка при гонке |
| Создание чата | INSERT chats → INSERT chat_members (все участники одним запросом) → COMMIT |
неизвестный участник вызывает FK-ошибку после вставки чата; откат удаляет и чат, и частичное членство |
| Сообщение (lab3, с ключом) | проверка членства → INSERT idempotency_keys … ON CONFLICT DO UPDATE … WHERE ключ старше 24 ч → если вставлен: UPDATE chats … RETURNING → INSERT messages; если нет: прочитать сохранённое сообщение и сравнить отпечаток → COMMIT. По умолчанию всё это — одна SQL-функция post_message в autocommit (одно обращение к БД) |
ключ, сообщение и «результат» коммитятся вместе или не коммитятся вовсе: «висящего» ключа нет. Конкурентный повтор ждёт на уникальном индексе завершения первой транзакции и затем видит её результат (READ COMMITTED, новый снимок на каждый оператор). Другое тело → 409, тот же — тот же Message |
Сообщение с attachment_ids (lab4, lab5) |
функция post_message_v3 (0005): проверка членства → проверка вложений (этого чата, не pending; failed/карантин → 409; FOR SHARE) → только если всё хорошо — захват ключа → UPDATE chats → INSERT messages (…, attachment_ids) → INSERT message_attachments |
чужое/неизвестное/незавершённое вложение — 404, в карантине — 409, ключ при этом не «сгорает». Порядок attachment_ids хранится массивом в строке сообщения: страница истории остаётся одним диапазонным сканом индекса |
| Загрузка вложения (lab5) | INSERT attachments … 'pending' (autocommit) → S3 PUT в staging (Content-MD5) → одна транзакция: UPDATE … SET status='queued' WHERE status='pending' + INSERT jobs + INSERT outbox + INSERT job_events → 202 |
202 только когда оригинал в staging и задание с outbox зафиксированы. Сбой до COMMIT оставляет невидимый pending, его убирает janitor. Компенсации в обработчике нет |
| Claim (worker) | SELECT jobs … FOR UPDATE → решение (no-op / superseded / работа) → SELECT attachments … FOR UPDATE → UPDATE jobs (processing, attempt+1, lease, token) + INSERT job_attempts + UPDATE attachments (processing) + событие |
дубль доставки видит конечное состояние или чужой lease и ничего не делает |
| Результат (worker) | SELECT jobs … FOR UPDATE (проверка токена) → SELECT attachments … FOR UPDATE → если версия не новее опубликованной: superseded; иначе INSERT attachment_variants ×3 + UPDATE attachments (ready, published_version, object_key) + UPDATE jobs/job_attempts + событие → потом ack |
результат публикуется атомарно и только владельцем текущей аренды; версия только растёт |
| Retry / failed (worker), lease (relay) | под блокировкой задания: попытка retry/failed/abandoned; задание queued с available_at + новая строка outbox, или failed (реестр) |
повтор идёт тем же путём outbox; бесконечного немого retry нет |
| Replay / reprocess (jobctl), уборка staging | SELECT attachments … FOR UPDATE (одна и та же блокировка) → проверки → новое задание + outbox, либо staging_state='deleting' |
уборка и replay сериализованы строкой вложения |
| Порядок блокировок | везде, где нужны обе строки: сначала jobs, потом attachments |
нет взаимных ожиданий в разном порядке |
| Сообщение (lab2-часть) | проверка членства → UPDATE chats SET last_message_at = greatest(clock_timestamp(), last_message_at + 1 мкс) RETURNING → INSERT messages → COMMIT |
строка чата заблокирована до конца транзакции, поэтому писатели одного чата идут по очереди. Время сообщений строго растёт в порядке коммитов: страница по cursor не пропустит сообщение, закоммиченное «задним числом» |
| Вход | SELECT пользователя, проверка Argon2id, запись сессии |
неверный пароль ничего не пишет |
| Logout | DELETE сессии (или DEL в Valkey) |
повтор с тем же токеном — 401 |
Чтение истории не требует snapshot между HTTP-запросами (так в контракте): новое сообщение появится на следующей странице. Список чатов сортируется по chats.created_at = clock_timestamp() без блокировки. Два чата, создаваемые одновременно, могут закоммититься не в порядке времени. Тогда у обхода, который уже начался, такой чат может оказаться «до» cursor; новый обход его увидит. Чаты создаются редко, поэтому мы не сериализуем их глобальным замком; это ограничение описано в REPORT.md.
Сессии
- Токен:
secrets.token_urlsafe(32)— 256 бит случайности, в ответе 43 символа. В хранилище лежит только SHA-256 токена. Для случайного 256-битного значения быстрого хеша достаточно, медленный KDF нужен только для низкоэнтропийных паролей. SESSION_STORE=valkey(по умолчанию): ключsession:<sha256-hex>, значение{user_id, expires_at}. Срок жизни задаётся абсолютнымPXAT expires_at, поэтому рестарт его не продлевает. Включёнappendonly yes+appendfsync always: подтверждённые вход и logout сохраняются до ответа клиенту. Valkey — единственное хранилище сессий, это не кэш над PostgreSQL. Поэтому нет второй копии, которая могла бы «оживить» отозванный токен после отказа. Если Valkey недоступен, проверить сессию нельзя: защищённые запросы и logout получают 503, анонимный доступ не открывается.SESSION_STORE=postgres: таблицаsessions, проверкаexpires_at > now()в запросе.