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>
921 lines
73 KiB
Markdown
921 lines
73 KiB
Markdown
# План лабы 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_*` этой командой.
|