Files
mtusi2026lab4/REPORT.md
T
ricoromaandClaude Opus 5.5 e30b6496f1 docs: record the passing CI run on the Gitea runner
- run 325 on 5e791a6: every step of the application job exits 0
  (make check, test, validate, student_test, test-persistence,
  test-failover stop and kill); link it in REPORT.md and the evidence
  table, note that the runner had the stand images cached by then

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-29 18:54:32 +03:00

230 KiB
Raw Blame History

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

  • Автор, группа: Сафронов Роман Николаевич, БВТ2301
  • Целевая оценка 5; выбранный трек 5: трек 2 «Согласованность двух хранилищ» (сверка bucket и БД — change track2-reconciler, стоимость обхода — change track2-reconcile-cost)
  • Commit/PR: ветка solution/bvt2301-safronov, PR «ЛР 4 — БВТ2301 — Сафронов — на 5» (ссылка — после публикации). Из чистого clone проверен commit de98d77 (2026-10-29, итоговый код всех changes лабы 4): evidence/tests/clean-clone-final.md. После него менялись только документы, добавлен CI job (.github/workflows/application.yml) и исправлен restart hook: --no-recreate в scripts/restart.sh (раздел «CI»). Код приложения прежний.
  • Использованные источники, библиотеки и помощь ИИ: раздел «Источники, библиотеки и использование ИИ» в конце отчёта.

Сделано по changes OpenSpec (openspec/changes/archive/) поверх кода лабы 3:

  • s3-storage (уровни «3» и «4»): SeaweedFS в стенде с закреплённым образом и volume, приватный bucket с первой секунды, одноразовый идемпотентный s3-bootstrap, у API свой пользователь S3 с правами только на объекты bucket, служебные серверы на loopback, проверка приватности вне API make s3_check;
  • attachments (уровни «3» и «4»): загрузка PNG/JPEG сырыми байтами со структурной проверкой до записи, метаданные в PostgreSQL, скачивание только участникам, attachment_ids в сообщениях, тесты рубрики;
  • upload-consistency (уровень «4»): строка pending до PUT, компенсация в загрузке, отдельный сервис-уборщик незавершённых загрузок с grace 900 с и своим пользователем S3;
  • upload-memory (уровень «4»): места загрузки на реплику (4 + очередь 16, затем 429), срок тела, одна копия тела при PUT, буферы сокетов и сроки LB пути загрузки, замер памяти при 1–40 одновременных загрузках;
  • track2-reconciler (уровень «5», трек 2): сверка bucket и БД с dry-run, исправлением, повторным запуском и пределом изменений, пометка потерянного оригинала;
  • fix-upload-put-flake (исправление уровня «4»): причина редких 503 на загрузке — срок чтения aiohttp портил соединение в пуле клиента S3;
  • track2-reconcile-cost (уровень «5», трек 2): гипотезы до замера, профиль стоимости обхода, стратегия «HEAD на строку», глубокая сверка по SHA-256, предел скорости, ранний отказ по пределу.

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

Версии. Образ API: python:3.12.14-slim-trixie и uv 0.12.17; LB: haproxy:3.4.6-trixie; PostgreSQL: postgres:18.6-trixie; Valkey: valkey/valkey:9.1.2-trixie; S3: chrislusf/seaweedfs:4.48. Все закреплены тегом и digest индекса в Dockerfile и docker-compose.yml (таблица «Сервисы стенда» ниже). Приложение: Python 3.12, FastAPI 0.141.1, uvicorn 0.54.0, pydantic 2.13.5, pydantic-settings 2.15.0, SQLAlchemy 2.1.1 (async), asyncpg 0.31.0, alembic 1.20.0, argon2-cffi 25.1.0, redis-py 8.1.0, structlog 24.4.0, aiobotocore 3.9.2 (botocore 1.43.106, aiohttp 3.14.5), остальное строго по uv.lock. Тесты: pytest 9.1.1, httpx 0.28.1, Pillow 13.0.0 (JPEG в тестах); нагрузка: k6 2.3.0 в контейнере (grafana/k6:2.3.0@sha256:…, bench/run.py). Проверено на Docker Desktop 29.9.2 (ВМ linux/arm64, 12 CPU, 7,7 GiB), macOS на Apple M3 Pro.

Нужно на машине:

  • Docker Engine 25+ с BuildKit и Compose v2, make, openssl (секреты в make env_setup), curl;
  • python3 3.9+ для публичных make check, make test, make test-persistence, make test-failover и для драйвера скилла (make instances, make s3_check, driver.py …) — только stdlib;
  • uv — для make validate, make student_test, make test_isolated, make failure_checks, стенда замеров make bench* и make run_dev;
  • свободные порты 127.0.0.1:8080 (LB), 5433 (PostgreSQL), 6380 (Valkey), 8334 (API S3) и 18088 (make test_isolated). Стенды лаб 2 и 3 занимают те же порты: перед запуском их останавливают (make stop в их каталоге). Другой порт LB — строкой APP_OUT_PORT в .env или аргументом make (make run_docker APP_OUT_PORT=8090), затем make test BASE_URL=http://localhost:8090.

Подготовка и секреты. make env_setup создаёт .env из .env.example и config.toml из config_example.toml. В шаблоне пароли PostgreSQL и Valkey и шесть секретов S3 пустые, в новый .env подставляются случайные (openssl rand): общего секрета стенда в git нет. Печатаются только имена. Отдельно запускать env_setup не обязательно: его вызывают make run_docker, make run_dev, make test_isolated и make failure_checks. Пароль PostgreSQL и административная пара S3 задаются при создании volume: после их смены нужен make wipe_data.

Последовательность проверяющего — та, что прошла из настоящего git clone (evidence/tests/clean-clone-final.md):

git clone <fork> && cd <каталог clone> && git checkout solution/bvt2301-safronov
make env_setup        # .env (случайные пароли и секреты S3) и config.toml из шаблонов
make run_docker       # build + up -d: postgres, valkey, s3 → migrate, s3-bootstrap → api × 2 и cleaner → haproxy
make replicas         # дождаться healthy реплик; готовность стенда — haproxy (healthy)
make check            # структура skeleton
uv sync && make validate PYTHON=.venv/bin/python   # полная валидация OpenAPI 3.1
make test             # публичный smoke через LB: загрузка fixture, сообщение с attachment_ids, SHA-256, 404 постороннему
make instances        # ≥2 X-Instance-Id одной сессии через LB
make s3_check         # приватность bucket вне API: права ключей API и уборщика, аноним, порты S3
make test-persistence ACTION_SCRIPT=scripts/restart.sh   # рестарт LB, реплик, PostgreSQL, Valkey и S3: те же данные и оригинал
STOP_ONE_LOG=/tmp/stop-one.log make test-failover ACTION_SCRIPT=scripts/stop-one.sh   # остановлена одна реплика
make replicas         # вернуть остановленную реплику (тот же контейнер и ID)
curl -s -o /dev/null http://127.0.0.1:8080/health/live    # сдвиг очереди round-robin: тест выберет другую реплику
STOP_ONE_LOG=/tmp/stop-one.log make test-failover ACTION_SCRIPT=scripts/stop-one.sh   # остановлена вторая
make replicas
python3 .claude/skills/run-mtusi-messenger/driver.py --port 8080 attachment-failover --mode stop   # принявшая реплика остановлена: файл отдаёт другая
python3 .claude/skills/run-mtusi-messenger/driver.py --port 8080 attachment-storage   # байты только в приватном bucket, не в БД и не на диске API
make student_test     # свой набор через LB, тесты реплик выполняются
make reconcile        # сверка bucket и БД, dry-run: код 0 — расхождений нет
make test_isolated    # образ на временной базе test_messenger, один контейнер API: smoke + свой набор
make failure_checks   # проверки отказов на отдельном проекте mtusi-lab4-failures (~15 мин); рабочий стенд не трогается

Ожидаемо — так прошло на de98d77 (2026-10-29, все шаги с кодом 0):

  • make check, make validate, make test, make test-persistence и оба make test-failover — PASS. У test-failover failed_attempts 0, восстановление 1,08 и 1,2 с;
  • make instances — instances: 2, по 6 ответов каждой реплики;
  • make s3_check — PASS: 70 checks, bucket messenger is private;
  • attachment-failover — загрузку приняла одна реплика, после её остановки файл отдала другая с тем же SHA-256, постороннему — 404; attachment-storage — PASS, файлов оригинала в контейнерах API 0;
  • make student_test — 198 passed, сверка покрытия «252 scenarios in 13 specs, 235 tested (70 by make failure_checks), 17 excluded»;
  • make reconcile — found {}, код 0;
  • make test_isolated — 193 passed, 5 skipped: тесты реплик против одного процесса пропускаются с причиной;
  • make failure_checks — 56 passed за ~14 мин и строка сводки журнала PostgreSQL стенда отказов [failure_checks] postgres log: … crash markers 0.

Строка STOP_ONE_LOG называет TARGET_INSTANCE_ID, который выбрал тест, и полный ID остановленного контейнера; docker compose ps -a показывает его Exited. Порт 8080 хоста был занят посторонним контейнером, поэтому клон поднимался на APP_OUT_PORT=8090 под своим проектом compose; это две строки .env до make env_setup (evidence/tests/clean-clone-final.md).

Вариант README без make — те же compose-команды, но после make env_setup: без config.toml compose падает с bind source path does not exist (он монтируется read-only, create_host_path: false), без секретов — на «… is empty».

make env_setup
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build   # тот же стенд, что make run_docker
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/health/ready   # 200 — готов

CI

Workflow skeleton .github/workflows/contracts.yml проверяет только контракт и не менялся. Сборку, стенд и make test ведёт свой job .github/workflows/application.yml (CONTRIBUTING.md, «CI») на раннере Gitea при каждом push в fork. Actions включены в настройках fork; в репозитории преподавателя они выключены, поэтому статуса job на самом PR нет — ссылка на прогон в описании PR.

Шаги job:

  1. checkout ровно commit прогона;
  2. make env_setup, make run_docker, make replicas под своим проектом compose mtusi-lab4-safronov-ci-<run_id>;
  3. готовность: /health/ready 200 через LB от двух разных X-Instance-Id;
  4. make check, make test;
  5. анонимный GET в S3 (список bucket и объектов) — 403;
  6. make validate — то же, что проверял бы contracts.yml (ниже);
  7. make student_test через LB, тесты реплик выполняются;
  8. make test-persistence;
  9. make test-failover в режимах stop и kill, после каждого — make replicas;
  10. при любом исходе — уборка стенда, его volumes и образа прогона.

На этом Gitea github.server_url — внутренний адрес http://gitea:3000, и контейнер job его не резолвит. Поэтому checkout job берёт публичный адрес литералом. contracts.yml skeleton на этом раннере падает на actions/checkout с Could not resolve host: gitea и до проверок не доходит. Его make check и make validate выполняет job application.

Job на раннере нашёл дефект restart hook. Там Compose 5.4, образы стенда скачивались при первом up. Строка scripts/restart.sh up -d --wait postgres valkey s3 должна была лишь дождаться тех же контейнеров, а пересоздала все три: метка контейнера хранит digest индекса образа, повторный up сравнивает её с digest манифеста платформы. s3-bootstrap (network_mode: service:s3) после пересоздания s3 не стартует (код 128), за ним падает start api haproxy, и make test-persistence отвечает «restart hook failed». Данные целы: пересоздан только контейнер, volume тот же. Проверка из чистого clone этого не поймала: образы были в кэше, а Compose 5.6 так не делает. Исправлено --no-recreate. Воспроизведение (Compose 5.4.0 и 5.6.1, с флагом и без) и прогон после правки на отдельном демоне Docker с пустым кэшем — в evidence/tests/ci-application.md.

Раннер (act_runner, образ gitea/runner-images:ubuntu-latest) запускает job в контейнере на том же Docker, что и стенд. Поэтому отличия от локального запуска собраны в override .github/ci/compose.yml:

  • bind mount файлов рабочего каталога (их нет на хосте раннера) заменены configs из переменных окружения — побайтная копия файла (.github/ci/stand-env.sh; без последнего перевода строки HAProxy конфиг не принимает);
  • порты на хост не публикуются: job подключается к сети стенда и ходит на http://haproxy:8080;
  • образ API — с тегом прогона, а не общим mtusi-messenger:lab4.

Секретов CI не получает: пароли и ключи — случайные из make env_setup и живут только в прогоне. Права токена — contents: read, pull_request_target нет. Прогоны идут по очереди и без отмены: прерванный job оставил бы стенд на общем хосте раннера, а шаг уборки хвостов удаляет только проекты с префиксом этого job. Без make s3_check, make test_isolated, make failure_checks и замеров: им нужны порты хоста и отдельные проекты, их вывод — в evidence/.

На раннере job прошёл целиком на 5e791a6 (run 325, 2026-10-29, ~5 мин). Все шаги — код 0:

  • make check, make test, make validate — PASS;
  • анонимный GET в S3 — 403;
  • make student_test — 198 passed;
  • make test-persistence — PASS;
  • make test-failover stop и kill — PASS, failed_attempts 0.

Первые два прогона упали: на checkout по внутреннему адресу и на дефекте restart hook (оба — выше). До push те же шаги прошли локально в контейнере образа раннера (evidence/tests/ci-application.md).

Сценарий защиты

make test                                   # 1–2. fixture, сообщение с attachment_ids, второй участник — тот же SHA-256, третий — 404 на метаданные и байты
D=.claude/skills/run-mtusi-messenger/driver.py
python3 $D --port 8080 upload --token <токен> --chat <id> --file tests/fixtures/sample.png   # то же по шагам
python3 $D --port 8080 download --token <токен второго участника> --attachment <id>         # SHA-256 оригинала
make s3_check                               # 2. прямой анонимный GET в S3 — 403 (с хоста и из сети стенда)
make test-persistence ACTION_SCRIPT=scripts/restart.sh   # 3. рестарт всего стенда: прежний токен, тот же оригинал
python3 $D --port 8080 attachment-failover --mode kill   # 3. загрузившая реплика убита: скачивание через другую, тот же SHA-256
python3 $D --port 8080 attachment-storage   # 4. схема, ключ, объект в bucket, docker diff реплик — файла оригинала нет
# уровень 4
python3 $D --port 8080 upload-consistency   # S3 заморожен и сбой фиксации ready: 503, компенсация, уборщик убирает остатки
make failure_checks                         # отказы S3, PostgreSQL, места загрузок, срок тела, уборщик, сверка (~15 мин)
# уровень 5, трек 2
python3 $D --port 8080 reconcile-cycle      # расхождения с обеих сторон: dry-run, --apply, повтор = 0 (~2 мин)
make reconcile                              # разовая сверка, dry-run; APPLY=1 — исправить
make stop && make bench_reconcile_quick     # самопроверка профиля стоимости (~4 мин); полная метка — evidence/reconcile/baseline/

Полные метки уже лежат в evidence/uploads/baseline/ и evidence/reconcile/baseline/ (разделы «Одновременные загрузки» и «Стоимость сверки»), на защите показываются они: прогоны идут по ~50 мин.

Остановка и удаление данных

  • make stop — остановить контейнеры; S3 останавливается плавно, ~15 с.
  • make down — удалить контейнеры; volumes postgres_data и s3_data остаются, кэш Valkey теряется (он без volume, данные от этого не страдают).
  • make wipe_data — удалить контейнеры и volumes mtusi-lab4_postgres_data и mtusi-lab4_s3_data, только после ввода yes; оба тома запрос называет по имени. Следующий make run_docker поднимает пустую базу со схемой и пустой приватный bucket.

Старый .env и консоль (changes s3-storage, upload-consistency)

make env_setup создаёт новый .env из .env.example со случайными паролями PostgreSQL и Valkey и шестью секретами S3 и печатает только их имена. Существующий .env он не перезаписывает, а дописывает в конец переменные шаблона, которых в нём нет: секреты — случайными значениями, остальные — значениями шаблона; прежние строки не меняются, печатаются только имена (с change upload-consistency).

Шаг оператора для .env, созданного до change s3-storage. Перенесите блок S3 из .env.example руками. Пять пустых секретов (S3_ROOT_ACCESS_KEY, S3_ROOT_SECRET_KEY, S3_JWT_SIGNING_KEY, S3_API_ACCESS_KEY, S3_API_SECRET_KEY) заполните значениями openssl rand -hex 32. Без них любая команда compose останавливается с сообщением «… is empty, copy S3 lines from .env.example». (Переменные, которых в .env нет вовсе, теперь допишет и make env_setup; пустые значения уже существующих строк он не трогает.)

Шаг оператора для .env, созданного до change upload-consistency. Достаточно make env_setup (его вызывает и make run_docker): он допишет S3_CLEANER_ACCESS_KEY и S3_CLEANER_SECRET_KEY со случайными значениями и напечатает «added to existing .env: S3_CLEANER_ACCESS_KEY S3_CLEANER_SECRET_KEY». Без них compose останавливается на «S3_CLEANER_… is empty, run make env_setup».

  • make run_docker. Порядок старта:

    • postgres, valkey и s3 до healthy;
    • одноразовые migrate (с change upload-consistency — ещё и индекс CONCURRENTLY) и s3-bootstrap (приватный bucket, пользователи API и уборщика, проверки приватности);
    • api × 2 и cleaner (уборщик незавершённых загрузок) после успешного завершения обоих;
    • haproxy на 127.0.0.1:8080.

    Проверки — make test, make student_test, make s3_check.

  • make run_dev. Цепочка make upgrade, make start_cache и make start_s3: up -d --wait s3, затем up --no-deps --exit-code-from s3-bootstrap s3-bootstrap, код bootstrap — код цели. Затем сервис на 127.0.0.1:8080. В консоли S3 доступен на 127.0.0.1:8334. Уборщика в консоли нет: зависшие загрузки консольного API убирает уборщик стенда (та же база) или разовый docker compose run --rm --no-deps cleaner --once. Порт 8080 занят HAProxy работающего стенда, поэтому перед make run_dev — make stop (или docker compose stop haproxy); свой набор против консоли — make student_test EXPECT_REPLICAS=1.

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

клиент → 127.0.0.1:8080 → haproxy → api × 2 → postgres (метаданные, сессии, ключи идемпотентности)
                                            → valkey (кэш карточек чатов)
                                            → s3 (байты вложений; SeaweedFS, приватный bucket)
                          migrate (один раз) ──→ postgres
                          s3-bootstrap (один раз, в сетевом пространстве s3) ──→ s3
                          cleaner (долгоживущий, без портов) ──→ postgres (строки pending), s3 (их объекты)

Источник истины — PostgreSQL: пользователи, чаты, сообщения, сессии, ключи идемпотентности и метаданные вложений (строка attachments с ключом объекта, размером, SHA-256 и статусом). S3 хранит только байты оригинала по ключу, который назначает сервер. Valkey — общий кэш неизменяемых карточек чатов, его отказ — обход в PostgreSQL. Реплики api одинаковы и взаимозаменяемы, порта на хосте у них нет; в памяти процесса нет ничего, от чего зависит ответ. Единственная точка входа — HAProxy.

Что перенесено из лабы 3 (репозиторий mtusi2026lab3-safronov, ветка solution/bvt2301-safronov, commit ce89eba; здесь — commit 5d5d8f9 «carry lab 3 over») без изменения поведения, кроме перечисленного ниже:

  • из лабы 2: PostgreSQL как источник истины, миграции alembic отдельным сервисом migrate, регистрация с паролем (Argon2id в потоке), вход по Basic только на POST /auth/sessions, остальное — Bearer-сессия в таблице sessions, кэш карточки чата в Valkey, keyset-пагинация, формат ошибок контракта;
  • из лабы 3: HAProxy перед двумя репликами без портов на хосте, X-Instance-Id в каждом ответе, обязательный Idempotency-Key с ключом и сообщением в одной транзакции, замеренная цепочка таймаутов, поочерёдная замена make rolling_update, ранний обработчик SIGTERM, строгие курсор и UUID на входе;
  • свои тесты (make student_test, make test_isolated, make failure_checks) и стенд замеров bench/ с профилями лаб 2 и 3.

Что изменилось при переходе 3 → 4:

  • переход API — вложения (contracts/README.md, «Вложения (с lab4)»): ручки загрузки, метаданных и скачивания, attachment_ids в сообщении (по умолчанию [], прежние текстовые POST валидны), пустой текст только с вложением;
  • миграции только расширяют схему: ef25d50b01a8 (таблицы attachments и message_attachments, ослабленное NOT VALID ограничение текста), 739b8f04d5fb (частичный индекс строк pending CONCURRENTLY), 5c3e1f0a9b7d (attachments.lost_at);
  • новые сервисы стенда: s3, одноразовый s3-bootstrap, уборщик cleaner на образе API; проект compose mtusi-lab4, образ mtusi-messenger:lab4 — чтобы не подключиться к данным лабы 3;
  • хэш идемпотентности учитывает attachment_ids только непустым: ключ, сохранённый версией лабы 3, повторяется без 409;
  • /health/ready S3 не проверяет: отказ S3 — 503 только на путях вложений;
  • у HAProxy — свой timeout server 30 с пути загрузки и буферы сокетов, у реплик — буфер приёма сокетов 512 KiB, ROLLOUT_DRAIN_TIMEOUT 90 с вместо 12 с.

