Files
mtusi2026lab4/REPORT.md
T

27 KiB
Raw Blame History

Отчёт — лабораторная 4

Цель: 5, трек 2 — согласованность PostgreSQL и S3. Автор и ссылка на PR указываются при публикации.

Запуск из чистого clone

Нужны Docker Desktop с Compose v2, Git Bash и Make. Для Go-тестов — Go 1.27.1, C-компилятор для -race и Docker; для публичных проверок — Python 3.9+. На Windows используйте PYTHON=python.

В Git Bash на Windows сначала выполните export PYTHONUTF8=1, чтобы Python читал UTF-8 контракты независимо от системной кодировки. В PowerShell эквивалент — $env:PYTHONUTF8='1'.

cp .env.example .env
make secrets
make up
make test PYTHON=python
make check PYTHON=python
make unit
make vet

Полный зафиксированный Go-прогон: go test -race -p 2 -count=1 ./... (эквивалент make unit GOFLAGS=-p=2). Ограничена только параллельность пакетов с Docker-фикстурами; конкурентные тесты внутри пакетов не отключены.

LB: http://localhost:8080; статистика HAProxy — только 127.0.0.1:8404. Если порт занят, до запуска и restart-проверок задайте export PUBLISH=127.0.0.1:18080 BASE_URL=http://localhost:18080.

После Compose make up и restart-hook дополнительно проверяют свежие readiness-ответы через LB: прежний Docker health status балансировщика может ещё оставаться healthy, пока его active checks выводят новые API из состояния DOWN. Ожидание ограничено 60 пробами, успех — три последовательных ответа.

make secrets создаёт игнорируемый Git каталог secrets/; повторный запуск сохраняет существующие значения. Неполный комплект не заменяется молча. Секреты передаются файлами *_FILE, не значениями в .env. make down сохраняет volumes. make destroy безвозвратно удаляет учебные данные PostgreSQL, Valkey и S3. Удаление файлов секретов при сохранённых volumes не является сбросом паролей.

Архитектура и решения

Клиент → HAProxy → API × 2 → PostgreSQL (метаданные), Valkey (сессии), SeaweedFS (байты). Перенесены lab3 API, устойчивые сессии, идемпотентность сообщений, drain/rolling update и инструменты исследования. Серии старого трека 1 сохранены, их результаты не выдаются за lab4.

SeaweedFS 4.53 и остальные Docker-образы закреплены digest в compose.yaml; SDK — minio-go/v7 7.4.1. weed server хранит и filer-метаданные, и байты в s3data. Внутренние master/filer/volume HTTP и gRPC слушают loopback контейнера, исключая сетевой обход S3-авторизации. Наружу не опубликован ни S3, ни административный интерфейс.

Миграция 00003_attachments.sql добавляет:

Таблица Назначение
files(hash, size_bytes, mime_type, status, created_at) Одна запись на содержимое; PK SHA-256 — 32 байта bytea. created_at нужен для grace period.
attachments(id, chat_id, owner_id, filename, file_hash, created_at) Логическое вложение с UUID и доступом через чат; существует до сообщения.
message_attachments(chat_id, message_id, attachment_id, ordinal) Ссылки сообщения; ordinal сохраняет порядок при чтении и идемпотентном повторе.

path не хранится: ключ — blobs/<lowercase SHA-256>. Имя используется только для отображения. Индекс attachments(file_hash) нужен для проверки использования общего файла; FK защищают ссылки. Принадлежность вложений чату проверяется одним запросом в транзакции отправки. История возвращает упорядоченные attachment_ids одним SQL-запросом.

Одинаковые байты дают одну строку files и один постоянный объект. Каждая загрузка получает свой UUID, владельца, имя и чат: знание хэша не даёт доступа. Дедупликация экономит постоянное хранение, но не клиентский трафик — сервер должен принять тело, чтобы вычислить хэш.

Upload и download

Принимаются сырые PNG/JPEG, не multipart, до 10 MiB и 40 млн пикселей, с истинным Content-Type. Нужен положительный Content-Length; неизвестная длина — 400. Имя — 1–255 code points, без разделителей пути и управляющих символов. Чужой объект даёт 404; аутентификация выполняется до разбора параметров.

  1. Поток с жёстким лимитом записывается в staging/<UUID>, одновременно считаются размер и SHA-256. Локального оригинала на API нет.
  2. Проверяются формат и число пикселей до выделения пиксельного буфера, затем изображение полностью декодируется для обнаружения повреждённого body.
  3. Под транзакционной advisory-блокировкой хэша проверяются files и общий объект. Готовые байты не копируются повторно; отсутствующий blob восстанавливается из новой загрузки.
  4. При необходимости серверный Copy публикует blobs/<hash>. Одна SQL-транзакция сохраняет готовый файл и новое логическое вложение; 201 возвращается после COMMIT.
  5. Staging удаляется отдельной ограниченной по времени компенсацией; её неудачу покрывает reconciler.

