103 KiB
План лабы 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 serverLB 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 переделывать.
Гипотезы (до прогонов коммитятся отдельно)
- Линейность. Время обхода растёт линейно по числу объектов, цена на объект от N почти не зависит.
- Батч против точечной сверки. Сверка страницы LIST (до 1000
ключей) одним запросом к БД (
object_key = ANY(...)) дешевлеHEADна каждую строку: запросов N/1000 против N. - Поверхностная против глубокой. Размер из LIST почти бесплатен; SHA-256 требует прочитать каждый объект и упирается в чтение S3 — глубокая сверка выборочная или по требованию.
- Влияние на рабочий трафик. Обход с ограниченной скоростью ухудшает p95 фоновой нагрузки API не больше порога, заданного до прогона.
- Безопасность. Ни одно подтверждённое и ни одно используемое в сообщениях вложение не удаляется при любой гонке с загрузками.
Методика (предварительно)
- Стенд
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 иmigrateS3-секретов не получают. .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_ids0–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.peakcgroup реплики и сэмплер, 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.
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.
-
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). -
Три места, где SeaweedFS по умолчанию не приватен (решения 1, 3):
- без учётных записей S3 открыт анониму → административная пара в окружении сервера с первого старта;
- master, filer и volume слушают все интерфейсы →
-ip.bind=127.0.0.1, в сеть выходит только шлюз S3; - gRPC-порт шлюза без ключа подписи принимает от любого контейнера
учётную запись администратора (воспроизведено) → обязательный
S3_JWT_SIGNING_KEY.
Выключены ещё телеметрия, Iceberg, Lance и встроенный IAM API.
-
Root по решению 5 выше (решение 3). Административную пару хранит только сервер
s3: без неё S3 открыт. Bootstrap работает не ею, аweed shellна loopback сервера с ключом подписи. У API и будущего уборщика административной пары нет. -
Права API — политика
s3:GetObject,s3:PutObject,s3:DeleteObjectна<bucket>/*, у bucket нет владельца (решение 3). Пользователь уборщика появится вupload-consistency. -
Bootstrap — сервис
s3-bootstrapсnetwork_mode: service:s3(решение 4):- сводит состояние к
.env, в том числе новый секрет API; - сам проверяет приватность при каждом запуске;
make s3_check— те же проверки с хоста и из сети (решение 8).
- сводит состояние к
-
Отдельной сети для S3 нет: служебные порты закрыты loopback и ключом подписи (решение 1).
-
Клиент — aiobotocore 3.9.2 (решения 6, 7):
- без повторов, срок на каждый вызов;
- отказ, таймаут и отказ в учётных данных — 503;
- ключи объектов с префиксом имени базы.
Отвергнуты boto3 в потоке, aioboto3, своя подпись, obstore и minio-py.
-
Память S3 (решение 2): лимит 512 МБ,
GOMEMLIMIT=400MiBи-s3.concurrentUploadLimitMB=64. Без них 20 одновременных загрузок по 10 MiB дают OOM-kill. Числа уточняетupload-memory. -
Остановка и перезапуск (решения 1, 2):
stop_grace_period: 20s— плавная остановка SeaweedFS занимает ~15 с, срок зашит в filer; на стенде отказов — 2 с;-master.electionTimeout=1s— перезапуск ~7 с вместо ~24 с.
-
Стенды (решение 9):
test_isolated— S3 рабочего стенда, префиксtest_<db>/, уборка черезfs.rm;failure_checks— свой S3 и проверка готовности без него;bench/— секреты на прогон и фильтр секретов в паспорте; профили лаб 2–3 S3 не запускают, методика прежняя;rolling-update.shbootstrap не запускает: bootstrap, как миграции, только расширяет права.
-
Проверка рестарта без публичного теста (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».
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.- Bootstrap — режимы
apply,check,cleanup: проверки с хоста и из сети идут между записью проверочного объекта и его удалением. Новый секрет API распознаётся поSignatureDoesNotMatch. - Клиент:
open()читает тело блоками, срок — на каждый блок; ключи в botocore передаются всегда, даже пустые. - Ожидаемо красные шире списка tasks: контракт лабы 4 требует
attachment_idsвMessage, код лабы 3 его не отдаёт — доattachmentsкрасные 32 теста (и 2 ошибки)make student_testчерез LB (вmake test_isolated— 29 и 2) и 5 проверокmake failure_checks. От S3 не зависит. - Дельта
healthсинхронизирована в основной спек в apply, как вscaling-bench: иначе маркер нового сценария — ссылка на неизвестный сценарий в сверке покрытия. rollout_from c50b721— дефект переноса (KNOWN_ISSUES.md): профильrolloutпроверен с--from 5d5d8f9.
Приняты 2026-10-20 в правках по /opsx:verify (tasks.md, группа 7),
подробности — design change s3-storage, «Уточнения apply», п. 8–13.
- Healthcheck S3 ждёт регистрации тома (
/dir/status, непустойDataNodes): первая запись после рестарта — 10–40 мс вместо до 4,8 с при сроке 5 с. Та же проба — вfault_hook.py. tmpfs: [/tmp, /data]уs3-bootstrap: без анонимного volume на каждый контейнер.- Клиент S3: удалённый bucket и отказ в доступе — 503 с
error(«bucket is missing», «denied access»), а не «объекта нет» и не «rejected credentials»;deleteглушит только отсутствующий ключ. Ограничение: HEAD без тела, удалённый bucket уhead—None. make test_isolatedпроверяет уборку префикса (fs.lsпослеfs.rm): код 0weed shellуспеха не значит.make s3_checkберёт порты изnetstatконтейнера S3, а не из фиксированного списка; проверка готовности без S3 — и дляpause.
Вопросы
-
Как в 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; (в) — только по просьбе пользователя. - (а) пользователь сам переносит блок из
-
attachment_idsотсутствует в ответах Message (код лабы 3), и поэтому до changeattachmentsкрасные 32 тестаmake student_testи 5 тестовmake failure_checks(решение 15). Добавлять ли пустой список раньше?Ответ пользователя 2026-10-20: нет, красное до
attachments. Поле приходит целиком вattachments(запрос, ответ, хэш идемпотентности), там же evidence тестов переснимается зелёным. -
Когда чинить
rollout_from c50b721(решение 17,KNOWN_ISSUES.md)?Ответ пользователя 2026-10-20: в change
attachments: он добавляет миграцию, и rollout со старого образа на новую схему — нужное evidence. До тех пор запись остаётся вKNOWN_ISSUES.md. -
HEAD при удалённом bucket даёт
None, как отсутствующий ключ: SeaweedFS отвечает на HEAD одним и тем же 404 без тела (решение 21, design «Уточнения apply» п. 10). Нужен ли лишний GETRange: 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.
-
Строка
pendingдо PUT — уже здесь (решение 1). Порядок: проверки →pendingс ключом объекта (commit) → PUT →ready(commit) → 201. При отказе S3 или БД после шагаpending— 503, строка остаётся.upload-consistencyдобавит компенсацию, уборщик и тесты отказов посреди загрузки, порядок шагов не меняя. -
Проверка изображения — структура без декодирования (решение 2), своя функция на stdlib:
- PNG: CRC чанков, поток IDAT распаковывается ровно в объём по размерам, типы фильтров строк;
- JPEG: маркеры, один кадр, скан, EOI;
- пиксели — из заголовка до распаковки.
Проба: 12 000 настоящих файлов без ложных отказов, память проверки до 3,5 MiB, «бомба» отсекается за доли миллисекунды. Pillow — только dev-группа, для JPEG в тестах. Поведение для клиента подтвердил пользователь («Вопросы», п. 1).
-
Схема (решение 3):
- таблицы
attachmentsиmessage_attachments— порядокposition, FK без каскада: вложение со ссылкой из сообщения БД удалить не даст; - ограничение текста сообщения ослаблено до 0–4000 с
NOT VALID, без сканаmessagesпод эксклюзивной блокировкой (дельтаdb-migrations); - чат вложения = чат сообщения проверяет сервис в той же транзакции.
Отвергнуты массив id в
messages, составной FK с третьим индексом наmessagesи типENUM. - таблицы
-
Ключ объекта —
<база>/attachments/<id>/original, хранится вobject_key(уникальный) (решение 4). -
Загрузка и скачивание не держат сессию БД (решение 5). Найдено:
get_db_sessionдержит соединение пула и срок 6 с до конца отправки ответа, и передача 10 MiB медленному клиенту оборвалась бы на 6-й секунде. Поэтому:db_session_scope()на каждый шаг с БД;- вход
CurrentUserBriefс короткой сессией; AttachmentService(db_scope, cache, storage).
-
Ответы до чтения тела (решение 6, проба). Ранние 404, 413 и 415 получают httpx, curl и любой клиент через LB.
urllibнапрямую к одной реплике ответ теряет — ограничение вREPORT.md. Медленные 10 MiB через LB проходят: таймауты HAProxy — простой, а не длительность. -
Порядок проверок загрузки: 401 → 400 → 404 → 415 (
Content-Type) → 413 (Content-Length) → тело (спек «Порядок проверок загрузки»). -
Скачивание (решение 7):
- поток из S3, отказ S3 — 503 до заголовков;
- заголовок
X-Content-Type-Options: nosniff; variantкромеoriginal— 400 по перечислению контракта лабы 4;- строка
readyбез объекта или с другим размером — 500 иerrorв журнале, строка не меняется.
-
Хэш идемпотентности (решение 9): пустой
attachment_idsхэш не меняет, id в нижнем регистре, порядок значим. -
Лимиты 10 MiB и 40 млн пикселей — константы, не настройки (дельта
service-configuration), соответствиеMAX_UPLOAD_BYTESиMAX_IMAGE_PIXELS— вREPORT.md. -
rollout_from = e1161f7— последний commit лабы 4 до этого change (решение 14). Проверка commit до стенда, правило — вbench.md, запись вKNOWN_ISSUES.mdудаляется в apply. -
Дельты синхронизируются в основные спеки в apply, как
healthвs3-storage: сверка покрытия читает толькоopenspec/specs/. -
Проверки отказов вложений — через hook стенда отказов: счётчики вложений по статусам и объектов в bucket (решение 12).
Уточнения apply (2026-10-20/21, design change attachments, «Уточнения
apply»):
- Текст из пробелов с вложением — 201 по ответу преподавателя («Вопросы», п. 2); без вложений — 400. Текст не нормализуется.
- Проверка изображения на готовом модуле повторила пробу: 17 вариантов, корпус 12 000 файлов без ложных отказов, «бомба» за 1 мс, пик памяти ≤ 3,2 MiB. Вход IDAT — кусками по 64 KiB.
- План истории: на пустой
message_attachmentsстендаbench/SubPlan—Seq Scanпустой таблицы; с данными —pk_message_attachments, индекс истории прежний. variantв/openapi.json—enum ["original"]черезjson_schema_extra: Literal pydantic пишетconst.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):
- Память загрузки — одно тело, а не два. Тело копится в
io.BytesIO,getvalue()отдаётbytesбез копии (bytearraybotocore копирует). В образе —MALLOC_MMAP_THRESHOLD_=131072: с динамическим порогом glibc вторая загрузка росла в куче, иreallocна миг держал два тела. Замер в образе: RSS 1,99 → 1,19–1,20 тела на каждой из трёх загрузок подряд. Буфер подContent-Lengthзаранее не выделяется: заявивший 10 MiB клиент держал бы их без передачи. - «Бомба» распаковывается до ожидаемого объёма + 1 байт, а не до 1 MiB: предел блока zlib — остаток ожидаемого плюс байт. Корпус 11 993 файлов — вердикты те же.
- «Старый образ на новой схеме» переформулирован: проверки, которые
прежний образ проходил на прежней схеме, проходят и на новой;
доказательство — замер
rollout(переснять с чистого дерева после commit правок). filenameне в UTF-8 — 400 (a%FFb.pngдавал 201 с U+FFFD): ручка строго разбирает строку запроса, новый сценарий «Имя не в UTF-8».- «Окружение не меняет лимит» проверяет тест
fault: обычный API стенда отказов — сMAX_UPLOAD_BYTES=1иMAX_IMAGE_PIXELS=1. - Мёртвые константы
MESSAGE_TEXT_MIN_LENGTHиATTACHMENT_READ_CHUNK_BYTESудалены: блок чтения задаёт uvicorn. - Невидимость
pendingчерез API (S6) — не здесь: задачаupload-consistency(раздел «Последовательность работ», п. 3).
Вопросы
-
Что считать «повреждённым изображением» (решение 2, спек
attachments, «Повреждённое изображение»)? По умолчанию — структурная проверка без декодирования пикселей:- 415 — обрезанный файл, битая CRC, сломанные маркеры, поток zlib не того объёма, «бомба»;
- байты после IEND или EOI принимаются как часть оригинала;
- изменённый байт внутри данных скана JPEG не ловится. У формата нет контрольной суммы, Pillow его тоже не ловит.
Альтернатива — полное декодирование Pillow. Оно стоит до 160 МБ на загрузку при лимите реплики 512 МБ, требует семафора уже в этом change и ловит не больше.
Ответ пользователя 2026-10-20: структурная проверка, как по умолчанию. Менять ничего не нужно.
-
Текст из одних пробелов вместе с вложением. По умолчанию — 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 changeattachments, решение 8), вREPORT.md— как согласование. -
Опасный
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):
- PUT подтверждён, а
readyне зафиксирован до отправки COMMIT, или строку уже убрал уборщик — объект удаляется до ответа 503; - исход COMMIT неизвестен — объект не трогается;
- после неудачного PUT компенсации нет: при замороженном S3 ответ стал бы 10 с, а позднего объекта по пробе нет (тело не уходит без ответа сервера);
- строку компенсация не удаляет, её убирает уборщик.
mark_ready→None— 503 вместо 500. - PUT подтверждён, а
-
Уборщик — сервис
cleaner,python -m src.cleaner(решение 2):- свой engine (пул 1) и клиент S3, цикл с интервалом,
--once; - SIGTERM — довести текущий шаг строки и выйти с кодом 0;
- healthcheck образа выключен;
- в консоли (
make run_dev) уборщика нет.
- свой engine (пул 1) и клиент S3, цикл с интервалом,
-
Проход (решение 3): строка под
FOR UPDATE SKIP LOCKED→ DELETE объекта → DELETE строки → commit. Блокировка упорядочивает уборщика иmark_readyзагрузки, пережившей grace. Остаток риска: API заморожен дольше grace посреди PUT — объект без строки, его находит сверка трека 2. После verify — пометка строки отдельной транзакцией до DELETE объекта (решение 18 ниже), после повторного — объект и строка одной транзакцией под блокировкой (решение 23). -
Grace 900 с, интервал 60 с, выборка 100 (решение 4):
- граница живой загрузки от строки до
ready: B = 2 × 6 + 5 = 17 с, запас ×50; - при grace ≤ B уборщик не стартует;
- стенд отказов — 20 с и 1 с.
- граница живой загрузки от строки до
-
Права уборщика в S3 (решение 8) —
s3:GetObjectиs3:DeleteObjectна объекты своего bucket, как задано пользователем («чтение/удаление»). Чтение пока не используется: HEAD не нужен, это задел глубокой сверки трека 2. List — вtrack2-reconciler, если понадобится. Проба: одного Delete хватает, DELETE отсутствующего — 204, удалённого bucket —NoSuchBucket(503). -
Частичный индекс строк
pendingпо(created_at, id)—CONCURRENTLYвautocommit_block(решение 6). Проба с асинхроннымenv.pyпрошла: с нуля, повтор, откат. -
Общий
session_scopeвsrc/infra/db/для API и уборщика (решение 7). -
Hook — списки
idвместо счётчиков (решение 10):- SeaweedFS убирает пустой каталог
<id>/лишь через ~2 мин после DELETE, а уборщик меняет счётчики параллельно с тестами. Объекты считаются по файламoriginal; - новые действия:
attachment-ids,last-pending(замечание S6),object-ids,fail-attachments insert|ready|stall,kill-apiиstart-api. Отказ триггера — SQLSTATE08006, для API это 503 (проба).
- SeaweedFS убирает пустой каталог
-
Тесты отказов (решение 10):
- пять новых тестов и три изменённых,
make failure_checksдольше ~2 мин; - «реплика убита» — между PUT и фиксацией (задержка в триггере), а не во время PUT: так проверяется ровно «PUT прошёл, COMMIT нет».
- пять новых тестов и три изменённых,
-
restart.shиrolling-update.shне меняются (решение 9): рестарт хранилищ уборщик переживает сам, новый код уборщика —docker compose up -d --no-deps cleaner. -
Для
upload-memory. Ожидание междуpendingиready(очередь загрузок) расширяет границу B. Проверку grace и решение 4 designupload-consistencyобновить в том же change.
Приняты 2026-10-21 в /opsx:apply (подробности — design, «Уточнения
apply»):
make env_setupдописывает в существующий.envнедостающие переменные шаблона (ответ на вопрос 1): секреты — случайными, остальные — значениями шаблона, прежние строки не меняются, в вывод — только имена. Правилоsettings.mdи дельтыservice-configuration/container-runобновлены (новый сценарий «Недостающие переменные в существующем.env»).- Статус в запросах уборщика — константа (
literal_execute): общий план asyncpg иначе не взял бы частичный индекс. План —Index Scanпоix_attachments_pending_created_at. - SIGTERM посреди прохода —
stop_requestedуclean_stale_pending: текущий шаг строки доводится до commit или отката, новые не начинаются (после решения 19). - Неверные настройки уборщика — запись без значений полей и код 2, а не traceback.
entrypointу сервисаcleaner, чтобыdocker compose run --rm --no-deps cleaner --onceпередавал флаг уборщику.- Красный прогон новых тестов отказов против прежнего кода: 4 из
11 упали (компенсация и уборка), остальные закрепляют уже
выполнявшееся поведение. Полный
make failure_checks— 29 passed, ~3,5 мин.
Приняты 2026-10-21 в правках по verify (решения основной сессии; design, «Уточнения apply», п. 16–20; tasks, группа 11):
- W1 — пометка строки до удаления объекта вместо одной транзакции
уборщика: блокировка →
updated_at = utcnow()→ commit; DELETE объекта; блокировка → DELETE строки → commit.mark_ready— только приupdated_at = created_at. Без миграции. Откат транзакции уборщика после удачного DELETE в S3 больше не даётreadyбез объекта. Остаток — окноmake rolling_update(прежние реплики и уборщик) и объект без строки, если зомби дописал объект после уборки, а компенсация не удалась. - SIGTERM уборщика — между шагами строки: три шага удлинили бы
худшую остановку до 17 с (после решения 23 шагов два — до 12 с);
доводится только текущий шаг (≤ 6 с).
Требование
graceful-shutdown«Остановка уборщика» уточнено. - W2, W3 — режимы hook
commitиoutliveи тесты веток «исход COMMIT неизвестен» и «строку убрал уборщик доready»; W1 — режимundeletable. Ожидание перевода вready— триггерBEFORE UPDATE OF statusуровня оператора: пометку уборщика он не задерживает. - Новые сценарии — «Исход фиксации неизвестен» (
attachments), «Загрузка дольше grace» и «Сбой уборки после удаления объекта» (storage-consistency), в дельтах и основных спеках. - W4 и S1 — evidence «Отказ S3 во время прохода» с закоммиченного
кода;
docker.md—entrypointуборщика.
Приняты 2026-10-21 в правках по повторному verify (решения основной сессии; design, «Уточнения apply», п. 21; tasks, группа 12):
- W1 повторной проверки — два шага вместо трёх: транзакция
пометки, затем объект и строка одной транзакцией под блокировкой
(как в
f2dc0b3, но на помеченной строке). В решении 18 объект удалялся без блокировки, и реплика до87c48b9успевала сделать строкуreadyпрямо перед удалением объекта — смесь «новый уборщик + прежние реплики» была хуже, чем до правки. Теперь обе смеси не хуже, чем до правки (проба блокировок — design, п. 21), остаётся только откат транзакции уборки после удачного DELETE. Цена — вызов S3 внутри транзакции (≤ 5 с <idle_in_transaction_session_timeout10 с). Решения 18 и 19 в части «три шага» заменены этим. - Порядок обновления: вперёд — сначала реплики (
make rolling_update), потомdocker compose up -d --no-deps cleaner; откат реплик на версию раньше87c48b9— сначала уборщик (balancer.md,REPORT.md). - Тесты 11.x не менялись:
undeletableна двухшаговой схеме роняет DELETE строки в той же транзакции, что DELETE объекта, — это тот же откат после удачного DELETE в S3; красный прогон наf2dc0b3в силе. Требованияgraceful-shutdownиstorage-consistencyне менялись.
Вопросы
-
Как перенести секреты уборщика
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_*этой командой. - По умолчанию — как в ответе на вопрос 1
upload-memory
Решения
Приняты 2026-10-21 в /opsx:propose, подробности — design change
upload-memory. Пробы — design, Context: проект compose umprobe,
реплика 1 CPU / 512 МБ, прототип в копии дерева в scratchpad.
- Проба опровергла «~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.
- при PUT aiohttp копирует тело (
- Места загрузки — на процесс API (решение 1): 4 места, очередь до
16, ожидание до 5 с по порядку прихода. Отвергнуты очередь в LB
(второй набор слотов ломал бы замену реплик и профили лабы 3),
--limit-concurrencyuvicorn, места по байтам и общий счётчик в Valkey или PostgreSQL. - Ответ при занятых местах — 429
rate_limited,Retry-After: 1(решение 2) — до ответа на вопрос 1 ниже. Очередь, а не сразу 429: сообщение несёт до 10 вложений, и 10–20 одновременных загрузок по 10 MiB на пробе проходят все. - Место — после проверок 401/400/404/415/413 и до тела, держится до
ответа (решение 3). Граница уборщика B = 17 с не меняется:
ожидание, тело и проверка — до
created_at, сроки tx1, PUT и tx2 прежние. Проверка grace и стенд отказов (20 с) остаются. Свойство закреплено сценариемstorage-consistencyи тестом:created_atожидавшей позжеupdated_atтой, что держала место. - Срок тела — 30 с с момента, как загрузка заняла место, иначе 400
invalid_request(решение 4), по образцу обрыва тела. 408 в контракте ручки нет. Срок простоя между блоками отвергнут: клиент по байту раз в 29 с держал бы место вечно. - В PUT уходит тот же
BytesIO(решение 5): после проверки ссылка наbytesудаляется, буфер снова не общий. Проба — 1,19 тела вместо 2,0–2,3, SHA-256 объекта совпал. - Буферы ядра (решение 6): у
api—net.ipv4.tcp_rmemдо 512 KiB (sysctlsв compose), у LB —tune.sndbuf.server 262144. При 40 загрузкахsockреплики — 17 MiB вместо 134, пик LB — 51 MiB вместо 109. Скорость загрузки одного клиента та же. - Цепочка таймаутов пути загрузки (решение 7):
timeout serverLB дляPOST …/attachments— 30 с: молчание до тела ≤ 17 с, после ≈ 26 с; остальные пути — прежние 10 с;- ответ LB 400 — в формате контракта;
ROLLOUT_DRAIN_TIMEOUT— 90 с, больше наибольшей длительности загрузки ~73 с;- 408 на медленные заголовки остаётся HTML:
http-errorего не меняет, запись вKNOWN_ISSUES.md.
- S3 без изменений (решение 8): лимит загрузок шлюза 64 МБ,
GOMEMLIMIT, 512 МБ и общий срок вызова 5 с. При 12 одновременных PUT (три реплики × 4 места) p95 — 1,6–1,9 с. Отдельный срок PUT не нужен — это закрывает открытый вопрос designattachments. - Профиль
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): в
make student_test— 10 одновременных загрузок. Вmake failure_checks— третий API с 1 местом, 1 в очереди, ожиданием 1 с и сроком тела 2 с, пять тестов. Сценарии памяти — исключения сверки со ссылкой на метку профиля. - Драйвер
lb-upload-timeouts(решение 7): сроки LB на заглушке заhaproxy.cfgпроекта. Evidence —evidence/uploads/lb-timeouts.md.
Приняты 2026-10-21 в /opsx:apply (подробности — design, «Уточнения
apply»; вопрос 1 открыт — сделано 429, как по умолчанию):
- Красный прогон — 5 из 5 новых тестов отказов на
f894040(п. 2):test_rejections_before_queueпроверяет и полноту очереди (429 ожидавшей),test_slot_released_after_failuresвключает шаг «400 по сроку тела» — оба поэтому красные на прежнем коде, а не зелёные, как ждали tasks. На дереве — все пять зелёные. - Тесты мест под срок тела стенда 2 с (п. 1, 3): держатель места
отпускается сразу после 429 ожидавшей, сверка — «новые
id— только держателя»; ранние отказы быстрее срока ожидания (1 с), а не 0,5 с. - Одна копия тела подтверждена до профиля: PUT 10 MiB в образе API против S3 стенда — 1,19 тела над базой против 2,31 у прежнего пути, SHA-256 совпал.
- Тип мест в сервисе — под
TYPE_CHECKING,Retry-After— таблицаRETRY_AFTERвerrors.py,UploadsBusyжурналирует сервис (п. 4–6). - Драйвер
lb-upload-timeouts(п. 8): пять случаев параллельно, ~33 с; код 0 на текущемhaproxy.cfg, код 1 наf894040(502 и 504 через 10 с, 400 HTML). - Профиль
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). - Буфер приёма 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 на клиента. - Метка
baselineна97a4be4принята с пометкой (решение пользователя 2026-10-22, commitce1ae2c). В паспорте — предупреждение «host swapped out 7464 pages»: вся выгрузка пришлась на прогонlimited-10MiB-c40-r2(host_swap). Пик памяти в нём как у повторов, искажено только время (9,95 загрузки/с против ~11,0, p95 2 815 мс против ~2 050); медиана ячейки и выводы H1–H4 от него не зависят. Предупреждение названо вREPORT.md. - Правки по verify (2026-10-22, tasks, группа 11; design, «Уточнения
apply», пп. 12–16). Метка
baselineне переснимается; числа, которых нет в её сводке,REPORT.mdдаёт формулой из её ячеек.- Разбор сводки: H1 считает 429, OOM и 5xx только по ячейкам
гипотезы (10 MiB, C = 10, 20, 40: у
baseline429 — 1 351, а не 2 731 обоих тел) и печатает рост сверх C = 10 на клиента; «Буферы соединений ограничены» — своя строка с вердиктом по сумме роста LB иsockреплики от C = 1 до 40 (уbaseline0,56 + 0,39 = 0,95 MiB при пороге 1). - Спеки: в требовании срока пути загрузки — буфер приёма LB от клиента 128 KiB; «Лимит размера до чтения тела» — одна копия тела и блоки чтения, рост пика ≤ 1,5 тела (как в сценарии).
- Проверки соотношения
wait_timeout_secondsиtimeout serverLB при старте нет: LB-значение API не знает; соотношение — вsettings.mdиconfig_example.toml. - Срок тела «узкого» API стенда отказов — 3 с вместо 2 с: запас
держателя места в
test_upload_slots_busyбыл ~0,5 с. Evidencefailure-checks.md— переснять после commit. REPORT.md: таблица 1 MiB, числа и commit строк тестов (ce1ae2c), ограничение «оборванный клиент в очереди держит место очереди до срока ожидания».
- Разбор сводки: H1 считает 429, OOM и 5xx только по ячейкам
гипотезы (10 MiB, C = 10, 20, 40: у
Вопросы
-
Какой код отдавать, когда все места загрузки реплики заняты и очередь полна или ожидание истекло: 429
rate_limitedили 503unavailable? Контракт (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. - 429 описан как «Ограничение частоты запросов», у него одного есть
заголовок
track2-reconciler
Решения
Приняты 2026-10-22 в /opsx:propose, подробности — design change
track2-reconciler. Пробы — design, Context: проект compose rcprobe,
SeaweedFS и PostgreSQL на tmpfs, bootstrap проекта.
-
Сверка — часть уборщика (решение 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и пометка), а объект строки любого статуса не удаляет никогда. - команда
-
Права 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):
- страницы LIST по 1000;
- на страницу — одно выражение к БД по
id(по тексту ключа — только для нестандартных ключей: по пробе в 15 раз дороже); - множество увиденных ключей, затем keyset строк
readyпоid.
Слияние отсортированных потоков отвергнуто: порядок списка SeaweedFS — обход каталогов, а не порядок байтов (проба). Действия — только после классификации, каждое с перепроверкой в БД и HEAD.
-
Безопасность (решение 4):
- grace уборщика по
LastModifiedобъекта и времени строки; - удаляются только объекты без строки и зависшие загрузки;
- чужие ключи — только отчёт и код 3;
- отсутствие объекта не подтверждается без проверки bucket;
- предел
[reconciler] max_changes(100): больше — ни одного изменения, код 3.
- grace уборщика по
-
Потерянный оригинал (решение 5) — колонка
attachments.lost_at.statusиupdated_atне меняются. Ответы API:- скачивание помеченного — 404 без обращения к S3, до пометки — 500, как было;
- метаданные — 200;
- ссылка в сообщении — 201.
Это вариант по умолчанию до ответа на вопрос 1 ниже. Статус
lost/failedотвергнут: контракт лабы 4 знает толькоready. -
Миграция (решение 6) —
ADD COLUMN lost_atсSET LOCAL lock_timeout. По пробе это только каталог: 0,36 мс. Смеси версий не хуже, чем до change. Порядок обновления:- вперёд —
s3-bootstrap,make rolling_update, затем уборщик; - откат — сначала уборщик.
- вперёд —
-
Коды разового прохода (решение 8): 0 — расхождений нет, 3 — остались (в том числе чужой объект или отказ по пределу), 1 — прерван, 2 — конфигурация.
-
Стенд отказов (решения 9, 11):
- плановая сверка выключена (
RECONCILER__INTERVAL_SECONDS=0); - сверку запускает hook;
- новые действия hook: объект мимо API, удаление объекта, строки и
размера, сдвиг времени строки,
lost-ids,fail-attachments mark,reconcile,stop|start cleaner,run-cleaner; - восемь тестов отказов, ~+3 мин; объекты без строки ждут grace, а строки состаривает hook.
- плановая сверка выключена (
-
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. -
Граница с
track2-reconcile-cost(решение 13). Здесь — одна стратегия «батч» и поверхностная сверка (наличие и размер). Там:- HEAD на строку;
- глубокая сверка SHA-256;
- ограничение скорости;
- профиль
reconcileстендаbench/; - гипотезы 1–4.
Гипотезу 5 проверяет стресс этого change.
-
Запись
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 её текст переписывается, запись остаётся открытой.
-
Решения 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 мс, keysetready— Index Scanpk_attachments, 0,57 мс; - hook
start cleaner—docker startконтейнера (compose startтребует контейнерmigrate); - драйвер на рабочем стенде — только после перестройки 12.1; в apply он проверен на временном полном стенде.
Вопросы
-
Вопрос преподавателю. Что отвечает 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), байты — 404not_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 и 8driver.py reconcile-cycle, правилоapi-contract.md.