Транзакционные границы лабы 4. У ручек вложений сессия БД — на шаг, а не на запрос: соединение пула не держится на время передачи байтов. Остальные ручки — одна сессия на запрос, как в лабе 3. Commit делает сервис, изоляция READ COMMITTED:

Операция Шаги
загрузка проверки 401 → 400 → 404 → 415 → 413 без тела → место загрузки (иначе 429) → тело со счётчиком и сроком → проверка изображения и SHA-256 → tx1: INSERT attachments (pending, ключ) → commit → PUT в S3 → tx2: pending → ready только у непомеченной строки → commit → 201. Сбой между PUT и отправкой COMMIT — DELETE объекта и 503; исход COMMIT неизвестен — объект остаётся уборщику
отправка сообщения членство → вложения: все ready и этого чата (иначе 404) → захват ключа идемпотентности → INSERT messages → INSERT message_attachments одной вставкой → один commit
метаданные и скачивание строка ready и членство в чате вложения (иначе 404); байты — GET из S3 потоком, сессия БД к этому времени закрыта
уборщик на строку pending старше grace: tx пометки (FOR UPDATE SKIP LOCKED, updated_at) → commit; tx уборки: та же блокировка → DELETE объекта в S3 → DELETE строки → commit
сверка чтения — короткие сеансы на страницу; каждое действие — после перепроверки в БД и HEAD; пометка и снятие пометки — условный UPDATE колонки lost_at

Подробно — разделы «Вложения», «Согласованность БД и S3» и «Сверка хранилищ» ниже.

Соответствие переменных .env.example

.env.example skeleton предлагает «логические» имена и просит сопоставить их с настоящими. Критерий — кто читает значение: то, что читают compose и контейнеры зависимостей, живёт в .env, то, что читает только приложение, — в секциях config.toml (согласование 2026-09-29). Имена S3 и лимиты вложений — в таблице «Соответствие имён skeleton S3_*» ниже.

Имя skeleton Где у нас Почему так
APP_HOST режим APP__RUN_MODE: console — 127.0.0.1, docker — 0.0.0.0 (литерал в environment compose и ENV в Dockerfile) адрес следует из режима; в .env режим не хранится, чтобы консоль и docker работали из одного файла
APP_PORT APP__PORT в .env (8080) — порт каждой реплики, на нём же healthcheck и проверки HAProxy; APP_OUT_PORT (8080) — порт на 127.0.0.1 хоста, его публикует только HAProxy параметр приложения в формате настроек; внешний порт приложение не читает, поэтому без секции
APP_ENV не используется окружение одно — учебный стенд
SESSION_TTL_SECONDS [auth] session_ttl_seconds в config.toml, по умолчанию 3600; разовая подмена — AUTH__SESSION_TTL_SECONDS читает только приложение; мост из .env с этим именем окружение бы не перекрыло (.claude/rules/settings.md)
DATABASE_URL_FILE не используется: URL собирает приложение из [database], адрес и порт в docker — POSTGRES_HOST / POSTGRES_PORT, пароль — мостом из POSTGRES_PASSWORD в .env пароль нужен ещё и контейнеру PostgreSQL, поэтому один источник — .env
SESSION_STORE postgres: таблица sessions, общая для всех реплик, без кэша — отзыв мгновенный другого хранилища сессий нет; Valkey без persistence стёр бы сессии рестартом
CACHE_URL_FILE не используется: адрес и порт Valkey — VALKEY_HOST, VALKEY_PORT и VALKEY_OUT_PORT в .env, пароль — мостом из VALKEY_PASSWORD в [cache] password; срок, окно пропуска и пул — [cache] как у PostgreSQL: пароль нужен и серверу Valkey
IDEMPOTENCY_TTL_SECONDS [idempotency] ttl_seconds в config.toml, по умолчанию 86400 (24 ч); разовая подмена — IDEMPOTENCY__TTL_SECONDS читает только приложение; срок меньше 86400 нарушает контракт и применяется только в проверках
API_REPLICAS API_REPLICAS в .env (2), deploy.replicas: ${API_REPLICAS:-2} сервиса api; Makefile — API_REPLICAS ?= 2 (make replicas, EXPECT_REPLICAS тестов) приложение его не читает, поэтому имя без секции

Роль S3 и её граница

S3 хранит только байты вложений, метаданные лежат в PostgreSQL. Пишет и читает S3 API своим ключом; удаляет ещё уборщик незавершённых загрузок своим ключом (только чтение и удаление). Change s3-storage дал сервер, bootstrap, клиент src/infra/s3/ и стенды, change attachments — ручки вложений и attachment_ids (раздел «Вложения» ниже), change upload-consistency — компенсацию в загрузке и уборщика (раздел «Согласованность БД и S3»), change upload-memory — места загрузки, срок тела, одна копия тела и сроки LB пути загрузки (раздел «Память и сроки загрузки»).

Сервер — SeaweedFS 4.48 (выбор подтверждён автором 2026-10-20). MinIO отвергнут: на 2026-10-20 его образы minio/minio и minio/mc из чистого clone не скачивались («pull access denied», quay.io/minio — 401 без авторизации), а стенд должен подниматься из репозитория. RustFS моложе, и его bootstrap требует mc или своего кода подписи admin API; у SeaweedFS bucket и пользователи создаются weed shell из того же закреплённого образа. Проба до выбора — design change s3-storage. Три места, где SeaweedFS по умолчанию не приватен, закрыты:

  • без учётных записей S3 открыт анониму — административная пара задана в окружении сервера с первого старта;
  • master, filer и volume слушают все интерфейсы — -ip.bind=127.0.0.1;
  • gRPC шлюза без ключа подписи принимает учётную запись администратора — ключ подписи обязателен.

Телеметрия, Iceberg, Lance и встроенный IAM API выключены.

Сервисы стенда

Роль Сервис Версия / digest индекса Health / readiness Volume Сеть / порт Credentials
load_balancer haproxy haproxy:3.4.6-trixie@sha256:e2739156…db26 /lb/ready на :8404 изнутри: есть готовая реплика — 127.0.0.1:8080 → 8080; :8404 только в сети нет
api × 2 api образ из Dockerfile, база python:3.12.14-slim-trixie@sha256:f77ac9e4…e51f HEALTHCHECK образа: /health/ready — (config.toml read-only) 8080 только в сети пароли PostgreSQL и Valkey, ключи пользователя API в S3 — мосты DATABASE__PASSWORD, CACHE__PASSWORD, S3__ACCESS_KEY_ID, S3__SECRET_ACCESS_KEY из .env
миграции migrate образ API код выхода 0 (service_completed_successfully) — сеть пароль PostgreSQL
postgres postgres postgres:18.6-trixie@sha256:5a5a84b1…9722 pg_isready -h 127.0.0.1 postgres_data 127.0.0.1:5433 → 5432 POSTGRES_PASSWORD
кэш (необязательная роль) valkey valkey/valkey:9.1.2-trixie@sha256:418652cf…9dfd valkey-cli ping с паролем — (persistence выключен) 127.0.0.1:6380 → 6379 VALKEY_PASSWORD
s3 s3 chrislusf/seaweedfs:4.48@sha256:4e61d15f…7872d wget: /cluster/healthz master, том зарегистрирован (DataNodes в /dir/status), /healthz filer и шлюза (loopback) s3_data:/data 127.0.0.1:8334 → 8333 (только API S3); в сети — 8333 и gRPC шлюза 18333, служебные порты на loopback административная пара (AWS_* из S3_ROOT_*) и ключ подписи (WEED_JWT_FILER_SIGNING_KEY из S3_JWT_SIGNING_KEY) — окружением
bootstrap S3 s3-bootstrap тот же образ S3 код выхода 0; реплики и уборщик ждут service_completed_successfully — (/tmp и /data — tmpfs) network_mode: service:s3, портов нет ключ подписи, ключи API и ключи уборщика — окружением; в weed shell через stdin, в curl файлами на tmpfs
уборщик незавершённых загрузок cleaner образ API, точка входа python -m src.cleaner healthcheck образа выключен (HTTP не слушает); живость — журнал; ждёт postgres healthy, migrate и s3-bootstrap — (config.toml read-only) портов нет пароль PostgreSQL (DATABASE__POOL_SIZE: 1), ключи пользователя уборщика в S3 (S3__* из S3_CLEANER_*)

Лимиты:

  • postgres 2 CPU / 1 ГБ, valkey 0,5 / 128 МБ, s3 1 / 512 МБ;
  • s3-bootstrap 0,5 / 128 МБ, migrate 0,5 / 256 МБ;
  • api 1 / 512 МБ на реплику, haproxy 1 / 256 МБ;
  • cleaner 0,25 / 256 МБ (в простое ~91 MiB, evidence/attachments/cleaner-process.md).

Сумма — 7,75 CPU / 3,5 ГиБ, без одноразовых сервисов — 6,75 CPU / 3,1 ГиБ. Соединения PostgreSQL: API_REPLICAS × pool_size + migrate + уборщик = 2 × 10 + 1 + 1 = 22, во время make rolling_update (три реплики) — 32, при max_connections 100 (переполнения пула нет, max_overflow 0). Секреты по сервисам проверены в evidence/s3/privacy.md (раздел 4) и, с уборщиком, в evidence/s3/cleaner-key.md (раздел 3).

Bootstrap S3 и его безопасный повтор

