- 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>
608 lines
70 KiB
Markdown
608 lines
70 KiB
Markdown
# Отчёт — лабораторная 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` дописывает только отсутствующие переменные**:
|
||
пустое или устаревшее значение уже существующей строки он не меняет —
|
||
его правят руками.
|