Files
mtusi2026lab4/PLAN.md
T

137 KiB
Raw Blame History

План лабы 4 на «5»

Рабочий документ на время лабы (составлен 2026-10-20). Пункты закрываются changes OpenSpec по порядку из раздела «Последовательность работ»; решение, принятое в design change, важнее этого плана. Когда change заархивирован, его строку здесь отметить; когда закрыты все — итоги перенести в REPORT.md, а файл удалить.

Задание — README.md, переходы API — COURSE.md, семантика — contracts/README.md, раздел «Вложения (с lab4)». Код пока в состоянии лабы 3 (commit 5d5d8f9, «carry lab 3 over»): S3 и вложений нет. Поэтому по коду, без запуска:

  • публичный smoke (LAB=4) упадёт на загрузке вложения;
  • make student_test красный на test_exclusion_evidence_exists: файлов evidence исключений сверки ещё нет (AGENTS.md, «Переход в следующую лабу»).

Оба пункта закрывает change attachments.

Что требует рубрика и чем закрываем

Уровень Пункт рубрики Как закрываем Change
3 S3 в общем стенде, persistent volume, закреплённая версия, создание приватного bucket описано сервис S3 в docker-compose.yml, одноразовый bootstrap как migrate s3-storage
3 метаданные в PostgreSQL, байты в приватном bucket, не в БД и не в локальном каталоге API таблица вложений, ключ объекта назначает сервер attachments
3 POST вложения → 201 ready после сохранения, побайтный download, attachment_ids в сообщении, smoke с checksum и 404 постороннему ручки upload / метаданные / content, поле сообщения, история attachments
3 реальные PNG/JPEG ≤ 10 MiB и ≤ 40 млн пикселей, MIME по содержимому, опасный filename отклонён, лимиты до неограниченного чтения и декодирования Content-Length до чтения, потоковое чтение со счётчиком, сигнатура по байтам, размеры из заголовка до декодирования attachments
3 upload → остановка обслужившей реплики → download через другую тот же файл; restart с volumes сохраняет метаданные и оригинал make test-persistence, make test-failover и свой сценарий: остановить реплику по X-Instance-Id загрузки attachments
3 (п. 5 «Что сделать») недоступность S3, чужой чат, restart всего стенда 503 вместо 500 при отказе S3, текстовые сообщения работают; тесты отказов attachments, upload-consistency
4 тесты: большой файл, повреждённое изображение, подмена MIME, чужое attachment_id, вложение другого чата; пользовательская ошибка не 500 student-tests/test_attachments.py attachments
4 прерванная загрузка и отказ между S3 и БД не оставляют вечных неучтённых объектов; механизм компенсации / очистки с grace period описан строка-намерение до PUT, компенсация, уборщик зависших намерений upload-consistency
4 лимиты, таймауты и потоковая обработка ограничивают RAM; ≥ 10 одновременных загрузок с замером пика памяти лимит одновременных загрузок на реплику, профиль uploads стенда bench/ upload-memory
4 bootstrap идемпотентен; у API отдельные S3 credentials с ограниченными правами; консоль не в общей сети; проверка приватности bucket вне API bootstrap дважды, пользователь API только на объекты bucket, анонимный GET / LIST → 403 s3-storage
5 трек 2 «Согласованность двух хранилищ» раздел «Трек 5» ниже track2-reconciler, track2-reconcile-cost

Сценарий защиты (README): п. 1 — smoke и команда драйвера; п. 2 — 404 постороннему и анонимный GET в S3 (s3-storage); п. 3 — test-persistence и test-failover; п. 4 — нет локального файла оригинала на API, отказы и эксперименты.

Ключевые решения

Ниже предложения. Окончательное решение принимается в design соответствующего change.

1. S3-сервер: SeaweedFS, не MinIO — подтверждено 2026-10-20

README разрешает любой из трёх: MinIO, SeaweedFS, RustFS. MinIO — самый известный вариант, но закрепить его образ из чистого clone сейчас нельзя. Проверено 2026-10-20:

  • docker buildx imagetools inspect minio/minio:latest и minio/mc:latest — «pull access denied, repository does not exist»; API Docker Hub на minio/minio отвечает 404;
  • quay.io/minio/minio — 401 без авторизации;
  • для сравнения chrislusf/seaweedfs и rustfs/rustfs:1.0.3 разрешаются, у обоих свежие теги (2026-10-17…20).

По публичным источникам (блоги, не объявления MinIO): сборки образов community edition прекращены в октябре 2025, с декабря 2025 — maintenance mode, в 2026 репозиторий архивирован; исправление CVE-2025-62506 в образ не попало. Варианты оставить MinIO и их цена:

Вариант Чем плох
старый закреплённый образ из чистого clone не скачивается — рубрика «3» (стенд из репозитория) не выполняется
сборка из исходников архивного репозитория свой Dockerfile с Go-сборкой, исправлений дальше не будет
форк pgsty/minio сторонний проект, доверие и сопровождение надо проверять

Сравнение оставшихся:

SeaweedFS RustFS
Зрелость с 2015 года, образы публикуются ежедневно проект моложе, открыт в 2025
Bootstrap bucket и пользователя weed shell (s3.bucket.create, s3.configure) из того же закреплённого образа admin API в стиле MinIO: нужен mc (образ недоступен, см. выше) или свой код подписи
Права пользователя API действия Read / Write / List / Admin на bucket IAM-политики в формате AWS, тоньше (s3:PutObject без s3:DeleteObject)
Консоль / UI master, filer, volume, admin UI — не публикуются консоль на отдельном порту — не публикуется или выключается

Предложение — SeaweedFS: один процесс weed server -s3 с volume, bootstrap одноразовым сервисом на том же образе. В design s3-storage — короткая проверка на стенде до выбора: идемпотентность создания bucket, запрет анонимного доступа, права пользователя API, healthcheck, переживание рестарта. Если SeaweedFS провалит проверку — RustFS. В .claude/rules/settings.md MinIO упомянут только примером секрета, правило обновляется в том же change.

2. Запись вложения: намерение → объект → готово

  • Порядок upload: проверки до чтения → потоковое чтение и проверка содержимого → строка-намерение pending с ключом объекта (commit) → PUT в S3 → строка ready (commit) → 201.
  • Ключ объекта — серверный (uuid), filename только для показа: ни путь, ни ключ из него не строятся.
  • Любой объект в bucket, загруженный API, известен БД до PUT. Сбой после PUT и до второго commit оставляет pending, а не неучтённый объект: его убирает уборщик после grace period (upload-consistency). Объект без строки возможен только мимо API — это класс расхождений трека 2.
  • Ответ на вопрос защиты «PUT прошёл, COMMIT нет» — отсюда.
  • pending во внешний API не попадает: контракт лабы 4 знает только ready; GET такого вложения — 404.

3. /health/ready без S3 — подтверждено 2026-10-20

Отказ S3 не выводит реплики из LB: вложения отвечают 503 unavailable, текстовые сообщения и история работают. Если включить S3 в готовность, его заминка разом выключит все реплики, включая текстовый путь (та же логика, что у таймаута готовности PostgreSQL, balancer.md). Решение и список критичных зависимостей — в REPORT.md (контракт: «Какие зависимости критичны, зафиксируйте в отчёте»).

4. Память загрузки

  • Тело ≤ 10 MiB: Content-Length больше лимита — 413 до чтения; без Content-Length — счётчик при чтении, обрыв на 10 MiB + 1.
  • Сигнатура PNG / JPEG по первым байтам; размеры из заголовка до декодирования, больше 40 млн пикселей — 413.
  • Главный риск — не байты, а декодирование: 40 млн пикселей RGB — около 120 МБ на одну загрузку при лимите реплики 512 МБ. Варианты для design attachments: проверка целостности без полного декодирования (PNG — CRC чанков и потоковая распаковка IDAT со счётчиком строк; JPEG — структура маркеров), полное декодирование под семафором, draft для JPEG. Цена каждого — в upload-memory.
  • Лимит одновременных загрузок на реплику и сроки чтения тела (HAProxy и API). timeout server LB 10 с рассчитан на запрос к БД, а не на медленную передачу 10 MiB — цепочку таймаутов пересмотреть для пути upload.

5. Учётные данные S3

  • root — только bootstrap; API и уборщик его не получают.
  • Пользователь API — объекты своего bucket: чтение, запись, удаление (компенсация). Без List и Admin.
  • Уборщик / reconciler — свой пользователь: List, чтение, удаление.
  • Пароли — .env (make env_setup генерирует, как Postgres и Valkey), в приложение — мостами S3__*. Соответствие имён skeleton (S3_ENDPOINT, S3_REGION, S3_BUCKET, S3_ACCESS_KEY_ID_FILE, S3_SECRET_ACCESS_KEY_FILE, MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS) — в REPORT.md, как в лабе 3.
  • API-порт S3 — только 127.0.0.1 (console-режим make run_dev), как Postgres и Valkey; UI и консоль не публикуются вообще.

6. Идемпотентность с attachment_ids

message_request_hash начинает учитывать attachment_ids. Пустой список не должен менять хэш: иначе ключ, сохранённый версией без вложений, после make rolling_update давал бы 409 на повтор того же тела. Порядок элементов массива значим (это JSON-массив), порядок ключей объекта — нет (контракт).

7. Уборщик — отдельный сервис (подтверждено 2026-10-20)

Фоновая работа в API-репликах запрещена до worker лабы 5 (AGENTS.md, «Архитектура в двух словах»). Уборщик зависших pending — отдельный сервис compose на образе API со своей командой и своими S3-правами, интервал и grace period в настройках. Отвергнута цель Makefile без расписания: с ней «вечных» объектов нет только при регулярном ручном запуске. В треке 2 уборщик вырастает в reconciler.

Трек 5: трек 2 «Согласованность двух хранилищ» (подтверждено 2026-10-20)

Почему трек 2.

  • Продолжает обязательный пункт «4» (компенсация и очистка): общий код, общие тесты отказов.
  • Контракт не расширяется, S3 остаётся во внутренней сети.
  • Замеры ложатся на готовый bench/ (наполнение, паспорт, сэмплер, summary.md), как трек 2 лабы 2.
  • Пригодится в лабе 5: staging-prefix, хвосты worker при доставке at least once.

Почему не трек 1 (presigned upload).

  • S3 должен быть доступен клиенту: подпись под внешний адрес, шире поверхность атаки.
  • Новые ручки init / complete в contracts/extensions.openapi.json.
  • Лимит размера (POST policy content-length-range) и checksum при complete на SeaweedFS / RustFS не проверены; без них complete читает объект обратно, и выигрыш по трафику API тает.
  • В лабе 5 загрузка становится асинхронной (202) — flow переделывать.

Гипотезы (до прогонов коммитятся отдельно)

  1. Линейность. Время обхода растёт линейно по числу объектов, цена на объект от N почти не зависит.
  2. Батч против точечной сверки. Сверка страницы LIST (до 1000 ключей) одним запросом к БД (object_key = ANY(...)) дешевле HEAD на каждую строку: запросов N/1000 против N.
  3. Поверхностная против глубокой. Размер из LIST почти бесплатен; SHA-256 требует прочитать каждый объект и упирается в чтение S3 — глубокая сверка выборочная или по требованию.
  4. Влияние на рабочий трафик. Обход с ограниченной скоростью ухудшает p95 фоновой нагрузки API не больше порога, заданного до прогона.
  5. Безопасность. Ни одно подтверждённое и ни одно используемое в сообщениях вложение не удаляется при любой гонке с загрузками.

Методика (предварительно)

  • Стенд mtusi-bench с S3 и лимитами из паспорта. N = 10k и 100k объектов; наполнение мимо API (SQL и прямой PUT), граница описана.
  • Внесённые расхождения, по доле каждого класса: объект без строки, зависший pending, строка ready без объекта, другой размер.
  • Метрики: время по фазам, запросы S3 и PostgreSQL, CPU / RAM reconciler, S3 и PostgreSQL (сэмплер), p95 фоновой нагрузки k6.
  • 3 повтора, A/A для отделения эффекта от шума (make bench_compare или его аналог для профиля).

