Files
mtusi2026lab4/PLAN.md
T
2026-10-22 21:04:01 +03:00

106 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 нет»; вопрос 1 преподавателю (ответ API на потерянный оригинал) открыт
6 track2-reconcile-cost 5 гипотезы, профиль стоимости обхода, стратегии, графики метки в evidence/, выводы по гипотезам и ограничения в REPORT.md
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.