Files
mtusi2026lab4/REPORT.md
T
ricoromaandClaude Opus 5.5 f2dc0b368a docs: add upload-consistency evidence and report
- evidence: consistency (driver upload-consistency), cleaner process,
  cleaner S3 key, pending index plan on the working database
- re-run failure_checks (29/29), student_test via LB and test_isolated
  with the cleaner and storage-consistency coverage
- REPORT: database and S3 consistency, compensation table, grace period
  rationale, "PUT succeeded, COMMIT did not" answer, level 4 rows,
  limitations; PLAN stage 3 and AGENTS evidence map

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-21 06:32:48 +03:00

70 KiB
Raw Blame History

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

  • Автор, группа: TODO
  • Целевая оценка; выбранный трек 5, если нужен: TODO
  • Commit/PR: TODO после публикации
  • Использованные источники, библиотеки и помощь ИИ: TODO

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

TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.

S3 (change s3-storage)

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.

  • make stop останавливает S3 плавно, ~15 с. make down volumes не трогает.

  • make wipe_data удаляет volumes mtusi-lab4_postgres_data и mtusi-lab4_s3_data только после ввода yes, оба тома запрос называет по имени.

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

TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab3, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.

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

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

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

Сервер — SeaweedFS 4.48. Выбор и проба — PLAN.md (решение 1) и 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.

Соответствие имён 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) и каждую убирает своей транзакцией:

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

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

Зачем блокировка. Загрузка короче grace, но процесс API, замороженный дольше grace (docker pause, пауза ВМ), после разморозки дойдёт до mark_ready. Без блокировки порядок «PUT → уборщик удалил объект → mark_ready сделал строку ready» дал бы ready без объекта (201 клиенту, 500 при скачивании). С блокировкой mark_ready ждёт commit уборщика и находит 0 строк → компенсация и 503; если mark_ready успел раньше, строка уже ready, и уборщик её не выбирает. Транзакция уборщика держит строку на время DELETE в S3 (≤ 5 с) — в своём пуле из одного соединения; [s3] timeout_seconds 5 < request_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 — не основание удалять) и оставлено для глубокой сверки трека 2.

Отказы хранилищ в уборщике. S3 недоступен, не ответил, отказал в доступе или bucket нет — транзакция строки откатывается, проход прерывается на первой строке (warning), следующий — через интервал. PostgreSQL недоступен — проход пропускается (warning). Непредвиденная ошибка — error с traceback, процесс живёт. Перезапуск не нужен: у клиента S3 нет повторов, пул PostgreSQL — с pool_pre_ping (test_cleaner_survives_outages). SIGTERM: текущая строка доводится, выход с кодом 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.

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

Дата Договорённость Где учтено
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

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

  • Почему файл в 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 с) удалит объект и строку;
    • процесс API убит между PUT и COMMIT — то же: строка pending и объект, уборщик убирает оба после grace (test_killed_between_put_and_ready).

    Уборщик удаляет объект раньше строки и под FOR UPDATE SKIP LOCKED, поэтому загрузка, пережившая grace, и уборщик не дают ready без объекта. Остаток риска назван в «Ограничениях»: процесс API заморожен дольше grace посреди самого PUT, уборщик убрал строку, а S3 принял тело после разморозки — объект без строки, его находит только сверка bucket и БД (трек 2).

  • Почему случайный 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; с него же переснято make student_test через LB, make failure_checks и make test_isolated (evidence/tests/).

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke make test (через LB и в make test_isolated) PASS: lab4 public API scenario — загрузка fixture, сообщение с attachment_ids, SHA-256 скачанного оригинала, 404 постороннему evidence/attachments/smoke.md, evidence/tests/test-isolated-s3-cleanup.md (раздел 0)
«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 — оба контейнера evidence/failover/test-failover.md
«4»: тесты большого файла, повреждённого изображения, подмены MIME, чужого attachment_id, вложения другого чата; ошибка клиента не 500 make student_test через LB (test_rubric.py: пять сценариев лабы 4), make test_isolated 197 passed через LB, 192 passed + 5 пропусков тестов реплик в одном процессе (оба — 5b42bd2); каждая ошибка — 4xx в формате контракта; сверка покрытия: 212 сценариев 13 спеков, 197 тестами (33 — проверками отказов), 15 исключений evidence/tests/student-test-lb.md, evidence/tests/test-isolated-s3-cleanup.md
«4»: отказы S3 на путях вложений, отклонённая загрузка ничего не оставляет make failure_checks 29 / 29, код 0 (5b42bd2): 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, после — ни того, ни другого; во всех — объектов без строки 0 (object-ids − attachment-ids); красный прогон до кода — 4 из 11 упали 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»: отдельные ограниченные 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 — upload-memory evidence/s3/memory.md
Логи без секретов S3 grep -F значений секретов по журналу клиента и make run_dev 0 совпадений; отказ в учётных данных — одна запись error без секрета evidence/s3/client.md
Остальные пункты уровня 4 TODO (upload-memory: лимиты и таймауты загрузки, ≥10 одновременных загрузок и пик памяти) TODO TODO
Выбранный трек 5, если заявлен TODO TODO TODO

TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.

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

TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
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) —

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

TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.

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 одновременных загрузок по 10 MiB заканчиваются через 7,2 с, это больше срока вызова клиента (5 с). Подбор лимитов и сроков — change upload-memory.
  • Отказ S3 — 503 на путях вложений, а не отказ сервиса. Отказ хоста, LB и PostgreSQL стенд не переживает (.claude/rules/balancer.md).

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

  • Проверка изображения структурная. Обрезанный файл, битая CRC, сломанные маркеры, поток zlib не того объёма и «бомба» — 415. Но байт, изменённый внутри сжатых данных скана JPEG, не ловится: у формата нет контрольной суммы, Pillow его тоже не ловит. Полное декодирование — worker лабы 5.
  • Память загрузки ~1,2 тела, без лимита одновременных загрузок. Одно тело и блоки чтения botocore (порог mmap glibc закреплён в образе, без него вторая загрузка на миг держала два тела). Около 30 одновременных загрузок по 10 MiB (~12,5 МБ каждая сверх ~120 МБ базы) доведут реплику 512 МБ до OOM. Лимит, сроки чтения тела и замер под конкуренцией — change upload-memory.
  • Ограничение текста сообщения 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 кончился ошибкой по сроку, компенсации нет — объект остаётся без строки. Вероятность мала (запас ×50, заморозка посреди PUT), такой объект находит только сверка bucket и БД (трек 2). ready без объекта при этом не возникает: mark_ready и уборщик упорядочены блокировкой строки.
  • Проверка grace — по настройкам уборщика. config.toml у API и уборщика общий, но подмена сроков окружением только у API (DATABASE__REQUEST_TIMEOUT_SECONDS, S3__TIMEOUT_SECONDS) обошла бы проверку. Если появится ожидание между pending и ready (очередь загрузок upload-memory), граница и проверка расширяются в том же change.
  • Незавершённые загрузки живут до ~16 мин (grace 900 с + интервал + проход): они не видны по API и занимают место в bucket.
  • Вложения ready без ссылок из сообщений уборщик не трогает: это учтённые вложения (строка и объект есть), контракт срока им не задаёт. Сюда же попадает загрузка, у которой клиент оборвал соединение уже после тела: uvicorn задачу не отменяет, вложение становится ready, а 201 до клиента не доходит.
  • Компенсация добавляет до 5 с к ответу 503, если S3 стал медленным после удачного PUT (срок DELETE). Худший путь загрузки и так длиннее timeout server HAProxy; пересмотр цепочки — upload-memory.
  • Пустые каталоги <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 дописывает только отсутствующие переменные: пустое или устаревшее значение уже существующей строки он не меняет — его правят руками.