Ограничения, которые заранее назвать

  • Генератор, API, S3 и БД на одном хосте, Docker Desktop — VM.
  • Одна нода S3, без репликации: отказ диска или хоста не переживается.
  • Строку без объекта не восстановить: байтов нет нигде. Reconciler её находит и помечает, но не «чинит».

Последовательность работ

Этапы 1–6 — changes OpenSpec, каждый проходит /opsx:propose → /opsx:apply → /opsx:verify → /opsx:archive. Этап 7 — сборка отчёта, не change. Замеры для отчёта снимаются с закоммиченного кода (bench.md, «Измеренное состояние — commit»). Отчёт пополняется в каждом change: evidence и строка в таблице доказательств REPORT.md — часть «готово». Возможности лаб 2 и 3 (bench_restore, профили failover и rollout, серии трека 1, проверки отказов) работают после каждого change.

Сводная таблица

№ Change Уровень Что происходит Готово, когда
0 — (подготовка) — этот план; выбор трека и S3-сервера план сохранён 2026-10-20; трек 2, SeaweedFS, решения 3 и 7 подтверждены 2026-10-20
1 s3-storage 3 (+4: bootstrap, права, консоль, приватность) S3 в стенде, bootstrap, клиент в src/infra/s3/, настройки, все стенды знают о S3 bootstrap дважды без ошибок, анонимный GET / LIST → 403, ключ API не может admin-операций, make test-persistence перезапускает и S3; заархивирован 2026-10-20 — openspec/changes/archive/2026-10-20-s3-storage/
2 attachments 3 (+4: тесты) миграция, домен attachment, ручки, attachment_ids в сообщениях, тесты зелёные make test, test-persistence, test-failover, свой сценарий отказа загрузившей реплики; негативные тесты; evidence исключений переснят; код — 116d8d3, гонка bench_restore — d56b892; evidence 2026-10-20 с d56b892: evidence/attachments/, исключения, evidence/tests/ (196 / 191 + 5 пропусков / 23 из 23), test-failover для обеих реплик; правки verify — dba40bc, после них student_test 197 и failure_checks 24 из 24, bench_rollout attachments переснят с e1f8531 на чистом дереве (8,67 с, ошибок 0, 12 001 = 12 001); заархивирован 2026-10-21 — openspec/changes/archive/2026-10-21-attachments/
3 upload-consistency 4 намерение до PUT, компенсация, уборщик с grace period, тесты отказов make failure_checks с отказами S3 и БД посреди загрузки: нет 500, нет неучтённых объектов старше grace period; код — 5b42bd2; evidence 2026-10-21 с него: evidence/attachments/consistency.md и cleaner-process.md, evidence/s3/cleaner-key.md, evidence/migrations/pending-index.md, evidence/tests/; REPORT.md — раздел «Согласованность БД и S3», ответ на вопрос «PUT прошёл, COMMIT нет», строки уровня «4». Правки по verify (W1–W4, S1) — код 87c48b9: пометка строки уборщиком до удаления объекта, тесты неизвестного COMMIT, загрузки дольше grace и сбоя уборки после удаления объекта; evidence 2026-10-21 с него: evidence/tests/ (failure_checks 32 из 32, student_test 197, сверка 215 / 36, test_isolated 192 + 5 пропусков), cleaner-process.md раздел 7 (отказ S3 во время прохода); REPORT.md — пометка, остаточный риск и окно rolling_update. Правки по повторному verify (W1, S1, S2) — код 5889ca2: уборщик в два шага, объект и строка одной транзакцией под блокировкой, смеси версий не хуже, чем до правки, порядок обновления; evidence 2026-10-21 с него: evidence/tests/failure-checks.md (32 из 32 за 228 с), cleaner-process.md раздел 7, S2 в student-test-lb.md (8 сценариев storage-consistency); REPORT.md — два шага, «Зачем DELETE объекта под блокировкой», смесь версий; заархивирован 2026-10-21 — openspec/changes/archive/2026-10-21-upload-consistency/
4 upload-memory 4 лимит загрузок на реплику, сроки тела, профиль uploads замер ≥ 10 одновременных загрузок: пик памяти ограничен, механизм объяснён; код — 6cab9d3 (места загрузки, срок тела, одна копия тела при PUT, буферы и сроки LB) и 97a4be4 (буфер приёма LB от клиента 128 KiB); метка evidence/uploads/baseline/ с 97a4be4 (commit ce1ae2c, принята с пометкой о swap хоста); evidence 2026-10-22: evidence/uploads/lb-timeouts.md и rollout-upload.md, evidence/tests/ (student_test 198, test_isolated 193 + 5 пропусков); REPORT.md — «Память и сроки загрузки», гипотезы H1–H4 и выводы по метке. Правки по verify — код 9d2ee30: разбор сводки профиля, спеки буфера LB и одной копии тела, срок тела «узкого» API 3 с; evidence с него: evidence/tests/failure-checks.md (37 из 37 за 263 с, commit 569a164); заархивирован 2026-10-22 — openspec/changes/archive/2026-10-22-upload-memory/
5 track2-reconciler 5 reconciler: dry-run / apply, классы расхождений, внедрение ошибок, доказательство безопасности ошибки внесены с обеих сторон, обнаружены, исправлены; повторный запуск находит 0; под загрузками ничего подтверждённого не удалено; код — c1648d9 (сверка в процессе уборщика, make reconcile, плановая сверка, lost_at и 404 потерянного оригинала, список по префиксу у ключа уборщика); evidence 2026-10-22 с него: evidence/reconcile/cycle.md (6 классов с обеих сторон, повтор 0, возврат оригинала), stress.md (640 / 640 с тем же SHA-256 под --apply), service.md, evidence/s3/cleaner-list.md (70 проверок), evidence/migrations/lost-at.md, evidence/tests/ (failure_checks 45 из 45 за 462 с и красный прогон 8 из 8 на c13df14, student_test 198, test_isolated 193 + 5 пропусков); REPORT.md — «Сверка хранилищ», строки уровня «5», ограничения, ответ «PUT прошёл, COMMIT нет». Правки по verify — код 84f8c35: строка с ключом вне префикса вложений — чужой объект, сигнал перед каждым вызовом хранилища, hook set-key, три новые проверки отказов; evidence 2026-10-22 с него (commit 96d2ecc): evidence/tests/failure-checks.md (48 из 48 за 524 с и красные прогоны группы 13), student-test-lb.md (198), evidence/reconcile/service.md (reconcile-signal); вопрос 1 преподавателю (ответ API на потерянный оригинал) открыт; заархивирован 2026-10-22 — openspec/changes/archive/2026-10-22-track2-reconciler/
5а fix-upload-put-flake 4 (исправление) причина редких 503 на загрузке (срок чтения aiohttp портил соединение пула S3), правка клиента, тест на стенде отказов, driver.py s3-idle тест красный до правки и зелёный после, s3-idle у образа без порчи, восемь student_test подряд без 503; тест — 4cfaab0, правка — b5983f0; evidence 2026-10-22 с b5983f0: evidence/s3/idle-connection.md (s3-idle до и после замены реплик, механизм, проба памяти PUT 1,17 тела, bench_uploads_quick), evidence/tests/failure-checks.md (49 из 49 за 570 с, красный 3 из 3 на 4cfaab0), student-test-lb.md (8 × 198); запись KNOWN_ISSUES.md удалена; полную метку uploads не переснимать (пользователь, 2026-10-23)
6 track2-reconcile-cost 5 гипотезы, профиль стоимости обхода, стратегии, графики метки в evidence/, выводы по гипотезам и ограничения в REPORT.md; код — 8d4cf7e (--strategy head, --deep и класс «другой SHA-256», снятие пометки по SHA-256, предел скорости [reconciler] max_objects_per_second 2000, ранний отказ по пределу, стоимость в итоге, профиль reconcile стенда bench/); гипотезы H1–H4 и ожидание S4 — aaf3fa3, до метки; правки проверки строк k6 — a42dd27, d8b8ae3; метка evidence/reconcile/baseline/ — 0072dbe (с d8b8ae3, 51 проход, dirty: false, хост чистый): H1, H2, H3 и S4 подтверждены, H4 не проверена (контраст r 1,08 при пороге > 1,5); evidence 2026-10-23 с 0072dbe: evidence/tests/failure-checks.md (54 из 54 за 712 с и красный прогон 5 из 5 на 7f4e626), evidence/reconcile/service.md (reconcile-signal --pace: код 1 за 0,2 с), make test_isolated, make student_test 198; REPORT.md — «Стоимость сверки: результаты метки baseline», «Сверка хранилищ», строки уровня «5», ограничения
7 — (отчёт и PR) 3–5 сводка REPORT.md, чистый clone, шаблон PR, уборка этого файла PR ЛР 4 — БВТ2301 — Сафронов — на 5

1. s3-storage — уровень 3, +4

Пункты рубрики.

  • «3»: S3 в общем стенде, persistent volume, закреплённая версия, создание приватного bucket описано.
  • «4»: bootstrap идемпотентен; отдельные credentials API с ограниченными правами; консоль не в общей сети; проверка приватности вне API.

Стенд.

  • Сервис S3: тег с версией и digest индекса (docker.md), named volume, healthcheck, лимиты CPU / RAM, restart: unless-stopped.
  • Одноразовый bootstrap (как migrate): bucket, запрет анонимного доступа, пользователи API и уборщика. Реплики ждут его service_completed_successfully.
  • Окружение по сервисам: root — только bootstrap; ключи API — только api; LB и migrate S3-секретов не получают.
  • .env.example, make env_setup (генерация паролей S3), строки в config_example.toml.
  • scripts/restart.sh перезапускает и S3; стенды bench/ (bench.compose.yml), make test_isolated (свой bucket или prefix по имени базы, как ключи Valkey) и make failure_checks (свой S3) знают о новом сервисе.

Код.

  • src/infra/s3/: фабрика клиента и глобал по образцу cache/instance.py, срок на каждый вызов, ошибки → доменные исключения (отказ → 503). Библиотека — решение design: aiobotocore (асинхронный, тянет закреплённый botocore) или boto3 в потоке.
  • Секция [s3] в Settings, мосты S3__*.
  • /health/ready — по решению 3.

Спеки (дельты). Новая object-storage (bucket, приватность, права, bootstrap); container-run (S3 в стенде, restart hook); service-configuration ([s3]); health (S3 не критичен для готовности); service-logging (ключи и подписи не логируются).

Правила. S3 — в infra.md, docker.md, settings.md; AGENTS.md (карта кода, таблица команд).

Evidence: evidence/s3/ — bootstrap дважды, анонимные GET и LIST → 403, ключ API против admin-операций и чужого bucket, docker compose ps без опубликованных UI-портов, test-persistence с рестартом S3.

2. attachments — уровень 3, +4 (тесты)

Пункты рубрики. Все пункты «3» о вложениях; «4» — негативные тесты.

Код.

  • Миграция: таблица вложений (чат, владелец, filename, content_type, размер, SHA-256, ключ объекта, статус, время) и связь сообщения с вложениями с порядком. Только расширение схемы (migrations.md).
  • Ручки: POST /chats/{chat_id}/attachments?filename=…, GET /attachments/{id}, GET /attachments/{id}/content (поток из S3, истинный Content-Type, без redirect, variant только original).
  • Проверки upload по решению 4; ошибки: 400 (filename, UUID), 413 (байты, пиксели), 415 (формат, повреждение, подмена MIME), 404 (чужой чат), 503 (S3).
  • Сообщения: attachment_ids 0–10 уникальных UuidIn, пустой текст с вложением, чужое / неизвестное / другого чата → 404; история и повтор отдают attachment_ids; хэш — решение 6.
  • Драйвер скилла run-mtusi-messenger: upload / download / SHA-256 и сценарий «остановить реплику, принявшую файл».

Тесты (student-tests/test_attachments.py, маркеры spec): PNG и JPEG; 413 по байтам и по пикселям (маленький файл с огромными размерами в заголовке); 415 на обрезанный файл, на текст с image/png, на JPEG с image/png; filename с /, \, NUL, управляющими символами — 400; чужое и неизвестное attachment_id, вложение другого чата — 404; посторонний — 404 на метаданные и content; ни одна ошибка не 500; идемпотентность с attachment_ids. Большие и «бомбы» генерируются в тесте, в git не кладутся (README fixtures).

