Files
mtusi2026lab4/PLAN.md
T
ricoromaandClaude Opus 5.5 f57635a5fb fix: address s3-storage verify findings
- s3 healthcheck and fault hook probe wait for the volume server to
  register with master (first write after restart no longer waits ~5 s)
- s3-bootstrap mounts /data as tmpfs: no anonymous volume per container
- S3 client: NoSuchBucket and AccessDenied are 503 with their own error
  logs, not a missing object or rejected credentials; delete ignores only
  a missing key
- test_isolated verifies prefix removal (weed shell exits 0 on errors)
- s3_check derives ports from listening sockets in the s3 container
- readiness without S3 is also checked with s3 paused

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

594 lines
46 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# План лабы 4 на «5»
Рабочий документ на время лабы (составлен 2026-10-20). Пункты
закрываются changes OpenSpec по порядку из раздела «Последовательность
работ»; решение, принятое в design change, важнее этого плана. Когда
change заархивирован, его строку здесь отметить; когда закрыты все —
итоги перенести в `REPORT.md`, а файл удалить.
Задание — `README.md`, переходы API — `COURSE.md`, семантика —
`contracts/README.md`, раздел «Вложения (с lab4)». Код пока в состоянии
лабы 3 (commit `5d5d8f9`, «carry lab 3 over»): S3 и вложений нет. Поэтому
по коду, без запуска:
- публичный smoke (`LAB=4`) упадёт на загрузке вложения;
- `make student_test` красный на `test_exclusion_evidence_exists`:
файлов evidence исключений сверки ещё нет (AGENTS.md, «Переход в
следующую лабу»).
Оба пункта закрывает change `attachments`.
## Что требует рубрика и чем закрываем
| Уровень | Пункт рубрики | Как закрываем | Change |
|---|---|---|---|
| 3 | S3 в общем стенде, persistent volume, закреплённая версия, создание приватного bucket описано | сервис S3 в `docker-compose.yml`, одноразовый bootstrap как `migrate` | `s3-storage` |
| 3 | метаданные в PostgreSQL, байты в приватном bucket, не в БД и не в локальном каталоге API | таблица вложений, ключ объекта назначает сервер | `attachments` |
| 3 | `POST` вложения → `201 ready` после сохранения, побайтный download, `attachment_ids` в сообщении, smoke с checksum и 404 постороннему | ручки upload / метаданные / content, поле сообщения, история | `attachments` |
| 3 | реальные PNG/JPEG ≤ 10 MiB и ≤ 40 млн пикселей, MIME по содержимому, опасный `filename` отклонён, лимиты до неограниченного чтения и декодирования | `Content-Length` до чтения, потоковое чтение со счётчиком, сигнатура по байтам, размеры из заголовка до декодирования | `attachments` |
| 3 | upload → остановка обслужившей реплики → download через другую тот же файл; restart с volumes сохраняет метаданные и оригинал | `make test-persistence`, `make test-failover` и свой сценарий: остановить реплику по `X-Instance-Id` **загрузки** | `attachments` |
| 3 (п. 5 «Что сделать») | недоступность S3, чужой чат, restart всего стенда | 503 вместо 500 при отказе S3, текстовые сообщения работают; тесты отказов | `attachments`, `upload-consistency` |
| 4 | тесты: большой файл, повреждённое изображение, подмена MIME, чужое `attachment_id`, вложение другого чата; пользовательская ошибка не 500 | `student-tests/test_attachments.py` | `attachments` |
| 4 | прерванная загрузка и отказ между S3 и БД не оставляют вечных неучтённых объектов; механизм компенсации / очистки с grace period описан | строка-намерение до PUT, компенсация, уборщик зависших намерений | `upload-consistency` |
| 4 | лимиты, таймауты и потоковая обработка ограничивают RAM; ≥ 10 одновременных загрузок с замером пика памяти | лимит одновременных загрузок на реплику, профиль `uploads` стенда `bench/` | `upload-memory` |
| 4 | bootstrap идемпотентен; у API отдельные S3 credentials с ограниченными правами; консоль не в общей сети; проверка приватности bucket вне API | bootstrap дважды, пользователь API только на объекты bucket, анонимный GET / LIST → 403 | `s3-storage` |
| 5 | трек 2 «Согласованность двух хранилищ» | раздел «Трек 5» ниже | `track2-reconciler`, `track2-reconcile-cost` |
Сценарий защиты (README): п. 1 — smoke и команда драйвера; п. 2 — 404
постороннему и анонимный GET в S3 (`s3-storage`); п. 3 —
`test-persistence` и `test-failover`; п. 4 — нет локального файла
оригинала на API, отказы и эксперименты.
## Ключевые решения
Ниже предложения. Окончательное решение принимается в design
соответствующего change.
### 1. S3-сервер: SeaweedFS, не MinIO — подтверждено 2026-10-20
README разрешает любой из трёх: MinIO, SeaweedFS, RustFS. MinIO —
самый известный вариант, но закрепить его образ из чистого clone
сейчас нельзя. Проверено 2026-10-20:
- `docker buildx imagetools inspect minio/minio:latest` и
`minio/mc:latest` — «pull access denied, repository does not exist»;
API Docker Hub на `minio/minio` отвечает 404;
- `quay.io/minio/minio` — 401 без авторизации;
- для сравнения `chrislusf/seaweedfs` и `rustfs/rustfs:1.0.3`
разрешаются, у обоих свежие теги (2026-10-17…20).
По публичным источникам (блоги, не объявления MinIO): сборки образов
community edition прекращены в октябре 2025, с декабря 2025 —
maintenance mode, в 2026 репозиторий архивирован; исправление
CVE-2025-62506 в образ не попало. Варианты оставить MinIO и их цена:
| Вариант | Чем плох |
|---|---|
| старый закреплённый образ | из чистого clone не скачивается — рубрика «3» (стенд из репозитория) не выполняется |
| сборка из исходников архивного репозитория | свой Dockerfile с Go-сборкой, исправлений дальше не будет |
| форк `pgsty/minio` | сторонний проект, доверие и сопровождение надо проверять |
Сравнение оставшихся:
| | SeaweedFS | RustFS |
|---|---|---|
| Зрелость | с 2015 года, образы публикуются ежедневно | проект моложе, открыт в 2025 |
| Bootstrap bucket и пользователя | `weed shell` (`s3.bucket.create`, `s3.configure`) из того же закреплённого образа | admin API в стиле MinIO: нужен `mc` (образ недоступен, см. выше) или свой код подписи |
| Права пользователя API | действия `Read` / `Write` / `List` / `Admin` на bucket | IAM-политики в формате AWS, тоньше (`s3:PutObject` без `s3:DeleteObject`) |
| Консоль / UI | master, filer, volume, admin UI — не публикуются | консоль на отдельном порту — не публикуется или выключается |
Предложение — **SeaweedFS**: один процесс `weed server -s3` с volume,
bootstrap одноразовым сервисом на том же образе. В design
`s3-storage` — короткая проверка на стенде до выбора: идемпотентность
создания bucket, запрет анонимного доступа, права пользователя API,
healthcheck, переживание рестарта. Если SeaweedFS провалит проверку —
RustFS. В `.claude/rules/settings.md` MinIO упомянут только примером
секрета, правило обновляется в том же change.
### 2. Запись вложения: намерение → объект → готово
- Порядок upload: проверки до чтения → потоковое чтение и проверка
содержимого → строка-намерение `pending` с ключом объекта (commit) →
`PUT` в S3 → строка `ready` (commit) → `201`.
- Ключ объекта — серверный (`uuid`), `filename` только для показа:
ни путь, ни ключ из него не строятся.
- Любой объект в bucket, загруженный API, известен БД **до** PUT.
Сбой после PUT и до второго commit оставляет `pending`, а не
неучтённый объект: его убирает уборщик после grace period
(`upload-consistency`). Объект без строки возможен только мимо API —
это класс расхождений трека 2.
- Ответ на вопрос защиты «PUT прошёл, COMMIT нет» — отсюда.
- `pending` во внешний API не попадает: контракт лабы 4 знает только
`ready`; `GET` такого вложения — 404.
### 3. `/health/ready` без S3 — подтверждено 2026-10-20
Отказ S3 не выводит реплики из LB: вложения отвечают 503 `unavailable`,
текстовые сообщения и история работают. Если включить S3 в готовность,
его заминка разом выключит все реплики, включая текстовый путь
(та же логика, что у таймаута готовности PostgreSQL, `balancer.md`).
Решение и список критичных зависимостей — в `REPORT.md` (контракт:
«Какие зависимости критичны, зафиксируйте в отчёте»).
### 4. Память загрузки
- Тело ≤ 10 MiB: `Content-Length` больше лимита — 413 до чтения; без
`Content-Length` — счётчик при чтении, обрыв на 10 MiB + 1.
- Сигнатура PNG / JPEG по первым байтам; размеры из заголовка до
декодирования, больше 40 млн пикселей — 413.
- Главный риск — не байты, а декодирование: 40 млн пикселей RGB —
около 120 МБ на одну загрузку при лимите реплики 512 МБ. Варианты
для design `attachments`: проверка целостности без полного
декодирования (PNG — CRC чанков и потоковая распаковка IDAT со
счётчиком строк; JPEG — структура маркеров), полное декодирование
под семафором, `draft` для JPEG. Цена каждого — в `upload-memory`.
- Лимит одновременных загрузок на реплику и сроки чтения тела (HAProxy
и API). `timeout server` LB 10 с рассчитан на запрос к БД, а не на
медленную передачу 10 MiB — цепочку таймаутов пересмотреть для пути
upload.
### 5. Учётные данные S3
- root — только bootstrap; API и уборщик его не получают.
- Пользователь API — объекты своего bucket: чтение, запись, удаление
(компенсация). Без List и Admin.
- Уборщик / reconciler — свой пользователь: List, чтение, удаление.
- Пароли — `.env` (`make env_setup` генерирует, как Postgres и
Valkey), в приложение — мостами `S3__*`. Соответствие имён skeleton
(`S3_ENDPOINT`, `S3_REGION`, `S3_BUCKET`, `S3_ACCESS_KEY_ID_FILE`,
`S3_SECRET_ACCESS_KEY_FILE`, `MAX_UPLOAD_BYTES`, `MAX_IMAGE_PIXELS`) —
в `REPORT.md`, как в лабе 3.
- API-порт S3 — только `127.0.0.1` (console-режим `make run_dev`), как
Postgres и Valkey; UI и консоль не публикуются вообще.
### 6. Идемпотентность с `attachment_ids`
`message_request_hash` начинает учитывать `attachment_ids`. Пустой
список не должен менять хэш: иначе ключ, сохранённый версией без
вложений, после `make rolling_update` давал бы 409 на повтор того же
тела. Порядок элементов массива значим (это JSON-массив), порядок
ключей объекта — нет (контракт).
### 7. Уборщик — отдельный сервис (подтверждено 2026-10-20)
Фоновая работа в API-репликах запрещена до worker лабы 5 (AGENTS.md,
«Архитектура в двух словах»). Уборщик зависших `pending` — отдельный
сервис compose на образе API со своей командой и своими S3-правами,
интервал и grace period в настройках. Отвергнута цель Makefile без
расписания: с ней «вечных» объектов нет только при регулярном ручном
запуске. В треке 2 уборщик вырастает в reconciler.
## Трек 5: трек 2 «Согласованность двух хранилищ» (подтверждено 2026-10-20)
**Почему трек 2.**
- Продолжает обязательный пункт «4» (компенсация и очистка): общий
код, общие тесты отказов.
- Контракт не расширяется, S3 остаётся во внутренней сети.
- Замеры ложатся на готовый `bench/` (наполнение, паспорт, сэмплер,
`summary.md`), как трек 2 лабы 2.
- Пригодится в лабе 5: staging-prefix, хвосты worker при доставке at
least once.
**Почему не трек 1 (presigned upload).**
- S3 должен быть доступен клиенту: подпись под внешний адрес, шире
поверхность атаки.
- Новые ручки init / complete в `contracts/extensions.openapi.json`.
- Лимит размера (POST policy `content-length-range`) и checksum при
complete на SeaweedFS / RustFS не проверены; без них complete читает
объект обратно, и выигрыш по трафику API тает.
- В лабе 5 загрузка становится асинхронной (202) — flow переделывать.
### Гипотезы (до прогонов коммитятся отдельно)
1. **Линейность.** Время обхода растёт линейно по числу объектов, цена
на объект от N почти не зависит.
2. **Батч против точечной сверки.** Сверка страницы LIST (до 1000
ключей) одним запросом к БД (`object_key = ANY(...)`) дешевле
`HEAD` на каждую строку: запросов N/1000 против N.
3. **Поверхностная против глубокой.** Размер из LIST почти бесплатен;
SHA-256 требует прочитать каждый объект и упирается в чтение S3 —
глубокая сверка выборочная или по требованию.
4. **Влияние на рабочий трафик.** Обход с ограниченной скоростью
ухудшает p95 фоновой нагрузки API не больше порога, заданного до
прогона.
5. **Безопасность.** Ни одно подтверждённое и ни одно используемое в
сообщениях вложение не удаляется при любой гонке с загрузками.
### Методика (предварительно)
- Стенд `mtusi-bench` с S3 и лимитами из паспорта. N = 10k и 100k
объектов; наполнение мимо API (SQL и прямой PUT), граница описана.
- Внесённые расхождения, по доле каждого класса: объект без строки,
зависший `pending`, строка `ready` без объекта, другой размер.
- Метрики: время по фазам, запросы S3 и PostgreSQL, CPU / RAM
reconciler, S3 и PostgreSQL (сэмплер), p95 фоновой нагрузки k6.
- 3 повтора, A/A для отделения эффекта от шума (`make bench_compare`
или его аналог для профиля).
### Ограничения, которые заранее назвать
- Генератор, API, S3 и БД на одном хосте, Docker Desktop — VM.
- Одна нода S3, без репликации: отказ диска или хоста не переживается.
- Строку без объекта не восстановить: байтов нет нигде. Reconciler её
находит и помечает, но не «чинит».
## Последовательность работ
Этапы 1–6 — changes OpenSpec, каждый проходит `/opsx:propose` →
`/opsx:apply` → `/opsx:verify` → `/opsx:archive`. Этап 7 — сборка
отчёта, не change. Замеры для отчёта снимаются с закоммиченного кода
(`bench.md`, «Измеренное состояние — commit»). Отчёт пополняется в
каждом change: evidence и строка в таблице доказательств `REPORT.md` —
часть «готово». Возможности лаб 2 и 3 (`bench_restore`, профили
`failover` и `rollout`, серии трека 1, проверки отказов) работают после
каждого change.
### Сводная таблица
| № | Change | Уровень | Что происходит | Готово, когда |
|---|---|---|---|---|
| 0 | — (подготовка) | — | этот план; выбор трека и S3-сервера | план сохранён 2026-10-20; трек 2, SeaweedFS, решения 3 и 7 подтверждены 2026-10-20 |
| 1 | `s3-storage` | 3 (+4: bootstrap, права, консоль, приватность) | S3 в стенде, bootstrap, клиент в `src/infra/s3/`, настройки, все стенды знают о S3 | bootstrap дважды без ошибок, анонимный GET / LIST → 403, ключ API не может admin-операций, `make test-persistence` перезапускает и S3 |
| 2 | `attachments` | 3 (+4: тесты) | миграция, домен `attachment`, ручки, `attachment_ids` в сообщениях, тесты | зелёные `make test`, `test-persistence`, `test-failover`, свой сценарий отказа загрузившей реплики; негативные тесты; evidence исключений переснят |
| 3 | `upload-consistency` | 4 | намерение до PUT, компенсация, уборщик с grace period, тесты отказов | `make failure_checks` с отказами S3 и БД посреди загрузки: нет 500, нет неучтённых объектов старше grace period |
| 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, объектов без строки нет.
**Спеки (дельты).** `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`.