docs(report):lab4 architecture and decisions
This commit is contained in:
@@ -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.
|
||||
|
||||
## Доказательства критериев
|
||||
|
||||
|
||||
Reference in New Issue
Block a user