Свой сценарий отказа. Публичный make test-failover останавливает реплику, ответившую на первое сообщение, а не на upload. Рубрика требует остановить именно принявшую файл: upload через LB → stop-one.sh по её X-Instance-Id → download через другую → тот же SHA-256.

Переход в лабу 4. Переснять четыре файла исключений сверки на стенде лабы 4: evidence/cache/hits.md, evidence/auth/passwords-and-tokens.md, evidence/replicas/test-persistence.md, evidence/idempotency/replay-after-restart.md.

Спеки (дельты). Новая attachments; messages (attachment_ids, пустой текст); idempotency (хэш); data-storage (байты в S3); student-tests.

Evidence: evidence/attachments/ (smoke, download другим участником, 404 постороннему, отказ загрузившей реплики), evidence/tests/.

3. upload-consistency — уровень 4

Пункт рубрики. Прерывание загрузки и отказ между S3 и БД не оставляют вечных неучтённых объектов; механизм с grace period описан.

Код.

  • Намерение до PUT (решение 2), компенсация при ошибке после PUT (удаление объекта, без гарантии — её даёт уборщик).
  • Уборщик (решение 7): pending старше grace period → DELETE объекта (идемпотентно, отсутствие — не ошибка) → удаление строки. Grace period больше максимального времени загрузки с запасом на часы; значения — настройки.

Тесты отказов (make failure_checks, новые действия fault_hook.py): S3 остановлен и заморожен до и во время PUT; отказ вставки строки после PUT (триггер, как fail-messages); kill реплики посреди загрузки; обрыв клиента посреди тела. Итог каждого: нет 500, pending убран уборщиком после grace period, объектов без строки нет. Ещё — невидимость pending через API (замечание verify attachments, S6; спек attachments, «Порядок записи»): действие hook с id последней строки pending (после «Запись в S3 не удалась»), по нему метаданные, байты и сообщение со ссылкой — 404 до уборки.

Спеки (дельты). attachments (сбои загрузки), новая или в object-storage — уборка.

Evidence: evidence/attachments/consistency.md, вывод make failure_checks; раздел REPORT.md с порядком записи.

4. upload-memory — уровень 4

Пункт рубрики. Лимиты, таймауты и потоковая обработка не дают одной загрузке занять неограниченную RAM; эксперимент ≥ 10 одновременных загрузок с замером пика памяти.

Код и стенд.

  • Лимит одновременных загрузок / декодирований на реплику; что видит клиент при превышении — решение design (ожидание с таймаутом или ответ с Retry-After).
  • Сроки чтения тела в API и HAProxy, цепочка таймаутов для upload (решение 4).
  • Профиль uploads стенда bench/: 1 / 10 / 20 / 40 одновременных загрузок по 1 и 10 MiB, memory.peak cgroup реплики и сэмплер, p95, ошибки по кодам. Варианты «без лимита» и «с лимитом».

Гипотеза. Пик памяти реплики ≈ база + K × (буфер тела + декодирование), где K — лимит одновременных загрузок; без лимита пик растёт с конкуренцией до OOM-kill.

Evidence: evidence/uploads/<метка>/, выводы и ограничения в REPORT.md.

5. track2-reconciler — уровень 5, трек 2

Пункт рубрики. Повторяемый reconciler для orphan / missing объектов и метаданных; ошибки на обеих сторонах; обнаружение и безопасное исправление с dry-run и повторным запуском; свежие и используемые вложения не удаляются.

Код.

  • Обход LIST bucket и БД (keyset), классы: объект без строки, зависший pending, строка ready без объекта, другой размер.
  • Режимы --dry-run (отчёт: класс, ключ, возраст) и --apply; повторный запуск после прерванного apply доводит работу, следующий находит 0.
  • Безопасность: grace period по времени объекта и строки; перепроверка строки в БД непосредственно перед удалением объекта; объекты, на которые ссылаются сообщения, не удаляются никогда.
  • Строка без объекта — что видит API (решение design: метка в БД, ответ content), байты не восстановить.

Внедрение ошибок (fault_hook.py): объект в bucket мимо API, удалённый объект, удалённая или изменённая строка, обрыв загрузки посередине.

Доказательство безопасности. Reconciler --apply под одновременными загрузками и отправками; затем каждое подтверждённое вложение скачивается с тем же SHA-256.

Evidence: evidence/reconcile/ — dry-run, apply, повтор = 0, стресс.

6. track2-reconcile-cost — уровень 5, трек 2

Пункт рубрики. Гипотеза, повторяемая методика, результаты и ограничения; измерить стоимость обхода.

Стенд bench/. Профиль reconcile по методике раздела «Трек 5»: наполнение N объектов с долей расхождений, стратегии (батч против HEAD, поверхностная против глубокой), фоновая нагрузка k6, сэмплер, 3 повтора и A/A.

Evidence: evidence/reconcile/<метка>/, графики (make bench_plots или его аналог), выводы по гипотезам 1–5 и ограничения в REPORT.md.

Передано из verify track2-reconciler (замечание S4). При массовом расхождении (N ≫ max_changes) --apply перепроверяет каждого кандидата (SELECT + HEAD) и только потом отказывает по пределу; плановый проход всё это время держит уборку зависших. Ранний отказ ломал бы инварианты отчёта (каждое расхождение названо, ошибка называет число изменений), поэтому там не сделан (design track2-reconciler, «Уточнения apply», п. 21). Здесь — замер цены отказа при N = 1k / 10k расхождений и выбор: перепроверка после решения о пределе с отчётом о неперепроверенных кандидатах, отдельный счётчик в итоге или ранний отказ только у плановой сверки.

7. Отчёт и PR

  • REPORT.md: запуск из чистого clone, архитектура и транзакционные границы, соответствие переменных skeleton, таблица доказательств, эксперименты, ответы на вопросы защиты, согласования с преподавателем, ИИ и источники.
  • Проверка из чистого clone, make check, make test на собранном образе, шаблон PR. Этот файл удаляется.

Риски

  • Декодирование больших изображений в лимите памяти реплики (решение 4) — главный технический риск лабы.
  • Совместимость выбранного S3-сервера: идемпотентный bootstrap, права, поведение при рестарте. Проверяется до выбора в design s3-storage.
  • Медленная загрузка 10 MiB против цепочки таймаутов лабы 3 (timeout server, timeout client, срок запроса к БД).
  • Доказательство «ничего свежего не удалено» требует настоящих гонок, а не последовательного сценария.
  • Объём bench/: новые профили uploads и reconcile не должны ломать прежние (bench_restore, failover, rollout, серии).

Вопросы и решения по ходу changes

Файл вопросов цикла OpenSpec: на каждый change — раздел ### <change> с подразделами «Решения» (принятые без пользователя, со ссылкой на design) и «Вопросы» (ждут ответа; ответ дописывается рядом с датой). При удалении плана открытые вопросы переносятся в REPORT.md.

s3-storage

Решения

