27 KiB
Отчёт — лабораторная 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; аутентификация выполняется до разбора параметров.
- Поток с жёстким лимитом записывается в
staging/<UUID>, одновременно считаются размер и SHA-256. Локального оригинала на API нет. - Проверяются формат и число пикселей до выделения пиксельного буфера, затем изображение полностью декодируется для обнаружения повреждённого body.
- Под транзакционной advisory-блокировкой хэша проверяются
filesи общий объект. Готовые байты не копируются повторно; отсутствующий blob восстанавливается из новой загрузки. - При необходимости серверный Copy публикует
blobs/<hash>. Одна SQL-транзакция сохраняет готовый файл и новое логическое вложение; 201 возвращается после COMMIT. - 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.
ИИ-ассистент использовался как парный программист: генерация кода, тестов и черновиков документации по моим архитектурным решениям с последующим ревью каждого модуля и переработкой по замечаниям; выбор стека, структура проекта, модель данных, обработка ошибок, логирование и границы модулей определены мной; все проверки воспроизведены мной вручную.