Files
mtusi2026lab4/ARCHITECTURE.md
T

76 lines
7.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# План хранения и транзакций
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 не останавливает поток.