Сервис s3-bootstrap выполняет infra/s3/bootstrap.sh в режиме apply. Каждый шаг можно повторять:

  1. Bucket: есть — «exists», нет — создаётся.
  2. Анонимный доступ — none. Если он открыт, bootstrap его закрывает.
  3. Политика api-objects (s3:GetObject, s3:PutObject, s3:DeleteObject на arn:aws:s3:::<bucket>/*) создаётся или обновляется.
  4. Пользователь api: если его нет, создаётся с ключами из .env; политика привязывается.
  5. Чужие ключи пользователя удаляются, нужный создаётся, если его нет.
  6. Проверка ключом API: PUT, GET и DELETE проверочного объекта. SignatureDoesNotMatch значит, что секрет в .env сменился, — ключ пересоздаётся.
  7. Проверки приватности: ключ API получает 403 на список и создание bucket, аноним — 403 на чтение и список. Расхождение — FAILED: <шаг>, код 1, реплики не стартуют.

С change upload-consistency шаги 3–6 общие для двух пользователей: api и cleaner с политикой cleaner-objects (s3:GetObject, s3:DeleteObject на объекты своего bucket — без записи, списка и прав на bucket). Ключ уборщика ждётся и проверяется DELETE несуществующего ключа (204; PUT ему запрещён), новый секрет уборщика так же распознаётся по SignatureDoesNotMatch. Проверки каждого запуска: ключ уборщика читает проверочный объект, получает 403 на запись и список и удаляет его; после этого GET ключом API — 404 (evidence/s3/cleaner-key.md).

Повтор не меняет правильное состояние: bucket и объекты сохраняются, пользователи не пересоздаются (evidence/s3/bootstrap.md, раздел 2; evidence/s3/cleaner-key.md, раздел 1).

Смена секрета API: новое значение в .env, затем make run_docker. Bootstrap пересоздаёт ключ, прежний секрет перестаёт действовать (раздел 3), а реплики с новым окружением пересоздаёт compose.

Bootstrap работает не административной парой S3, а weed shell на loopback сервера с ключом подписи. Административная пара есть только у сервера. make rolling_update bootstrap не запускает: он, как миграции, только расширяет права. Его изменения применяет docker compose up -d s3-bootstrap или make run_docker.

Критичные и некритичные зависимости готовности

  • PostgreSQL критичен: в нём источник истины и сессии. /health/ready выполняет SELECT 1 со сроком 2 с, без него — 503.
  • Valkey не критичен: это кэш, без него обязательные запросы идут в PostgreSQL.
  • S3 не критичен: без него недоступны только пути вложений (503 unavailable), текст работает. /health/ready к S3 не обращается: иначе отказ S3 вывел бы из LB все реплики, и текст перестал бы работать тоже. Проверка — test_readiness_without_object_storage в make failure_checks.

Сроки клиента S3 (change fix-upload-put-flake)

Клиент — aiobotocore поверх aiohttp, без повторов (total_max_attempts=1), пул keep-alive на [s3] max_connections с простоем до 15 с. Сроков два, и оба задаёт приложение:

  • [s3] connect_timeout_seconds (1 с) — на установку соединения;
  • asyncio.timeout([s3] timeout_seconds) (5 с) — на весь вызов в _call и на каждый блок потокового чтения в _read_chunk.

Собственного срока чтения aiohttp нет (read_timeout=None). Раньше он был равен timeout_seconds и давал редкие 503 на исправном S3. Цепочка такая:

  • после скачивания оригинала с паузой чтения (буфер ответа больше 512 KiB: read_bufsize по умолчанию 256 KiB, порог паузы вдвое больше) aiohttp 3.14.5 — версия uv.lock, другие пробой не проверялись — перевзводил этот срок в resume_reading() уже у соединения, вернувшегося в пул;
  • через 5 с простоя срок срабатывал на простаивающем соединении, и пул отдавал его следующему вызову (keep-alive 15 с не истёк);
  • PUT падал за 1 мс с ReadTimeoutError, а S3 видел заголовки без тела (botocore ставит Expect: 100-continue).

Механизм, захват пакетов и проверенные гипотезы — evidence/s3/idle-connection.md и design change. Повтор не добавлен: он скрыл бы причину, а таймаут порченого соединения не отличить от таймаута зависшего S3. Всякое чтение из S3 идёт только через _call и _read_chunk, поэтому без sock_read ни один вызов не остаётся без срока (.claude/rules/infra.md).

Соответствие имён skeleton S3_*

Имя .env.example skeleton Реальная конфигурация
S3_ENDPOINT S3__HOST и S3__PORT: в консоли — мосты 127.0.0.1 и ${S3_OUT_PORT}, в docker — S3_HOST и S3_PORT через x-s3-env
S3_REGION [s3] region в config.toml (us-east-1, нужен подписи SigV4)
S3_BUCKET S3__BUCKET в .env: читают приложение и bootstrap
S3_ACCESS_KEY_ID_FILE, S3_SECRET_ACCESS_KEY_FILE мосты S3__ACCESS_KEY_ID=${S3_API_ACCESS_KEY} и S3__SECRET_ACCESS_KEY=${S3_API_SECRET_KEY}: значения из .env, а не файлы, как с DATABASE_URL_FILE
MAX_UPLOAD_BYTES константа ATTACHMENT_MAX_BYTES = 10 485 760 в src/utils/constants.py, не настройка
MAX_IMAGE_PIXELS константа ATTACHMENT_MAX_PIXELS = 40 000 000 там же, не настройка

Лимиты вложений задаёт контракт, они одинаковы на всех установках, поэтому ни окружение, ни .env, ни config.toml их не меняют (спек service-configuration, «Лимиты вложений — константы контракта»; design change attachments, решение 10). Проверка: обычный API стенда отказов запускается с MAX_UPLOAD_BYTES=1 и MAX_IMAGE_PIXELS=1, а sample.png всё равно принимается — 201 (test_environment_does_not_change_limits, evidence/tests/failure-checks.md).

Вложения (change attachments)

POST /chats/{id}/attachments?filename=…  (сырые байты PNG/JPEG)
  └─ вход: короткая сессия БД (CurrentUserBrief)
  └─ членство (404) → Content-Type (415) → Content-Length (413)
  └─ тело со счётчиком (413 сразу за 10 MiB) → структура и SHA-256 в потоке (415 / 413)
  └─ tx1: строка attachments, status=pending, object_key  ── commit
  └─ PUT <база>/attachments/<id>/original в S3
  └─ tx2: pending → ready                                 ── commit
       (сбой до отправки COMMIT или строки уже нет — DELETE объекта, 503)
  └─ 201 Attachment (status=ready)
GET /attachments/{id}           → строка ready + членство (404 иначе)
GET /attachments/{id}/content   → GET из S3 потоком (StreamingResponse), Content-Length, nosniff
POST /chats/{id}/messages {text, attachment_ids}
  └─ членство → вложения: все ready и этого чата (404 до захвата ключа)
  └─ ключ → сообщение → message_attachments (position) ── один commit

Порядок записи и отказы (design, решение 1). Объект, который записывает API, известен PostgreSQL до записи: строка pending с object_key фиксируется до PUT.

Отказы на каждом шаге, компенсация и уборка — раздел «Согласованность БД и S3» ниже. Строку pending API не показывает (метаданные, байты и ссылка в сообщении — 404 с тем же message, что у неизвестного id).

Проверка изображения — структурная, без декодирования пикселей (src/utils/image.py, только stdlib; решение 2, подтверждено пользователем):

  • тип — по сигнатуре; Content-Type запроса должен совпасть, иначе 415 (подмена MIME);
  • размеры — из IHDR / SOF до распаковки: больше 40 млн пикселей — 413;
  • PNG: CRC каждого чанка, IHDR первым, нет неизвестных критичных чанков, IDAT подряд, поток zlib распаковывается блоками по 1 MiB и ровно в объём по размерам (больше — «бомба», 415 сразу), типы фильтров строк, IEND; JPEG: маркеры и длины сегментов, один SOF, скан, EOI;
  • байты после IEND / EOI — часть оригинала (входят в размер и SHA-256);
  • пик памяти проверки ≤ 3,2 MiB при любом числе пикселей; «бомба» 100 × 100 → 200 MiB отклоняется за 1 мс; корпус 12 000 файлов macOS — ни одного ложного отказа (design change attachments, «Уточнения apply», п. 1).

Схема (ревизия ef25d50b01a8, решение 3): attachments (составной FK (chat_id, owner_id) → chat_members — владелец участник чата; CHECK размера, SHA-256 32 байта, типа, статуса, длины и символов filename; уникальный object_key) и message_attachments (PK (message_id, position), 0–9, уникальная пара сообщение–вложение, индекс по attachment_id, FK без каскада — вложение со ссылкой не удалить). Ограничение текста сообщения ослаблено с 1–4000 до 0–4000 NOT VALID: пустой текст допустим с вложением, правило «текст или вложение» держит сервис. История читает attachment_ids коррелированным подзапросом ARRAY(…) по pk_message_attachments, индекс истории прежний.

Ключ объекта — <имя базы>/attachments/<id>/original, назначает сервер и хранит в строке. filename только отображается: 400 на /, \, управляющие символы (Cc) и пустое / из пробелов, остальное (включая символы направления текста) хранится как прислано. Процент-коды имени — строгий UTF-8: Starlette заменил бы неверный байт на U+FFFD, поэтому ручка разбирает сырую строку запроса сама, и filename=a%FFb.png — 400, а не 201 с искажённым именем (сценарий «Имя не в UTF-8»).

Память одной загрузки — одно тело (решение 6). Тело копится в io.BytesIO, getvalue() отдаёт bytes над тем же буфером без копии (bytes, а не bytearray: его botocore копирует). В образе MALLOC_MMAP_THRESHOLD_=131072: с динамическим порогом glibc после первой загрузки растил буфер в куче, и realloc на миг держал два тела. Проба в образе API, три загрузки 10 MiB подряд в одном процессе: пик RSS 1,99 тела до правки → 1,19–1,20 после (одно тело и блоки чтения botocore по 1 MiB; design, «Уточнения apply», п. 10).

Без сессии БД на всю передачу (решение 5). Зависимость get_db_session закрывается после отправки ответа, и её срок 6 с охватил бы чтение тела и отдачу потока: медленные 10 MiB оборвались бы на 6-й секунде. Ручки вложений берут короткий вход (CurrentUserBrief), сервис открывает сессию на каждый шаг; загрузка 12,4 с и скачивание 13,1 с через LB проходят (evidence/attachments/slow-transfer.md).

Идемпотентность: хэш тела включает attachment_ids только непустым (str(UUID), нижний регистр, порядок значим) — ключ, сохранённый версией без вложений, повторяется после замены реплик; повтор отдаёт те же attachment_ids.

Отказ S3 — 503 только на загрузке и скачивании байтов; метаданные, сообщения со ссылкой на готовое вложение, история и /health/ready работают.

Согласованность БД и S3 (change upload-consistency)

Инвариант порядка записи: объект, который пишет API, известен PostgreSQL до записи — строка pending с object_key фиксируется до PUT. Поэтому любой обрыв после неё оставляет «след» в БД, по которому объект можно найти и убрать. Механизм — два слоя: компенсация в самой загрузке (быстро, без гарантии) и уборщик (гарантия, после grace).

Компенсация в загрузке (AttachmentService._mark_ready, _compensate; design, решение 1). Объект удаляется сразу, только когда точно известно, что вложение не станет ready:

Где сбой Ответ Объект Строка pending
проверки и тело (401, 400, 404, 413, 415, обрыв клиента) 4xx не записывался нет
tx1 — запись строки (отказ PostgreSQL) 503 не записывался нет
PUT: S3 недоступен, срок 5 с, 5xx, отказ в доступе 503 не трогается: при замороженном S3 тело не уходит без ответа сервера (проба), а DELETE ждал бы ещё 5 с уборщику
tx2 до отправки COMMIT (UPDATE, пул, срок на нём) 503 (отказ БД) или 500 (дефект) удаляется до ответа ключом API, без повторов; не удалось — warning, остаётся уборщику уборщику
tx2 на самом COMMIT (связь оборвалась во время фиксации) 503 не трогается: вложение могло стать ready, удаление дало бы ready без объекта уборщику, если фиксации не было
mark_ready → 0 строк (строку убрал или пометил к уборке уборщик: загрузка длилась дольше grace) 503, error в журнале удаляется до ответа нет или помеченная — уборщику
процесс убит, задача отменена — не трогается уборщику

Граница «до отправки COMMIT» — флаг, который ставится прямо перед commit() и только при найденной строке. Компенсация не удаляет строку: чаще всего tx2 падает из-за отказа PostgreSQL, и удаление строки упало бы так же; а строка без объекта безопасна — её уберёт уборщик. Обратный порядок (строка, потом объект) при сбое второго шага оставил бы объект без строки.

Уборщик — отдельный сервис cleaner (python -m src.cleaner), а не фоновая задача реплик: N реплик были бы N уборщиками, а остановка реплики обрывала бы проход. Раз в [cleaner] interval_seconds (60 с) он выбирает строки pending старше [cleaner] pending_grace_seconds (900 с) выборками по 100 (keyset по (created_at, id), частичный индекс ix_attachments_pending_created_at — план в evidence/migrations/pending-index.md) и каждую убирает в два шага (после двух verify):

  1. транзакция пометки: SELECT … FOR UPDATE SKIP LOCKED той же строки (всё ещё pending и старше порога; нет — пропуск), updated_at = now() уборщика, commit;
  2. транзакция уборки: та же блокировка (нет строки или занята — пропуск), DELETE объекта ключом уборщика (отсутствие объекта — тоже 204), DELETE строки, commit.

Объект удаляется раньше строки: сбой между ними оставляет строку без объекта (следующий проход её доуберёт, пометка ставится заново), а не объект без строки. Строки ready выборка не видит никогда. SIGTERM доводит только текущий шаг до commit или отката (≤ 6 с), между шагами уборщик останавливается сам.

Зачем блокировка. Загрузка короче grace, но процесс API, замороженный дольше grace (docker pause, пауза ВМ), после разморозки дойдёт до mark_ready. Без блокировки порядок «PUT → уборщик удалил объект → mark_ready сделал строку ready» дал бы ready без объекта (201 клиенту, 500 при скачивании). С блокировкой mark_ready ждёт commit уборщика и находит 0 строк → компенсация и 503; если mark_ready успел раньше, строка уже ready, и уборщик её не выбирает.

Зачем пометка (замечание W1 verify). В первой версии блокировка, DELETE объекта и DELETE строки шли одной транзакцией. Её откат уже после удачного DELETE в S3 (сбой БД перед COMMIT, срок, заморозка уборщика) или DELETE, который S3 выполнил после срока вызова, возвращали строку pending как была, и ждавший mark_ready делал её ready без объекта. Теперь mark_ready переводит в ready только непомеченную строку (updated_at = created_at: вставка пишет оба поля одним значением), а пометка зафиксирована до DELETE объекта. Помеченная строка ready уже не станет: загрузка получает 503 и удаляет свой объект, уборку доводит следующий проход (test_cleaner_failure_after_object_delete). Миграции нет, CHECK updated_at >= created_at выполняется.

Зачем DELETE объекта под блокировкой (замечание W1 повторного verify). В первой редакции пометки объект удалялся между транзакциями, без блокировки. Реплика до 87c48b9 пометку не проверяет: она успевала сделать строку ready между commit пометки и DELETE объекта, и уборщик удалял объект готового вложения без всякого сбоя. Теперь объект и строка удаляются одной транзакцией под блокировкой: такая реплика либо успела раньше (строка ready с целым объектом, уборщик её не находит), либо ждёт commit и находит 0 строк (проба блокировок — design, «Уточнения apply», п. 21). Цена — вызов S3 внутри транзакции: ≤ 5 с ([s3] timeout_seconds) внутри срока шага 6 с, меньше idle_in_transaction_session_timeout 10 с; пул уборщика свой, из одного соединения.

Grace period и его обоснование. Граница живой загрузки B — от записи created_at строки до фиксации ready: tx1 ≤ request_timeout_seconds (6 с; created_at назначается до tx1) + PUT ≤ [s3] timeout_seconds (5 с) + tx2 ≤ 6 с, B = 2 × 6 + 5 = 17 с. Тело и проверка изображения идут до created_at: медленный клиент B не удлиняет. Grace 900 с — запас ×50 над B: покрывает заморозку процесса API (профиль failover с docker pause, остановки ВМ Docker Desktop) и расхождение часов консольного API на macOS и уборщика в ВМ (секунды). Цена — незавершённые загрузки (а это только сбои) живут до ~16 мин (grace + интервал + проход). Уборщик при старте проверяет grace > 2 × request_timeout_seconds + s3.timeout_seconds по своим настройкам и иначе не стартует (код 2, ошибка называет grace, оба срока и границу — evidence/attachments/cleaner-process.md). Стенд отказов — grace 20 с и интервал 1 с: честное значение для тех же сроков по умолчанию. Отвергнуто: 60 с (запас ×3,5 съедает одна пауза ВМ), 24 ч (остатки сбоев лежат сутки, защита без разового запуска невозможна).

Права S3 уборщика — свой пользователь cleaner: чтение и удаление объектов своего bucket, без записи, списка и прав на bucket; ключи S3_CLEANER_* только у s3-bootstrap и cleaner (make s3_check — 68 проверок, evidence/s3/cleaner-key.md). Уборка чтение не использует (HEAD перед удалением не нужен: удаление идемпотентно, а промах HEAD — не основание удалять). С change track2-reconciler уборщику добавлен список объектов — только с префиксом вложений своей базы — для сверки bucket и БД (раздел «Сверка хранилищ»; 70 проверок evidence/s3/cleaner-list.md).

Отказы хранилищ в уборщике. S3 недоступен, не ответил, отказал в доступе или bucket нет — транзакция уборки откатывается, строка остаётся pending и помеченной, проход прерывается на первой строке (warning), следующий — через интервал (пометка ставится заново). PostgreSQL недоступен — проход пропускается (warning). Непредвиденная ошибка — error с traceback, процесс живёт. Перезапуск не нужен: у клиента S3 нет повторов, пул PostgreSQL — с pool_pre_ping (test_cleaner_survives_outages). SIGTERM: текущий шаг уборки доводится до commit или отката, новые не начинаются, выход с кодом 0 за ~0,6 с.

Доказательства: evidence/attachments/consistency.md (рабочий стенд: S3 заморожен и сбой фиксации ready → 503, строки не видны, компенсация удалила объект, cleaner --once убрал обе загрузки, объектов без строки 0), evidence/tests/failure-checks.md (стенд отказов: восемь проверок вложений и уборщика, в том числе kill реплики между PUT и фиксацией), evidence/attachments/cleaner-process.md, evidence/s3/cleaner-key.md, evidence/migrations/pending-index.md.

Память и сроки загрузки (change upload-memory)

Рубрика «4»: лимиты, таймауты и потоковая обработка не дают загрузкам занять неограниченную RAM. До change лимита одновременных загрузок не было, и проба показала больше, чем было записано в этом отчёте: при записи в S3 тело копировалось ещё раз (пик загрузки — около двух тел, а не 1,2), 20 одновременных загрузок по 10 MiB без swap убивали реплику 512 МБ (OOM-kill), а недочитанное тело копилось в буферах сокетов ядра — до 32 MiB на соединение. Design change upload-memory, решения 1–9.

Места загрузки — на процесс API (src/infra/upload_slots.py, asyncio.Semaphore): [uploads] max_concurrent (4) загрузки одновременно, ещё до max_waiting (16) ждут места по порядку прихода, но не дольше wait_timeout_seconds (5 с). Очередь полна — сразу 429 rate_limited с Retry-After: 1, срок вышел — 429 по сроку; у такой загрузки нет ни строки, ни объекта. Место берётся после проверок 401 → 400 → 404 → 415 → 413 по Content-Length и до чтения тела, держится до ответа (включая запись в S3, ready и компенсацию) и освобождается при любом исходе — 201, ошибка, обрыв, срок, отмена. Ранние отказы места не ждут и не занимают: посторонний и заведомо большое тело не вытесняют живые загрузки. Ожидающая загрузка соединения с PostgreSQL не держит. Места считает каждая реплика сама — это допуск к обработке, как лимит хэшей паролей, а не состояние, от которого зависит ответ. Почему 429, а не 503: из двух кодов контракта ручки к ограничению подходит только 429 (у него одного Retry-After), 503 — «зависимость недоступна», и клиент не отличил бы занятые места от отказа S3. Места ограничивают одновременность, а не частоту, поэтому трактовка — открытый вопрос преподавателю (раздел «Открытые вопросы преподавателю», п. 1).

Срок тела — [uploads] body_timeout_seconds (30 с) на всё тело с момента, как загрузка заняла место (asyncio.timeout вокруг чтения); не успел — 400 invalid_request «Upload body was not received in time», ни метаданных, ни объекта, место свободно. Не срок простоя между блоками: клиент, который шлёт по байту раз в 29 с, держал бы место вечно. 30 с хватает для 10 MiB от 2,8 Мбит/с.

Одна копия тела. Тело копится в BytesIO; проверка изображения и SHA-256 идут над getvalue() (bytes над тем же буфером), затем ссылка на bytes удаляется, и в PUT уходит сам BytesIO. Пока ссылка жива, буфер общий, и aiohttp при getbuffer() копировал тело целиком. Проба в образе API: шаг PUT 10 MiB — 2,31 тела над базой прежним путём и 1,19 новым; в метке профиля — 2,17 и 1,20 тела на загрузку (раздел «Одновременные загрузки» ниже).

Буферы ядра. У реплик api — sysctls: net.ipv4.tcp_rmem "4096 131072 524288": буфер приёма сокета до 512 KiB вместо 32 MiB ВМ Docker Desktop (ожидающая или отклонённая загрузка держит в ядре до 0,5 MiB). У LB — tune.sndbuf.server 262144 (буфер отправки к реплике) и tune.rcvbuf.client 131072 (буфер приёма от клиента). Второй добавлен после первой метки профиля: в ней пик LB рос на ~2,6 MiB на клиента, очередь приёма сокета клиента — до 9 MiB (97a4be4; design, «Уточнения apply», п. 11). С ним в метке baseline пик LB «с лимитом» 10 MiB растёт на (52,3 − 30,5) / 39 = 0,56 MiB на клиента от 1 до 40 клиентов (ячейки summary.md), скорость одного клиента прежняя.

Цепочка таймаутов пути загрузки (решение 7):

Звено Значение Формула и обоснование
молчание реплики до тела ≤ 17 с вход и членство — по шагу БД: 2 × [database] request_timeout_seconds (6) + [uploads] wait_timeout_seconds (5)
тело ≤ 30 с [uploads] body_timeout_seconds; простой клиента ≤ timeout client LB (30 с)
молчание реплики после тела ≈ 26 с проверка (до ~4 с при 4 загрузках на 1 CPU) + pending 6 + PUT 5 + ready 6 + компенсация 5
timeout server LB пути загрузки 30 с больше 17 и 26 с: http-request set-timeout server 30s if METH_POST { path_reg ^/api/v1/chats/[^/]+/attachments$ }
timeout server остальных путей 10 с цепочка лабы 3 не меняется: общий 30 с держал бы любой запрос к зависшей реплике 30 с
наибольшая длительность загрузки U ≈ 73 с 17 + 30 + 26
ROLLOUT_DRAIN_TIMEOUT 90 с > U и > 30 с: плановая замена не обрывает живую загрузку (было 12 с); обычный дренаж — 0–2 с
graceful_shutdown_seconds 8 с прежний: stop-one.sh и docker stop — отказ, загрузка дольше 8 с обрывается, строку pending убирает уборщик

Ответ LB 400 (клиент замолчал посреди тела дольше timeout client) — теперь в формате контракта (http-error status 400), как 502/503/504. Поведение проверяет driver.py lb-upload-timeouts на заглушке реплики за конфигурацией проекта (evidence/uploads/lb-timeouts.md).

Граница живой загрузки уборщика прежняя — B = 2 × request_timeout_seconds + s3.timeout_seconds = 17 с. Ожидание места, тело и проверка изображения идут до записи метаданных (created_at строки pending), а сроки tx1, PUT и tx2 не менялись. Поэтому grace 900 с, проверка уборщика при старте и стенд отказов (grace 20 с) не меняются; свойство закреплено сценарием storage-consistency «Ожидание места не входит в возраст загрузки» (test_upload_waits_for_slot: created_at ожидавшей позже updated_at той, что держала место). Отдельного срока PUT по размеру нет: места ограничивают одновременные PUT (4 на реплику, 12 при замене), p95 PUT при 12 — 1,6–1,9 с, а больший срок удлинил бы B.

Значения по умолчанию — секция [uploads] (config.toml, подмена — UPLOADS__*):

Параметр Значение Почему
max_concurrent 4 бюджет реплики 512 МБ: база ~105 MiB + хэши паролей до 4 × 64 MiB + загрузки на 4 местах (метка: пик «с лимитом» при 40 × 10 MiB — 181 MiB, то есть ~76 MiB над базой) ≈ 440 MiB; при 8 местах — больше 512
max_waiting 16 сообщение несёт до 10 вложений, и клиент шлёт их разом: 10–20 одновременных загрузок по 10 MiB проходят без 429; ожидающий держит ≤ ~0,8 MiB
wait_timeout_seconds 5 с молчание до тела ≤ 17 с < 30 с LB; дольше ждать бессмысленно — реплика насыщена
body_timeout_seconds 30 с см. «Срок тела»
Retry-After 1 с (константа) за секунду реплика доводит несколько загрузок, повтор через LB уходит на следующую реплику

Значения — настройки, а не константы: у установок разный лимит памяти, а профилю uploads нужен вариант «без лимита». Запись «Started API» называет все четыре. Неверное значение (UPLOADS__MAX_CONCURRENT=0, -1, abc) — ошибка проверки настроек с именем поля, сервис не стартует.

Доказательства: evidence/uploads/baseline/summary.md (память под 1–40 одновременными загрузками, три варианта кода), evidence/tests/failure-checks.md (места, очередь, 429, срок тела — «узкий по загрузкам» API стенда отказов), evidence/uploads/lb-timeouts.md, evidence/uploads/rollout-upload.md, evidence/tests/student-test-lb.md (10 одновременных загрузок через LB).

Сверка хранилищ (трек 2, change track2-reconciler)

Уровень «5», трек 2 «Согласованность двух хранилищ»: повторяемый reconciler объектов без метаданных и метаданных без объектов — с dry-run, исправлением и повторным запуском, не трогающий свежее и используемое. Уборщик идёт только от строк pending, поэтому два остаточных риска upload-consistency без сверки не находил никто: объект без строки (PUT-зомби после уборки) и строку ready без объекта (сбой мимо API, объект удалён вручную). Объект, удалённый мимо API, до change давал 500 на каждое скачивание.

Где работает. Сверка — часть процесса уборщика, а не реплик API: у уборщика уже есть свой пул, ключи на чтение и удаление и долгоживущий процесс. Разовый проход — make reconcile (docker compose run --rm --no-deps cleaner reconcile [--apply] [--max-changes N]), по умолчанию dry-run. Плановая — в сервисе cleaner при старте и раз в [reconciler] interval_seconds, с исправлением. Отдельный сервис и пользователь S3 reconciler отвергнуты: второй процесс с доступом к той же базе и ещё два секрета ради почти пустого разделения прав.

Классы расхождений (ReconcileFinding):

Класс Что это --apply
orphan_object объект <база>/attachments/<id>/original, строки этого id нет и на ключ никто не ссылается объект удаляется
missing_object строка ready, объекта по её ключу нет оригинал помечается потерянным (lost_at)
size_mismatch строка ready, размер объекта ≠ size_bytes помечается потерянным, объект не удаляется
stale_pending строка pending старше grace (то же, что убирает уборщик) убирается шагом уборщика (пометка, затем объект и строка под блокировкой)
restored_object оригинал помечен, а объект снова есть того же размера пометка снимается
unknown_object ключ под префиксом, которого API не пишет, или <id>/original, у строки которого другой ключ только отчёт и код 3 — не удаляется никогда

Проход (design, решение 3): (1) S3 → БД — страницы ListObjectsV2 по префиксу <база>/attachments/ ([reconciler] page_size, 1000), на страницу одно выражение к БД id = ANY(:ids) OR object_key = ANY(:keys) (Bitmap OR по pk_attachments и uq_attachments_object_key, 1,5 мс на 1000 ключей; по id в 15 раз дешевле, чем по тексту ключа); каждый ключ — в множество; (2) БД → S3 — keyset строк ready по id (Index Scan pk_attachments, 0,6 мс на 1000), ключа нет в множестве — «метаданные без объекта»; (3) зависшие загрузки; (4) перепроверка каждого кандидата в БД и HEAD — в обоих режимах; (5) предел изменений; (6) с --apply — действия: зависшие → объекты без строки → пометки → снятия пометок, перед каждым ещё раз своё условие. Слияние двух отсортированных потоков отвергнуто: порядок списка SeaweedFS — обход каталогов, а не порядок байтов (проба), на нестандартных ключах оно дало бы ложные расхождения. Цена множества — память O(N), ~15 МБ на 100 тыс. объектов.

Почему два снимка (список и строки) не дают ложных расхождений. API пишет строку до PUT: если объект попал в список, строка его загрузки уже зафиксирована и видна выборке, которая идёт после. Строка ready старше порога стала ready до прохода, а её объект записан ещё раньше — список его видит; неполный ответ списка отсекает HEAD.

Безопасность (решение 4):

  • что удаляется — только объект без строки и зависшая загрузка; строки ready, используемые вложения (FK message_attachments), объект, на который ссылается строка любого статуса, и чужой ключ — ни в каком классе; строка с ключом вне <база>/attachments/ (например, база, восстановленная под другим именем) — «чужой объект»: её объект сверка не читает, строку не помечает и не убирает (замечание W2 verify);
  • свежее — grace общий с уборщиком ([cleaner] pending_grace_seconds, 900 с): объект — по LastModified S3, строка ready — по updated_at, pending — по created_at; свежее не считается расхождением;
  • перепроверка непосредственно перед действием — строка в БД (по id и по ключу) и HEAD объекта; не подтвердилось — действие не выполняется;
  • bucket на месте — отсутствие объекта подтверждается только после списка с MaxKeys=1: удалённый bucket — NoSuchBucket, проход прерван, а не «потеря всех оригиналов»;
  • предел изменений — удалений, пометок и снятий больше [reconciler] max_changes (100) — ни одного из них, error с числом и пределом, код 3; больше — аргументом --max-changes. Он защищает от сверки с «чужой» базой (пустой или из старой копии при живом bucket) и от пустого пересозданного bucket. Абсолютный, а не доля: на маленьком стенде доля слишком мала, на большом — велика;
  • параллельность — сверка и уборщик, две сверки разом не мешают друг другу: зависшие — под той же FOR UPDATE SKIP LOCKED и пометкой, удаление объекта и условный UPDATE идемпотентны.

Права S3 уборщика. Политика cleaner-objects получила s3:ListBucket с условием StringLike s3:prefix <база>/attachments/* (SeaweedFS 4.48 его соблюдает: весь bucket, test_<db>/, .s3-check/ и HEAD bucket — 403). Префикс bootstrap берёт из POSTGRES_DB (S3_CLEANER_LIST_PREFIX, проверка ^[a-z0-9_]+/attachments/$), уборщик строит свой из имени базы. make s3_check — 70 проверок, новые строки списка уборщика (evidence/s3/cleaner-list.md).

Потерянный оригинал и ответы API (решение 5). Пометка — колонка attachments.lost_at (ревизия 5c3e1f0a9b7d, ADD COLUMN … NULL под SET LOCAL lock_timeout), status и updated_at не меняются. Ответы: скачивание помеченного — 404 not_found без обращения к S3 (запись info «Attachment content is lost»), непомеченного без объекта — 500, как было; метаданные — 200 тем же Attachment; ссылка в новом сообщении — 201; после снятия пометки — снова 200 с байтами. Статус lost / failed отвергнут: контракт лабы 4 знает только ready, и прежние реплики упали бы на неизвестном значении при make rolling_update. Это вопрос преподавателю (раздел «Открытые вопросы преподавателю», п. 2): в контракте рядом «Отсутствующий вариант ready-объекта — 404», «404 — объекта нет» и «Неожиданное исключение — 500». Сделан вариант по умолчанию; ответ «иначе» меняет одну ветку open_content, сценарий и тесты, но не сверку.

Плановая сверка и параметры ([reconciler], решения 9–10):

Параметр По умолчанию Почему
interval_seconds 3600 с (0 — выключена) объект без строки живёт не дольше grace + интервал + проход (~15 + 60 мин); проход на рабочем стенде (~2–3 тыс. объектов) — 0,49–0,82 с, то есть меньше секунды в час; первая сверка — при старте, иначе частые пересоздания уборщика откладывали бы её
page_size 1000 (1–1000) больше S3 за страницу не отдаёт; одно выражение к БД на страницу
max_changes 100 см. «Безопасность»; разовый проход принимает больший аргументом

Своего grace у сверки нет — одна ручка «свежести» на всю согласованность, со своей проверкой границы живой загрузки. Пока идёт проход сверки, уборка зависших ждёт его конца. На стенде отказов плановая сверка выключена (её запускают тесты), в bench/ — тоже.

Журнал и коды. Находка, которая осталась, — warning «Found storage discrepancy» (класс, ключ, id, возраст, размеры, если разные), исправленная — info «Fixed storage discrepancy» с действием, итог — «Finished reconcile pass» (просмотрено, найдено и исправлено по классам, свежие, уже помеченные, длительность, причина прерывания), предел — error; отдельных записей не больше 1000 за проход. Коды разового прохода: 0 — расхождений нет, 3 — остались (чужие или отказ по пределу), 1 — прерван отказом S3 / PostgreSQL / сигналом, 2 — конфигурация. SIGTERM во время сверки: сигнал проверяется перед каждым вызовом хранилища, текущий вызов доводится — вызов S3 ≤ 5 с, шаг с БД ≤ 6 с, новых страниц и действий нет; сервис — код 0 за 4,7 с (evidence/reconcile/service.md).

Порядок обновления (решение 6): docker compose up -d s3-bootstrap (политика со списком) → make rolling_update (миграция, затем реплики) → docker compose up -d --no-deps cleaner. Смеси не хуже, чем до change: прежние реплики колонку не читают (у помеченного без объекта — 500, как раньше); новый уборщик на прежней политике получает AccessDenied на списке — проход сверки прерван, уборка работает. Откат — сначала уборщик, потом реплики; колонка и пометки остаются и прежнему коду не мешают.

На время восстановления базы уборщик останавливают (docker compose stop cleaner): база из старой копии или пустая при живом bucket сделала бы объекты новых вложений «объектами без метаданных», и сверка удалила бы их в пределах max_changes. После восстановления — сначала make reconcile (dry-run), потом docker compose start cleaner.

Доказательства: evidence/reconcile/cycle.md (рабочий стенд: все шесть классов с обеих сторон, dry-run без изменений, 500 → --apply → 404 / 200, повтор, чужой объект, свежий объект после grace, возврат оригинала), evidence/reconcile/stress.md (--apply раз в ~3 с под 640 загрузками и отправками: внесённое исправлено, все 640 скачиваются с тем же SHA-256, повтор — 0), evidence/reconcile/service.md, evidence/tests/failure-checks.md (одиннадцать проверок отказов сверки: восемь и их красный прогон на c13df14, три по замечаниям verify и их красные прогоны на a6071da и на временных регрессиях), evidence/s3/cleaner-list.md, evidence/migrations/lost-at.md. Стоимость обхода, стратегия «HEAD на строку», глубокая сверка SHA-256 и ограничение скорости — change track2-reconcile-cost, ниже.

Стратегии, глубокая сверка и предел скорости (change track2-reconcile-cost). Разовый проход (make reconcile, cleaner reconcile) получил три аргумента; плановая сверка сервиса по-прежнему batch, поверхностная, с пределом из настроек.

  • --strategy head — альтернатива для сравнения, а не замена. Направление S3 → БД — выборка строки на объект, а не на страницу. Направление БД → S3 — HEAD на каждую строку ready, без множества ключей в памяти. Находит те же классы, что batch (test_reconcile_head_strategy_same_findings), в том числе у строки, которая ссылается на <Z>/original чужого id: обе стратегии сравнивают строку с объектом по её ключу (до правки по verify W2 batch такую строку не сравнивал, test_reconcile_row_with_other_id_key). Объект, перезаписанный меньше grace назад, свеж для обеих и в перепроверке (S1, test_reconcile_fresh_overwrite_untouched). По метке она в ~21 раз дороже по времени и в ~110 раз по запросам; память batch — 161 Б на ключ. Поэтому основной остаётся batch (раздел «Стоимость сверки: результаты метки baseline», H1, H2).
  • --deep — GET каждого согласованного объекта и SHA-256 потоком против sha256 строки. Новый класс «другой SHA-256» (checksum_mismatch): с --apply — пометка потерянного оригинала (lost_at), как у объекта, которого нет. Повреждение того же размера поверхностная сверка не видит, глубокая — видит (test_reconcile_deep_checksum). Цена — 5,5 мс на MiB при 0,25 CPU, упор в CPU уборщика (H3). Поэтому только по требованию.
  • «Оригинал вернулся» — только тот же SHA-256. Пометку снимает объект с тем же содержимым. Объект того же размера с другими байтами пометку не снимает. До change снимал по размеру (test_reconcile_restore_needs_same_bytes). Вернувшийся объект читается и поверхностным проходом, но только он: объект с другими байтами остаётся lost_known.
  • Предел скорости [reconciler] max_objects_per_second (2000, 0 — без предела; разовый — --max-objects-per-second). Проход затрагивает в среднем не больше R объектов S3 в секунду: ключ списка, HEAD и GET считаются одинаково. После каждого вызова S3 — пауза до графика, кусками по 0,2 с. Сигнал паузу прерывает: остановка ≤ 1 с, а итог вызова перед паузой (ключи страницы, удалённый объект) учитывается в итоге и записи «Fixed» — проход останавливает проверка сигнала перед следующим вызовом (test_reconcile_rate_limit, driver.py reconcile-signal --pace [--apply], evidence/reconcile/service.md; до правки по verify W1 удалённый перед паузой объект оставался в журнале «Found»). Почему 2000 и предел для head и глубокой — по метке, раздел «Стоимость сверки: результаты метки baseline».
  • Ранний отказ по пределу. С --apply, как только подтверждённых изменений стало больше max_changes, остальные кандидаты не перепроверяются: они в итоге как unchecked, код 3, изменений нет. До change проход перепроверял всех (выборка и HEAD) и отказывал в конце: 10 000 кандидатов — +56,5 с, теперь — +0,60 с, HEAD 101 (S4; test_reconcile_limit_stops_rechecks).
  • Стоимость в итоге. «Finished reconcile pass» называет объекты S3 (storage_objects), запросы S3 по операциям (s3_requests), прочитанные байты (read_bytes), сеансы БД (db_sessions) и длительность шагов (phase_ms). Запросы S3 метка сверяет с метриками шлюза S3 (в проходах без фона — точное равенство, расхождений нет). pg_stat_database рядом — только справочный счёт: транзакций около двух на сеанс (pool_pre_ping и проверки LB дают свои), равенства с db_sessions нет и не требуется (design, решение 8).

Согласования с преподавателем

Дата Договорённость Где учтено
2026-09-26 FastAPI с его расхождениями (лишний 422 переведён в 400, порядок кодов: битый JSON — 400 раньше 401, остальная валидация после зависимостей) .claude/rules/api-contract.md, «FastAPI»
2026-09-29 Конфиг через pydantic-settings: окружение → .env → config.toml → дефолты, config.toml монтируется read-only, не в образе .claude/rules/settings.md, docker.md
2026-10-20 «Пустой текст» сообщения — и "", и из одних пробелов: с хотя бы одним вложением — 201 (текст как прислан), без вложений — 400 спек messages, «Пробелы с вложением»; CreateMessage; test_blank_text_with_attachment

Открытые вопросы преподавателю

Контракт допускает две трактовки, ответа пока нет. Сделан вариант по умолчанию, ниже — что поменяет другой ответ. Подход и остальной код от ответа не зависят.

  1. Все места загрузки реплики заняты: 429 rate_limited или 503 unavailable? contracts/openapi.json у uploadAttachment допускает оба: 429 — «Ограничение частоты запросов», и только у него есть Retry-After; 503 — «Зависимость недоступна». contracts/README.md называет 429 факультативным ограничением запросов, а места ограничивают одновременность, а не частоту.
    • Сделано: 429 с Retry-After: 1. Из двух описаний к ограничению подходит только 429. 503 клиент не отличил бы от отказа S3.
    • Ответ «503» меняет DOMAIN_ERRORS и RETRY_AFTER в src/api/errors.py, проверку Retry-After в student-tests/contract.py, ожидания test_upload_slots_busy и test_rejections_before_queue, сценарии спеков attachments и api-conventions и правило api-contract.md.
  2. Что отвечает API на вложение, чей оригинал по сверке потерян (объекта нет, он другого размера или с другим SHA-256)? У Attachment.status в лабе 4 одно значение — ready: failed и 409 появляются с лабы 5. contracts/README.md пишет: «Отсутствующий вариант ready-объекта — 404», «404 — объекта нет», «Неожиданное исключение — 500».
    • Сделано, вариант (а): метаданные — 200 как раньше, байты — 404 not_found, как у отсутствующего варианта, ссылка в новом сообщении — 201. До пометки сверкой байты — 500: расхождение непредвиденное.
    • Другие варианты: (б) вложение целиком как незавершённое — метаданные, байты и ссылка дают 404; (в) байты — 500 и после пометки, пометка только для отчёта. Каждый меняет ветку lost_at в AttachmentService.open_content, для (б) — ещё get_attachment и выборку вложений сообщения. Меняются и сценарий attachments «Потерянный оригинал», и ожидания test_reconcile_finds_and_fixes, test_reconcile_keeps_fresh_used_and_unknown, test_reconcile_restored_original и driver.py reconcile-cycle. Классы, правила безопасности и схема сверки остаются прежними.

Ответы на вопросы защиты

  • Почему файл в Docker volume одной API-реплики не равен объектному хранилищу? Volume привязан к контейнеру одной реплики: другая реплика его не видит, остановка или пересоздание реплики уносит доступ, а LB шлёт скачивание на любую. Объектное хранилище — общий сервис со своим volume и правами: оригинал отдаёт любая реплика (evidence/attachments/failover.md: принял 5f5d4ac50d9a, после его stop / kill отдал 847ad74efd7c), реплики не пишут файлы оригиналов на диск (docker diff, evidence/attachments/storage.md), и в S3 видно, какой объект какому вложению принадлежит (ключ с id).

  • Когда можно честно вернуть 201? Когда оригинал записан в S3 (PUT подтверждён) и метаданные в PostgreSQL зафиксированы в статусе ready — после второго commit. До этого — проверки и строка pending, которую API никому не показывает. Отказ S3 или БД на любом шаге — 503, а не 201 (test_upload_with_object_storage_stopped).

  • Что произойдёт, если S3 PUT прошёл, а COMMIT в PostgreSQL — нет? Строка pending с ключом объекта зафиксирована до PUT, поэтому объект не бывает «вечным неучтённым»: клиент получает 503, вложения для API нет (404), а в БД есть строка, по которой его можно найти. Дальше три случая:

    • сбой до отправки COMMIT (UPDATE упал, пул, срок) — вложение точно не станет ready, и API сразу удаляет объект (компенсация), строку убирает уборщик (test_ready_failure_compensated: объекта нет сразу после 503; evidence/attachments/consistency.md);
    • связь оборвалась во время COMMIT — исход неизвестен, вложение могло стать ready, поэтому объект не трогаем; если фиксации не было, строка осталась pending, и уборщик после grace (900 с) удалит объект и строку (test_ready_commit_outcome_unknown: отложенный триггер роняет COMMIT, объект на месте сразу после 503, после grace — ни строки, ни объекта);
    • процесс API убит между PUT и COMMIT — то же: строка pending и объект, уборщик убирает оба после grace (test_killed_between_put_and_ready).

    Уборщик под FOR UPDATE SKIP LOCKED сначала помечает строку отдельной транзакцией, потом удаляет объект, потом строку. Помеченную строку mark_ready не переводит в ready, поэтому загрузка, пережившая grace, получает 503 (test_upload_outlives_grace), и даже сбой уборки после удаления объекта не даёт ready без объекта (test_cleaner_failure_after_object_delete). Остаётся случай, когда процесс API заморожен дольше grace посреди самого PUT, уборщик убрал строку, а S3 принял тело после разморозки и удалить его API не смог — объект без строки. Его находит и удаляет сверка bucket и БД (change track2-reconciler): плановая сверка уборщика при старте и раз в час удаляет объект без строки старше grace, то есть такой зомби живёт не дольше grace + интервал (~75 мин) — evidence/reconcile/cycle.md (объекты O и B), test_reconcile_finds_and_fixes. Строку ready без объекта, если она всё же появится (окно make rolling_update со старыми репликами, удаление мимо API), сверка помечает потерянной: скачивание — 404, а не 500.

  • Почему случайный object key и приватный bucket не заменяют ACL приложения? Приватный bucket закрывает прямой доступ к S3, но скачивает через API любой аутентифицированный пользователь: кто может читать — решает приложение по членству в чате вложения (посторонний — 404, evidence/attachments/smoke.md). Случайный ключ — не секрет: он попадает в логи, в БД, в URL, а attachment_id клиенты передают друг другу в сообщениях; знание id не даёт права. Ключ API S3 у всех реплик один и права пользователя не различает.

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

Строки S3 (change s3-storage) сняты на стенде make run_docker: evidence/s3/restart.md, client.md, privacy.md — с commit f57635a (правки по verify), остальные файлы evidence/s3/ — с 2e997f9. Строки вложений (change attachments) — с d56b892 (код приложения 116d8d3) на стенде mtusi-lab4: HAProxy и две реплики, PostgreSQL, Valkey, S3. После правок по verify (код dba40bc) с e1f8531 переснято: make student_test через LB и make failure_checks (evidence/tests/student-test-lb.md, failure-checks.md) и замер bench_rollout на чистом дереве (evidence/rollout/attachments/, dirty: false). Строки согласованности БД и S3 (change upload-consistency) — с 5b42bd2 на том же стенде с уборщиком cleaner. После правок по verify (код 87c48b9: пометка строки уборщиком, три новых теста отказов) с 87c48b9 переснято make student_test через LB, make failure_checks и make test_isolated (evidence/tests/) и снят раздел 7 evidence/attachments/cleaner-process.md (отказ S3 во время прохода). driver.py upload-consistency на коде 87c48b9 — тоже PASS, файл evidence/attachments/consistency.md остался с 5b42bd2: его шаги правка не меняет. После правки по повторному verify (код 5889ca2: уборщик в два шага — пометка, затем объект и строка одной транзакцией под блокировкой) с 5889ca2 переснято make failure_checks (evidence/tests/failure-checks.md) и раздел 7 evidence/attachments/cleaner-process.md; make test, make student_test через LB (197 passed, сверка 215 / 200 / 36 / 15) и driver.py upload-consistency на этом коде — PASS, их файлы остались с 87c48b9 и 5b42bd2: правка их шагов не меняет. Строки памяти и сроков загрузки (change upload-memory) — с ce1ae2c (код 97a4be4): метка evidence/uploads/baseline/, evidence/uploads/lb-timeouts.md и rollout-upload.md; с того же commit переснято make test_isolated и make student_test через LB (evidence/tests/), поэтому строка тестов рубрики называет ce1ae2c. После правок по verify (9d2ee30: срок тела «узкого» API стенда отказов 3 с вместо 2 с, код приложения прежний) переснято make failure_checks (37 / 37). Строки сверки хранилищ (change track2-reconciler, трек 2) — с c1648d9 на рабочем стенде после порядка обновления change (evidence/reconcile/, evidence/s3/cleaner-list.md, evidence/migrations/lost-at.md); с того же commit снят make test_isolated (evidence/tests/). После правок по verify (84f8c35: сверка и тесты отказов, код API прежний) переснято make failure_checks (48 / 48) и make student_test через LB. После change fix-upload-put-flake (b5983f0: у клиента S3 нет срока чтения aiohttp, четвёртый API стенда отказов) на нём сняты восемь прогонов make student_test через LB после замены реплик. После правок по verify (723b6c3: код отличается от b5983f0 только комментарием в src/infra/s3/client.py) реплики снова заменены, и на нём пересняты make failure_checks (49 / 49, полный вывод) и make test_isolated (evidence/tests/test-isolated-s3-cleanup.md, раздел 0). Поэтому строки отказов S3, мест загрузки и срока тела называют 723b6c3.

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke make test (через LB и в make test_isolated), в том числе из чистого clone на de98d77 PASS: lab4 public API scenario — загрузка fixture, сообщение с attachment_ids, SHA-256 скачанного оригинала, 404 постороннему evidence/attachments/smoke.md, evidence/tests/clean-clone-final.md, evidence/tests/test-isolated-s3-cleanup.md (раздел 0)
Стенд собирается и проходит проверки из чистого clone git clone во временный каталог, последовательность раздела «Запуск из чистого clone» (de98d77, 2026-10-29) все шаги — код 0: make check, make validate, make test, make instances (2 реплики), make s3_check (70), make test-persistence, make test-failover × 2, attachment-failover, attachment-storage, make student_test (198), make reconcile (found {}), make test_isolated (193 + 5), make failure_checks (56, crash markers 0); секретов .env в журнале — 0 evidence/tests/clean-clone-final.md
CI: сборка, стенд и make test в отдельном job (CONTRIBUTING.md, «CI») .github/workflows/application.yml на раннере Gitea (run 325, 5e791a6); до push — шаги workflow в контейнере образа раннера с сокетом Docker, затем на отдельном демоне Docker 29.2.1 с пустым кэшем и Compose 5.4.0 run 325 — success: стенд с конфигами из configs и без портов хоста, обе реплики в LB; make check, make test, make validate — PASS; аноним в S3 — 403; make student_test — 198 passed (тесты реплик выполнены); make test-persistence, make test-failover stop и kill — PASS, failed_attempts 0; уборка стенда и volumes. Найден и исправлен дефект restart hook (--no-recreate): контроль без правки падает так же, как run 321 evidence/tests/ci-application.md
«3»: метаданные в PostgreSQL, байты в приватном bucket, не в БД и не на диске API driver.py --port 8080 attachment-storage из bytea только sha256 (32 байта), object_key = messenger/attachments/<id>/original без filename, объект в bucket 111 817 байт, анонимный GET ключа — 403, docker diff реплик — только config.toml; открыли bucket анониму — код 1 «anonymous GET … got 200», bootstrap закрыл — код 0 evidence/attachments/storage.md
«3»: POST вложения → 201 ready после сохранения; оригинал побайтно; attachment_ids читают участники; посторонний — 404 make test; driver.py upload Алисой, download Бобом и Евой 201 status=ready, variants=[], sha256 99ea7533…; Боб — 200 image/png, 111 817 байт, тот же SHA-256 (отдала другая реплика); Ева — 404 на метаданные и байты evidence/attachments/smoke.md
«3»: реальные PNG/JPEG ≤10 MiB и ≤40 млн пикселей, MIME по содержимому, опасные filename, лимиты до чтения и распаковки make student_test через LB (test_attachments.py, 33 теста) 10 485 760 байт — 201, +1 — 413; 30 MiB с Content-Length и частями — 413; 8000 × 5000 — 201, 40 000 001+ — 413; «бомба» — 415 (распаковано не больше ожидаемого объёма + 1 байт); текст, GIF, пустое тело, подмена MIME — 415; filename с /, \, NUL, \n, DEL, U+0085, пустой, 256 — 400; a%FFb.png, a%C3.png, a%ED%A0%80b.png — 400; U+202E, U+2066, U+2028 — 201 как есть evidence/tests/student-test-lb.md
«3»: остановка загрузившей реплики → download через другую driver.py --port 8080 attachment-failover --mode stop и --mode kill загрузку принял 5f5d4ac50d9a, stop-one.sh его остановил (stop и kill), метаданные и байты — 200 от 847ad74efd7c, SHA-256 совпал, посторонний — 404; после make replicas обе UP evidence/attachments/failover.md
«3»: restart с volumes сохраняет метаданные и оригинал make test-persistence ACTION_SCRIPT=scripts/restart.sh (LAB=4) PASS: прежний токен читает данные, оригинал вложения тот же; StartedAt новый у всех шести контейнеров (API, LB, PostgreSQL, Valkey, S3) evidence/replicas/test-persistence.md
«3»: failover с записью make test-failover ACTION_SCRIPT=scripts/stop-one.sh (каждая реплика, stop и kill, STOP_ONE_LOG) 4 × PASS, failed_attempts 0, восстановление 0,76–1,2 с; STOP_ONE_LOG — оба контейнера; из чистого clone — ещё 2 × PASS (stop, обе реплики по очереди, 1,08 и 1,2 с) evidence/failover/test-failover.md, evidence/tests/clean-clone-final.md
«3»: обязательные возможности лаб 2 и 3 сохранены make student_test через LB (test_identification.py, test_idempotency.py, test_load_balancing.py, test_race.py, test_chat_cache.py), make instances, driver.py auth-storage, повтор отправки после --force-recreate api Basic только на вход, Bearer на остальном, X-User-Id игнорируется; X-Instance-Id в каждом ответе, одна сессия на обеих репликах (instances: 2, 6 / 6); повтор с тем же Idempotency-Key через другую реплику и после пересоздания реплик — тот же Message, гонка 10 клиентов с одним ключом — одно сообщение; Argon2id в users, SHA-256 токена в sessions; кэш карточки — одно чтение chats на 50 evidence/tests/student-test-lb.md, evidence/tests/clean-clone-final.md, evidence/auth/passwords-and-tokens.md, evidence/idempotency/replay-after-restart.md, evidence/cache/hits.md
«4»: тесты большого файла, повреждённого изображения, подмены MIME, чужого attachment_id, вложения другого чата; ошибка клиента не 500 make student_test через LB (test_rubric.py: пять сценариев лабы 4), make test_isolated 198 passed через LB (b5983f0, восемь прогонов подряд после замены реплик — без падений, «Object storage is unavailable» в журнале реплик 0 при 536 загрузках), 193 passed + 5 пропусков тестов реплик в одном процессе (723b6c3); каждая ошибка — 4xx в формате контракта; из чистого clone на de98d77 — 198 passed через LB и 193 + 5 в make test_isolated, сверка покрытия: 252 сценария 13 спеков, 235 тестами (70 — проверками отказов), 17 исключений evidence/tests/student-test-lb.md, evidence/tests/test-isolated-s3-cleanup.md (раздел 0, пересъёмка на 723b6c3), evidence/tests/clean-clone-final.md
«4»: отказы S3 на путях вложений, отклонённая загрузка ничего не оставляет make failure_checks 49 / 49, код 0 (723b6c3, 552 с): S3 остановлен — загрузка 503, ровно одна новая строка pending, готовые те же, текст 201; скачивание 503, метаданные 200, история с attachment_ids 200, /health/ready 200; S3 заморожен — 503 не позже 5,6 с; отклонённые загрузки — ни новых строк, ни новых объектов (списки id); рабочий стенд не тронут evidence/tests/failure-checks.md
«4»: прерывание загрузки и отказ между S3 и БД не оставляют вечных неучтённых объектов make failure_checks (стенд отказов: уборщик с grace 20 с, интервал 1 с) сбой записи строки (SQLSTATE 08006) — 503, ни строки, ни объекта; обрыв клиента посреди тела — ни строки, ни объекта; сбой фиксации ready — 503, объекта нет сразу (компенсация), строка pending не видна по API, на G/2 ещё на месте, после G + I + 5 с убрана; S3 заморожен на время PUT — строка убрана после grace, объект не появился; kill реплики между PUT и фиксацией — 201 не дошёл, строка и объект есть до grace, после — ни того, ни другого; COMMIT ready упал (отложенный триггер) — 503, объект на месте (исход неизвестен), после grace убран; загрузка дольше grace (строка «старше» на час, уборщик убрал её, пока перевод в ready ждал) — 503, а не 201 и не 500, ни строки, ни объекта; уборщик удалил объект, а удаление строки упало в той же транзакции уборки — 503, а не 201, ready без объекта нет, следующий проход доводит уборку; во всех — объектов без строки 0 (object-ids − attachment-ids); красный прогон до кода — 4 из 11 упали; тесты по verify: W1 — 201 на коде f2dc0b3, W2 и W3 — красные на временных регрессиях (компенсация на любой сбой, RuntimeError → 500) evidence/tests/failure-checks.md
«4»: то же на рабочем стенде через LB driver.py --port 8080 upload-consistency S3 заморожен — 503 за 5,1 с, строка pending с ключом; сбой фиксации ready — 503, объекта нет; обе строки — 404 на метаданные, байты и ссылку; cleaner --once (grace 30 с) — removed 2, код 0; строк и объектов нет, «1200 objects, 1200 rows, 0 objects without a row»; готовое вложение — тот же SHA-256; в журнале API шаги put / ready и «Deleted attachment object», filename — 0 вхождений evidence/attachments/consistency.md
«4»: документированный механизм компенсации и очистки с безопасным grace period описание и проверка старта уборщика таблица компенсации, уборщик под FOR UPDATE SKIP LOCKED в два шага — пометка строки, затем объект и строка одной транзакцией, B = 2 × 6 + 5 = 17 с, grace 900 с (×50); grace 17 с — код 2 с grace, обоими сроками и границей; интервал 0 и abc — код 2; старт — «Started cleaner» с 60 / 900 / 100; docker compose stop cleaner — 0,57 с, код 0 раздел «Согласованность БД и S3», evidence/attachments/cleaner-process.md
«4»: уборщик переживает отказы хранилищ, готовые вложения не трогает make failure_checks (test_cleaner_survives_outages); make test-persistence S3 остановлен и PostgreSQL остановлен на 3 с: строка на месте после G + 3I, после возврата S3 убрана за I + 5 с без перезапуска; готовое вложение старше grace — 200 ready, тот же SHA-256; после scripts/restart.sh (make test-persistence — PASS) у уборщика прежний StartedAt, RestartCount 0, cleaner --once — код 0 evidence/tests/failure-checks.md, evidence/attachments/cleaner-process.md (раздел 6)
«4»: отказ S3 во время прохода уборщика виден в журнале, строка не теряется рабочий стенд (5889ca2): docker compose pause s3 → загрузка через LB → docker compose run --rm --no-deps -e CLEANER__PENDING_GRACE_SECONDS=30 cleaner --once → unpause → тот же --once загрузка 503, строка pending; проход: DELETE объекта — срок 5,01 с, warning «Object storage is unavailable» (delete_object, TimeoutError, без ключей) и «Interrupted cleanup pass» с interrupted_by: object_storage, код 1, строка на месте и помечена; после unpause — «Removed stale attachment», код 0, ни строки, ни файла original evidence/attachments/cleaner-process.md (раздел 7)
«4»: отдельные ограниченные credentials уборщика make s3_check (строки cleaner key …), bootstrap на пустом volume и со сменой секрета, docker compose config ключ уборщика: GET / HEAD / DELETE своего объекта 200 / 200 / 204, повторный DELETE 204; запись, список, bucket, политика, ACL, чужой bucket — 403; новый секрет — ключ пересоздан, прежний — 403 SignatureDoesNotMatch; ключи уборщика только у s3-bootstrap и cleaner, у уборщика нет пароля Valkey, ключей API и административных evidence/s3/cleaner-key.md
«4»: индекс уборщика без блокировки записи, план по индексу alembic upgrade head --sql; с нуля, повтор, откат на временной базе; EXPLAIN (ANALYZE, BUFFERS) общего плана на рабочей базе с откатом; make bench_rollout_quick CREATE INDEX CONCURRENTLY IF NOT EXISTS вне транзакции; повтор и повтор после «сбоя» проходят, indisvalid true; 22 000 строк (2 000 pending) — Index Scan using ix_attachments_pending_created_at, 100 кандидатов за 28–29 буферов, 0,03–0,04 мс; замена под нагрузкой e656d6bbe1a4 → 739b8f04d5fb, ошибок 0 evidence/migrations/pending-index.md
«4»: длинная передача не держит соединение пула разовый скрипт: 10 MiB частями ~12 с и скачивание с медленным чтением 201 за 12,4 с и 200 за 13,1 с через LB, «Database is unavailable» — 0 evidence/attachments/slow-transfer.md
«4»: rolling update на схему вложений под нагрузкой make bench_rollout ROLLOUT_LABEL=attachments (с образа e1161f7) e1f8531, dirty: false: замена 8,67 с, ревизия e656d6bbe1a4 → ef25d50b01a8, ошибок 0 / 0 / 0, 200 успешных в секунду всё время, ответов старых после дренажа 0, сообщений = ключей 12 001 evidence/rollout/attachments/summary.md
«4»: исключения сверки покрытия сняты на стенде лабы 4 driver.py cache-check --require-test-keys, auth-storage, повтор после --force-recreate api кэш: одно чтение chats на 50; Argon2id и SHA-256 токена; повтор через новый процесс — тот же Message с attachment_ids evidence/cache/hits.md, evidence/auth/passwords-and-tokens.md, evidence/idempotency/replay-after-restart.md
«3»: S3-сервер в общем стенде, закреплённая версия make run_docker, docker compose ps s3 на chrislusf/seaweedfs:4.48@sha256:… в состоянии healthy, s3-bootstrap — Exited (0), реплики стартуют после него evidence/s3/privacy.md (раздел 3), evidence/s3/bootstrap.md (раздел 1)
«3»: persistent volume S3 scripts/restart.sh; docker kill -s KILL сервера S3 ID контейнеров прежние, StartedAt новый, hook — 24 с; объекты клиента читаются с тем же SHA-256: 3/3 после рестарта, 20/20 после SIGKILL; первая запись после healthy — 11–27 мс в 18 рестартах и kill (healthcheck ждёт регистрации тома) evidence/s3/restart.md
«3»: создание приватного bucket описано docker compose logs s3-bootstrap на пустом volume «bucket messenger created», «user api created», «checks passed» evidence/s3/bootstrap.md (раздел 1), «Архитектура и решения» → «Bootstrap S3»
«4»: bootstrap идемпотентен docker compose run --rm s3-bootstrap дважды; повтор с новым секретом; S3_BUCKET=Bad_Bucket повтор — «exists», код 0, объекты на месте; новый секрет работает, прежний — 503; ошибка — код 1, «FAILED: bucket create», реплики не стартуют evidence/s3/bootstrap.md
«4»: отдельные ограниченные credentials API make s3_check (строки api key …); секреты по сервисам из docker compose config ключ API: объекты своего bucket — 200 / 204; список, bucket, политика, ACL, чужой bucket — 403; административной пары у API нет evidence/s3/privacy.md (разделы 1, 4)
«4»: административная консоль не в общей сети make s3_check: слушающие сокеты контейнера S3 (netstat), затем nc -z из сети стенда; docker port; gRPC без токена вне loopback слушают только 8333 и 18333; master, filer и volume — только на 127.0.0.1 и из сети закрыты, admin UI не слушает; со служебными серверами на 0.0.0.0 (временный стенд) — код 1 и список лишних портов; на хосте — только 127.0.0.1:8334; PutIdentity без токена — UNAUTHENTICATED evidence/s3/privacy.md, evidence/s3/grpc-admin.md
«4»: проверка private bucket вне API make s3_check; затем открыть чтение s3.anonymous.set -access Read 48 проверок, код 0 (f57635a; с уборщиком — 68, evidence/s3/cleaner-key.md); после открытия чтения — 10 FAIL с названиями; следующий bootstrap закрывает доступ, снова PASS evidence/s3/privacy.md
«4»: S3 недоступен — ограниченная ошибка, текст работает make failure_checks (test_readiness_without_object_storage[stop|pause]); клиент при pause и stop S3, без bucket и без прав без S3 (остановлен или заморожен) /health/ready и /health/live — 200 быстрее 1 с; вызов клиента — 503 за 1–8 мс (stop) или за срок 5 с (pause), после возврата проходит; удалённый bucket и отказ в доступе — 503 с записью error, а не «объекта нет» (кроме HEAD: 404 без тела) evidence/tests/failure-checks.md, evidence/s3/client.md
«4»: память S3 при одновременных загрузках 20 одновременных PUT по 10 MiB ключом API все подтверждены, анонимная память не больше 379 MiB из 512, OOM нет; с местами API в S3 не больше 4 PUT от реплики — в метке uploads 503 по сроку S3 нет evidence/s3/memory.md, evidence/uploads/baseline/summary.md
Логи без секретов S3 grep -F значений секретов по журналу клиента и make run_dev 0 совпадений; отказ в учётных данных — одна запись error без секрета evidence/s3/client.md
«4»: ≥ 10 одновременных загрузок, пик памяти make bench_uploads (метка baseline, 97a4be4, dirty: false; 72 прогона: 3 варианта × 2 тела × 4 уровня × 3 повтора; реплика 1 CPU / 512 МБ без swap) «с лимитом», 10 MiB: пик реплики 169,5 / 177,3 / 181,3 MiB при 10 / 20 / 40 клиентах, OOM 0, 5xx 0, лишние — 429; «без лимита» и код до change при 40 × 10 MiB — OOM 3/3, код до change и при 20 × 10 MiB — OOM 3/3; в паспорте — предупреждение о swap хоста (раздел «Одновременные загрузки») evidence/uploads/baseline/summary.md
«4»: лимит одновременных загрузок, очередь и 429 make failure_checks: «узкий по загрузкам» API (1 место, 1 в очереди, ожидание 1 с, срок тела 3 с; прогон 723b6c3) при полной очереди — 429 rate_limited быстрее 0,5 с, по сроку ожидания — 429 не раньше 1 с, Retry-After ≥ 1, ни строки, ни объекта; 404 / 413 / 415 — раньше очереди; место освобождается после 413, 415, 400 по сроку, обрыва и 503; ожидавшая — 201, её created_at позже updated_at державшей место evidence/tests/failure-checks.md
«4»: срок передачи тела make failure_checks (test_slow_body) прогон 723b6c3: тело частями дольше срока тела стенда (4 с при сроке 3 с) — 400 «Upload body was not received in time», ни строки, ни объекта; мелкими частями в срок — 201 с тем же SHA-256 evidence/tests/failure-checks.md
«4»: 10 одновременных загрузок проходят make student_test через LB и make test_isolated (test_concurrent_uploads) 10 участников одного чата, PNG ~1 MiB: все 201, id разные, скачиваются побайтно — и через LB, и на одном процессе evidence/tests/student-test-lb.md, evidence/tests/test-isolated-s3-cleanup.md
«4»: таймауты LB пути загрузки driver.py lb-upload-timeouts на текущем haproxy.cfg и на f894040 сейчас: молчание 12 с до и после тела — 201, другой путь — 504 через 10,01 с, 32 с — 504 через 30,11 с, клиент молчит посреди тела — 400 JSON через 30,02 с; на f894040 — 502 / 504 через 10 с и 400 HTML (код 1) evidence/uploads/lb-timeouts.md
«4»: плановая замена не обрывает загрузку две загрузки ~20 и ~26 с через LB во время make rolling_update обе 201 с тем же SHA-256; дренаж реплики с загрузкой — 14 с, остановка после ответа (ROLLOUT_DRAIN_TIMEOUT 90 с) evidence/uploads/rollout-upload.md
«5», трек 2: ошибки внесены с обеих сторон, найдены и исправлены, повтор находит 0 driver.py --port 8090 reconcile-cycle (рабочий стенд, c1648d9) внесены O (объект без строки), X (чужой ключ), удалён объект A (в сообщении), удалена строка B, размер C +1, обрыв COMMIT P; после grace 30 с dry-run — 6 находок своих классов (orphan_object ×2, missing_object, size_mismatch, stale_pending, unknown_object), код 3, строки, объекты и пометки не изменились; байты A — 500; --apply — O, B удалены, P убрана, A и C помечены, свежий F не тронут, X остался (код 3); байты A — 404, метаданные 200 = ответ загрузки, история отдаёт A; повтор — только X; после удаления X оператором — код 0; F удалён после grace; A возвращён — restored_object, 200 с тем же SHA-256; итоговый dry-run — код 0; 45 проверок, PASS evidence/reconcile/cycle.md
«5», трек 2: dry-run, --apply, повторный запуск; коды выхода make reconcile, плановая сверка уборщика при старте (--apply), docker compose run … cleaner reconcile с чужим объектом и с неверными RECONCILER__*; driver.py reconcile-signal стенд после обновления: плановая сверка при старте — 2 086 объектов и строк, found {}; make reconcile — found {}, код 0; чужой объект старше grace — warning «Found …», код 3, после его удаления — код 0; driver.py reconcile-signal (временный проект, 84f8c35): разовый --apply при замороженном S3 и docker stop — код 1, interrupted_by: stop, остановка 5,0 с; RECONCILER__PAGE_SIZE=5000, MAX_CHANGES=0, INTERVAL_SECONDS=-1, --max-changes 0 — код 2 с именем поля evidence/reconcile/service.md
«5», трек 2: свежие и используемые вложения не удаляются, ничего подтверждённого не теряется под нагрузкой driver.py --port 8090 reconcile-stress (4 клиента × 40 с, --apply раз в ~3 с, grace 20 с); make failure_checks (11 проверок сверки, 84f8c35) 640 загрузок 201 и 640 сообщений, 9 проходов --apply с кодом 0; внесённые 2 объекта без строки удалены, 2 потери помечены, новых пометок — только они; каждое из 640 вложений — тот же SHA-256, сообщения отдают свои вложения; повтор — 0; на стенде отказов: свежие объект и вложение не тронуты, вложение в сообщении только помечено (метаданные 200, история с id), чужой ключ не удалён (код 3), предел 2 при 3 изменениях — ни одного (код 3, error), S3 остановлен — код 1 без изменений, сбой БД на пометке — код 1, повтор доводит; плановая сверка с интервалом 1 с помечает потерю сама; объект, на который ссылается строка (в том числе строка другого id), — чужой, не удалён; отказ по пределу не мешает уборке зависшей загрузки; строка с ключом вне <база>/attachments/ — чужая, без пометки и уборки; красный прогон на c13df14 — 8 из 8 упали, проверки по verify — 1 из 3 на a6071da, 2 из 2 на временных регрессиях evidence/reconcile/stress.md, evidence/tests/failure-checks.md
«5», трек 2: права S3 для сверки, схема пометки make s3_check; bootstrap с неверным префиксом; alembic с нуля / повтор / откат / --sql; make rolling_update ключ уборщика: список messenger/attachments/ — 200, всего bucket, .s3-check/ и чужого bucket — 403, 70 проверок PASS; неверный S3_CLEANER_LIST_PREFIX — код 1; ADD COLUMN lost_at после SET LOCAL lock_timeout = '2s', ревизия 739b8f04d5fb → 5c3e1f0a9b7d поочерёдной заменой за 12 с evidence/s3/cleaner-list.md, evidence/migrations/lost-at.md
«5», трек 2: стоимость сверки — гипотезы до замера, профиль, повторы make bench_reconcile (метка baseline, d8b8ae3, dirty: false; гипотезы — aaf3fa3, раньше; 51 проход: 3 повтора, 1 000 × 1 MiB и 10k → 30k → 100k × 4 KiB, 0,25 % расхождений каждого класса) найденное = внесённому во всех проходах, счёт сверки = метрикам шлюза S3; H1 подтверждена: batch 281 / 311 / 320 мкс на объект (разброс 13,7 %), LIST ⌈N/1000⌉ + 1, 161 Б памяти на ключ; H2 подтверждена: HEAD на строку в 21,7 / 20,4 раза дороже, 2015 против ~18 запросов на 1000 объектов; H3 подтверждена: глубокая в 11,2 раза дороже, 5,50 мс на MiB, упор в CPU уборщика, 1 CPU — в 2,80 раза быстрее; S4 подтверждена: отказ по пределу при 10 000 кандидатах +0,60 с вместо +56,5 с, HEAD 101 evidence/reconcile/baseline/summary.md
«5», трек 2: влияние сверки на фоновую нагрузку та же метка, этап D: 300 скачиваний + 50 записей + 50 чтений в секунду, 4 варианта CPU уборщика и предела H4 не проверена: все r ≤ 1,08, a 0,96–1,06, 5xx нет, но контраст fast-unlimited (1 CPU, без предела) дал r скачиваний 1,08 при пороге > 1,5 — метод влияния не показал; предел 2000 держит CPU S3 за проход 0,27–0,32 ядра при любом CPU уборщика (без него — 0,42–0,73) ценой прохода в 2,2–4 раза дольше evidence/reconcile/baseline/summary.md, passes.csv, windows.csv
«5», трек 2: head, глубокая, возврат по SHA-256, предел скорости, ранний отказ make failure_checks (5 проверок и 2 по замечаниям verify, ca0c4b2); красные прогоны на 7f4e626 и 16f2cde; driver.py reconcile-signal --pace [--apply] (временный проект) 56 из 56 за 877 с; на 7f4e626 — 5 из 5 упали по ожидаемым причинам (argparse, нет поля deep, пометку снял объект того же размера, changes 7 вместо 3); на 16f2cde — 2 из 2 (batch не сравнил строку с чужим <Z>/original, помечен только что перезаписанный объект); docker stop во время паузы предела 1 объект/с — код 1, interrupted_by: stop, выход через 0,06 с, ключи страницы в итоге, а с --apply каждое удалённое — «Fixed» (4 из 4; на 16f2cde — 3 из 4) evidence/tests/failure-checks.md, evidence/reconcile/service.md

Какие процессы и хранилища перезапускает restart hook, подтверждено отдельно, а не только PASS теста: StartedAt у LB, обеих реплик, PostgreSQL, Valkey и S3 новый, ID контейнеров прежние (evidence/replicas/test-persistence.md, evidence/s3/restart.md); в проверке из чистого clone — время работы этих контейнеров после hook меньше его длительности, а у уборщика, которого hook не трогает, — прежнее (evidence/tests/clean-clone-final.md).

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

Два замера с гипотезами, записанными и закоммиченными до прогонов. У каждого в своём разделе ниже — хост и лимиты контейнеров, версии, объём данных, профиль и интенсивность нагрузки, окна и прогрев, повторы, коды ответов, p50 / p95 / p99, CPU и память, выводы и ограничения. Сырые итоги без токенов лежат в каталогах меток:

  • память при одновременных загрузках (уровень «4»: «≥ 10 одновременных загрузок с измерением пика памяти») — make bench_uploads, метка evidence/uploads/baseline/, разделы «Одновременные загрузки: гипотезы» и «… результаты»;
  • стоимость сверки bucket и БД (уровень «5», трек 2: «измерьте стоимость обхода») — make bench_reconcile, метка evidence/reconcile/baseline/, разделы «Стоимость сверки: гипотезы» и «… результаты».

Таблица ниже — отказы и пробы: внесённое воздействие, ожидание, наблюдение и потери. Команды и полные выводы — в файлах таблицы «Доказательства критериев».

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
docker pause сервера S3 вызов клиента — 503 не позже срока 5 с 5 004–5 005 мс, TimeoutError → 503, без повторов после unpause следующий вызов — 8 мс; потерь нет
docker compose stop s3 плавная остановка без SIGKILL; вызовы — 503 сразу остановка 15,3 с, код 0; вызов — 503 за 1–8 мс после start первый вызов тем же клиентом проходит (29 мс)
SIGKILL сервера S3 сразу после 20 подтверждённых PUT подтверждённое не теряется 20/20 с тем же SHA-256 healthy через 5 с; потерь нет
scripts/restart.sh все хранилища и реплики перезапущены, данные целы 24 с; bootstrap — «exists»; 3/3 объекта с тем же SHA-256 —
Рестарт и SIGKILL S3, сразу первая запись запись не ждёт регистрации тома после healthy до правки healthcheck — 2 из 8 рестартов ждали 4 771 и 2 523 мс (срок 5 с); после — 11–27 мс в 12 рестартах и 6 kill —
Bucket удалён мимо bootstrap 503 и error, а не «объекта нет» put, open, delete — 503, «bucket is missing» / «denied access»; head — None (404 без тела, ограничение принято) —
Неверный секрет API у приложения 503 и запись error без секрета SignatureDoesNotMatch → 503, одна запись error —
20 одновременных PUT по 10 MiB без OOM анонимная память не больше 379 MiB; последний PUT подтверждён через 7,2 с (очередь лимита загрузок 64 МБ) —
Загрузка при остановленном S3 (make failure_checks) 503 быстрее срока вызова, строка pending остаётся, текст работает 503; pending +1, ready без изменений; текстовое сообщение 201 после start та же загрузка — 201
S3 заморожен при загрузке и скачивании 503 не позже 5 с + запас 503 за ~5,0 с (срок вызова S3) после unpause скачивание — те же байты
Остановка (stop / kill) реплики, принявшей вложение скачивание через другую реплику 200 от другой реплики, тот же SHA-256 потерь нет, реплика возвращается make replicas
Поочерёдная замена на схему вложений под нагрузкой 100 записей + 100 чтений/с (bench_rollout, метка attachments; 2 реплики 1 CPU / 512 МБ, PostgreSQL 2 / 1 ГБ; хост на сети, давления памяти нет, Swapouts 0) ошибок нет, миграция одна, старые реплики работают на новой схеме замена 8,67 с, ошибок 0, p95 до 3 мс / макс. 31 мс в замене; первый ответ новой реплики — 3,72 с, последний старой — 8,01 с (старые писали и читали на новой схеме); ревизия e656d6bbe1a4 → ef25d50b01a8 (две таблицы и NOT VALID) потерь нет: 12 001 сообщение = 12 001 ключ
Память одной загрузки 10 MiB (проба в образе API, три загрузки подряд в одном процессе) одно тело и блок чтения пик RSS: bytearray + bytes(...) — 1,99–2,11 тела; BytesIO + getvalue() при динамическом пороге mmap — 1,25 / 2,05 / 1,07 (копия в realloc на второй); с MALLOC_MMAP_THRESHOLD_=131072 — 1,20 / 1,19 / 1,19 —
Медленный клиент 10 MiB (~12 с) загрузка и скачивание проходят, сессия БД не держится 201 за 12,4 с, 200 за 13,1 с; в реплике загрузка — 12 430 мс —
PostgreSQL отказывает при переводе в ready после записанного объекта (триггер, SQLSTATE 08006; рабочий стенд и стенд отказов) 503, объект удалён до ответа, строка pending до уборщика 503; объекта нет сразу; журнал — шаг ready, «Deleted attachment object» строка убрана уборщиком после grace (стенд отказов: ≤ 20 + 1 + 5 с; рабочий стенд — cleaner --once с grace 30 с); объектов без строки 0
docker kill реплики между PUT и фиксацией (перевод в ready задержан на 4 с) 201 до клиента не доходит, после grace — ни строки, ни объекта клиент — ошибка соединения; до grace строка pending и объект есть; после start-api и grace — убраны — ; объектов без строки 0
S3 и PostgreSQL остановлены, пока уборщику есть что убирать строка остаётся, уборщик не падает и доводит уборку после возврата после G + 3I при остановленном S3 строка на месте; после start S3 — убрана за ≤ I + 5 с, без перезапуска уборщика; готовое вложение цело ≤ 6 с после возврата S3
docker compose stop cleaner во время работы и на старте выход до SIGKILL, код 0 0,57 с, код 0, «Stopped cleaner»; через 0,05–1 с после up — «Stopped cleaner before startup», 0,2 с; сразу после up (окно запуска интерпретатора) — SIGKILL через 10 с (137) —
Объект мимо API, удалённый объект, удалённая строка, изменённый размер, обрыв COMMIT, чужой ключ (рабочий стенд, reconcile-cycle) dry-run находит всё и ничего не меняет, --apply исправляет безопасное, повтор — 0 6 находок, снимки до и после dry-run равны; --apply — 5 исправлений, чужой ключ остался (код 3); после его удаления и grace — код 0 объект без строки живёт ≤ grace + интервал сверки; байты помеченного — 404, а не 500
--apply раз в ~3 с под 4 × 40 с загрузок и отправок (reconcile-stress) внесённое исправлено, подтверждённое цело 640 / 640 загрузок скачиваются с тем же SHA-256, новых пометок — только 2 внесённые потерь нет
docker compose stop cleaner, пока сверка ждёт замороженный S3 выход до SIGKILL, код 0, итог «остановка» 4,7 с, код 0, «Finished reconcile pass» с interrupted_by: stop следующий старт — сверка до конца, расхождений нет
10 одновременных медленных скачиваний оригинала 4 MiB, затем простой S3 дольше срока вызова, затем загрузки (change fix-upload-put-flake: test_upload_after_idle_s3 на API со сроком S3 1 с, driver.py s3-idle на рабочем стенде) исправный S3 — каждая загрузка 201 до правки (срок чтения aiohttp 5 с): тест красный 3 из 3 уже в первом раунде, 503 за 1 мс (ReadTimeoutError); s3-idle — 13 испорченных соединений и 13 упавших PUT из 36. После правки (read_timeout=None): тест — 96 из 96 загрузок 201 за 8 раундов, 3 из 3 прогонов; s3-idle — 0 испорченных, 36 из 36 PUT, эталон с прежним сроком в том же процессе портит 14 данные целы и до правки: упавший PUT оставлял строку pending уборщику; evidence/s3/idle-connection.md

Одновременные загрузки: гипотезы (change upload-memory)

Гипотезы записаны до первого прогона метки профиля uploads и зафиксированы отдельным commit раньше commit с результатами (спек load-benchmark, «Загрузки в отчёте»). Числа в них — из проб design change upload-memory (Context, «Пробы»), а не из метки. Расхождение с результатом метки гипотезу не меняет: вывод пишется ниже, после прогона.

Методика (design, решение 10): make bench_uploads на стенде mtusi-bench — LB, одна реплика API 1 CPU / 512 МБ без swap (memswap_limit = память), PostgreSQL, Valkey и S3 с лимитами рабочего стенда. Варианты: «до» — образ f894040 (код до change), «без лимита» — текущий код с UPLOADS__MAX_CONCURRENT=1000, UPLOADS__MAX_WAITING=0, «с лимитом» — значения по умолчанию (4 места, 16 в очереди). Тела — PNG из шума около 1 MiB и около 10 MiB; C ∈ {1, 10, 20, 40} одновременных клиентов без пауз (на 429 — пауза Retry-After); 3 повтора; на каждый прогон — новые реплика и volume S3; пик — memory.peak cgroup реплики, сброшенный в начале окна.

  • H1 — «с лимитом»: пик памяти реплики при 10 MiB и C = 10, 20, 40 не больше половины лимита контейнера (256 MiB). Сверх пика при C = 10 — не больше 1 MiB на каждого клиента. OOM нет, ответов 5xx нет, лишние загрузки получают 429.
  • H2 — «без лимита» и «до»: у «без лимита» пик растёт примерно на 1,2–1,3 тела на клиента, и при 40 × 10 MiB реплика завершена ядром из-за памяти (OOM-kill). У «до» пик растёт на ~2,1 тела на клиента (вторая копия тела при PUT), и реплика убита уже при 20 × 10 MiB.
  • H3 — пропускная способность: загрузок 201 в секунду при C ≥ 10 у «с лимитом» не меньше 90 % от «без лимита» на тех же C, пока «без лимита» жив: предел задаёт S3 (7–8,5 загрузки по 10 MiB в секунду на реплику), а не места. p95 у «с лимитом» растёт на время ожидания в очереди.
  • H4 — срок записи в S3: 503 из-за срока PUT (5 с) нет ни в одном варианте, пока реплика жива: в S3 не больше 4 PUT от одной реплики (формулировка design, решение 10; p95 PUT при 12 одновременных на пробе — 1,6–1,9 с).

Одновременные загрузки: результаты метки baseline

  • Метка: evidence/uploads/baseline/ (commit с результатами — ce1ae2c, гипотезы — 511e285, раньше). Код и стенд — 97a4be4, dirty: false, посторонних контейнеров в ВМ нет; 72 прогона, ~45 мин, 2026-10-22.
  • Стенд: LB 1 CPU / 256 МБ, реплика 1 CPU / 512 МБ без swap (буфер приёма 4096 131072 524288), PostgreSQL, Valkey, S3 1 CPU / 512 МБ; образ «до» — f894040. Тела — PNG из шума: 1 048 276 байт (1024 × 341) и 10 479 107 байт (1024 × 3409). Окно — 3 с разгона и 20 с, клиенты без пауз; на прогон — новые реплика и volume S3. Хост: Apple M3 Pro, 18 ГиБ, macOS 26.6.2; Docker Desktop 29.9.1, ВМ 12 CPU / 7,7 ГиБ, ядро 7.0.14-linuxkit; питание от сети, свободно 49 % памяти до и 51 % после.
  • Предупреждение паспорта (метка принята с пометкой, решение пользователя 2026-10-22): «host swapped out 7464 pages during the run». Вся выгрузка пришлась на один прогон — limited-10MiB-c40-r2 (пометка host_swap). Пик памяти в нём такой же, как у повторов (180,7 MiB против 181,3 и 182,8), искажено только время: 9,95 загрузки/с против ~11,0 и p95 2 815 мс против ~2 050. Медиана ячейки (11,00/с, 181,3 MiB) и выводы H1–H4 от него не зависят.
  • Первая метка отброшена (на 511e285): swap хоста 337 056 страниц и dirty: true. Из неё взят только рост пика LB «с лимитом» на ~2,6 MiB на клиента (38,8 → 139,9 MiB от 1 до 40 клиентов): сценарий load-balancing «Буферы соединений ограничены» не выполнялся, и это дало правку 97a4be4 (tune.rcvbuf.client).

Медианы трёх повторов, тело 10 MiB (из summary.md метки; «пик» — memory.peak реплики за окно, сброшенный перед нагрузкой; при OOM — наибольшая выборка):

Вариант C Пик, MiB OOM 201 429 5xx Загрузок/с p95, мс Пик LB, MiB
до 1 130,7 0/3 258 0 0 11,20 106 31,9
до 10 322,1 0/3 215 0 0 9,25 1 479 30,3
до 20 454,2 3/3 1 0 380 0 — 37,7
до 40 493,5 3/3 0 0 760 0 — 53,2
без лимита 1 120,7 0/3 263 0 0 11,45 106 30,3
без лимита 10 225,4 0/3 208 0 0 8,85 1 485 30,5
без лимита 20 330,9 0/3 218 0 0 9,00 2 712 38,2
без лимита 40 507,3 3/3 0 0 760 0 — 52,3
с лимитом 1 120,7 0/3 253 0 0 10,95 113 30,5
с лимитом 10 169,5 0/3 258 0 0 10,80 1 214 36,1
с лимитом 20 177,3 0/3 269 0 0 10,90 2 059 42,9
с лимитом 40 181,3 0/3 269 452 0 11,00 2 092 52,3

Те же медианы, тело ~1 MiB (OOM нет ни в одной ячейке, 5xx — 0):

Вариант C Пик, MiB OOM 201 429 5xx Загрузок/с p95, мс Пик LB, MiB
до 1 110,0 0/3 1 445 0 0 62,85 17 30,8
до 10 136,8 0/3 2 976 0 0 129,85 108 34,4
до 20 153,0 0/3 2 950 0 0 127,85 196 37,6
до 40 199,2 0/3 3 043 0 0 132,15 365 52,8
без лимита 1 109,0 0/3 1 477 0 0 64,05 17 30,8
без лимита 10 127,1 0/3 2 946 0 0 128,30 107 34,8
без лимита 20 138,0 0/3 3 026 0 0 131,75 203 37,4
без лимита 40 163,2 0/3 3 045 0 0 131,95 367 52,7
с лимитом 1 109,0 0/3 1 480 0 0 64,20 17 30,5
с лимитом 10 119,7 0/3 2 822 0 0 124,00 106 34,6
с лимитом 20 127,0 0/3 2 728 0 0 118,75 211 38,3
с лимитом 40 132,2 0/3 2 751 460 0 119,60 210 52,5

Память до окна во всех ячейках — ~105 MiB, пик старта реплики (фиктивный хэш пароля, разогрев) — ~152,6 MiB и в пик окна не входит.

Выводы (строки «Гипотезы» и «Сценарии спеков» summary.md):

  • H1 — подтверждена. «С лимитом» пик 169,5 / 177,3 / 181,3 MiB при 10 / 20 / 40 клиентах — меньше половины лимита (256 MiB); рост сверх C = 10 на клиента — (177,3 − 169,5) / 10 = 0,78 MiB при C = 20 и (181,3 − 169,5) / 30 = 0,39 MiB при C = 40 (порог 1); OOM 0, 5xx 0, лишние загрузки — 429 (1 351 за ячейки 10 MiB, строка «Сценарии спеков»). Строка H1 сводки метки считает 429 по обоим телам и C = 1 (2 731): так разбор сводки работал до правки по verify, новые метки считают только ячейки гипотезы. Сценарий attachments «Память не растёт с числом загрузок» выполнен. load-balancing «Буферы соединений ограничены» (C = 1 → 40, ячейки «с лимитом» 10 MiB) — пик LB (52,3 − 30,5) / 39 = 0,56 MiB на клиента, sock реплики (19,4 − 4,1) / 39 = 0,39 MiB, в сумме 0,95 MiB при пороге 1 MiB, OOM 0: выполнен. Вердикта по нему в сводке метки нет — его строку разбор пишет с правки по verify, числа выше — из ячеек той же сводки.
  • H2 — подтверждена. «Без лимита»: 1,20 тела на клиента при C = 10 и 1,13 при C = 20 (чуть ниже ожидаемых 1,2–1,3), при 40 × 10 MiB — OOM 3/3. «До»: 2,17 тела на клиента при C = 10 — вторая копия тела при PUT, при 20 × 10 MiB — OOM 3/3. Сценарий attachments «Одна копия тела при записи в S3» (≤ 1,5 тела у «без лимита», больше у «до») выполнен.
  • H3 — подтверждена. «С лимитом» / «без лимита» на тех же C: 10 MiB — 122 % и 121 % при 10 и 20 клиентах (10,80 / 8,85 и 10,90 / 9,00), 1 MiB — 97 / 90 / 91 % при 10 / 20 / 40. На 10 MiB с местами даже быстрее — вероятно, потому что без лимита один CPU реплики делит между 10–20 проверками изображения, а S3 — между 10–20 PUT (метка этого не разбирает). На 1 MiB 90 % при C = 20 — ровно на пороге. p95 «с лимитом» растёт на ожидание в очереди (2 059 мс при 20 клиентах).
  • H4 — подтверждена. 503 нет ни в одном из 63 прогонов без OOM, в том числе у «без лимита» при 20 клиентах по 10 MiB.
  • Ограничения измерения: один хост с ВМ Docker Desktop, генератор k6 на том же хосте и в той же ВМ, одна нода S3; пик — по cgroup реплики, без разбора памяти внутри процесса; окно 20 с и 3 повтора. Пробные метки quick-uploads-* в git не идут.

Стоимость сверки: гипотезы (change track2-reconcile-cost)

Гипотезы записаны до первого прохода метки профиля reconcile и закоммичены отдельно, раньше commit с её результатами (спек load-benchmark, «Гипотезы сверки до прогонов»). Числа в гипотезах взяты из проб design change track2-reconcile-cost (Context, «Пробы»), а не из метки. Пробы шли на шумном хосте, но счётчики в них точные. Если метка разойдётся с гипотезой, гипотезу не правлю: ниже, после метки, пишу вывод «опровергнута». Код метки — 8d4cf7e.

Методика (design, решения 1–3 и 8–11), команда make bench_reconcile.

Стенд mtusi-bench, лимиты рабочего стенда:

  • LB, две реплики API по 1 CPU / 512 МБ;
  • PostgreSQL 2 CPU / 1 ГБ, Valkey 0,5 / 128 МБ;
  • S3 1 / 512 МБ, с портом метрик шлюза только на loopback своего контейнера.

Проход — разовый процесс уборщика из образа приложения: reconcile, 0,25 CPU / 256 МБ без swap; в управляемом опыте — 1 CPU. Grace проходов — 30 с. Без фоновой нагрузки проходы идут dry-run и без предела скорости.

Данные — синтетические вложения одного чата, наполнение мимо API: метаданные пишутся \copy в PostgreSQL стенда, объекты — прямым PUT в S3 ключами пользователя API.

  • Этапы: A — 1 000 объектов по 1 MiB; B → C → D — 10 000 → 30 000 → 100 000 объектов по 4 KiB, набор растёт.
  • Расхождения: по 0,25 % на класс — объект без метаданных, метаданные без объекта, другой размер, зависшая загрузка. Класс объекта задаёт i mod 400, содержимое — номер и зерно.
  • Каждый проход сверяет найденное с моделью набора. Расхождение — отказ команды.

Ячейки:

  • A: batch, deep, deep-fast;
  • B: batch, head, deep;
  • C: batch, head;
  • D: batch и четыре варианта под фоновой нагрузкой — stand (0,25 CPU, предел 2000/с), stand-unlimited (0,25 CPU, без предела), fast-unlimited (1 CPU, без предела), fast-limited (1 CPU, 2000/с);
  • S4 — свежий стенд: 10 000 согласованных объектов, затем 1 000 и 10 000 строк ready без объекта; --apply --max-changes 100 на образе 7f4e626 (код до change, «до») и на образе checkout («после»).

Фоновая нагрузка — k6 через LB: 300 скачиваний вложений набора, 50 записей сообщений и 50 чтений истории в секунду. До первого прохода и после каждого — тихое окно 30 с.

Повторы и шум. Три повтора кругами, повторы одной ячейки не идут подряд. Шум — разброс повторов. У проходов под нагрузкой ещё A/A: отношение a = p95 окна до прохода / p95 окна после.

Счётчики. Запросы S3 по итогу прохода сверяются с метриками шлюза (SeaweedFS_s3_request_total; HEAD шлюз считает типом GET). CPU и память — по cgroup, отсчёты раз в 0,5 с.

Гипотезы:

  • H1 — линейность (batch, этапы B, C, D, 0,25 CPU):

    • цена на объект (duration_ms / N) при 10k, 30k и 100k различается не больше чем на 20 %. Проба: 0,30 мс и при 10k, и при 100k;
    • запросы S3: LIST = ⌈N / 1000⌉ + 1 (страницы списка и проба bucket), HEAD — только у кандидатов (0,75 % N);
    • сеансов PostgreSQL — по одному на страницу списка, на страницу строк ready и на выборку зависших, плюс по одному на кандидата, кроме зависших;
    • пик памяти уборщика растёт с N не больше чем на 300 Б на ключ. Считается как наклон пика между 10k и 100k: постоянная часть прохода (прогрев клиентов, ~14 МиБ на пробе быстрого профиля) в разность не входит. Проба — ~150 Б на ключ. Отсюда предел batch при 256 МБ — порядка миллиона ключей.
  • H2 — batch против HEAD на строку (этапы B и C):

    • на обход batch делает ≈ 3 запроса на 1000 объектов, HEAD — ≈ 2 на объект. С перепроверкой при 1 % расхождений — ~18 против ~2 000 запросов к S3 и PostgreSQL на 1000 объектов;
    • время на объект у HEAD больше в 10 раз и более. Проба: ~17×;
    • память HEAD от N не растёт: пик при 30k больше пика при 10k не больше чем на 5 МиБ.
  • H3 — поверхностная против глубокой:

    • глубокая на 4 KiB (B) дороже batch по времени на объект не меньше чем в 5 раз (проба: ~9×), GET — на каждую согласованную строку;
    • на 1 MiB (A) время на объект больше, чем на 4 KiB, на 5 мс на MiB и более (проба: ~8 мс при 0,25 CPU);
    • на лимите стенда глубокую ограничивает CPU уборщика (≥ 90 % его лимита), а не S3 (≤ 0,5 ядра);
    • с 1 CPU у уборщика глубокая быстрее не меньше чем в 1,5 раза.

    Вывод, который проверяется: глубокая сверка — по требованию, в плановую она не входит.

  • H4 — влияние на фоновую нагрузку (D, 100k, batch). r — p95 окна прохода / p95 тихих окон до и после, по каждому из трёх сценариев:

    • держится: у stand, stand-unlimited и fast-limited медиана r по трём повторам ≤ 1,5 во всех трёх сценариях;
    • контраст: у fast-unlimited медиана r скачиваний > 1,5 (проба: 2,2–2,75). Иначе метод эффекта не видит, и H4 — «не проверена», а не «подтверждена»;
    • шум: медиана a вне [1/1,5; 1,5] — вывод «не различимо на этом хосте»;
    • ответ 5xx фоновой нагрузки — пометка прохода, с ней H4 не подтверждается.
  • S4 — цена отказа по пределу (ожидание, не гипотеза трека). Сравнение — с ячейкой batch этапа B: тот же N = 10k, кандидатов нет.

    • «до» длиннее её примерно на D × 5 мс: +5 с при D = 1 000 и +50 с при D = 10 000;
    • «после» длиннее не больше чем на 1 с, HEAD — не больше max_changes + 1 = 101;
    • у обоих — отказ с кодом 3, данные не меняются.

Предел скорости по умолчанию (2000 объектов S3 в секунду) обоснован пробой: ~0,2 ядра шлюза на списке, плановый проход 100k — ~65 с вместо ~30. Проверяет его H4 (stand против stand-unlimited, fast-limited против fast-unlimited). Рекомендации для HEAD и глубокой сверки выводятся из CPU S3 на объект в ячейках без нагрузки — после метки.

Стоимость сверки: результаты метки baseline

  • Метка: evidence/reconcile/baseline/ (commit с результатами — 0072dbe; гипотезы — aaf3fa3, раньше). Код и стенд — d8b8ae3, dirty: false; 51 проход за 45 мин, 2026-10-23 15:06–15:52 UTC. От 8d4cf7e (код гипотез) d8b8ae3 отличается только проверкой полноты строк фоновой нагрузки в bench/: src тот же.
  • Хост — по паспорту: Apple M3 Pro, 18 ГиБ, macOS 26.6.2; Docker Desktop 29.9.2, ВМ 12 CPU / 7,7 ГиБ, ядро 7.0.14-linuxkit; питание от сети, свободно 65 % памяти до и 60 % после. swapouts_delta 0, slept_seconds 0, host_warnings и посторонних контейнеров нет. Прерванных итераций фоновой нагрузки — 0 по всем сценариям.
  • Две первые попытки метки упали на проходе 39 из 51, в начале этапа D, на проверке полноты строк фоновой нагрузки. Её строгое равенство ломалось на итерации k6, которую прервала остановка SIGINT уже после записи строки: на aaf3fa3 — против iterations, на a42dd27 — против своего счётчика строк. Ни одной строки не пропало, хост в обеих чистый. Проверка теперь — снизу по итерациям и счётчику, лишних не больше VU сценария (design change, «Уточнения apply», п. 15). Каталоги неполных меток в git не идут, метка снята заново целиком.
  • Найденное в каждом проходе равно внесённому по классам, listed_objects и checked_rows равны модели набора, пометок count_mismatch нет: счёт сверки совпал с метриками шлюза S3.
  • Вердикты после verify. Verify (S6) нашёл, что вердикты bench/reconcile.py проверяли не все критерии гипотез: сеансы PostgreSQL в H1 (и LIST — с допуском ±1), «~18 против ~2000» запросов на 1000 объектов в H2, GET на каждую строку в H3, неизменность данных в S4. Критерии добавлены (LIST и сеансы — точно, H2 — ±25 %, S4 — ни одного исправления в итоге и записей «Fixed»). Пути пересобрать summary.md метки офлайн у стенда нет, и ради этого он не заводился: summary.md метки посчитан прежним кодом. Новые критерии на данных метки (passes.csv, windows.csv, raw/*-cleaner.json) пересчитаны отдельно — все выполняются, вердикты те же: LIST 11 / 31 / 101 и сеансов 96 / 286 / 953 равны ожидаемым, 18,2 / 18,1 против 2015, GET 9 900 / 988 / 988 — по строке того же размера с объектом, у S4 fixed пуст во всех 12 проходах. Ошибок фона по всему итогу k6 тоже нет: http_req_failed 0 из 356 170, dropped_iterations нет (S9).
  • Метка и правка W2. После метки verify (W2) нашёл, что batch не сравнивал с объектом строку, ключ которой — <Z>/original другого вложения (head сравнивал). Исправлено в пользу head: каждая строка сверяется с объектом по своему ключу (спек storage-consistency, «Строка ссылается на объект другого id»). Метка остаётся действительной: в её наборе у каждой строки свой ключ (<база>/attachments/<свой id>/original, reconcile.rows_csv), новая ветка на нём не срабатывает, лишних запросов S3 и PostgreSQL не добавляет; на строку прибавилось одно сравнение ключа со своим.

Проходы без фоновой нагрузки. Медианы трёх повторов из summary.md, разброс там же. «мкс/объект» — длительность прохода / N, CPU — средние ядра за окно прохода, память уборщика — пик.

Этап N Ячейка Проход, с мкс/объект LIST / HEAD / GET Сеансов БД CPU уборщика CPU S3 Пик памяти, МиБ
A (1 MiB) 997 batch 0,41 416 2 / 9 / 0 12 0,230 0,127 91,8
A (1 MiB) 997 deep 8,59 8 617 2 / 9 / 988 12 0,249 0,202 96,1
A (1 MiB) 997 deep-fast (1 CPU) 3,07 3 079 2 / 9 / 988 12 0,595 0,477 95,3
B (4 KiB) 9 975 batch 2,81 281 11 / 75 / 0 96 0,245 0,327 97,4
B (4 KiB) 9 975 head 60,98 6 114 11 / 10 025 / 0 10 061 0,249 0,070 96,4
B (4 KiB) 9 975 deep 31,31 3 139 11 / 75 / 9 900 96 0,249 0,159 98,3
C (4 KiB) 29 925 batch 9,29 311 31 / 225 / 0 286 0,239 0,326 101,0
C (4 KiB) 29 925 head 189,79 6 342 31 / 30 075 / 0 30 181 0,249 0,073 96,6
D (4 KiB) 99 750 batch 31,93 320 101 / 750 / 0 953 0,241 0,315 111,2

Фоновая нагрузка (H4), этап D, 100k, batch, медианы трёх повторов:

Ячейка CPU уборщика / предел Проход, с CPU уборщика CPU S3 CPU реплик r скачиваний / записи / чтения a скачиваний / записи / чтения 5xx
stand 0,25 / 2000 57,5 0,11–0,12 0,27–0,30 0,99–1,14 1,01 / 1,02 / 1,03 0,98 / 0,96 / 0,96 0
stand-unlimited 0,25 / — 26,7 0,25 0,42–0,45 1,02–1,17 1,06 / 1,07 / 1,07 1,04 / 1,06 / 1,04 0
fast-unlimited 1 / — 12,9 0,50 0,70–0,73 1,06–1,24 1,08 / 1,08 / 1,08 1,01 / 1,04 / 1,01 0
fast-limited 1 / 2000 52,2 0,12–0,13 0,28–0,32 0,99–1,14 1,02 / 1,03 / 1,02 1,00 / 0,98 / 0,99 0

CPU — диапазон трёх повторов из passes.csv (cpu_cleaner, cpu_s3, cpu_api — сумма двух реплик). p95 скачиваний в тихих окнах — 5,4–6,3 мс, во время прохода fast-unlimited — 5,88–7,48 мс (windows.csv).

Отказ по пределу (S4), --apply --max-changes 100, 10 000 согласованных объектов:

Кандидатов «До» (7f4e626), с «После», с База — B batch (10k, dry-run), с HEAD «после» Не перепроверено Код
1 000 7,99 3,08 2,81 101 899 3 / 3
10 000 59,28 3,41 2,81 101 9 899 3 / 3

База S4 — не «проход без кандидатов», как названа в гипотезах выше и в summary.md метки: у B batch 75 перепроверок (объекты без строки, строки без объекта, другой размер) и 25 зависших загрузок; шаг перепроверки — 0,49–0,51 с прохода (phase_recheck_ms). «После» перепроверяет 101 кандидата, поэтому его прирост над базой мерит цену отказа без лишних перепроверок, а не нулевую; вердикт от этого не меняется: +0,27 и +0,60 с меньше порога 1 с (замечание S5 verify, метка не переснималась).

Повторы D batch (r1–r3) в метке идут подряд: в группе без нагрузки на этапе D одна ячейка, остальные проходы этого набора — блок под фоновой нагрузкой. Спек load-benchmark это исключение теперь называет (замечание S8 verify). Разброс повторов D batch — 30,7–32,2 с (5 %), у C batch, где повторы чередуются с head, — 9,1–9,6 с (5 %): шума от порядка повторов не видно.

Выводы (раздел «Гипотезы» summary.md):

  • H1 — подтверждена. Цена batch на объект — 281 / 311 / 320 мкс при 10k / 30k / 100k: разброс 13,7 % при пороге 20 %. LIST — 11 / 31 / 101 (= ⌈N / 1000⌉ + 1), HEAD — 75 / 225 / 750, то есть только кандидаты; сеансов — 96 / 286 / 953. Наклон пика памяти между 10k и 100k — 161 Б на ключ (порог 300, проба ~150): при 256 МБ уборщика batch держит порядка миллиона ключей.

  • H2 — подтверждена. HEAD на строку дороже batch по времени на объект в 21,7 раза при 10k и в 20,4 раза при 30k (порог 10, проба ~17). Запросов S3 и сеансов на 1000 объектов — 18,2 / 18,1 у batch против 2015 у HEAD. Пик памяти HEAD от 10k до 30k вырос на 0,2 МиБ (порог 5): памяти на ключи он не держит, но на 100k шёл бы ~10 мин против 32 с.

  • H3 — подтверждена. Глубокая на 4 KiB дороже batch в 11,2 раза (порог 5). Байты стоят 5,50 мс на MiB (порог 5). На 1 MiB на лимите стенда уборщик занят на 0,249 ядра (100 % лимита), S3 — на 0,202 ядра: упор в CPU уборщика, а не в S3. С 1 CPU глубокая быстрее в 2,80 раза (порог 1,5). Вывод: глубокая сверка — только по требованию, в плановую она не входит.

  • H4 — не проверена. Критерий «держится» выполнен: у stand, stand-unlimited и fast-limited медиана r ≤ 1,07 во всех трёх сценариях, a — 0,96–1,06, 5xx нет. Но контраст не сработал: у fast-unlimited медиана r скачиваний — 1,08, а по критерию нужно больше 1,5. Методика не показала, что заметила бы влияние, если бы оно было. Поэтому вывод «проход не мешает фоновой нагрузке» метка не доказывает: «держится» здесь не отличить от «метод не видит». Почему контраст не сработал (по данным метки):

    • проход fast-unlimited шёл с ожидаемой скоростью: 100k за 12,9 с против 13,1 с в пробе. Уборщик занял 0,50 ядра из 1: его ограничивал уже не свой CPU, а, по пробе design, последовательный список шлюза;
    • S3 за окно прохода занят на 0,70–0,73 ядра из 1 вместе с фоновыми скачиваниями. Насыщения не было: у шлюза оставалось ~0,3 ядра. Обход идёт одним потоком, страница за страницей, а 300 скачиваний в секунду по 4 KiB обслуживаются параллельно и коротко. Реплики заняты на 1,06–1,24 ядра из 2;
    • проба design, обещавшая ×2,2–2,75, была одной и на шумном хосте. В тихих окнах той же пробы p95 был 10 и 6 мс, а одно окно дало 93 мс. В метке тихие окна стабильны (5,4–6,3 мс), и самый большой эффект — первый повтор fast-unlimited: 7,48 против 6,25 мс (r 1,20; в окне шага списка — 1,24).

    Что это значит для предела скорости. Метка не показала, что на этих лимитах предел нужен, чтобы защитить задержки фона: даже без предела и с 1 CPU уборщика p95 вырос на ≤ 8 % (медиана). Зато метка измерила, что предел ограничивает долю CPU шлюза, сколько бы CPU ни дали уборщику: с пределом S3 за проход — 0,27–0,32 ядра и при 0,25, и при 1 CPU уборщика. Без предела — 0,42–0,45 и 0,70–0,73. Цена предела — проход 100k в 2,2 раза (0,25 CPU) и в 4 раза (1 CPU) дольше; на рабочем стенде (2–3 тыс. объектов) — около секунды в час. Поэтому 2000 оставлен как страховка доли S3 для быстрого уборщика (design, «Risks»), а не как доказанная защита задержек. Влияние на задержки может проявиться там, где шлюз близок к насыщению: больше фоновой нагрузки, медленнее S3. Его метка не воспроизводит. Чтобы H4 проверить, нужен контраст, который насыщает S3: например, fast-unlimited при S3 с 0,5 CPU или с фоном в 2–3 раза больше. Это смена методики и новая метка; в этот change она не входит.

  • S4 — подтверждена. «До» длиннее базы (B batch) на 5,2 с при 1 000 кандидатах и на 56,5 с при 10 000 (ожидалось ~5 и ~50 с: ~5 мс на кандидата). «После» — на 0,27 и 0,60 с (порог 1 с), HEAD — 101 = max_changes + 1, не перепроверено 899 и 9 899. Коды — 3 у обоих, данные не менялись.

Выбор предела 2000. Ключ списка стоит шлюзу 0,100 мс CPU (D batch: 0,315 ядра × 31,9 с / 100 501 объект S3). При 2000 объектов в секунду это ~0,2 ядра S3 из 1 — оценка по цене ключа, а не замер. У stand и fast-limited метка показала 0,27–0,32 ядра S3 за окно прохода, но это вместе с фоновыми скачиваниями: сколько из этого приходится на одну сверку, метка не выделяет (тихого окна без прохода с CPU S3 в ней нет). Естественная скорость batch на 0,25 CPU — ~3 100 объектов/с за проход, с 1 CPU под фоновой нагрузкой — ~7 800/с; предел срезает обе до 2000.

Рекомендации для head и глубокой сверки. Предел считает объекты S3 (ключ списка, HEAD, GET), а объект у них дороже ключа списка. CPU шлюза на объект S3 в ячейках без нагрузки (CPU S3 × длительность / объекты S3 из passes.csv):

Ячейка мс CPU S3 на объект S3 при 2000/с, ядер Естественная скорость на 0,25 CPU, объектов/с Предел для доли ~0,2 ядра
batch (D) 0,10 0,20 ~3 100 2000
head (B) 0,21 0,43 ~330 ~1000
deep, 4 KiB (B) 0,25 0,50 ~640 ~800
deep, 1 MiB (A; 1 CPU — 0,73) 0,87 1,74 ~230 (1 CPU — ~650) ~250

На лимите стенда (0,25 CPU) предел 2000 у head и глубокой не срабатывает: их держит собственный CPU уборщика, и S3 занят на 0,07–0,20 ядра. С быстрым уборщиком разовый проход стоит запускать с --max-objects-per-second около 1000 для head, около 800 для глубокой на мелких объектах и около 250 на объектах порядка мегабайта. Иначе глубокая на 1 MiB с 1 CPU занимает уже ~0,48 ядра шлюза.

Ограничения измерения:

  • один хост, ВМ Docker Desktop, генератор k6 на том же хосте и в той же ВМ;
  • одна нода S3 (SeaweedFS, 1 CPU);
  • объекты синтетические и двух размеров (4 KiB и 1 MiB), один чат;
  • лимит CPU уборщика — 0,25 и 1, другие не мерились;
  • CPU — средние по отсчётам cgroup раз в 0,5 с за окно прохода; память уборщика — пик за жизнь контейнера;
  • 3 повтора; второй метки A/A нет, шум — разброс повторов и a.

Пробные метки quick-reconcile-* в git не идут.

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

Какие отказы стенд выдерживает (подтверждено проверками, таблица «Доказательства критериев»):

  • остановка, kill и заморозка одной реплики API: LB уводит запросы, запись восстанавливается за 0,76–1,2 с без дублей, вложение отдаёт другая реплика с тем же SHA-256;
  • отказ S3 (остановлен, заморожен, нет bucket, отказ в доступе): 503 только на загрузке и скачивании байтов, а текст, история, метаданные и /health/ready работают;
  • отказ PostgreSQL или процесса API посреди загрузки, обрыв клиента, медленный клиент: ответ 503 или 4xx, а не 201 и не 500; неучтённых объектов старше grace + интервал не остаётся (компенсация, уборщик, сверка);
  • отказ Valkey: обход кэша;
  • рестарт всего стенда с volumes: данные, прежние сессии и оригиналы вложений целы.

Чего стенд не выдерживает: отказ хоста или ВМ Docker, единственного HAProxy и единственного PostgreSQL (без него API отвечает 503, LB выводит реплики), потерю диска S3 (одна нода без репликации). Один Docker-host — не отказоустойчивость к потере этого host (COURSE.md).

Что не реализовано:

  • трек 1 «Прямой upload» — выбран один трек 5, трек 2;
  • в CI нет make s3_check, make test_isolated, make failure_checks и замеров bench/: им нужны порты хоста, отдельные проекты и десятки минут (раздел «CI» в «Запуск из чистого clone»). Их выводы — в evidence/;
  • Swarm: стенд — один проект Compose;
  • полное декодирование изображения, превью и асинхронная обработка — лаба 5; лимит одновременных скачиваний — вне лабы.

Учебные упрощения: один хост, генератор нагрузки на нём же; одна нода S3 без fsync; секреты в .env и видны в docker inspect; HTTP без TLS (лаба 7).

Подтверждено и гипотеза. Замер загрузок: H1–H4 подтверждены — с местами загрузки пик реплики при 40 × 10 MiB — 181,3 MiB (медиана), а без них реплику убивает OOM. Замер сверки: H1, H2, H3 и S4 подтверждены, H4 не проверена — контраст без предела не насытил S3, поэтому предел скорости 2000 — страховка доли CPU шлюза, а не доказанная защита задержек фона.

Известные дефекты (KNOWN_ISSUES.md, четыре открытые записи, ни одна не затрагивает стенды проекта в штатной работе):

  • повторный bootstrap после удаления bucket на маленьком tmpfs падает на «api key wait (code 500)» — не хватает слотов томов SeaweedFS;
  • уборщик удаляет объект зависшей загрузки по ключу вне своего префикса (бывает только в базе, восстановленной под другим именем);
  • LB отвечает 408 на медленные заголовки страницей HAProxy, а не в формате контракта;
  • поля float настроек принимают inf.

Следующие шаги: ответы на открытые вопросы преподавателю; новая метка сверки с контрастом, который насыщает S3 (S3 0,5 CPU или фон в 2–3 раза больше), — проверка H4; исправление записей KNOWN_ISSUES.md; лаба 5 — 202, worker и staging-prefix, где сверке прибавятся варианты под префиксом вложения.

S3 (change s3-storage):

  • Одна нода S3 без репликации и fsync. SIGKILL процесса подтверждённых объектов не теряет (evidence/s3/restart.md). Отказ диска или ВМ теряет объекты, и запись, подтверждённая перед падением ВМ, может пропасть. Учебное упрощение, как один PostgreSQL.
  • Плавная остановка SeaweedFS ~15 с: срок зашит в filer. Поэтому stop_grace_period: 20s, а make stop и scripts/restart.sh дольше на ~15 с. На стенде отказов — 2 с: там проверяется отказ.
  • gRPC шлюза открыт в сети стенда: отдельно его не закрыть, он защищён ключом подписи (evidence/s3/grpc-admin.md).
  • Секреты S3 видны в docker inspect контейнеров s3 и s3-bootstrap, как POSTGRES_PASSWORD. Стенд локальный, порты только на 127.0.0.1. TLS — лаба 7.
  • Лимит загрузок шлюза ставит запросы в очередь. 20 одновременных PUT по 10 MiB напрямую заканчиваются через 7,2 с — больше срока вызова клиента (5 с). Через API столько PUT не бывает: места загрузки дают не больше 4 PUT от реплики (12 при замене, p95 1,6–1,9 с), и в метке uploads 503 по сроку S3 нет (change upload-memory, решение 8).
  • Отказ S3 — 503 на путях вложений, а не отказ сервиса. Отказ хоста, LB и PostgreSQL стенд не переживает (.claude/rules/balancer.md).
  • Дефект aiohttp (проверен в 3.14.5): срок чтения переживает ответ. После потокового ответа с паузой чтения resume_reading() взводит sock_read у соединения в пуле. Через срок соединение портится, и следующий вызов на нём падает за 1 мс. Проект от этого закрыт тем, что sock_read не использует (read_timeout=None, раздел «Сроки клиента S3»). Срок вызова и блока даёт asyncio.timeout приложения: зависший S3 по-прежнему обрывается за 5 с. Обновлением aiohttp от дефекта не уйти: 3.14.5 — последняя версия, дефект воспроизведён в ней, а ниже 3.14.0 не пускает aiobotocore 3.9.2. Другие версии пробой не проверялись; по исходникам перевзвод срока в resume_reading() есть в каждой просмотренной версии от 3.12.15 до 3.14.4, нижняя граница дефекта не установлена (evidence/s3/idle-connection.md, раздел 1). Отчёт об ошибке в aiohttp не отправлен: это вне лабы. Если upstream её исправит, проекту срок чтения aiohttp всё равно не нужен. Новый дефект того же рода поймают test_upload_after_idle_s3 и driver.py s3-idle.

Вложения (change attachments):

  • Проверка изображения структурная. Обрезанный файл, битая CRC, сломанные маркеры, поток zlib не того объёма и «бомба» — 415. Но байт, изменённый внутри сжатых данных скана JPEG, не ловится: у формата нет контрольной суммы, Pillow его тоже не ловит. Полное декодирование — worker лабы 5.
  • Память загрузки — ~1,2 тела на загрузку, загрузок на реплике — не больше 4. Прежняя оценка «~1,2 тела» была неверна: проверка моделировала только botocore, а aiohttp при PUT копировал тело ещё раз (до change — 2,17 тела на загрузку, OOM при 20 × 10 MiB). После change upload-memory — 1,20 тела (одна копия), а число одновременных загрузок ограничено местами (раздел «Память и сроки загрузки»; порог mmap glibc в образе по-прежнему нужен).
  • Ограничение текста сообщения NOT VALID. Ослабленное условие (<= 4000) добавлено без проверки прежних строк: они уже удовлетворяли более строгому, а VALIDATE держал бы ACCESS EXCLUSIVE на всё время просмотра messages. В каталоге ограничение помечено «не проверено»; новые строки оно проверяет как обычно.
  • Ранний ответ на большое тело. 404, 413 и 415 отдаются, не дочитав тело. Через LB ответ получает любой клиент (HAProxy дочитывает тело), httpx и curl — и напрямую; Python urllib напрямую к одной реплике ответ теряет (BrokenPipe).
  • Смешанные версии во время make rolling_update. Старая реплика не знает путей вложений (404) и attachment_ids (400) и отдаёт сообщения без attachment_ids. Окно — секунды замены. Откат на e1161f7 (MIGRATE=0) прячет вложения и показывает пустые тексты сообщений с вложениями; схема при этом не откатывается.
  • Обрыв S3 посреди скачивания — статус уже ушёл: клиент получает тело короче Content-Length, причина — в журнале.

Согласованность БД и S3 (change upload-consistency):

  • Остаток риска — объект без строки. Процесс API заморожен дольше grace (15 мин) ровно посреди PUT, уборщик за это время убрал строку, а после разморозки S3 принял тело. Для API PUT кончился ошибкой по сроку, компенсации нет — объект остаётся без строки. То же, если PUT прошёл после уборки, mark_ready вернул 0 строк, а удаление при компенсации не удалось (warning «Attachment object kept for cleaner»). Вероятность мала (запас ×50, заморозка посреди PUT); с change track2-reconciler такой объект удаляет плановая сверка не позже grace + интервал сверки (~75 мин). ready без объекта при этом не возникает: уборщик помечает строку до удаления объекта, а помеченную mark_ready в ready не переводит.

  • Смесь версий уборщика и реплик. Реплики до 87c48b9 (f2dc0b3 и раньше) пометку не проверяют, а прежний уборщик её не ставит; make rolling_update уборщика не пересоздаёт. Обе смеси не хуже, чем до правки:

    • новый уборщик + прежние реплики: объект и строка удаляются одной транзакцией под блокировкой, прежний mark_ready либо делает строку ready с целым объектом (уборщик её пропускает), либо ждёт commit и находит 0 строк;
    • прежний уборщик + новые реплики — поведение до правки.

    В обеих для загрузки, пережившей grace, остаётся прежний риск: откат транзакции уборки после удачного DELETE в S3 даёт ready без объекта. Нужно совпадение зомби дольше 15 мин и сбоя в окне меньше секунды. Порядок обновления сокращает окно: вперёд — сначала реплики (make rolling_update), потом docker compose up -d --no-deps cleaner; откат реплик на версию раньше 87c48b9 — сначала уборщик (его откат или docker compose stop cleaner), потом make rolling_update COMMIT=… MIGRATE=0. Новый mark_ready работает на строках прежних реплик (вставка всегда писала created_at = updated_at).

  • Проверка grace — по настройкам уборщика. config.toml у API и уборщика общий, но подмена сроков окружением только у API (DATABASE__REQUEST_TIMEOUT_SECONDS, S3__TIMEOUT_SECONDS) обошла бы проверку. Очередь загрузок change upload-memory границу не меняет: ожидание места, тело и проверка идут до pending (раздел «Память и сроки загрузки»).

  • Незавершённые загрузки живут до ~16 мин (grace 900 с + интервал + проход): они не видны по API и занимают место в bucket.

  • Вложения ready без ссылок из сообщений уборщик не трогает: это учтённые вложения (строка и объект есть), контракт срока им не задаёт. Сюда же попадает загрузка, у которой клиент оборвал соединение уже после тела: uvicorn задачу не отменяет, вложение становится ready, а 201 до клиента не доходит.

  • Компенсация добавляет до 5 с к ответу 503, если S3 стал медленным после удачного PUT (срок DELETE). Это учтено в цепочке пути загрузки: молчание после тела ≈ 26 с < timeout server LB пути загрузки 30 с (change upload-memory).

Память и сроки загрузки (change upload-memory):

  • Места считает каждая реплика. Одна может отвечать 429, пока у другой места есть; LB 429 не повторяет. Сглаживают очередь (16) и Retry-After: 1 — повтор клиента уходит на следующую реплику (round-robin). Общей очереди на стенд нет.
  • Оборванный клиент в очереди держит её место до срока ожидания (5 с): обрыв соединения API замечает, только когда начинает читать тело, то есть получив место. Пока такая загрузка ждёт, новая может получить 429 при полной очереди; затем она берёт место, сразу заканчивается interrupted и отпускает его (проба verify). Места загрузки она не держит дольше обычной.
  • 429 или 503 — вопрос преподавателю открыт (раздел «Открытые вопросы преподавателю», п. 1). Ответ «503» поменяет строку таблицы ошибок, сценарии спеков и ожидания тестов, но не подход.
  • Тело отклонённой загрузки реплика дочитывает и выбрасывает (uvicorn держит соединение): памяти это не стоит (буферы ограничены), но тратит CPU и сеть. Закрывать соединение после раннего ответа нельзя: ядро сбросило бы его вместе с непрочитанным ответом.
  • Буфер приёма LB от клиента — 128 KiB. Окно TCP клиента — ~20 Мбит/с при RTT 50 мс (10 MiB за ~4 с); клиенту с RTT больше ~370 мс 10 MiB за срок тела 30 с не передать.
  • Тысячи одновременных загрузок упрутся в LB: ~0,5 MiB на соединение в буферах ядра, а maxconn 4096 больше лимита LB 256 МБ. На стенде нагрузки такого уровня нет.
  • Скачиваний без лимита. Медленный клиент держит буферы отдачи у реплики и LB; лимит одновременных скачиваний вне change.
  • В консоли (make run_dev) ограничения буфера сокетов нет — sysctls только у контейнеров api; места и срок тела работают.
  • 408 на медленные заголовки — страницей HAProxy, не в формате контракта (timeout http-request 10 с; http-error такой ответ не меняет, errorfile дал бы статичный request_id) — KNOWN_ISSUES.md.
  • Зависшая реплика держит загрузку 30 с до 504 вместо 10 — только на пути загрузки; обнаружение отказа проверками LB прежнее (6,5 с).
  • ROLLOUT_DRAIN_TIMEOUT 90 с: застрявшая загрузка задерживает замену до ~73 с (срок тела); обычный дренаж — 0–2 с.
  • Замер памяти — один хост (ВМ Docker Desktop, генератор на том же хосте, одна нода S3), предупреждение о swap хоста в паспорте метки — раздел «Одновременные загрузки: результаты».
  • Пустые каталоги <id>/ в filer SeaweedFS после удаления объекта живут ~2 мин (fs.ls их видит, список S3 — нет). Проверки и драйвер считают объекты по файлам original; сверке трека 2 — учесть.
  • Окно 0 у уборщика, как у API. SIGTERM в первые десятки мс после старта контейнера (запуск интерпретатора до раннего обработчика) теряется: PID 1 без обработчика, Docker через 10 с шлёт SIGKILL (137). Данных это не портит — соединений и транзакций ещё нет (evidence/attachments/cleaner-process.md, раздел 5).
  • После make rolling_update уборщик на прежнем образе. Схема только расширяется (индекс), прежний код уборщика корректен; новый код — docker compose up -d --no-deps cleaner или make run_docker.
  • make env_setup дописывает только отсутствующие переменные: пустое или устаревшее значение уже существующей строки он не меняет — его правят руками.

Сверка хранилищ (change track2-reconciler):

  • Источник истины — PostgreSQL. База из старой копии или пустая при живом bucket сделает объекты новых вложений «объектами без метаданных», и сверка удалит их в пределах max_changes (100). По истине БД это верно, но восстановление базы «в живую» при работающем уборщике опасно: поэтому на время восстановления уборщик останавливают, а после — сначала make reconcile (dry-run).
  • Чужой объект живёт, пока его не удалит оператор: код 3 и warning на каждом проходе плановой сверки. Удалять непонятное опаснее (в лабе 5 под префиксом появятся варианты).
  • Повреждение того же размера плановая сверка не видит: она поверхностная — наличие и размер из LIST. Скачивание сверяет тоже только размер. SHA-256 сверяет разовый проход --deep (change track2-reconcile-cost): 5,5 мс на MiB при 0,25 CPU, поэтому только по требованию.
  • Память O(N) на ключи списка — по метке 161 Б на ключ (~16 МБ на 100 тыс. объектов при лимите уборщика 256 МБ, порядка миллиона ключей до лимита). Уборка зависших ждёт конца прохода сверки: на рабочем стенде — меньше секунды, на 100 тыс. — 32 с, с пределом скорости — ~58 с. Без множества ключей — --strategy head, но она в ~21 раз медленнее. При массовом расхождении --apply с change track2-reconcile-cost отказывает рано: остальные кандидаты — в unchecked, число изменений в ошибке — нижняя граница (max_changes + 1).
  • Зависшая загрузка с ключом вне префикса вложений своей базы: сверка её только называет (чужой объект), а сервис уборки, как и до change, убирает её вместе с объектом по этому ключу (KNOWN_ISSUES.md).
  • Пометка по ложному «нет объекта» при неполном списке отсечена HEAD и проверкой bucket; остаётся bucket, пересозданный пустым между проверкой и UPDATE — тогда пометка верна и снимается сама, когда объект вернётся.
  • Две сверки разом (плановая и разовая) — действия идемпотентны, отчёты могут разойтись в числах fixed; блокировки нет.
  • Часы: LastModified — часы ВМ, порог — часы контейнера уборщика (одни часы), точность LastModified — секунда; updated_at строк консольного API на macOS расходится на секунды — меньше grace.
  • Ответ API на потерянный оригинал — трактовка контракта, вопрос преподавателю открыт (раздел «Открытые вопросы преподавателю», п. 2).
  • Старый образ уборщика после make rolling_update — сверки нет, как до change; новый — docker compose up -d --no-deps cleaner (порядок обновления).
  • Синтетика прогонов драйвера (reconcile-cycle, reconcile-stress) остаётся в рабочей базе и bucket: согласованные вложения и помеченные потерянными — одно за прогон цикла и два за прогон стресса (lost_known 1 → 3; их байты — 404).
  • make failure_checks дольше на ~4,5 мин (48 проверок, ~9 мин): объекты нельзя состарить, тесты ждут grace стенда (20 с).

Стоимость сверки (change track2-reconcile-cost):

  • H4 не проверена. Контраст без предела и с 1 CPU уборщика не насытил S3 (0,70–0,73 ядра из 1) и задержки фона почти не сдвинул (r 1,08). Поэтому «сверка не мешает фону» на этих лимитах не доказана, а только не опровергнута. Предел 2000 оставлен как граница доли CPU шлюза, а не как доказанная защита задержек. Проверка — новая метка с контрастом, который насыщает S3 (S3 0,5 CPU или фон в 2–3 раза больше). Это смена методики.
  • Измерение: один хост, ВМ Docker Desktop, генератор k6 на том же хосте и в той же ВМ; одна нода S3; синтетические объекты двух размеров (4 KiB и 1 MiB) в одном чате; CPU уборщика — 0,25 и 1; 3 повтора без второй метки A/A.
  • Предел скорости — среднее за проход, а не мгновенная скорость: страница списка (1000 ключей) — один вызов, после неё пауза. Шлюз получает запросы пачками. У head и глубокой предел 2000 на лимите стенда не срабатывает: их держит CPU уборщика. С быстрым уборщиком нужен меньший --max-objects-per-second (раздел «Стоимость сверки: результаты метки baseline», рекомендации).
  • Глубокая сверка — только разовая: плановая всегда поверхностная, и повреждение того же размера ждёт ручного --deep.
  • Ранний отказ называет нижнюю границу: changes в ошибке — max_changes + 1, точного числа изменений нет. Полный список — в dry-run, он перепроверяет всех.
  • make failure_checks — ещё ~4 мин (56 проверок, ~15 мин): семь проверок сверки change ждут grace стенда.

Источники, библиотеки и использование ИИ

Документация и спецификации, по которым приняты решения. Ссылки — на корень документации, нужный раздел назван словами. Поведение стенда при этом проверено пробами и тестами, их выводы — в evidence/:

  • Amazon S3 — https://docs.aws.amazon.com/AmazonS3/latest/userguide/ (из README.md задания): загрузка объектов, presigned URL (почему не трек 1), политики bucket с условием s3:prefix; API Reference — ListObjectsV2, HeadObject, DeleteObject.
  • SeaweedFS 4.48 — https://github.com/seaweedfs/seaweedfs (wiki и исходники): шлюз S3, учётные записи и политики IAM, weed shell (s3.bucket.create, s3.anonymous.set, fs.ls, fs.rm), ключ подписи WEED_JWT_FILER_SIGNING_KEY, -ip.bind, метрики шлюза.
  • aiobotocore — https://aiobotocore.aio-libs.org/, botocore Config (connect_timeout, read_timeout, retries, max_pool_connections); исходники aiohttp 3.14.5 — resume_reading() и таймер sock_read (причина flake, evidence/s3/idle-connection.md).
  • PNG — https://www.w3.org/TR/png/ (чанки, CRC, IHDR, фильтры строк, Adam7), zlib — RFC 1950 / 1951 и zlib.decompressobj(max_length) Python; JPEG — ITU-T T.81 (маркеры, SOF, длины сегментов).
  • PostgreSQL 18 — https://www.postgresql.org/docs/18/: частичные индексы, CREATE INDEX CONCURRENTLY, SELECT … FOR UPDATE SKIP LOCKED, ALTER TABLE … ADD COLUMN под lock_timeout, NOT VALID ограничения, pg_stat_database.
  • HAProxy 3.4 — https://docs.haproxy.org/: http-request set-timeout, tune.sndbuf.server, tune.rcvbuf.client, http-error, timeout http-request.
  • Linux — cgroup v2 (memory.peak, memory.stat anon / sock, memory.events oom_kill), ip-sysctl (tcp_rmem); glibc mallopt (M_MMAP_THRESHOLD, переменная MALLOC_MMAP_THRESHOLD_).
  • Starlette — Request.stream(); k6 — https://grafana.com/docs/k6/latest/ (constant-vus, constant-arrival-rate).
  • Из лаб 2 и 3 — FastAPI, uvicorn, SQLAlchemy, asyncpg, alembic, argon2-cffi, redis-py, Valkey, Docker Compose (источники перечислены в отчётах этих лаб).

Библиотеки и образы: FastAPI, pydantic, pydantic-settings, structlog, SQLAlchemy, asyncpg, alembic, argon2-cffi, redis-py, aiobotocore, uvicorn (версии — раздел «Запуск из чистого clone»); тесты — pytest, httpx, Pillow; стенд — HAProxy, PostgreSQL, Valkey, SeaweedFS, k6 в закреплённых образах. Проверка изображения — свой код на stdlib (src/utils/image.py), без библиотек декодирования. Сторонний код в репозиторий не копировался.

Использование ИИ. Инструмент — Claude Code, модель Claude Opus 5.5. Работа велась по changes OpenSpec (openspec/changes/archive/, семь changes лабы 4: s3-storage, attachments, upload-consistency, upload-memory, track2-reconciler, fix-upload-put-flake, track2-reconcile-cost). Все семь в архиве, спеки синхронизированы, активных changes нет. Каждый change проходил этапы propose → apply → verify → правки по verify → archive. Каждый этап выполнял отдельный субагент, основная сессия координировала: передавала этапы, проверяла итоги, коммитила на ветке feat/<change> и вливала её в основную, присылала автору прогресс. Все commit после переноса лабы 3 (5d5d8f9) помечены Co-Authored-By: Claude Opus 5.5. Рабочий план лабы (PLAN.md: рубрика → changes, ключевые решения, трек 5, риски, вопросы по ходу changes) удалён после закрытия всех changes. Его итоги перенесены в этот отчёт и в design архивных changes, открытые вопросы — в раздел «Открытые вопросы преподавателю». Последняя версия плана — git show fd03b84:PLAN.md, на неё ссылаются архивные changes и ранние файлы evidence/.

Что делал ИИ:

  • код приложения и уборщика, миграции, docker-compose.yml, haproxy.cfg, infra/s3/bootstrap.sh, скрипты стенда;
  • собственные тесты student-tests/, стенд проверок отказов и его hook;
  • профили uploads и reconcile стенда замеров bench/, сэмплер памяти, сводки и графики;
  • драйвер проверок (driver.py s3-check, attachment-failover, upload-consistency, reconcile-cycle и другие), запуск замеров и проверок, evidence, этот отчёт, правила .claude/rules/ и спеки OpenSpec;
  • CI job application и override стенда для раннера Gitea; схему раннера (job — контейнер рядом со стендом) ИИ установил по журналу публичного прогона на этом Gitea и повторил локально.

Что решал автор:

  • трек 2 «Согласованность двух хранилищ» и SeaweedFS вместо MinIO (2026-10-20); /health/ready без S3 и уборщик — отдельный сервис, а не фоновая задача реплик (2026-10-20);
  • проверка изображения структурная, без полного декодирования; filename отклоняется только по правилу контракта (/, \, NUL и категория Cc), символы направления текста принимаются (2026-10-20);
  • текст из пробелов с вложением — вопрос преподавателю (ответ — «Согласования с преподавателем», 2026-10-20);
  • метку uploads принять с предупреждением о swap хоста (2026-10-22) и после fix-upload-put-flake полную метку не переснимать (2026-10-23);
  • добавить CI job по CONTRIBUTING.md, «CI», и включить Actions в fork (2026-10-29);
  • все замечания каждого verify — в правки, без отдельного согласования; работа в автономном режиме. Решения, принятые основной сессией без автора, отмечены в design changes как принятые без пользователя (например, дописывание недостающих переменных в существующий .env, 2026-10-21; варианты по умолчанию в открытых вопросах преподавателю).

Как проверялось:

  • verify каждого change отдельным субагентом: сверка с задачами, спеками и рубрикой. Найденное правилось, и evidence переснималось с закоммиченного кода. Примеры — гонка уборщика с mark_ready, которая давала ready без объекта (два раунда verify upload-consistency), строка с ключом вне префикса в сверке, неполные вердикты сводки метки сверки;
  • публичные проверки skeleton (make test, make test-persistence, make test-failover) и собственные (make student_test, make failure_checks, make test_isolated, make s3_check) — на итоговом коде каждого change и из чистого clone (evidence/tests/clean-clone-final.md); у новых проверок отказов — красный прогон до кода;
  • гипотезы обоих замеров закоммичены до прогонов, хост проверялся перед каждой меткой. Первая метка uploads (грязное дерево, swap хоста 337 056 страниц) отброшена; принятая снята на чистом дереве, с пометкой о swap 7 464 страниц в одном прогоне (решение автора выше);
  • ошибки ИИ, найденные по ходу, описаны в отчёте как есть:
    • оценка «~1,2 тела на загрузку» до change upload-memory была неверна: на деле ~2,17 тела и OOM при 20 × 10 MiB;
    • первая метка uploads снята на грязном дереве со swap хоста;
    • две попытки метки сверки упали на собственной проверке полноты строк k6;
    • срок чтения aiohttp давал редкие 503 на исправном S3 (fix-upload-put-flake);
    • restart hook (scripts/restart.sh) полагался на то, что up --wait не пересоздаёт работающие контейнеры. Compose 5.4 пересоздаёт их, если образ скачивался при первом up, и make test-persistence на чистой машине падал. Проверка из чистого clone этого не поймала: образы были в кэше. Нашёл CI job на раннере Gitea, исправлено --no-recreate (evidence/tests/ci-application.md).

Утверждения отчёта о поведении стенда подтверждены командами, их выводы лежат в evidence/. Решения, перечисленные выше, принимал автор.