docs(report):lab4 architecture and decisions

This commit is contained in:
Голиков Maximillian Антон
2026-10-23 16:30:15 +03:00
parent 61edc04c95
commit c5833fd9dc
+138 -1
View File
@@ -138,7 +138,144 @@ Prerequisites:
## Архитектура и решения
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab3, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
Схема:
client (curl / python / smoke)
|
v
nginx LB (:8080) единственная публичная точка
|
+-> api-1 :8080 реплика 1
+-> api-2 :8080 реплика 2
|
+-> postgres :5432 users, chats, chat_members, messages,
| sessions, idempotency_keys, attachments,
| message_attachments
+-> redis :6379 сессии (SESSION_STORE=redis)
+-> minio :9000 S3, приватный bucket messenger-attachments
(порты наружу не публикуются)
|
+-- mc-init (одноразовый) bootstrap: bucket + policy + API-user
+-- migrate (одноразовый) goose up
Источник истины - PostgreSQL для метаданных и S3 для бинарных байтов.
Разделение намеренное: байты не хранятся в БД (не BLOB, не локальный
каталог api), только в приватном bucket; в Postgres - object_key,
sha256, content_type, size_bytes, status, привязка к chat_id и к
message_attachments. Через S3 любая API-реплика читает любую вложенность
одинаково; локальный volume API не годится, потому что файл лежит только
на одной реплике и теряется при её остановке - это критерий README
уровня 3 «Upload → остановка обслужившей API → download через другую
возвращает тот же файл».
Сессии - в Redis (без изменений от lab2-3). Без sticky session на LB
любая реплика видит любую сессию.
Транзакционные границы:
- Создание чата - одна транзакция в Postgres (chats + chat_members).
- Идемпотентная отправка сообщения - одна транзакция: слот в
idempotency_keys, проверка и линковка attachments, INSERT в messages,
INSERT в message_attachments. Либо всё, либо ничего.
- Загрузка вложения - две точки сохранения без общей транзакции (S3
и Postgres - разные системы). Последовательность:
INSERT attachments (status='pending', object_key, sha256) → COMMIT
PutObject в S3 → OK/FAIL
UPDATE attachments status='ready' → COMMIT
Это ключевая граница lab4. Ниже - как каждый отказ на этой границе
компенсируется.
- Регистрация - один INSERT с UNIQUE-индексом на username (23505 →
409 через mapError).
Компенсация и сверка (уровень 4):
- Отказ между INSERT и PutObject. Строка pending осталась, объекта в
S3 нет. Handler ловит ошибку PutObject и сразу вызывает
MarkFailed(id, "upload_failed") - компенсация в том же запросе, без
ожидания reconciler.
- Отказ между PutObject и UPDATE status='ready'. Объект в S3 есть,
строка pending. Это и есть «вечный неучтённый объект», если ничего
не делать. Закрывает reconciler: ListStalePending(now - grace) →
Delete(object_key) → DeletePending(id). Grace 1 час: свежие pending
(реальные upload'ы) не трогаются, только застрявшие.
- Обратный случай: PutObject прошёл, INSERT в Postgres упал. Объект
в S3 есть, строки в БД нет - orphan. Закрывает reconciler:
List(S3) → отфильтровать LastModified < now - grace → ExistingKeys(DB)
→ Delete тех, которых нет в БД. Grace 1 час защищает свежий Put,
чей INSERT ещё не закоммичен.
- Reconciler запускается во всех репликах, но использует
pg_try_advisory_lock: одна реплика на tick берёт session-level
advisory lock, остальные пропускают tick. Postgres автоматически
освобождает лок, если процесс упал.
Отдельные S3-креды и приватность bucket:
- Root-креды MinIO (minio_root_user/minio_root_password) видят только
minio и mc-init. API-контейнер их не получает.
- API использует messenger-api с policy только на messenger-attachments
(GetObject, PutObject, DeleteObject на bucket/*, ListBucket на bucket).
Создание/удаление bucket, policy, пользователей недоступны.
- Bucket приватный: без подписи GET возвращает 403. Проверяется в
evidence/s3-private.txt.
- MINIO_BROWSER=off: административная консоль не слушается. Порты
9000/9001 не публикуются на хост (только внутри internal-сети).
Что перенесено из lab3 без изменений:
- Схема БД: users, chats, chat_members, messages, sessions
- idempotency_keys с TTL 24 часа, Idempotency-Key обязателен
- X-Instance-Id в каждом ответе API (os.Hostname())
- Миграции goose, отдельный процесс /server migrate
- Graceful drain на SIGTERM, atomic ready-флаг, SHUTDOWN_DRAIN_SECONDS
- CPU/RAM лимиты на api, postgres, redis через deploy.resources
- nginx LB перед двумя репликами, upstream keepalive
- Горизонтальное масштабирование: две реплики, общие сессии в Redis
Что добавлено/изменено в lab4:
1. Отдельный сервис minio (pgsty/silo), persistent volume minio_data.
2. Одноразовый сервис mc-init: создаёт bucket, policy, API-user.
Идемпотентен.
3. Миграция 0003: таблицы attachments и message_attachments, индексы,
ограничения (status, size, sha256, content_type, filename).
4. Миграция 0004: ослаблен CHECK messages_text_not_blank - пустой
текст разрешён при наличии вложений (lab4 anyOf), но
whitespace-only по-прежнему запрещён.
5. Три endpoint: POST /chats/{chat_id}/attachments (raw bytes PNG/JPEG,
max 10 MiB, max 40M пикселей), GET /attachments/{id} и
GET /attachments/{id}/content (без redirect, только участникам чата).
6. POST /messages принимает attachment_ids (0-10), все вложения должны
принадлежать этому чату и быть ready; anyOf text или attachments.
7. RequestHash расширен: sha256(text) без attachments (обратная
совместимость с lab3), sha256(text + 0x00 + ids) с attachments.
8. Reconciler в API, pg advisory lock, две задачи (stale pending,
orphan objects), grace 1 час.
9. Healthcheck /health/ready пингует S3 (BucketExists).
10. nginx client_max_body_size=12m (10 MiB upload + запас на 11 MiB
negative-тест, чтобы 413 шёл от API с X-Request-Id, а не от nginx).
Соответствие переменных .env.example реальной конфигурации (новое
в lab4):
- S3_ENDPOINT, S3_BUCKET, S3_REGION, S3_USE_SSL - читаются в
config.Load, идут в s3.Config. Для внутреннего MinIO
http://minio:9000, SSL=false.
- S3_ACCESS_KEY_ID_FILE, S3_SECRET_ACCESS_KEY_FILE - secrets в
/run/secrets, читаются через readSecretOptional.
- MAX_UPLOAD_BYTES - идёт в AttachmentService (io.LimitReader body =
maxBytes+1, 413 при превышении).
- MAX_IMAGE_PIXELS - идёт в AttachmentService (image.DecodeConfig,
413 при W*H > maxPixels).
- RECONCILER_ENABLED, RECONCILER_INTERVAL_SECONDS,
RECONCILER_GRACE_SECONDS - читаются в config.Load, идут в
service.Reconciler.
- MINIO_ROOT_USER - только для minio и mc-init, не попадает в api.
## Доказательства критериев