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

1293 lines
106 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# План лабы 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».
12. **`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`.
13. **Bootstrap — режимы `apply`, `check`, `cleanup`**: проверки с хоста и
из сети идут между записью проверочного объекта и его удалением.
Новый секрет API распознаётся по `SignatureDoesNotMatch`.
14. **Клиент**: `open()` читает тело блоками, срок — на каждый блок;
ключи в botocore передаются всегда, даже пустые.
15. **Ожидаемо красные шире списка tasks**: контракт лабы 4 требует
`attachment_ids` в `Message`, код лабы 3 его не отдаёт — до
`attachments` красные 32 теста (и 2 ошибки) `make student_test`
через LB (в `make test_isolated` — 29 и 2) и 5 проверок `make
failure_checks`. От S3 не зависит.
16. **Дельта `health` синхронизирована в основной спек в apply**, как в
`scaling-bench`: иначе маркер нового сценария — ссылка на
неизвестный сценарий в сверке покрытия.
17. **`rollout_from c50b721` — дефект переноса** (`KNOWN_ISSUES.md`):
профиль `rollout` проверен с `--from 5d5d8f9`.
Приняты 2026-10-20 в правках по `/opsx:verify` (tasks.md, группа 7),
подробности — design change `s3-storage`, «Уточнения apply», п. 8–13.
18. **Healthcheck S3 ждёт регистрации тома** (`/dir/status`, непустой
`DataNodes`): первая запись после рестарта — 10–40 мс вместо до
4,8 с при сроке 5 с. Та же проба — в `fault_hook.py`.
19. **`tmpfs: [/tmp, /data]` у `s3-bootstrap`**: без анонимного volume на
каждый контейнер.
20. **Клиент S3**: удалённый bucket и отказ в доступе — 503 с `error`
(«bucket is missing», «denied access»), а не «объекта нет» и не
«rejected credentials»; `delete` глушит только отсутствующий ключ.
Ограничение: HEAD без тела, удалённый bucket у `head` — `None`.
21. **`make test_isolated` проверяет уборку префикса** (`fs.ls` после
`fs.rm`): код 0 `weed shell` успеха не значит.
22. **`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»):
14. **Текст из пробелов с вложением — 201** по ответу преподавателя
(«Вопросы», п. 2); без вложений — 400. Текст не нормализуется.
15. **Проверка изображения на готовом модуле** повторила пробу: 17
вариантов, корпус 12 000 файлов без ложных отказов, «бомба» за 1 мс,
пик памяти ≤ 3,2 MiB. Вход IDAT — кусками по 64 KiB.
16. **План истории**: на пустой `message_attachments` стенда `bench/`
`SubPlan` — `Seq Scan` пустой таблицы; с данными —
`pk_message_attachments`, индекс истории прежний.
17. **`variant` в `/openapi.json`** — `enum ["original"]` через
`json_schema_extra`: Literal pydantic пишет `const`.
18. **`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):
19. **Память загрузки — одно тело, а не два.** Тело копится в
`io.BytesIO`, `getvalue()` отдаёт `bytes` без копии (`bytearray`
botocore копирует). В образе — `MALLOC_MMAP_THRESHOLD_=131072`: с
динамическим порогом glibc вторая загрузка росла в куче, и `realloc`
на миг держал два тела. Замер в образе: RSS 1,99 → 1,19–1,20 тела на
каждой из трёх загрузок подряд. Буфер под `Content-Length` заранее
не выделяется: заявивший 10 MiB клиент держал бы их без передачи.
20. **«Бомба» распаковывается до ожидаемого объёма + 1 байт**, а не до
1 MiB: предел блока zlib — остаток ожидаемого плюс байт. Корпус
11 993 файлов — вердикты те же.
21. **«Старый образ на новой схеме»** переформулирован: проверки, которые
прежний образ проходил на прежней схеме, проходят и на новой;
доказательство — замер `rollout` (переснять с чистого дерева после
commit правок).
22. **`filename` не в UTF-8 — 400** (`a%FFb.png` давал 201 с U+FFFD):
ручка строго разбирает строку запроса, новый сценарий «Имя не в
UTF-8».
23. **«Окружение не меняет лимит»** проверяет тест `fault`: обычный API
стенда отказов — с `MAX_UPLOAD_BYTES=1` и `MAX_IMAGE_PIXELS=1`.
24. **Мёртвые константы** `MESSAGE_TEXT_MIN_LENGTH` и
`ATTACHMENT_READ_CHUNK_BYTES` удалены: блок чтения задаёт uvicorn.
25. **Невидимость `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»):
12. **`make env_setup` дописывает в существующий `.env` недостающие
переменные шаблона** (ответ на вопрос 1): секреты — случайными,
остальные — значениями шаблона, прежние строки не меняются, в вывод
— только имена. Правило `settings.md` и дельты
`service-configuration` / `container-run` обновлены (новый сценарий
«Недостающие переменные в существующем `.env`»).
13. **Статус в запросах уборщика — константа** (`literal_execute`):
общий план asyncpg иначе не взял бы частичный индекс. План — `Index
Scan` по `ix_attachments_pending_created_at`.
14. **SIGTERM посреди прохода** — `stop_requested` у
`clean_stale_pending`: текущий шаг строки доводится до commit или
отката, новые не начинаются (после решения 19).
15. **Неверные настройки уборщика** — запись без значений полей и код 2,
а не traceback.
16. **`entrypoint` у сервиса `cleaner`**, чтобы `docker compose run
--rm --no-deps cleaner --once` передавал флаг уборщику.
17. **Красный прогон** новых тестов отказов против прежнего кода: 4 из
11 упали (компенсация и уборка), остальные закрепляют уже
выполнявшееся поведение. Полный `make failure_checks` — 29 passed,
~3,5 мин.
Приняты 2026-10-21 в правках по verify (решения основной сессии;
design, «Уточнения apply», п. 16–20; tasks, группа 11):
18. **W1 — пометка строки до удаления объекта** вместо одной транзакции
уборщика: блокировка → `updated_at = utcnow()` → commit; DELETE
объекта; блокировка → DELETE строки → commit. `mark_ready` — только
при `updated_at = created_at`. Без миграции. Откат транзакции
уборщика после удачного DELETE в S3 больше не даёт `ready` без
объекта. Остаток — окно `make rolling_update` (прежние реплики и
уборщик) и объект без строки, если зомби дописал объект после
уборки, а компенсация не удалась.
19. **SIGTERM уборщика — между шагами строки**: три шага удлинили бы
худшую остановку до 17 с (после решения 23 шагов два — до 12 с);
доводится только текущий шаг (≤ 6 с).
Требование `graceful-shutdown` «Остановка уборщика» уточнено.
20. **W2, W3 — режимы hook `commit` и `outlive`** и тесты веток «исход
COMMIT неизвестен» и «строку убрал уборщик до `ready`»; W1 — режим
`undeletable`. Ожидание перевода в `ready` — триггер `BEFORE UPDATE
OF status` уровня оператора: пометку уборщика он не задерживает.
21. **Новые сценарии** — «Исход фиксации неизвестен» (`attachments`),
«Загрузка дольше grace» и «Сбой уборки после удаления объекта»
(`storage-consistency`), в дельтах и основных спеках.
22. **W4 и S1** — evidence «Отказ S3 во время прохода» с закоммиченного
кода; `docker.md` — `entrypoint` уборщика.
Приняты 2026-10-21 в правках по повторному verify (решения основной
сессии; design, «Уточнения apply», п. 21; tasks, группа 12):
23. **W1 повторной проверки — два шага вместо трёх**: транзакция
пометки, затем объект и строка одной транзакцией под блокировкой
(как в `f2dc0b3`, но на помеченной строке). В решении 18 объект
удалялся без блокировки, и реплика до `87c48b9` успевала сделать
строку `ready` прямо перед удалением объекта — смесь «новый уборщик +
прежние реплики» была хуже, чем до правки. Теперь обе смеси не хуже,
чем до правки (проба блокировок — design, п. 21), остаётся только
откат транзакции уборки после удачного DELETE. Цена — вызов S3 внутри
транзакции (≤ 5 с < `idle_in_transaction_session_timeout` 10 с).
Решения 18 и 19 в части «три шага» заменены этим.
24. **Порядок обновления**: вперёд — сначала реплики (`make
rolling_update`), потом `docker compose up -d --no-deps cleaner`;
откат реплик на версию раньше `87c48b9` — сначала уборщик
(`balancer.md`, `REPORT.md`).
25. **Тесты 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, как по умолчанию):
13. **Красный прогон — 5 из 5** новых тестов отказов на `f894040`
(п. 2): `test_rejections_before_queue` проверяет и полноту очереди
(429 ожидавшей), `test_slot_released_after_failures` включает шаг
«400 по сроку тела» — оба поэтому красные на прежнем коде, а не
зелёные, как ждали tasks. На дереве — все пять зелёные.
14. **Тесты мест под срок тела стенда 2 с** (п. 1, 3): держатель места
отпускается сразу после 429 ожидавшей, сверка — «новые `id` — только
держателя»; ранние отказы быстрее срока ожидания (1 с), а не 0,5 с.
15. **Одна копия тела подтверждена до профиля**: PUT 10 MiB в образе API
против S3 стенда — 1,19 тела над базой против 2,31 у прежнего пути,
SHA-256 совпал.
16. **Тип мест в сервисе — под `TYPE_CHECKING`, `Retry-After` — таблица
`RETRY_AFTER` в `errors.py`, `UploadsBusy` журналирует сервис** (п.
4–6).
17. **Драйвер `lb-upload-timeouts`** (п. 8): пять случаев параллельно,
~33 с; код 0 на текущем `haproxy.cfg`, код 1 на `f894040` (502 и 504
через 10 с, 400 HTML).
18. **Профиль `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`).
19. **Буфер приёма 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 на клиента.
20. **Метка `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`.
21. **Правки по 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`.