feat: implement lab 4 attachments and storage reconciliation

This commit is contained in:
2026-10-27 22:14:19 +03:00
parent ec540a1a72
commit fea6770389
128 changed files with 27650 additions and 24 deletions
+35
View File
@@ -0,0 +1,35 @@
---
name: lab4-bench
description: Load measurements of lab 4 for grade 5 — peak memory of concurrent attachment uploads (level 4, profile uploads) and the cost of the bucket/database reconcile pass (track 2, profile reconcile). Use when asked to run benchmarks, make bench-uploads / bench-reconcile (or their -quick self-checks), or fill REPORT.md with measured numbers and hypothesis outcomes.
---
# Замеры лабы 4 (уровень 4 и трек 2)
Порядок работы — **`bench/RUNBOOK.md`**, правила стенда —
`bench/AGENTS.md`. Прочитать оба целиком (`cat`) до первой команды
`make bench-*`; корневой `AGENTS.md` (разделы 2, 8–11) действует всегда.
Коротко:
1. Шаг 0 RUNBOOK: ресурсы ВМ Docker (≥ 10 CPU, ≥ 7 ГиБ, ядро ≥ 6.12),
самопроверки разбора (`bench/analysis.py`, `uploads.py`,
`reconcile.py` с `--selftest`), `make test-isolated`,
`make failure-checks`, `make stop`, самопроверки
`make bench-uploads-quick` и `make bench-reconcile-quick`. Остановка и
отчёт пользователю.
2. Уровень 4: `make bench-uploads` (~45 мин) → `evidence/uploads/baseline/`;
таблица ячеек и итоги U1–U4 из `summary.md` — в `REPORT.md`.
3. Трек 2: `make bench-reconcile` (~45 мин) →
`evidence/reconcile/baseline/`; таблицы проходов и фоновой нагрузки,
итоги H1–H5 — в `REPORT.md`.
4. Шаг 3 RUNBOOK: строки `TODO (Codex)` в `REPORT.md`, раздел «Железо и
стенд замеров» из `meta.json`, `make lint`, `make check`,
`make test-isolated`, уборка `vlad-bench*`.
Нельзя: переписывать гипотезы после замеров, менять код приложения или
профиль ради результата, править файлы меток руками, перезаписывать или
удалять каталоги меток без согласия, считать числа вручную вместо
`summary.md`. Долгие команды — в фоне с журналом (`nohup make … >
/tmp/bench-*.log 2>&1 &`), docker — вне sandbox с одобрения пользователя.
`found differs from the model`, `aborted`, `host_warnings` — остановиться
и сказать пользователю.
+40
View File
@@ -0,0 +1,40 @@
---
name: messenger-stand
description: Run, check and operate the lab 4 messenger stand — HAProxy with API replicas, PostgreSQL, Valkey, SeaweedFS S3 with bootstrap, the cleaner. Use when asked to start or stop the stand, run make test / student-test / test-isolated / failure-checks / s3-check, show X-Instance-Id distribution, stop one replica (test-failover, attachment-failover), restore replicas, run cleanup or reconcile, do a rolling update, or reproduce an API bug over HTTP.
---
# Стенд мессенджера лабы 4
Команды — корневой `AGENTS.md`, раздел 4; устройство стенда, S3,
уборщик, таймауты, скрипты — `infra/AGENTS.md`; тесты —
`student-tests/AGENTS.md`.
| Задача | Команда |
|---|---|
| поднять стенд (LB + 2 реплики + хранилища + S3 + уборщик) | `make up` → `127.0.0.1:${HOST_PORT:-8080}` |
| публичный smoke / свои тесты | `make test`, `make student-test` |
| всё на чистом отдельном стенде | `make test-isolated` (smoke, тесты, attachment-failover, test-failover, test-persistence) |
| проверки отказов | `make failure-checks [FAULT_ARGS=-rP]` |
| приватность bucket вне API | `make s3-check` |
| вложение после остановки принявшей реплики | `make attachment-failover [STOP_MODE=kill]` |
| реплики за LB | `make instances`, `make lb-stats` |
| отказ каждой реплики по очереди | `make failover-each [STOP_MODE=kill]` |
| вернуть реплики / изменить число | `make replicas [API_REPLICAS=3]` |
| уборка незавершённых загрузок / сверка (dry-run) | `make cleanup-once` / `make reconcile [STRATEGY=head] [DEEP=1]` |
| обновить код без простоя | `make rolling-update` |
| остановить / удалить контейнеры | `make stop` / `make down` (volume остаются) |
Правила:
- Порт занят другим сервисом — не убивать процесс: другой порт в `.env`
(`make env HOST_PORT=… S3_HOST_PORT=…` до первого `make up`) и
`BASE_URL=http://localhost:<порт>` у тестов.
- Тесты против рабочего стенда оставляют в базе и bucket синтетические
данные; чистый прогон — `make test-isolated`.
- `make reconcile APPLY=1` меняет рабочий стенд (удаляет объекты без
строки, помечает потерянные оригиналы) — только с согласия
пользователя; без `APPLY` — только отчёт.
- `make wipe`, `docker compose down -v` и любое удаление volume — только
с согласия пользователя.
- Пароли и ключи S3 из `.env` и токены не печатать; в `evidence/` —
только обезличенный вывод (`evidence/AGENTS.md`).
+168
View File
@@ -0,0 +1,168 @@
# Правила команд Codex для проекта (execpolicy, Starlark).
#
# Действуют на команды, которые Codex запускает вне sandbox (docker, сеть):
# allow — без вопроса;
# prompt — спросить пользователя перед каждым запуском;
# forbidden — не запускать никогда.
# Несколько совпавших правил — побеждает самое строгое (forbidden →
# prompt → allow). pattern — точный префикс аргументов команды; список в
# позиции — варианты. match / not_match — примеры, которые Codex
# проверяет при загрузке правил.
#
# Файл загружается, только если проект доверенный (слой .codex/ проекта
# trusted). После правки — перезапустить Codex. Проверка правила (команда —
# без «--» перед ней: с ним ничего не сопоставляется):
# codex execpolicy check --pretty --rules "$PWD/.codex/rules/messenger.rules" git push
#
# Источник запретов — корневой AGENTS.md, раздел 2 «Нельзя»; правила их
# дублируют на уровне команд, но не заменяют.
# --- git: только смотреть; изменения — по просьбе пользователя -------------
prefix_rule(
pattern = ["git", ["status", "diff", "log", "show", "rev-parse", "ls-files"]],
decision = "allow",
justification = "Read-only git commands are always fine.",
match = ["git status", "git diff --stat", "git log --oneline -5"],
not_match = ["git commit -m x"],
)
prefix_rule(
pattern = ["git", ["commit", "checkout", "switch", "reset", "stash", "rebase", "merge", "restore", "tag", "branch"]],
decision = "prompt",
justification = "AGENTS.md: git changes only when the user asked for them (commit message in English, conventional style).",
match = ["git commit -m 'feat: x'", "git reset --hard", "git checkout main"],
not_match = ["git status"],
)
prefix_rule(
pattern = ["git", ["push", "clean"]],
decision = "forbidden",
justification = "Never push or clean the working tree: the user does it; git clean would delete evidence and local files.",
match = ["git push", "git push origin main", "git clean -fdx"],
)
# --- данные стендов: удаление только с согласия -----------------------------
prefix_rule(
pattern = ["make", "wipe"],
decision = "prompt",
justification = "make wipe deletes the working stand volume (all data). Ask the user first (AGENTS.md, section 2, item 8).",
match = ["make wipe"],
)
prefix_rule(
pattern = ["docker", "compose", "down", "-v"],
decision = "prompt",
justification = "down -v deletes volumes. The bench and test stands remove their own projects themselves; for the working stand ask the user.",
match = ["docker compose down -v", "docker compose down -v --remove-orphans"],
not_match = ["docker compose down"],
)
prefix_rule(
pattern = ["docker", "volume", ["rm", "prune"]],
decision = "prompt",
justification = "Deleting volumes deletes data: only bench leftovers (vlad-bench*) and only with the user's consent.",
match = ["docker volume rm vlad-bench_pgdata", "docker volume prune -f"],
)
prefix_rule(
pattern = ["docker", ["rm", "kill", "stop", "pause"]],
decision = "prompt",
justification = "Only own containers (vladimirceva-lab4*, vlad-bench*); never containers of other projects.",
match = ["docker rm -f vlad-bench-gen", "docker stop some-container"],
)
prefix_rule(
pattern = ["docker", ["system", "builder", "image", "container", "network"], "prune"],
decision = "forbidden",
justification = "Prune touches every project on this machine. Remove own leftovers by name instead (bench/AGENTS.md).",
match = ["docker system prune -af", "docker image prune -a"],
)
# --- процессы: не убивать по порту вслепую ------------------------------------
prefix_rule(
pattern = [["kill", "pkill", "killall"]],
decision = "prompt",
justification = "Kill only a PID whose command is `python -m src` (AGENTS.md, section 10). A published port on macOS belongs to com.docker.backend: killing it stops Docker Desktop.",
match = ["kill 12345", "pkill -f uvicorn"],
)
prefix_rule(
pattern = ["rm", ["-rf", "-fr", "-r"]],
decision = "prompt",
justification = "Recursive delete: label folders in evidence/ are removed only with the user's consent (bench/AGENTS.md).",
match = ["rm -rf evidence/scaling/quick-x"],
)
# --- проект: проверки, стенд, замеры — без вопроса ----------------------------
prefix_rule(
pattern = [
"make",
[
"install", "lint", "fmt", "check", "validate", "test", "load",
"test-persistence", "test-failover", "student-test", "test-isolated",
"failure-checks", "requirements", "requirements-check", "env",
"docker-build", "up", "stop", "down", "logs", "db-up", "run",
"migrate-local", "replicas", "instances", "lb-stats",
"failover-each", "rolling-update",
"attachment-failover", "s3-check", "cleanup-once",
"bench-uploads", "bench-uploads-quick", "bench-reconcile",
"bench-reconcile-quick",
"bench-failover", "bench-failover-quick", "bench-rollout",
"bench-rollout-quick", "bench-scaling", "bench-scaling-quick",
"bench-compare", "bench-plots",
],
],
decision = "allow",
justification = "Project targets: checks, the working stand without deleting data, bench profiles (bench/RUNBOOK.md).",
match = ["make lint", "make test-isolated", "make bench-uploads", "make bench-reconcile-quick", "make failover-each STOP_MODE=kill"],
not_match = ["make wipe", "make reconcile APPLY=1"],
)
# make reconcile без APPLY — dry-run: ничего не меняет
prefix_rule(
pattern = ["make", "reconcile"],
decision = "allow",
justification = "Dry-run reconcile only reports discrepancies (exit 0 or 3).",
match = ["make reconcile", "make reconcile STRATEGY=head DEEP=1"],
)
# с APPLY=1 сверка удаляет объекты без строки и помечает потерянные
# оригиналы в рабочей базе: спросить пользователя
prefix_rule(
pattern = ["make", "reconcile", "APPLY=1"],
decision = "prompt",
justification = "reconcile --apply deletes orphan objects and marks lost originals in the working stand: ask the user first.",
match = ["make reconcile APPLY=1", "make reconcile APPLY=1 MAX_CHANGES=10"],
)
prefix_rule(
pattern = ["docker", ["ps", "info", "version", "inspect", "logs", "images", "events", "exec", "cp", "build", "tag", "run", "start", "unpause"]],
decision = "allow",
justification = "Inspecting and running own stand containers; deletion is covered by stricter rules above.",
match = ["docker ps -a", "docker info", "docker logs -t vlad-bench-lb"],
)
prefix_rule(
pattern = ["docker", "compose"],
decision = "allow",
justification = "Compose of this project; down -v is prompted by the stricter rule above.",
match = ["docker compose ps", "docker compose logs api"],
)
prefix_rule(
pattern = ["uv", ["run", "sync", "lock", "export"]],
decision = "allow",
justification = "Project environment from uv.lock; new dependencies still need the user's consent (AGENTS.md, section 2, item 11).",
match = ["uv run pytest", "uv sync", "uv run python bench/reconcile.py --selftest"],
)
prefix_rule(
pattern = [["python3", "python"], ["scripts/lab4.py", "student-tests/stand.py", "tests/smoke.py", "tests/resilience.py", "scripts/check_contract.py"]],
decision = "allow",
justification = "Project scripts on the host Python (stdlib only).",
match = ["python3 scripts/lab4.py s3-check", "python3 student-tests/stand.py isolated"],
)
+14
View File
@@ -18,3 +18,17 @@ __pycache__
node_modules
evidence
.DS_Store
.codex
.agents
tests
student-tests
bench
contracts
infra
scripts
**/AGENTS.md
**/__pycache__
**/*.pyc
**/.DS_Store
*.md
**/*.md
+25 -1
View File
@@ -1,6 +1,7 @@
# Copy to .env for your LOCAL synthetic test environment; never commit .env.
# These are logical interface suggestions; map actual framework names in REPORT.md.
APP_HOST=0.0.0.0
# Host process (make run); the container binds 0.0.0.0 in Dockerfile.
APP_HOST=127.0.0.1
APP_PORT=8080
APP_ENV=lab
SESSION_TTL_SECONDS=3600
@@ -11,6 +12,8 @@ SESSION_STORE=postgres
CACHE_URL_FILE=/run/secrets/cache_url
API_REPLICAS=2
IDEMPOTENCY_TTL_SECONDS=86400
# Lab 4 logical names (skeleton). Containers get S3_ENDPOINT from compose.yaml,
# make run overrides it with 127.0.0.1:S3_HOST_PORT; keys come from the lines below.
S3_ENDPOINT=http://s3:9000
S3_REGION=us-east-1
S3_BUCKET=messenger-attachments
@@ -18,3 +21,24 @@ S3_ACCESS_KEY_ID_FILE=/run/secrets/s3_access_key_id
S3_SECRET_ACCESS_KEY_FILE=/run/secrets/s3_secret_access_key
MAX_UPLOAD_BYTES=10485760
MAX_IMAGE_PIXELS=40000000
# Compose and make run. make env fills the empty passwords and keys locally.
HOST_PORT=8080
POSTGRES_USER=messenger
POSTGRES_DB=messenger
POSTGRES_PASSWORD=
POSTGRES_HOST_PORT=5433
VALKEY_PASSWORD=
VALKEY_HOST_PORT=6380
LOG_LEVEL=INFO
SHUTDOWN_TIMEOUT=5
# S3 (SeaweedFS): the root pair and the signing key stay with the s3 server;
# the API and the cleaner have their own users created by s3-bootstrap.
S3_HOST_PORT=8334
S3_ROOT_ACCESS_KEY=
S3_ROOT_SECRET_KEY=
S3_JWT_SIGNING_KEY=
S3_API_ACCESS_KEY=
S3_API_SECRET_KEY=
S3_CLEANER_ACCESS_KEY=
S3_CLEANER_SECRET_KEY=
+8
View File
@@ -25,8 +25,16 @@ bin/
obj/
coverage/
*.log
!evidence/**/raw/*.log
.DS_Store
.idea/
.vscode/
# Temporary benchmark state and self-check results are not submission evidence.
bench/.bench.lock
evidence/failover/quick-*/
evidence/rollout/quick-*/
evidence/scaling/quick-*/
evidence/uploads/quick-*/
evidence/reconcile/quick-*/
# Keep small, sanitized evidence summaries in evidence/ under version control.
# Inspect git diff --cached: ignore rules are not a secret scanner.
+1
View File
@@ -0,0 +1 @@
3.13
+340
View File
@@ -0,0 +1,340 @@
# AGENTS.md — мессенджер MTUSI, лабораторная 4
REST API мессенджера с вложениями-изображениями: реплики API за HAProxy,
PostgreSQL — источник истины (в том числе метаданные вложений), Valkey —
кэш карточек чатов, S3 (SeaweedFS) — байты в приватном bucket. Код
перенесён из сданной лабы 3: загрузка PNG/JPEG (201 `ready`), скачивание
через API, `attachment_ids`, уборщик, сверка bucket и БД. Цель — **«5»**:
уровни 3 и 4 `README.md` и трек 2 «Согласованность двух хранилищ».
**Состояние (23 октября 2026).** Код, тесты, стенд и все проверки без
нагрузки готовы и сняты на машине разработки (`evidence/`, таблица
доказательств `REPORT.md`): `make test-isolated` — все 0,
`make failure-checks` — 24 passed, `make s3-check` — 63 проверки без
нарушений. Самопроверки `make bench-uploads-quick` и
`make bench-reconcile-quick` прошли. **Остались замеры под нагрузкой на
машине замеров** — порядок в `bench/RUNBOOK.md`: профили `uploads`
(уровень 4, пик памяти) и `reconcile` (трек 2, стоимость обхода), итоги
гипотез U1–U4 и H1–H5 в `REPORT.md` (строки `TODO (Codex)`). Гипотезы
записаны до замеров — не переписывать.
Стек: Python 3.13, FastAPI, uvicorn, pydantic v2, SQLAlchemy Core 2.1 +
asyncpg, alembic, argon2-cffi, redis-py, aiobotocore 3.x; PostgreSQL
18.6, Valkey 9.1.2, HAProxy 3.4.6, SeaweedFS 4.48; uv, pip +
`requirements.txt` с хешами (в образе), pytest + httpx.
## 1. Где инструкции и как их читать
Codex сам загружает `AGENTS.md` от корня репозитория до рабочего
каталога (вместе — не больше 32 КиБ). Правила слоёв лежат глубже,
поэтому **перед правкой файла прочитай каждый `AGENTS.md` на пути к
нему** (`cat`), даже если задача «на одну строку».
| Файл | Когда читать |
|---|---|
| `AGENTS.md` (этот) | всегда: запреты, команды, карта, Definition of Done |
| `src/AGENTS.md` | любая правка в `src/`: слои, импорты, ошибки, конфиг (таблица переменных), точка входа, уборщик, логи, время |
| `src/api/AGENTS.md` | роуты, схемы, middleware, вход и Bearer, `X-Instance-Id`, `Idempotency-Key`, вложения |
| `src/services/AGENTS.md` | бизнес-правила, отправка с ключом, загрузка вложения, уборка и сверка |
| `src/storage/AGENTS.md` | PostgreSQL: транзакции, гонки, ключ идемпотентности, вложения; кэш Valkey; объекты S3 |
| `migrations/AGENTS.md` | схема БД, новые ревизии, совместимость с работающей версией |
| `infra/AGENTS.md` | `Dockerfile`, `compose.yaml`, S3 и bootstrap, уборщик, HAProxy и цепочка таймаутов, `scripts/*.sh`, `scripts/lab4.py` |
| `student-tests/AGENTS.md` | собственные тесты, отдельные стенды, проверки отказов |
| `evidence/AGENTS.md` | доказательства для `REPORT.md` |
| `bench/AGENTS.md` | нагрузочный стенд: методика, честность результатов |
| `bench/RUNBOOK.md` | замеры лабы 4 по шагам; читать перед любым `make bench-*` |
Ещё Codex читает **правила команд** `.codex/rules/messenger.rules` (что
идёт вне sandbox без вопроса, что с подтверждением, что запрещено;
только у доверенного проекта, после правки — перезапуск Codex; проверка
— `codex execpolicy check --pretty --rules "$PWD/.codex/rules/messenger.rules"
make wipe`, команда без `--`) и **навыки** `.agents/skills/`: `lab4-bench` (замеры по
`bench/RUNBOOK.md`), `messenger-stand` (стенд, проверки, демонстрация).
Правила дублируют раздел 2, но не заменяют его.
Конфликт: более глубокий файл уточняет корневой, но не отменяет
раздел 2. Прямая просьба пользователя в чате важнее этих файлов, кроме
пунктов раздела 2, помеченных «спросить»: там сначала переспроси.
## 2. Нельзя
1. **Менять skeleton преподавателя** (спросить): `contracts/`, `tests/`,
`scripts/` (кроме своих `restart.sh`, `stop-one.sh`,
`rolling-update.sh`, `lab4.py`), `lab.json`, `README.md`, `COURSE.md`,
`CONTRIBUTING.md`, `MAINTAINERS.md`, `Dockerfile.example`,
`compose.example.yaml`, `infra/README.md`, `requirements-dev.txt`,
`evidence/README.md`, `examples/`, `.github/`, верх `Makefile` до
строки `=====`. Публичный тест упал — чиним приложение.
2. **Подгонять тесты под код**: ослаблять `assert`, менять ожидаемый
статус, ставить `skip`/`xfail`, удалять тест, чтобы прогон позеленел.
3. **Состояние в памяти процесса, от которого зависит корректность**:
сессии, данные, ключи идемпотентности и метаданные — только
PostgreSQL, байты вложений — только S3 (не диск реплики и не БД);
Valkey — только кэш неизменяемой карточки чата. `--workers`,
gunicorn, `reload` в образе: масштабирование — числом реплик. Sticky
session в HAProxy. Уборка и сверка — только процесс `cleaner`, не
реплики.
4. **Порты реплик наружу и `container_name` у `api`**; консоль,
master, volume, filer SeaweedFS и мониторинг LB — наружу.
5. **Файлы конфигурации приложения** (`config.toml`, pydantic-settings с
файлами): настройки — только переменные окружения (`src/config.py`).
6. **JSON-логи, structlog, `print`** вместо логгера (`src/log.py`).
7. **Писать в лог** текст сообщений, `display_name`, `title`, username,
`filename` (только длину), пароль, токен, ключи S3, их хэши,
`Authorization`, `Idempotency-Key`, тела, параметры SQL. Можно id,
ключ объекта S3, длины и размеры.
8. **Git без просьбы**: `commit`, `push`, `checkout`, `reset`, `stash`,
`rebase`, `clean`. Смотреть можно: `status`, `diff`, `log`.
9. **Удалять данные стенда без просьбы** (спросить): `make wipe`,
`docker compose down -v`, `docker volume rm`, `FLUSHALL` рабочего
Valkey, `TRUNCATE`/`DROP` в рабочей базе, удаление объектов рабочего
bucket мимо API; каталоги меток в `evidence/`.
10. **Секреты и `.env`** в git, образ, `evidence/`, вывод и отчёт; `COPY .
.` в Dockerfile. Пароли, токены и ключи S3 в командной строке не
печатать. Административную пару S3 — никому, кроме сервера `s3`.
11. **Незакреплённые версии**: `latest`, тег без digest, пакет без lock.
12. **Новая зависимость** (спросить): объяснить, зачем она и почему не
хватает stdlib и текущих пакетов; проверить точное имя пакета.
13. **Миграция, которая ломает работающую версию** (удаление,
переименование, `NOT NULL` без значения): только расширение схемы,
contract — отдельной ревизией позже (`migrations/AGENTS.md`). Править
применённую ревизию нельзя.
14. **`HTTPException`** в сервисах и хранилище, **403** для чужого чата
или вложения, **422** наружу: ошибки только через `src/errors.py`.
Прозрачные повторы `POST` (кроме отказа соединения в LB).
15. **Обходить sandbox Codex** (раздел 10): нет сети или docker — просить
одобрение или пользователя.
16. **Выдумывать результаты**: в отчёт, `REPORT.md` и `evidence/` — только
реальный вывод команд, которые ты запустил. Гипотезы U1–U4 и H1–H5
после замеров не переписывать.
17. **Чинить попутно найденное** без просьбы: записать в
`KNOWN_ISSUES.md` (путь, симптом, предложение) и сказать в отчёте.
18. **Менять код приложения ради замеров** (спросить): профили `bench/`
проверяют записанные гипотезы на коде, который уже проверен.
## 3. Порядок работы
1. Найди, откуда требование: `README.md` (рубрика), `contracts/README.md`
(семантика, раздел «Вложения (с lab4)»), `contracts/openapi.json`
(схемы, коды), `COURSE.md` (переходы API). Неясно или противоречит
контракту — остановись и спроси. Ответ преподавателя — в раздел 12.
2. Прочитай нужные `AGENTS.md` (раздел 1) и затрагиваемые файлы целиком.
3. Задача больше пары файлов — сначала короткий план в чате.
4. Минимальный дифф: не переименовывать и не «улучшать» лишнее.
5. Проверки из раздела 8 — до того, как сказать «готово».
6. Отчёт пользователю — раздел 11.
## 4. Команды
| Команда | Что делает |
|---|---|
| `make install` / `make env [HOST_PORT=…]` | `uv sync` / `.env` со случайными паролями и ключами S3 (существующий дополняется) |
| `make up` | postgres, valkey, s3 → migrate, s3-bootstrap → api × `API_REPLICAS` (2), cleaner → haproxy на `127.0.0.1:HOST_PORT` (8080); ждёт healthy |
| `make stop` / `make down` / `make logs` | остановить / удалить контейнеры (volume остаются) / журнал реплик |
| `make wipe` | удалить контейнеры и volume `pgdata`, `s3data`: только после `yes` (раздел 2, п. 9) |
| `make replicas [API_REPLICAS=N]` / `make instances` / `make lb-stats` | вернуть реплики / `X-Instance-Id` одной сессии / слоты HAProxy |
| `make failover-each [STOP_MODE=kill]` | `make test-failover` для каждой реплики по очереди |
| `make attachment-failover [STOP_MODE=kill]` | вложение → стоп принявшей реплики → скачивание через другую (тот же SHA-256), 404 постороннему |
| `make s3-check` | приватность bucket вне API: права ключей, анонимно с хоста и из сети, порты S3 |
| `make cleanup-once` / `make reconcile [APPLY=1] [MAX_CHANGES=N] [STRATEGY=head] [DEEP=1] [RATE=R]` | разовый проход уборщика / разовая сверка, по умолчанию dry-run (0 / 3 / 1 / 2) |
| `make rolling-update` | поочерёдная замена реплик без простоя |
| `make db-up` / `make run [RUN_PORT=8081]` / `make migrate-local` | хранилища и bootstrap / процесс на хосте без LB / миграции с хоста |
| `make lint` / `make fmt` | ruff: проверка / исправление и формат |
| `make test [BASE_URL=...]` | публичный smoke (вложение, SHA-256, 404 постороннему) |
| `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | данные, токен и оригинал после рестарта LB, реплик и всех хранилищ |
| `make test-failover ACTION_SCRIPT=scripts/stop-one.sh [STOP_MODE=kill]` | отказ одной реплики: запись ≤ 10 с, без дублей |
| `make student-test [BASE_URL=...] [EXPECT_REPLICAS=...]` | свои тесты против запущенного стенда (без проверок отказов) |
| `make test-isolated` / `make failure-checks [FAULT_ARGS=-rP]` | отдельный стенд: всё выше (~2 мин) / проверки отказов (~4 мин) |
| `make check` / `make validate PYTHON=.venv/bin/python` | офлайн-проверка skeleton / валидация OpenAPI |
| `make requirements` / `make requirements-check` | `requirements.txt` из `uv.lock` / сверка |
| `make bench-uploads` / `make bench-reconcile` (+ `-quick`) | лаба 4 под нагрузкой (`bench/RUNBOOK.md`); `quick-*` в отчёт не идут |
| `make bench-failover`, `bench-rollout`, `bench-scaling` | профили лабы 3 (сохранены, в лабе 4 не обязательны) |
Проверки ходят на `http://localhost:8080` (HAProxy). Внешние порты —
`HOST_PORT`, `POSTGRES_HOST_PORT` (5433), `VALKEY_HOST_PORT` (6380),
`S3_HOST_PORT` (8334) в `.env`; разовая подмена — аргументом make (`make
test BASE_URL=http://localhost:8090`). В сети стенда: 8080, 5432, 6379,
8333, 8404. Тесты против рабочего стенда оставляют данные; чистый прогон
— `make test-isolated`.
## 5. Карта кода
```
src/ пакет приложения: python -m src (__main__ → early_stop.install() → main.run())
main.py create_app(): Db, кэш, хранилище, клиент S3, места загрузок, пароли, middleware, роутеры
config.py Settings.from_env(): только окружение (Database, Cache, ObjectStorage, Uploads, Cleaner, сроки)
early_stop.py SIGTERM/SIGINT до старта сервера: строка журнала и выход 0 (stdlib)
constants.py, log.py, errors.py, clock.py, domain.py, pagination.py, healthcheck.py
images.py структурная проверка PNG/JPEG без декодирования пикселей (stdlib)
db.py, cache.py PostgreSQL (пул, сроки, transaction()/read()) и Valkey (срок, обход при отказе)
s3.py ObjectStore (aiobotocore): put/head/get/delete/list, срок на вызов и блок, без повторов, счётчики
uploads.py UploadSlots: места загрузок процесса, очередь, срок ожидания → 429
passwords.py Argon2id в потоке с лимитом, фиктивный хэш
cleaner/ python -m src.cleaner: уборка незавершённых загрузок, сверка (разовая и плановая)
api/ routes/ (health, users, sessions, chats, messages, attachments), schemas, deps,
identity (BearerBackend), request_id, handlers
services/ User/Session/Chat/Message/Attachment/Cleanup/ReconcileService; access.py
storage/ base.py (Storage, MaintenanceStorage), postgres.py, cached.py, tables.py, objects.py (AttachmentObjects)
migrations/ alembic: 0001 схема лабы 2, 0002 idempotency_keys, 0003 attachments (expand)
student-tests/ тесты по HTTP; stand.py — отдельные стенды; fault_hook.py; images.py; fixtures/
bench/ run.py, common.py, uploads.py, reconcile.py, fill_objects.py, loadgen.py, sampler.py, analysis.py, RUNBOOK.md
infra/haproxy/ haproxy.cfg: DNS Docker, проверки /health/ready, цепочка таймаутов, путь загрузки 40 с, буферы
infra/valkey/ valkey.conf: лимит памяти, LRU, без persistence
infra/s3/ bootstrap.sh: bucket, политики, пользователи API и уборщика, проверки приватности
scripts/ restart.sh, stop-one.sh, rolling-update.sh, lab4.py (свои); остальное — skeleton
.codex/rules/ правила команд Codex; .agents/skills/ — навыки Codex
evidence/ доказательства для REPORT.md; uploads/, reconcile/ — метки стенда
Dockerfile, compose.yaml, alembic.ini, pyproject.toml, uv.lock, requirements.txt, .env.example
```
Поток загрузки: HAProxy → реплика → middleware (401) → роут (400) →
`AttachmentService` (404, 415, 413, место 429, тело, структура) →
`pending` (PostgreSQL) → PUT (S3) → `ready` → 201; сбой между ними —
компенсация или уборщик (`src/services/AGENTS.md`).
## 6. Контракт: самое важное
Полностью — `src/api/AGENTS.md` и `contracts/`. Переход 3 → 4
(`COURSE.md`): вложения и `attachment_ids`; текстовые POST лабы 3
остаются валидными.
- Каждый ответ API — с `X-Request-Id` и `X-Instance-Id`; ошибка —
`{"error": {"code", "message", "request_id"}}`. Коды: 400, 401, 404
(нет или чужое — одинаково), 409, 413, 415, 429 (с `Retry-After`), 503
(PostgreSQL или S3), 500; 422 и 403 — никогда.
- Загрузка — сырые байты, 201 `ready` только после PUT и фиксации
строки; ключ объекта назначает сервер, `filename` — для показа. Байты —
только через API участникам чата.
- Сообщение: `attachment_ids` до 10, `ready` из того же чата; пустой
текст — только с вложением. Повтор с тем же ключом (24 ч) — тот же 201.
## 7. Конфигурация, логи, Docker, зависимости
**Переменные окружения** читает только `src/config.py`; неверное
значение — выход с кодом 2. Группы: `APP_*`, `LOG_LEVEL`,
`SHUTDOWN_TIMEOUT`, `KEEP_ALIVE_TIMEOUT`; `SESSION_TTL_SECONDS`,
`IDEMPOTENCY_TTL_SECONDS`, `KDF_CONCURRENCY`; `DB_*`, `CACHE_*`, `S3_*`,
`UPLOAD_*`, `CLEANER_*`, `RECONCILE_*`. Таблица — `src/AGENTS.md`.
Логические имена `.env.example` skeleton и их соответствие — `REPORT.md`,
«Конфигурация». Лимиты контракта (10 MiB, 40 млн пикселей, 10 вложений)
— константы `src/constants.py`, не окружение.
**Логи**: строка на событие, `время уровень логгер [rid=...] сообщение
key=value`; итог сверки `reconcile pass finished …` разбирает
`bench/reconcile.py` — имена полей не менять.
**Docker, compose, S3, HAProxy** — `infra/AGENTS.md`. Числа менять только
вместе: обнаружение отказа ≤ 10 с; `timeout server` пути загрузки 40 с >
ожидание места 5 с + срок тела 30 с; `CLEANER_GRACE` 900 с > граница
живой загрузки 21 с; дренаж замены 90 с > 40 с.
**Зависимости**: `pyproject.toml` → `uv lock` → `make requirements` →
`make requirements-check` → пересборка образа.
## 8. Definition of Done
- [ ] `make fmt`, затем `make lint` — без ошибок;
- [ ] `make test-isolated` — в `results` все 0;
- [ ] правка хранилища, вложений, уборщика, сверки, сессий, ключей, кэша,
`db.py`, `cache.py`, `s3.py`, таймаутов — ещё `make failure-checks`;
- [ ] правка `compose.yaml`, `haproxy.cfg`, `infra/s3/`, `scripts/*` —
`make up`, `make test`, `make instances`, `make s3-check`,
`make attachment-failover`, `make test-persistence
ACTION_SCRIPT=scripts/restart.sh`, `make failover-each`; скрипт
замены — `make rolling-update`;
- [ ] правка схемы — новая expand-ревизия, `alembic check` без
расхождений (`migrations/AGENTS.md`);
- [ ] правка `Dockerfile`, зависимостей — `make up`, все `(healthy)`,
`make test`, `make requirements-check`;
- [ ] правка `bench/` — самопроверки разбора и `make bench-*-quick`
(`bench/AGENTS.md`);
- [ ] новое поведение из рубрики — тест в `student-tests/`;
- [ ] изменилось описанное в `REPORT.md`, `evidence/`, `AGENTS.md` —
обновлено там же;
- [ ] остановлены серверы и удалены контейнеры, которые ты запустил
(кроме рабочего стенда, если он работал до тебя).
Не смог выполнить пункт (нет сети, docker, порт занят) — так и напиши,
с причиной. «Должно работать» не считается проверкой.
## 9. Если тест или проверка упали
1. Воспроизведи и прочитай вывод целиком.
2. Назови причину: **дефект приложения** → чинить код; **ошибка в самом
тесте** (противоречит контракту или зависит от случайного) → править
тест можно, но назови, чему он противоречил; **стенд** (порт занят
чужим сервисом — smoke получает 404 на `/health/live`, старый образ,
не тот `BASE_URL`, остатки прерванного прогона, реплика ещё не `UP` в
LB, S3 ещё не healthy) → чинить стенд.
3. Причина неясна или правка теста спорная — остановись и спроси.
Тест `tests/` не правится никогда. Дефект вне задачи — в
`KNOWN_ISSUES.md`. Проверки отказов меряют время с запасом 0,3–1 с: на
загруженном хосте возможно ложное падение — перезапусти один раз и
скажи об этом.
## 10. Особенности Codex
- В sandbox нет сети: `uv sync`/`uv lock`/`docker build` упадут. Docker
из sandbox часто недоступен (сокет): почти всё здесь требует docker.
Запроси запуск вне sandbox (правила `.codex/rules/` разрешают команды
проекта без вопроса, если проект доверенный) или попроси пользователя;
приложи команду дословно.
- Долгие команды (`make bench-*` — до часа) — в фоне с журналом:
`nohup make … > /tmp/bench-x.log 2>&1 &`, затем `tail` журнала.
- Сервис на хосте (`make run`) — в фоне с журналом; до запуска проверь
порт (`lsof -nP -iTCP:8081 -sTCP:LISTEN`), в конце убей только PID,
чей `ps -p <PID> -o command=` — `python -m src`.
- Никогда не убивать процесс по порту вслепую: порт опубликованного
контейнера на macOS держит `com.docker.backend`. Чужие процессы и
контейнеры не трогать — взять другой порт (`make env HOST_PORT=…
POSTGRES_HOST_PORT=… VALKEY_HOST_PORT=… S3_HOST_PORT=…` до первого
`make up`).
- Держи этот файл ≤ ~28 КБ (`wc -c`, кириллица — два байта на символ):
Codex читает `AGENTS.md` до 32 КиБ вместе. Новое правило слоя — во
вложенный `AGENTS.md`.
## 11. Отчёт пользователю в конце задачи
По-русски, коротко: что сделано (файлы и суть); какие проверки и с каким
итогом (`24 passed`, `PASS: lab4 ...`, `results: {...}`, метки
`evidence/…`); что не проверено и почему; что записано в
`KNOWN_ISSUES.md`, вопросы к преподавателю.
## 12. Согласования с преподавателем
Договорённости, которых нет в skeleton. Каждую упомянуть в `REPORT.md`.
| Дата | Договорённость | Где учтено |
|---|---|---|
| 2026-10-20 | Лаба 4: «пустой текст» сообщения — и `""`, и строка только из пробельных символов. Допустимы: вложение + непустой текст, без вложения + непустой текст, вложение + пустой текст. `" "` с ≥ 1 вложением — 201, без вложений — 400 | `src/api/schemas.py` (`CreateMessage`), `student-tests/test_attachments.py`, `REPORT.md` |
## 13. Стиль кода
- ruff (`pyproject.toml`): строка 88, py313, isort, bugbear, pyupgrade,
simplify, pytest-style, async. Формат — `make fmt`.
- Аннотации типов везде; дженерики PEP 695. Исключение — скрипты на
`python3` хоста (`student-tests/stand.py`, `fault_hook.py`,
`scripts/lab4.py`): Python 3.9+, stdlib, `from __future__ import
annotations`.
- Методы сервисов и изменяющие методы хранилища — keyword-only.
- Комментарии и докстринги — короткие, по-русски, объясняют «почему».
Сообщения логов и `error.message` — по-английски.
- Константы контракта — `src/constants.py`; время — `src/clock.py`.
- Коммиты (только по просьбе): английский, conventional.
## 14. Документы решения
`REPORT.md` (отчёт, гипотезы U1–U4 и H1–H5, ответы защиты), `evidence/`
(`evidence/AGENTS.md`), `KNOWN_ISSUES.md`, `bench/RUNBOOK.md`. Метки и
отчёт лабы 3 остались в её репозитории.
## 15. Дальше: лаба 5
Новый skeleton — отдельный репозиторий; сначала его `COURSE.md` (брокер,
worker, превью; загрузка — 202). Переносить всё своё (код, тесты,
миграции, `bench/`, `infra/` кроме `README.md`, свои `scripts/*`,
Dockerfile, compose, lock-файлы, `AGENTS.md`, `.codex/`, `.agents/`,
`KNOWN_ISSUES.md`); `Makefile`, `.env.example`, `.gitignore`,
`.dockerignore` — сливать; skeleton, `.env`, volumes, `REPORT.md` и
`evidence/` — не копировать. `name:` compose — `vladimirceva-lab5`.
+62
View File
@@ -0,0 +1,62 @@
# Образ API мессенджера, лаба 4: сервер (реплики за HAProxy), миграции и
# уборщик (`python -m src.cleaner`). Правила — infra/AGENTS.md.
#
# Базовый образ закреплён тегом с патч-версией и digest индекса
# (linux/amd64 + linux/arm64), в обоих stage один и тот же: venv ссылается
# на интерпретатор базового образа. Обновление — новый тег и строка
# Digest из `docker buildx imagetools inspect python:<тег>`.
# deps: зависимости строго по requirements.txt (экспорт uv.lock с хешами).
# У asyncpg, greenlet и argon2-cffi-bindings есть готовые колёса для
# linux amd64/arm64: компилятор в образе не нужен
FROM python:3.13.15-slim-trixie@sha256:7c61056e61ac89e852de05f3dc6fa51a6dd2181797bceed46aa725dd7cb2cd3b AS deps
ENV PIP_NO_CACHE_DIR=1 \
PIP_DISABLE_PIP_VERSION_CHECK=1
RUN python -m venv /opt/venv
COPY requirements.txt /tmp/requirements.txt
# --require-hashes: пакет с другим хешем или без пина — сборка падает;
# --no-deps: ставится ровно список из файла, без догрузки зависимостей;
# --only-binary: сборка из исходников (sdist) запрещена
RUN /opt/venv/bin/pip install --require-hashes --no-deps --only-binary=:all: \
-r /tmp/requirements.txt
# runtime: интерпретатор базового образа, venv и код; без pip-кэша и тестов
FROM python:3.13.15-slim-trixie@sha256:7c61056e61ac89e852de05f3dc6fa51a6dd2181797bceed46aa725dd7cb2cd3b AS runtime
RUN groupadd --system --gid 10001 messenger \
&& useradd --system --uid 10001 --gid messenger --no-create-home \
--home-dir /nonexistent --shell /usr/sbin/nologin messenger
# MALLOC_MMAP_THRESHOLD_: блоки glibc от 128 KiB всегда в mmap, и буфер
# тела загрузки (io.BytesIO до 10 MiB) растёт через mremap без копии. С
# динамическим порогом после первой загрузки glibc поднимает его до ~10
# MiB, буферы растут в куче, и realloc на миг держит два тела
ENV PATH=/opt/venv/bin:$PATH \
PYTHONUNBUFFERED=1 \
PYTHONDONTWRITEBYTECODE=1 \
MALLOC_MMAP_THRESHOLD_=131072 \
APP_HOST=0.0.0.0 \
APP_PORT=8080
WORKDIR /app
# код и venv принадлежат root: пользователю messenger — только чтение.
# Миграции едут в том же образе: сервис migrate запускает его с командой
# `python -m alembic upgrade head`
COPY --from=deps /opt/venv /opt/venv
COPY src ./src
COPY alembic.ini ./
COPY migrations ./migrations
USER messenger:messenger
EXPOSE 8080
HEALTHCHECK --interval=10s --timeout=3s --start-period=10s --start-interval=1s \
--retries=3 CMD ["python", "-m", "src.healthcheck"]
# exec-форма: сервер — PID 1 и сам получает SIGTERM от docker stop
CMD ["python", "-m", "src"]
+46
View File
@@ -0,0 +1,46 @@
# Известные проблемы
Найдены попутно и не исправлены без отдельной просьбы (AGENTS.md,
раздел 2, п. 17). Формат: что, где, симптом, предложение. Исправленное
удаляется отсюда.
## Докстринг пакета называет лабу 3
`src/__init__.py`: «REST API мессенджера MTUSI, лабораторная 3: реплики
за HAProxy», без S3 и вложений. Поведения не меняет. Не исправлено
намеренно: `src_sha256` (хеш `src/` и `migrations/`) подписывает
доказательства `evidence/` и метки замеров лабы 4, правка докстринга его
бы изменила. Предложение: исправить вместе со следующей правкой кода, до
новых замеров.
## Записи лабы 3
Две записи ниже перенесены из лабы 3 вместе с `bench/`: они касаются
серий трека 1 лабы 3 (`make bench-scaling`), которые в лабе 4 сохранены,
но не обязательны. Профилей лабы 4 (`uploads`, `reconcile`) они не
затрагивают.
## Возобновление прерванной серии требует доработки
Статический анализ `bench/run.py:run_scaling` и `scaling_cell`:
ветка `resume` сохраняет прежний `meta.aborted`, а финальная проверка
этого поля возвращает ошибку даже после завершения оставшихся ячеек.
Ступени незавершённой ячейки уже записываются в `runs.csv` и
`samples.csv`; повтор той же ячейки добавляет строки с теми же номерами,
а соответствующие raw JSON перезаписываются. Очистки/разделения
незавершённого повтора в коде нет.
Прерванный прогон специально не запускался. Обычные завершённые серии
не затронуты. Предложение: отдельно реализовать восстановление только
незавершённой ячейки с сохранением её исходных данных и снятием
`aborted` после успешного продолжения.
## Подпись насыщения для A/B с одной конфигурацией
В `bench/plots.py:saturation` единственная точка возвращает `None`,
а `main` трактует это как продолжающийся рост ≥ 10 %. В лабе 3 это было
видно в сводке графиков `scaling-h6` (её репозиторий): для каждой метки
и лимита БД есть только 4 реплики, поэтому проверить рост от числа
реплик нельзя. Сами R*, диапазоны и график сравнения верны.
Предложение: отдельно печатать «недостаточно конфигураций» при числе
точек меньше двух.
+330
View File
@@ -28,3 +28,333 @@ test-persistence:
test-failover:
@test -n "$(ACTION_SCRIPT)" || (echo "Set ACTION_SCRIPT to your implemented executable stop-one hook"; exit 2)
$(PYTHON) tests/resilience.py --mode failover --action-script "$(ACTION_SCRIPT)" --base-url "$(BASE_URL)" $(TLS_ARGS)
# ===========================================================================
# Собственные цели решения. Цели skeleton выше (help, check, validate, test,
# load, test-persistence, test-failover) не менять: в следующей лабе
# Makefile придёт новый, свои цели переносятся в него слиянием.
# ===========================================================================
# .env: подстановки compose и окружение приложения на хосте. Без него —
# значения по умолчанию ниже (пароли и ключи пустые: сначала `make env`)
-include .env
IMAGE ?= mtusi-messenger-vladimirceva:lab4
# порт HAProxy на 127.0.0.1 — единственный порт API стенда на хосте
HOST_PORT ?= 8080
# порт сервиса на хосте (make run): другой, чем у стенда, — оба могут
# работать одновременно
RUN_PORT ?= 8081
POSTGRES_USER ?= messenger
POSTGRES_DB ?= messenger
POSTGRES_HOST_PORT ?= 5433
VALKEY_HOST_PORT ?= 6380
S3_HOST_PORT ?= 8334
SESSION_TTL_SECONDS ?= 3600
# реплик API за HAProxy; разово — `make replicas API_REPLICAS=3`
API_REPLICAS ?= 2
DC = docker compose
UV_EXPORT = uv export --frozen --no-dev --no-emit-project --no-header --format requirements.txt
# долгие замеры на macOS — под caffeinate: ноутбук не уснёт по простою
CAFFEINATE := $(shell command -v caffeinate >/dev/null 2>&1 && echo caffeinate -isu)
# --- приложение на хосте ----------------------------------------------------
.PHONY: install
install:
uv sync
# окружение сервиса и миграций на хосте: хранилища стенда на 127.0.0.1,
# пароли и ключи пользователя API в S3 из .env. .env читается в рецепте, а
# не при разборе Makefile: так первый запуск видит и файл, только что
# созданный `make env`. Рецепт без эха — секреты не печатаются
LOCAL_ENV = set -a; . ./.env; set +a; \
export DB_HOST=127.0.0.1 DB_PORT="$$POSTGRES_HOST_PORT" DB_NAME="$$POSTGRES_DB" \
DB_USER="$$POSTGRES_USER" DB_PASSWORD="$$POSTGRES_PASSWORD" CACHE_HOST=127.0.0.1 \
CACHE_PORT="$$VALKEY_HOST_PORT" CACHE_PASSWORD="$$VALKEY_PASSWORD" \
S3_ENDPOINT="http://127.0.0.1:$$S3_HOST_PORT" S3_ACCESS_KEY_ID="$$S3_API_ACCESS_KEY" \
S3_SECRET_ACCESS_KEY="$$S3_API_SECRET_KEY"
# PostgreSQL, Valkey и S3 из compose, миграции с хоста, затем один процесс
# сервиса на 127.0.0.1:RUN_PORT без LB, текстовые логи в stdout; стоп —
# Ctrl+C. Срок сессии — `make run SESSION_TTL_SECONDS=2`
.PHONY: run
run: migrate-local
@echo "uv run python -m src # 127.0.0.1:$(RUN_PORT), SESSION_TTL_SECONDS=$(SESSION_TTL_SECONDS)"
@$(LOCAL_ENV); APP_PORT=$(RUN_PORT) SESSION_TTL_SECONDS=$(SESSION_TTL_SECONDS) \
uv run python -m src
# миграции с хоста в PostgreSQL стенда (127.0.0.1:POSTGRES_HOST_PORT)
.PHONY: migrate-local
migrate-local: db-up
@echo "uv run alembic upgrade head # 127.0.0.1:$(POSTGRES_HOST_PORT)"
@$(LOCAL_ENV); uv run alembic upgrade head
.PHONY: lint
lint:
uv run ruff format --check .
uv run ruff check .
.PHONY: fmt
fmt:
uv run ruff format .
uv run ruff check --fix .
# собственные тесты против запущенного стенда (BASE_URL, по умолчанию
# HAProxy рабочего стенда); EXPECT_REPLICAS — сколько реплик за BASE_URL
# (против `make run` — 1: тесты реплик пропускаются с причиной).
# Проверки отказов (маркер fault) — make failure-checks
EXPECT_REPLICAS ?= $(API_REPLICAS)
.PHONY: student-test
student-test:
BASE_URL=$(BASE_URL) EXPECT_REPLICAS=$(EXPECT_REPLICAS) uv run pytest
# отдельный стенд из того же compose.yaml (свои PostgreSQL, Valkey, S3,
# volume, HAProxy и две реплики, свои пароли и ключи, без .env): сборка,
# миграции и bootstrap S3, make test и make student-test через его LB,
# test-failover, test-persistence, затем уборка при любом исходе. Рабочий
# стенд не трогается. $(PYTHON), а не uv run: uv повторно шлёт SIGINT, и
# Ctrl+C обрывал бы уборку
.PHONY: test-isolated
test-isolated:
$(PYTHON) student-tests/stand.py isolated
# проверки отказов (pytest -m fault) на таком же отдельном стенде: свои
# хранилища и S3, уборщик с grace 25 с, обычный, «тесный» и «узкий по
# загрузкам» API, hook student-tests/fault_hook.py. FAULT_ARGS — аргументы
# pytest
.PHONY: failure-checks
failure-checks:
$(PYTHON) student-tests/stand.py failures $(FAULT_ARGS)
# requirements.txt для образа — только из uv.lock, с хешами
.PHONY: requirements
requirements:
$(UV_EXPORT) --output-file requirements.txt
.PHONY: requirements-check
requirements-check:
$(UV_EXPORT) | diff -u requirements.txt - && echo "requirements.txt matches uv.lock"
# --- Docker и compose ---------------------------------------------------------
# .env из шаблона со случайными паролями PostgreSQL и Valkey и ключами S3:
# в шаблоне они пустые, общего пароля стенда в git нет. Существующий .env
# не перезаписывается — дописываются только переменные шаблона, которых в
# нём нет (секреты — случайными). Печатаются только имена
.PHONY: env
env:
@$(PYTHON) scripts/lab4.py env
.PHONY: docker-build
docker-build:
docker build -t $(IMAGE) .
# весь стенд: postgres, valkey, s3 -> migrate, s3-bootstrap -> api ×
# API_REPLICAS и cleaner -> haproxy; --wait ждёт healthy реплик и LB
# (миграции и bootstrap к этому моменту завершились с кодом 0). Реплики с
# изменённым образом пересоздаются все разом, с простоем; без простоя —
# make rolling-update
.PHONY: up
up: env
$(DC) up -d --build --wait api cleaner haproxy
# остановить контейнеры (SIGTERM); данные и контейнеры остаются. LB
# останавливается раньше реплик (depends_on); S3 — плавно, ~15 с
.PHONY: stop
stop:
$(DC) stop
# удалить контейнеры; volume pgdata и s3data с данными остаются
# (удаление — wipe)
.PHONY: down
down:
$(DC) down
# журнал всех реплик; префикс строки — имя контейнера реплики
.PHONY: logs
logs:
$(DC) logs -f api
# хранилища стенда с ожиданием healthcheck и bootstrap S3: для make run.
# --wait одноразовый сервис не ждёт — код bootstrap отдельно
.PHONY: db-up
db-up: env
$(DC) up -d --wait postgres valkey s3
$(DC) up --no-deps --exit-code-from s3-bootstrap s3-bootstrap
# удалить контейнеры и volume с данными стенда: только после ввода yes
.PHONY: wipe
wipe:
@read -p "Удалить все данные стенда (volume PostgreSQL pgdata и S3 s3data)? Введите yes: " answer; \
if [ "$$answer" = "yes" ]; then \
$(DC) down -v --remove-orphans; \
else \
echo "cancelled, nothing removed"; exit 1; \
fi
# --- Реплики за HAProxy (лаба 3) --------------------------------------------
# вернуть остановленные реплики (те же контейнеры и X-Instance-Id) и
# выставить их число API_REPLICAS; ждёт healthy
.PHONY: replicas
replicas:
$(DC) up -d --no-deps --no-recreate --wait --scale api=$(API_REPLICAS) api
# вход одним синтетическим пользователем и серия GET /users/me с одним
# токеном через LB: X-Instance-Id каждого ответа и итог по репликам
.PHONY: instances
instances:
$(PYTHON) scripts/lab4.py instances --base-url "$(BASE_URL)"
# слоты HAProxy: адрес, состояние проверки (DRAIN/MAINT при замене),
# запросы, ошибки соединения, повторы, перенаправления
.PHONY: lb-stats
lb-stats:
$(PYTHON) scripts/lab4.py lb-stats
# make test-failover для каждой реплики по очереди с возвратом
# предыдущей (make replicas): какой контейнер остановлен, строка
# STOP_ONE_LOG и итог теста. STOP_MODE=kill — без graceful
STOP_MODE ?= stop
.PHONY: failover-each
failover-each:
$(PYTHON) scripts/lab4.py failover-each --base-url "$(BASE_URL)" \
--replicas $(API_REPLICAS) --mode $(STOP_MODE)
# поочерёдная замена реплик на образ рабочего дерева без простоя:
# сборка, миграции один раз, по одной реплике через drain в LB
.PHONY: rolling-update
rolling-update:
API_REPLICAS=$(API_REPLICAS) scripts/rolling-update.sh
# --- S3 и вложения (лаба 4) ---------------------------------------------------
# вложение через LB → остановка реплики, принявшей загрузку (stop-one.sh по
# её X-Instance-Id) → скачивание через другую, тот же SHA-256 → 404
# постороннему → make replicas. STOP_MODE=kill — без graceful
.PHONY: attachment-failover
attachment-failover:
$(PYTHON) scripts/lab4.py attachment-failover --base-url "$(BASE_URL)" \
--replicas $(API_REPLICAS) --mode $(STOP_MODE)
# приватность bucket вне API: права ключей API и уборщика (bootstrap в
# режиме check), анонимные запросы с хоста и из сети стенда, порты
# контейнера S3; затем уборка проверочных объектов. Код 1 при нарушении
.PHONY: s3-check
s3-check:
$(PYTHON) scripts/lab4.py s3-check
# разовый проход уборщика незавершённых загрузок: 0 — проход дошёл до
# конца, 1 — прерван отказом, 2 — конфигурация
.PHONY: cleanup-once
cleanup-once:
$(DC) run --rm --no-deps cleaner --once
# разовая сверка bucket и БД (трек 2) в контейнере уборщика. По умолчанию
# dry-run; APPLY=1 — исправить безопасное; MAX_CHANGES, STRATEGY=head,
# DEEP=1 (SHA-256 содержимого), RATE (объектов S3/с, 0 — без предела).
# Коды: 0 — расхождений нет, 3 — остались, 1 — прервана, 2 — конфигурация
APPLY ?=
MAX_CHANGES ?=
STRATEGY ?=
DEEP ?=
RATE ?=
.PHONY: reconcile
reconcile:
$(DC) run --rm --no-deps cleaner reconcile $(if $(APPLY),--apply,) \
$(if $(MAX_CHANGES),--max-changes $(MAX_CHANGES),) \
$(if $(STRATEGY),--strategy $(STRATEGY),) $(if $(DEEP),--deep,) \
$(if $(RATE),--rate $(RATE),)
# --- Нагрузочный стенд (уровень «4» — отказ и замена под нагрузкой лабы 3,
# память одновременных загрузок; уровень «5» — трек 2, стоимость сверки) --
# Порядок работы — bench/RUNBOOK.md, правила — bench/AGENTS.md. Свой проект
# compose vlad-bench, рабочий стенд перед замером — make stop.
FAILOVER_LABEL ?= baseline
ROLLOUT_LABEL ?= baseline
UPLOADS_LABEL ?= baseline
RECONCILE_LABEL ?= baseline
# серия трека 1 лабы 3 (сохраняется): a, b, db, ab, quick
SERIES ?=
SCALING_LABEL ?=
LABELS ?=
PLOTS ?= scaling
BENCH = $(CAFFEINATE) uv run python bench/run.py
# уровень 4 лабы 3: две реплики под постоянной нагрузкой, каждая в режимах
# stop, kill, pause с возвратом; пишет evidence/failover/<метка>/
.PHONY: bench-failover
bench-failover:
$(BENCH) failover --label "$(FAILOVER_LABEL)"
# проверка стенда отказа (~2 мин); метка quick-failover-<UTC> в отчёт не идёт
.PHONY: bench-failover-quick
bench-failover-quick:
$(BENCH) failover-quick
# уровень 4 лабы 3: поочерёдная замена (scripts/rolling-update.sh) под той
# же нагрузкой, с новой expand-ревизией; пишет evidence/rollout/<метка>/
.PHONY: bench-rollout
bench-rollout:
$(BENCH) rollout --label "$(ROLLOUT_LABEL)"
.PHONY: bench-rollout-quick
bench-rollout-quick:
$(BENCH) rollout-quick
# уровень 4 лабы 4: память реплики при 1/10/20/40 одновременных загрузках
# по ~1 и ~10 MiB, варианты «с лимитом» (места по умолчанию) и «без
# лимита»; пишет evidence/uploads/<метка>/
.PHONY: bench-uploads
bench-uploads:
$(BENCH) uploads --label "$(UPLOADS_LABEL)"
# самопроверка профиля загрузок (~5 мин); метка quick-uploads-<UTC>
.PHONY: bench-uploads-quick
bench-uploads-quick:
$(BENCH) uploads-quick
# уровень 5, трек 2: стоимость сверки bucket и БД по размеру набора,
# стратегиям и под фоновой нагрузкой; пишет evidence/reconcile/<метка>/
.PHONY: bench-reconcile
bench-reconcile:
$(BENCH) reconcile --label "$(RECONCILE_LABEL)"
# самопроверка профиля сверки (~6 мин); метка quick-reconcile-<UTC>
.PHONY: bench-reconcile-quick
bench-reconcile-quick:
$(BENCH) reconcile-quick
# трек 1 лабы 3 (сохраняется для сравнения, в лабе 4 не обязателен):
# серия конфигураций, на каждую ячейку свежий стенд, открытая модель,
# поиск R*; пишет evidence/scaling/<метка>/. CONFIGS="4x1-pg0.5 4x1" —
# ячейки вместо профильных; RESUME=1 — продолжить прерванную метку
CONFIGS ?=
.PHONY: bench-scaling
bench-scaling:
@test -n "$(SERIES)" || (echo "usage: make bench-scaling SERIES=a|b|db|ab [SCALING_LABEL=...] [CONFIGS=...] [RESUME=1]"; exit 2)
$(BENCH) scaling --series "$(SERIES)" $(if $(SCALING_LABEL),--label "$(SCALING_LABEL)",) \
$(if $(CONFIGS),--configs "$(CONFIGS)",) $(if $(RESUME),--resume,)
# самопроверка серий (~5 мин): 1 × 1 и 2 × 1, короткие окна
.PHONY: bench-scaling-quick
bench-scaling-quick:
$(BENCH) scaling --series quick
# сравнение двух меток серий (по общим конфигурациям); AA — метка того же
# кода, что BEFORE: уровень шума
.PHONY: bench-compare
bench-compare:
@test -n "$(BEFORE)" -a -n "$(AFTER)" || \
(echo "usage: make bench-compare BEFORE=<label> AFTER=<label> [AA=<label>]"; exit 2)
uv run python bench/compare.py --before "$(BEFORE)" --after "$(AFTER)" \
$(if $(AA),--aa "$(AA)",)
# графики SVG и сводка серий трека 1: evidence/plots/<PLOTS>/
.PHONY: bench-plots
bench-plots:
@test -n "$(LABELS)" || (echo "usage: make bench-plots LABELS=\"scaling-a scaling-b\" [PLOTS=scaling]"; exit 2)
uv run python bench/plots.py --out "$(PLOTS)" $(LABELS)
+569 -23
View File
@@ -1,37 +1,583 @@
# Отчёт — лабораторная 4
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
- Автор, группа: Владимирцева, БВТ2301
- Целевая оценка 5; выбранный трек 5: 2 «Согласованность двух хранилищ»
- MR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: раздел 8 в конце
отчёта
## Запуск из чистого clone
**Работа выполнена в объёме требований на оценку «5», трек 2.** Метаданные
вложений — в PostgreSQL, байты — в приватном bucket SeaweedFS; загрузка
отвечает `201 ready` только после записи объекта и фиксации строки;
скачивание идёт через API и только участникам чата, в том числе после
остановки принявшей реплики. Прерванная загрузка и отказ между S3 и БД не
оставляют вечных объектов: компенсация в загрузке, уборщик с grace 900 с
и сверка bucket и БД с обеих сторон (dry-run, `--apply`, повтор, предел
изменений, свежие и используемые вложения не трогаются). Память загрузок
ограничена местами процесса, а не числом клиентов.
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
Все проверки без нагрузки сняты на машине разработки 23 октября 2026
(раздел 3). Замеры под нагрузкой — профили `uploads` (уровень 4: пик
памяти при ≥ 10 одновременных загрузках) и `reconcile` (трек 2: стоимость
обхода) — сняты на машине замеров по `bench/RUNBOOK.md`: TODO (Codex) —
одна строка с главными числами обеих меток. Гипотезы U1–U4 и H1–H5
записаны в разделе 4 **до** замеров; итоги — отдельными абзацами под
ними.
## Архитектура и решения
## 1. Запуск и демонстрация
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab3, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
Нужны Docker Compose (Docker Desktop), make и uv. API — Python 3.13.15;
PostgreSQL 18.6, Valkey 9.1.2, HAProxy 3.4.6, SeaweedFS 4.48. Образы
закреплены тегом и digest индекса в [Dockerfile](Dockerfile) и
[compose.yaml](compose.yaml), зависимости — [uv.lock](uv.lock) и
`requirements.txt` с хешами (aiobotocore 3.10.0, botocore 1.43.117,
aiohttp 3.14.5 добавлены в лабе 4).
## Доказательства критериев
`.env.example` дополнен переменными Compose лабы 4: порт API S3 на хосте
и семь пустых секретов S3 (административная пара сервера, ключ подписи
gRPC шлюза, пары пользователей API и уборщика). `make env` заполняет все
пароли и ключи случайными значениями; существующий `.env` дополняется
недостающими строками, прежние не меняются. Порты хоста меняются
аргументами (`make env HOST_PORT=8180 S3_HOST_PORT=8434 …`).
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
```sh
make install # uv sync
make env # .env со случайными паролями и ключами S3 (в git нет)
make up # postgres, valkey, s3 → migrate, s3-bootstrap → api × 2, cleaner → haproxy
make test # публичный smoke через LB (вложение, SHA-256, 404 постороннему)
make s3-check # приватность bucket вне API
make attachment-failover # вложение → стоп принявшей реплики → скачивание через другую
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
make replicas # вернуть остановленную реплику
make reconcile # сверка bucket и БД, dry-run (APPLY=1 — исправить)
make test-isolated # всё выше на отдельном чистом стенде (~2 мин)
make failure-checks # проверки отказов (~4 мин)
```
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
`make up` ждёт готовности хранилищ, успешного bootstrap S3 и миграций,
готовности реплик и HAProxy. Единственная точка входа API — HAProxy на
`127.0.0.1:${HOST_PORT}` (8080). Bootstrap S3 и миграции — одноразовые
сервисы: реплики и уборщик их ждут, повтор — no-op.
## Эксперименты и отказы
**Сценарий защиты** (`README.md`):
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
1. `make test` — загрузка фикстуры, сообщение с `attachment_ids`,
скачивание вторым участником и сверка SHA-256
([вывод](evidence/attachments/smoke.txt)).
2. Третий пользователь — 404 на метаданные и байты
([attachment-failover](evidence/attachments/failover.txt)); прямой
анонимный GET в S3 — 403 с хоста и из сети стенда
([s3-check](evidence/s3/privacy.txt)).
3. `make test-persistence ACTION_SCRIPT=scripts/restart.sh` — данные,
токен и оригинал после рестарта LB, реплик, PostgreSQL, Valkey и S3
([вывод](evidence/stand/persistence.txt)); `make attachment-failover
[STOP_MODE=kill]` — оригинал отдаёт другая реплика.
4. На API нет локального файла оригинала: `docker diff` реплик пуст,
файловая система только для чтения ([стенд](evidence/stand/stand.txt)).
Для 4/5 — проверки отказов и замеры (разделы 3–4).
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
Остановка: `make stop` (контейнеры остаются; S3 останавливается плавно
~15 с), `make down` (контейнеры удаляются, volume `pgdata` и `s3data`
остаются). Удаление учебных данных — `make wipe`, только после ввода
`yes`.
## Ограничения и следующие шаги
## 2. Архитектура и решения
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
```text
клиент → 127.0.0.1:HOST_PORT → HAProxy ─┬→ api-1 ─┬→ PostgreSQL (данные, сессии, ключи, метаданные вложений)
└→ api-2 ─┼→ Valkey (кэш карточек чатов)
└→ S3 SeaweedFS (байты вложений, приватный bucket)
migrate, s3-bootstrap (один раз на up и на замену, до реплик)
cleaner (уборка незавершённых загрузок, сверка) → PostgreSQL, S3
```
**Перенесено из лабы 3** без изменений поведения: REST API, слои HTTP →
сервисы → хранилище (SQLAlchemy Core + asyncpg), PostgreSQL как источник
истины, Basic → Bearer-сессии, кэш карточек в Valkey с обходом при
отказе, ≥ 2 взаимозаменяемые реплики за HAProxy, `X-Instance-Id`,
обязательный `Idempotency-Key`, цепочка таймаутов, поочерёдная замена,
ранний обработчик SIGTERM.
**Изменено в лабе 4:**
| Что | Как |
|---|---|
| S3 | SeaweedFS 4.48 одним процессом `weed server`, служебные серверы на loopback контейнера, volume `s3data`; приватный bucket и пользователи создаёт одноразовый `s3-bootstrap` |
| Вложения | `POST /chats/{id}/attachments`, `GET /attachments/{id}`, `GET /attachments/{id}/content`; таблицы `attachments`, `message_attachments` (ревизия `0003`, expand) |
| Сообщения | `attachment_ids` (до 10, `ready`, из того же чата), пустой текст — только с вложением; хэш тела ключа включает `attachment_ids`, только если список не пуст |
| Согласованность | строка `pending` до PUT, `ready` после; компенсация при известном сбое; уборщик `cleaner` (отдельный процесс) с grace 900 с |
| Память | места загрузок на процесс (4 + очередь 16, ожидание 5 с → 429), срок тела 30 с, одна копия тела, `MALLOC_MMAP_THRESHOLD_`, буферы сокетов реплики и LB |
| Трек 2 | сверка bucket и БД в процессе уборщика: разовая (`make reconcile`) и плановая раз в час |
| LB | путь загрузки — `timeout server` 40 с, буферы `tune.sndbuf.server` / `tune.rcvbuf.client`, дренаж замены 90 с |
### S3: выбор и приватность
**Почему SeaweedFS.** Из трёх серверов skeleton он запускается одним
процессом и одним образом с закреплённым digest для amd64 и arm64, а
пользователей и политики настраивает `weed shell` того же образа
(bootstrap без отдельного клиента и без консоли). MinIO и RustFS в этой
работе не сравнивались.
Приватность с первой секунды: административная пара задаётся серверу
окружением — учётная запись есть до первого запроса, анонимного окна
нет. Master, volume и filer слушают только `127.0.0.1` контейнера; в сеть
выходят API S3 (8333) и gRPC шлюза (18333, закрыт ключом подписи
`WEED_JWT_FILER_SIGNING_KEY`, без него gRPC принял бы учётную запись
администратора от любого контейнера сети). На хост публикуется только API
S3 и только на loopback. Консоли нет.
`s3-bootstrap` (одноразовый, `network_mode: service:s3`) создаёт bucket,
ставит анонимному доступу `none`, создаёт пользователей и политики:
**API** — чтение, запись и удаление объектов своего bucket; **уборщик** —
чтение, удаление и список только с префиксом `<база>/attachments/`.
Затем сам проверяет приватность обоими ключами и без ключа. Повтор
сводит состояние к `.env` ([bootstrap](evidence/s3/bootstrap.txt)).
Административная пара — только у сервера, ключи каждого пользователя —
только у своего процесса ([стенд](evidence/stand/stand.txt)).
### Вложения: модель и путь загрузки
Ключ объекта назначает сервер: `<имя базы>/attachments/<id>/original`
(`id` — UUID v4 сервера); `filename` хранится только для показа
(1–255 code points, без `/`, `\` и управляющих символов). Байтов в БД
нет: строка хранит размер, SHA-256, тип, статус, ключ, `lost_at`.
Загрузка (`AttachmentService.upload`), до чтения тела и без места:
401 (middleware) → 400 (`chat_id`, `filename`, строгий UTF-8) → 404
(не участник) → 415 (`Content-Type` не PNG/JPEG) → 413 (`Content-Length`
больше 10 MiB). Затем место загрузки (иначе очередь до 5 с и 429 с
`Retry-After`), тело потоком в один `BytesIO` со счётчиком (больше
10 MiB — 413 сразу) и сроком 30 с (400); структурная проверка PNG/JPEG
без декодирования пикселей: чанки и CRC PNG, маркеры JPEG до SOS и EOI,
размеры из заголовка до любой распаковки (больше 40 млн пикселей —
413, повреждено, не тот формат, MIME не совпал с содержимым — 415).
Потом строка `pending` → PUT → `ready` → 201.
**Когда 201 честен:** только после того, как S3 подтвердил PUT и строка
`ready` зафиксирована — тогда оригинал есть и его метаданные видит любая
реплика. Скачивание — потоком через API (блоки 64 KiB из S3),
`Content-Type` оригинала, `nosniff`; адрес и ключи S3 клиенту не
отдаются, redirect нет. Чужое, неизвестное, незавершённое и потерянное —
404 одинаково.
### Согласованность БД и S3 (уровень 4)
Порядок записи — **строка раньше объекта**: у любого объекта есть строка,
по которой его найдёт уборщик.
| Сбой | Что происходит | Остаток |
|---|---|---|
| до строки (тело, проверка, место) | ответ 4xx/429/503, в S3 ничего нет | нет |
| PUT не прошёл (S3 недоступен, срок 5 с) | 503 | строка `pending` (и, возможно, поздний объект) — уборщик через grace |
| сбой `ready` до отправки COMMIT | компенсация: объект удаляется до ответа, 503 | строка `pending` — уборщик |
| сбой на самом COMMIT | исход неизвестен (`OutcomeUnknown`): объект не трогается, 503 | `ready` (тогда всё цело) или `pending` — уборщик |
| процесс убит между PUT и `ready` | ответа нет | строка `pending` с объектом — уборщик |
**Уборщик** — отдельный сервис `cleaner` (`python -m src.cleaner`), а не
задача реплик: N реплик были бы N уборщиками, а остановка реплики
обрывала бы проход. Раз в 60 с он берёт строки `pending` старше
`CLEANER_GRACE` (900 с) по частичному индексу и убирает каждую в два шага
под `FOR UPDATE SKIP LOCKED`: пометка (`updated_at`, commit), затем
удаление объекта и строки в одной транзакции (объект раньше строки:
упал S3 — строка остаётся, повтор безопасен). Помеченную строку загрузка
в `ready` уже не переведёт (`UPDATE … WHERE updated_at = created_at`), а
ответит 503 и удалит объект. **Grace безопасен:** живая загрузка держит
строку `pending` не дольше `2 × (DB_OPERATION_TIMEOUT 6 + закрытие 2) +
S3_TIMEOUT 5` = 21 с; уборщик с grace не больше этой границы не
стартует (код 2). `ready` уборщик не трогает никогда.
### Память и сроки загрузки
- **Места загрузок процесса** (`UPLOAD_MAX_CONCURRENT` 4): тело читается
только на месте. Без места — очередь (`UPLOAD_MAX_WAITING` 16) не
дольше `UPLOAD_WAIT_TIMEOUT` 5 с, затем 429 `rate_limited` с
`Retry-After: 1`; тело ожидающего не читается и копится только в буфере
сокета.
- **Одна копия тела**: `BytesIO` → `getvalue()` (bytes над тем же
буфером) для проверки и SHA-256 → ссылка удаляется → PUT отправляет тот
же буфер. `MALLOC_MMAP_THRESHOLD_=131072`: буфер больше 128 KiB — свой
mmap, после ответа возвращается ядру.
- **Буферы**: приём сокетов реплики до 512 KiB (`net.ipv4.tcp_rmem`), LB
— `tune.sndbuf.server` 256 KiB к реплике, `tune.rcvbuf.client` 128 KiB
от клиента: ожидающая загрузка не держит мегабайты в ядре.
- **Сроки**: тело — 30 с с момента места (иначе 400, место освобождается);
`timeout server` LB пути загрузки — 40 с (ожидание 5 + тело 30 +
запись); вызов S3 — 5 с целиком и на каждый блок (`asyncio.timeout`;
`read_timeout` aiohttp выключен: он переживал ответ и портил
соединение в пуле); повторов S3 нет.
Ожидаемая граница памяти реплики «с лимитом»: 4 тела по 10 MiB + базовая
память процесса (~100 MiB) + буферы ожидающих (≤ 16 × 0,5 MiB) — далеко
ниже лимита 512 MiB. Проверка — профиль `uploads` (раздел 4.2).
### Сверка bucket и БД (трек 2)
Уборщик видит только строки `pending`. Объект без строки (PUT пережил
свою строку, объект мимо API) и строку `ready` без объекта (удалён мимо
API) находит **сверка** — в том же процессе: разовая (`make reconcile`,
по умолчанию dry-run) и плановая (при старте и раз в
`RECONCILE_INTERVAL` 3600 с, `batch`, с исправлением).
| Класс | Что найдено | Действие с `--apply` |
|---|---|---|
| `orphan_object` | объект старше grace, строки нет, ссылок нет | объект удаляется |
| `stale_pending` | строка `pending` старше grace | шаг уборщика (пометка, объект и строка) |
| `missing_object` | строка `ready`, объекта нет, bucket на месте | оригинал помечается потерянным (`lost_at`): скачивание 404, метаданные 200 |
| `size_mismatch` | размер объекта ≠ строке | помечается, объект не трогается |
| `checksum_mismatch` | только `--deep`: SHA-256 содержимого другой | помечается |
| `restored_object` | помеченный оригинал снова на месте с тем же SHA-256 | пометка снимается |
| `foreign_object` | ключ, которого API не пишет; строка с ключом вне префикса | только отчёт, код 3 |
**Безопасность.** Удаляется только объект без строки и зависшая
загрузка; строки `ready`, объект, на который ссылается строка, свежее
(моложе grace по `LastModified` объекта и `created_at` строки) и чужой
ключ — никогда. Перед каждым действием — перепроверка в БД и HEAD;
«объекта нет» — только после проверки, что bucket на месте (иначе
удалённый bucket пометил бы все оригиналы). Больше `RECONCILE_MAX_CHANGES`
(100) изменений — ни одного и код 3: массовое «расхождение» скорее значит
подменённую базу или bucket. Сигнал остановки — перед каждым вызовом
хранилища. Коды разового прохода: 0 — расхождений нет, 3 — остались, 1 —
прервана, 2 — конфигурация.
**Стоимость обхода** — в итоговой строке каждого прохода (`reconcile pass
finished …`): вызовы S3 по операциям, ключи списка, прочитанные байты,
запросы к PostgreSQL, длительность шагов, CPU прохода, пик RSS процесса.
Стратегии: `batch` — страница списка (1000 ключей) и одна выборка строк
на страницу, ключи в памяти; `head` — выборка на объект и HEAD на строку,
без множества ключей; `--deep` — GET и SHA-256 каждого согласованного
оригинала. Предел скорости `RECONCILE_RATE` (2000 объектов S3/с) —
пауза после каждого вызова S3. Замер стоимости — профиль `reconcile`
(раздел 4.3).
### Лимиты, пулы, порты и сроки
| Сервис | CPU | Память | Порт на хосте | Секреты |
|---|---|---|---|---|
| api × 2 | 1 | 512 МиБ | нет | пароли PostgreSQL и Valkey, ключи пользователя API S3 |
| cleaner | 0,25 | 256 МиБ | нет | пароль PostgreSQL, ключи пользователя уборщика S3 |
| haproxy | 1 | 256 МиБ | `127.0.0.1:HOST_PORT` | нет |
| postgres | 2 | 1 ГиБ | `127.0.0.1:POSTGRES_HOST_PORT` (для `make run`) | свой |
| valkey | 0,5 | 128 МиБ | `127.0.0.1:VALKEY_HOST_PORT` (для `make run`) | свой |
| s3 | 1 | 512 МиБ | `127.0.0.1:S3_HOST_PORT`, только API S3 | административная пара, ключ подписи |
| s3-bootstrap | 0,5 | 128 МиБ | нет | ключ подписи, ключи обоих пользователей |
| migrate | 0,5 | 256 МиБ | нет | пароль PostgreSQL |
Соединения PostgreSQL: 2 × 15 + migrate + cleaner = 32 ≤ 100, на пике
замены 47. Сроки, которые меняются только вместе: обнаружение отказа
реплики ≤ 6,5 с (как в лабе 3); `timeout server` 10 с, пути загрузки —
40 с; `S3_TIMEOUT` 5 с; граница живой загрузки 21 с < `CLEANER_GRACE`
900 с; `ROLLOUT_DRAIN_TIMEOUT` 90 с — дренаж замены дольше самой долгой
загрузки.
### Миграции и совместимость
`0003` — только расширение: две новые таблицы, частичный индекс `pending`,
`lost_at`; `ck_messages_text_length` ослаблен до `char_length(text) <=
4000` (пустой текст — только с вложением, это правило API) и добавлен
`NOT VALID` — старые строки удовлетворяют прежнему, более строгому
условию, полный обход `messages` под блокировкой не нужен. Ревизия
начинается с `SET LOCAL lock_timeout = '2s'`. Реплики лабы 3 работают на
схеме `0003`: новых обязательных колонок в их таблицах нет
([migrations](evidence/stand/migrations.txt)).
### Конфигурация: логические имена `.env.example`
| Имя skeleton | Реализация |
|---|---|
| `APP_HOST`, `APP_PORT` | те же имена; в образе `0.0.0.0:8080`; на хосте — `HOST_PORT` у HAProxy |
| `APP_ENV` | не используется: режим один |
| `SESSION_TTL_SECONDS`, `IDEMPOTENCY_TTL_SECONDS`, `API_REPLICAS` | те же имена |
| `DATABASE_URL_FILE`, `CACHE_URL_FILE` | не используются: `DB_*` и `CACHE_*`, пароли из `.env` через `environment` compose |
| `SESSION_STORE` | `postgres` |
| `S3_ENDPOINT`, `S3_REGION`, `S3_BUCKET` | те же имена; контейнерам compose задаёт `http://s3:8333`, `make run` — `127.0.0.1:S3_HOST_PORT` |
| `S3_ACCESS_KEY_ID_FILE`, `S3_SECRET_ACCESS_KEY_FILE` | не используются: `S3_ACCESS_KEY_ID` / `S3_SECRET_ACCESS_KEY` каждому процессу — ключи **своего** пользователя (`S3_API_*` у реплик, `S3_CLEANER_*` у уборщика из `.env`) |
| `MAX_UPLOAD_BYTES`, `MAX_IMAGE_PIXELS` | не используются: лимиты контракта (10 MiB, 40 млн пикселей) — константы `src/constants.py`, окружение их не меняет (проверяет стенд отказов) |
Новые настройки: `S3_TIMEOUT`, `S3_CONNECT_TIMEOUT`, `S3_MAX_CONNECTIONS`,
`UPLOAD_*`, `CLEANER_*`, `RECONCILE_*`. Полная таблица —
[src/AGENTS.md](src/AGENTS.md).
### Согласования с преподавателем
| Дата | Договорённость | Где учтено |
|---|---|---|
| 2026-10-20 | «Пустой текст» сообщения — и `""`, и строка только из пробельных символов. `" "` с ≥ 1 вложением — 201, без вложений — 400 | `CreateMessage` (`src/api/schemas.py`), тесты `test_attachments.py` |
## 3. Доказательства критериев
Код всех файлов ниже — `src_sha256`
`bc10d566e2f63173541445a2f6273b967447e13e5dd7f1fb76900934e5692cbe`
(проект не под git), машина разработки: Apple M3 Pro, macOS 26.6.2,
Docker 29.9.2.
| Критерий | Результат | Доказательство |
|---|---|---|
| Возможности лабы 3 сохранены | smoke, свои тесты лаб 1–3, test-failover, test-persistence на отдельном стенде с двумя репликами | [test-isolated](evidence/tests/test-isolated.txt) |
| S3 в общем стенде; метаданные в PostgreSQL, байты в приватном bucket, не в БД и не на диске API | 35 оригиналов (14 MB) в S3, таблица метаданных 96 kB; `docker diff` реплик пуст | [стенд](evidence/stand/stand.txt), [migrations](evidence/stand/migrations.txt) |
| Публичный smoke: 201 ready, оригинал побайтно, checksum, 404 постороннему | `PASS: lab4 public API scenario` | [smoke](evidence/attachments/smoke.txt) |
| Реальные PNG/JPEG ≤ 10 MiB и ≤ 40 млн пикселей; MIME по содержимому; опасный filename; лимит до чтения/декодирования | ровно 10 MiB — 201; 10 MiB + 1 (заявлено и потоком) — 413; бомба PNG, огромные размеры — 413 без декодирования; text, webp, обрезка, порча CRC, MIME не совпал — 415; `/`, `\`, NUL, Cc, не-UTF-8 — 400 | [тесты через LB](evidence/tests/student-test-lb.txt) (`test_attachments.py`) |
| Upload → остановка обслужившей реплики → download через другую | `stop` и `kill`: 200 от другой реплики через 0,53 с, тот же SHA-256, посторонний — 404 | [attachment-failover](evidence/attachments/failover.txt) |
| Restart с volumes сохраняет метаданные и оригинал | `make test-persistence`: PASS, рестарт LB, реплик, PostgreSQL, Valkey, S3 | [persistence](evidence/stand/persistence.txt) |
| Тесты: большой файл, повреждённое изображение, подмена MIME, чужое `attachment_id`, вложение другого чата; 4xx не превращаются в 500 | 130 passed через LB, 46 из них — вложения | [тесты через LB](evidence/tests/student-test-lb.txt) |
| Прерывание и отказ между S3 и БД не оставляют вечных объектов | сбой `ready` — объект удалён сразу, строка — уборщиком через 25,8 с (grace 25 с стенда); API убит между PUT и `ready` — уборщик убрал строку и объект; 24 passed | [failure-checks](evidence/tests/failure-checks.txt) |
| Лимиты и сроки не дают одной загрузке занять неограниченную RAM | полная очередь — 429 за 0,005 с с `Retry-After: 1`; медленное тело — 400 по сроку, место освобождено | [failure-checks](evidence/tests/failure-checks.txt) |
| Недоступность S3 | остановлен — 503 за 0,04 с; заморожен — 503 за 5,01 с; текст и готовность работают | [failure-checks](evidence/tests/failure-checks.txt) |
| Эксперимент ≥ 10 одновременных загрузок с пиком памяти | TODO (Codex): пики «с лимитом» и «без лимита» при C = 10/20/40 | TODO (Codex): `evidence/uploads/baseline/summary.md` |
| Bootstrap идемпотентен; отдельные ключи с ограниченными правами | первый запуск — created, повторы — exists, код 0 | [bootstrap](evidence/s3/bootstrap.txt), [стенд](evidence/stand/stand.txt) |
| Консоль не в общей сети; проверка private bucket вне API | 63 проверки, 0 нарушений; из сети открыты только 8333 и 18333 | [s3-check](evidence/s3/privacy.txt) |
| Трек 2: обнаружение и безопасное исправление с обеих сторон, dry-run и повтор | 5 классов внесены и найдены dry-run без изменений; `--apply` исправил безопасное, чужой объект оставил (код 3); повтор — только он; вернувшийся оригинал снял пометку (код 0); на согласованном рабочем стенде все виды прохода — 0 находок | [failure-checks](evidence/tests/failure-checks.txt), [рабочий стенд](evidence/reconcile/working-stand.txt) |
| Трек 2: свежие и используемые вложения не удаляются | `--apply` трижды во время 2 023 загрузок и отправок 4 клиентов — ни одно 201 не удалено и не помечено; строка без объекта, на которую ссылается сообщение, только помечена; глубокая не читает вложения моложе grace | [failure-checks](evidence/tests/failure-checks.txt), [рабочий стенд](evidence/reconcile/working-stand.txt) |
| Трек 2: стоимость обхода | TODO (Codex): мс и запросы на 1 000 объектов по стратегиям, p95 фона | TODO (Codex): `evidence/reconcile/baseline/summary.md` |
## 4. Эксперименты и отказы
### 4.1. Проверки отказов без нагрузки
`make failure-checks FAULT_ARGS=-rP` — 24 passed за 3 мин 38 с на
отдельном стенде (S3 с bootstrap, три процесса API: обычный, «тесный» и
«узкий по загрузкам» — 1 место, очередь 1, ожидание 1 с, срок тела 2 с;
уборщик с grace 25 с и проходом раз в секунду). Машина разработки,
23 октября 2026 ([вывод](evidence/tests/failure-checks.txt)).
| Воздействие | Что ожидали | Что наблюдали | Восстановление / потеря данных |
|---|---|---|---|
| S3 остановлен, загрузка | 503 быстро, без деталей S3; текст и готовность работают | 503 за 0,040 с; текст 201, `/health/ready` 200 | строка `pending` остаётся уборщику; тот же файл после возврата — 201 |
| S3 заморожен, загрузка и скачивание | 503 не дольше срока вызова S3 (5 с) | 503 за 5,01 с и 5,01 с; метаданные и ссылка в сообщении работают | после разморозки — тот же оригинал |
| Объект записан, сбой перевода в `ready` (триггер в БД) | 503, компенсация удаляет объект, строку убирает уборщик | 503; объектов столько же, сколько до загрузки; строка убрана через 25,8 с | объектов без строки нет |
| Процесс API убит между PUT и `ready` | 201 нет; строку и объект убирает уборщик после grace | клиент — обрыв соединения; строка и объект убраны через 19,3 с после проверки | объектов без строки нет |
| Место занято и очередь полна | 429 сразу с `Retry-After`; ожидавший — 429 по сроку ожидания | 429 за 0,005 с, `Retry-After: 1`; ожидавший — 429; занявший место — 201 | у отказов нет ни строки, ни объекта |
| Тело не приходит дольше срока | 400, место освобождается | 400 за 3,01 с (срок тела 2 с + отправка половины) | следующая загрузка — 201 |
| Расхождения с обеих сторон (5 классов) | dry-run находит и ничего не меняет; `--apply` — безопасное; чужое — только отчёт | dry-run — все 5, объектов и строк столько же; `--apply` — код 3 (чужой объект); повтор — только чужой; возврат оригинала — пометка снята, код 0 | потерянный оригинал: метаданные 200, байты 404, сообщение со ссылкой живо |
| `--apply` во время загрузок 4 клиентов | ни одно подтверждённое вложение не тронуто | 3 прохода с кодом 0 за 15 с, 2 023 загрузки и отправки без ошибок | каждое 201 скачивается с тем же SHA-256 |
| PostgreSQL остановлен / заморожен, пул из 1 (лаба 2–3) | 503 быстро / за срок операции | 503 за 0,008 с; заморожен — 4,01 с, второй запрос 1,01 с (ожидание пула) | — |
| Valkey остановлен / заморожен (лаба 2) | ответы из PostgreSQL, одна задержка ≤ 0,2 с | 200 за 0,012 с; заморозка — +0,205 с у первого чтения | кэш возвращается без рестарта API |
Остальные 11 проверок печатей времени не дают, только утверждения:
срок сессии и отсутствие продления, токен при остановленной БД — 503,
откаты составных операций (чат, ключ идемпотентности), 503 не
сохраняется результатом ключа, срок ключа, готовность без Valkey и без
S3, восстановление кэша после `FLUSHALL` и возврата Valkey.
### 4.2. Память при одновременных загрузках (уровень 4)
**Методика** (`make bench-uploads`, профиль `uploads`, `bench/AGENTS.md`):
свой проект compose `vlad-bench` — LB, **одна** реплика API 1 CPU /
512 МиБ без swap (OOM-kill виден, а не прячется в swap), PostgreSQL,
Valkey и S3 с лимитами рабочего стенда; генератор на stdlib внутри сети
стенда (2 CPU / 1 ГиБ), только через LB. Тела — настоящие PNG из шума
(`loadgen.py body`, зерно 20261023): ~1 MiB и 10 485 256 байт (≤ лимита
контракта). Варианты: «с лимитом» — значения по умолчанию (4 места,
очередь 16, ожидание 5 с); «без лимита» — `UPLOAD_MAX_CONCURRENT=1000`,
`UPLOAD_MAX_WAITING=0` (override только этого варианта). Прогон —
вариант × тело × C ∈ {1, 10, 20, 40} × 3 повтора, порядок — круги с
перестановкой по зерну; на каждый прогон — новый S3 на пустом volume и
новая реплика, разогревающая загрузка, затем **сброс `memory.peak`**
cgroup реплики, S3 и LB своим дескриптором (ядро ≥ 6.12) и закрытая
модель: C клиентов шлют загрузку за загрузкой 3 с разгона + 20 с окна (на
429 — пауза `Retry-After`, на прочие ошибки — 1 с). Пик окна — `memory.peak`
через тот же дескриптор; раз в 0,2 с — `memory.current`, `anon`, `sock`,
`oom_kill`. Загрузок/с и перцентили — по загрузкам, начатым в окне.
**Гипотезы (записаны до замеров).** Пороги — константы `U*` в
`bench/uploads.py`, вердикт считает `summary.md`.
- **U1 — память «с лимитом» ограничена местами, а не клиентами.** При
теле 10 MiB и C = 10, 20, 40 пик окна реплики ≤ половины лимита
(256 MiB), рост пика сверх C = 10 — не больше 1 MiB на клиента, OOM и
5xx нет ни в одном прогоне «с лимитом». Основание: на местах не больше
4 тел (≈ 40 MiB) поверх ~100 MiB процесса, ожидающие держат только
буфер сокета (≤ 512 KiB), остальные получают 429.
- **U2 — без лимита память растёт с клиентами.** При C = 10 рост пика —
не меньше 0,8 тела на клиента; при C = 40 × 10 MiB — OOM-kill или пик
≥ 90 % лимита. Основание: каждая одновременная загрузка держит своё тело.
- **U3 — лимит не стоит пропускной способности.** Загрузок 201 в секунду
при C ≥ 10 у «с лимитом» — не меньше 90 % «без лимита» на тех же C и
теле, пока у того нет OOM. Основание: предел задают CPU одного процесса
и S3 (1 CPU, запись шлюза до 64 МБ одновременно), а не число
параллельных тел.
- **U4 — граница очереди.** У «с лимитом» при C ≤ 20 (4 места + 16 в
очереди) 429 нет, при C = 40 — есть в каждом прогоне. Основание:
ожидание места при 16 в очереди — около 4 оборотов по ~0,3–0,5 с, меньше
5 с срока ожидания.
**Результаты.** TODO (Codex): таблица ячеек из
`evidence/uploads/baseline/summary.md` как есть (вариант, тело, C, пик
старта, до окна, пик, `anon`, `sock`, OOM, 201, 429, 5xx, загрузок/с,
p50/p95, пик и `anon` S3, пик LB, пометки) и ссылка на метку.
**Итог U1.** TODO (Codex): строка вердикта из `summary.md` и абзац
объяснения.
**Итог U2.** TODO (Codex).
**Итог U3.** TODO (Codex).
**Итог U4.** TODO (Codex).
### 4.3. Стоимость сверки (трек 2)
**Методика** (`make bench-reconcile`, профиль `reconcile`): стенд
`vlad-bench` с LB, двумя репликами, PostgreSQL, Valkey и S3 рабочего
стенда. Набор — мимо API (исключение чёрного ящика только этого
профиля): метаданные `COPY attachments FROM STDIN`, объекты — PUT
загрузчиком `bench/fill_objects.py` ключами пользователя API. Объект `i`:
`id` и содержимое — из SHA-256 `<зерно>:<i>`, класс — `i mod 400` (по
0,25 %: объект без строки, строка без объекта, другой размер, зависшая
загрузка), строки — сутки назад. Проход — разовый `cleaner reconcile …`
(`docker compose run`, grace 30 с, лимит CPU ячейки), через grace + 2 с
после последнего PUT; результат — его итоговая строка. **Каждый проход
сверяет найденное с моделью набора** (иначе профиль падает): это и
проверка корректности сверки на 100 000 объектов. Этапы: A — 1 000 ×
1 MiB (`batch`, `deep`, `deep-fast`); B — 10 000 × 4 KiB (`batch`,
`head`, `deep`); C — тот же стенд + 20 000 (`batch`, `head`); D — + 70 000
(`batch` и под фоновой нагрузкой: `load-stand` — предел 2000/с и
0,25 CPU, `load-unlimited` — без предела, `load-fast` — без предела и
1 CPU, `load-fast-limited` — с пределом и 1 CPU); E — свежий стенд,
10 000 согласованных + 1 000 строк без объекта (`batch` и `refuse` —
`--apply --max-changes 100`). 3 повтора кругами. Фоновая нагрузка —
200 скачиваний, 50 записей и 50 чтений истории в секунду через LB, тихие
окна 20 с до и после прохода. CPU S3, PostgreSQL и реплик за окно прохода
— сэмплер cgroup раз в 0,5 с.
**Гипотезы (записаны до замеров).** Пороги — константы `H*_` в
`bench/reconcile.py`, вердикт считает `summary.md`.
- **H1 — `batch` линейна.** На наборах 4 KiB (10 000, 30 000, 100 000)
время на 1 000 объектов различается не больше чем на 30 %, рост пика RSS
— не больше 300 байт на ключ (множество ключей страниц). Основание: на
страницу из 1 000 ключей — один LIST и одна выборка строк; кандидатов
0,75 % с перепроверкой.
- **H2 — `head` стоит круга на объект.** На 10 000 и 30 000 время `head` —
не меньше 5 × `batch` на том же наборе, запросов к БД не меньше, чем
объектов, а пик RSS от 10 000 к 30 000 растёт не больше чем на 5 MiB
(множества ключей нет).
- **H3 — глубокая сверка упирается в байты и CPU уборщика.** Прочитано
ровно (согласованных объектов × размер) во всех глубоких проходах; на
1 000 × 1 MiB `deep` дольше `batch` не меньше чем в 5 раз, а на 1 CPU
(`deep-fast`) быстрее, чем на 0,25, не меньше чем в 1,5 раза.
- **H4 — предел скорости защищает фон.** В ячейках с пределом (2000
объектов/с) p95 фоновых скачиваний в окне прохода — не больше 1,5 × p95
тихих окон, 5xx нет ни в одном окне, генератор отправил всё по
расписанию, затронуто объектов в секунду — не больше предела / 0,9; без
предела при 1 CPU отношение p95 больше, чем с пределом при 1 CPU.
- **H5 — отказ по пределу ничего не меняет и стоит как dry-run.** При
1 000 кандидатах `--apply --max-changes 100` исправляет 0, код 3,
`refused` во всех повторах; время — в пределах ±20 % dry-run того же
набора, HEAD столько же (перепроверка всех кандидатов делается до
решения об отказе).
**Результаты.** TODO (Codex): таблицы «Проходы» и «Фоновая нагрузка» из
`evidence/reconcile/baseline/summary.md` как есть и ссылка на метку.
**Итог H1.** TODO (Codex): строка вердикта из `summary.md` и абзац
объяснения.
**Итог H2.** TODO (Codex).
**Итог H3.** TODO (Codex).
**Итог H4.** TODO (Codex).
**Итог H5.** TODO (Codex).
**Что это значит для плановой сверки.** TODO (Codex): по `ms_per_1k`
`batch` при 0,25 CPU — сколько займёт плановая сверка (раз в час, предел
2000/с) на 100 000 и 1 000 000 объектов (экстраполяция, оговорить) и
какую долю часа она занимает.
### 4.4. Железо и стенд замеров
TODO (Codex): по `meta.json` меток `uploads/baseline` и
`reconcile/baseline` — `host` (модель CPU, ядра, память, питание),
`docker` (версии, CPU и память ВМ, ядро), `image.versions`, `budget`,
`host_warnings`, `src_sha256` (должен совпадать с разделом 3).
## 5. Ограничения
- Один Docker-host, один HAProxy, одна PostgreSQL, один Valkey и **один
узел S3 без репликации**. Выдерживается отказ процесса API (любой одной
реплики при ≥ 2 живых) и уборщика. Отказ S3 — 503 на загрузке и
скачивании (текст работает); отказ хоста, LB и PostgreSQL не
выдерживается.
- Оригинал хранится в одном экземпляре на volume `s3data`; резервной
копии bucket и восстановления в стенде нет. На время восстановления базы
из backup уборщик нужно остановить: сверка сочла бы объекты новее
backup «без строки» и после grace удалила бы их.
- Окно уборки — `CLEANER_GRACE` 900 с: незавершённая загрузка держит
объект до 15 минут плюс интервал прохода. Сверка с `--deep` читает все
байты — её стоимость растёт с объёмом bucket (раздел 4.3).
- Лимиты загрузок — на процесс: при N репликах одновременно в памяти до
4 × N тел; общей очереди между репликами нет (её роль играет 429 и
повтор клиента).
- Проверка изображения — структурная, без декодирования пикселей:
повреждение внутри сжатых данных при правильных CRC и маркерах не
обнаруживается (превью и декодирование — лаба 5).
- Presigned upload (трек 1) не делался; обязательный путь через API —
единственный.
- Замеры под нагрузкой — на одной машине замеров (раздел 4.4); числа с
машины разработки в отчёт не ставятся.
- TODO (Codex): что обнаружено при замерах (пометки, предупреждения о
хосте, опровергнутые гипотезы).
## 6. Ответы на вопросы защиты
- **Почему файл в Docker volume одной API-реплики не равен объектному
хранилищу?** Volume принадлежит одному контейнеру на одном хосте: другая
реплика его не видит, при остановке или пересоздании реплики (замена,
отказ) файл недоступен или пропадает, доступ к нему никто не проверяет,
его нельзя масштабировать и резервировать отдельно от реплики. S3 —
общая служба с собственными правами доступа и долговечностью, к которой
обращаются все реплики: после остановки принявшей реплики оригинал
отдала другая ([attachment-failover](evidence/attachments/failover.txt)).
- **Когда можно честно вернуть 201?** Только когда оригинал записан в S3
(PUT подтверждён) **и** строка `ready` зафиксирована в PostgreSQL: тогда
любой участник через любую реплику получит метаданные и те же байты.
Раньше нельзя: после ответа отказ одного из хранилищ потерял бы
принятое вложение.
- **Что произойдёт, если S3 PUT прошёл, а COMMIT в PostgreSQL — нет?**
Строка `pending` с ключом записана до PUT, поэтому объект не «потерян»:
если сбой был до отправки COMMIT, загрузка сама удаляет объект и
отвечает 503; если исход COMMIT неизвестен, объект не трогается (строка
могла стать `ready`) и ответ — 503. В обоих случаях остаток — строка
`pending` (и, возможно, объект); через grace 900 с уборщик убирает их
вместе, а сверка находит и объекты, у которых строки нет вовсе. Клиент
повторяет загрузку.
- **Почему случайный object key и приватный bucket не заменяют ACL
приложения?** Приватный bucket закрывает анонимный доступ, но S3 не
знает пользователей мессенджера и их чатов: кто может видеть вложение,
решает только членство в чате, и проверяет его API на каждом запросе
(посторонний — 404). Случайный ключ — не право доступа: он попадает в
журналы, ответы, копии и не отзывается, когда пользователь выходит из
чата; ключи S3 есть у процессов, а не у пользователей.
## 7. Что ещё проверить на защите
- `make reconcile` на рабочем стенде после ручного удаления объекта или
строки — сценарии те же, что в проверках отказов (`test_reconcile_*`).
- `make bench-uploads-quick` (~5 мин) — пик памяти «с лимитом» и OOM
«без лимита» при 40 × 10 MiB.
## 8. Источники и помощь ИИ
- [Amazon S3: загрузка объектов](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html),
[presigned URLs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html)
(почему трек 1 не выбран).
- [SeaweedFS](https://github.com/seaweedfs/seaweedfs): `weed server`,
S3 API, IAM через `weed shell`, ключ подписи filer.
- [aiobotocore](https://github.com/aio-libs/aiobotocore), документация
botocore (конфигурация повторов и сроков).
- Спецификации PNG (W3C, чанки и CRC) и JPEG (ITU T.81, маркеры) — для
структурной проверки без декодирования.
- Документация ядра Linux, cgroup v2: `memory.peak`, `memory.stat`,
`memory.events` — для замера пика памяти.
- Документация HAProxy 3.4 (`http-request set-timeout`, `tune.*buf`),
PostgreSQL 18 (`FOR UPDATE SKIP LOCKED`, частичные индексы, `NOT VALID`).
**Помощь ИИ.** Перенос кода лабы 3 на skeleton лабы 4, реализация
вложений, уборщика, сверки, тестов, стенда `bench/` и этого отчёта
сделаны с Claude (Anthropic, Claude Code) по решениям и проверкам автора;
каждое изменение проверено командами из раздела 3 на реальном стенде.
Замеры под нагрузкой на машине замеров выполняет Codex (OpenAI) по
`bench/RUNBOOK.md` — без права менять код, гипотезы и методику; числа в
отчёт — только из файлов меток.
+13
View File
@@ -0,0 +1,13 @@
# Миграции alembic; правила — migrations/AGENTS.md.
# URL подключения migrations/env.py собирает из тех же переменных DB_*,
# что и приложение (src/config.py), поэтому sqlalchemy.url здесь нет.
# Секций logging тоже нет: журнал идёт текстовым форматом src/log.py.
[alembic]
script_location = %(here)s/migrations
# имя ревизии: <номер>_<slug>.py, номер задаётся при создании (--rev-id)
file_template = %%(rev)s_%%(slug)s
truncate_slug_length = 40
# импорт src из корня репозитория и из /app в образе
prepend_sys_path = .
path_separator = os
+186
View File
@@ -0,0 +1,186 @@
# bench/ — нагрузочный стенд лаб 3 и 4
В лабе 4 нужен для двух вещей из `README.md`:
- уровень «4»: «эксперимент ≥ 10 одновременных загрузок с измерением
пика памяти» — профиль `uploads`;
- уровень «5», трек 2 «Согласованность двух хранилищ»: «измерьте
стоимость обхода» — профиль `reconcile`.
Профили лабы 3 (`failover`, `rollout`, серии `scaling`) сохранены и
работают на коде лабы 4, но в лабе 4 не обязательны: их метки и числа
остались в репозитории лабы 3 и сюда не переносятся.
Порядок работы по шагам — `bench/RUNBOOK.md`. Здесь — правила, которые
действуют на каждом шаге.
## Что есть
| Файл | Команда | Что делает |
|---|---|---|
| `run.py` | `make bench-uploads`, `bench-reconcile`, `*-quick`; лаба 3 — `bench-failover`, `bench-rollout`, `bench-scaling` | оркестратор: стенд, профили, файлы метки |
| `common.py` | — | docker, стенд compose `vlad-bench` (с лабы 4 — S3, bootstrap, уборщик), паспорт, хост, бюджет, сэмплер `peak` |
| `uploads.py` | `uv run python bench/uploads.py --selftest` | профиль `uploads` без docker: план кругами, разбор сэмплера `peak`, строка `runs.csv`, сводка, вердикты U1–U4 |
| `reconcile.py` | `uv run python bench/reconcile.py --selftest` | профиль `reconcile` без docker: модель набора (id, содержимое и класс по номеру и зерну), строки `COPY`, план, разбор итога уборщика, сверка с моделью, окна фоновой нагрузки, вердикты H1–H5, сводка |
| `fill_objects.py` | — (контейнер `vlad-bench-fill`) | PUT объектов набора мимо API: botocore образа стенда, ключи пользователя API из окружения контейнера |
| `analysis.py` | `uv run python bench/analysis.py --selftest` | разбор без docker: журналы запросов, события Docker, журнал HAProxy, агрегаты сэмплера, признаки узкого места, поиск R* |
| `loadgen.py` | — (`docker exec` в `vlad-bench-gen`) | генератор на stdlib: `setup`, `step`, `constant` (с лабы 4 — скачивания вложений и `--stop-file`), `retry`, `body` (PNG из шума), `uploads` (закрытая модель загрузок) |
| `sampler.py` | — (контейнер `vlad-bench-sampler`) | `list`/`scan` — CPU и память cgroup раз в интервал; `peak` (лаба 4) — сброс `memory.peak` своим дескриптором, выборки `current`/`anon`/`sock`/`oom_kill` раз в 0,2 с |
| `compare.py`, `plots.py` | `make bench-compare`, `make bench-plots` | лаба 3: «до/после» серий и графики SVG |
| `bench.compose.yml`, `bench.env` | — | override стенда: имена, лимиты `BENCH_*`, без портов и swap; S3 и уборщик с лимитами рабочего стенда |
Профили (поля — `UploadsProfile`, `ReconcileProfile` в `run.py`,
целиком в `meta.json`):
| Профиль | Что | Время |
|---|---|---|
| `uploads` | LB, одна реплика 1 CPU / 512 МБ без swap, S3 1 CPU / 512 МБ; варианты «с лимитом» (места по умолчанию: 4 + очередь 16) и «без лимита» (`UPLOAD_MAX_CONCURRENT=1000`, `UPLOAD_MAX_WAITING=0`) × тела ~1 и ~10 MiB × 1/10/20/40 клиентов × 3 повтора = 48 прогонов | ~45 мин |
| `uploads-quick` | оба варианта, 10 MiB, 1/10/40 клиентов, один повтор, окно 10 с | ~5 мин |
| `reconcile` | LB, две реплики, S3; этапы: A — 1 000 × 1 MiB (`batch`, `deep`, `deep-fast`); B — 10 000 × 4 KiB (`batch`, `head`, `deep`); C — тот же стенд +20 000 (`batch`, `head`); D — +70 000 (`batch` и четыре ячейки под фоновой нагрузкой); E — свежий, 10 000 согласованных + 1 000 строк без объекта (`batch`, `refuse`); 3 повтора кругами | ~45 мин |
| `reconcile-quick` | 2 000 × 4 KiB (`batch`, `head`, `deep`, `load-stand`, `load-fast`) и 500 + 100 (`batch`, `refuse`), один повтор | ~6 мин |
Ячейки сверки (`reconcile.CELLS`): `batch` — выборка строк на страницу
списка; `head` — выборка на объект и HEAD на строку; `deep` — SHA-256
содержимого; `-fast` — уборщик 1 CPU вместо 0,25; `load-*` — проход под
фоновой нагрузкой (скачивания 200/с, запись 50/с, чтение 50/с через LB):
`load-stand` — предел скорости по умолчанию (`RECONCILE_RATE`, 2000
объектов/с) и 0,25 CPU, `load-unlimited` — без предела, `load-fast` —
без предела и 1 CPU, `load-fast-limited` — с пределом и 1 CPU; `refuse` —
`--apply --max-changes 100` (быстрый — 10) при большем числе кандидатов.
Все прочие ячейки — dry-run.
Стенд — свой проект compose `vlad-bench`: тот же `compose.yaml` с
override `bench.compose.yml` и подстановками `bench.env`, а не `.env`
рабочего стенда. Контейнеры: `vlad-bench-postgres`, `vlad-bench-valkey`,
`vlad-bench-s3`, `vlad-bench-lb`, реплики `vlad-bench-api-N`, генератор
`vlad-bench-gen`, сэмплер `vlad-bench-sampler`, загрузчик
`vlad-bench-fill`, разовые проходы `vlad-bench-reconcile-<n>`; сеть
`vlad-bench-net`, volume `vlad-bench_pgdata`, `vlad-bench_s3data`.
Генератор ходит только через LB (`http://haproxy:8080`).
Файлы меток:
- `evidence/uploads/<метка>/`: `summary.md` (ячейки — медиана и min–max
повторов, вердикты U1–U4), `runs.csv` (строка на прогон: память до
окна, пик окна, пик старта, `anon`, `sock`, OOM, ответы по кодам,
загрузок/с, p50/p95/p99, пики S3 и LB, пометки), `meta.json` (профиль,
план, тела с SHA-256, паспорт стенда, `app_env` по вариантам), `raw/`
(`<прогон>-gen.json` — итог генератора, `<прогон>-peak.jsonl` — строки
сэмплера);
- `evidence/reconcile/<метка>/`: `summary.md` (проходы, фоновая нагрузка,
вердикты H1–H5), `passes.csv` (строка на проход: найдено по классам,
стоимость — вызовы S3 по операциям, ключи списка, прочитанные байты,
запросы к БД, длительность шагов, CPU и пик RSS уборщика, CPU S3,
PostgreSQL и реплик за окно прохода), `windows.csv` (окно × вид
запроса фоновой нагрузки), `meta.json` (план, модели наборов,
наполнение), `raw/` (журнал каждого прохода, журнал запросов фоновой
нагрузки `.csv.gz`).
Хеш кода `src_sha256` (по `src/` и `migrations/` **внутри образа**),
версии пакетов и значения по умолчанию (`app_defaults`: пул, мест
загрузок, сверки, `MALLOC_MMAP_THRESHOLD_`) — в паспорте метки. Образ
метки `mtusi-messenger-vladimirceva:bench-<метка>` остаётся в docker;
образы `quick-*` стенд удаляет.
## Методика не меняется между метками
Не меняются (поменял — новая методика, метки переснимаются, в
`REPORT.md` — что и почему):
- **машина и сессия**: метки одного профиля — на одной машине, рабочий
стенд остановлен (`make stop`), посторонних контейнеров нет;
- **профиль** (`run.py`): лимиты (реплика 1 CPU / 512 МиБ без swap,
PostgreSQL 2 / 1 ГиБ, Valkey 0,5 / 128 МиБ, HAProxy 1 / 256 МиБ, S3 1 /
512 МиБ, уборщик 0,25 / 256 МиБ, генератор 2 / 1 ГиБ, сэмплер 0,25 /
256 МиБ), тела и их зерно, клиенты, окна, наборы, классы и их доли
(0,25 % на класс), этапы и ячейки, фоновая нагрузка, повторы, зерно
порядка. Новый параметр — поле профиля, а не константа в коде;
- **хранилища, S3 и LB**: те же пины образов и аргументы, что у рабочего
стенда (`compose.yaml`), тот же `haproxy.cfg`, `valkey.conf`,
`infra/s3/bootstrap.sh`; bucket `bench` (`bench.env`);
- **приложение**: значения по умолчанию `src/config.py`; окружение
стенда — срок сессии, у варианта «без лимита» — два `UPLOAD_*`
(override `variant-unlimited.compose.yml` во временном каталоге), у
проходов сверки — `CLEANER_GRACE=30`;
- **пороги вердиктов** (`U*` в `uploads.py`, `H*_` в `reconcile.py`)
записаны до замеров вместе с гипотезами в `REPORT.md`. Их изменение —
смена методики, а не подгонка вывода.
## Честность результатов
- В `evidence/uploads/<метка>/` и `evidence/reconcile/<метка>/` пишет
только `run.py`. Руками эти файлы не править и не пересобирать.
- Каталог метки не перезаписывается. Неудачная метка (`aborted`,
предупреждения о хосте, пометки) не удаляется молча и не выдаётся за
результат: сними новую метку и скажи пользователю, почему старая не
годится. Удалять каталог метки — только с согласия пользователя.
- Числа в `REPORT.md` переносятся из `summary.md` и `*.csv` как есть.
- Гипотезы U1–U4 и H1–H5 записаны в `REPORT.md` **до** замеров и после
них не переписываются; итог — отдельным абзацем ниже. Опровергнутая
гипотеза — тоже результат.
- Проект не под git: измеренный код называет `src_sha256` в паспорте.
## Как устроен стенд (не ломать)
- Чёрный ящик: `run.py` не импортирует `src`; запросы к API — только
генератор по HTTP через LB.
- Исключения, только на стенде `vlad-bench`:
- PostgreSQL стенда — `docker exec … psql` от пользователя контейнера,
SQL через stdin: `VACUUM (ANALYZE)`, `CHECKPOINT`, число строк,
ревизия; у профиля `reconcile` — ещё `COPY attachments FROM STDIN`
(метаданные набора; схему не трогает, файла CSV нет — строки
генерирует `reconcile.rows_csv`);
- объекты набора `reconcile` — `fill_objects.py` в `vlad-bench-fill`
(ключи API — `docker run -e <имя>` без значения в argv);
- S3 профиля `uploads` — перед каждым прогоном удаляется вместе с
volume и поднимается заново с bootstrap; к bucket оркестратор не
обращается;
- сэмплер `peak` — `--user 0`, cgroupfs на запись, без сети: запись
`reset` в `memory.peak` своим дескриптором — управление счётчиком
ядра, а не приложением;
- проход сверки — процесс уборщика из образа (`docker compose run
cleaner reconcile …`), результат — его итоговая строка `reconcile
pass finished` (`raw/<проход>-cleaner.log`).
- Найденное каждым проходом сверяется с моделью набора
(`reconcile.found_problems`): расхождение — отказ профиля с проходом,
классом и обоими числами. Это проверка корректности сверки, а не
пометка.
- Все вызовы compose — с `-p vlad-bench`, обоими `-f` (у варианта —
третьим) и `--env-file bench/bench.env`. Пароли хранилищ и семь
секретов S3 — новые на прогон, никуда не пишутся; compose требует
секреты S3 и у профилей лабы 3, которые S3 не запускают.
- Пароли и токены пользователей стенда живут только в генераторе; в
stdout, результаты и паспорт не попадают. В паспорт окружения реплик не
попадают имена с `PASSWORD`, `SECRET`, `ACCESS_KEY`.
- Все отметки времени — часы ВМ Docker: генератор, сэмплер, журнал
уборщика (`src/log.py`, UTC с мс).
- Только стандартная библиотека Python на хосте и в генераторе.
- Один прогон за раз: блокировка `bench/.bench.lock`. Остатки
прерванного прогона `run.py` не удаляет сам: печатает команды уборки.
- Чужие контейнеры не останавливать и не удалять.
- Столбцы `runs.csv`, `passes.csv`, `windows.csv` не переименовывать и не
удалять. Новая метрика — новый столбец в конце.
## Пометки и что с ними делать
| Где | Пометка | Значит | Действие |
|---|---|---|---|
| `meta.json` | `aborted` | прогон прерван | новая метка после разбора `app-tail.log` |
| `meta.json` | `host_warnings` | батарея, давление на память, посторонние контейнеры, выгрузка страниц, сон | устранить и переснять |
| `runs.csv` | `oom` | реплику завершило ядро по памяти | это результат варианта (ожидаем у «без лимита»), не сбой |
| `runs.csv` | `peak_sampled` | `memory.peak` не сброшен (ядро < 6.12) | пик — по выборкам раз в 0,2 с: сказать в отчёте |
| `runs.csv` | `host_swap` | хост выгружал страницы во время прогона | переснять метку |
| `passes.csv` | `cpu_limit` | лимит CPU прохода не тот, что у ячейки | дефект стенда: разобраться, не переносить в отчёт |
| `passes.csv` | `exit` | код уборщика не 3 | набор с расхождениями даёт 3: смотреть `raw/<проход>-cleaner.log` |
| `passes.csv` | `bg_dropped` | генератор фоновой нагрузки не отправил часть запросов по расписанию | H4 по такой метке не подтверждается: сказать пользователю, переснять на тихом хосте |
| профиль падает | `found differs from the model` | сверка нашла не то, что внесено | дефект сверки или стенда: остановиться, сказать пользователю |
## Проверка правок стенда
`make fmt && make lint`; `uv run python bench/analysis.py --selftest`,
`uv run python bench/uploads.py --selftest`, `uv run python
bench/reconcile.py --selftest`; затем `make bench-uploads-quick` и
`make bench-reconcile-quick`: прогоны доходят до конца, `aborted` нет.
Правка общего (`common.py`, `loadgen.py`, `sampler.py`) — ещё
`make bench-failover-quick`. Docker недоступен из sandbox — попросить
пользователя запустить команду и прислать вывод.
+230
View File
@@ -0,0 +1,230 @@
# Лаба 4: замеры уровня 4 и трека 2 — порядок работы
Документ для того, кто выполняет замеры на устройстве, где идут прогоны,
— человека или Codex. Правила стенда — `bench/AGENTS.md`, общие —
корневой `AGENTS.md`. Читать целиком до первого `make bench-*`.
**Цель — оценка «5»** (`README.md`): весь уровень 4 и законченный трек 2
«Согласованность двух хранилищ». Приложение, тесты, стенд и все проверки
уровней 3 и 4, которые не требуют нагрузки, готовы и сняты на машине
разработки (`evidence/`, таблица доказательств `REPORT.md`). По этому
документу остаются два замера под нагрузкой, их выводы и отчёт. **Код
приложения не меняется**: замеры проверяют записанные гипотезы, а не
подбирают код под них.
**Что требует задание.**
- Уровень 4: «лимиты/таймауты и потоковая обработка не позволяют одной
загрузке занять неограниченную RAM. Проведён эксперимент ≥ 10
одновременных загрузок с измерением пика памяти» → профиль `uploads`.
- Трек 2: «разработайте повторяемый reconciler … внедрите ошибки на обеих
сторонах, покажите обнаружение и безопасное исправление с
dry-run/повторным запуском. Докажите, что свежие и используемые
вложения не удаляются; измерьте стоимость обхода» — обнаружение,
исправление, повтор и защита свежих сняты без нагрузки
(`evidence/reconcile/`, проверки отказов); **стоимость обхода** →
профиль `reconcile`. Плюс гипотеза, повторяемая методика, результаты,
ограничения.
- `COURSE.md`: версии и образы, железо, лимиты CPU/RAM, команда запуска,
прогрев, длительность, интенсивность, успешные запросы, ошибки,
p50/p95/p99, CPU/RAM. Всё это стенд пишет в `meta.json` и `summary.md`.
## Словарь
- **Метка** — один прогон профиля; каталог
`evidence/<uploads|reconcile>/<метка>/` не перезаписывается.
- **Прогон** (`uploads`) — вариант × тело × число клиентов × повтор:
новый S3, новая реплика, разогрев, окно. **Ячейка** — все повторы
одного варианта, тела и числа клиентов.
- **Проход** (`reconcile`) — один запуск `cleaner reconcile …` на наборе
этапа. **Этап** — набор N объектов; **ячейка** — вид прохода
(`batch`, `head`, `deep`, `load-*`, `refuse`).
- **Пик** — `memory.peak` cgroup реплики, сброшенный перед окном; **до
окна** — первая выборка `memory.current` после сброса.
- **Классы расхождений набора** — по 0,25 %: объект без строки
(`orphan_object`), строка без объекта (`missing_object`), другой размер
(`size_mismatch`), зависшая загрузка (`stale_pending`).
## Сколько это занимает
| Шаг | Что | Время |
|---|---|---|
| 0 | подготовка, проверки, самопроверки стенда | 25–30 мин |
| 1 | уровень 4: память загрузок (`uploads`) | ~45 мин + 20 мин отчёт |
| 2 | трек 2: стоимость сверки (`reconcile`) | ~45 мин + 30 мин отчёт |
| 3 | отчёт и финальные проверки | 40 мин |
Шаги 1–2 — в одной сессии устройства, без перезагрузки. Во время
прогонов устройством не пользоваться, крышку ноутбука не закрывать
(цели `bench-*` идут под `caffeinate`, но от сна при закрытой крышке он
не спасает). Длинные команды — в фоне с журналом в файл, не в чате.
**Точки остановки.** После шагов 0, 1 и 2 — короткий отчёт пользователю
(что снято, пометки и предупреждения, главные числа) и ожидание
«продолжай». Что-то пошло не по плану (`aborted`, `host_warnings`,
упавшие проверки, `found differs from the model`) — остановиться сразу,
не переснимать молча.
**Как запускать долгое** (Codex: команды с docker — вне sandbox, с
одобрения пользователя; корневой `AGENTS.md`, раздел 10):
```sh
nohup make bench-uploads > /tmp/bench-uploads.log 2>&1 &
tail -n 20 /tmp/bench-uploads.log # раз в несколько минут
```
Каждый прогон `uploads` печатает строку `peak … MiB, 201 …, 429 …, 5xx
…, … uploads/s [пометки]`, каждый проход `reconcile` — `… ms, cpu … ms,
s3 list/head/get …, db …`.
---
## Шаг 0. Подготовка
- [ ] Docker доступен: `docker version`. Из sandbox Codex docker часто
недоступен — запроси запуск вне sandbox или попроси пользователя.
- [ ] Ресурсы ВМ Docker Desktop: `docker info --format '{{.NCPU}} CPU,
{{.MemTotal}} bytes {{.KernelVersion}}'`. Нужно **не меньше 10 CPU
и 7 ГиБ** (`reconcile` на пике — 9,75 CPU лимитов и ~6,4 ГиБ с
запасом, `uploads` — 8 CPU и ~5,4 ГиБ). Меньше — Settings →
Resources в Docker Desktop: CPU — максимум, память — 8 ГиБ,
перезапуск Docker. Не помещается и после этого — **сказать
пользователю до замеров**, лимиты профиля не уменьшать. Ядро ВМ
≥ 6.12 — иначе сброса `memory.peak` нет и пик будет по выборкам
(пометка `peak_sampled`): сказать пользователю, в отчёт.
- [ ] `make install`, `make lint`, самопроверки разбора:
```sh
uv run python bench/analysis.py --selftest # analysis selftest: ok
uv run python bench/uploads.py --selftest # uploads selftest: ok
uv run python bench/reconcile.py --selftest # reconcile selftest: ok
```
- [ ] `make test-isolated` (в `results` все 0) и `make failure-checks`
(`24 passed`). Красное — сначала разобраться (корневой
`AGENTS.md`, раздел 9), замеры не начинать.
- [ ] Рабочий стенд остановлен: `make stop`. `docker ps` — пусто. Чужие
контейнеры не останавливать: если они есть, спросить пользователя
(стенд пишет их в `host_warnings`).
- [ ] Питание от сети, свободной памяти достаточно (`memory_pressure`),
тяжёлые программы закрыты.
- [ ] Самопроверки стенда (метки `quick-*` в отчёт не идут):
```sh
make bench-uploads-quick # ~5 мин: 6 прогонов, у «без лимита» C=40 — oom
make bench-reconcile-quick # ~6 мин: 7 проходов, нет aborted
```
Смотри `summary.md` каждой метки: нет `aborted`, в разделе
«Предупреждения о хосте» пусто, у `uploads-quick` пометок
`peak_sampled` нет нигде, кроме прогонов с `oom` (после гибели
реплики пик читается по выборкам), у `reconcile-quick` в
`passes.csv` столбец `model_ok` — `True` во всех строках.
- [ ] Гипотезы U1–U4 и H1–H5 уже записаны в `REPORT.md` («Память
загрузок: гипотезы», «Трек 2: гипотезы») **до** замеров. Не
переписывай их; итог — отдельными абзацами «Итог: …» под каждой.
- [ ] Проект не под git: измеренный код называет `src_sha256` в паспорте.
Если пользователь сделал из проекта git-репозиторий — коммит перед
замером только с его согласия.
**Остановка:** отчёт пользователю — ресурсы ВМ, ядро, результаты
проверок и самопроверок.
## Шаг 1. Уровень 4: память загрузок
```sh
nohup make bench-uploads > /tmp/bench-uploads.log 2>&1 &
```
Метка `baseline` (`evidence/uploads/baseline/`, ~45 мин, 48 прогонов).
Проверь `summary.md`:
- [ ] `aborted` нет, предупреждений о хосте нет;
- [ ] в каждой ячейке 3 повтора; `oom` — только у «без лимита» (у «с
лимитом» `oom` — опровержение U1, а не сбой: так и записать);
- [ ] `peak_sampled` — только в прогонах с `oom`.
В `REPORT.md` (раздел «Память при одновременных загрузках», строки
`TODO (Codex)`):
- таблица ячеек из `summary.md` как есть (вариант, тело, C, пик, до окна,
`anon`, `sock`, OOM, 201, 429, 5xx, загрузок/с, p50/p95) и ссылка на
метку;
- итог каждой гипотезы U1–U4 — строка вердикта из `summary.md` с
числами, затем абзац объяснения. Опора объяснения: места загрузок
(`UPLOAD_MAX_CONCURRENT` 4, очередь 16, ожидание 5 с → 429 с
`Retry-After`), одна копия тела в `BytesIO` и
`MALLOC_MMAP_THRESHOLD_=131072` (буфер тела — отдельный mmap,
возвращается ядру), буфер приёма сокета реплики 512 KiB (`sock`
ожидающих клиентов), лимит одновременной записи шлюза S3 64 МБ;
- строка таблицы доказательств: «Эксперимент ≥ 10 одновременных
загрузок с измерением пика памяти» → `evidence/uploads/baseline/`.
**Остановка:** отчёт пользователю — пики «с лимитом» и «без лимита» при
C = 10/20/40, OOM, итоги U1–U4.
## Шаг 2. Трек 2: стоимость сверки
```sh
nohup make bench-reconcile > /tmp/bench-reconcile.log 2>&1 &
```
Метка `baseline` (`evidence/reconcile/baseline/`, ~45 мин). Наполнение
этапа D (70 000 объектов) — несколько минут без строк в журнале, это
нормально.
Проверь `summary.md` и `passes.csv`:
- [ ] `aborted` нет, предупреждений о хосте нет;
- [ ] `model_ok` — `True` во всех строках, `flags` пустые (иначе — в
`bench/AGENTS.md`, «Пометки»);
- [ ] у каждой ячейки 3 повтора; у ячеек `load-*` есть строки
`windows.csv` всех трёх окон.
В `REPORT.md` (раздел «Стоимость сверки», строки `TODO (Codex)`):
- таблица проходов из `summary.md` как есть (этап, N, размер, ячейка,
время, мс на 1 000, вызовы S3, запросы к БД, прочитано, CPU, RSS) и
таблица фоновой нагрузки;
- итог H1–H5 — строки вердиктов из `summary.md` с числами, затем абзац
объяснения: что стоит дороже всего и почему (`batch` — страница списка
и одна выборка на 1 000 объектов, множество ключей в памяти; `head` —
круг к БД и S3 на каждый объект; `deep` — чтение всех байт и SHA-256 в
квоте 0,25 CPU; предел скорости растягивает проход, но держит фон);
- практический вывод для плановой сверки (раз в `RECONCILE_INTERVAL`
3600 с, `batch`, предел 2000/с): сколько она займёт на N объектов по
числам `ms_per_1k` — с оговоркой, что это экстраполяция;
- строка таблицы доказательств: «Трек 2: стоимость обхода» →
`evidence/reconcile/baseline/`.
**Остановка:** отчёт пользователю — время и запросы на 1 000 объектов по
стратегиям, отношение p95 фона, итоги H1–H5.
## Шаг 3. Отчёт и проверка
- [ ] `REPORT.md`: все строки `TODO (Codex)` заменены реальными числами со
ссылками на метки; гипотезы не переписаны, итоги — отдельными
абзацами; раздел «Железо и стенд замеров» — из `meta.json` меток
(`host`, `docker`, `image.versions`, `budget`); ограничения
дополнены тем, что обнаружено.
- [ ] Корневой `AGENTS.md`: абзац «Состояние» — что снято, где результаты.
- [ ] `make lint`, `make check`, `make test-isolated` — после всех правок.
- [ ] Остановить всё, что запускал: `docker ps -a | grep vlad-bench` —
пусто; рабочий стенд — как был до тебя.
- [ ] Отчёт пользователю (корневой `AGENTS.md`, раздел 11).
## Чеклист готовности
- [ ] `evidence/uploads/baseline/` — 48 прогонов, без `aborted`.
- [ ] `evidence/reconcile/baseline/` — 45 проходов, `model_ok` везде.
- [ ] `REPORT.md`: итоги U1–U4 и H1–H5, таблицы, железо, ограничения.
## Если что-то пошло не так
| Симптом | Причина и что делать |
|---|---|
| `leftovers of an interrupted bench run` | прошлый прогон прерван: выполнить напечатанные команды уборки (только `vlad-bench*`), затем повторить |
| `another bench run holds bench/.bench.lock` | идёт другой прогон: дождаться (`ps aux \| grep bench/run.py`) |
| `limits need N CPU, docker VM has M` | ВМ Docker меньше лимитов: шаг 0, ресурсы; не уменьшать лимиты профиля |
| `peak sampler did not reset memory.peak` | нет записи в cgroupfs: Docker не Desktop или rootless — сказать пользователю |
| `warm-up upload failed` | реплика или S3 не готовы: `app-tail.log` метки; повторить один раз |
| `found differs from the model` | сверка нашла не то, что внесено: дефект — остановиться, `raw/<проход>-cleaner.log`, сказать пользователю |
| `no 'reconcile pass finished' line` | уборщик упал: последние строки журнала в сообщении; разбор, не переснимать вслепую |
| `aborted` | новая метка после разбора `app-tail.log` и `raw/` |
| `host_warnings` | устранить причину (питание, память, посторонние контейнеры) и переснять метку новым именем |
+546
View File
@@ -0,0 +1,546 @@
"""Разбор результатов стенда без docker: журналы, окна, признаки, поиск R*.
Чистые функции над строками журналов генератора, событиями Docker,
журналом HAProxy и тиками сэмплера. Их зовёт `run.py`; самопроверка —
`uv run python bench/analysis.py --selftest`. Только stdlib.
Все отметки времени — часы ВМ Docker в миллисекундах эпохи: генератор
(`time.time()` в контейнере), события Docker (`timeNano`), журнал HAProxy
(`docker logs -t`), сэмплер. Часы хоста с ними не сравниваются.
"""
import dataclasses
import datetime
import json
import math
import re
import sys
# --- журнал запросов генератора (профили failover и rollout) ----------------
@dataclasses.dataclass(frozen=True)
class Request:
scheduled: float
sent: float | None
done: float | None
kind: str
status: int
instance: str
key: str
error: str
@property
def ok(self) -> bool:
return self.status == (201 if self.kind == "write" else 200)
@property
def latency(self) -> float | None:
"""Задержка от момента по расписанию до ответа, мс."""
return None if self.done is None else self.done - self.scheduled
def parse_requests(text: str) -> list[Request]:
out = []
for line in text.splitlines():
parts = line.split(",")
if len(parts) != 9 or parts[0] != "fo":
continue
out.append(
Request(
scheduled=float(parts[1]),
sent=float(parts[2]) if parts[2] else None,
done=float(parts[3]) if parts[3] else None,
kind=parts[4],
status=int(parts[5]),
instance=parts[6],
key=parts[7],
error=parts[8],
),
)
out.sort(key=lambda r: r.scheduled)
return out
def percentile(values: list[float], fraction: float) -> float | None:
if not values:
return None
ordered = sorted(values)
return ordered[max(1, math.ceil(fraction * len(ordered))) - 1]
def error_label(request: Request) -> str:
return request.error or str(request.status)
def window_stats(requests: list[Request], start: float, end: float) -> dict:
"""Запросы окна [start, end) по моменту расписания."""
inside = [r for r in requests if start <= r.scheduled < end]
seconds = max((end - start) / 1000, 1e-9)
ok = [r for r in inside if r.ok]
errors: dict[str, int] = {}
for request in inside:
if not request.ok:
errors[error_label(request)] = errors.get(error_label(request), 0) + 1
latencies = [r.latency for r in ok if r.latency is not None]
return {
"seconds": round(seconds, 2),
"requests": len(inside),
"ok": len(ok),
"ok_rps": round(len(ok) / seconds, 1),
"ok_write_rps": round(sum(r.kind == "write" for r in ok) / seconds, 1),
"ok_read_rps": round(sum(r.kind == "read" for r in ok) / seconds, 1),
"errors": sum(errors.values()),
"error_kinds": errors,
"p50_ms": _r(percentile(latencies, 0.5)),
"p95_ms": _r(percentile(latencies, 0.95)),
"p99_ms": _r(percentile(latencies, 0.99)),
"max_ms": _r(max(latencies) if latencies else None),
}
def _r(value: float | None, digits: int = 1) -> float | None:
return None if value is None else round(value, digits)
def timeline(
requests: list[Request],
origin: float,
start: float,
end: float,
groups: dict[str, set[str]] | None = None,
) -> list[dict]:
"""Посекундная шкала от `origin`: успешные по видам, ошибки, реплики.
`groups` — именованные наборы X-Instance-Id (цель и остальные, старые
и новые): у каждого — число успешных ответов в секунду.
"""
first = math.floor((start - origin) / 1000)
last = math.ceil((end - origin) / 1000)
rows = []
for second in range(first, last):
lo, hi = origin + second * 1000, origin + (second + 1) * 1000
inside = [r for r in requests if lo <= r.scheduled < hi]
ok = [r for r in inside if r.ok]
errors: dict[str, int] = {}
for request in inside:
if not request.ok:
errors[error_label(request)] = errors.get(error_label(request), 0) + 1
latencies = [r.latency for r in ok if r.latency is not None]
row = {
"second": second,
"sent": len(inside),
"ok_write": sum(r.kind == "write" for r in ok),
"ok_read": sum(r.kind == "read" for r in ok),
"errors": sum(errors.values()),
"error_kinds": ";".join(f"{k}:{v}" for k, v in sorted(errors.items())),
"p95_ms": _r(percentile(latencies, 0.95)),
"max_ms": _r(max(latencies) if latencies else None),
}
for name, ids in (groups or {}).items():
row[f"ok_{name}"] = sum(r.instance in ids for r in ok)
rows.append(row)
return rows
def recovery_seconds(
requests: list[Request],
action: float,
end: float,
offered_per_s: float,
) -> float | None:
"""Время восстановления, с: от действия до начала первой секунды, после
которой до `end` нет ни одной ошибки и успешных не меньше 90 % от
поданной нагрузки в каждой секунде. None — не восстановилось."""
rows = timeline(requests, action, action, end)
good = [
row["errors"] == 0 and row["ok_write"] + row["ok_read"] >= 0.9 * offered_per_s
for row in rows
]
for index in range(len(good)):
if all(good[index:]):
return float(rows[index]["second"])
return None
# --- события Docker и журнал HAProxy ------------------------------------------------
def parse_events(text: str) -> list[tuple[float, str, str]]:
"""`docker events --format '{{json .}}'`: (мс, действие, id контейнера)."""
events = []
for line in text.splitlines():
line = line.strip()
if not line:
continue
data = json.loads(line)
action = data.get("Action") or data.get("status") or ""
actor = (data.get("Actor") or {}).get("ID") or data.get("id") or ""
events.append((int(data["timeNano"]) / 1e6, action.split(":")[0], actor))
events.sort()
return events
_LB_STATE = re.compile(
r"Server api/(?P<slot>api-\d+)\b.*?(?P<state>is DOWN|is UP|is going DOWN"
r"|enters drain|enters maintenance|is leaving forced drain|is leaving maintenance"
r"|administratively READY)",
)
def parse_docker_time(stamp: str) -> float:
"""RFC 3339 с наносекундами из `docker logs -t` → мс эпохи."""
stamp = stamp.rstrip("Z")
main, _, fraction = stamp.partition(".")
base = datetime.datetime.fromisoformat(main).replace(tzinfo=datetime.UTC)
return base.timestamp() * 1000 + float(f"0.{fraction or 0}") * 1000
def parse_lb_log(text: str) -> list[tuple[float, str, str]]:
"""Смены состояния слотов: (мс, слот, состояние). Дубли строк HAProxy
(мастер и воркер пишут одну и ту же) схлопываются."""
seen = set()
out = []
for line in text.splitlines():
stamp, _, message = line.partition(" ")
match = _LB_STATE.search(message)
if not match:
continue
when = parse_docker_time(stamp)
item = (round(when / 50), match.group("slot"), match.group("state"))
if item in seen:
continue
seen.add(item)
out.append((when, match.group("slot"), match.group("state")))
out.sort()
return out
def lb_http_errors(text: str) -> dict[str, int]:
"""Ответы с ошибкой в журнале HAProxy (option dontlog-normal пишет
только их): статус → число."""
counts: dict[str, int] = {}
for line in text.splitlines():
match = re.search(r'\s(\d{3}) \d+ - - (\S{4}) .*"(GET|POST) ', line)
if match and match.group(1)[0] in "45":
counts[match.group(1)] = counts.get(match.group(1), 0) + 1
return counts
# --- сэмплер ---------------------------------------------------------------------------
def window_ticks(ticks: list[dict], start: float, end: float) -> list[dict]:
"""Тики окна [start, end] (секунды эпохи) плюс по одному снаружи:
приращения считаются по краям окна."""
inside = [t for t in ticks if start <= t["ts"] <= end]
before = [t for t in ticks if t["ts"] < start]
after = [t for t in ticks if t["ts"] > end]
return ([before[-1]] if before else []) + inside + ([after[0]] if after else [])
def cgroup_usage(ticks: list[dict], container: str) -> dict | None:
"""CPU (ядер), доля троттлинга и память контейнера по тикам окна.
Каждый соседний интервал считается отдельно: новая cgroup (контейнер
перезапущен) даёт отрицательное приращение — такой интервал
пропускается, а не обнуляет окно.
"""
points = [(t["ts"], t["cg"].get(container[:12])) for t in ticks]
points = [(ts, line) for ts, line in points if line]
if len(points) < 2:
return None
cpu_us = seconds = periods = throttled = 0.0
memory = 0
for (t0, a), (t1, b) in zip(points, points[1:], strict=False):
if b[0] < a[0]:
continue
cpu_us += b[0] - a[0]
seconds += t1 - t0
periods += b[1] - a[1]
throttled += b[2] - a[2]
memory = max(memory, a[4], b[4])
if seconds <= 0:
return None
return {
"cpu_cores": round(cpu_us / seconds / 1e6, 3),
"throttled_share": round(throttled / periods, 4) if periods else 0.0,
"memory_mib": round(memory / 2**20, 1),
}
def vm_busy(ticks: list[dict]) -> float | None:
if len(ticks) < 2:
return None
busy = ticks[-1]["vm"][0] - ticks[0]["vm"][0]
total = ticks[-1]["vm"][1] - ticks[0]["vm"][1]
return round(busy / total, 4) if total else None
def lb_delta(ticks: list[dict], field: str) -> int | None:
"""Приращение счётчика HAProxy по всем слотам за окно."""
with_lb = [t for t in ticks if t.get("lb")]
if len(with_lb) < 2:
return None
def total(tick: dict) -> int:
return sum(
row.get(field, 0) for name, row in tick["lb"].items() if name != "FRONTEND"
)
return total(with_lb[-1]) - total(with_lb[0])
def pg_stats(ticks: list[dict], replica_addrs: set[str]) -> dict:
"""Соединения приложения и счётчики базы за окно."""
with_pg = [t for t in ticks if t.get("pg")]
if not with_pg:
return {}
per_tick_total, per_replica_max, active, lock_waits = [], 0, [], []
for tick in with_pg:
by_addr: dict[str, int] = {}
busy = waiting = 0
for addr, state, wait, count in tick["pg"]["conn"]:
by_addr[addr] = by_addr.get(addr, 0) + count
if state == "active":
busy += count
if wait == "Lock":
waiting += count
per_tick_total.append(sum(by_addr.values()))
known = [
n for a, n in by_addr.items() if not replica_addrs or a in replica_addrs
]
per_replica_max = max([per_replica_max, *known])
active.append(busy)
lock_waits.append(waiting)
first, last = with_pg[0]["pg"]["db"], with_pg[-1]["pg"]["db"]
seconds = max(with_pg[-1]["ts"] - with_pg[0]["ts"], 1e-9)
return {
"pg_conn_max": max(per_tick_total),
"pg_conn_replica_max": per_replica_max,
"pg_active_mean": round(sum(active) / len(active), 2),
"pg_lock_wait_mean": round(sum(lock_waits) / len(lock_waits), 2),
"pg_new_sessions": last["sessions"] - first["sessions"],
"pg_commits_per_s": round(
(last["xact_commit"] - first["xact_commit"]) / seconds, 1
),
}
# --- признаки узкого места (серии трека 1) ------------------------------------------
# Пороги заданы до прогонов (REPORT.md, гипотезы трека 1). Сработавший
# признак на первой нарушившей ступени называет, во что упёрлась система
THRESHOLDS = {
# реплика: доля своего лимита CPU или заметный троттлинг CFS
"app_cpu_share": 0.85,
"app_throttled_share": 0.20,
# PostgreSQL: доля лимита CPU, средние ожидания блокировок
"db_cpu_share": 0.85,
"db_lock_wait_mean": 1.0,
# пул: соединений одной реплики не меньше доли её предела (размер + переполнение)
"pool_share": 0.90,
# переоткрытие соединений: новых сессий PostgreSQL за окно ступени
"churn_sessions": 20,
# LB: доля его лимита CPU
"lb_cpu_share": 0.85,
# ВМ Docker занята почти целиком: реплики ждут CPU хоста
"host_busy_share": 0.90,
# генератор: доля лимита CPU или отставание от расписания
"gen_cpu_share": 0.90,
"gen_lag_p99_ms": 50.0,
}
def signals(row: dict, limits: dict, pool_cap: int) -> list[str]:
"""Признаки узкого места ступени по агрегатам `row` (см. run.py)."""
found = []
if (row.get("api_cpu_max") or 0) >= THRESHOLDS["app_cpu_share"] * limits[
"api_cpus"
] or (row.get("api_throttled_max") or 0) >= THRESHOLDS["app_throttled_share"]:
found.append("app")
if (row.get("db_cpu_cores") or 0) >= THRESHOLDS["db_cpu_share"] * limits["db_cpus"]:
found.append("db_cpu")
if (row.get("pg_lock_wait_mean") or 0) >= THRESHOLDS["db_lock_wait_mean"]:
found.append("db_lock")
if (
pool_cap
and (row.get("pg_conn_replica_max") or 0) >= THRESHOLDS["pool_share"] * pool_cap
):
found.append("pool")
if (row.get("pg_new_sessions") or 0) >= THRESHOLDS["churn_sessions"]:
found.append("churn")
if (row.get("lb_cpu_cores") or 0) >= THRESHOLDS["lb_cpu_share"] * limits["lb_cpus"]:
found.append("lb")
if (row.get("vm_busy_share") or 0) >= THRESHOLDS["host_busy_share"]:
found.append("host")
if (
(row.get("gen_cpu_cores") or 0)
>= THRESHOLDS["gen_cpu_share"] * limits["gen_cpus"]
or (row.get("lag_p99_ms") or 0) >= THRESHOLDS["gen_lag_p99_ms"]
or (row.get("dropped") or 0) > 0
):
found.append("generator")
return found
# --- поиск R* ---------------------------------------------------------------------------
@dataclasses.dataclass
class Search:
"""Автомат поиска R*: наибольшей интенсивности, на которой ступень
выдерживает SLO.
Сначала фиксированные уровни (сравнение конфигураций на одной
нагрузке), затем лестница `base × factor^i`: начало — первая ступенька
не ниже `start`, подъём до первой нарушившей (если нарушена первая —
спуск до первой прошедшей), затем `bisections` делений интервала
«прошла — нарушила» по среднему геометрическому, с округлением до
целого. R* — наибольшая прошедшая ступень поиска.
"""
fixed: tuple[float, ...]
base: float
factor: float
start: float
bisections: int
cap: float
floor: float = 25.0
results: list[tuple[float, bool, str]] = dataclasses.field(default_factory=list)
def ladder(self, rate: float) -> float:
steps = math.ceil(math.log(rate / self.base, self.factor) - 1e-9)
return round(self.base * self.factor ** max(steps, 0))
def record(self, rate: float, passed: bool, phase: str) -> None:
self.results.append((rate, passed, phase))
def next_rate(self) -> tuple[float, str] | None:
done_fixed = [r for r in self.results if r[2] == "fixed"]
if len(done_fixed) < len(self.fixed):
return self.fixed[len(done_fixed)], "fixed"
search = [r for r in self.results if r[2] != "fixed"]
passed = [rate for rate, ok, _ in search if ok]
failed = [rate for rate, ok, _ in search if not ok]
if not search:
fixed_pass = [rate for rate, ok, _ in done_fixed if ok]
start = max([self.start, *fixed_pass])
return min(self.ladder(start), self.cap), "ladder"
phase = search[-1][2]
if phase == "ladder":
last_rate, last_ok, _ = search[-1]
if last_ok and not failed:
if last_rate >= self.cap:
return None
return min(round(last_rate * self.factor), self.cap), "ladder"
if not last_ok and not passed:
lower = round(last_rate / self.factor)
return (lower, "ladder") if lower >= self.floor else None
# интервал найден: деления
if not passed or not failed:
return None
bisections = sum(1 for r in search if r[2] == "bisect")
if bisections >= self.bisections:
return None
lo = max(passed)
hi = (
min(rate for rate in failed if rate > lo)
if any(r > lo for r in failed)
else None
)
if hi is None:
return None
middle = round(math.sqrt(lo * hi))
if middle <= lo or middle >= hi:
return None
return middle, "bisect"
def r_star(self) -> float | None:
passed = [rate for rate, ok, phase in self.results if ok and phase != "fixed"]
return max(passed) if passed else None
def first_fail(self) -> float | None:
r_star = self.r_star() or 0
failed = [
rate for rate, ok, phase in self.results if not ok and phase != "fixed"
]
above = [rate for rate in failed if rate > r_star]
return min(above) if above else None
# --- самопроверка ---------------------------------------------------------------------
def _selftest() -> None:
# поиск: подъём, нарушение, два деления
search = Search(
fixed=(250, 500), base=100, factor=1.25, start=600, bisections=2, cap=8000
)
capacity = 1000
plan = []
while (step := search.next_rate()) is not None:
rate, phase = step
plan.append((rate, phase))
search.record(rate, rate <= capacity, phase)
assert plan[:2] == [(250, "fixed"), (500, "fixed")], plan
# лестница 100 × 1,25^i: первая ступенька не ниже 600 — 745
assert plan[2] == (745, "ladder"), plan
assert search.r_star() is not None, plan
assert search.r_star() <= capacity, plan
assert search.first_fail() > capacity, plan
assert sum(phase == "bisect" for _, phase in plan) == 2, plan
# первая ступень поиска нарушена — спуск
search = Search(fixed=(), base=100, factor=1.25, start=300, bisections=1, cap=8000)
plan = []
while (step := search.next_rate()) is not None:
plan.append(step)
search.record(step[0], step[0] <= 200, step[1])
assert plan[0] == (305, "ladder"), plan
assert plan[1] == (244, "ladder"), plan
assert search.r_star() <= 200, plan
# окно и время восстановления
reqs = [
Request(
1000 + i * 10, 1000 + i * 10, 1005 + i * 10, "write", 201, "a", f"k{i}", ""
)
for i in range(500)
]
reqs[200] = dataclasses.replace(reqs[200], status=502)
stats = window_stats(reqs, 1000, 6000)
assert stats["errors"] == 1, stats
assert stats["ok"] == 499, stats
assert recovery_seconds(reqs, 1000, 6000, 100) == 3.0
rows = timeline(reqs, 1000, 1000, 6000, {"a": {"a"}})
assert rows[2]["errors"] == 1, rows[:3]
assert rows[0]["ok_a"] == 100, rows[:3]
# сэмплер: приращения, перезапуск контейнера
ticks = [
{"ts": 0.0, "cg": {"abc": [0, 0, 0, 0, 100]}, "vm": [0, 100]},
{"ts": 1.0, "cg": {"abc": [500_000, 10, 1, 0, 200]}, "vm": [50, 200]},
{"ts": 2.0, "cg": {"abc": [100_000, 2, 0, 0, 50]}, "vm": [60, 300]},
{"ts": 3.0, "cg": {"abc": [600_000, 12, 0, 0, 80]}, "vm": [160, 400]},
]
usage = cgroup_usage(ticks, "abc")
assert usage["cpu_cores"] == 0.5, usage
assert vm_busy(ticks) == 0.5333, vm_busy(ticks)
# журнал LB: дубли схлопываются
log = (
"2026-10-14T10:00:00.100000000Z Server api/api-1 is DOWN, reason: x\n"
"2026-10-14T10:00:00.101000000Z [WARNING] (8) : Server api/api-1 is DOWN, reason: x\n"
"2026-10-14T10:00:03.000000000Z Server api/api-1 is UP, reason: y\n"
)
parsed = parse_lb_log(log)
assert [p[2] for p in parsed] == ["is DOWN", "is UP"], parsed
print("analysis selftest: ok")
if __name__ == "__main__":
if sys.argv[1:] == ["--selftest"]:
_selftest()
else:
print("usage: python bench/analysis.py --selftest", file=sys.stderr)
sys.exit(2)
+104
View File
@@ -0,0 +1,104 @@
# Override нагрузочного стенда (bench/run.py): тот же compose.yaml под
# проектом vlad-bench, со своими volume, сетью, именами и лимитами. Пины
# хранилищ и LB, healthcheck хранилищ, valkey.conf, haproxy.cfg и
# миграции — из основного файла. Подстановки — bench/bench.env, а не .env
# рабочего стенда; пароли, образ и BENCH_* передаёт run.py (поля профиля),
# без них стенд не поднимается. Что не меняется между метками —
# bench/AGENTS.md.
#
# Лимиты — в той же форме deploy.resources.limits, что у основного файла:
# cpus / mem_limit рядом с ними compose не принимает. Swap выключен
# (memswap_limit = memory). Портов на хост нет: генератор и сэмплер ходят
# внутри сети vlad-bench-net.
#
# S3, s3-bootstrap и уборщик (лаба 4) запускают только профили uploads и
# reconcile: остальные поднимают сервисы списком и реплики с --no-deps, их
# методика не меняется. Секреты S3 compose требует при разборе файла (:?),
# поэтому run.py генерирует их на каждый прогон любого профиля.
services:
postgres:
container_name: vlad-bench-postgres
# упавший контейнер не поднимается сам: прогон помечается stand_down
restart: "no"
command: ["postgres", "-c", "max_connections=${BENCH_DB_MAX_CONNECTIONS:?run make bench-*}"]
ports: !reset []
deploy:
resources:
limits:
cpus: ${BENCH_DB_CPUS:?run make bench-*}
memory: ${BENCH_DB_MEMORY:?run make bench-*}
memswap_limit: ${BENCH_DB_MEMORY:?run make bench-*}
valkey:
container_name: vlad-bench-valkey
restart: "no"
ports: !reset []
deploy:
resources:
limits:
cpus: ${BENCH_CACHE_CPUS:?run make bench-*}
memory: ${BENCH_CACHE_MEMORY:?run make bench-*}
memswap_limit: ${BENCH_CACHE_MEMORY:?run make bench-*}
# образ, аргументы, healthcheck и GOMEMLIMIT — из основного файла;
# volume — свой у проекта (vlad-bench_s3data), профиль uploads заводит
# новый на каждый прогон
s3:
container_name: vlad-bench-s3
restart: "no"
ports: !reset []
deploy:
resources:
limits:
cpus: ${BENCH_S3_CPUS:?run make bench-*}
memory: ${BENCH_S3_MEMORY:?run make bench-*}
memswap_limit: ${BENCH_S3_MEMORY:?run make bench-*}
migrate:
image: ${BENCH_IMAGE:?run make bench-*}
# только разовые проходы профиля reconcile (docker compose run): лимит CPU
# прохода — BENCH_CLEANER_CPUS вызова
cleaner:
image: ${BENCH_IMAGE:?run make bench-*}
restart: "no"
deploy:
resources:
limits:
cpus: ${BENCH_CLEANER_CPUS:?run make bench-*}
memory: ${BENCH_CLEANER_MEMORY:?run make bench-*}
memswap_limit: ${BENCH_CLEANER_MEMORY:?run make bench-*}
# реплики без container_name: их число — BENCH_API_REPLICAS (--scale)
api:
image: ${BENCH_IMAGE:?run make bench-*}
restart: "no"
# проверка образа — второй процесс Python раз в несколько секунд в квоте
# CPU реплики; готовность и так проверяет LB раз в секунду
healthcheck:
disable: true
environment:
SESSION_TTL_SECONDS: ${BENCH_SESSION_TTL:?run make bench-*}
deploy:
replicas: ${BENCH_API_REPLICAS:?run make bench-*}
resources:
limits:
cpus: ${BENCH_API_CPUS:?run make bench-*}
memory: ${BENCH_API_MEMORY:?run make bench-*}
memswap_limit: ${BENCH_API_MEMORY:?run make bench-*}
haproxy:
container_name: vlad-bench-lb
restart: "no"
ports: !reset []
deploy:
resources:
limits:
cpus: ${BENCH_LB_CPUS:?run make bench-*}
memory: ${BENCH_LB_MEMORY:?run make bench-*}
memswap_limit: ${BENCH_LB_MEMORY:?run make bench-*}
networks:
default:
# генератор и сэмплер подключаются к сети стенда по имени
name: vlad-bench-net
+8
View File
@@ -0,0 +1,8 @@
# Подстановки compose для нагрузочного стенда вместо .env рабочего стенда
# (docker compose --env-file bench/bench.env). Только несекретные имена:
# пароли и ключи S3 генерирует bench/run.py на каждый прогон, лимиты, образ,
# число реплик и срок сессии приходят из профиля (BENCH_*).
POSTGRES_USER=bench
POSTGRES_DB=bench
LOG_LEVEL=INFO
S3_BUCKET=bench
+1056
View File
File diff suppressed because it is too large Load Diff
+248
View File
@@ -0,0 +1,248 @@
"""Сравнение двух меток серий трека 1: «до» и «после» одного изменения.
uv run python bench/compare.py --before scaling-ab-before \\
--after scaling-ab-after [--aa scaling-ab-aa]
→ evidence/compare/<до>__<после>.md
По общим конфигурациям: R* (медиана, min–max, Δ), задержки на
фиксированных уровнях, CPU на запрос реплик и PostgreSQL, новые сессии
PostgreSQL и соединения на ступени R* и на первой нарушившей. С `--aa`
(метка того же кода, что «до») — уровень шума: наибольшее |Δ медианы R*|
между «до» и A/A по общим конфигурациям.
Изменение R* — эффект, только если: разбросы повторов не пересекаются,
|Δ медианы| больше шума A/A и не меньше двух ступеней сетки поиска
(R* после / R* до ≥ √factor ≈ 1,118 при factor 1,25: шаг сетки после двух
делений — factor^¼, одна ступень — в пределах разрешения поиска). Иначе
— «шум» или «в пределах разрешения».
Методика меток должна совпадать: профиль (кроме списка ячеек серии ab),
лимиты, образы хранилищ, хост. Различаться может только код приложения
(`src_sha256`). Иначе — отказ.
"""
import argparse
import csv
import json
import math
import statistics
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
SCALING = ROOT / "evidence" / "scaling"
OUT = ROOT / "evidence" / "compare"
def read_csv(path: Path) -> list[dict]:
with path.open(encoding="utf-8") as handle:
return list(csv.DictReader(handle))
def num(value) -> float | None:
try:
return float(value)
except (TypeError, ValueError):
return None
def load(label: str) -> dict:
folder = SCALING / label
if not (folder / "meta.json").exists():
raise SystemExit(f"no label {label} in evidence/scaling")
return {
"label": label,
"meta": json.loads((folder / "meta.json").read_text(encoding="utf-8")),
"searches": read_csv(folder / "searches.csv"),
"runs": read_csv(folder / "runs.csv"),
}
def methodology(meta: dict) -> dict:
"""Что должно совпасть у сравниваемых меток."""
profile = dict(meta["profile"])
profile.pop("configs", None)
stand = meta.get("stand") or {}
return {
"profile": profile,
"series_name": profile.get("name"),
"configs": meta.get("configs"),
"cpu_model": meta["host"].get("cpu_model"),
"vm_cpus": meta["docker"].get("NCPU"),
"postgres_image": (stand.get("postgres") or {}).get("image"),
}
def check_methodology(before: dict, after: dict) -> list[str]:
a, b = methodology(before["meta"]), methodology(after["meta"])
problems = []
if a["profile"] != b["profile"]:
problems.append("profile differs")
if a["cpu_model"] != b["cpu_model"] or a["vm_cpus"] != b["vm_cpus"]:
problems.append("host or docker VM differs")
common = set(a["configs"] or {}) & set(b["configs"] or {})
for config in sorted(common):
if a["configs"][config] != b["configs"][config]:
problems.append(f"limits of {config} differ")
return problems
def stats_by_config(data: dict) -> dict:
out = {}
for row in data["searches"]:
entry = out.setdefault(row["config"], {"r": [], "cells": []})
if num(row["r_star"]) is not None:
entry["r"].append(num(row["r_star"]))
entry["cells"].append(row)
for entry in out.values():
values = entry["r"] or [0.0]
entry["median"] = statistics.median(values)
entry["min"], entry["max"] = min(values), max(values)
return out
def step_metric(data: dict, config: str, which: str, key: str) -> float | None:
"""Медиана поля на ступени R* (`star`) или первой нарушившей (`fail`)."""
values = []
for search in data["searches"]:
if search["config"] != config:
continue
rate = num(search["r_star"] if which == "star" else search["first_fail"])
row = next(
(
r
for r in data["runs"]
if r["cell"] == search["cell"]
and r["phase"] != "fixed"
and num(r["rate"]) == rate
),
None,
)
if row is not None and num(row.get(key)) is not None:
values.append(num(row[key]))
return statistics.median(values) if values else None
def fixed_metric(data: dict, config: str, rate: float, key: str) -> float | None:
values = [
num(r[key])
for r in data["runs"]
if r["config"] == config
and r["phase"] == "fixed"
and num(r["rate"]) == rate
and num(r.get(key)) is not None
]
return statistics.median(values) if values else None
def fmt(value: float | None, digits: int = 1) -> str:
if value is None:
return "—"
return f"{round(value, digits):g}"
def main() -> None:
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
parser.add_argument("--before", required=True)
parser.add_argument("--after", required=True)
parser.add_argument("--aa")
args = parser.parse_args()
before, after = load(args.before), load(args.after)
aa = load(args.aa) if args.aa else None
problems = check_methodology(before, after)
if aa:
problems += [f"A/A: {p}" for p in check_methodology(before, aa)]
if aa["meta"]["code"]["src_sha256"] != before["meta"]["code"]["src_sha256"]:
problems.append("A/A label has different code than BEFORE (src_sha256)")
if problems:
raise SystemExit("labels are not comparable: " + "; ".join(problems))
factor = before["meta"]["profile"]["ladder_factor"]
two_steps = math.sqrt(factor)
sb, sa = stats_by_config(before), stats_by_config(after)
common = [c for c in before["meta"]["profile"]["configs"] if c in sb and c in sa]
noise = None
if aa:
saa = stats_by_config(aa)
deltas = [
abs(saa[c]["median"] - sb[c]["median"]) / sb[c]["median"]
for c in common
if c in saa and sb[c]["median"]
]
noise = max(deltas) if deltas else None
same_code = (
before["meta"]["code"]["src_sha256"] == after["meta"]["code"]["src_sha256"]
)
lines = [
f"# Сравнение: {args.before} → {args.after}",
"",
f"- Код «до»: src_sha256 `{before['meta']['code']['src_sha256'][:16]}`; «после»: "
f"`{after['meta']['code']['src_sha256'][:16]}`"
+ (" — **код одинаковый: это A/A, а не изменение**" if same_code else "")
+ ".",
f"- Пул приложения «до»: {before['meta']['image'].get('app_defaults')}; «после»: "
f"{after['meta']['image'].get('app_defaults')}.",
f"- Шум A/A ({args.aa}): "
+ (
f"наибольшее |Δ медианы R*| = {noise * 100:.1f} %"
if noise is not None
else "не задан"
)
+ ".",
f"- Порог эффекта: разбросы не пересекаются, |Δ| > шума и R* после / до ≥ "
f"{two_steps:.3f} (две ступени сетки поиска; одна ступень — {factor**0.25:.3f}).",
"",
"| Конфигурация | R* до, медиана (min–max) | R* после | Δ | Вывод | p95 до / после на фиксированных, мс | API мкс/запрос до / после | PostgreSQL мкс/запрос на R* до / после | Новых сессий за окно на первой нарушившей до / после | Соединений на R* до / после |",
"|---|---|---|---|---|---|---|---|---|---|",
]
rates = before["meta"]["profile"]["fixed_rates"]
for config in common:
b, a = sb[config], sa[config]
delta = (a["median"] - b["median"]) / b["median"] if b["median"] else None
overlap = not (a["min"] > b["max"] or a["max"] < b["min"])
ratio = a["median"] / b["median"] if b["median"] else None
if delta is None:
verdict = "нет данных"
elif overlap:
verdict = "шум (разбросы пересекаются)"
elif noise is not None and abs(delta) <= noise:
verdict = "шум (в пределах A/A)"
elif ratio is not None and (ratio >= two_steps or ratio <= 1 / two_steps):
verdict = "эффект"
else:
verdict = "в пределах разрешения поиска"
p95 = " ; ".join(
f"{r:g}: {fmt(fixed_metric(before, config, r, 'p95_ms'))} / {fmt(fixed_metric(after, config, r, 'p95_ms'))}"
for r in rates
)
api_us = (
f"{fmt(fixed_metric(before, config, rates[-1], 'api_cpu_us_per_req'))} / "
f"{fmt(fixed_metric(after, config, rates[-1], 'api_cpu_us_per_req'))}"
)
db_us = (
f"{fmt(step_metric(before, config, 'star', 'db_cpu_us_per_req'))} / "
f"{fmt(step_metric(after, config, 'star', 'db_cpu_us_per_req'))}"
)
sessions = (
f"{fmt(step_metric(before, config, 'fail', 'pg_new_sessions'), 0)} / "
f"{fmt(step_metric(after, config, 'fail', 'pg_new_sessions'), 0)}"
)
conns = (
f"{fmt(step_metric(before, config, 'star', 'pg_conn_max'), 0)} / "
f"{fmt(step_metric(after, config, 'star', 'pg_conn_max'), 0)}"
)
lines.append(
f"| {config} | {b['median']:g} ({b['min']:g}–{b['max']:g}) | "
f"{a['median']:g} ({a['min']:g}–{a['max']:g}) | "
f"{fmt(delta * 100 if delta is not None else None)} % | {verdict} | {p95} | "
f"{api_us} | {db_us} | {sessions} | {conns} |"
)
OUT.mkdir(parents=True, exist_ok=True)
path = OUT / f"{args.before}__{args.after}.md"
path.write_text("\n".join(lines) + "\n", encoding="utf-8")
print("\n".join(lines))
print(f"\nwritten: {path.relative_to(ROOT)}")
if __name__ == "__main__":
main()
+118
View File
@@ -0,0 +1,118 @@
"""Загрузчик объектов профиля reconcile: PUT в S3 стенда мимо API.
Работает только в контейнере `vlad-bench-fill` на образе стенда: там есть
botocore (зависимость aiobotocore образа); `src` не импортируется. Модель
набора (номера, ключи, содержимое) — `bench/reconcile.py`, его копирует
рядом `bench/run.py` (`docker cp`). Ключи пользователя API — окружение
контейнера (`S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`: `docker run -e
<имя>` без значения в argv); в вывод они не попадают.
Объекты — номера диапазона [--start, --end), у которых по модели есть
объект; несколько процессов по нескольку потоков, у каждого процесса свой
клиент. Вывод — одна строка JSON `{"objects", "put_per_s", "seconds"}`;
ошибка любого PUT — код 1.
"""
import argparse
import json
import os
import sys
import time
from concurrent.futures import ThreadPoolExecutor
from multiprocessing import Pool
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parent))
import reconcile # noqa: E402
KEY_ENV = ("S3_ACCESS_KEY_ID", "S3_SECRET_ACCESS_KEY")
def client(endpoint: str, threads: int):
import botocore.session # noqa: PLC0415 - только в контейнере стенда
from botocore.config import Config # noqa: PLC0415
return botocore.session.get_session().create_client(
"s3",
endpoint_url=endpoint,
region_name="us-east-1",
aws_access_key_id=os.environ[KEY_ENV[0]],
aws_secret_access_key=os.environ[KEY_ENV[1]],
config=Config(
s3={"addressing_style": "path"},
retries={"total_max_attempts": 3},
max_pool_connections=threads,
),
)
def put_chunk(job: tuple[dict, list[int]]) -> int:
"""Один процесс: свой клиент, потоки по номерам; число записанных."""
args, indices = job
s3 = client(args["endpoint"], args["threads"])
def put(index: int) -> None:
attachment_id = reconcile.object_id(args["seed"], index)
s3.put_object(
Bucket=args["bucket"],
Key=reconcile.object_key(args["namespace"], attachment_id),
Body=reconcile.content(args["seed"], index, args["size"]),
ContentType=reconcile.CONTENT_TYPE,
)
with ThreadPoolExecutor(max_workers=args["threads"]) as pool:
for _ in pool.map(put, indices):
pass
return len(indices)
def main(argv: list[str]) -> int:
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
parser.add_argument("--endpoint", required=True)
parser.add_argument("--bucket", required=True)
parser.add_argument("--namespace", required=True)
parser.add_argument("--seed", type=int, required=True)
parser.add_argument("--start", type=int, required=True)
parser.add_argument("--end", type=int, required=True)
parser.add_argument("--size", type=int, required=True)
parser.add_argument("--force", choices=(reconcile.FORCE_OK,))
parser.add_argument("--processes", type=int, default=3)
parser.add_argument("--threads", type=int, default=16)
args = parser.parse_args(argv)
if not Path("/.dockerenv").exists():
print(json.dumps({"error": "run only in the bench container"}), flush=True)
return 2
if any(not os.environ.get(name) for name in KEY_ENV):
print(json.dumps({"error": f"{' and '.join(KEY_ENV)} required"}), flush=True)
return 2
indices = reconcile.object_indices(args.start, args.end, args.force)
parts = [indices[i :: args.processes] for i in range(args.processes)]
shared = {
key: getattr(args, key)
for key in ("endpoint", "bucket", "namespace", "seed", "size", "threads")
}
started = time.monotonic()
try:
with Pool(args.processes) as pool:
done = sum(pool.map(put_chunk, [(shared, p) for p in parts if p]))
except Exception as exc: # noqa: BLE001
# без текста исключения botocore: в нём адрес и заголовки запроса
print(json.dumps({"error": f"put failed ({type(exc).__name__})"}), flush=True)
return 1
seconds = time.monotonic() - started
print(
json.dumps(
{
"objects": done,
"put_per_s": round(done / seconds, 1) if seconds else 0.0,
"seconds": round(seconds, 2),
},
),
flush=True,
)
return 0 if done == len(indices) else 1
if __name__ == "__main__":
sys.exit(main(sys.argv[1:]))
+1250
View File
File diff suppressed because it is too large Load Diff
+412
View File
@@ -0,0 +1,412 @@
"""Графики серий трека 1: SVG на стандартной библиотеке.
uv run python bench/plots.py --out scaling scaling-a scaling-b scaling-db
→ evidence/plots/<out>/: rstar-by-config.svg, rstar-by-replicas.svg,
summary.md (R*, эффективность, точка насыщения)
`run.py` после серии зовёт `render_label()`: в каталоге метки —
`p95-by-rate.svg` (p95 от поданной интенсивности по ячейкам) и
`cpu-by-component.svg` (CPU компонентов на ступени R*). Числа берутся из
`searches.csv` и `runs.csv` меток как есть.
"""
import argparse
import csv
import html
import math
import re
import statistics
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
SCALING = ROOT / "evidence" / "scaling"
PLOTS = ROOT / "evidence" / "plots"
COLORS = (
"#2f6fbf",
"#d0752a",
"#3c9a5f",
"#b8404a",
"#7a5cb5",
"#8c6d3f",
"#c25f9c",
"#5f8f9c",
)
COMPONENTS = (
("api_cpu_cores", "API (сумма реплик)", "#2f6fbf"),
("db_cpu_cores", "PostgreSQL", "#b8404a"),
("lb_cpu_cores", "HAProxy", "#3c9a5f"),
("cache_cpu_cores", "Valkey", "#7a5cb5"),
("gen_cpu_cores", "генератор", "#8c6d3f"),
)
CONFIG_RE = re.compile(r"(\d+)x([\d.]+)(?:-pg([\d.]+))?")
def read_csv(path: Path) -> list[dict]:
if not path.exists():
return []
with path.open(encoding="utf-8") as handle:
return list(csv.DictReader(handle))
def num(value) -> float | None:
try:
return float(value)
except (TypeError, ValueError):
return None
def nice_step(raw: float) -> float:
"""Круглый шаг сетки не меньше raw: 1, 2, 2,5, 5 или 10 × 10^k."""
magnitude = 10 ** math.floor(math.log10(raw))
return next(m * magnitude for m in (1, 2, 2.5, 5, 10) if m * magnitude >= raw)
def nice_ticks(top: float, count: int = 6) -> list[float]:
step = nice_step(top / count) if top > 0 else 1.0
return [round(step * i, 6) for i in range(int(top / step) + 1)]
class Svg:
"""Поле графика с осями: x и y в единицах данных."""
def __init__(self, width: int, height: int, title: str) -> None:
self.width, self.height = width, height
# справа — место под легенду: имена меток длинные
self.left, self.right, self.top, self.bottom = 70, 300, 40, 50
self.parts = [
f'<svg xmlns="http://www.w3.org/2000/svg" width="{width}" height="{height}" '
f'viewBox="0 0 {width} {height}" font-family="sans-serif" font-size="12">',
f'<rect width="{width}" height="{height}" fill="white"/>',
f'<text x="{width / 2}" y="22" text-anchor="middle" font-size="14">'
f"{html.escape(title)}</text>",
]
self.x0 = self.x1 = self.y0 = self.y1 = 0.0
self.ystep = 1.0
self.legend_row = 0
def scale(self, x0: float, x1: float, y0: float, y1: float) -> None:
"""Ось y — от y0 до круглого значения не меньше y1 (шаг сетки
1, 2, 2,5 или 5 × 10^k, пять–шесть делений)."""
self.ystep = nice_step(max(y1 - y0, 1e-9) / 5)
top = y0 + self.ystep * math.ceil(max(y1 - y0, 1e-9) / self.ystep)
self.x0, self.x1, self.y0, self.y1 = (
x0,
x1 if x1 > x0 else x0 + 1,
y0,
top,
)
def px(self, x: float) -> float:
span = self.width - self.left - self.right
return self.left + (x - self.x0) / (self.x1 - self.x0) * span
def py(self, y: float) -> float:
span = self.height - self.top - self.bottom
return self.height - self.bottom - (y - self.y0) / (self.y1 - self.y0) * span
def axes(self, xlabel: str, ylabel: str, xticks: list[tuple[float, str]]) -> None:
bottom, left = self.height - self.bottom, self.left
right = self.width - self.right
self.parts.append(
f'<line x1="{left}" y1="{bottom}" x2="{right}" y2="{bottom}" stroke="#333"/>'
)
self.parts.append(
f'<line x1="{left}" y1="{self.top}" x2="{left}" y2="{bottom}" stroke="#333"/>'
)
for x, text in xticks:
self.parts.append(
f'<text x="{self.px(x):.1f}" y="{bottom + 16}" text-anchor="middle">{html.escape(text)}</text>'
)
for index in range(round((self.y1 - self.y0) / self.ystep) + 1):
value = round(self.y0 + self.ystep * index, 6)
y = self.py(value)
self.parts.append(
f'<line x1="{left}" y1="{y:.1f}" x2="{right}" y2="{y:.1f}" stroke="#eee"/>'
)
self.parts.append(
f'<text x="{left - 6}" y="{y + 4:.1f}" text-anchor="end">{value:g}</text>'
)
self.parts.append(
f'<text x="{(left + right) / 2}" y="{self.height - 12}" text-anchor="middle">{html.escape(xlabel)}</text>'
)
self.parts.append(
f'<text x="16" y="{(self.top + bottom) / 2}" text-anchor="middle" '
f'transform="rotate(-90 16 {(self.top + bottom) / 2})">{html.escape(ylabel)}</text>'
)
def line(
self, points: list[tuple[float, float]], color: str, dash: str = ""
) -> None:
if not points:
return
path = " ".join(f"{self.px(x):.1f},{self.py(y):.1f}" for x, y in points)
extra = f' stroke-dasharray="{dash}"' if dash else ""
self.parts.append(
f'<polyline points="{path}" fill="none" stroke="{color}" stroke-width="2"{extra}/>'
)
def dot(self, x: float, y: float, color: str, hollow: bool = False) -> None:
fill = "white" if hollow else color
self.parts.append(
f'<circle cx="{self.px(x):.1f}" cy="{self.py(y):.1f}" r="3.5" fill="{fill}" stroke="{color}"/>'
)
def whisker(self, x: float, lo: float, hi: float, color: str) -> None:
self.parts.append(
f'<line x1="{self.px(x):.1f}" y1="{self.py(lo):.1f}" x2="{self.px(x):.1f}" '
f'y2="{self.py(hi):.1f}" stroke="{color}" stroke-width="1.5"/>'
)
def bar(self, x: float, width: float, y0: float, y1: float, color: str) -> None:
left = self.px(x - width / 2)
right = self.px(x + width / 2)
self.parts.append(
f'<rect x="{left:.1f}" y="{self.py(y1):.1f}" width="{right - left:.1f}" '
f'height="{self.py(y0) - self.py(y1):.1f}" fill="{color}" opacity="0.85"/>'
)
def legend(self, text: str, color: str, dash: str = "") -> None:
x = self.width - self.right + 14
y = self.top + 14 + 18 * self.legend_row
extra = f' stroke-dasharray="{dash}"' if dash else ""
self.parts.append(
f'<line x1="{x}" y1="{y - 4}" x2="{x + 18}" y2="{y - 4}" stroke="{color}" stroke-width="3"{extra}/>'
)
self.parts.append(f'<text x="{x + 24}" y="{y}">{html.escape(text)}</text>')
self.legend_row += 1
def save(self, path: Path) -> None:
path.write_text("\n".join([*self.parts, "</svg>"]) + "\n", encoding="utf-8")
def render_label(folder: Path) -> None:
"""Графики одной метки серии: p95 от интенсивности, CPU на ступени R*."""
runs = read_csv(folder / "runs.csv")
searches = read_csv(folder / "searches.csv")
if not runs:
return
configs = list(dict.fromkeys(row["config"] for row in runs))
rates = [num(r["rate"]) or 0 for r in runs]
p95s = [min(num(r["p95_ms"]) or 0, 1000) for r in runs]
svg = Svg(1000, 440, f"p95 успешных от поданной интенсивности: {folder.name}")
svg.scale(0, max(rates) * 1.05, 0, max(max(p95s) * 1.1, 250))
ticks = [(x, f"{x:g}") for x in nice_ticks(max(rates))]
svg.axes("запросов в секунду (по расписанию)", "p95, мс (≤ 1000)", ticks)
svg.line([(0, 200), (max(rates) * 1.05, 200)], "#999", "4 4")
for index, config in enumerate(configs):
color = COLORS[index % len(COLORS)]
cells = sorted(
{(r["cell"], r["repeat"]) for r in runs if r["config"] == config}
)
for cell, _ in cells:
points = sorted(
(num(r["rate"]) or 0, min(num(r["p95_ms"]) or 1000, 1000))
for r in runs
if r["cell"] == cell
)
svg.line(points, color)
for r in runs:
if r["cell"] == cell:
svg.dot(
num(r["rate"]) or 0,
min(num(r["p95_ms"]) or 1000, 1000),
color,
hollow=r["slo_pass"] != "True",
)
svg.legend(config, color)
svg.legend("SLO 200 мс", "#999", "4 4")
svg.save(folder / "p95-by-rate.svg")
# CPU компонентов на ступени R* каждой ячейки (медиана по повторам)
stacks = []
for config in configs:
values = {key: [] for key, _, _ in COMPONENTS}
for search in [s for s in searches if s["config"] == config]:
star = num(search["r_star"])
row = next(
(
r
for r in runs
if r["cell"] == search["cell"]
and r["phase"] != "fixed"
and num(r["rate"]) == star
),
None,
)
if row is None:
continue
for key, _, _ in COMPONENTS:
if num(row.get(key)) is not None:
values[key].append(num(row[key]))
stacks.append(
(config, {k: statistics.median(v) if v else 0 for k, v in values.items()})
)
if not stacks:
return
top = max(sum(s.values()) for _, s in stacks) or 1
svg = Svg(
1000, 440, f"CPU компонентов на ступени R* (медиана), ядер: {folder.name}"
)
svg.scale(0, len(stacks) + 1, 0, top * 1.15)
svg.axes("конфигурация", "ядер", [(i + 1, c) for i, (c, _) in enumerate(stacks)])
for index, (_, stack) in enumerate(stacks):
base = 0.0
for key, _, color in COMPONENTS:
svg.bar(index + 1, 0.5, base, base + stack[key], color)
base += stack[key]
for _, name, color in COMPONENTS:
svg.legend(name, color)
svg.save(folder / "cpu-by-component.svg")
def label_rows(label: str) -> list[dict]:
rows = read_csv(SCALING / label / "searches.csv")
for row in rows:
row["label"] = label
return rows
def summarize(rows: list[dict]) -> dict[tuple[str, str], dict]:
"""(метка, конфигурация) → медиана, min, max R*, реплик, CPU."""
out: dict[tuple[str, str], dict] = {}
for row in rows:
key = (row["label"], row["config"])
entry = out.setdefault(
key,
{
"values": [],
"replicas": int(row["replicas"]),
"api_cpus": num(row["api_cpus"]),
"db_cpus": num(row["db_cpus"]),
"signals": {},
},
)
if num(row["r_star"]) is not None:
entry["values"].append(num(row["r_star"]))
for signal in (row["signals_at_fail"] or "").split(";"):
if signal:
entry["signals"][signal] = entry["signals"].get(signal, 0) + 1
for entry in out.values():
values = entry["values"] or [0]
entry["median"] = statistics.median(values)
entry["min"], entry["max"] = min(values), max(values)
return out
def saturation(points: list[tuple[int, float]]) -> int | None:
"""Наименьшее k, после которого следующая реплика даёт < +10 % R*."""
points = sorted(points)
for (k, r), (_, r_next) in zip(points, points[1:], strict=False):
if r_next < 1.10 * r:
return k
return None
def main() -> None:
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
parser.add_argument("--out", required=True)
parser.add_argument("labels", nargs="+")
args = parser.parse_args()
if not re.fullmatch(r"[A-Za-z0-9._-]{1,48}", args.out):
raise SystemExit("--out must be a simple name")
rows = [row for label in args.labels for row in label_rows(label)]
if not rows:
raise SystemExit("no searches.csv in the given labels")
stats = summarize(rows)
folder = PLOTS / args.out
folder.mkdir(parents=True, exist_ok=True)
# R* по конфигурациям всех меток: медиана и min–max
items = list(stats.items())
top = max(entry["max"] for _, entry in items) or 1
svg = Svg(
max(1000, 90 * len(items) + 380), 460, "R* по конфигурациям: медиана и min–max"
)
svg.scale(0, len(items) + 1, 0, top * 1.15)
svg.axes(
"метка / конфигурация",
"R*, запросов/с",
[(i + 1, cfg) for i, ((_, cfg), _) in enumerate(items)],
)
labels = list(dict.fromkeys(label for (label, _), _ in items))
for index, ((label, _), entry) in enumerate(items):
color = COLORS[labels.index(label) % len(COLORS)]
svg.bar(index + 1, 0.55, 0, entry["median"], color)
svg.whisker(index + 1, entry["min"], entry["max"], "#222")
for label in labels:
svg.legend(label, COLORS[labels.index(label) % len(COLORS)])
svg.save(folder / "rstar-by-config.svg")
# R* от числа реплик по 1 CPU — по меткам, где такие конфигурации есть
svg = Svg(
860, 440, "R* от числа реплик (по 1 CPU): медиана, min–max, линейный рост"
)
curves = {}
for (label, config), entry in items:
match = CONFIG_RE.fullmatch(config)
if match and float(match.group(2)) == 1.0:
curves.setdefault((label, match.group(3) or "2"), []).append(
(entry["replicas"], entry)
)
if curves:
max_k = max(k for points in curves.values() for k, _ in points)
# линия линейного роста от 1 × 1 тоже должна поместиться
ideal = [
e["median"] * max_k
for points in curves.values()
for k, e in points
if k == 1
]
svg.scale(0, max_k + 0.5, 0, max([top, *ideal]) * 1.05)
svg.axes("реплик", "R*, запросов/с", [(k, str(k)) for k in range(1, max_k + 1)])
for index, ((label, pg), points) in enumerate(sorted(curves.items())):
color = COLORS[index % len(COLORS)]
points.sort(key=lambda p: p[0])
svg.line([(k, e["median"]) for k, e in points], color)
for k, entry in points:
svg.dot(k, entry["median"], color)
svg.whisker(k, entry["min"], entry["max"], color)
one = next((e["median"] for k, e in points if k == 1), None)
if one:
svg.line([(1, one), (max_k, one * max_k)], color, "3 4")
svg.legend(f"{label}, PostgreSQL {pg} CPU", color)
svg.save(folder / "rstar-by-replicas.svg")
lines = [
f"# Графики трека 1: {args.out}",
"",
f"Метки: {', '.join(args.labels)}. Числа — `searches.csv` меток.",
"",
"| Метка | Конфигурация | Реплик | CPU реплики | PostgreSQL CPU | R* медиана | min–max | Эффективность к 1 × 1 метки | Признаки на первой нарушившей |",
"|---|---|---|---|---|---|---|---|---|",
]
for (label, config), entry in items:
one = stats.get((label, "1x1"))
eff = (
f"{entry['median'] / (entry['replicas'] * one['median']):.2f}"
if one and one["median"] and config != "1x1"
else "—"
)
signals = (
", ".join(f"{k} ×{v}" for k, v in sorted(entry["signals"].items())) or "—"
)
lines.append(
f"| {label} | {config} | {entry['replicas']} | {entry['api_cpus']:g} | "
f"{entry['db_cpus']:g} | {entry['median']:g} | {entry['min']:g}–{entry['max']:g} | "
f"{eff} | {signals} |"
)
lines += ["", "## Точка насыщения", ""]
for (label, pg), points in sorted(curves.items()):
k = saturation([(k, e["median"]) for k, e in points])
verdict = (
f"после {k} реплик(и) следующая даёт меньше +10 % R*"
if k
else "в пределах снятых конфигураций рост не останавливается (≥ +10 % на реплику)"
)
lines.append(f"- {label}, PostgreSQL {pg} CPU: {verdict}.")
(folder / "summary.md").write_text("\n".join(lines) + "\n", encoding="utf-8")
print(f"written: {folder.relative_to(ROOT)}")
if __name__ == "__main__":
main()
+950
View File
@@ -0,0 +1,950 @@
"""Профиль reconcile: набор, план, разбор и сводка без docker. Только stdlib.
Оркестрирует проходы `run.py` (профили `reconcile`, `reconcile-quick`);
здесь — чистые функции: модель набора (id, содержимое и класс объекта по
номеру и зерну), строки CSV метаданных для `COPY`, план проходов кругами,
разбор итоговой строки уборщика `reconcile pass finished …`, сверка
найденного с моделью, окна фоновой нагрузки, строки `passes.csv` и
`windows.csv`, вердикты H1–H5 (гипотезы записаны в `REPORT.md` до
замеров) и `summary.md`. Самопроверка — `uv run python
bench/reconcile.py --selftest`.
Модуль импортирует и загрузчик `bench/fill_objects.py` в контейнере на
образе стенда: на верхнем уровне — только stdlib.
"""
import hashlib
import random
import re
import statistics
import sys
import uuid
from collections.abc import Iterable
from dataclasses import dataclass
from datetime import UTC, datetime
# класс объекта i — по i mod PERIOD: 0 — объект без строки, 1 — строка
# `ready` без объекта, 2 — размер в строке на байт больше, 3 — зависшая
# загрузка `pending` с объектом; по 0,25 % набора на класс
PERIOD = 400
CLASSES = ("orphan_object", "missing_object", "size_mismatch", "stale_pending")
# найденное уборщиком (src/services/reconcile.py, KINDS)
KINDS = (
"orphan_object",
"stale_pending",
"missing_object",
"size_mismatch",
"checksum_mismatch",
"restored_object",
"foreign_object",
)
# принудительный класс диапазона: все согласованы или все — строки без
# объекта (набор отказа по пределу)
FORCE_OK = "ok"
FORCE_MISSING = "missing_object"
CONTENT_TYPE = "image/png"
KIB = 1024
MIB = 2**20
COPY_COLUMNS = (
"id",
"chat_id",
"owner_id",
"filename",
"content_type",
"size_bytes",
"sha256",
"object_key",
"status",
"created_at",
"updated_at",
)
# ячейки: стратегия, глубина, CPU уборщика (stand — лимит рабочего стенда
# 0,25, fast — управляемый опыт 1 CPU), предел скорости (default — из
# настроек RECONCILE_RATE, иначе число), фоновая нагрузка, --apply
CELLS: dict[str, dict] = {
"batch": {"strategy": "batch", "deep": False, "cpu": "stand", "rate": 0},
"head": {"strategy": "head", "deep": False, "cpu": "stand", "rate": 0},
"deep": {"strategy": "batch", "deep": True, "cpu": "stand", "rate": 0},
"deep-fast": {"strategy": "batch", "deep": True, "cpu": "fast", "rate": 0},
"load-stand": {"strategy": "batch", "cpu": "stand", "rate": "default", "load": 1},
"load-unlimited": {"strategy": "batch", "cpu": "stand", "rate": 0, "load": 1},
"load-fast": {"strategy": "batch", "cpu": "fast", "rate": 0, "load": 1},
"load-fast-limited": {
"strategy": "batch",
"cpu": "fast",
"rate": "default",
"load": 1,
},
# отказ по пределу: --apply --max-changes 100 при 1 000 кандидатов
"refuse": {"strategy": "batch", "cpu": "stand", "rate": 0, "apply": 1},
}
LOAD_CELLS = ("load-stand", "load-unlimited", "load-fast", "load-fast-limited")
LIMITED_LOAD = ("load-stand", "load-fast-limited")
WINDOWS = ("before", "pass", "after")
LOAD_KINDS = ("download", "write", "read")
FINISHED = "reconcile pass finished"
S3_OPERATIONS = ("list", "head", "get", "delete")
PHASES = ("list", "rows", "stale", "recheck", "act")
ACTIONS = ("cleared_lost", "deleted_object", "marked_lost", "removed_pending")
# пороги гипотез — до замеров (REPORT.md, «Трек 2: гипотезы»)
H1_SPREAD = 0.30
H1_BYTES_PER_KEY = 300
H2_TIME_RATIO = 5
H2_RSS_GROWTH_MIB = 5
H3_DEEP_RATIO = 5
H3_FAST_RATIO = 1.5
H4_THRESHOLD = 1.5
H4_RATE_SHARE = 0.9
H5_SPREAD = 0.20
PASS_COLUMNS = (
"pass",
"stage",
"cell",
"repeat",
"order",
"n",
"size",
"strategy",
"deep",
"apply",
"rate",
"cleaner_cpus",
"nano_cpus",
"exit_code",
"refused",
"listed_objects",
"checked_rows",
*(f"found_{kind}" for kind in KINDS),
*(f"fixed_{action}" for action in ACTIONS),
"remaining",
*(f"s3_{op}" for op in S3_OPERATIONS),
"listed_keys",
"read_bytes",
"db_queries",
*(f"phase_{name}_ms" for name in PHASES),
"cpu_ms",
"maxrss_kib",
"took_ms",
"ms_per_1k",
"cpu_share",
"touched_per_s",
"s3_cpu_cores",
"db_cpu_cores",
"api_cpu_cores",
"model_ok",
"flags",
)
WINDOW_COLUMNS = (
"pass",
"cell",
"repeat",
"window",
"kind",
"seconds",
"requests",
"ok",
"errors",
"errors_5xx",
"p50_ms",
"p95_ms",
"p99_ms",
"ratio_p95",
)
# --- набор ---------------------------------------------------------------------
def object_class(index: int, force: str | None = None) -> str | None:
"""Класс расхождения объекта `index`; `None` — согласован."""
if force == FORCE_OK:
return None
if force is not None:
return force
slot = index % PERIOD
return CLASSES[slot] if slot < len(CLASSES) else None
def object_id(seed: int, index: int) -> str:
"""UUID v4 из SHA-256 строки `<зерно>:<номер>` — как id сервера."""
digest = hashlib.sha256(f"{seed}:{index}".encode()).digest()
return str(uuid.UUID(bytes=digest[:16], version=4))
def content(seed: int, index: int, size: int) -> bytes:
"""Повторённый SHA-256 строки `<зерно>:<номер>:c` нужного размера."""
block = hashlib.sha256(f"{seed}:{index}:c".encode()).digest()
return (block * (size // len(block) + 1))[:size]
def object_key(namespace: str, attachment_id: str) -> str:
"""Ключ оригинала — как `AttachmentObjects.key_of` (src/storage/objects.py)."""
return f"{namespace}/attachments/{attachment_id}/original"
def has_object(kind: str | None) -> bool:
return kind != "missing_object"
def has_row(kind: str | None) -> bool:
return kind != "orphan_object"
def object_indices(start: int, end: int, force: str | None = None) -> list[int]:
"""Номера диапазона, у которых есть объект в bucket."""
return [i for i in range(start, end) if has_object(object_class(i, force))]
def rows_csv(
*,
seed: int,
start: int,
end: int,
size: int,
namespace: str,
chat_id: str,
owner_id: str,
created_at: str,
force: str | None = None,
) -> str:
"""Строки CSV `COPY attachments (COPY_COLUMNS)` диапазона: `ready` — у
согласованных, строк без объекта и другого размера (`size_bytes` на
байт больше), `pending` — у зависшей загрузки; у объекта без строки
строки нет. SHA-256 — от того же содержимого, что положит загрузчик."""
lines = []
for index in range(start, end):
kind = object_class(index, force)
if not has_row(kind):
continue
attachment_id = object_id(seed, index)
digest = hashlib.sha256(content(seed, index, size)).hexdigest()
size_bytes = size + 1 if kind == "size_mismatch" else size
status = "pending" if kind == "stale_pending" else "ready"
lines.append(
",".join(
(
attachment_id,
chat_id,
owner_id,
f"bench-{index}.png",
CONTENT_TYPE,
str(size_bytes),
f"\\x{digest}",
object_key(namespace, attachment_id),
status,
created_at,
created_at,
),
),
)
return "\n".join(lines) + ("\n" if lines else "")
def class_count(n: int, slot: int) -> int:
"""Сколько номеров `i < n` дают `i mod PERIOD == slot`."""
return n // PERIOD + (1 if n % PERIOD > slot else 0)
@dataclass(frozen=True)
class Model:
"""Ожидаемое у набора: объекты в bucket, строки `ready` и `pending`,
расхождения по классам и согласованные пары."""
objects: int
ready_rows: int
pending_rows: int
found: dict[str, int]
consistent: int
@property
def candidates(self) -> int:
return sum(self.found.values())
def model(n: int, *, clean: int = 0, missing: int = 0) -> Model:
"""Набор из `n` объектов с классами по номеру; набор отказа по пределу
— `clean` согласованных и `missing` строк без объекта."""
if clean or missing:
return Model(
objects=clean,
ready_rows=clean + missing,
pending_rows=0,
found={"missing_object": missing} if missing else {},
consistent=clean,
)
found = {kind: class_count(n, slot) for slot, kind in enumerate(CLASSES)}
return Model(
objects=n - found["missing_object"],
ready_rows=n - found["orphan_object"] - found["stale_pending"],
pending_rows=found["stale_pending"],
found={kind: count for kind, count in found.items() if count},
consistent=n - sum(found.values()),
)
def downloads(seed: int, n: int, count: int) -> list[str]:
"""`id` согласованных вложений набора для фоновых скачиваний."""
pool = [i for i in range(n) if object_class(i) is None]
chosen = random.Random(seed).sample(pool, min(count, len(pool)))
return [object_id(seed, i) for i in chosen]
# --- план --------------------------------------------------------------------------
def plan_passes(
stages: Iterable[tuple[str, tuple[str, ...]]], repeats: int, seed: int
) -> list[dict]:
"""Проходы этапов кругами: в круге r — перестановка ячеек этапа
`Random(seed + номер этапа × 100 + r)`; круг не начинается с ячейки,
которой кончился прежний."""
plan: list[dict] = []
for stage_no, (stage, cells) in enumerate(stages):
previous = None
for round_no in range(1, repeats + 1):
order = list(range(len(cells)))
random.Random(seed + stage_no * 100 + round_no).shuffle(order)
if len(order) > 1 and order[0] == previous:
order[0], order[1] = order[1], order[0]
for index in order:
cell = cells[index]
plan.append(
{
"pass": f"{stage}-{cell}-r{round_no}",
"stage": stage,
"cell": cell,
"repeat": round_no,
"order": len(plan) + 1,
},
)
previous = order[-1]
return plan
# --- разбор ------------------------------------------------------------------------
_PAIR = re.compile(r"(\w+)=(\S*)")
def _value(text: str) -> object:
if text in ("true", "false"):
return text == "true"
if text == "None":
return None
if text.endswith("ms") and text[:-2].isdigit():
return int(text[:-2])
try:
return int(text)
except ValueError:
pass
try:
return float(text)
except ValueError:
return text
def parse_finished(log: str) -> dict | None:
"""Итог прохода из журнала уборщика: время строки (секунды эпохи, часы
ВМ) и поля `key=value`; `took` — в мс. Нет строки — `None`."""
for line in reversed(log.splitlines()):
if FINISHED not in line:
continue
stamp = line.split(" ", 1)[0]
fields = {
key: _value(value)
for key, value in _PAIR.findall(line.split(FINISHED, 1)[1])
}
fields["ts"] = parse_log_time(stamp)
fields["took_ms"] = fields.pop("took", None)
return fields
return None
def parse_log_time(stamp: str) -> float:
"""`2026-10-23T12:00:00.123Z` (src/log.py) → секунды эпохи."""
moment = datetime.strptime(stamp, "%Y-%m-%dT%H:%M:%S.%fZ")
return moment.replace(tzinfo=UTC).timestamp()
def found_problems(fields: dict, expected: Model, *, deep: bool) -> list[str]:
"""Расхождения итога прохода с моделью набора: класс, найдено, ожидалось."""
problems = []
for kind in KINDS:
want = expected.found.get(kind, 0)
got = fields.get(f"found_{kind}", 0)
if kind == "checksum_mismatch" and not deep:
want = 0
if got != want:
problems.append(f"found_{kind}={got} expected={want}")
for name, want in (
("listed_objects", expected.objects),
("checked_rows", expected.ready_rows),
):
if fields.get(name) != want:
problems.append(f"{name}={fields.get(name)} expected={want}")
return problems
def touched(fields: dict) -> int:
"""Объектов S3, затронутых проходом: ключи списка и вызовы на объект."""
return int(fields.get("listed_keys") or 0) + sum(
int(fields.get(f"s3_{op}") or 0) for op in ("head", "get", "delete")
)
def pass_row(
item: dict,
*,
n: int,
size: int,
cell: dict,
cleaner_cpus: float,
rate: float,
fields: dict | None,
exit_code: int | None,
nano_cpus: int | None,
usage: dict,
problems: list[str],
extra_flags: Iterable[str] = (),
) -> dict:
"""Строка `passes.csv`. Пометки: `no_result` — итоговой строки нет,
`model` — найденное разошлось с моделью, `cpu_limit` — лимит CPU
контейнера прохода не тот, `exit` — неожиданный код выхода;
`extra_flags` — от оркестратора (`bg_dropped` — генератор фоновой
нагрузки не отправил часть запросов по расписанию)."""
fields = fields or {}
took = fields.get("took_ms")
cpu = fields.get("cpu_ms")
flags = list(extra_flags)
if not fields:
flags.append("no_result")
if problems:
flags.append("model")
if nano_cpus is not None and nano_cpus != round(cleaner_cpus * 1e9):
flags.append("cpu_limit")
# в каждом наборе профиля расхождения есть: dry-run и отказ — код 3
if exit_code != 3:
flags.append("exit")
return {
**{key: item[key] for key in ("pass", "stage", "cell", "repeat", "order")},
"n": n,
"size": size,
"strategy": cell["strategy"],
"deep": bool(cell.get("deep")),
"apply": bool(cell.get("apply")),
"rate": rate,
"cleaner_cpus": cleaner_cpus,
"nano_cpus": nano_cpus,
"exit_code": exit_code,
**{
key: fields.get(key)
for key in PASS_COLUMNS
if key.startswith(("found_", "fixed_", "s3_", "phase_"))
and key not in ("s3_cpu_cores",)
},
"refused": fields.get("refused"),
"listed_objects": fields.get("listed_objects"),
"checked_rows": fields.get("checked_rows"),
"remaining": fields.get("remaining"),
"listed_keys": fields.get("listed_keys"),
"read_bytes": fields.get("read_bytes"),
"db_queries": fields.get("db_queries"),
"cpu_ms": cpu,
"maxrss_kib": fields.get("maxrss_kib"),
"took_ms": took,
"ms_per_1k": round(took / n * 1000, 2) if took is not None and n else None,
"cpu_share": round(cpu / took, 3) if cpu is not None and took else None,
"touched_per_s": (
round(touched(fields) / took * 1000, 1) if fields and took else None
),
"s3_cpu_cores": usage.get("s3_cpu_cores"),
"db_cpu_cores": usage.get("db_cpu_cores"),
"api_cpu_cores": usage.get("api_cpu_cores"),
"model_ok": not problems,
"flags": " ".join(flags + [f"model:{p}" for p in problems[:3]]),
}
# --- фоновая нагрузка --------------------------------------------------------------
def window_rows(
item: dict,
requests: list,
bounds: dict[str, tuple[float, float]],
stats_fn,
) -> list[dict]:
"""Строки `windows.csv` прохода под нагрузкой: окно × вид запроса;
`ratio_p95` у окна `pass` — p95 прохода / p95 тихих окон (до и после
вместе). `stats_fn` — `analysis.window_stats`, `bounds` — мс эпохи."""
rows = []
for kind in LOAD_KINDS:
of_kind = [r for r in requests if r.kind == kind]
quiet = [
r
for name in ("before", "after")
for r in of_kind
if bounds[name][0] <= r.scheduled < bounds[name][1]
]
quiet_p95 = stats_fn(quiet, 0, float("inf"))["p95_ms"] if quiet else None
for window in WINDOWS:
start, end = bounds[window]
stats = stats_fn(of_kind, start, end)
ratio = None
if window == "pass" and stats["p95_ms"] and quiet_p95:
ratio = round(stats["p95_ms"] / quiet_p95, 3)
rows.append(
{
"pass": item["pass"],
"cell": item["cell"],
"repeat": item["repeat"],
"window": window,
"kind": kind,
"seconds": stats["seconds"],
"requests": stats["requests"],
"ok": stats["ok"],
"errors": stats["errors"],
"errors_5xx": sum(
count
for label, count in stats["error_kinds"].items()
if label.startswith("5")
),
"p50_ms": stats["p50_ms"],
"p95_ms": stats["p95_ms"],
"p99_ms": stats["p99_ms"],
"ratio_p95": ratio,
},
)
return rows
# --- вердикты ----------------------------------------------------------------------
CONFIRMED = "подтверждена"
REFUTED = "опровергнута"
UNTESTED = "нет данных"
@dataclass(frozen=True)
class Verdict:
hypothesis: str
result: str
numbers: str
def num(value) -> float | None:
if value is None or value == "":
return None
try:
return float(value)
except (TypeError, ValueError):
return None
def med(values: Iterable) -> float | None:
present = [v for v in (num(x) for x in values) if v is not None]
return statistics.median(present) if present else None
def spread(values: Iterable, digits: int = 0) -> str:
present = [v for v in (num(x) for x in values) if v is not None]
if not present:
return "—"
mid = statistics.median(present)
if len(present) == 1:
return f"{mid:.{digits}f}"
return f"{mid:.{digits}f} ({min(present):.{digits}f}–{max(present):.{digits}f})"
def fmt(value: float | None, digits: int = 2) -> str:
return "—" if value is None else f"{value:.{digits}f}"
def cell_rows(passes: list[dict], stage: str, cell: str) -> list[dict]:
return [
p
for p in passes
if p["stage"] == stage and p["cell"] == cell and not p.get("flags")
]
def cell_median(passes: list[dict], stage: str, cell: str, column: str) -> float | None:
return med(p.get(column) for p in cell_rows(passes, stage, cell))
def verdict_h1(stages: dict[str, dict], passes: list[dict]) -> Verdict:
"""batch линейна: мс на 1 000 объектов по этапам 4 KiB — в пределах
±30 %, рост RSS ≤ 300 байт на ключ."""
# ряд по N — наборы с классами по номеру; набор отказа по пределу
# (строки без объекта сверх набора) — другая модель, в ряд не идёт
small = [
s
for s, info in stages.items()
if info["size"] <= 64 * KIB and not info.get("missing")
]
per_k = {s: cell_median(passes, s, "batch", "ms_per_1k") for s in small}
rss = {s: cell_median(passes, s, "batch", "maxrss_kib") for s in small}
present = {s: v for s, v in per_k.items() if v}
if len(present) < 2:
return Verdict("H1", UNTESTED, "нужно ≥ 2 этапов batch с 4 KiB")
low, high = min(present.values()), max(present.values())
spread_ok = high / low - 1 <= H1_SPREAD
first = min(present, key=lambda s: stages[s]["n"])
last = max(present, key=lambda s: stages[s]["n"])
keys = stages[last]["n"] - stages[first]["n"]
growth = None
if rss.get(first) and rss.get(last) and keys > 0:
growth = (rss[last] - rss[first]) * 1024 / keys
rss_ok = growth is not None and growth <= H1_BYTES_PER_KEY
numbers = (
"мс на 1 000 объектов: "
+ ", ".join(f"{stages[s]['n']} — {fmt(v)}" for s, v in present.items())
+ f" (разброс {high / low - 1:.0%}, порог {H1_SPREAD:.0%}); рост RSS "
f"{fmt(growth, 0)} Б на ключ ({stages[first]['n']} → {stages[last]['n']}, "
f"порог {H1_BYTES_PER_KEY})"
)
return Verdict("H1", CONFIRMED if spread_ok and rss_ok else REFUTED, numbers)
def verdict_h2(stages: dict[str, dict], passes: list[dict]) -> Verdict:
"""head: время ≥ 5 × batch на тех же N, запросов к БД не меньше
объектов, RSS почти не растёт."""
parts, checks = [], []
rss = {}
for stage, info in stages.items():
head = cell_median(passes, stage, "head", "took_ms")
batch = cell_median(passes, stage, "batch", "took_ms")
if not head or not batch:
continue
queries = cell_median(passes, stage, "head", "db_queries")
listed = cell_median(passes, stage, "head", "listed_objects")
rss[info["n"]] = cell_median(passes, stage, "head", "maxrss_kib")
ratio = head / batch
checks.append(ratio >= H2_TIME_RATIO)
checks.append(queries is not None and listed is not None and queries >= listed)
parts.append(
f"N={info['n']}: head {head:.0f} мс / batch {batch:.0f} мс = "
f"{ratio:.1f}×, запросов БД {fmt(queries, 0)} на {fmt(listed, 0)} объектов"
)
if not parts:
return Verdict("H2", UNTESTED, "нет пар head и batch")
present = {n: v for n, v in rss.items() if v}
if len(present) >= 2:
growth = (present[max(present)] - present[min(present)]) / 1024
checks.append(growth <= H2_RSS_GROWTH_MIB)
parts.append(
f"рост RSS head {min(present)} → {max(present)}: {growth:.1f} MiB "
f"(порог {H2_RSS_GROWTH_MIB})"
)
return Verdict("H2", CONFIRMED if all(checks) else REFUTED, "; ".join(parts))
def verdict_h3(
stages: dict[str, dict], passes: list[dict], models: dict[str, Model]
) -> Verdict:
"""deep: прочитано ровно согласованные × размер; на 1 MiB — ≥ 5 × batch;
1 CPU быстрее 0,25 CPU ≥ 1,5 раза."""
parts, checks = [], []
for stage, info in stages.items():
rows = cell_rows(passes, stage, "deep") + cell_rows(passes, stage, "deep-fast")
if not rows:
continue
want = models[stage].consistent * info["size"]
exact = all(int(num(r["read_bytes"]) or -1) == want for r in rows)
checks.append(exact)
parts.append(
f"N={info['n']} × {info['size'] // KIB} KiB: read_bytes = {want} "
f"{'во всех' if exact else 'не во всех'} {len(rows)} проходах"
)
if info["size"] >= MIB:
deep = cell_median(passes, stage, "deep", "took_ms")
batch = cell_median(passes, stage, "batch", "took_ms")
fast = cell_median(passes, stage, "deep-fast", "took_ms")
share = cell_median(passes, stage, "deep", "cpu_share")
if deep and batch:
checks.append(deep / batch >= H3_DEEP_RATIO)
parts.append(
f"deep / batch = {deep / batch:.1f}× (порог {H3_DEEP_RATIO})"
)
if deep and fast:
checks.append(deep / fast >= H3_FAST_RATIO)
parts.append(
f"0,25 CPU / 1 CPU = {deep / fast:.2f}× (порог {H3_FAST_RATIO}), "
f"CPU уборщика / время при 0,25 CPU = {fmt(share)}"
)
if not parts:
return Verdict("H3", UNTESTED, "нет глубоких проходов")
return Verdict("H3", CONFIRMED if all(checks) else REFUTED, "; ".join(parts))
def verdict_h4(passes: list[dict], windows: list[dict]) -> Verdict:
"""Под нагрузкой: с пределом скорости p95 скачиваний в проходе ≤ 1,5 ×
тихих, 5xx нет; предел соблюдён (затронуто/с ≤ предела / 0,9); без
предела при 1 CPU отношение больше, чем с ним."""
ratios: dict[str, float | None] = {}
for cell in LOAD_CELLS:
ratios[cell] = med(
w["ratio_p95"]
for w in windows
if w["cell"] == cell and w["window"] == "pass" and w["kind"] == "download"
)
if not any(ratios.values()):
return Verdict("H4", UNTESTED, "нет проходов под нагрузкой")
fives = sum(int(num(w["errors_5xx"]) or 0) for w in windows)
# генератор не успевал по расписанию — отношение p95 не о сверке
dropped = sum("bg_dropped" in str(p.get("flags") or "") for p in passes)
checks = [fives == 0, dropped == 0]
for cell in LIMITED_LOAD:
if ratios.get(cell) is not None:
checks.append(ratios[cell] <= H4_THRESHOLD)
rates = []
for p in passes:
if p["cell"] in LIMITED_LOAD and num(p.get("rate")):
observed = num(p.get("touched_per_s"))
rates.append(observed)
checks.append(
observed is not None and observed <= num(p["rate"]) / H4_RATE_SHARE
)
if ratios.get("load-fast") and ratios.get("load-fast-limited"):
checks.append(ratios["load-fast"] > ratios["load-fast-limited"])
numbers = (
"p95 скачиваний в проходе / в тихих окнах: "
+ ", ".join(f"{cell} {fmt(value)}" for cell, value in ratios.items())
+ f" (порог для ячеек с пределом {H4_THRESHOLD}); 5xx во всех окнах: {fives}; "
f"проходов с bg_dropped: {dropped}; затронуто объектов/с с пределом: "
f"{', '.join(fmt(r, 0) for r in rates) or '—'}"
)
return Verdict("H4", CONFIRMED if all(checks) else REFUTED, numbers)
def verdict_h5(passes: list[dict]) -> Verdict:
"""Отказ по пределу ничего не меняет и стоит как dry-run того же набора."""
stage = next((p["stage"] for p in passes if p["cell"] == "refuse"), None)
if stage is None:
return Verdict("H5", UNTESTED, "нет проходов отказа")
refuse = [p for p in passes if p["stage"] == stage and p["cell"] == "refuse"]
fixed = sum(
int(num(p.get(f"fixed_{action}")) or 0) for p in refuse for action in ACTIONS
)
codes = sorted({p.get("exit_code") for p in refuse}, key=str)
refused = all(p.get("refused") in (True, "True") for p in refuse)
took_r = cell_median(passes, stage, "refuse", "took_ms")
took_d = cell_median(passes, stage, "batch", "took_ms")
calls = {
cell: cell_median(passes, stage, cell, "s3_head")
for cell in ("refuse", "batch")
}
checks = [fixed == 0, refused, codes == [3]]
numbers = (
f"исправлено {fixed}, коды {codes}, refused во всех: {refused}; время "
f"отказа {fmt(took_r, 0)} мс / dry-run {fmt(took_d, 0)} мс; HEAD "
f"{fmt(calls['refuse'], 0)} / {fmt(calls['batch'], 0)}"
)
if took_r and took_d:
checks.append(abs(took_r / took_d - 1) <= H5_SPREAD)
checks.append(calls["refuse"] is not None and calls["refuse"] == calls["batch"])
return Verdict("H5", CONFIRMED if all(checks) else REFUTED, numbers)
# --- сводка ------------------------------------------------------------------------
def render_summary(
meta: dict,
passes: list[dict],
windows: list[dict],
verdicts: list[Verdict],
) -> str:
profile = meta["profile"]
lines = [
f"# Сверка bucket и БД: метка `{meta['label']}`",
"",
f"- Статус: **{'прерван: ' + meta['aborted'] if meta.get('aborted') else 'готово'}**",
f"- Код (`src_sha256` образа): `{meta.get('code', {}).get('src_sha256', '—')}`",
f"- Профиль `{profile['name']}`: повторов {profile['repeats']}, уборщик "
f"{profile['cleaner_cpus']} CPU (управляемый опыт — {profile['fast_cpus']}), "
f"предел скорости по умолчанию {profile['default_rate']:g} объектов/с, "
f"grace прохода {profile['grace_s']} с, страница {profile['page_size']}",
f"- Фоновая нагрузка (H4): скачиваний {profile['load_download_rate']:g}/с, "
f"записей {profile['load_write_rate']:g}/с, чтений {profile['load_read_rate']:g}/с; "
f"тихие окна {profile['quiet_s']:g} с до и после прохода",
"- Значения — медиана (min–max) повторов. Стоимость — итоговая строка "
"уборщика (счётчики клиента S3, запросы к БД, `cpu_ms` — CPU самого "
"прохода без старта процесса, `maxrss_kib` — пик RSS процесса); CPU S3, "
"PostgreSQL и реплик — сэмплер за окно прохода. LIST включает проверку "
"bucket перед каждым «объекта нет» (список с одним ключом)",
"",
"## Проходы",
"",
"| Этап | N | Размер | Ячейка | Время, мс | мс на 1 000 | LIST | HEAD | GET "
"| Запросов БД | Прочитано, MiB | CPU, мс | RSS, MiB | S3 CPU | Пометки |",
"|---|---:|---:|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---|",
]
seen: list[tuple[str, str]] = []
for p in passes:
key = (p["stage"], p["cell"])
if key not in seen:
seen.append(key)
for stage, cell in seen:
rows = [p for p in passes if p["stage"] == stage and p["cell"] == cell]
first = rows[0]
flags = sorted({f for r in rows for f in str(r.get("flags") or "").split()})
lines.append(
f"| {stage} | {first['n']} | {int(first['size']) // KIB} KiB | {cell} | "
f"{spread(r['took_ms'] for r in rows)} | "
f"{spread((r['ms_per_1k'] for r in rows), 2)} | "
f"{spread(r['s3_list'] for r in rows)} | {spread(r['s3_head'] for r in rows)} | "
f"{spread(r['s3_get'] for r in rows)} | {spread(r['db_queries'] for r in rows)} | "
f"{spread(((num(r['read_bytes']) or 0) / MIB for r in rows), 1)} | "
f"{spread(r['cpu_ms'] for r in rows)} | "
f"{spread(((num(r['maxrss_kib']) or 0) / 1024 for r in rows), 1)} | "
f"{spread((r['s3_cpu_cores'] for r in rows), 2)} | {' '.join(flags) or '—'} |"
)
if windows:
lines += [
"",
"## Фоновая нагрузка",
"",
"| Ячейка | Окно | Скачиваний | p95 скачиваний, мс | p95 записи, мс | "
"Ошибок | p95 прохода / тихих |",
"|---|---|---:|---:|---:|---:|---:|",
]
for cell in LOAD_CELLS:
for window in WINDOWS:
rows = [
w for w in windows if w["cell"] == cell and w["window"] == window
]
if not rows:
continue
down = [w for w in rows if w["kind"] == "download"]
write = [w for w in rows if w["kind"] == "write"]
lines.append(
f"| {cell} | {window} | {spread(w['requests'] for w in down)} | "
f"{spread((w['p95_ms'] for w in down), 1)} | "
f"{spread((w['p95_ms'] for w in write), 1)} | "
f"{sum(int(num(w['errors']) or 0) for w in rows)} | "
f"{spread((w['ratio_p95'] for w in down), 2) if window == 'pass' else '—'} |"
)
lines += [
"",
"## Гипотезы",
"",
"Тексты и пороги — `REPORT.md`, «Трек 2: гипотезы» (записаны до замеров). "
"Итог по числам этой метки; вывод — в `REPORT.md`.",
"",
"| Гипотеза | Итог | Числа |",
"|---|---|---|",
]
lines += [f"| {v.hypothesis} | {v.result} | {v.numbers} |" for v in verdicts]
warnings = meta.get("host_warnings") or []
if warnings:
lines += ["", "## Предупреждения о хосте", "", *(f"- {w}" for w in warnings)]
return "\n".join(lines) + "\n"
# --- самопроверка ------------------------------------------------------------------
def selftest() -> None:
m = model(2000)
assert m.found == {
"orphan_object": 5,
"missing_object": 5,
"size_mismatch": 5,
"stale_pending": 5,
}, m.found
assert (m.objects, m.ready_rows, m.pending_rows) == (1995, 1990, 5)
assert m.consistent == 1980
assert (class_count(401, 0), class_count(401, 1)) == (2, 1)
s4 = model(0, clean=500, missing=100)
assert (s4.objects, s4.ready_rows, s4.candidates) == (500, 600, 100)
assert object_id(1, 2) == object_id(1, 2) != object_id(1, 3)
assert uuid.UUID(object_id(1, 2)).version == 4
assert len(content(1, 2, 4096)) == 4096
assert content(1, 2, 10) == content(1, 2, 10)
assert len(object_indices(0, 400)) == 399
assert object_indices(0, 10, FORCE_MISSING) == []
csv_text = rows_csv(
seed=1,
start=0,
end=400,
size=8,
namespace="bench",
chat_id="c",
owner_id="o",
created_at="2026-10-22T00:00:00Z",
)
rows = csv_text.splitlines()
assert len(rows) == 399, len(rows)
assert ",ready," in rows[0]
assert ",9,\\x" in rows[1]
assert ",pending," in rows[2]
assert rows[0].count(",") == len(COPY_COLUMNS) - 1
plan = plan_passes([("a", ("batch", "deep")), ("b", ("batch",))], 2, 7)
assert [p["order"] for p in plan] == [1, 2, 3, 4, 5, 6]
assert {p["pass"] for p in plan if p["stage"] == "a"} == {
"a-batch-r1",
"a-deep-r1",
"a-batch-r2",
"a-deep-r2",
}
assert plan[1]["cell"] != plan[2]["cell"]
log = (
"2026-10-23T12:00:00.000Z INFO src.cleaner [rid=-] cleaner started mode=reconcile\n"
"2026-10-23T12:00:05.250Z WARNING src.services.reconcile [rid=-] "
"reconcile pass finished apply=false strategy=batch deep=false rate=0 "
"listed_objects=1995 checked_rows=1990 fresh_objects=0 fresh_rows=0 lost_known=0 "
"found_orphan_object=5 found_stale_pending=5 found_missing_object=5 "
"found_size_mismatch=5 found_checksum_mismatch=0 found_restored_object=0 "
"found_foreign_object=0 fixed_cleared_lost=0 fixed_deleted_object=0 "
"fixed_marked_lost=0 fixed_removed_pending=0 remaining=20 refused=false "
"unlogged=0 interrupted_by=None s3_list=7 s3_head=15 s3_get=0 s3_delete=0 "
"listed_keys=2000 read_bytes=0 db_queries=30 phase_list_ms=100 phase_rows_ms=50 "
"phase_stale_ms=2 phase_recheck_ms=40 phase_act_ms=0 cpu_ms=900 maxrss_kib=90000 "
"took=1200ms\n"
)
fields = parse_finished(log)
assert fields is not None
assert (fields["took_ms"], fields["refused"]) == (1200, False)
assert (fields["interrupted_by"], fields["s3_list"]) == (None, 7)
assert abs(fields["ts"] - 1_792_756_805.25) < 1e-3, fields["ts"]
assert found_problems(fields, m, deep=False) == []
bad = dict(fields, found_orphan_object=4)
assert found_problems(bad, m, deep=False) == ["found_orphan_object=4 expected=5"]
assert touched(fields) == 2015
row = pass_row(
{"pass": "q-batch-r1", "stage": "q", "cell": "batch", "repeat": 1, "order": 1},
n=2000,
size=4096,
cell=CELLS["batch"],
cleaner_cpus=0.25,
rate=0,
fields=fields,
exit_code=3,
nano_cpus=250_000_000,
usage={},
problems=[],
)
assert (row["ms_per_1k"], row["cpu_share"], row["flags"]) == (600.0, 0.75, "")
assert set(row) <= set(PASS_COLUMNS), set(row) - set(PASS_COLUMNS)
passes = [
dict(row, stage=s, n=n, ms_per_1k=v, maxrss_kib=r)
for s, n, v, r in (("b", 10_000, 10.0, 90_000), ("d", 100_000, 11.0, 110_000))
]
stages = {"b": {"n": 10_000, "size": 4096}, "d": {"n": 100_000, "size": 4096}}
h1 = verdict_h1(stages, passes)
assert h1.result == CONFIRMED, h1
passes[1]["maxrss_kib"] = 200_000
assert verdict_h1(stages, passes).result == REFUTED
assert verdict_h5([]).result == UNTESTED
print("reconcile selftest: ok")
if __name__ == "__main__":
if sys.argv[1:] == ["--selftest"]:
selftest()
else:
raise SystemExit("usage: uv run python bench/reconcile.py --selftest")
+2694
View File
File diff suppressed because it is too large Load Diff
+274
View File
@@ -0,0 +1,274 @@
"""Сэмплер стенда: раз в секунду — ресурсы контейнеров, LB и PostgreSQL.
Работает только внутри контейнера `vlad-bench-sampler` (образ
приложения: в нём есть Python и asyncpg) с `--cgroupns host`: тогда в
`/sys/fs/cgroup/docker/<id>/` видны cgroup всех контейнеров ВМ Docker.
Его запускает `bench/run.py` (`Stand.start_sampler`), на хосте он не
работает. Пишет строки JSON в файл `--out`; время — часы ВМ (`time.time()`),
те же, что у генератора.
Строка тика:
{"ts": ..., "cg": {"<id12>": [usage_usec, nr_periods, nr_throttled,
throttled_usec, memory_current]},
"vm": [занято_jiffies, всего_jiffies],
"lb": {"<слот>": {...}, "FRONTEND": {...}}, # режим list
"pg": {"conn": [[адрес, состояние, ожидание, n], ...],
"db": {xact_commit, xact_rollback, sessions, numbackends}}}
Режимы:
list — заданные контейнеры (`--container id` …), опрос статистики
HAProxy (`/stats;csv` на :8404 внутри сети) и одно постоянное
соединение с PostgreSQL стенда (`pg_stat_activity`,
`pg_stat_database`); его слот занимает одно из
`max_connections`. Серии трека 1;
scan — все каталоги контейнеров в cgroup на каждом тике (новые
реплики видны с первого тика), без сети, LB и PostgreSQL:
наблюдатель не обращается к стенду. Профили failover, rollout
и reconcile;
peak — пиковая память заданных контейнеров (`--container роль=id`) за
окно прогона профиля uploads (лаба 4). Контейнер с `--user 0`,
cgroupfs на запись, без сети. `memory.peak` каждого контейнера
открывается на чтение и запись: прежнее значение — пик с
запуска, запись `reset` в свой дескриптор сбрасывает пик для
этого дескриптора (ядро ≥ 6.12). Раз в `--interval` —
`memory.current`, `anon` и `sock` из `memory.stat`, `oom_kill`
из `memory.events`. Появился `--stop-file` — пик через тот же
дескриптор и выход.
Строки режима peak:
{"start": {"<роль>": байт|null}, "reset": {"<роль>": true|false}}
{"ts": ..., "pk": {"<роль>": [current, anon, sock, oom_kill]|null}}
{"ts": ..., "peak": {"<роль>": байт|null}, "end": true}
Пароль PostgreSQL — только из окружения контейнера (`PGPASSWORD`), в
вывод не попадает.
"""
import argparse
import asyncio
import contextlib
import json
import os
import re
import sys
import time
import urllib.request
from pathlib import Path
CGROUP = Path("/sys/fs/cgroup/docker")
HEX64 = re.compile(r"[0-9a-f]{64}")
LB_STATS = "http://haproxy:8404/stats;csv"
LB_FIELDS = ("scur", "stot", "econ", "eresp", "wretr", "wredis", "qcur", "rate")
# соединения приложения: application_name из src/constants.py (копия:
# сэмплер код приложения не импортирует)
APP_NAME = "mtusi-messenger"
PG_CONN_SQL = """
SELECT coalesce(host(client_addr), '-'), coalesce(state, '-'),
coalesce(wait_event_type, 'CPU'), count(*)
FROM pg_stat_activity
WHERE backend_type = 'client backend' AND application_name = $1
GROUP BY 1, 2, 3
"""
PG_DB_SQL = """
SELECT xact_commit, xact_rollback, sessions, numbackends
FROM pg_stat_database WHERE datname = current_database()
"""
def cgroup_line(container: str) -> list[int] | None:
"""usage_usec, nr_periods, nr_throttled, throttled_usec, memory.current."""
folder = CGROUP / container
try:
stat = (folder / "cpu.stat").read_text()
memory = int((folder / "memory.current").read_text())
except (OSError, ValueError):
return None
values = dict(line.split() for line in stat.splitlines() if line)
return [
int(values.get("usage_usec", 0)),
int(values.get("nr_periods", 0)),
int(values.get("nr_throttled", 0)),
int(values.get("throttled_usec", 0)),
memory,
]
def vm_line() -> list[int]:
fields = Path("/proc/stat").read_text().splitlines()[0].split()[1:9]
user, nice, system, idle, iowait, irq, softirq, steal = (int(f) for f in fields)
total = user + nice + system + idle + iowait + irq + softirq + steal
return [total - idle - iowait, total]
def lb_stats() -> dict | None:
try:
with urllib.request.urlopen(LB_STATS, timeout=0.5) as response: # noqa: S310
text = response.read().decode()
except OSError:
return None
lines = text.splitlines()
header = lines[0].lstrip("# ").split(",")
out = {}
for line in lines[1:]:
row = dict(zip(header, line.split(","), strict=False))
if row.get("pxname") != "api" and row.get("pxname") != "entry":
continue
name = "FRONTEND" if row["pxname"] == "entry" else row["svname"]
if name == "FRONTEND" and row["svname"] != "FRONTEND":
continue
out[name] = {
"status": row.get("status", ""),
"addr": row.get("addr", ""),
**{field: int(row[field]) for field in LB_FIELDS if row.get(field)},
}
return out
def _memory_line(container: str) -> list[int] | None:
"""memory.current, anon, sock, oom_kill контейнера; `None` — его нет."""
folder = CGROUP / container
try:
current = int((folder / "memory.current").read_text())
stat = dict(
line.split() for line in (folder / "memory.stat").read_text().splitlines()
)
events = dict(
line.split() for line in (folder / "memory.events").read_text().splitlines()
)
except (OSError, ValueError):
return None
return [
current,
int(stat.get("anon", 0)),
int(stat.get("sock", 0)),
int(events.get("oom_kill", 0)),
]
def _read_fd(fd: int) -> int | None:
try:
os.lseek(fd, 0, os.SEEK_SET)
return int(os.read(fd, 64).decode().strip())
except (OSError, ValueError):
return None
def peak(args: argparse.Namespace) -> None:
"""Режим peak: сброс пика своим дескриптором, выборки, пик в конце."""
targets = dict(item.split("=", 1) for item in args.container)
handles: dict[str, int] = {}
start: dict[str, int | None] = {}
reset: dict[str, bool] = {}
for role, container in targets.items():
try:
fd = os.open(CGROUP / container / "memory.peak", os.O_RDWR)
except OSError:
start[role], reset[role] = None, False
continue
start[role] = _read_fd(fd)
try:
os.lseek(fd, 0, os.SEEK_SET)
os.write(fd, b"reset")
reset[role] = True
handles[role] = fd
except OSError:
reset[role] = False
os.close(fd)
with open(args.out, "a", encoding="ascii") as out:
out.write(json.dumps({"start": start, "reset": reset}) + "\n")
out.flush()
next_tick = time.monotonic()
while not os.path.exists(args.stop_file):
tick = {
"ts": round(time.time(), 3),
"pk": {role: _memory_line(c) for role, c in targets.items()},
}
out.write(json.dumps(tick, separators=(",", ":")) + "\n")
out.flush()
next_tick += args.interval
time.sleep(max(0.0, next_tick - time.monotonic()))
final = {
"ts": round(time.time(), 3),
"peak": {role: _read_fd(fd) for role, fd in handles.items()},
"end": True,
}
out.write(json.dumps(final) + "\n")
async def main(args: argparse.Namespace) -> None:
interval = args.interval
connection = None
if args.mode == "list":
import asyncpg # noqa: PLC0415 - нужен только режиму list
for _ in range(20):
try:
connection = await asyncpg.connect(
host="postgres",
user=os.environ["PGUSER"],
database=os.environ["PGDATABASE"],
password=os.environ["PGPASSWORD"],
server_settings={"application_name": "bench-sampler"},
timeout=3,
)
break
except (OSError, asyncpg.PostgresError):
await asyncio.sleep(0.5)
out = open(args.out, "a", encoding="ascii") # noqa: ASYNC230, SIM115
next_tick = time.monotonic()
while True:
ts = time.time()
if args.mode == "scan":
# файлы cgroup — псевдофайловая система ядра: чтение без ожидания
try:
ids = [
p.name
for p in CGROUP.iterdir() # noqa: ASYNC240
if HEX64.fullmatch(p.name)
]
except OSError:
ids = []
else:
ids = args.container
tick: dict = {"ts": round(ts, 3), "cg": {}, "vm": vm_line()}
for container in ids:
line = cgroup_line(container)
if line is not None:
tick["cg"][container[:12]] = line
if args.mode == "list":
tick["lb"] = await asyncio.to_thread(lb_stats)
if connection is not None:
with contextlib.suppress(Exception):
rows = await connection.fetch(PG_CONN_SQL, APP_NAME)
db = await connection.fetchrow(PG_DB_SQL)
# соединения приложения: адрес реплики, состояние, ожидание
tick["pg"] = {
"conn": [list(row) for row in rows],
"db": dict(db),
}
out.write(json.dumps(tick, separators=(",", ":")) + "\n")
out.flush()
next_tick += interval
await asyncio.sleep(max(0.0, next_tick - time.monotonic()))
def parser() -> argparse.ArgumentParser:
root = argparse.ArgumentParser(description=__doc__.splitlines()[0])
root.add_argument("--mode", choices=("list", "scan", "peak"), required=True)
root.add_argument("--interval", type=float, default=1.0)
root.add_argument("--out", required=True)
# list — id контейнера; peak — роль=id
root.add_argument("--container", action="append", default=[])
root.add_argument("--stop-file", default="/tmp/peak.stop")
return root
if __name__ == "__main__":
with contextlib.suppress(KeyboardInterrupt):
arguments = parser().parse_args()
# peak — без event loop: только файлы cgroup и пауза между выборками
if arguments.mode == "peak":
peak(arguments)
else:
asyncio.run(main(arguments))
sys.exit(0)
+578
View File
@@ -0,0 +1,578 @@
"""Профиль uploads: план, разбор сэмплера peak, сводка без docker. Только stdlib.
Оркестрирует прогоны `run.py` (профили `uploads`, `uploads-quick`); здесь
— чистые функции: план прогонов кругами, пиковая память по строкам
сэмплера в режиме `peak` (`bench/sampler.py`), строка `runs.csv`, сводка
по ячейкам и вердикты U1–U4 (гипотезы записаны в `REPORT.md` до замеров).
Самопроверка — `uv run python bench/uploads.py --selftest`.
"""
import random
import statistics
import sys
from collections.abc import Iterable
from dataclasses import dataclass
MIB = 2**20
VARIANTS = ("limited", "unlimited")
VARIANT_NAMES = {"limited": "с лимитом", "unlimited": "без лимита"}
ROLES = ("api", "s3", "lb")
# пороги гипотез — до замеров (REPORT.md, «Память загрузок: гипотезы»)
U1_HALF = 0.5
U1_GROWTH_MIB = 1.0
U2_BODIES_PER_CLIENT = 0.8
U2_NEAR_LIMIT = 0.9
U3_SHARE = 0.9
RUN_COLUMNS = (
"run",
"variant",
"size",
"body_bytes",
"clients",
"repeat",
"order",
"mem_before_mib",
"start_peak_mib",
"peak_mib",
"peak_source",
"anon_max_mib",
"sock_max_mib",
"oom_kill",
"oom_killed",
"exit_code",
"running_after",
"started",
"ok",
"rejected_429",
"errors_5xx",
"other_errors",
"statuses",
"uploads_per_s",
"mib_per_s",
"p50_ms",
"p95_ms",
"p99_ms",
"max_ms",
"s3_peak_mib",
"s3_anon_max_mib",
"lb_peak_mib",
"lb_sock_max_mib",
"gen_cpu_s",
"host_swapouts",
"flags",
)
def plan_runs(
variants: Iterable[str],
sizes: Iterable[str],
clients: Iterable[int],
repeats: int,
seed: int,
) -> list[dict]:
"""Прогоны кругами: в круге r — перестановка ячеек (вариант × размер ×
клиенты) генератором `Random(seed + r)`; круг не начинается с ячейки,
которой кончился прежний."""
cells = [(v, s, c) for v in variants for s in sizes for c in clients]
plan: list[dict] = []
previous = None
for round_no in range(1, repeats + 1):
order = list(range(len(cells)))
random.Random(seed + round_no).shuffle(order)
if len(order) > 1 and order[0] == previous:
order[0], order[1] = order[1], order[0]
for index in order:
variant, size, count = cells[index]
plan.append(
{
"run": f"{variant}-{size}-c{count}-r{round_no}",
"variant": variant,
"size": size,
"clients": count,
"repeat": round_no,
"order": len(plan) + 1,
},
)
previous = order[-1]
return plan
@dataclass
class Peak:
"""Память одного контейнера за окно по строкам сэмплера `peak`."""
start_peak: int | None = None
reset: bool = False
peak: int | None = None
first_current: int | None = None
max_current: int = 0
max_anon: int = 0
max_sock: int = 0
oom_first: int | None = None
oom_last: int | None = None
samples: int = 0
missing: int = 0
@property
def oom_kills(self) -> int:
if self.oom_first is None or self.oom_last is None:
return 0
return self.oom_last - self.oom_first
@property
def window_peak(self) -> int | None:
"""Пик окна: `memory.peak` своего дескриптора после сброса; без
сброса или чтения (контейнер погиб) — наибольшая выборка."""
if self.reset and self.peak is not None:
return max(self.peak, self.max_current)
return self.max_current or None
@property
def source(self) -> str:
return "reset" if self.reset and self.peak is not None else "sampled"
def parse_peak(lines: list[dict]) -> dict[str, Peak]:
"""Строки сэмплера `peak` → память по ролям."""
roles: dict[str, Peak] = {}
def role(name: str) -> Peak:
return roles.setdefault(name, Peak())
for line in lines:
if "reset" in line:
for name, value in line.get("start", {}).items():
role(name).start_peak = value
for name, ok in line["reset"].items():
role(name).reset = bool(ok)
elif "pk" in line:
for name, values in line["pk"].items():
item = role(name)
if values is None:
item.missing += 1
continue
current, anon, sock, oom = values
item.samples += 1
if item.first_current is None:
item.first_current = current
item.max_current = max(item.max_current, current)
item.max_anon = max(item.max_anon, anon)
item.max_sock = max(item.max_sock, sock)
if item.oom_first is None:
item.oom_first = oom
item.oom_last = oom
elif "peak" in line:
for name, value in line["peak"].items():
role(name).peak = value
return roles
def mib(value: int | float | None) -> float | None:
return None if value is None else round(value / MIB, 1)
def run_row(
run: dict,
*,
body_bytes: int,
peaks: dict[str, Peak],
result: dict,
state: dict,
swapouts: int | None,
) -> dict:
"""Строка `runs.csv`. Пометки: `oom` — реплику завершило ядро из-за
памяти (`OOMKilled` или `oom_kill` cgroup) — результат варианта, а не
сбой; `host_swap` — хост выгружал страницы во время прогона;
`peak_sampled` — пик окна по выборкам, а не по сброшенному
`memory.peak`; `no_result` — генератор не вернул итог."""
api = peaks.get("api", Peak())
s3 = peaks.get("s3", Peak())
lb = peaks.get("lb", Peak())
oom = bool(state.get("oom_killed")) or api.oom_kills > 0
flags = []
if oom:
flags.append("oom")
if swapouts:
flags.append("host_swap")
if api.source == "sampled":
flags.append("peak_sampled")
if not result:
flags.append("no_result")
return {
**{key: run[key] for key in ("run", "variant", "size", "clients", "repeat")},
"order": run["order"],
"body_bytes": body_bytes,
"mem_before_mib": mib(api.first_current),
"start_peak_mib": mib(api.start_peak),
"peak_mib": mib(api.window_peak),
"peak_source": api.source,
"anon_max_mib": mib(api.max_anon),
"sock_max_mib": mib(api.max_sock),
"oom_kill": api.oom_kills,
"oom_killed": bool(state.get("oom_killed")),
"exit_code": state.get("exit_code"),
"running_after": state.get("running"),
"started": result.get("started"),
"ok": result.get("ok"),
"rejected_429": result.get("rejected_429"),
"errors_5xx": result.get("errors_5xx"),
"other_errors": result.get("other_errors"),
"statuses": " ".join(
f"{k}:{v}" for k, v in sorted(result.get("statuses", {}).items())
),
**{
key: result.get(key)
for key in (
"uploads_per_s",
"mib_per_s",
"p50_ms",
"p95_ms",
"p99_ms",
"max_ms",
"gen_cpu_s",
)
},
"s3_peak_mib": mib(s3.window_peak),
"s3_anon_max_mib": mib(s3.max_anon),
"lb_peak_mib": mib(lb.window_peak),
"lb_sock_max_mib": mib(lb.max_sock),
"host_swapouts": swapouts,
"flags": " ".join(flags),
}
# --- сводка ------------------------------------------------------------------------
def num(value) -> float | None:
if value is None or value == "":
return None
try:
return float(value)
except (TypeError, ValueError):
return None
def median(values: Iterable) -> float | None:
present = [v for v in (num(x) for x in values) if v is not None]
return statistics.median(present) if present else None
def spread(values: Iterable, digits: int = 1) -> str:
present = [v for v in (num(x) for x in values) if v is not None]
if not present:
return "—"
mid = statistics.median(present)
if len(present) == 1:
return f"{mid:.{digits}f}"
return f"{mid:.{digits}f} ({min(present):.{digits}f}–{max(present):.{digits}f})"
def fmt(value: float | None, digits: int = 1) -> str:
return "—" if value is None else f"{value:.{digits}f}"
def is_oom(row: dict) -> bool:
return "oom" in str(row.get("flags") or "").split()
def cells(rows: list[dict]) -> dict[tuple[str, str, int], list[dict]]:
grouped: dict[tuple[str, str, int], list[dict]] = {}
for row in rows:
key = (row["variant"], row["size"], int(row["clients"]))
grouped.setdefault(key, []).append(row)
return grouped
def per_client_bodies(row: dict) -> float | None:
"""Рост пика окна над памятью до окна на клиента, в телах."""
peak, before = num(row.get("peak_mib")), num(row.get("mem_before_mib"))
body, clients = num(row.get("body_bytes")), int(row["clients"])
if peak is None or before is None or not body or not clients:
return None
return (peak - before) * MIB / body / clients
@dataclass(frozen=True)
class Verdict:
hypothesis: str
result: str
numbers: str
CONFIRMED = "подтверждена"
REFUTED = "опровергнута"
UNTESTED = "нет данных"
def verdicts(rows: list[dict], *, limit_mib: float, big: str) -> list[Verdict]:
grouped = cells(rows)
def group(variant: str, size: str, clients: int) -> list[dict]:
return grouped.get((variant, size, clients), [])
out = []
# U1: с лимитом пик ≤ половины лимита при C = 10, 20, 40 (большое тело),
# рост сверх C = 10 ≤ 1 MiB на клиента; OOM и 5xx нет ни в одном прогоне
levels = [c for c in (10, 20, 40) if group("limited", big, c)]
limited = [r for r in rows if r["variant"] == "limited"]
if levels:
peaks = {
c: median(r["peak_mib"] for r in group("limited", big, c)) for c in levels
}
base = peaks.get(10)
growth = {
c: (peaks[c] - base) / (c - 10)
for c in levels
if c > 10 and base is not None and peaks[c] is not None
}
ooms = sum(is_oom(r) for r in limited)
fives = sum(int(num(r.get("errors_5xx")) or 0) for r in limited)
ok = (
all(v is not None and v <= limit_mib * U1_HALF for v in peaks.values())
and all(v <= U1_GROWTH_MIB for v in growth.values())
and not ooms
and not fives
)
out.append(
Verdict(
"U1",
CONFIRMED if ok else REFUTED,
"пик, MiB: "
+ ", ".join(f"C={c} {fmt(v)}" for c, v in peaks.items())
+ f" (половина лимита {limit_mib * U1_HALF:g}); сверх C=10, MiB "
"на клиента: "
+ (", ".join(f"C={c} {fmt(v, 2)}" for c, v in growth.items()) or "—")
+ f"; OOM {ooms}, 5xx {fives} во всех прогонах «с лимитом»",
),
)
else:
out.append(Verdict("U1", UNTESTED, "нет ячеек «с лимитом» C ≥ 10"))
# U2: без лимита рост ≥ 0,8 тела на клиента при C = 10; при C = 40 —
# OOM или пик ≥ 90 % лимита
ten = group("unlimited", big, 10)
forty = group("unlimited", big, 40)
if ten or forty:
slope = median(per_client_bodies(r) for r in ten if not is_oom(r))
near = all(
is_oom(r) or (num(r["peak_mib"]) or 0) >= limit_mib * U2_NEAR_LIMIT
for r in forty
)
ok = (
slope is not None and slope >= U2_BODIES_PER_CLIENT and bool(forty) and near
)
out.append(
Verdict(
"U2",
CONFIRMED if ok else REFUTED,
f"C=10: {fmt(slope, 2)} тела на клиента (порог {U2_BODIES_PER_CLIENT}); "
f"C=40: OOM {sum(is_oom(r) for r in forty)}/{len(forty)}, пик "
f"{spread(r['peak_mib'] for r in forty)} MiB (90 % лимита "
f"{limit_mib * U2_NEAR_LIMIT:g})",
),
)
else:
out.append(Verdict("U2", UNTESTED, "нет ячеек «без лимита»"))
# U3: загрузок/с с лимитом ≥ 90 % без лимита при C ≥ 10, пока тот жив
ratios = []
for variant_size in sorted({r["size"] for r in rows}):
for clients in (10, 20, 40):
lim = group("limited", variant_size, clients)
unl = group("unlimited", variant_size, clients)
if not lim or not unl or any(is_oom(r) for r in unl):
continue
a = median(r["uploads_per_s"] for r in lim)
b = median(r["uploads_per_s"] for r in unl)
if a is not None and b:
ratios.append((variant_size, clients, a, b, a / b))
if ratios:
out.append(
Verdict(
"U3",
CONFIRMED if all(r[4] >= U3_SHARE for r in ratios) else REFUTED,
"; ".join(
f"{s} C={c}: {a:.2f} / {b:.2f} = {ratio:.0%}"
for s, c, a, b, ratio in ratios
),
),
)
else:
out.append(Verdict("U3", UNTESTED, "нет пар ячеек без OOM"))
# U4: с лимитом 429 нет при C ≤ 20 (4 места + 16 в очереди), есть при C = 40
low = [r for r in limited if int(r["clients"]) <= 20]
high = [r for r in limited if int(r["clients"]) >= 40]
if low and high:
low_429 = sum(int(num(r.get("rejected_429")) or 0) for r in low)
high_429 = [int(num(r.get("rejected_429")) or 0) for r in high]
ok = low_429 == 0 and all(v > 0 for v in high_429)
out.append(
Verdict(
"U4",
CONFIRMED if ok else REFUTED,
f"429 при C ≤ 20: {low_429} в {len(low)} прогонах; при C = 40: "
+ ", ".join(map(str, high_429)),
),
)
else:
out.append(Verdict("U4", UNTESTED, "нет ячеек «с лимитом» C ≤ 20 и C = 40"))
return out
def render_summary(meta: dict, rows: list[dict]) -> str:
profile = meta["profile"]
bodies = meta.get("bodies", {})
big = max(bodies, key=lambda k: bodies[k]["bytes"]) if bodies else ""
limit_mib = float(profile["api_memory"].rstrip("m"))
lines = [
f"# Память загрузок: метка `{meta['label']}`",
"",
f"- Статус: **{'прерван: ' + meta['aborted'] if meta.get('aborted') else 'готово'}**",
f"- Код (`src_sha256` образа): `{meta.get('code', {}).get('src_sha256', '—')}`",
f"- Профиль `{profile['name']}`: варианты "
+ ", ".join(f"«{VARIANT_NAMES[v]}»" for v in profile["variants"])
+ f"; клиенты {', '.join(map(str, profile['clients']))}; повторов "
f"{profile['repeats']}; окно {profile['window_s']:g} с после "
f"{profile['warmup_s']:g} с разгона",
"- Тела: "
+ ", ".join(
f"{name} — {item['bytes']} байт ({item['width']} × {item['height']}), "
f"SHA-256 `{item['sha256'][:16]}…`"
for name, item in bodies.items()
),
f"- Реплика {profile['api_cpus']} CPU / {profile['api_memory']} без swap, "
f"буфер приёма `{meta.get('stand', {}).get('api_tcp_rmem', '—')}`; S3 "
f"{profile['s3_cpus']} CPU / {profile['s3_memory']}; «без лимита» — "
+ ", ".join(f"`{k}={v}`" for k, v in profile["unlimited_env"]),
"- Пик — `memory.peak` cgroup, сброшенный своим дескриптором после "
"разогрева (`peak_source` = reset); без сброса — наибольшая выборка "
f"раз в {profile['sample_interval_s']:g} с (`peak_sampled`). «До окна» — "
"первая выборка. Ответы по кодам и задержки — загрузки, начатые в окне. "
"Значения — медиана (min–max) повторов. Пик S3 включает страничный кэш "
"записанных объектов и упирается в лимит; память самого шлюза — `anon`",
"",
"## Ячейки",
"",
"| Вариант | Тело | C | Пик старта, MiB | До окна, MiB | Пик, MiB | anon, MiB "
"| sock, MiB | OOM | 201 | 429 | 5xx | прочие | Загрузок/с | p50, мс | "
"p95, мс | S3 пик / anon, MiB | LB пик, MiB | Пометки |",
"|---|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|"
"---:|---:|---:|---|",
]
grouped = cells(rows)
for (variant, size, clients), items in sorted(
grouped.items(), key=lambda kv: (kv[0][0], kv[0][1], kv[0][2])
):
flags = sorted({f for r in items for f in str(r.get("flags") or "").split()})
lines.append(
f"| {VARIANT_NAMES.get(variant, variant)} | {size} | {clients} | "
f"{spread(r['start_peak_mib'] for r in items)} | "
f"{spread(r['mem_before_mib'] for r in items)} | "
f"{spread(r['peak_mib'] for r in items)} | "
f"{spread(r['anon_max_mib'] for r in items)} | "
f"{spread(r['sock_max_mib'] for r in items)} | "
f"{sum(is_oom(r) for r in items)}/{len(items)} | "
f"{spread((r['ok'] for r in items), 0)} | "
f"{spread((r['rejected_429'] for r in items), 0)} | "
f"{spread((r['errors_5xx'] for r in items), 0)} | "
f"{spread((r['other_errors'] for r in items), 0)} | "
f"{spread((r['uploads_per_s'] for r in items), 2)} | "
f"{spread((r['p50_ms'] for r in items), 0)} | "
f"{spread((r['p95_ms'] for r in items), 0)} | "
f"{spread(r['s3_peak_mib'] for r in items)} / "
f"{spread(r['s3_anon_max_mib'] for r in items)} | "
f"{spread(r['lb_peak_mib'] for r in items)} | {' '.join(flags) or '—'} |"
)
lines += [
"",
"## Гипотезы",
"",
"Тексты и пороги — `REPORT.md`, «Память загрузок: гипотезы» (записаны до "
f"замеров); большое тело — `{big}`, лимит памяти реплики {limit_mib:g} MiB.",
"",
"| Гипотеза | Итог | Числа |",
"|---|---|---|",
]
lines += [
f"| {v.hypothesis} | {v.result} | {v.numbers} |"
for v in verdicts(rows, limit_mib=limit_mib, big=big)
]
warnings = meta.get("host_warnings") or []
if warnings:
lines += ["", "## Предупреждения о хосте", "", *(f"- {w}" for w in warnings)]
return "\n".join(lines) + "\n"
# --- самопроверка ------------------------------------------------------------------
def selftest() -> None:
plan = plan_runs(VARIANTS, ("1mib", "10mib"), (1, 10), 2, 5)
assert [p["order"] for p in plan] == list(range(1, 17))
assert plan[7]["run"] != plan[8]["run"]
assert len({p["run"] for p in plan}) == 16
lines = [
{"start": {"api": 300 * MIB, "s3": None}, "reset": {"api": True, "s3": False}},
{"ts": 1.0, "pk": {"api": [100 * MIB, 50 * MIB, 1 * MIB, 0], "s3": None}},
{"ts": 1.2, "pk": {"api": [180 * MIB, 120 * MIB, 3 * MIB, 0], "s3": None}},
{"ts": 1.4, "pk": {"api": [150 * MIB, 90 * MIB, 2 * MIB, 1], "s3": None}},
{"ts": 1.6, "peak": {"api": 200 * MIB}, "end": True},
]
peaks = parse_peak(lines)
api = peaks["api"]
assert (api.start_peak, api.window_peak) == (300 * MIB, 200 * MIB)
assert (api.first_current, api.max_sock) == (100 * MIB, 3 * MIB)
assert (api.oom_kills, api.source) == (1, "reset")
assert (peaks["s3"].missing, peaks["s3"].source) == (3, "sampled")
run = {"run": "limited-10mib-c10-r1", "variant": "limited", "size": "10mib"}
run |= {"clients": 10, "repeat": 1, "order": 1}
result = {"ok": 40, "rejected_429": 0, "errors_5xx": 0, "statuses": {"201": 40}}
row = run_row(
run,
body_bytes=10 * MIB,
peaks=peaks,
result=result,
state={"oom_killed": False, "exit_code": 0, "running": True},
swapouts=0,
)
assert (row["peak_mib"], row["mem_before_mib"]) == (200.0, 100.0)
assert row["flags"] == "oom", row["flags"]
assert set(row) <= set(RUN_COLUMNS), set(row) - set(RUN_COLUMNS)
assert per_client_bodies(row) == 1.0
rows = []
for clients, peak in ((10, 100.0), (20, 105.0), (40, 125.0)):
rows.append(
{
"variant": "limited",
"size": "10mib",
"clients": clients,
"body_bytes": 10 * MIB,
"peak_mib": peak,
"mem_before_mib": 80.0,
"errors_5xx": 0,
"rejected_429": 0 if clients <= 20 else 7,
"uploads_per_s": 4.0,
"flags": "",
},
)
rows.append(dict(rows[0], variant="unlimited", peak_mib=200.0, uploads_per_s=4.1))
rows.append(dict(rows[2], variant="unlimited", flags="oom"))
result_by = {
v.hypothesis: v.result for v in verdicts(rows, limit_mib=512, big="10mib")
}
assert result_by == {
"U1": CONFIRMED,
"U2": CONFIRMED,
"U3": CONFIRMED,
"U4": CONFIRMED,
}, result_by
rows[2]["peak_mib"] = 400.0
assert verdicts(rows, limit_mib=512, big="10mib")[0].result == REFUTED
print("uploads selftest: ok")
if __name__ == "__main__":
if sys.argv[1:] == ["--selftest"]:
selftest()
else:
raise SystemExit("usage: uv run python bench/uploads.py --selftest")
+399
View File
@@ -0,0 +1,399 @@
# Стенд лабы 4: HAProxy — единственная точка входа API, за ним
# API_REPLICAS реплик; PostgreSQL (источник истины: данные, сессии, ключи
# идемпотентности, метаданные вложений), Valkey (общий кэш карточек
# чатов), S3 — SeaweedFS (байты вложений в приватном bucket), одноразовые
# миграции и bootstrap S3, уборщик незавершённых загрузок и сверка bucket
# и БД. Значения ${...} compose берёт из .env (шаблон .env.example, `make
# env`). Порты публикуются только на 127.0.0.1; внутри сети стенда порты
# фиксированы: 5432, 6379, 8080, 8333 (API S3), мониторинг LB — 8404.
# Правила — infra/AGENTS.md; запуск — `make up`.
#
# Имя проекта меняется в каждой лабе: от него зависят имена volume, и
# стенд лабы 4 не подключается к данным лабы 3.
name: vladimirceva-lab4
# окружение по сервисам: секреты получают только те, кому они нужны.
# PostgreSQL — api, cleaner и migrate
x-db-env: &db-env
LOG_LEVEL: ${LOG_LEVEL:-INFO}
DB_HOST: postgres
DB_PORT: "5432"
DB_NAME: ${POSTGRES_DB:?POSTGRES_DB is not set, run make env}
DB_USER: ${POSTGRES_USER:?POSTGRES_USER is not set, run make env}
DB_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is empty, run make env}
# Valkey — только api
x-cache-env: &cache-env
CACHE_HOST: valkey
CACHE_PORT: "6379"
CACHE_PASSWORD: ${VALKEY_PASSWORD:?VALKEY_PASSWORD is empty, run make env}
# S3 — api и cleaner: адрес в сети и bucket. Ключи — у каждого своего
# пользователя S3 (не административные): административная пара — только
# у s3, ключ подписи служебных вызовов — у s3 и s3-bootstrap
x-s3-env: &s3-env
S3_ENDPOINT: http://s3:8333
S3_BUCKET: ${S3_BUCKET:-messenger-attachments}
# образ сервера S3 и bootstrap: тег с версией и digest индекса (amd64 и
# arm64)
x-s3-image: &s3-image chrislusf/seaweedfs:4.48@sha256:4e61d15fd35994cb1e43e1e553dff106794841fd9a99ade2fc8c8bfce4d7872d
# ужесточение контейнеров приложения: файловая система только для
# чтения, без capabilities и повышения привилегий
x-hardened: &hardened
read_only: true
cap_drop:
- ALL
security_opt:
- no-new-privileges:true
services:
postgres:
image: postgres:18.6-trixie@sha256:5a5a84b19854a9ffaa54082c166ff4ec27473a361e496e5ea167f298f2da9722
restart: unless-stopped
environment:
POSTGRES_USER: ${POSTGRES_USER:?POSTGRES_USER is not set, run make env}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is empty, run make env}
POSTGRES_DB: ${POSTGRES_DB:?POSTGRES_DB is not set, run make env}
ports:
# только localhost: к нему подключается `make run` и миграции с
# хоста. API наружу так не публикуется — только через LB
- "127.0.0.1:${POSTGRES_HOST_PORT:-5433}:5432"
volumes:
# Postgres 18 хранит данные в /var/lib/postgresql/18/docker; volume
# образа — весь /var/lib/postgresql (Config.Volumes)
- pgdata:/var/lib/postgresql
healthcheck:
# по TCP, а не через сокет: при инициализации образ поднимает
# временный сервер только на сокете, и проверка через сокет
# сказала бы «готов» раньше времени. $$ — переменная контейнера
test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U \"$$POSTGRES_USER\" -d \"$$POSTGRES_DB\""]
interval: 5s
timeout: 3s
retries: 10
start_period: 30s
start_interval: 1s
deploy:
resources:
limits:
# соединения: API_REPLICAS × (DB_POOL_SIZE + DB_POOL_OVERFLOW) +
# migrate + cleaner (пул 1) ≤ max_connections (100): 2 × 15 + 1 +
# 1 = 32, при поочерёдной замене 3 × 15 + 1 + 1 = 47 (REPORT.md,
# «Лимиты и пулы»)
cpus: "2.0"
memory: 1G
# кэш карточек чатов: volume нет, persistence выключен в valkey.conf —
# после рестарта кэш пуст, данные остаются в PostgreSQL
valkey:
image: valkey/valkey:9.1.2-trixie@sha256:418652cfb58ef879d4978c33553735d7147016032d5aefaa14c828e611eb9dfd
restart: unless-stopped
# $$ — переменная контейнера: пароля нет в command литералом. Через
# docker-entrypoint.sh образа: он запускает сервер не от root
command:
- sh
- -c
- exec docker-entrypoint.sh valkey-server /usr/local/etc/valkey/valkey.conf --requirepass "$$VALKEY_PASSWORD"
environment:
VALKEY_PASSWORD: ${VALKEY_PASSWORD:?VALKEY_PASSWORD is empty, run make env}
# пароль для valkey-cli в контейнере (healthcheck), без -a в команде
VALKEYCLI_AUTH: ${VALKEY_PASSWORD:?VALKEY_PASSWORD is empty, run make env}
ports:
# только localhost: к нему подключается `make run`
- "127.0.0.1:${VALKEY_HOST_PORT:-6380}:6379"
volumes:
- type: bind
source: ./infra/valkey/valkey.conf
target: /usr/local/etc/valkey/valkey.conf
read_only: true
bind:
create_host_path: false
healthcheck:
# PONG только после AUTH: проверяет и запуск, и пароль
test: ["CMD-SHELL", 'test "$$(valkey-cli ping)" = PONG']
interval: 5s
timeout: 3s
retries: 10
start_period: 10s
start_interval: 1s
deploy:
resources:
limits:
# maxmemory 64mb в valkey.conf плюс накладные
cpus: "0.5"
memory: 128M
# S3 — байты вложений (infra/AGENTS.md, «S3»): master, volume, filer и
# шлюз S3 одним процессом weed server. Служебные серверы слушают только
# 127.0.0.1 контейнера, в сеть выходят API S3 (8333) и gRPC шлюза
# (18333), закрытый ключом подписи. Entrypoint образа сам переходит на
# пользователя seaweed и добавляет -dir=/data
s3:
image: *s3-image
restart: unless-stopped
command:
- server
# master, volume и filer — только loopback контейнера
- -ip=127.0.0.1
- -ip.bind=127.0.0.1
# по умолчанию master шлёт статистику на telemetry.seaweedfs.com
- -master.telemetry=false
# узел один, выборам ждать некого: перезапуск до healthy ~7 с, а не ~24
- -master.electionTimeout=1s
# пауза перед остановкой тома нужна кластеру, а не одному узлу
- -volume.preStopSeconds=0
- -filer
- -s3
- -s3.ip.bind=0.0.0.0
- -s3.port=8333
# REST Catalog и Lance по умолчанию открыты на 8181 и 9101
- -s3.port.iceberg=0
- -s3.port.lance=0
# встроенный IAM API на порту S3 не нужен: bootstrap — weed shell
- -s3.iam=false
# шлюз держит не больше 64 МБ загрузок одновременно, лишние ждут
- -s3.concurrentUploadLimitMB=64
environment:
# административная пара: учётная запись есть с первого старта, и
# анонимного окна нет. Только у сервера: ни API, ни bootstrap её не
# получают
AWS_ACCESS_KEY_ID: ${S3_ROOT_ACCESS_KEY:?S3_ROOT_ACCESS_KEY is empty, run make env}
AWS_SECRET_ACCESS_KEY: ${S3_ROOT_SECRET_KEY:?S3_ROOT_SECRET_KEY is empty, run make env}
# без ключа подписи gRPC шлюза принимает учётную запись
# администратора от любого контейнера сети
WEED_JWT_FILER_SIGNING_KEY: ${S3_JWT_SIGNING_KEY:?S3_JWT_SIGNING_KEY is empty, run make env}
# сборщик мусора Go чаще у предела: вместе с лимитом загрузок шлюза
# 20 одновременных PUT по 10 MiB укладываются в 512 МБ
GOMEMLIMIT: 400MiB
ports:
# только localhost и только API S3: проверки приватности с хоста
# (make s3-check) и make run; консоль, UI и служебные серверы не
# публикуются
- "127.0.0.1:${S3_HOST_PORT:-8334}:8333"
volumes:
# volume образа (Config.Volumes): тома, filer и IAM
- s3data:/data
healthcheck:
# master выбран, том зарегистрирован у master (непустой DataNodes),
# filer и шлюз S3 отвечают; всё на loopback. Без проверки тома healthy
# наступает на ~4 с раньше регистрации, и первая запись ждала бы её
# почти весь срок вызова клиента
test: ["CMD-SHELL", "wget -q -O /dev/null http://127.0.0.1:9333/cluster/healthz && wget -q -O - http://127.0.0.1:9333/dir/status | grep -qF '\"DataNodes\":[{' && wget -q -O /dev/null http://127.0.0.1:8888/healthz && wget -q -O /dev/null http://127.0.0.1:8333/healthz"]
interval: 5s
timeout: 3s
retries: 10
start_period: 30s
start_interval: 1s
# плавная остановка ~15 с: срок ожидания подписок filer зашит в код. При
# 10 с остановка кончалась бы SIGKILL (код 137)
stop_grace_period: 20s
deploy:
resources:
limits:
cpus: "1.0"
memory: 512M
# bootstrap S3 — один раз до реплик, как миграции: приватный bucket,
# пользователь API («объекты своего bucket»), пользователь уборщика
# («чтение и удаление объектов и список по префиксу вложений своей
# базы»), проверки приватности. Повтор сводит состояние к .env и ничего
# не ломает. В сетевом пространстве s3: master и filer на 127.0.0.1
# сервера ему доступны, а в сети их нет. make s3-check запускает его же
# в режиме check
s3-bootstrap:
image: *s3-image
network_mode: service:s3
user: seaweed
entrypoint: ["sh", "/opt/s3/bootstrap.sh"]
command: ["apply"]
restart: "no"
environment:
S3_BUCKET: ${S3_BUCKET:-messenger-attachments}
# ключ подписи: им weed shell подписывает вызовы IAM filer
WEED_JWT_FILER_SIGNING_KEY: ${S3_JWT_SIGNING_KEY:?S3_JWT_SIGNING_KEY is empty, run make env}
S3_API_ACCESS_KEY: ${S3_API_ACCESS_KEY:?S3_API_ACCESS_KEY is empty, run make env}
S3_API_SECRET_KEY: ${S3_API_SECRET_KEY:?S3_API_SECRET_KEY is empty, run make env}
S3_CLEANER_ACCESS_KEY: ${S3_CLEANER_ACCESS_KEY:?S3_CLEANER_ACCESS_KEY is empty, run make env}
S3_CLEANER_SECRET_KEY: ${S3_CLEANER_SECRET_KEY:?S3_CLEANER_SECRET_KEY is empty, run make env}
# список уборщику — только по префиксу вложений своей базы; не
# секрет: уборщик строит тот же префикс сам из имени базы
S3_CLEANER_LIST_PREFIX: ${POSTGRES_DB:?POSTGRES_DB is not set, run make env}/attachments/
HOME: /tmp
volumes:
- type: bind
source: ./infra/s3/bootstrap.sh
target: /opt/s3/bootstrap.sh
read_only: true
bind:
create_host_path: false
# файл ключа для curl и политика — только в памяти. /data — volume
# образа: без tmpfs каждый новый контейнер bootstrap оставлял бы
# анонимный volume
tmpfs:
- /tmp
- /data
depends_on:
s3:
condition: service_healthy
deploy:
resources:
limits:
cpus: "0.5"
memory: 128M
# миграции до старта реплик: тот же образ, другая команда. Один раз на
# `up`, реплики ждут его завершения; сами реплики миграции не запускают
# (их несколько — они гонялись бы за одну схему). Повторный запуск —
# no-op: alembic применяет только недостающие ревизии
migrate:
image: mtusi-messenger-vladimirceva:lab4
# образ собирает сервис api (make up, make docker-build)
pull_policy: never
command: ["python", "-m", "alembic", "upgrade", "head"]
restart: "no"
# только PostgreSQL: пароль Valkey и ключи S3 миграциям не нужны
environment: *db-env
<<: *hardened
depends_on:
postgres:
condition: service_healthy
deploy:
resources:
limits:
cpus: "0.5"
memory: 256M
# реплики API: портов наружу нет, фиксированного имени контейнера нет
# (оба мешали бы масштабированию одного сервиса) — запросы идут только
# через haproxy. X-Instance-Id — hostname, то есть короткий ID
# контейнера. Разовая подмена числа — `make replicas API_REPLICAS=N`
api:
build: .
# тот же тег, что у make docker-build
image: mtusi-messenger-vladimirceva:lab4
restart: unless-stopped
environment:
<<: [*db-env, *cache-env, *s3-env]
# пользователь API в S3: чтение, запись и удаление объектов своего
# bucket; списка и прав на bucket нет
S3_ACCESS_KEY_ID: ${S3_API_ACCESS_KEY:?S3_API_ACCESS_KEY is empty, run make env}
S3_SECRET_ACCESS_KEY: ${S3_API_SECRET_KEY:?S3_API_SECRET_KEY is empty, run make env}
SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600}
IDEMPOTENCY_TTL_SECONDS: ${IDEMPOTENCY_TTL_SECONDS:-86400}
SHUTDOWN_TIMEOUT: ${SHUTDOWN_TIMEOUT:-5}
<<: *hardened
# приложение ничего не пишет на диск, кроме временных файлов Python
tmpfs:
- /tmp
depends_on:
postgres:
condition: service_healthy
# без кэша API работает, но в штатном стенде он есть с первого запроса
valkey:
condition: service_healthy
migrate:
condition: service_completed_successfully
# bucket и пользователь API есть до первого запроса
s3-bootstrap:
condition: service_completed_successfully
# healthcheck — из образа; SIGKILL не раньше, чем через 10 с после
# SIGTERM (uvicorn завершается сам за SHUTDOWN_TIMEOUT ≤ 9 с)
stop_grace_period: 10s
# буфер приёма сокетов реплики — до 512 KiB, а не до 32 MiB ВМ Docker:
# ядро копит недочитанное тело (ожидание места загрузки, отказ до
# тела) в буфере сокета, и он считается памятью контейнера. Получают
# все контейнеры сервиса, в том числе стенды тестов и bench/
sysctls:
net.ipv4.tcp_rmem: "4096 131072 524288"
deploy:
replicas: ${API_REPLICAS:-2}
resources:
limits:
# один процесс, один event loop: больше одного CPU он не займёт,
# кроме Argon2id входа в потоках (под лимитом вход медленнее).
# Память: Argon2id 4 × 64 MiB + интерпретатор + места загрузок
# (4 × тело до 10 MiB)
cpus: "1.0"
memory: 512M
# уборщик незавершённых загрузок и сверка bucket и БД: один процесс на
# образе API со своей точкой входа. Реплики его не ждут, сам он ждёт
# схему и пользователя S3. Портов нет, HTTP не слушает. Разовый проход —
# docker compose run --rm --no-deps cleaner --once, сверка — make reconcile
cleaner:
image: mtusi-messenger-vladimirceva:lab4
pull_policy: never
# точка входа, а не command: аргументы `docker compose run cleaner …`
# — флаги уборщика, а не замена команды
entrypoint: ["python", "-m", "src.cleaner"]
restart: unless-stopped
environment:
<<: [*db-env, *s3-env]
# проход последовательный: второе соединение не нужно
DB_POOL_SIZE: "1"
DB_POOL_OVERFLOW: "0"
# пользователь уборщика: чтение, удаление и список по префиксу; ключей
# API, пароля Valkey и административных ключей S3 нет
S3_ACCESS_KEY_ID: ${S3_CLEANER_ACCESS_KEY:?S3_CLEANER_ACCESS_KEY is empty, run make env}
S3_SECRET_ACCESS_KEY: ${S3_CLEANER_SECRET_KEY:?S3_CLEANER_SECRET_KEY is empty, run make env}
<<: *hardened
tmpfs:
- /tmp
depends_on:
postgres:
condition: service_healthy
migrate:
condition: service_completed_successfully
s3-bootstrap:
condition: service_completed_successfully
# healthcheck образа — HTTP /health/ready, а уборщик HTTP не слушает.
# Живость — журнал: старт, проходы, отказы
healthcheck:
disable: true
# SIGTERM: текущий шаг доводится (≤ 6 с), затем выход с кодом 0
stop_grace_period: 10s
deploy:
resources:
limits:
cpus: "0.25"
memory: 256M
# единственная точка входа: реплики находит через DNS Docker, проверяет
# /health/ready; конфиг — infra/haproxy/haproxy.cfg. Секретов не получает
haproxy:
image: haproxy:3.4.6-trixie@sha256:e273915691a8eab3f105bf3e39fd4c29a4ecf334e33421903b5589d25e14db26
restart: unless-stopped
ports:
# только localhost: стенд учебный; API с хоста доступно только так
- "127.0.0.1:${HOST_PORT:-8080}:8080"
volumes:
- type: bind
source: ./infra/haproxy/haproxy.cfg
target: /usr/local/etc/haproxy/haproxy.cfg
read_only: true
bind:
create_host_path: false
<<: *hardened
# make stop гасит LB раньше реплик, make up поднимает после них
depends_on:
- api
healthcheck:
# healthy — через LB можно обслужить запрос: /lb/ready отвечает 200,
# пока есть хотя бы одна готовая реплика. curl в образе нет, bash есть
test: ["CMD", "bash", "-c", "exec 3<>/dev/tcp/127.0.0.1/8404 && printf 'GET /lb/ready HTTP/1.0\\r\\n\\r\\n' >&3 && head -n 1 <&3 | grep -q ' 200 '"]
interval: 5s
timeout: 3s
retries: 3
start_period: 10s
start_interval: 1s
deploy:
resources:
limits:
# nbthread 1 в haproxy.cfg
cpus: "1.0"
memory: 256M
volumes:
pgdata:
s3data:
+67
View File
@@ -0,0 +1,67 @@
# evidence/ — доказательства для REPORT.md
Требования преподавателя — `evidence/README.md` (skeleton, не менять).
Каждый файл здесь — подтверждение строки таблицы «Доказательства
критериев» в `REPORT.md`. Доказательства лабы 3 остались в её
репозитории: сюда они не копируются даже по одному файлу — всё снято
заново на стенде лабы 4.
## Правила
- **Только реальный вывод** команд, которые ты сам запустил в этой
задаче. Не дописывать «ожидаемый» результат, не править числа, не
склеивать выводы разных прогонов без пометки. Нечем проверить (нет
docker, сети) — не создавать файл, а сказать пользователю.
- Шапка файла — комментарии `#`: что доказывает (критерий рубрики), дата
UTC, окружение (ОС, CPU, версии Docker, Compose, Python), стенд
(рабочий `make up` и его порт, отдельный стенд тестов), код
(`src_sha256` — хеш `src/` и `migrations/`, как в паспорте `bench/`;
commit, если проект под git). Как повторить — команды.
- Команда — строкой `$ ...`, под ней вывод. Длинный вывод можно
сокращать с пометкой `...`, но не менять строки, на которые ссылается
отчёт.
- Итог — комментарием `#` после вывода: что именно видно и почему это
закрывает критерий.
- Без секретов, токенов, ключей S3, `.env`, реальных данных и текстов
сообщений; абсолютные пути домашнего каталога — `<репозиторий>`.
Значения переменных окружения контейнеров не печатать — только имена.
- Файл пишется инструментом правки (`apply_patch`), а не перенаправлением
`>` из shell: так правку видно в диффе.
## Состав
Сняты на машине разработки (без нагрузки), 23 октября 2026:
| Файл | Критерий |
|---|---|
| `stand/stand.txt` | стенд: HAProxy — единственный порт API, ≥ 2 реплики без портов, S3 только на loopback и только API S3, консоль и служебные порты не опубликованы, лимиты у всех, секреты и ключи S3 только у своих сервисов |
| `stand/migrations.txt` | миграции `0001 → 0003` с нуля, повтор — no-op, `alembic check`, схема `attachments` и `message_attachments` |
| `stand/persistence.txt` | `make test-persistence ACTION_SCRIPT=scripts/restart.sh`: данные, токен и оригинал вложения после рестарта LB, реплик, PostgreSQL, Valkey и S3 с теми же volume |
| `s3/bootstrap.txt` | bootstrap S3: первый запуск, повтор (идемпотентно), пользователи API и уборщика, проверки приватности |
| `s3/privacy.txt` | `make s3-check`: приватность bucket вне API (анонимно с хоста и из сети стенда, права ключей API и уборщика, открытые порты контейнера S3) |
| `attachments/failover.txt` | `make attachment-failover`: загрузка через LB, остановка принявшей реплики, скачивание через другую — тот же SHA-256, посторонний — 404 |
| `attachments/smoke.txt` | публичный smoke лабы 4 через LB рабочего стенда |
| `reconcile/working-stand.txt` | разовая сверка на рабочем стенде (dry-run и `APPLY=1`), плановая сверка при старте уборщика, проход уборки |
| `tests/test-isolated.txt` | smoke, свои тесты через LB с тестами реплик, вложение после остановки принявшей реплики, `test-failover`, `test-persistence` на отдельном стенде |
| `tests/student-test-lb.txt` | свои тесты через LB рабочего стенда |
| `tests/failure-checks.txt` | проверки отказов (`-rP`, с числами): S3 остановлен и заморожен, компенсация, обрыв между PUT и `ready`, уборщик, места загрузок и 429, срок тела, сверка с обеих сторон под загрузками |
Снимает Codex на машине замеров (`bench/RUNBOOK.md`):
| Каталог | Критерий |
|---|---|
| `uploads/<метка>/` | уровень 4: ≥ 10 одновременных загрузок, пик памяти реплики (`make bench-uploads`) |
| `reconcile/<метка>/` | трек 2: стоимость обхода сверки (`make bench-reconcile`) |
Поменялось поведение, которое показано в файле, — перезапусти проверку
и обнови файл целиком, вместе с датой в шапке.
## Каталоги меток — исключение из правил выше
`uploads/<метка>/`, `reconcile/<метка>/` (и профилей лабы 3:
`failover/`, `rollout/`, `scaling/`, `compare/`, `plots/`) пишут стенд и
его скрипты (`make bench-*`): руками их не править и не создавать, шапку
и паспорт стенд ставит сам. Каталог метки не перезаписывается и не
удаляется без согласия пользователя. Метки `quick-*` — самопроверки, в
git и отчёт не идут. Правила — `bench/AGENTS.md`, порядок —
`bench/RUNBOOK.md`.
+96
View File
@@ -0,0 +1,96 @@
# Что доказывает: уровень 3 — «upload → остановка обслужившей
# API-реплики → download через другую возвращает тот же файл»; сценарий
# защиты, пп. 1–2 (SHA-256 у второго участника, 404 постороннему для
# метаданных и байтов). Оригинал — не на диске реплики: его отдаёт
# другая реплика из S3.
# Дата: 2026-10-23T16:42:47Z и 16:43:03Z (UTC)
# Окружение: macOS 26.6.2, Apple M3 Pro; ВМ Docker 12 CPU / 7,7 ГиБ;
# Docker 29.9.2, Compose 5.6.1; python3 хоста 3.11.9.
# Стенд: рабочий (`make up`, проект vladimirceva-lab4), HAProxy
# 127.0.0.1:8180 (порт из .env), 2 реплики.
# Код: src_sha256 bc10d566e2f63173541445a2f6273b967447e13e5dd7f1fb76900934e5692cbe.
# Как повторить: make attachment-failover [STOP_MODE=kill]
# (BASE_URL=http://localhost:<HOST_PORT>, если порт не 8080)
#
# Сценарий (scripts/lab4.py attachment-failover): alice загружает
# tests/fixtures/sample.png через LB и отправляет сообщение с вложением в
# чат с bob; реплика, принявшая загрузку, — по X-Instance-Id ответа;
# scripts/stop-one.sh останавливает именно её (STOP_ONE_LOG); bob
# скачивает оригинал через LB — ответ другой реплики, SHA-256 сверяется с
# фикстурой; eve (не участник) — 404 на метаданные и байты; затем
# make replicas возвращает остановленную реплику.
$ make attachment-failover BASE_URL=http://localhost:8180
python3 scripts/lab4.py attachment-failover --base-url "http://localhost:8180" \
--replicas 2 --mode stop
upload: 201 X-Instance-Id=fb8be4112529 size=111817 sha256=99ea7533c441f79c… (fixture 99ea7533c441f79c…)
message with attachment: 201 attachment_ids=['87c4f989-1515-4d0b-9bb7-19493ead7dbc']
=== docker compose ps before
NAME CONTAINER ID STATE STATUS
vladimirceva-lab4-api-1 fb8be4112529 running Up 22 seconds (healthy)
vladimirceva-lab4-api-2 9251f26b17c2 running Up 2 minutes (healthy)
vladimirceva-lab4-cleaner-1 c2206a081b48 running Up 2 minutes
vladimirceva-lab4-haproxy-1 db93a92d9c9f running Up 2 minutes (healthy)
vladimirceva-lab4-migrate-1 6db418eeeba1 exited Exited (0) 2 minutes ago
vladimirceva-lab4-postgres-1 6f5bb1b06af0 running Up 2 minutes (healthy)
vladimirceva-lab4-s3-1 8c8e8394de9c running Up 2 minutes (healthy)
vladimirceva-lab4-s3-bootstrap-1 4e5e32b7a144 exited Exited (0) About a minute ago
vladimirceva-lab4-valkey-1 74ae147278b7 running Up 2 minutes (healthy)
$ TARGET_INSTANCE_ID=fb8be4112529 STOP_MODE=stop scripts/stop-one.sh
exit 0; STOP_ONE_LOG: 2026-10-23T16:42:49Z TARGET_INSTANCE_ID=fb8be4112529 container=fb8be41125292eb2bf6e4fa4939667b00d4a1bec119a87a9637ecb7df2cbd364 mode=stop
download by bob after stop: 200 X-Instance-Id=9251f26b17c2 after 0.53s, bytes=111817, sha256 == fixture, content-type=image/png
outsider GET /attachments/{id}: 404
outsider GET /attachments/{id}/content: 404
=== docker compose ps after
NAME CONTAINER ID STATE STATUS
vladimirceva-lab4-api-1 fb8be4112529 exited Exited (0) Less than a second ago
vladimirceva-lab4-api-2 9251f26b17c2 running Up 2 minutes (healthy)
vladimirceva-lab4-cleaner-1 c2206a081b48 running Up 2 minutes
vladimirceva-lab4-haproxy-1 db93a92d9c9f running Up 2 minutes (healthy)
vladimirceva-lab4-migrate-1 6db418eeeba1 exited Exited (0) 2 minutes ago
vladimirceva-lab4-postgres-1 6f5bb1b06af0 running Up 2 minutes (healthy)
vladimirceva-lab4-s3-1 8c8e8394de9c running Up 2 minutes (healthy)
vladimirceva-lab4-s3-bootstrap-1 4e5e32b7a144 exited Exited (0) About a minute ago
vladimirceva-lab4-valkey-1 74ae147278b7 running Up 2 minutes (healthy)
replicas restored:
NAME CONTAINER ID STATE STATUS
vladimirceva-lab4-api-1 fb8be4112529 running Up 2 seconds (healthy)
vladimirceva-lab4-api-2 9251f26b17c2 running Up 2 minutes (healthy)
vladimirceva-lab4-cleaner-1 c2206a081b48 running Up 2 minutes
vladimirceva-lab4-haproxy-1 db93a92d9c9f running Up 2 minutes (healthy)
vladimirceva-lab4-migrate-1 6db418eeeba1 exited Exited (0) 2 minutes ago
vladimirceva-lab4-postgres-1 6f5bb1b06af0 running Up 2 minutes (healthy)
vladimirceva-lab4-s3-1 8c8e8394de9c running Up 2 minutes (healthy)
vladimirceva-lab4-s3-bootstrap-1 4e5e32b7a144 exited Exited (0) About a minute ago
vladimirceva-lab4-valkey-1 74ae147278b7 running Up 2 minutes (healthy)
PASS
# Тот же сценарий без graceful (docker kill); строки ps до остановки и
# после возврата — как выше, сокращены:
$ make attachment-failover BASE_URL=http://localhost:8180 STOP_MODE=kill
upload: 201 X-Instance-Id=fb8be4112529 size=111817 sha256=99ea7533c441f79c… (fixture 99ea7533c441f79c…)
message with attachment: 201 attachment_ids=['f0c91d44-864a-488e-89dd-dba636be5023']
...
$ TARGET_INSTANCE_ID=fb8be4112529 STOP_MODE=kill scripts/stop-one.sh
exit 0; STOP_ONE_LOG: 2026-10-23T16:43:04Z TARGET_INSTANCE_ID=fb8be4112529 container=fb8be41125292eb2bf6e4fa4939667b00d4a1bec119a87a9637ecb7df2cbd364 mode=kill
download by bob after stop: 200 X-Instance-Id=9251f26b17c2 after 0.53s, bytes=111817, sha256 == fixture, content-type=image/png
outsider GET /attachments/{id}: 404
outsider GET /attachments/{id}/content: 404
=== docker compose ps after
NAME CONTAINER ID STATE STATUS
vladimirceva-lab4-api-1 fb8be4112529 exited Exited (137) Less than a second ago
vladimirceva-lab4-api-2 9251f26b17c2 running Up 2 minutes (healthy)
...
PASS
# Итог: в обоих режимах остановлена именно принявшая загрузку реплика
# (ID в STOP_ONE_LOG = X-Instance-Id ответа загрузки, exited 0 / 137),
# оригинал отдала другая реплика (9251f26b17c2) с тем же SHA-256 и
# размером, что у фикстуры; посторонний получает 404 и на метаданные, и
# на байты. 0,53 с до первого 200 — слот остановленной реплики ещё UP в
# LB: запрос на её адрес ждёт timeout connect 0,5 с и уходит повтором
# (retry-on conn-failure, redispatch) на другую реплику — клиент ошибки
# не видит. Тот же сценарий на отдельном стенде — tests/test-isolated.txt.
+18
View File
@@ -0,0 +1,18 @@
# Что доказывает: уровень 3 — публичный smoke лабы 4 через LB рабочего
# стенда: вложение tests/fixtures/sample.png загружается (201 ready),
# сообщение с attachment_ids читается участниками, скачанный оригинал
# совпадает по SHA-256, посторонний получает 404 (tests/smoke.py).
# Дата: 2026-10-23T16:41Z (UTC)
# Окружение: macOS 26.6.2, Apple M3 Pro; Docker 29.9.2, Compose 5.6.1;
# python3 хоста 3.11.9.
# Стенд: рабочий (`make up`, проект vladimirceva-lab4), HAProxy
# 127.0.0.1:8180 (порт из .env), 2 реплики.
# Код: src_sha256 bc10d566e2f63173541445a2f6273b967447e13e5dd7f1fb76900934e5692cbe.
# Как повторить: make up; make test [BASE_URL=http://localhost:<HOST_PORT>]
$ make test BASE_URL=http://localhost:8180
python3 tests/smoke.py --base-url "http://localhost:8180"
PASS: lab4 public API scenario; infrastructure and grading evidence remain separate.
# Итог: сценарий skeleton лабы 4 проходит через LB. Проверка через
# отдельный стенд и вместе с собственными тестами — tests/test-isolated.txt.
+53
View File
@@ -0,0 +1,53 @@
# Что доказывает: трек 2 — сверка bucket и БД работает на рабочем стенде
# повторяемо: плановая сверка с исправлением при старте уборщика, разовая
# dry-run (по умолчанию), стратегия head с глубокой проверкой SHA-256,
# --apply и повтор; на согласованном стенде — ничего не найдено и ничего
# не изменено (код 0). Свежие вложения (моложе grace) глубокая не читает.
# Обнаружение и исправление внесённых расхождений с обеих сторон —
# tests/failure-checks.txt (test_reconcile_*).
# Дата: 2026-10-23T16:40–16:45Z (UTC)
# Окружение: macOS 26.6.2, Apple M3 Pro; Docker 29.9.2, Compose 5.6.1.
# Стенд: рабочий (`make up`, проект vladimirceva-lab4); к моменту проверки
# в bucket 35 оригиналов (smoke, attachment-failover, persistence).
# Код: src_sha256 bc10d566e2f63173541445a2f6273b967447e13e5dd7f1fb76900934e5692cbe.
# Как повторить: make up; docker compose logs --no-log-prefix cleaner;
# make reconcile; make reconcile STRATEGY=head DEEP=1;
# make reconcile RATE=0 MAX_CHANGES=5 APPLY=1; make cleanup-once
# Сервис уборщика при старте (`make up`): строка старта и плановая сверка
# (batch, с исправлением, предел скорости 2000 объектов/с):
$ docker compose logs --no-log-prefix cleaner
2026-10-23T16:40:35.936Z INFO src.cleaner [rid=-] cleaner started mode=service interval=60s grace=900s live_upload_bound=21s batch=100 reconcile_interval=3600s reconcile_page=1000 reconcile_max_changes=100 reconcile_rate=2000 db=postgres:5432/messenger pool=1 s3=http://s3:8333 bucket=messenger-attachments
2026-10-23T16:40:36.058Z INFO src.services.reconcile [rid=-] reconcile pass finished apply=true strategy=batch deep=false rate=2000 listed_objects=28 checked_rows=28 fresh_objects=0 fresh_rows=0 lost_known=0 found_orphan_object=0 found_stale_pending=0 found_missing_object=0 found_size_mismatch=0 found_checksum_mismatch=0 found_restored_object=0 found_foreign_object=0 fixed_cleared_lost=0 fixed_deleted_object=0 fixed_marked_lost=0 fixed_removed_pending=0 remaining=0 refused=false unlogged=0 interrupted_by=None s3_list=2 s3_head=0 s3_get=0 s3_delete=0 listed_keys=29 read_bytes=0 db_queries=3 phase_list_ms=24 phase_rows_ms=1 phase_stale_ms=1 phase_recheck_ms=0 phase_act_ms=0 cpu_ms=14 maxrss_kib=94012 took=26ms
# Разовая сверка, dry-run:
$ make reconcile
docker compose run --rm --no-deps cleaner reconcile
2026-10-23T16:44:49.064Z INFO src.cleaner [rid=-] cleaner started mode=reconcile interval=60s grace=900s live_upload_bound=21s batch=100 reconcile_interval=3600s reconcile_page=1000 reconcile_max_changes=100 reconcile_rate=2000 db=postgres:5432/messenger pool=1 s3=http://s3:8333 bucket=messenger-attachments
2026-10-23T16:44:49.260Z INFO src.services.reconcile [rid=-] reconcile pass finished apply=false strategy=batch deep=false rate=2000 listed_objects=35 checked_rows=35 fresh_objects=0 fresh_rows=0 lost_known=0 found_orphan_object=0 found_stale_pending=0 found_missing_object=0 found_size_mismatch=0 found_checksum_mismatch=0 found_restored_object=0 found_foreign_object=0 fixed_cleared_lost=0 fixed_deleted_object=0 fixed_marked_lost=0 fixed_removed_pending=0 remaining=0 refused=false unlogged=0 interrupted_by=None s3_list=2 s3_head=0 s3_get=0 s3_delete=0 listed_keys=36 read_bytes=0 db_queries=3 phase_list_ms=126 phase_rows_ms=2 phase_stale_ms=1 phase_recheck_ms=0 phase_act_ms=0 cpu_ms=38 maxrss_kib=94656 took=130ms
2026-10-23T16:44:49.264Z INFO src.cleaner [rid=-] cleaner stopped exit_code=0
# HEAD на строку и SHA-256 содержимого:
$ make reconcile STRATEGY=head DEEP=1
2026-10-23T16:45:07.048Z INFO src.services.reconcile [rid=-] reconcile pass finished apply=false strategy=head deep=true rate=2000 listed_objects=35 checked_rows=35 fresh_objects=0 fresh_rows=0 lost_known=0 found_orphan_object=0 found_stale_pending=0 found_missing_object=0 found_size_mismatch=0 found_checksum_mismatch=0 found_restored_object=0 found_foreign_object=0 fixed_cleared_lost=0 fixed_deleted_object=0 fixed_marked_lost=0 fixed_removed_pending=0 remaining=0 refused=false unlogged=0 interrupted_by=None s3_list=2 s3_head=35 s3_get=28 s3_delete=0 listed_keys=36 read_bytes=14103868 db_queries=37 phase_list_ms=194 phase_rows_ms=233 phase_stale_ms=2 phase_recheck_ms=0 phase_act_ms=0 cpu_ms=111 maxrss_kib=95340 took=429ms
2026-10-23T16:45:07.109Z INFO src.cleaner [rid=-] cleaner stopped exit_code=0
# С исправлением, без предела скорости, предел изменений 5:
$ make reconcile RATE=0 MAX_CHANGES=5 APPLY=1
2026-10-23T16:45:11.716Z INFO src.services.reconcile [rid=-] reconcile pass finished apply=true strategy=batch deep=false rate=0 listed_objects=35 checked_rows=35 fresh_objects=0 fresh_rows=0 lost_known=0 found_orphan_object=0 found_stale_pending=0 found_missing_object=0 found_size_mismatch=0 found_checksum_mismatch=0 found_restored_object=0 found_foreign_object=0 fixed_cleared_lost=0 fixed_deleted_object=0 fixed_marked_lost=0 fixed_removed_pending=0 remaining=0 refused=false unlogged=0 interrupted_by=None s3_list=2 s3_head=0 s3_get=0 s3_delete=0 listed_keys=36 read_bytes=0 db_queries=3 phase_list_ms=115 phase_rows_ms=63 phase_stale_ms=2 phase_recheck_ms=0 phase_act_ms=0 cpu_ms=36 maxrss_kib=94560 took=180ms
2026-10-23T16:45:11.720Z INFO src.cleaner [rid=-] cleaner stopped exit_code=0
# Проход уборщика незавершённых загрузок:
$ make cleanup-once
docker compose run --rm --no-deps cleaner --once
2026-10-23T16:44:53.932Z INFO src.cleaner [rid=-] cleaner started mode=once interval=60s grace=900s live_upload_bound=21s batch=100 reconcile_interval=3600s reconcile_page=1000 reconcile_max_changes=100 reconcile_rate=2000 db=postgres:5432/messenger pool=1 s3=http://s3:8333 bucket=messenger-attachments
2026-10-23T16:44:54.039Z INFO src.cleaner [rid=-] cleaner stopped exit_code=0
# Итог: на согласованном стенде все виды прохода ничего не находят и
# ничего не меняют (remaining=0, fixed_*=0, код 0) — повторный запуск
# безопасен. batch: 2 вызова LIST (проверка bucket и страница) и 3
# запроса к БД на 35 объектов; head: HEAD на каждую строку и выборка на
# каждый объект (35 HEAD, 37 запросов). Глубокая прочитала 28 из 35
# оригиналов (13,5 МиБ): 7 вложений моложе grace (900 с — загружены за
# последние минуты) не читаются и не могут стать кандидатами. Граница
# живой загрузки 21 с < grace 900 с — уборщик проверяет это при старте.
+43
View File
@@ -0,0 +1,43 @@
# Что доказывает: bootstrap S3 идемпотентен (уровень 4: «bucket bootstrap
# идемпотентен; API использует отдельные S3 credentials с ограниченными
# правами»); bucket, политики и пользователи создаются до реплик, повтор
# ничего не ломает.
# Дата: 2026-10-23T16:42Z (UTC)
# Окружение: macOS 26.6.2, Apple M3 Pro; ВМ Docker 12 CPU / 7,7 ГиБ;
# Docker 29.9.2, Compose 5.6.1; SeaweedFS chrislusf/seaweedfs:4.48@sha256:4e61d15f….
# Стенд: рабочий (`make up`, проект vladimirceva-lab4), volume s3data.
# Код: src_sha256 bc10d566e2f63173541445a2f6273b967447e13e5dd7f1fb76900934e5692cbe.
# Как повторить: make up (первый запуск на пустом volume, затем повторы при
# каждом make up); вручную — docker compose up --no-deps --exit-code-from
# s3-bootstrap s3-bootstrap
#
# Журнал контейнера s3-bootstrap хранит все его запуски: первый — на
# пустом volume при первом `make up` этого стенда (volume s3data создан
# 2026-10-23T15:55:31Z), второй — `make up` в 16:40Z после пересборки
# образа.
$ docker compose logs --no-log-prefix s3-bootstrap
s3-bootstrap: bucket messenger-attachments created
s3-bootstrap: user api created
s3-bootstrap: user cleaner created
s3-bootstrap: checks passed (api key put/get; cleaner key get/delete and list messenger/attachments/; api key list and bucket create, cleaner key put and list of the bucket, anonymous get and list denied)
s3-bootstrap: bucket messenger-attachments exists
s3-bootstrap: user api exists
s3-bootstrap: user cleaner exists
s3-bootstrap: checks passed (api key put/get; cleaner key get/delete and list messenger/attachments/; api key list and bucket create, cleaner key put and list of the bucket, anonymous get and list denied)
# Ещё один повтор вручную, при работающих репликах:
$ docker compose up --no-deps --exit-code-from s3-bootstrap s3-bootstrap
s3-bootstrap-1 | s3-bootstrap: bucket messenger-attachments exists
s3-bootstrap-1 | s3-bootstrap: user api exists
s3-bootstrap-1 | s3-bootstrap: user cleaner exists
s3-bootstrap-1 | s3-bootstrap: checks passed (api key put/get; cleaner key get/delete and list messenger/attachments/; api key list and bucket create, cleaner key put and list of the bucket, anonymous get and list denied)
s3-bootstrap-1 exited with code 0
$ docker inspect -f '{{.State.ExitCode}}' vladimirceva-lab4-s3-bootstrap-1
0
# Итог: первый запуск создал bucket и двух пользователей, повторы видят их
# (exists), сводят политики и ключи к .env и заново проверяют
# приватность — код 0, данные bucket не тронуты. Реплики и уборщик ждут
# bootstrap (depends_on: service_completed_successfully), как миграций.
# Полная проверка прав — s3/privacy.txt.
+101
View File
@@ -0,0 +1,101 @@
# Что доказывает: приватность bucket вне API (уровень 4: «есть проверка
# private bucket вне API»; «API использует отдельные S3 credentials с
# ограниченными правами»; «административная консоль не открыта в общей
# сети»; сценарий защиты, п. 2: «direct unauthenticated S3 GET не отдаёт
# объект»).
# Дата: 2026-10-23T16:41Z (UTC)
# Окружение: macOS 26.6.2, Apple M3 Pro; ВМ Docker 12 CPU / 7,7 ГиБ, ядро
# 7.0.14-linuxkit; Docker 29.9.2, Compose 5.6.1; python3 хоста 3.11.9.
# Стенд: рабочий (`make up`, проект vladimirceva-lab4). HAProxy
# 127.0.0.1:8180, API S3 127.0.0.1:8434 — порты из .env (стандартные
# 8080/8334 на этой машине заняты другим стендом).
# Код: src_sha256 bc10d566e2f63173541445a2f6273b967447e13e5dd7f1fb76900934e5692cbe
# (проект не под git).
# Как повторить: make up; make s3-check
#
# Три места проверки: bootstrap в режиме check (в сетевом пространстве
# s3, ключами пользователей API и уборщика и без ключа), хост (API S3 на
# 127.0.0.1:S3_HOST_PORT без ключа), сеть стенда (из контейнера haproxy:
# анонимные запросы и порты контейнера s3). Пробный объект
# .s3-check/probe создаётся и удаляется самой проверкой.
$ make s3-check
python3 scripts/lab4.py s3-check
$ docker compose run --rm --no-deps s3-bootstrap check
s3-bootstrap: checks passed; probe object messenger-attachments/.s3-check/probe kept for host and network checks
$ docker compose run --rm --no-deps s3-bootstrap cleanup -> exit 0
where check expected got verdict
bootstrap (loopback s3) anonymous access setting none none ok
bootstrap (loopback s3) api key put object 200 200 ok
bootstrap (loopback s3) api key get object 200 200 ok
bootstrap (loopback s3) api key head object 200 200 ok
bootstrap (loopback s3) api key get missing object 404 404 ok
bootstrap (loopback s3) api key list objects 403 403 ok
bootstrap (loopback s3) api key create bucket 403 403 ok
bootstrap (loopback s3) api key delete bucket 403 403 ok
bootstrap (loopback s3) api key get bucket policy 403 403 ok
bootstrap (loopback s3) api key put bucket policy 403 403 ok
bootstrap (loopback s3) api key get bucket acl 403 403 ok
bootstrap (loopback s3) api key put bucket acl public-read 403 403 ok
bootstrap (loopback s3) api key put object acl public-read 403 403 ok
bootstrap (loopback s3) api key put cleaner probe object 200 200 ok
bootstrap (loopback s3) cleaner key get object 200 200 ok
bootstrap (loopback s3) cleaner key head object 200 200 ok
bootstrap (loopback s3) cleaner key delete object 204 204 ok
bootstrap (loopback s3) cleaner key delete object again 204 204 ok
bootstrap (loopback s3) api key get deleted object 404 404 ok
bootstrap (loopback s3) cleaner key delete missing object 204 204 ok
bootstrap (loopback s3) cleaner key put object 403 403 ok
bootstrap (loopback s3) cleaner key list objects 403 403 ok
bootstrap (loopback s3) cleaner key list attachments prefix 200 200 ok
bootstrap (loopback s3) cleaner key list other prefix 403 403 ok
bootstrap (loopback s3) cleaner key create bucket 403 403 ok
bootstrap (loopback s3) cleaner key delete bucket 403 403 ok
bootstrap (loopback s3) cleaner key get bucket policy 403 403 ok
bootstrap (loopback s3) cleaner key put bucket policy 403 403 ok
bootstrap (loopback s3) cleaner key get bucket acl 403 403 ok
bootstrap (loopback s3) cleaner key put bucket acl public-read 403 403 ok
bootstrap (loopback s3) cleaner key put object acl public-read 403 403 ok
bootstrap (loopback s3) api key put object to other bucket 403 403 ok
bootstrap (loopback s3) api key get object from other bucket 403 403 ok
bootstrap (loopback s3) api key list other bucket 403 403 ok
bootstrap (loopback s3) api key delete other bucket 403 403 ok
bootstrap (loopback s3) cleaner key get object from other bucket 403 403 ok
bootstrap (loopback s3) cleaner key delete object in other bucket 403 403 ok
bootstrap (loopback s3) cleaner key list other bucket 403 403 ok
bootstrap (loopback s3) cleaner key delete other bucket 403 403 ok
bootstrap (loopback s3) anonymous get object 403 403 ok
bootstrap (loopback s3) anonymous head object 403 403 ok
bootstrap (loopback s3) anonymous get missing object 403 403 ok
bootstrap (loopback s3) anonymous list objects 403 403 ok
bootstrap (loopback s3) anonymous list buckets 403 403 ok
bootstrap (loopback s3) anonymous put object 403 403 ok
bootstrap (loopback s3) anonymous create bucket 403 403 ok
host 127.0.0.1 anonymous get object 403 403 ok
host 127.0.0.1 anonymous head object 403 403 ok
host 127.0.0.1 anonymous list objects 403 403 ok
host 127.0.0.1 anonymous list buckets 403 403 ok
host 127.0.0.1 anonymous put object 403 403 ok
stand network (haproxy) anonymous get object 403 403 ok
stand network (haproxy) anonymous list objects 403 403 ok
stand network (haproxy) anonymous put object 403 403 ok
stand network (haproxy) s3 port 8080 closed closed ok
stand network (haproxy) s3 port 8333 open open ok
stand network (haproxy) s3 port 8888 closed closed ok
stand network (haproxy) s3 port 9333 closed closed ok
stand network (haproxy) s3 port 18080 closed closed ok
stand network (haproxy) s3 port 18333 open open ok
stand network (haproxy) s3 port 18888 closed closed ok
stand network (haproxy) s3 port 19333 closed closed ok
stand network (haproxy) s3 port 38461 closed closed ok
checks: 63, failed: 0, bootstrap exit 0
# Итог: 63 проверки, нарушений 0. Анонимно bucket недоступен ни на
# loopback S3, ни с хоста, ни из сети стенда (403 на GET, HEAD, LIST,
# PUT, создание bucket). Ключ API — только объекты своего bucket (нет
# списка, прав на bucket, политики и ACL, чужого bucket). Ключ уборщика —
# чтение, удаление и список только по префиксу messenger/attachments/
# (другой префикс и весь bucket — 403, записи нет). Из сети стенда
# открыты только API S3 (8333) и gRPC шлюза (18333, закрыт ключом
# подписи); master (9333), volume (8080), filer (8888) и их gRPC — только
# на loopback контейнера, консоли нет.
+95
View File
@@ -0,0 +1,95 @@
# Что доказывает: миграции Attachment (README, «Что должно быть в PR»):
# ревизия 0003 создаёт attachments и message_attachments, миграции
# выполняются однократно сервисом migrate до реплик, повтор — no-op,
# описание схемы (src/storage/tables.py) совпадает с базой. С нуля все
# ревизии применяет каждый make test-isolated и make failure-checks
# (пустая база отдельного стенда) — tests/test-isolated.txt.
# Дата: 2026-10-23T16:46Z (UTC)
# Окружение: macOS 26.6.2, Apple M3 Pro; Docker 29.9.2, Compose 5.6.1;
# uv Python 3.13.15, alembic 1.20.0.
# Стенд: рабочий (`make up`, проект vladimirceva-lab4), PostgreSQL 18.6 на
# 127.0.0.1:5533 (порт из .env).
# Код: src_sha256 bc10d566e2f63173541445a2f6273b967447e13e5dd7f1fb76900934e5692cbe.
# Как повторить: make up; docker compose run --rm migrate; переменные DB_*
# из .env и uv run alembic check / alembic history (migrations/AGENTS.md)
$ docker compose run --rm migrate
2026-10-23T16:46:30.131Z INFO src.migrations [rid=-] migrations started db=postgres:5432/messenger
2026-10-23T16:46:30.149Z INFO alembic.runtime.migration [rid=-] Context impl PostgresqlImpl.
2026-10-23T16:46:30.149Z INFO alembic.runtime.migration [rid=-] Will assume transactional DDL.
2026-10-23T16:46:30.156Z INFO src.migrations [rid=-] migrations finished db=messenger
exit=0
$ uv run alembic check
2026-10-23T16:46:32.220Z INFO src.migrations [rid=-] migrations finished db=messenger
No new upgrade operations detected.
$ uv run alembic history
0002 -> 0003 (head), attachments and message attachments
0001 -> 0002, idempotency keys for sending messages
<base> -> 0001, messenger schema: users, sessions, chats, chat members, messages
$ psql -c "SELECT version_num FROM alembic_version"
version_num
-------------
0003
(1 row)
$ psql -c "\d attachments"
Table "public.attachments"
Column | Type | Collation | Nullable | Default
--------------+--------------------------+-----------+----------+---------
id | uuid | | not null |
chat_id | uuid | | not null |
owner_id | uuid | | not null |
filename | text | | not null |
content_type | text | | not null |
size_bytes | integer | | not null |
sha256 | bytea | | not null |
object_key | text | | not null |
status | text | | not null |
created_at | timestamp with time zone | | not null |
updated_at | timestamp with time zone | | not null |
lost_at | timestamp with time zone | | |
Indexes:
"pk_attachments" PRIMARY KEY, btree (id)
"ix_attachments_pending_created_at" btree (created_at, id) WHERE status = 'pending'::text
"uq_attachments_object_key" UNIQUE CONSTRAINT, btree (object_key)
Check constraints:
"ck_attachments_content_type" CHECK (content_type = ANY (ARRAY['image/png'::text, 'image/jpeg'::text]))
"ck_attachments_filename_chars" CHECK (filename !~ '[/\\\u0001-\u001f\u007f-\u009f]'::text)
"ck_attachments_filename_length" CHECK (char_length(filename) >= 1 AND char_length(filename) <= 255)
"ck_attachments_object_key_length" CHECK (octet_length(object_key) >= 1 AND octet_length(object_key) <= 1024)
"ck_attachments_sha256_length" CHECK (octet_length(sha256) = 32)
"ck_attachments_size_bytes" CHECK (size_bytes >= 1 AND size_bytes <= 10485760)
"ck_attachments_status" CHECK (status = ANY (ARRAY['pending'::text, 'ready'::text]))
"ck_attachments_updated_after_created" CHECK (updated_at >= created_at)
Foreign-key constraints:
"fk_attachments_chat_id_owner_id_chat_members" FOREIGN KEY (chat_id, owner_id) REFERENCES chat_members(chat_id, user_id)
Referenced by:
TABLE "message_attachments" CONSTRAINT "fk_message_attachments_attachment_id_attachments" FOREIGN KEY (attachment_id) REFERENCES attachments(id)
$ psql -c "\d message_attachments"
Table "public.message_attachments"
Column | Type | Collation | Nullable | Default
---------------+----------+-----------+----------+---------
message_id | uuid | | not null |
position | smallint | | not null |
attachment_id | uuid | | not null |
Indexes:
"pk_message_attachments" PRIMARY KEY, btree (message_id, "position")
"ix_message_attachments_attachment_id" btree (attachment_id)
"uq_message_attachments_message_id_attachment_id" UNIQUE CONSTRAINT, btree (message_id, attachment_id)
Check constraints:
"ck_message_attachments_position_range" CHECK ("position" >= 0 AND "position" <= 9)
Foreign-key constraints:
"fk_message_attachments_attachment_id_attachments" FOREIGN KEY (attachment_id) REFERENCES attachments(id)
"fk_message_attachments_message_id_messages" FOREIGN KEY (message_id) REFERENCES messages(id)
# Итог: база на ревизии 0003 (head); повторный запуск migrate — no-op
# (новых ревизий не применено), alembic check расхождений схемы и
# tables.py не видит. Байтов в схеме нет: оригинал — объект S3 по
# object_key (уникален), в строке — размер, SHA-256 и статус. Членство
# владельца страхует составной внешний ключ на chat_members; связь с
# сообщением — без каскада, позиции 0–9 (не больше 10 вложений). Частичный
# индекс pending — для выборки кандидатов уборщика.
+59
View File
@@ -0,0 +1,59 @@
# Что доказывает: уровень 3 — «restart с сохранением volumes сохраняет
# метаданные и оригинал»; сценарий защиты, п. 3 (persistence: общий тест
# с лабы 4 сохраняет и повторно читает оригинал через API). Hook
# перезапускает LB, все реплики и все хранилища, включая S3.
# Дата: 2026-10-23T16:43:50Z (UTC)
# Окружение: macOS 26.6.2, Apple M3 Pro; Docker 29.9.2, Compose 5.6.1;
# python3 хоста 3.11.9.
# Стенд: рабочий (`make up`, проект vladimirceva-lab4), HAProxy
# 127.0.0.1:8180 (порт из .env), 2 реплики.
# Код: src_sha256 bc10d566e2f63173541445a2f6273b967447e13e5dd7f1fb76900934e5692cbe.
# Как повторить: make test-persistence ACTION_SCRIPT=scripts/restart.sh
#
# tests/resilience.py (skeleton) создаёт пользователей, чат, сообщения и
# вложение, вызывает hook (его вывод скрыт самим тестом), затем прежним
# токеном читает те же данные и скачивает оригинал — байты должны
# совпасть. scripts/restart.sh: stop haproxy api → restart postgres
# valkey s3 → up -d --wait postgres valkey s3 → start api haproxy (start
# api запускает и migrate, s3-bootstrap — оба no-op). Уборщик hook не
# трогает: рестарт хранилищ он переживает сам.
# До hook:
$ docker inspect -f '{{.Name}} {{.State.StartedAt}} {{.State.Status}}' <контейнеры проекта>
vladimirceva-lab4-api-1 2026-10-23T16:43:05.518185386Z running
vladimirceva-lab4-api-2 2026-10-23T16:40:32.373815843Z running
vladimirceva-lab4-cleaner-1 2026-10-23T16:40:32.293661634Z running
vladimirceva-lab4-haproxy-1 2026-10-23T16:40:32.461651343Z running
vladimirceva-lab4-migrate-1 2026-10-23T16:40:26.344051756Z exited
vladimirceva-lab4-postgres-1 2026-10-23T16:40:24.748109464Z running
vladimirceva-lab4-s3-1 2026-10-23T16:40:24.555450964Z running
vladimirceva-lab4-s3-bootstrap-1 2026-10-23T16:41:14.405565709Z exited
vladimirceva-lab4-valkey-1 2026-10-23T16:40:24.660524006Z running
$ make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://localhost:8180
python3 tests/resilience.py --mode persistence --action-script "scripts/restart.sh" --base-url "http://localhost:8180"
Executing explicit persistence hook; hook output suppressed to avoid leaking secrets.
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.
# (25,6 с вместе с hook)
# После hook:
$ docker inspect -f '{{.Name}} {{.State.StartedAt}} {{.State.Status}}' <контейнеры проекта>
vladimirceva-lab4-api-1 2026-10-23T16:44:14.295621792Z running
vladimirceva-lab4-api-2 2026-10-23T16:44:14.364260917Z running
vladimirceva-lab4-cleaner-1 2026-10-23T16:40:32.293661634Z running
vladimirceva-lab4-haproxy-1 2026-10-23T16:44:14.446801626Z running
vladimirceva-lab4-migrate-1 2026-10-23T16:44:11.70032518Z exited
vladimirceva-lab4-postgres-1 2026-10-23T16:43:51.777618921Z running
vladimirceva-lab4-s3-1 2026-10-23T16:44:06.786787678Z running
vladimirceva-lab4-s3-bootstrap-1 2026-10-23T16:44:11.635117847Z exited
vladimirceva-lab4-valkey-1 2026-10-23T16:43:51.839501379Z running
$ docker volume inspect -f '{{.Name}} {{.CreatedAt}}' vladimirceva-lab4_pgdata vladimirceva-lab4_s3data
vladimirceva-lab4_pgdata 2026-10-23T15:55:31Z
vladimirceva-lab4_s3data 2026-10-23T15:55:31Z
# Итог: PASS — данные, прежняя сессия и оригинал вложения (побайтно, тот
# же размер) пережили перезапуск. StartedAt новые у haproxy, обеих
# реплик, postgres, valkey и s3 (s3 — через ~15 с плавной остановки
# filer), migrate и s3-bootstrap отработали заново; уборщик не
# перезапускался (по замыслу). Volume pgdata и s3data — те же (дата
# создания не изменилась).
+91
View File
@@ -0,0 +1,91 @@
# Что доказывает: стенд лабы 4 — уровень 3 «S3-сервер в общем стенде;
# метаданные — в PostgreSQL, байты — в приватном bucket, не в БД и не в
# локальном каталоге API»; уровень 4 «API использует отдельные S3
# credentials с ограниченными правами; административная консоль не
# открыта в общей сети»; с лабы 3 — HAProxy единственная точка входа,
# реплики без портов, лимиты CPU/RAM у всех, секреты только где нужны;
# сценарий защиты, п. 4 («на API нет обязательного локального файла
# оригинала»).
# Дата: 2026-10-23T16:46Z (UTC)
# Окружение: macOS 26.6.2, Apple M3 Pro; ВМ Docker 12 CPU / 7,7 ГиБ;
# Docker 29.9.2, Compose 5.6.1.
# Стенд: рабочий (`make up`, проект vladimirceva-lab4); порты хоста из
# .env (8180, 5533, 6480, 8434): стандартные 8080/5433/6380/8334 на этой
# машине заняты другим стендом.
# Код: src_sha256 bc10d566e2f63173541445a2f6273b967447e13e5dd7f1fb76900934e5692cbe.
# Как повторить: make up; команды ниже. Значения переменных окружения не
# печатаются — только имена; ключи сравниваются без вывода.
$ docker compose ps -a --format 'table {{.Name}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}'
NAME IMAGE STATUS PORTS
vladimirceva-lab4-api-1 mtusi-messenger-vladimirceva:lab4 Up About a minute (healthy) 8080/tcp
vladimirceva-lab4-api-2 mtusi-messenger-vladimirceva:lab4 Up About a minute (healthy) 8080/tcp
vladimirceva-lab4-cleaner-1 mtusi-messenger-vladimirceva:lab4 Up 5 minutes 8080/tcp
vladimirceva-lab4-haproxy-1 haproxy:3.4.6-trixie@sha256:e273915691a8eab3f105bf3e39fd4c29a4ecf334e33421903b5589d25e14db26 Up About a minute (healthy) 127.0.0.1:8180->8080/tcp
vladimirceva-lab4-migrate-1 mtusi-messenger-vladimirceva:lab4 Exited (0) About a minute ago
vladimirceva-lab4-postgres-1 postgres:18.6-trixie@sha256:5a5a84b19854a9ffaa54082c166ff4ec27473a361e496e5ea167f298f2da9722 Up About a minute (healthy) 127.0.0.1:5533->5432/tcp
vladimirceva-lab4-s3-1 chrislusf/seaweedfs:4.48@sha256:4e61d15fd35994cb1e43e1e553dff106794841fd9a99ade2fc8c8bfce4d7872d Up About a minute (healthy) 127.0.0.1:8434->8333/tcp
vladimirceva-lab4-s3-bootstrap-1 chrislusf/seaweedfs:4.48@sha256:4e61d15fd35994cb1e43e1e553dff106794841fd9a99ade2fc8c8bfce4d7872d Exited (0) About a minute ago
vladimirceva-lab4-valkey-1 valkey/valkey:9.1.2-trixie@sha256:418652cfb58ef879d4978c33553735d7147016032d5aefaa14c828e611eb9dfd Up About a minute (healthy) 127.0.0.1:6480->6379/tcp
# «8080/tcp» у api и cleaner — EXPOSE образа, не публикация на хост:
$ docker inspect -f '{{.Name}} cpus={{.HostConfig.NanoCpus}} mem={{.HostConfig.Memory}} ports={{json .HostConfig.PortBindings}} ro={{.HostConfig.ReadonlyRootfs}} capdrop={{.HostConfig.CapDrop}}' <контейнеры проекта>
vladimirceva-lab4-api-1 cpus=1000000000 mem=536870912 ports={} ro=true capdrop=[ALL]
vladimirceva-lab4-api-2 cpus=1000000000 mem=536870912 ports={} ro=true capdrop=[ALL]
vladimirceva-lab4-cleaner-1 cpus=250000000 mem=268435456 ports={} ro=true capdrop=[ALL]
vladimirceva-lab4-haproxy-1 cpus=1000000000 mem=268435456 ports={"8080/tcp":[{"HostIp":"127.0.0.1","HostPort":"8180"}]} ro=true capdrop=[ALL]
vladimirceva-lab4-migrate-1 cpus=500000000 mem=268435456 ports={} ro=true capdrop=[ALL]
vladimirceva-lab4-postgres-1 cpus=2000000000 mem=1073741824 ports={"5432/tcp":[{"HostIp":"127.0.0.1","HostPort":"5533"}]} ro=false capdrop=<no value>
vladimirceva-lab4-s3-1 cpus=1000000000 mem=536870912 ports={"8333/tcp":[{"HostIp":"127.0.0.1","HostPort":"8434"}]} ro=false capdrop=<no value>
vladimirceva-lab4-s3-bootstrap-1 cpus=500000000 mem=134217728 ports={} ro=false capdrop=<no value>
vladimirceva-lab4-valkey-1 cpus=500000000 mem=134217728 ports={"6379/tcp":[{"HostIp":"127.0.0.1","HostPort":"6480"}]} ro=false capdrop=<no value>
# Имена переменных окружения по контейнерам (значения не печатаются):
$ docker inspect -f '{{range .Config.Env}}{{println .}}{{end}}' <контейнер> | cut -d= -f1 | grep -E '^(DB_|CACHE_|S3_|AWS_|WEED_|POSTGRES_|VALKEY|UPLOAD|CLEANER|RECONCILE|SESSION|IDEMP|SHUTDOWN|LOG_|GOMEM|MALLOC)' | sort
vladimirceva-lab4-api-1: CACHE_HOST CACHE_PASSWORD CACHE_PORT DB_HOST DB_NAME DB_PASSWORD DB_PORT DB_USER IDEMPOTENCY_TTL_SECONDS LOG_LEVEL MALLOC_MMAP_THRESHOLD_ S3_ACCESS_KEY_ID S3_BUCKET S3_ENDPOINT S3_SECRET_ACCESS_KEY SESSION_TTL_SECONDS SHUTDOWN_TIMEOUT
vladimirceva-lab4-api-2: CACHE_HOST CACHE_PASSWORD CACHE_PORT DB_HOST DB_NAME DB_PASSWORD DB_PORT DB_USER IDEMPOTENCY_TTL_SECONDS LOG_LEVEL MALLOC_MMAP_THRESHOLD_ S3_ACCESS_KEY_ID S3_BUCKET S3_ENDPOINT S3_SECRET_ACCESS_KEY SESSION_TTL_SECONDS SHUTDOWN_TIMEOUT
vladimirceva-lab4-cleaner-1: DB_HOST DB_NAME DB_PASSWORD DB_POOL_OVERFLOW DB_POOL_SIZE DB_PORT DB_USER LOG_LEVEL MALLOC_MMAP_THRESHOLD_ S3_ACCESS_KEY_ID S3_BUCKET S3_ENDPOINT S3_SECRET_ACCESS_KEY
vladimirceva-lab4-haproxy-1:
vladimirceva-lab4-migrate-1: DB_HOST DB_NAME DB_PASSWORD DB_PORT DB_USER LOG_LEVEL MALLOC_MMAP_THRESHOLD_
vladimirceva-lab4-postgres-1: POSTGRES_DB POSTGRES_PASSWORD POSTGRES_USER
vladimirceva-lab4-s3-1: AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY GOMEMLIMIT WEED_JWT_FILER_SIGNING_KEY
vladimirceva-lab4-s3-bootstrap-1: S3_API_ACCESS_KEY S3_API_SECRET_KEY S3_BUCKET S3_CLEANER_ACCESS_KEY S3_CLEANER_LIST_PREFIX S3_CLEANER_SECRET_KEY WEED_JWT_FILER_SIGNING_KEY
vladimirceva-lab4-valkey-1: VALKEYCLI_AUTH VALKEY_PASSWORD VALKEY_VERSION
# Чьи ключи S3 у кого (сравнение значений в python3 без вывода самих значений):
api S3_ACCESS_KEY_ID == .env S3_API_ACCESS_KEY: True
cleaner S3_ACCESS_KEY_ID == .env S3_CLEANER_ACCESS_KEY: True
api key != cleaner key: True
api key != root key: True
root pair only in s3 (not in api/cleaner): True
# Реплики ничего не пишут на диск (файловая система только для чтения,
# /tmp — tmpfs):
$ docker diff vladimirceva-lab4-api-1
$ docker exec vladimirceva-lab4-api-1 sh -c 'find /tmp -type f | wc -l'
0
$ docker diff vladimirceva-lab4-api-2
$ docker exec vladimirceva-lab4-api-2 sh -c 'find /tmp -type f | wc -l'
0
# Метаданные — в PostgreSQL, байтов в БД нет (только SHA-256 и ключ):
$ psql -c "SELECT status, count(*), pg_size_pretty(sum(size_bytes)) AS bytes_in_s3 FROM attachments GROUP BY status"
status | count | bytes_in_s3
--------+-------+-------------
ready | 35 | 14 MB
(1 row)
$ psql -c "SELECT pg_size_pretty(pg_total_relation_size('attachments')) AS attachments_table, pg_size_pretty(pg_database_size(current_database())) AS database"
attachments_table | database
-------------------+----------
96 kB | 8990 kB
(1 row)
# Итог: единственный порт API — HAProxy на 127.0.0.1; у реплик и уборщика
# портов нет; S3 публикует на хост только API S3 и только на loopback
# (консоли нет; служебные порты закрыты — s3/privacy.txt). Лимиты CPU и
# памяти у всех контейнеров. Пароль Valkey — только у api и valkey;
# пароль PostgreSQL — у api, cleaner, migrate; административная пара S3 —
# только у s3, ключ подписи — у s3 и s3-bootstrap; у реплик — ключи
# пользователя API, у уборщика — свои. 35 оригиналов (14 MB) лежат в S3,
# таблица метаданных — 96 kB, вся база — 9 MB; на дисках реплик файлов
# нет.
+131
View File
@@ -0,0 +1,131 @@
# Что доказывает: уровень 4 — «прерывание загрузки и отказ между записью
# S3/БД не оставляют вечных неучтённых объектов: есть компенсация,
# сверка и очистка с безопасным grace period»; «лимиты/таймауты не
# позволяют одной загрузке занять неограниченную RAM»; проверка
# недоступности S3 (README, «Что сделать», п. 5). Трек 2 — ошибки
# внедрены с обеих сторон, обнаружены dry-run, безопасно исправлены
# --apply, повтор находит только неисправимое; свежие и используемые
# вложения под загрузками не удаляются. С лаб 2–3 — отказы PostgreSQL,
# Valkey, пул, сроки сессии и ключа.
# Дата: 2026-10-23T16:52:13Z (UTC)
# Окружение: macOS 26.6.2, Apple M3 Pro; ВМ Docker 12 CPU / 7,7 ГиБ;
# Docker 29.9.2, Compose 5.6.1; python3 хоста 3.11.9, uv Python 3.13.15,
# pytest 9.1.1.
# Стенд: отдельный проект vladimirceva-lab4-failures (student-tests/stand.py):
# PostgreSQL, Valkey, S3 с bootstrap; три процесса API без LB — обычный,
# «тесный» (сроки сессии и ключа 2 с, пул 1, срок операции 2 с) и «узкий
# по загрузкам» (1 место, очередь 1, ожидание 1 с, срок тела 2 с; ему же
# передано MAX_UPLOAD_BYTES=1 и MAX_IMAGE_PIXELS=1 — лимиты контракта
# окружение не меняет); уборщик с grace 25 с и проходом раз в секунду
# (без плановой сверки: её запускают тесты). Удаляется после прогона.
# Код: src_sha256 bc10d566e2f63173541445a2f6273b967447e13e5dd7f1fb76900934e5692cbe.
# Как повторить: make failure-checks FAULT_ARGS=-rP
#
# Вывод сборки образа и строки compose о контейнерах сокращены (...).
$ make failure-checks FAULT_ARGS=-rP
python3 student-tests/stand.py failures -rP
[failures] project=vladimirceva-lab4-failures
[failures] build image
...
[failures] start postgres, valkey and s3
...
[failures] s3 bootstrap
[failures] migrations
...
2026-10-23T16:52:25.803Z INFO alembic.runtime.migration [rid=-] Running upgrade -> 0001, messenger schema: users, sessions, chats, chat members, messages
2026-10-23T16:52:25.814Z INFO alembic.runtime.migration [rid=-] Running upgrade 0001 -> 0002, idempotency keys for sending messages
2026-10-23T16:52:25.818Z INFO alembic.runtime.migration [rid=-] Running upgrade 0002 -> 0003, attachments and message attachments
2026-10-23T16:52:25.829Z INFO src.migrations [rid=-] migrations finished db=messenger
[failures] ready: api=http://127.0.0.1:59093 tight=http://127.0.0.1:59099 uploads=http://127.0.0.1:59105 cleaner=vladimirceva-lab4-failures-cleaner
[failures] pytest -m fault
============================= test session starts ==============================
platform darwin -- Python 3.13.15, pytest-9.1.1, pluggy-1.6.0
rootdir: <репозиторий>
configfile: pyproject.toml
testpaths: student-tests
plugins: anyio-4.15.1
collected 154 items / 130 deselected / 24 selected
student-tests/test_failures.py ........................ [100%]
==================================== PASSES ====================================
________________________ test_database_stopped_and_back ________________________
----------------------------- Captured stdout call -----------------------------
postgres stopped: POST message -> 503 in 0.008s
___________________ test_frozen_database_and_exhausted_pool ____________________
----------------------------- Captured stdout call -----------------------------
postgres paused: first request -> 503 in 4.01s, second (pool of 1 busy) -> 503 in 1.01s
_______________________ test_readiness_without_database ________________________
----------------------------- Captured stdout call -----------------------------
postgres stopped: /health/ready -> 503 in 0.011s
_______________________ test_valkey_stopped_is_bypassed ________________________
----------------------------- Captured stdout call -----------------------------
valkey stopped: GET chat -> 200 in 0.012s, POST message -> 201 in 0.011s
_____________________ test_valkey_paused_costs_one_timeout _____________________
----------------------------- Captured stdout call -----------------------------
valkey paused: baseline 0.002s, first read 0.205s, second read 0.003s
_________________________ test_upload_with_s3_stopped __________________________
----------------------------- Captured stdout call -----------------------------
s3 stopped: upload -> 503 in 0.040s
___________________ test_upload_and_download_with_s3_paused ____________________
----------------------------- Captured stdout call -----------------------------
s3 paused: upload -> 503 in 5.01s, download -> 503 in 5.01s
____________ test_ready_failure_compensates_and_cleaner_removes_row ____________
----------------------------- Captured stdout call -----------------------------
ready failed: object compensated at once, row removed after 25.8s
_______________________ test_kill_between_put_and_ready ________________________
----------------------------- Captured stdout call -----------------------------
killed between PUT and ready: client got ['RemoteProtocolError']
cleaner removed row and object 19.3s after the kill check
________________________ test_upload_slots_busy_is_429 _________________________
----------------------------- Captured stdout call -----------------------------
slots busy: third upload -> 429 in 0.005s (Too many uploads in progress, retry later)
_______________________ test_upload_body_timeout_is_400 ________________________
----------------------------- Captured stdout call -----------------------------
slow body: -> 400 in 3.01s (Upload body was not received in time)
__________________ test_reconcile_finds_and_fixes_both_sides ___________________
----------------------------- Captured stdout call -----------------------------
dry-run: {'7465519f-7877-413d-a045-81bfd7b10de7': 'orphan_object', 'fd249ee1-1c8b-430a-84e6-d0761ba2accb': 'size_mismatch', '13691faf-6b35-4f7b-8d9e-03b9947a11a8': 'missing_object', '115eff2d-49d9-4531-95f3-10df6fcc3481': 'stale_pending', 'attachments': 'foreign_object'}
after fixes: apply=false strategy=batch deep=false rate=2000 listed_objects=7 checked_rows=7 fresh_objects=0 fresh_rows=0 lost_known=1 found_orphan_object=0 found_stale_pending=0 found_missing_object=0 found_size_mismatch=0 found_checksum_mismatch=0 found_restored_object=0 found_foreign_object=0 fixed_cleared_lost=0 fixed_deleted_object=0 fixed_marked_lost=0 fixed_removed_pending=0 remaining=0 refused=false u
______________________ test_reconcile_apply_under_uploads ______________________
----------------------------- Captured stdout call -----------------------------
reconcile --apply passes: [0, 0, 0]; uploads: 2023; errors: []
================ 24 passed, 130 deselected in 218.83s (0:03:38) ================
[failures] cleanup
[failures] results: {'fault': 0}
$ docker ps -a --format '{{.Names}}' | grep failures; docker volume ls -q | grep failures
(пусто)
# Итог: 24 passed. Что именно проверено (утверждения тестов, а не только
# печать выше; student-tests/test_failures.py):
# - S3 остановлен — загрузка 503 за 0,04 с, в тексте ошибки нет
# внутренностей S3; строка pending остаётся уборщику, ready нет; текст и
# /health/ready работают (S3 готовность не проверяет); после возврата S3
# тот же файл — 201. Заморожен — загрузка и скачивание 503 за срок
# вызова 5,01 с, метаданные и ссылка в сообщении работают, после
# разморозки оригинал побайтно тот же.
# - Сбой перевода в ready после записанного объекта (триггер в БД) — 503,
# объект удалён компенсацией сразу, строку pending уборщик убрал через
# 25,8 с (grace 25 с); объектов без строки 0.
# - Процесс API убит между PUT и ready — клиент 201 не получил, уборщик
# после grace убрал и строку, и объект.
# - Места загрузок: при занятом месте и полной очереди — 429 за 0,005 с с
# Retry-After: 1; ожидавшая загрузка — 429 по сроку ожидания места;
# занявшая место — 201 с полным размером (MAX_UPLOAD_BYTES=1 в окружении
# лимит не изменил). Медленное тело — 400 по сроку тела (2 с + отправка),
# ни строки, ни объекта, место освобождено (следующая загрузка — 201).
# - Сверка: внесены объект без строки, чужой объект, строка без объекта
# (на неё ссылается сообщение), другой размер, зависшая загрузка — dry-run
# нашёл все пять классов и ничего не изменил (число объектов и строк то
# же); --apply удалил объект без строки, убрал зависшую, пометил
# потерянный оригинал (метаданные 200, байты 404, сообщение со ссылкой
# живо) и другой размер, чужой объект не тронул (код 3); повтор нашёл
# только чужой; вернувшийся оригинал с тем же SHA-256 снял пометку (код
# 0), повторный dry-run — 0 находок (lost_known=1 — оригинал другого
# размера остаётся помеченным).
# - --apply трижды во время 2023 загрузок и отправок четырёх клиентов —
# коды 0, ни одно подтверждённое (201) вложение не удалено и не помечено,
# каждое скачивается с тем же SHA-256: свежие и используемые вложения
# сверка не трогает.
+42
View File
@@ -0,0 +1,42 @@
# Что доказывает: уровень 4 — собственные тесты проходят через LB
# рабочего стенда с двумя репликами: вложения (слишком большой файл,
# повреждённое изображение, подмена MIME, чужое attachment_id, вложение
# другого чата, опасный filename, 10 одновременных загрузок, скачивание
# через другую реплику), обязательные сценарии лаб 1–3, гонки,
# идемпотентность через разные реплики.
# Дата: 2026-10-23T16:47:29Z (UTC)
# Окружение: macOS 26.6.2, Apple M3 Pro; Docker 29.9.2, Compose 5.6.1;
# uv Python 3.13.15, pytest 9.1.1.
# Стенд: рабочий (`make up`, проект vladimirceva-lab4), HAProxy
# 127.0.0.1:8180 (порт из .env), 2 реплики, EXPECT_REPLICAS=2.
# Код: src_sha256 bc10d566e2f63173541445a2f6273b967447e13e5dd7f1fb76900934e5692cbe.
# Как повторить: make up; make student-test [BASE_URL=http://localhost:<HOST_PORT>]
# Проверки отказов (24, маркер fault) здесь не идут — только на своём
# стенде: tests/failure-checks.txt.
$ make student-test BASE_URL=http://localhost:8180
BASE_URL=http://localhost:8180 EXPECT_REPLICAS=2 uv run pytest
============================= test session starts ==============================
platform darwin -- Python 3.13.15, pytest-9.1.1, pluggy-1.6.0
rootdir: <репозиторий>
configfile: pyproject.toml
testpaths: student-tests
plugins: anyio-4.15.1
collected 154 items / 24 deselected / 130 selected
student-tests/test_attachments.py ...................................... [ 29%]
........ [ 35%]
student-tests/test_auth.py ...................... [ 52%]
student-tests/test_balancing.py ... [ 54%]
student-tests/test_cache.py .... [ 57%]
student-tests/test_idempotency.py ................... [ 72%]
student-tests/test_race.py .... [ 75%]
student-tests/test_request_id.py ............. [ 85%]
student-tests/test_rubric.py ................... [100%]
===================== 130 passed, 24 deselected in 34.66s ======================
# Итог: 130 passed, пропусков нет (тесты реплик идут: EXPECT_REPLICAS=2),
# из них 46 — test_attachments.py. Пользовательские ошибки (413, 415, 400,
# 404) не превращаются в 500 — каждый негативный тест проверяет статус и
# форму ошибки контракта.
+94
View File
@@ -0,0 +1,94 @@
# Что доказывает: уровни 3 и 4 на отдельном чистом стенде с LB и двумя
# репликами: публичный smoke лабы 4, собственные тесты (с тестами
# реплик), make test-failover, вложение после остановки принявшей
# реплики (тот же SHA-256 через другую, 404 постороннему), make
# test-persistence (рестарт LB, реплик и всех хранилищ, в том числе S3);
# миграции 0001 → 0002 → 0003 с нуля на пустой базе.
# Дата: 2026-10-23T16:48:19Z (UTC)
# Окружение: macOS 26.6.2, Apple M3 Pro; ВМ Docker 12 CPU / 7,7 ГиБ;
# Docker 29.9.2, Compose 5.6.1; python3 хоста 3.11.9, uv Python 3.13.15.
# Стенд: отдельный проект vladimirceva-lab4-isolated (student-tests/stand.py):
# свои PostgreSQL, Valkey, S3 с bootstrap, volume, HAProxy на свободном
# порту и 2 реплики, свои пароли и ключи S3; удаляется после прогона.
# Рабочий стенд не затрагивается.
# Код: src_sha256 bc10d566e2f63173541445a2f6273b967447e13e5dd7f1fb76900934e5692cbe
# (образ :lab4-test собран из того же рабочего дерева).
# Как повторить: make test-isolated
#
# Вывод сборки образа и строки compose о контейнерах, сети и volume
# сокращены (...); остальное — как есть.
$ make test-isolated
python3 student-tests/stand.py isolated
[isolated] project=vladimirceva-lab4-isolated
[isolated] build image
Image mtusi-messenger-vladimirceva:lab4-test Building
...
Image mtusi-messenger-vladimirceva:lab4-test Built
[isolated] start postgres, valkey and s3
...
[isolated] s3 bootstrap
[isolated] migrations
2026-10-23T16:48:31.044Z INFO src.migrations [rid=-] migrations started db=postgres:5432/messenger
2026-10-23T16:48:31.062Z INFO alembic.runtime.migration [rid=-] Context impl PostgresqlImpl.
2026-10-23T16:48:31.062Z INFO alembic.runtime.migration [rid=-] Will assume transactional DDL.
2026-10-23T16:48:31.070Z INFO alembic.runtime.migration [rid=-] Running upgrade -> 0001, messenger schema: users, sessions, chats, chat members, messages
2026-10-23T16:48:31.081Z INFO alembic.runtime.migration [rid=-] Running upgrade 0001 -> 0002, idempotency keys for sending messages
2026-10-23T16:48:31.085Z INFO alembic.runtime.migration [rid=-] Running upgrade 0002 -> 0003, attachments and message attachments
2026-10-23T16:48:31.093Z INFO src.migrations [rid=-] migrations finished db=messenger
...
[isolated] ready: lb=http://127.0.0.1:58414 replicas=2
[isolated] make test
PASS: lab4 public API scenario; infrastructure and grading evidence remain separate.
[isolated] pytest
============================= test session starts ==============================
platform darwin -- Python 3.13.15, pytest-9.1.1, pluggy-1.6.0
rootdir: <репозиторий>
configfile: pyproject.toml
testpaths: student-tests
plugins: anyio-4.15.1
collected 154 items / 24 deselected / 130 selected
student-tests/test_attachments.py ...................................... [ 29%]
........ [ 35%]
student-tests/test_auth.py ...................... [ 52%]
student-tests/test_balancing.py ... [ 54%]
student-tests/test_cache.py .... [ 57%]
student-tests/test_idempotency.py ................... [ 72%]
student-tests/test_race.py .... [ 75%]
student-tests/test_request_id.py ............. [ 85%]
student-tests/test_rubric.py ................... [100%]
===================== 130 passed, 24 deselected in 33.94s ======================
[isolated] make test-failover (scripts/stop-one.sh)
Executing explicit failover hook; hook output suppressed to avoid leaking secrets.
{"observed_instances_before": 2, "successful_writes": 124, "failed_attempts": 0, "first_recovery_seconds": 1.199}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
[isolated] restore replicas
...
[isolated] attachment failover (scripts/lab4.py, stop the uploader)
upload: 201 X-Instance-Id=8e155477e367 size=111817 sha256=99ea7533c441f79c… (fixture 99ea7533c441f79c…)
message with attachment: 201 attachment_ids=['b5f06800-4aca-48df-87bc-c67d932c448f']
...
exit 0; STOP_ONE_LOG: 2026-10-23T16:49:31Z TARGET_INSTANCE_ID=8e155477e367 container=8e155477e367cc8c061169c1856dbdaf09bba0a5c0f441499e6fda3d5560fa44 mode=stop
download by bob after stop: 200 X-Instance-Id=89d14eb71508 after 0.51s, bytes=111817, sha256 == fixture, content-type=image/png
outsider GET /attachments/{id}: 404
outsider GET /attachments/{id}/content: 404
...
vladimirceva-lab4-isolated-api-2 8e155477e367 exited Exited (0) Less than a second ago
...
PASS
[isolated] make test-persistence (scripts/restart.sh)
...
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.
[isolated] cleanup
[isolated] results: {'test': 0, 'student-test': 0, 'test-failover': 0, 'attachment-failover': 0, 'test-persistence': 0}
$ docker ps -a --format '{{.Names}}' | grep isolated
(пусто)
# Итог: все пять шагов — код 0. Миграции применились с нуля на пустой
# базе (0001 → 0002 → 0003). Тесты реплик идут (EXPECT_REPLICAS=2), 130
# passed. test-failover: 124 успешные записи, ни одной неудачной, первая
# запись после hook — 1,2 с. Вложение после остановки принявшей реплики
# отдала другая (тот же SHA-256), посторонний — 404. Стенд удалён.
+297
View File
@@ -0,0 +1,297 @@
# Docker, compose, HAProxy и скрипты стенда
Правила для `Dockerfile`, `.dockerignore`, `compose.yaml`,
`infra/haproxy/haproxy.cfg`, `infra/valkey/valkey.conf`,
`infra/s3/bootstrap.sh` и своих скриптов `scripts/restart.sh`,
`scripts/stop-one.sh`, `scripts/rolling-update.sh`, `scripts/lab4.py`.
`infra/README.md` и остальное в `scripts/` — skeleton, не менять.
Требования рубрики (`README.md`) и `Dockerfile.example` важнее этого
файла.
```
клиент → 127.0.0.1:HOST_PORT → haproxy → api × API_REPLICAS → postgres (данные, сессии, ключи, метаданные вложений)
→ valkey (кэш карточек)
→ s3 (SeaweedFS: байты вложений, приватный bucket)
migrate, s3-bootstrap (один раз на up, до реплик)
cleaner (уборка незавершённых загрузок, сверка) → postgres, s3
```
## Dockerfile
- Два stage (`deps` → `runtime`) на **одном** базовом образе
`python:<патч>-slim-trixie@sha256:<digest индекса>`: venv ссылается на
интерпретатор базового образа. Новый digest — строка `Digest:` из
`docker buildx imagetools inspect <тег>`. Не `latest` и не `3.13-slim`.
- Зависимости — `pip install --require-hashes --no-deps
--only-binary=:all: -r requirements.txt`. `requirements.txt` — только
`make requirements` из `uv.lock`.
- Runtime: UID/GID 10001, `USER messenger`; код и venv принадлежат root.
- Копируются только `requirements.txt`, `src/`, `alembic.ini`,
`migrations/`. `COPY . .` запрещён.
- `ENV MALLOC_MMAP_THRESHOLD_=131072` (лаба 4): буфер тела загрузки
`BytesIO` больше 128 KiB растёт отдельным mmap и при освобождении
возвращается ядру, а не остаётся в куче glibc; без него пик памяти
после серии загрузок не опускается. Профиль `bench` `uploads` меряет
именно этот образ (значение — в паспорте, `app_defaults`).
- `CMD ["python", "-m", "src"]` в exec-форме: сервер — PID 1. Ранний
обработчик SIGTERM ставит `src/__main__.py` до импорта приложения
(`src/early_stop.py`): без него PID 1 терял бы сигнал во время старта, и
`docker stop` стартующей реплики ждал бы 10 с и SIGKILL. `init: true`
у `api` не ставить: сервер перестал бы быть PID 1.
- `HEALTHCHECK` — `python -m src.healthcheck` с `--start-interval=1s`.
## `.dockerignore`
Файл skeleton дополняется. Паттерн без `**/` действует только в корне
контекста: вложенные `AGENTS.md`, `__pycache__`, `*.pyc`, `.DS_Store` —
через `**/`. В образ не попадают `.env`, секреты, `tests/`,
`student-tests/`, `bench/`, `contracts/`, `evidence/`, `infra/`,
`scripts/`, `.codex/`, `.agents/`, `.venv/`, документация.
## `compose.yaml`
- Проект `name: vladimirceva-lab4` — имя меняется в каждой лабе: от него
зависят имена volume, и стенд не подключается к данным прошлой лабы.
- Сервисы: `postgres`, `valkey` (пины, свой healthcheck), `s3`
(SeaweedFS, раздел «S3»), `migrate` (образ API, `alembic upgrade
head`), `s3-bootstrap`, `api` × `API_REPLICAS` (по умолчанию 2),
`cleaner`, `haproxy`. `api` ждёт хранилища (`service_healthy`),
`migrate` и `s3-bootstrap` (`service_completed_successfully`);
`cleaner` — PostgreSQL, `migrate` и `s3-bootstrap`; `haproxy` — `api`
(`service_started`): `make stop` гасит LB раньше реплик.
- **`api` без `ports` и без `container_name`** (оба мешают
масштабированию одного сервиса): запросы — только через `haproxy`.
`deploy.replicas: ${API_REPLICAS:-2}`; разово — `make replicas
API_REPLICAS=N`. X-Instance-Id реплики — hostname, то есть короткий ID
контейнера.
- Наружу (`127.0.0.1`) — только `haproxy` (API, `HOST_PORT`), `postgres`,
`valkey` и API S3 (`S3_HOST_PORT`, 8334): `make run`, миграции и
проверки приватности с хоста. Мониторинг LB (`:8404`), runtime API
(`127.0.0.1:9999` в контейнере LB), master, volume, filer и консоль
SeaweedFS наружу не публикуются.
- Секреты — только тем, кому нужны: якоря `x-db-env` (PostgreSQL — `api`,
`cleaner`, `migrate`), `x-cache-env` (Valkey — только `api`),
`x-s3-env` (адрес и bucket — `api`, `cleaner`). Ключи S3 — у каждого
свои: реплики — пользователь API (`S3_API_*`), уборщик — свой
(`S3_CLEANER_*`), bootstrap — ключи обоих пользователей и ключ подписи,
сервер `s3` — административная пара и ключ подписи; у `haproxy`
окружения нет. Новая переменная контейнера — строка в якоре или
`environment` сервиса и в `.env.example`.
- Лимиты CPU/RAM у **всех** сервисов (`deploy.resources.limits`): API 1 /
512 МиБ на реплику, PostgreSQL 2 / 1 ГиБ, Valkey 0,5 / 128 МиБ, S3 1 /
512 МиБ, HAProxy 1 / 256 МиБ, migrate 0,5 / 256 МиБ, s3-bootstrap 0,5 /
128 МиБ, cleaner 0,25 / 256 МиБ. Override стендов (`bench/`) задаёт
лимиты в той же форме: `cpus`/`mem_limit` рядом compose не принимает.
- Соединения PostgreSQL: `API_REPLICAS × (DB_POOL_SIZE + DB_POOL_OVERFLOW)
+ migrate + cleaner ≤ max_connections` (100): 2 × 15 + 1 + 1 = 32, на
пике замены 3 × 15 + 1 + 1 = 47. Больше реплик или больше пул —
пересчитать.
- Буфер приёма сокетов реплики (`sysctls: net.ipv4.tcp_rmem "4096 131072
524288"`, лаба 4): недочитанное тело (клиент ждёт место загрузки) копится
в буфере сокета и считается памятью контейнера; по умолчанию ВМ Docker
дала бы до 32 МиБ на соединение.
- Ужесточение (`x-hardened`) у `api`, `migrate`, `haproxy`: `read_only`,
`cap_drop: ALL`, `no-new-privileges`; у `api` ещё `tmpfs: /tmp`.
`stop_grace_period: 10s` у `api` (uvicorn завершается за
`SHUTDOWN_TIMEOUT` ≤ 9 с), `restart: unless-stopped` — не поднимает
контейнер ни после `docker stop`, ни после `docker kill`.
- PostgreSQL: healthcheck `pg_isready -h 127.0.0.1` по TCP; volume
`pgdata` на `/var/lib/postgresql` (PostgreSQL 18). Valkey: volume нет,
persistence выключен в `valkey.conf`, пароль — в `command` через
переменную контейнера, healthcheck `valkey-cli ping` с `VALKEYCLI_AUTH`.
- Отдельные стенды — свои проекты с override
(`student-tests/stand.compose.yml`, `bench/bench.compose.yml`). Меняешь
сервис здесь — проверь `make test-isolated`, `make failure-checks`,
`make bench-failover-quick`.
## S3 (`s3`, `s3-bootstrap`, `infra/s3/bootstrap.sh`, лаба 4)
- SeaweedFS `chrislusf/seaweedfs:4.48@sha256:…` (тег и digest индекса
amd64 + arm64, якорь `x-s3-image`): один процесс `weed server` —
master, volume, filer и шлюз S3. Служебные серверы слушают только
`127.0.0.1` контейнера (`-ip.bind`), в сеть выходят API S3 (8333) и
gRPC шлюза (18333), закрытый ключом подписи `WEED_JWT_FILER_SIGNING_KEY`.
Телеметрия, IAM API, Iceberg и Lance выключены. `-s3.concurrentUploadLimitMB=64`
и `GOMEMLIMIT=400MiB` держат шлюз в 512 МиБ при параллельных PUT.
- Административная пара (`S3_ROOT_*`) — только у сервера: с первого
старта учётная запись есть, анонимного окна нет.
- `s3-bootstrap` — одноразовый, как `migrate`: `network_mode: service:s3`
(master и filer на loopback ему доступны, в сети их нет), пользователь
образа `seaweed`, `sh /opt/s3/bootstrap.sh apply`: bucket, анонимный
доступ `none`, политики и пользователи API (чтение, запись, удаление
объектов своего bucket) и уборщика (чтение, удаление и список **только
с префиксом** `S3_CLEANER_LIST_PREFIX` = `<база>/attachments/`), затем
сам проверяет приватность (анонимный GET/PUT/LIST — 403, ключи —
только свои права). Повтор сводит состояние к `.env` и ничего не
ломает. Секреты — через stdin `weed shell` и файл на tmpfs, не argv.
Режимы `check` и `cleanup` — для `make s3-check`.
- Volume `s3data` на `/data`. Плавная остановка ~15 с (ожидание подписок
filer зашито в код): `stop_grace_period: 20s`. Healthcheck — master
выбран, том зарегистрирован, filer и шлюз отвечают.
- API и уборщик ходят на `http://s3:8333`; `make run` — на
`127.0.0.1:S3_HOST_PORT`. Готовность реплики S3 не проверяет.
## Уборщик (`cleaner`, лаба 4)
Образ API, `entrypoint: ["python", "-m", "src.cleaner"]` (аргументы
`docker compose run cleaner …` — флаги уборщика), пул 1 + 0, ключи
`S3_CLEANER_*`, без healthcheck (HTTP не слушает: живость — журнал),
`stop_grace_period: 10s` (шаг доводится ≤ 6 с), 0,25 CPU / 256 МиБ.
Разовые запуски: `make cleanup-once`, `make reconcile [APPLY=1 …]`. На
время восстановления базы из backup уборщик останавливают: сверка
сочла бы новые объекты «без строки».
## HAProxy (`infra/haproxy/haproxy.cfg`)
- Прокси `frontend entry` (`:8080`), `backend api`, `frontend monitor`
(`:8404`: `/lb/ready` — healthcheck контейнера LB, `/stats;csv`). Имена
разные: с HAProxy 3.3 одинаковые имена frontend и backend — ошибка.
Проверка конфига: `docker compose exec haproxy haproxy -c -f
/usr/local/etc/haproxy/haproxy.cfg`.
- Реплики — через DNS Docker: `resolvers docker` (127.0.0.11, `hold` 1 с)
и `server-template api- 8 api:8080 … init-addr none init-state down`:
новая и пропавшая реплика видны без перезагрузки LB; слот, получивший
адрес, начинает `DOWN` и получает запросы только после `rise` проверок.
8 слотов — максимум реплик серий трека 1 и замены (N + 1).
- Проверка — активная, `GET /health/ready` (не `/health/live`: живой
процесс без PostgreSQL запросы не обслуживает), `inter 1s fastinter
500ms fall 2 rise 2`, `timeout check 2500ms`.
- `balance roundrobin` без `cookie` и `stick-table`: sticky session
запрещён (README, п. 3), разные X-Instance-Id одной сессии — проверка
уровня 3.
- Повтор в LB — только `retry-on conn-failure`, `retries 2`, `option
redispatch 1` (каждый повтор — на другую реплику): запрос до реплики не
дошёл, повтор безопасен для любого метода. Ответ, который реплика уже
начала, не повторяется: `POST /users` и `POST /chats` не идемпотентны,
`POST` сообщения повторяет клиент с тем же ключом.
- Ответы самого LB (502/503/504) — в формате ошибки контракта
(`http-error … lf-string`, `code` `unavailable`, `request_id` —
`unique-id`); X-Instance-Id у них нет — контракт допускает.
- `log stdout`, `option httplog` + `dontlog-normal`: в журнале только
ошибки, повторы и смены состояния слотов. `nbthread 1` = лимит CPU LB.
### Цепочка таймаутов (менять только вместе)
- Худшее обнаружение отказа ≤ 10 с (рубрика «3»): зависшая реплика —
`inter + timeout check + (fall − 1) × (fastinter + timeout check)` =
6,5 с; пропавший адрес (`kill`, `stop` после выхода) — 2,5 с; закрытый
сокет (окно graceful) — 1,5 с. Возврат — ≤ 1,5 с после готовности.
- `timeout connect` × (`retries` + 1) = 1,5 с < 2 с таймаута клиента
`tests/resilience.py`: перенаправление успевает раньше.
- `timeout server` 10 с > срок операции хранилища (`DB_OPERATION_TIMEOUT`
6 с + закрытие соединения 2 с) и KDF входа. У `POST
/api/v1/chats/{id}/attachments` — 40 с (`http-request set-timeout
server 40s`): ожидание места 5 с + срок тела 30 с + запись (< 21 с
границы, обычно секунды) укладываются, и ответ 429/400 приходит от
реплики, а не 504 от LB.
- Буферы LB (лаба 4): `tune.sndbuf.server 262144`, `tune.rcvbuf.client
131072` — тело загрузки, которое реплика ещё не читает, не копится в
LB мегабайтами на соединение.
- `ROLLOUT_DRAIN_TIMEOUT` 90 с (`scripts/rolling-update.sh`): дренаж
старой реплики дольше самой долгой загрузки (40 с).
- Срок проверки внутри `/health/ready` (2 с, `READINESS_TIMEOUT`) <
`timeout check` 2,5 с: медленный PostgreSQL даёт 503 реплики, а не
таймаут проверки. Уменьшать срок готовности ради быстрого обнаружения
нельзя: проверка берёт соединение из общего пула.
- Простаивающее соединение LB → реплика закрывает LB: `http-reuse never`,
`timeout http-keep-alive` 10 с < `KEEP_ALIVE_TIMEOUT` реплики 60 с.
Иначе LB мог бы отправить запрос в соединение, которое реплика в этот
момент закрывает (502, `empty-response` LB не повторяет).
- `SHUTDOWN_TIMEOUT` (5 с, не больше 9) < `stop_grace_period` 10 с.
## `scripts/restart.sh`
Hook `make test-persistence ACTION_SCRIPT=scripts/restart.sh`: `stop
haproxy api` → `restart postgres valkey s3` → `up -d --wait postgres
valkey s3` → `start api haproxy`. Перезапускает LB, **все** реплики и
**все** хранилища (с лабы 4 — и S3), сохраняя volume: без `down -v`,
`FLUSHALL`, повторного наполнения. `start api` поднимает и `migrate`,
`s3-bootstrap` (no-op). Уборщика не трогает: рестарт хранилищ он
переживает сам. Число реплик не меняется. `#!/bin/sh`, `set -eu`,
исполняемый бит, секреты не печатает. Доказательство перезапуска —
`StartedAt` до и после.
## `scripts/stop-one.sh`
Hook `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`:
`TARGET_INSTANCE_ID` (X-Instance-Id = начало ID контейнера, только hex,
12–64 символа) ищется префиксом среди **работающих** реплик сервиса `api`
этого проекта (`docker compose ps -q --no-trunc api`); иначе — код 2/3,
ничего не трогается. `STOP_MODE=stop` (`docker stop --timeout 9`,
graceful) или `kill`; реплика остаётся остановленной; возврат — `make
replicas` (те же контейнеры и ID). `STOP_ONE_LOG=<файл>` — строка «время,
TARGET_INSTANCE_ID, полный ID, режим»: тест скрывает вывод hook, а
evidence должно показать, какой контейнер остановлен. PostgreSQL,
Valkey, LB, чужие контейнеры и volume — никогда.
## `scripts/rolling-update.sh` (`make rolling-update`)
Compose сам поочерёдно не заменяет (это `update_config` Swarm); плагинов
нет. Порядок:
0. Предусловия (код 2, ничего не менялось): работает ровно
`API_REPLICAS`, остановленных нет, runtime API LB отвечает, есть слот
для N + 1, нет слотов в ручном `drain`/`maint` (остаток прерванной
замены: флаги 1 и 8 в `srv_admin_state`), все реплики `UP`.
1. Сборка образа сервиса из рабочего дерева (`ROLLOUT_BUILD=0` — без
сборки: так делает стенд `bench/`, переставив тег сам).
2. Миграции один раз: пересоздаётся контейнер **сервиса** `migrate` на
новом образе (`up --no-deps --force-recreate --exit-code-from
migrate`), а не `run --rm`: иначе `restart.sh` позже запускал бы
`migrate` прежнего образа на новой схеме («Can't locate revision»).
Ошибка — код 1 до замены реплик.
3. `up --no-recreate --no-build --scale api=N+1`: одна новая реплика.
4. Новая `healthy` (на стенде `bench/` без healthcheck — `running`) **и**
`UP` в LB по её адресу (≤ `ROLLOUT_READY_TIMEOUT` 60 с).
5. Старая: `drain` через runtime API → запросов в полёте 0 (≤ 12 с) →
`maint` → `docker stop --timeout 10` (в строке — код выхода) → `docker
rm` → адрес ушёл из слота → слот `ready`. Дренаж убирает гонку
keep-alive: SIGTERM приходит реплике, которой LB уже не шлёт запросы.
Сбой (`trap`): новая не стала `UP` — удаляется (со слотом — `maint` и
штатный stop; без слота — `docker rm -f`); новая уже `UP` — вывод старой
доводится до конца. В любом исходе — `API_REPLICAS` готовых реплик и
слоты без ручного состояния; повтор доводит замену. Автоматического
отката нет: откат — вернуть прежний код и снова `make rolling-update`
(схема только расширялась). Runtime API — `stats socket
ipv4@127.0.0.1:9999 level admin`, доступ — `docker compose exec -T
haproxy bash -c 'exec 3<>/dev/tcp/127.0.0.1/9999 …'`.
После замен реплики называются `api-N` с растущим номером: штатные цели
работают с сервисом `api`, а не с именами; `make down` + `make up` снова
дают `api-1`, `api-2`.
## `scripts/lab4.py`
Свои операторские команды (stdlib, Python 3.9+): `env` (`make env`:
`.env` из `.env.example` со случайными паролями и ключами S3; в
существующий дописывает недостающие переменные, прежние строки не
меняет; несекретные значения — из окружения, `make env HOST_PORT=…`),
`instances`, `lb-stats`, `failover-each`, `attachment-failover` (`make
attachment-failover`: вложение через LB, остановка принявшей реплики,
скачивание через другую — тот же SHA-256, посторонний — 404, `make
replicas`), `s3-check` (`make s3-check`: bootstrap в режиме `check`,
анонимные запросы с хоста и из сети стенда, порты контейнера S3, затем
`cleanup`; таблица «где → проверка → ожидаемо → получено», код 1 при
нарушении). Пароль и токен синтетического пользователя — только в
памяти; ключи S3 не печатаются.
## Что стенд не переживает
Один Docker-host, один HAProxy, одна PostgreSQL, один Valkey, один S3
без реплик. Выдерживается отказ процесса API (любой одной реплики при
≥ 2 живых), уборщика (незавершённое уберёт следующий проход). Не
выдерживается отказ хоста, LB, PostgreSQL и S3 (без S3 — 503 на
загрузке и скачивании, текст работает); отказ Valkey — деградация до
PostgreSQL. Это пишется в `REPORT.md` прямо.
## Проверка правок
`docker compose config --quiet`, `make up`, `docker compose ps` (все
`healthy`), `make test`, `make instances`, `make test-persistence
ACTION_SCRIPT=scripts/restart.sh`, `make failover-each`, `make
attachment-failover`, `make s3-check`, `make test-isolated`. Правка
`haproxy.cfg` — ещё `haproxy -c` (выше) и `make failure-checks` (места и
срок тела); правка S3 и bootstrap — `make s3-check` и повтор
`make db-up` (идемпотентность); правка скриптов — `make rolling-update`
на рабочем стенде и `make bench-rollout-quick`.
+152
View File
@@ -0,0 +1,152 @@
# Балансировщик лаб 3–4: единственная точка входа перед репликами сервиса
# api. Правила и цепочка таймаутов — infra/AGENTS.md; тот же файл берёт
# нагрузочный стенд bench/. Порты внутри сети стенда фиксированы: 8080 —
# API (и у реплик, и у LB), 8404 — мониторинг. Секретов LB не получает.
global
# журнал — в stdout контейнера (docker compose logs haproxy)
log stdout format raw local0 info
maxconn 4096
# один поток на лимит 1 CPU: иначе HAProxy создал бы поток на каждый
# CPU ВМ и делил между ними одну квоту
nbthread 1
# runtime API для поочерёдной замены (scripts/rolling-update.sh): слот
# уходящей реплики — drain, maint, затем снова ready. Только loopback
# внутри контейнера LB: из сети compose и с хоста не достать, доступ —
# docker compose exec haproxy (bash /dev/tcp)
stats socket ipv4@127.0.0.1:9999 level admin
# лаба 4: буферы сокетов фиксированы. Отправка к реплике — 256 KiB: тело
# загрузки, которое реплика не читает (ожидание места, отказ до тела),
# не копится в памяти LB целиком. Приём от клиента — 128 KiB: без него
# ядро растило буфер до tcp_rmem ВМ (32 MiB), и тело, которое LB не
# может отдать реплике, копилось там. Окно 128 KiB — ~20 Мбит/с при RTT
# 50 мс: 10 MiB за ~4 с при сроке тела 30 с
tune.sndbuf.server 262144
tune.rcvbuf.client 131072
# DNS Docker: имя сервиса api отвечает адресами всех работающих реплик.
# Пропавший адрес уходит из слота, новый появляется за 1–2 с без
# перезагрузки LB
resolvers docker
nameserver dns 127.0.0.11:53
accepted_payload_size 8192
resolve_retries 3
timeout resolve 1s
timeout retry 1s
hold valid 1s
hold obsolete 1s
hold nx 1s
hold other 1s
hold refused 1s
hold timeout 1s
defaults
mode http
log global
option httplog
# обычные успешные запросы не пишутся; ошибки, таймауты, повторы,
# перенаправления и смена состояния реплик — пишутся
option dontlog-normal
# timeout connect × (retries + 1) = 0,5 × 3 = 1,5 с < 2 с таймаута
# клиента tests/resilience.py: перенаправление успевает раньше
timeout connect 500ms
retries 2
# каждый повтор — на другую реплику, а не на ту же
option redispatch 1
# повтор только если соединение не установлено: запрос до реплики не
# дошёл, повтор безопасен для любого метода. Ответ, который реплика уже
# начала, не повторяется: POST /users и POST /chats не идемпотентны,
# отправку сообщения повторяет клиент с тем же Idempotency-Key
retry-on conn-failure
# больше срока операции хранилища (DB_OPERATION_TIMEOUT 6 с + закрытие
# соединения 2 с) и KDF входа: LB не рвёт ответ, который API ещё отдаст.
# У пути загрузки вложения — 40 с (backend api, set-timeout)
timeout server 10s
timeout client 30s
timeout http-request 10s
# простаивающий сеанс клиента, а с ним и соединение с репликой
# (http-reuse never): меньше KEEP_ALIVE_TIMEOUT реплики (60 с)
timeout http-keep-alive 10s
# больше срока проверки внутри /health/ready (2 с) на 0,5 с: медленный
# PostgreSQL даёт 503 от реплики, а не таймаут проверки
timeout check 2500ms
# request_id ответов, которые создаёт сам LB
unique-id-format lb-%{+X}o%ci%cp%Ts%rt%pid
# ответы самого LB — в формате ошибки контракта; отдельных кодов для 502
# и 504 в контракте нет, ближайший — unavailable. X-Instance-Id у них
# нет: контракт это допускает. 400 — неверный запрос или клиент
# замолчал посреди тела загрузки дольше timeout client (лаба 4)
http-error status 400 content-type application/json lf-string '{"error":{"code":"invalid_request","message":"Invalid request","request_id":"%[unique-id]"}}' hdr X-Request-Id "%[unique-id]"
http-error status 502 content-type application/json lf-string '{"error":{"code":"unavailable","message":"API replica closed the connection","request_id":"%[unique-id]"}}' hdr X-Request-Id "%[unique-id]"
http-error status 503 content-type application/json lf-string '{"error":{"code":"unavailable","message":"No API replica is available","request_id":"%[unique-id]"}}' hdr X-Request-Id "%[unique-id]"
http-error status 504 content-type application/json lf-string '{"error":{"code":"unavailable","message":"API replica did not respond in time","request_id":"%[unique-id]"}}' hdr X-Request-Id "%[unique-id]"
# точка входа клиентов: на хосте — 127.0.0.1:HOST_PORT (compose)
frontend entry
bind :8080
default_backend api
backend api
# по очереди, без cookie и stick-table: sticky session запрещён
# (README, п. 3), разные X-Instance-Id у одной сессии — проверка «3»
balance roundrobin
# путь загрузки вложения (лаба 4): срок ответа реплики 40 с вместо 10 —
# больше самого долгого молчания живой загрузки:
# до тела — вход и членство (2 × (DB_OPERATION_TIMEOUT 6 + закрытие 2))
# + ожидание места UPLOAD_WAIT_TIMEOUT 5 = 21 с;
# после тела — проверка изображения (до ~4 с) + pending 8 + PUT 5
# (S3_TIMEOUT) + ready 8 + компенсация 5 = 30 с.
# Тело ограничивают UPLOAD_BODY_TIMEOUT (30 с) и timeout client;
# наибольшая длительность загрузки 21 + 30 + 30 ≈ 81 с <
# ROLLOUT_DRAIN_TIMEOUT (90 с, scripts/rolling-update.sh). Остальные пути
# — прежние 10 с: общий срок 40 с держал бы любой запрос к зависшей
# реплике 40 с. Выражение — путь ручки (src/api/routes/attachments.py)
http-request set-timeout server 40s if METH_POST { path_reg ^/api/v1/chats/[^/]+/attachments$ }
# соединение с репликой не уходит в общий пул и не отдаётся другому
# клиенту: живёт, пока жив сеанс клиента, а простаивающий сеанс LB
# закрывает по timeout http-keep-alive (10 с). uvicorn держит
# простаивающее соединение 60 с — значит, закрывает LB, и запрос не
# уходит в соединение, которое реплика в этот момент закрывает (ответа
# не было бы, а empty-response LB не повторяет). Гонку при SIGTERM
# (uvicorn сразу закрывает простаивающие соединения) это не убирает:
# остановка без вывода из LB может дать одиночный 502. Плановая
# остановка (scripts/rolling-update.sh) сначала выводит реплику (drain)
http-reuse never
# активная проверка готовности: /health/live для LB не годится, живой
# процесс без PostgreSQL запросы не обслуживает
option httpchk
http-check send meth GET uri /health/ready
http-check expect status 200
# реплика исключается после 2 неудачных проверок подряд и возвращается
# после 2 успешных; проверка раз в секунду (inter), после первой
# неудачи и до возврата — через fastinter. Следующая проверка
# начинается через интервал после конца предыдущей, поэтому худшее
# обнаружение:
# зависшая (соединение есть, ответа нет): inter + timeout check +
# (fall − 1) × (fastinter + timeout check) = 1 + 2,5 + 0,5 + 2,5
# = 6,5 с ≤ 10 с;
# адрес пропал (kill, stop после выхода): таймаут соединения
# проверки min(timeout connect, inter) = 0,5 с: 1 + 0,5 + 0,5 + 0,5
# = 2,5 с; DNS уводит слот в обслуживание за 1–2 с;
# сокет закрыт, адрес жив (окно graceful): 1 + 0,5 = 1,5 с.
# Возврат: ≤ inter + fastinter = 1,5 с после готовности.
# init-state down: слот, получивший адрес из DNS (старт LB, новая или
# вернувшаяся реплика), начинает DOWN и получает запросы только после
# rise проверок — иначе запросы шли бы на процесс, который ещё не
# слушает порт
default-server check inter 1s fastinter 500ms fall 2 rise 2 resolvers docker init-addr none init-state down resolve-prefer ipv4
# 8 слотов — максимум реплик стенда (серии трека 1 и замена N + 1);
# лишние слоты в MAINT, девятую реплику LB не увидит
server-template api- 8 api:8080
# мониторинг внутри сети compose, наружу не публикуется:
# /lb/ready — healthcheck контейнера LB (200, пока есть готовая реплика),
# /stats и /stats;csv — состояние и счётчики каждого слота (make lb-stats)
frontend monitor
bind :8404
monitor-uri /lb/ready
monitor fail if { nbsrv(api) lt 1 }
stats enable
stats uri /stats
# адрес реплики в статистике (поле addr): только внутри сети
stats show-legends
+500
View File
@@ -0,0 +1,500 @@
#!/bin/sh
# Bootstrap S3 стенда (SeaweedFS): приватный bucket, пользователь API с
# политикой «только объекты своего bucket», пользователь уборщика с
# политикой «чтение и удаление объектов своего bucket и их список только по
# префиксу вложений своей базы» (S3_CLEANER_LIST_PREFIX, <база>/attachments/:
# для сверки bucket и БД), проверки приватности вне API. Правила —
# infra/AGENTS.md, «S3».
#
# Запускается сервисом compose s3-bootstrap на образе сервера в сетевом
# пространстве сервиса s3 (network_mode: service:s3): master и filer
# слушают 127.0.0.1 сервера, из сети стенда их нет. Административные
# вызовы — weed shell с ключом подписи (WEED_JWT_FILER_SIGNING_KEY), а не
# административной парой S3: её хранит только сервер.
#
# Режимы:
# apply (по умолчанию) — свести состояние к окружению (.env) и проверить
# права; каждый шаг безопасно повторять;
# check — ничего не менять в настройке, проверить права и приватность
# шире, чем apply: чужой bucket (временный, создаётся и удаляется
# здесь же), административные запросы ключей API и уборщика, запись
# ключом уборщика, его список по своему префиксу (200), без префикса и
# с чужим (403), анонимные запросы. Общий проверочный
# объект остаётся для проверок с хоста и из сети (make s3-check) до
# режима cleanup; объект проверок удаления ключом уборщика — свой;
# cleanup — удалить проверочные объекты и временные bucket-ы check.
#
# Секреты: в weed shell — через stdin (printf — встроенная команда sh), в
# curl — файлом -K на tmpfs; в argv процессов и в выводе их нет. Ошибка
# шага — «FAILED: <шаг>» и код 1.
set -eu
MODE=${1:-apply}
BUCKET=${S3_BUCKET:?S3_BUCKET is not set}
: "${S3_API_ACCESS_KEY:?S3_API_ACCESS_KEY is empty, run make env}"
: "${S3_API_SECRET_KEY:?S3_API_SECRET_KEY is empty, run make env}"
: "${S3_CLEANER_ACCESS_KEY:?S3_CLEANER_ACCESS_KEY is empty, run make env}"
: "${S3_CLEANER_SECRET_KEY:?S3_CLEANER_SECRET_KEY is empty, run make env}"
: "${WEED_JWT_FILER_SIGNING_KEY:?S3_JWT_SIGNING_KEY is empty, run make env}"
# префикс списка уборщика: имя базы и /attachments/; в JSON политики идёт
# только проверенное значение
LIST_PREFIX=${S3_CLEANER_LIST_PREFIX:-}
MASTER=127.0.0.1:9333
# порт API S3 внутри сети стенда фиксирован (compose.yaml)
S3=http://127.0.0.1:8333
API_USER=api
API_POLICY=api-objects
CLEANER_USER=cleaner
CLEANER_POLICY=cleaner-objects
# регион подписи; SeaweedFS берёт его из запроса
REGION=us-east-1
TAG="s3-bootstrap"
# проверочный объект make s3-check: один и тот же ключ, повтор
# перезаписывает остаток прерванного прогона
CHECK_KEY=.s3-check/probe
# объект проверок ключа уборщика: его он удаляет, общий нужен проверкам с
# хоста
CLEANER_CHECK_KEY=.s3-check/cleaner-probe
CHECK_BUCKET_PREFIX="${BUCKET}-check-"
# сколько секунд ждать, пока изменения IAM дойдут до шлюза (подписка на
# filer)
IAM_WAIT_SECONDS=10
umask 077
WORK=$(mktemp -d)
API_CRED="$WORK/api.cred"
CLEANER_CRED="$WORK/cleaner.cred"
BODY="$WORK/body"
TEMP_BUCKET=""
cleanup_work() {
if [ -n "$TEMP_BUCKET" ]; then
ws "s3.bucket.delete -name ${TEMP_BUCKET}" >/dev/null 2>&1 || true
fi
rm -rf "$WORK"
}
trap cleanup_work EXIT
say() {
echo "${TAG}: $*"
}
fail() {
echo "${TAG}: FAILED: $*" >&2
exit 1
}
# одна команда weed shell; вывод — в stdout, код — код shell
ws() {
printf '%s\n' "$1" | weed shell -master="$MASTER" 2>&1
}
# команда без секретов: при ошибке печатается вывод shell
ws_step() {
step=$1
shift
if ! out=$(ws "$*"); then
printf '%s\n' "$out" | sed "s/^/${TAG}: /" >&2
fail "$step"
fi
}
# команда с секретом: вывод не печатается никогда
ws_secret_step() {
step=$1
shift
ws "$*" >/dev/null || fail "$step"
}
# ключи API и уборщика для curl: файлы на tmpfs, в argv только путь
printf 'user = "%s:%s"\n' "$S3_API_ACCESS_KEY" "$S3_API_SECRET_KEY" \
>"$API_CRED"
printf 'user = "%s:%s"\n' "$S3_CLEANER_ACCESS_KEY" "$S3_CLEANER_SECRET_KEY" \
>"$CLEANER_CRED"
# подписанный ключом из файла $1 запрос: печатает код ответа, тело — в
# $BODY
signed_by() {
cred=$1
shift
curl -s -o "$BODY" -w '%{http_code}' --max-time 5 -K "$cred" \
--aws-sigv4 "aws:amz:${REGION}:s3" "$@" || echo 000
}
# подписанный ключом API запрос
signed() {
signed_by "$API_CRED" "$@"
}
# подписанный ключом уборщика запрос
cleaner_signed() {
signed_by "$CLEANER_CRED" "$@"
}
# анонимный запрос: печатает код ответа
anon() {
curl -s -o "$BODY" -w '%{http_code}' --max-time 5 "$@" || echo 000
}
FAILED_CHECKS=0
# строка проверки: имя, ожидаемый и полученный код. Код выхода 1 — в
# конце, после всех строк
check() {
name=$1
expected=$2
got=$3
if [ "$expected" = "$got" ]; then
verdict=ok
else
verdict=FAIL
FAILED_CHECKS=$((FAILED_CHECKS + 1))
fi
printf '%s: check\t%s\t%s\t%s\t%s\n' "$TAG" "$name" "$expected" "$got" "$verdict"
}
bucket_exists() {
ws "s3.bucket.list" | grep -qE "^[[:space:]]*$1([[:space:]]|\$)"
}
# ждать, пока ключ примет шлюз: изменения IAM доходят подпиской на filer.
# $1 — ожидаемый код, остальное — запрос signed_by с файлом ключа.
# SignatureDoesNotMatch — ключ есть, секрет другой: возвращается 2
wait_key() {
expected=$1
shift
i=0
while [ "$i" -lt "$IAM_WAIT_SECONDS" ]; do
code=$(signed_by "$@")
if [ "$code" = "$expected" ]; then
return 0
fi
if [ "$code" = 403 ] && grep -q SignatureDoesNotMatch "$BODY"; then
return 2
fi
i=$((i + 1))
sleep 1
done
return 1
}
# ключ API — записью проверочного объекта
wait_api_key() {
wait_key 200 "$API_CRED" -X PUT --data-binary "$TAG" "$1"
}
# ключ уборщика — удалением ключа, которого нет (запись ему запрещена):
# 204, как у удаления существующего
wait_cleaner_key() {
wait_key 204 "$CLEANER_CRED" -X DELETE "$1"
}
# ждать ключ пользователя $1 через функцию $2 с адресом $3; новый секрет
# (SignatureDoesNotMatch) — пересоздать ключ и ждать снова
wait_user_key() {
user=$1
waiter=$2
url=$3
status=0
"$waiter" "$url" || status=$?
if [ "$status" = 2 ]; then
recreate_key "$user"
status=0
"$waiter" "$url" || status=$?
fi
[ "$status" = 0 ] || fail "${user} key wait (code ${code})"
}
# ---------------------------------------------------------------- apply
apply_bucket() {
if bucket_exists "$BUCKET"; then
say "bucket ${BUCKET} exists"
else
ws_step "bucket create" "s3.bucket.create -name ${BUCKET}"
say "bucket ${BUCKET} created"
fi
# анонимный доступ — none; меняется, только если он открыт
if ! ws "s3.anonymous.get -bucket ${BUCKET}" | grep -q '^Access: none$'; then
ws_step "anonymous access none" \
"s3.anonymous.set -bucket ${BUCKET} -access none"
say "anonymous access to ${BUCKET} closed"
fi
}
# политика $1 с действиями $2 (JSON-список) над объектами своего bucket
put_policy() {
cat >"$WORK/policy.json" <<EOF
{"Version": "2012-10-17", "Statement": [{"Effect": "Allow",
"Action": $2,
"Resource": ["arn:aws:s3:::${BUCKET}/*"]}]}
EOF
ws_step "policy put $1" "s3.policy -put -name=$1 -file=$WORK/policy.json"
}
# префикс списка уборщика — только вида <база>/attachments/: иначе в
# условие политики попало бы что угодно
check_list_prefix() {
database=${LIST_PREFIX%/attachments/}
# ^[a-z0-9_]+/attachments/$: суффикс на месте, имя базы непустое и без
# других символов (в том числе перевода строки и «/»)
case "$database" in
"$LIST_PREFIX" | "" | *[!a-z0-9_]*)
fail "cleaner list prefix: S3_CLEANER_LIST_PREFIX must be <database>/attachments/"
;;
esac
}
# уборщику — чтение и удаление объектов своего bucket и их список только с
# префиксом вложений своей базы (условие s3:prefix соблюдает SeaweedFS 4.48:
# весь bucket, другой префикс и HEAD bucket — 403); без записи и прав на
# bucket
put_cleaner_policy() {
cat >"$WORK/policy.json" <<EOF
{"Version": "2012-10-17", "Statement": [{"Effect": "Allow",
"Action": ["s3:GetObject", "s3:DeleteObject"],
"Resource": ["arn:aws:s3:::${BUCKET}/*"]},
{"Effect": "Allow", "Action": ["s3:ListBucket"],
"Resource": ["arn:aws:s3:::${BUCKET}"],
"Condition": {"StringLike": {"s3:prefix": ["${LIST_PREFIX}*"]}}}]}
EOF
ws_step "policy put ${CLEANER_POLICY}" \
"s3.policy -put -name=${CLEANER_POLICY} -file=$WORK/policy.json"
}
apply_policies() {
put_policy "$API_POLICY" \
'["s3:GetObject", "s3:PutObject", "s3:DeleteObject"]'
put_cleaner_policy
}
# ключ и секрет пользователя $1 — из окружения (.env)
user_keys() {
case "$1" in
"$API_USER")
ACCESS_KEY=$S3_API_ACCESS_KEY
SECRET_KEY=$S3_API_SECRET_KEY
;;
"$CLEANER_USER")
ACCESS_KEY=$S3_CLEANER_ACCESS_KEY
SECRET_KEY=$S3_CLEANER_SECRET_KEY
;;
*) fail "unknown user $1" ;;
esac
}
# пользователь $1 с политикой $2 и ключом из окружения; повтор — no-op
apply_user() {
name=$1
policy=$2
user_keys "$name"
if ws "s3.user.show -name ${name}" >/dev/null; then
say "user ${name} exists"
else
ws_secret_step "user ${name} create" \
"s3.user.create -name ${name} -access_key ${ACCESS_KEY} -secret_key ${SECRET_KEY}"
say "user ${name} created"
fi
ws_step "policy attach ${name}" \
"s3.policy.attach -policy ${policy} -user ${name}"
# ключи пользователя: чужие удаляются, нужного нет — создаётся
if ! keys_out=$(ws "s3.accesskey.list -user ${name}"); then
fail "access key list ${name}"
fi
keys=$(printf '%s\n' "$keys_out" | awk 'NR > 1 && NF { print $1 }')
for key in $keys; do
if [ "$key" != "$ACCESS_KEY" ]; then
ws_secret_step "stale key delete ${name}" \
"s3.accesskey.delete -user ${name} -access_key ${key}"
say "stale key of ${name} removed"
fi
done
if ! printf '%s\n' "$keys" | grep -qxF "$ACCESS_KEY"; then
ws_secret_step "key create ${name}" \
"s3.accesskey.create -user ${name} -access_key ${ACCESS_KEY} -secret_key ${SECRET_KEY}"
say "key of ${name} created"
fi
}
recreate_key() {
user_keys "$1"
ws_secret_step "key delete $1" \
"s3.accesskey.delete -user $1 -access_key ${ACCESS_KEY}"
ws_secret_step "key create $1" \
"s3.accesskey.create -user $1 -access_key ${ACCESS_KEY} -secret_key ${SECRET_KEY}"
say "key of $1 recreated (secret changed)"
}
# проверки каждого запуска: ключ API пишет и читает проверочный объект,
# список и создание bucket — 403; ключ уборщика читает его, запись и
# список — 403, затем удаляет; после удаления ключ API получает 404;
# аноним не читает объект и не видит список
apply_checks() {
probe="${S3}/${BUCKET}/.s3-bootstrap/check-$$"
wait_user_key "$API_USER" wait_api_key "$probe"
[ "$(signed "$probe")" = 200 ] || fail "api key get"
[ "$(anon "$probe")" = 403 ] || fail "anonymous get is not denied"
[ "$(anon "${S3}/${BUCKET}?list-type=2")" = 403 ] \
|| fail "anonymous list is not denied"
[ "$(signed "${S3}/${BUCKET}?list-type=2")" = 403 ] \
|| fail "api key list is not denied"
[ "$(signed -X PUT "${S3}/${CHECK_BUCKET_PREFIX}forbidden-$$")" = 403 ] \
|| fail "api key bucket create is not denied"
wait_user_key "$CLEANER_USER" wait_cleaner_key \
"${S3}/${BUCKET}/.s3-bootstrap/missing-$$"
[ "$(cleaner_signed "$probe")" = 200 ] && [ "$(cat "$BODY")" = "$TAG" ] \
|| fail "cleaner key get"
[ "$(cleaner_signed -X PUT --data-binary "$TAG" "$probe")" = 403 ] \
|| fail "cleaner key put is not denied"
[ "$(cleaner_signed "${S3}/${BUCKET}?list-type=2")" = 403 ] \
|| fail "cleaner key list is not denied"
# список своего префикса: политика доходит до шлюза подпиской, как ключ
wait_key 200 "$CLEANER_CRED" "$(list_url "$LIST_PREFIX")" \
|| fail "cleaner key list ${LIST_PREFIX} (code ${code})"
[ "$(cleaner_signed -X DELETE "$probe")" = 204 ] || fail "cleaner key delete"
[ "$(signed "$probe")" = 404 ] || fail "object is still there after delete"
say "checks passed (api key put/get; cleaner key get/delete and list" \
"${LIST_PREFIX}; api key list and bucket create, cleaner key put and" \
"list of the bucket, anonymous get and list denied)"
}
# адрес ListObjectsV2 своего bucket с префиксом $1 (символы [a-z0-9_.-/],
# «/» — %2F в строке запроса подписи) и одним ключом
list_url() {
encoded=$(printf '%s' "$1" | sed 's#/#%2F#g')
printf '%s' "${S3}/${BUCKET}?list-type=2&max-keys=1&prefix=${encoded}"
}
# ---------------------------------------------------------------- check
run_checks() {
bucket_exists "$BUCKET" || fail "bucket ${BUCKET} does not exist, run make up"
access=$(ws "s3.anonymous.get -bucket ${BUCKET}" \
| sed -n 's/^Access: //p')
check "anonymous access setting" none "${access:-unknown}"
obj="${S3}/${BUCKET}/${CHECK_KEY}"
missing="${S3}/${BUCKET}/.s3-check/missing-$$"
# ключ API: объекты своего bucket
check "api key put object" 200 \
"$(signed -X PUT --data-binary "$TAG check" "$obj")"
check "api key get object" 200 "$(signed "$obj")"
check "api key head object" 200 "$(signed -I "$obj")"
check "api key get missing object" 404 "$(signed "$missing")"
# ключ API: всё остальное запрещено
check "api key list objects" 403 "$(signed "${S3}/${BUCKET}?list-type=2")"
check "api key create bucket" 403 \
"$(signed -X PUT "${S3}/${CHECK_BUCKET_PREFIX}forbidden-$$")"
check "api key delete bucket" 403 "$(signed -X DELETE "${S3}/${BUCKET}")"
check "api key get bucket policy" 403 "$(signed "${S3}/${BUCKET}?policy")"
check "api key put bucket policy" 403 \
"$(signed -X PUT --data-binary '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":"*","Action":"s3:GetObject","Resource":"arn:aws:s3:::'"${BUCKET}"'/*"}]}' "${S3}/${BUCKET}?policy")"
check "api key get bucket acl" 403 "$(signed "${S3}/${BUCKET}?acl")"
check "api key put bucket acl public-read" 403 \
"$(signed -X PUT -H 'x-amz-acl: public-read' "${S3}/${BUCKET}?acl")"
check "api key put object acl public-read" 403 \
"$(signed -X PUT -H 'x-amz-acl: public-read' "${obj}?acl")"
# ключ уборщика: чтение и удаление объектов своего bucket; удаляет он
# свой проверочный объект, общий нужен проверкам с хоста
own="${S3}/${BUCKET}/${CLEANER_CHECK_KEY}"
check "api key put cleaner probe object" 200 \
"$(signed -X PUT --data-binary "$TAG cleaner" "$own")"
check "cleaner key get object" 200 "$(cleaner_signed "$own")"
check "cleaner key head object" 200 "$(cleaner_signed -I "$own")"
check "cleaner key delete object" 204 "$(cleaner_signed -X DELETE "$own")"
check "cleaner key delete object again" 204 \
"$(cleaner_signed -X DELETE "$own")"
check "api key get deleted object" 404 "$(signed "$own")"
check "cleaner key delete missing object" 204 \
"$(cleaner_signed -X DELETE "$missing")"
# ключ уборщика: запись, список и всё, что с bucket, запрещено
check "cleaner key put object" 403 \
"$(cleaner_signed -X PUT --data-binary "$TAG" "$own")"
check "cleaner key list objects" 403 \
"$(cleaner_signed "${S3}/${BUCKET}?list-type=2")"
check "cleaner key list attachments prefix" 200 \
"$(cleaner_signed "$(list_url "$LIST_PREFIX")")"
check "cleaner key list other prefix" 403 \
"$(cleaner_signed "$(list_url .s3-check/)")"
check "cleaner key create bucket" 403 \
"$(cleaner_signed -X PUT "${S3}/${CHECK_BUCKET_PREFIX}forbidden-$$")"
check "cleaner key delete bucket" 403 \
"$(cleaner_signed -X DELETE "${S3}/${BUCKET}")"
check "cleaner key get bucket policy" 403 \
"$(cleaner_signed "${S3}/${BUCKET}?policy")"
check "cleaner key put bucket policy" 403 \
"$(cleaner_signed -X PUT --data-binary '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":"*","Action":"s3:GetObject","Resource":"arn:aws:s3:::'"${BUCKET}"'/*"}]}' "${S3}/${BUCKET}?policy")"
check "cleaner key get bucket acl" 403 \
"$(cleaner_signed "${S3}/${BUCKET}?acl")"
check "cleaner key put bucket acl public-read" 403 \
"$(cleaner_signed -X PUT -H 'x-amz-acl: public-read' "${S3}/${BUCKET}?acl")"
check "cleaner key put object acl public-read" 403 \
"$(cleaner_signed -X PUT -H 'x-amz-acl: public-read' "${obj}?acl")"
# чужой bucket: временный, создаёт и удаляет weed shell
TEMP_BUCKET="${CHECK_BUCKET_PREFIX}$(od -An -N4 -tx4 /dev/urandom | tr -d ' ')"
ws_step "temporary bucket create" "s3.bucket.create -name ${TEMP_BUCKET}"
other="${S3}/${TEMP_BUCKET}"
check "api key put object to other bucket" 403 \
"$(signed -X PUT --data-binary "$TAG" "${other}/probe")"
check "api key get object from other bucket" 403 "$(signed "${other}/probe")"
check "api key list other bucket" 403 "$(signed "${other}?list-type=2")"
check "api key delete other bucket" 403 "$(signed -X DELETE "$other")"
check "cleaner key get object from other bucket" 403 \
"$(cleaner_signed "${other}/probe")"
check "cleaner key delete object in other bucket" 403 \
"$(cleaner_signed -X DELETE "${other}/probe")"
check "cleaner key list other bucket" 403 \
"$(cleaner_signed "${other}?list-type=2")"
check "cleaner key delete other bucket" 403 \
"$(cleaner_signed -X DELETE "$other")"
ws_step "temporary bucket delete" "s3.bucket.delete -name ${TEMP_BUCKET}"
TEMP_BUCKET=""
# аноним изнутри сервера; с хоста и из сети стенда — make s3-check
check "anonymous get object" 403 "$(anon "$obj")"
check "anonymous head object" 403 "$(anon -I "$obj")"
check "anonymous get missing object" 403 "$(anon "$missing")"
check "anonymous list objects" 403 "$(anon "${S3}/${BUCKET}?list-type=2")"
check "anonymous list buckets" 403 "$(anon "${S3}/")"
check "anonymous put object" 403 \
"$(anon -X PUT --data-binary "$TAG" "${S3}/${BUCKET}/.s3-check/anonymous")"
check "anonymous create bucket" 403 \
"$(anon -X PUT "${S3}/${CHECK_BUCKET_PREFIX}anonymous-$$")"
if [ "$FAILED_CHECKS" -gt 0 ]; then
fail "${FAILED_CHECKS} check(s) failed"
fi
say "checks passed; probe object ${BUCKET}/${CHECK_KEY} kept for host and network checks"
}
run_cleanup() {
for key in "$CHECK_KEY" "$CLEANER_CHECK_KEY"; do
code=$(signed -X DELETE "${S3}/${BUCKET}/${key}")
case "$code" in
204 | 404) say "probe object ${BUCKET}/${key} removed" ;;
*) fail "probe object delete (code ${code})" ;;
esac
done
# временные bucket-ы прерванных проверок
for name in $(ws "s3.bucket.list" | awk '{ print $1 }' \
| grep -E "^${CHECK_BUCKET_PREFIX}[0-9a-f]+\$" || true); do
ws_step "temporary bucket delete" "s3.bucket.delete -name ${name}"
say "temporary bucket ${name} removed"
done
}
case "$MODE" in
apply | check) check_list_prefix ;;
esac
case "$MODE" in
apply)
apply_bucket
apply_policies
apply_user "$API_USER" "$API_POLICY"
apply_user "$CLEANER_USER" "$CLEANER_POLICY"
apply_checks
;;
check) run_checks ;;
cleanup) run_cleanup ;;
*) fail "unknown mode ${MODE}: apply, check or cleanup" ;;
esac
+15
View File
@@ -0,0 +1,15 @@
# Valkey стенда — кэш карточек чатов (src/storage/cached.py).
# Монтируется в контейнер только на чтение. Пароль задаёт command в
# compose.yaml из переменной контейнера, здесь его нет.
# лимит памяти; при нехватке вытесняются давно не читанные ключи
maxmemory 64mb
maxmemory-policy allkeys-lru
# persistence выключен: источник истины — PostgreSQL, кэш после рестарта
# пуст и заполняется заново при чтении
save ""
appendonly no
# без пароля сервер не примет соединения извне контейнера
protected-mode yes
+98
View File
@@ -0,0 +1,98 @@
# migrations/ — схема PostgreSQL (alembic)
Схема создаётся миграциями до первого запроса: одноразовый сервис
compose `migrate` (тот же образ, `python -m alembic upgrade head`)
завершается с кодом 0, и только потом стартуют реплики `api`. Реплики
сами миграции не запускают: их несколько, и они гонялись бы за одну
схему. При поочерёдной замене миграции — один раз, на новом образе, до
первой новой реплики (`scripts/rolling-update.sh`). С хоста —
`make migrate-local` (его же вызывает `make run`). Адрес базы
`env.py` собирает из тех же переменных `DB_*`, что и приложение.
Ревизии: `0001` — схема лабы 2 (пользователи, сессии, чаты, участники,
сообщения); `0002` — `idempotency_keys` (лаба 3): первичный ключ (автор,
чат, ключ), внешний ключ `(chat_id, user_id) → chat_members`, ссылка на
сообщение `DEFERRABLE INITIALLY DEFERRED` (ключ вставляется раньше
сообщения в той же транзакции), `CHECK` формата ключа и длины хэша,
индекс по `created_at` для уборки просроченных; `0003` — вложения (лаба
4): `attachments` (внешний ключ `(chat_id, owner_id) → chat_members`,
уникальный `object_key`, `CHECK` статуса, типа, размера, длины SHA-256 и
`filename`, `lost_at` — пометка потерянного оригинала, частичный индекс
`ix_attachments_pending_created_at (created_at, id) WHERE status =
'pending'` для уборщика) и `message_attachments` (первичный ключ
`(message_id, position)`, уникальная пара `(message_id, attachment_id)`,
`position` 0–9, внешние ключи без каскада, индекс по `attachment_id`);
`ck_messages_text_length` ослаблен до `char_length(text) <= 4000`
(пустой текст — только с вложением, это правило API) и добавлен заново
`NOT VALID`: проверка старых строк не нужна (прежнее условие строже), а
полный обход `messages` под блокировкой — не нужен тем более. Ревизия
начинается с `SET LOCAL lock_timeout = '2s'`.
## Совместимость с работающей версией (с лабы 3)
Во время поочерёдной замены старые реплики работают на новой схеме,
пока их не заменят. Поэтому ревизия **только расширяет** схему (expand):
- новые таблицы; новые колонки `NULL` или с `server_default`; индексы
(на большой таблице — `CREATE INDEX CONCURRENTLY` вне транзакции);
- удаление и переименование колонок и таблиц, `NOT NULL` без значения по
умолчанию — отдельной ревизией **после** того, как старого кода не
осталось (expand → contract); нельзя так — ограничение в `REPORT.md`;
- первой строкой ревизии, которая берёт блокировку на рабочую таблицу
(`ADD COLUMN`, внешний ключ на неё, `ALTER`), — `op.execute("SET LOCAL
lock_timeout = '2s'")`: за ожидающей блокировкой встают все новые
запросы к таблице, и чужая долгая транзакция остановила бы запись всех
реплик. По сроку миграция падает без изменений, замена не начинается,
повтор проходит. 2 с меньше `DB_STATEMENT_TIMEOUT_MS` (5 с): запросы в
очереди за миграцией дожидаются её отказа, а не падают вместе с ней;
- в ревизиях — литералы, а не константы `src`: применённая ревизия не
меняется вместе с кодом.
Под нагрузкой это проверяет профиль `rollout` стенда `bench/`: он
добавляет в образ пробную expand-ревизию `9001_rollout_probe` (только в
образе и базе стенда, `bench/common.py`) и меняет реплики, пока идут
запись и чтение.
## Правила
- Ревизии: `versions/<номер>_<slug>.py`, номер по порядку (`0001`,
`0002`, ...), задаётся при создании: `uv run alembic revision
--rev-id 0002 -m "<что изменилось, англ.>"`. Цепочка линейная.
- **Применённую ревизию не править**: она уже стоит на volume рабочего
стенда и у проверяющего. Любое изменение — новая ревизия с
`upgrade()` и `downgrade()`.
- Описание схемы для запросов — `src/storage/tables.py`. Ревизия и
`tables.py` меняются вместе; расхождение ловит `alembic check` (ниже).
Имена ограничений и индексов — явные, в стиле `pk_<таблица>`,
`uq_<таблица>_<колонки>`, `fk_<таблица>_<колонки>_<таблица>`,
`ck_<таблица>_<смысл>`, `ix_<таблица>_<колонки>`: по имени их снимает
`downgrade()`, по нему же индекс виден в планах запроса.
- Повторный запуск миграций — no-op (alembic хранит версию в
`alembic_version`), данные не дублируются: так `scripts/restart.sh`
может запускать `migrate` на каждом старте реплик.
- Миграция с данными (не только схема) — без чтения в Python всей
таблицы: SQL одним оператором, в журнал — число затронутых строк. Если
миграция удаляет данные — сказать пользователю до запуска.
- Индекс на большой таблице рабочего стенда — `CREATE INDEX
CONCURRENTLY` в ревизии с `autocommit_block()`; на учебном стенде
допустим и обычный, но в `REPORT.md` — время и блокировка.
- `CHECK` дублируют контракт (первым отвечает API 400); новый лимит
контракта — в `src/constants.py` и в `CHECK` одной ревизией.
## Проверка ревизии
1. `make db-up`, затем `make migrate-local`.
2. `alembic check` с хоста — «No new upgrade operations detected»:
```sh
set -a; . ./.env; set +a
DB_HOST=127.0.0.1 DB_PORT=$POSTGRES_HOST_PORT DB_NAME=$POSTGRES_DB \
DB_USER=$POSTGRES_USER DB_PASSWORD=$POSTGRES_PASSWORD uv run alembic check
```
(переменные из `.env` в выводе не печатаются).
3. С нуля и повторно: `make test-isolated` поднимает пустую базу и
применяет все ревизии; `docker compose run --rm migrate` на рабочем
стенде — no-op.
4. `downgrade -1` и снова `upgrade head` на отдельном стенде, не на
рабочем (раздел 2 корневого `AGENTS.md`, п. 8).
+82
View File
@@ -0,0 +1,82 @@
"""Окружение alembic: адрес базы и формат журнала — как у приложения.
URL собирается из тех же переменных `DB_*` (`src/config.py`) и не
проходит через ConfigParser alembic, поэтому `%` в пароле ничего не
ломает. Журнал — текстовый формат `src/log.py`: у процесса миграций нет
uvicorn, который применил бы его сам, поэтому конфиг применяется здесь.
Асинхронное только подключение; ревизии — синхронный код `op.*`.
Неверная переменная окружения — та же строка `configuration error` и
код 2, что у сервиса.
"""
import asyncio
import logging.config
import sys
from alembic import context
from sqlalchemy import pool
from sqlalchemy.engine import Connection
from sqlalchemy.ext.asyncio import create_async_engine
from src.config import ConfigError, Settings
from src.db import database_url
from src.log import get_logger, logging_config
from src.storage.tables import metadata
try:
settings = Settings.from_env()
except ConfigError as exc:
print(f"configuration error: {exc}", file=sys.stderr)
raise SystemExit(2) from None
logging.config.dictConfig(logging_config(settings.log_level))
log = get_logger("src.migrations")
target_metadata = metadata
def run_migrations_offline() -> None:
"""SQL без подключения: `alembic upgrade head --sql`."""
context.configure(
url=database_url(settings.database),
target_metadata=target_metadata,
literal_binds=True,
dialect_opts={"paramstyle": "named"},
)
with context.begin_transaction():
context.run_migrations()
def do_run_migrations(connection: Connection) -> None:
context.configure(connection=connection, target_metadata=target_metadata)
with context.begin_transaction():
context.run_migrations()
async def run_async_migrations() -> None:
database = settings.database
# по журналу видно, какую базу мигрировали; пароля в строке нет
log.info(
"migrations started db=%s:%d/%s",
database.host,
database.port,
database.name,
)
engine = create_async_engine(
database_url(database),
poolclass=pool.NullPool,
connect_args={"timeout": database.connect_timeout},
)
try:
async with engine.connect() as connection:
await connection.run_sync(do_run_migrations)
finally:
await engine.dispose()
log.info("migrations finished db=%s", database.name)
if context.is_offline_mode():
run_migrations_offline()
else:
asyncio.run(run_async_migrations())
+25
View File
@@ -0,0 +1,25 @@
"""${message}
Revision ID: ${up_revision}
Revises: ${down_revision | comma,n}
Create Date: ${create_date}
"""
from collections.abc import Sequence
import sqlalchemy as sa
from alembic import op
${imports if imports else ""}
revision: str = ${repr(up_revision)}
down_revision: str | Sequence[str] | None = ${repr(down_revision)}
branch_labels: str | Sequence[str] | None = ${repr(branch_labels)}
depends_on: str | Sequence[str] | None = ${repr(depends_on)}
def upgrade() -> None:
${upgrades if upgrades else "pass"}
def downgrade() -> None:
${downgrades if downgrades else "pass"}
@@ -0,0 +1,147 @@
"""messenger schema: users, sessions, chats, chat members, messages
Revision ID: 0001
Revises:
Create Date: 2026-10-02
Схема лабы 2 целиком: в лабе 1 хранилище было в памяти процесса, данных
для переноса нет. Таблицы и ограничения — как в `src/storage/tables.py`
(`alembic check` сверяет), обоснование — REPORT.md, «Схема».
"""
from collections.abc import Sequence
import sqlalchemy as sa
from alembic import op
revision: str = "0001"
down_revision: str | Sequence[str] | None = None
branch_labels: str | Sequence[str] | None = None
depends_on: str | Sequence[str] | None = None
def upgrade() -> None:
op.create_table(
"users",
sa.Column("id", sa.Uuid(), nullable=False),
sa.Column("username", sa.Text(), nullable=False),
sa.Column("display_name", sa.Text(), nullable=False),
sa.Column("password_hash", sa.Text(), nullable=False),
sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
sa.PrimaryKeyConstraint("id", name="pk_users"),
sa.UniqueConstraint("username", name="uq_users_username"),
sa.CheckConstraint(
"username ~ '^[a-z0-9_]{3,32}$'",
name="ck_users_username_format",
),
sa.CheckConstraint(
"char_length(display_name) BETWEEN 1 AND 100",
name="ck_users_display_name_length",
),
sa.CheckConstraint(
"password_hash LIKE '$argon2id$%'",
name="ck_users_password_hash_argon2id",
),
)
op.create_table(
"sessions",
sa.Column("id", sa.Uuid(), nullable=False),
sa.Column("user_id", sa.Uuid(), nullable=False),
sa.Column("token_hash", sa.LargeBinary(), nullable=False),
sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
sa.PrimaryKeyConstraint("id", name="pk_sessions"),
sa.ForeignKeyConstraint(
["user_id"],
["users.id"],
name="fk_sessions_user_id_users",
),
sa.UniqueConstraint("token_hash", name="uq_sessions_token_hash"),
sa.CheckConstraint(
"octet_length(token_hash) = 32",
name="ck_sessions_token_hash_length",
),
sa.CheckConstraint(
"expires_at > created_at",
name="ck_sessions_expires_after_created",
),
)
op.create_table(
"chats",
sa.Column("id", sa.Uuid(), nullable=False),
sa.Column("title", sa.Text(), nullable=False),
sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
sa.PrimaryKeyConstraint("id", name="pk_chats"),
sa.CheckConstraint(
"char_length(title) BETWEEN 1 AND 100",
name="ck_chats_title_length",
),
)
op.create_table(
"chat_members",
sa.Column("chat_id", sa.Uuid(), nullable=False),
sa.Column("user_id", sa.Uuid(), nullable=False),
sa.Column("position", sa.SmallInteger(), nullable=False),
sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
sa.PrimaryKeyConstraint("chat_id", "user_id", name="pk_chat_members"),
sa.ForeignKeyConstraint(
["chat_id"],
["chats.id"],
name="fk_chat_members_chat_id_chats",
),
sa.ForeignKeyConstraint(
["user_id"],
["users.id"],
name="fk_chat_members_user_id_users",
),
sa.UniqueConstraint(
"chat_id",
"position",
name="uq_chat_members_chat_id_position",
),
sa.CheckConstraint(
"position >= 0",
name="ck_chat_members_position_non_negative",
),
)
op.create_index(
"ix_chat_members_user_id_created_at_chat_id",
"chat_members",
["user_id", "created_at", "chat_id"],
)
op.create_table(
"messages",
sa.Column("id", sa.Uuid(), nullable=False),
sa.Column("chat_id", sa.Uuid(), nullable=False),
sa.Column("sender_id", sa.Uuid(), nullable=False),
sa.Column("text", sa.Text(), nullable=False),
sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
sa.PrimaryKeyConstraint("id", name="pk_messages"),
sa.ForeignKeyConstraint(
["chat_id", "sender_id"],
["chat_members.chat_id", "chat_members.user_id"],
name="fk_messages_chat_id_sender_id_chat_members",
),
sa.CheckConstraint(
"char_length(text) BETWEEN 1 AND 4000",
name="ck_messages_text_length",
),
)
op.create_index(
"ix_messages_chat_id_created_at_id",
"messages",
["chat_id", "created_at", "id"],
)
def downgrade() -> None:
op.drop_index("ix_messages_chat_id_created_at_id", table_name="messages")
op.drop_table("messages")
op.drop_index(
"ix_chat_members_user_id_created_at_chat_id",
table_name="chat_members",
)
op.drop_table("chat_members")
op.drop_table("chats")
op.drop_table("sessions")
op.drop_table("users")
@@ -0,0 +1,81 @@
"""idempotency keys for sending messages
Revision ID: 0002
Revises: 0001
Create Date: 2026-10-14
Лаба 3: `Idempotency-Key` обязателен при отправке сообщения, ключ и
сообщение пишутся одной транзакцией (`src/storage/postgres.py`).
Только расширение схемы (expand): новая таблица, существующие не
меняются. Реплики прежней версии на этой схеме работают как раньше —
таблицу ключей они не замечают, поэтому поочерёдная замена может
применить ревизию до первой новой реплики (`scripts/rolling-update.sh`).
Новая таблица пуста, `CREATE TABLE` не блокирует таблицы, которые читают
работающие реплики, кроме короткой ссылки на `messages` и
`chat_members` (`SHARE ROW EXCLUSIVE` на время создания внешних ключей).
"""
from collections.abc import Sequence
import sqlalchemy as sa
from alembic import op
revision: str = "0002"
down_revision: str | Sequence[str] | None = "0001"
branch_labels: str | Sequence[str] | None = None
depends_on: str | Sequence[str] | None = None
def upgrade() -> None:
# ожидание блокировки ограничено: долгая чужая транзакция на messages
# не выстроит за миграцией очередь из запросов всех реплик — миграция
# упадёт без изменений, и её можно повторить
op.execute("SET LOCAL lock_timeout = '2s'")
op.create_table(
"idempotency_keys",
sa.Column("user_id", sa.Uuid(), nullable=False),
sa.Column("chat_id", sa.Uuid(), nullable=False),
sa.Column("key", sa.Text(), nullable=False),
sa.Column("request_hash", sa.LargeBinary(), nullable=False),
sa.Column("message_id", sa.Uuid(), nullable=False),
sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
sa.PrimaryKeyConstraint(
"user_id",
"chat_id",
"key",
name="pk_idempotency_keys",
),
sa.ForeignKeyConstraint(
["chat_id", "user_id"],
["chat_members.chat_id", "chat_members.user_id"],
name="fk_idempotency_keys_chat_id_user_id_chat_members",
),
# ключ вставляется раньше сообщения в той же транзакции: ссылка
# проверяется при commit
sa.ForeignKeyConstraint(
["message_id"],
["messages.id"],
name="fk_idempotency_keys_message_id_messages",
deferrable=True,
initially="DEFERRED",
),
sa.CheckConstraint(
"key ~ '^[A-Za-z0-9._:-]{1,128}$'",
name="ck_idempotency_keys_key_format",
),
sa.CheckConstraint(
"octet_length(request_hash) = 32",
name="ck_idempotency_keys_request_hash_length",
),
)
op.create_index(
"ix_idempotency_keys_created_at",
"idempotency_keys",
["created_at"],
)
def downgrade() -> None:
op.drop_index("ix_idempotency_keys_created_at", table_name="idempotency_keys")
op.drop_table("idempotency_keys")
+169
View File
@@ -0,0 +1,169 @@
"""attachments and message attachments
Revision ID: 0003
Revises: 0002
Create Date: 2026-10-23
Лаба 4: вложения-изображения. Метаданные — здесь, байты — объект
`object_key` в приватном bucket S3 (`src/storage/objects.py`).
Только расширение схемы (expand):
- таблица `attachments`: строка `pending` пишется до записи объекта и
становится `ready` после неё; составной внешний ключ `(chat_id,
owner_id) → chat_members` (владелец — участник чата), уникальный
`object_key`, `CHECK` типа, статуса, размера, SHA-256, длины и символов
`filename`; `lost_at` — пометка сверки «оригинал потерян»; частичный
индекс строк `pending` по `(created_at, id)` — кандидаты уборщика;
- таблица `message_attachments`: вложения сообщения с порядком
`position`, внешние ключи без каскада — вложение со ссылкой из
сообщения БД удалить не даст;
- ограничение текста сообщения **ослаблено** с 1–4000 до `<= 4000`:
пустой текст допустим с вложением (правило держит схема API). Новое
ограничение — `NOT VALID`: прежние строки строже нового условия,
проверять их нечего, а `VALIDATE` держал бы `ACCESS EXCLUSIVE` на время
полного просмотра `messages`. Отметка «не проверено» в каталоге — цена.
Реплики лабы 3 на этой схеме работают как раньше: новых таблиц они не
замечают, а их сообщения удовлетворяют новому ограничению. Таблицы
новые и пустые, поэтому индексы создаются обычным `CREATE INDEX` в той
же транзакции. Блокировки на рабочие таблицы (`messages`,
`chat_members` — внешние ключи и замена `CHECK`) ограничены
`lock_timeout`.
"""
from collections.abc import Sequence
import sqlalchemy as sa
from alembic import op
revision: str = "0003"
down_revision: str | Sequence[str] | None = "0002"
branch_labels: str | Sequence[str] | None = None
depends_on: str | Sequence[str] | None = None
def upgrade() -> None:
# чужая долгая транзакция на messages не выстроит за миграцией очередь
# из запросов всех реплик: по сроку — ошибка без изменений, повтор
op.execute("SET LOCAL lock_timeout = '2s'")
op.create_table(
"attachments",
sa.Column("id", sa.Uuid(), nullable=False),
sa.Column("chat_id", sa.Uuid(), nullable=False),
sa.Column("owner_id", sa.Uuid(), nullable=False),
sa.Column("filename", sa.Text(), nullable=False),
sa.Column("content_type", sa.Text(), nullable=False),
sa.Column("size_bytes", sa.Integer(), nullable=False),
sa.Column("sha256", sa.LargeBinary(), nullable=False),
sa.Column("object_key", sa.Text(), nullable=False),
sa.Column("status", sa.Text(), nullable=False),
sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
sa.Column("lost_at", sa.DateTime(timezone=True), nullable=True),
sa.PrimaryKeyConstraint("id", name="pk_attachments"),
sa.ForeignKeyConstraint(
["chat_id", "owner_id"],
["chat_members.chat_id", "chat_members.user_id"],
name="fk_attachments_chat_id_owner_id_chat_members",
),
sa.UniqueConstraint("object_key", name="uq_attachments_object_key"),
sa.CheckConstraint(
"content_type IN ('image/png', 'image/jpeg')",
name="ck_attachments_content_type",
),
sa.CheckConstraint(
"status IN ('pending', 'ready')",
name="ck_attachments_status",
),
sa.CheckConstraint(
"size_bytes BETWEEN 1 AND 10485760",
name="ck_attachments_size_bytes",
),
sa.CheckConstraint(
"octet_length(sha256) = 32",
name="ck_attachments_sha256_length",
),
sa.CheckConstraint(
"char_length(filename) BETWEEN 1 AND 255",
name="ck_attachments_filename_length",
),
# без `/`, `\` и управляющих символов (категория Cc)
sa.CheckConstraint(
r"filename !~ '[/\\\u0001-\u001f\u007f-\u009f]'",
name="ck_attachments_filename_chars",
),
sa.CheckConstraint(
"octet_length(object_key) BETWEEN 1 AND 1024",
name="ck_attachments_object_key_length",
),
sa.CheckConstraint(
"updated_at >= created_at",
name="ck_attachments_updated_after_created",
),
)
op.create_index(
"ix_attachments_pending_created_at",
"attachments",
["created_at", "id"],
postgresql_where=sa.text("status = 'pending'"),
)
op.create_table(
"message_attachments",
sa.Column("message_id", sa.Uuid(), nullable=False),
sa.Column("position", sa.SmallInteger(), nullable=False),
sa.Column("attachment_id", sa.Uuid(), nullable=False),
sa.PrimaryKeyConstraint(
"message_id",
"position",
name="pk_message_attachments",
),
sa.ForeignKeyConstraint(
["message_id"],
["messages.id"],
name="fk_message_attachments_message_id_messages",
),
sa.ForeignKeyConstraint(
["attachment_id"],
["attachments.id"],
name="fk_message_attachments_attachment_id_attachments",
),
sa.UniqueConstraint(
"message_id",
"attachment_id",
name="uq_message_attachments_message_id_attachment_id",
),
sa.CheckConstraint(
"position BETWEEN 0 AND 9",
name="ck_message_attachments_position_range",
),
)
op.create_index(
"ix_message_attachments_attachment_id",
"message_attachments",
["attachment_id"],
)
# ослабление текста: DROP и ADD ... NOT VALID в одной транзакции —
# без просмотра messages. Autogenerate изменение CHECK не видит
op.drop_constraint("ck_messages_text_length", "messages", type_="check")
op.execute(
"ALTER TABLE messages ADD CONSTRAINT ck_messages_text_length "
"CHECK (char_length(text) <= 4000) NOT VALID",
)
def downgrade() -> None:
# прежнее строгое ограничение тоже NOT VALID: строки с пустым текстом
# и вложением, записанные новой версией, остаются в таблице
op.execute("SET LOCAL lock_timeout = '2s'")
op.drop_constraint("ck_messages_text_length", "messages", type_="check")
op.execute(
"ALTER TABLE messages ADD CONSTRAINT ck_messages_text_length "
"CHECK (char_length(text) BETWEEN 1 AND 4000) NOT VALID",
)
op.drop_index(
"ix_message_attachments_attachment_id", table_name="message_attachments"
)
op.drop_table("message_attachments")
op.drop_index("ix_attachments_pending_created_at", table_name="attachments")
op.drop_table("attachments")
+64
View File
@@ -0,0 +1,64 @@
[project]
name = "mtusi-messenger"
version = "0.4.0"
description = "Lab 4: messenger REST API with image attachments in private S3 (SeaweedFS)"
requires-python = ">=3.13,<3.14"
dependencies = [
"fastapi>=0.120,<1",
"uvicorn>=0.38,<1",
# PostgreSQL: SQLAlchemy Core поверх asyncpg — пул, таймауты и
# параметризованные запросы; extra asyncio ставит greenlet
"sqlalchemy[asyncio]>=2.1.1,<2.2",
"asyncpg>=0.31,<0.32",
# миграции; в основной группе: сервис migrate работает на образе API
"alembic>=1.20,<2",
# Argon2id для паролей: bcrypt режет пароль на 72 байтах
"argon2-cffi>=25.1,<26",
# клиент Valkey: протокол Redis, асинхронный клиент redis.asyncio
"redis>=8.1,<9",
# клиент S3 (лаба 4): асинхронный поверх botocore (SigV4, ListObjectsV2,
# потоковое чтение). botocore aiobotocore закрепляет узко — обновлять
# вместе через uv lock
"aiobotocore>=3.9.2,<4",
]
[dependency-groups]
dev = [
# student-tests: httpx.Client против запущенного стенда
"pytest>=8.4,<10",
"httpx>=0.28,<1",
"ruff>=0.16,<0.17",
# make validate (полная проверка OpenAPI skeleton)
"openapi-spec-validator==0.7.2",
]
[tool.uv]
# приложение не собирается пакетом: запуск `python -m src` из корня
package = false
[tool.ruff]
line-length = 88
target-version = "py313"
# first-party для isort: пакет src и хелперы набора student-tests
src = [".", "student-tests"]
# публичные проверки skeleton не форматируем и не правим; свои скрипты в
# scripts/ (lab3.py) линтер проверяет
extend-exclude = ["tests", "scripts/check_contract.py", "scripts/validate_openapi.py"]
[tool.ruff.lint]
select = ["E", "F", "W", "I", "B", "UP", "SIM", "C4", "RET", "PT", "ASYNC"]
[tool.ruff.lint.per-file-ignores]
# стенд собирает строки markdown-таблиц и SVG: они длиннее 88 символов
"bench/*.py" = ["E501"]
[tool.pytest.ini_options]
testpaths = ["student-tests"]
# хелперы набора импортируются из его каталога
pythonpath = ["student-tests"]
# проверки отказов (маркер fault) — только make failure-checks: там
# pytest -m fault перекрывает этот -m
addopts = "-ra --strict-markers -m 'not fault'"
markers = [
"fault: проверка отказа хранилища; нужен стенд make failure-checks и его hook",
]
+396
View File
@@ -0,0 +1,396 @@
aiobotocore==3.10.0 \
--hash=sha256:35480ef11c51e23087273b85d97f80da2f356a46ce5f3fb88e24483cd343ffdb \
--hash=sha256:de0ccbcb82b6b0009f1b6667f48442e9d0432f9b8bfe6172fa51777cbea89d03
# via mtusi-messenger
aiohappyeyeballs==2.7.1 \
--hash=sha256:065665c041c42a5938ed220bdcd7230f22527fbec085e1853d2402c8a3615d9d \
--hash=sha256:9243213661e29250eb41368e5daa826fc017156c3b8a11440826b2e3ed376472
# via aiohttp
aiohttp==3.14.5 \
--hash=sha256:15a310d3c71398e3d7bfc93a1a73fbe664315cd9e9016b8efc1cff85eeab7155 \
--hash=sha256:1b5416552740edf07234cc9437d0706f2acb67b93c198670b1a68e1b2b587dec \
--hash=sha256:1ffa3a523a36d8628f98c06492ae16a31a23d14c0b4ec721757b477319f656d6 \
--hash=sha256:3ae800a20947e2c2e53088047d021e6bf7d51560cc49f6a0737a1f79d2e3a13c \
--hash=sha256:42b5e616946dbaf505e2bff18c9af2cd4ef9e7ef300ee58a6e951a5b7cf147ae \
--hash=sha256:42f320d4a5b00b9af0bddcfec5407dc6f2d9816f006b2f79ebbaa31f16895df3 \
--hash=sha256:43351bdb5e4c3cb7d1772368e988534e869a74db7778079a83782c11c69535c7 \
--hash=sha256:43e1b7994a8b038125f722bff07492ef501110722c2727c408995d9fb864c421 \
--hash=sha256:5558a7f5a05af9ecf744af91e5baefc436f93c9333e656c27ec253f9a6bbe178 \
--hash=sha256:5f3e96071686755d9cd3600c3880183eb94b012178e92746d68101800f0ed8a3 \
--hash=sha256:5fb6a6e919bfb703227bc1ce6579281b84b1a2ba57deb9794dfdbec7dcd1e40c \
--hash=sha256:74efb69332b85675b1eabd760a8cfc2e2cf42c60607c66f88014c1bdfb40942d \
--hash=sha256:9ad7e6aa38c20da1be697874349c4c273c8a03b7887169665081706398d0439a \
--hash=sha256:a9918e58faf62ba2c7147927d06057aec78f42475aff5048047ec47e7265a600 \
--hash=sha256:c2c30484dd1417ef98b51021ffa2cc0d7f3c78918adaaaab7e70817335ab3e02 \
--hash=sha256:c8c4478bef6d57fcfda15dae461ea3c9f06aa7b257c58df3f2300174ccbb185a \
--hash=sha256:cd88b01f3d37b7a2a34f91d98f14720206f1ea3d540843fab2d649dd5fb91fec \
--hash=sha256:d05e94cdfe0d15d0206f970722d2554780ce562787b21b218b275447f8751319 \
--hash=sha256:dab9ac5a67c8d1f070c00fa8fccb7cbd1b8dcc1a8d6b42f37540df9b3d4cc603 \
--hash=sha256:e1cc2bfaee8c214f06080a7c7d5772419b8a1108e8e5349236189811823fb02a \
--hash=sha256:efc21a454892828368b11c2c780de0ff8bc991f73f6b99c6b66e56205470929b \
--hash=sha256:f001b571ead90ca1770f1e616db255351a1703317f20374c361ef22f12c06d09 \
--hash=sha256:f2ed8b64dc0c651c0f5a9c926777719770021251b8f336d97c4b80b660836ce1 \
--hash=sha256:f59c7673465908cbe506117176156c127f29f917677afceada34957179221d91 \
--hash=sha256:f9033b43f511f27547c557dcaba0177649e10a3725336ccd2cce0fdc1dc4850d
# via aiobotocore
aioitertools==0.13.0 \
--hash=sha256:0be0292b856f08dfac90e31f4739432f4cb6d7520ab9eb73e143f4f2fa5259be \
--hash=sha256:620bd241acc0bbb9ec819f1ab215866871b4bbd1f73836a55f799200ee86950c
# via aiobotocore
aiosignal==1.4.0 \
--hash=sha256:053243f8b92b990551949e63930a839ff0cf0b0ebbe0597b0f3fb19e1a0fe82e \
--hash=sha256:f47eecd9468083c2029cc99945502cb7708b082c232f9aca65da147157b251c7
# via aiohttp
alembic==1.20.0 \
--hash=sha256:77eb101048d95f982c0353e9233404889dcd7a6fc244c107836c0e2fc9cf7d9d \
--hash=sha256:db505480647bc60386c5369402f4a57a506b7539c9e9ef5e270d45cbbe4939bf
# via mtusi-messenger
annotated-doc==0.0.5 \
--hash=sha256:117bac03a25ede5df5440e855b32d556049ca169ead221505badf432fed4b101 \
--hash=sha256:c7e58ce09192557605d8bbd92836d7e1d520ac9580096042c0bfd197efacf1bb
# via fastapi
annotated-types==0.8.0 \
--hash=sha256:13b2beaad985e05e2d6407ee4c4f35590b11f8d693a258a561055cac8f64cab7 \
--hash=sha256:f072f4d804ea359e4eaf198b1af7a8b0943881a87f31bb764f8bf219bb9419e0
# via pydantic
anyio==4.15.1 \
--hash=sha256:6152fdbbf9a77fdec97731721bebf7c4c44f7c29b424b0065826173efc7ed101 \
--hash=sha256:9f28306018cbd6d329e64a36d58256edff76dd996fe423bc957326e578b82a94
# via starlette
argon2-cffi==25.1.0 \
--hash=sha256:694ae5cc8a42f4c4e2bf2ca0e64e51e23a040c6a517a85074683d3959e1346c1 \
--hash=sha256:fdc8b074db390fccb6eb4a3604ae7231f219aa669a2652e0f20e16ba513d5741
# via mtusi-messenger
argon2-cffi-bindings==26.1.0 \
--hash=sha256:21ca0396fe5ec995dd54431c32698189666f9224810acfa752e50d2bd94d9df2 \
--hash=sha256:224865cbbcb7a2bd1356741dff12b0134df726b6d44bb7b500df8e303cbd9e81 \
--hash=sha256:27f1821903e2ceadcb88ec2b45ef190897b7682449c772f4d9b53e42c520cf29 \
--hash=sha256:2c36ff87b5dfaa477d0bd51e9d7f6abdae7c8955d2983c97419085d842154b3e \
--hash=sha256:34b7d9c24a4165a2c61cc8ae11d44d48c9ce2830fb536cb7914e11fdd9962728 \
--hash=sha256:63505c71542a44b68b1e38060450fb006404170da375feb31af153e7f9c6205d \
--hash=sha256:78de2d65e0b9ea7ce9d1b1c3e87297b2d7305a02c266ee2a2d6910daddd7ee69 \
--hash=sha256:a86c069c91a747a2c4e5c51473590aeb48172fff9b2130d23729a42d98665ecb \
--hash=sha256:af11ac37a7c53dc16cb7950a6190851b0870fe218b6c60c0bb7ac355234e3083 \
--hash=sha256:d88e5f7e60f28ae0b0cc6b2f16c43e87cd642a196a86f85e0d8bb6fe016fc16d \
--hash=sha256:f9c4420a7a864fe1b86ce35befc95b8e39fb852493b81cf798671ddc265de638 \
--hash=sha256:ffff613aaa9ce6236766e2fc6dc560bb5abde7a2e2416e3db1f9ae395a2b4dd4
# via argon2-cffi
asyncpg==0.31.0 \
--hash=sha256:0bfbcc5b7ffcd9b75ab1558f00db2ae07db9c80637ad1b2469c43df79d7a5ae2 \
--hash=sha256:22bc525ebbdc24d1261ecbf6f504998244d4e3be1721784b5f64664d61fbe602 \
--hash=sha256:54a64f91839ba59008eccf7aad2e93d6e3de688d796f35803235ea1c4898ae1e \
--hash=sha256:bef056aa502ee34204c161c72ca1f3c274917596877f825968368b2c33f585f4 \
--hash=sha256:c0e0822b1038dc7253b337b0f3f676cadc4ac31b126c5d42691c39691962e403 \
--hash=sha256:c204fab1b91e08b0f47e90a75d1b3c62174dab21f670ad6c5d0f243a228f015b \
--hash=sha256:c989386c83940bfbd787180f2b1519415e2d3d6277a70d9d0f0145ac73500735 \
--hash=sha256:dc5f2fa9916f292e5c5c8b2ac2813763bcd7f58e130055b4ad8a0531314201ab \
--hash=sha256:f890de5e1e4f7e14023619399a471ce4b71f5418cd67a51853b9910fdfa73696
# via mtusi-messenger
attrs==26.1.0 \
--hash=sha256:c647aa4a12dfbad9333ca4e71fe62ddc36f4e63b2d260a37a8b83d2f043ac309 \
--hash=sha256:d03ceb89cb322a8fd706d4fb91940737b6642aa36998fe130a9bc96c985eff32
# via aiohttp
botocore==1.43.117 \
--hash=sha256:5920ef9b3002e1361846549078549d9154a6e0004c22853c01ce7b279d05d495 \
--hash=sha256:71993702832cc37c2495048b9945f2929d306fccb3fb767e9964e437e637fa6c
# via aiobotocore
cffi==2.1.1 \
--hash=sha256:19ee6127ee34de7d83ce3d371ebc5ed91addbdcc39f9ab15ce4eb35a4e534971 \
--hash=sha256:1aa5645c30469b09530c4ebca77ebf8f17618293c58f8549cb1a543a50236e7d \
--hash=sha256:31348097ff5bbe827ccc41795d4dd099d9f0625e7def00ee653c137a490c2a6c \
--hash=sha256:334644fbac4eff73d985a17a91226df55d0f394160c4cfb880e084c8f7161cac \
--hash=sha256:63bbfd5ded17c4840ac07cd8f1c21ba9d9708141f840b324f422f41b207e3973 \
--hash=sha256:6a8dddef476fab96d066d578fc88526767b836ab5ab21754e1d5bf3879c31c7c \
--hash=sha256:9d2055050ea716bd38b7f7f1579c275386646b4894c155a3e2f3cd62ed41b7c6 \
--hash=sha256:a2d7755bef5a12ed488f4ef1f1b69ee9191d7396083b755a5d2295f6edb4768b \
--hash=sha256:a931079504ecc49efed7744c476a5c343a92fabf66dec2db95edb1b2fdc770e2 \
--hash=sha256:aa9511c62d14da7aacc9b4bf51f3f697a621e83b2d6919008243c3aad168eea3 \
--hash=sha256:b5bdfd1c873d4e093aabc0ca84c4ca6dbc4f752afb5c86f146d9742580c9da2e \
--hash=sha256:dd31f52ea1086513bb9df30f8fcee9b8918323ae067a3d5b78bc826a000712be \
--hash=sha256:e0bcb7e0f677f543555d2adff3bf19c05f66cdb4796e5ff602442ab2fe3c4ef7 \
--hash=sha256:f16c709686a78c727bbbf059f92b0bf41c6fc60deec706d2dc19f529175a6125 \
--hash=sha256:fcd22650c908d7b7da162bbfaab594a1227a15d1643a98c68b122ac642fa2264
# via argon2-cffi-bindings
click==8.5.0 \
--hash=sha256:255bc9599cf7748b4b1a446ccc735421bd08a2ae529a8b88597d3de5664ee360 \
--hash=sha256:ba0d2089de75ea0310e2dde03160e6ca10009947fb95a182f9b54021bb272e34
# via uvicorn
fastapi==0.142.1 \
--hash=sha256:761663e3e6939da45f997a6f68362abc0fa9d8606e76d504f15f806d2281581d \
--hash=sha256:7eea2b5b1632ed43de2c090b3a43b7d92267189dfbbd55a967307ed763b6c57a
# via mtusi-messenger
frozenlist==1.8.0 \
--hash=sha256:032efa2674356903cd0261c4317a561a6850f3ac864a63fc1583147fb05a79b0 \
--hash=sha256:03ae967b4e297f58f8c774c7eabcce57fe3c2434817d4385c50661845a058121 \
--hash=sha256:07cdca25a91a4386d2e76ad992916a85038a9b97561bf7a3fd12d5d9ce31870c \
--hash=sha256:0c18a16eab41e82c295618a77502e17b195883241c563b00f0aa5106fc4eaa0d \
--hash=sha256:0f96534f8bfebc1a394209427d0f8a63d343c9779cda6fc25e8e121b5fd8555b \
--hash=sha256:21900c48ae04d13d416f0e1e0c4d81f7931f73a9dfa0b7a8746fb2fe7dd970ed \
--hash=sha256:29548f9b5b5e3460ce7378144c3010363d8035cea44bc0bf02d57f5a685e084e \
--hash=sha256:3ede829ed8d842f6cd48fc7081d7a41001a56f1f38603f9d49bf3020d59a31ad \
--hash=sha256:3ef2d026f16a2b1866e1d86fc4e1291e1ed8a387b2c333809419a2f8b3a77b82 \
--hash=sha256:44389d135b3ff43ba8cc89ff7f51f5a0bb6b63d829c8300f79a2fe4fe61bcc62 \
--hash=sha256:4e0c11f2cc6717e0a741f84a527c52616140741cd812a50422f83dc31749fb52 \
--hash=sha256:50066c3997d0091c411a66e710f4e11752251e6d2d73d70d8d5d4c76442a199d \
--hash=sha256:517279f58009d0b1f2e7c1b130b377a349405da3f7621ed6bfae50b10adf20c1 \
--hash=sha256:5500ef82073f599ac84d888e3a8c1f77ac831183244bfd7f11eaa0289fb30714 \
--hash=sha256:581ef5194c48035a7de2aefc72ac6539823bb71508189e5de01d60c9dcd5fa65 \
--hash=sha256:5c1c8e78426e59b3f8005e9b19f6ff46e5845895adbde20ece9218319eca6506 \
--hash=sha256:5d63a068f978fc69421fb0e6eb91a9603187527c86b7cd3f534a5b77a592b888 \
--hash=sha256:6da155091429aeba16851ecb10a9104a108bcd32f6c1642867eadaee401c1c41 \
--hash=sha256:878be833caa6a3821caf85eb39c5ba92d28e85df26d57afb06b35b2efd937231 \
--hash=sha256:8b7b94a067d1c504ee0b16def57ad5738701e4ba10cec90529f13fa03c833496 \
--hash=sha256:8d92f1a84bb12d9e56f818b3a746f3efba93c1b63c8387a73dde655e1e42282a \
--hash=sha256:96153e77a591c8adc2ee805756c61f59fef4cf4073a9275ee86fe8cba41241f7 \
--hash=sha256:b3210649ee28062ea6099cfda39e147fa1bc039583c8ee4481cb7811e2448c51 \
--hash=sha256:b4dec9482a65c54a5044486847b8a66bf10c9cb4926d42927ec4e8fd5db7fed8 \
--hash=sha256:bf0a7e10b077bf5fb9380ad3ae8ce20ef919a6ad93b4552896419ac7e1d8e042 \
--hash=sha256:cf253e0e1c3ceb4aaff6df637ce033ff6535fb8c70a764a8f46aafd3d6ab798e \
--hash=sha256:db1e72ede2d0d7ccb213f218df6a078a9c09a7de257c2fe8fcef16d5925230b1 \
--hash=sha256:e25ac20a2ef37e91c1b39938b591457666a0fa835c7783c3a8f33ea42870db94 \
--hash=sha256:eaa352d7047a31d87dafcacbabe89df0aa506abb5b1b85a2fb91bc3faa02d822 \
--hash=sha256:ec3cc8c5d4084591b4237c0a272cc4f50a5b03396a47d9caaf76f5d7b38a4f11 \
--hash=sha256:eefdba20de0d938cec6a89bd4d70f346a03108a19b9df4248d3cf0d88f1b0f51 \
--hash=sha256:f21f00a91358803399890ab167098c131ec2ddd5f8f5fd5fe9c9f2c6fcd91e40 \
--hash=sha256:f6292f1de555ffcc675941d65fffffb0a5bcd992905015f85d0592201793e0e5 \
--hash=sha256:fb30f9626572a76dfe4293c7194a09fb1fe93ba94c7d4f720dfae3b646b45027
# via
# aiohttp
# aiosignal
greenlet==3.5.6 \
--hash=sha256:06c0e933290fba8ffe53ead4ae1b8044b0e9754b75cebf381aa2bc3e50d82fac \
--hash=sha256:5b602b4201b965a8354d74e232364a66ff243dd142e350d035f46169bb36e13d \
--hash=sha256:7f731ebac68ea06d628658295cb2d217b10186329fcf9a3b6a149045059bf92e \
--hash=sha256:876077e7ebb8c84ed068e2b23d4c62ebb010d60df84b9591af1be2f39010ffb2 \
--hash=sha256:8e67c43bdfc88d5fee6db0d3e40175b362fc95fb85f0412d233b9b203c53a575 \
--hash=sha256:a93ee7c6e8fd0f8a83525a51bd777be57ee17787e91d805bd8d6faf9dcada18e \
--hash=sha256:c75116c9de79949de23006e2d9b35ee82874c594fcf5c0311b439acaa14b8441 \
--hash=sha256:cad5782f93f7f738b62c6527b6f32a60694d924029f299a8b524758cfa53d815 \
--hash=sha256:df19e2d0b1620039af5102563fbd96e8938c7f5c3f5828528d641d9fc585525e \
--hash=sha256:f96f0e30b5a95c7631b12bfe214cbc90ec8fe8cfa36920596c10514a65743519 \
--hash=sha256:f98e8215e172f567ce80eeaed9107fb4d32b6c44f26983d9b8334658136a205a
# via sqlalchemy
h11==0.16.0 \
--hash=sha256:4e35b956cf45792e4caa5885e69fba00bdbc6ffafbfa020300e549b208ee5ff1 \
--hash=sha256:63cf8bbe7522de3bf65932fda1d9c2772064ffb3dae62d55932da54b31cb6c86
# via uvicorn
idna==3.20 \
--hash=sha256:a7db850025b95ded1eae8a46181a1a6c56c92c96f0e2b005d9ff8dc0210cab44 \
--hash=sha256:ab7ae7122974553370f0bdb919e1a960b2cd1bc1ef0276416d896db81c14582c
# via
# anyio
# yarl
jmespath==1.1.0 \
--hash=sha256:472c87d80f36026ae83c6ddd0f1d05d4e510134ed462851fd5f754c8c3cbb88d \
--hash=sha256:a5663118de4908c91729bea0acadca56526eb2698e83de10cd116ae0f4e97c64
# via
# aiobotocore
# botocore
mako==1.4.3 \
--hash=sha256:723296007c870bfd6b3f0c3230dba7198096e5269297ebf5e4eff9e7ffa39d4f \
--hash=sha256:cd6537fe88d5fec315c55c2f8529bc4ce7a9a352ad7db3eeaa6a66e2dd4ec37a
# via alembic
markupsafe==3.0.3 \
--hash=sha256:116bb52f642a37c115f517494ea5feb03889e04df47eeff5b130b1808ce7c219 \
--hash=sha256:12c63dfb4a98206f045aa9563db46507995f7ef6d83b2f68eda65c307c6829eb \
--hash=sha256:133a43e73a802c5562be9bbcd03d090aa5a1fe899db609c29e8c8d815c5f6de6 \
--hash=sha256:1b4b79e8ebf6b55351f0d91fe80f893b4743f104bff22e90697db1590e47a218 \
--hash=sha256:218551f6df4868a8d527e3062d0fb968682fe92054e89978594c28e642c43a73 \
--hash=sha256:3524b778fe5cfb3452a09d31e7b5adefeea8c5be1d43c4f810ba09f2ceb29d37 \
--hash=sha256:4e885a3d1efa2eadc93c894a21770e4bc67899e3543680313b09f139e149ab19 \
--hash=sha256:509fa21c6deb7a7a273d629cf5ec029bc209d1a51178615ddf718f5918992ab9 \
--hash=sha256:69c0b73548bc525c8cb9a251cddf1931d1db4d2258e9599c28c07ef3580ef354 \
--hash=sha256:722695808f4b6457b320fdc131280796bdceb04ab50fe1795cd540799ebe1698 \
--hash=sha256:795e7751525cae078558e679d646ae45574b47ed6e7771863fcc079a6171a0fc \
--hash=sha256:7e68f88e5b8799aa49c85cd116c932a1ac15caaa3f5db09087854d218359e485 \
--hash=sha256:8485f406a96febb5140bfeca44a73e3ce5116b2501ac54fe953e488fb1d03b12 \
--hash=sha256:8709b08f4a89aa7586de0aadc8da56180242ee0ada3999749b183aa23df95025 \
--hash=sha256:8f71bc33915be5186016f675cd83a1e08523649b0e33efdb898db577ef5bb009 \
--hash=sha256:9a1abfdc021a164803f4d485104931fb8f8c1efd55bc6b748d2f5774e78b62c5 \
--hash=sha256:9b79b7a16f7fedff2495d684f2b59b0457c3b493778c9eed31111be64d58279f \
--hash=sha256:a4afe79fb3de0b7097d81da19090f4df4f8d3a2b3adaa8764138aac2e44f3af1 \
--hash=sha256:ad2cf8aa28b8c020ab2fc8287b0f823d0a7d8630784c31e9ee5edea20f406287 \
--hash=sha256:b8512a91625c9b3da6f127803b166b629725e68af71f8184ae7e7d54686a56d6 \
--hash=sha256:bdd37121970bfd8be76c5fb069c7751683bdf373db1ed6c010162b2a130248ed \
--hash=sha256:ccfcd093f13f0f0b7fdd0f198b90053bf7b2f02a3927a30e63f3ccc9df56b676 \
--hash=sha256:e1cf1972137e83c5d4c136c43ced9ac51d0e124706ee1c8aa8532c1287fa8795
# via mako
multidict==7.1.0 \
--hash=sha256:0179698c3c913eb64f32397083747fad20ed0f0a2b7469a08cd1a8a95d14d90e \
--hash=sha256:034b0dc1b7fb8279599c5d8563f86abb4d2454735b06544ecab23c54572ad2bd \
--hash=sha256:1401caec21fd7f002e79ab6806bbfd1f54bb3de6d5e12bd91c6685dce16ad2be \
--hash=sha256:1fed3d721f75c25a9fcdd0e362af53f4b20acbcdc63081112f85419ba0ce3444 \
--hash=sha256:23f6d325241b0db006ca2841309ed17622137e134930a740a8f1331ec4404791 \
--hash=sha256:2a964dfeb2aba3663f0536c809aa1ff385f065e89fae57e883fb7edfb4067c2f \
--hash=sha256:379f477b98a1e9a77ddc3ccaa8c709d3fb4a288ff54b96e171e637b55b4adbae \
--hash=sha256:40f586bc8a084a3671ddcae9e5fbd3228a596bfb63d9f0380f153f9a65b69f08 \
--hash=sha256:41e0c3350d08994ee8640c39884e16514e282f70ba40f5b2299582509a327774 \
--hash=sha256:5129cc1f5fec6888e2db0be936dab67242e32c738811c8769aeea93aab4257a8 \
--hash=sha256:51d7f33be9a4a1a2801430846d72841deea0894eae8381a07e7d90e0f71b3c4b \
--hash=sha256:5c8074ad4d67067c87bd0663dfda654f786336078c8fd7d2f6c1aa41de8494cc \
--hash=sha256:5fa1484f74d011addf2e5f5a0378ec41521989839a05d6051d8067d8ce732423 \
--hash=sha256:61a4e5d81b8d4e4ad61964b230129e7a2b914793d96289029078fc9009f074ec \
--hash=sha256:6e7f70d912a589e30290ed926f90ddbc3160998359cbad7c9ede1bcee481748c \
--hash=sha256:7b25c335fc53acf29d4d21dbc19fe39d2824201cdda0448623152cc5917bd259 \
--hash=sha256:7de54b49e6da811b0321e412d14efdaa1ee0c0b6609296ea5b9022bc5b2bd843 \
--hash=sha256:abeec7a89d698aa1c9b4c36bd5e3c746faef0867076e6a2ca27fa5077c4ece26 \
--hash=sha256:aeba2c750102051aa51e087c2ccbc79f2724a41c94168f8731e36f54c453551a \
--hash=sha256:c53be0dd676484a660acc56e4f1cd0dd74bc1255d12fa285e86a3fa9d5f22bf9 \
--hash=sha256:c81062e947f4b5a624135a843f6ac4b3c7fe6508300c9fb27347f022ba0c513d \
--hash=sha256:ccf98ee859fe29f874ddd8e637f14ba59108a333492b521acb885a9095244a9c \
--hash=sha256:d02cd23b5af182a49d635ee72be38053767711987a9fd82625b16b93828a0d8c \
--hash=sha256:d9ef29cfd98e17085b4f91bba8fa1570bec6787d5c52ce653ed33a58785585d0 \
--hash=sha256:df03e392cae1e05462918abbae06d6100f1e53f67db971ff0ac6c07d9edf7321
# via
# aiobotocore
# aiohttp
# yarl
opentelemetry-api==1.45.0 \
--hash=sha256:711ede81773c8025c2c03dac0450bc89f3d30aea6eabcc815c570d4e35a963f7 \
--hash=sha256:80e068aba7cd56c8b58512d6a36f8d25cb1dfaa0c0a4cc1c938ccf9f362d9cb3
# via fastapi
propcache==0.5.4 \
--hash=sha256:0c889f6fa84957bc7e8b4eab71fd16a0455068d5045e3aa40c733071d2b2fd77 \
--hash=sha256:36c0d9db44b523ef93d03341b1c42d69ff01d673c053d1b1c6c3a363bcaa39ba \
--hash=sha256:3e413d7a4a9b4866b7a761d6060d434b64d23cd35122eda3b026a0bbe8196b25 \
--hash=sha256:425f8cc86ab5018b4b8d4a23bc8e74d964bd3d757c3702e301aa79be76c53f6c \
--hash=sha256:44149f46500a0a41b95b4d99c2e586a77319539730607b9892974a092788b111 \
--hash=sha256:62c60aec739ed00124573cce1178138fd690c7676352d67a37328c1cf51d7468 \
--hash=sha256:69fc35c0779522da366c563e5faf203ffc1f8ff0021d5b1337fa4efa5be73177 \
--hash=sha256:7cc528e760a8af06f2b13e9b9f362cd90c7c718ea61228a96dbd31ba16ed7f47 \
--hash=sha256:96f7c5c15656040ddcbc51e56dc59b58aa25999d743c126abd425b9766ab43e9 \
--hash=sha256:a5793c7698a53f56f4a1889a4737c7eeb1b7ad0842fa6b1abca22913ff79c8c1 \
--hash=sha256:ae58f361bd5dae942717c65d3413b478c70aea9c462599e7b9adad3731db3894 \
--hash=sha256:c02c0e570c5c7e077b0181a9f3cdb7d4c3617d1cda6b5c95bd5d34022923d82c \
--hash=sha256:c2ba30a89035b57b73e00475de948521602f543d79ce01db10b04b36c4c76fc8 \
--hash=sha256:c3e98c55bde2bcf7db3c70d1aed7ae9aa8aebbf19a250c66645cde44cdb8b867 \
--hash=sha256:db3ae52ccc150dbc84704e9d642743897f3e1c54742ff34cacb661e52e3818a9 \
--hash=sha256:dbab5f5ff6897c81f355d079010cdae85b02e5a0b518b5251523b8ad8ae9ac3c \
--hash=sha256:e1d52a05dc417279f7e5c7618c5dfbbc29923aaf9bc0a5c1802ddcebf54c61a0 \
--hash=sha256:f85915e00dcb1cd9f2f890ead064ed40a27df06f0db65be427b29482ae357572 \
--hash=sha256:ff6b113f50bc066a698db5d944d2c6dc7507168dd3341e255a8892fd0715a558
# via
# aiohttp
# yarl
pycparser==3.0 ; implementation_name != 'PyPy' \
--hash=sha256:600f49d217304a5902ac3c37e1281c9fe94e4d0489de643a9504c5cdfdfc6b29 \
--hash=sha256:b727414169a36b7d524c1c3e31839a521725078d7b2ff038656844266160a992
# via cffi
pydantic==2.13.5 \
--hash=sha256:346a034f080da3755d8e9cb5e00e8b07de1d39e4f6e2c87d8ab7cafa0b269a73 \
--hash=sha256:51a9c5f7b2f8e636f04c6cada605d9b6a3bf1348fdf945a3d8869b19bba0ee08
# via fastapi
pydantic-core==2.46.5 \
--hash=sha256:10416c15b8839ecc4ef4d0885da76da6fd0f67333a0eb8aff6d93c4b8f2910fc \
--hash=sha256:15f4a94963c95accac15b7b657bb177d3ad82bb90b0d0526d9a9b85079925db5 \
--hash=sha256:193375f3548919d3f0b60936ca113ada3e38f264f91b9b8e0508efaad57be931 \
--hash=sha256:24922243639cbdac66c75fcb6fd6495a9cb52b213d62f9a0d16f0310b1ff8038 \
--hash=sha256:5ee239d575f80b08eca11f6e20f90c4c695de7825c67eefe6091fbf20dda648e \
--hash=sha256:6f7b393a8b3da82f5c1fc0751e6d01ac6c55b93c18226a60bdfba4a724efafd1 \
--hash=sha256:79bdfa52f843137045b2d081cc05c120ba6665d29b7559c2c47690906f39279f \
--hash=sha256:7ac031912d54f3d83ef3b3eb98dfabc1608802e2202263d25957eeed40b94761 \
--hash=sha256:837b396ca3d7b74091ca623f6cbd8351bd42d670a79c2683e79fb089f06a2de5 \
--hash=sha256:97bf8de4d541598c94a59344eeb988a94c08ff76b5723c41f6567ec18c7892ea \
--hash=sha256:9c4b71f10dd532fb7a5cbc8f58707779e64f03a258c2bf8bfbaecfcd9970b519 \
--hash=sha256:b7ca9034437b6022f941f4857459562ee00a560b97e7cce8a0ec5a74fc6766e0 \
--hash=sha256:c76fe65e607be28c7fd4d56fc3c42b1583aa058ce3408b7ad0fd540171d31f9f \
--hash=sha256:d22a945598fb91236b4dd793a6e42e4f3dd7740bb5aace5ebd7d4c08d13bb575 \
--hash=sha256:e80675d75ae2cd14372cb65cad5400d9347a3d3f6c13000183f22dfd027283ed \
--hash=sha256:f332f0e72a5a0400141f830744e141bf9f97917878dbe968669e8a7fefea78ff
# via pydantic
python-dateutil==2.9.0.post0 \
--hash=sha256:37dd54208da7e1cd875388217d5e00ebd4179249f90fb72437e91a35459a0ad3 \
--hash=sha256:a8b2bc7bffae282281c8140a97d3aa9c14da0b136dfe83f850eea9a5f7470427
# via
# aiobotocore
# botocore
redis==8.1.0 \
--hash=sha256:6e1a19beef9225c83efd689c7e6b7da2d5215b1f42cd13b7fc3714d0a09c7b25 \
--hash=sha256:a4fe1aac3d3b3cc791d4b3d5931c5a956045dc951ee74d1c913ee3ac4d2ee9fb
# via mtusi-messenger
six==1.17.0 \
--hash=sha256:4721f391ed90541fddacab5acf947aa0d3dc7d27b2e1e8eda2be8970586c3274 \
--hash=sha256:ff70335d468e7eb6ec65b95b99d3a2836546063f63acc5171de367e834932a81
# via python-dateutil
sqlalchemy==2.1.1 \
--hash=sha256:28b882509319789d52966d70164ccfc5bc1aaffc1c7f98a79bbccec13346ebd7 \
--hash=sha256:389e7098e9ae15094f222496de98b0fd211c06b896c73c6e46aa9ca5b6fcd590 \
--hash=sha256:4357c1a222e141662251a59d3702f9b124294941171dfa6bd570513e9f4905ee \
--hash=sha256:7c60fb6793cf60b2733012352f0e1861c38b24727d0e37a1da1f3974eb79f0ed \
--hash=sha256:7ed18c0747eec4a0d8d9abe4c89d96ec0eda97721ab7d3a31d0c1ebcbf38cd2e \
--hash=sha256:a74c46cd93e34b912adafab98aa71c862518451a019d97f9c2f37392fc8eea3f \
--hash=sha256:abd893deac6b0765f51d87129c5631cc5bc8f784f8bf22a9d3903695c764bccc \
--hash=sha256:b04365ffe57cdeaf4d0f75630332d857dde3f91336bc4bdec76c810473c9c35e \
--hash=sha256:cf88881d593f527860fa7c63a50095496a5fa15632b1fee58e3114353f7fbc22 \
--hash=sha256:dee7886f4725c304641929a38d1ebe163f9fb45a5c9363f34bbb85bfdcb084c5 \
--hash=sha256:eef01acb10295adfac8a960f716687052fe16f14a3f5955b56c24eefa9df7851 \
--hash=sha256:fcf3cbb33bb23bad75d2150157c21804618745731e9931ab27e61879a9f6123b
# via
# alembic
# mtusi-messenger
starlette==1.7.0 \
--hash=sha256:67f8e99895493dd2911a03f11314af6ceebeae4e704bb9f43dfc6a9db151c93e \
--hash=sha256:c79f74ea63cff761804fbbfb182f1e0b440c2d07b164d24700c5a1bab5d6ff5d
# via fastapi
typing-extensions==4.16.0 \
--hash=sha256:481caa481374e813c1b176ada14e97f1f67a4539ce9cfeb3f350d78d6370c2e8 \
--hash=sha256:dc983d19a509c94dba722ee6abd33940f7c05a89e243c47e907eb4db6f1a43e5
# via
# alembic
# anyio
# fastapi
# opentelemetry-api
# pydantic
# pydantic-core
# sqlalchemy
# typing-inspection
typing-inspection==0.4.4 \
--hash=sha256:547274fa6b0a561ccf549cc9524b999a578e737d015d8709d021f9d0d13bea47 \
--hash=sha256:65b8397ba37ccbce054456aaccddfc91e6e3083c92824df348d96ca832f3f147
# via
# fastapi
# pydantic
urllib3==2.8.0 \
--hash=sha256:0cf3cae568d36aa9576b28dfb35f11328f1cb974ca7647d9475ebb86c75ac6e3 \
--hash=sha256:63bf2ead4c879426ebf22ef2a781eeb4aa3b4ae798a0435506f8687fd5bb9b63
# via botocore
uvicorn==0.54.0 \
--hash=sha256:505bdb0f318731d45f1f712071fc781a8981f6847a31c902c9f5e652d4f67faf \
--hash=sha256:a2e33cbfaa0306f8e6b0c13e0cb89d7d7a2da3e62b90c66e18c33d9807b28620
# via mtusi-messenger
wrapt==2.5.1 \
--hash=sha256:09b1893ee4063706574c1813abf479b8b51926633fbdb6f96aab8dc7b0976668 \
--hash=sha256:0c9480bdee340a1602cae5a777146ab4be3e384fdcb569fffdf8721032314645 \
--hash=sha256:5b53000b424dc2133eaaf22838a2352d3497f5d7c2e7d9a2acfe675ab7225bb1 \
--hash=sha256:76f230a9b07e3cb66646d265398f579abb6128b1bb4cb97c74b1ae5d09e96f31 \
--hash=sha256:ab6db7d2a18d366cc57c2228253cf26443190aba0a6dd0939b3c1e8ac6e29e2c \
--hash=sha256:c6e6c226b1ca5402d7ae5fb34a0d21f1b49124fe4200e5884d1e19e53c47ac1d \
--hash=sha256:d800c7689154622b0ba2922ceca44a3cf2ef61c3b9a4c4eeb1d8b3050d7ededa \
--hash=sha256:dc401274fcc7b15b3b2c12df2ff34024a11925243a7d3daee91c6d7d14f9addf \
--hash=sha256:f1630201b0e2a96bb26304b7adfbd91a4ef486abb5a4c48377444a0bed749f37 \
--hash=sha256:f280c115ea64eff3dcbd68a668ce3f63476a4ba386bbabb318017e286196ea2c \
--hash=sha256:f595bb0185aab3e9dc31950c95d914f56ea8278810c3b928f3426e12ed6d27bc \
--hash=sha256:f98eaf784cd12bc69c77af398084174531007cd81849c962163ccfc6e791f3ea \
--hash=sha256:fd3f878a4aac3c262447ddf43c5f4c18fc67dfc3ba69c4fb1c7a4c4af96abe7e
# via aiobotocore
yarl==1.25.1 \
--hash=sha256:03dd38de09bc213e9a8b29761eec33ee1d5318dac0e49d8af36e4d27830e23a7 \
--hash=sha256:0a66db89ea473abeac4b70523cafd94db3772380e565f9d28af7a179b7af71fa \
--hash=sha256:0f12afda4eea8c8994a76d4df1875c765194f5fbe8a9d197929ea303caee29ec \
--hash=sha256:10b2fd95332f0d716d5eee3c9fb2ce8eada19082de7fee83d32e37992fd75c26 \
--hash=sha256:126a2533570c554719ca40a1288fdee1700b6bc82e7131aa69fa85252d92e651 \
--hash=sha256:14b79a30a93a3ce2e8832603fd0ab780ada281b0ba5110b519a634f2d7d7d1fc \
--hash=sha256:1f51020b2eb8a003c84925638ec63c21a750a4bddd3a22ec8eac6a742dadf1b9 \
--hash=sha256:25868beca8b6765f8f7d0e11fe6dd7c66dd4b0793b9500286d20cc92352126a5 \
--hash=sha256:2b49375d22299b0a834c2bca72f39aaecc270d96fb24c30424899676f487b22a \
--hash=sha256:3feb99222553a8cbedfa52c2f59dd84c3f50d5b582c728d522caf8d72769a54b \
--hash=sha256:4bd6340d20ae2c7ca719b87b426e808e90743b676d05d4c26c4fb5ca71f41184 \
--hash=sha256:681c758b0490f9e96b78e5fa8e8dc6e648e9185bb6eaebe73183c33ea0c445f3 \
--hash=sha256:a2ed0ba415ccdf08f14bf544cb78346d0f76086707ffee24921a2c84dbf1305a \
--hash=sha256:a3faadac7d812ddac258feb57b9846b60c1b437c4f4b9ad42595c6f6fe4390df \
--hash=sha256:b10dd0557ba422715b5206b3743192135a6022acca8baec51aa127d0a75db8fe \
--hash=sha256:be80550d9bfe83d9b62398a37081a90434e6df2d978ec345c3d2820de6beddab \
--hash=sha256:e07595c7d6f4db270ceede356a1bd1c07a34f1c26f958d1ed0cd7b48e0d2bba3 \
--hash=sha256:eb96ed1ae6c7d072d60840c0434aef07a2df611812810807fbc54263a6053e9a \
--hash=sha256:ef74070ac553c59eb4f04258722066d6c6135b7baa03b2e9f2da65c096e96d98
# via aiohttp
+600
View File
@@ -0,0 +1,600 @@
#!/usr/bin/env python3
"""Операторские команды стенда лабы 4 (свои, не skeleton). Python 3.9+, stdlib.
python3 scripts/lab4.py env
.env из .env.example со случайными паролями и ключами S3 (make env);
несекретные переменные, заданные в окружении (`make env
HOST_PORT=8180`), берутся оттуда — так стенд встаёт рядом с чужим
на других портах. Существующий .env не перезаписывается,
дописываются только переменные шаблона, которых в нём нет.
Печатает только имена;
python3 scripts/lab4.py instances [--base-url URL] [--requests 12]
вход одним синтетическим пользователем и серия GET /users/me с одним
токеном через LB: X-Instance-Id каждого ответа и итог по репликам
(шаг 1 сценария защиты лабы 3);
python3 scripts/lab4.py lb-stats
слоты HAProxy рабочего стенда: адрес, состояние проверки, запросы в
полёте, всего, ошибки соединения, повторы, перенаправления;
python3 scripts/lab4.py failover-each [--base-url URL] [--replicas 2]
[--mode stop|kill]
make test-failover для каждой реплики по очереди: перед прогоном все
реплики возвращены (make replicas), тест останавливает реплику,
ответившую на его первую запись; если это реплика, которую уже
проверили, очередь LB сдвигается одним запросом и прогон
повторяется. Печатает docker compose ps до и после, строку
STOP_ONE_LOG и итог теста — это evidence «какой контейнер
действительно остановлен»;
python3 scripts/lab4.py attachment-failover [--base-url URL]
[--replicas 2] [--mode stop|kill]
лаба 4: загрузка tests/fixtures/sample.png через LB, сообщение со
ссылкой, остановка именно реплики, принявшей загрузку
(scripts/stop-one.sh по X-Instance-Id ответа загрузки), скачивание
вторым участником через другую реплику — тот же SHA-256, 404
постороннему; затем реплики возвращаются;
python3 scripts/lab4.py s3-check
лаба 4: приватность bucket вне API (make s3-check): bootstrap в
режиме check (права ключей API и уборщика, чужой bucket,
административные запросы), анонимные запросы с хоста и из сети
стенда, порты контейнера S3 из сети, затем cleanup. Таблица «где →
проверка → ожидаемо → получено», код 1 при нарушении.
Пароли синтетических пользователей и токены живут только в памяти и не
печатаются. Работает с проектом compose репозитория (compose.yaml и .env)
или с тем, что задают COMPOSE_PROJECT_NAME / COMPOSE_FILE /
COMPOSE_ENV_FILES (стенды student-tests/stand.py).
"""
from __future__ import annotations
import argparse
import base64
import hashlib
import json
import os
import re
import secrets
import subprocess
import sys
import tempfile
import time
import urllib.error
import urllib.request
import uuid
from collections import Counter
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
FIXTURE = ROOT / "tests" / "fixtures" / "sample.png"
LB_STATS = (
"exec 3<>/dev/tcp/127.0.0.1/8404 && "
"printf 'GET /stats;csv HTTP/1.0\\r\\n\\r\\n' >&3 && cat <&3"
)
STAT_FIELDS = ("addr", "status", "scur", "stot", "econ", "eresp", "wretr", "wredis")
# пустые значения этих переменных шаблона — секреты: make env их генерирует
SECRET_SUFFIXES = ("_PASSWORD", "_KEY")
# порты API S3 и gRPC шлюза: единственные, что открыты в сеть стенда
S3_NETWORK_PORTS = ("8333", "18333")
def call(base: str, method: str, path: str, headers=None, body=None, raw=None):
data = json.dumps(body).encode() if body is not None else raw
request = urllib.request.Request(base + path, data=data, method=method)
for key, value in (headers or {}).items():
request.add_header(key, value)
if body is not None:
request.add_header("Content-Type", "application/json")
try:
with urllib.request.urlopen(request, timeout=10) as response:
return response.status, dict(response.headers), response.read()
except urllib.error.HTTPError as error:
return error.code, dict(error.headers), error.read()
def register(base: str, label: str = "ops") -> dict:
"""Синтетический пользователь с паролем и входом: id и токен."""
username = f"{label}_" + secrets.token_hex(6)
password = secrets.token_urlsafe(18)
status, _, data = call(
base,
"POST",
"/api/v1/users",
body={"username": username, "display_name": "Оператор", "password": password},
)
if status != 201:
raise SystemExit(f"register -> {status}")
user_id = json.loads(data)["id"]
basic = base64.b64encode(f"{username}:{password}".encode()).decode()
status, _, data = call(
base,
"POST",
"/api/v1/auth/sessions",
headers={"Authorization": "Basic " + basic},
)
if status != 201:
raise SystemExit(f"login -> {status}")
return {"id": user_id, "token": json.loads(data)["token"]}
def login(base: str) -> str:
return register(base)["token"]
def bearer(actor: dict) -> dict:
return {"Authorization": "Bearer " + actor["token"]}
def instance_of(headers: dict) -> str:
return headers.get("X-Instance-Id") or headers.get("x-instance-id") or "-"
# --- env ------------------------------------------------------------------------
def _assignments(text: str) -> list[tuple[str, str]]:
pairs = []
for line in text.splitlines():
match = re.match(r"([A-Z][A-Z0-9_]*)=(.*)$", line)
if match:
pairs.append((match.group(1), match.group(2)))
return pairs
def _value(name: str, value: str) -> str:
"""Значение для нового .env: секрет — случайный, несекретная переменная
из окружения (`make env HOST_PORT=8180`) — как задано, иначе шаблон."""
if name.endswith(SECRET_SUFFIXES):
# ключи S3 и пароли — случайный hex; длина ключа S3 — 64 символа
return value or secrets.token_hex(32 if name.startswith("S3_") else 16)
return os.environ.get(name, value)
def env(_args: argparse.Namespace) -> int:
template = (ROOT / ".env.example").read_text(encoding="utf-8")
target = ROOT / ".env"
if not target.exists():
lines = []
generated = []
for line in template.splitlines():
match = re.match(r"([A-Z][A-Z0-9_]*)=(.*)$", line)
if match:
value = _value(match.group(1), match.group(2))
if value != match.group(2) and match.group(1).endswith(SECRET_SUFFIXES):
generated.append(match.group(1))
line = f"{match.group(1)}={value}"
lines.append(line)
target.write_text("\n".join(lines) + "\n", encoding="utf-8")
target.chmod(0o600)
print(f".env created; generated: {' '.join(generated) or '-'}")
return 0
existing = {name for name, _ in _assignments(target.read_text(encoding="utf-8"))}
missing = [(n, v) for n, v in _assignments(template) if n not in existing]
if missing:
with target.open("a", encoding="utf-8") as handle:
handle.write("\n# added by make env from .env.example\n")
for name, value in missing:
handle.write(f"{name}={_value(name, value)}\n")
print("added to existing .env: " + " ".join(name for name, _ in missing))
else:
print(".env ready")
return 0
def instances(args: argparse.Namespace) -> int:
token = login(args.base_url)
seen: Counter = Counter()
print(f"one session, {args.requests} x GET /api/v1/users/me via {args.base_url}")
for number in range(1, args.requests + 1):
status, headers, _ = call(
args.base_url,
"GET",
"/api/v1/users/me",
headers={"Authorization": "Bearer " + token},
)
instance = headers.get("X-Instance-Id") or headers.get("x-instance-id") or "-"
seen[instance] += 1
print(f" {number:2d}: {status} X-Instance-Id={instance}")
print(f"replicas seen: {len(seen)} {dict(seen)}")
return 0 if len(seen) >= 2 else 1
def compose(*args: str, check: bool = True) -> subprocess.CompletedProcess:
return subprocess.run(
["docker", "compose", *args],
cwd=ROOT,
capture_output=True,
text=True,
check=check,
)
def lb_rows() -> list[dict]:
done = compose("exec", "-T", "haproxy", "bash", "-c", LB_STATS)
lines = [
line for line in done.stdout.splitlines() if line.startswith(("# ", "api,"))
]
header = lines[0][2:].split(",")
rows = []
for line in lines[1:]:
# zip(strict=) — только с Python 3.10, скрипт работает и на 3.9
row = dict(zip(header, line.split(","))) # noqa: B905
if row["svname"] in ("BACKEND", "FRONTEND") or not row.get("addr"):
continue
rows.append(row)
return rows
def lb_stats(_args: argparse.Namespace) -> int:
print("slot " + " ".join(f"{field:>12}" for field in STAT_FIELDS))
for row in lb_rows():
print(
f"{row['svname']:<9} "
+ " ".join(f"{row.get(f, ''):>12}" for f in STAT_FIELDS)
)
return 0
def wait_lb_up(replicas: int, timeout: float = 30) -> bool:
"""Все реплики UP в LB: `--wait` compose ждёт только healthcheck
контейнера, а слот вернувшейся реплики включается после проверок LB."""
deadline = time.monotonic() + timeout
while time.monotonic() < deadline:
up = [row for row in lb_rows() if row.get("status") == "UP"]
if len(up) >= replicas:
return True
time.sleep(0.5)
return False
def ps() -> str:
return compose(
"ps", "-a", "--format", "table {{.Name}}\t{{.ID}}\t{{.State}}\t{{.Status}}"
).stdout
def failover_each(args: argparse.Namespace) -> int:
done: set[str] = set()
log = Path(tempfile.mkdtemp(prefix="stop-one-")) / "stop-one.log"
env = {**os.environ, "STOP_ONE_LOG": str(log), "STOP_MODE": args.mode}
attempt = 0
while len(done) < args.replicas and attempt < args.replicas * 4:
attempt += 1
replicas = compose(
"up",
"-d",
"--no-deps",
"--no-recreate",
"--wait",
"--scale",
f"api={args.replicas}",
"api",
check=False,
)
if replicas.returncode != 0 or not wait_lb_up(args.replicas):
print(replicas.stderr or "replicas are not UP in the LB")
return 2
# сдвиг очереди round-robin: тест останавливает реплику, ответившую
# на его первую запись; с каждой попыткой сдвиг на запрос больше
for _ in range(attempt - 1):
call(args.base_url, "GET", "/health/live")
print(f"=== attempt {attempt}: docker compose ps before\n{ps()}", flush=True)
before = log.read_text().splitlines() if log.exists() else []
test = subprocess.run(
[
sys.executable,
"tests/resilience.py",
"--mode",
"failover",
"--action-script",
"scripts/stop-one.sh",
"--base-url",
args.base_url,
],
cwd=ROOT,
env=env,
capture_output=True,
text=True,
check=False,
)
print(
"$ make test-failover ACTION_SCRIPT=scripts/stop-one.sh "
f"(STOP_MODE={args.mode})"
)
print(test.stdout.strip())
lines = log.read_text().splitlines() if log.exists() else []
new = lines[len(before) :]
print("STOP_ONE_LOG: " + (new[-1] if new else "(no line)"))
print(f"docker compose ps after\n{ps()}", flush=True)
if test.returncode != 0:
return test.returncode
stopped = new[-1].split("container=")[1].split()[0][:12] if new else ""
if stopped:
done.add(stopped)
compose(
"up",
"-d",
"--no-deps",
"--no-recreate",
"--wait",
"--scale",
f"api={args.replicas}",
"api",
)
print(f"replicas stopped one by one: {sorted(done)}; all restored:\n{ps()}")
return 0 if len(done) >= args.replicas else 1
# --- лаба 4: вложение и отказ принявшей реплики ------------------------------
def restore_replicas(replicas: int) -> None:
compose(
"up",
"-d",
"--no-deps",
"--no-recreate",
"--wait",
"--scale",
f"api={replicas}",
"api",
)
wait_lb_up(replicas)
def attachment_failover(args: argparse.Namespace) -> int:
base = args.base_url
restore_replicas(args.replicas)
alice, bob, eve = (register(base, label) for label in ("alice", "bob", "eve"))
status, _, data = call(
base,
"POST",
"/api/v1/chats",
headers=bearer(alice),
body={"title": "Отказ реплики", "member_ids": [alice["id"], bob["id"]]},
)
if status != 201:
raise SystemExit(f"create chat -> {status}")
chat = json.loads(data)["id"]
content = FIXTURE.read_bytes()
expected = hashlib.sha256(content).hexdigest()
status, headers, data = call(
base,
"POST",
f"/api/v1/chats/{chat}/attachments?filename=sample.png",
headers={**bearer(alice), "Content-Type": "image/png"},
raw=content,
)
if status != 201:
raise SystemExit(f"upload -> {status} {data[:200]!r}")
attachment = json.loads(data)
uploader = instance_of(headers)
print(
f"upload: 201 X-Instance-Id={uploader} size={attachment['size_bytes']} "
f"sha256={attachment['sha256'][:16]}… (fixture {expected[:16]}…)"
)
status, headers, data = call(
base,
"POST",
f"/api/v1/chats/{chat}/messages",
headers={**bearer(alice), "Idempotency-Key": uuid.uuid4().hex},
body={"text": "", "attachment_ids": [attachment["id"]]},
)
print(
f"message with attachment: {status} attachment_ids="
f"{json.loads(data).get('attachment_ids') if status == 201 else '-'}"
)
log = Path(tempfile.mkdtemp(prefix="stop-one-")) / "stop-one.log"
print(f"=== docker compose ps before\n{ps()}", flush=True)
stop = subprocess.run(
["scripts/stop-one.sh"],
cwd=ROOT,
env={
**os.environ,
"TARGET_INSTANCE_ID": uploader,
"STOP_MODE": args.mode,
"STOP_ONE_LOG": str(log),
},
capture_output=True,
text=True,
check=False,
)
print(f"$ TARGET_INSTANCE_ID={uploader} STOP_MODE={args.mode} scripts/stop-one.sh")
stopped = log.read_text().strip() if log.exists() else "-"
print(f"exit {stop.returncode}; STOP_ONE_LOG: {stopped}")
if stop.returncode != 0:
print(stop.stderr.strip())
return 1
# LB исключает реплику за ≤ 2,5 с; ответы ещё могут прийти от неё —
# ждём ответа другой реплики не дольше 10 с
deadline = time.monotonic() + 10
started = time.monotonic()
result = None
while time.monotonic() < deadline:
try:
status, headers, data = call(
base,
"GET",
f"/api/v1/attachments/{attachment['id']}/content",
headers=bearer(bob),
)
except OSError:
status, headers, data = 0, {}, b""
if status == 200 and instance_of(headers) != uploader:
result = (status, headers, data)
break
time.sleep(0.2)
ok = result is not None
if result is not None:
status, headers, data = result
digest = hashlib.sha256(data).hexdigest()
ok = digest == expected and instance_of(headers) != uploader
kind = headers.get("content-type") or headers.get("Content-Type")
print(
f"download by bob after stop: {status} "
f"X-Instance-Id={instance_of(headers)} "
f"after {time.monotonic() - started:.2f}s, bytes={len(data)}, "
f"sha256 {'== fixture' if digest == expected else '!= fixture'}, "
f"content-type={kind}"
)
else:
print("download by bob after stop: no 200 from another replica in 10 s")
for suffix in ("", "/content"):
status, _, _ = call(
base,
"GET",
f"/api/v1/attachments/{attachment['id']}{suffix}",
headers=bearer(eve),
)
print(f"outsider GET /attachments/{{id}}{suffix}: {status}")
ok = ok and status == 404
print(f"=== docker compose ps after\n{ps()}", flush=True)
restore_replicas(args.replicas)
print(f"replicas restored:\n{ps()}")
print("PASS" if ok else "FAIL")
return 0 if ok else 1
# --- лаба 4: приватность bucket вне API --------------------------------------
def _env_value(name: str, default: str) -> str:
env_file = os.environ.get("COMPOSE_ENV_FILES") or str(ROOT / ".env")
path = Path(env_file.split(",")[0])
if path.exists():
for key, value in _assignments(path.read_text(encoding="utf-8")):
if key == name and value:
return value
return os.environ.get(name) or default
def _http_status(url: str, method: str = "GET", data: bytes | None = None) -> str:
request = urllib.request.Request(url, data=data, method=method)
try:
with urllib.request.urlopen(request, timeout=5) as response:
return str(response.status)
except urllib.error.HTTPError as error:
return str(error.code)
except OSError as error:
return type(error).__name__
def _network_status(path: str, method: str = "GET") -> str:
"""Анонимный запрос к API S3 из сети стенда (контейнер LB, bash /dev/tcp)."""
request = (
f"{method} {path} HTTP/1.0\\r\\nHost: s3\\r\\nContent-Length: 0\\r\\n\\r\\n"
)
script = f"exec 3<>/dev/tcp/s3/8333 && printf '{request}' >&3 && head -n 1 <&3"
done = compose("exec", "-T", "haproxy", "bash", "-c", script, check=False)
match = re.search(r"HTTP/1\.[01] (\d{3})", done.stdout)
return match.group(1) if match else "no answer"
def _port_open(port: str) -> bool:
script = f"timeout 2 bash -c 'exec 3<>/dev/tcp/s3/{port}'"
return (
compose("exec", "-T", "haproxy", "bash", "-c", script, check=False).returncode
== 0
)
def s3_check(_args: argparse.Namespace) -> int:
rows: list[tuple[str, str, str, str]] = []
print("$ docker compose run --rm --no-deps s3-bootstrap check")
check = compose("run", "--rm", "--no-deps", "s3-bootstrap", "check", check=False)
for line in check.stdout.splitlines():
parts = line.split("\t")
if line.startswith("s3-bootstrap: check") and len(parts) == 5:
rows.append(("bootstrap (loopback s3)", parts[1], parts[2], parts[3]))
elif line.strip():
print(line)
if check.returncode != 0:
print(check.stderr.strip())
bucket = _env_value("S3_BUCKET", "messenger-attachments")
host = f"http://127.0.0.1:{_env_value('S3_HOST_PORT', '8334')}"
probe = f"/{bucket}/.s3-check/probe"
try:
for name, url, method in (
("anonymous get object", host + probe, "GET"),
("anonymous head object", host + probe, "HEAD"),
("anonymous list objects", f"{host}/{bucket}?list-type=2", "GET"),
("anonymous list buckets", host + "/", "GET"),
):
rows.append(("host 127.0.0.1", name, "403", _http_status(url, method)))
rows.append(
(
"host 127.0.0.1",
"anonymous put object",
"403",
_http_status(f"{host}/{bucket}/.s3-check/anonymous", "PUT", b"x"),
)
)
for name, path, method in (
("anonymous get object", probe, "GET"),
("anonymous list objects", f"/{bucket}?list-type=2", "GET"),
("anonymous put object", f"/{bucket}/.s3-check/anonymous", "PUT"),
):
rows.append(
("stand network (haproxy)", name, "403", _network_status(path, method))
)
listening = compose(
"exec", "-T", "s3", "sh", "-c", "netstat -tln", check=False
).stdout
ports = sorted(
{
m.group(1)
for m in re.finditer(r"\s\S+:(\d+)\s+\S+:\*?\S*\s+LISTEN", listening)
},
key=int,
)
for port in ports:
expected = "open" if port in S3_NETWORK_PORTS else "closed"
got = "open" if _port_open(port) else "closed"
rows.append(("stand network (haproxy)", f"s3 port {port}", expected, got))
finally:
cleanup = compose(
"run", "--rm", "--no-deps", "s3-bootstrap", "cleanup", check=False
)
print(
"$ docker compose run --rm --no-deps s3-bootstrap cleanup -> exit",
cleanup.returncode,
)
failed = 0
print(f"{'where':<26} {'check':<46} {'expected':>8} {'got':>8} verdict")
for where, name, expected, got in rows:
verdict = "ok" if expected == got else "FAIL"
failed += verdict != "ok"
print(f"{where:<26} {name:<46} {expected:>8} {got:>8} {verdict}")
print(f"checks: {len(rows)}, failed: {failed}, bootstrap exit {check.returncode}")
return 1 if failed or check.returncode != 0 else 0
def main() -> int:
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
commands = parser.add_subparsers(dest="command", required=True)
commands.add_parser("env")
one = commands.add_parser("instances")
one.add_argument("--base-url", default="http://localhost:8080")
one.add_argument("--requests", type=int, default=12)
commands.add_parser("lb-stats")
each = commands.add_parser("failover-each")
each.add_argument("--base-url", default="http://localhost:8080")
each.add_argument("--replicas", type=int, default=2)
each.add_argument("--mode", choices=("stop", "kill"), default="stop")
attachment = commands.add_parser("attachment-failover")
attachment.add_argument("--base-url", default="http://localhost:8080")
attachment.add_argument("--replicas", type=int, default=2)
attachment.add_argument("--mode", choices=("stop", "kill"), default="stop")
commands.add_parser("s3-check")
args = parser.parse_args()
handler = {
"env": env,
"instances": instances,
"lb-stats": lb_stats,
"failover-each": failover_each,
"attachment-failover": attachment_failover,
"s3-check": s3_check,
}
return handler[args.command](args)
if __name__ == "__main__":
sys.exit(main())
+23
View File
@@ -0,0 +1,23 @@
#!/bin/sh
set -eu
# Restart hook для make test-persistence (tests/README.md) по образцу
# scripts/restart.example.sh. Перезапускает балансировщик, все реплики API
# и все хранилища стенда — PostgreSQL, Valkey и с лабы 4 S3 — с сохранением
# volume, схемы, данных и объектов: без down -v, FLUSHALL и повторного
# наполнения. Кэш Valkey после рестарта пуст: persistence у него выключен,
# данные — в PostgreSQL. Bucket, пользователи и объекты S3 — в его volume.
# LB гасится первым и поднимается последним. start поднимает те же
# контейнеры всех реплик: число реплик не меняется (реплика, которую
# оставил остановленной stop-one.sh, тоже запускается). start api
# запускает и его зависимости migrate и s3-bootstrap: повторный прогон
# миграций и bootstrap ничего не меняет («exists»). Уборщика hook не
# трогает: он не хранилище и не реплика API, рестарт хранилищ переживает
# сам. Готовность через LB ждёт сам тест. Секретов не печатает. Остановка
# S3 плавная, ~15 с: весь hook — ~25 с.
cd "$(dirname "$0")/.."
docker compose stop haproxy api
docker compose restart postgres valkey s3
# те же контейнеры: --wait только дожидается их healthcheck
docker compose up -d --wait postgres valkey s3
docker compose start api haproxy
+424
View File
@@ -0,0 +1,424 @@
#!/bin/sh
set -eu
# Поочерёдная замена реплик api на новый образ без простоя (рубрика «4»
# лабы 3, сохраняется в лабе 4): make rolling-update. Правила — infra/AGENTS.md, «Поочерёдная
# замена». Compose сам так не умеет (это update_config Swarm), сторонние
# плагины не используются: ещё одна незакреплённая зависимость.
# 0. предусловия: работает ровно API_REPLICAS реплик, остановленных нет,
# слотов LB с ручным состоянием (drain, maint) нет, все реплики UP в
# LB, для ещё одной есть слот; иначе код 2, ничего не менялось;
# 1. сборка образа из рабочего дерева (ROLLOUT_BUILD=0 — без сборки:
# тег сервиса уже указывает на новый образ, так делает bench/);
# 2. миграции один раз: контейнер сервиса migrate пересоздаётся на новом
# образе и выполняется до новых реплик — в новом образе новые
# ревизии, они только расширяют схему (migrations/AGENTS.md);
# 3–5. для каждой старой реплики: рядом одна новая (--scale N+1
# --no-recreate) → новая healthy и UP в LB → слот старой drain,
# запросов в полёте 0 → maint → docker stop → docker rm → адрес ушёл
# из слота → слот ready.
# Сбой: новая реплика не готова — она удаляется; новая уже UP — вывод
# старой доводится до конца. В любом исходе работает API_REPLICAS реплик,
# слоты LB без ручного состояния; повторный запуск доводит замену.
# Отката нет: откат — вернуть прежний код и снова make rolling-update
# (схема только расширялась, прежний код на ней работает).
# Окружение:
# API_REPLICAS (2) — число реплик до и после;
# ROLLOUT_BUILD (1) — собрать образ сервиса api из рабочего дерева;
# ROLLOUT_MIGRATE (1) — 0: без миграций;
# ROLLOUT_READY_TIMEOUT (60) — срок готовности новой реплики, с;
# ROLLOUT_DRAIN_TIMEOUT (90) — срок дренажа старой, с: больше самой
# долгой живой загрузки вложения (~81 с, haproxy.cfg, set-timeout
# пути загрузки) — плановая замена её не обрывает; обычный дренаж —
# доли секунды.
# Проект compose — как у самого docker compose: COMPOSE_PROJECT_NAME,
# COMPOSE_FILE, COMPOSE_ENV_FILES или compose.yaml и .env репозитория;
# стенд bench/ (профиль rollout) вызывает этот же скрипт со своими.
# Секретов не печатает. Коды: 0 — замена завершена; 2 — неверный ввод или
# стенд не готов, ничего не менялось; 1 — сбой; 130 / 143 — прерван
# (Ctrl+C / SIGTERM).
cd "$(dirname "$0")/.."
# runtime API HAProxy: только loopback внутри контейнера LB (haproxy.cfg)
LB_API_PORT=9999
replicas="${API_REPLICAS:-2}"
ready_timeout="${ROLLOUT_READY_TIMEOUT:-60}"
drain_timeout="${ROLLOUT_DRAIN_TIMEOUT:-90}"
build="${ROLLOUT_BUILD:-1}"
migrate="${ROLLOUT_MIGRATE:-1}"
# состояние текущей замены для trap: "" — реплики не тронуты, starting —
# новая запущена и ещё не UP, replacing — новая UP, старая выводится из LB
# и удаляется
state=""
before=""
new_id=""
old_id=""
old_addr=""
old_slot=""
step=""
log() {
printf '%s rolling-update: %s\n' "$(date -u +%H:%M:%S)" "$*"
}
fail() {
code=$1
shift
printf '%s rolling-update: error: %s\n' "$(date -u +%H:%M:%S)" "$*" >&2
exit "$code"
}
short() {
printf '%.12s' "$1"
}
count() {
printf '%s\n' "$1" | grep -c . || true
}
# команда runtime API LB изнутри его контейнера (curl и socat в образе
# нет, bash есть); ответ — в stdout
lb() {
docker compose exec -T haproxy bash -c \
'exec 3<>"/dev/tcp/127.0.0.1/$2" && printf "%s\n" "$1" >&3 && cat <&3' \
lb "$1" "$LB_API_PORT"
}
# та же команда LB для оператора — в подсказках ручной уборки
lb_hint() {
printf "docker compose exec -T haproxy bash -c 'exec 3<>/dev/tcp/127.0.0.1/%s && echo \"%s\" >&3 && cat <&3'" \
"$LB_API_PORT" "$1"
}
# смена состояния слота: успешная команда отвечает пустой строкой, ошибка
# — текстом («No such server.»)
lb_set() {
answer=$(lb "set server api/$1 state $2" | tr -d '\r\n')
if [ -n "$answer" ]; then
printf '%s rolling-update: error: LB set server api/%s state %s: %s\n' \
"$(date -u +%H:%M:%S)" "$1" "$2" "$answer" >&2
return 1
fi
}
# занятые слоты backend api: «слот адрес запросов_в_полёте состояние»;
# состояние последним — в нём бывают пробелы («DOWN 1/2»)
slots() {
lb "show stat" | awk -F, '
/^# / { sub(/^# /, ""); for (i = 1; i <= NF; i++) col[$i] = i; next }
$1 == "api" && $2 != "BACKEND" && $(col["addr"]) != "" {
addr = $(col["addr"]); sub(/:[0-9]+$/, "", addr)
print $2, addr, $(col["scur"]), $(col["status"])
}'
}
slot_total() {
lb "show stat" | awk -F, '$1 == "api" && $2 != "BACKEND" && $2 != "" { n++ } END { print n + 0 }'
}
# слоты с ручным состоянием, которое оставила прерванная замена: флаги
# FMAINT (1) и FDRAIN (8) в srv_admin_state; обслуживание по DNS (32) —
# штатное. show stat их не различает: у слота без адреса и то и другое —
# «MAINT (resolution)», а следующей реплике в этом слоте LB запросов не даст
manual_slots() {
lb "show servers state api" | awk '
/^# / { for (i = 2; i <= NF; i++) col[$i] = i - 1; next }
NF > 5 && col["srv_admin_state"] {
s = $(col["srv_admin_state"])
if (s % 2 == 1 || int(s / 8) % 2 == 1) print $(col["srv_name"])
}'
}
# поле слота с адресом $1: 1 — слот, 3 — запросов в полёте, 4 — состояние
slot_field() {
slots | awk -v addr="$1" -v field="$2" '
$2 == addr { if (field == 4) { $1 = $2 = $3 = ""; sub(/^ +/, "") ; print } else print $field; exit }'
}
address() {
docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' "$1"
}
health() {
docker inspect -f '{{if .State.Health}}{{.State.Health.Status}}{{else}}{{.State.Status}}{{end}}' "$1" 2>/dev/null || echo gone
}
now() {
date +%s
}
# новая реплика — ID, которого не было до up --scale (список before)
find_new() {
for id in $(docker compose ps -a -q --no-trunc api); do
case " $before " in
*" $id "*) ;;
*) printf '%s\n' "$id" ;;
esac
done
}
# дождаться, пока адрес удалённой реплики уйдёт из слота (DNS, hold 1 с),
# не дольше 10 с
wait_address_gone() {
deadline=$(($(now) + 10))
while [ -n "$(slot_field "$1" 1)" ]; do
if [ "$(now)" -ge "$deadline" ]; then
log "$step: address $1 still in slot after 10s"
return 0
fi
sleep 0.25
done
}
# довести вывод старой реплики до удаления (шаги 3–5). Ошибки проверяются
# явно (|| return 1): в trap функция вызывается под if, где set -e не
# действует. Повторный вызов после частичного — тоже корректен: удалённый
# контейнер пропускается
remove_old() {
lb_set "$old_slot" maint || return 1
if docker inspect "$old_id" >/dev/null 2>&1; then
log "$step: maint slot $old_slot, stopping old $(short "$old_id")"
stopping=$(now)
# stop_grace_period сервиса: uvicorn завершается сам за SHUTDOWN_TIMEOUT
docker stop --timeout 10 "$old_id" >/dev/null || return 1
stopped=$(($(now) - stopping))
# код выхода: 0 — graceful по SIGTERM, 137 — SIGKILL по сроку
exited=$(docker inspect -f '{{.State.ExitCode}}' "$old_id" 2>/dev/null || echo '?')
docker rm "$old_id" >/dev/null || return 1
log "$step: removed old $(short "$old_id") (stop ${stopped}s, exit $exited)"
fi
wait_address_gone "$old_addr"
lb_set "$old_slot" ready || return 1
log "$step: slot $old_slot ready"
}
# убрать новую реплику, которая не стала готовой. Есть слот (DNS уже отдал
# его) — maint, затем штатная остановка: стартующий процесс выходит сразу
# по раннему обработчику SIGTERM (src/early_stop.py), работающий —
# дорабатывает запросы, которые LB успел отправить на слот до maint. Слота
# нет — запросов на ней не было, и docker rm -f безопасен: это и страховка
# на первые десятки миллисекунд старта интерпретатора, где SIGTERM ещё
# некому принять. Прерывание между up --scale и поиском новой: ID ещё не
# известен, ищется здесь
remove_new() {
if [ -z "$new_id" ]; then
new_id=$(find_new | tail -n 1)
fi
if [ -z "$new_id" ]; then
log "$step: no new replica was created"
return 0
fi
log "$step: removing new replica $(short "$new_id") that is not ready"
new_addr=$(address "$new_id" 2>/dev/null || true)
new_slot=""
if [ -n "$new_addr" ]; then
new_slot=$(slot_field "$new_addr" 1)
fi
if [ -z "$new_slot" ]; then
docker rm -f "$new_id" >/dev/null || return 1
log "$step: removed new $(short "$new_id") (no slot: docker rm -f)"
return 0
fi
lb_set "$new_slot" maint || return 1
stopping=$(now)
docker stop --timeout 10 "$new_id" >/dev/null || return 1
stopped=$(($(now) - stopping))
exited=$(docker inspect -f '{{.State.ExitCode}}' "$new_id" 2>/dev/null || echo '?')
docker rm -f "$new_id" >/dev/null || return 1
log "$step: removed new $(short "$new_id") (slot $new_slot: stop ${stopped}s, exit $exited)"
wait_address_gone "$new_addr"
lb_set "$new_slot" ready || return 1
}
cleanup() {
code=$?
set +e
trap '' INT TERM
case "$state" in
starting)
if ! remove_new; then
log "manual cleanup: docker rm -f ${new_id:-<new api container>}; slots in manual state: $(lb_hint 'show servers state api') (srv_admin_state 1 or 8); set each ready: $(lb_hint 'set server api/<slot> state ready')"
fi
;;
replacing)
log "$step: new replica is UP, finishing removal of old $(short "$old_id")"
if ! remove_old; then
log "manual cleanup: docker rm -f $old_id; then $(lb_hint "set server api/$old_slot state ready")"
fi
;;
esac
if [ "$code" -ne 0 ] && [ -n "$state" ]; then
log "stopped: $(count "$(docker compose ps -q api)") api replicas running; rerun make rolling-update to finish"
fi
exit "$code"
}
for value in "$replicas" "$ready_timeout" "$drain_timeout"; do
case "$value" in
'' | *[!0-9]* | 0) fail 2 "API_REPLICAS and ROLLOUT_*_TIMEOUT must be positive integers" ;;
esac
done
for value in "$build" "$migrate"; do
case "$value" in
0 | 1) ;;
*) fail 2 "ROLLOUT_BUILD and ROLLOUT_MIGRATE must be 0 or 1" ;;
esac
done
# 0. предусловия — ничего не меняют
if ! lb "show info" >/dev/null 2>&1; then
fail 2 "HAProxy runtime API is unreachable: start the LB with the current infra/haproxy/haproxy.cfg (docker compose up -d --force-recreate --no-deps haproxy)"
fi
old=$(docker compose ps -q --no-trunc api)
all=$(docker compose ps -a -q --no-trunc api)
if [ "$(count "$all")" -ne "$(count "$old")" ]; then
fail 2 "stopped api replicas exist: run make replicas first"
fi
if [ "$(count "$old")" -ne "$replicas" ]; then
fail 2 "$(count "$old") api replicas running, API_REPLICAS=$replicas: run make replicas first"
fi
slots_total=$(slot_total)
if [ $((replicas + 1)) -gt "$slots_total" ]; then
fail 2 "API_REPLICAS + 1 = $((replicas + 1)) replicas do not fit $slots_total LB slots"
fi
# раньше проверки UP: слот работающей реплики в ручном drain — не повод для
# make replicas, а остаток прерванной замены
stuck=$(manual_slots | tr '\n' ' ')
if [ -n "$stuck" ]; then
fail 2 "LB slots left in manual drain/maint by an interrupted rollout: ${stuck% }; set each ready: $(lb_hint 'set server api/<slot> state ready')"
fi
for id in $old; do
status=$(slot_field "$(address "$id")" 4)
if [ "$status" != UP ]; then
fail 2 "replica $(short "$id") is not UP in LB (${status:-no slot}): run make replicas and wait"
fi
done
image=$(docker inspect -f '{{.Config.Image}}' "$(printf '%s\n' "$old" | head -n 1)")
ids=""
for id in $old; do
ids="$ids $(short "$id")"
done
log "start: $replicas replicas${ids}, image $image"
began=$(now)
trap cleanup EXIT
trap 'exit 130' INT
trap 'exit 143' TERM
# 1. сборка: тот же тег сервиса, работающие реплики остаются на прежнем
# образе (контейнер держит образ по ID, а не по тегу)
if [ "$build" = 1 ]; then
started=$(now)
docker compose build api
log "build done in $(($(now) - started))s"
else
log "build skipped (ROLLOUT_BUILD=0): tag $image already points to the new image"
fi
# 2. миграции один раз, до первой новой реплики. Контейнер сервиса migrate
# пересоздаётся на новом образе, а не одноразовый run --rm: иначе в стенде
# остался бы migrate прежнего образа, и restart.sh (start api запускает
# зависимость migrate) гонял бы старые миграции на новой схеме — «Can't
# locate revision», и реплики не стартуют
if [ "$migrate" = 1 ]; then
started=$(now)
if ! docker compose up --no-deps --no-build --force-recreate \
--abort-on-container-exit --exit-code-from migrate migrate; then
fail 1 "migrations failed: no replica was replaced"
fi
log "migrate done in $(($(now) - started))s"
else
log "migrate skipped (ROLLOUT_MIGRATE=0)"
fi
number=0
for old_id in $old; do
number=$((number + 1))
step="replica $number/$replicas"
# 3. одна новая реплика рядом со старыми. new_id прежнего шага — уже
# рабочая реплика: сбросить до state, иначе уборка удалила бы её
new_id=""
before=$(docker compose ps -a -q --no-trunc api | tr '\n' ' ')
state=starting
started=$(now)
docker compose up -d --no-deps --no-recreate --no-build --scale "api=$((replicas + 1))" api
new_id=$(find_new | tail -n 1)
if [ -z "$new_id" ]; then
state=""
fail 1 "$step: compose did not start a new replica"
fi
log "$step: started new $(short "$new_id")"
# 4. новая готова: healthy (или running без healthcheck) и UP в LB по её
# адресу — слот начинает DOWN и включается после rise проверок
deadline=$(($(now) + ready_timeout))
while :; do
current=$(health "$new_id")
status=""
case "$current" in
healthy | running)
new_addr=$(address "$new_id")
if [ -n "$new_addr" ]; then
status=$(slot_field "$new_addr" 4)
fi
if [ "$status" = UP ]; then
break
fi
;;
exited | dead | gone)
fail 1 "$step: new replica $(short "$new_id") $current"
;;
esac
if [ "$(now)" -ge "$deadline" ]; then
fail 1 "$step: new replica $(short "$new_id") not UP in LB within ${ready_timeout}s (container ${current}, LB ${status:-no slot})"
fi
sleep 0.25
done
log "$step: new $(short "$new_id") addr $new_addr slot $(slot_field "$new_addr" 1) UP in $(($(now) - started))s"
# 5. старая: drain → запросов в полёте 0 → maint → stop → rm → ready
old_addr=$(address "$old_id")
old_slot=$(slot_field "$old_addr" 1)
if [ -z "$old_slot" ]; then
fail 1 "$step: old replica $(short "$old_id") has no LB slot"
fi
state=replacing
lb_set "$old_slot" drain
log "$step: drain old $(short "$old_id") addr $old_addr slot $old_slot"
started=$(now)
deadline=$((started + drain_timeout))
while :; do
inflight=$(slot_field "$old_addr" 3)
if [ "${inflight:-0}" = 0 ]; then
log "$step: old $(short "$old_id") idle after $(($(now) - started))s"
break
fi
if [ "$(now)" -ge "$deadline" ]; then
log "$step: drain timeout ${drain_timeout}s, $inflight requests in flight: graceful stop finishes them"
break
fi
sleep 0.25
done
remove_old
state=""
old_slot=""
done
# итог: API_REPLICAS реплик, ни одной прежней, все UP
current=$(docker compose ps -q --no-trunc api)
if [ "$(count "$current")" -ne "$replicas" ]; then
fail 1 "$(count "$current") api replicas running after rollout, expected $replicas"
fi
ids=""
for id in $current; do
case " $(printf '%s\n' "$old" | tr '\n' ' ') " in
*" $id "*) fail 1 "old replica $(short "$id") still running" ;;
esac
status=$(slot_field "$(address "$id")" 4)
if [ "$status" != UP ]; then
fail 1 "replica $(short "$id") is not UP in LB after rollout (${status:-no slot})"
fi
ids="$ids $(short "$id")"
done
log "done: $replicas replicas${ids} UP in $(($(now) - began))s"
+82
View File
@@ -0,0 +1,82 @@
#!/bin/sh
set -eu
# Failover hook для make test-failover (tests/README.md) по образцу
# scripts/stop-one.example.sh; правила — infra/AGENTS.md.
# TARGET_INSTANCE_ID — X-Instance-Id реплики, то есть начало ID её
# контейнера (hostname в compose). Скрипт останавливает ровно одну
# работающую реплику сервиса api этого проекта и оставляет её
# остановленной: restart: unless-stopped не поднимает контейнер ни после
# docker stop, ни после docker kill. PostgreSQL, Valkey, LB, чужие
# контейнеры и volumes не трогает. Восстановление — make replicas.
# STOP_MODE=stop (по умолчанию) — docker stop: SIGTERM и graceful;
# STOP_MODE=kill — docker kill: SIGKILL, отказ процесса без graceful;
# STOP_ONE_LOG=<файл> — дописать строку «время, TARGET_INSTANCE_ID,
# полный ID контейнера, режим»: тест скрывает вывод hook, а evidence
# должно показать, какой контейнер остановлен.
# Секретов и окружения не печатает. Неверный ввод — код 2 до вызова
# docker, нет такой реплики — код 3.
# Проект compose — как у самого docker compose: COMPOSE_PROJECT_NAME,
# COMPOSE_FILE и т. п. или compose.yaml и .env репозитория.
# пустое значение — код 2 в любой оболочке (${VAR:?} даёт 1 в bash и 2 в
# dash)
if [ -z "${TARGET_INSTANCE_ID:-}" ]; then
echo "stop-one: TARGET_INSTANCE_ID is empty; test provides target API instance alias" >&2
exit 2
fi
mode="${STOP_MODE:-stop}"
case "$mode" in
stop | kill) ;;
*)
echo "stop-one: STOP_MODE must be stop or kill" >&2
exit 2
;;
esac
# hostname контейнера — его ID в hex, от 12 символов
case "$TARGET_INSTANCE_ID" in
*[!0-9a-f]*)
echo "stop-one: TARGET_INSTANCE_ID is not a container id" >&2
exit 2
;;
esac
if [ "${#TARGET_INSTANCE_ID}" -lt 12 ] || [ "${#TARGET_INSTANCE_ID}" -gt 64 ]; then
echo "stop-one: TARGET_INSTANCE_ID is not a container id" >&2
exit 2
fi
cd "$(dirname "$0")/.."
# только работающие реплики сервиса api этого проекта, полные ID
match=""
for id in $(docker compose ps -q --no-trunc api); do
case "$id" in
"$TARGET_INSTANCE_ID"*)
if [ -n "$match" ]; then
echo "stop-one: TARGET_INSTANCE_ID matches several replicas" >&2
exit 3
fi
match="$id"
;;
esac
done
if [ -z "$match" ]; then
echo "stop-one: no running api replica of this project matches TARGET_INSTANCE_ID" >&2
exit 3
fi
if [ "$mode" = stop ]; then
# uvicorn завершается сам не позже SHUTDOWN_TIMEOUT (5 с, не больше 9);
# срок 9 с гарантирует возврат hook раньше 10 с и для зависшего процесса
docker stop --timeout 9 "$match" >/dev/null
else
docker kill "$match" >/dev/null
fi
if [ -n "${STOP_ONE_LOG:-}" ]; then
printf '%s TARGET_INSTANCE_ID=%s container=%s mode=%s\n' \
"$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$TARGET_INSTANCE_ID" "$match" "$mode" \
>>"$STOP_ONE_LOG"
fi
echo "stop-one: stopped api container $(printf '%.12s' "$match") (mode $mode)" >&2
+241
View File
@@ -0,0 +1,241 @@
# src/ — устройство приложения
Дополняет корневой `AGENTS.md`. Правила конкретных слоёв — в
`api/AGENTS.md`, `services/AGENTS.md`, `storage/AGENTS.md`.
## Слои и направление зависимостей
```
api/ (routes, deps, identity, request_id, handlers, schemas)
↓ cleaner/ (python -m src.cleaner)
services/ (UserService, SessionService, ChatService, MessageService,
AttachmentService, CleanupService, ReconcileService, access.py)
↓
storage/ (Storage Protocol → CachedStorage → PostgresStorage;
MaintenanceStorage; AttachmentObjects → s3.ObjectStore)
```
Общие модули нижнего уровня: `domain.py`, `errors.py`, `pagination.py`,
`clock.py`, `constants.py`, `log.py`, `config.py`, `images.py`
(структурная проверка PNG/JPEG без декодирования, stdlib). Инфраструктура
— тоже общие модули: `db.py` (PostgreSQL), `cache.py` (Valkey), `s3.py`
(клиент S3, лаба 4), `uploads.py` (места загрузок процесса API),
`passwords.py` (Argon2id). В них нет бизнес-правил.
| Модуль | Может импортировать | Не может импортировать |
|---|---|---|
| `api/*` | services, storage (только типы `Storage`, `AttachmentObjects`), `uploads.UploadSlots` (тип), общие модули, fastapi/starlette | `storage.postgres`, `storage.cached`, `db`, `cache`, `s3` (их собирает `main.py`) |
| `services/*` | `storage` (Protocol и `AttachmentObjects`), `passwords`, `uploads`, `images`, общие модули, `anyio.to_thread` (проверка изображения в потоке) | `api/*`, `db`, `cache`, `s3`, fastapi, starlette, pydantic, sqlalchemy |
| `storage/*` | `domain`, `errors`, `pagination`, `clock`, `constants`, `db`, `cache`, `s3` (типы и клиент), sqlalchemy | `api/*`, `services/*`, fastapi, `log` |
| `db`, `cache`, `s3`, `passwords`, `uploads` | `config`, `constants`, `errors`, `log`, свой драйвер (asyncpg, redis, aiobotocore) | `api/*`, `services/*`, `storage/*` |
| `cleaner/*` | всё, кроме `api/*`: он собирает свой процесс | `api/*` |
| `domain`, `clock`, `constants`, `images` | только стандартную библиотеку | всё остальное из `src` |
| `errors` | `constants` | остальное |
| `pagination` | `domain`, `errors` | остальное |
| `main.py` | всё: он собирает приложение | — |
| `healthcheck.py` | только стандартную библиотеку | `src.*` (проверка должна быть дешёвой) |
| `early_stop.py` | только стандартную библиотеку | `src.*`: работает до импорта приложения и настройки журнала |
Цикл импортов или импорт «вверх» — признак, что код лежит не в том слое.
`migrations/env.py` импортирует `config`, `db.database_url`, `log` и
`storage.tables` — и ничего, что создаёт engine при импорте.
## Кто за что отвечает
- **Роут**: принять запрос (pydantic-модель, параметры пути и query),
взять сессию и сервис из зависимостей, вызвать сервис именованными
аргументами, превратить доменный объект в модель ответа. Бизнес-правил
нет.
- **Сервис**: правила контракта, которые не выражаются схемой (дубликаты
участников, вызывающий в чате, членство, курсор), пароль и сессия,
вызов хранилища, логи бизнес-событий.
- **Хранилище**: атомарная операция над данными — одна транзакция
PostgreSQL; назначение `id` и `created_at`; уникальность и внешние
ключи; перевод сработавшего ограничения в доменную ошибку. Кэш —
обёртка `CachedStorage` над тем же интерфейсом.
- **Инфраструктура**: пул, сроки, обход отказов, журнал отказов. Отказ
PostgreSQL → `Unavailable` (503) в `db.py`; отказ Valkey → промах в
`cache.py`.
## Ошибки (`errors.py`)
- У каждого класса свои `status_code`, `code`, `default_message` и, у
401, `challenge` (значение `WWW-Authenticate`). Перевод в ответ — один
обработчик `api/handlers.py` (`app_error_response`), его же зовёт
`AuthenticationMiddleware` через `identity.on_auth_error`.
- Новая ошибка: наследник подходящего класса (`InvalidRequest` → 400,
`NotFound` → 404, ...), `code` — только из enum `Error.code` в
`contracts/openapi.json`. Текст — английский, без id, путей, имён
классов, SQL и признаков существования чужого объекта.
- Нет чата и чат чужой — **одно и то же** `NotFound`.
- Тот же `Idempotency-Key` с другим телом — `IdempotencyConflict` (409
`conflict`); нет ключа или он не по шаблону — 400 из валидации
заголовка ручки. Ключ в текст ошибки не попадает.
- Вход: `InvalidCredentials` (вызов Basic) — одна ошибка на неверный
пароль, неизвестный username и битый Basic. Остальное: `Unauthorized`
(вызов Bearer). Недоступность хранилища — `Unavailable` (503), никогда
не 401.
## Время (`clock.py`)
- `created_at` назначает `MonotonicClock` внутри хранилища, перед
вставкой: строго возрастающее aware-время UTC с шагом ≥ 1 мкс внутри
**процесса**. С лабы 3 процессов несколько (реплики): между репликами
монотонности нет, порядок задают часы ВМ Docker (у реплик одного хоста
общие) и `id` при равенстве. Транзакции фиксируются не в порядке
времени: запись с меньшим `created_at` может стать видимой позже
соседней (REPORT.md, «Пагинация»).
- Срок сессии сравнивается с `utc_now()` — без монотонной поправки.
- Наружу — только `to_rfc3339()`: `2026-09-01T12:00:00.000000Z`; обратно
(значение из кэша) — `from_rfc3339()`. `datetime.now()` без UTC и
`isoformat()` в ответах не использовать: smoke требует суффикс `Z`.
## Пагинация (`pagination.py`)
- Порядок `(created_at, id)` по возрастанию; `sort_key()` — единственное
место, где он задан в Python; в SQL — `ORDER BY created_at, id` и
сравнение кортежей.
- Сервис просит у хранилища `limit + 1` строк и отдаёт их в
`make_page()`: лишняя строка значит, что есть следующая страница.
Страница ровно из `limit` при пустом остатке даёт `next_cursor=None`.
- Курсор — ключ последнего элемента страницы плюс область
(`history_scope(chat_id)`, `chat_list_scope(user_id)`). Курсор чужой
области, битый base64, не та структура → `InvalidCursor` (400).
Формат курсора внутренний: клиенты и тесты его не разбирают.
## Логи (`log.py`)
- Логгер модуля: `log = get_logger(__name__)` сразу после импортов.
`logging.getLogger` напрямую, `print` и `traceback.print_exc` не
использовать (исключение — строка `configuration error` в stderr при
неверном окружении, до настройки логов).
- Формат задаёт `logging_config()`, его применяет uvicorn
(`uvicorn.run(log_config=...)`); у процесса миграций — `migrations/env.py`.
Второй `dictConfig`/`basicConfig` в коде приложения не добавлять.
- Сообщение — английский, нижний регистр, данные — `key=value` через
`%`-подстановку: `log.info("chat created chat_id=%s members=%d", ...)`.
Не f-string: форматирование ленивое.
- `rid` добавляет фильтр из contextvar `request_id_var`; ставит его
только `RequestIdMiddleware`.
- Уровни: `info` — бизнес-событие (создан пользователь, сессия, чат,
сообщение; отказ по бизнес-правилу), старт и остановка, возврат кэша;
`warning` — обработано, но требует внимания (неудачный вход, отказ БД
или Valkey); `error` — операция не выполнена. 4xx — не ошибки сервера.
- **Нельзя в лог**: `text` сообщения, `display_name`, `title`, username,
пароль, токен, их хэши, `Authorization`, `Idempotency-Key` (его
выбирает клиент, в нём может быть что угодно; повтор виден по
`replayed=true`), тела, query-строку, параметры SQL. Engine создан с
`hide_parameters=True`: текст ошибки драйвера содержит SQL, но не
параметры. Вместо текста — `length=len(text)`.
## Конфигурация (`config.py`)
- `Settings.from_env()` читает только `os.environ`, без `.env` и файлов.
Экземпляр создаётся в `run()` и кладётся в `app.state.settings`;
модульного глобала `settings` нет.
- Подключения — вложенные `Database` и `Cache` (переменные `DB_*`,
`CACHE_*`). Пароли — поля с `repr=False`: в `repr()` настроек их нет.
- У dataclass со `slots=True` атрибут класса — дескриптор, а не значение:
умолчания в `from_env` берутся у экземпляра (`default = cls()`).
- Неверное значение — `ConfigError` с именем переменной; `run()`
печатает её в stderr и выходит с кодом 2.
- Новая настройка — поле `Settings` (или `Database`/`Cache`) с безопасным
дефолтом и границами, `environment` в `compose.yaml` (если её задают
контейнеру), строка в `.env.example` (если она приходит из `.env`),
строка в таблице ниже.
| Переменная | По умолчанию | Смысл |
|---|---|---|
| `APP_HOST` / `APP_PORT` | `127.0.0.1` (в образе `0.0.0.0`) / `8080` | адрес и порт прослушивания |
| `APP_INSTANCE_ID` | hostname (в контейнере — начало его ID) | значение `X-Instance-Id`; `[A-Za-z0-9._-]{1,64}`; по нему `scripts/stop-one.sh` находит реплику |
| `LOG_LEVEL` | `INFO` | `DEBUG`/`INFO`/`WARNING`/`ERROR` |
| `SHUTDOWN_TIMEOUT` | `5` | секунды дожидания запросов после SIGTERM, 1..9 (< `stop_grace_period` 10 с) |
| `KEEP_ALIVE_TIMEOUT` | `60` | секунды простаивающего keep-alive соединения uvicorn; больше `timeout http-keep-alive` HAProxy (10 с) — закрывает LB, а не реплика (`infra/AGENTS.md`) |
| `SESSION_TTL_SECONDS` | `3600` | срок сессии (контракт); в тесте истечения — 2 |
| `IDEMPOTENCY_TTL_SECONDS` | `86400` | сколько повтор с тем же `Idempotency-Key` отдаёт прежний результат (контракт: ≥ 24 ч); в тесте срока — 2 |
| `KDF_CONCURRENCY` | `4` | одновременных хэшей Argon2id (64 MiB на каждый) |
| `DB_HOST` / `DB_PORT` / `DB_NAME` / `DB_USER` / `DB_PASSWORD` | `127.0.0.1` / `5432` / `messenger` / `messenger` / пусто | подключение к PostgreSQL |
| `DB_POOL_SIZE` / `DB_POOL_OVERFLOW` / `DB_POOL_TIMEOUT` | `10` / `5` / `5` с | пул на процесс и ожидание соединения |
| `DB_CONNECT_TIMEOUT` / `DB_STATEMENT_TIMEOUT_MS` / `DB_OPERATION_TIMEOUT` | `3` с / `5000` / `6` с | подключение, серверный срок запроса, срок операции хранилища целиком |
| `CACHE_HOST` / `CACHE_PORT` / `CACHE_PASSWORD` | `127.0.0.1` / `6379` / пусто | подключение к Valkey |
| `CACHE_TIMEOUT` / `CACHE_RETRY_AFTER` / `CACHE_CHAT_TTL` / `CACHE_MAX_CONNECTIONS` | `0.2` с / `5` с / `3600` с / `10` | срок команды, окно пропуска после отказа, срок карточки, пул |
| `S3_ENDPOINT` / `S3_BUCKET` / `S3_REGION` | `http://127.0.0.1:8334` (в compose `http://s3:8333`) / `messenger-attachments` / `us-east-1` | адрес API S3, приватный bucket, регион подписи |
| `S3_ACCESS_KEY_ID` / `S3_SECRET_ACCESS_KEY` | пусто (`repr=False`) | ключи **своего** пользователя S3: у реплик — API (`S3_API_*` из `.env`), у уборщика — свои (`S3_CLEANER_*`); административная пара — только у сервера `s3` |
| `S3_TIMEOUT` / `S3_CONNECT_TIMEOUT` / `S3_MAX_CONNECTIONS` | `5` с / `1` с / `10` | срок вызова S3 целиком и каждого блока чтения (`asyncio.timeout`; `read_timeout` aiohttp выключен), подключение, пул клиента; повторов нет |
| `UPLOAD_MAX_CONCURRENT` / `UPLOAD_MAX_WAITING` / `UPLOAD_WAIT_TIMEOUT` / `UPLOAD_BODY_TIMEOUT` | `4` / `16` / `5` с / `30` с | мест загрузки на процесс, очередь за местом, ожидание места (затем 429 с `Retry-After`), срок тела с момента места (затем 400) |
| `CLEANER_INTERVAL` / `CLEANER_GRACE` / `CLEANER_BATCH` | `60` с / `900` с / `100` | уборщик: пауза между проходами, возраст незавершённой загрузки (> границы живой загрузки 21 с, иначе код 2), кандидатов на выборку |
| `RECONCILE_INTERVAL` / `RECONCILE_PAGE_SIZE` / `RECONCILE_MAX_CHANGES` / `RECONCILE_RATE` | `3600` с (0 — плановой нет) / `1000` / `100` / `2000` | плановая сверка, страница списка и строк, предел изменений за проход, объектов S3 в секунду (0 — без предела) |
## Приложение (`main.py`)
- `create_app()` собирает `Db`, кэш (`create_cache`, пространство ключей
— имя базы), `CachedStorage(PostgresStorage(db), cache)`,
`Passwords`, с лабы 4 — клиент S3 (`create_object_store`, пространство
ключей — то же имя базы) в `AttachmentObjects` и `UploadSlots`; кладёт
их в `app.state`. Соединения открываются лениво: без PostgreSQL
процесс стартует, `/health/ready` отвечает 503. S3 готовность не
проверяет: без него текст работает, загрузка и скачивание — 503.
- Порядок middleware (снаружи внутрь): `ServerErrorMiddleware` →
`RequestIdMiddleware` → `AuthenticationMiddleware` → роутер.
`add_middleware` добавляет **снаружи**, поэтому `RequestIdMiddleware`
регистрируется последним. Порядок не менять: иначе ответы 401/503 от
аутентификации не попадут в access-лог и получат случайный id вместо
входящего `X-Request-Id` (ловит `student-tests/test_request_id.py`).
- `lifespan`: первой строкой `early_stop.disarm()` (дальше сигналы —
забота uvicorn), фиктивный хэш пароля, `store.start()` (модели
botocore, без сети), `ready=True`; в начале остановки `ready=False`,
затем `engine.dispose()`, закрытие клиентов Valkey и S3. Пустые ключи
S3 — строка `warning` при старте, а не отказ.
Строки «messenger started instance=…» (там же пул, сроки, keep-alive) и
«messenger stopped instance=…»: по ним реплика в журнале
сопоставляется с `X-Instance-Id`. Долгих операций в остановке нет:
SIGTERM укладывается в `SHUTDOWN_TIMEOUT`.
- `RequestIdMiddleware(instance_id=...)` ставит `X-Request-Id` и
`X-Instance-Id` каждому ответу; ответам 500 их ставит
`handlers.error_response` (они формируются снаружи middleware).
- `uvicorn.run(app, ...)` — экземпляр, без `workers` и `reload`, с
`timeout_keep_alive`: один процесс, пул соединений считан на него.
Масштабирование — числом реплик за HAProxy, а не `--workers`.
- В памяти процесса нет ничего, от чего зависит корректность: сессии,
данные и ключи идемпотентности — в PostgreSQL, Valkey — общий кэш
неизменяемых карточек (лаба 3, реплики взаимозаменяемы).
## Уборщик (`cleaner/`, лаба 4)
`python -m src.cleaner` — второй процесс на образе API (сервис compose
`cleaner`), а не задача реплик: N реплик были бы N уборщиками, а
остановка реплики обрывала бы проход. `__main__` → `early_stop.install()`
→ `main.run()`: настройки (неверные — код 2), проверка `CLEANER_GRACE` >
границы живой загрузки `2 × (DB_OPERATION_TIMEOUT + 2) + S3_TIMEOUT` (21
с; иначе код 2 до соединений), свой пул (на стенде 1 соединение) и
клиент S3 с ключами уборщика. Режимы: сервис (уборка раз в
`CLEANER_INTERVAL`, плановая сверка `batch` с исправлением при старте и
раз в `RECONCILE_INTERVAL`), `--once`, `reconcile [--apply]
[--max-changes N] [--strategy batch|head] [--deep] [--rate R]` (dry-run
по умолчанию; коды 0 / 3 / 1 / 2 — докстринг `cleaner/main.py`).
SIGTERM: текущий шаг доводится до commit или отката, новых нет.
## Точка входа (`__main__.py`, `early_stop.py`)
`python -m src` → `early_stop.install()` **до** импорта приложения →
`main.run()`. В контейнере сервер — PID 1, а ядро не доставляет PID 1
сигнал без обработчика: пока идёт импорт (почти весь старт), SIGTERM
терялся бы, и `docker stop` стартующей реплики ждал бы 10 с и SIGKILL.
Ранний обработчик пишет одну строку «stopped before startup» (формат
`log.py`, без rid) и завершает процесс с кодом 0. `early_stop.py` — только
stdlib. Проверка — `evidence/stand/early-stop.txt`.
## Рецепт: новая ручка
1. Найти путь, схемы и коды в `contracts/openapi.json`; если ручки там
нет — она не нужна для «4», спросить пользователя.
2. Модели запроса/ответа — в `api/schemas.py` с именами из контракта.
3. Операция данных — метод в `storage/base.py` (Protocol, докстринг: что
атомарно и какие ошибки), реализация в `storage/postgres.py`
(одна транзакция), делегирование в `storage/cached.py`. Нужна новая
колонка или индекс — сначала ревизия (`migrations/AGENTS.md`).
4. Правила — метод сервиса (keyword-only, async), лог события.
5. Роут — в `api/routes/<домен>.py`; новый файл роутов — зарегистрировать
в `api/routes/__init__.py`. Публичная ручка под `/api/v1` — добавить в
`PUBLIC_ENDPOINTS` (`api/identity.py`).
6. Тест в `student-tests/`, затем Definition of Done (корневой файл, раздел 8).
+7
View File
@@ -0,0 +1,7 @@
"""REST API мессенджера MTUSI, лабораторная 3: реплики за HAProxy.
PostgreSQL — источник истины (данные, сессии, ключи идемпотентности),
Valkey — общий кэш карточек чатов. Пакет намеренно пустой при импорте:
`import src.<модуль>` не поднимает приложение, не читает окружение и не
подключается к базе.
"""
+10
View File
@@ -0,0 +1,10 @@
if __name__ == "__main__":
# обработчик SIGTERM — до импорта приложения (src/early_stop.py):
# импорт и есть почти весь старт, а PID 1 без обработчика сигнал теряет
from src import early_stop
early_stop.install()
from src.main import run
run()
+181
View File
@@ -0,0 +1,181 @@
# src/api/ — HTTP-слой и контракт
Источник правды — `contracts/openapi.json` и `contracts/README.md`.
Сгенерированная FastAPI схема (`/openapi.json`) — только справка, но
схемы безопасности в ней совпадают с контрактом (это проверяет
`student-tests/test_auth.py`).
## Устройство
| Файл | Что делает |
|---|---|
| `routes/health.py` | `/health/live` (всегда 200), `/health/ready` (200, если старт завершён и PostgreSQL отвечает `SELECT 1` за 2 с, иначе 503; Valkey не проверяется). Вне `/api/v1`, без идентификации, в access-лог не пишутся. `/health/ready` раз в секунду опрашивает HAProxy: по нему реплика исключается из LB и возвращается |
| `routes/users.py`, `sessions.py`, `chats.py`, `messages.py` | ручки v1; префикс `/api/v1` добавляет `api_router` в `routes/__init__.py`; `messages.py` объявляет обязательный заголовок `Idempotency-Key` |
| `routes/attachments.py` (лаба 4) | `POST /chats/{chat_id}/attachments?filename=` (сырое тело потоком через `request.stream()`, схема тела — `openapi_extra`), `GET /attachments/{id}` (метаданные), `GET /attachments/{id}/content[?variant=original]` (байты `StreamingResponse` с `Content-Length`, `X-Content-Type-Options: nosniff`) |
| `schemas.py` | все pydantic-модели; имена = схемы контракта (`CreateUser`, `User`, `Session`, `ChatPage`, ...) |
| `deps.py` | `get_storage`, `get_passwords`, фабрики сервисов, `current_identity` / `current_user`, разбор Basic (`basic_credentials`), `PageParams` |
| `identity.py` | `BearerBackend` для `AuthenticationMiddleware`, `PUBLIC_ENDPOINTS`, `on_auth_error` |
| `request_id.py` | чистое ASGI-middleware (`__call__`): id запроса, заголовки `X-Request-Id` и `X-Instance-Id`, access-лог |
| `handlers.py` | `error_response()`, `app_error_response()` (с `WWW-Authenticate`) и обработчики всех исключений |
## Правила ручек
- Ручки и зависимости — только `async def`: драйвер БД асинхронный, а
синхронная `def` ушла бы в threadpool.
- Ручка: зависимости → вызов сервиса именованными аргументами →
`Schema.model_validate(domain_obj)`. Логики, обращений к хранилищу и
`try/except` здесь нет.
- POST создания — `status_code=201` в декораторе; `response_model` —
модель контракта. `DELETE /auth/sessions/current` — 204 без тела
(`response_class=Response`).
- Текущий пользователь — `CurrentUser`, текущая сессия (для logout) —
`CurrentIdentity` из `deps.py`. Заголовки `Authorization` и `X-User-Id`
в ручках не читать и не объявлять `Header()`.
- Ошибки — исключения из `src/errors.py`. `HTTPException` не бросать,
`JSONResponse` с ошибкой руками не собирать — только `handlers.py`.
- Модели API в сервис не передавать: разбирать на именованные аргументы.
## Идентификация (лаба 2)
- Bearer проверяет `BearerBackend` в `AuthenticationMiddleware` **до
роутинга и разбора тела**: битый JSON без токена получает 401, а не
400 («сначала аутентификация», `contracts/README.md`). Не переносить
проверку в зависимость ручки — порядок сломается.
- Защищено всё под `/api/v1/`, кроме `PUBLIC_ENDPOINTS`:
`POST /api/v1/users` и `POST /api/v1/auth/sessions`. Health и `/docs`
— вне `/api/v1`.
- Токен — из `Authorization: Bearer <token>` (схема без учёта
регистра). Нет заголовка, другая схема (в том числе Basic на
бизнес-ручке), пустой, неизвестный, истёкший, отозванный токен —
одинаковый 401 `Unauthorized` с `WWW-Authenticate: Bearer
realm="messenger"`.
- PostgreSQL недоступен во время проверки токена — 503 `unavailable` без
`WWW-Authenticate`: бэкенд заворачивает любую `AppError` в
`AuthFailure`, и `on_auth_error` отвечает её статусом. Запрос никогда
не идёт дальше как анонимный.
- `X-User-Id` не читается нигде: не даёт доступа и не меняет владельца
сессии.
- `current_identity` объявляет `Security(HTTPBearer(scheme_name=
"bearerAuth", bearerFormat="opaque session token", auto_error=False))`
только ради схемы в `/openapi.json` и кнопки Authorize в `/docs`; сам
заголовок там не читается — сессию уже положил бэкенд в `request.user`.
## Вход по Basic (`POST /auth/sessions`)
- Путь публичный для middleware; Basic разбирает зависимость
`basic_credentials`. Схема объявлена через `HTTPBase(scheme="basic",
scheme_name="basicAuth", auto_error=False)` (импорт из
`fastapi.security.http`). **Не `HTTPBasic`**: он декодирует ASCII и на
пароле не из ASCII сам отвечает 401 мимо формата контракта.
- Разбор: схема `Basic` → base64 строго (`validate=True`) → UTF-8 →
`partition(":")` по **первому** двоеточию (в пароле двоеточие
допустимо). Username не по шаблону и пароль вне 12–128 code points
отсекаются здесь, до БД и KDF. Любой сбой — тот же 401
`InvalidCredentials` с `WWW-Authenticate: Basic realm="messenger",
charset="UTF-8"`, что и неверный пароль. Ответа 400 у входа нет.
- JSON-тело входа не читается.
## Ловушки FastAPI и что ждёт контракт
| Ситуация | FastAPI по умолчанию | Нужно |
|---|---|---|
| ошибка валидации тела/пути/query | 422 `{"detail": ...}` | 400 `invalid_request` в формате контракта (`on_validation_error`) |
| битый JSON, массив вместо объекта | 422 `json_invalid` | 400 (с токеном) или 401 (без токена: middleware раньше) |
| неизвестный путь / метод | 404 / 405 `{"detail"}` | формат контракта (`on_http_error`) |
| необработанное исключение | 500 text/plain без `X-Request-Id` | 500 `internal_error` + заголовок (`on_unexpected_error` ставит его сам) |
| `Authorization` как `Header()` | пропуск → 400 из валидации | только схемы безопасности с `auto_error=False` |
| `HTTPBasic` | ASCII, свой 401 | `HTTPBase` + свой разбор |
| `strict=True` на всю модель | UUID-строка из JSON не проходит | строгость на полях: `StrictStr`, `NonBlankStr` |
## Валидация (всё — 400)
- Модели запросов наследуют `_Request` (`extra="forbid"`): лишнее поле,
например `sender_id` в сообщении, — 400.
- Строки — `StrictStr`: число вместо строки — 400. Обязательные строки
(`display_name`, `title`, `password`) — `NonBlankStr`: одни пробелы —
400, значение не обрезается и не нормализуется. `text` сообщения с
лабы 4 может быть пустым только с вложением (раздел «Вложения»).
- Длины — в Unicode code points (`len(str)`): `display_name`, `title`
1–100, `text` 0–4000, `password` 12–128, `filename` 1–255. `username` —
`^[a-z0-9_]{3,32}$` целиком.
- `member_ids`: 1–100 UUID; дубликаты, неизвестные и отсутствие
вызывающего — 400 из сервиса/хранилища (`InvalidMembers`).
- `chat_id` не UUID, `limit` вне 1–100 или не число, пустой или битый
`cursor` — 400.
- Лимиты — только из `src/constants.py`.
## Ответы
- Модели ответа наследуют `_Response` (`from_attributes=True`), время —
тип `Timestamp` (RFC 3339 с `Z`). Лишних полей нет: smoke сверяет
`additionalProperties: false`. В `User` нет пароля, хэша и сессии.
- `Session`: `token`, `token_type="Bearer"`, `expires_at`, `user`.
- Список — `{"items": [...], "next_cursor": null | "..."}`.
- `X-Request-Id` ставит `RequestIdMiddleware` каждому ответу; входящий
заголовок принимается, только если он `[A-Za-z0-9._-]{1,64}`.
- `X-Instance-Id` (лаба 3) — **в каждом ответе API**: успех, ошибки,
health, 401/503 от аутентификации, 404 неизвестного пути, 405, 500.
Одно значение на процесс (`Settings.instance_id`: `APP_INSTANCE_ID` или
hostname — в контейнере начало ID). Ответы самого HAProxy (502/503/504)
его не имеют — контракт допускает. Тест — `test_request_id.py`.
- Access-лог: одна строка `METHOD path -> status (ms)`, без query, тела
и заголовков. Второй access-лог (uvicorn) выключен.
## Отправка сообщения: `Idempotency-Key` (лаба 3)
- Заголовок обязателен только у `POST /api/v1/chats/{chat_id}/messages`:
параметр ручки `Header(alias="Idempotency-Key", pattern=...)` с
шаблоном `IDEMPOTENCY_KEY_PATTERN` (`^[A-Za-z0-9._:-]{1,128}$`). Нет
ключа, пустой, длиннее 128, недопустимый символ, не-ASCII — 400
`invalid_request` той же валидацией, что тело; значение ключа в текст
ошибки не попадает. Другие POST ключ не читают.
- Порядок кодов: 401 (сессия — middleware) → 400 (ключ и тело — схема
ручки) → 404 (не участник — сервис) → 409 (ключ занят другим телом —
хранилище). Без токена — 401 даже с битым JSON и без ключа:
аутентификация в middleware раньше разбора тела и заголовков ручки.
Закреплено `test_idempotency.py::test_codes_order_401_400_404_409`.
- Повтор того же тела — **тот же 201 и то же `Message`** (тот же `id`,
`created_at` до микросекунды): ручка не различает новое и повторное.
«То же тело» — семантически: пробелы и `\u`-экранирование не важны
(хэш канонического JSON в сервисе).
- Прозрачных повторов других POST нет ни в API, ни в LB.
## Вложения (лаба 4)
Контракт — `contracts/README.md`, «Вложения (с lab4)», и
`contracts/openapi.json`. Как это сделано:
- **Загрузка** — тело читается только сервисом (`AttachmentService`),
потоком из `request.stream()`; ручка не вызывает `request.body()` и не
объявляет тело параметром (иначе FastAPI прочитал бы его целиком до
проверок). Схема тела для `/openapi.json` — `openapi_extra`.
`filename` — обязательный query: строгий UTF-8 по сырой
`scope["query_string"]` (битые percent-последовательности — 400, а не
`U+FFFD`), затем `DisplayFilename` (1–255 code points, без `/`, `\` и
управляющих Cc, не из одних пробелов; значение не меняется). Обрыв
клиента (`ClientDisconnect`) — `UploadInterrupted` (400).
- Коды загрузки: 401 → 400 (`chat_id`, `filename`) → 404 (не участник)
→ 415 (`Content-Type`) → 413 (`Content-Length`) → 429 (нет места, с
`Retry-After`) → 413/400 (тело больше лимита, срок тела, обрыв) →
415/413 (содержимое) → 503 (S3 или PostgreSQL) → 201 `Attachment`
(`status: ready`, `sha256` hex). Порядок и причины — `src/services/AGENTS.md`.
- **Метаданные и байты** — участникам чата; чужое, неизвестное,
незавершённое (`pending`) и потерянное (`lost_at`, только байты) — 404
одинаково. `variant` — только `original` (иначе 400): превью — лаба 5.
Байты идут через API: адреса и ключи S3 клиенту не отдаются, в ответе
нет `Location` и `x-amz-*`.
- **Сообщение** (`CreateMessage`): `text` — `StrictStr` до 4000 code
points; `attachment_ids` — до 10 UUID без повторов; пустой текст (в том
числе из пробелов) — только с ≥ 1 вложением (согласование 20 октября
2026, корневой `AGENTS.md`, раздел 12). Вложения не `ready` или из
другого чата — 404 из хранилища. `Message.attachment_ids` — в порядке
отправки, `[]` у сообщений без вложений.
- `handlers.app_error_response` добавляет `Retry-After` к 429
(`AppError.retry_after`) и `WWW-Authenticate` к 401.
## Проверка правок этого слоя
`make fmt && make lint && make test-isolated`. Для точечной проверки —
рабочий стенд (`make up`) и `curl -s -i` с выводом статуса,
`x-request-id`, `x-instance-id`, `www-authenticate` и тела. Токен в
вывод и отчёт не копировать.
View File
+193
View File
@@ -0,0 +1,193 @@
"""Зависимости ручек: хранилище, сервисы, текущая сессия, вход, страница.
С лабы 4 — `AttachmentService`: хранилище, объекты вложений в S3 и места
загрузок процесса из `app.state` (их собирает `main.py`).
"""
import base64
import binascii
import re
from dataclasses import dataclass, field
from typing import Annotated
from fastapi import Depends, Query, Request, Security
from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
from fastapi.security.http import HTTPBase
from src.constants import (
PAGE_LIMIT_DEFAULT,
PAGE_LIMIT_MAX,
PAGE_LIMIT_MIN,
PASSWORD_MAX_LENGTH,
PASSWORD_MIN_LENGTH,
USERNAME_PATTERN,
)
from src.domain import Identity, User
from src.errors import InvalidCredentials, Unauthorized
from src.passwords import Passwords
from src.services import (
AttachmentService,
ChatService,
MessageService,
SessionService,
UserService,
)
from src.storage import Storage
async def get_storage(request: Request) -> Storage:
return request.app.state.storage
async def get_passwords(request: Request) -> Passwords:
return request.app.state.passwords
StorageDep = Annotated[Storage, Depends(get_storage)]
PasswordsDep = Annotated[Passwords, Depends(get_passwords)]
async def get_user_service(storage: StorageDep, passwords: PasswordsDep) -> UserService:
return UserService(storage, passwords)
async def get_session_service(
request: Request,
storage: StorageDep,
passwords: PasswordsDep,
) -> SessionService:
return SessionService(
storage, passwords, ttl=request.app.state.settings.session_ttl
)
async def get_chat_service(storage: StorageDep) -> ChatService:
return ChatService(storage)
async def get_message_service(request: Request, storage: StorageDep) -> MessageService:
return MessageService(
storage,
key_ttl=request.app.state.settings.idempotency_ttl,
)
async def get_attachment_service(
request: Request, storage: StorageDep
) -> AttachmentService:
state = request.app.state
return AttachmentService(
storage,
state.objects,
state.upload_slots,
body_timeout=state.settings.uploads.body_timeout,
)
UserServiceDep = Annotated[UserService, Depends(get_user_service)]
SessionServiceDep = Annotated[SessionService, Depends(get_session_service)]
ChatServiceDep = Annotated[ChatService, Depends(get_chat_service)]
MessageServiceDep = Annotated[MessageService, Depends(get_message_service)]
AttachmentServiceDep = Annotated[AttachmentService, Depends(get_attachment_service)]
# схемы bearerAuth и basicAuth из contracts/openapi.json: они есть в
# /openapi.json и дают кнопку Authorize в /docs. auto_error=False —
# FastAPI не отвечает сам своим 403/401 мимо формата контракта.
# Bearer проверяет BearerBackend (identity.py) ещё до роутинга.
bearer_scheme = HTTPBearer(
scheme_name="bearerAuth",
bearerFormat="opaque session token",
auto_error=False,
)
# HTTPBase, а не HTTPBasic: HTTPBasic декодирует credentials как ASCII и
# на пароле не из ASCII сам отвечает 401, а контракт требует UTF-8
basic_scheme = HTTPBase(scheme="basic", scheme_name="basicAuth", auto_error=False)
async def current_identity(
request: Request,
_credentials: Annotated[
HTTPAuthorizationCredentials | None, Security(bearer_scheme)
],
) -> Identity:
"""Сессия, которую нашёл BearerBackend.
`_credentials` здесь не читается: параметр только объявляет схему
bearerAuth в OpenAPI. Если ручку вдруг повесили на публичный путь,
сессии нет — 401, а не падение.
"""
identity = request.user
if not isinstance(identity, Identity):
raise Unauthorized
return identity
CurrentIdentity = Annotated[Identity, Depends(current_identity)]
async def current_user(identity: CurrentIdentity) -> User:
return identity.user
CurrentUser = Annotated[User, Depends(current_user)]
@dataclass(frozen=True, slots=True)
class BasicCredentials:
username: str
password: str = field(repr=False)
def parse_basic(
credentials: HTTPAuthorizationCredentials | None,
) -> BasicCredentials | None:
"""username и пароль из `Authorization: Basic`; `None` — разбор не удался.
base64 строго, UTF-8, разделитель — первое двоеточие: в username его
не бывает, в пароле оно допустимо. Значения, которые не могут быть
верными (формат username и длина пароля публичны), отсекаются здесь:
до БД и KDF не доходит ни мусор, ни пароль в мегабайт.
"""
if credentials is None or credentials.scheme.lower() != "basic":
return None
try:
decoded = base64.b64decode(credentials.credentials, validate=True)
username, separator, password = decoded.decode().partition(":")
except (binascii.Error, UnicodeDecodeError):
return None
if not separator or not re.fullmatch(USERNAME_PATTERN, username):
return None
if not PASSWORD_MIN_LENGTH <= len(password) <= PASSWORD_MAX_LENGTH:
return None
return BasicCredentials(username=username, password=password)
async def basic_credentials(
credentials: Annotated[HTTPAuthorizationCredentials | None, Security(basic_scheme)],
) -> BasicCredentials:
"""Учётные данные входа; любой сбой разбора — тот же 401, что неверный пароль."""
parsed = parse_basic(credentials)
if parsed is None:
raise InvalidCredentials
return parsed
BasicCredentialsDep = Annotated[BasicCredentials, Depends(basic_credentials)]
@dataclass(frozen=True, slots=True)
class PageParams:
limit: int
cursor: str | None
async def page_params(
limit: Annotated[int, Query(ge=PAGE_LIMIT_MIN, le=PAGE_LIMIT_MAX)] = (
PAGE_LIMIT_DEFAULT
),
cursor: Annotated[str | None, Query(min_length=1)] = None,
) -> PageParams:
return PageParams(limit=limit, cursor=cursor)
PageDep = Annotated[PageParams, Depends(page_params)]
+130
View File
@@ -0,0 +1,130 @@
"""Любая ошибка → `{"error": {"code", "message", "request_id"}}`.
- `AppError`: статус, `code` и `WWW-Authenticate` (у 401) берутся из
класса исключения.
- Ошибки валидации FastAPI → 400 `invalid_request` (422 не отдаётся).
- 404 неизвестного пути и 405 → формат контракта.
- Непредвиденное исключение → 500 без деталей. Traceback пишет uvicorn:
Starlette после ответа бросает исключение дальше.
"""
from uuid import uuid4
from fastapi import FastAPI, Request
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from starlette.exceptions import HTTPException as StarletteHTTPException
from starlette.requests import HTTPConnection
from src.api.schemas import ErrorBody, ErrorResponse
from src.constants import INSTANCE_ID_HEADER, REQUEST_ID_HEADER
from src.errors import AppError
_HTTP_ERRORS: dict[int, tuple[str, str]] = {
404: ("not_found", "Not found"),
405: ("invalid_request", "Method not allowed"),
}
def request_id_of(conn: HTTPConnection) -> str:
"""Id запроса от RequestIdMiddleware; запасной — если ошибка случилась раньше."""
return getattr(conn.state, "request_id", None) or uuid4().hex
def error_response(
conn: HTTPConnection,
*,
status_code: int,
code: str,
message: str,
headers: dict[str, str] | None = None,
) -> JSONResponse:
request_id = request_id_of(conn)
body = ErrorResponse(
error=ErrorBody(code=code, message=message, request_id=request_id),
)
return JSONResponse(
status_code=status_code,
content=body.model_dump(),
# заголовки ставит и middleware; здесь они нужны ответам 500,
# которые формируются снаружи всех middleware
headers={
**(headers or {}),
REQUEST_ID_HEADER: request_id,
INSTANCE_ID_HEADER: conn.app.state.settings.instance_id,
},
)
def app_error_response(conn: HTTPConnection, exc: AppError) -> JSONResponse:
"""Ответ на доменную ошибку; общий для ручек и AuthenticationMiddleware.
У 401 — `WWW-Authenticate`, у 429 — `Retry-After` (контракт: целое
число секунд).
"""
headers = {}
if exc.challenge:
headers["WWW-Authenticate"] = exc.challenge
if exc.retry_after is not None:
headers["Retry-After"] = str(exc.retry_after)
return error_response(
conn,
status_code=exc.status_code,
code=exc.code,
message=str(exc),
headers=headers or None,
)
async def on_app_error(request: Request, exc: AppError) -> JSONResponse:
return app_error_response(request, exc)
async def on_validation_error(
request: Request,
exc: RequestValidationError,
) -> JSONResponse:
# первая ошибка: где и что не так; входное значение в ответ не попадает
errors = exc.errors()
first = errors[0] if errors else {}
location = ".".join(str(part) for part in first.get("loc", ()))
reason = first.get("msg", "Invalid request")
return error_response(
request,
status_code=400,
code="invalid_request",
message=f"{location}: {reason}" if location else reason,
)
async def on_http_error(
request: Request,
exc: StarletteHTTPException,
) -> JSONResponse:
code, message = _HTTP_ERRORS.get(
exc.status_code,
("invalid_request", "Invalid request"),
)
return error_response(
request,
status_code=exc.status_code,
code=code,
message=message,
headers=exc.headers,
)
async def on_unexpected_error(request: Request, _exc: Exception) -> JSONResponse:
return error_response(
request,
status_code=500,
code="internal_error",
message="Internal server error",
)
def install(app: FastAPI) -> None:
app.add_exception_handler(AppError, on_app_error)
app.add_exception_handler(RequestValidationError, on_validation_error)
app.add_exception_handler(StarletteHTTPException, on_http_error)
app.add_exception_handler(Exception, on_unexpected_error)
+89
View File
@@ -0,0 +1,89 @@
"""Идентификация лабы 2: Bearer-сессия — до роутинга и разбора тела.
Работает через стандартный `AuthenticationMiddleware` Starlette.
`BearerBackend` вызывается на каждый запрос:
- публичный путь (health, docs, `POST /api/v1/users`,
`POST /api/v1/auth/sessions`) — `None`, запрос идёт дальше без
пользователя. Вход по Basic разбирает сама ручка входа (`deps.py`);
- защищённый путь — сессия по токену из `Authorization: Bearer <token>`
или отказ, и middleware сразу отвечает через `on_auth_error`.
Поэтому 401 приходит раньше любой проверки тела, пути и query: «сначала
аутентификация» из contracts/README.md выполняется даже для битого JSON.
Ручки берут готовую сессию из `request.user` (`deps.current_identity`).
`X-User-Id` больше не читается нигде: он не даёт доступа и не меняет
владельца сессии. Basic на бизнес-ручке — чужая схема, тот же 401 с
вызовом Bearer. Недоступность PostgreSQL — 503, а не 401 и не анонимный
доступ.
"""
from fastapi.responses import JSONResponse
from fastapi.security.utils import get_authorization_scheme_param
from starlette.authentication import (
AuthCredentials,
AuthenticationBackend,
AuthenticationError,
)
from starlette.requests import HTTPConnection
from src.api.handlers import app_error_response
from src.constants import API_PREFIX, AUTHORIZATION_HEADER, SESSIONS_PATH
from src.domain import Identity
from src.errors import AppError, Unauthorized
from src.services import SessionService
# публичные пути внутри API_PREFIX: регистрация и вход по Basic
PUBLIC_ENDPOINTS = frozenset(
{
("POST", f"{API_PREFIX}/users"),
("POST", SESSIONS_PATH),
},
)
def requires_identity(method: str, path: str) -> bool:
return path.startswith(f"{API_PREFIX}/") and (method, path) not in PUBLIC_ENDPOINTS
def bearer_token(header: str | None) -> str | None:
"""Токен из `Authorization: Bearer <token>`; другая схема — `None`."""
scheme, token = get_authorization_scheme_param(header)
if scheme.lower() != "bearer" or not token:
return None
return token
class AuthFailure(AuthenticationError):
"""Отказ бэкенда с доменной ошибкой: 401 или 503 (БД недоступна)."""
def __init__(self, error: AppError) -> None:
super().__init__(str(error))
self.error = error
class BearerBackend(AuthenticationBackend):
async def authenticate(
self,
conn: HTTPConnection,
) -> tuple[AuthCredentials, Identity] | None:
if not requires_identity(conn.scope.get("method", ""), conn.scope["path"]):
return None
state = conn.app.state
sessions = SessionService(
state.storage,
state.passwords,
ttl=state.settings.session_ttl,
)
token = bearer_token(conn.headers.get(AUTHORIZATION_HEADER))
try:
identity = await sessions.authenticate(token=token)
except AppError as exc:
raise AuthFailure(exc) from exc
return AuthCredentials(["authenticated"]), identity
def on_auth_error(conn: HTTPConnection, exc: AuthenticationError) -> JSONResponse:
error = exc.error if isinstance(exc, AuthFailure) else Unauthorized()
return app_error_response(conn, error)
+83
View File
@@ -0,0 +1,83 @@
"""X-Request-Id и X-Instance-Id на каждом ответе, одна строка access-лога.
Чистое ASGI-middleware: прямой вызов приложения и обёртка send.
Без дочерней задачи и потока сообщений на каждый запрос: это уменьшает
накладные расходы слоя, исследуемые в треке «5».
Id запроса: входящий `X-Request-Id`, если он короткий и безопасный
(`[A-Za-z0-9._-]{1,64}`), иначе новый uuid4. Так id проходит через
балансировщик, а мусор из заголовка не попадает в логи. Тот же id — в
заголовке ответа, в `request_id` тела ошибки и в каждой строке лога
этого запроса.
`X-Instance-Id` (лаба 3) — реплика, которая обслужила запрос: одно
значение на процесс (`Settings.instance_id`). Ответы, которые создаёт
сам HAProxy (502/503/504), его не имеют — контракт это допускает.
"""
import re
import time
from uuid import uuid4
from starlette.datastructures import Headers, MutableHeaders
from starlette.types import ASGIApp, Message, Receive, Scope, Send
from src.constants import HEALTH_PATHS, INSTANCE_ID_HEADER, REQUEST_ID_HEADER
from src.log import get_logger, request_id_var
log = get_logger("src.http")
_SAFE_REQUEST_ID = re.compile(r"[A-Za-z0-9._-]{1,64}")
def _request_id(scope: Scope) -> str:
incoming = Headers(scope=scope).get(REQUEST_ID_HEADER)
if incoming and _SAFE_REQUEST_ID.fullmatch(incoming):
return incoming
return uuid4().hex
class RequestIdMiddleware:
def __init__(self, app: ASGIApp, *, instance_id: str) -> None:
self.app = app
self.instance_id = instance_id
async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
if scope["type"] != "http":
await self.app(scope, receive, send)
return
request_id = _request_id(scope)
# request.state.request_id — для обработчиков ошибок
scope.setdefault("state", {})["request_id"] = request_id
# не сбрасывается: у каждого запроса в uvicorn своя задача, а
# traceback непредвиденной ошибки uvicorn пишет уже после выхода
# отсюда, и в нём тоже нужен rid
request_id_var.set(request_id)
status_code = 500
started = time.perf_counter()
async def send_with_ids(message: Message) -> None:
nonlocal status_code
if message["type"] == "http.response.start":
status_code = message["status"]
headers = MutableHeaders(scope=message)
if REQUEST_ID_HEADER not in headers:
headers.append(REQUEST_ID_HEADER, request_id)
if INSTANCE_ID_HEADER not in headers:
headers.append(INSTANCE_ID_HEADER, self.instance_id)
await send(message)
try:
await self.app(scope, receive, send_with_ids)
finally:
# health дёргают healthcheck и балансировщик: в лог не пишем.
# Путь без query; тела и заголовки идентификации не логируются
if scope["path"] not in HEALTH_PATHS:
log.info(
"%s %s -> %d (%.1f ms)",
scope["method"],
scope["path"],
status_code,
(time.perf_counter() - started) * 1000,
)
+26
View File
@@ -0,0 +1,26 @@
"""Роутеры. `api_router` собирает ручки версии 1 под API_PREFIX.
Новый домен регистрируется только здесь.
"""
from fastapi import APIRouter
from src.api.routes.attachments import router as attachments_router
from src.api.routes.chats import router as chats_router
from src.api.routes.health import router as health_router
from src.api.routes.messages import router as messages_router
from src.api.routes.sessions import router as sessions_router
from src.api.routes.users import router as users_router
from src.constants import API_PREFIX
api_router = APIRouter(prefix=API_PREFIX)
api_router.include_router(users_router)
api_router.include_router(sessions_router)
api_router.include_router(chats_router)
api_router.include_router(messages_router)
api_router.include_router(attachments_router)
__all__ = [
"api_router",
"health_router",
]
+160
View File
@@ -0,0 +1,160 @@
"""Вложения (лаба 4): загрузка, метаданные, байты оригинала.
Один домен с двумя префиксами путей — `/chats/{chat_id}/attachments` и
`/attachments/{attachment_id}`, поэтому пути полные в декораторах.
Загрузка не объявляет параметр тела: FastAPI тело не читает, и оно уходит
в сервис асинхронным итератором `request.stream()` только после проверок
входа, параметров, членства, `Content-Type` и `Content-Length`. Схема тела
для `/openapi.json` — в `openapi_extra`, как в контракте.
"""
from collections.abc import AsyncIterator
from typing import Annotated, Literal
from urllib.parse import unquote_to_bytes
from uuid import UUID
from fastapi import APIRouter, Query, Request
from fastapi.responses import StreamingResponse
from starlette.background import BackgroundTask
from starlette.requests import ClientDisconnect
from src.api import schemas
from src.api.deps import AttachmentServiceDep, CurrentUser
from src.constants import ATTACHMENT_FILENAME_MAX_LENGTH, ATTACHMENT_TYPES
from src.errors import InvalidFilename, UploadInterrupted
router = APIRouter(tags=["attachments"])
_BINARY = {"schema": {"type": "string", "format": "binary"}}
_UPLOAD_BODY = {
"requestBody": {
"required": True,
"description": "Raw bytes of one PNG or JPEG image, not multipart.",
"content": dict.fromkeys(ATTACHMENT_TYPES, _BINARY),
},
}
_DOWNLOAD_RESPONSES = {
200: {
"description": "Original bytes",
"content": dict.fromkeys(ATTACHMENT_TYPES, _BINARY),
},
}
FilenameQuery = Annotated[
schemas.DisplayFilename,
Query(min_length=1, max_length=ATTACHMENT_FILENAME_MAX_LENGTH),
]
def _media_type(request: Request) -> str | None:
"""Тип из `Content-Type` без параметров и пробелов, в нижнем регистре."""
value = request.headers.get("content-type")
if value is None:
return None
return value.split(";", 1)[0].strip().lower() or None
def _content_length(request: Request) -> int | None:
value = request.headers.get("content-length")
return int(value) if value is not None and value.isdigit() else None
def _check_filename_encoding(request: Request) -> None:
"""`filename` в строке запроса — строгий UTF-8, иначе 400.
Starlette декодирует процент-коды с заменой неверных байтов на
U+FFFD, и `a%FFb.png` прошёл бы как `a\\ufffdb.png`. Здесь те же пары
(`&`, `=`, `+` — пробел), что у разбора Starlette, но байты значения
проверяются строго.
"""
for pair in request.scope["query_string"].split(b"&"):
name, _, value = pair.partition(b"=")
if unquote_to_bytes(name.replace(b"+", b" ")) != b"filename":
continue
if not value.isascii():
raise InvalidFilename
try:
unquote_to_bytes(value.replace(b"+", b" ")).decode("utf-8")
except UnicodeDecodeError:
raise InvalidFilename from None
async def _body(request: Request) -> AsyncIterator[bytes]:
"""Тело блоками по мере прихода; обрыв клиента — `UploadInterrupted` (400)."""
try:
async for chunk in request.stream():
if chunk:
yield chunk
except ClientDisconnect:
raise UploadInterrupted from None
@router.post(
"/chats/{chat_id}/attachments",
status_code=201,
response_model=schemas.Attachment,
openapi_extra=_UPLOAD_BODY,
)
async def upload_attachment(
user: CurrentUser,
chat_id: UUID,
filename: FilenameQuery,
request: Request,
attachments: AttachmentServiceDep,
) -> schemas.Attachment:
"""201 — оригинал в S3 и метаданные в PostgreSQL сохранены."""
_check_filename_encoding(request)
attachment = await attachments.upload(
chat_id=chat_id,
owner_id=user.id,
filename=filename,
content_type=_media_type(request),
content_length=_content_length(request),
body=_body(request),
)
return schemas.Attachment.model_validate(attachment)
@router.get("/attachments/{attachment_id}", response_model=schemas.Attachment)
async def get_attachment(
user: CurrentUser,
attachment_id: UUID,
attachments: AttachmentServiceDep,
) -> schemas.Attachment:
attachment = await attachments.get(attachment_id=attachment_id, user_id=user.id)
return schemas.Attachment.model_validate(attachment)
@router.get(
"/attachments/{attachment_id}/content",
response_class=StreamingResponse,
responses=_DOWNLOAD_RESPONSES,
)
async def download_attachment(
user: CurrentUser,
attachment_id: UUID,
attachments: AttachmentServiceDep,
# вариант на лабе 4 один; enum — как в контракте (Literal из одного
# значения pydantic пишет как const)
variant: Annotated[
Literal["original"],
Query(json_schema_extra={"enum": ["original"]}),
] = "original",
) -> StreamingResponse:
"""Байты оригинала потоком из S3, без redirect: доступ проверяет API.
Отказ S3 до заголовков — 503; посреди потока соединение обрывается.
"""
content = await attachments.open_content(
attachment_id=attachment_id, user_id=user.id
)
return StreamingResponse(
content.chunks,
media_type=content.content_type,
headers={
"Content-Length": str(content.size_bytes),
"X-Content-Type-Options": "nosniff",
},
# генератор сам закрывает объект; это — если он не начался
background=BackgroundTask(content.close),
)
+46
View File
@@ -0,0 +1,46 @@
from uuid import UUID
from fastapi import APIRouter
from src.api import schemas
from src.api.deps import ChatServiceDep, CurrentUser, PageDep
router = APIRouter(prefix="/chats", tags=["chats"])
@router.post("", status_code=201, response_model=schemas.Chat)
async def create_chat(
user: CurrentUser,
body: schemas.CreateChat,
chats: ChatServiceDep,
) -> schemas.Chat:
chat = await chats.create(
creator_id=user.id,
title=body.title,
member_ids=body.member_ids,
)
return schemas.Chat.model_validate(chat)
@router.get("", response_model=schemas.ChatPage)
async def list_chats(
user: CurrentUser,
page: PageDep,
chats: ChatServiceDep,
) -> schemas.ChatPage:
result = await chats.list_for(
user_id=user.id,
limit=page.limit,
cursor=page.cursor,
)
return schemas.ChatPage.model_validate(result)
@router.get("/{chat_id}", response_model=schemas.Chat)
async def get_chat(
user: CurrentUser,
chat_id: UUID,
chats: ChatServiceDep,
) -> schemas.Chat:
chat = await chats.get(chat_id=chat_id, user_id=user.id)
return schemas.Chat.model_validate(chat)
+32
View File
@@ -0,0 +1,32 @@
from fastapi import APIRouter, Request
from src.api.schemas import ErrorResponse, Health
from src.constants import HEALTH_LIVE_PATH, HEALTH_READY_PATH
from src.errors import Unavailable
# вне версии API, без идентификации, в access-лог не пишутся
router = APIRouter(tags=["health"])
@router.get(HEALTH_LIVE_PATH, response_model=Health)
async def live() -> Health:
"""Процесс жив и отвечает по HTTP. Хранилища не проверяются."""
return Health()
@router.get(
HEALTH_READY_PATH,
response_model=Health,
responses={503: {"model": ErrorResponse}},
)
async def ready(request: Request) -> Health:
"""Можно обслуживать обязательный путь; иначе 503.
Критичная зависимость — PostgreSQL (`SELECT 1` за 2 с): в нём данные
и сессии. Valkey не проверяется: это кэш, без него запросы идут в
PostgreSQL. До конца старта и с начала остановки — тоже 503.
"""
if not request.app.state.ready:
raise Unavailable
await request.app.state.storage.ping()
return Health()
+52
View File
@@ -0,0 +1,52 @@
from typing import Annotated
from uuid import UUID
from fastapi import APIRouter, Header
from src.api import schemas
from src.api.deps import CurrentUser, MessageServiceDep, PageDep
from src.constants import IDEMPOTENCY_KEY_HEADER, IDEMPOTENCY_KEY_PATTERN
router = APIRouter(prefix="/chats/{chat_id}/messages", tags=["messages"])
# обязательный заголовок (лаба 3). Проверяет схема ручки вместе с телом:
# нет ключа или он не по шаблону — 400 после 401 (middleware) и до 404
# (членство в сервисе). Значение в текст ошибки не попадает
IdempotencyKey = Annotated[
str,
Header(alias=IDEMPOTENCY_KEY_HEADER, pattern=IDEMPOTENCY_KEY_PATTERN),
]
@router.post("", status_code=201, response_model=schemas.Message)
async def send_message(
user: CurrentUser,
chat_id: UUID,
body: schemas.CreateMessage,
idempotency_key: IdempotencyKey,
messages: MessageServiceDep,
) -> schemas.Message:
message = await messages.send(
chat_id=chat_id,
sender_id=user.id,
text=body.text,
attachment_ids=body.attachment_ids,
idempotency_key=idempotency_key,
)
return schemas.Message.model_validate(message)
@router.get("", response_model=schemas.MessagePage)
async def list_messages(
user: CurrentUser,
chat_id: UUID,
page: PageDep,
messages: MessageServiceDep,
) -> schemas.MessagePage:
result = await messages.history(
chat_id=chat_id,
user_id=user.id,
limit=page.limit,
cursor=page.cursor,
)
return schemas.MessagePage.model_validate(result)
+29
View File
@@ -0,0 +1,29 @@
from fastapi import APIRouter, Response
from src.api import schemas
from src.api.deps import BasicCredentialsDep, CurrentIdentity, SessionServiceDep
router = APIRouter(prefix="/auth/sessions", tags=["sessions"])
@router.post("", status_code=201, response_model=schemas.Session)
async def create_session(
credentials: BasicCredentialsDep,
sessions: SessionServiceDep,
) -> schemas.Session:
"""Вход по `Authorization: Basic`; тело запроса не читается."""
issued = await sessions.login(
username=credentials.username,
password=credentials.password,
)
return schemas.Session.model_validate(issued)
@router.delete("/current", status_code=204, response_class=Response)
async def revoke_current_session(
identity: CurrentIdentity,
sessions: SessionServiceDep,
) -> Response:
"""Выход: отзывается только сессия этого токена."""
await sessions.revoke(session_id=identity.session_id)
return Response(status_code=204)
+24
View File
@@ -0,0 +1,24 @@
from fastapi import APIRouter
from src.api import schemas
from src.api.deps import CurrentUser, UserServiceDep
router = APIRouter(prefix="/users", tags=["users"])
@router.post("", status_code=201, response_model=schemas.User)
async def register_user(
body: schemas.CreateUser,
users: UserServiceDep,
) -> schemas.User:
user = await users.register(
username=body.username,
display_name=body.display_name,
password=body.password,
)
return schemas.User.model_validate(user)
@router.get("/me", response_model=schemas.User)
async def get_me(user: CurrentUser) -> schemas.User:
return schemas.User.model_validate(user)
+198
View File
@@ -0,0 +1,198 @@
"""HTTP-модели. Имена и поля совпадают со схемами contracts/openapi.json.
Модели запросов строгие: лишнее поле или неверный тип — 400. Строгость
задаётся на уровне полей (`StrictStr`), а не `strict=True` на всю
модель: иначе UUID, пришедший строкой в JSON, не прошёл бы проверку.
"""
import unicodedata
from datetime import datetime
from typing import Annotated, Any, Literal, Self
from uuid import UUID
from pydantic import (
AfterValidator,
BaseModel,
BeforeValidator,
ConfigDict,
Field,
PlainSerializer,
StrictStr,
model_validator,
)
from src.clock import to_rfc3339
from src.constants import (
CHAT_MEMBERS_MAX,
CHAT_TITLE_MAX_LENGTH,
DISPLAY_NAME_MAX_LENGTH,
MESSAGE_ATTACHMENTS_MAX,
MESSAGE_TEXT_MAX_LENGTH,
PASSWORD_MAX_LENGTH,
PASSWORD_MIN_LENGTH,
USERNAME_PATTERN,
)
# символы, запрещённые в имени файла контрактом, кроме управляющих (Cc)
_FILENAME_SEPARATORS = frozenset("/\\")
def _not_blank(value: str) -> str:
"""Строка из одних пробельных символов невалидна; значение не обрезается."""
if not value.strip():
raise ValueError("must not be blank")
return value
def _display_filename(value: str) -> str:
"""Имя вложения только для показа: 400 — на `/`, `\\`, управляющие
символы категории Cc (NUL, U+0001–U+001F, U+007F–U+009F) и строку из
одних пробелов. Символы форматирования и направления текста (Cf) —
часть письменностей и emoji: принимаются, значение не меняется."""
_not_blank(value)
for char in value:
if char in _FILENAME_SEPARATORS or unicodedata.category(char) == "Cc":
raise ValueError("must not contain path separators or control characters")
return value
def _sha256_hex(value: object) -> object:
"""SHA-256 в домене — байты; в ответе — hex в нижнем регистре."""
return value.hex() if isinstance(value, bytes) else value
# строгая непустая строка: число не превращается в строку, пробелы — 400
NonBlankStr = Annotated[StrictStr, AfterValidator(_not_blank)]
# время в ответе: RFC 3339 UTC с микросекундами и Z
Timestamp = Annotated[datetime, PlainSerializer(to_rfc3339, return_type=str)]
class _Request(BaseModel):
model_config = ConfigDict(extra="forbid")
class _Response(BaseModel):
model_config = ConfigDict(from_attributes=True)
class CreateUser(_Request):
username: StrictStr = Field(pattern=USERNAME_PATTERN)
display_name: NonBlankStr = Field(min_length=1, max_length=DISPLAY_NAME_MAX_LENGTH)
# длина в code points; значение не обрезается и не нормализуется
password: NonBlankStr = Field(
min_length=PASSWORD_MIN_LENGTH,
max_length=PASSWORD_MAX_LENGTH,
json_schema_extra={"writeOnly": True},
)
class User(_Response):
"""Пароля, его хэша и данных сессии здесь нет и быть не может."""
id: UUID
username: str
display_name: str
created_at: Timestamp
class Session(_Response):
"""Ответ на вход. Токен клиент видит только здесь, один раз."""
token: str
token_type: Literal["Bearer"] = "Bearer"
expires_at: Timestamp
user: User
class CreateChat(_Request):
title: NonBlankStr = Field(min_length=1, max_length=CHAT_TITLE_MAX_LENGTH)
# только форма списка; дубликаты, существование участников и
# вызывающего в списке проверяет ChatService.create
member_ids: list[UUID] = Field(min_length=1, max_length=CHAT_MEMBERS_MAX)
class Chat(_Response):
id: UUID
title: str
member_ids: list[UUID]
created_at: Timestamp
class ChatPage(_Response):
items: list[Chat]
next_cursor: str | None
class CreateMessage(_Request):
"""Отправитель берётся из идентификации: поле sender_id даёт 400.
С лабы 4 — `attachment_ids`: 0–10 разных вложений, по умолчанию `[]`.
Пустой текст — `""` или строка из одних пробелов — допустим только с
хотя бы одним вложением (контракт и уточнение преподавателя,
REPORT.md); текст сохраняется как прислан.
"""
text: StrictStr = Field(max_length=MESSAGE_TEXT_MAX_LENGTH)
attachment_ids: list[UUID] = Field(
default_factory=list, max_length=MESSAGE_ATTACHMENTS_MAX
)
@model_validator(mode="after")
def _text_or_attachments(self) -> Self:
if len(set(self.attachment_ids)) != len(self.attachment_ids):
raise ValueError("attachment_ids must be unique")
if not self.text.strip() and not self.attachment_ids:
raise ValueError("text must not be blank without attachments")
return self
class Message(_Response):
id: UUID
chat_id: UUID
sender_id: UUID
text: str
created_at: Timestamp
attachment_ids: list[UUID]
class MessagePage(_Response):
items: list[Message]
next_cursor: str | None
# имя вложения в query загрузки; длина 1–255 — в Query ручки, чтобы она
# была в /openapi.json
DisplayFilename = Annotated[str, AfterValidator(_display_filename)]
class Attachment(_Response):
"""Схема контракта `Attachment`; ключа объекта и пометки сверки в ней нет."""
id: UUID
chat_id: UUID
owner_id: UUID
filename: str
content_type: Literal["image/png", "image/jpeg"]
size_bytes: int
sha256: Annotated[str, BeforeValidator(_sha256_hex)]
# наружу — только готовые вложения; варианты — с лабы 5
status: Literal["ready"]
variants: list[dict[str, Any]] = Field(default_factory=list)
error_code: None = None
created_at: Timestamp
updated_at: Timestamp
class Health(BaseModel):
status: Literal["ok"] = "ok"
class ErrorBody(BaseModel):
code: str
message: str
request_id: str
class ErrorResponse(BaseModel):
error: ErrorBody
+128
View File
@@ -0,0 +1,128 @@
"""Valkey: кэш со сроком на команду и обходом при отказе.
Кэш — не источник истины, поэтому его отказ — промах, а не ошибка:
`get` отдаёт `None`, `set` — `False`, и запрос идёт в PostgreSQL с тем
же ответом. Вся команда — ожидание пула, соединение, повтор и ответ —
ограничена `CACHE_TIMEOUT`. После отказа кэш пропускается на
`CACHE_RETRY_AFTER` секунд: следующие запросы не ждут срок заново.
redis-py по умолчанию повторяет команду с паузами, и замороженный
Valkey держал бы запрос секунды. Здесь повтор один, без паузы и только
на обрыв соединения: так старое соединение пула после рестарта Valkey
открывается заново сразу, а таймаут не повторяется.
В журнал — одна строка `warning` на отказ и `info` при возврате. Пароль
есть только в настройках пула и в журнал не попадает.
"""
import asyncio
import time
from redis.asyncio import BlockingConnectionPool, Redis
from redis.asyncio.retry import Retry
from redis.backoff import NoBackoff
from redis.exceptions import ConnectionError as RedisConnectionError
from redis.exceptions import RedisError
from src.config import Cache as CacheSettings
from src.log import get_logger
log = get_logger(__name__)
class Cache:
"""Строковый кэш поверх клиента Valkey: отказ — промах.
`namespace` — имя базы PostgreSQL, из которой взяты значения: на одном
Valkey ключи разных баз (рабочей и тестовой) не пересекаются.
"""
def __init__(
self,
client: Redis,
*,
namespace: str,
timeout: float,
retry_after: float,
) -> None:
self.namespace = namespace
self._client = client
self._timeout = timeout
self._retry_after = retry_after
# monotonic-время конца пропуска; None — кэш работает
self._skip_until: float | None = None
async def get(self, key: str) -> str | None:
"""Значение ключа; `None` — промах, в том числе из-за отказа."""
if self._skipping():
return None
try:
async with asyncio.timeout(self._timeout):
value = await self._client.get(key)
except (RedisError, OSError) as exc:
self._failed(exc)
return None
self._succeeded()
return value
async def set(self, key: str, value: str, *, ttl: int) -> bool:
"""Записать со сроком в секундах; `False` — не записано из-за отказа."""
if self._skipping():
return False
try:
async with asyncio.timeout(self._timeout):
await self._client.set(key, value, ex=ttl)
except (RedisError, OSError) as exc:
self._failed(exc)
return False
self._succeeded()
return True
async def close(self) -> None:
await self._client.aclose()
def _skipping(self) -> bool:
return self._skip_until is not None and time.monotonic() < self._skip_until
def _failed(self, error: Exception) -> None:
# одна строка на отказ: неудачные пробы после окна пропуска молчат.
# TimeoutError от asyncio.timeout без текста — тогда repr
if self._skip_until is None:
log.warning(
"cache unavailable error_type=%s error=%s retry_after=%.1fs",
type(error).__name__,
str(error) or repr(error),
self._retry_after,
)
self._skip_until = time.monotonic() + self._retry_after
def _succeeded(self) -> None:
if self._skip_until is not None:
self._skip_until = None
log.info("cache available again")
def create_cache(settings: CacheSettings, *, namespace: str) -> Cache:
"""Кэш с пулом и сроками из настроек; соединения открываются лениво."""
# BlockingConnectionPool: при всплеске запросов команда ждёт свободное
# соединение, а обычный пул сразу бросал бы MaxConnectionsError, и
# здоровый Valkey пропускался бы как отказавший.
# Retry — из redis.asyncio: синхронный класс асинхронное соединение
# принимает молча, но повтор с ним не выполняется
pool = BlockingConnectionPool(
host=settings.host,
port=settings.port,
password=settings.password or None,
max_connections=settings.max_connections,
timeout=settings.timeout,
socket_timeout=settings.timeout,
socket_connect_timeout=settings.timeout,
retry=Retry(NoBackoff(), 1, supported_errors=(RedisConnectionError,)),
decode_responses=True,
)
return Cache(
Redis.from_pool(pool),
namespace=namespace,
timeout=settings.timeout,
retry_after=settings.retry_after,
)
+1
View File
@@ -0,0 +1 @@
"""Уборщик незавершённых загрузок и сверка bucket и БД: `python -m src.cleaner`."""
+10
View File
@@ -0,0 +1,10 @@
if __name__ == "__main__":
# как у API (src/__main__.py): обработчик SIGTERM — до импорта, иначе
# PID 1 контейнера уборщика терял бы сигнал во время старта
from src import early_stop
early_stop.install()
from src.cleaner.main import run
run()
+293
View File
@@ -0,0 +1,293 @@
"""Процесс уборщика: уборка незавершённых загрузок и сверка bucket и БД.
python -m src.cleaner # сервис: уборка раз в CLEANER_INTERVAL,
# плановая сверка с исправлением при старте
# и раз в RECONCILE_INTERVAL
python -m src.cleaner --once # один проход уборки
python -m src.cleaner reconcile [--apply] [--max-changes N]
[--strategy batch|head] [--deep] [--rate R] # разовая сверка, dry-run
Отдельный процесс стенда (сервис compose `cleaner`), а не задача реплик
API: N реплик были бы N уборщиками, а остановка реплики обрывала бы
проход. Свой пул PostgreSQL (на стенде — одно соединение: проход
последовательный) и свой клиент S3 с ключами пользователя уборщика:
чтение, удаление и список по префиксу вложений своей базы.
Коды выхода. Сервис и `--once`: 0 — остановлен сигналом или проход дошёл
до конца; 1 — `--once` прерван отказом хранилища или ошибкой; 2 —
конфигурация (неверная переменная; grace не больше границы живой
загрузки). Разовая сверка: 0 — расхождений нет, 3 — остались (в том числе
чужие объекты и отказ по пределу), 1 — прервана отказом, ошибкой или
сигналом, 2 — конфигурация.
"""
import argparse
import asyncio
import logging.config
import signal
import sys
from contextlib import suppress
from datetime import timedelta
from src import early_stop
from src.clock import utc_now
from src.config import ConfigError, Settings
from src.constants import DB_CLOSE_TIMEOUT
from src.db import Db
from src.log import get_logger, logging_config
from src.s3 import create_object_store
from src.services import CleanupService, ReconcileService
from src.services.cleanup import STOPPED, CleanupResult
from src.services.reconcile import BATCH, STRATEGIES, ReconcileResult
from src.storage import AttachmentObjects, PostgresStorage
log = get_logger("src.cleaner")
EXIT_OK = 0
EXIT_FAILED = 1
EXIT_CONFIG = 2
def live_upload_bound(settings: Settings) -> float:
"""Граница живой загрузки, с: от строки `pending` до фиксации `ready`.
Два шага с PostgreSQL (строка и `ready`), каждый — не дольше срока
операции и закрытия соединения, и PUT — не дольше срока вызова S3:
`2 × (6 + 2) + 5 = 21` с по умолчанию. Ожидание места, тело и проверка
изображения идут до строки и в границу не входят.
"""
return 2 * (settings.database.operation_timeout + DB_CLOSE_TIMEOUT) + (
settings.s3.timeout
)
def _positive(value: str) -> int:
number = int(value)
if number < 1:
raise argparse.ArgumentTypeError("must be at least 1")
return number
def _rate(value: str) -> float:
number = float(value)
if not 0 <= number < float("inf"):
raise argparse.ArgumentTypeError("must be a non-negative number")
return number
def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
root = argparse.ArgumentParser(
prog="python -m src.cleaner",
description="Remove stale pending attachments; reconcile the bucket "
"with the database.",
)
root.add_argument("--once", action="store_true", help="one cleanup pass")
commands = root.add_subparsers(dest="command")
reconcile = commands.add_parser(
"reconcile",
help="one reconcile pass, dry-run by default: 0 clean, 3 discrepancies "
"left, 1 interrupted, 2 bad config",
)
reconcile.add_argument("--apply", action="store_true", help="fix what is safe")
reconcile.add_argument(
"--max-changes",
type=_positive,
default=None,
help="change limit (default RECONCILE_MAX_CHANGES)",
)
reconcile.add_argument(
"--strategy",
choices=STRATEGIES,
default=BATCH,
help="batch: a database query per list page; head: a query per object "
"and HEAD per ready row",
)
reconcile.add_argument(
"--deep", action="store_true", help="read objects and compare SHA-256"
)
reconcile.add_argument(
"--rate",
type=_rate,
default=None,
help="S3 objects per second, 0 - no limit (default RECONCILE_RATE)",
)
return root.parse_args(argv)
def run() -> None:
args = parse_args()
try:
settings = Settings.from_env()
except ConfigError as exc:
print(f"configuration error: {exc}", file=sys.stderr)
raise SystemExit(EXIT_CONFIG) from None
logging.config.dictConfig(logging_config(settings.log_level))
raise SystemExit(asyncio.run(main(settings, args)))
async def main(settings: Settings, args: argparse.Namespace) -> int:
cleaner = settings.cleaner
bound = live_upload_bound(settings)
if cleaner.grace <= bound:
# до соединений: ни одного обращения к хранилищам
log.error(
"cleaner grace is not longer than live upload bound grace=%ds "
"bound=%.0fs db_operation_timeout=%gs s3_timeout=%gs",
cleaner.grace,
bound,
settings.database.operation_timeout,
settings.s3.timeout,
)
return EXIT_CONFIG
stop = asyncio.Event()
loop = asyncio.get_running_loop()
for signum in (signal.SIGTERM, signal.SIGINT):
loop.add_signal_handler(signum, stop.set)
# дальше сигналы обрабатывает цикл: текущий шаг доводится до commit или
# отката, новые не начинаются
early_stop.disarm()
db = Db(settings.database)
store = create_object_store(settings.s3, namespace=db.name)
objects = AttachmentObjects(store)
storage = PostgresStorage(db)
cleanup = CleanupService(storage, objects)
reconcile = ReconcileService(storage, objects)
mode = args.command or ("once" if args.once else "service")
code = EXIT_OK
try:
if not (settings.s3.access_key_id and settings.s3.secret_access_key):
log.warning("object storage credentials are empty")
# модели botocore — при старте, сети нет
await store.start()
log.info(
"cleaner started mode=%s interval=%gs grace=%ds live_upload_bound=%.0fs "
"batch=%d reconcile_interval=%ds reconcile_page=%d "
"reconcile_max_changes=%d reconcile_rate=%g db=%s:%d/%s pool=%d "
"s3=%s bucket=%s",
mode,
cleaner.interval,
cleaner.grace,
bound,
cleaner.batch,
cleaner.reconcile_interval,
cleaner.reconcile_page,
cleaner.reconcile_max_changes,
cleaner.reconcile_rate,
settings.database.host,
settings.database.port,
settings.database.name,
settings.database.pool_size,
settings.s3.endpoint,
settings.s3.bucket,
)
if args.command == "reconcile":
result = await _reconcile(
reconcile,
settings,
apply=args.apply,
max_changes=args.max_changes or cleaner.reconcile_max_changes,
strategy=args.strategy,
deep=args.deep,
rate=cleaner.reconcile_rate if args.rate is None else args.rate,
stop=stop,
)
code = EXIT_FAILED if result is None else result.exit_code
else:
code = await _serve(cleanup, reconcile, settings, once=args.once, stop=stop)
finally:
await db.dispose()
await store.close()
log.info("cleaner stopped exit_code=%d", code)
return code
async def _serve(
cleanup: CleanupService,
reconcile: ReconcileService,
settings: Settings,
*,
once: bool,
stop: asyncio.Event,
) -> int:
"""Проходы уборки до сигнала; после прохода — плановая сверка с
исправлением, если подошёл её срок: первая — при старте."""
cleaner = settings.cleaner
loop = asyncio.get_running_loop()
next_reconcile = (
loop.time() if cleaner.reconcile_interval > 0 and not once else None
)
while not stop.is_set():
result = await _clean(cleanup, settings, stop)
if once:
if result is None or result.interrupted_by not in (None, STOPPED):
return EXIT_FAILED
return EXIT_OK
pause = cleaner.interval
if next_reconcile is not None and not stop.is_set():
if loop.time() >= next_reconcile:
# плановая: batch, поверхностная, пределы из настроек
await _reconcile(
reconcile,
settings,
apply=True,
max_changes=cleaner.reconcile_max_changes,
strategy=BATCH,
deep=False,
rate=cleaner.reconcile_rate,
stop=stop,
)
next_reconcile = loop.time() + cleaner.reconcile_interval
pause = min(pause, max(0.0, next_reconcile - loop.time()))
# пауза до следующего прохода или до сигнала
with suppress(TimeoutError):
await asyncio.wait_for(stop.wait(), timeout=pause)
return EXIT_OK
async def _clean(
cleanup: CleanupService, settings: Settings, stop: asyncio.Event
) -> CleanupResult | None:
"""Проход уборки; `None` — непредвиденная ошибка: она в журнале с
traceback, процесс живёт до следующего прохода."""
# порог — один на проход, по часам приложения, как срок сессий
older_than = utc_now() - timedelta(seconds=settings.cleaner.grace)
try:
return await cleanup.clean(
older_than=older_than,
batch=settings.cleaner.batch,
stop_requested=stop.is_set,
)
except Exception:
log.error("cleanup pass failed", exc_info=True)
return None
async def _reconcile(
reconcile: ReconcileService,
settings: Settings,
*,
apply: bool,
max_changes: int,
strategy: str,
deep: bool,
rate: float,
stop: asyncio.Event,
) -> ReconcileResult | None:
"""Проход сверки; `None` — непредвиденная ошибка с traceback."""
older_than = utc_now() - timedelta(seconds=settings.cleaner.grace)
try:
return await reconcile.reconcile(
older_than=older_than,
apply=apply,
max_changes=max_changes,
page_size=settings.cleaner.reconcile_page,
batch=settings.cleaner.batch,
strategy=strategy,
deep=deep,
rate=rate,
stop_requested=stop.is_set,
)
except Exception:
log.error("reconcile pass failed", exc_info=True)
return None
+51
View File
@@ -0,0 +1,51 @@
"""Время сервера: монотонные часы и формат RFC 3339.
`created_at` задаёт порядок истории `(created_at, id)`. Системные часы
могут шагнуть назад (NTP) или выдать одно значение двум записям подряд.
`MonotonicClock` отдаёт строго возрастающее время с шагом не меньше 1 мкс.
Хранилище берёт время у него перед вставкой. Процесс один, event loop
один, а `now()` не содержит `await`: два вызова не перемешаются.
Строгий рост — внутри одного процесса. Транзакции фиксируются не в том
порядке, в каком получили время, поэтому запись с меньшим `created_at`
может стать видимой чуть позже соседней (REPORT.md, «Пагинация»).
"""
from datetime import UTC, datetime, timedelta
# RFC 3339 в UTC: всегда шесть знаков микросекунд и суффикс Z
RFC3339_FORMAT = "%Y-%m-%dT%H:%M:%S.%fZ"
_TICK = timedelta(microseconds=1)
class MonotonicClock:
"""Строго возрастающее aware-время UTC.
Не потокобезопасен: вызывается только из event loop процесса.
"""
def __init__(self) -> None:
self._last: datetime | None = None
def now(self) -> datetime:
current = datetime.now(UTC)
if self._last is not None and current <= self._last:
current = self._last + _TICK
self._last = current
return current
def utc_now() -> datetime:
"""Текущее время UTC без монотонной поправки: для сравнения со сроком."""
return datetime.now(UTC)
def to_rfc3339(value: datetime) -> str:
"""Время для ответа API: `2026-09-01T12:00:00.000000Z`."""
return value.astimezone(UTC).strftime(RFC3339_FORMAT)
def from_rfc3339(value: str) -> datetime:
"""Обратно из `to_rfc3339()`: aware-время UTC с микросекундами."""
return datetime.strptime(value, RFC3339_FORMAT).replace(tzinfo=UTC)
+448
View File
@@ -0,0 +1,448 @@
"""Настройки процесса — только из переменных окружения.
Файлов конфигурации нет. В compose переменные задаёт `environment`
(значения подставляются из `.env`), `make run` передаёт их приложению на
хосте сам; без них действуют значения по умолчанию. Полный список
переменных — AGENTS.md, раздел «Конфигурация».
Пароли PostgreSQL и Valkey и ключи S3 тоже приходят переменными: в
`repr()` настроек их нет, в лог они не пишутся.
"""
import os
import re
import socket
from collections.abc import Mapping
from dataclasses import dataclass, field
from typing import Self
LOG_LEVELS = ("DEBUG", "INFO", "WARNING", "ERROR")
DEFAULT_HOST = "127.0.0.1"
DEFAULT_PORT = 8080
DEFAULT_LOG_LEVEL = "INFO"
DEFAULT_SHUTDOWN_TIMEOUT = 5
# секунды, которые uvicorn держит простаивающее keep-alive соединение.
# Больше timeout http-keep-alive HAProxy (10 с): простаивающее соединение
# LB → реплика закрывает LB, а не реплика (infra/AGENTS.md, «Цепочка
# таймаутов»)
DEFAULT_KEEP_ALIVE = 60
# контракт: SESSION_TTL_SECONDS, по умолчанию 3600
DEFAULT_SESSION_TTL = 3600
# контракт: результат отправки по ключу хранится не меньше 24 ч
DEFAULT_IDEMPOTENCY_TTL = 24 * 3600
# одновременных хэшей Argon2id: каждый берёт 64 MiB памяти
DEFAULT_KDF_CONCURRENCY = 4
# срок сессии и ключа не больше 30 суток: длиннее учебному стенду не нужно
MAX_SESSION_TTL = 30 * 24 * 3600
# X-Instance-Id: в compose это hostname контейнера (начало его ID)
_INSTANCE_ID = re.compile(r"[A-Za-z0-9._-]{1,64}")
# имя bucket S3: строчные буквы, цифры, точка и дефис, 3–63 символа
_BUCKET = re.compile(r"[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]")
# адрес S3: схема http(s), хост и необязательный порт, без пути
_ENDPOINT = re.compile(r"https?://[A-Za-z0-9.-]+(:[0-9]{1,5})?")
class ConfigError(ValueError):
"""Переменная окружения задана, но её значение неверно."""
def _text(env: Mapping[str, str], name: str, default: str) -> str:
value = env.get(name, "").strip()
return value or default
def _int(env: Mapping[str, str], name: str, default: int, low: int, high: int) -> int:
raw = env.get(name, "").strip()
if not raw:
return default
try:
value = int(raw)
except ValueError:
raise ConfigError(f"{name} must be an integer, got {raw!r}") from None
if not low <= value <= high:
raise ConfigError(f"{name} must be within {low}..{high}, got {value}")
return value
def _instance_id(env: Mapping[str, str]) -> str:
"""`APP_INSTANCE_ID` или hostname: стабилен, пока жив процесс.
В контейнере hostname — короткий ID контейнера: по нему
`scripts/stop-one.sh` находит реплику, ответившую тесту.
"""
raw = env.get("APP_INSTANCE_ID", "").strip()
if not raw:
return socket.gethostname() or "local"
if not _INSTANCE_ID.fullmatch(raw):
raise ConfigError(
f"APP_INSTANCE_ID must match {_INSTANCE_ID.pattern}, got {raw!r}",
)
return raw
def _float(
env: Mapping[str, str],
name: str,
default: float,
low: float,
high: float,
) -> float:
raw = env.get(name, "").strip()
if not raw:
return default
try:
value = float(raw)
except ValueError:
raise ConfigError(f"{name} must be a number, got {raw!r}") from None
if not low <= value <= high:
raise ConfigError(f"{name} must be within {low}..{high}, got {value}")
return value
@dataclass(frozen=True, slots=True)
class Database:
"""Подключение к PostgreSQL, пул и сроки (переменные `DB_*`)."""
host: str = "127.0.0.1"
port: int = 5432
name: str = "messenger"
user: str = "messenger"
password: str = field(default="", repr=False)
# соединений в пуле и сверх него: пул считается на один процесс
pool_size: int = 10
pool_overflow: int = 5
# секунды ожидания свободного соединения пула
pool_timeout: float = 5.0
# секунды на установку соединения
connect_timeout: float = 3.0
# серверный statement_timeout, мс; 0 — без ограничения
statement_timeout_ms: int = 5000
# секунды на одну операцию хранилища целиком: зависший сервер или
# обрыв сети, где серверный таймаут не сработает
operation_timeout: float = 6.0
@classmethod
def from_env(cls, env: Mapping[str, str]) -> Self:
# у dataclass со slots атрибут класса — дескриптор, не значение:
# значения по умолчанию берутся у экземпляра
default = cls()
return cls(
host=_text(env, "DB_HOST", default.host),
port=_int(env, "DB_PORT", default.port, 1, 65535),
name=_text(env, "DB_NAME", default.name),
user=_text(env, "DB_USER", default.user),
password=env.get("DB_PASSWORD", ""),
pool_size=_int(env, "DB_POOL_SIZE", default.pool_size, 1, 100),
pool_overflow=_int(
env,
"DB_POOL_OVERFLOW",
default.pool_overflow,
0,
100,
),
pool_timeout=_float(
env,
"DB_POOL_TIMEOUT",
default.pool_timeout,
0.1,
60,
),
connect_timeout=_float(
env,
"DB_CONNECT_TIMEOUT",
default.connect_timeout,
0.1,
60,
),
statement_timeout_ms=_int(
env,
"DB_STATEMENT_TIMEOUT_MS",
default.statement_timeout_ms,
0,
600_000,
),
operation_timeout=_float(
env,
"DB_OPERATION_TIMEOUT",
default.operation_timeout,
0.1,
120,
),
)
@dataclass(frozen=True, slots=True)
class Cache:
"""Подключение к Valkey (кэш карточек чатов, переменные `CACHE_*`)."""
host: str = "127.0.0.1"
port: int = 6379
password: str = field(default="", repr=False)
# секунды на всю команду: ожидание пула, соединение, повтор, ответ;
# дольше — запрос идёт в PostgreSQL
timeout: float = 0.2
# секунды, на которые кэш пропускается после отказа Valkey
retry_after: float = 5.0
# секунды жизни карточки чата в кэше
chat_ttl: int = 3600
# соединений в пуле клиента
max_connections: int = 10
@classmethod
def from_env(cls, env: Mapping[str, str]) -> Self:
default = cls()
return cls(
host=_text(env, "CACHE_HOST", default.host),
port=_int(env, "CACHE_PORT", default.port, 1, 65535),
password=env.get("CACHE_PASSWORD", ""),
timeout=_float(env, "CACHE_TIMEOUT", default.timeout, 0.01, 10),
retry_after=_float(
env,
"CACHE_RETRY_AFTER",
default.retry_after,
0.1,
600,
),
chat_ttl=_int(env, "CACHE_CHAT_TTL", default.chat_ttl, 1, 86_400),
max_connections=_int(
env,
"CACHE_MAX_CONNECTIONS",
default.max_connections,
1,
1000,
),
)
def _matching(
env: Mapping[str, str], name: str, default: str, pattern: re.Pattern[str]
) -> str:
value = _text(env, name, default)
if not pattern.fullmatch(value):
raise ConfigError(f"{name} must match {pattern.pattern}, got {value!r}")
return value
@dataclass(frozen=True, slots=True)
class ObjectStorage:
"""S3 (SeaweedFS): байты вложений (переменные `S3_*`).
Ключи — пользователя S3 этого процесса: у реплик API — права на
объекты своего bucket, у уборщика — чтение, удаление и список по
префиксу вложений (infra/AGENTS.md, «S3»). Административной пары S3
у приложения нет.
"""
endpoint: str = "http://127.0.0.1:8334"
bucket: str = "messenger-attachments"
# регион подписи SigV4; SeaweedFS берёт его из запроса
region: str = "us-east-1"
access_key_id: str = field(default="", repr=False)
secret_access_key: str = field(default="", repr=False)
# секунды на вызов целиком и на каждый блок чтения тела объекта;
# меньше timeout server HAProxy (10 с)
timeout: float = 5.0
# секунды на установку соединения
connect_timeout: float = 1.0
# соединений в пуле клиента
max_connections: int = 10
@classmethod
def from_env(cls, env: Mapping[str, str]) -> Self:
default = cls()
return cls(
endpoint=_matching(env, "S3_ENDPOINT", default.endpoint, _ENDPOINT),
bucket=_matching(env, "S3_BUCKET", default.bucket, _BUCKET),
region=_text(env, "S3_REGION", default.region),
access_key_id=env.get("S3_ACCESS_KEY_ID", ""),
secret_access_key=env.get("S3_SECRET_ACCESS_KEY", ""),
timeout=_float(env, "S3_TIMEOUT", default.timeout, 0.1, 60),
connect_timeout=_float(
env,
"S3_CONNECT_TIMEOUT",
default.connect_timeout,
0.1,
30,
),
max_connections=_int(
env,
"S3_MAX_CONNECTIONS",
default.max_connections,
1,
1000,
),
)
@dataclass(frozen=True, slots=True)
class Uploads:
"""Места загрузок вложений процесса API (переменные `UPLOAD_*`).
Память загрузок реплики ограничена числом мест, а не числом клиентов:
одна загрузка держит одно тело (до 10 MiB). Значения — настройки, а не
константы: у установок разный лимит памяти, а профилю `uploads` стенда
`bench/` нужен вариант «без лимита».
"""
# загрузок одновременно на процесс
max_concurrent: int = 4
# ещё столько ждут места по порядку прихода; больше — сразу 429
max_waiting: int = 16
# секунды ожидания места; дольше — 429
wait_timeout: float = 5.0
# секунды на всё тело с момента, как загрузка заняла место; дольше — 400
body_timeout: float = 30.0
@classmethod
def from_env(cls, env: Mapping[str, str]) -> Self:
default = cls()
return cls(
max_concurrent=_int(
env,
"UPLOAD_MAX_CONCURRENT",
default.max_concurrent,
1,
1000,
),
max_waiting=_int(env, "UPLOAD_MAX_WAITING", default.max_waiting, 0, 1000),
wait_timeout=_float(
env, "UPLOAD_WAIT_TIMEOUT", default.wait_timeout, 0.1, 60
),
body_timeout=_float(
env, "UPLOAD_BODY_TIMEOUT", default.body_timeout, 1, 300
),
)
@dataclass(frozen=True, slots=True)
class Cleaner:
"""Уборщик незавершённых загрузок и сверка bucket и БД (`CLEANER_*`,
`RECONCILE_*`). Читает только процесс `python -m src.cleaner`."""
# секунды между проходами уборки
interval: float = 60.0
# секунды, после которых строка pending и объект без строки считаются
# брошенными; больше границы живой загрузки (уборщик проверяет при старте)
grace: int = 900
# строк за одну выборку кандидатов
batch: int = 100
# секунды между плановыми сверками; 0 — без плановой сверки
reconcile_interval: int = 3600
# ключей на страницу списка S3 (ListObjectsV2 отдаёт не больше 1000)
reconcile_page: int = 1000
# больше изменений за проход — ни одного и код 3
reconcile_max_changes: int = 100
# объектов S3 в секунду в среднем за проход; 0 — без предела
reconcile_rate: float = 2000.0
@classmethod
def from_env(cls, env: Mapping[str, str]) -> Self:
default = cls()
return cls(
interval=_float(env, "CLEANER_INTERVAL", default.interval, 0.1, 3600),
grace=_int(env, "CLEANER_GRACE", default.grace, 1, 7 * 86_400),
batch=_int(env, "CLEANER_BATCH", default.batch, 1, 1000),
reconcile_interval=_int(
env,
"RECONCILE_INTERVAL",
default.reconcile_interval,
0,
7 * 86_400,
),
reconcile_page=_int(
env, "RECONCILE_PAGE_SIZE", default.reconcile_page, 1, 1000
),
reconcile_max_changes=_int(
env,
"RECONCILE_MAX_CHANGES",
default.reconcile_max_changes,
1,
1_000_000,
),
reconcile_rate=_float(
env, "RECONCILE_RATE", default.reconcile_rate, 0, 1_000_000
),
)
@dataclass(frozen=True, slots=True)
class Settings:
# адрес прослушивания: локально только loopback, в образе ENV APP_HOST=0.0.0.0
host: str = DEFAULT_HOST
port: int = DEFAULT_PORT
log_level: str = DEFAULT_LOG_LEVEL
# секунды, которые uvicorn дорабатывает начатые запросы после SIGTERM;
# docker stop шлёт SIGKILL через 10 с, поэтому не больше 9
shutdown_timeout: int = DEFAULT_SHUTDOWN_TIMEOUT
keep_alive: int = DEFAULT_KEEP_ALIVE
# X-Instance-Id этого процесса; from_env берёт APP_INSTANCE_ID или
# hostname
instance_id: str = "local"
# секунды жизни сессии с момента входа; запросы и рестарт не продлевают
session_ttl: int = DEFAULT_SESSION_TTL
# секунды, в течение которых повтор с тем же Idempotency-Key отдаёт
# прежний результат; позже ключ можно занять заново
idempotency_ttl: int = DEFAULT_IDEMPOTENCY_TTL
kdf_concurrency: int = DEFAULT_KDF_CONCURRENCY
database: Database = Database()
cache: Cache = Cache()
s3: ObjectStorage = ObjectStorage()
uploads: Uploads = Uploads()
cleaner: Cleaner = Cleaner()
@classmethod
def from_env(cls, env: Mapping[str, str] | None = None) -> Self:
"""Настройки из окружения; неверное значение — `ConfigError`."""
env = os.environ if env is None else env
log_level = _text(env, "LOG_LEVEL", DEFAULT_LOG_LEVEL).upper()
if log_level not in LOG_LEVELS:
raise ConfigError(
f"LOG_LEVEL must be one of {', '.join(LOG_LEVELS)}, got {log_level!r}",
)
return cls(
host=_text(env, "APP_HOST", DEFAULT_HOST),
port=_int(env, "APP_PORT", DEFAULT_PORT, 1, 65535),
log_level=log_level,
shutdown_timeout=_int(
env,
"SHUTDOWN_TIMEOUT",
DEFAULT_SHUTDOWN_TIMEOUT,
1,
9,
),
keep_alive=_int(
env,
"KEEP_ALIVE_TIMEOUT",
DEFAULT_KEEP_ALIVE,
1,
3600,
),
instance_id=_instance_id(env),
session_ttl=_int(
env,
"SESSION_TTL_SECONDS",
DEFAULT_SESSION_TTL,
1,
MAX_SESSION_TTL,
),
idempotency_ttl=_int(
env,
"IDEMPOTENCY_TTL_SECONDS",
DEFAULT_IDEMPOTENCY_TTL,
1,
MAX_SESSION_TTL,
),
kdf_concurrency=_int(
env,
"KDF_CONCURRENCY",
DEFAULT_KDF_CONCURRENCY,
1,
64,
),
database=Database.from_env(env),
cache=Cache.from_env(env),
s3=ObjectStorage.from_env(env),
uploads=Uploads.from_env(env),
cleaner=Cleaner.from_env(env),
)
+92
View File
@@ -0,0 +1,92 @@
"""Константы, одинаковые на всех установках.
Лимиты взяты из contracts/openapi.json и contracts/README.md. Это часть
контракта: значения не меняются и не выносятся в настройки.
"""
# пути
API_PREFIX = "/api/v1"
HEALTH_LIVE_PATH = "/health/live"
HEALTH_READY_PATH = "/health/ready"
HEALTH_PATHS = frozenset({HEALTH_LIVE_PATH, HEALTH_READY_PATH})
SESSIONS_PATH = f"{API_PREFIX}/auth/sessions"
# заголовки
REQUEST_ID_HEADER = "X-Request-Id"
AUTHORIZATION_HEADER = "Authorization"
# с лабы 3: какая реплика ответила (каждый ответ API) и ключ повтора
# отправки сообщения
INSTANCE_ID_HEADER = "X-Instance-Id"
IDEMPOTENCY_KEY_HEADER = "Idempotency-Key"
# пользователь
USERNAME_PATTERN = r"^[a-z0-9_]{3,32}$"
DISPLAY_NAME_MAX_LENGTH = 100
# пароль: 12–128 Unicode code points, хэшируется целиком как UTF-8
PASSWORD_MIN_LENGTH = 12
PASSWORD_MAX_LENGTH = 128
# начало строки Argon2id: CHECK в БД не даёт записать пароль иначе
PASSWORD_HASH_PREFIX = "$argon2id$"
# сессия
# байты случайности токена: 256 бит, 43 символа base64url
SESSION_TOKEN_BYTES = 32
# в БД хранится SHA-256 токена, а не токен
TOKEN_HASH_BYTES = 32
# realm в WWW-Authenticate у ответов 401
AUTH_REALM = "messenger"
# чат
CHAT_TITLE_MAX_LENGTH = 100
CHAT_MEMBERS_MAX = 100
# сообщение
MESSAGE_TEXT_MAX_LENGTH = 4000
# с лабы 4: до 10 разных вложений этого чата
MESSAGE_ATTACHMENTS_MAX = 10
# вложение (лаба 4). Лимиты — константы контракта, а не настройки:
# MAX_UPLOAD_BYTES и MAX_IMAGE_PIXELS из .env.example их не меняют
ATTACHMENT_MAX_BYTES = 10 * 1024 * 1024
ATTACHMENT_MAX_PIXELS = 40_000_000
ATTACHMENT_FILENAME_MAX_LENGTH = 255
# Content-Type загрузки и скачивания: тип без параметров
ATTACHMENT_TYPES = ("image/png", "image/jpeg")
ATTACHMENT_PENDING = "pending"
ATTACHMENT_READY = "ready"
# в БД хранится SHA-256 оригинала (наружу — hex в нижнем регистре)
SHA256_BYTES = 32
# ключ объекта: <имя базы>/attachments/<id>/original. Имя базы разделяет
# объекты рабочей и тестовых баз на одном S3, как ключи кэша
S3_KEY_ATTACHMENTS = "attachments"
S3_KEY_ORIGINAL = "original"
# секунды простоя, после которых клиент S3 закрывает соединение сам: раньше
# шлюза SeaweedFS
S3_KEEPALIVE_TIMEOUT = 15
# блок отдачи оригинала клиенту
DOWNLOAD_CHUNK_BYTES = 64 * 1024
# Retry-After у 429 «места загрузки заняты», секунды
UPLOAD_RETRY_AFTER = 1
# ключ идемпотентности отправки (лаба 3): ASCII, 1–128 символов целиком
IDEMPOTENCY_KEY_PATTERN = r"^[A-Za-z0-9._:-]{1,128}$"
# в БД хранится SHA-256 канонического тела запроса, а не тело
REQUEST_HASH_BYTES = 32
# пагинация
PAGE_LIMIT_MIN = 1
PAGE_LIMIT_MAX = 100
PAGE_LIMIT_DEFAULT = 50
# PostgreSQL
# имя соединений сервиса в pg_stat_activity
DB_APPLICATION_NAME = "mtusi-messenger"
# секунды на SELECT 1 в /health/ready
READINESS_TIMEOUT = 2.0
# секунды на мягкое закрытие соединения; дальше asyncpg обрывает его
DB_CLOSE_TIMEOUT = 2.0
# кэш (Valkey)
# начало ключей; v1 — формат значения: новый формат — v2, старые ключи
# тогда просто не читаются
CACHE_KEY_PREFIX = "messenger:v1"
+185
View File
@@ -0,0 +1,185 @@
"""PostgreSQL: engine с ограниченным пулом, срок операции, отказ → 503.
`Db` — то, через что хранилище ходит в базу. Запись — явная транзакция
`transaction()`: commit при выходе, откат при ошибке. Одиночный SELECT
читает через `read()` в AUTOCOMMIT. Вся операция ограничена
`DB_OPERATION_TIMEOUT`: зависший сервер не держит запрос бесконечно.
Ошибки, которые значат «базы нет или она не отвечает», превращаются в
`Unavailable` (503) со строкой `warning` в журнале; остальные (нарушение
ограничения, синтаксис) идут дальше как есть: это дефект или доменная
ошибка, а не отказ хранилища.
Engine открывает соединения лениво: без PostgreSQL процесс стартует,
а `/health/ready` отвечает 503.
"""
import asyncio
from collections.abc import AsyncIterator
from contextlib import asynccontextmanager
import asyncpg
from sqlalchemy import URL, text
from sqlalchemy import exc as sa_exc
from sqlalchemy.ext.asyncio import AsyncConnection, AsyncEngine, create_async_engine
from src.config import Database as DatabaseSettings
from src.constants import DB_APPLICATION_NAME, DB_CLOSE_TIMEOUT, READINESS_TIMEOUT
from src.errors import Unavailable
from src.log import get_logger
log = get_logger(__name__)
# SQLSTATE «база недоступна»: класс 08 — ошибки соединения, 57014 —
# сработал statement_timeout, 57P01–57P03 — сервер останавливается или
# ещё не принимает подключения
UNAVAILABLE_SQLSTATES = ("08", "57014", "57P01", "57P02", "57P03")
# длина текста ошибки в журнале: одна строка, без простыни SQLAlchemy
_ERROR_TEXT_LIMIT = 300
class BoundedCloseConnection(asyncpg.Connection):
"""Соединение asyncpg, мягкое закрытие которого ограничено сроком.
Прерванный по сроку запрос SQLAlchemy закрывает соединение мягко, а
asyncpg при этом ждёт ответа сервера без ограничения: замёрзший
PostgreSQL держал бы запрос до разморозки. Здесь закрытие ограничено
`DB_CLOSE_TIMEOUT`, дальше asyncpg обрывает соединение.
"""
# сигнатура — как у asyncpg.Connection.close: SQLAlchemy зовёт её так
async def close(self, *, timeout: float | None = None) -> None: # noqa: ASYNC109
await asyncio.wait_for(
super().close(timeout=timeout), timeout or DB_CLOSE_TIMEOUT
)
def database_url(settings: DatabaseSettings) -> URL:
"""URL драйвера asyncpg; пароль экранирует `URL.create`, строку не собираем."""
return URL.create(
"postgresql+asyncpg",
username=settings.user,
password=settings.password,
host=settings.host,
port=settings.port,
database=settings.name,
)
def create_engine(settings: DatabaseSettings) -> AsyncEngine:
"""Engine с ограниченным пулом и таймаутами из настроек."""
return create_async_engine(
database_url(settings),
pool_size=settings.pool_size,
max_overflow=settings.pool_overflow,
pool_timeout=settings.pool_timeout,
# одиночные SELECT не требуют отдельных BEGIN/COMMIT; запись ниже
# получает READ COMMITTED через engine с тем же пулом
isolation_level="AUTOCOMMIT",
skip_autocommit_rollback=True,
# после рестарта PostgreSQL соединения пула мертвы: проверка при
# выдаче не даёт первому запросу получить ошибку
pool_pre_ping=True,
# текст ошибки драйвера уходит в журнал: без этого в нём были бы
# параметры SQL — тексты сообщений, хэши паролей и токенов
hide_parameters=True,
connect_args={
"timeout": settings.connect_timeout,
# command_timeout asyncpg не задан: на зависшем сервере он
# отменяет запрос через новое соединение и ждёт без срока
"connection_class": BoundedCloseConnection,
"server_settings": {
"application_name": DB_APPLICATION_NAME,
"statement_timeout": str(settings.statement_timeout_ms),
},
},
)
def is_unavailable(error: BaseException) -> bool:
"""Ошибка значит «PostgreSQL недоступен» (→ 503), а не дефект (→ 500).
Остановленный сервер — `ConnectionRefusedError`, неразрешимое имя —
`socket.gaierror`, срок операции — `TimeoutError`: всё это `OSError`.
Пул исчерпан — `sqlalchemy.exc.TimeoutError`. Оборванное соединение и
statement_timeout — `DBAPIError` с признаком или SQLSTATE.
"""
if isinstance(error, OSError | sa_exc.TimeoutError):
return True
if isinstance(error, sa_exc.DBAPIError):
if error.connection_invalidated:
return True
sqlstate = getattr(error.orig, "sqlstate", None) or ""
return sqlstate.startswith(UNAVAILABLE_SQLSTATES)
return False
def _one_line(error: BaseException) -> str:
# TimeoutError от asyncio.timeout без текста — тогда repr
raw = " ".join(str(error).split()) or repr(error)
return raw[:_ERROR_TEXT_LIMIT]
class Db:
"""Engine процесса и границы транзакций хранилища."""
def __init__(self, settings: DatabaseSettings) -> None:
# имя базы: им же разделяются ключи кэша разных баз на одном Valkey
self.name = settings.name
self.engine = create_engine(settings)
# производный engine разделяет пул; запись всегда в транзакции
self._write_engine = self.engine.execution_options(
isolation_level="READ COMMITTED"
)
self._operation_timeout = settings.operation_timeout
@asynccontextmanager
async def _operation(self) -> AsyncIterator[None]:
"""Срок и перевод отказов общие для чтения и записи.
На сроке asyncio отменяет ожидание драйвера: SQLAlchemy считает
такое соединение испорченным и не возвращает его в пул, а его
закрытие ограничено `BoundedCloseConnection`. Поэтому замёрзший
сервер даёт 503 через `DB_OPERATION_TIMEOUT` + `DB_CLOSE_TIMEOUT`.
"""
try:
async with asyncio.timeout(self._operation_timeout):
yield
except Exception as exc:
if not is_unavailable(exc):
raise
log.warning(
"database unavailable error_type=%s error=%s",
type(exc).__name__,
_one_line(exc),
)
raise Unavailable from exc
@asynccontextmanager
async def transaction(self) -> AsyncIterator[AsyncConnection]:
"""Атомарная запись: commit при выходе, rollback при исключении."""
async with self._operation(), self._write_engine.begin() as connection:
yield connection
@asynccontextmanager
async def read(self) -> AsyncIterator[AsyncConnection]:
"""Один SELECT в AUTOCOMMIT; составные операции требуют transaction."""
async with self._operation(), self.engine.connect() as connection:
yield connection
async def ping(self) -> None:
"""`SELECT 1` за `READINESS_TIMEOUT`; иначе `Unavailable`.
Не логирует: healthcheck спрашивает каждые несколько секунд.
Любая ошибка — 503: готовность не отвечает 500.
"""
try:
async with (
asyncio.timeout(READINESS_TIMEOUT),
self.engine.connect() as connection,
):
await connection.execute(text("SELECT 1"))
except Exception as exc:
raise Unavailable from exc
async def dispose(self) -> None:
await self.engine.dispose()
+117
View File
@@ -0,0 +1,117 @@
"""Доменные записи. Неизменяемые: хранилище отдаёт их наружу без копирования.
Пароль, его хэш и токен сессии в `User` не входят: хэш живёт только в
`Credentials` (вход), токен — только в `IssuedSession` (ответ на вход).
"""
from dataclasses import dataclass, field
from datetime import datetime
from uuid import UUID
@dataclass(frozen=True, slots=True)
class User:
id: UUID
username: str
display_name: str
created_at: datetime
@dataclass(frozen=True, slots=True)
class Credentials:
"""Пользователь и хэш его пароля: только для проверки при входе."""
user: User
password_hash: str = field(repr=False)
@dataclass(frozen=True, slots=True)
class Session:
"""Серверная сессия входа. Срок фиксируется при создании."""
id: UUID
user_id: UUID
expires_at: datetime
created_at: datetime
@dataclass(frozen=True, slots=True)
class IssuedSession:
"""Ответ на вход: токен отдаётся клиенту один раз и нигде не хранится."""
token: str = field(repr=False)
expires_at: datetime
user: User
@dataclass(frozen=True, slots=True)
class Identity:
"""Кто прислал запрос: действующая сессия и её владелец."""
session_id: UUID
user: User
@dataclass(frozen=True, slots=True)
class Chat:
id: UUID
title: str
# в порядке, переданном при создании
member_ids: tuple[UUID, ...]
created_at: datetime
@dataclass(frozen=True, slots=True)
class Message:
id: UUID
chat_id: UUID
sender_id: UUID
text: str
created_at: datetime
# с лабы 4: вложения этого чата в порядке отправки
attachment_ids: tuple[UUID, ...] = ()
@dataclass(frozen=True, slots=True)
class Attachment:
"""Метаданные вложения; байты — объект `object_key` в S3.
`status`: `pending` — строка записана до объекта, загрузка не
закончена (наружу не видна); `ready` — объект записан, 201 отдан.
`lost_at` — сверка подтвердила, что объекта готового вложения нет или
он другого размера. `filename` только показывается: ни ключ, ни путь из
него не строятся.
"""
id: UUID
chat_id: UUID
owner_id: UUID
filename: str
content_type: str
size_bytes: int
sha256: bytes
object_key: str
status: str
created_at: datetime
updated_at: datetime
lost_at: datetime | None = None
@dataclass(frozen=True, slots=True)
class SentMessage:
"""Итог отправки с ключом: новое сообщение или сохранённое прежнее.
`replayed` — ответ на повтор того же тела; клиенту оба случая
отдаются одинаково (201 и то же `Message`), флаг нужен журналу.
"""
message: Message
replayed: bool
@dataclass(frozen=True, slots=True)
class Page[T]:
"""Страница списка в порядке `(created_at, id)`."""
items: tuple[T, ...]
next_cursor: str | None
+63
View File
@@ -0,0 +1,63 @@
"""Остановка до старта сервера: SIGTERM и SIGINT во время импорта.
В контейнере `python -m src` — PID 1, а ядро не доставляет PID 1 сигнал,
для которого нет обработчика. Пока импортируется приложение (почти весь
старт, сотни миллисекунд при лимите в 1 CPU), обработчик uvicorn ещё не
стоит, и `docker stop` стартующей реплики ждал бы `stop_grace_period`
(10 с) и кончался SIGKILL. Это бьёт по поочерёдной замене: сбой на
середине убирает только что запущенную реплику (`scripts/rolling-update.sh`).
`install()` ставится первым делом в `src/__main__.py`, до импорта
приложения: сигнал до старта сервера пишет одну строку журнала и
завершает процесс с кодом 0 (запросов и соединений ещё нет).
`disarm()` — первая строка lifespan: дальше сигналы обрабатывает
uvicorn. После остановки сервера uvicorn возвращает этот обработчик и
повторяет пойманный сигнал — снятый обработчик его игнорирует, и
процесс выходит штатно, с кодом 0.
Только стандартная библиотека: модуль работает до настройки журнала и
до импорта `src.config`. Строка — в формате `src/log.py`, без rid.
"""
import contextlib
import os
import signal
import socket
import time
from types import FrameType
_armed = False
def _line(signum: int) -> bytes:
now = time.time()
stamp = time.strftime("%Y-%m-%dT%H:%M:%S", time.gmtime(now))
millis = int(now % 1 * 1000)
instance = os.environ.get("APP_INSTANCE_ID", "").strip() or socket.gethostname()
return (
f"{stamp}.{millis:03d}Z INFO src.early_stop [rid=-] "
f"stopped before startup signal={signal.Signals(signum).name} "
f"instance={instance}\n"
).encode()
def _stop(signum: int, _frame: FrameType | None) -> None:
if not _armed:
return
# ошибка записи выходу не мешает
with contextlib.suppress(OSError):
os.write(1, _line(signum))
os._exit(0)
def install() -> None:
global _armed
_armed = True
signal.signal(signal.SIGTERM, _stop)
signal.signal(signal.SIGINT, _stop)
def disarm() -> None:
"""Сервер стартовал: дальше сигналы — забота uvicorn."""
global _armed
_armed = False
+171
View File
@@ -0,0 +1,171 @@
"""Ошибки приложения. Каждая сама знает свой HTTP-статус и `code` контракта.
Сервисы, хранилище и пагинация бросают только их (не `HTTPException`).
В ответ `{"error": {...}}` их переводит один обработчик в
src/api/handlers.py. Текст ошибки уходит клиенту в `error.message`:
по-английски, без деталей реализации и без признаков существования
чужого объекта. У ответов 401 есть ещё `WWW-Authenticate`: вызов той
схемы, которой клиенту повторить запрос (`challenge`).
"""
from src.constants import AUTH_REALM, UPLOAD_RETRY_AFTER
class AppError(Exception):
status_code: int = 400
code: str = "invalid_request"
default_message: str = "Invalid request"
# значение WWW-Authenticate; только у 401
challenge: str | None = None
# секунды Retry-After; только у 429
retry_after: int | None = None
def __init__(self, message: str | None = None) -> None:
super().__init__(message or self.default_message)
class InvalidRequest(AppError):
"""Запрос синтаксически верен, но нарушает правила контракта."""
class InvalidMembers(InvalidRequest):
"""Дубликаты в member_ids, неизвестный участник или нет вызывающего."""
default_message = "Invalid chat members"
class InvalidCursor(InvalidRequest):
"""Курсор повреждён или выдан для другого списка."""
default_message = "Invalid cursor"
class InvalidFilename(InvalidRequest):
"""`filename` загрузки не в строгом UTF-8 (остальное проверяет схема)."""
default_message = "Invalid filename"
class UploadInterrupted(InvalidRequest):
"""Клиент оборвал соединение посреди тела загрузки."""
default_message = "Upload body was interrupted"
class UploadTimedOut(InvalidRequest):
"""Тело загрузки не пришло за `UPLOAD_BODY_TIMEOUT`."""
default_message = "Upload body was not received in time"
class InvalidCredentials(AppError):
"""Вход отклонён: неверный пароль, неизвестный username или битый Basic.
Все причины — один ответ: по нему не узнать, есть ли пользователь.
"""
status_code = 401
code = "unauthorized"
default_message = "Invalid username or password"
challenge = f'Basic realm="{AUTH_REALM}", charset="UTF-8"'
class Unauthorized(AppError):
"""Нет Bearer-токена, он неизвестен, истёк или отозван."""
status_code = 401
code = "unauthorized"
default_message = "Valid bearer token is required"
challenge = f'Bearer realm="{AUTH_REALM}"'
class NotFound(AppError):
"""Объекта нет или он чужой: оба случая неразличимы для клиента."""
status_code = 404
code = "not_found"
default_message = "Not found"
class UsernameTaken(AppError):
status_code = 409
code = "conflict"
default_message = "Username is already taken"
class IdempotencyConflict(AppError):
"""Тот же `Idempotency-Key` уже принят с другим телом сообщения.
Ключ в текст не попадает: его выбирает клиент.
"""
status_code = 409
code = "conflict"
default_message = "Idempotency key was already used with a different request"
class PayloadTooLarge(AppError):
"""Тело больше 10 MiB или изображение больше 40 млн пикселей."""
status_code = 413
code = "payload_too_large"
default_message = "Attachment exceeds the size limit"
class UnsupportedMediaType(AppError):
"""Не PNG и не JPEG: `Content-Type`, сигнатура, подмена или повреждение."""
status_code = 415
code = "unsupported_media_type"
default_message = "Only intact PNG and JPEG images are accepted"
class UploadsBusy(AppError):
"""Места загрузок процесса заняты: очередь полна или срок ожидания вышел.
Ни строки, ни объекта у такой загрузки нет; повтор — после
`Retry-After`, через LB он уходит на следующую реплику.
"""
status_code = 429
code = "rate_limited"
default_message = "Too many uploads in progress, retry later"
retry_after = UPLOAD_RETRY_AFTER
class ContentMissing(AppError):
"""У готового вложения нет объекта в S3 или он другого размера.
Дефект согласованности хранилищ, а не ошибка клиента: 500, причина —
строка `error` в журнале. Пометку «потерян» ставит сверка.
"""
status_code = 500
code = "internal_error"
default_message = "Internal server error"
class Unavailable(AppError):
"""PostgreSQL недоступен или не ответил вовремя; приложение не готово.
Ограниченная ошибка вместо 500 и никогда не пропуск запроса как
анонимного: недоступность хранилища сессий — не отказ в доступе.
"""
status_code = 503
code = "unavailable"
default_message = "Service is temporarily unavailable"
class OutcomeUnknown(Unavailable):
"""Связь с PostgreSQL оборвалась на COMMIT: изменение могло записаться.
Для клиента — тот же 503. Внутри — сигнал не откатывать побочный
эффект: объект вложения, ставшего `ready`, удалять нельзя.
"""
class ObjectStorageUnavailable(Unavailable):
"""S3 недоступен, не ответил вовремя, отказал в ключах или bucket нет."""
default_message = "Attachment storage is temporarily unavailable"
+25
View File
@@ -0,0 +1,25 @@
"""HEALTHCHECK образа: `python -m src.healthcheck`.
Код выхода 0 — `/health/ready` ответил 200, иначе 1. Только стандартная
библиотека и без импорта приложения: в slim-образе нет curl, а проверка
должна быть дешёвой.
"""
import os
import sys
import urllib.error
import urllib.request
def main() -> int:
port = os.environ.get("APP_PORT", "8080")
url = f"http://127.0.0.1:{port}/health/ready"
try:
with urllib.request.urlopen(url, timeout=2) as response:
return 0 if response.status == 200 else 1
except (urllib.error.URLError, OSError):
return 1
if __name__ == "__main__":
sys.exit(main())
+389
View File
@@ -0,0 +1,389 @@
"""Структурная проверка PNG и JPEG без декодирования пикселей.
Тип — по сигнатуре, размеры — из заголовка до распаковки (IHDR у PNG,
кадр SOF у JPEG): лимит пикселей срабатывает раньше, чем что-то
распаковано. Целостность:
- PNG: IHDR первым и с допустимыми полями, длина и CRC каждого чанка,
нет неизвестных критичных чанков, PLTE на своём месте, IDAT подряд,
поток zlib завершён и распакован ровно в объём по размерам, глубине и
чересстрочности, тип фильтра каждой строки ≤ 4, есть IEND;
- JPEG: маркеры и длины сегментов до EOI, один кадр с ненулевыми
размерами, хотя бы один скан после кадра, EOI есть.
Байты после IEND и EOI допускаются: они часть оригинала (входят в размер
и SHA-256). Искажение внутри сжатых данных скана JPEG не обнаруживается:
у формата нет контрольной суммы — граница названа в REPORT.md.
Память не зависит от числа пикселей: IDAT распаковывается блоками не
больше `_INFLATE_OUT_BYTES` и не дальше ожидаемого объёма плюс байт
(«бомба» отсекается первым лишним байтом), вход подаётся кусками
`_INFLATE_IN_BYTES`. Строки проверяются срезом с шагом длины строки,
конец данных скана JPEG ищет регулярное выражение — оба в C, без цикла
Python по байтам. Только стандартная библиотека; бросает свои исключения,
сервис переводит их в ошибки API (413, 415).
"""
import re
import struct
import zlib
from dataclasses import dataclass
PNG = "image/png"
JPEG = "image/jpeg"
PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
JPEG_SIGNATURE = b"\xff\xd8\xff"
# выход распаковки за один вызов и кусок входа: пик памяти проверки —
# единицы MiB при любом числе пикселей
_INFLATE_OUT_BYTES = 1024 * 1024
_INFLATE_IN_BYTES = 64 * 1024
# предел длины чанка PNG и размера по спецификации: 2^31 - 1
_PNG_MAX_UINT = 2**31 - 1
# допустимая глубина по типу цвета и число каналов
_PNG_DEPTHS: dict[int, frozenset[int]] = {
0: frozenset({1, 2, 4, 8, 16}),
2: frozenset({8, 16}),
3: frozenset({1, 2, 4, 8}),
4: frozenset({8, 16}),
6: frozenset({8, 16}),
}
_PNG_CHANNELS = {0: 1, 2: 3, 3: 1, 4: 2, 6: 4}
_PNG_PALETTE_TYPE = 3
# PLTE запрещён у серых изображений
_PNG_NO_PALETTE_TYPES = frozenset({0, 4})
# проходы Adam7: (x0, y0, dx, dy)
_ADAM7 = (
(0, 0, 8, 8),
(4, 0, 8, 8),
(0, 4, 4, 8),
(2, 0, 4, 4),
(0, 2, 2, 4),
(1, 0, 2, 2),
(0, 1, 1, 2),
)
# типы фильтра строки 0–4: всё, что не они, остаётся после translate
_PNG_FILTER_TYPES = bytes(range(5))
# маркеры кадра: SOF0–3, 5–7, 9–11, 13–15 (C4 — DHT, C8 — JPG, CC — DAC)
_JPEG_SOF = frozenset(
{0xC0, 0xC1, 0xC2, 0xC3, 0xC5, 0xC6, 0xC7} | {0xC9, 0xCA, 0xCB, 0xCD, 0xCE, 0xCF},
)
_JPEG_SOI = 0xD8
_JPEG_EOI = 0xD9
_JPEG_SOS = 0xDA
_JPEG_TEM = 0x01
_JPEG_RST = frozenset(range(0xD0, 0xD8))
# конец данных скана: FF, за которым не 00 (вставка) и не RST0–7
_JPEG_SCAN_END = re.compile(rb"\xff[^\x00\xd0-\xd7]")
class ImageError(ValueError):
"""Изображение не прошло проверку."""
class UnsupportedImage(ImageError):
"""Не PNG и не JPEG."""
class DamagedImage(ImageError):
"""Структура изображения нарушена."""
class TooManyPixels(ImageError):
"""В заголовке больше пикселей, чем допускает лимит."""
@dataclass(frozen=True, slots=True)
class ImageInfo:
content_type: str
width: int
height: int
def inspect_image(data: bytes, *, max_pixels: int) -> ImageInfo:
"""Тип и размеры изображения после проверки структуры.
`UnsupportedImage` — сигнатура не PNG и не JPEG (в том числе пустые
данные), `TooManyPixels` — больше `max_pixels` по заголовку,
`DamagedImage` — нарушена структура.
"""
if data.startswith(PNG_SIGNATURE):
return _inspect_png(data, max_pixels=max_pixels)
if data.startswith(JPEG_SIGNATURE):
return _inspect_jpeg(data, max_pixels=max_pixels)
raise UnsupportedImage("unknown signature")
def _check_pixels(width: int, height: int, *, max_pixels: int) -> None:
if width * height > max_pixels:
raise TooManyPixels("too many pixels")
# --- PNG ---------------------------------------------------------------
@dataclass(frozen=True, slots=True)
class _Segment:
"""Строки одного прохода в распакованном потоке: [start, end), шаг."""
start: int
end: int
stride: int
def _png_segments(
width: int,
height: int,
*,
bits_per_pixel: int,
interlaced: bool,
) -> list[_Segment]:
"""Где в распакованном потоке строки и какой они длины.
Строка — байт фильтра и `ceil(ширина × бит на пиксель / 8)` байт.
Пустой проход Adam7 (ширина или высота 0) строк не даёт.
"""
passes = _ADAM7 if interlaced else ((0, 0, 1, 1),)
segments = []
start = 0
for x0, y0, dx, dy in passes:
pass_width = (width - x0 + dx - 1) // dx if width > x0 else 0
pass_height = (height - y0 + dy - 1) // dy if height > y0 else 0
if not pass_width or not pass_height:
continue
stride = 1 + (pass_width * bits_per_pixel + 7) // 8
end = start + stride * pass_height
segments.append(_Segment(start=start, end=end, stride=stride))
start = end
return segments
class _IdatStream:
"""Поток IDAT: распаковка блоками, объём и типы фильтров строк."""
def __init__(self, segments: list[_Segment]) -> None:
self._segments = segments
self._expected = segments[-1].end
self._inflater = zlib.decompressobj()
self._total = 0
def feed(self, chunk: memoryview) -> None:
for offset in range(0, len(chunk), _INFLATE_IN_BYTES):
if self._inflater.eof:
# остаток после конца потока zlib libpng тоже пропускает
return
self._inflate(chunk[offset : offset + _INFLATE_IN_BYTES])
def finish(self) -> None:
if not self._inflater.eof or self._total != self._expected:
raise DamagedImage("image data size differs")
def _inflate(self, piece: memoryview | bytes) -> None:
while True:
# не дальше ожидаемого объёма: «бомбу» выдаёт первый лишний
# байт, а не блок; больше ожидаемого `_check_rows` не пустит,
# поэтому предел не меньше 1
max_length = min(_INFLATE_OUT_BYTES, self._expected - self._total + 1)
try:
out = self._inflater.decompress(piece, max_length)
except zlib.error as exc:
raise DamagedImage("broken image data stream") from exc
self._check_rows(out)
if self._inflater.eof:
return
piece = self._inflater.unconsumed_tail
# вход кончился, а выход не упёрся в предел — буфер пуст
if not piece and len(out) < max_length:
return
def _check_rows(self, out: bytes) -> None:
begin = self._total
self._total += len(out)
# «бомба» и лишние данные: выход больше, чем дают размеры
if self._total > self._expected:
raise DamagedImage("image data longer than dimensions")
for segment in self._segments:
low = max(begin, segment.start)
high = min(self._total, segment.end)
if low >= high:
continue
# первый байт фильтра в [low, high) по сетке строк прохода
first = low + (-(low - segment.start) % segment.stride)
filters = out[first - begin : high - begin : segment.stride]
if filters.translate(None, _PNG_FILTER_TYPES):
raise DamagedImage("unknown row filter")
def _inspect_png(data: bytes, *, max_pixels: int) -> ImageInfo:
view = memoryview(data)
size = len(data)
pos = len(PNG_SIGNATURE)
width = height = 0
color_type = -1
stream: _IdatStream | None = None
seen_palette = False
idat_state = "before" # before → inside → after
first = True
while True:
if pos + 8 > size:
raise DamagedImage("truncated chunk header")
length, chunk_type = struct.unpack_from(">I4s", data, pos)
if length > _PNG_MAX_UINT or not chunk_type.isalpha():
raise DamagedImage("bad chunk")
body_end = pos + 8 + length
if body_end + 4 > size:
raise DamagedImage("truncated chunk")
(crc,) = struct.unpack_from(">I", data, body_end)
if zlib.crc32(view[pos + 4 : body_end]) != crc:
raise DamagedImage("chunk CRC mismatch")
body = view[pos + 8 : body_end]
pos = body_end + 4
if first:
if chunk_type != b"IHDR":
raise DamagedImage("IHDR is not first")
first = False
width, height, color_type, bits_per_pixel, interlaced = _parse_ihdr(body)
_check_pixels(width, height, max_pixels=max_pixels)
stream = _IdatStream(
_png_segments(
width,
height,
bits_per_pixel=bits_per_pixel,
interlaced=interlaced,
),
)
continue
assert stream is not None
if chunk_type == b"IDAT":
if idat_state == "after":
raise DamagedImage("IDAT chunks are not consecutive")
if color_type == _PNG_PALETTE_TYPE and not seen_palette:
raise DamagedImage("PLTE is missing")
idat_state = "inside"
stream.feed(body)
continue
if idat_state == "inside":
idat_state = "after"
if chunk_type == b"IEND":
if length or idat_state == "before":
raise DamagedImage("bad IEND")
stream.finish()
return ImageInfo(content_type=PNG, width=width, height=height)
if chunk_type == b"PLTE":
if (
seen_palette
or idat_state != "before"
or color_type in _PNG_NO_PALETTE_TYPES
or not length
or length % 3
or length > 3 * 256
):
raise DamagedImage("bad PLTE")
seen_palette = True
continue
if chunk_type == b"IHDR" or chunk_type[0:1].isupper():
# второй IHDR или неизвестный критичный чанк
raise DamagedImage("unexpected critical chunk")
# вспомогательный чанк: проверена только CRC
def _parse_ihdr(body: memoryview) -> tuple[int, int, int, int, bool]:
"""Ширина, высота, тип цвета, бит на пиксель, чересстрочность."""
if len(body) != 13:
raise DamagedImage("bad IHDR length")
width, height, depth, color_type, compression, filtering, interlace = struct.unpack(
">IIBBBBB", body
)
if (
not 0 < width <= _PNG_MAX_UINT
or not 0 < height <= _PNG_MAX_UINT
or depth not in _PNG_DEPTHS.get(color_type, ())
or compression
or filtering
or interlace not in (0, 1)
):
raise DamagedImage("bad IHDR")
bits_per_pixel = depth * _PNG_CHANNELS[color_type]
return width, height, color_type, bits_per_pixel, interlace == 1
# --- JPEG --------------------------------------------------------------
def _inspect_jpeg(data: bytes, *, max_pixels: int) -> ImageInfo:
size = len(data)
pos = 2
frame: tuple[int, int] | None = None
scans = 0
while True:
if pos >= size or data[pos] != 0xFF:
raise DamagedImage("marker expected")
# байты-заполнители FF перед маркером
while pos < size and data[pos] == 0xFF:
pos += 1
if pos >= size:
raise DamagedImage("truncated marker")
marker = data[pos]
pos += 1
if marker == _JPEG_EOI:
if frame is None or not scans:
raise DamagedImage("no frame or scan")
width, height = frame
return ImageInfo(content_type=JPEG, width=width, height=height)
if marker == _JPEG_TEM:
continue
if marker in (0x00, _JPEG_SOI) or marker in _JPEG_RST:
raise DamagedImage("unexpected marker")
if pos + 2 > size:
raise DamagedImage("truncated segment")
(length,) = struct.unpack_from(">H", data, pos)
if length < 2 or pos + length > size:
raise DamagedImage("bad segment length")
segment = data[pos + 2 : pos + length]
pos += length
if marker in _JPEG_SOF:
if frame is not None:
raise DamagedImage("more than one frame")
frame = _parse_sof(segment)
_check_pixels(*frame, max_pixels=max_pixels)
elif marker == _JPEG_SOS:
if frame is None:
raise DamagedImage("scan before frame")
_check_sos(segment)
scans += 1
# данные скана: до первого маркера, кроме вставок и RST
found = _JPEG_SCAN_END.search(data, pos)
if found is None:
raise DamagedImage("scan data is not terminated")
pos = found.start()
def _parse_sof(segment: bytes) -> tuple[int, int]:
"""Ширина и высота кадра; длина сегмента сходится с числом компонент."""
if len(segment) < 6:
raise DamagedImage("bad frame header")
_, height, width, components = struct.unpack_from(">BHHB", segment)
if (
not width
or not height
or not 1 <= components <= 4
or len(segment) != 6 + 3 * components
):
raise DamagedImage("bad frame header")
return width, height
def _check_sos(segment: bytes) -> None:
if not segment:
raise DamagedImage("bad scan header")
components = segment[0]
if not 1 <= components <= 4 or len(segment) != 4 + 2 * components:
raise DamagedImage("bad scan header")
+88
View File
@@ -0,0 +1,88 @@
"""Логи обычным текстом в stdout: одна строка на событие.
Формат строки (перенос — только здесь, в логе строка одна):
2026-09-30T12:00:00.123Z INFO src.http [rid=3f2a...]
POST /api/v1/users -> 201 (1.4 ms)
`rid` — id запроса из contextvar, тот же, что в заголовке `X-Request-Id`
и в теле ошибки; вне запроса (старт, остановка) там `-`. Время — UTC.
Логи uvicorn идут через тот же handler и формат: по строкам «Shutting
down» и «Finished server process» видно, сколько заняла остановка.
"""
import logging
import time
from contextvars import ContextVar
from typing import Any
# ставит только RequestIdMiddleware
request_id_var: ContextVar[str] = ContextVar("request_id", default="-")
LOG_FORMAT = "%(asctime)s %(levelname)-7s %(name)s [rid=%(request_id)s] %(message)s"
class UtcFormatter(logging.Formatter):
"""Время записи в UTC с миллисекундами и суффиксом Z."""
converter = time.gmtime
default_time_format = "%Y-%m-%dT%H:%M:%S"
default_msec_format = "%s.%03dZ"
class RequestIdFilter(logging.Filter):
"""Добавляет в каждую запись поле `request_id` из contextvar."""
def filter(self, record: logging.LogRecord) -> bool:
record.request_id = request_id_var.get()
return True
def get_logger(name: str) -> logging.Logger:
"""Логгер модуля приложения: `get_logger(__name__)`."""
return logging.getLogger(name)
def logging_config(level: str) -> dict[str, Any]:
"""Конфиг для `uvicorn.run(log_config=...)`.
uvicorn применяет его сам через `logging.config.dictConfig` до старта
приложения, поэтому второй настройки логирования в коде нет. Процессы
без uvicorn — миграции (`migrations/env.py`) и уборщик
(`src/cleaner/main.py`) — применяют тот же конфиг сами.
"""
return {
"version": 1,
"disable_existing_loggers": False,
"filters": {"request_id": {"()": RequestIdFilter}},
"formatters": {"text": {"()": UtcFormatter, "fmt": LOG_FORMAT}},
"handlers": {
"stdout": {
"class": "logging.StreamHandler",
"stream": "ext://sys.stdout",
"formatter": "text",
"filters": ["request_id"],
},
},
"loggers": {
"src": {
"level": level,
"handlers": ["stdout"],
"propagate": False,
},
# uvicorn.error наследует handler от uvicorn: свой дал бы дубли
"uvicorn": {"level": "INFO", "handlers": ["stdout"], "propagate": False},
# access-лог пишет RequestIdMiddleware, у uvicorn он выключен
"uvicorn.access": {"level": "WARNING", "handlers": [], "propagate": False},
# сервис migrate: строки «Running upgrade ...» тем же форматом
"alembic": {"level": "INFO", "handlers": ["stdout"], "propagate": False},
# SQL и его параметры в журнал не идут: только предупреждения
"sqlalchemy": {"level": "WARNING"},
# клиент S3 (лаба 4): на DEBUG botocore пишет заголовки запроса
# с подписью — уровень не опускается вместе с LOG_LEVEL
"botocore": {"level": "WARNING"},
"aiobotocore": {"level": "WARNING"},
"aiohttp": {"level": "WARNING"},
},
"root": {"level": "WARNING", "handlers": ["stdout"]},
}
+167
View File
@@ -0,0 +1,167 @@
"""Сборка приложения и запуск uvicorn.
Порядок middleware (снаружи внутрь): ServerErrorMiddleware Starlette →
RequestIdMiddleware → AuthenticationMiddleware (Bearer) →
ExceptionMiddleware → роутер. Последний `add_middleware` оказывается
снаружи, поэтому RequestIdMiddleware добавляется последним: ответ 401
получает тот же id, что и остальные ответы, и попадает в access-лог.
Хранилище собирается здесь: `CachedStorage` (Valkey) поверх
`PostgresStorage`; с лабы 4 — ещё объекты вложений в S3
(`AttachmentObjects` поверх клиента `src/s3.py`) и места загрузок процесса
(`UploadSlots`). Engine и клиенты Valkey и S3 открывают соединения
лениво: без PostgreSQL процесс стартует, а `/health/ready` отвечает 503.
S3 готовность не проверяет: без него недоступны только байты вложений.
С лабы 3 процессов несколько — реплики за HAProxy. В памяти процесса нет
ничего, от чего зависит корректность: сессии, данные и ключи
идемпотентности — в PostgreSQL, Valkey — общий кэш неизменяемых карточек.
Каждый процесс по-прежнему один, с одним event loop: масштабирование —
числом реплик, а не `--workers`.
"""
import os
import sys
from collections.abc import AsyncIterator
from contextlib import asynccontextmanager
import uvicorn
from fastapi import FastAPI
from starlette.middleware.authentication import AuthenticationMiddleware
from src import early_stop
from src.api import handlers
from src.api.identity import BearerBackend, on_auth_error
from src.api.request_id import RequestIdMiddleware
from src.api.routes import api_router, health_router
from src.cache import create_cache
from src.config import ConfigError, Settings
from src.db import Db
from src.log import get_logger, logging_config
from src.passwords import Passwords
from src.s3 import create_object_store
from src.storage import AttachmentObjects, CachedStorage, PostgresStorage
from src.uploads import UploadSlots
log = get_logger(__name__)
@asynccontextmanager
async def lifespan(app: FastAPI) -> AsyncIterator[None]:
# сервер стартовал: сигналы дальше обрабатывает uvicorn
early_stop.disarm()
settings: Settings = app.state.settings
if not settings.database.password:
log.warning("database password is empty")
if not settings.cache.password:
log.warning("cache password is empty")
if not (settings.s3.access_key_id and settings.s3.secret_access_key):
log.warning("object storage credentials are empty")
# модели botocore — при старте, сети нет: первый запрос к S3 не ждёт
await app.state.object_store.start()
# десятки миллисекунд CPU при старте: время ответа на вход с
# неизвестным username ровное с первого запроса
await app.state.passwords.prepare()
# instance — значение X-Instance-Id: по этой строке реплика в журнале
# сопоставляется с ответами, которые видел клиент
uploads = settings.uploads
log.info(
"messenger started instance=%s host=%s port=%d pid=%d db=%s:%d/%s "
"cache=%s:%d s3=%s bucket=%s pool=%d+%d session_ttl=%ds "
"idempotency_ttl=%ds shutdown_timeout=%ds keep_alive=%ds "
"uploads=%d+%d upload_wait=%gs upload_body=%gs s3_timeout=%gs",
settings.instance_id,
settings.host,
settings.port,
os.getpid(),
settings.database.host,
settings.database.port,
settings.database.name,
settings.cache.host,
settings.cache.port,
settings.s3.endpoint,
settings.s3.bucket,
settings.database.pool_size,
settings.database.pool_overflow,
settings.session_ttl,
settings.idempotency_ttl,
settings.shutdown_timeout,
settings.keep_alive,
uploads.max_concurrent,
uploads.max_waiting,
uploads.wait_timeout,
uploads.body_timeout,
settings.s3.timeout,
)
app.state.ready = True
try:
yield
finally:
app.state.ready = False
# сюда uvicorn приходит после SIGTERM, когда начатые запросы
# закончились или вышел SHUTDOWN_TIMEOUT; данные уже в PostgreSQL
await app.state.db.dispose()
await app.state.cache.close()
await app.state.object_store.close()
log.info("messenger stopped instance=%s", settings.instance_id)
def create_app(settings: Settings | None = None) -> FastAPI:
"""Приложение с хранилищем на PostgreSQL и кэшем в Valkey."""
settings = settings or Settings.from_env()
app = FastAPI(
title="MTUSI Messenger — лабораторная 4",
version="1.4.0",
lifespan=lifespan,
)
db = Db(settings.database)
# ключи кэша и объектов — по имени базы: тестовая база не видит
# карточек и вложений рабочей
cache = create_cache(settings.cache, namespace=db.name)
object_store = create_object_store(settings.s3, namespace=db.name)
app.state.settings = settings
app.state.db = db
app.state.cache = cache
app.state.object_store = object_store
app.state.storage = CachedStorage(
PostgresStorage(db),
cache,
chat_ttl=settings.cache.chat_ttl,
)
app.state.objects = AttachmentObjects(object_store)
app.state.upload_slots = UploadSlots(settings.uploads)
app.state.passwords = Passwords(settings.kdf_concurrency)
app.state.ready = False
handlers.install(app)
app.add_middleware(
AuthenticationMiddleware,
backend=BearerBackend(),
on_error=on_auth_error,
)
app.add_middleware(RequestIdMiddleware, instance_id=settings.instance_id)
app.include_router(health_router)
app.include_router(api_router)
return app
def run() -> None:
"""Точка входа `python -m src`: один процесс, один event loop."""
try:
settings = Settings.from_env()
except ConfigError as exc:
print(f"configuration error: {exc}", file=sys.stderr)
raise SystemExit(2) from None
# экземпляр, а не строка импорта: без reload и без --workers. Пул
# соединений считается на один процесс; процессов — число реплик
uvicorn.run(
create_app(settings),
host=settings.host,
port=settings.port,
log_config=logging_config(settings.log_level),
access_log=False,
server_header=False,
timeout_graceful_shutdown=settings.shutdown_timeout,
timeout_keep_alive=settings.keep_alive,
)
+88
View File
@@ -0,0 +1,88 @@
"""Keyset-пагинация по `(created_at, id)` и непрозрачный курсор.
Курсор — base64url без `=` от строки `<scope>|<микросекунды>|<id hex>`:
ключ последнего элемента страницы плюс область списка. Область —
`chat:<id>` для истории чата и `chats-of:<id>` для списка чатов
пользователя, поэтому курсор другого чата или пользователя не
принимается (400). Клиент курсор не разбирает, формат можно менять.
"""
import base64
import binascii
from collections.abc import Sequence
from datetime import UTC, datetime, timedelta
from typing import Protocol
from uuid import UUID
from src.domain import Page
from src.errors import InvalidCursor
type SortKey = tuple[datetime, UUID]
_EPOCH = datetime(1970, 1, 1, tzinfo=UTC)
_MICROSECOND = timedelta(microseconds=1)
_SEPARATOR = "|"
class Keyed(Protocol):
@property
def id(self) -> UUID: ...
@property
def created_at(self) -> datetime: ...
def sort_key(item: Keyed) -> SortKey:
"""Порядок контракта: `created_at`, при равенстве — `id` как UUID."""
return item.created_at, item.id
def history_scope(chat_id: UUID) -> str:
return f"chat:{chat_id}"
def chat_list_scope(user_id: UUID) -> str:
return f"chats-of:{user_id}"
def encode_cursor(scope: str, key: SortKey) -> str:
created_at, item_id = key
micros = (created_at - _EPOCH) // _MICROSECOND
raw = _SEPARATOR.join((scope, str(micros), item_id.hex))
return base64.urlsafe_b64encode(raw.encode()).rstrip(b"=").decode("ascii")
def decode_cursor(cursor: str | None, scope: str) -> SortKey | None:
"""Ключ, после которого начинается страница; нет курсора — `None`.
Битый курсор или курсор другой области — `InvalidCursor`.
"""
if cursor is None:
return None
try:
padded = cursor + "=" * (-len(cursor) % 4)
# Нестрогий декодер молча игнорировал посторонние символы курсора.
raw = base64.b64decode(
padded.encode("ascii"), altchars=b"-_", validate=True
).decode()
cursor_scope, micros, item_hex = raw.split(_SEPARATOR)
created_at = _EPOCH + int(micros) * _MICROSECOND
item_id = UUID(hex=item_hex)
except (ValueError, UnicodeError, binascii.Error, OverflowError):
raise InvalidCursor from None
if cursor_scope != scope:
raise InvalidCursor
return created_at, item_id
def make_page[T: Keyed](rows: Sequence[T], *, limit: int, scope: str) -> Page[T]:
"""Страница из выборки длиной до `limit + 1`.
Лишний элемент значит, что дальше есть ещё записи. Курсор строится по
последнему элементу страницы, а не по лишнему: тот придёт первым на
следующей странице.
"""
items = tuple(rows[:limit])
if len(rows) <= limit:
return Page(items=items, next_cursor=None)
return Page(items=items, next_cursor=encode_cursor(scope, sort_key(items[-1])))
+74
View File
@@ -0,0 +1,74 @@
"""Хэширование паролей: Argon2id в потоке с отдельным лимитом.
Профиль RFC 9106 low-memory (t=3, m=64 MiB, p=4) назван явно, а не взят
умолчанием argon2-cffi: обновление библиотеки не поменяет его молча. Один
хэш — десятки миллисекунд CPU и 64 MiB памяти, поэтому он считается в
потоке, а не в event loop (иначе один вход останавливал бы все запросы
процесса), и не больше `KDF_CONCURRENCY` хэшей одновременно: общий пул
потоков anyio на 40 потоков дал бы до 2,5 GiB памяти.
Пароль хэшируется целиком как UTF-8, без обрезки: bcrypt не подходит,
он режет пароль на 72 байтах, а 128 code points занимают до 512 байт.
"""
import secrets
import anyio
from anyio import to_thread
from argon2 import PasswordHasher, profiles
from argon2.exceptions import VerifyMismatchError
class Passwords:
def __init__(self, concurrency: int) -> None:
self._hasher = PasswordHasher.from_parameters(profiles.RFC_9106_LOW_MEMORY)
self._limiter = anyio.CapacityLimiter(concurrency)
# хэш для неизвестного username; считает lifespan при старте
self._dummy_hash: str | None = None
async def hash(self, password: str) -> str:
"""Строка Argon2id с параметрами и солью."""
return await to_thread.run_sync(
self._hasher.hash,
password,
limiter=self._limiter,
)
async def verify(self, *, password: str, password_hash: str | None) -> bool:
"""Подходит ли пароль к хэшу.
`password_hash=None` — пользователя нет. Пароль всё равно
проверяется, против фиктивного хэша: время ответа не выдаёт,
существует ли username.
"""
if password_hash is None:
await to_thread.run_sync(
self._matches,
await self.prepare(),
password,
limiter=self._limiter,
)
return False
return await to_thread.run_sync(
self._matches,
password_hash,
password,
limiter=self._limiter,
)
async def prepare(self) -> str:
"""Фиктивный хэш, один на процесс.
Lifespan вызывает его при старте: иначе первый вход с неизвестным
username считал бы хэш и проверку — вдвое дольше неверного пароля.
"""
if self._dummy_hash is None:
self._dummy_hash = await self.hash(secrets.token_urlsafe(16))
return self._dummy_hash
def _matches(self, password_hash: str, password: str) -> bool:
# повреждённый хэш (InvalidHashError) — дефект, а не неверный пароль
try:
return self._hasher.verify(password_hash, password)
except VerifyMismatchError:
return False
+369
View File
@@ -0,0 +1,369 @@
"""S3 (SeaweedFS): клиент aiobotocore со сроком на вызов, без повторов.
Байты вложений живут в приватном bucket; метаданные — в PostgreSQL.
Клиент — тот же, через что хранилище (`storage/objects.py`) ходит в S3:
- **срок** — `asyncio.timeout(S3_TIMEOUT)` на каждый вызов и на каждый
блок потокового чтения тела. Других сроков чтения нет: `read_timeout`
botocore выключен. В aiohttp он превращается в срок чтения сокета,
который после потокового ответа с паузой чтения взводится заново уже у
соединения, вернувшегося в пул, и через срок портит простаивающее
соединение — следующий вызов падает за миллисекунду (так было в лабе 4
соседнего проекта на aiohttp 3.14). Срок установки соединения —
`S3_CONNECT_TIMEOUT`;
- **повторов нет** (`total_max_attempts=1`): рестарт S3 повтора не
требует, таймаут, как у Valkey, не повторяется, а загрузку повторяет
клиент контракта;
- **ошибки** — доменные: отказ соединения, обрыв, таймаут, 5xx, отказ в
ключах или в доступе и отсутствующий bucket — `ObjectStorageUnavailable`
(503); отсутствующий ключ — `StoredObjectMissing` (`head` отдаёт
`None`, `delete` — не ошибка). Прочие ошибки botocore не переводятся:
это дефект, 500. Удалённый bucket у HEAD не отличить от отсутствующего
ключа (SeaweedFS отвечает 404 без тела) — поэтому сверка проверяет
bucket отдельно, списком;
- **счётчики**: попытки вызовов по операциям, ключи страниц списка и
прочитанные байты — `stats()`; по разности снимков сверка называет
стоимость прохода.
В журнал — адрес, bucket, ключ объекта, длительность и класс ошибки, без
текста исключения botocore: ключей доступа и подписей там нет. Логгеры
botocore и aiohttp выше WARNING не поднимаются (`src/log.py`): на DEBUG
botocore пишет заголовки с подписью.
"""
import asyncio
import time
from collections import Counter
from collections.abc import AsyncIterator, Mapping
from contextlib import AsyncExitStack, asynccontextmanager
from dataclasses import dataclass
from datetime import datetime
from types import MappingProxyType
from typing import Any, BinaryIO
import aiohttp
from aiobotocore.config import AioConfig
from aiobotocore.session import get_session
from botocore.exceptions import ClientError, HTTPClientError, IncompleteReadError
from botocore.exceptions import ConnectionError as BotoConnectionError
from src.config import ObjectStorage as S3Settings
from src.constants import DOWNLOAD_CHUNK_BYTES, S3_KEEPALIVE_TIMEOUT
from src.errors import ObjectStorageUnavailable
from src.log import get_logger
log = get_logger(__name__)
# отказ в ключах: ключ или секрет не совпали с сервером
_CREDENTIAL_CODES = frozenset({"InvalidAccessKeyId", "SignatureDoesNotMatch"})
# отказ в доступе: у ключа нет прав или bucket уже нет (PUT в удалённый
# bucket SeaweedFS отклоняет так же); у HEAD тела нет, только статус
_DENIED_CODES = frozenset({"AccessDenied", "403", "Forbidden"})
_MISSING_BUCKET_CODES = frozenset({"NoSuchBucket"})
# отсутствующий ключ: у GET — NoSuchKey, у HEAD — только статус
_MISSING_CODES = frozenset({"NoSuchKey", "404", "NotFound"})
# недоступность: отказ и таймаут соединения, обрыв и таймаут чтения,
# неполный ответ, ошибки aiohttp и сокета, asyncio.timeout (TimeoutError —
# подкласс OSError). Ошибки параметров botocore сюда не входят: дефект
_UNAVAILABLE = (
BotoConnectionError,
HTTPClientError,
IncompleteReadError,
aiohttp.ClientError,
OSError,
)
# имя операции botocore → имя в счётчиках
OPERATIONS = MappingProxyType(
{
"list_objects_v2": "list",
"head_object": "head",
"get_object": "get",
"delete_object": "delete",
"put_object": "put",
},
)
class StoredObjectMissing(Exception):
"""Ключа в bucket нет."""
@dataclass(frozen=True, slots=True)
class ObjectInfo:
"""Объект в bucket; `last_modified` — часы S3, точность — секунда."""
key: str
size: int
last_modified: datetime | None = None
@dataclass(frozen=True, slots=True)
class ObjectPage:
"""Страница списка по префиксу; `next_token` `None` — страница последняя."""
objects: tuple[ObjectInfo, ...]
next_token: str | None
@dataclass(frozen=True, slots=True)
class StoreStats:
"""Снимок счётчиков клиента с его создания."""
calls: Mapping[str, int]
listed_keys: int
read_bytes: int
class StoredObject:
"""Открытый на чтение объект: размер и чтение блоками со сроком на блок.
Отдача 10 MiB медленному клиенту длится дольше срока вызова, а один
блок — нет.
"""
def __init__(self, info: ObjectInfo, body: Any, store: "ObjectStore") -> None:
self.info = info
self._body = body
self._store = store
@property
def size(self) -> int:
return self.info.size
async def iter_chunks(
self, chunk_bytes: int = DOWNLOAD_CHUNK_BYTES
) -> AsyncIterator[bytes]:
while True:
chunk = await self._store.read_chunk(self._body, self.info.key, chunk_bytes)
if not chunk:
return
yield chunk
class ObjectStore:
"""Объекты одного bucket ключами пользователя S3 этого процесса.
`namespace` — имя базы PostgreSQL процесса: из него хранилище строит
ключи объектов, и объекты отдельного стенда тестов не смешиваются с
рабочими, как ключи кэша. Клиент создаёт `start()` (модели botocore —
при старте, сети нет) или первый вызов; соединения открываются лениво.
"""
def __init__(self, settings: S3Settings, *, namespace: str) -> None:
self.namespace = namespace
self.bucket = settings.bucket
self.endpoint = settings.endpoint
self._settings = settings
self._timeout = settings.timeout
self._client: Any = None
self._stack: AsyncExitStack | None = None
self._lock = asyncio.Lock()
self._calls: Counter[str] = Counter()
self._listed_keys = 0
self._read_bytes = 0
def stats(self) -> StoreStats:
return StoreStats(
calls=MappingProxyType({n: self._calls[n] for n in OPERATIONS.values()}),
listed_keys=self._listed_keys,
read_bytes=self._read_bytes,
)
async def start(self) -> None:
await self._get_client()
async def close(self) -> None:
async with self._lock:
if self._stack is not None:
await self._stack.aclose()
self._stack = None
self._client = None
async def put(self, key: str, body: BinaryIO, *, content_type: str) -> None:
"""Записать объект из потока с `read`, `seek` и `tell`.
Поток, а не `bytes`: botocore обернул бы `bytes` в свой `BytesIO`,
а aiohttp при отправке скопировал бы его буфер — два тела в памяти
на загрузку вместо одного.
"""
await self._call("put_object", key, Body=body, ContentType=content_type)
async def head(self, key: str) -> ObjectInfo | None:
"""Размер и время записи; `None` — объекта нет (или нет bucket)."""
try:
response = await self._call("head_object", key)
except StoredObjectMissing:
return None
return ObjectInfo(
key=key,
size=response["ContentLength"],
last_modified=response.get("LastModified"),
)
async def list_page(
self, prefix: str, *, token: str | None, max_keys: int
) -> ObjectPage:
"""Страница ListObjectsV2 по префиксу. Нет bucket — не пустая
страница, а `ObjectStorageUnavailable`."""
params: dict[str, Any] = {"Prefix": prefix, "MaxKeys": max_keys}
if token is not None:
params["ContinuationToken"] = token
response = await self._call("list_objects_v2", None, **params)
contents = response.get("Contents", ())
self._listed_keys += len(contents)
objects = tuple(
ObjectInfo(
key=item["Key"],
size=item["Size"],
last_modified=item.get("LastModified"),
)
for item in contents
)
token = (
response.get("NextContinuationToken")
if response.get("IsTruncated")
else None
)
return ObjectPage(objects=objects, next_token=token)
@asynccontextmanager
async def open(self, key: str) -> AsyncIterator[StoredObject]:
"""Объект на чтение блоками; нет объекта — `StoredObjectMissing`.
Соединение возвращается в пул (или закрывается, если тело
прочитано не до конца) при выходе из контекста.
"""
response = await self._call("get_object", key)
body = response["Body"]
info = ObjectInfo(
key=key,
size=response["ContentLength"],
last_modified=response.get("LastModified"),
)
try:
yield StoredObject(info, body, self)
finally:
body.close()
async def delete(self, key: str) -> None:
"""Удалить объект; отсутствие — не ошибка, нет bucket — 503."""
try:
await self._call("delete_object", key)
except StoredObjectMissing:
return
async def read_chunk(self, body: Any, key: str, chunk_bytes: int) -> bytes:
started = time.monotonic()
try:
async with asyncio.timeout(self._timeout):
chunk = await body.read(chunk_bytes)
except (ClientError, *_UNAVAILABLE) as exc:
failure = self._failure(exc, "read_body", key, started)
if failure is None:
raise
raise failure from exc
self._read_bytes += len(chunk)
return chunk
async def _get_client(self) -> Any:
if self._client is not None:
return self._client
async with self._lock:
if self._client is None:
stack = AsyncExitStack()
self._client = await stack.enter_async_context(self._create())
self._stack = stack
return self._client
def _create(self) -> Any:
settings = self._settings
config = AioConfig(
# виртуальные хосты bucket.s3 DNS Docker не разрешает
s3={"addressing_style": "path"},
connect_timeout=settings.connect_timeout,
# срок чтения — только asyncio.timeout вызова и блока (докстринг)
read_timeout=None,
retries={"total_max_attempts": 1},
max_pool_connections=settings.max_connections,
connector_args={"keepalive_timeout": S3_KEEPALIVE_TIMEOUT},
)
# ключи передаются всегда, даже пустые: иначе botocore искал бы
# учётные данные в окружении и ~/.aws
return get_session().create_client(
"s3",
endpoint_url=settings.endpoint,
region_name=settings.region,
aws_access_key_id=settings.access_key_id,
aws_secret_access_key=settings.secret_access_key,
config=config,
)
async def _call(self, operation: str, key: str | None, **params: Any) -> dict:
"""Вызов со сроком и переводом ошибок; `key=None` — вызов без ключа
(список), в журнал тогда идёт префикс."""
client = await self._get_client()
self._calls[OPERATIONS.get(operation, operation)] += 1
started = time.monotonic()
if key is not None:
params["Key"] = key
target = key if key is not None else params.get("Prefix")
try:
async with asyncio.timeout(self._timeout):
return await getattr(client, operation)(Bucket=self.bucket, **params)
except (ClientError, *_UNAVAILABLE) as exc:
failure = self._failure(
exc, operation, target, started, listing=key is None
)
if failure is None:
raise
raise failure from exc
def _failure(
self,
error: Exception,
operation: str,
key: str | None,
started: float,
*,
listing: bool = False,
) -> Exception | None:
"""Доменное исключение вместо ошибки клиента; `None` — не переводить.
У списка и 404 без тела — отсутствующий bucket: «объекта нет» у
списка не бывает.
"""
took = (time.monotonic() - started) * 1000
where = (
f"operation={operation} endpoint={self.endpoint} bucket={self.bucket} "
f"key={key} took={took:.0f}ms error_type={type(error).__name__}"
)
if isinstance(error, ClientError):
code = str(error.response.get("Error", {}).get("Code", ""))
status = error.response.get("ResponseMetadata", {}).get("HTTPStatusCode", 0)
if code in _MISSING_BUCKET_CODES or (listing and code in _MISSING_CODES):
log.error("object storage bucket is missing %s code=%s", where, code)
return ObjectStorageUnavailable()
if code in _MISSING_CODES:
return StoredObjectMissing()
if code in _CREDENTIAL_CODES:
log.error("object storage rejected credentials %s code=%s", where, code)
return ObjectStorageUnavailable()
if code in _DENIED_CODES or status == 403:
log.error("object storage denied access %s code=%s", where, code)
return ObjectStorageUnavailable()
if status >= 500:
log.warning(
"object storage unavailable %s code=%s status=%s",
where,
code,
status,
)
return ObjectStorageUnavailable()
return None
log.warning("object storage unavailable %s", where)
return ObjectStorageUnavailable()
def create_object_store(settings: S3Settings, *, namespace: str) -> ObjectStore:
"""Хранилище объектов по настройкам; клиент и соединения — лениво."""
return ObjectStore(settings, namespace=namespace)
+160
View File
@@ -0,0 +1,160 @@
# src/services/ — бизнес-логика
## Правила
- Класс на домен: `UserService`, `SessionService`, `ChatService`,
`MessageService`, с лабы 4 — `AttachmentService` (загрузка, метаданные,
скачивание), `CleanupService` (уборка незавершённых загрузок) и
`ReconcileService` (сверка bucket и БД); два последних живут в
процессе уборщика (`src/cleaner/main.py`). Конструктор принимает
`Storage` / `MaintenanceStorage` (Protocol) и `AttachmentObjects`, не
реализацию; `UserService` и `SessionService` — ещё `Passwords`,
`SessionService` — срок сессии, `AttachmentService` — `UploadSlots` и
срок тела. Сервис создаётся на запрос фабрикой из `api/deps.py`
(`SessionService` — ещё и `BearerBackend` в `api/identity.py`);
состояния у него нет (места загрузок — общий объект процесса в
`app.state`).
- Публичные методы — `async def` и keyword-only (`*,`).
- Сервис не знает про HTTP и про SQL: не импортирует fastapi, starlette,
pydantic, sqlalchemy, `src.db`, `src.cache`; не принимает модели API и
`Request`, не возвращает словари. Вход — примитивы и `UUID`, выход —
объекты `src/domain.py`.
- Ошибки — только классы из `src/errors.py`. `Unavailable` из хранилища
сервис не ловит: 503 должен дойти до клиента.
- Проверка доступа к чату — одна функция `access.chat_of_member()`.
Сервисы не вызывают друг друга: общий код — в функции модуля
`access.py` или новом модуле рядом.
- `id` и `created_at` сервис не назначает: это делает хранилище внутри
своей транзакции.
## Пароли и сессии
- Пароль хэшируется `Passwords.hash()` (Argon2id в потоке, лимит
`KDF_CONCURRENCY`) **до** обращения к БД: соединение пула не ждёт KDF.
- Вход (`SessionService.login`) — две операции хранилища: чтение хэша
(своя транзакция закрыта до KDF), проверка пароля вне БД, затем
создание сессии. Неизвестный username проверяется против фиктивного
хэша: время ответа не выдаёт, есть ли пользователь. Ошибка одна —
`InvalidCredentials`.
- Токен — `secrets.token_urlsafe(32)`; в хранилище уходит только
`hash_token(token)` (SHA-256). Токен возвращается клиенту один раз
(`IssuedSession`) и больше нигде не живёт.
- `authenticate` — один запрос хранилища по хэшу токена; нет токена или
сессии — `Unauthorized`. Срок не продлевается.
- `revoke` удаляет только текущую сессию; повторный выход тем же токеном
до сервиса не дойдёт (401 в middleware).
## Отправка с ключом идемпотентности (лаба 3)
- `MessageService(storage, key_ttl=IDEMPOTENCY_TTL_SECONDS)`;
`send(chat_id, sender_id, text, idempotency_key)`.
- Порядок: сессию уже проверил middleware, ключ и тело — схема ручки;
здесь членство (`chat_of_member` → `NotFound`, 404), затем один вызов
`storage.create_message(..., key, request_hash, key_ttl)`. Повтор
проходит членство и сессию заново: посторонний с чужим ключом — 404,
отозванный токен — 401.
- `request_hash(text=..., attachment_ids=())` — SHA-256 канонического
JSON тела (`sort_keys`, без пробелов, UTF-8), собранного из
**разобранных** полей: другая запись того же JSON — тот же хэш.
`attachment_ids` входит в JSON, только если список не пуст: тело лабы 3
без поля, `[]` и прежний ключ дают один хэш (повтор старого запроса
после замены реплик — тот же 201). Порядок `attachment_ids` значим.
- Решение «новое / повтор / 409», срок ключа и атомарность — в
хранилище, одной транзакцией (`storage/AGENTS.md`). Сервис не держит ни
ключей, ни результатов в памяти процесса: повтор может прийти на другую
реплику.
- Лог: `message created …` или `message replayed …` с `message_id`,
`chat_id`, `length`, `replayed`; ключ и текст — никогда.
## Загрузка вложения (`AttachmentService.upload`, лаба 4)
201 `ready` — только когда объект записан в S3 и строка `ready`
зафиксирована. Порядок:
1. 401 — middleware; 400 (`chat_id`, `filename`, строгий UTF-8) — схема
ручки; 404 — членство (`chat_of_member`); 415 — `Content-Type` не
`image/png`/`image/jpeg`; 413 — `Content-Length` больше 10 MiB. Всё
это — без места загрузки и до чтения тела.
2. Место (`UploadSlots.slot()`): свободно — сразу; нет — очередь
процесса до `UPLOAD_MAX_WAITING` не дольше `UPLOAD_WAIT_TIMEOUT`,
иначе 429 `rate_limited` с `Retry-After` (тело не читалось, строки
нет). Место держится до ответа, включая запись и компенсацию.
3. Тело — в один `BytesIO` со счётчиком (больше 10 MiB — 413 сразу) и
сроком `UPLOAD_BODY_TIMEOUT` (400 `invalid_request`); обрыв — 400.
4. Структура PNG/JPEG без декодирования пикселей (`src/images.py`, в
потоке) и SHA-256 над `getvalue()` (bytes над буфером, без копии);
затем ссылка удаляется (`del data`), чтобы PUT отправил тот же буфер,
а не его копию. Повреждено, не тот формат, MIME не совпал — 415;
больше 40 млн пикселей — 413.
5. Строка `pending` с ключом объекта → PUT → `ready` (хранилище, п. 1–2
«Вложения»). Сбой PUT — 503, строку и возможный поздний объект убирает
уборщик. Сбой `ready` до COMMIT — компенсация: объект удаляется до
ответа (без повторов; не вышло — уборщик), ответ 503. Сбой на COMMIT
(`OutcomeUnknown`) — 503, объект не трогается: строка могла стать
`ready`. Строку уже пометил уборщик (загрузка пережила grace) —
объект удаляется, 503.
Граница живой загрузки (от строки до `ready`): `2 × (DB_OPERATION_TIMEOUT
+ 2) + S3_TIMEOUT` = 21 с; ожидание места, тело и проверка — до строки и
в неё не входят. `CLEANER_GRACE` (900 с) обязан быть больше — уборщик
проверяет это при старте.
Скачивание — `get` (метаданные) и `open_content` (поток блоками по 64 KiB
из S3): то же членство, 404 на чужое, незавершённое и потерянное
(`lost_at`). Байты идут через API, адрес S3 клиенту не отдаётся.
## Уборка и сверка (`cleanup.py`, `reconcile.py`, лаба 4)
- Общий код — функция модуля `cleanup.remove_stale` (пометка, затем
объект и строка под блокировкой); `ReconcileService` зовёт её, а не
`CleanupService`: сервисы не вызывают друг друга.
- Сверка (класс расхождений, что безопасно исправлять, перепроверка,
предел изменений, предел скорости, стратегии, стоимость) — докстринг
`src/services/reconcile.py`. Главное: удаляется только объект без
строки старше grace и зависшая загрузка; строки `ready`, объект, на
который ссылается строка, свежее и чужой ключ — никогда; «объекта нет»
— только после проверки, что bucket на месте; dry-run по умолчанию.
- Сигнал остановки проверяется перед каждым вызовом хранилища и в паузе
предела скорости; шаг, начатый в БД, доводится до commit или отката.
- Итоговая строка прохода `reconcile pass finished …` — найдено и
исправлено по классам и стоимость (`s3_<операция>`, `listed_keys`,
`read_bytes`, `db_queries`, `phase_<шаг>_ms`, `cpu_ms` прохода,
`maxrss_kib` процесса, `took`). Её разбирает `bench/reconcile.py`:
имена полей не менять.
## Что проверяет сервис, а что — другие
| Правило | Где |
|---|---|
| форма тела, длины, пустые строки, лишние поля, длина пароля | `api/schemas.py` |
| формат Basic, длина пароля при входе | `api/deps.py` (`parse_basic`) |
| дубликаты в `member_ids`, вызывающий в списке | `ChatService.create` |
| участники существуют | хранилище (`create_chat`, в той же транзакции) |
| username уникален | хранилище (`create_user`, уникальный индекс) |
| пользователь — участник чата (GET чата, история, отправка) | `access.chat_of_member` (карточка из кэша или БД) |
| отправитель — участник (страховка) | внешний ключ `messages → chat_members` |
| `Idempotency-Key` есть и по шаблону | схема ручки (`api/routes/messages.py`) |
| повтор того же тела / другое тело / срок ключа | хранилище (`create_message`, одна транзакция) |
| `attachment_ids`: до 10, UUID, без повторов; пустой текст (и из пробелов) — только с вложением | `api/schemas.py` (`CreateMessage`) |
| вложения сообщения `ready` и из этого чата | хранилище (`create_message`, та же транзакция) |
| `filename` безопасен для показа (1–255 символов, без `/` `\` и управляющих Cc, не из одних пробелов) | `api/schemas.py` (`DisplayFilename`) и строгий UTF-8 в ручке |
| тип, размер, пиксели, целостность изображения; место и срок тела | `AttachmentService.upload` |
| курсор разбирается и относится к этому списку | `pagination.decode_cursor` из сервиса |
| пароль верный, сессия действует | `SessionService` |
## Логи
- Логгер модуля: `log = get_logger(__name__)`.
- `info` на каждое изменение состояния (пользователь, сессия, чат,
сообщение созданы; сессия отозвана) и на отказ по бизнес-правилу
(username занят, неверные участники); `warning` — неудачный вход.
Чтения не логируются: access-строку и так пишет middleware.
- В строке — id и счётчики: `user_id=`, `session_id=`, `chat_id=`,
`message_id=`, `members=`, `length=`, `ttl=`. Никогда — `text`,
`display_name`, `title`, `username`, пароль, токен и их хэши.
## Тесты
Новое правило сервиса — тест в `student-tests/` через HTTP (статус и
форма ошибки). Юнит-тесты сервиса с подменой хранилища допустимы, но
не заменяют HTTP-тест.
+17
View File
@@ -0,0 +1,17 @@
from src.services.attachments import AttachmentService
from src.services.chats import ChatService
from src.services.cleanup import CleanupService
from src.services.messages import MessageService
from src.services.reconcile import ReconcileService
from src.services.sessions import SessionService
from src.services.users import UserService
__all__ = [
"AttachmentService",
"ChatService",
"CleanupService",
"MessageService",
"ReconcileService",
"SessionService",
"UserService",
]
+21
View File
@@ -0,0 +1,21 @@
"""Проверка доступа к чату — общая для сервисов чатов и сообщений."""
from uuid import UUID
from src.domain import Chat
from src.errors import NotFound
from src.storage import Storage
async def chat_of_member(storage: Storage, *, chat_id: UUID, user_id: UUID) -> Chat:
"""Чат, если пользователь в нём состоит; иначе `NotFound`.
Несуществующий и чужой чат неразличимы: 404 не раскрывает, что чат
есть. Состав чата после создания не меняется, поэтому результат
проверки (в том числе по карточке из кэша) не устаревает до конца
запроса.
"""
chat = await storage.get_chat(chat_id)
if chat is None or user_id not in chat.member_ids:
raise NotFound
return chat
+384
View File
@@ -0,0 +1,384 @@
"""Вложения: загрузка оригинала в S3 с метаданными в PostgreSQL, чтение, отдача.
Порядок записи загрузки (REPORT.md, «Согласованность БД и S3»): проверки
→ место загрузки → тело → проверка изображения и SHA-256 → строка
`pending` с ключом объекта (commit) → PUT в S3 → `ready` (commit) → 201.
Любой объект, который пишет API, известен PostgreSQL **до** записи:
обрыв после строки `pending` оставляет в базе след, по которому уборщик
найдёт и уберёт объект. Компенсация в самой загрузке — удаление объекта,
только когда точно известно, что вложение `ready` не станет.
Сессии БД на весь запрос нет: каждая операция хранилища — своё короткое
соединение, и передача тела 10 MiB медленному клиенту соединение пула не
держит. `filename` в журнал не пишется: его выбирает пользователь.
"""
import asyncio
import hashlib
import io
import time
from collections.abc import AsyncIterator, Awaitable, Callable
from contextlib import AsyncExitStack
from dataclasses import dataclass
from uuid import UUID
from anyio import to_thread
from src.constants import (
ATTACHMENT_MAX_BYTES,
ATTACHMENT_MAX_PIXELS,
ATTACHMENT_READY,
ATTACHMENT_TYPES,
)
from src.domain import Attachment
from src.errors import (
ContentMissing,
NotFound,
OutcomeUnknown,
PayloadTooLarge,
Unavailable,
UnsupportedMediaType,
UploadInterrupted,
UploadsBusy,
UploadTimedOut,
)
from src.images import (
DamagedImage,
ImageInfo,
TooManyPixels,
UnsupportedImage,
inspect_image,
)
from src.log import get_logger
from src.services.access import chat_of_member
from src.storage import AttachmentObjects, Storage
from src.storage.objects import StoredObjectMissing
from src.uploads import UploadSlots
log = get_logger(__name__)
@dataclass(frozen=True, slots=True)
class AttachmentContent:
"""Оригинал на отдачу: блоки из S3 и закрытие объекта.
`chunks` сам закрывает объект в конце; `close` — на случай, если
отдача не началась (клиент ушёл раньше).
"""
content_type: str
size_bytes: int
chunks: AsyncIterator[bytes]
close: Callable[[], Awaitable[None]]
def _inspect(data: bytes) -> tuple[ImageInfo, bytes]:
"""Структура изображения и SHA-256 — одним вызовом в потоке."""
info = inspect_image(data, max_pixels=ATTACHMENT_MAX_PIXELS)
return info, hashlib.sha256(data).digest()
class AttachmentService:
def __init__(
self,
storage: Storage,
objects: AttachmentObjects,
slots: UploadSlots,
*,
body_timeout: float,
) -> None:
self._storage = storage
self._objects = objects
self._slots = slots
self._body_timeout = body_timeout
async def upload(
self,
*,
chat_id: UUID,
owner_id: UUID,
filename: str,
content_type: str | None,
content_length: int | None,
body: AsyncIterator[bytes],
) -> Attachment:
"""Оригинал в S3 и `ready` в PostgreSQL — только тогда 201.
Порядок проверок: 401 (middleware) → 400 (`chat_id`, `filename` —
схема ручки) → 404 (членство) → 415 (`Content-Type`) → 413
(`Content-Length`) — всё это без места загрузки и до чтения тела;
затем место (429), тело со счётчиком и сроком (413, 400),
содержимое (415, 413). Место держится до ответа, включая запись и
компенсацию.
"""
started = time.monotonic()
await chat_of_member(self._storage, chat_id=chat_id, user_id=owner_id)
if content_type not in ATTACHMENT_TYPES:
self._rejected(chat_id, filename, "type")
raise UnsupportedMediaType
if content_length is not None and content_length > ATTACHMENT_MAX_BYTES:
self._rejected(chat_id, filename, "declared_size")
raise PayloadTooLarge
waiting_since = time.monotonic()
try:
async with self._slots.slot() as waited_ms:
return await self._store(
chat_id=chat_id,
owner_id=owner_id,
filename=filename,
content_type=content_type,
body=body,
started=started,
waited_ms=waited_ms,
)
except UploadsBusy:
# бросает только вход в место: тело не читалось, строки нет
self._rejected(
chat_id,
filename,
"busy",
f"waited={(time.monotonic() - waiting_since) * 1000:.0f}ms",
)
raise
async def _store(
self,
*,
chat_id: UUID,
owner_id: UUID,
filename: str,
content_type: str,
body: AsyncIterator[bytes],
started: float,
waited_ms: int,
) -> Attachment:
"""Путь загрузки на занятом месте: тело, проверка, запись."""
buffer = await self._read_body(body, chat_id=chat_id, filename=filename)
# bytes над буфером BytesIO, без копии
data = buffer.getvalue()
try:
info, sha256 = await to_thread.run_sync(_inspect, data)
except TooManyPixels:
self._rejected(chat_id, filename, "pixels")
raise PayloadTooLarge from None
except DamagedImage:
self._rejected(chat_id, filename, "damaged")
raise UnsupportedMediaType from None
except UnsupportedImage:
# не PNG и не JPEG по сигнатуре, в том числе пустое тело
self._rejected(chat_id, filename, "content")
raise UnsupportedMediaType from None
if info.content_type != content_type:
self._rejected(chat_id, filename, "content_mismatch")
raise UnsupportedMediaType
size = len(data)
# пока жива ссылка на bytes, буфер BytesIO общий, и при отправке
# PUT его скопировали бы целиком — два тела на загрузку вместо одного
del data
pending = await self._storage.create_pending_attachment(
chat_id=chat_id,
owner_id=owner_id,
filename=filename,
content_type=info.content_type,
size_bytes=size,
sha256=sha256,
key_of=self._objects.key_of,
)
try:
await self._objects.put(
pending.object_key, buffer, content_type=pending.content_type
)
except Exception:
# объект не трогаем: при замороженном S3 удаление ждало бы ещё
# срок вызова, а тело без ответа сервера не уходит. Строку и
# возможный поздний объект убирает уборщик
log.warning(
"attachment upload left pending attachment_id=%s step=put",
pending.id,
)
raise
ready = await self._mark_ready(pending)
log.info(
"attachment uploaded attachment_id=%s chat_id=%s size=%d "
"content_type=%s width=%d height=%d waited=%dms took=%.0fms",
ready.id,
chat_id,
ready.size_bytes,
ready.content_type,
info.width,
info.height,
waited_ms,
(time.monotonic() - started) * 1000,
)
return ready
async def _mark_ready(self, pending: Attachment) -> Attachment:
"""`pending` → `ready` после записанного объекта, с компенсацией.
Сбой до отправки COMMIT — вложение `ready` не станет: объект
удаляется до ответа (без гарантии), строку убирает уборщик. Сбой на
самом COMMIT (`OutcomeUnknown`) — исход неизвестен, объект не
трогается. Строки `pending` уже нет или уборщик её пометил
(загрузка пережила grace) — объект удаляется, ответ 503.
"""
try:
ready = await self._storage.mark_attachment_ready(pending.id)
except OutcomeUnknown:
log.warning(
"attachment upload left pending attachment_id=%s step=commit",
pending.id,
)
raise
except Exception:
# CancelledError сюда не попадает: при отмене задачи await
# ненадёжен, остаток убирает уборщик
log.warning(
"attachment upload left pending attachment_id=%s step=ready",
pending.id,
)
await self._compensate(pending)
raise
if ready is None:
log.error(
"pending attachment was removed before ready attachment_id=%s",
pending.id,
)
await self._compensate(pending)
raise Unavailable
return ready
async def _compensate(self, pending: Attachment) -> None:
"""Удалить объект загрузки, которая не станет `ready`; без повторов.
Не вышло — `warning`, исходная ошибка загрузки уходит дальше, а
объект вместе со строкой убирает уборщик.
"""
try:
await self._objects.delete(pending.object_key)
except Exception as exc:
log.warning(
"attachment object kept for cleaner attachment_id=%s "
"object_key=%s error_type=%s",
pending.id,
pending.object_key,
type(exc).__name__,
)
return
log.info(
"attachment object deleted attachment_id=%s object_key=%s",
pending.id,
pending.object_key,
)
async def _read_body(
self,
body: AsyncIterator[bytes],
*,
chat_id: UUID,
filename: str,
) -> io.BytesIO:
"""Тело целиком в `BytesIO`; больше лимита — 413 сразу, без
дочитывания; не пришло за `UPLOAD_BODY_TIMEOUT` — 400.
Срок — один на всё тело с момента, как загрузка заняла место:
клиент, который шлёт по байту, место вечно не держит. Буфер под
`Content-Length` заранее не выделяется: заявивший 10 MiB клиент
держал бы их, ничего не передав.
"""
buffer = io.BytesIO()
size = 0
try:
async with asyncio.timeout(self._body_timeout):
async for chunk in body:
size += len(chunk)
if size > ATTACHMENT_MAX_BYTES:
self._rejected(chat_id, filename, "size")
raise PayloadTooLarge
buffer.write(chunk)
except UploadInterrupted:
self._rejected(chat_id, filename, "interrupted")
raise
except TimeoutError:
self._rejected(chat_id, filename, "body_timeout", f"received={size}")
raise UploadTimedOut from None
return buffer
def _rejected(self, chat_id: UUID, filename: str, reason: str, *extra: str) -> None:
# имя файла выбирает пользователь: в журнал — только его длина
log.info(
"attachment rejected reason=%s chat_id=%s filename_length=%d%s",
reason,
chat_id,
len(filename),
"".join(f" {item}" for item in extra),
)
async def get(self, *, attachment_id: UUID, user_id: UUID) -> Attachment:
"""Готовое вложение для участника его чата.
Нет строки, она `pending` или пользователь не участник — один и тот
же `NotFound`: 404 не раскрывает, что вложение есть.
"""
attachment = await self._storage.get_attachment(attachment_id)
if attachment is None or attachment.status != ATTACHMENT_READY:
raise NotFound
await chat_of_member(self._storage, chat_id=attachment.chat_id, user_id=user_id)
return attachment
async def open_content(
self, *, attachment_id: UUID, user_id: UUID
) -> AttachmentContent:
"""Оригинал потоком из S3.
Отказ S3 — 503 до заголовков ответа. Нет объекта или размер в S3
другой — `error` в журнале и 500; строку сервис не меняет. Оригинал,
который сверка уже пометила потерянным (`lost_at`), — 404 без
обращения к S3, как отсутствующий вариант готового вложения
(`contracts/README.md`); метаданные при этом 200.
"""
attachment = await self.get(attachment_id=attachment_id, user_id=user_id)
if attachment.lost_at is not None:
log.info(
"attachment content is lost attachment_id=%s object_key=%s",
attachment.id,
attachment.object_key,
)
raise NotFound
stack = AsyncExitStack()
try:
stored = await stack.enter_async_context(
self._objects.open(attachment.object_key)
)
except StoredObjectMissing:
log.error(
"attachment content is missing attachment_id=%s object_key=%s",
attachment.id,
attachment.object_key,
)
raise ContentMissing from None
if stored.size != attachment.size_bytes:
await stack.aclose()
log.error(
"attachment content size differs attachment_id=%s object_key=%s "
"size=%d stored_size=%d",
attachment.id,
attachment.object_key,
attachment.size_bytes,
stored.size,
)
raise ContentMissing
async def chunks() -> AsyncIterator[bytes]:
try:
async for chunk in stored.iter_chunks():
yield chunk
finally:
await stack.aclose()
return AttachmentContent(
content_type=attachment.content_type,
size_bytes=attachment.size_bytes,
chunks=chunks(),
close=stack.aclose,
)
+56
View File
@@ -0,0 +1,56 @@
from collections.abc import Sequence
from uuid import UUID
from src.domain import Chat, Page
from src.errors import InvalidMembers
from src.log import get_logger
from src.pagination import chat_list_scope, decode_cursor, make_page
from src.services.access import chat_of_member
from src.storage import Storage
log = get_logger(__name__)
class ChatService:
def __init__(self, storage: Storage) -> None:
self._storage = storage
async def create(
self,
*,
creator_id: UUID,
title: str,
member_ids: Sequence[UUID],
) -> Chat:
if len(set(member_ids)) != len(member_ids):
log.info("chat rejected: duplicate members count=%d", len(member_ids))
raise InvalidMembers
if creator_id not in member_ids:
log.info("chat rejected: creator is not a member")
raise InvalidMembers
try:
chat = await self._storage.create_chat(title=title, member_ids=member_ids)
except InvalidMembers:
log.info("chat rejected: unknown members")
raise
log.info(
"chat created chat_id=%s members=%d",
chat.id,
len(chat.member_ids),
)
return chat
async def get(self, *, chat_id: UUID, user_id: UUID) -> Chat:
return await chat_of_member(self._storage, chat_id=chat_id, user_id=user_id)
async def list_for(
self,
*,
user_id: UUID,
limit: int,
cursor: str | None,
) -> Page[Chat]:
scope = chat_list_scope(user_id)
after = decode_cursor(cursor, scope)
rows = await self._storage.list_chats_of(user_id, after=after, limit=limit + 1)
return make_page(rows, limit=limit, scope=scope)
+154
View File
@@ -0,0 +1,154 @@
"""Уборка незавершённых загрузок: строки `pending` старше grace и их объекты.
Сервис процесса уборщика (`python -m src.cleaner`), а не реплик API:
N реплик были бы N уборщиками, а остановка реплики обрывала бы проход.
Строка убирается в два шага (storage/AGENTS.md, «Вложения»):
1. пометка — своя транзакция: блокировка `FOR UPDATE SKIP LOCKED`,
`updated_at` = сейчас, commit. Загрузка, пережившая grace, ждёт эту
блокировку в `mark_attachment_ready` и после commit находит строку
помеченной: 503 и компенсация. Помеченная строка `ready` уже не станет,
поэтому никакой исход шага 2 не даёт `ready` без объекта;
2. объект и строка — одна транзакция под той же блокировкой: DELETE
объекта, DELETE строки, commit. Объект раньше строки: сбой между ними
оставляет строку без объекта (её доуберёт следующий проход), а не
объект без строки.
Строки `ready` выборка не видит никогда. Отказ S3 или PostgreSQL
прерывает проход (причину уже записал нижний слой), строка ждёт
следующего прохода — пометка ставится заново.
"""
import time
from collections.abc import Callable
from dataclasses import dataclass
from datetime import datetime
from uuid import UUID
from src.clock import utc_now
from src.domain import Attachment
from src.errors import ObjectStorageUnavailable, Unavailable
from src.log import get_logger
from src.pagination import SortKey
from src.storage import AttachmentObjects, MaintenanceStorage
log = get_logger(__name__)
# причины прерывания прохода — в итоге и журнале
STOPPED = "stop"
OBJECT_STORAGE = "object_storage"
DATABASE = "database"
def never() -> bool:
return False
@dataclass(frozen=True, slots=True)
class CleanupResult:
removed: int
skipped: int
interrupted_by: str | None
took_ms: int
class CleanupService:
def __init__(self, storage: MaintenanceStorage, objects: AttachmentObjects) -> None:
self._storage = storage
self._objects = objects
async def clean(
self,
*,
older_than: datetime,
batch: int,
stop_requested: Callable[[], bool] = never,
) -> CleanupResult:
"""Один проход: строки `pending` с `created_at < older_than`.
Кандидаты — выборками по `batch` (keyset по `(created_at, id)`, без
блокировки), затем каждая строка отдельно. `stop_requested()` —
перед каждой строкой и между её шагами: по SIGTERM текущий шаг
доводится до commit или отката, новые не начинаются.
"""
started = time.monotonic()
removed = skipped = 0
interrupted_by: str | None = None
after: SortKey | None = None
try:
while interrupted_by is None:
candidates = await self._storage.list_stale_pending(
older_than=older_than, after=after, limit=batch
)
for candidate in candidates:
if stop_requested():
interrupted_by = STOPPED
break
done = await remove_stale(
self._storage,
self._objects,
candidate.id,
older_than=older_than,
stop_requested=stop_requested,
)
if done is None:
skipped += 1
else:
removed += 1
if interrupted_by is None and stop_requested():
interrupted_by = STOPPED
if len(candidates) < batch:
break
after = (candidates[-1].created_at, candidates[-1].id)
except ObjectStorageUnavailable:
interrupted_by = OBJECT_STORAGE
except Unavailable:
interrupted_by = DATABASE
result = CleanupResult(
removed=removed,
skipped=skipped,
interrupted_by=interrupted_by,
took_ms=round((time.monotonic() - started) * 1000),
)
line = "cleanup pass finished removed=%d skipped=%d interrupted_by=%s took=%dms"
args = (removed, skipped, interrupted_by, result.took_ms)
if interrupted_by in (OBJECT_STORAGE, DATABASE):
log.warning(line, *args)
elif removed or interrupted_by:
log.info(line, *args)
else:
# пустой проход раз в минуту журнал не засоряет
log.debug(line, *args)
return result
async def remove_stale(
storage: MaintenanceStorage,
objects: AttachmentObjects,
attachment_id: UUID,
*,
older_than: datetime,
stop_requested: Callable[[], bool] = never,
) -> Attachment | None:
"""Убрать одну зависшую строку в два шага; `None` — её уже нет, она
`ready` или её держит другая транзакция.
Функция модуля, а не метод: тот же шаг вызывает сверка для зависших
загрузок, а сервисы друг друга не вызывают (services/AGENTS.md).
"""
marked = await storage.mark_pending_removing(attachment_id, older_than=older_than)
if marked is None or stop_requested():
return None
removed = await storage.remove_stale_pending(
attachment_id,
older_than=older_than,
delete_object=objects.delete,
)
if removed is not None:
log.info(
"stale attachment removed attachment_id=%s object_key=%s age=%ds",
removed.id,
removed.object_key,
(utc_now() - removed.created_at).total_seconds(),
)
return removed
+109
View File
@@ -0,0 +1,109 @@
import hashlib
import json
from collections.abc import Sequence
from datetime import timedelta
from uuid import UUID
from src.domain import Message, Page
from src.errors import NotFound
from src.log import get_logger
from src.pagination import decode_cursor, history_scope, make_page
from src.services.access import chat_of_member
from src.storage import Storage
log = get_logger(__name__)
def request_hash(*, text: str, attachment_ids: Sequence[UUID] = ()) -> bytes:
"""SHA-256 канонического JSON тела отправки.
Тело собирается из уже разобранных полей: пробелы, `\\u`-экранирование
и порядок ключей исходного JSON на хэш не влияют — это «тот же JSON»
из контракта. `attachment_ids` (лаба 4) входит в тело только
непустым: отсутствующее поле и `[]` равны (контракт), и ключ, который
сохранила реплика лабы 3, после замены реплик повторяется тем же
сообщением, а не 409. Id — в записи сервера (нижний регистр), порядок
значим: это JSON-массив.
"""
body: dict[str, object] = {"text": text}
if attachment_ids:
body["attachment_ids"] = [
str(attachment_id) for attachment_id in attachment_ids
]
canonical = json.dumps(
body,
ensure_ascii=False,
sort_keys=True,
separators=(",", ":"),
)
return hashlib.sha256(canonical.encode()).digest()
class MessageService:
def __init__(self, storage: Storage, *, key_ttl: int) -> None:
self._storage = storage
self._key_ttl = timedelta(seconds=key_ttl)
async def send(
self,
*,
chat_id: UUID,
sender_id: UUID,
text: str,
attachment_ids: Sequence[UUID],
idempotency_key: str,
) -> Message:
"""Отправка с ключом идемпотентности.
Порядок проверок: сессию уже проверил middleware (401), ключ и
тело — схема ручки (400), здесь членство (404), затем хранилище:
вложения — готовые вложения этого чата (404), ключ (409). Повтор
проходит членство и вложения заново, как и проверку сессии.
"""
# членство — по карточке чата (из кэша, если она там есть); состав
# чата не меняется, а внешние ключи сообщения и ключа — страховка
await chat_of_member(self._storage, chat_id=chat_id, user_id=sender_id)
try:
sent = await self._storage.create_message(
chat_id=chat_id,
sender_id=sender_id,
text=text,
attachment_ids=attachment_ids,
key=idempotency_key,
request_hash=request_hash(text=text, attachment_ids=attachment_ids),
key_ttl=self._key_ttl,
)
except NotFound:
if attachment_ids:
log.info(
"message rejected: attachments not found chat_id=%s attachments=%d",
chat_id,
len(attachment_ids),
)
raise
# ни текст, ни ключ в лог не пишутся: ключ выбирает клиент, в нём
# может оказаться что угодно; повтор виден по replayed
log.info(
"message %s message_id=%s chat_id=%s length=%d attachments=%d replayed=%s",
"replayed" if sent.replayed else "created",
sent.message.id,
chat_id,
len(text),
len(attachment_ids),
str(sent.replayed).lower(),
)
return sent.message
async def history(
self,
*,
chat_id: UUID,
user_id: UUID,
limit: int,
cursor: str | None,
) -> Page[Message]:
await chat_of_member(self._storage, chat_id=chat_id, user_id=user_id)
scope = history_scope(chat_id)
after = decode_cursor(cursor, scope)
rows = await self._storage.list_messages(chat_id, after=after, limit=limit + 1)
return make_page(rows, limit=limit, scope=scope)
+680
View File
@@ -0,0 +1,680 @@
"""Сверка bucket и БД: трек 2 «Согласованность двух хранилищ».
Уборщик идёт только от строк `pending` и двух расхождений не видит:
объекта без строки (PUT, который пережил свою строку; объект, положенный
мимо API) и строки `ready` без объекта (объект удалён мимо API). Сверка
находит их с обеих сторон, по умолчанию только сообщает (dry-run), с
`--apply` исправляет то, что безопасно:
- `orphan_object` — объект `<префикс><id>/original` старше grace, строки
этого `id` нет и на ключ никто не ссылается → объект удаляется;
- `stale_pending` — строка `pending` старше grace → шаг уборщика
(пометка, затем объект и строка под блокировкой);
- `missing_object` — строка `ready` старше grace, объекта нет, bucket на
месте → оригинал помечается потерянным (`lost_at`);
- `size_mismatch` — строка `ready`, размер объекта другой → помечается,
объект не трогается;
- `checksum_mismatch` — только `--deep`: SHA-256 содержимого другой →
помечается;
- `restored_object` — помеченный оригинал снова на месте с тем же
SHA-256 → пометка снимается;
- `foreign_object` — ключ под префиксом, которого API не пишет; строка с
ключом вне префикса или с ключом другого `id` → только отчёт и код 3.
Удаляется только объект без строки и зависшая загрузка: строки `ready`,
объект, на который ссылается строка, и чужой ключ — никогда. Свежее
(моложе grace по `LastModified` объекта и `created_at` строки) не
трогается: загрузка в полёте пишет объект после строки. Перед каждым
решением — перепроверка в БД и HEAD, в обоих режимах; «объекта нет» —
только после проверки, что bucket на месте. Больше `max_changes`
изменений — ни одного (код 3): массовое «расхождение» скорее значит
подменённую базу или bucket, чем настоящие потери.
Проход: (1) S3 → БД — страницы списка по префиксу вложений своей базы;
стратегия `batch` — на страницу одна выборка строк по `id`, ключи — в
множество `seen`; стратегия `head` — своя выборка на объект, без
множества; (2) БД → S3 — keyset строк `ready` по `id`: `batch` — ключа нет
в `seen`; `head` — HEAD на строку; (3) зависшие `pending`; (4)
перепроверка кандидатов; (5) с `apply` — действия по порядку: зависшие →
объекты без строки → пометки → снятия пометок. Отказ хранилища на шагах
1–4 прерывает проход без единого изменения.
Стоимость: вызовы S3 по операциям, ключи списка и прочитанные байты (по
счётчикам клиента), запросы к PostgreSQL, длительность шагов и пик RSS
процесса — в итоговой строке журнала. Предел скорости `rate` (объектов
S3 в секунду в среднем за проход, 0 — без него) — пауза после каждого
вызова S3, кусками с проверкой сигнала.
"""
import asyncio
import hashlib
import resource
import time
from collections import Counter
from collections.abc import Awaitable, Callable
from dataclasses import dataclass, field
from datetime import datetime
from typing import Any
from uuid import UUID
from src.clock import utc_now
from src.constants import ATTACHMENT_READY
from src.domain import Attachment
from src.errors import ObjectStorageUnavailable, Unavailable
from src.log import get_logger
from src.services.cleanup import (
DATABASE,
OBJECT_STORAGE,
STOPPED,
never,
remove_stale,
)
from src.storage import AttachmentObjects, MaintenanceStorage
from src.storage.objects import ObjectInfo, StoredObjectMissing, StoreStats
log = get_logger(__name__)
ORPHAN = "orphan_object"
STALE = "stale_pending"
MISSING = "missing_object"
SIZE = "size_mismatch"
CHECKSUM = "checksum_mismatch"
RESTORED = "restored_object"
FOREIGN = "foreign_object"
KINDS = (ORPHAN, STALE, MISSING, SIZE, CHECKSUM, RESTORED, FOREIGN)
# изменения под пределом max_changes; зависшие убирает и уборщик без него
LIMITED = frozenset({ORPHAN, MISSING, SIZE, CHECKSUM, RESTORED})
# порядок действий apply
ORDER = (STALE, ORPHAN, MISSING, SIZE, CHECKSUM, RESTORED)
ACTIONS = {
STALE: "removed_pending",
ORPHAN: "deleted_object",
MISSING: "marked_lost",
SIZE: "marked_lost",
CHECKSUM: "marked_lost",
RESTORED: "cleared_lost",
}
BATCH = "batch"
HEAD = "head"
STRATEGIES = (BATCH, HEAD)
PHASES = ("list", "rows", "stale", "recheck", "act")
S3_OPERATIONS = ("list", "head", "get", "delete")
# операции, у которых вызов затрагивает один объект; у списка — ключи страницы
_OBJECT_OPERATIONS = ("head", "get", "delete")
# отдельных строк журнала о находках за проход; остальное — unlogged
FINDINGS_LOGGED_MAX = 1000
# шаг паузы предела скорости: сигнал остановки ждёт не дольше
PACE_STEP_SECONDS = 0.2
def _cpu_seconds() -> float:
"""CPU процесса (user + system), с; потоки входят."""
usage = resource.getrusage(resource.RUSAGE_SELF)
return usage.ru_utime + usage.ru_stime
class _Stopped(Exception):
"""Сигнал остановки между вызовами хранилищ или во время паузы."""
@dataclass(frozen=True, slots=True)
class Finding:
kind: str
object_key: str
attachment_id: UUID | None
age_seconds: int | None
size: int | None = None
stored_size: int | None = None
@dataclass(frozen=True, slots=True)
class ReconcileResult:
apply: bool
strategy: str
deep: bool
found: dict[str, int]
fixed: dict[str, int]
remaining: int
refused: bool
interrupted_by: str | None
took_ms: int
cost: dict[str, Any]
@property
def exit_code(self) -> int:
"""0 — расхождений нет, 3 — остались (в том числе отказ по пределу),
1 — проход прерван."""
if self.interrupted_by is not None:
return 1
return 3 if self.remaining or self.refused else 0
@dataclass
class _Pass:
apply: bool
strategy: str
deep: bool
rate: float
older_than: datetime
stop_requested: Callable[[], bool]
before: StoreStats
started: float = field(default_factory=time.monotonic)
# CPU процесса к началу прохода: в итог — только сам проход, без
# импорта и загрузки моделей botocore
cpu_before: float = field(default_factory=_cpu_seconds)
seen: set[str] = field(default_factory=set)
candidates: list[Finding] = field(default_factory=list)
confirmed: list[Finding] = field(default_factory=list)
foreign: list[Finding] = field(default_factory=list)
counts: Counter[str] = field(default_factory=Counter)
fixed: Counter[str] = field(default_factory=Counter)
fixed_findings: set[int] = field(default_factory=set)
phase_ms: dict[str, int] = field(default_factory=lambda: dict.fromkeys(PHASES, 0))
logged: int = 0
def check_stop(self) -> None:
if self.stop_requested():
raise _Stopped
def age(self, moment: datetime | None) -> int | None:
if moment is None:
return None
return max(0, round((utc_now() - moment).total_seconds()))
def fresh_object(self, obj: ObjectInfo) -> bool:
# время записи неизвестно — считать свежим: удалять нельзя
return obj.last_modified is None or obj.last_modified >= self.older_than
def fresh_row(self, row: Attachment) -> bool:
return row.created_at >= self.older_than
class ReconcileService:
def __init__(self, storage: MaintenanceStorage, objects: AttachmentObjects) -> None:
self._storage = storage
self._objects = objects
async def reconcile(
self,
*,
older_than: datetime,
apply: bool,
max_changes: int,
page_size: int,
batch: int,
strategy: str = BATCH,
deep: bool = False,
rate: float = 0.0,
stop_requested: Callable[[], bool] = never,
) -> ReconcileResult:
state = _Pass(
apply=apply,
strategy=strategy,
deep=deep,
rate=rate,
older_than=older_than,
stop_requested=stop_requested,
before=self._objects.stats(),
)
refused = False
interrupted_by: str | None = None
try:
await self._phase(state, "list", self._list_objects(state, page_size))
await self._phase(state, "rows", self._check_rows(state, page_size))
await self._phase(state, "stale", self._stale_pending(state, batch))
await self._phase(state, "recheck", self._recheck_all(state))
if apply:
refused = await self._phase(state, "act", self._act(state, max_changes))
except _Stopped:
interrupted_by = STOPPED
except ObjectStorageUnavailable:
# причину уже записал клиент S3
interrupted_by = OBJECT_STORAGE
except Unavailable:
# причину уже записал src/db.py
interrupted_by = DATABASE
return self._finish(state, refused=refused, interrupted_by=interrupted_by)
async def _phase(self, state: _Pass, name: str, work: Awaitable[Any]) -> Any:
started = time.monotonic()
try:
return await work
finally:
state.phase_ms[name] += round((time.monotonic() - started) * 1000)
# --- обёртки вызовов: сигнал до вызова, счёт и предел скорости ----------
async def _db[T](self, state: _Pass, call: Callable[[], Awaitable[T]]) -> T:
state.check_stop()
state.counts["db_queries"] += 1
return await call()
async def _s3[T](self, state: _Pass, call: Callable[[], Awaitable[T]]) -> T:
state.check_stop()
result = await call()
await self._pace(state)
return result
def _touched(self, state: _Pass) -> int:
now = self._objects.stats()
touched = now.listed_keys - state.before.listed_keys
for name in _OBJECT_OPERATIONS:
touched += now.calls[name] - state.before.calls[name]
return touched
async def _pace(self, state: _Pass) -> None:
"""Пауза, пока затронутых объектов больше `rate × время прохода`.
После вызова, а не перед следующим: тогда и последний вызов прохода
не обгоняет предел.
"""
if state.rate <= 0:
return
ahead = self._touched(state) / state.rate - (time.monotonic() - state.started)
while ahead > 0:
state.check_stop()
step = min(ahead, PACE_STEP_SECONDS)
await asyncio.sleep(step)
ahead -= step
async def _read_sha(self, state: _Pass, key: str) -> bytes | None:
"""SHA-256 содержимого объекта потоком; `None` — объекта нет."""
state.check_stop()
digest = hashlib.sha256()
try:
async with self._objects.open(key) as stored:
async for chunk in stored.iter_chunks():
digest.update(chunk)
except StoredObjectMissing:
return None
await self._pace(state)
return digest.digest()
# --- 1. S3 → БД ------------------------------------------------------------
async def _list_objects(self, state: _Pass, page_size: int) -> None:
# bucket на месте — до первой страницы: иначе отказ, а не «пусто»
await self._s3(state, self._objects.probe)
token: str | None = None
while True:
page = await self._s3(
state,
lambda token=token: self._objects.list_page(
token=token, max_keys=page_size
),
)
state.counts["listed_objects"] += len(page.objects)
own: dict[UUID, ObjectInfo] = {}
for obj in page.objects:
attachment_id = self._objects.parse(obj.key)
if attachment_id is None:
# такого ключа API не пишет: не наш — только отчёт
self._foreign(state, obj.key, None, state.age(obj.last_modified))
continue
own[attachment_id] = obj
if state.strategy == BATCH:
state.seen.add(obj.key)
if state.strategy == BATCH:
ids = list(own)
rows = await self._db(
state, lambda ids=ids: self._storage.attachments_by_ids(ids)
)
by_id = {row.id: row for row in rows}
for attachment_id, obj in own.items():
await self._object(
state, attachment_id, obj, by_id.get(attachment_id)
)
else:
for attachment_id, obj in own.items():
rows = await self._db(
state,
lambda attachment_id=attachment_id: (
self._storage.attachments_by_ids([attachment_id])
),
)
await self._object(
state, attachment_id, obj, rows[0] if rows else None
)
token = page.next_token
if token is None:
return
async def _object(
self,
state: _Pass,
attachment_id: UUID,
obj: ObjectInfo,
row: Attachment | None,
) -> None:
if row is None:
if state.fresh_object(obj):
state.counts["fresh_objects"] += 1
else:
state.candidates.append(
Finding(
ORPHAN,
obj.key,
attachment_id,
state.age(obj.last_modified),
stored_size=obj.size,
)
)
return
if row.object_key != obj.key:
# строка этого id ссылается на другой ключ: объект не её
self._foreign(state, obj.key, attachment_id, state.age(obj.last_modified))
return
if state.strategy == BATCH:
await self._pair(state, row, obj)
# head: пару проверит шаг строк своим HEAD
async def _pair(self, state: _Pass, row: Attachment, obj: ObjectInfo) -> None:
"""Строка и её объект на месте: размер, пометка, с `deep` — SHA-256.
Строки `pending` — дело шага зависших."""
if row.status != ATTACHMENT_READY:
return
age = state.age(row.created_at)
if row.lost_at is not None:
if obj.size == row.size_bytes:
state.candidates.append(
Finding(RESTORED, row.object_key, row.id, age, row.size_bytes)
)
else:
state.counts["lost_known"] += 1
return
if obj.size != row.size_bytes:
state.candidates.append(
Finding(SIZE, row.object_key, row.id, age, row.size_bytes, obj.size)
)
return
if state.deep and not state.fresh_row(row):
digest = await self._read_sha(state, row.object_key)
if digest is not None and digest != row.sha256:
state.candidates.append(
Finding(CHECKSUM, row.object_key, row.id, age, row.size_bytes)
)
# --- 2. БД → S3 ------------------------------------------------------------
async def _check_rows(self, state: _Pass, page_size: int) -> None:
after: UUID | None = None
while True:
rows = await self._db(
state,
lambda after=after: self._storage.ready_page(
after=after, limit=page_size
),
)
for row in rows:
state.counts["checked_rows"] += 1
if not self._objects.is_own(row.object_key):
# ключ вне префикса своей базы: объект не читается, строка
# не помечается
self._foreign(
state, row.object_key, row.id, state.age(row.created_at)
)
continue
if state.strategy == BATCH:
if row.object_key not in state.seen:
self._row_without_object(state, row)
continue
obj = await self._s3(
state, lambda row=row: self._objects.head(row.object_key)
)
if obj is None:
self._row_without_object(state, row)
else:
await self._pair(state, row, obj)
if len(rows) < page_size:
return
after = rows[-1].id
def _row_without_object(self, state: _Pass, row: Attachment) -> None:
if row.lost_at is not None:
state.counts["lost_known"] += 1
elif state.fresh_row(row):
# готовая строка моложе grace: объект мог появиться после страницы
state.counts["fresh_rows"] += 1
else:
state.candidates.append(
Finding(
MISSING,
row.object_key,
row.id,
state.age(row.created_at),
row.size_bytes,
)
)
# --- 3. зависшие загрузки ------------------------------------------------
async def _stale_pending(self, state: _Pass, batch: int) -> None:
after = None
while True:
rows = await self._db(
state,
lambda after=after: self._storage.list_stale_pending(
older_than=state.older_than, after=after, limit=batch
),
)
for row in rows:
state.candidates.append(
Finding(STALE, row.object_key, row.id, state.age(row.created_at))
)
if len(rows) < batch:
return
after = (rows[-1].created_at, rows[-1].id)
# --- 4. перепроверка ------------------------------------------------------
async def _recheck_all(self, state: _Pass) -> None:
for finding in state.candidates:
# зависшую перепроверяет сам шаг уборщика, под блокировкой строки
if finding.kind == STALE or await self._recheck(state, finding):
state.confirmed.append(finding)
elif finding.kind == RESTORED:
# объект того же размера, но другой: оригинал по-прежнему
# потерян
state.counts["lost_known"] += 1
async def _row(self, state: _Pass, finding: Finding) -> Attachment | None:
"""Строка находки всё ещё `ready` с тем же ключом, иначе `None`."""
assert finding.attachment_id is not None
row = await self._db(
state, lambda: self._storage.get_attachment(finding.attachment_id)
)
if row is None or row.status != ATTACHMENT_READY:
return None
return row if row.object_key == finding.object_key else None
async def _recheck(self, state: _Pass, finding: Finding) -> bool:
key = finding.object_key
if finding.kind == ORPHAN:
assert finding.attachment_id is not None
references = await self._db(
state,
lambda: self._storage.attachment_references(finding.attachment_id, key),
)
if references:
return False
obj = await self._s3(state, lambda: self._objects.head(key))
return obj is not None and not state.fresh_object(obj)
row = await self._row(state, finding)
if row is None:
return False
if finding.kind == MISSING:
if row.lost_at is not None:
return False
# HEAD удалённого bucket — тоже «нет»: сначала bucket
await self._s3(state, self._objects.probe)
return await self._s3(state, lambda: self._objects.head(key)) is None
obj = await self._s3(state, lambda: self._objects.head(key))
if obj is None:
return False
if finding.kind == SIZE:
return row.lost_at is None and obj.size != row.size_bytes
if obj.size != row.size_bytes:
return False
digest = await self._read_sha(state, key)
if finding.kind == CHECKSUM:
return row.lost_at is None and digest is not None and digest != row.sha256
# RESTORED: пометку снимает только тот же SHA-256
return row.lost_at is not None and digest == row.sha256
# --- 5. действия ----------------------------------------------------------
async def _act(self, state: _Pass, max_changes: int) -> bool:
"""Действия по порядку; `True` — отказ по пределу, ничего не менялось."""
changes = sum(finding.kind in LIMITED for finding in state.confirmed)
if changes > max_changes:
log.error(
"reconcile changes exceed limit changes=%d max_changes=%d",
changes,
max_changes,
)
return True
ordered = sorted(
enumerate(state.confirmed), key=lambda item: ORDER.index(item[1].kind)
)
for index, finding in ordered:
state.check_stop()
if await self._fix(state, finding):
state.fixed[ACTIONS[finding.kind]] += 1
state.fixed_findings.add(index)
self._log_finding(state, finding, fixed=True)
return False
async def _fix(self, state: _Pass, finding: Finding) -> bool:
assert finding.attachment_id is not None
if finding.kind == STALE:
# пометка и уборка — два сеанса с БД, объект — внутри второго
state.counts["db_queries"] += 2
removed = await remove_stale(
self._storage,
self._objects,
finding.attachment_id,
older_than=state.older_than,
stop_requested=state.stop_requested,
)
await self._pace(state)
return removed is not None
# каждое действие ещё раз проверяет своё условие
if not await self._recheck(state, finding):
return False
if finding.kind == ORPHAN:
await self._s3(state, lambda: self._objects.delete(finding.object_key))
return True
if finding.kind == RESTORED:
return await self._db(
state,
lambda: self._storage.clear_attachment_lost(
finding.attachment_id, finding.object_key
),
)
return await self._db(
state,
lambda: self._storage.mark_attachment_lost(
finding.attachment_id, finding.object_key
),
)
# --- журнал и итог ---------------------------------------------------------
def _foreign(
self, state: _Pass, key: str, attachment_id: UUID | None, age: int | None
) -> None:
state.foreign.append(Finding(FOREIGN, key, attachment_id, age))
def _log_finding(self, state: _Pass, finding: Finding, *, fixed: bool) -> None:
state.logged += 1
if state.logged > FINDINGS_LOGGED_MAX:
state.counts["unlogged"] += 1
return
details = (
f"kind={finding.kind} object_key={finding.object_key} "
f"attachment_id={finding.attachment_id} age={finding.age_seconds}s"
)
if finding.size is not None and finding.stored_size is not None:
details += f" size={finding.size} stored_size={finding.stored_size}"
if fixed:
log.info(
"storage discrepancy fixed %s action=%s apply=true",
details,
ACTIONS[finding.kind],
)
else:
log.warning(
"storage discrepancy found %s apply=%s",
details,
str(state.apply).lower(),
)
def _finish(
self, state: _Pass, *, refused: bool, interrupted_by: str | None
) -> ReconcileResult:
remaining = [
finding
for index, finding in enumerate(state.confirmed)
if index not in state.fixed_findings
] + state.foreign
for finding in remaining:
self._log_finding(state, finding, fixed=False)
found = dict.fromkeys(KINDS, 0)
for finding in [*state.confirmed, *state.foreign]:
found[finding.kind] += 1
fixed = {
action: state.fixed[action] for action in sorted(set(ACTIONS.values()))
}
now = self._objects.stats()
maxrss = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss
cost: dict[str, Any] = {
**{
f"s3_{name}": now.calls[name] - state.before.calls[name]
for name in S3_OPERATIONS
},
"listed_keys": now.listed_keys - state.before.listed_keys,
"read_bytes": now.read_bytes - state.before.read_bytes,
"db_queries": state.counts["db_queries"],
**{f"phase_{name}_ms": state.phase_ms[name] for name in PHASES},
# CPU — за проход; пик RSS — процесса (Linux — КиБ): у разового
# прохода — отдельный процесс, у сервиса — с его старта
"cpu_ms": round((_cpu_seconds() - state.cpu_before) * 1000),
"maxrss_kib": maxrss,
}
result = ReconcileResult(
apply=state.apply,
strategy=state.strategy,
deep=state.deep,
found=found,
fixed=fixed,
remaining=len(remaining),
refused=refused,
interrupted_by=interrupted_by,
took_ms=round((time.monotonic() - state.started) * 1000),
cost=cost,
)
fields = {
"apply": str(state.apply).lower(),
"strategy": state.strategy,
"deep": str(state.deep).lower(),
"rate": f"{state.rate:g}",
"listed_objects": state.counts["listed_objects"],
"checked_rows": state.counts["checked_rows"],
"fresh_objects": state.counts["fresh_objects"],
"fresh_rows": state.counts["fresh_rows"],
"lost_known": state.counts["lost_known"],
**{f"found_{kind}": count for kind, count in found.items()},
**{f"fixed_{action}": count for action, count in fixed.items()},
"remaining": result.remaining,
"refused": str(refused).lower(),
"unlogged": state.counts["unlogged"],
"interrupted_by": interrupted_by,
**cost,
"took": f"{result.took_ms}ms",
}
line = " ".join(f"{name}={value}" for name, value in fields.items())
if result.remaining or refused or interrupted_by:
log.warning("reconcile pass finished %s", line)
else:
log.info("reconcile pass finished %s", line)
return result
+93
View File
@@ -0,0 +1,93 @@
"""Вход по паролю, проверка Bearer-токена, выход.
Токен — `secrets.token_urlsafe(32)`: 256 бит случайности, ничего не
кодирует (не username, не UUID, не JWT). В БД хранится только SHA-256
токена: быстрого хэша достаточно, перебирать 256 бит нечего. Медленный
KDF нужен паролю, который выбирает человек.
Срок сессии фиксируется при входе (`SESSION_TTL_SECONDS`). Ни запросы,
ни рестарт его не продлевают. Каждый запрос — поиск сессии в PostgreSQL,
без кэша: отзыв действует мгновенно.
"""
import hashlib
import secrets
from datetime import timedelta
from uuid import UUID
from src.constants import SESSION_TOKEN_BYTES
from src.domain import Identity, IssuedSession
from src.errors import InvalidCredentials, Unauthorized
from src.log import get_logger
from src.passwords import Passwords
from src.storage import Storage
log = get_logger(__name__)
def hash_token(token: str) -> bytes:
"""SHA-256 токена: по нему ищется сессия, сам токен не хранится."""
return hashlib.sha256(token.encode()).digest()
class SessionService:
def __init__(self, storage: Storage, passwords: Passwords, *, ttl: int) -> None:
self._storage = storage
self._passwords = passwords
self._ttl = timedelta(seconds=ttl)
async def login(self, *, username: str, password: str) -> IssuedSession:
"""Проверка пароля и новая сессия.
Две операции хранилища: чтение хэша закрывает свою транзакцию до
KDF, поэтому соединение пула не ждёт хэш и очередь лимита.
Пароли и пользователи не меняются: между операциями проверять
нечего.
"""
credentials = await self._storage.get_credentials(username)
# неизвестный username проверяется против фиктивного хэша: время
# ответа то же, что у неверного пароля
valid = await self._passwords.verify(
password=password,
password_hash=credentials.password_hash if credentials else None,
)
if credentials is None or not valid:
# без username и пароля: по журналу не перебрать имена
log.warning("login failed")
raise InvalidCredentials
token = secrets.token_urlsafe(SESSION_TOKEN_BYTES)
session = await self._storage.create_session(
user_id=credentials.user.id,
token_hash=hash_token(token),
ttl=self._ttl,
)
log.info(
"session created user_id=%s session_id=%s ttl=%ds",
session.user_id,
session.id,
self._ttl.total_seconds(),
)
return IssuedSession(
token=token,
expires_at=session.expires_at,
user=credentials.user,
)
async def authenticate(self, *, token: str | None) -> Identity:
"""Действующая сессия по Bearer-токену; иначе `Unauthorized`.
Недоступность БД сюда не превращается: `Unavailable` идёт дальше
(503) — отказ хранилища не делает токен недействительным и не
пропускает запрос как анонимный.
"""
if not token:
raise Unauthorized
identity = await self._storage.get_identity(hash_token(token))
if identity is None:
raise Unauthorized
return identity
async def revoke(self, *, session_id: UUID) -> None:
deleted = await self._storage.delete_session(session_id)
# False — параллельный выход тем же токеном уже удалил сессию
log.info("session revoked session_id=%s already=%s", session_id, not deleted)

Some files were not shown because too many files have changed in this diff Show More