Files
mtusi2026lab4/REPORT.md
T
2026-10-22 21:31:49 +03:00

1200 lines
135 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»), change `upload-memory` — места
загрузки, срок тела, одна копия тела и сроки LB пути загрузки (раздел
«Память и сроки загрузки»).
Сервер — 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`) и каждую убирает в два шага
(после двух verify):
1. транзакция пометки: `SELECT … FOR UPDATE SKIP LOCKED` той же строки
(всё ещё `pending` и старше порога; нет — пропуск), `updated_at =
now()` уборщика, commit;
2. транзакция уборки: та же блокировка (нет строки или занята —
пропуск), DELETE объекта ключом уборщика (отсутствие объекта — тоже
204), DELETE строки, commit.
Объект удаляется раньше строки: сбой между ними оставляет строку без
объекта (следующий проход её доуберёт, пометка ставится заново), а не
объект без строки. Строки `ready` выборка не видит никогда. SIGTERM
доводит только текущий шаг до commit или отката (≤ 6 с), между шагами
уборщик останавливается сам.
**Зачем блокировка.** Загрузка короче grace, но процесс API, замороженный
дольше grace (`docker pause`, пауза ВМ), после разморозки дойдёт до
`mark_ready`. Без блокировки порядок «PUT → уборщик удалил объект →
`mark_ready` сделал строку `ready`» дал бы `ready` без объекта (201
клиенту, 500 при скачивании). С блокировкой `mark_ready` ждёт commit
уборщика и находит 0 строк → компенсация и 503; если `mark_ready` успел
раньше, строка уже `ready`, и уборщик её не выбирает.
**Зачем пометка** (замечание W1 verify). В первой версии блокировка,
DELETE объекта и DELETE строки шли одной транзакцией. Её откат уже после
удачного DELETE в S3 (сбой БД перед COMMIT, срок, заморозка уборщика) или
DELETE, который S3 выполнил после срока вызова, возвращали строку
`pending` как была, и ждавший `mark_ready` делал её `ready` без объекта.
Теперь `mark_ready` переводит в `ready` только непомеченную строку
(`updated_at = created_at`: вставка пишет оба поля одним значением), а
пометка зафиксирована до DELETE объекта. Помеченная строка `ready` уже не
станет: загрузка получает 503 и удаляет свой объект, уборку доводит
следующий проход (`test_cleaner_failure_after_object_delete`). Миграции
нет, CHECK `updated_at >= created_at` выполняется.
**Зачем DELETE объекта под блокировкой** (замечание W1 повторного
verify). В первой редакции пометки объект удалялся между транзакциями,
без блокировки. Реплика до `87c48b9` пометку не проверяет: она успевала
сделать строку `ready` между commit пометки и DELETE объекта, и уборщик
удалял объект готового вложения без всякого сбоя. Теперь объект и строка
удаляются одной транзакцией под блокировкой: такая реплика либо успела
раньше (строка `ready` с целым объектом, уборщик её не находит), либо ждёт
commit и находит 0 строк (проба блокировок — design, «Уточнения apply»,
п. 21). Цена — вызов S3 внутри транзакции: ≤ 5 с (`[s3]
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 — не
основание удалять). С change `track2-reconciler` уборщику добавлен
список объектов — только с префиксом вложений своей базы — для сверки
bucket и БД (раздел «Сверка хранилищ»; 70 проверок
`evidence/s3/cleaner-list.md`).
**Отказы хранилищ в уборщике.** S3 недоступен, не ответил, отказал в
доступе или bucket нет — транзакция уборки откатывается, строка остаётся
`pending` и помеченной, проход прерывается на первой строке (`warning`),
следующий — через интервал (пометка ставится заново).
PostgreSQL недоступен — проход пропускается (`warning`). Непредвиденная
ошибка — `error` с traceback, процесс живёт. Перезапуск не нужен: у
клиента S3 нет повторов, пул PostgreSQL — с `pool_pre_ping`
(`test_cleaner_survives_outages`). SIGTERM: текущий шаг уборки доводится
до commit или отката, новые не начинаются, выход с кодом 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`.
### Память и сроки загрузки (change `upload-memory`)
Рубрика «4»: лимиты, таймауты и потоковая обработка не дают загрузкам
занять неограниченную RAM. До change лимита одновременных загрузок не
было, и проба показала больше, чем было записано в этом отчёте: при
записи в S3 тело копировалось ещё раз (пик загрузки — около двух тел, а
не 1,2), 20 одновременных загрузок по 10 MiB без swap убивали реплику
512 МБ (OOM-kill), а недочитанное тело копилось в буферах сокетов ядра —
до 32 MiB на соединение. Design change `upload-memory`, решения 1–9.
**Места загрузки — на процесс API** (`src/infra/upload_slots.py`,
`asyncio.Semaphore`): `[uploads] max_concurrent` (4) загрузки
одновременно, ещё до `max_waiting` (16) ждут места по порядку прихода, но
не дольше `wait_timeout_seconds` (5 с). Очередь полна — сразу `429
rate_limited` с `Retry-After: 1`, срок вышел — 429 по сроку; у такой
загрузки нет ни строки, ни объекта. Место берётся после проверок 401 →
400 → 404 → 415 → 413 по `Content-Length` и до чтения тела, держится до
ответа (включая запись в S3, `ready` и компенсацию) и освобождается при
любом исходе — 201, ошибка, обрыв, срок, отмена. Ранние отказы места не
ждут и не занимают: посторонний и заведомо большое тело не вытесняют
живые загрузки. Ожидающая загрузка соединения с PostgreSQL не держит.
Места считает каждая реплика сама — это допуск к обработке, как лимит
хэшей паролей, а не состояние, от которого зависит ответ. Почему 429, а
не 503: из двух кодов контракта ручки к ограничению подходит только 429
(у него одного `Retry-After`), 503 — «зависимость недоступна», и клиент
не отличил бы занятые места от отказа S3. Места ограничивают
одновременность, а не частоту, поэтому трактовка — открытый вопрос
преподавателю (`PLAN.md`, `### upload-memory`, «Вопросы», п. 1).
**Срок тела** — `[uploads] body_timeout_seconds` (30 с) на всё тело с
момента, как загрузка заняла место (`asyncio.timeout` вокруг чтения);
не успел — 400 `invalid_request` «Upload body was not received in time»,
ни метаданных, ни объекта, место свободно. Не срок простоя между
блоками: клиент, который шлёт по байту раз в 29 с, держал бы место
вечно. 30 с хватает для 10 MiB от 2,8 Мбит/с.
**Одна копия тела.** Тело копится в `BytesIO`; проверка изображения и
SHA-256 идут над `getvalue()` (`bytes` над тем же буфером), затем ссылка
на `bytes` удаляется, и в PUT уходит сам `BytesIO`. Пока ссылка жива,
буфер общий, и aiohttp при `getbuffer()` копировал тело целиком. Проба в
образе API: шаг PUT 10 MiB — 2,31 тела над базой прежним путём и 1,19
новым; в метке профиля — 2,17 и 1,20 тела на загрузку (раздел
«Одновременные загрузки» ниже).
**Буферы ядра.** У реплик `api` — `sysctls: net.ipv4.tcp_rmem "4096
131072 524288"`: буфер приёма сокета до 512 KiB вместо 32 MiB ВМ Docker
Desktop (ожидающая или отклонённая загрузка держит в ядре до 0,5 MiB). У
LB — `tune.sndbuf.server 262144` (буфер отправки к реплике) и
`tune.rcvbuf.client 131072` (буфер приёма от клиента). Второй добавлен
после первой метки профиля: в ней пик LB рос на ~2,6 MiB на клиента,
очередь приёма сокета клиента — до 9 MiB (`97a4be4`; design, «Уточнения
apply», п. 11). С ним в метке `baseline` пик LB «с лимитом» 10 MiB растёт
на (52,3 − 30,5) / 39 = 0,56 MiB на клиента от 1 до 40 клиентов (ячейки
`summary.md`), скорость одного клиента прежняя.
**Цепочка таймаутов пути загрузки** (решение 7):
| Звено | Значение | Формула и обоснование |
| --- | --- | --- |
| молчание реплики до тела | ≤ 17 с | вход и членство — по шагу БД: `2 × [database] request_timeout_seconds` (6) + `[uploads] wait_timeout_seconds` (5) |
| тело | ≤ 30 с | `[uploads] body_timeout_seconds`; простой клиента ≤ `timeout client` LB (30 с) |
| молчание реплики после тела | ≈ 26 с | проверка (до ~4 с при 4 загрузках на 1 CPU) + `pending` 6 + PUT 5 + `ready` 6 + компенсация 5 |
| `timeout server` LB пути загрузки | 30 с | больше 17 и 26 с: `http-request set-timeout server 30s if METH_POST { path_reg ^/api/v1/chats/[^/]+/attachments$ }` |
| `timeout server` остальных путей | 10 с | цепочка лабы 3 не меняется: общий 30 с держал бы любой запрос к зависшей реплике 30 с |
| наибольшая длительность загрузки U | ≈ 73 с | 17 + 30 + 26 |
| `ROLLOUT_DRAIN_TIMEOUT` | 90 с | > U и > 30 с: плановая замена не обрывает живую загрузку (было 12 с); обычный дренаж — 0–2 с |
| `graceful_shutdown_seconds` | 8 с | прежний: `stop-one.sh` и `docker stop` — отказ, загрузка дольше 8 с обрывается, строку `pending` убирает уборщик |
Ответ LB 400 (клиент замолчал посреди тела дольше `timeout client`) —
теперь в формате контракта (`http-error status 400`), как 502/503/504.
Поведение проверяет `driver.py lb-upload-timeouts` на заглушке реплики
за конфигурацией проекта (`evidence/uploads/lb-timeouts.md`).
**Граница живой загрузки уборщика прежняя** — B = `2 ×
request_timeout_seconds + s3.timeout_seconds` = 17 с. Ожидание места,
тело и проверка изображения идут до записи метаданных (`created_at`
строки `pending`), а сроки tx1, PUT и tx2 не менялись. Поэтому grace
900 с, проверка уборщика при старте и стенд отказов (grace 20 с) не
меняются; свойство закреплено сценарием `storage-consistency` «Ожидание
места не входит в возраст загрузки» (`test_upload_waits_for_slot`:
`created_at` ожидавшей позже `updated_at` той, что держала место).
Отдельного срока PUT по размеру нет: места ограничивают одновременные PUT
(4 на реплику, 12 при замене), p95 PUT при 12 — 1,6–1,9 с, а больший
срок удлинил бы B.
**Значения по умолчанию** — секция `[uploads]` (`config.toml`, подмена —
`UPLOADS__*`):
| Параметр | Значение | Почему |
| --- | --- | --- |
| `max_concurrent` | 4 | бюджет реплики 512 МБ: база ~105 MiB + хэши паролей до 4 × 64 MiB + загрузки на 4 местах (метка: пик «с лимитом» при 40 × 10 MiB — 181 MiB, то есть ~76 MiB над базой) ≈ 440 MiB; при 8 местах — больше 512 |
| `max_waiting` | 16 | сообщение несёт до 10 вложений, и клиент шлёт их разом: 10–20 одновременных загрузок по 10 MiB проходят без 429; ожидающий держит ≤ ~0,8 MiB |
| `wait_timeout_seconds` | 5 с | молчание до тела ≤ 17 с < 30 с LB; дольше ждать бессмысленно — реплика насыщена |
| `body_timeout_seconds` | 30 с | см. «Срок тела» |
| `Retry-After` | 1 с (константа) | за секунду реплика доводит несколько загрузок, повтор через LB уходит на следующую реплику |
Значения — настройки, а не константы: у установок разный лимит памяти, а
профилю `uploads` нужен вариант «без лимита». Запись «Started API»
называет все четыре. Неверное значение (`UPLOADS__MAX_CONCURRENT=0`,
`-1`, `abc`) — ошибка проверки настроек с именем поля, сервис не
стартует.
**Доказательства**: `evidence/uploads/baseline/summary.md` (память под
1–40 одновременными загрузками, три варианта кода),
`evidence/tests/failure-checks.md` (места, очередь, 429, срок тела —
«узкий по загрузкам» API стенда отказов), `evidence/uploads/lb-timeouts.md`,
`evidence/uploads/rollout-upload.md`, `evidence/tests/student-test-lb.md`
(10 одновременных загрузок через LB).
### Сверка хранилищ (трек 2, change `track2-reconciler`)
Уровень «5», трек 2 «Согласованность двух хранилищ»: повторяемый
reconciler объектов без метаданных и метаданных без объектов — с dry-run,
исправлением и повторным запуском, не трогающий свежее и используемое.
Уборщик идёт только от строк `pending`, поэтому два остаточных риска
`upload-consistency` без сверки не находил никто: объект без строки
(PUT-зомби после уборки) и строку `ready` без объекта (сбой мимо API,
объект удалён вручную). Объект, удалённый мимо API, до change давал 500
на каждое скачивание.
**Где работает.** Сверка — часть процесса уборщика, а не реплик API: у
уборщика уже есть свой пул, ключи на чтение и удаление и долгоживущий
процесс. Разовый проход — `make reconcile` (`docker compose run --rm
--no-deps cleaner reconcile [--apply] [--max-changes N]`), по умолчанию
dry-run. Плановая — в сервисе `cleaner` при старте и раз в
`[reconciler] interval_seconds`, с исправлением. Отдельный сервис и
пользователь S3 `reconciler` отвергнуты: второй процесс с доступом к той
же базе и ещё два секрета ради почти пустого разделения прав.
**Классы расхождений** (`ReconcileFinding`):
| Класс | Что это | `--apply` |
| --- | --- | --- |
| `orphan_object` | объект `<база>/attachments/<id>/original`, строки этого `id` нет и на ключ никто не ссылается | объект удаляется |
| `missing_object` | строка `ready`, объекта по её ключу нет | оригинал помечается потерянным (`lost_at`) |
| `size_mismatch` | строка `ready`, размер объекта ≠ `size_bytes` | помечается потерянным, объект не удаляется |
| `stale_pending` | строка `pending` старше grace (то же, что убирает уборщик) | убирается шагом уборщика (пометка, затем объект и строка под блокировкой) |
| `restored_object` | оригинал помечен, а объект снова есть того же размера | пометка снимается |
| `unknown_object` | ключ под префиксом, которого API не пишет, или `<id>/original`, у строки которого другой ключ | только отчёт и код 3 — не удаляется никогда |
**Проход** (design, решение 3): (1) S3 → БД — страницы ListObjectsV2 по
префиксу `<база>/attachments/` (`[reconciler] page_size`, 1000), на
страницу одно выражение к БД `id = ANY(:ids) OR object_key = ANY(:keys)`
(Bitmap OR по `pk_attachments` и `uq_attachments_object_key`, 1,5 мс на
1000 ключей; по `id` в 15 раз дешевле, чем по тексту ключа); каждый ключ
— в множество; (2) БД → S3 — keyset строк `ready` по `id` (Index Scan
`pk_attachments`, 0,6 мс на 1000), ключа нет в множестве — «метаданные
без объекта»; (3) зависшие загрузки; (4) перепроверка каждого кандидата
в БД и HEAD — в обоих режимах; (5) предел изменений; (6) с `--apply` —
действия: зависшие → объекты без строки → пометки → снятия пометок,
перед каждым ещё раз своё условие. Слияние двух отсортированных потоков
отвергнуто: порядок списка SeaweedFS — обход каталогов, а не порядок
байтов (проба), на нестандартных ключах оно дало бы ложные расхождения.
Цена множества — память O(N), ~15 МБ на 100 тыс. объектов.
**Почему два снимка (список и строки) не дают ложных расхождений.** API
пишет строку до PUT: если объект попал в список, строка его загрузки уже
зафиксирована и видна выборке, которая идёт после. Строка `ready` старше
порога стала `ready` до прохода, а её объект записан ещё раньше — список
его видит; неполный ответ списка отсекает HEAD.
**Безопасность** (решение 4):
- **что удаляется** — только объект без строки и зависшая загрузка;
строки `ready`, используемые вложения (FK `message_attachments`),
объект, на который ссылается строка любого статуса, и чужой ключ — ни
в каком классе; строка с ключом вне `<база>/attachments/` (например,
база, восстановленная под другим именем) — «чужой объект»: её объект
сверка не читает, строку не помечает и не убирает (замечание W2
verify);
- **свежее** — grace общий с уборщиком (`[cleaner] pending_grace_seconds`,
900 с): объект — по `LastModified` S3, строка `ready` — по `updated_at`,
`pending` — по `created_at`; свежее не считается расхождением;
- **перепроверка непосредственно перед действием** — строка в БД (по
`id` и по ключу) и HEAD объекта; не подтвердилось — действие не
выполняется;
- **bucket на месте** — отсутствие объекта подтверждается только после
списка с `MaxKeys=1`: удалённый bucket — `NoSuchBucket`, проход прерван,
а не «потеря всех оригиналов»;
- **предел изменений** — удалений, пометок и снятий больше
`[reconciler] max_changes` (100) — ни одного из них, `error` с числом и
пределом, код 3; больше — аргументом `--max-changes`. Он защищает от
сверки с «чужой» базой (пустой или из старой копии при живом bucket) и
от пустого пересозданного bucket. Абсолютный, а не доля: на маленьком
стенде доля слишком мала, на большом — велика;
- **параллельность** — сверка и уборщик, две сверки разом не мешают друг
другу: зависшие — под той же `FOR UPDATE SKIP LOCKED` и пометкой,
удаление объекта и условный `UPDATE` идемпотентны.
**Права S3 уборщика.** Политика `cleaner-objects` получила `s3:ListBucket`
с условием `StringLike s3:prefix <база>/attachments/*` (SeaweedFS 4.48 его
соблюдает: весь bucket, `test_<db>/`, `.s3-check/` и HEAD bucket — 403).
Префикс bootstrap берёт из `POSTGRES_DB` (`S3_CLEANER_LIST_PREFIX`,
проверка `^[a-z0-9_]+/attachments/$`), уборщик строит свой из имени базы.
`make s3_check` — 70 проверок, новые строки списка уборщика
(`evidence/s3/cleaner-list.md`).
**Потерянный оригинал и ответы API** (решение 5). Пометка — колонка
`attachments.lost_at` (ревизия `5c3e1f0a9b7d`, `ADD COLUMN … NULL` под
`SET LOCAL lock_timeout`), `status` и `updated_at` не меняются. Ответы:
скачивание помеченного — **404** `not_found` без обращения к S3 (запись
`info` «Attachment content is lost»), непомеченного без объекта — 500,
как было; метаданные — 200 тем же `Attachment`; ссылка в новом сообщении
— 201; после снятия пометки — снова 200 с байтами. Статус `lost` /
`failed` отвергнут: контракт лабы 4 знает только `ready`, и прежние
реплики упали бы на неизвестном значении при `make rolling_update`.
**Это вопрос преподавателю** (`PLAN.md`, `### track2-reconciler`,
«Вопросы», п. 1): в контракте рядом «Отсутствующий вариант ready-объекта
— 404», «404 — объекта нет» и «Неожиданное исключение — 500». Сделан
вариант по умолчанию; ответ «иначе» меняет одну ветку `open_content`,
сценарий и тесты, но не сверку.
**Плановая сверка и параметры** (`[reconciler]`, решения 9–10):
| Параметр | По умолчанию | Почему |
| --- | --- | --- |
| `interval_seconds` | 3600 с (0 — выключена) | объект без строки живёт не дольше grace + интервал + проход (~15 + 60 мин); проход на рабочем стенде (~2–3 тыс. объектов) — 0,49–0,82 с, то есть меньше секунды в час; первая сверка — при старте, иначе частые пересоздания уборщика откладывали бы её |
| `page_size` | 1000 (1–1000) | больше S3 за страницу не отдаёт; одно выражение к БД на страницу |
| `max_changes` | 100 | см. «Безопасность»; разовый проход принимает больший аргументом |
Своего grace у сверки нет — одна ручка «свежести» на всю
согласованность, со своей проверкой границы живой загрузки. Пока идёт
проход сверки, уборка зависших ждёт его конца. На стенде отказов
плановая сверка выключена (её запускают тесты), в `bench/` — тоже.
**Журнал и коды.** Находка, которая осталась, — `warning` «Found storage
discrepancy» (класс, ключ, `id`, возраст, размеры, если разные),
исправленная — `info` «Fixed storage discrepancy» с действием, итог —
«Finished reconcile pass» (просмотрено, найдено и исправлено по классам,
свежие, уже помеченные, длительность, причина прерывания), предел —
`error`; отдельных записей не больше 1000 за проход. Коды разового
прохода: 0 — расхождений нет, 3 — остались (чужие или отказ по пределу),
1 — прерван отказом S3 / PostgreSQL / сигналом, 2 — конфигурация. SIGTERM
во время сверки: сигнал проверяется перед каждым вызовом хранилища,
текущий вызов доводится — вызов S3 ≤ 5 с, шаг с БД ≤ 6 с, новых страниц
и действий нет; сервис — код 0 за 4,7 с (`evidence/reconcile/service.md`).
**Порядок обновления** (решение 6): `docker compose up -d s3-bootstrap`
(политика со списком) → `make rolling_update` (миграция, затем реплики) →
`docker compose up -d --no-deps cleaner`. Смеси не хуже, чем до change:
прежние реплики колонку не читают (у помеченного без объекта — 500, как
раньше); новый уборщик на прежней политике получает `AccessDenied` на
списке — проход сверки прерван, уборка работает. Откат — сначала
уборщик, потом реплики; колонка и пометки остаются и прежнему коду не
мешают.
**На время восстановления базы уборщик останавливают** (`docker compose
stop cleaner`): база из старой копии или пустая при живом bucket сделала
бы объекты новых вложений «объектами без метаданных», и сверка удалила
бы их в пределах `max_changes`. После восстановления — сначала `make
reconcile` (dry-run), потом `docker compose start cleaner`.
**Доказательства:** `evidence/reconcile/cycle.md` (рабочий стенд: все
шесть классов с обеих сторон, dry-run без изменений, 500 → `--apply` →
404 / 200, повтор, чужой объект, свежий объект после grace, возврат
оригинала), `evidence/reconcile/stress.md` (`--apply` раз в ~3 с под 640
загрузками и отправками: внесённое исправлено, все 640 скачиваются с тем
же SHA-256, повтор — 0), `evidence/reconcile/service.md`,
`evidence/tests/failure-checks.md` (одиннадцать проверок отказов сверки:
восемь и их красный прогон на `c13df14`, три по замечаниям verify и их
красные прогоны на `a6071da` и на временных регрессиях),
`evidence/s3/cleaner-list.md`,
`evidence/migrations/lost-at.md`. Стоимость обхода, стратегия «HEAD на
строку», глубокая сверка SHA-256 и ограничение скорости — следующий
change `track2-reconcile-cost`.
### Согласования с преподавателем
| Дата | Договорённость | Где учтено |
| --- | --- | --- |
| 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 с)
удалит объект и строку (`test_ready_commit_outcome_unknown`:
отложенный триггер роняет COMMIT, объект на месте сразу после 503,
после grace — ни строки, ни объекта);
- процесс API убит между PUT и COMMIT — то же: строка `pending` и
объект, уборщик убирает оба после grace
(`test_killed_between_put_and_ready`).
Уборщик под `FOR UPDATE SKIP LOCKED` сначала помечает строку
отдельной транзакцией, потом удаляет объект, потом строку. Помеченную
строку `mark_ready` не переводит в `ready`, поэтому загрузка,
пережившая grace, получает 503 (`test_upload_outlives_grace`), и даже
сбой уборки после удаления объекта не даёт `ready` без объекта
(`test_cleaner_failure_after_object_delete`). Остаётся случай, когда
процесс API заморожен дольше grace посреди самого PUT, уборщик убрал
строку, а S3 принял тело после разморозки и удалить его API не смог —
объект без строки. Его находит и удаляет сверка bucket и БД (change
`track2-reconciler`): плановая сверка уборщика при старте и раз в час
удаляет объект без строки старше grace, то есть такой зомби живёт не
дольше grace + интервал (~75 мин) — `evidence/reconcile/cycle.md`
(объекты O и B), `test_reconcile_finds_and_fixes`. Строку `ready` без
объекта, если она всё же появится (окно `make rolling_update` со
старыми репликами, удаление мимо API), сверка помечает потерянной:
скачивание — 404, а не 500.
- **Почему случайный 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`. После правок по verify (код
`87c48b9`: пометка строки уборщиком, три новых теста отказов) с
`87c48b9` переснято `make student_test` через LB, `make failure_checks`
и `make test_isolated` (`evidence/tests/`) и снят раздел 7
`evidence/attachments/cleaner-process.md` (отказ S3 во время прохода).
`driver.py upload-consistency` на коде `87c48b9` — тоже PASS, файл
`evidence/attachments/consistency.md` остался с `5b42bd2`: его шаги
правка не меняет. После правки по повторному verify (код `5889ca2`:
уборщик в два шага — пометка, затем объект и строка одной транзакцией
под блокировкой) с `5889ca2` переснято `make failure_checks`
(`evidence/tests/failure-checks.md`) и раздел 7
`evidence/attachments/cleaner-process.md`; `make test`, `make
student_test` через LB (197 passed, сверка 215 / 200 / 36 / 15) и
`driver.py upload-consistency` на этом коде — PASS, их файлы остались с
`87c48b9` и `5b42bd2`: правка их шагов не меняет. Строки памяти и сроков
загрузки (change `upload-memory`) — с `ce1ae2c` (код `97a4be4`): метка
`evidence/uploads/baseline/`, `evidence/uploads/lb-timeouts.md` и
`rollout-upload.md`; с того же commit переснято `make test_isolated` и
`make student_test` через LB (`evidence/tests/`), поэтому строка тестов
рубрики называет `ce1ae2c`. После правок по verify (`9d2ee30`: срок тела
«узкого» API стенда отказов 3 с вместо 2 с, код приложения прежний)
переснято `make failure_checks` (37 / 37). Строки сверки хранилищ (change
`track2-reconciler`, трек 2) — с `c1648d9` на рабочем стенде после
порядка обновления change (`evidence/reconcile/`, `evidence/s3/cleaner-
list.md`, `evidence/migrations/lost-at.md`); с того же commit снят `make
test_isolated` (`evidence/tests/`). После правок по verify (`84f8c35`:
сверка и тесты отказов, код API прежний) переснято `make failure_checks`
(48 / 48) и `make student_test` через LB, поэтому строки отказов S3, мест
загрузки и срока тела называют `84f8c35`.
| Критерий 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` | 198 passed через LB (`84f8c35`; из восьми прогонов подряд три дали по одному 503 на загрузке — PUT в S3 без тела, `KNOWN_ISSUES.md`), 193 passed + 5 пропусков тестов реплик в одном процессе (`c1648d9`); каждая ошибка — 4xx в формате контракта; сверка покрытия: 243 сценария 13 спеков, 226 тестами (61 — проверками отказов), 17 исключений | `evidence/tests/student-test-lb.md`, `evidence/tests/test-isolated-s3-cleanup.md` |
| «4»: отказы S3 на путях вложений, отклонённая загрузка ничего не оставляет | `make failure_checks` | 48 / 48, код 0 (`84f8c35`): 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, после — ни того, ни другого; COMMIT `ready` упал (отложенный триггер) — 503, объект на месте (исход неизвестен), после grace убран; загрузка дольше grace (строка «старше» на час, уборщик убрал её, пока перевод в `ready` ждал) — 503, а не 201 и не 500, ни строки, ни объекта; уборщик удалил объект, а удаление строки упало в той же транзакции уборки — 503, а не 201, `ready` без объекта нет, следующий проход доводит уборку; во всех — объектов без строки 0 (`object-ids − attachment-ids`); красный прогон до кода — 4 из 11 упали; тесты по verify: W1 — 201 на коде `f2dc0b3`, W2 и W3 — красные на временных регрессиях (компенсация на любой сбой, `RuntimeError` → 500) | `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»: отказ S3 во время прохода уборщика виден в журнале, строка не теряется | рабочий стенд (`5889ca2`): `docker compose pause s3` → загрузка через LB → `docker compose run --rm --no-deps -e CLEANER__PENDING_GRACE_SECONDS=30 cleaner --once` → `unpause` → тот же `--once` | загрузка 503, строка `pending`; проход: DELETE объекта — срок 5,01 с, `warning` «Object storage is unavailable» (`delete_object`, `TimeoutError`, без ключей) и «Interrupted cleanup pass» с `interrupted_by: object_storage`, код 1, строка на месте и помечена; после `unpause` — «Removed stale attachment», код 0, ни строки, ни файла `original` | `evidence/attachments/cleaner-process.md` (раздел 7) |
| «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 в S3 не больше 4 PUT от реплики — в метке `uploads` 503 по сроку S3 нет | `evidence/s3/memory.md`, `evidence/uploads/baseline/summary.md` |
| Логи без секретов S3 | `grep -F` значений секретов по журналу клиента и `make run_dev` | 0 совпадений; отказ в учётных данных — одна запись `error` без секрета | `evidence/s3/client.md` |
| «4»: ≥ 10 одновременных загрузок, пик памяти | `make bench_uploads` (метка `baseline`, `97a4be4`, `dirty: false`; 72 прогона: 3 варианта × 2 тела × 4 уровня × 3 повтора; реплика 1 CPU / 512 МБ без swap) | «с лимитом», 10 MiB: пик реплики 169,5 / 177,3 / 181,3 MiB при 10 / 20 / 40 клиентах, OOM 0, 5xx 0, лишние — 429; «без лимита» и код до change при 40 × 10 MiB — OOM 3/3, код до change и при 20 × 10 MiB — OOM 3/3; в паспорте — предупреждение о swap хоста (раздел «Одновременные загрузки») | `evidence/uploads/baseline/summary.md` |
| «4»: лимит одновременных загрузок, очередь и 429 | `make failure_checks`: «узкий по загрузкам» API (1 место, 1 в очереди, ожидание 1 с, срок тела 3 с; прогон `84f8c35`) | при полной очереди — 429 `rate_limited` быстрее 0,5 с, по сроку ожидания — 429 не раньше 1 с, `Retry-After` ≥ 1, ни строки, ни объекта; 404 / 413 / 415 — раньше очереди; место освобождается после 413, 415, 400 по сроку, обрыва и 503; ожидавшая — 201, её `created_at` позже `updated_at` державшей место | `evidence/tests/failure-checks.md` |
| «4»: срок передачи тела | `make failure_checks` (`test_slow_body`) | прогон `84f8c35`: тело частями дольше срока тела стенда (4 с при сроке 3 с) — 400 «Upload body was not received in time», ни строки, ни объекта; мелкими частями в срок — 201 с тем же SHA-256 | `evidence/tests/failure-checks.md` |
| «4»: 10 одновременных загрузок проходят | `make student_test` через LB и `make test_isolated` (`test_concurrent_uploads`) | 10 участников одного чата, PNG ~1 MiB: все 201, `id` разные, скачиваются побайтно — и через LB, и на одном процессе | `evidence/tests/student-test-lb.md`, `evidence/tests/test-isolated-s3-cleanup.md` |
| «4»: таймауты LB пути загрузки | `driver.py lb-upload-timeouts` на текущем `haproxy.cfg` и на `f894040` | сейчас: молчание 12 с до и после тела — 201, другой путь — 504 через 10,01 с, 32 с — 504 через 30,11 с, клиент молчит посреди тела — 400 JSON через 30,02 с; на `f894040` — 502 / 504 через 10 с и 400 HTML (код 1) | `evidence/uploads/lb-timeouts.md` |
| «4»: плановая замена не обрывает загрузку | две загрузки ~20 и ~26 с через LB во время `make rolling_update` | обе 201 с тем же SHA-256; дренаж реплики с загрузкой — 14 с, остановка после ответа (`ROLLOUT_DRAIN_TIMEOUT` 90 с) | `evidence/uploads/rollout-upload.md` |
| «5», трек 2: ошибки внесены с обеих сторон, найдены и исправлены, повтор находит 0 | `driver.py --port 8090 reconcile-cycle` (рабочий стенд, `c1648d9`) | внесены O (объект без строки), X (чужой ключ), удалён объект A (в сообщении), удалена строка B, размер C +1, обрыв COMMIT P; после grace 30 с dry-run — 6 находок своих классов (`orphan_object` ×2, `missing_object`, `size_mismatch`, `stale_pending`, `unknown_object`), код 3, строки, объекты и пометки не изменились; байты A — 500; `--apply` — O, B удалены, P убрана, A и C помечены, свежий F не тронут, X остался (код 3); байты A — 404, метаданные 200 = ответ загрузки, история отдаёт A; повтор — только X; после удаления X оператором — код 0; F удалён после grace; A возвращён — `restored_object`, 200 с тем же SHA-256; итоговый dry-run — код 0; 45 проверок, PASS | `evidence/reconcile/cycle.md` |
| «5», трек 2: dry-run, `--apply`, повторный запуск; коды выхода | `make reconcile`, плановая сверка уборщика при старте (`--apply`), `docker compose run … cleaner reconcile` с чужим объектом и с неверными `RECONCILER__*`; `driver.py reconcile-signal` | стенд после обновления: плановая сверка при старте — 2 086 объектов и строк, `found {}`; `make reconcile` — `found {}`, код 0; чужой объект старше grace — `warning` «Found …», код 3, после его удаления — код 0; `driver.py reconcile-signal` (временный проект, `84f8c35`): разовый `--apply` при замороженном S3 и `docker stop` — код 1, `interrupted_by: stop`, остановка 5,0 с; `RECONCILER__PAGE_SIZE=5000`, `MAX_CHANGES=0`, `INTERVAL_SECONDS=-1`, `--max-changes 0` — код 2 с именем поля | `evidence/reconcile/service.md` |
| «5», трек 2: свежие и используемые вложения не удаляются, ничего подтверждённого не теряется под нагрузкой | `driver.py --port 8090 reconcile-stress` (4 клиента × 40 с, `--apply` раз в ~3 с, grace 20 с); `make failure_checks` (11 проверок сверки, `84f8c35`) | 640 загрузок 201 и 640 сообщений, 9 проходов `--apply` с кодом 0; внесённые 2 объекта без строки удалены, 2 потери помечены, новых пометок — только они; каждое из 640 вложений — тот же SHA-256, сообщения отдают свои вложения; повтор — 0; на стенде отказов: свежие объект и вложение не тронуты, вложение в сообщении только помечено (метаданные 200, история с `id`), чужой ключ не удалён (код 3), предел 2 при 3 изменениях — ни одного (код 3, `error`), S3 остановлен — код 1 без изменений, сбой БД на пометке — код 1, повтор доводит; плановая сверка с интервалом 1 с помечает потерю сама; объект, на который ссылается строка (в том числе строка другого `id`), — чужой, не удалён; отказ по пределу не мешает уборке зависшей загрузки; строка с ключом вне `<база>/attachments/` — чужая, без пометки и уборки; красный прогон на `c13df14` — 8 из 8 упали, проверки по verify — 1 из 3 на `a6071da`, 2 из 2 на временных регрессиях | `evidence/reconcile/stress.md`, `evidence/tests/failure-checks.md` |
| «5», трек 2: права S3 для сверки, схема пометки | `make s3_check`; bootstrap с неверным префиксом; `alembic` с нуля / повтор / откат / `--sql`; `make rolling_update` | ключ уборщика: список `messenger/attachments/` — 200, всего bucket, `.s3-check/` и чужого bucket — 403, 70 проверок PASS; неверный `S3_CLEANER_LIST_PREFIX` — код 1; `ADD COLUMN lost_at` после `SET LOCAL lock_timeout = '2s'`, ревизия `739b8f04d5fb` → `5c3e1f0a9b7d` поочерёдной заменой за 12 с | `evidence/s3/cleaner-list.md`, `evidence/migrations/lost-at.md` |
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) | — |
| Объект мимо API, удалённый объект, удалённая строка, изменённый размер, обрыв COMMIT, чужой ключ (рабочий стенд, `reconcile-cycle`) | dry-run находит всё и ничего не меняет, `--apply` исправляет безопасное, повтор — 0 | 6 находок, снимки до и после dry-run равны; `--apply` — 5 исправлений, чужой ключ остался (код 3); после его удаления и grace — код 0 | объект без строки живёт ≤ grace + интервал сверки; байты помеченного — 404, а не 500 |
| `--apply` раз в ~3 с под 4 × 40 с загрузок и отправок (`reconcile-stress`) | внесённое исправлено, подтверждённое цело | 640 / 640 загрузок скачиваются с тем же SHA-256, новых пометок — только 2 внесённые | потерь нет |
| `docker compose stop cleaner`, пока сверка ждёт замороженный S3 | выход до SIGKILL, код 0, итог «остановка» | 4,7 с, код 0, «Finished reconcile pass» с `interrupted_by: stop` | следующий старт — сверка до конца, расхождений нет |
### Одновременные загрузки: гипотезы (change `upload-memory`)
Гипотезы записаны до первого прогона метки профиля `uploads` и
зафиксированы отдельным commit раньше commit с результатами (спек
`load-benchmark`, «Загрузки в отчёте»). Числа в них — из проб design
change `upload-memory` (Context, «Пробы»), а не из метки. Расхождение с
результатом метки гипотезу не меняет: вывод пишется ниже, после прогона.
Методика (design, решение 10): `make bench_uploads` на стенде
`mtusi-bench` — LB, одна реплика API 1 CPU / 512 МБ без swap
(`memswap_limit` = память), PostgreSQL, Valkey и S3 с лимитами рабочего
стенда. Варианты: «до» — образ `f894040` (код до change), «без лимита» —
текущий код с `UPLOADS__MAX_CONCURRENT=1000`, `UPLOADS__MAX_WAITING=0`, «с
лимитом» — значения по умолчанию (4 места, 16 в очереди). Тела — PNG из
шума около 1 MiB и около 10 MiB; C ∈ {1, 10, 20, 40} одновременных
клиентов без пауз (на 429 — пауза `Retry-After`); 3 повтора; на каждый
прогон — новые реплика и volume S3; пик — `memory.peak` cgroup реплики,
сброшенный в начале окна.
- **H1 — «с лимитом»:** пик памяти реплики при 10 MiB и C = 10, 20, 40 не
больше половины лимита контейнера (256 MiB). Сверх пика при C = 10 — не
больше 1 MiB на каждого клиента. OOM нет, ответов 5xx нет, лишние
загрузки получают 429.
- **H2 — «без лимита» и «до»:** у «без лимита» пик растёт примерно на
1,2–1,3 тела на клиента, и при 40 × 10 MiB реплика завершена ядром из-за
памяти (OOM-kill). У «до» пик растёт на ~2,1 тела на клиента (вторая
копия тела при PUT), и реплика убита уже при 20 × 10 MiB.
- **H3 — пропускная способность:** загрузок 201 в секунду при C ≥ 10 у «с
лимитом» не меньше 90 % от «без лимита» на тех же C, пока «без лимита»
жив: предел задаёт S3 (7–8,5 загрузки по 10 MiB в секунду на реплику), а
не места. p95 у «с лимитом» растёт на время ожидания в очереди.
- **H4 — срок записи в S3:** 503 из-за срока PUT (5 с) нет ни в одном
варианте, пока реплика жива: в S3 не больше 4 PUT от одной реплики
(формулировка design, решение 10; p95 PUT при 12 одновременных на пробе
— 1,6–1,9 с).
### Одновременные загрузки: результаты метки `baseline`
- Метка: `evidence/uploads/baseline/` (commit с результатами — `ce1ae2c`,
гипотезы — `511e285`, раньше). Код и стенд — `97a4be4`, `dirty: false`,
посторонних контейнеров в ВМ нет; 72 прогона, ~45 мин, 2026-10-22.
- Стенд: LB 1 CPU / 256 МБ, реплика 1 CPU / 512 МБ без swap (буфер приёма
`4096 131072 524288`), PostgreSQL, Valkey, S3 1 CPU / 512 МБ; образ «до»
— `f894040`. Тела — PNG из шума: 1 048 276 байт (1024 × 341) и
10 479 107 байт (1024 × 3409). Окно — 3 с разгона и 20 с, клиенты без
пауз; на прогон — новые реплика и volume S3. Хост: Apple M3 Pro,
18 ГиБ, macOS 26.6.2; Docker Desktop 29.9.1, ВМ 12 CPU / 7,7 ГиБ, ядро
7.0.14-linuxkit; питание от сети, свободно 49 % памяти до и 51 %
после.
- **Предупреждение паспорта** (метка принята с пометкой, решение
пользователя 2026-10-22): «host swapped out 7464 pages during the run».
Вся выгрузка пришлась на один прогон — `limited-10MiB-c40-r2` (пометка
`host_swap`). Пик памяти в нём такой же, как у повторов (180,7 MiB
против 181,3 и 182,8), искажено только время: 9,95 загрузки/с против
~11,0 и p95 2 815 мс против ~2 050. Медиана ячейки (11,00/с, 181,3 MiB)
и выводы H1–H4 от него не зависят.
- **Первая метка отброшена** (на `511e285`): swap хоста 337 056 страниц
и `dirty: true`. Из неё взят только рост пика LB «с лимитом» на ~2,6
MiB на клиента (38,8 → 139,9 MiB от 1 до 40 клиентов): сценарий
`load-balancing` «Буферы соединений ограничены» не выполнялся, и это
дало правку `97a4be4` (`tune.rcvbuf.client`).
Медианы трёх повторов, тело 10 MiB (из `summary.md` метки; «пик» —
`memory.peak` реплики за окно, сброшенный перед нагрузкой; при OOM —
наибольшая выборка):
| Вариант | C | Пик, MiB | OOM | 201 | 429 | 5xx | Загрузок/с | p95, мс | Пик LB, MiB |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| до | 1 | 130,7 | 0/3 | 258 | 0 | 0 | 11,20 | 106 | 31,9 |
| до | 10 | 322,1 | 0/3 | 215 | 0 | 0 | 9,25 | 1 479 | 30,3 |
| до | 20 | 454,2 | 3/3 | 1 | 0 | 380 | 0 | — | 37,7 |
| до | 40 | 493,5 | 3/3 | 0 | 0 | 760 | 0 | — | 53,2 |
| без лимита | 1 | 120,7 | 0/3 | 263 | 0 | 0 | 11,45 | 106 | 30,3 |
| без лимита | 10 | 225,4 | 0/3 | 208 | 0 | 0 | 8,85 | 1 485 | 30,5 |
| без лимита | 20 | 330,9 | 0/3 | 218 | 0 | 0 | 9,00 | 2 712 | 38,2 |
| без лимита | 40 | 507,3 | 3/3 | 0 | 0 | 760 | 0 | — | 52,3 |
| с лимитом | 1 | 120,7 | 0/3 | 253 | 0 | 0 | 10,95 | 113 | 30,5 |
| с лимитом | 10 | 169,5 | 0/3 | 258 | 0 | 0 | 10,80 | 1 214 | 36,1 |
| с лимитом | 20 | 177,3 | 0/3 | 269 | 0 | 0 | 10,90 | 2 059 | 42,9 |
| с лимитом | 40 | 181,3 | 0/3 | 269 | 452 | 0 | 11,00 | 2 092 | 52,3 |
Те же медианы, тело ~1 MiB (OOM нет ни в одной ячейке, 5xx — 0):
| Вариант | C | Пик, MiB | OOM | 201 | 429 | 5xx | Загрузок/с | p95, мс | Пик LB, MiB |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| до | 1 | 110,0 | 0/3 | 1 445 | 0 | 0 | 62,85 | 17 | 30,8 |
| до | 10 | 136,8 | 0/3 | 2 976 | 0 | 0 | 129,85 | 108 | 34,4 |
| до | 20 | 153,0 | 0/3 | 2 950 | 0 | 0 | 127,85 | 196 | 37,6 |
| до | 40 | 199,2 | 0/3 | 3 043 | 0 | 0 | 132,15 | 365 | 52,8 |
| без лимита | 1 | 109,0 | 0/3 | 1 477 | 0 | 0 | 64,05 | 17 | 30,8 |
| без лимита | 10 | 127,1 | 0/3 | 2 946 | 0 | 0 | 128,30 | 107 | 34,8 |
| без лимита | 20 | 138,0 | 0/3 | 3 026 | 0 | 0 | 131,75 | 203 | 37,4 |
| без лимита | 40 | 163,2 | 0/3 | 3 045 | 0 | 0 | 131,95 | 367 | 52,7 |
| с лимитом | 1 | 109,0 | 0/3 | 1 480 | 0 | 0 | 64,20 | 17 | 30,5 |
| с лимитом | 10 | 119,7 | 0/3 | 2 822 | 0 | 0 | 124,00 | 106 | 34,6 |
| с лимитом | 20 | 127,0 | 0/3 | 2 728 | 0 | 0 | 118,75 | 211 | 38,3 |
| с лимитом | 40 | 132,2 | 0/3 | 2 751 | 460 | 0 | 119,60 | 210 | 52,5 |
Память до окна во всех ячейках — ~105 MiB, пик старта реплики (фиктивный
хэш пароля, разогрев) — ~152,6 MiB и в пик окна не входит.
Выводы (строки «Гипотезы» и «Сценарии спеков» `summary.md`):
- **H1 — подтверждена.** «С лимитом» пик 169,5 / 177,3 / 181,3 MiB при 10
/ 20 / 40 клиентах — меньше половины лимита (256 MiB); рост сверх C = 10
на клиента — (177,3 − 169,5) / 10 = 0,78 MiB при C = 20 и (181,3 −
169,5) / 30 = 0,39 MiB при C = 40 (порог 1); OOM 0, 5xx 0, лишние
загрузки — 429 (1 351 за ячейки 10 MiB, строка «Сценарии спеков»).
Строка H1 сводки метки считает 429 по обоим телам и C = 1 (2 731): так
разбор сводки работал до правки по verify, новые метки считают только
ячейки гипотезы. Сценарий `attachments` «Память не растёт с числом
загрузок» выполнен. `load-balancing` «Буферы соединений ограничены»
(C = 1 → 40, ячейки «с лимитом» 10 MiB) — пик LB (52,3 − 30,5) / 39 =
0,56 MiB на клиента, `sock` реплики (19,4 − 4,1) / 39 = 0,39 MiB, в
сумме 0,95 MiB при пороге 1 MiB, OOM 0: выполнен. Вердикта по нему в
сводке метки нет — его строку разбор пишет с правки по verify, числа
выше — из ячеек той же сводки.
- **H2 — подтверждена.** «Без лимита»: 1,20 тела на клиента при C = 10 и
1,13 при C = 20 (чуть ниже ожидаемых 1,2–1,3), при 40 × 10 MiB — OOM
3/3. «До»: 2,17 тела на клиента при C = 10 — вторая копия тела при PUT,
при 20 × 10 MiB — OOM 3/3. Сценарий `attachments` «Одна копия тела при
записи в S3» (≤ 1,5 тела у «без лимита», больше у «до») выполнен.
- **H3 — подтверждена.** «С лимитом» / «без лимита» на тех же C: 10 MiB —
122 % и 121 % при 10 и 20 клиентах (10,80 / 8,85 и 10,90 / 9,00), 1 MiB
— 97 / 90 / 91 % при 10 / 20 / 40. На 10 MiB с местами даже быстрее —
вероятно, потому что без лимита один CPU реплики делит между 10–20
проверками изображения, а S3 — между 10–20 PUT (метка этого не
разбирает). На 1 MiB 90 % при C = 20 — ровно на пороге. p95 «с
лимитом» растёт на ожидание в очереди (2 059 мс при 20 клиентах).
- **H4 — подтверждена.** 503 нет ни в одном из 63 прогонов без OOM, в
том числе у «без лимита» при 20 клиентах по 10 MiB.
- Ограничения измерения: один хост с ВМ Docker Desktop, генератор k6 на
том же хосте и в той же ВМ, одна нода S3; пик — по cgroup реплики, без
разбора памяти внутри процесса; окно 20 с и 3 повтора. Пробные метки
`quick-uploads-*` в git не идут.
## Ограничения и следующие шаги
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 одновременных
PUT по 10 MiB напрямую заканчиваются через 7,2 с — больше срока вызова
клиента (5 с). Через API столько PUT не бывает: места загрузки дают не
больше 4 PUT от реплики (12 при замене, p95 1,6–1,9 с), и в метке
`uploads` 503 по сроку S3 нет (change `upload-memory`, решение 8).
- **Отказ S3 — 503 на путях вложений, а не отказ сервиса.** Отказ хоста,
LB и PostgreSQL стенд не переживает (`.claude/rules/balancer.md`).
Вложения (change `attachments`):
- **Проверка изображения структурная.** Обрезанный файл, битая CRC,
сломанные маркеры, поток zlib не того объёма и «бомба» — 415. Но байт,
изменённый внутри сжатых данных скана JPEG, не ловится: у формата нет
контрольной суммы, Pillow его тоже не ловит. Полное декодирование —
worker лабы 5.
- **Память загрузки — ~1,2 тела на загрузку, загрузок на реплике — не
больше 4.** Прежняя оценка «~1,2 тела» была неверна: проверка
моделировала только botocore, а aiohttp при PUT копировал тело ещё раз
(до change — 2,17 тела на загрузку, OOM при 20 × 10 MiB). После change
`upload-memory` — 1,20 тела (одна копия), а число одновременных
загрузок ограничено местами (раздел «Память и сроки загрузки»; порог
mmap glibc в образе по-прежнему нужен).
- **Ограничение текста сообщения `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 кончился ошибкой по сроку,
компенсации нет — объект остаётся без строки. То же, если PUT прошёл
после уборки, `mark_ready` вернул 0 строк, а удаление при компенсации
не удалось (`warning` «Attachment object kept for cleaner»). Вероятность
мала (запас ×50, заморозка посреди PUT); с change `track2-reconciler`
такой объект удаляет плановая сверка не позже grace + интервал сверки
(~75 мин). `ready` без объекта при этом не возникает:
уборщик помечает строку до удаления объекта, а помеченную `mark_ready`
в `ready` не переводит.
- **Смесь версий уборщика и реплик.** Реплики до `87c48b9` (`f2dc0b3`
и раньше) пометку не проверяют, а прежний уборщик её не ставит;
`make rolling_update` уборщика не пересоздаёт. Обе смеси не хуже, чем
до правки:
- новый уборщик + прежние реплики: объект и строка удаляются одной
транзакцией под блокировкой, прежний `mark_ready` либо делает строку
`ready` с целым объектом (уборщик её пропускает), либо ждёт commit и
находит 0 строк;
- прежний уборщик + новые реплики — поведение до правки.
В обеих для загрузки, пережившей grace, остаётся прежний риск: откат
транзакции уборки после удачного DELETE в S3 даёт `ready` без объекта.
Нужно совпадение зомби дольше 15 мин и сбоя в окне меньше секунды.
Порядок обновления сокращает окно: вперёд — сначала реплики (`make
rolling_update`), потом `docker compose up -d --no-deps cleaner`;
откат реплик на версию раньше `87c48b9` — сначала уборщик (его откат
или `docker compose stop cleaner`), потом `make rolling_update
COMMIT=… MIGRATE=0`. Новый `mark_ready` работает на строках прежних
реплик (вставка всегда писала `created_at` = `updated_at`).
- **Проверка grace — по настройкам уборщика.** `config.toml` у API и
уборщика общий, но подмена сроков окружением только у API
(`DATABASE__REQUEST_TIMEOUT_SECONDS`, `S3__TIMEOUT_SECONDS`) обошла бы
проверку. Очередь загрузок change `upload-memory` границу не меняет:
ожидание места, тело и проверка идут до `pending` (раздел «Память и
сроки загрузки»).
- **Незавершённые загрузки живут до ~16 мин** (grace 900 с + интервал +
проход): они не видны по API и занимают место в bucket.
- **Вложения `ready` без ссылок из сообщений** уборщик не трогает: это
учтённые вложения (строка и объект есть), контракт срока им не задаёт.
Сюда же попадает загрузка, у которой клиент оборвал соединение уже
после тела: uvicorn задачу не отменяет, вложение становится `ready`, а
201 до клиента не доходит.
- **Компенсация добавляет до 5 с к ответу 503**, если S3 стал медленным
после удачного PUT (срок DELETE). Это учтено в цепочке пути загрузки:
молчание после тела ≈ 26 с < `timeout server` LB пути загрузки 30 с
(change `upload-memory`).
Память и сроки загрузки (change `upload-memory`):
- **Места считает каждая реплика.** Одна может отвечать 429, пока у
другой места есть; LB 429 не повторяет. Сглаживают очередь (16) и
`Retry-After: 1` — повтор клиента уходит на следующую реплику
(round-robin). Общей очереди на стенд нет.
- **Оборванный клиент в очереди держит её место до срока ожидания**
(5 с): обрыв соединения API замечает, только когда начинает читать
тело, то есть получив место. Пока такая загрузка ждёт, новая может
получить 429 при полной очереди; затем она берёт место, сразу
заканчивается `interrupted` и отпускает его (проба verify). Места
загрузки она не держит дольше обычной.
- **429 или 503 — вопрос преподавателю открыт** (`PLAN.md`, «Вопросы»,
п. 1). Ответ «503» поменяет строку таблицы ошибок, сценарии спеков и
ожидания тестов, но не подход.
- **Тело отклонённой загрузки реплика дочитывает и выбрасывает**
(uvicorn держит соединение): памяти это не стоит (буферы ограничены),
но тратит CPU и сеть. Закрывать соединение после раннего ответа нельзя:
ядро сбросило бы его вместе с непрочитанным ответом.
- **Буфер приёма LB от клиента — 128 KiB.** Окно TCP клиента — ~20
Мбит/с при RTT 50 мс (10 MiB за ~4 с); клиенту с RTT больше ~370 мс
10 MiB за срок тела 30 с не передать.
- **Тысячи одновременных загрузок упрутся в LB**: ~0,5 MiB на
соединение в буферах ядра, а `maxconn` 4096 больше лимита LB 256 МБ.
На стенде нагрузки такого уровня нет.
- **Скачиваний без лимита.** Медленный клиент держит буферы отдачи у
реплики и LB; лимит одновременных скачиваний вне change.
- **В консоли (`make run_dev`) ограничения буфера сокетов нет** —
`sysctls` только у контейнеров `api`; места и срок тела работают.
- **408 на медленные заголовки — страницей HAProxy, не в формате
контракта** (`timeout http-request` 10 с; `http-error` такой ответ не
меняет, `errorfile` дал бы статичный `request_id`) — `KNOWN_ISSUES.md`.
- **Зависшая реплика держит загрузку 30 с до 504** вместо 10 — только на
пути загрузки; обнаружение отказа проверками LB прежнее (6,5 с).
- **`ROLLOUT_DRAIN_TIMEOUT` 90 с**: застрявшая загрузка задерживает
замену до ~73 с (срок тела); обычный дренаж — 0–2 с.
- **Замер памяти — один хост** (ВМ Docker Desktop, генератор на том же
хосте, одна нода S3), предупреждение о swap хоста в паспорте метки —
раздел «Одновременные загрузки: результаты».
- **Пустые каталоги `<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` дописывает только отсутствующие переменные**:
пустое или устаревшее значение уже существующей строки он не меняет —
его правят руками.
Сверка хранилищ (change `track2-reconciler`):
- **Источник истины — PostgreSQL.** База из старой копии или пустая при
живом bucket сделает объекты новых вложений «объектами без
метаданных», и сверка удалит их в пределах `max_changes` (100). По
истине БД это верно, но восстановление базы «в живую» при работающем
уборщике опасно: поэтому на время восстановления уборщик
останавливают, а после — сначала `make reconcile` (dry-run).
- **Чужой объект живёт, пока его не удалит оператор**: код 3 и `warning`
на каждом проходе плановой сверки. Удалять непонятное опаснее (в лабе 5
под префиксом появятся варианты).
- **Повреждение того же размера не видно**: сверка поверхностная —
наличие и размер из LIST. Скачивание сверяет тоже только размер.
SHA-256 — глубокая сверка change `track2-reconcile-cost`.
- **Память O(N) на ключи списка** (~15 МБ на 100 тыс. объектов при лимите
уборщика 256 МБ) и **уборка зависших ждёт конца прохода сверки** (на
рабочем стенде — меньше секунды, на 100 тыс. — порядка минуты). Замер —
следующий change. При массовом расхождении (N ≫ предела) `--apply`
перепроверяет каждого кандидата (SELECT + HEAD) и только потом
отказывает по пределу: ранний отказ сделал бы отчёт и число изменений в
ошибке неполными — решение и замер в `track2-reconcile-cost`.
- **Зависшая загрузка с ключом вне префикса вложений своей базы**: сверка
её только называет (чужой объект), а сервис уборки, как и до change,
убирает её вместе с объектом по этому ключу (`KNOWN_ISSUES.md`).
- **Пометка по ложному «нет объекта»** при неполном списке отсечена HEAD и
проверкой bucket; остаётся bucket, пересозданный пустым между
проверкой и `UPDATE` — тогда пометка верна и снимается сама, когда
объект вернётся.
- **Две сверки разом** (плановая и разовая) — действия идемпотентны,
отчёты могут разойтись в числах `fixed`; блокировки нет.
- **Часы**: `LastModified` — часы ВМ, порог — часы контейнера уборщика
(одни часы), точность `LastModified` — секунда; `updated_at` строк
консольного API на macOS расходится на секунды — меньше grace.
- **Ответ API на потерянный оригинал — трактовка контракта**, вопрос
преподавателю открыт (раздел «Сверка хранилищ»).
- **Старый образ уборщика после `make rolling_update`** — сверки нет, как
до change; новый — `docker compose up -d --no-deps cleaner` (порядок
обновления).
- **Синтетика прогонов драйвера** (`reconcile-cycle`, `reconcile-stress`)
остаётся в рабочей базе и bucket: согласованные вложения и помеченные
потерянными — одно за прогон цикла и два за прогон стресса
(`lost_known` 1 → 3; их байты — 404).
- **`make failure_checks` дольше на ~4,5 мин** (48 проверок, ~9 мин):
объекты нельзя состарить, тесты ждут grace стенда (20 с).