feat: implement lab 4 attachments and storage reconciliation
This commit is contained in:
@@ -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` — остановиться
|
||||
и сказать пользователю.
|
||||
@@ -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`).
|
||||
@@ -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"],
|
||||
)
|
||||
@@ -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
@@ -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=
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -0,0 +1 @@
|
||||
3.13
|
||||
@@ -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
@@ -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"]
|
||||
@@ -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*, диапазоны и график сравнения верны.
|
||||
Предложение: отдельно печатать «недостаточно конфигураций» при числе
|
||||
точек меньше двух.
|
||||
@@ -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)
|
||||
|
||||
@@ -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
@@ -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
@@ -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 — попросить
|
||||
пользователя запустить команду и прислать вывод.
|
||||
@@ -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` | устранить причину (питание, память, посторонние контейнеры) и переснять метку новым именем |
|
||||
@@ -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)
|
||||
@@ -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
|
||||
@@ -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
File diff suppressed because it is too large
Load Diff
@@ -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()
|
||||
@@ -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
File diff suppressed because it is too large
Load Diff
+412
@@ -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()
|
||||
@@ -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
File diff suppressed because it is too large
Load Diff
@@ -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)
|
||||
@@ -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
@@ -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:
|
||||
@@ -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`.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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 с — уборщик проверяет это при старте.
|
||||
@@ -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.
|
||||
@@ -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 контейнера, консоли нет.
|
||||
@@ -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 — для выборки кандидатов уборщика.
|
||||
@@ -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 — те же (дата
|
||||
# создания не изменилась).
|
||||
@@ -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; на дисках реплик файлов
|
||||
# нет.
|
||||
@@ -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: свежие и используемые вложения
|
||||
# сверка не трогает.
|
||||
@@ -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 — каждый негативный тест проверяет статус и
|
||||
# форму ошибки контракта.
|
||||
@@ -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
@@ -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`.
|
||||
@@ -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
|
||||
Executable
+500
@@ -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
|
||||
@@ -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
|
||||
@@ -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).
|
||||
@@ -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())
|
||||
@@ -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")
|
||||
@@ -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")
|
||||
@@ -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",
|
||||
]
|
||||
@@ -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
|
||||
Executable
+600
@@ -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())
|
||||
Executable
+23
@@ -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
|
||||
Executable
+424
@@ -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"
|
||||
Executable
+82
@@ -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
@@ -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).
|
||||
@@ -0,0 +1,7 @@
|
||||
"""REST API мессенджера MTUSI, лабораторная 3: реплики за HAProxy.
|
||||
|
||||
PostgreSQL — источник истины (данные, сессии, ключи идемпотентности),
|
||||
Valkey — общий кэш карточек чатов. Пакет намеренно пустой при импорте:
|
||||
`import src.<модуль>` не поднимает приложение, не читает окружение и не
|
||||
подключается к базе.
|
||||
"""
|
||||
@@ -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()
|
||||
@@ -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` и тела. Токен в
|
||||
вывод и отчёт не копировать.
|
||||
+193
@@ -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)]
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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,
|
||||
)
|
||||
@@ -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",
|
||||
]
|
||||
@@ -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),
|
||||
)
|
||||
@@ -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)
|
||||
@@ -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()
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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
@@ -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,
|
||||
)
|
||||
@@ -0,0 +1 @@
|
||||
"""Уборщик незавершённых загрузок и сверка bucket и БД: `python -m src.cleaner`."""
|
||||
@@ -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()
|
||||
@@ -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
|
||||
@@ -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
@@ -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),
|
||||
)
|
||||
@@ -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"
|
||||
@@ -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
@@ -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
|
||||
@@ -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
@@ -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"
|
||||
@@ -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
@@ -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
@@ -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
@@ -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,
|
||||
)
|
||||
@@ -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])))
|
||||
@@ -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
|
||||
@@ -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)
|
||||
@@ -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-тест.
|
||||
@@ -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",
|
||||
]
|
||||
@@ -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
|
||||
@@ -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,
|
||||
)
|
||||
@@ -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)
|
||||
@@ -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
|
||||
@@ -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)
|
||||
@@ -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
|
||||
@@ -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
Reference in New Issue
Block a user