1293 lines
106 KiB
Markdown
1293 lines
106 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/`; `REPORT.md` — раздел «Согласованность БД и S3», ответ на вопрос «PUT прошёл, COMMIT нет», строки уровня «4». Правки по verify (W1–W4, S1) — код `87c48b9`: пометка строки уборщиком до удаления объекта, тесты неизвестного COMMIT, загрузки дольше grace и сбоя уборки после удаления объекта; evidence 2026-10-21 с него: `evidence/tests/` (`failure_checks` 32 из 32, `student_test` 197, сверка 215 / 36, `test_isolated` 192 + 5 пропусков), `cleaner-process.md` раздел 7 (отказ S3 во время прохода); `REPORT.md` — пометка, остаточный риск и окно `rolling_update`. Правки по повторному verify (W1, S1, S2) — код `5889ca2`: уборщик в два шага, объект и строка одной транзакцией под блокировкой, смеси версий не хуже, чем до правки, порядок обновления; evidence 2026-10-21 с него: `evidence/tests/failure-checks.md` (32 из 32 за 228 с), `cleaner-process.md` раздел 7, S2 в `student-test-lb.md` (8 сценариев `storage-consistency`); `REPORT.md` — два шага, «Зачем DELETE объекта под блокировкой», смесь версий; заархивирован 2026-10-21** — `openspec/changes/archive/2026-10-21-upload-consistency/` |
|
||
| 4 | `upload-memory` | 4 | лимит загрузок на реплику, сроки тела, профиль `uploads` | замер ≥ 10 одновременных загрузок: пик памяти ограничен, механизм объяснён; **код — `6cab9d3` (места загрузки, срок тела, одна копия тела при PUT, буферы и сроки LB) и `97a4be4` (буфер приёма LB от клиента 128 KiB); метка `evidence/uploads/baseline/` с `97a4be4` (commit `ce1ae2c`, принята с пометкой о swap хоста); evidence 2026-10-22: `evidence/uploads/lb-timeouts.md` и `rollout-upload.md`, `evidence/tests/` (`student_test` 198, `test_isolated` 193 + 5 пропусков); `REPORT.md` — «Память и сроки загрузки», гипотезы H1–H4 и выводы по метке. Правки по verify — код `9d2ee30`: разбор сводки профиля, спеки буфера LB и одной копии тела, срок тела «узкого» API 3 с; evidence с него: `evidence/tests/failure-checks.md` (37 из 37 за 263 с, commit `569a164`); заархивирован 2026-10-22** — `openspec/changes/archive/2026-10-22-upload-memory/` |
|
||
| 5 | `track2-reconciler` | 5 | reconciler: dry-run / apply, классы расхождений, внедрение ошибок, доказательство безопасности | ошибки внесены с обеих сторон, обнаружены, исправлены; повторный запуск находит 0; под загрузками ничего подтверждённого не удалено; **код — `c1648d9` (сверка в процессе уборщика, `make reconcile`, плановая сверка, `lost_at` и 404 потерянного оригинала, список по префиксу у ключа уборщика); evidence 2026-10-22 с него: `evidence/reconcile/cycle.md` (6 классов с обеих сторон, повтор 0, возврат оригинала), `stress.md` (640 / 640 с тем же SHA-256 под `--apply`), `service.md`, `evidence/s3/cleaner-list.md` (70 проверок), `evidence/migrations/lost-at.md`, `evidence/tests/` (`failure_checks` 45 из 45 за 462 с и красный прогон 8 из 8 на `c13df14`, `student_test` 198, `test_isolated` 193 + 5 пропусков); `REPORT.md` — «Сверка хранилищ», строки уровня «5», ограничения, ответ «PUT прошёл, COMMIT нет»; вопрос 1 преподавателю (ответ API на потерянный оригинал) открыт** |
|
||
| 6 | `track2-reconcile-cost` | 5 | гипотезы, профиль стоимости обхода, стратегии, графики | метки в `evidence/`, выводы по гипотезам и ограничения в `REPORT.md` |
|
||
| 7 | — (отчёт и PR) | 3–5 | сводка `REPORT.md`, чистый clone, шаблон PR, уборка этого файла | PR `ЛР 4 — БВТ2301 — Сафронов — на 5` |
|
||
|
||
### 1. `s3-storage` — уровень 3, +4
|
||
|
||
**Пункты рубрики.**
|
||
- «3»: S3 в общем стенде, persistent volume, закреплённая версия,
|
||
создание приватного bucket описано.
|
||
- «4»: bootstrap идемпотентен; отдельные credentials API с
|
||
ограниченными правами; консоль не в общей сети; проверка приватности
|
||
вне API.
|
||
|
||
**Стенд.**
|
||
- Сервис S3: тег с версией и digest индекса (`docker.md`), named
|
||
volume, healthcheck, лимиты CPU / RAM, `restart: unless-stopped`.
|
||
- Одноразовый bootstrap (как `migrate`): bucket, запрет анонимного
|
||
доступа, пользователи API и уборщика. Реплики ждут его
|
||
`service_completed_successfully`.
|
||
- Окружение по сервисам: root — только bootstrap; ключи API — только
|
||
`api`; LB и `migrate` S3-секретов не получают.
|
||
- `.env.example`, `make env_setup` (генерация паролей S3), строки в
|
||
`config_example.toml`.
|
||
- `scripts/restart.sh` перезапускает и S3; стенды `bench/`
|
||
(`bench.compose.yml`), `make test_isolated` (свой bucket или prefix
|
||
по имени базы, как ключи Valkey) и `make failure_checks` (свой S3)
|
||
знают о новом сервисе.
|
||
|
||
**Код.**
|
||
- `src/infra/s3/`: фабрика клиента и глобал по образцу
|
||
`cache/instance.py`, срок на каждый вызов, ошибки → доменные
|
||
исключения (отказ → 503). Библиотека — решение design: aiobotocore
|
||
(асинхронный, тянет закреплённый botocore) или boto3 в потоке.
|
||
- Секция `[s3]` в `Settings`, мосты `S3__*`.
|
||
- `/health/ready` — по решению 3.
|
||
|
||
**Спеки (дельты).** Новая `object-storage` (bucket, приватность,
|
||
права, bootstrap); `container-run` (S3 в стенде, restart hook);
|
||
`service-configuration` (`[s3]`); `health` (S3 не критичен для
|
||
готовности); `service-logging` (ключи и подписи не логируются).
|
||
|
||
**Правила.** S3 — в `infra.md`, `docker.md`, `settings.md`; AGENTS.md
|
||
(карта кода, таблица команд).
|
||
|
||
**Evidence:** `evidence/s3/` — bootstrap дважды, анонимные GET и LIST
|
||
→ 403, ключ API против admin-операций и чужого bucket, `docker compose
|
||
ps` без опубликованных UI-портов, `test-persistence` с рестартом S3.
|
||
|
||
### 2. `attachments` — уровень 3, +4 (тесты)
|
||
|
||
**Пункты рубрики.** Все пункты «3» о вложениях; «4» — негативные
|
||
тесты.
|
||
|
||
**Код.**
|
||
- Миграция: таблица вложений (чат, владелец, `filename`,
|
||
`content_type`, размер, SHA-256, ключ объекта, статус, время) и связь
|
||
сообщения с вложениями с порядком. Только расширение схемы
|
||
(`migrations.md`).
|
||
- Ручки: `POST /chats/{chat_id}/attachments?filename=…`,
|
||
`GET /attachments/{id}`, `GET /attachments/{id}/content` (поток из
|
||
S3, истинный `Content-Type`, без redirect, `variant` только
|
||
`original`).
|
||
- Проверки upload по решению 4; ошибки: 400 (`filename`, UUID), 413
|
||
(байты, пиксели), 415 (формат, повреждение, подмена MIME), 404
|
||
(чужой чат), 503 (S3).
|
||
- Сообщения: `attachment_ids` 0–10 уникальных `UuidIn`, пустой текст с
|
||
вложением, чужое / неизвестное / другого чата → 404; история и
|
||
повтор отдают `attachment_ids`; хэш — решение 6.
|
||
- Драйвер скилла `run-mtusi-messenger`: upload / download / SHA-256 и
|
||
сценарий «остановить реплику, принявшую файл».
|
||
|
||
**Тесты** (`student-tests/test_attachments.py`, маркеры `spec`):
|
||
PNG и JPEG; 413 по байтам и по пикселям (маленький файл с огромными
|
||
размерами в заголовке); 415 на обрезанный файл, на текст с
|
||
`image/png`, на JPEG с `image/png`; `filename` с `/`, `\`, NUL,
|
||
управляющими символами — 400; чужое и неизвестное `attachment_id`,
|
||
вложение другого чата — 404; посторонний — 404 на метаданные и
|
||
content; ни одна ошибка не 500; идемпотентность с `attachment_ids`.
|
||
Большие и «бомбы» генерируются в тесте, в git не кладутся (README
|
||
fixtures).
|
||
|
||
**Свой сценарий отказа.** Публичный `make test-failover` останавливает
|
||
реплику, ответившую на первое *сообщение*, а не на upload. Рубрика
|
||
требует остановить именно принявшую файл: upload через LB →
|
||
`stop-one.sh` по её `X-Instance-Id` → download через другую → тот же
|
||
SHA-256.
|
||
|
||
**Переход в лабу 4.** Переснять четыре файла исключений сверки на
|
||
стенде лабы 4: `evidence/cache/hits.md`,
|
||
`evidence/auth/passwords-and-tokens.md`,
|
||
`evidence/replicas/test-persistence.md`,
|
||
`evidence/idempotency/replay-after-restart.md`.
|
||
|
||
**Спеки (дельты).** Новая `attachments`; `messages` (`attachment_ids`,
|
||
пустой текст); `idempotency` (хэш); `data-storage` (байты в S3);
|
||
`student-tests`.
|
||
|
||
**Evidence:** `evidence/attachments/` (smoke, download другим
|
||
участником, 404 постороннему, отказ загрузившей реплики),
|
||
`evidence/tests/`.
|
||
|
||
### 3. `upload-consistency` — уровень 4
|
||
|
||
**Пункт рубрики.** Прерывание загрузки и отказ между S3 и БД не
|
||
оставляют вечных неучтённых объектов; механизм с grace period описан.
|
||
|
||
**Код.**
|
||
- Намерение до PUT (решение 2), компенсация при ошибке после PUT
|
||
(удаление объекта, без гарантии — её даёт уборщик).
|
||
- Уборщик (решение 7): `pending` старше grace period → `DELETE`
|
||
объекта (идемпотентно, отсутствие — не ошибка) → удаление строки.
|
||
Grace period больше максимального времени загрузки с запасом на
|
||
часы; значения — настройки.
|
||
|
||
**Тесты отказов** (`make failure_checks`, новые действия
|
||
`fault_hook.py`): S3 остановлен и заморожен до и во время PUT; отказ
|
||
вставки строки после PUT (триггер, как `fail-messages`); kill реплики
|
||
посреди загрузки; обрыв клиента посреди тела. Итог каждого: нет 500,
|
||
`pending` убран уборщиком после grace period, объектов без строки нет.
|
||
Ещё — невидимость `pending` через API (замечание verify `attachments`,
|
||
S6; спек `attachments`, «Порядок записи»): действие hook с id последней
|
||
строки `pending` (после «Запись в S3 не удалась»), по нему метаданные,
|
||
байты и сообщение со ссылкой — 404 до уборки.
|
||
|
||
**Спеки (дельты).** `attachments` (сбои загрузки), новая или в
|
||
`object-storage` — уборка.
|
||
|
||
**Evidence:** `evidence/attachments/consistency.md`, вывод
|
||
`make failure_checks`; раздел `REPORT.md` с порядком записи.
|
||
|
||
### 4. `upload-memory` — уровень 4
|
||
|
||
**Пункт рубрики.** Лимиты, таймауты и потоковая обработка не дают
|
||
одной загрузке занять неограниченную RAM; эксперимент ≥ 10
|
||
одновременных загрузок с замером пика памяти.
|
||
|
||
**Код и стенд.**
|
||
- Лимит одновременных загрузок / декодирований на реплику; что видит
|
||
клиент при превышении — решение design (ожидание с таймаутом или
|
||
ответ с `Retry-After`).
|
||
- Сроки чтения тела в API и HAProxy, цепочка таймаутов для upload
|
||
(решение 4).
|
||
- Профиль `uploads` стенда `bench/`: 1 / 10 / 20 / 40 одновременных
|
||
загрузок по 1 и 10 MiB, `memory.peak` cgroup реплики и сэмплер,
|
||
p95, ошибки по кодам. Варианты «без лимита» и «с лимитом».
|
||
|
||
**Гипотеза.** Пик памяти реплики ≈ база + K × (буфер тела +
|
||
декодирование), где K — лимит одновременных загрузок; без лимита пик
|
||
растёт с конкуренцией до OOM-kill.
|
||
|
||
**Evidence:** `evidence/uploads/<метка>/`, выводы и ограничения в
|
||
`REPORT.md`.
|
||
|
||
### 5. `track2-reconciler` — уровень 5, трек 2
|
||
|
||
**Пункт рубрики.** Повторяемый reconciler для orphan / missing
|
||
объектов и метаданных; ошибки на обеих сторонах; обнаружение и
|
||
безопасное исправление с dry-run и повторным запуском; свежие и
|
||
используемые вложения не удаляются.
|
||
|
||
**Код.**
|
||
- Обход LIST bucket и БД (keyset), классы: объект без строки,
|
||
зависший `pending`, строка `ready` без объекта, другой размер.
|
||
- Режимы `--dry-run` (отчёт: класс, ключ, возраст) и `--apply`;
|
||
повторный запуск после прерванного `apply` доводит работу,
|
||
следующий находит 0.
|
||
- Безопасность: grace period по времени объекта и строки; перепроверка
|
||
строки в БД непосредственно перед удалением объекта; объекты,
|
||
на которые ссылаются сообщения, не удаляются никогда.
|
||
- Строка без объекта — что видит API (решение design: метка в БД,
|
||
ответ content), байты не восстановить.
|
||
|
||
**Внедрение ошибок** (`fault_hook.py`): объект в bucket мимо API,
|
||
удалённый объект, удалённая или изменённая строка, обрыв загрузки
|
||
посередине.
|
||
|
||
**Доказательство безопасности.** Reconciler `--apply` под
|
||
одновременными загрузками и отправками; затем каждое подтверждённое
|
||
вложение скачивается с тем же SHA-256.
|
||
|
||
**Evidence:** `evidence/reconcile/` — dry-run, apply, повтор = 0,
|
||
стресс.
|
||
|
||
### 6. `track2-reconcile-cost` — уровень 5, трек 2
|
||
|
||
**Пункт рубрики.** Гипотеза, повторяемая методика, результаты и
|
||
ограничения; измерить стоимость обхода.
|
||
|
||
**Стенд `bench/`.** Профиль `reconcile` по методике раздела «Трек 5»:
|
||
наполнение N объектов с долей расхождений, стратегии (батч против
|
||
`HEAD`, поверхностная против глубокой), фоновая нагрузка k6, сэмплер,
|
||
3 повтора и A/A.
|
||
|
||
**Evidence:** `evidence/reconcile/<метка>/`, графики (`make
|
||
bench_plots` или его аналог), выводы по гипотезам 1–5 и ограничения в
|
||
`REPORT.md`.
|
||
|
||
**Передано из verify `track2-reconciler` (замечание S4).** При массовом
|
||
расхождении (N ≫ `max_changes`) `--apply` перепроверяет каждого
|
||
кандидата (SELECT + HEAD) и только потом отказывает по пределу; плановый
|
||
проход всё это время держит уборку зависших. Ранний отказ ломал бы
|
||
инварианты отчёта (каждое расхождение названо, ошибка называет число
|
||
изменений), поэтому там не сделан (design `track2-reconciler`,
|
||
«Уточнения apply», п. 21). Здесь — замер цены отказа при N = 1k / 10k
|
||
расхождений и выбор: перепроверка после решения о пределе с отчётом о
|
||
неперепроверенных кандидатах, отдельный счётчик в итоге или ранний отказ
|
||
только у плановой сверки.
|
||
|
||
### 7. Отчёт и PR
|
||
|
||
- `REPORT.md`: запуск из чистого clone, архитектура и транзакционные
|
||
границы, соответствие переменных skeleton, таблица доказательств,
|
||
эксперименты, ответы на вопросы защиты, согласования с
|
||
преподавателем, ИИ и источники.
|
||
- Проверка из чистого clone, `make check`, `make test` на собранном
|
||
образе, шаблон PR. Этот файл удаляется.
|
||
|
||
## Риски
|
||
|
||
- Декодирование больших изображений в лимите памяти реплики
|
||
(решение 4) — главный технический риск лабы.
|
||
- Совместимость выбранного S3-сервера: идемпотентный bootstrap, права,
|
||
поведение при рестарте. Проверяется до выбора в design `s3-storage`.
|
||
- Медленная загрузка 10 MiB против цепочки таймаутов лабы 3
|
||
(`timeout server`, `timeout client`, срок запроса к БД).
|
||
- Доказательство «ничего свежего не удалено» требует настоящих гонок,
|
||
а не последовательного сценария.
|
||
- Объём `bench/`: новые профили `uploads` и `reconcile` не должны
|
||
ломать прежние (`bench_restore`, `failover`, `rollout`, серии).
|
||
|
||
## Вопросы и решения по ходу changes
|
||
|
||
Файл вопросов цикла OpenSpec: на каждый change — раздел `### <change>`
|
||
с подразделами «Решения» (принятые без пользователя, со ссылкой на
|
||
design) и «Вопросы» (ждут ответа; ответ дописывается рядом с датой).
|
||
При удалении плана открытые вопросы переносятся в `REPORT.md`.
|
||
|
||
### s3-storage
|
||
|
||
#### Решения
|
||
|
||
Приняты 2026-10-20 в `/opsx:propose`, подробности — design change
|
||
`s3-storage`.
|
||
|
||
1. **SeaweedFS прошёл пробу** на стенде вне репозитория (design,
|
||
Context), RustFS не понадобился. Проверены: идемпотентность bucket и
|
||
пользователя, анонимные запросы, права ключа API, healthcheck,
|
||
рестарт с volume, `kill -9`, память, клиент. Образ —
|
||
`chrislusf/seaweedfs:4.48@sha256:4e61d15f…`. Команды `s3.configure`
|
||
из решения 1 выше в 4.48 нет, вместо неё IAM-команды `s3.user.*` и
|
||
`s3.policy*` (решение 4).
|
||
2. **Три места, где SeaweedFS по умолчанию не приватен** (решения 1, 3):
|
||
- без учётных записей S3 открыт анониму → административная пара в
|
||
окружении сервера с первого старта;
|
||
- master, filer и volume слушают все интерфейсы →
|
||
`-ip.bind=127.0.0.1`, в сеть выходит только шлюз S3;
|
||
- gRPC-порт шлюза без ключа подписи принимает от любого контейнера
|
||
учётную запись администратора (воспроизведено) → обязательный
|
||
`S3_JWT_SIGNING_KEY`.
|
||
|
||
Выключены ещё телеметрия, Iceberg, Lance и встроенный IAM API.
|
||
3. **Root по решению 5 выше** (решение 3). Административную пару
|
||
хранит только сервер `s3`: без неё S3 открыт. Bootstrap работает не
|
||
ею, а `weed shell` на loopback сервера с ключом подписи. У API и
|
||
будущего уборщика административной пары нет.
|
||
4. **Права API** — политика `s3:GetObject`, `s3:PutObject`,
|
||
`s3:DeleteObject` на `<bucket>/*`, у bucket нет владельца (решение
|
||
3). Пользователь уборщика появится в `upload-consistency`.
|
||
5. **Bootstrap** — сервис `s3-bootstrap` с `network_mode: service:s3`
|
||
(решение 4):
|
||
- сводит состояние к `.env`, в том числе новый секрет API;
|
||
- сам проверяет приватность при каждом запуске;
|
||
- `make s3_check` — те же проверки с хоста и из сети (решение 8).
|
||
6. **Отдельной сети для S3 нет**: служебные порты закрыты loopback и
|
||
ключом подписи (решение 1).
|
||
7. **Клиент** — aiobotocore 3.9.2 (решения 6, 7):
|
||
- без повторов, срок на каждый вызов;
|
||
- отказ, таймаут и отказ в учётных данных — 503;
|
||
- ключи объектов с префиксом имени базы.
|
||
|
||
Отвергнуты boto3 в потоке, aioboto3, своя подпись, obstore и
|
||
minio-py.
|
||
8. **Память S3** (решение 2): лимит 512 МБ, `GOMEMLIMIT=400MiB` и
|
||
`-s3.concurrentUploadLimitMB=64`. Без них 20 одновременных загрузок
|
||
по 10 MiB дают OOM-kill. Числа уточняет `upload-memory`.
|
||
9. **Остановка и перезапуск** (решения 1, 2):
|
||
- `stop_grace_period: 20s` — плавная остановка SeaweedFS занимает
|
||
~15 с, срок зашит в filer; на стенде отказов — 2 с;
|
||
- `-master.electionTimeout=1s` — перезапуск ~7 с вместо ~24 с.
|
||
10. **Стенды** (решение 9):
|
||
- `test_isolated` — S3 рабочего стенда, префикс `test_<db>/`,
|
||
уборка через `fs.rm`;
|
||
- `failure_checks` — свой S3 и проверка готовности без него;
|
||
- `bench/` — секреты на прогон и фильтр секретов в паспорте;
|
||
профили лаб 2–3 S3 не запускают, методика прежняя;
|
||
- `rolling-update.sh` bootstrap не запускает: bootstrap, как
|
||
миграции, только расширяет права.
|
||
11. **Проверка рестарта без публичного теста** (design, Context;
|
||
решение 9). Публичные `make test`, `test-persistence` и
|
||
`test-failover` с `LAB=4` загружают вложение и до `attachments`
|
||
красные. Поэтому рестарт hook-ом проверяется напрямую: `StartedAt`,
|
||
«exists» bootstrap, объект с тем же SHA-256.
|
||
|
||
Приняты 2026-10-20 в `/opsx:apply`, подробности — design change
|
||
`s3-storage`, «Уточнения apply».
|
||
|
||
12. **`make start_s3` — два шага**: `up -d --wait s3`, затем `up
|
||
--no-deps --exit-code-from s3-bootstrap s3-bootstrap`. `--wait` не
|
||
ждёт завершения одноразового сервиса (compose v5.5.1), вопреки
|
||
пробе propose. Так же — `run_failures.py`.
|
||
13. **Bootstrap — режимы `apply`, `check`, `cleanup`**: проверки с хоста и
|
||
из сети идут между записью проверочного объекта и его удалением.
|
||
Новый секрет API распознаётся по `SignatureDoesNotMatch`.
|
||
14. **Клиент**: `open()` читает тело блоками, срок — на каждый блок;
|
||
ключи в botocore передаются всегда, даже пустые.
|
||
15. **Ожидаемо красные шире списка tasks**: контракт лабы 4 требует
|
||
`attachment_ids` в `Message`, код лабы 3 его не отдаёт — до
|
||
`attachments` красные 32 теста (и 2 ошибки) `make student_test`
|
||
через LB (в `make test_isolated` — 29 и 2) и 5 проверок `make
|
||
failure_checks`. От S3 не зависит.
|
||
16. **Дельта `health` синхронизирована в основной спек в apply**, как в
|
||
`scaling-bench`: иначе маркер нового сценария — ссылка на
|
||
неизвестный сценарий в сверке покрытия.
|
||
17. **`rollout_from c50b721` — дефект переноса** (`KNOWN_ISSUES.md`):
|
||
профиль `rollout` проверен с `--from 5d5d8f9`.
|
||
|
||
Приняты 2026-10-20 в правках по `/opsx:verify` (tasks.md, группа 7),
|
||
подробности — design change `s3-storage`, «Уточнения apply», п. 8–13.
|
||
|
||
18. **Healthcheck S3 ждёт регистрации тома** (`/dir/status`, непустой
|
||
`DataNodes`): первая запись после рестарта — 10–40 мс вместо до
|
||
4,8 с при сроке 5 с. Та же проба — в `fault_hook.py`.
|
||
19. **`tmpfs: [/tmp, /data]` у `s3-bootstrap`**: без анонимного volume на
|
||
каждый контейнер.
|
||
20. **Клиент S3**: удалённый bucket и отказ в доступе — 503 с `error`
|
||
(«bucket is missing», «denied access»), а не «объекта нет» и не
|
||
«rejected credentials»; `delete` глушит только отсутствующий ключ.
|
||
Ограничение: HEAD без тела, удалённый bucket у `head` — `None`.
|
||
21. **`make test_isolated` проверяет уборку префикса** (`fs.ls` после
|
||
`fs.rm`): код 0 `weed shell` успеха не значит.
|
||
22. **`make s3_check` берёт порты из `netstat` контейнера S3**, а не из
|
||
фиксированного списка; проверка готовности без S3 — и для `pause`.
|
||
|
||
#### Вопросы
|
||
|
||
1. Как в apply добавить строки S3 в рабочий `.env`? Агент `.env` не
|
||
читает, а `make env_setup` существующий файл не меняет (правило
|
||
`settings.md`). Варианты:
|
||
- (а) пользователь сам переносит блок из `.env.example` и
|
||
генерирует секреты, как было с Valkey; design исходит из этого;
|
||
- (б) агент с согласия пользователя: значения `openssl rand` попадут
|
||
в журнал сессии;
|
||
- (в) научить `make env_setup` дописывать недостающие переменные
|
||
шаблона со сгенерированными секретами в существующий `.env`. Это
|
||
меняет правило `settings.md` и спек `container-run` не нарушает:
|
||
существующие значения не перезаписываются.
|
||
|
||
**Ответ 2026-10-20 (основная сессия, по факту):** в рабочей копии
|
||
лабы 4 `.env` ещё нет. Его создаст `make env_setup` из обновлённого
|
||
`.env.example` вместе с секретами S3, переносить нечего. Для уже
|
||
существующего `.env` остаётся (а), как в design; (в) — только по
|
||
просьбе пользователя.
|
||
2. `attachment_ids` отсутствует в ответах Message (код лабы 3), и
|
||
поэтому до change `attachments` красные 32 теста `make student_test`
|
||
и 5 тестов `make failure_checks` (решение 15). Добавлять ли пустой
|
||
список раньше?
|
||
|
||
**Ответ пользователя 2026-10-20:** нет, красное до `attachments`.
|
||
Поле приходит целиком в `attachments` (запрос, ответ, хэш
|
||
идемпотентности), там же evidence тестов переснимается зелёным.
|
||
3. Когда чинить `rollout_from c50b721` (решение 17, `KNOWN_ISSUES.md`)?
|
||
|
||
**Ответ пользователя 2026-10-20:** в change `attachments`: он
|
||
добавляет миграцию, и rollout со старого образа на новую схему — нужное
|
||
evidence. До тех пор запись остаётся в `KNOWN_ISSUES.md`.
|
||
4. HEAD при удалённом bucket даёт `None`, как отсутствующий ключ:
|
||
SeaweedFS отвечает на HEAD одним и тем же 404 без тела (решение 21,
|
||
design «Уточнения apply» п. 10). Нужен ли лишний GET `Range:
|
||
bytes=0-0` на каждый промах, чтобы их различить?
|
||
|
||
**Ответ основной сессии 2026-10-20:** нет, ограничение принято.
|
||
Удалённый bucket видят `put`, `open` и `delete` (503), а также
|
||
bootstrap и `make s3_check`. Лишний запрос на каждый промах не нужен.
|
||
Правило для следующих changes: промах `head` не основание для
|
||
разрушающего решения (удалить строку, пометить вложение потерянным)
|
||
без проверки, что bucket на месте. Это учитывают `upload-consistency`
|
||
и reconciler трека 2.
|
||
|
||
### attachments
|
||
|
||
#### Решения
|
||
|
||
Приняты 2026-10-20 в `/opsx:propose`, подробности — design change
|
||
`attachments`.
|
||
|
||
1. **Строка `pending` до PUT — уже здесь** (решение 1). Порядок:
|
||
проверки → `pending` с ключом объекта (commit) → PUT → `ready`
|
||
(commit) → 201. При отказе S3 или БД после шага `pending` — 503,
|
||
строка остаётся. `upload-consistency` добавит компенсацию, уборщик и
|
||
тесты отказов посреди загрузки, порядок шагов не меняя.
|
||
2. **Проверка изображения — структура без декодирования** (решение 2),
|
||
своя функция на stdlib:
|
||
- PNG: CRC чанков, поток IDAT распаковывается ровно в объём по
|
||
размерам, типы фильтров строк;
|
||
- JPEG: маркеры, один кадр, скан, EOI;
|
||
- пиксели — из заголовка до распаковки.
|
||
|
||
Проба: 12 000 настоящих файлов без ложных отказов, память проверки
|
||
до 3,5 MiB, «бомба» отсекается за доли миллисекунды. Pillow — только
|
||
dev-группа, для JPEG в тестах. Поведение для клиента подтвердил
|
||
пользователь («Вопросы», п. 1).
|
||
3. **Схема** (решение 3):
|
||
- таблицы `attachments` и `message_attachments` — порядок
|
||
`position`, FK без каскада: вложение со ссылкой из сообщения БД
|
||
удалить не даст;
|
||
- ограничение текста сообщения ослаблено до 0–4000 с `NOT VALID`,
|
||
без скана `messages` под эксклюзивной блокировкой (дельта
|
||
`db-migrations`);
|
||
- чат вложения = чат сообщения проверяет сервис в той же транзакции.
|
||
|
||
Отвергнуты массив id в `messages`, составной FK с третьим индексом
|
||
на `messages` и тип `ENUM`.
|
||
4. **Ключ объекта** — `<база>/attachments/<id>/original`, хранится в
|
||
`object_key` (уникальный) (решение 4).
|
||
5. **Загрузка и скачивание не держат сессию БД** (решение 5). Найдено:
|
||
`get_db_session` держит соединение пула и срок 6 с до конца отправки
|
||
ответа, и передача 10 MiB медленному клиенту оборвалась бы на 6-й
|
||
секунде. Поэтому:
|
||
- `db_session_scope()` на каждый шаг с БД;
|
||
- вход `CurrentUserBrief` с короткой сессией;
|
||
- `AttachmentService(db_scope, cache, storage)`.
|
||
6. **Ответы до чтения тела** (решение 6, проба). Ранние 404, 413 и 415
|
||
получают httpx, curl и любой клиент через LB. `urllib` напрямую к
|
||
одной реплике ответ теряет — ограничение в `REPORT.md`. Медленные
|
||
10 MiB через LB проходят: таймауты HAProxy — простой, а не длительность.
|
||
7. **Порядок проверок загрузки**: 401 → 400 → 404 → 415 (`Content-Type`)
|
||
→ 413 (`Content-Length`) → тело (спек «Порядок проверок загрузки»).
|
||
8. **Скачивание** (решение 7):
|
||
- поток из S3, отказ S3 — 503 до заголовков;
|
||
- заголовок `X-Content-Type-Options: nosniff`;
|
||
- `variant` кроме `original` — 400 по перечислению контракта лабы 4;
|
||
- строка `ready` без объекта или с другим размером — 500 и `error`
|
||
в журнале, строка не меняется.
|
||
9. **Хэш идемпотентности** (решение 9): пустой `attachment_ids` хэш не
|
||
меняет, id в нижнем регистре, порядок значим.
|
||
10. **Лимиты 10 MiB и 40 млн пикселей — константы, не настройки**
|
||
(дельта `service-configuration`), соответствие `MAX_UPLOAD_BYTES` и
|
||
`MAX_IMAGE_PIXELS` — в `REPORT.md`.
|
||
11. **`rollout_from = e1161f7`** — последний commit лабы 4 до этого
|
||
change (решение 14). Проверка commit до стенда, правило — в
|
||
`bench.md`, запись в `KNOWN_ISSUES.md` удаляется в apply.
|
||
12. **Дельты синхронизируются в основные спеки в apply**, как `health`
|
||
в `s3-storage`: сверка покрытия читает только `openspec/specs/`.
|
||
13. **Проверки отказов вложений** — через hook стенда отказов: счётчики
|
||
вложений по статусам и объектов в bucket (решение 12).
|
||
|
||
Уточнения apply (2026-10-20/21, design change `attachments`, «Уточнения
|
||
apply»):
|
||
|
||
14. **Текст из пробелов с вложением — 201** по ответу преподавателя
|
||
(«Вопросы», п. 2); без вложений — 400. Текст не нормализуется.
|
||
15. **Проверка изображения на готовом модуле** повторила пробу: 17
|
||
вариантов, корпус 12 000 файлов без ложных отказов, «бомба» за 1 мс,
|
||
пик памяти ≤ 3,2 MiB. Вход IDAT — кусками по 64 KiB.
|
||
16. **План истории**: на пустой `message_attachments` стенда `bench/`
|
||
`SubPlan` — `Seq Scan` пустой таблицы; с данными —
|
||
`pk_message_attachments`, индекс истории прежний.
|
||
17. **`variant` в `/openapi.json`** — `enum ["original"]` через
|
||
`json_schema_extra`: Literal pydantic пишет `const`.
|
||
18. **`bench_restore_quick` падал** из-за гонки стенда (реплика
|
||
пересоздаётся с тем же IP, LB держит устаревший `UP`), не из-за
|
||
вложений. **Решение основной сессии 2026-10-21: чинить в этом
|
||
change** — возможности лаб 2–3 (`bench_restore`) должны работать
|
||
после каждого change, а 7.2 — задача `attachments`. `switch_api` ждёт
|
||
готовности процесса новой реплики изнутри контейнера, затем `UP` в
|
||
LB (design, «Уточнения apply», п. 9); запись `KNOWN_ISSUES.md`
|
||
удалена.
|
||
|
||
Замечания `/opsx:verify` 2026-10-21 (все приняты, tasks группа 10;
|
||
design, «Уточнения apply», пп. 10–15):
|
||
|
||
19. **Память загрузки — одно тело, а не два.** Тело копится в
|
||
`io.BytesIO`, `getvalue()` отдаёт `bytes` без копии (`bytearray`
|
||
botocore копирует). В образе — `MALLOC_MMAP_THRESHOLD_=131072`: с
|
||
динамическим порогом glibc вторая загрузка росла в куче, и `realloc`
|
||
на миг держал два тела. Замер в образе: RSS 1,99 → 1,19–1,20 тела на
|
||
каждой из трёх загрузок подряд. Буфер под `Content-Length` заранее
|
||
не выделяется: заявивший 10 MiB клиент держал бы их без передачи.
|
||
20. **«Бомба» распаковывается до ожидаемого объёма + 1 байт**, а не до
|
||
1 MiB: предел блока zlib — остаток ожидаемого плюс байт. Корпус
|
||
11 993 файлов — вердикты те же.
|
||
21. **«Старый образ на новой схеме»** переформулирован: проверки, которые
|
||
прежний образ проходил на прежней схеме, проходят и на новой;
|
||
доказательство — замер `rollout` (переснять с чистого дерева после
|
||
commit правок).
|
||
22. **`filename` не в UTF-8 — 400** (`a%FFb.png` давал 201 с U+FFFD):
|
||
ручка строго разбирает строку запроса, новый сценарий «Имя не в
|
||
UTF-8».
|
||
23. **«Окружение не меняет лимит»** проверяет тест `fault`: обычный API
|
||
стенда отказов — с `MAX_UPLOAD_BYTES=1` и `MAX_IMAGE_PIXELS=1`.
|
||
24. **Мёртвые константы** `MESSAGE_TEXT_MIN_LENGTH` и
|
||
`ATTACHMENT_READ_CHUNK_BYTES` удалены: блок чтения задаёт uvicorn.
|
||
25. **Невидимость `pending` через API** (S6) — не здесь: задача
|
||
`upload-consistency` (раздел «Последовательность работ», п. 3).
|
||
|
||
#### Вопросы
|
||
|
||
1. Что считать «повреждённым изображением» (решение 2, спек
|
||
`attachments`, «Повреждённое изображение»)? По умолчанию —
|
||
структурная проверка без декодирования пикселей:
|
||
- 415 — обрезанный файл, битая CRC, сломанные маркеры, поток zlib не
|
||
того объёма, «бомба»;
|
||
- байты после IEND или EOI принимаются как часть оригинала;
|
||
- изменённый байт внутри данных скана JPEG не ловится. У формата нет
|
||
контрольной суммы, Pillow его тоже не ловит.
|
||
|
||
Альтернатива — полное декодирование Pillow. Оно стоит до 160 МБ на
|
||
загрузку при лимите реплики 512 МБ, требует семафора уже в этом
|
||
change и ловит не больше.
|
||
|
||
**Ответ пользователя 2026-10-20:** структурная проверка, как по
|
||
умолчанию. Менять ничего не нужно.
|
||
2. Текст из одних пробелов вместе с вложением. По умолчанию — 400: общее
|
||
правило контракта «обязательные строки не состоят только из
|
||
пробельных символов», а исключение названо только для `text=""`.
|
||
Фраза «нельзя пустой/пробельный текст без вложений» допускает и
|
||
прочтение «с вложением можно». Это две трактовки контракта, то есть
|
||
вопрос преподавателю (AGENTS.md).
|
||
|
||
**Ответ пользователя 2026-10-20:** пока 400, как по умолчанию. Это
|
||
неоднозначность контракта: `contracts/README.md`, строка 18 («нельзя
|
||
… пробельный текст без вложений») против строк 9 (обязательные строки
|
||
не из одних пробелов) и 50 (исключение — только `text=""` с
|
||
вложением). Пользователь спросит преподавателя.
|
||
|
||
**Ответ преподавателя 2026-10-20 — вопрос закрыт.** «Пустой текст» —
|
||
это и `""`, и текст только из пробельных символов. Допустимы:
|
||
вложение + непустой текст, без вложения + непустой текст, вложение +
|
||
пустой текст. Итог: текст из одних пробелов с хотя бы одним
|
||
вложением — 201 (текст сохраняется и возвращается как прислан), без
|
||
вложений — 400. Записано в AGENTS.md, «Согласования с
|
||
преподавателем»; в apply поправлены валидатор `CreateMessage`,
|
||
сценарий `messages` «Пробелы с вложением» и его тест (design change
|
||
`attachments`, решение 8), в `REPORT.md` — как согласование.
|
||
3. Опасный `filename`. Контракт называет `/`, `\`, NUL и управляющие
|
||
символы. По умолчанию 400 и на символы управления направлением
|
||
текста (U+202A–U+202E, U+2066–U+2069) и разделители строк (U+2028,
|
||
U+2029): ими подменяют видимое имя (например, U+202E перед
|
||
`gnp.exe`). ZWJ и остальные форматирующие разрешены: на них держатся
|
||
emoji и письменности. Оставить так?
|
||
|
||
**Ответ пользователя 2026-10-20:** нет, только то, что в контракте:
|
||
400 на `/`, `\`, NUL и управляющие символы — категория Unicode Cc
|
||
(U+0000–U+001F, U+007F–U+009F). Символы направления текста,
|
||
разделители строк U+2028 и U+2029 и прочие символы категорий Cf, Zl и
|
||
Zp принимаются и возвращаются без изменений. Спеки `attachments`,
|
||
design (решения 3 и 10) и tasks приведены к этому, отвергнутый вариант
|
||
с причиной — в design, решение 10.
|
||
|
||
### upload-consistency
|
||
|
||
#### Решения
|
||
|
||
Приняты 2026-10-21 в `/opsx:propose`, подробности — design change
|
||
`upload-consistency`. Пробы — design, Context.
|
||
|
||
1. **Компенсация — только удаление объекта и только при известном
|
||
исходе** (решение 1):
|
||
- PUT подтверждён, а `ready` не зафиксирован до отправки COMMIT, или
|
||
строку уже убрал уборщик — объект удаляется до ответа 503;
|
||
- исход COMMIT неизвестен — объект не трогается;
|
||
- после неудачного PUT компенсации нет: при замороженном S3 ответ
|
||
стал бы 10 с, а позднего объекта по пробе нет (тело не уходит без
|
||
ответа сервера);
|
||
- строку компенсация не удаляет, её убирает уборщик.
|
||
|
||
`mark_ready` → `None` — 503 вместо 500.
|
||
2. **Уборщик — сервис `cleaner`, `python -m src.cleaner`** (решение 2):
|
||
- свой engine (пул 1) и клиент S3, цикл с интервалом, `--once`;
|
||
- SIGTERM — довести текущий шаг строки и выйти с кодом 0;
|
||
- healthcheck образа выключен;
|
||
- в консоли (`make run_dev`) уборщика нет.
|
||
3. **Проход** (решение 3): строка под `FOR UPDATE SKIP LOCKED` → DELETE
|
||
объекта → DELETE строки → commit. Блокировка упорядочивает уборщика и
|
||
`mark_ready` загрузки, пережившей grace. Остаток риска: API заморожен
|
||
дольше grace посреди PUT — объект без строки, его находит сверка
|
||
трека 2. После verify — пометка строки отдельной транзакцией до
|
||
DELETE объекта (решение 18 ниже), после повторного — объект и строка
|
||
одной транзакцией под блокировкой (решение 23).
|
||
4. **Grace 900 с, интервал 60 с, выборка 100** (решение 4):
|
||
- граница живой загрузки от строки до `ready`: B = 2 × 6 + 5 = 17 с,
|
||
запас ×50;
|
||
- при grace ≤ B уборщик не стартует;
|
||
- стенд отказов — 20 с и 1 с.
|
||
5. **Права уборщика в S3** (решение 8) — `s3:GetObject` и
|
||
`s3:DeleteObject` на объекты своего bucket, как задано пользователем
|
||
(«чтение/удаление»). Чтение пока не используется: HEAD не нужен, это
|
||
задел глубокой сверки трека 2. List — в `track2-reconciler`, если
|
||
понадобится. Проба: одного Delete хватает, DELETE отсутствующего —
|
||
204, удалённого bucket — `NoSuchBucket` (503).
|
||
6. **Частичный индекс строк `pending` по `(created_at, id)`** —
|
||
`CONCURRENTLY` в `autocommit_block` (решение 6). Проба с асинхронным
|
||
`env.py` прошла: с нуля, повтор, откат.
|
||
7. **Общий `session_scope` в `src/infra/db/`** для API и уборщика
|
||
(решение 7).
|
||
8. **Hook — списки `id` вместо счётчиков** (решение 10):
|
||
- SeaweedFS убирает пустой каталог `<id>/` лишь через ~2 мин после
|
||
DELETE, а уборщик меняет счётчики параллельно с тестами. Объекты
|
||
считаются по файлам `original`;
|
||
- новые действия: `attachment-ids`, `last-pending` (замечание S6),
|
||
`object-ids`, `fail-attachments insert|ready|stall`, `kill-api` и
|
||
`start-api`. Отказ триггера — SQLSTATE `08006`, для API это 503
|
||
(проба).
|
||
9. **Тесты отказов** (решение 10):
|
||
- пять новых тестов и три изменённых, `make failure_checks` дольше
|
||
~2 мин;
|
||
- «реплика убита» — между PUT и фиксацией (задержка в триггере), а
|
||
не во время PUT: так проверяется ровно «PUT прошёл, COMMIT нет».
|
||
10. **`restart.sh` и `rolling-update.sh` не меняются** (решение 9):
|
||
рестарт хранилищ уборщик переживает сам, новый код уборщика —
|
||
`docker compose up -d --no-deps cleaner`.
|
||
11. **Для `upload-memory`.** Ожидание между `pending` и `ready` (очередь
|
||
загрузок) расширяет границу B. Проверку grace и решение 4 design
|
||
`upload-consistency` обновить в том же change.
|
||
|
||
Приняты 2026-10-21 в `/opsx:apply` (подробности — design, «Уточнения
|
||
apply»):
|
||
|
||
12. **`make env_setup` дописывает в существующий `.env` недостающие
|
||
переменные шаблона** (ответ на вопрос 1): секреты — случайными,
|
||
остальные — значениями шаблона, прежние строки не меняются, в вывод
|
||
— только имена. Правило `settings.md` и дельты
|
||
`service-configuration` / `container-run` обновлены (новый сценарий
|
||
«Недостающие переменные в существующем `.env`»).
|
||
13. **Статус в запросах уборщика — константа** (`literal_execute`):
|
||
общий план asyncpg иначе не взял бы частичный индекс. План — `Index
|
||
Scan` по `ix_attachments_pending_created_at`.
|
||
14. **SIGTERM посреди прохода** — `stop_requested` у
|
||
`clean_stale_pending`: текущий шаг строки доводится до commit или
|
||
отката, новые не начинаются (после решения 19).
|
||
15. **Неверные настройки уборщика** — запись без значений полей и код 2,
|
||
а не traceback.
|
||
16. **`entrypoint` у сервиса `cleaner`**, чтобы `docker compose run
|
||
--rm --no-deps cleaner --once` передавал флаг уборщику.
|
||
17. **Красный прогон** новых тестов отказов против прежнего кода: 4 из
|
||
11 упали (компенсация и уборка), остальные закрепляют уже
|
||
выполнявшееся поведение. Полный `make failure_checks` — 29 passed,
|
||
~3,5 мин.
|
||
|
||
Приняты 2026-10-21 в правках по verify (решения основной сессии;
|
||
design, «Уточнения apply», п. 16–20; tasks, группа 11):
|
||
|
||
18. **W1 — пометка строки до удаления объекта** вместо одной транзакции
|
||
уборщика: блокировка → `updated_at = utcnow()` → commit; DELETE
|
||
объекта; блокировка → DELETE строки → commit. `mark_ready` — только
|
||
при `updated_at = created_at`. Без миграции. Откат транзакции
|
||
уборщика после удачного DELETE в S3 больше не даёт `ready` без
|
||
объекта. Остаток — окно `make rolling_update` (прежние реплики и
|
||
уборщик) и объект без строки, если зомби дописал объект после
|
||
уборки, а компенсация не удалась.
|
||
19. **SIGTERM уборщика — между шагами строки**: три шага удлинили бы
|
||
худшую остановку до 17 с (после решения 23 шагов два — до 12 с);
|
||
доводится только текущий шаг (≤ 6 с).
|
||
Требование `graceful-shutdown` «Остановка уборщика» уточнено.
|
||
20. **W2, W3 — режимы hook `commit` и `outlive`** и тесты веток «исход
|
||
COMMIT неизвестен» и «строку убрал уборщик до `ready`»; W1 — режим
|
||
`undeletable`. Ожидание перевода в `ready` — триггер `BEFORE UPDATE
|
||
OF status` уровня оператора: пометку уборщика он не задерживает.
|
||
21. **Новые сценарии** — «Исход фиксации неизвестен» (`attachments`),
|
||
«Загрузка дольше grace» и «Сбой уборки после удаления объекта»
|
||
(`storage-consistency`), в дельтах и основных спеках.
|
||
22. **W4 и S1** — evidence «Отказ S3 во время прохода» с закоммиченного
|
||
кода; `docker.md` — `entrypoint` уборщика.
|
||
|
||
Приняты 2026-10-21 в правках по повторному verify (решения основной
|
||
сессии; design, «Уточнения apply», п. 21; tasks, группа 12):
|
||
|
||
23. **W1 повторной проверки — два шага вместо трёх**: транзакция
|
||
пометки, затем объект и строка одной транзакцией под блокировкой
|
||
(как в `f2dc0b3`, но на помеченной строке). В решении 18 объект
|
||
удалялся без блокировки, и реплика до `87c48b9` успевала сделать
|
||
строку `ready` прямо перед удалением объекта — смесь «новый уборщик +
|
||
прежние реплики» была хуже, чем до правки. Теперь обе смеси не хуже,
|
||
чем до правки (проба блокировок — design, п. 21), остаётся только
|
||
откат транзакции уборки после удачного DELETE. Цена — вызов S3 внутри
|
||
транзакции (≤ 5 с < `idle_in_transaction_session_timeout` 10 с).
|
||
Решения 18 и 19 в части «три шага» заменены этим.
|
||
24. **Порядок обновления**: вперёд — сначала реплики (`make
|
||
rolling_update`), потом `docker compose up -d --no-deps cleaner`;
|
||
откат реплик на версию раньше `87c48b9` — сначала уборщик
|
||
(`balancer.md`, `REPORT.md`).
|
||
25. **Тесты 11.x не менялись**: `undeletable` на двухшаговой схеме роняет
|
||
DELETE строки в той же транзакции, что DELETE объекта, — это тот же
|
||
откат после удачного DELETE в S3; красный прогон на `f2dc0b3` в силе.
|
||
Требования `graceful-shutdown` и `storage-consistency` не менялись.
|
||
|
||
#### Вопросы
|
||
|
||
1. Как перенести секреты уборщика `S3_CLEANER_ACCESS_KEY` и
|
||
`S3_CLEANER_SECRET_KEY` в рабочий `.env`? Без них compose не
|
||
разбирает файл (`:?`). Тогда apply не проверит изменения ни на рабочем
|
||
стенде, ни в `make failure_checks` и `make test_isolated` (tasks,
|
||
шапка).
|
||
- По умолчанию — как в ответе на вопрос 1 `s3-storage`: пользователь
|
||
переносит из `.env.example` строки и комментарий,
|
||
значения — `openssl rand -hex 10` (ключ) и `openssl rand -hex 20`
|
||
(секрет).
|
||
- Альтернатива — научить `make env_setup` дописывать недостающие
|
||
секреты в существующий `.env`; только по просьбе пользователя.
|
||
|
||
Спеки и design от выбора не меняются.
|
||
|
||
**Ответ основной сессии 2026-10-21** (пользователь недоступен и
|
||
поручил работать самостоятельно): альтернатива. `make env_setup`
|
||
дописывает в существующий `.env` переменные шаблона, которых в нём
|
||
нет: секреты — случайными значениями, остальные — значениями
|
||
шаблона; существующие строки не меняет, печатает только имена.
|
||
Причины: значения не попадают ни в журнал сессии, ни в вывод;
|
||
тот же путь нужен и проверяющему со старым `.env` при переходе между
|
||
changes; ручной перенос блокирует автономную проверку на стенде.
|
||
Правило `settings.md` и сценарии `make env_setup` обновляет apply.
|
||
**Сделано в apply** (решение 12 выше): рабочий `.env` получил две
|
||
строки `S3_CLEANER_*` этой командой.
|
||
|
||
### upload-memory
|
||
|
||
#### Решения
|
||
|
||
Приняты 2026-10-21 в `/opsx:propose`, подробности — design change
|
||
`upload-memory`. Пробы — design, Context: проект compose `umprobe`,
|
||
реплика 1 CPU / 512 МБ, прототип в копии дерева в scratchpad.
|
||
|
||
1. **Проба опровергла «~1,2 тела» из `REPORT.md`** (Context, п. 1–5):
|
||
- при PUT aiohttp копирует тело (`getbuffer()` у `BytesIO`, общего с
|
||
`bytes`). Пик загрузки — около двух тел, и спек `attachments`
|
||
(«Лимит размера до чтения тела») сейчас нарушен;
|
||
- код `f894040` без swap при 20 одновременных загрузках по 10 MiB —
|
||
OOM-kill. Со swap рабочего стенда при 30 — 512 MiB и ещё 267 MiB в
|
||
swap;
|
||
- ожидание до чтения тела само память не бережёт: ядро копит
|
||
недочитанное тело в буфере сокета, до 32 MiB на соединение;
|
||
- LB даёт 502/504, если реплика молчит дольше 10 с до тела или после
|
||
него, а клиенту, замолчавшему посреди тела, отвечает 400 в HTML.
|
||
2. **Места загрузки — на процесс API** (решение 1): 4 места, очередь до
|
||
16, ожидание до 5 с по порядку прихода. Отвергнуты очередь в LB
|
||
(второй набор слотов ломал бы замену реплик и профили лабы 3),
|
||
`--limit-concurrency` uvicorn, места по байтам и общий счётчик в
|
||
Valkey или PostgreSQL.
|
||
3. **Ответ при занятых местах — 429 `rate_limited`, `Retry-After: 1`**
|
||
(решение 2) — до ответа на вопрос 1 ниже. Очередь, а не сразу 429:
|
||
сообщение несёт до 10 вложений, и 10–20 одновременных загрузок по
|
||
10 MiB на пробе проходят все.
|
||
4. **Место — после проверок 401/400/404/415/413 и до тела, держится до
|
||
ответа** (решение 3). Граница уборщика B = 17 с не меняется:
|
||
ожидание, тело и проверка — до `created_at`, сроки tx1, PUT и tx2
|
||
прежние. Проверка grace и стенд отказов (20 с) остаются. Свойство
|
||
закреплено сценарием `storage-consistency` и тестом: `created_at`
|
||
ожидавшей позже `updated_at` той, что держала место.
|
||
5. **Срок тела — 30 с с момента, как загрузка заняла место, иначе 400
|
||
`invalid_request`** (решение 4), по образцу обрыва тела. 408 в
|
||
контракте ручки нет. Срок простоя между блоками отвергнут: клиент по
|
||
байту раз в 29 с держал бы место вечно.
|
||
6. **В PUT уходит тот же `BytesIO`** (решение 5): после проверки ссылка
|
||
на `bytes` удаляется, буфер снова не общий. Проба — 1,19 тела вместо
|
||
2,0–2,3, SHA-256 объекта совпал.
|
||
7. **Буферы ядра** (решение 6): у `api` — `net.ipv4.tcp_rmem` до 512 KiB
|
||
(`sysctls` в compose), у LB — `tune.sndbuf.server 262144`. При 40
|
||
загрузках `sock` реплики — 17 MiB вместо 134, пик LB — 51 MiB вместо
|
||
109. Скорость загрузки одного клиента та же.
|
||
8. **Цепочка таймаутов пути загрузки** (решение 7):
|
||
- `timeout server` LB для `POST …/attachments` — 30 с: молчание до
|
||
тела ≤ 17 с, после ≈ 26 с; остальные пути — прежние 10 с;
|
||
- ответ LB 400 — в формате контракта;
|
||
- `ROLLOUT_DRAIN_TIMEOUT` — 90 с, больше наибольшей длительности
|
||
загрузки ~73 с;
|
||
- 408 на медленные заголовки остаётся HTML: `http-error` его не
|
||
меняет, запись в `KNOWN_ISSUES.md`.
|
||
9. **S3 без изменений** (решение 8): лимит загрузок шлюза 64 МБ,
|
||
`GOMEMLIMIT`, 512 МБ и общий срок вызова 5 с. При 12 одновременных
|
||
PUT (три реплики × 4 места) p95 — 1,6–1,9 с. Отдельный срок PUT не
|
||
нужен — это закрывает открытый вопрос design `attachments`.
|
||
10. **Профиль `uploads`** (решение 10): одна реплика без swap, S3 рабочего
|
||
стенда. Варианты: «до» (образ `f894040`), «без лимита» и «с
|
||
лимитом». Тела 1 и 10 MiB, 1 / 10 / 20 / 40 клиентов, 3 повтора,
|
||
новые S3 и реплика на прогон. Пик окна — `memory.peak` со сбросом
|
||
через свой дескриптор: пик старта (фиктивный хэш, 152 MiB) его иначе
|
||
перекрывает. Гипотезы H1–H4 — в design, в `REPORT.md` — отдельным
|
||
commit до прогонов.
|
||
11. **Тесты** (решение 11): в `make student_test` — 10 одновременных
|
||
загрузок. В `make failure_checks` — третий API с 1 местом, 1 в
|
||
очереди, ожиданием 1 с и сроком тела 2 с, пять тестов. Сценарии
|
||
памяти — исключения сверки со ссылкой на метку профиля.
|
||
12. **Драйвер `lb-upload-timeouts`** (решение 7): сроки LB на заглушке за
|
||
`haproxy.cfg` проекта. Evidence — `evidence/uploads/lb-timeouts.md`.
|
||
|
||
Приняты 2026-10-21 в `/opsx:apply` (подробности — design, «Уточнения
|
||
apply»; вопрос 1 открыт — сделано 429, как по умолчанию):
|
||
|
||
13. **Красный прогон — 5 из 5** новых тестов отказов на `f894040`
|
||
(п. 2): `test_rejections_before_queue` проверяет и полноту очереди
|
||
(429 ожидавшей), `test_slot_released_after_failures` включает шаг
|
||
«400 по сроку тела» — оба поэтому красные на прежнем коде, а не
|
||
зелёные, как ждали tasks. На дереве — все пять зелёные.
|
||
14. **Тесты мест под срок тела стенда 2 с** (п. 1, 3): держатель места
|
||
отпускается сразу после 429 ожидавшей, сверка — «новые `id` — только
|
||
держателя»; ранние отказы быстрее срока ожидания (1 с), а не 0,5 с.
|
||
15. **Одна копия тела подтверждена до профиля**: PUT 10 MiB в образе API
|
||
против S3 стенда — 1,19 тела над базой против 2,31 у прежнего пути,
|
||
SHA-256 совпал.
|
||
16. **Тип мест в сервисе — под `TYPE_CHECKING`, `Retry-After` — таблица
|
||
`RETRY_AFTER` в `errors.py`, `UploadsBusy` журналирует сервис** (п.
|
||
4–6).
|
||
17. **Драйвер `lb-upload-timeouts`** (п. 8): пять случаев параллельно,
|
||
~33 с; код 0 на текущем `haproxy.cfg`, код 1 на `f894040` (502 и 504
|
||
через 10 с, 400 HTML).
|
||
18. **Профиль `uploads`** (п. 10): разбор — `bench/uploads.py`; окно
|
||
памяти — весь прогон k6 со сбросом пика после разогрева; окружение
|
||
варианта — свой override, чтобы `stand.app_env` прежних профилей не
|
||
менялся; S3 перед прогоном — `kill` и новый volume. `uploads_quick`
|
||
на дереве: «с лимитом» при 40 × 10 MiB — пик 180 MiB, 429 вместо
|
||
5xx; «без лимита» — OOM. Попутно исправлен сэмплер: каждый запуск
|
||
оставлял анонимный volume (удаление без `-v`).
|
||
19. **Буфер приёма LB от клиента — `tune.rcvbuf.client 131072`**
|
||
(`97a4be4`; design, «Уточнения apply», п. 11). Первая метка
|
||
`baseline` (на `511e285`) отброшена: swap хоста 337 056 страниц и
|
||
`dirty`. Из неё взят только рост пика LB «с лимитом» ~2,6 MiB на
|
||
клиента — сценарий `load-balancing` «Буферы соединений ограничены» не
|
||
выполнялся из-за буфера приёма LB от клиента (до 9 MiB на сокет).
|
||
После правки — 0,56 MiB на клиента.
|
||
20. **Метка `baseline` на `97a4be4` принята с пометкой (решение
|
||
пользователя 2026-10-22, commit `ce1ae2c`).** В паспорте —
|
||
предупреждение «host swapped out 7464 pages»: вся выгрузка пришлась
|
||
на прогон `limited-10MiB-c40-r2` (`host_swap`). Пик памяти в нём как у
|
||
повторов, искажено только время (9,95 загрузки/с против ~11,0, p95
|
||
2 815 мс против ~2 050); медиана ячейки и выводы H1–H4 от него не
|
||
зависят. Предупреждение названо в `REPORT.md`.
|
||
21. **Правки по verify (2026-10-22, tasks, группа 11; design, «Уточнения
|
||
apply», пп. 12–16).** Метка `baseline` не переснимается; числа,
|
||
которых нет в её сводке, `REPORT.md` даёт формулой из её ячеек.
|
||
- Разбор сводки: H1 считает 429, OOM и 5xx только по ячейкам
|
||
гипотезы (10 MiB, C = 10, 20, 40: у `baseline` 429 — 1 351, а не
|
||
2 731 обоих тел) и печатает рост сверх C = 10 на клиента;
|
||
«Буферы соединений ограничены» — своя строка с вердиктом по сумме
|
||
роста LB и `sock` реплики от C = 1 до 40 (у `baseline` 0,56 + 0,39 =
|
||
0,95 MiB при пороге 1).
|
||
- Спеки: в требовании срока пути загрузки — буфер приёма LB от
|
||
клиента 128 KiB; «Лимит размера до чтения тела» — одна копия тела и
|
||
блоки чтения, рост пика ≤ 1,5 тела (как в сценарии).
|
||
- Проверки соотношения `wait_timeout_seconds` и `timeout server` LB
|
||
при старте нет: LB-значение API не знает; соотношение — в
|
||
`settings.md` и `config_example.toml`.
|
||
- Срок тела «узкого» API стенда отказов — 3 с вместо 2 с: запас
|
||
держателя места в `test_upload_slots_busy` был ~0,5 с. Evidence
|
||
`failure-checks.md` — переснять после commit.
|
||
- `REPORT.md`: таблица 1 MiB, числа и commit строк тестов
|
||
(`ce1ae2c`), ограничение «оборванный клиент в очереди держит место
|
||
очереди до срока ожидания».
|
||
|
||
#### Вопросы
|
||
|
||
1. Какой код отдавать, когда все места загрузки реплики заняты и
|
||
очередь полна или ожидание истекло: 429 `rate_limited` или 503
|
||
`unavailable`? Контракт (`contracts/openapi.json`, ручка
|
||
`uploadAttachment`) допускает оба:
|
||
- 429 описан как «Ограничение частоты запросов», у него одного есть
|
||
заголовок `Retry-After`;
|
||
- 503 описан как «Зависимость недоступна».
|
||
|
||
`contracts/README.md` разрешает факультативное ограничение запросов
|
||
кодом `429 rate_limited`. Места загрузки ограничивают одновременность,
|
||
а не частоту, и это расхождение формулировки. Поэтому трактовку
|
||
выбирает преподаватель.
|
||
- По умолчанию до ответа — 429 с `Retry-After: 1`. Причины: из двух
|
||
описаний контракта к ограничению подходит только 429, а «зависимость
|
||
недоступна» неверно. Кроме того, клиент и профиль `uploads` отличат
|
||
занятые места от отказа S3, который тоже 503.
|
||
- Ответ «503» меняет строку таблицы `src/api/errors.py` (заголовок
|
||
`Retry-After` остаётся), сценарии `attachments` и
|
||
`api-conventions`, ожидания тестов и `REPORT.md`. Остальной design
|
||
и задачи не меняются (design, решение 2).
|
||
|
||
**Состояние на apply 2026-10-21:** ответа нет, сделано 429
|
||
`rate_limited` с `Retry-After: 1` (поручение основной сессии). Строки,
|
||
которые поменяет ответ «503»: `DOMAIN_ERRORS` и `RETRY_AFTER` в
|
||
`src/api/errors.py`, `ERROR_CODES` и проверка `Retry-After` в
|
||
`student-tests/contract.py`, ожидания `test_upload_slots_busy` и
|
||
`test_rejections_before_queue`, сценарии спеков `attachments` и
|
||
`api-conventions`, правило `api-contract.md`.
|
||
|
||
### track2-reconciler
|
||
|
||
#### Решения
|
||
|
||
Приняты 2026-10-22 в `/opsx:propose`, подробности — design change
|
||
`track2-reconciler`. Пробы — design, Context: проект compose `rcprobe`,
|
||
SeaweedFS и PostgreSQL на tmpfs, bootstrap проекта.
|
||
|
||
1. **Сверка — часть уборщика** (решение 1):
|
||
- команда `python -m src.cleaner reconcile [--apply] [--max-changes
|
||
N]`, по умолчанию dry-run; цель `make reconcile [APPLY=1]`;
|
||
- плановая сверка в сервисе `cleaner` — при старте и раз в
|
||
`[reconciler] interval_seconds` (3600 с), с исправлением;
|
||
- `--once` — как было.
|
||
|
||
Отвергнуты:
|
||
- отдельный сервис и пользователь S3 `reconciler`: второй процесс и
|
||
два секрета ради почти пустого разделения прав;
|
||
- сверка только вручную: PUT-зомби жил бы до запуска.
|
||
|
||
С уборщиком на строках `pending` сверка не спорит: убирает их его
|
||
процедурой (`FOR UPDATE SKIP LOCKED` и пометка), а объект строки любого
|
||
статуса не удаляет никогда.
|
||
2. **Права S3** (решение 2). `cleaner-objects` получает `s3:ListBucket`
|
||
с условием `s3:prefix` `<база>/attachments/*`, префикс bootstrap берёт
|
||
из `POSTGRES_DB` (`S3_CLEANER_LIST_PREFIX`). Проба: SeaweedFS 4.48
|
||
условие соблюдает — весь bucket, `test_<db>/` и чужой bucket дают 403.
|
||
Нового пользователя и секретов нет. `make s3_check` получает строки
|
||
списка ключом уборщика.
|
||
3. **Проход** (решение 3):
|
||
- страницы LIST по 1000;
|
||
- на страницу — одно выражение к БД по `id` (по тексту ключа — только
|
||
для нестандартных ключей: по пробе в 15 раз дороже);
|
||
- множество увиденных ключей, затем keyset строк `ready` по `id`.
|
||
|
||
Слияние отсортированных потоков отвергнуто: порядок списка SeaweedFS —
|
||
обход каталогов, а не порядок байтов (проба). Действия — только после
|
||
классификации, каждое с перепроверкой в БД и HEAD.
|
||
4. **Безопасность** (решение 4):
|
||
- grace уборщика по `LastModified` объекта и времени строки;
|
||
- удаляются только объекты без строки и зависшие загрузки;
|
||
- чужие ключи — только отчёт и код 3;
|
||
- отсутствие объекта не подтверждается без проверки bucket;
|
||
- предел `[reconciler] max_changes` (100): больше — ни одного
|
||
изменения, код 3.
|
||
5. **Потерянный оригинал** (решение 5) — колонка `attachments.lost_at`.
|
||
`status` и `updated_at` не меняются. Ответы API:
|
||
- скачивание помеченного — 404 без обращения к S3, до пометки — 500,
|
||
как было;
|
||
- метаданные — 200;
|
||
- ссылка в сообщении — 201.
|
||
|
||
Это вариант по умолчанию до ответа на вопрос 1 ниже. Статус
|
||
`lost`/`failed` отвергнут: контракт лабы 4 знает только `ready`.
|
||
6. **Миграция** (решение 6) — `ADD COLUMN lost_at` с `SET LOCAL
|
||
lock_timeout`. По пробе это только каталог: 0,36 мс. Смеси версий не
|
||
хуже, чем до change. Порядок обновления:
|
||
- вперёд — `s3-bootstrap`, `make rolling_update`, затем уборщик;
|
||
- откат — сначала уборщик.
|
||
7. **Коды разового прохода** (решение 8): 0 — расхождений нет, 3 —
|
||
остались (в том числе чужой объект или отказ по пределу), 1 —
|
||
прерван, 2 — конфигурация.
|
||
8. **Стенд отказов** (решения 9, 11):
|
||
- плановая сверка выключена (`RECONCILER__INTERVAL_SECONDS=0`);
|
||
- сверку запускает hook;
|
||
- новые действия hook: объект мимо API, удаление объекта, строки и
|
||
размера, сдвиг времени строки, `lost-ids`, `fail-attachments mark`,
|
||
`reconcile`, `stop|start cleaner`, `run-cleaner`;
|
||
- восемь тестов отказов, ~+3 мин; объекты без строки ждут grace, а
|
||
строки состаривает hook.
|
||
9. **Evidence** (решение 12), `evidence/reconcile/`:
|
||
- `cycle.md` — драйвер `reconcile-cycle`: dry-run, apply, повтор = 0,
|
||
возврат оригинала;
|
||
- `stress.md` — `reconcile-stress`;
|
||
- `service.md`.
|
||
|
||
Плюс `evidence/s3/cleaner-list.md` и `evidence/migrations/lost-at.md`.
|
||
10. **Граница с `track2-reconcile-cost`** (решение 13). Здесь — одна
|
||
стратегия «батч» и поверхностная сверка (наличие и размер). Там:
|
||
- HEAD на строку;
|
||
- глубокая сверка SHA-256;
|
||
- ограничение скорости;
|
||
- профиль `reconcile` стенда `bench/`;
|
||
- гипотезы 1–4.
|
||
|
||
Гипотезу 5 проверяет стресс этого change.
|
||
11. **Запись `KNOWN_ISSUES.md` о bootstrap после удаления bucket —
|
||
воспроизведена и объяснена** (design, Context; решение 14). Причина —
|
||
не имя bucket, а слоты томов:
|
||
- `-volume.max=0` даёт на tmpfs 4 ГБ три слота;
|
||
- после удаления коллекции их занимают тома коллекции по умолчанию;
|
||
- PUT получает «no free volumes left», 500.
|
||
|
||
На 16 ГБ повтор bootstrap прошёл за 2 с. У рабочего стенда 403
|
||
свободных слота. Reconciler bucket не создаёт, поэтому запись не
|
||
чинится. В apply её текст переписывается, запись остаётся открытой.
|
||
12. **Решения apply (2026-10-22)** — подробно design, «Уточнения apply»:
|
||
- потерянный оригинал — вариант (а) до ответа на вопрос 1;
|
||
- `ReconcileAction` (названия действий), в итоге — `remaining` и
|
||
`unlogged`, `found` / `fixed` — `MappingProxyType`;
|
||
- шаг уборщика публичный (`remove_stale_pending`): сверка убирает
|
||
зависшие по одной, с записью «Fixed» на каждую;
|
||
- у `--apply` исправленное — `info` «Fixed», оставшееся — `warning`
|
||
«Found»;
|
||
- перед каждым действием — ещё одна проверка его условия (HEAD,
|
||
условный `UPDATE`, ссылки на ключ), перед пометками — снова bucket;
|
||
- свежие чужие объекты и объекты без `LastModified` — свежие;
|
||
- отказ после сигнала — `interrupted_by: stop`;
|
||
- 404 у списка — отсутствующий bucket;
|
||
- ревизия `5c3e1f0a9b7d`; планы: страница по `id` — BitmapOr, 1,5 мс,
|
||
keyset `ready` — Index Scan `pk_attachments`, 0,57 мс;
|
||
- hook `start cleaner` — `docker start` контейнера (`compose start`
|
||
требует контейнер `migrate`);
|
||
- драйвер на рабочем стенде — только после перестройки 12.1; в apply
|
||
он проверен на временном полном стенде.
|
||
13. **Правки по verify (2026-10-22, группа 13 tasks)** — design,
|
||
«Уточнения apply», пп. 19–23:
|
||
- W1: hook `set-key`, сценарии «Объект, на который ссылается строка,
|
||
не удаляется» и «Предел не останавливает уборку зависших», тесты
|
||
`…_keeps_referenced_objects` и `…_limit_keeps_cleanup` (зелёные на
|
||
`a6071da`, красные на временных регрессиях);
|
||
- W2: строка с ключом вне `<база>/attachments/` — «чужой объект» без
|
||
HEAD, пометки и уборки; сценарий «Ключ вне префикса вложений не
|
||
трогается», тест `…_foreign_key_untouched` (красный на `a6071da`);
|
||
сервис уборки такую зависшую загрузку по-прежнему убирает —
|
||
`KNOWN_ISSUES.md`;
|
||
- S1: сигнал — перед каждым вызовом хранилища, остановка ≤ 5 с (S3) /
|
||
≤ 6 с (БД);
|
||
- S4: ранний отказ по пределу не сделан — передан в
|
||
`track2-reconcile-cost` (раздел 6 выше);
|
||
- S5: `driver.py reconcile-signal` — код 1 разового прохода по
|
||
SIGTERM; снимок — после commit, на временном стенде.
|
||
|
||
#### Вопросы
|
||
|
||
1. **Вопрос преподавателю.** Что отвечает API лабы 4 на вложение,
|
||
оригинал которого потерян, после того как сверка это подтвердила?
|
||
Объекта в bucket нет или он другого размера, байтов не восстановить.
|
||
|
||
Контракт неоднозначен:
|
||
- `contracts/openapi.json`: у `Attachment.status` в лабе 4 одно
|
||
значение — `ready`, `failed` и 409 появляются с лабы 5;
|
||
- `contracts/README.md`: «Отсутствующий вариант ready-объекта — 404»,
|
||
«404 — объекта нет или он чужой» и «Неожиданное исключение — 500».
|
||
|
||
Варианты:
|
||
- (а) **по умолчанию:** метаданные — 200 как раньше (`ready`,
|
||
`error_code=null`), байты — 404 `not_found`, как отсутствующий
|
||
вариант, ссылка в новом сообщении — 201. До пометки байты — 500:
|
||
непредвиденное расхождение;
|
||
- (б) вложение целиком как незавершённое: метаданные, байты и ссылка
|
||
— 404;
|
||
- (в) байты — 500 и после пометки: пометка только для отчёта.
|
||
|
||
Ответ (б) или (в) меняет только ветку `open_content` и выборку
|
||
вложений сообщения, сценарий `attachments` «Потерянный оригинал», тест
|
||
`test_reconcile_finds_and_fixes` и `REPORT.md`. Классы, правила
|
||
безопасности, схема и задачи сверки не меняются (design, Open
|
||
Questions).
|
||
|
||
**Состояние на apply 2026-10-22:** ответа нет, сделан вариант (а)
|
||
(поручение основной сессии). Строки, которые поменяет ответ «иначе»:
|
||
ветка `lost_at` в `AttachmentService.open_content`
|
||
(`src/core/services/attachment.py`), для (б) — ещё проверка `lost_at`
|
||
в `get_attachment` и `MessageService` (выборка вложений сообщения);
|
||
сценарий `attachments` «Потерянный оригинал», `assert_lost_content` и
|
||
ожидания `test_reconcile_finds_and_fixes`,
|
||
`test_reconcile_keeps_fresh_used_and_unknown`,
|
||
`test_reconcile_restored_original`, шаги 5–6 и 8 `driver.py
|
||
reconcile-cycle`, правило `api-contract.md`.
|