Пиксельный буфер 40 млн RGBA64 занимает 320 MB, но это не вся память декодера: progressive JPEG хранит коэффициенты, а PNG — текущую и предыдущую строки. Например, progressive JPEG 4:4:4 8000×5000 требует около 600 MB живых буферов, а однострочный RGBA64 PNG на 40 млн пикселей — около 960 MB. Поэтому допускается один декодер на реплику, API ограничен 2 GiB, GOMEMLIMIT=1536MiB. Первоначальная оценка 512 MiB исправлена после независимого ревью. Upload/download остаются потоковыми; проверка только заголовка не используется, поскольку она пропускает повреждённый body.

Обычный запрос, включая GET метаданных, имеет бюджет 5 s, бинарный — 30 s; socket и соответствующий HAProxy timeout — 35 s. Shutdown допускает 38 s на активные обработчики, Compose stop grace — 45 s с учётом drain 2 s. MAX_UPLOAD_BYTES и MAX_IMAGE_PIXELS можно уменьшить, но нельзя повысить сверх контракта. Для транзакций с S3 I/O локальный idle timeout увеличен до 35 s. Обрыв чтения S3 при декодировании возвращает 503; повреждённые байты, успешно прочитанные из хранилища, — 415.

Download сначала авторизует вложение через чат, затем передаёт оригинал через API без redirect. variants=[], error_code=null, у неизменяемой логической записи updated_at=created_at. Внутренний failed отвечает 409 вместо JSON вне обязательного enum lab4.

S3 намеренно исключён из readiness: при его отказе файловые операции дают 503, текстовые сообщения и доступные метаданные продолжают работать. PostgreSQL и Valkey остаются критическими зависимостями.

Согласованность и reconciler

Общей транзакции PostgreSQL/S3 нет: успешный Copy и неуспешный COMMIT оставляют orphan. При ошибке одной загрузки нельзя удалять общий blob — он может использоваться другими. Компенсируется только её staging.

Публикация и удаление используют одну pg_advisory_xact_lock по первым 8 байтам SHA-256. Коллизия ключа блокировки лишь сериализует разные файлы. Перед изменением reconciler повторно проверяет метаданные, ссылки и возраст текущего объекта под этой блокировкой. Память обхода ограничена страницами до 500 записей.

Grace period — 1 h, минимум 2 min, выше бюджета upload. Свежие данные и неизвестный возраст не разрешают удаление. По умолчанию CLI выполняет dry-run без изменений.

Находка после grace Действие с --apply
Старый staging Повторный HEAD, затем удаление.
Старый blob без files Под блокировкой повторить проверку БД и возраста, удалить объект.
Старый pending/ready без единого логического вложения Удалить объект, затем строку; свежие байты защищают даже старую строку.
Используемый ready без объекта Пометить файл failed, сохранить вложения, сообщения и связи.
Неверный размер или SHA-256 (--deep) Только сообщить, не удалять используемые данные.

Непривязанное к сообщению логическое вложение не считается мусором — его можно прикрепить позже. Повторный apply безопасен; уже обработанный missing не создаёт нового исправления. Повторная проверенная загрузка восстанавливает файл; простое появление объекта само не меняет failed на ready.

make reconcile
make reconcile APPLY=1
make reconcile DEEP=1

В каждой API-реплике shallow apply выполняется каждые 10 min с grace 1 h и бюджетом прохода 2 min. Прерывание логируется; ручной CLI позволяет выполнить полный обход. Ошибка S3, запрет доступа или отсутствие bucket не считаются отсутствием отдельного файла.

Bootstrap — одноразовый s3-init с отдельным admin-ключом; приватные статические identities загружаются до приёма запросов. После создания/проверки bucket bootstrap ждёт успешного чтения устойчивого служебного marker и write/read/delete-пробы: доступность S3 gateway сама по себе не означает, что прежние volumes уже зарегистрированы. Marker находится вне staging/ и blobs/. Это барьер запуска, а не прозрачный retry загрузки пользователя. API имеет только Read/Write одного bucket, reconciler — дополнительно List. S3_RECONCILE_*_FILE выбирают отдельные ключи фонового обхода. SESSION_STORE=postgres и CACHE_URL_FILE в исходном skeleton не используются: фактический store сессий — Valkey через SESSION_STORE_URL_FILE, отдельного кэша нет.

Доказательства критериев

