forked from mtusi2026/mtusi2026lab4
This commit is contained in:
@@ -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)
|
||||
|
||||
@@ -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
|
||||
}
|
||||
|
||||
@@ -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
|
||||
}
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user