From c5833fd9dc9e6612dc53a93989255f01134ffce9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=93=D0=BE=D0=BB=D0=B8=D0=BA=D0=BE=D0=B2=20Maximillian?= =?UTF-8?q?=20=D0=90=D0=BD=D1=82=D0=BE=D0=BD?= Date: Fri, 23 Oct 2026 16:30:15 +0300 Subject: [PATCH] docs(report):lab4 architecture and decisions --- REPORT.md | 139 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 138 insertions(+), 1 deletion(-) diff --git a/REPORT.md b/REPORT.md index 17c7ab9..b05963c 100644 --- a/REPORT.md +++ b/REPORT.md @@ -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. ## Доказательства критериев