test: verify attachment consistency and memory

This commit is contained in:
2026-10-02 20:16:39 +03:00
parent ec0e6707b8
commit b3d5d76302
6 changed files with 1046 additions and 21 deletions
+158 -21
View File
@@ -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)
+654
View File
@@ -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)
}
+69
View File
@@ -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
}
+17
View File
@@ -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
}
+19
View File
@@ -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.
+129
View File
@@ -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
}