Files
mtusi2026lab4/PLAN.md
T
ricoromaandClaude Opus 5.5 87c48b940b fix: address upload-consistency verify findings
Mark a stale pending row in its own committed transaction before the
cleaner deletes the object, and let mark_ready promote only unmarked
rows, so a cleaner rollback after the object delete can no longer leave
a ready attachment without its object. Add fault checks for an unknown
COMMIT outcome, an upload outliving the grace period and a cleaner
failure after the object delete; fix the cleaner entrypoint in rules.

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

921 lines
73 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/` (`failure_checks` 29 из 29, `student_test` 197, сверка 212 / 33, `test_isolated` 192 + 5 пропусков); `REPORT.md` — раздел «Согласованность БД и S3», ответ на вопрос «PUT прошёл, COMMIT нет», строки уровня «4»** |
| 4 | `upload-memory` | 4 | лимит загрузок на реплику, сроки тела, профиль `uploads` | замер ≥ 10 одновременных загрузок: пик памяти ограничен, механизм объяснён |
| 5 | `track2-reconciler` | 5 | reconciler: dry-run / apply, классы расхождений, внедрение ошибок, доказательство безопасности | ошибки внесены с обеих сторон, обнаружены, исправлены; повторный запуск находит 0; под загрузками ничего подтверждённого не удалено |
| 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`.
### 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 ниже).
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`: строка доводится, новые не берутся.
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 с; доводится только текущий шаг (≤ 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` уборщика.
#### Вопросы
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_*` этой командой.