Files
mtusi2026lab4/REPORT.md
T
ricoromaandClaude Opus 5.5 f2dc0b368a docs: add upload-consistency evidence and report
- evidence: consistency (driver upload-consistency), cleaner process,
  cleaner S3 key, pending index plan on the working database
- re-run failure_checks (29/29), student_test via LB and test_isolated
  with the cleaner and storage-consistency coverage
- REPORT: database and S3 consistency, compensation table, grace period
  rationale, "PUT succeeded, COMMIT did not" answer, level 4 rows,
  limitations; PLAN stage 3 and AGENTS evidence map

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

608 lines
70 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
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
## Запуск из чистого clone
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
### S3 (change `s3-storage`)
`make env_setup` создаёт новый `.env` из `.env.example` со случайными
паролями PostgreSQL и Valkey и шестью секретами S3 и печатает только их
имена. Существующий `.env` он не перезаписывает, а дописывает в конец
переменные шаблона, которых в нём нет: секреты — случайными значениями,
остальные — значениями шаблона; прежние строки не меняются, печатаются
только имена (с change `upload-consistency`).
**Шаг оператора для `.env`, созданного до change `s3-storage`.**
Перенесите блок S3 из `.env.example` руками. Пять пустых секретов
(`S3_ROOT_ACCESS_KEY`, `S3_ROOT_SECRET_KEY`, `S3_JWT_SIGNING_KEY`,
`S3_API_ACCESS_KEY`, `S3_API_SECRET_KEY`) заполните значениями `openssl
rand -hex 32`. Без них любая команда compose останавливается с
сообщением «… is empty, copy S3 lines from .env.example». (Переменные,
которых в `.env` нет вовсе, теперь допишет и `make env_setup`; пустые
значения уже существующих строк он не трогает.)
**Шаг оператора для `.env`, созданного до change `upload-consistency`.**
Достаточно `make env_setup` (его вызывает и `make run_docker`): он
допишет `S3_CLEANER_ACCESS_KEY` и `S3_CLEANER_SECRET_KEY` со случайными
значениями и напечатает «added to existing .env:
S3_CLEANER_ACCESS_KEY S3_CLEANER_SECRET_KEY». Без них compose
останавливается на «S3_CLEANER_… is empty, run make env_setup».
- `make run_docker`. Порядок старта:
- postgres, valkey и s3 до `healthy`;
- одноразовые `migrate` (с change `upload-consistency` — ещё и индекс
`CONCURRENTLY`) и `s3-bootstrap` (приватный bucket, пользователи API
и уборщика, проверки приватности);
- `api` × 2 и `cleaner` (уборщик незавершённых загрузок) после
успешного завершения обоих;
- haproxy на `127.0.0.1:8080`.
Проверки — `make test`, `make student_test`, `make s3_check`.
- `make run_dev`. Цепочка `make upgrade`, `make start_cache` и `make
start_s3`: `up -d --wait s3`, затем `up --no-deps --exit-code-from
s3-bootstrap s3-bootstrap`, код bootstrap — код цели. Затем сервис на
`127.0.0.1:8080`. В консоли S3 доступен на `127.0.0.1:8334`. Уборщика
в консоли нет: зависшие загрузки консольного API убирает уборщик
стенда (та же база) или разовый `docker compose run --rm --no-deps
cleaner --once`.
- `make stop` останавливает S3 плавно, ~15 с. `make down` volumes не
трогает.
- `make wipe_data` удаляет volumes `mtusi-lab4_postgres_data` и
`mtusi-lab4_s3_data` только после ввода `yes`, оба тома запрос
называет по имени.
## Архитектура и решения
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab3, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
```
клиент → 127.0.0.1:8080 → haproxy → api × 2 → postgres (метаданные, сессии, ключи идемпотентности)
→ valkey (кэш карточек чатов)
→ s3 (байты вложений; SeaweedFS, приватный bucket)
migrate (один раз) ──→ postgres
s3-bootstrap (один раз, в сетевом пространстве s3) ──→ s3
cleaner (долгоживущий, без портов) ──→ postgres (строки pending), s3 (их объекты)
```
### Роль S3 и её граница
S3 хранит только байты вложений, метаданные лежат в PostgreSQL. Пишет и
читает S3 API своим ключом; удаляет ещё уборщик незавершённых загрузок
своим ключом (только чтение и удаление). Change `s3-storage` дал
сервер, bootstrap, клиент `src/infra/s3/` и стенды, change
`attachments` — ручки вложений и `attachment_ids` (раздел «Вложения»
ниже), change `upload-consistency` — компенсацию в загрузке и уборщика
(раздел «Согласованность БД и S3»). Лимит одновременных загрузок —
`upload-memory`.
Сервер — SeaweedFS 4.48. Выбор и проба — `PLAN.md` (решение 1) и
design change `s3-storage`. Три места, где SeaweedFS по умолчанию не
приватен, закрыты:
- без учётных записей S3 открыт анониму — административная пара задана
в окружении сервера с первого старта;
- master, filer и volume слушают все интерфейсы — `-ip.bind=127.0.0.1`;
- gRPC шлюза без ключа подписи принимает учётную запись администратора
— ключ подписи обязателен.
Телеметрия, Iceberg, Lance и встроенный IAM API выключены.
### Сервисы стенда
| Роль | Сервис | Версия / digest индекса | Health / readiness | Volume | Сеть / порт | Credentials |
| --- | --- | --- | --- | --- | --- | --- |
| load_balancer | `haproxy` | `haproxy:3.4.6-trixie@sha256:e2739156…db26` | `/lb/ready` на `:8404` изнутри: есть готовая реплика | — | `127.0.0.1:8080` → `8080`; `:8404` только в сети | нет |
| api × 2 | `api` | образ из `Dockerfile`, база `python:3.12.14-slim-trixie@sha256:f77ac9e4…e51f` | HEALTHCHECK образа: `/health/ready` | — (`config.toml` read-only) | `8080` только в сети | пароли PostgreSQL и Valkey, ключи пользователя API в S3 — мосты `DATABASE__PASSWORD`, `CACHE__PASSWORD`, `S3__ACCESS_KEY_ID`, `S3__SECRET_ACCESS_KEY` из `.env` |
| миграции | `migrate` | образ API | код выхода 0 (`service_completed_successfully`) | — | сеть | пароль PostgreSQL |
| postgres | `postgres` | `postgres:18.6-trixie@sha256:5a5a84b1…9722` | `pg_isready -h 127.0.0.1` | `postgres_data` | `127.0.0.1:5433` → `5432` | `POSTGRES_PASSWORD` |
| кэш (необязательная роль) | `valkey` | `valkey/valkey:9.1.2-trixie@sha256:418652cf…9dfd` | `valkey-cli ping` с паролем | — (persistence выключен) | `127.0.0.1:6380` → `6379` | `VALKEY_PASSWORD` |
| s3 | `s3` | `chrislusf/seaweedfs:4.48@sha256:4e61d15f…7872d` | `wget`: `/cluster/healthz` master, том зарегистрирован (`DataNodes` в `/dir/status`), `/healthz` filer и шлюза (loopback) | `s3_data:/data` | `127.0.0.1:8334` → `8333` (только API S3); в сети — `8333` и gRPC шлюза `18333`, служебные порты на loopback | административная пара (`AWS_*` из `S3_ROOT_*`) и ключ подписи (`WEED_JWT_FILER_SIGNING_KEY` из `S3_JWT_SIGNING_KEY`) — окружением |
| bootstrap S3 | `s3-bootstrap` | тот же образ S3 | код выхода 0; реплики и уборщик ждут `service_completed_successfully` | — (`/tmp` и `/data` — tmpfs) | `network_mode: service:s3`, портов нет | ключ подписи, ключи API и ключи уборщика — окружением; в `weed shell` через stdin, в `curl` файлами на tmpfs |
| уборщик незавершённых загрузок | `cleaner` | образ API, точка входа `python -m src.cleaner` | healthcheck образа выключен (HTTP не слушает); живость — журнал; ждёт `postgres` healthy, `migrate` и `s3-bootstrap` | — (`config.toml` read-only) | портов нет | пароль PostgreSQL (`DATABASE__POOL_SIZE: 1`), ключи пользователя уборщика в S3 (`S3__*` из `S3_CLEANER_*`) |
Лимиты:
- postgres 2 CPU / 1 ГБ, valkey 0,5 / 128 МБ, s3 1 / 512 МБ;
- `s3-bootstrap` 0,5 / 128 МБ, `migrate` 0,5 / 256 МБ;
- `api` 1 / 512 МБ на реплику, haproxy 1 / 256 МБ;
- `cleaner` 0,25 / 256 МБ (в простое ~91 MiB,
`evidence/attachments/cleaner-process.md`).
Сумма — 7,75 CPU / 3,5 ГиБ, без одноразовых сервисов — 6,75 CPU /
3,1 ГиБ. Соединения PostgreSQL: `API_REPLICAS` × `pool_size` +
`migrate` + уборщик = 2 × 10 + 1 + 1 = 22, во время `make
rolling_update` (три реплики) — 32, при `max_connections` 100
(переполнения пула нет, `max_overflow` 0). Секреты по сервисам
проверены в `evidence/s3/privacy.md` (раздел 4) и, с уборщиком, в
`evidence/s3/cleaner-key.md` (раздел 3).
### Bootstrap S3 и его безопасный повтор
Сервис `s3-bootstrap` выполняет `infra/s3/bootstrap.sh` в режиме
`apply`. Каждый шаг можно повторять:
1. Bucket: есть — «exists», нет — создаётся.
2. Анонимный доступ — `none`. Если он открыт, bootstrap его закрывает.
3. Политика `api-objects` (`s3:GetObject`, `s3:PutObject`,
`s3:DeleteObject` на `arn:aws:s3:::<bucket>/*`) создаётся или
обновляется.
4. Пользователь `api`: если его нет, создаётся с ключами из `.env`;
политика привязывается.
5. Чужие ключи пользователя удаляются, нужный создаётся, если его нет.
6. Проверка ключом API: PUT, GET и DELETE проверочного объекта.
`SignatureDoesNotMatch` значит, что секрет в `.env` сменился, —
ключ пересоздаётся.
7. Проверки приватности: ключ API получает 403 на список и создание
bucket, аноним — 403 на чтение и список. Расхождение — `FAILED:
<шаг>`, код 1, реплики не стартуют.
С change `upload-consistency` шаги 3–6 общие для двух пользователей:
`api` и `cleaner` с политикой `cleaner-objects` (`s3:GetObject`,
`s3:DeleteObject` на объекты своего bucket — без записи, списка и прав
на bucket). Ключ уборщика ждётся и проверяется DELETE несуществующего
ключа (204; PUT ему запрещён), новый секрет уборщика так же
распознаётся по `SignatureDoesNotMatch`. Проверки каждого запуска:
ключ уборщика читает проверочный объект, получает 403 на запись и
список и удаляет его; после этого GET ключом API — 404
(`evidence/s3/cleaner-key.md`).
Повтор не меняет правильное состояние: bucket и объекты сохраняются,
пользователи не пересоздаются (`evidence/s3/bootstrap.md`, раздел 2;
`evidence/s3/cleaner-key.md`, раздел 1).
Смена секрета API: новое значение в `.env`, затем `make run_docker`.
Bootstrap пересоздаёт ключ, прежний секрет перестаёт действовать
(раздел 3), а реплики с новым окружением пересоздаёт compose.
Bootstrap работает не административной парой S3, а `weed shell` на
loopback сервера с ключом подписи. Административная пара есть только у
сервера. `make rolling_update` bootstrap не запускает: он, как
миграции, только расширяет права. Его изменения применяет `docker
compose up -d s3-bootstrap` или `make run_docker`.
### Критичные и некритичные зависимости готовности
- PostgreSQL **критичен**: в нём источник истины и сессии.
`/health/ready` выполняет `SELECT 1` со сроком 2 с, без него — 503.
- Valkey **не критичен**: это кэш, без него обязательные запросы идут в
PostgreSQL.
- S3 **не критичен**: без него недоступны только пути вложений (503
`unavailable`), текст работает. `/health/ready` к S3 не обращается:
иначе отказ S3 вывел бы из LB все реплики, и текст перестал бы
работать тоже. Проверка — `test_readiness_without_object_storage` в
`make failure_checks`.
### Соответствие имён skeleton `S3_*`
| Имя `.env.example` skeleton | Реальная конфигурация |
| --- | --- |
| `S3_ENDPOINT` | `S3__HOST` и `S3__PORT`: в консоли — мосты `127.0.0.1` и `${S3_OUT_PORT}`, в docker — `S3_HOST` и `S3_PORT` через `x-s3-env` |
| `S3_REGION` | `[s3] region` в `config.toml` (`us-east-1`, нужен подписи SigV4) |
| `S3_BUCKET` | `S3__BUCKET` в `.env`: читают приложение и bootstrap |
| `S3_ACCESS_KEY_ID_FILE`, `S3_SECRET_ACCESS_KEY_FILE` | мосты `S3__ACCESS_KEY_ID=${S3_API_ACCESS_KEY}` и `S3__SECRET_ACCESS_KEY=${S3_API_SECRET_KEY}`: значения из `.env`, а не файлы, как с `DATABASE_URL_FILE` |
| `MAX_UPLOAD_BYTES` | константа `ATTACHMENT_MAX_BYTES` = 10 485 760 в `src/utils/constants.py`, не настройка |
| `MAX_IMAGE_PIXELS` | константа `ATTACHMENT_MAX_PIXELS` = 40 000 000 там же, не настройка |
Лимиты вложений задаёт контракт, они одинаковы на всех установках,
поэтому ни окружение, ни `.env`, ни `config.toml` их не меняют (спек
`service-configuration`, «Лимиты вложений — константы контракта»;
design change `attachments`, решение 10). Проверка: обычный API стенда
отказов запускается с `MAX_UPLOAD_BYTES=1` и `MAX_IMAGE_PIXELS=1`, а
`sample.png` всё равно принимается — 201
(`test_environment_does_not_change_limits`,
`evidence/tests/failure-checks.md`).
### Вложения (change `attachments`)
```
POST /chats/{id}/attachments?filename=… (сырые байты PNG/JPEG)
└─ вход: короткая сессия БД (CurrentUserBrief)
└─ членство (404) → Content-Type (415) → Content-Length (413)
└─ тело со счётчиком (413 сразу за 10 MiB) → структура и SHA-256 в потоке (415 / 413)
└─ tx1: строка attachments, status=pending, object_key ── commit
└─ PUT <база>/attachments/<id>/original в S3
└─ tx2: pending → ready ── commit
(сбой до отправки COMMIT или строки уже нет — DELETE объекта, 503)
└─ 201 Attachment (status=ready)
GET /attachments/{id} → строка ready + членство (404 иначе)
GET /attachments/{id}/content → GET из S3 потоком (StreamingResponse), Content-Length, nosniff
POST /chats/{id}/messages {text, attachment_ids}
└─ членство → вложения: все ready и этого чата (404 до захвата ключа)
└─ ключ → сообщение → message_attachments (position) ── один commit
```
**Порядок записи и отказы** (design, решение 1). Объект, который
записывает API, известен PostgreSQL до записи: строка `pending` с
`object_key` фиксируется до PUT.
Отказы на каждом шаге, компенсация и уборка — раздел «Согласованность
БД и S3» ниже. Строку `pending` API не показывает (метаданные, байты и
ссылка в сообщении — 404 с тем же `message`, что у неизвестного `id`).
**Проверка изображения — структурная, без декодирования пикселей**
(`src/utils/image.py`, только stdlib; решение 2, подтверждено
пользователем):
- тип — по сигнатуре; `Content-Type` запроса должен совпасть, иначе 415
(подмена MIME);
- размеры — из IHDR / SOF до распаковки: больше 40 млн пикселей — 413;
- PNG: CRC каждого чанка, IHDR первым, нет неизвестных критичных чанков,
IDAT подряд, поток zlib распаковывается блоками по 1 MiB и ровно в
объём по размерам (больше — «бомба», 415 сразу), типы фильтров строк,
IEND; JPEG: маркеры и длины сегментов, один SOF, скан, EOI;
- байты после IEND / EOI — часть оригинала (входят в размер и SHA-256);
- пик памяти проверки ≤ 3,2 MiB при любом числе пикселей; «бомба»
100 × 100 → 200 MiB отклоняется за 1 мс; корпус 12 000 файлов macOS —
ни одного ложного отказа (design change `attachments`, «Уточнения
apply», п. 1).
**Схема** (ревизия `ef25d50b01a8`, решение 3): `attachments` (составной
FK `(chat_id, owner_id) → chat_members` — владелец участник чата; CHECK
размера, SHA-256 32 байта, типа, статуса, длины и символов `filename`;
уникальный `object_key`) и `message_attachments` (PK `(message_id,
position)`, 0–9, уникальная пара сообщение–вложение, индекс по
`attachment_id`, FK без каскада — вложение со ссылкой не удалить).
Ограничение текста сообщения ослаблено с 1–4000 до 0–4000 `NOT VALID`:
пустой текст допустим с вложением, правило «текст или вложение» держит
сервис. История читает `attachment_ids` коррелированным подзапросом
`ARRAY(…)` по `pk_message_attachments`, индекс истории прежний.
**Ключ объекта** — `<имя базы>/attachments/<id>/original`, назначает
сервер и хранит в строке. `filename` только отображается: 400 на `/`,
`\`, управляющие символы (Cc) и пустое / из пробелов, остальное
(включая символы направления текста) хранится как прислано.
Процент-коды имени — строгий UTF-8: Starlette заменил бы неверный байт
на U+FFFD, поэтому ручка разбирает сырую строку запроса сама, и
`filename=a%FFb.png` — 400, а не 201 с искажённым именем (сценарий «Имя
не в UTF-8»).
**Память одной загрузки — одно тело** (решение 6). Тело копится в
`io.BytesIO`, `getvalue()` отдаёт `bytes` над тем же буфером без копии
(`bytes`, а не `bytearray`: его botocore копирует). В образе
`MALLOC_MMAP_THRESHOLD_=131072`: с динамическим порогом glibc после
первой загрузки растил буфер в куче, и `realloc` на миг держал два тела.
Проба в образе API, три загрузки 10 MiB подряд в одном процессе: пик
RSS 1,99 тела до правки → 1,19–1,20 после (одно тело и блоки чтения
botocore по 1 MiB; design, «Уточнения apply», п. 10).
**Без сессии БД на всю передачу** (решение 5). Зависимость
`get_db_session` закрывается после отправки ответа, и её срок 6 с
охватил бы чтение тела и отдачу потока: медленные 10 MiB оборвались бы
на 6-й секунде. Ручки вложений берут короткий вход (`CurrentUserBrief`),
сервис открывает сессию на каждый шаг; загрузка 12,4 с и скачивание
13,1 с через LB проходят (`evidence/attachments/slow-transfer.md`).
**Идемпотентность**: хэш тела включает `attachment_ids` только
непустым (`str(UUID)`, нижний регистр, порядок значим) — ключ,
сохранённый версией без вложений, повторяется после замены реплик; повтор
отдаёт те же `attachment_ids`.
**Отказ S3** — 503 только на загрузке и скачивании байтов; метаданные,
сообщения со ссылкой на готовое вложение, история и `/health/ready`
работают.
### Согласованность БД и S3 (change `upload-consistency`)
Инвариант порядка записи: объект, который пишет API, известен
PostgreSQL **до** записи — строка `pending` с `object_key` фиксируется
до PUT. Поэтому любой обрыв после неё оставляет «след» в БД, по которому
объект можно найти и убрать. Механизм — два слоя: компенсация в самой
загрузке (быстро, без гарантии) и уборщик (гарантия, после grace).
**Компенсация в загрузке** (`AttachmentService._mark_ready`,
`_compensate`; design, решение 1). Объект удаляется сразу, только когда
точно известно, что вложение не станет `ready`:
| Где сбой | Ответ | Объект | Строка `pending` |
| --- | --- | --- | --- |
| проверки и тело (401, 400, 404, 413, 415, обрыв клиента) | 4xx | не записывался | нет |
| tx1 — запись строки (отказ PostgreSQL) | 503 | не записывался | нет |
| PUT: S3 недоступен, срок 5 с, 5xx, отказ в доступе | 503 | не трогается: при замороженном S3 тело не уходит без ответа сервера (проба), а DELETE ждал бы ещё 5 с | уборщику |
| tx2 до отправки COMMIT (`UPDATE`, пул, срок на нём) | 503 (отказ БД) или 500 (дефект) | **удаляется до ответа** ключом API, без повторов; не удалось — `warning`, остаётся уборщику | уборщику |
| tx2 на самом COMMIT (связь оборвалась во время фиксации) | 503 | **не трогается**: вложение могло стать `ready`, удаление дало бы `ready` без объекта | уборщику, если фиксации не было |
| `mark_ready` → 0 строк (строку убрал уборщик: загрузка длилась дольше grace) | 503, `error` в журнале | **удаляется до ответа** | нет |
| процесс убит, задача отменена | — | не трогается | уборщику |
Граница «до отправки COMMIT» — флаг, который ставится прямо перед
`commit()` и только при найденной строке. Компенсация не удаляет строку:
чаще всего tx2 падает из-за отказа PostgreSQL, и удаление строки упало
бы так же; а строка без объекта безопасна — её уберёт уборщик. Обратный
порядок (строка, потом объект) при сбое второго шага оставил бы объект
без строки.
**Уборщик** — отдельный сервис `cleaner` (`python -m src.cleaner`), а не
фоновая задача реплик: N реплик были бы N уборщиками, а остановка реплики
обрывала бы проход. Раз в `[cleaner] interval_seconds` (60 с) он
выбирает строки `pending` старше `[cleaner] pending_grace_seconds`
(900 с) выборками по 100 (keyset по `(created_at, id)`, частичный индекс
`ix_attachments_pending_created_at` — план в
`evidence/migrations/pending-index.md`) и каждую убирает своей
транзакцией:
1. `SELECT … FOR UPDATE SKIP LOCKED` той же строки (всё ещё `pending` и
старше порога; нет — пропуск);
2. DELETE объекта ключом уборщика (отсутствие объекта — тоже 204);
3. DELETE строки, commit.
Объект удаляется раньше строки: сбой между шагами оставляет строку без
объекта (следующий проход её доуберёт), а не объект без строки. Строки
`ready` выборка не видит никогда.
**Зачем блокировка.** Загрузка короче grace, но процесс API, замороженный
дольше grace (`docker pause`, пауза ВМ), после разморозки дойдёт до
`mark_ready`. Без блокировки порядок «PUT → уборщик удалил объект →
`mark_ready` сделал строку `ready`» дал бы `ready` без объекта (201
клиенту, 500 при скачивании). С блокировкой `mark_ready` ждёт commit
уборщика и находит 0 строк → компенсация и 503; если `mark_ready` успел
раньше, строка уже `ready`, и уборщик её не выбирает. Транзакция
уборщика держит строку на время DELETE в S3 (≤ 5 с) — в своём пуле из
одного соединения; `[s3] timeout_seconds` 5 < `request_timeout_seconds`
6 < `idle_in_transaction_session_timeout` 10 с.
**Grace period и его обоснование.** Граница живой загрузки B — от
записи `created_at` строки до фиксации `ready`: tx1 ≤
`request_timeout_seconds` (6 с; `created_at` назначается до tx1) + PUT
≤ `[s3] timeout_seconds` (5 с) + tx2 ≤ 6 с, B = 2 × 6 + 5 = 17 с. Тело
и проверка изображения идут до `created_at`: медленный клиент B не
удлиняет. Grace 900 с — запас ×50 над B: покрывает заморозку процесса API
(профиль `failover` с `docker pause`, остановки ВМ Docker Desktop) и
расхождение часов консольного API на macOS и уборщика в ВМ (секунды).
Цена — незавершённые загрузки (а это только сбои) живут до ~16 мин
(grace + интервал + проход). Уборщик при старте проверяет `grace >
2 × request_timeout_seconds + s3.timeout_seconds` по своим настройкам и
иначе не стартует (код 2, ошибка называет grace, оба срока и границу —
`evidence/attachments/cleaner-process.md`). Стенд отказов — grace 20 с
и интервал 1 с: честное значение для тех же сроков по умолчанию.
Отвергнуто: 60 с (запас ×3,5 съедает одна пауза ВМ), 24 ч (остатки
сбоев лежат сутки, защита без разового запуска невозможна).
**Права S3 уборщика** — свой пользователь `cleaner`: чтение и удаление
объектов своего bucket, без записи, списка и прав на bucket; ключи
`S3_CLEANER_*` только у `s3-bootstrap` и `cleaner` (`make s3_check` — 68
проверок, `evidence/s3/cleaner-key.md`). Чтение сейчас не используется
(HEAD перед удалением не нужен: удаление идемпотентно, а промах HEAD — не
основание удалять) и оставлено для глубокой сверки трека 2.
**Отказы хранилищ в уборщике.** S3 недоступен, не ответил, отказал в
доступе или bucket нет — транзакция строки откатывается, проход
прерывается на первой строке (`warning`), следующий — через интервал.
PostgreSQL недоступен — проход пропускается (`warning`). Непредвиденная
ошибка — `error` с traceback, процесс живёт. Перезапуск не нужен: у
клиента S3 нет повторов, пул PostgreSQL — с `pool_pre_ping`
(`test_cleaner_survives_outages`). SIGTERM: текущая строка доводится,
выход с кодом 0 за ~0,6 с.
**Доказательства**: `evidence/attachments/consistency.md` (рабочий
стенд: S3 заморожен и сбой фиксации `ready` → 503, строки не видны,
компенсация удалила объект, `cleaner --once` убрал обе загрузки,
объектов без строки 0), `evidence/tests/failure-checks.md` (стенд
отказов: восемь проверок вложений и уборщика, в том числе kill реплики
между PUT и фиксацией), `evidence/attachments/cleaner-process.md`,
`evidence/s3/cleaner-key.md`, `evidence/migrations/pending-index.md`.
### Согласования с преподавателем
| Дата | Договорённость | Где учтено |
| --- | --- | --- |
| 2026-09-26 | FastAPI с его расхождениями (лишний 422 переведён в 400, порядок кодов: битый JSON — 400 раньше 401, остальная валидация после зависимостей) | `.claude/rules/api-contract.md`, «FastAPI» |
| 2026-09-29 | Конфиг через pydantic-settings: окружение → `.env` → `config.toml` → дефолты, `config.toml` монтируется read-only, не в образе | `.claude/rules/settings.md`, `docker.md` |
| 2026-10-20 | «Пустой текст» сообщения — и `""`, и из одних пробелов: с хотя бы одним вложением — 201 (текст как прислан), без вложений — 400 | спек `messages`, «Пробелы с вложением»; `CreateMessage`; `test_blank_text_with_attachment` |
### Ответы на вопросы защиты
- **Почему файл в Docker volume одной API-реплики не равен объектному
хранилищу?** Volume привязан к контейнеру одной реплики: другая
реплика его не видит, остановка или пересоздание реплики уносит
доступ, а LB шлёт скачивание на любую. Объектное хранилище — общий
сервис со своим volume и правами: оригинал отдаёт любая реплика
(`evidence/attachments/failover.md`: принял `5f5d4ac50d9a`, после его
`stop` / `kill` отдал `847ad74efd7c`), реплики не пишут файлы
оригиналов на диск (`docker diff`, `evidence/attachments/storage.md`),
и в S3 видно, какой объект какому вложению принадлежит (ключ с `id`).
- **Когда можно честно вернуть 201?** Когда оригинал записан в S3 (PUT
подтверждён) и метаданные в PostgreSQL зафиксированы в статусе `ready`
— после второго commit. До этого — проверки и строка `pending`,
которую API никому не показывает. Отказ S3 или БД на любом шаге — 503,
а не 201 (`test_upload_with_object_storage_stopped`).
- **Что произойдёт, если S3 PUT прошёл, а COMMIT в PostgreSQL — нет?**
Строка `pending` с ключом объекта зафиксирована **до** PUT, поэтому
объект не бывает «вечным неучтённым»: клиент получает 503, вложения
для API нет (404), а в БД есть строка, по которой его можно найти.
Дальше три случая:
- сбой **до** отправки COMMIT (`UPDATE` упал, пул, срок) — вложение
точно не станет `ready`, и API сразу удаляет объект (компенсация),
строку убирает уборщик (`test_ready_failure_compensated`: объекта нет
сразу после 503; `evidence/attachments/consistency.md`);
- связь оборвалась **во время** COMMIT — исход неизвестен, вложение
могло стать `ready`, поэтому объект не трогаем; если фиксации не
было, строка осталась `pending`, и уборщик после grace (900 с)
удалит объект и строку;
- процесс API убит между PUT и COMMIT — то же: строка `pending` и
объект, уборщик убирает оба после grace
(`test_killed_between_put_and_ready`).
Уборщик удаляет объект раньше строки и под `FOR UPDATE SKIP LOCKED`,
поэтому загрузка, пережившая grace, и уборщик не дают `ready` без
объекта. Остаток риска назван в «Ограничениях»: процесс API заморожен
дольше grace посреди самого PUT, уборщик убрал строку, а S3 принял
тело после разморозки — объект без строки, его находит только сверка
bucket и БД (трек 2).
- **Почему случайный object key и приватный bucket не заменяют ACL
приложения?** Приватный bucket закрывает прямой доступ к S3, но
скачивает через API любой аутентифицированный пользователь: кто
может читать — решает приложение по членству в чате вложения
(посторонний — 404, `evidence/attachments/smoke.md`). Случайный ключ —
не секрет: он попадает в логи, в БД, в URL, а `attachment_id`
клиенты передают друг другу в сообщениях; знание id не даёт права.
Ключ API S3 у всех реплик один и права пользователя не различает.
## Доказательства критериев
Строки S3 (change `s3-storage`) сняты на стенде `make run_docker`:
`evidence/s3/restart.md`, `client.md`, `privacy.md` — с commit
`f57635a` (правки по verify), остальные файлы `evidence/s3/` — с
`2e997f9`. Строки вложений (change `attachments`) — с `d56b892` (код
приложения `116d8d3`) на стенде `mtusi-lab4`: HAProxy и две реплики,
PostgreSQL, Valkey, S3. После правок по verify (код `dba40bc`) с
`e1f8531` переснято: `make student_test` через LB и `make
failure_checks` (`evidence/tests/student-test-lb.md`,
`failure-checks.md`) и замер `bench_rollout` на чистом дереве
(`evidence/rollout/attachments/`, `dirty: false`). Строки
согласованности БД и S3 (change `upload-consistency`) — с `5b42bd2` на
том же стенде с уборщиком `cleaner`; с него же переснято `make
student_test` через LB, `make failure_checks` и `make test_isolated`
(`evidence/tests/`).
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | `make test` (через LB и в `make test_isolated`) | `PASS: lab4 public API scenario` — загрузка fixture, сообщение с `attachment_ids`, SHA-256 скачанного оригинала, 404 постороннему | `evidence/attachments/smoke.md`, `evidence/tests/test-isolated-s3-cleanup.md` (раздел 0) |
| «3»: метаданные в PostgreSQL, байты в приватном bucket, не в БД и не на диске API | `driver.py --port 8080 attachment-storage` | из `bytea` только `sha256` (32 байта), `object_key` = `messenger/attachments/<id>/original` без `filename`, объект в bucket 111 817 байт, анонимный GET ключа — 403, `docker diff` реплик — только `config.toml`; открыли bucket анониму — код 1 «anonymous GET … got 200», bootstrap закрыл — код 0 | `evidence/attachments/storage.md` |
| «3»: POST вложения → 201 `ready` после сохранения; оригинал побайтно; `attachment_ids` читают участники; посторонний — 404 | `make test`; `driver.py upload` Алисой, `download` Бобом и Евой | 201 `status=ready`, `variants=[]`, `sha256` 99ea7533…; Боб — 200 `image/png`, 111 817 байт, тот же SHA-256 (отдала другая реплика); Ева — 404 на метаданные и байты | `evidence/attachments/smoke.md` |
| «3»: реальные PNG/JPEG ≤10 MiB и ≤40 млн пикселей, MIME по содержимому, опасные `filename`, лимиты до чтения и распаковки | `make student_test` через LB (`test_attachments.py`, 33 теста) | 10 485 760 байт — 201, +1 — 413; 30 MiB с `Content-Length` и частями — 413; 8000 × 5000 — 201, 40 000 001+ — 413; «бомба» — 415 (распаковано не больше ожидаемого объёма + 1 байт); текст, GIF, пустое тело, подмена MIME — 415; `filename` с `/`, `\`, NUL, `\n`, DEL, U+0085, пустой, 256 — 400; `a%FFb.png`, `a%C3.png`, `a%ED%A0%80b.png` — 400; U+202E, U+2066, U+2028 — 201 как есть | `evidence/tests/student-test-lb.md` |
| «3»: остановка загрузившей реплики → download через другую | `driver.py --port 8080 attachment-failover --mode stop` и `--mode kill` | загрузку принял `5f5d4ac50d9a`, `stop-one.sh` его остановил (`stop` и `kill`), метаданные и байты — 200 от `847ad74efd7c`, SHA-256 совпал, посторонний — 404; после `make replicas` обе `UP` | `evidence/attachments/failover.md` |
| «3»: restart с volumes сохраняет метаданные и оригинал | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` (`LAB=4`) | PASS: прежний токен читает данные, оригинал вложения тот же; `StartedAt` новый у всех шести контейнеров (API, LB, PostgreSQL, Valkey, S3) | `evidence/replicas/test-persistence.md` |
| «3»: failover с записью | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` (каждая реплика, `stop` и `kill`, `STOP_ONE_LOG`) | 4 × PASS, `failed_attempts` 0, восстановление 0,76–1,2 с; `STOP_ONE_LOG` — оба контейнера | `evidence/failover/test-failover.md` |
| «4»: тесты большого файла, повреждённого изображения, подмены MIME, чужого `attachment_id`, вложения другого чата; ошибка клиента не 500 | `make student_test` через LB (`test_rubric.py`: пять сценариев лабы 4), `make test_isolated` | 197 passed через LB, 192 passed + 5 пропусков тестов реплик в одном процессе (оба — `5b42bd2`); каждая ошибка — 4xx в формате контракта; сверка покрытия: 212 сценариев 13 спеков, 197 тестами (33 — проверками отказов), 15 исключений | `evidence/tests/student-test-lb.md`, `evidence/tests/test-isolated-s3-cleanup.md` |
| «4»: отказы S3 на путях вложений, отклонённая загрузка ничего не оставляет | `make failure_checks` | 29 / 29, код 0 (`5b42bd2`): S3 остановлен — загрузка 503, ровно одна новая строка `pending`, готовые те же, текст 201; скачивание 503, метаданные 200, история с `attachment_ids` 200, `/health/ready` 200; S3 заморожен — 503 не позже 5,6 с; отклонённые загрузки — ни новых строк, ни новых объектов (списки `id`); рабочий стенд не тронут | `evidence/tests/failure-checks.md` |
| «4»: прерывание загрузки и отказ между S3 и БД не оставляют вечных неучтённых объектов | `make failure_checks` (стенд отказов: уборщик с grace 20 с, интервал 1 с) | сбой записи строки (SQLSTATE 08006) — 503, ни строки, ни объекта; обрыв клиента посреди тела — ни строки, ни объекта; сбой фиксации `ready` — 503, объекта нет сразу (компенсация), строка `pending` не видна по API, на G/2 ещё на месте, после G + I + 5 с убрана; S3 заморожен на время PUT — строка убрана после grace, объект не появился; kill реплики между PUT и фиксацией — 201 не дошёл, строка и объект есть до grace, после — ни того, ни другого; во всех — объектов без строки 0 (`object-ids − attachment-ids`); красный прогон до кода — 4 из 11 упали | `evidence/tests/failure-checks.md` |
| «4»: то же на рабочем стенде через LB | `driver.py --port 8080 upload-consistency` | S3 заморожен — 503 за 5,1 с, строка `pending` с ключом; сбой фиксации `ready` — 503, объекта нет; обе строки — 404 на метаданные, байты и ссылку; `cleaner --once` (grace 30 с) — `removed 2`, код 0; строк и объектов нет, «1200 objects, 1200 rows, 0 objects without a row»; готовое вложение — тот же SHA-256; в журнале API шаги `put` / `ready` и «Deleted attachment object», `filename` — 0 вхождений | `evidence/attachments/consistency.md` |
| «4»: документированный механизм компенсации и очистки с безопасным grace period | описание и проверка старта уборщика | таблица компенсации, уборщик под `FOR UPDATE SKIP LOCKED`, B = 2 × 6 + 5 = 17 с, grace 900 с (×50); grace 17 с — код 2 с grace, обоими сроками и границей; интервал 0 и `abc` — код 2; старт — «Started cleaner» с 60 / 900 / 100; `docker compose stop cleaner` — 0,57 с, код 0 | раздел «Согласованность БД и S3», `evidence/attachments/cleaner-process.md` |
| «4»: уборщик переживает отказы хранилищ, готовые вложения не трогает | `make failure_checks` (`test_cleaner_survives_outages`); `make test-persistence` | S3 остановлен и PostgreSQL остановлен на 3 с: строка на месте после G + 3I, после возврата S3 убрана за I + 5 с без перезапуска; готовое вложение старше grace — 200 `ready`, тот же SHA-256; после `scripts/restart.sh` (`make test-persistence` — PASS) у уборщика прежний `StartedAt`, `RestartCount` 0, `cleaner --once` — код 0 | `evidence/tests/failure-checks.md`, `evidence/attachments/cleaner-process.md` (раздел 6) |
| «4»: отдельные ограниченные credentials уборщика | `make s3_check` (строки `cleaner key …`), bootstrap на пустом volume и со сменой секрета, `docker compose config` | ключ уборщика: GET / HEAD / DELETE своего объекта 200 / 200 / 204, повторный DELETE 204; запись, список, bucket, политика, ACL, чужой bucket — 403; новый секрет — ключ пересоздан, прежний — 403 `SignatureDoesNotMatch`; ключи уборщика только у `s3-bootstrap` и `cleaner`, у уборщика нет пароля Valkey, ключей API и административных | `evidence/s3/cleaner-key.md` |
| «4»: индекс уборщика без блокировки записи, план по индексу | `alembic upgrade head --sql`; с нуля, повтор, откат на временной базе; `EXPLAIN (ANALYZE, BUFFERS)` общего плана на рабочей базе с откатом; `make bench_rollout_quick` | `CREATE INDEX CONCURRENTLY IF NOT EXISTS` вне транзакции; повтор и повтор после «сбоя» проходят, `indisvalid` true; 22 000 строк (2 000 `pending`) — `Index Scan using ix_attachments_pending_created_at`, 100 кандидатов за 28–29 буферов, 0,03–0,04 мс; замена под нагрузкой `e656d6bbe1a4 → 739b8f04d5fb`, ошибок 0 | `evidence/migrations/pending-index.md` |
| «4»: длинная передача не держит соединение пула | разовый скрипт: 10 MiB частями ~12 с и скачивание с медленным чтением | 201 за 12,4 с и 200 за 13,1 с через LB, «Database is unavailable» — 0 | `evidence/attachments/slow-transfer.md` |
| «4»: rolling update на схему вложений под нагрузкой | `make bench_rollout ROLLOUT_LABEL=attachments` (с образа `e1161f7`) | `e1f8531`, `dirty: false`: замена 8,67 с, ревизия `e656d6bbe1a4` → `ef25d50b01a8`, ошибок 0 / 0 / 0, 200 успешных в секунду всё время, ответов старых после дренажа 0, сообщений = ключей 12 001 | `evidence/rollout/attachments/summary.md` |
| «4»: исключения сверки покрытия сняты на стенде лабы 4 | `driver.py cache-check --require-test-keys`, `auth-storage`, повтор после `--force-recreate api` | кэш: одно чтение `chats` на 50; Argon2id и SHA-256 токена; повтор через новый процесс — тот же `Message` с `attachment_ids` | `evidence/cache/hits.md`, `evidence/auth/passwords-and-tokens.md`, `evidence/idempotency/replay-after-restart.md` |
| «3»: S3-сервер в общем стенде, закреплённая версия | `make run_docker`, `docker compose ps` | `s3` на `chrislusf/seaweedfs:4.48@sha256:…` в состоянии `healthy`, `s3-bootstrap` — `Exited (0)`, реплики стартуют после него | `evidence/s3/privacy.md` (раздел 3), `evidence/s3/bootstrap.md` (раздел 1) |
| «3»: persistent volume S3 | `scripts/restart.sh`; `docker kill -s KILL` сервера S3 | ID контейнеров прежние, `StartedAt` новый, hook — 24 с; объекты клиента читаются с тем же SHA-256: 3/3 после рестарта, 20/20 после SIGKILL; первая запись после `healthy` — 11–27 мс в 18 рестартах и `kill` (healthcheck ждёт регистрации тома) | `evidence/s3/restart.md` |
| «3»: создание приватного bucket описано | `docker compose logs s3-bootstrap` на пустом volume | «bucket messenger created», «user api created», «checks passed» | `evidence/s3/bootstrap.md` (раздел 1), «Архитектура и решения» → «Bootstrap S3» |
| «4»: bootstrap идемпотентен | `docker compose run --rm s3-bootstrap` дважды; повтор с новым секретом; `S3_BUCKET=Bad_Bucket` | повтор — «exists», код 0, объекты на месте; новый секрет работает, прежний — 503; ошибка — код 1, «FAILED: bucket create», реплики не стартуют | `evidence/s3/bootstrap.md` |
| «4»: отдельные ограниченные credentials API | `make s3_check` (строки `api key …`); секреты по сервисам из `docker compose config` | ключ API: объекты своего bucket — 200 / 204; список, bucket, политика, ACL, чужой bucket — 403; административной пары у API нет | `evidence/s3/privacy.md` (разделы 1, 4) |
| «4»: административная консоль не в общей сети | `make s3_check`: слушающие сокеты контейнера S3 (`netstat`), затем `nc -z` из сети стенда; `docker port`; gRPC без токена | вне loopback слушают только 8333 и 18333; master, filer и volume — только на `127.0.0.1` и из сети закрыты, admin UI не слушает; со служебными серверами на `0.0.0.0` (временный стенд) — код 1 и список лишних портов; на хосте — только `127.0.0.1:8334`; `PutIdentity` без токена — `UNAUTHENTICATED` | `evidence/s3/privacy.md`, `evidence/s3/grpc-admin.md` |
| «4»: проверка private bucket вне API | `make s3_check`; затем открыть чтение `s3.anonymous.set -access Read` | 48 проверок, код 0 (`f57635a`; с уборщиком — 68, `evidence/s3/cleaner-key.md`); после открытия чтения — 10 FAIL с названиями; следующий bootstrap закрывает доступ, снова PASS | `evidence/s3/privacy.md` |
| «4»: S3 недоступен — ограниченная ошибка, текст работает | `make failure_checks` (`test_readiness_without_object_storage[stop\|pause]`); клиент при `pause` и `stop` S3, без bucket и без прав | без S3 (остановлен или заморожен) `/health/ready` и `/health/live` — 200 быстрее 1 с; вызов клиента — 503 за 1–8 мс (`stop`) или за срок 5 с (`pause`), после возврата проходит; удалённый bucket и отказ в доступе — 503 с записью `error`, а не «объекта нет» (кроме HEAD: 404 без тела) | `evidence/tests/failure-checks.md`, `evidence/s3/client.md` |
| «4»: память S3 при одновременных загрузках | 20 одновременных PUT по 10 MiB ключом API | все подтверждены, анонимная память не больше 379 MiB из 512, OOM нет; подбор лимитов API — `upload-memory` | `evidence/s3/memory.md` |
| Логи без секретов S3 | `grep -F` значений секретов по журналу клиента и `make run_dev` | 0 совпадений; отказ в учётных данных — одна запись `error` без секрета | `evidence/s3/client.md` |
| Остальные пункты уровня 4 | TODO (`upload-memory`: лимиты и таймауты загрузки, ≥10 одновременных загрузок и пик памяти) | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
## Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| `docker pause` сервера S3 | вызов клиента — 503 не позже срока 5 с | 5 004–5 005 мс, `TimeoutError` → 503, без повторов | после `unpause` следующий вызов — 8 мс; потерь нет |
| `docker compose stop s3` | плавная остановка без SIGKILL; вызовы — 503 сразу | остановка 15,3 с, код 0; вызов — 503 за 1–8 мс | после `start` первый вызов тем же клиентом проходит (29 мс) |
| SIGKILL сервера S3 сразу после 20 подтверждённых PUT | подтверждённое не теряется | 20/20 с тем же SHA-256 | `healthy` через 5 с; потерь нет |
| `scripts/restart.sh` | все хранилища и реплики перезапущены, данные целы | 24 с; bootstrap — «exists»; 3/3 объекта с тем же SHA-256 | — |
| Рестарт и SIGKILL S3, сразу первая запись | запись не ждёт регистрации тома после `healthy` | до правки healthcheck — 2 из 8 рестартов ждали 4 771 и 2 523 мс (срок 5 с); после — 11–27 мс в 12 рестартах и 6 `kill` | — |
| Bucket удалён мимо bootstrap | 503 и `error`, а не «объекта нет» | `put`, `open`, `delete` — 503, «bucket is missing» / «denied access»; `head` — `None` (404 без тела, ограничение принято) | — |
| Неверный секрет API у приложения | 503 и запись `error` без секрета | `SignatureDoesNotMatch` → 503, одна запись `error` | — |
| 20 одновременных PUT по 10 MiB | без OOM | анонимная память не больше 379 MiB; последний PUT подтверждён через 7,2 с (очередь лимита загрузок 64 МБ) | — |
| Загрузка при остановленном S3 (`make failure_checks`) | 503 быстрее срока вызова, строка `pending` остаётся, текст работает | 503; `pending` +1, `ready` без изменений; текстовое сообщение 201 | после `start` та же загрузка — 201 |
| S3 заморожен при загрузке и скачивании | 503 не позже 5 с + запас | 503 за ~5,0 с (срок вызова S3) | после `unpause` скачивание — те же байты |
| Остановка (`stop` / `kill`) реплики, принявшей вложение | скачивание через другую реплику | 200 от другой реплики, тот же SHA-256 | потерь нет, реплика возвращается `make replicas` |
| Поочерёдная замена на схему вложений под нагрузкой 100 записей + 100 чтений/с (`bench_rollout`, метка `attachments`; 2 реплики 1 CPU / 512 МБ, PostgreSQL 2 / 1 ГБ; хост на сети, давления памяти нет, `Swapouts` 0) | ошибок нет, миграция одна, старые реплики работают на новой схеме | замена 8,67 с, ошибок 0, p95 до 3 мс / макс. 31 мс в замене; первый ответ новой реплики — 3,72 с, последний старой — 8,01 с (старые писали и читали на новой схеме); ревизия `e656d6bbe1a4` → `ef25d50b01a8` (две таблицы и `NOT VALID`) | потерь нет: 12 001 сообщение = 12 001 ключ |
| Память одной загрузки 10 MiB (проба в образе API, три загрузки подряд в одном процессе) | одно тело и блок чтения | пик RSS: `bytearray` + `bytes(...)` — 1,99–2,11 тела; `BytesIO` + `getvalue()` при динамическом пороге mmap — 1,25 / 2,05 / 1,07 (копия в `realloc` на второй); с `MALLOC_MMAP_THRESHOLD_=131072` — 1,20 / 1,19 / 1,19 | — |
| Медленный клиент 10 MiB (~12 с) | загрузка и скачивание проходят, сессия БД не держится | 201 за 12,4 с, 200 за 13,1 с; в реплике загрузка — 12 430 мс | — |
| PostgreSQL отказывает при переводе в `ready` после записанного объекта (триггер, SQLSTATE 08006; рабочий стенд и стенд отказов) | 503, объект удалён до ответа, строка `pending` до уборщика | 503; объекта нет сразу; журнал — шаг `ready`, «Deleted attachment object» | строка убрана уборщиком после grace (стенд отказов: ≤ 20 + 1 + 5 с; рабочий стенд — `cleaner --once` с grace 30 с); объектов без строки 0 |
| `docker kill` реплики между PUT и фиксацией (перевод в `ready` задержан на 4 с) | 201 до клиента не доходит, после grace — ни строки, ни объекта | клиент — ошибка соединения; до grace строка `pending` и объект есть; после `start-api` и grace — убраны | — ; объектов без строки 0 |
| S3 и PostgreSQL остановлены, пока уборщику есть что убирать | строка остаётся, уборщик не падает и доводит уборку после возврата | после G + 3I при остановленном S3 строка на месте; после `start` S3 — убрана за ≤ I + 5 с, без перезапуска уборщика; готовое вложение цело | ≤ 6 с после возврата S3 |
| `docker compose stop cleaner` во время работы и на старте | выход до SIGKILL, код 0 | 0,57 с, код 0, «Stopped cleaner»; через 0,05–1 с после `up` — «Stopped cleaner before startup», 0,2 с; сразу после `up` (окно запуска интерпретатора) — SIGKILL через 10 с (137) | — |
## Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
S3 (change `s3-storage`):
- **Одна нода S3 без репликации и fsync.** SIGKILL процесса
подтверждённых объектов не теряет (`evidence/s3/restart.md`). Отказ
диска или ВМ теряет объекты, и запись, подтверждённая перед падением
ВМ, может пропасть. Учебное упрощение, как один PostgreSQL.
- **Плавная остановка SeaweedFS ~15 с**: срок зашит в filer. Поэтому
`stop_grace_period: 20s`, а `make stop` и `scripts/restart.sh` дольше
на ~15 с. На стенде отказов — 2 с: там проверяется отказ.
- **gRPC шлюза открыт в сети стенда**: отдельно его не закрыть, он
защищён ключом подписи (`evidence/s3/grpc-admin.md`).
- **Секреты S3 видны в `docker inspect`** контейнеров `s3` и
`s3-bootstrap`, как `POSTGRES_PASSWORD`. Стенд локальный, порты только
на `127.0.0.1`. TLS — лаба 7.
- **Лимит загрузок шлюза ставит запросы в очередь.** 20 одновременных
загрузок по 10 MiB заканчиваются через 7,2 с, это больше срока вызова
клиента (5 с). Подбор лимитов и сроков — change `upload-memory`.
- **Отказ S3 — 503 на путях вложений, а не отказ сервиса.** Отказ хоста,
LB и PostgreSQL стенд не переживает (`.claude/rules/balancer.md`).
Вложения (change `attachments`):
- **Проверка изображения структурная.** Обрезанный файл, битая CRC,
сломанные маркеры, поток zlib не того объёма и «бомба» — 415. Но байт,
изменённый внутри сжатых данных скана JPEG, не ловится: у формата нет
контрольной суммы, Pillow его тоже не ловит. Полное декодирование —
worker лабы 5.
- **Память загрузки ~1,2 тела, без лимита одновременных загрузок.**
Одно тело и блоки чтения botocore (порог mmap glibc закреплён в
образе, без него вторая загрузка на миг держала два тела). Около 30
одновременных загрузок по 10 MiB (~12,5 МБ каждая сверх ~120 МБ базы)
доведут реплику 512 МБ до OOM. Лимит, сроки чтения тела и замер под
конкуренцией — change `upload-memory`.
- **Ограничение текста сообщения `NOT VALID`.** Ослабленное условие
(`<= 4000`) добавлено без проверки прежних строк: они уже
удовлетворяли более строгому, а `VALIDATE` держал бы `ACCESS
EXCLUSIVE` на всё время просмотра `messages`. В каталоге ограничение
помечено «не проверено»; новые строки оно проверяет как обычно.
- **Ранний ответ на большое тело.** 404, 413 и 415 отдаются, не дочитав
тело. Через LB ответ получает любой клиент (HAProxy дочитывает тело),
httpx и `curl` — и напрямую; Python `urllib` напрямую к одной реплике
ответ теряет (`BrokenPipe`).
- **Смешанные версии во время `make rolling_update`.** Старая реплика не
знает путей вложений (404) и `attachment_ids` (400) и отдаёт сообщения
без `attachment_ids`. Окно — секунды замены. Откат на `e1161f7`
(`MIGRATE=0`) прячет вложения и показывает пустые тексты сообщений с
вложениями; схема при этом не откатывается.
- **Обрыв S3 посреди скачивания** — статус уже ушёл: клиент получает
тело короче `Content-Length`, причина — в журнале.
Согласованность БД и S3 (change `upload-consistency`):
- **Остаток риска — объект без строки.** Процесс API заморожен дольше
grace (15 мин) ровно посреди PUT, уборщик за это время убрал строку, а
после разморозки S3 принял тело. Для API PUT кончился ошибкой по сроку,
компенсации нет — объект остаётся без строки. Вероятность мала (запас
×50, заморозка посреди PUT), такой объект находит только сверка bucket
и БД (трек 2). `ready` без объекта при этом не возникает: `mark_ready`
и уборщик упорядочены блокировкой строки.
- **Проверка grace — по настройкам уборщика.** `config.toml` у API и
уборщика общий, но подмена сроков окружением только у API
(`DATABASE__REQUEST_TIMEOUT_SECONDS`, `S3__TIMEOUT_SECONDS`) обошла бы
проверку. Если появится ожидание между `pending` и `ready` (очередь
загрузок `upload-memory`), граница и проверка расширяются в том же
change.
- **Незавершённые загрузки живут до ~16 мин** (grace 900 с + интервал +
проход): они не видны по API и занимают место в bucket.
- **Вложения `ready` без ссылок из сообщений** уборщик не трогает: это
учтённые вложения (строка и объект есть), контракт срока им не задаёт.
Сюда же попадает загрузка, у которой клиент оборвал соединение уже
после тела: uvicorn задачу не отменяет, вложение становится `ready`, а
201 до клиента не доходит.
- **Компенсация добавляет до 5 с к ответу 503**, если S3 стал медленным
после удачного PUT (срок DELETE). Худший путь загрузки и так длиннее
`timeout server` HAProxy; пересмотр цепочки — `upload-memory`.
- **Пустые каталоги `<id>/` в filer SeaweedFS** после удаления объекта
живут ~2 мин (`fs.ls` их видит, список S3 — нет). Проверки и драйвер
считают объекты по файлам `original`; сверке трека 2 — учесть.
- **Окно 0 у уборщика, как у API.** SIGTERM в первые десятки мс после
старта контейнера (запуск интерпретатора до раннего обработчика)
теряется: PID 1 без обработчика, Docker через 10 с шлёт SIGKILL (137).
Данных это не портит — соединений и транзакций ещё нет
(`evidence/attachments/cleaner-process.md`, раздел 5).
- **После `make rolling_update` уборщик на прежнем образе.** Схема только
расширяется (индекс), прежний код уборщика корректен; новый код —
`docker compose up -d --no-deps cleaner` или `make run_docker`.
- **`make env_setup` дописывает только отсутствующие переменные**:
пустое или устаревшее значение уже существующей строки он не меняет —
его правят руками.