Обязательные tests/, contracts/openapi.json и README задания сохранены. Собственные проверки используют настоящий PostgreSQL/SeaweedFS; узкий двойник байтов нужен для детерминированных отказов. Отказ после Copy также внедряется SQL trigger, отвергающим INSERT метаданных.

Критерий Команда / доказательство
Smoke: checksum, сообщение, ACL make test; evidence/smoke.txt
Restart БД/S3/сессий с volumes make test-persistence ACTION_SCRIPT=scripts/restart.cmd PYTHON=python; evidence/persistence.txt
Failover загрузившей реплики python -X utf8 scripts/lab4/failover.py; evidence/failover-uploaders.json, обе реплики
Конкурентная запись при отказе make test-failover ACTION_SCRIPT=scripts/stop-one.cmd PYTHON=python; evidence/failover.txt
MIME, повреждение, bytes/pixels, имя, чужой чат internal/attachment/validation_test.go, internal/app/attachment_test.go
Дедупликация, гонка upload/GC, SQL rollback internal/attachment/service_test.go
Приватность bucket вне API evidence/private-bucket.txt
Credentials, bootstrap, S3 restart internal/platform/s3store/*_test.go, internal/testenv/s3_test.go
Отказ S3, прерывание upload TestAttachmentRealS3RoundTripValidationAndOutage
Полный race/vet/check make unit, make vet, make check; evidence/tests.txt
≥10 одновременных upload, память API make upload-memory PYTHON=python; evidence/upload-memory.json
Трек 2: faults, dry/apply/repeat, стоимость go run ./tools/reconcilebench; evidence/track2/

На Linux используйте .sh hooks; на Windows .cmd вызывает Git Bash sh, поскольку Python запускает hook без shell interpolation. Failover-hook оставляет выбранную реплику остановленной: восстановите её до повторного теста.

Публичная persistence-проверка прошла за 57.838 s: сохранены сообщения, исходный файл и прежняя сессия; StartedAt в доказательстве подтверждает перезапуск API, LB, PostgreSQL, Valkey и S3. Собственный failover остановил именно реплику из ответа upload для каждого из двух API: 4.837/4.160 s на остановку, после неё другой API вернул те же байты. Публичный concurrent failover: 130 подтверждённых записей, 0 неудачных попыток, восстановление записи за 4.265 s; дублей и потери подтверждённых данных нет. Остановленные API восстановлены.

Дополнительный make validate требует requirements-dev.txt. В этой сессии установка валидатора из PyPI не завершилась из-за сетевых timeout, поэтому локальная полная OpenAPI-валидация не заявляется. Контракт не изменён; offline check и используемое публичными тестами подмножество JSON Schema проверены.

Эксперименты и отказы

Гипотеза трека 2: сериализация по хэшу и повторные проверки позволяют безопасно убирать старые orphan/pending, сохраняя свежие и используемые данные; повторный проход не выполняет повторных исправлений. Deep дополнительно читает байты и потому дороже shallow.

Машинные исходные данные и методика находятся в evidence/track2/ и evidence/upload-memory.json. Память измеряется у контейнеров API. Семплирование может пропустить короткий пик: это наблюдённый максимум Docker working set, не доказательство абсолютного RSS bound.

Два burst-прогона по 10 одновременно стартующих загрузок на API × 2, baseline/tail по 3 s, одинаковые байты внутри серии, прогретое хранилище. Дедупликация могла использовать объект предыдущего прогона, но каждое тело полностью передавалось и декодировалось. Во всех 20 запросах — 201 и правильный checksum; последующее скачивание каждой серии совпало побайтно.

PNG payload Успехи p50, ms p95/max, ms Наибольший sampled working set реплики, MiB
1 MiB, 512×512 RGB 10/10 216.34 259.15 69.6
10 MiB, 1600×1600 RGB 10/10 1 865.39 1 997.06 69.6

При 10 наблюдениях nearest-rank p95 совпадает с максимумом, это не устойчивый хвостовой percentile. Маленькая серия короче частоты семплирования; post-tail сохранён, но краткие пики могут быть пропущены. Это эксперимент памяти, не измерение точки насыщения или production throughput.

Отдельно выполнены одиночные upload/download на границе 40 млн пикселей с более дорогими путями декодера:

Формат Размер входа, B Наибольший sampled working set, MiB Итог
Progressive JPEG RGB 4:4:4, 8000×5000 469 711 585.2 201, checksum совпал, без OOM/restart
Progressive JPEG CMYK 4:4:4, 8000×5000 939 079 945.5 201, checksum совпал, без OOM/restart
PNG RGBA64, 40 000 000×1 1 397 354 1 290.3 201, checksum совпал, без OOM/restart

Полные сэмплы, container limits и состояния до/после — evidence/decoder-memory-*.json. Старый прогон при 512 MiB оставлен отдельно как историческое сравнение, не как доказательство текущего лимита. В стресс-серии процесс уже был прогрет предыдущими изображениями: baseline может включать не возвращённую ОС память. Три выбранных формата не доказывают абсолютный максимум для всех допустимых файлов и сочетаний нагрузки.

Для воспроизведения тяжёлых fixtures нужен только дополнительный Pillow 11.1.0 в своём Python-окружении; основной API и harness от него не зависят. Генератор пишет в игнорируемый bin/, а не в обязательные публичные fixtures:

python -X utf8 scripts/lab4/generate-decoder-fixtures.py
python -X utf8 scripts/lab4/decoder-memory.py --file bin/decoder-fixtures/progressive-rgb-444-40mp.jpg --mime image/jpeg --label progressive-rgb --output evidence/decoder-memory-progressive-rgb.json
python -X utf8 scripts/lab4/decoder-memory.py --file bin/decoder-fixtures/progressive-cmyk-444-40mp.jpg --mime image/jpeg --label progressive-cmyk --output evidence/decoder-memory-progressive-cmyk.json
python -X utf8 scripts/lab4/decoder-memory.py --file bin/decoder-fixtures/wide-rgba64-40mp.png --mime image/png --label wide-rgba64 --output evidence/decoder-memory-wide-rgba64.json

Среда: Windows amd64, 16 логических CPU у клиента, Docker VM — 8 CPU и 12 547 280 896 B RAM. Лимиты Compose: API по 1 CPU/2 GiB, PostgreSQL 1 CPU/512 MiB, S3 1 CPU/512 MiB, HAProxy 0.5 CPU/128 MiB, Valkey 0.5 CPU/320 MiB. Данные синтетические; общий host не является выделенным нагрузочным стендом.

Трек 2: использованы отдельные реальные PostgreSQL/S3 testcontainers, grace 120 s и реальное ожидание 125 s перед очисткой старых объектов. Dry-run нашёл 6 несогласованностей и не изменил данные. Apply выполнил 5 исправлений; сообщение о намеренно повреждённом используемом объекте осталось без удаления. Повторный apply выполнил 0 исправлений. Проверки сохранили свежие staging/orphan/pending, ссылки сообщений и используемые объекты.

Используемых файлов/объектов Shallow dry-run, ms SQL statements Операции порта S3 Sampled Go HeapAlloc, B
100 184 2 103 3 875 232
1 000 2 160 3 1 004 4 159 720
5 000 10 121 11 5 012 5 157 552

Это один прогон на размер на прогретом стенде, без статистических повторов. Измерена память Go-процесса сверки во время Run, не RSS и не память PostgreSQL/S3. В стоимости S3 считаются вызовы порта, а не все внутренние HTTP-запросы SDK. Для cost-датасета SQL-метаданные старые, реальные объекты свежие: дополнительная проверка orphan для них ещё не нужна. Отдельный regression на 1 003 старых объектах проверяет пакетное чтение БД. 10k/50k и production SLA не заявляются.

Ограничения и следующие шаги

  • PostgreSQL, Valkey, SeaweedFS, LB и Docker host остаются единичными точками отказа; отказ API-реплики не доказывает HA всего стенда.
  • SHA-256 используется в принятой модели криптографических коллизий. Дедупликация не позволяет клиенту пропустить отправку тела.
  • Удаление клиентских вложений и сборка «давно не прикреплённых» логических вложений не входят в контракт.
  • Повреждение используемого объекта обнаруживается deep-проверкой, но исходные байты нельзя восстановить без новой загрузки или backup.
  • Между страницами сверки нет snapshot; безопасность изменений обеспечивают повторные проверки под блокировкой.
  • Периодический обход ограничен двумя минутами и начинает каждый проход заново: для существенно больших наборов нужен ручной полный CLI-проход либо будущий resumable cursor. 5 000 объектов укладываются в измеренный бюджет; автоматическое продвижение на произвольном объёме не доказано.
  • После аварии bootstrap и одновременно неудачной компенсации может остаться небольшой служебный .health/check-*; это не вложение, и attachment-reconciler не обходит служебный namespace. Постоянный .health/storage-v1 удалять нельзя.
  • HTTP предназначен для локального изолированного стенда с синтетическими данными; удалённая демонстрация требует TLS.

Источники

Контракт текущего репозитория; SeaweedFS, minio-go, S3 uploads, PostgreSQL advisory locks.

ИИ-ассистент использовался как парный программист: генерация кода, тестов и черновиков документации по моим архитектурным решениям с последующим ревью каждого модуля и переработкой по замечаниям; выбор стека, структура проекта, модель данных, обработка ошибок, логирование и границы модулей определены мной; все проверки воспроизведены мной вручную.