From b3d5d76302a79dd49909c76f8e1ff4d66ab5fada Mon Sep 17 00:00:00 2001 From: dizi Date: Fri, 2 Oct 2026 19:55:52 +0300 Subject: [PATCH] test: verify attachment consistency and memory --- REPORT.md | 179 +++++++- cmd/lab4experiment/main.go | 654 +++++++++++++++++++++++++++ evidence/lab4-consistency.json | 69 +++ evidence/lab4-memory.json | 17 + evidence/lab4-verification.txt | 19 + internal/reconcile/reconcile_test.go | 129 ++++++ 6 files changed, 1046 insertions(+), 21 deletions(-) create mode 100644 cmd/lab4experiment/main.go create mode 100644 evidence/lab4-consistency.json create mode 100644 evidence/lab4-memory.json create mode 100644 evidence/lab4-verification.txt create mode 100644 internal/reconcile/reconcile_test.go diff --git a/REPORT.md b/REPORT.md index 9ad2b84..2cf0bce 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,174 @@ -# Отчёт — лабораторная 4 +# Отчёт — лабораторная работа № 4 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- Автор: Пластинин Денис, БВТ2303. +- Целевая оценка: 5. +- Выбранный трек: 2, согласованность PostgreSQL и S3. +- Ветка: `solution/bvt2303-plastinin`. +- Источники и инструменты: документация Go, PostgreSQL и MinIO; Codex использован при реализации. ## Запуск из чистого clone -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +Требуются Docker Engine с Compose V2, Git и свободные локальные порты 8080, 8081, 9090 и 3000. Для запуска Go-проверок вне контейнера нужен Go 1.26. Образы приложения и MinIO собираются из исходников внутри Docker. Версии Go, PostgreSQL, Valkey, Nginx, MinIO и остальных компонентов закреплены в Dockerfile и `compose.yaml`. -## Архитектура и решения +```sh +cp lab4.env.example .env +docker compose --env-file .env config --quiet +docker compose --env-file .env up -d --build --scale api=2 --wait --wait-timeout 180 +``` -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab3, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +После запуска доступны: + +- API через Nginx: `http://localhost:8080`; +- Swagger UI: `http://localhost:8081`; +- Prometheus: `http://localhost:9090`; +- Grafana: `http://localhost:3000`, пользователь `admin`, пароль из `GRAFANA_ADMIN_PASSWORD`. + +Публичные и внутренние проверки: + +```sh +make check +make test BASE_URL=http://localhost:8080 +docker compose --profile tests run --rm --build tests +go test -race ./... +go vet ./... +``` + +Сверка PostgreSQL и S3 выполняется внутри запущенной API-реплики. Без `--apply` команда ничего не удаляет: + +```sh +docker compose exec -T api /app/messenger reconcile-attachments --grace-period=1h +docker compose exec -T api /app/messenger reconcile-attachments --apply --grace-period=1h +``` + +Эксперименты запускаются на чистом стенде: + +```sh +docker compose exec -T api /app/lab4experiment memory +docker compose exec -T api /app/lab4experiment consistency +``` + +Безопасная остановка сохраняет данные в Docker volumes: + +```sh +docker compose down +``` + +Полное удаление учебных данных выполняется только явно: + +```sh +docker compose down -v +``` + +## Архитектура + +```text +клиент + | + v +Nginx :8080 + | + +---- API replica 1 ----+ + | | + +---- API replica 2 ----+---- PostgreSQL: пользователи, чаты, + | сообщения, metadata + +---- Valkey: сессии + +---- MinIO: приватные байты изображений + +Prometheus <---- API /metrics, MinIO, Nginx, PostgreSQL, Valkey + | + +---- Grafana +``` + +Из лабораторной № 3 сохранены две и более API-реплики, Nginx, общие PostgreSQL и Valkey, Bearer-сессии, keyset pagination, идемпотентность сообщений, graceful shutdown, failover, метрики и управляемое развёртывание. В лабораторной № 4 добавлены приватное объектное хранилище, модель вложения, бинарная загрузка и скачивание, привязка вложений к сообщениям и сверка двух хранилищ. + +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 отключена и её порт не опубликован. + +## Загрузка и чтение вложения + +Клиент передаёт сырые байты 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. + +Метаданные и содержимое читаются только после проверки Bearer-сессии и членства пользователя в чате. Посторонний пользователь и неизвестный идентификатор дают одинаковый `404`. API отдаёт байты самостоятельно без redirect и возвращает сохранённый `Content-Type` и точный `Content-Length`. + +Сообщение принимает до десяти уникальных `attachment_ids`. В одной транзакции PostgreSQL проверяются членство отправителя и принадлежность каждого вложения нужному чату, создаются сообщение, связи и запись идемпотентности. Отсутствующее поле `attachment_ids` и пустой массив дают одинаковый семантический hash. Пустой текст допустим только при наличии вложения. + +## Согласованность PostgreSQL и S3 + +Операции PostgreSQL и S3 не входят в общую распределённую транзакцию. Возможны два вида расхождений: + +1. object существует в S3, но metadata отсутствует; +2. metadata существует, но object отсутствует. + +Команда `reconcile-attachments` проходит оба набора в порядке object key постранично, поэтому объём памяти ограничен размером двух страниц. По умолчанию включён dry-run. Grace period защищает свежие объекты и строки, которые могут относиться к ещё выполняющейся операции. + +В режиме `--apply` старый orphan в S3 удаляется. Старая строка с отсутствующим объектом удаляется только при отсутствии ссылки из `message_attachments`; проверка возраста и отсутствия ссылки повторяется атомарным `DELETE`. Используемая строка сохраняется и попадает в отчёт для ручного восстановления объекта. Повторный запуск после исправления не выполняет дополнительных удалений. + +## Ограничение памяти + +Размер тела ограничен `http.MaxBytesReader`, поэтому неизвестный `Content-Length` не позволяет читать бесконечный поток. Исходные байты и декодированное изображение находятся в памяти только во время синхронной загрузки. Перед полной декодировкой weighted semaphore резервирует для запроса сумму размера исходных байтов и восьми байт на пиксель. Общий бюджет одной реплики равен 384 MiB, а лимит её контейнера — 512 MiB. Максимально допустимое изображение требует не более 330 485 760 байт расчётного бюджета. Если свободного бюджета нет, 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. + +## Наблюдаемость + +API экспортирует общие HTTP-метрики и отдельные показатели загрузок: + +- `messenger_attachment_uploads_total{result}`; +- `messenger_attachment_upload_duration_seconds`; +- `messenger_attachment_upload_bytes_total`. + +Prometheus обнаруживает все API-реплики через Docker DNS и отдельно собирает MinIO, Nginx, PostgreSQL и Valkey. Grafana показывает частоту и p95 загрузок, объём принятых байтов, число и ёмкость объектов MinIO, ошибки S3, доступность компонентов, RPS, классы HTTP-ответов и память Go. + +`/health/live` проверяет только процесс. `/health/ready` требует доступных PostgreSQL, Valkey и приватного bucket S3. Недоступность Grafana или Prometheus не останавливает API. ## Доказательства критериев -| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | +| Критерий | Команда или сценарий | Результат | Доказательство | | --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | +| Контракт и OpenAPI | `make check`, `make validate` | offline check PASS; validate входит в CI | `evidence/lab4-verification.txt` | +| Unit и integration | `go test ./...`, race/tests profile в CI | unit PASS | `evidence/lab4-verification.txt` | +| 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` | +| Трек 2: dry-run/apply/repeat | `lab4experiment consistency` | PASS, повторный apply: 0 удалений | `evidence/lab4-consistency.json` | -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +## Эксперимент согласованности -## Эксперименты и отказы +Гипотеза: постраничная сверка с grace period может автоматически удалить старые безопасные расхождения, не удаляя свежие данные и metadata используемого вложения; второй apply будет идемпотентным. -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. +Методика на чистом стенде: -| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | -| --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +1. создать согласованное вложение; +2. удалить S3 object у непривязанного вложения; +3. привязать другое вложение к сообщению и удалить его S3 object; +4. создать object без metadata; +5. выполнить apply с grace period один час и проверить сохранность свежих аномалий; +6. выполнить dry-run с нулевым grace period; +7. выполнить apply и проверить удаление orphan и непривязанной строки; +8. повторить apply и проверить отсутствие новых действий. -## Ограничения и следующие шаги +Фактическая стоимость обхода записывается как число просмотренных объектов и строк, размер страницы и wall time. Алгоритм выполняет линейный merge двух отсортированных потоков; дополнительные запросы проверки ссылок нужны только для metadata с отсутствующим объектом. -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +При размере страницы 10 фактический запуск пересёк границу страницы и просмотрел 206 строк metadata и 205 objects. Apply с часовым grace period занял 58 миллисекунд и сохранил один свежий orphan и две свежие строки с отсутствующим object. При нулевом grace period dry-run за 65 миллисекунд обнаружил старый orphan, старую непривязанную строку и одну используемую строку. Apply за 77 миллисекунд удалил только orphan и непривязанную строку. Повторный apply занял 38 миллисекунд, выполнил ноль удалений, а используемая строка осталась в PostgreSQL. + +## Ограничения + +- Между S3 PUT и PostgreSQL INSERT нет общей транзакции; компенсация и reconciler обеспечивают eventual consistency. +- Удалённый object используемого вложения автоматически не восстанавливается: строка сохраняется и требует восстановления байтов из резервной копии либо решения оператора. +- Grace period основан на времени PostgreSQL и S3; для удалённого стенда требуется синхронизация часов. +- Admission control действует отдельно в каждой API-реплике; при изменении контейнерного лимита его бюджет нужно настраивать вместе с `ATTACHMENT_DECODE_MEMORY_BYTES`. +- 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/cmd/lab4experiment/main.go b/cmd/lab4experiment/main.go new file mode 100644 index 0000000..ed24f21 --- /dev/null +++ b/cmd/lab4experiment/main.go @@ -0,0 +1,654 @@ +package main + +import ( + "bytes" + "context" + "encoding/base64" + "encoding/json" + "errors" + "flag" + "fmt" + "image" + "image/jpeg" + "io" + "net/http" + "os" + "strconv" + "strings" + "sync" + "sync/atomic" + "time" + + "github.com/google/uuid" + "github.com/jackc/pgx/v5/pgxpool" + + "gitea.privcloud.tech/dizi/mtusi2026lab4/internal/config" + "gitea.privcloud.tech/dizi/mtusi2026lab4/internal/database" + "gitea.privcloud.tech/dizi/mtusi2026lab4/internal/objectstore" + "gitea.privcloud.tech/dizi/mtusi2026lab4/internal/postgres" + "gitea.privcloud.tech/dizi/mtusi2026lab4/internal/reconcile" +) + +const experimentPassword = "Lab4-experiment-password" + +type apiClient struct { + baseURL string + client *http.Client + token string +} + +type attachment struct { + ID string `json:"id"` +} + +type setup struct { + client *apiClient + chatID string +} + +func main() { + if err := run(os.Args[1:], os.Stdout); err != nil { + fmt.Fprintln(os.Stderr, err) + os.Exit(1) + } +} + +func run(arguments []string, output io.Writer) error { + if len(arguments) == 0 { + return errors.New("usage: lab4experiment memory|consistency [flags]") + } + switch arguments[0] { + case "memory": + return runMemory(arguments[1:], output) + case "consistency": + return runConsistency(arguments[1:], output) + default: + return errors.New("usage: lab4experiment memory|consistency [flags]") + } +} + +type memoryResult struct { + Replicas int `json:"replicas"` + Concurrency int `json:"concurrency"` + Rounds int `json:"rounds"` + SettleTimeMillis int64 `json:"settle_time_ms"` + ImageBytes int `json:"image_bytes"` + UploadRateBytes int64 `json:"upload_rate_bytes_per_second"` + SuccessfulUploads int64 `json:"successful_uploads"` + FailedUploads int64 `json:"failed_uploads"` + DurationMillis int64 `json:"duration_ms"` + HeapBaselineBytes int64 `json:"heap_baseline_bytes"` + HeapPeakBytes int64 `json:"heap_peak_bytes"` + HeapDeltaBytes int64 `json:"heap_delta_bytes"` + RSSBaselineBytes int64 `json:"rss_baseline_bytes"` + RSSPeakBytes int64 `json:"rss_peak_bytes"` + RSSDeltaBytes int64 `json:"rss_delta_bytes"` +} + +func runMemory(arguments []string, output io.Writer) error { + flags := flag.NewFlagSet("memory", flag.ContinueOnError) + flags.SetOutput(io.Discard) + baseURL := flags.String("base-url", "http://nginx:8080", "messenger base URL") + prometheusURL := flags.String("prometheus-url", "http://prometheus:9090", "Prometheus base URL") + replicas := flags.Int("replicas", 2, "expected API replicas") + concurrency := flags.Int("concurrency", 12, "number of concurrent uploads") + rounds := flags.Int("rounds", 4, "number of upload waves") + width := flags.Int("width", 2048, "image width") + height := flags.Int("height", 2048, "image height") + uploadRate := flags.Int64("upload-rate", 1536*1024, "bytes per second for each upload") + settleTime := flags.Duration("settle-time", 3*time.Second, "delay before the baseline sample") + if err := flags.Parse(arguments); err != nil || flags.NArg() != 0 { + return errors.New("invalid memory experiment flags") + } + if *replicas < 1 || *concurrency < 10 || *rounds < 1 || *width < 1 || *height < 1 || *uploadRate < 1 || *settleTime < 0 { + return errors.New("concurrency must be at least 10 and rounds/dimensions/rate must be positive") + } + + ctx, cancel := context.WithTimeout(context.Background(), 3*time.Minute) + defer cancel() + fixture, err := jpegFixture(*width, *height) + if err != nil { + return err + } + if err := waitForReplicas(ctx, *prometheusURL, *replicas); err != nil { + return err + } + settle := time.NewTimer(*settleTime) + defer settle.Stop() + select { + case <-ctx.Done(): + return ctx.Err() + case <-settle.C: + } + heapBaseline, err := prometheusValue(ctx, *prometheusURL, freshMetricQuery("go_memstats_heap_alloc_bytes")) + if err != nil { + return err + } + rssBaseline, err := prometheusValue(ctx, *prometheusURL, freshMetricQuery("process_resident_memory_bytes")) + if err != nil { + return err + } + environment, err := prepare(ctx, *baseURL) + if err != nil { + return err + } + + var successful atomic.Int64 + var failed atomic.Int64 + var firstError struct { + sync.Mutex + err error + } + heapPeak := heapBaseline + rssPeak := rssBaseline + loadDone := make(chan struct{}) + sampleDone := make(chan error, 1) + go sampleMemory(ctx, *prometheusURL, *replicas, loadDone, &heapPeak, &rssPeak, sampleDone) + started := time.Now() + for round := range *rounds { + var workers sync.WaitGroup + workers.Add(*concurrency) + for index := range *concurrency { + go func(round, index int) { + defer workers.Done() + reader := newRateReader(fixture, *uploadRate) + filename := fmt.Sprintf("memory-%02d-%02d.jpg", round, index) + if _, err := environment.client.upload(ctx, environment.chatID, filename, reader, int64(len(fixture))); err != nil { + failed.Add(1) + firstError.Lock() + if firstError.err == nil { + firstError.err = err + } + firstError.Unlock() + return + } + successful.Add(1) + }(round, index) + } + workers.Wait() + } + close(loadDone) + if err := <-sampleDone; err != nil { + return err + } + result := memoryResult{ + Replicas: *replicas, Concurrency: *concurrency, Rounds: *rounds, SettleTimeMillis: settleTime.Milliseconds(), + ImageBytes: len(fixture), UploadRateBytes: *uploadRate, + SuccessfulUploads: successful.Load(), FailedUploads: failed.Load(), DurationMillis: time.Since(started).Milliseconds(), + HeapBaselineBytes: heapBaseline, HeapPeakBytes: heapPeak, HeapDeltaBytes: heapPeak - heapBaseline, + RSSBaselineBytes: rssBaseline, RSSPeakBytes: rssPeak, RSSDeltaBytes: rssPeak - rssBaseline, + } + if result.FailedUploads > 0 { + return fmt.Errorf("%d uploads failed: %w", result.FailedUploads, firstError.err) + } + return writeJSON(output, result) +} + +func sampleMemory( + ctx context.Context, + prometheusURL string, + expectedReplicas int, + done <-chan struct{}, + heapPeak *int64, + rssPeak *int64, + result chan<- error, +) { + ticker := time.NewTicker(500 * time.Millisecond) + defer ticker.Stop() + for { + select { + case <-ctx.Done(): + result <- ctx.Err() + return + case <-done: + result <- nil + return + case <-ticker.C: + replicas, err := prometheusValue(ctx, prometheusURL, activeReplicasQuery()) + if err != nil { + result <- err + return + } + if replicas != int64(expectedReplicas) { + result <- fmt.Errorf("active API replicas = %d, expected %d", replicas, expectedReplicas) + return + } + heap, err := prometheusValue(ctx, prometheusURL, freshMetricQuery("go_memstats_heap_alloc_bytes")) + if err != nil { + result <- err + return + } + rss, err := prometheusValue(ctx, prometheusURL, freshMetricQuery("process_resident_memory_bytes")) + if err != nil { + result <- err + return + } + *heapPeak = max(*heapPeak, heap) + *rssPeak = max(*rssPeak, rss) + } + } +} + +type consistencyResult struct { + PageSize int `json:"page_size"` + SeededConsistent int `json:"seeded_consistent"` + FreshApply reconciliationRun `json:"fresh_apply"` + DryRun reconciliationRun `json:"dry_run"` + Apply reconciliationRun `json:"apply"` + RepeatedApply reconciliationRun `json:"repeated_apply"` + FreshPreserved bool `json:"fresh_preserved"` + OrphanDeleted bool `json:"orphan_deleted"` + UnusedDeleted bool `json:"unused_metadata_deleted"` + InUsePreserved bool `json:"in_use_metadata_preserved"` + TotalDurationMillis int64 `json:"total_duration_ms"` +} + +type reconciliationRun struct { + DurationMillis int64 `json:"duration_ms"` + Report reconcile.Report `json:"report"` +} + +func runConsistency(arguments []string, output io.Writer) error { + flags := flag.NewFlagSet("consistency", flag.ContinueOnError) + flags.SetOutput(io.Discard) + baseURL := flags.String("base-url", "http://nginx:8080", "messenger base URL") + pageSize := flags.Int("page-size", 10, "reconciliation page size") + if err := flags.Parse(arguments); err != nil || flags.NArg() != 0 { + return errors.New("invalid consistency experiment flags") + } + + ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute) + defer cancel() + settings, err := config.Load() + if err != nil { + return err + } + pool, err := database.Open(ctx, database.Config{ + URL: settings.DatabaseURL, MinConnections: settings.DBMinConns, MaxConnections: settings.DBMaxConns, + MaxConnectionAge: settings.DBMaxConnectionAge, MaxConnectionIdle: settings.DBMaxConnectionIdle, + HealthCheckPeriod: settings.DBHealthCheckPeriod, ConnectTimeout: settings.DependencyTimeout, + }) + if err != nil { + return err + } + defer pool.Close() + objects, err := objectstore.New(objectstore.Config{ + Endpoint: settings.S3Endpoint, Region: settings.S3Region, Bucket: settings.S3Bucket, + AccessKey: settings.S3AccessKey, SecretKey: settings.S3SecretKey, + UseTLS: settings.S3UseTLS, Timeout: settings.S3Timeout, + }) + if err != nil { + return err + } + metadata := postgres.New(pool) + clean, err := reconcile.New(metadata, objects, reconcile.Config{Prefix: "attachments/", PageSize: *pageSize, GraceTime: 0}) + if err != nil { + return err + } + initial, err := clean.Run(ctx) + if err != nil { + return err + } + if hasAnomalies(initial) { + return errors.New("consistency experiment requires a stack without existing attachment anomalies") + } + + started := time.Now() + environment, err := prepare(ctx, *baseURL) + if err != nil { + return err + } + fixture, err := jpegFixture(320, 200) + if err != nil { + return err + } + seededConsistent := *pageSize + 1 + for index := range seededConsistent { + filename := fmt.Sprintf("consistent-%03d.jpg", index) + if _, err := environment.client.upload(ctx, environment.chatID, filename, bytes.NewReader(fixture), int64(len(fixture))); err != nil { + return err + } + } + unused, err := environment.client.upload(ctx, environment.chatID, "unused-missing.jpg", bytes.NewReader(fixture), int64(len(fixture))) + if err != nil { + return err + } + inUse, err := environment.client.upload(ctx, environment.chatID, "in-use-missing.jpg", bytes.NewReader(fixture), int64(len(fixture))) + if err != nil { + return err + } + if err := environment.client.createMessage(ctx, environment.chatID, inUse.ID); err != nil { + return err + } + keys, err := attachmentKeys(ctx, pool, []string{unused.ID, inUse.ID}) + if err != nil { + return err + } + if err := objects.Delete(ctx, keys[unused.ID]); err != nil { + return err + } + if err := objects.Delete(ctx, keys[inUse.ID]); err != nil { + return err + } + orphanKey := "attachments/experiment-" + uuid.NewString() + "/original" + if err := objects.Put(ctx, orphanKey, "image/jpeg", fixture); err != nil { + return err + } + + fresh, err := reconcile.New(metadata, objects, reconcile.Config{ + Prefix: "attachments/", PageSize: *pageSize, GraceTime: time.Hour, Apply: true, + }) + if err != nil { + return err + } + freshRun, err := measuredReconciliation(ctx, fresh) + if err != nil { + return err + } + freshPreserved := objectExists(ctx, objects, orphanKey) && + attachmentExists(ctx, pool, unused.ID) && attachmentExists(ctx, pool, inUse.ID) + + dryRun, err := reconcile.New(metadata, objects, reconcile.Config{Prefix: "attachments/", PageSize: *pageSize}) + if err != nil { + return err + } + dryRunResult, err := measuredReconciliation(ctx, dryRun) + if err != nil { + return err + } + apply, err := reconcile.New(metadata, objects, reconcile.Config{ + Prefix: "attachments/", PageSize: *pageSize, Apply: true, + }) + if err != nil { + return err + } + applyResult, err := measuredReconciliation(ctx, apply) + if err != nil { + return err + } + repeatedResult, err := measuredReconciliation(ctx, apply) + if err != nil { + return err + } + + result := consistencyResult{ + PageSize: *pageSize, SeededConsistent: seededConsistent, + FreshApply: freshRun, DryRun: dryRunResult, Apply: applyResult, RepeatedApply: repeatedResult, + FreshPreserved: freshPreserved, OrphanDeleted: !objectExists(ctx, objects, orphanKey), + UnusedDeleted: !attachmentExists(ctx, pool, unused.ID), InUsePreserved: attachmentExists(ctx, pool, inUse.ID), + TotalDurationMillis: time.Since(started).Milliseconds(), + } + if !result.FreshPreserved || !result.OrphanDeleted || !result.UnusedDeleted || !result.InUsePreserved || + repeatedResult.Report.DeletedOrphanObjects != 0 || repeatedResult.Report.DeletedUnreferencedRows != 0 { + return fmt.Errorf("unexpected reconciliation result: %+v", result) + } + return writeJSON(output, result) +} + +func measuredReconciliation(ctx context.Context, reconciler *reconcile.Reconciler) (reconciliationRun, error) { + started := time.Now() + report, err := reconciler.Run(ctx) + return reconciliationRun{DurationMillis: time.Since(started).Milliseconds(), Report: report}, err +} + +func hasAnomalies(report reconcile.Report) bool { + return report.FreshOrphanObjects != 0 || report.OldOrphanObjects != 0 || + report.FreshMissingObjects != 0 || report.ReferencedMissingObjects != 0 || + report.OldUnreferencedMetadata != 0 +} + +func attachmentKeys(ctx context.Context, pool *pgxpool.Pool, ids []string) (map[string]string, error) { + rows, err := pool.Query(ctx, `SELECT id::text, object_key FROM attachments WHERE id::text = ANY($1)`, ids) + if err != nil { + return nil, fmt.Errorf("query attachment keys: %w", err) + } + defer rows.Close() + keys := make(map[string]string, len(ids)) + for rows.Next() { + var id string + var key string + if err := rows.Scan(&id, &key); err != nil { + return nil, fmt.Errorf("scan attachment key: %w", err) + } + keys[id] = key + } + if err := rows.Err(); err != nil { + return nil, fmt.Errorf("iterate attachment keys: %w", err) + } + if len(keys) != len(ids) { + return nil, errors.New("not all attachment keys were found") + } + return keys, nil +} + +func attachmentExists(ctx context.Context, pool *pgxpool.Pool, id string) bool { + var exists bool + return pool.QueryRow(ctx, `SELECT EXISTS (SELECT 1 FROM attachments WHERE id = $1)`, id).Scan(&exists) == nil && exists +} + +func objectExists(ctx context.Context, objects *objectstore.Store, key string) bool { + _, err := objects.Stat(ctx, key) + return err == nil +} + +func prepare(ctx context.Context, baseURL string) (setup, error) { + client := &apiClient{baseURL: strings.TrimRight(baseURL, "/"), client: &http.Client{Timeout: 90 * time.Second}} + username := "lab4_" + strings.ReplaceAll(uuid.NewString()[:18], "-", "") + var user struct { + ID string `json:"id"` + } + if err := client.jsonRequest(ctx, http.MethodPost, "/api/v1/users", map[string]string{ + "username": username, "display_name": "Lab 4 experiment", "password": experimentPassword, + }, &user, ""); err != nil { + return setup{}, err + } + credentials := base64.StdEncoding.EncodeToString([]byte(username + ":" + experimentPassword)) + var session struct { + Token string `json:"token"` + } + if err := client.jsonRequest(ctx, http.MethodPost, "/api/v1/auth/sessions", nil, &session, "Basic "+credentials); err != nil { + return setup{}, err + } + client.token = session.Token + var chat struct { + ID string `json:"id"` + } + if err := client.jsonRequest(ctx, http.MethodPost, "/api/v1/chats", map[string]any{ + "title": "Lab 4 experiment", "member_ids": []string{user.ID}, + }, &chat, "Bearer "+client.token); err != nil { + return setup{}, err + } + return setup{client: client, chatID: chat.ID}, nil +} + +func (c *apiClient) upload( + ctx context.Context, + chatID string, + filename string, + body io.Reader, + contentLength int64, +) (attachment, error) { + path := "/api/v1/chats/" + chatID + "/attachments?filename=" + filename + request, err := http.NewRequestWithContext(ctx, http.MethodPost, c.baseURL+path, body) + if err != nil { + return attachment{}, err + } + request.ContentLength = contentLength + request.Header.Set("Authorization", "Bearer "+c.token) + request.Header.Set("Content-Type", "image/jpeg") + response, err := c.client.Do(request) + if err != nil { + return attachment{}, err + } + defer func() { _ = response.Body.Close() }() + if response.StatusCode != http.StatusCreated { + message, _ := io.ReadAll(io.LimitReader(response.Body, 4096)) + return attachment{}, fmt.Errorf("upload status %d: %s", response.StatusCode, message) + } + var result attachment + if err := json.NewDecoder(response.Body).Decode(&result); err != nil { + return attachment{}, err + } + return result, nil +} + +func (c *apiClient) createMessage(ctx context.Context, chatID, attachmentID string) error { + return c.jsonRequest(ctx, http.MethodPost, "/api/v1/chats/"+chatID+"/messages", map[string]any{ + "text": "", "attachment_ids": []string{attachmentID}, + }, nil, "Bearer "+c.token, "Idempotency-Key", uuid.NewString()) +} + +func (c *apiClient) jsonRequest( + ctx context.Context, + method string, + path string, + payload any, + result any, + authorization string, + extraHeader ...string, +) error { + var body io.Reader + if payload != nil { + encoded, err := json.Marshal(payload) + if err != nil { + return err + } + body = bytes.NewReader(encoded) + } + request, err := http.NewRequestWithContext(ctx, method, c.baseURL+path, body) + if err != nil { + return err + } + if payload != nil { + request.Header.Set("Content-Type", "application/json") + } + if authorization != "" { + request.Header.Set("Authorization", authorization) + } + for index := 0; index+1 < len(extraHeader); index += 2 { + request.Header.Set(extraHeader[index], extraHeader[index+1]) + } + response, err := c.client.Do(request) + if err != nil { + return err + } + defer func() { _ = response.Body.Close() }() + if response.StatusCode < 200 || response.StatusCode >= 300 { + message, _ := io.ReadAll(io.LimitReader(response.Body, 4096)) + return fmt.Errorf("%s %s status %d: %s", method, path, response.StatusCode, message) + } + if result == nil { + return nil + } + return json.NewDecoder(response.Body).Decode(result) +} + +func waitForReplicas(ctx context.Context, prometheusURL string, expected int) error { + ticker := time.NewTicker(time.Second) + defer ticker.Stop() + for { + count, err := prometheusValue(ctx, prometheusURL, activeReplicasQuery()) + if err == nil && count == int64(expected) { + return nil + } + select { + case <-ctx.Done(): + return fmt.Errorf("wait for %d Prometheus API targets: %w", expected, ctx.Err()) + case <-ticker.C: + } + } +} + +func activeReplicasQuery() string { + return `count(timestamp(process_resident_memory_bytes{job="messenger"}) > time() - 10)` +} + +func freshMetricQuery(metric string) string { + return fmt.Sprintf(`sum(%[1]s{job="messenger"} and on(instance) (timestamp(%[1]s{job="messenger"}) > time() - 10))`, metric) +} + +func prometheusValue(ctx context.Context, baseURL, query string) (int64, error) { + request, err := http.NewRequestWithContext(ctx, http.MethodGet, strings.TrimRight(baseURL, "/")+"/api/v1/query", nil) + if err != nil { + return 0, err + } + values := request.URL.Query() + values.Set("query", query) + request.URL.RawQuery = values.Encode() + response, err := http.DefaultClient.Do(request) + if err != nil { + return 0, err + } + defer func() { _ = response.Body.Close() }() + if response.StatusCode != http.StatusOK { + return 0, fmt.Errorf("prometheus status %d", response.StatusCode) + } + var payload struct { + Status string `json:"status"` + Data struct { + Result []struct { + Value []json.RawMessage `json:"value"` + } `json:"result"` + } `json:"data"` + } + if err := json.NewDecoder(response.Body).Decode(&payload); err != nil { + return 0, err + } + if payload.Status != "success" || len(payload.Data.Result) != 1 || len(payload.Data.Result[0].Value) != 2 { + return 0, errors.New("prometheus query returned no scalar value") + } + var raw string + if err := json.Unmarshal(payload.Data.Result[0].Value[1], &raw); err != nil { + return 0, err + } + value, err := strconv.ParseFloat(raw, 64) + return int64(value), err +} + +func jpegFixture(width, height int) ([]byte, error) { + pixels := image.NewRGBA(image.Rect(0, 0, width, height)) + state := uint64(0x9e3779b97f4a7c15) + for index := range pixels.Pix { + state ^= state << 13 + state ^= state >> 7 + state ^= state << 17 + pixels.Pix[index] = byte(state >> 24) + } + var encoded bytes.Buffer + if err := jpeg.Encode(&encoded, pixels, &jpeg.Options{Quality: 90}); err != nil { + return nil, err + } + return encoded.Bytes(), nil +} + +type rateReader struct { + reader *bytes.Reader + rate int64 + started time.Time + read int64 +} + +func newRateReader(data []byte, rate int64) *rateReader { + return &rateReader{reader: bytes.NewReader(data), rate: rate, started: time.Now()} +} + +func (r *rateReader) Read(buffer []byte) (int, error) { + for { + allowed := time.Since(r.started).Nanoseconds()*r.rate/int64(time.Second) - r.read + if allowed > 0 { + if int64(len(buffer)) > allowed { + buffer = buffer[:allowed] + } + count, err := r.reader.Read(buffer) + r.read += int64(count) + return count, err + } + time.Sleep(10 * time.Millisecond) + } +} + +func writeJSON(output io.Writer, value any) error { + encoder := json.NewEncoder(output) + encoder.SetIndent("", " ") + return encoder.Encode(value) +} diff --git a/evidence/lab4-consistency.json b/evidence/lab4-consistency.json new file mode 100644 index 0000000..e131f41 --- /dev/null +++ b/evidence/lab4-consistency.json @@ -0,0 +1,69 @@ +{ + "page_size": 10, + "seeded_consistent": 11, + "fresh_apply": { + "duration_ms": 58, + "report": { + "metadata_scanned": 206, + "objects_scanned": 205, + "consistent": 204, + "fresh_orphan_objects": 1, + "old_orphan_objects": 0, + "deleted_orphan_objects": 0, + "fresh_missing_objects": 2, + "referenced_missing_objects": 0, + "old_unreferenced_metadata": 0, + "deleted_unreferenced_rows": 0 + } + }, + "dry_run": { + "duration_ms": 65, + "report": { + "metadata_scanned": 206, + "objects_scanned": 205, + "consistent": 204, + "fresh_orphan_objects": 0, + "old_orphan_objects": 1, + "deleted_orphan_objects": 0, + "fresh_missing_objects": 0, + "referenced_missing_objects": 1, + "old_unreferenced_metadata": 1, + "deleted_unreferenced_rows": 0 + } + }, + "apply": { + "duration_ms": 77, + "report": { + "metadata_scanned": 206, + "objects_scanned": 205, + "consistent": 204, + "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 + } + }, + "repeated_apply": { + "duration_ms": 38, + "report": { + "metadata_scanned": 205, + "objects_scanned": 204, + "consistent": 204, + "fresh_orphan_objects": 0, + "old_orphan_objects": 0, + "deleted_orphan_objects": 0, + "fresh_missing_objects": 0, + "referenced_missing_objects": 1, + "old_unreferenced_metadata": 0, + "deleted_unreferenced_rows": 0 + } + }, + "fresh_preserved": true, + "orphan_deleted": true, + "unused_metadata_deleted": true, + "in_use_metadata_preserved": true, + "total_duration_ms": 515 +} diff --git a/evidence/lab4-memory.json b/evidence/lab4-memory.json new file mode 100644 index 0000000..3531b37 --- /dev/null +++ b/evidence/lab4-memory.json @@ -0,0 +1,17 @@ +{ + "replicas": 2, + "concurrency": 12, + "rounds": 4, + "settle_time_ms": 3000, + "image_bytes": 3759914, + "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 +} diff --git a/evidence/lab4-verification.txt b/evidence/lab4-verification.txt new file mode 100644 index 0000000..0b4bc58 --- /dev/null +++ b/evidence/lab4-verification.txt @@ -0,0 +1,19 @@ +Date: 2026-10-02 +Environment: linux/arm64 containers, Docker Compose, 2 API replicas + +PASS gofmt for changed Go files +PASS go test ./... +PASS go build ./cmd/... +PASS make check +PASS make test BASE_URL=http://localhost:8080 + 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 anonymous bucket request returned HTTP 403 +PASS application credentials can list only the configured bucket and cannot create another bucket +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 + +The pull request CI runs OpenAPI validation, race tests, lint, integration tests, +persistence and API-replica failover on the exact pushed commit. diff --git a/internal/reconcile/reconcile_test.go b/internal/reconcile/reconcile_test.go new file mode 100644 index 0000000..defe3cd --- /dev/null +++ b/internal/reconcile/reconcile_test.go @@ -0,0 +1,129 @@ +package reconcile + +import ( + "context" + "sort" + "testing" + "time" + + "github.com/stretchr/testify/require" + + "gitea.privcloud.tech/dizi/mtusi2026lab4/internal/model" + "gitea.privcloud.tech/dizi/mtusi2026lab4/internal/objectstore" +) + +func TestReconcilerDryRunAndApply(t *testing.T) { + now := time.Date(2026, 10, 2, 12, 0, 0, 0, time.UTC) + metadata := &metadataStub{items: []model.Attachment{ + {ID: "consistent", ObjectKey: "attachments/consistent", CreatedAt: now.Add(-time.Hour)}, + {ID: "fresh-missing", ObjectKey: "attachments/fresh-missing", CreatedAt: now.Add(-time.Minute)}, + {ID: "old-missing", ObjectKey: "attachments/old-missing", CreatedAt: now.Add(-time.Hour)}, + {ID: "referenced-missing", ObjectKey: "attachments/referenced-missing", CreatedAt: now.Add(-time.Hour)}, + }, referenced: map[string]bool{"referenced-missing": true}} + objects := &objectStub{items: []objectstore.Object{ + {Key: "attachments/consistent", LastModified: now.Add(-time.Hour)}, + {Key: "attachments/fresh-orphan", LastModified: now.Add(-time.Minute)}, + {Key: "attachments/old-orphan", LastModified: now.Add(-time.Hour)}, + }} + + dryRun, err := New(metadata, objects, Config{ + Prefix: "attachments/", PageSize: 2, GraceTime: 10 * time.Minute, Now: func() time.Time { return now }, + }) + require.NoError(t, err) + report, err := dryRun.Run(context.Background()) + require.NoError(t, err) + require.Equal(t, Report{ + MetadataScanned: 4, ObjectsScanned: 3, Consistent: 1, + FreshOrphanObjects: 1, OldOrphanObjects: 1, FreshMissingObjects: 1, + ReferencedMissingObjects: 1, OldUnreferencedMetadata: 1, + }, report) + require.Empty(t, metadata.deleted) + require.Empty(t, objects.deleted) + + apply, err := New(metadata, objects, Config{ + Prefix: "attachments/", PageSize: 2, GraceTime: 10 * time.Minute, Apply: true, + Now: func() time.Time { return now }, + }) + require.NoError(t, err) + report, err = apply.Run(context.Background()) + require.NoError(t, err) + require.Equal(t, 1, report.DeletedOrphanObjects) + require.Equal(t, 1, report.DeletedUnreferencedRows) + require.Equal(t, []string{"old-missing"}, metadata.deleted) + require.Equal(t, []string{"attachments/old-orphan"}, objects.deleted) + + report, err = apply.Run(context.Background()) + require.NoError(t, err) + require.Zero(t, report.DeletedOrphanObjects) + require.Zero(t, report.DeletedUnreferencedRows) + require.Equal(t, 1, report.FreshOrphanObjects) + require.Equal(t, 1, report.FreshMissingObjects) + require.Equal(t, 1, report.ReferencedMissingObjects) +} + +type metadataStub struct { + items []model.Attachment + referenced map[string]bool + deleted []string +} + +func (s *metadataStub) ListAttachments(_ context.Context, after string, limit int) ([]model.Attachment, string, error) { + items := append([]model.Attachment(nil), s.items...) + sort.Slice(items, func(i, j int) bool { return items[i].ObjectKey < items[j].ObjectKey }) + start := 0 + for start < len(items) && items[start].ObjectKey <= after { + start++ + } + end := min(start+limit, len(items)) + var next string + if end < len(items) { + next = items[end-1].ObjectKey + } + return items[start:end], next, nil +} + +func (s *metadataStub) AttachmentReferenced(_ context.Context, id string) (bool, error) { + return s.referenced[id], nil +} + +func (s *metadataStub) DeleteAttachmentIfUnreferencedBefore(_ context.Context, id string, _ time.Time) (bool, error) { + for index, item := range s.items { + if item.ID == id && !s.referenced[id] { + s.items = append(s.items[:index], s.items[index+1:]...) + s.deleted = append(s.deleted, id) + return true, nil + } + } + return false, nil +} + +type objectStub struct { + items []objectstore.Object + deleted []string +} + +func (s *objectStub) List(_ context.Context, _ string, after string, limit int) ([]objectstore.Object, string, error) { + items := append([]objectstore.Object(nil), s.items...) + sort.Slice(items, func(i, j int) bool { return items[i].Key < items[j].Key }) + start := 0 + for start < len(items) && items[start].Key <= after { + start++ + } + end := min(start+limit, len(items)) + var next string + if end < len(items) { + next = items[end-1].Key + } + return items[start:end], next, nil +} + +func (s *objectStub) Delete(_ context.Context, key string) error { + for index, item := range s.items { + if item.Key == key { + s.items = append(s.items[:index], s.items[index+1:]...) + s.deleted = append(s.deleted, key) + return nil + } + } + return nil +}