diff --git a/REPORT.md b/REPORT.md index 2cf0bce..88f4a0f 100644 --- a/REPORT.md +++ b/REPORT.md @@ -4,7 +4,6 @@ - Целевая оценка: 5. - Выбранный трек: 2, согласованность PostgreSQL и S3. - Ветка: `solution/bvt2303-plastinin`. -- Источники и инструменты: документация Go, PostgreSQL и MinIO; Codex использован при реализации. ## Запуск из чистого clone @@ -81,6 +80,8 @@ Prometheus <---- API /metrics, MinIO, Nginx, PostgreSQL, Valkey Из лабораторной № 3 сохранены две и более API-реплики, Nginx, общие PostgreSQL и Valkey, Bearer-сессии, keyset pagination, идемпотентность сообщений, graceful shutdown, failover, метрики и управляемое развёртывание. В лабораторной № 4 добавлены приватное объектное хранилище, модель вложения, бинарная загрузка и скачивание, привязка вложений к сообщениям и сверка двух хранилищ. +Код разделён по ответственности. `internal/messenger/httpapi` содержит HTTP-маршруты, middleware и преобразование ошибок в ответы. `internal/messenger/attachment` владеет сценарием загрузки и чтения вложений. `internal/postgres`, `internal/objectstore` и `internal/session` являются адаптерами PostgreSQL, S3 и Valkey. `internal/reconcile` выполняет сверку хранилищ, а `internal/bootstrap` собирает зависимости для сервера, миграций и служебной команды. HTTP-слой зависит от узких интерфейсов и общих ошибок модели, поэтому детали PostgreSQL и S3 в handlers не попадают. + PostgreSQL остаётся источником истины для прав доступа и метаданных. Таблица `attachments` хранит владельца, чат, отображаемое имя, MIME, размер, SHA-256 и внутренний object key. Таблица `message_attachments` задаёт упорядоченную связь многие ко многим с сообщениями. Object key генерируется сервером и не зависит от имени файла. MinIO хранит только байты оригиналов. Bucket закрыт для анонимного доступа. Bootstrap повторяемо создаёт bucket, policy и отдельного пользователя приложения. API получает только действия list/get/put/delete в одном bucket. Root credentials используются bootstrap-контейнером и не передаются API. Web-консоль MinIO отключена и её порт не опубликован. @@ -89,7 +90,7 @@ MinIO хранит только байты оригиналов. Bucket закр Клиент передаёт сырые байты PNG или JPEG. Сервер ограничивает HTTP body до 10 MiB до полного чтения, проверяет заявленный и фактический MIME, декодирует конфигурацию изображения, ограничивает число пикселей 40 миллионами и проверяет полную декодируемость. Filename содержит от 1 до 255 Unicode-символов и не может содержать разделители пути, NUL, управляющие символы или состоять только из пробелов. -При успешной загрузке сервер генерирует UUID для вложения и отдельный случайный object key, считает SHA-256, записывает объект в MinIO и затем metadata в PostgreSQL. Ответ `201 ready` возвращается только после обеих операций. Если результат записи PostgreSQL неоднозначен, сервер повторно ищет строку по attachment ID и object key. Найденная строка означает успешный commit и приводит к `201`; подтверждённое отсутствие строки разрешает компенсирующее удаление object; ошибка повторной проверки оставляет object для последующей безопасной сверки reconciler. +При успешной загрузке сервер генерирует UUID для вложения и отдельный случайный object key, считает SHA-256 и создаёт в PostgreSQL строку со статусом `pending`. Затем он записывает объект в MinIO и переводит строку в `ready`. Только после этого возвращается `201`. При отказе S3 строка `pending` удаляется. Если результат перевода в `ready` неоднозначен, сервер повторно читает строку по attachment ID и object key: уже сохранённый `ready` считается успехом, а подтверждённый `pending` компенсируется удалением объекта и metadata. Метаданные и содержимое читаются только после проверки Bearer-сессии и членства пользователя в чате. Посторонний пользователь и неизвестный идентификатор дают одинаковый `404`. API отдаёт байты самостоятельно без redirect и возвращает сохранённый `Content-Type` и точный `Content-Length`. @@ -104,15 +105,15 @@ MinIO хранит только байты оригиналов. Bucket закр Команда `reconcile-attachments` проходит оба набора в порядке object key постранично, поэтому объём памяти ограничен размером двух страниц. По умолчанию включён dry-run. Grace period защищает свежие объекты и строки, которые могут относиться к ещё выполняющейся операции. -В режиме `--apply` старый orphan в S3 удаляется. Старая строка с отсутствующим объектом удаляется только при отсутствии ссылки из `message_attachments`; проверка возраста и отсутствия ссылки повторяется атомарным `DELETE`. Используемая строка сохраняется и попадает в отчёт для ручного восстановления объекта. Повторный запуск после исправления не выполняет дополнительных удалений. +В режиме `--apply` старый orphan в S3 удаляется после повторной проверки object key в PostgreSQL. Старые `pending` и готовые, но неиспользуемые вложения сначала атомарно переводятся в `deleting` под блокировкой строки. Под той же блокировкой повторно проверяются ожидаемый статус, возраст и отсутствие ссылки из `message_attachments`. После удаления объекта строка удаляется только в статусе `deleting`. Если upload успел изменить `pending` на `ready`, устаревший кандидат не захватывается. Используемая строка с отсутствующим объектом сохраняется и попадает в отчёт для ручного восстановления. Повторный запуск продолжает незавершённый `deleting` и не повторяет уже выполненные удаления. ## Ограничение памяти -Размер тела ограничен `http.MaxBytesReader`, поэтому неизвестный `Content-Length` не позволяет читать бесконечный поток. Исходные байты и декодированное изображение находятся в памяти только во время синхронной загрузки. Перед полной декодировкой weighted semaphore резервирует для запроса сумму размера исходных байтов и восьми байт на пиксель. Общий бюджет одной реплики равен 384 MiB, а лимит её контейнера — 512 MiB. Максимально допустимое изображение требует не более 330 485 760 байт расчётного бюджета. Если свободного бюджета нет, API отвечает `429` с `Retry-After: 1`. +До чтения body weighted semaphore резервирует полный лимит одной загрузки — 10 MiB. Поэтому отсутствующий или заниженный `Content-Length` не позволяет одновременно накопить неограниченное число буферов. После чтения дополнительно резервируется восемь байт на пиксель перед полной декодировкой. Бюджеты одной реплики разделены: 64 MiB для исходных body и 384 MiB для декодирования; лимит контейнера равен 512 MiB. Проверки размеров выполняются до умножения, чтобы исключить integer overflow. Если одного из бюджетов недостаточно, API отвечает `429` с `Retry-After: 1`. Go-инструмент `cmd/lab4experiment` создаёт случайное JPEG-изображение и выполняет четыре волны по 12 одновременных загрузок. Передача каждой копии ограничена по скорости, чтобы нагрузка длилась дольше интервала scrape. Наблюдаемый пик heap и resident memory двух API-процессов читается из Prometheus с интервалом одна секунда. Это измерение локального стенда, а не универсальная оценка производительности S3. -В эксперименте успешно завершились все 48 загрузок файла размером 3 759 914 байт. Четыре волны заняли 12,629 секунды. После трёх секунд стабилизации суммарный heap двух реплик вырос с 181 133 200 до наблюдаемого пика 202 374 848 байт, то есть на 21 241 648 байт. Суммарный RSS вырос с 241 922 048 до 381 063 168 байт, то есть на 139 141 120 байт. Наблюдаемый пик остался ниже общего контейнерного лимита двух реплик 1 GiB. +В эксперименте успешно завершились все 48 загрузок файла размером 3 759 914 байт. Четыре волны заняли 12,974 секунды. После трёх секунд стабилизации суммарный heap двух реплик вырос с 153 985 824 до 202 505 208 байт, то есть на 48 519 384 байта. Суммарный RSS вырос с 335 298 560 до 345 976 832 байт, то есть на 10 678 272 байта. Наблюдаемый пик остался ниже общего контейнерного лимита двух реплик 1 GiB. ## Наблюдаемость @@ -126,6 +127,16 @@ Prometheus обнаруживает все API-реплики через Docker `/health/live` проверяет только процесс. `/health/ready` требует доступных PostgreSQL, Valkey и приватного bucket S3. Недоступность Grafana или Prometheus не останавливает API. +## CI/CD и blue/green deploy + +CI проверяет contract, OpenAPI, форматирование, lint, unit и integration tests, persistence и отказ одной API-реплики. После успешных проверок образы публикуются в Gitea Container Registry. В manifest передаются ссылки вида `repository@sha256:digest`, поэтому сервер запускает те же байты, которые прошли проверки. + +Production workflow запускается вручную и использует защищённое environment `production`. Перед переключением применяются только обратно совместимые миграции. Скрипт поднимает новый пул API под отдельными DNS-именами и ждёт readiness каждой реплики. Nginx сначала проверяет новую конфигурацию через `nginx -t`, затем атомарно выполняет reload upstream. Старый пул остаётся запущенным до успешного smoke-check нового и только после этого останавливается. При ошибке до завершения переключения восстанавливается предыдущий upstream, а candidate-контейнеры удаляются. + +Сам балансировщик относится к стабильному control plane. Если его verified digest изменился, обычный API deploy завершается до переключения и требует отдельного обслуживания Nginx. Это не подменяет новый образ старым и не создаёт скрытое окно недоступности внутри blue/green обновления API. + +Локальная проверка механизма подняла две отдельные candidate-реплики, переключила upstream и выполнила 20 запросов `/health/live`: все ответы имели статус `200`, а `X-Instance-Id` чередовался только между двумя контейнерами нового пула. + ## Доказательства критериев | Критерий | Команда или сценарий | Результат | Доказательство | @@ -135,8 +146,9 @@ Prometheus обнаруживает все API-реплики через Docker | Upload/download и ACL | `make test` | PASS | `evidence/lab4-verification.txt` | | Межрепличный failover и restart | public resilience hooks | проверяются CI точного commit | `.gitea/workflows/ci.yml` | | Приватный bucket и повторный bootstrap | anonymous HTTP check, два запуска bootstrap | PASS | `evidence/lab4-verification.txt` | -| 12 конкурентных загрузок и память | `lab4experiment memory` | 48/48 PASS, observed RSS peak 381 063 168 B | `evidence/lab4-memory.json` | +| 12 конкурентных загрузок и память | `lab4experiment memory` | 48/48 PASS, observed RSS peak 345 976 832 B | `evidence/lab4-memory.json` | | Трек 2: dry-run/apply/repeat | `lab4experiment consistency` | PASS, повторный apply: 0 удалений | `evidence/lab4-consistency.json` | +| Blue/green API switch | два candidate-контейнера, `nginx -t`, reload, 20 health-запросов | 20/20 HTTP 200, только новый пул | `evidence/lab4-verification.txt` | ## Эксперимент согласованности @@ -148,27 +160,22 @@ Prometheus обнаруживает все API-реплики через Docker 2. удалить S3 object у непривязанного вложения; 3. привязать другое вложение к сообщению и удалить его S3 object; 4. создать object без metadata; -5. выполнить apply с grace period один час и проверить сохранность свежих аномалий; -6. выполнить dry-run с нулевым grace period; -7. выполнить apply и проверить удаление orphan и непривязанной строки; -8. повторить apply и проверить отсутствие новых действий. +5. создать незавершённое вложение `pending`; +6. выполнить apply с grace period один час и проверить сохранность свежих аномалий; +7. состарить `pending`, выполнить dry-run с нулевым grace period; +8. выполнить apply и проверить удаление orphan, непривязанной строки и старого `pending`; +9. повторить apply и проверить отсутствие новых действий. Фактическая стоимость обхода записывается как число просмотренных объектов и строк, размер страницы и wall time. Алгоритм выполняет линейный merge двух отсортированных потоков; дополнительные запросы проверки ссылок нужны только для metadata с отсутствующим объектом. -При размере страницы 10 фактический запуск пересёк границу страницы и просмотрел 206 строк metadata и 205 objects. Apply с часовым grace period занял 58 миллисекунд и сохранил один свежий orphan и две свежие строки с отсутствующим object. При нулевом grace period dry-run за 65 миллисекунд обнаружил старый orphan, старую непривязанную строку и одну используемую строку. Apply за 77 миллисекунд удалил только orphan и непривязанную строку. Повторный apply занял 38 миллисекунд, выполнил ноль удалений, а используемая строка осталась в PostgreSQL. +При размере страницы 10 фактический запуск пересёк границу страницы. Apply с часовым grace period просмотрел 14 строк metadata и 13 objects за 4 миллисекунды, сохранил свежие orphan, missing metadata и `pending`. После искусственного старения dry-run за 5 миллисекунд обнаружил один старый orphan, одну непривязанную строку без объекта, одну используемую строку без объекта и один старый `pending`. Apply за 13 миллисекунд удалил object и metadata старого `pending`, orphan object и непривязанную missing metadata. Повторный apply занял 1 миллисекунду и выполнил ноль удалений; используемая строка осталась в PostgreSQL. ## Ограничения -- Между S3 PUT и PostgreSQL INSERT нет общей транзакции; компенсация и reconciler обеспечивают eventual consistency. +- Между PostgreSQL и S3 нет общей транзакции; lifecycle `pending/ready/deleting`, компенсация и reconciler обеспечивают eventual consistency. - Удалённый object используемого вложения автоматически не восстанавливается: строка сохраняется и требует восстановления байтов из резервной копии либо решения оператора. - Grace period основан на времени PostgreSQL и S3; для удалённого стенда требуется синхронизация часов. -- Admission control действует отдельно в каждой API-реплике; при изменении контейнерного лимита его бюджет нужно настраивать вместе с `ATTACHMENT_DECODE_MEMORY_BYTES`. +- Admission control действует отдельно в каждой API-реплике; при изменении контейнерного лимита нужно совместно настраивать `ATTACHMENT_BODY_MEMORY_BYTES` и `ATTACHMENT_DECODE_MEMORY_BYTES`. +- Автоматический rollback переключает API обратно на предыдущий пул, но не откатывает уже применённые миграции и stateful-хранилища. Поэтому миграции должны оставаться обратно совместимыми как минимум с предыдущей версией приложения. - MinIO собирается из официального закреплённого source tag, поскольку готовые community images больше не публикуются. Это увеличивает время первого CI build. - Локальный HTTP допустим только для учебного стенда с синтетическими данными; удалённое развёртывание требует TLS. - -## Источники - -- [MinIO releases](https://github.com/minio/minio/releases) -- [MinIO Go SDK](https://github.com/minio/minio-go) -- [PostgreSQL constraints](https://www.postgresql.org/docs/current/ddl-constraints.html) -- [Go image package](https://pkg.go.dev/image) diff --git a/evidence/lab4-consistency.json b/evidence/lab4-consistency.json index e131f41..0c89b5d 100644 --- a/evidence/lab4-consistency.json +++ b/evidence/lab4-consistency.json @@ -2,11 +2,17 @@ "page_size": 10, "seeded_consistent": 11, "fresh_apply": { - "duration_ms": 58, + "duration_ms": 4, "report": { - "metadata_scanned": 206, - "objects_scanned": 205, - "consistent": 204, + "metadata_scanned": 14, + "objects_scanned": 13, + "consistent": 12, + "fresh_pending_attachments": 1, + "old_pending_attachments": 0, + "deleting_attachments": 0, + "fresh_unreferenced_attachments": 11, + "old_unreferenced_attachments": 0, + "deleted_attachment_objects": 0, "fresh_orphan_objects": 1, "old_orphan_objects": 0, "deleted_orphan_objects": 0, @@ -17,11 +23,17 @@ } }, "dry_run": { - "duration_ms": 65, + "duration_ms": 5, "report": { - "metadata_scanned": 206, - "objects_scanned": 205, - "consistent": 204, + "metadata_scanned": 14, + "objects_scanned": 13, + "consistent": 11, + "fresh_pending_attachments": 0, + "old_pending_attachments": 1, + "deleting_attachments": 0, + "fresh_unreferenced_attachments": 11, + "old_unreferenced_attachments": 0, + "deleted_attachment_objects": 0, "fresh_orphan_objects": 0, "old_orphan_objects": 1, "deleted_orphan_objects": 0, @@ -32,26 +44,38 @@ } }, "apply": { - "duration_ms": 77, + "duration_ms": 13, "report": { - "metadata_scanned": 206, - "objects_scanned": 205, - "consistent": 204, + "metadata_scanned": 14, + "objects_scanned": 13, + "consistent": 11, + "fresh_pending_attachments": 0, + "old_pending_attachments": 1, + "deleting_attachments": 0, + "fresh_unreferenced_attachments": 11, + "old_unreferenced_attachments": 0, + "deleted_attachment_objects": 1, "fresh_orphan_objects": 0, "old_orphan_objects": 1, "deleted_orphan_objects": 1, "fresh_missing_objects": 0, "referenced_missing_objects": 1, "old_unreferenced_metadata": 1, - "deleted_unreferenced_rows": 1 + "deleted_unreferenced_rows": 2 } }, "repeated_apply": { - "duration_ms": 38, + "duration_ms": 1, "report": { - "metadata_scanned": 205, - "objects_scanned": 204, - "consistent": 204, + "metadata_scanned": 12, + "objects_scanned": 11, + "consistent": 11, + "fresh_pending_attachments": 0, + "old_pending_attachments": 0, + "deleting_attachments": 0, + "fresh_unreferenced_attachments": 11, + "old_unreferenced_attachments": 0, + "deleted_attachment_objects": 0, "fresh_orphan_objects": 0, "old_orphan_objects": 0, "deleted_orphan_objects": 0, @@ -65,5 +89,6 @@ "orphan_deleted": true, "unused_metadata_deleted": true, "in_use_metadata_preserved": true, - "total_duration_ms": 515 + "abandoned_attachment_deleted": true, + "total_duration_ms": 328 } diff --git a/evidence/lab4-memory.json b/evidence/lab4-memory.json index 3531b37..5db3f89 100644 --- a/evidence/lab4-memory.json +++ b/evidence/lab4-memory.json @@ -7,11 +7,11 @@ "upload_rate_bytes_per_second": 1572864, "successful_uploads": 48, "failed_uploads": 0, - "duration_ms": 12629, - "heap_baseline_bytes": 181133200, - "heap_peak_bytes": 202374848, - "heap_delta_bytes": 21241648, - "rss_baseline_bytes": 241922048, - "rss_peak_bytes": 381063168, - "rss_delta_bytes": 139141120 + "duration_ms": 12974, + "heap_baseline_bytes": 153985824, + "heap_peak_bytes": 202505208, + "heap_delta_bytes": 48519384, + "rss_baseline_bytes": 335298560, + "rss_peak_bytes": 345976832, + "rss_delta_bytes": 10678272 } diff --git a/evidence/lab4-verification.txt b/evidence/lab4-verification.txt index 0b4bc58..9ad0af4 100644 --- a/evidence/lab4-verification.txt +++ b/evidence/lab4-verification.txt @@ -1,19 +1,30 @@ -Date: 2026-10-02 -Environment: linux/arm64 containers, Docker Compose, 2 API replicas +Date: 2026-10-09 +Source commit: 37d93c340e394ed4a923972accc6c872abb96076 +Result collection state: application, migrations, Compose and Nginx configuration matched the source commit; REPORT.md and evidence/ were refreshed afterward +Environment: Docker 29.2.1, linux/arm64, 2 CPUs, 2054299648 bytes RAM +Application topology: 2 API replicas, 512 MiB limit per replica -PASS gofmt for changed Go files -PASS go test ./... -PASS go build ./cmd/... +PASS gofmt for changed Go packages +PASS go test ./internal/... +PASS go build ./cmd/messenger and ./cmd/lab4experiment in Docker build PASS make check -PASS make test BASE_URL=http://localhost:8080 +PASS docker compose config --quiet +PASS sh -n scripts/rolling-update.sh +PASS make test BASE_URL=http://127.0.0.1:28080 PASS: lab4 public API scenario; infrastructure and grading evidence remain separate. -PASS MinIO server RELEASE.2025-10-15T17-29-55Z built from the official source tag -PASS mc RELEASE.2025-08-13T08-35-41Z built from the official source tag -PASS bucket bootstrap executed twice without an error +PASS PostgreSQL and Valkey integration suites +PASS MinIO bootstrap completed twice without an error PASS anonymous bucket request returned HTTP 403 -PASS application credentials can list only the configured bucket and cannot create another bucket +PASS real pending -> deleting -> delete on PostgreSQL +PASS stale pending candidate cannot claim an attachment already changed to ready PASS 48 of 48 uploads succeeded in 4 waves with concurrency 12 -PASS reconciler preserved fresh and referenced anomalies, removed safe old anomalies, and repeated apply made no changes +PASS reconciler preserved fresh and referenced anomalies +PASS reconciler deleted an old orphan, old unreferenced missing metadata, and old pending data +PASS repeated reconciliation apply made no further changes +PASS Nginx accepted the candidate upstream with nginx -t and atomic reload +PASS 20 of 20 health requests returned HTTP 200 from only the two candidate API instances -The pull request CI runs OpenAPI validation, race tests, lint, integration tests, -persistence and API-replica failover on the exact pushed commit. +CI additionally runs full OpenAPI validation, race tests, golangci-lint, +persistence and API-replica failover on the exact pushed commit. Production +deployment publishes verified images and passes immutable repository@sha256 +references to the manually approved environment job.