forked from mtusi2026/mtusi2026lab4
- тело загрузки: один буфер ровно Content-Length, без копий до S3 и djpeg; - PNG: zlib получает вход кусками по 64 KiB (unconsumed_tail копировал остаток IDAT); - djpeg, убитый OOM-killer'ом, -> 503 (ресурсы сервера), а не 415; - api: memswap_limit = memory (жёсткий лимит без swap); S3: GOMEMLIMIT и лимиты одновременных загрузок SeaweedFS, память 1g; - docs: CONSISTENCY.md, DEFENSE.md, WINDOWS.md, DATA_MODEL.md под lab4; scripts/demo_attachments.py для сценария защиты; CI и collect_evidence под lab4; - bench/reconcile_faults.py: отчёты трека 2 (ошибки с обеих сторон, прерванный apply). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
48 lines
12 KiB
Markdown
48 lines
12 KiB
Markdown
# Модель данных lab4
|
||
|
||
Схема: [0001_init.sql](../migrations/0001_init.sql) (lab2), [0002_idempotency_keys.sql](../migrations/0002_idempotency_keys.sql) и [0003_post_message_function.sql](../migrations/0003_post_message_function.sql) (lab3), [0004_attachments.sql](../migrations/0004_attachments.sql) (lab4). Миграции применяет один раз отдельный сервис `migrate` до старта реплик API; миграции lab3 и lab4 только добавляют объекты (0004 ещё ослабляет `CHECK` длины текста), поэтому совместимы с работающей предыдущей версией. Байты вложений живут **только** в приватном bucket S3 (SeaweedFS), в PostgreSQL — их метаданные; согласованность двух хранилищ — [CONSISTENCY.md](CONSISTENCY.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) | `id uuid` | FK `(chat_id, owner_id) → chat_members`; `UNIQUE object_key` (`COLLATE "C"`, формат `o/<32 hex>`); `CHECK` статуса `pending/ready`, типа `image/png|jpeg`, размера 1…10 MiB, пикселей ≤ 40 млн, длины SHA-256, карантина (`lost_at`/`lost_reason` только у `ready`) | метаданные оригинала; `object_key` генерирует сервер (128 случайных бит), с id и filename не связан. `pending` — намерение загрузки (строка раньше объекта), `ready` — объект записан. Частичный индекс `(created_at) WHERE status='pending'` — для janitor |
|
||
| `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) | в той же функции `post_message_v2`: проверка членства → проверка вложений (`ready`, этого чата, не в карантине; `FOR SHARE`) → только если всё хорошо — захват ключа → `UPDATE chats` → `INSERT messages (…, attachment_ids)` → `INSERT message_attachments` | чужое/неизвестное/незавершённое вложение — 404, в карантине — 409, ключ при этом не «сгорает». Порядок `attachment_ids` хранится массивом в строке сообщения: страница истории остаётся одним диапазонным сканом индекса |
|
||
| Загрузка вложения (lab4) | `INSERT attachments … 'pending'` (autocommit) → S3 PUT (Content-MD5) → `UPDATE … SET status='ready' WHERE status='pending'` (autocommit) → 201 | 201 только когда и объект, и строка `ready` зафиксированы. Сбой между шагами оставляет `pending`, его убирает janitor после `PENDING_GRACE_SECONDS`. Компенсации в обработчике запроса нет: после потерянного ответа COMMIT неизвестно, `ready` ли строка |
|
||
| Сообщение (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()` в запросе.
|