Приняты 2026-10-20 в /opsx:propose, подробности — design change s3-storage.

  1. SeaweedFS прошёл пробу на стенде вне репозитория (design, Context), RustFS не понадобился. Проверены: идемпотентность bucket и пользователя, анонимные запросы, права ключа API, healthcheck, рестарт с volume, kill -9, память, клиент. Образ — chrislusf/seaweedfs:4.48@sha256:4e61d15f…. Команды s3.configure из решения 1 выше в 4.48 нет, вместо неё IAM-команды s3.user.* и s3.policy* (решение 4).

  2. Три места, где SeaweedFS по умолчанию не приватен (решения 1, 3):

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

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

  3. Root по решению 5 выше (решение 3). Административную пару хранит только сервер s3: без неё S3 открыт. Bootstrap работает не ею, а weed shell на loopback сервера с ключом подписи. У API и будущего уборщика административной пары нет.

  4. Права API — политика s3:GetObject, s3:PutObject, s3:DeleteObject на <bucket>/*, у bucket нет владельца (решение 3). Пользователь уборщика появится в upload-consistency.

  5. Bootstrap — сервис s3-bootstrap с network_mode: service:s3 (решение 4):

    • сводит состояние к .env, в том числе новый секрет API;
    • сам проверяет приватность при каждом запуске;
    • make s3_check — те же проверки с хоста и из сети (решение 8).
  6. Отдельной сети для S3 нет: служебные порты закрыты loopback и ключом подписи (решение 1).

  7. Клиент — aiobotocore 3.9.2 (решения 6, 7):

    • без повторов, срок на каждый вызов;
    • отказ, таймаут и отказ в учётных данных — 503;
    • ключи объектов с префиксом имени базы.

    Отвергнуты boto3 в потоке, aioboto3, своя подпись, obstore и minio-py.

  8. Память S3 (решение 2): лимит 512 МБ, GOMEMLIMIT=400MiB и -s3.concurrentUploadLimitMB=64. Без них 20 одновременных загрузок по 10 MiB дают OOM-kill. Числа уточняет upload-memory.

  9. Остановка и перезапуск (решения 1, 2):

    • stop_grace_period: 20s — плавная остановка SeaweedFS занимает ~15 с, срок зашит в filer; на стенде отказов — 2 с;
    • -master.electionTimeout=1s — перезапуск ~7 с вместо ~24 с.
  10. Стенды (решение 9):

    • test_isolated — S3 рабочего стенда, префикс test_<db>/, уборка через fs.rm;
    • failure_checks — свой S3 и проверка готовности без него;
    • bench/ — секреты на прогон и фильтр секретов в паспорте; профили лаб 2–3 S3 не запускают, методика прежняя;
    • rolling-update.sh bootstrap не запускает: bootstrap, как миграции, только расширяет права.
  11. Проверка рестарта без публичного теста (design, Context; решение 9). Публичные make test, test-persistence и test-failover с LAB=4 загружают вложение и до attachments красные. Поэтому рестарт hook-ом проверяется напрямую: StartedAt, «exists» bootstrap, объект с тем же SHA-256.

Приняты 2026-10-20 в /opsx:apply, подробности — design change s3-storage, «Уточнения apply».

  1. make start_s3 — два шага: up -d --wait s3, затем up --no-deps --exit-code-from s3-bootstrap s3-bootstrap. --wait не ждёт завершения одноразового сервиса (compose v5.5.1), вопреки пробе propose. Так же — run_failures.py.
  2. Bootstrap — режимы apply, check, cleanup: проверки с хоста и из сети идут между записью проверочного объекта и его удалением. Новый секрет API распознаётся по SignatureDoesNotMatch.
  3. Клиент: open() читает тело блоками, срок — на каждый блок; ключи в botocore передаются всегда, даже пустые.
  4. Ожидаемо красные шире списка tasks: контракт лабы 4 требует attachment_ids в Message, код лабы 3 его не отдаёт — до attachments красные 32 теста (и 2 ошибки) make student_test через LB (в make test_isolated — 29 и 2) и 5 проверок make failure_checks. От S3 не зависит.
  5. Дельта health синхронизирована в основной спек в apply, как в scaling-bench: иначе маркер нового сценария — ссылка на неизвестный сценарий в сверке покрытия.
  6. rollout_from c50b721 — дефект переноса (KNOWN_ISSUES.md): профиль rollout проверен с --from 5d5d8f9.

Приняты 2026-10-20 в правках по /opsx:verify (tasks.md, группа 7), подробности — design change s3-storage, «Уточнения apply», п. 8–13.

  1. Healthcheck S3 ждёт регистрации тома (/dir/status, непустой DataNodes): первая запись после рестарта — 10–40 мс вместо до 4,8 с при сроке 5 с. Та же проба — в fault_hook.py.
  2. tmpfs: [/tmp, /data] у s3-bootstrap: без анонимного volume на каждый контейнер.
  3. Клиент S3: удалённый bucket и отказ в доступе — 503 с error («bucket is missing», «denied access»), а не «объекта нет» и не «rejected credentials»; delete глушит только отсутствующий ключ. Ограничение: HEAD без тела, удалённый bucket у head — None.
  4. make test_isolated проверяет уборку префикса (fs.ls после fs.rm): код 0 weed shell успеха не значит.
  5. make s3_check берёт порты из netstat контейнера S3, а не из фиксированного списка; проверка готовности без S3 — и для pause.

Вопросы

  1. Как в apply добавить строки S3 в рабочий .env? Агент .env не читает, а make env_setup существующий файл не меняет (правило settings.md). Варианты:

    • (а) пользователь сам переносит блок из .env.example и генерирует секреты, как было с Valkey; design исходит из этого;
    • (б) агент с согласия пользователя: значения openssl rand попадут в журнал сессии;
    • (в) научить make env_setup дописывать недостающие переменные шаблона со сгенерированными секретами в существующий .env. Это меняет правило settings.md и спек container-run не нарушает: существующие значения не перезаписываются.

    Ответ 2026-10-20 (основная сессия, по факту): в рабочей копии лабы 4 .env ещё нет. Его создаст make env_setup из обновлённого .env.example вместе с секретами S3, переносить нечего. Для уже существующего .env остаётся (а), как в design; (в) — только по просьбе пользователя.

  2. attachment_ids отсутствует в ответах Message (код лабы 3), и поэтому до change attachments красные 32 теста make student_test и 5 тестов make failure_checks (решение 15). Добавлять ли пустой список раньше?

    Ответ пользователя 2026-10-20: нет, красное до attachments. Поле приходит целиком в attachments (запрос, ответ, хэш идемпотентности), там же evidence тестов переснимается зелёным.

  3. Когда чинить rollout_from c50b721 (решение 17, KNOWN_ISSUES.md)?

    Ответ пользователя 2026-10-20: в change attachments: он добавляет миграцию, и rollout со старого образа на новую схему — нужное evidence. До тех пор запись остаётся в KNOWN_ISSUES.md.

  4. HEAD при удалённом bucket даёт None, как отсутствующий ключ: SeaweedFS отвечает на HEAD одним и тем же 404 без тела (решение 21, design «Уточнения apply» п. 10). Нужен ли лишний GET Range: bytes=0-0 на каждый промах, чтобы их различить?

    Ответ основной сессии 2026-10-20: нет, ограничение принято. Удалённый bucket видят put, open и delete (503), а также bootstrap и make s3_check. Лишний запрос на каждый промах не нужен. Правило для следующих changes: промах head не основание для разрушающего решения (удалить строку, пометить вложение потерянным) без проверки, что bucket на месте. Это учитывают upload-consistency и reconciler трека 2.

attachments

Решения

Приняты 2026-10-20 в /opsx:propose, подробности — design change attachments.

  1. Строка pending до PUT — уже здесь (решение 1). Порядок: проверки → pending с ключом объекта (commit) → PUT → ready (commit) → 201. При отказе S3 или БД после шага pending — 503, строка остаётся. upload-consistency добавит компенсацию, уборщик и тесты отказов посреди загрузки, порядок шагов не меняя.

  2. Проверка изображения — структура без декодирования (решение 2), своя функция на stdlib:

    • PNG: CRC чанков, поток IDAT распаковывается ровно в объём по размерам, типы фильтров строк;
    • JPEG: маркеры, один кадр, скан, EOI;
    • пиксели — из заголовка до распаковки.

    Проба: 12 000 настоящих файлов без ложных отказов, память проверки до 3,5 MiB, «бомба» отсекается за доли миллисекунды. Pillow — только dev-группа, для JPEG в тестах. Поведение для клиента подтвердил пользователь («Вопросы», п. 1).

  3. Схема (решение 3):

    • таблицы attachments и message_attachments — порядок position, FK без каскада: вложение со ссылкой из сообщения БД удалить не даст;
    • ограничение текста сообщения ослаблено до 0–4000 с NOT VALID, без скана messages под эксклюзивной блокировкой (дельта db-migrations);
    • чат вложения = чат сообщения проверяет сервис в той же транзакции.

    Отвергнуты массив id в messages, составной FK с третьим индексом на messages и тип ENUM.

  4. Ключ объекта — <база>/attachments/<id>/original, хранится в object_key (уникальный) (решение 4).

  5. Загрузка и скачивание не держат сессию БД (решение 5). Найдено: get_db_session держит соединение пула и срок 6 с до конца отправки ответа, и передача 10 MiB медленному клиенту оборвалась бы на 6-й секунде. Поэтому:

    • db_session_scope() на каждый шаг с БД;
    • вход CurrentUserBrief с короткой сессией;
    • AttachmentService(db_scope, cache, storage).
  6. Ответы до чтения тела (решение 6, проба). Ранние 404, 413 и 415 получают httpx, curl и любой клиент через LB. urllib напрямую к одной реплике ответ теряет — ограничение в REPORT.md. Медленные 10 MiB через LB проходят: таймауты HAProxy — простой, а не длительность.

  7. Порядок проверок загрузки: 401 → 400 → 404 → 415 (Content-Type) → 413 (Content-Length) → тело (спек «Порядок проверок загрузки»).

  8. Скачивание (решение 7):

    • поток из S3, отказ S3 — 503 до заголовков;
    • заголовок X-Content-Type-Options: nosniff;
    • variant кроме original — 400 по перечислению контракта лабы 4;
    • строка ready без объекта или с другим размером — 500 и error в журнале, строка не меняется.
  9. Хэш идемпотентности (решение 9): пустой attachment_ids хэш не меняет, id в нижнем регистре, порядок значим.

  10. Лимиты 10 MiB и 40 млн пикселей — константы, не настройки (дельта service-configuration), соответствие MAX_UPLOAD_BYTES и MAX_IMAGE_PIXELS — в REPORT.md.

  11. rollout_from = e1161f7 — последний commit лабы 4 до этого change (решение 14). Проверка commit до стенда, правило — в bench.md, запись в KNOWN_ISSUES.md удаляется в apply.

  12. Дельты синхронизируются в основные спеки в apply, как health в s3-storage: сверка покрытия читает только openspec/specs/.

  13. Проверки отказов вложений — через hook стенда отказов: счётчики вложений по статусам и объектов в bucket (решение 12).

Уточнения apply (2026-10-20/21, design change attachments, «Уточнения apply»):

  1. Текст из пробелов с вложением — 201 по ответу преподавателя («Вопросы», п. 2); без вложений — 400. Текст не нормализуется.
  2. Проверка изображения на готовом модуле повторила пробу: 17 вариантов, корпус 12 000 файлов без ложных отказов, «бомба» за 1 мс, пик памяти ≤ 3,2 MiB. Вход IDAT — кусками по 64 KiB.
  3. План истории: на пустой message_attachments стенда bench/ SubPlan — Seq Scan пустой таблицы; с данными — pk_message_attachments, индекс истории прежний.
  4. variant в /openapi.json — enum ["original"] через json_schema_extra: Literal pydantic пишет const.
  5. bench_restore_quick падал из-за гонки стенда (реплика пересоздаётся с тем же IP, LB держит устаревший UP), не из-за вложений. Решение основной сессии 2026-10-21: чинить в этом change — возможности лаб 2–3 (bench_restore) должны работать после каждого change, а 7.2 — задача attachments. switch_api ждёт готовности процесса новой реплики изнутри контейнера, затем UP в LB (design, «Уточнения apply», п. 9); запись KNOWN_ISSUES.md удалена.

Замечания /opsx:verify 2026-10-21 (все приняты, tasks группа 10; design, «Уточнения apply», пп. 10–15):

  1. Память загрузки — одно тело, а не два. Тело копится в io.BytesIO, getvalue() отдаёт bytes без копии (bytearray botocore копирует). В образе — MALLOC_MMAP_THRESHOLD_=131072: с динамическим порогом glibc вторая загрузка росла в куче, и realloc на миг держал два тела. Замер в образе: RSS 1,99 → 1,19–1,20 тела на каждой из трёх загрузок подряд. Буфер под Content-Length заранее не выделяется: заявивший 10 MiB клиент держал бы их без передачи.
  2. «Бомба» распаковывается до ожидаемого объёма + 1 байт, а не до 1 MiB: предел блока zlib — остаток ожидаемого плюс байт. Корпус 11 993 файлов — вердикты те же.
  3. «Старый образ на новой схеме» переформулирован: проверки, которые прежний образ проходил на прежней схеме, проходят и на новой; доказательство — замер rollout (переснять с чистого дерева после commit правок).
  4. filename не в UTF-8 — 400 (a%FFb.png давал 201 с U+FFFD): ручка строго разбирает строку запроса, новый сценарий «Имя не в UTF-8».
  5. «Окружение не меняет лимит» проверяет тест fault: обычный API стенда отказов — с MAX_UPLOAD_BYTES=1 и MAX_IMAGE_PIXELS=1.
  6. Мёртвые константы MESSAGE_TEXT_MIN_LENGTH и ATTACHMENT_READ_CHUNK_BYTES удалены: блок чтения задаёт uvicorn.
  7. Невидимость pending через API (S6) — не здесь: задача upload-consistency (раздел «Последовательность работ», п. 3).

Вопросы

  1. Что считать «повреждённым изображением» (решение 2, спек attachments, «Повреждённое изображение»)? По умолчанию — структурная проверка без декодирования пикселей:

    • 415 — обрезанный файл, битая CRC, сломанные маркеры, поток zlib не того объёма, «бомба»;
    • байты после IEND или EOI принимаются как часть оригинала;
    • изменённый байт внутри данных скана JPEG не ловится. У формата нет контрольной суммы, Pillow его тоже не ловит.

    Альтернатива — полное декодирование Pillow. Оно стоит до 160 МБ на загрузку при лимите реплики 512 МБ, требует семафора уже в этом change и ловит не больше.

    Ответ пользователя 2026-10-20: структурная проверка, как по умолчанию. Менять ничего не нужно.

  2. Текст из одних пробелов вместе с вложением. По умолчанию — 400: общее правило контракта «обязательные строки не состоят только из пробельных символов», а исключение названо только для text="". Фраза «нельзя пустой/пробельный текст без вложений» допускает и прочтение «с вложением можно». Это две трактовки контракта, то есть вопрос преподавателю (AGENTS.md).

    Ответ пользователя 2026-10-20: пока 400, как по умолчанию. Это неоднозначность контракта: contracts/README.md, строка 18 («нельзя … пробельный текст без вложений») против строк 9 (обязательные строки не из одних пробелов) и 50 (исключение — только text="" с вложением). Пользователь спросит преподавателя.

    Ответ преподавателя 2026-10-20 — вопрос закрыт. «Пустой текст» — это и "", и текст только из пробельных символов. Допустимы: вложение + непустой текст, без вложения + непустой текст, вложение + пустой текст. Итог: текст из одних пробелов с хотя бы одним вложением — 201 (текст сохраняется и возвращается как прислан), без вложений — 400. Записано в AGENTS.md, «Согласования с преподавателем»; в apply поправлены валидатор CreateMessage, сценарий messages «Пробелы с вложением» и его тест (design change attachments, решение 8), в REPORT.md — как согласование.

  3. Опасный filename. Контракт называет /, \, NUL и управляющие символы. По умолчанию 400 и на символы управления направлением текста (U+202A–U+202E, U+2066–U+2069) и разделители строк (U+2028, U+2029): ими подменяют видимое имя (например, U+202E перед gnp.exe). ZWJ и остальные форматирующие разрешены: на них держатся emoji и письменности. Оставить так?

    Ответ пользователя 2026-10-20: нет, только то, что в контракте: 400 на /, \, NUL и управляющие символы — категория Unicode Cc (U+0000–U+001F, U+007F–U+009F). Символы направления текста, разделители строк U+2028 и U+2029 и прочие символы категорий Cf, Zl и Zp принимаются и возвращаются без изменений. Спеки attachments, design (решения 3 и 10) и tasks приведены к этому, отвергнутый вариант с причиной — в design, решение 10.

upload-consistency

Решения

Приняты 2026-10-21 в /opsx:propose, подробности — design change upload-consistency. Пробы — design, Context.

  1. Компенсация — только удаление объекта и только при известном исходе (решение 1):

    • PUT подтверждён, а ready не зафиксирован до отправки COMMIT, или строку уже убрал уборщик — объект удаляется до ответа 503;
    • исход COMMIT неизвестен — объект не трогается;
    • после неудачного PUT компенсации нет: при замороженном S3 ответ стал бы 10 с, а позднего объекта по пробе нет (тело не уходит без ответа сервера);
    • строку компенсация не удаляет, её убирает уборщик.

    mark_ready → None — 503 вместо 500.

  2. Уборщик — сервис cleaner, python -m src.cleaner (решение 2):

    • свой engine (пул 1) и клиент S3, цикл с интервалом, --once;
    • SIGTERM — довести текущий шаг строки и выйти с кодом 0;
    • healthcheck образа выключен;
    • в консоли (make run_dev) уборщика нет.
  3. Проход (решение 3): строка под FOR UPDATE SKIP LOCKED → DELETE объекта → DELETE строки → commit. Блокировка упорядочивает уборщика и mark_ready загрузки, пережившей grace. Остаток риска: API заморожен дольше grace посреди PUT — объект без строки, его находит сверка трека 2. После verify — пометка строки отдельной транзакцией до DELETE объекта (решение 18 ниже), после повторного — объект и строка одной транзакцией под блокировкой (решение 23).

  4. Grace 900 с, интервал 60 с, выборка 100 (решение 4):

    • граница живой загрузки от строки до ready: B = 2 × 6 + 5 = 17 с, запас ×50;
    • при grace ≤ B уборщик не стартует;
    • стенд отказов — 20 с и 1 с.
  5. Права уборщика в S3 (решение 8) — s3:GetObject и s3:DeleteObject на объекты своего bucket, как задано пользователем («чтение/удаление»). Чтение пока не используется: HEAD не нужен, это задел глубокой сверки трека 2. List — в track2-reconciler, если понадобится. Проба: одного Delete хватает, DELETE отсутствующего — 204, удалённого bucket — NoSuchBucket (503).

  6. Частичный индекс строк pending по (created_at, id) — CONCURRENTLY в autocommit_block (решение 6). Проба с асинхронным env.py прошла: с нуля, повтор, откат.

  7. Общий session_scope в src/infra/db/ для API и уборщика (решение 7).

  8. Hook — списки id вместо счётчиков (решение 10):

    • SeaweedFS убирает пустой каталог <id>/ лишь через ~2 мин после DELETE, а уборщик меняет счётчики параллельно с тестами. Объекты считаются по файлам original;
    • новые действия: attachment-ids, last-pending (замечание S6), object-ids, fail-attachments insert|ready|stall, kill-api и start-api. Отказ триггера — SQLSTATE 08006, для API это 503 (проба).
  9. Тесты отказов (решение 10):

    • пять новых тестов и три изменённых, make failure_checks дольше ~2 мин;
    • «реплика убита» — между PUT и фиксацией (задержка в триггере), а не во время PUT: так проверяется ровно «PUT прошёл, COMMIT нет».
  10. restart.sh и rolling-update.sh не меняются (решение 9): рестарт хранилищ уборщик переживает сам, новый код уборщика — docker compose up -d --no-deps cleaner.

  11. Для upload-memory. Ожидание между pending и ready (очередь загрузок) расширяет границу B. Проверку grace и решение 4 design upload-consistency обновить в том же change.

Приняты 2026-10-21 в /opsx:apply (подробности — design, «Уточнения apply»):

  1. make env_setup дописывает в существующий .env недостающие переменные шаблона (ответ на вопрос 1): секреты — случайными, остальные — значениями шаблона, прежние строки не меняются, в вывод — только имена. Правило settings.md и дельты service-configuration / container-run обновлены (новый сценарий «Недостающие переменные в существующем .env»).
  2. Статус в запросах уборщика — константа (literal_execute): общий план asyncpg иначе не взял бы частичный индекс. План — Index Scan по ix_attachments_pending_created_at.
  3. SIGTERM посреди прохода — stop_requested у clean_stale_pending: текущий шаг строки доводится до commit или отката, новые не начинаются (после решения 19).
  4. Неверные настройки уборщика — запись без значений полей и код 2, а не traceback.
  5. entrypoint у сервиса cleaner, чтобы docker compose run --rm --no-deps cleaner --once передавал флаг уборщику.
  6. Красный прогон новых тестов отказов против прежнего кода: 4 из 11 упали (компенсация и уборка), остальные закрепляют уже выполнявшееся поведение. Полный make failure_checks — 29 passed, ~3,5 мин.

Приняты 2026-10-21 в правках по verify (решения основной сессии; design, «Уточнения apply», п. 16–20; tasks, группа 11):

  1. W1 — пометка строки до удаления объекта вместо одной транзакции уборщика: блокировка → updated_at = utcnow() → commit; DELETE объекта; блокировка → DELETE строки → commit. mark_ready — только при updated_at = created_at. Без миграции. Откат транзакции уборщика после удачного DELETE в S3 больше не даёт ready без объекта. Остаток — окно make rolling_update (прежние реплики и уборщик) и объект без строки, если зомби дописал объект после уборки, а компенсация не удалась.
  2. SIGTERM уборщика — между шагами строки: три шага удлинили бы худшую остановку до 17 с (после решения 23 шагов два — до 12 с); доводится только текущий шаг (≤ 6 с). Требование graceful-shutdown «Остановка уборщика» уточнено.
  3. W2, W3 — режимы hook commit и outlive и тесты веток «исход COMMIT неизвестен» и «строку убрал уборщик до ready»; W1 — режим undeletable. Ожидание перевода в ready — триггер BEFORE UPDATE OF status уровня оператора: пометку уборщика он не задерживает.
  4. Новые сценарии — «Исход фиксации неизвестен» (attachments), «Загрузка дольше grace» и «Сбой уборки после удаления объекта» (storage-consistency), в дельтах и основных спеках.
  5. W4 и S1 — evidence «Отказ S3 во время прохода» с закоммиченного кода; docker.md — entrypoint уборщика.

Приняты 2026-10-21 в правках по повторному verify (решения основной сессии; design, «Уточнения apply», п. 21; tasks, группа 12):

  1. W1 повторной проверки — два шага вместо трёх: транзакция пометки, затем объект и строка одной транзакцией под блокировкой (как в f2dc0b3, но на помеченной строке). В решении 18 объект удалялся без блокировки, и реплика до 87c48b9 успевала сделать строку ready прямо перед удалением объекта — смесь «новый уборщик + прежние реплики» была хуже, чем до правки. Теперь обе смеси не хуже, чем до правки (проба блокировок — design, п. 21), остаётся только откат транзакции уборки после удачного DELETE. Цена — вызов S3 внутри транзакции (≤ 5 с < idle_in_transaction_session_timeout 10 с). Решения 18 и 19 в части «три шага» заменены этим.
  2. Порядок обновления: вперёд — сначала реплики (make rolling_update), потом docker compose up -d --no-deps cleaner; откат реплик на версию раньше 87c48b9 — сначала уборщик (balancer.md, REPORT.md).
  3. Тесты 11.x не менялись: undeletable на двухшаговой схеме роняет DELETE строки в той же транзакции, что DELETE объекта, — это тот же откат после удачного DELETE в S3; красный прогон на f2dc0b3 в силе. Требования graceful-shutdown и storage-consistency не менялись.

Вопросы

  1. Как перенести секреты уборщика S3_CLEANER_ACCESS_KEY и S3_CLEANER_SECRET_KEY в рабочий .env? Без них compose не разбирает файл (:?). Тогда apply не проверит изменения ни на рабочем стенде, ни в make failure_checks и make test_isolated (tasks, шапка).

    • По умолчанию — как в ответе на вопрос 1 s3-storage: пользователь переносит из .env.example строки и комментарий, значения — openssl rand -hex 10 (ключ) и openssl rand -hex 20 (секрет).
    • Альтернатива — научить make env_setup дописывать недостающие секреты в существующий .env; только по просьбе пользователя.

    Спеки и design от выбора не меняются.

    Ответ основной сессии 2026-10-21 (пользователь недоступен и поручил работать самостоятельно): альтернатива. make env_setup дописывает в существующий .env переменные шаблона, которых в нём нет: секреты — случайными значениями, остальные — значениями шаблона; существующие строки не меняет, печатает только имена. Причины: значения не попадают ни в журнал сессии, ни в вывод; тот же путь нужен и проверяющему со старым .env при переходе между changes; ручной перенос блокирует автономную проверку на стенде. Правило settings.md и сценарии make env_setup обновляет apply. Сделано в apply (решение 12 выше): рабочий .env получил две строки S3_CLEANER_* этой командой.

upload-memory

Решения

Приняты 2026-10-21 в /opsx:propose, подробности — design change upload-memory. Пробы — design, Context: проект compose umprobe, реплика 1 CPU / 512 МБ, прототип в копии дерева в scratchpad.

  1. Проба опровергла «~1,2 тела» из REPORT.md (Context, п. 1–5):
    • при PUT aiohttp копирует тело (getbuffer() у BytesIO, общего с bytes). Пик загрузки — около двух тел, и спек attachments («Лимит размера до чтения тела») сейчас нарушен;
    • код f894040 без swap при 20 одновременных загрузках по 10 MiB — OOM-kill. Со swap рабочего стенда при 30 — 512 MiB и ещё 267 MiB в swap;
    • ожидание до чтения тела само память не бережёт: ядро копит недочитанное тело в буфере сокета, до 32 MiB на соединение;
    • LB даёт 502/504, если реплика молчит дольше 10 с до тела или после него, а клиенту, замолчавшему посреди тела, отвечает 400 в HTML.
  2. Места загрузки — на процесс API (решение 1): 4 места, очередь до 16, ожидание до 5 с по порядку прихода. Отвергнуты очередь в LB (второй набор слотов ломал бы замену реплик и профили лабы 3), --limit-concurrency uvicorn, места по байтам и общий счётчик в Valkey или PostgreSQL.
  3. Ответ при занятых местах — 429 rate_limited, Retry-After: 1 (решение 2) — до ответа на вопрос 1 ниже. Очередь, а не сразу 429: сообщение несёт до 10 вложений, и 10–20 одновременных загрузок по 10 MiB на пробе проходят все.
  4. Место — после проверок 401/400/404/415/413 и до тела, держится до ответа (решение 3). Граница уборщика B = 17 с не меняется: ожидание, тело и проверка — до created_at, сроки tx1, PUT и tx2 прежние. Проверка grace и стенд отказов (20 с) остаются. Свойство закреплено сценарием storage-consistency и тестом: created_at ожидавшей позже updated_at той, что держала место.
  5. Срок тела — 30 с с момента, как загрузка заняла место, иначе 400 invalid_request (решение 4), по образцу обрыва тела. 408 в контракте ручки нет. Срок простоя между блоками отвергнут: клиент по байту раз в 29 с держал бы место вечно.
  6. В PUT уходит тот же BytesIO (решение 5): после проверки ссылка на bytes удаляется, буфер снова не общий. Проба — 1,19 тела вместо 2,0–2,3, SHA-256 объекта совпал.
  7. Буферы ядра (решение 6): у api — net.ipv4.tcp_rmem до 512 KiB (sysctls в compose), у LB — tune.sndbuf.server 262144. При 40 загрузках sock реплики — 17 MiB вместо 134, пик LB — 51 MiB вместо 109. Скорость загрузки одного клиента та же.
  8. Цепочка таймаутов пути загрузки (решение 7):
    • timeout server LB для POST …/attachments — 30 с: молчание до тела ≤ 17 с, после ≈ 26 с; остальные пути — прежние 10 с;
    • ответ LB 400 — в формате контракта;
    • ROLLOUT_DRAIN_TIMEOUT — 90 с, больше наибольшей длительности загрузки ~73 с;
    • 408 на медленные заголовки остаётся HTML: http-error его не меняет, запись в KNOWN_ISSUES.md.
  9. S3 без изменений (решение 8): лимит загрузок шлюза 64 МБ, GOMEMLIMIT, 512 МБ и общий срок вызова 5 с. При 12 одновременных PUT (три реплики × 4 места) p95 — 1,6–1,9 с. Отдельный срок PUT не нужен — это закрывает открытый вопрос design attachments.
  10. Профиль uploads (решение 10): одна реплика без swap, S3 рабочего стенда. Варианты: «до» (образ f894040), «без лимита» и «с лимитом». Тела 1 и 10 MiB, 1 / 10 / 20 / 40 клиентов, 3 повтора, новые S3 и реплика на прогон. Пик окна — memory.peak со сбросом через свой дескриптор: пик старта (фиктивный хэш, 152 MiB) его иначе перекрывает. Гипотезы H1–H4 — в design, в REPORT.md — отдельным commit до прогонов.
  11. Тесты (решение 11): в make student_test — 10 одновременных загрузок. В make failure_checks — третий API с 1 местом, 1 в очереди, ожиданием 1 с и сроком тела 2 с, пять тестов. Сценарии памяти — исключения сверки со ссылкой на метку профиля.
  12. Драйвер lb-upload-timeouts (решение 7): сроки LB на заглушке за haproxy.cfg проекта. Evidence — evidence/uploads/lb-timeouts.md.

Приняты 2026-10-21 в /opsx:apply (подробности — design, «Уточнения apply»; вопрос 1 открыт — сделано 429, как по умолчанию):

  1. Красный прогон — 5 из 5 новых тестов отказов на f894040 (п. 2): test_rejections_before_queue проверяет и полноту очереди (429 ожидавшей), test_slot_released_after_failures включает шаг «400 по сроку тела» — оба поэтому красные на прежнем коде, а не зелёные, как ждали tasks. На дереве — все пять зелёные.
  2. Тесты мест под срок тела стенда 2 с (п. 1, 3): держатель места отпускается сразу после 429 ожидавшей, сверка — «новые id — только держателя»; ранние отказы быстрее срока ожидания (1 с), а не 0,5 с.
  3. Одна копия тела подтверждена до профиля: PUT 10 MiB в образе API против S3 стенда — 1,19 тела над базой против 2,31 у прежнего пути, SHA-256 совпал.
  4. Тип мест в сервисе — под TYPE_CHECKING, Retry-After — таблица RETRY_AFTER в errors.py, UploadsBusy журналирует сервис (п. 4–6).
  5. Драйвер lb-upload-timeouts (п. 8): пять случаев параллельно, ~33 с; код 0 на текущем haproxy.cfg, код 1 на f894040 (502 и 504 через 10 с, 400 HTML).
  6. Профиль uploads (п. 10): разбор — bench/uploads.py; окно памяти — весь прогон k6 со сбросом пика после разогрева; окружение варианта — свой override, чтобы stand.app_env прежних профилей не менялся; S3 перед прогоном — kill и новый volume. uploads_quick на дереве: «с лимитом» при 40 × 10 MiB — пик 180 MiB, 429 вместо 5xx; «без лимита» — OOM. Попутно исправлен сэмплер: каждый запуск оставлял анонимный volume (удаление без -v).
  7. Буфер приёма LB от клиента — tune.rcvbuf.client 131072 (97a4be4; design, «Уточнения apply», п. 11). Первая метка baseline (на 511e285) отброшена: swap хоста 337 056 страниц и dirty. Из неё взят только рост пика LB «с лимитом» ~2,6 MiB на клиента — сценарий load-balancing «Буферы соединений ограничены» не выполнялся из-за буфера приёма LB от клиента (до 9 MiB на сокет). После правки — 0,56 MiB на клиента.
  8. Метка baseline на 97a4be4 принята с пометкой (решение пользователя 2026-10-22, commit ce1ae2c). В паспорте — предупреждение «host swapped out 7464 pages»: вся выгрузка пришлась на прогон limited-10MiB-c40-r2 (host_swap). Пик памяти в нём как у повторов, искажено только время (9,95 загрузки/с против ~11,0, p95 2 815 мс против ~2 050); медиана ячейки и выводы H1–H4 от него не зависят. Предупреждение названо в REPORT.md.
  9. Правки по verify (2026-10-22, tasks, группа 11; design, «Уточнения apply», пп. 12–16). Метка baseline не переснимается; числа, которых нет в её сводке, REPORT.md даёт формулой из её ячеек.
    • Разбор сводки: H1 считает 429, OOM и 5xx только по ячейкам гипотезы (10 MiB, C = 10, 20, 40: у baseline 429 — 1 351, а не 2 731 обоих тел) и печатает рост сверх C = 10 на клиента; «Буферы соединений ограничены» — своя строка с вердиктом по сумме роста LB и sock реплики от C = 1 до 40 (у baseline 0,56 + 0,39 = 0,95 MiB при пороге 1).
    • Спеки: в требовании срока пути загрузки — буфер приёма LB от клиента 128 KiB; «Лимит размера до чтения тела» — одна копия тела и блоки чтения, рост пика ≤ 1,5 тела (как в сценарии).
    • Проверки соотношения wait_timeout_seconds и timeout server LB при старте нет: LB-значение API не знает; соотношение — в settings.md и config_example.toml.
    • Срок тела «узкого» API стенда отказов — 3 с вместо 2 с: запас держателя места в test_upload_slots_busy был ~0,5 с. Evidence failure-checks.md — переснять после commit.
    • REPORT.md: таблица 1 MiB, числа и commit строк тестов (ce1ae2c), ограничение «оборванный клиент в очереди держит место очереди до срока ожидания».

Вопросы

  1. Какой код отдавать, когда все места загрузки реплики заняты и очередь полна или ожидание истекло: 429 rate_limited или 503 unavailable? Контракт (contracts/openapi.json, ручка uploadAttachment) допускает оба:

    • 429 описан как «Ограничение частоты запросов», у него одного есть заголовок Retry-After;
    • 503 описан как «Зависимость недоступна».

    contracts/README.md разрешает факультативное ограничение запросов кодом 429 rate_limited. Места загрузки ограничивают одновременность, а не частоту, и это расхождение формулировки. Поэтому трактовку выбирает преподаватель.

    • По умолчанию до ответа — 429 с Retry-After: 1. Причины: из двух описаний контракта к ограничению подходит только 429, а «зависимость недоступна» неверно. Кроме того, клиент и профиль uploads отличат занятые места от отказа S3, который тоже 503.
    • Ответ «503» меняет строку таблицы src/api/errors.py (заголовок Retry-After остаётся), сценарии attachments и api-conventions, ожидания тестов и REPORT.md. Остальной design и задачи не меняются (design, решение 2).

    Состояние на apply 2026-10-21: ответа нет, сделано 429 rate_limited с Retry-After: 1 (поручение основной сессии). Строки, которые поменяет ответ «503»: DOMAIN_ERRORS и RETRY_AFTER в src/api/errors.py, ERROR_CODES и проверка Retry-After в student-tests/contract.py, ожидания test_upload_slots_busy и test_rejections_before_queue, сценарии спеков attachments и api-conventions, правило api-contract.md.

track2-reconciler

Решения

Приняты 2026-10-22 в /opsx:propose, подробности — design change track2-reconciler. Пробы — design, Context: проект compose rcprobe, SeaweedFS и PostgreSQL на tmpfs, bootstrap проекта.

  1. Сверка — часть уборщика (решение 1):

    • команда python -m src.cleaner reconcile [--apply] [--max-changes N], по умолчанию dry-run; цель make reconcile [APPLY=1];
    • плановая сверка в сервисе cleaner — при старте и раз в [reconciler] interval_seconds (3600 с), с исправлением;
    • --once — как было.

    Отвергнуты:

    • отдельный сервис и пользователь S3 reconciler: второй процесс и два секрета ради почти пустого разделения прав;
    • сверка только вручную: PUT-зомби жил бы до запуска.

    С уборщиком на строках pending сверка не спорит: убирает их его процедурой (FOR UPDATE SKIP LOCKED и пометка), а объект строки любого статуса не удаляет никогда.

  2. Права S3 (решение 2). cleaner-objects получает s3:ListBucket с условием s3:prefix <база>/attachments/*, префикс bootstrap берёт из POSTGRES_DB (S3_CLEANER_LIST_PREFIX). Проба: SeaweedFS 4.48 условие соблюдает — весь bucket, test_<db>/ и чужой bucket дают 403. Нового пользователя и секретов нет. make s3_check получает строки списка ключом уборщика.

  3. Проход (решение 3):

    • страницы LIST по 1000;
    • на страницу — одно выражение к БД по id (по тексту ключа — только для нестандартных ключей: по пробе в 15 раз дороже);
    • множество увиденных ключей, затем keyset строк ready по id.

    Слияние отсортированных потоков отвергнуто: порядок списка SeaweedFS — обход каталогов, а не порядок байтов (проба). Действия — только после классификации, каждое с перепроверкой в БД и HEAD.

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

    • grace уборщика по LastModified объекта и времени строки;
    • удаляются только объекты без строки и зависшие загрузки;
    • чужие ключи — только отчёт и код 3;
    • отсутствие объекта не подтверждается без проверки bucket;
    • предел [reconciler] max_changes (100): больше — ни одного изменения, код 3.
  5. Потерянный оригинал (решение 5) — колонка attachments.lost_at. status и updated_at не меняются. Ответы API:

    • скачивание помеченного — 404 без обращения к S3, до пометки — 500, как было;
    • метаданные — 200;
    • ссылка в сообщении — 201.

    Это вариант по умолчанию до ответа на вопрос 1 ниже. Статус lost/failed отвергнут: контракт лабы 4 знает только ready.

  6. Миграция (решение 6) — ADD COLUMN lost_at с SET LOCAL lock_timeout. По пробе это только каталог: 0,36 мс. Смеси версий не хуже, чем до change. Порядок обновления:

    • вперёд — s3-bootstrap, make rolling_update, затем уборщик;
    • откат — сначала уборщик.
  7. Коды разового прохода (решение 8): 0 — расхождений нет, 3 — остались (в том числе чужой объект или отказ по пределу), 1 — прерван, 2 — конфигурация.

  8. Стенд отказов (решения 9, 11):

    • плановая сверка выключена (RECONCILER__INTERVAL_SECONDS=0);
    • сверку запускает hook;
    • новые действия hook: объект мимо API, удаление объекта, строки и размера, сдвиг времени строки, lost-ids, fail-attachments mark, reconcile, stop|start cleaner, run-cleaner;
    • восемь тестов отказов, ~+3 мин; объекты без строки ждут grace, а строки состаривает hook.
  9. Evidence (решение 12), evidence/reconcile/:

    • cycle.md — драйвер reconcile-cycle: dry-run, apply, повтор = 0, возврат оригинала;
    • stress.md — reconcile-stress;
    • service.md.

    Плюс evidence/s3/cleaner-list.md и evidence/migrations/lost-at.md.

  10. Граница с track2-reconcile-cost (решение 13). Здесь — одна стратегия «батч» и поверхностная сверка (наличие и размер). Там:

    • HEAD на строку;
    • глубокая сверка SHA-256;
    • ограничение скорости;
    • профиль reconcile стенда bench/;
    • гипотезы 1–4.

    Гипотезу 5 проверяет стресс этого change.

  11. Запись KNOWN_ISSUES.md о bootstrap после удаления bucket — воспроизведена и объяснена (design, Context; решение 14). Причина — не имя bucket, а слоты томов:

    • -volume.max=0 даёт на tmpfs 4 ГБ три слота;
    • после удаления коллекции их занимают тома коллекции по умолчанию;
    • PUT получает «no free volumes left», 500.

    На 16 ГБ повтор bootstrap прошёл за 2 с. У рабочего стенда 403 свободных слота. Reconciler bucket не создаёт, поэтому запись не чинится. В apply её текст переписывается, запись остаётся открытой.

  12. Решения apply (2026-10-22) — подробно design, «Уточнения apply»:

    • потерянный оригинал — вариант (а) до ответа на вопрос 1;
    • ReconcileAction (названия действий), в итоге — remaining и unlogged, found / fixed — MappingProxyType;
    • шаг уборщика публичный (remove_stale_pending): сверка убирает зависшие по одной, с записью «Fixed» на каждую;
    • у --apply исправленное — info «Fixed», оставшееся — warning «Found»;
    • перед каждым действием — ещё одна проверка его условия (HEAD, условный UPDATE, ссылки на ключ), перед пометками — снова bucket;
    • свежие чужие объекты и объекты без LastModified — свежие;
    • отказ после сигнала — interrupted_by: stop;
    • 404 у списка — отсутствующий bucket;
    • ревизия 5c3e1f0a9b7d; планы: страница по id — BitmapOr, 1,5 мс, keyset ready — Index Scan pk_attachments, 0,57 мс;
    • hook start cleaner — docker start контейнера (compose start требует контейнер migrate);
    • драйвер на рабочем стенде — только после перестройки 12.1; в apply он проверен на временном полном стенде.
  13. Правки по verify (2026-10-22, группа 13 tasks) — design, «Уточнения apply», пп. 19–23:

    • W1: hook set-key, сценарии «Объект, на который ссылается строка, не удаляется» и «Предел не останавливает уборку зависших», тесты …_keeps_referenced_objects и …_limit_keeps_cleanup (зелёные на a6071da, красные на временных регрессиях);
    • W2: строка с ключом вне <база>/attachments/ — «чужой объект» без HEAD, пометки и уборки; сценарий «Ключ вне префикса вложений не трогается», тест …_foreign_key_untouched (красный на a6071da); сервис уборки такую зависшую загрузку по-прежнему убирает — KNOWN_ISSUES.md;
    • S1: сигнал — перед каждым вызовом хранилища, остановка ≤ 5 с (S3) / ≤ 6 с (БД);
    • S4: ранний отказ по пределу не сделан — передан в track2-reconcile-cost (раздел 6 выше);
    • S5: driver.py reconcile-signal — код 1 разового прохода по SIGTERM; снимок — после commit, на временном стенде.

Вопросы

  1. Вопрос преподавателю. Что отвечает API лабы 4 на вложение, оригинал которого потерян, после того как сверка это подтвердила? Объекта в bucket нет или он другого размера, байтов не восстановить.

    Контракт неоднозначен:

    • contracts/openapi.json: у Attachment.status в лабе 4 одно значение — ready, failed и 409 появляются с лабы 5;
    • contracts/README.md: «Отсутствующий вариант ready-объекта — 404», «404 — объекта нет или он чужой» и «Неожиданное исключение — 500».

    Варианты:

    • (а) по умолчанию: метаданные — 200 как раньше (ready, error_code=null), байты — 404 not_found, как отсутствующий вариант, ссылка в новом сообщении — 201. До пометки байты — 500: непредвиденное расхождение;
    • (б) вложение целиком как незавершённое: метаданные, байты и ссылка — 404;
    • (в) байты — 500 и после пометки: пометка только для отчёта.

    Ответ (б) или (в) меняет только ветку open_content и выборку вложений сообщения, сценарий attachments «Потерянный оригинал», тест test_reconcile_finds_and_fixes и REPORT.md. Классы, правила безопасности, схема и задачи сверки не меняются (design, Open Questions).

    Состояние на apply 2026-10-22: ответа нет, сделан вариант (а) (поручение основной сессии). Строки, которые поменяет ответ «иначе»: ветка lost_at в AttachmentService.open_content (src/core/services/attachment.py), для (б) — ещё проверка lost_at в get_attachment и MessageService (выборка вложений сообщения); сценарий attachments «Потерянный оригинал», assert_lost_content и ожидания test_reconcile_finds_and_fixes, test_reconcile_keeps_fresh_used_and_unknown, test_reconcile_restored_original, шаги 5–6 и 8 driver.py reconcile-cycle, правило api-contract.md.

fix-upload-put-flake

Change вне сводной таблицы, до track2-reconcile-cost: исправление записи KNOWN_ISSUES.md «Изредка 503 на загрузке: PUT в S3 обрывается без тела» (решение пользователя 2026-10-22).

Решения

Приняты 2026-10-22 в /opsx:propose, подробности — design change fix-upload-put-flake. Пробы — design, Context: временный проект compose upfprobe (тот же docker-compose.yml, синтетические секреты, данные S3 — volume upfprobe_s3_data, удалён после пробы), образы текущего дерева, f894040 и прототипа правки.

  1. Причина найдена и воспроизведена (design, Context):

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

    Подтверждено:

    • журнал рабочего стенда: три 503 через 5,9–6,8 с после скачиваний test_concurrent_uploads на той же реплике;
    • локальная проба aiohttp и проба клиента в образе API;
    • HTTP через LB: до 13 × 503 за 4 раунда;
    • захват пакетов: FIN клиента через 0,1 мс после заголовков PUT, 0 байт тела.

    Полный make student_test на пробном стенде — 10 прогонов из 10 зелёные: вероятность отказа на прогон зависит от таймингов. Поэтому доказательство — целевое воспроизведение.

  2. Не регрессия upload-memory: образ f894040 (тело bytes) — 8 × 503 в 4 раундах из 5 с той же подписью. В набор триггер пришёл с test_concurrent_uploads (10 скачиваний по 1 MiB, затем ≥ 5 с без вызовов S3).

  3. Правка — read_timeout=None (решение 1). Срок вызова и блока чтения — asyncio.timeout приложения, как было. Прототип в раундах теста: 0 отказов из 120 загрузок после простоя, а на текущем образе в тех же раундах — 17 × 503 (испорчено 17 соединений из 60). 503 при docker pause S3 — за 5,02 с; обрыв ответа посреди тела — через 5,9 с.

    Отвергнуты:

    • force_close;
    • связка сроков keep-alive и sock_read;
    • свой коннектор и патч aiohttp;
    • другая версия aiohttp: новее 3.14.5 нет, дефект в ней воспроизведён, а aiobotocore 3.9.2 требует ≥ 3.14.0;
    • снятие Expect;
    • больший буфер ответа;
    • повтор.
  4. Правило «S3 без повторов» не меняется (решение 2): повтор лечил бы симптом, а ReadTimeoutError порчи не отличить от таймаута зависшего S3 без закрытых полей aiohttp.

  5. Тест — стенд отказов, четвёртый API с S3__TIMEOUT_SECONDS=1 (решение 3): до 8 раундов «10 одновременных медленных скачиваний ~4 MiB → простой 1,5 с → 12 загрузок». Вероятность промаха на прежнем коде ≈ 4e-12, make failure_checks дольше на ~20 с. В make student_test не кладётся: раунд там — 6+ с простоя, нужно ~5 раундов (+35 с), и тест всё равно вероятностный. Hook с пробой клиента в контейнере отвергнут: это импорт src в обход HTTP.

  6. Evidence механизма — driver.py s3-idle (решение 4): проба клиента в реплике стенда, вариант образа против эталона с прежним сроком. Файл — evidence/s3/idle-connection.md.

  7. Путь PUT не меняется (решение 5): то же тело, заголовки, соединение и срок. Проба памяти PUT 10 MiB на прототипе — 1,18 тела против 1,19.

Приняты в /opsx:apply 2026-10-23 (design, «Уточнения apply»):

  1. Медленное скачивание теста — Api.attachment_content_slowly, ответ проверяет обычный assert_content. Оригинал — png_noise(1024, 1365) (~4 MiB), пользователи — фикстуры обычного API: база у API стенда общая.
  2. Красный прогон на 4cfaab0: три из трёх упали уже в раунде 1.
  3. driver.py s3-idle считает объекты по списку записанных ключей: списка у ключа API нет. Удаляет их отдельный клиент без скачиваний, остаток проверяет weed shell fs.tree по файлам. Эталон — клиент проекта с подменённым на время start() AioConfig (read_timeout=[s3] timeout_seconds). По умолчанию 3 раунда и PUT по 128 KiB.
  4. Evidence — с b5983f0. make test_isolated на нём записан в evidence/s3/idle-connection.md (раздел 7), а evidence/tests/test-isolated-s3-cleanup.md не переснимался: его предмет — уборка префикса test_<db>/, а она не менялась. Полный make failure_checks снят с фильтром вывода, без построчного списка тестов: итог 49 passed и results — в файле.

Правки по /opsx:verify 2026-10-23 (tasks, группа 6; design, «Уточнения apply», п. 8):

  1. Буфер ответа aiohttp 3.14.5 — 256 KiB (DEFAULT_CHUNK_SIZE), пауза чтения выше 512 KiB; прежние 64 / 128 KiB — значения 3.12–3.13. Сходится с замером propose: до 200 KiB соединения не взводятся.
  2. Версии aiohttp — «в каких проверено»: дефект воспроизведён только в 3.14.5. По исходникам (кэш uv и sdist PyPI) перевзвод срока в resume_reading() есть в 3.12.15, 3.13.2, 3.13.3, 3.13.5 и 3.14.0–3.14.5 (с 3.14.2 — только после паузы); нижняя граница не установлена.
  3. Ссылка botocore/handlers.py:380–397 оставлена: по .venv и по образу add_expect_header — строки 380–397 (def — 380, Expect — 397), а не 378–395, как в замечании S2. client_proto.py:196–201 исправлена на 196–202, httpsession.py:97–98 — на 97–99.
  4. Спек object-storage: срок из настроек — единственный срок вызова, «кроме срока установки соединения» (connect_timeout_seconds), в дельте и основном спеке одинаково.
  5. make test_isolated и полный make failure_checks пересняты на 723b6c3 (код — b5983f0 плюс комментарий) с полным выводом: 193 + 5 пропусков и 49 из 49 за 552 с (evidence/tests/).

Вопросы

  1. Нужна ли пересъёмка полной метки make bench_uploads (evidence/uploads/baseline/)?

    • Правка путь PUT не меняет: то же тело, те же заголовки, то же соединение из пула, тот же срок вызова. Исчезает только взвод таймера sock_read после записи тела.
    • Профиль uploads только загружает и не скачивает, порча соединений в метке не возникала (design, решение 5).
    • По мнению агента пересъёмка не нужна: хватит точечной пробы памяти и make bench_uploads_quick в apply (tasks 4.4).
    • Полный прогон (~50 мин) требует тихого хоста, а на нём сейчас работают контейнеры другого проекта. Решение — за пользователем.

    По умолчанию до ответа — не переснимать, метка baseline остаётся.

    Ответ пользователя 2026-10-23: полную метку не переснимать, evidence/uploads/baseline/ остаётся. В apply — точечная проба памяти PUT и make bench_uploads_quick (tasks 4.4).

track2-reconcile-cost

Решения

Приняты 2026-10-23 в /opsx:propose, подробности — design change track2-reconcile-cost. Пробы — design, Context: временный проект compose rccost, тот же docker-compose.yml, образ рабочего стенда (7f4e626), PostgreSQL и S3 на volumes rccost_* — удалены по имени. После пробы volumes, сети и образы — как до неё (155 / 17 / 24). Во время пробы работали domains-*, поэтому задержки шумные, а счётчики точные.

  1. Профиль reconcile (решение 1):

    • make bench_reconcile — ~50 мин, make bench_reconcile_quick — ~6 мин;
    • результаты — evidence/reconcile/<метка>/;
    • этапы: A — 1k × 1 MiB, свежий стенд; B — 10k × 4 KiB, свежий; C — 30k и D — 100k, тот же набор растёт; S4 — свежий стенд;
    • три повтора кругами.

    Полная метка — отдельная точка commit после commit гипотез, на тихом хосте: основная сессия останавливает domains-* на ~50 мин.

  2. Набор (решение 2):

    • N = 10k / 30k / 100k объектов по 4 KiB и 1k по 1 MiB;
    • расхождения — по 0,25 % на класс (без метаданных, без объекта, другой размер, зависшая загрузка), класс по номеру объекта;
    • grace проходов — 30 с.

    Отвергнуты: 10k и 100k без средней точки, 1M, доли 0 % и 10 %, случайные позиции.

  3. Наполнение мимо API (решение 3):

    • строки — \copy через stdin psql стенда;
    • объекты — загрузчик bench/fill_objects.py в контейнере на образе стенда, botocore и ключи API, ~1 750 PUT/с, упор в S3.

    Проход сверки — разовый уборщик, его результат — его журнал. Это новое исключение границы чёрного ящика — только у профиля сверки.

  4. Стратегия --strategy head (решение 4): выборка строки на объект и HEAD на строку, без множества ключей. Только разовый проход; плановая — batch. Проба: ~5,15 мс на объект против 0,30 у batch (~17×).

  5. Глубокая сверка --deep — по требованию (решение 5):

    • SHA-256 потоком;
    • новый класс checksum_mismatch, с --apply — пометка потерянного оригинала;
    • «оригинал вернулся» теперь требует того же SHA-256 во всех режимах.

    Выборочная глубокая в плановой отвергнута. Проба: предел глубокой на лимите стенда — CPU уборщика, а не S3 (уточнение гипотезы 3).

  6. Предел скорости [reconciler] max_objects_per_second, по умолчанию 2000 (решение 6):

    • считаются объекты S3: ключи списка, HEAD, GET, DELETE;
    • пауза прерывается сигналом;
    • разовый проход принимает --max-objects-per-second, make reconcile — RATE.

    2000/с — ~0,2 ядра S3 на списке. Плановый проход 100k — ~65 с вместо ~30.

  7. S4 — ранний отказ по пределу (решение 7). Выбран порог «подтверждено больше предела» с отдельным счётчиком unchecked в итоге. Он действует у любого --apply, dry-run перепроверяет всех. Проба на текущем коде: +5,3 мс на кандидата, +53 с при 10 000 кандидатов. Отвергнуты отказ по числу неподтверждённых кандидатов и ранний отказ только у плановой сверки. Замер — ячейки S4 на образе 7f4e626 и на checkout.

  8. Счёт запросов (решение 8):

    • внутренний: счётчики клиента S3 по операциям и байтам, сеансы БД обёрткой db_scope — в итоге прохода;
    • внешний — только в метке: метрики шлюза -metricsPort на loopback, только у S3 профиля сверки (override генерирует run.py) — и pg_stat_database. Проба: шлюз считает HEAD типом GET, совпало до запроса.

    Отвергнуты pg_stat_statements и порт метрик у рабочего стенда.

  9. Фоновая нагрузка и порог H4 (решение 10):

    • 300 скачиваний, 50 записей и 50 чтений истории в секунду;
    • тихие окна по 30 с до и после прохода;
    • порог — медиана p95(проход) / p95(окна) ≤ 1,5 у stand, stand-unlimited, fast-limited;
    • контраст: fast-unlimited (1 CPU без предела) > 1,5 (проба: ×2,2);
    • A/A окон вне [1/1,5; 1,5] — «не различимо».
  10. A/A и сравнение меток (решение 11): A/A — внутри метки (разброс повторов, окна до и после). Второй метки и make bench_compare нет.

  11. Гипотезы H1–H4 и ожидание S4 (решение 12) уточнены по пробе. Они идут в REPORT.md отдельным commit до метки.

  12. Пять тестов отказов и аргументы hook (решение 14). Красный прогон — на 7f4e626. Остановку во время паузы предела проверяет driver.py reconcile-signal --pace → evidence/reconcile/service.md.

Решения apply (2026-10-23, /opsx:apply без пользователя; подробно — design, «Уточнения apply», пп. 1–13):

  1. Пауза предела скорости — после каждого вызова S3: иначе последний вызов прохода предел не ограничивал бы (п. 1).

  2. GET отдаёт last_modified, находка несёт SHA-256 строки; глубокая и свежесть, вернувшийся объект с другим SHA-256 — lost_known (пп. 2–5).

  3. Hook и тесты: позиционный предел и флаги по одному разу; тест предела скорости — своя потеря и остановленный уборщик (пп. 6–7).

  4. Быстрый профиль — два свежих стенда (S4 — свой), k6 блока H4 останавливается pkill -INT, длительности — 0,01 мс (пп. 8–9).

  5. Память в H1 и H2 — наклон и рост пика от N, а не прирост прохода: постоянная часть прохода ~14 МиБ (п. 10).

  6. Модель сверяется в каждом проходе (found, listed_objects, checked_rows), окно шага списка — справочно (пп. 11–12).

  7. reconcile-signal --pace — объекты пробы, иначе на пустом bucket паузы нет; остановка — от события kill до FinishedAt (п. 13). Проверка на временном проекте rcpace (tmpfs, без портов): до правки п. 14 — 1,16 с (FAIL), после — 0,22 с, код драйвера 0; режим без --pace — PASS (4,6 с при замороженном S3). Проект убран: volumes 155, сети 17.

  8. Уборщик выходит os._exit после main(): финализация интерпретатора при 0,25 CPU — 0,8–1,5 с, остановка по сигналу иначе больше секунды (п. 14).

  9. Красный прогон 1.3 (make failure_checks FAULT_ARGS='-k "head_strategy or deep_checksum or restore_needs or rate_limit or limit_stops"', код 7f4e626, тесты из дерева): 5 failed за 117 с — head и предел скорости — argparse (пустой отчёт, нет итога), глубокая — нет поля deep, восстановление — пометку снял другой объект того же размера, предел — changes 7 вместо 3. Затем все 16 тестов сверки на дереве — 16 passed за 500 с.

  10. make bench_reconcile_quick на дереве (хост тихий: все контейнеры, включая рабочий стенд и domains-*, остановлены пользователем; дерево грязное): первый — код 0 за 3 мин 39 с, после правок пп. 16–17 — код 0 за 3 мин 30 с (быстрее оценки design ~6 мин). 9 проходов, найденное = внесённому, count_mismatch нет, 5xx фона нет, строки k6 = итерациям; volumes 155, сети 17, тег bench-from снят. Во втором у проходов 1 CPU (0,3 и 1,1 с) CPU уборщика не посчитан — окно короче отсчёта сэмплера в конце жизни контейнера; исправлено (reconcile.window_cpu — по охватывающим отсчётам).

  11. Регресс bench/: make bench_quick — complete 18/18 за 3 мин 26 с, make bench_uploads_quick — complete 6/6 за 4 мин 9 с (у «без лимита» при 40 × 10 MiB — OOM, как у метки baseline); --selftest uploads, resources, scaling, failover, rollout, reconcile — код 0.

  12. Commit кода — 8d4cf7e. Рабочий стенд переведён на него: make rolling_update APP_OUT_PORT=8090 (2 реплики UP за 9 с), уборщик пересоздан на том же образе, make student_test BASE_URL=http://localhost:8090 — 198 passed. Гипотезы H1–H4 и ожидание S4 — REPORT.md, «Стоимость сверки: гипотезы», отдельным commit до метки; H1 и H2 по памяти — в форме п. 17.

  13. Гипотезы — aaf3fa3. Первая метка baseline на нём упала на 39/51 (37 мин): «D: 264071 k6 lines of download, 264070 iterations» — итерация, прерванная остановкой k6 SIGINT уже после строки, в iterations не входит. Правка a42dd27 — счётчик bg_lines_<сценарий> k6 и точное «строк = счётчику»; вторая метка на ней упала там же (39/51): «D: write: 43997 k6 lines, 43996 counted by bg_lines (lines lost)» — у прерванной итерации k6 теряет и отсчёт счётчика. Полнота строк теперь — снизу по итерациям и по счётчику (меньше — «lines lost»), сверху — лишних против каждого не больше VU сценария (design, «Уточнения apply», п. 15). Офлайн на итогах k6 обеих упавших меток проверка проходит (download 1 и write 1 прерванная). Хост в обеих — swapouts_delta 0, host_warnings пусты. Каталоги неполных меток — в scratchpad (baseline-failed-aaf3fa3/, baseline-failed-a42dd27/), метка переснимается целиком после commit правки.

  14. Правка — d8b8ae3. Метка baseline с него — complete 51/51 за 45 мин (15:06–15:52 UTC), dirty: false, swapouts_delta 0, slept_seconds 0, host_warnings пусты, прерванных итераций фона — 0; commit метки — 0072dbe (10.1). Вердикты summary.md: H1, H2, H3, S4 подтверждены, H4 — «не проверена». Контраст fast-unlimited дал r скачиваний 1,08 при пороге > 1,5. Проход шёл со скоростью пробы (100k за 12,9 с), уборщик 0,50 ядра, S3 0,70–0,73 из 1 вместе с фоном: шлюз не насыщен. Проба design (×2,2) была одной, на шумном хосте. Дефекта стенда нет, гипотеза не правилась, перемер не делался. Вывод для предела: защита задержек фона на этих лимитах не показана. Измерено, что предел держит CPU S3 за проход на 0,27–0,32 ядра при любом CPU уборщика. 2000 оставлен как граница доли шлюза (REPORT.md, «Стоимость сверки: результаты метки baseline»). Рекомендации для head и глубокой — по CPU S3 на объект: ~1000 и ~800 / ~250 объектов/с для быстрого уборщика.

  15. Evidence 11.1–11.2 с 0072dbe:

    • make failure_checks — 54 из 54 за 712 с;
    • красный прогон 1.3 (7f4e626, 5 из 5) перенесён из scratchpad в evidence/tests/failure-checks.md;
    • driver.py reconcile-signal --pace на временном проекте rcpace — код 1, выход через 0,2 с после docker stop (evidence/reconcile/service.md);
    • make test_isolated — 193 passed, 5 skipped, 54 deselected, сверка покрытия 250 / 233 / 68 / 17, префикс test_messenger/ и база убраны (evidence/tests/test-isolated-s3-cleanup.md).

    Рабочий стенд — make run_docker APP_OUT_PORT=8090 (реплики api-27, api-28), make student_test BASE_URL=http://localhost:8090 — 198 passed.

Правки по verify

Verify на 16f2cde: CRITICAL нет; W1–W3 и S1–S10 — группа 12 tasks.md, решения — design, «Правки по verify», пп. 1–8. Коротко:

  1. W1: _pace по сигналу возвращается, проход останавливает следующий check_stop(). Красный прогон на 16f2cde — driver.py reconcile-signal --pace: listed_objects 0 при 8 ключах; новый режим --pace --apply: удалено 4 объекта, «Fixed» и fixed — 3.
  2. W2: правильно поведение head — строка сравнивается с объектом по своему ключу, чей бы id в нём ни стоял; batch выровнен (HEAD такой строки в шаге строк). Тест test_reconcile_row_with_other_id_key красный на 16f2cde (batch не назвал ни size_mismatch, ни checksum_mismatch у Y1, Y2). Метка baseline действительна: у строк её набора свои ключи.
  3. S1: свежесть объекта другого размера — в классификации, перепроверке и перед пометкой; «другой SHA-256» перечитывается с fresh_before. Тест test_reconcile_fresh_overwrite_untouched красный на 16f2cde (объект другого размера, перезаписанный только что, помечен).
  4. S2: allow_inf_nan=False у max_objects_per_second; на образе 16f2cde inf проходил — «Started cleaner» с Infinity. Прочие поля float — KNOWN_ISSUES.md.
  5. S4, S6, S9 — bench/reconcile.py, run.py: допуск строк по vus_max, критерии вердиктов, пометки bg_failed / bg_dropped. Офлайн-пересборки summary.md нет; новые критерии на данных метки пересчитаны скриптом scratchpad — все выполняются, вердикты те же.
  6. S8: спек load-benchmark называет исключение для группы из одной ячейки; S5, S7, S10, W3 — тексты REPORT.md и design.
  7. Код правок — ca0c4b2. С него: make rolling_update APP_OUT_PORT=8090 (реплики api-29, api-30), уборщик пересоздан (плановая сверка при старте — без расхождений), make student_test BASE_URL=http://localhost:8090 — 198 passed, покрытие 252 / 235 / 70 / 17; make failure_checks — 56 из 56, pytest 877 с, команда 898 с; driver.py reconcile-signal --pace и --pace --apply на временном rcpace — PASS (evidence/reconcile/service.md). Красный прогон тестов verify переснят с окончательной версией …_fresh_overwrite_untouched против src 16f2cde (git archive), 2 из 2 упали по ожидаемым причинам (evidence/tests/failure-checks.md); образ mtusi-messenger:lab4 затем пересобран из ca0c4b2. make bench_reconcile_quick (на дереве точки 1) — код 0 за 3,7 мин; на шумном хосте новая пометка bg_dropped (45 недосланных итераций).

Вопросы

Нет. Вопрос 1 раздела ### track2-reconciler (ответ API на потерянный оригинал) открыт и касается и класса «другой SHA-256». Ответ меняет ту же ветку open_content, а не решения этого change.