Files
mtusi2026lab4/ARCHITECTURE.md
T

7.7 KiB
Raw Blame History

План хранения и транзакций

PostgreSQL — источник истины для пользователей, сессий, чатов, членства и сообщений. Данные пользователей неизменяемы в обязательном API. Valkey кэширует именно их публичное представление на 60 секунд; действительность сессии проверяется в PostgreSQL при каждом запросе. Поэтому отказ кэша не отменяет logout/expiry и не даёт доступ анонимному клиенту. При отказе PostgreSQL защищённые запросы получают 503.

users: UUID PK, UNIQUE username, display_name, password_hash (Argon2id), created_at. sessions: SHA-256 случайного 256-битного токена PK, user FK, expires_at, created_at. chats: UUID PK, title, created_at. members: (chat_id, user_id) PK и внешние ключи на chats/users. messages: UUID PK, chat FK, sender FK, text, created_at; составной FK на members не позволяет записать отправителя вне чата даже при ошибке в приложении.

Создание чата и всех его участников — одна транзакция. Создание сообщения — одна транзакция после проверки доступа. Регистрация защищена UNIQUE, гонка завершается одним 201 и остальными 409. Logout удаляет сессию в транзакции; Valkey не хранит разрешение на вход. Ранее начавшийся запрос может завершиться одновременно с logout.

История: индекс (chat_id, created_at, id), keyset по (created_at,id), LIMIT n+1. Отдельный индекс members(user_id,chat_id) ускоряет список доступных чатов. Часы БД единые, но страницы между запросами не являются snapshot: конкурентная незавершённая транзакция может стать видимой позднее курсора. Для неизменной истории пропусков нет.

Пул ограничен 5 соединениями, ожидание 2 секунды; statement_timeout=2s, lock_timeout=1s. KDF ограничен четырьмя параллельными задачами. Cursor подписан общим локально генерируемым секретом, который сохраняется при рестарте.

Миграции нумеруются, учитываются в schema_migrations, защищены advisory lock. Отдельный одноразовый сервис migrate запускается до API. Повторный запуск проверяет хеши применённых миграций, не пересоздаёт таблицы и не seed-ит данные.

Вложения и согласованность двух хранилищ

SeaweedFS хранит байты в приватном bucket messenger. API имеет только Read/Write для messenger/originals/* и List для messenger; отдельные административные credentials доступны одноразовому storage-init. В S3-конфигурации нет anonymous. API и S3 не публикуют host ports; filer/master/volume слушают loopback внутри S3-контейнера.

Проверка Bearer/ACL и filename выполняется до чтения файла. Два upload slots на API ограничивают одновременные временные файлы, один decoder slot — распаковку PNG/JPEG. Оригинал пишется порциями в tmpfs /tmp (32 MiB); каждый файл ≤10 MiB. Проверка размеров до декодирования ограничивает изображение 40 миллионами пикселей. API имеет 512 MiB RAM. Временный файл — буфер текущего запроса, а не хранилище подтверждённого вложения.

Ключ originals/UUID генерирует сервер. После валидации API берёт advisory xact lock от ключа, пишет S3, затем INSERT метаданных в той же PostgreSQL-транзакции. 201 возвращается после COMMIT. DB/S3 не имеют общей атомарной транзакции: падение после PUT может оставить orphan. При неопределённом результате COMMIT запрещено безусловно удалять S3-объект, поскольку метаданные могли успешно сохраниться.

Reconciler (src.reconcile) по умолчанию dry-run. --apply удаляет только объекты без метаданных, старше grace (по умолчанию 600 с, минимум 60 с при deadline запроса 30 с). Под тем же lock он заново проверяет и наличие метаданных, и LastModified объекта. Существующие метаданные защищают объект независимо от ссылки из сообщения; свежие и занятые ключи пропускаются. Это исключает удаление действующей загрузки при обычном продвижении процессов; произвольная многоминутная приостановка OS не является SLA.

Если байты пропали, метаданные остаются, storage_state становится missing, API отвечает 503 вместо ложной готовности. После восстановления из резервной копии reconciler проверяет реальный размер и SHA-256 и возвращает ready. Он не способен изобрести потерянные байты. Повторный --apply не создаёт новых эффектов для исправленных записей. Обход S3 постраничный, метаданных — keyset блоками по 100; сетевые ошибки не считаются доказательством отсутствующего объекта. Только S3 404/NoSuchKey означает missing.

Message хранит attachment_ids, а message_attachments обеспечивает внешние ключи. Все вложения проверяются на принадлежность текущему чату до атомарной записи сообщения. В хеш идемпотентности входит список вложений; отсутствие списка и [] канонически равны.

Отдельный процесс src.reconcile_loop выполняет apply каждые 60 секунд с grace 600. Readiness читает байты зарезервированного S3 control object: metadata LIST не доказывает готовность volume server после перезапуска. Контрольный объект исключён из orphan cleanup. Decoder/PUT при отмене запроса завершаются перед закрытием временного файла и освобождением semaphore, поскольку asyncio не останавливает поток.