ЛР 3 - БВТ2301 - Кокорин - на 4 #110

Closed
kokorindenis wants to merge 2 commits from kokorindenis/mtusi2026lab3:solution/bvt2301-kokorin into main
69 changed files with 4464 additions and 29 deletions
+10
View File
@@ -18,3 +18,13 @@ __pycache__
node_modules
evidence
.DS_Store
# В образ не входят контракт, публичные тесты и отладочные материалы:
# приложению нужны только src/, migrations/, alembic.ini и requirements.txt.
tests
student-tests
contracts
examples
infra
Makefile
*.md
.vscode
+14 -11
View File
@@ -1,13 +1,16 @@
# 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
# Copy to .env only if you prefer a file; scripts/deploy.sh reads the same names
# from the process environment. Never commit .env.
#
# Public HTTP port of the single entrypoint (Traefik). API tasks publish no ports.
APP_PORT=8080
APP_ENV=lab
SESSION_TTL_SECONDS=3600
# Choose credentials locally. File paths contain no secret values.
DATABASE_URL_FILE=/run/secrets/database_url
# Optional on 3, required use on 4 in lab2; Redis OR Valkey:
SESSION_STORE=postgres
CACHE_URL_FILE=/run/secrets/cache_url
API_IMAGE=mtusi-messenger-lab3:3.0.0
# Two API replicas are declared in stack.yaml; override only for experiments.
API_REPLICAS=2
IDEMPOTENCY_TTL_SECONDS=86400
# Bearer session lifetime; survives restarts because Valkey stores absolute expiry.
SESSION_TTL_SECONDS=3600
# Sessions live in Valkey. The former SESSION_STORE=postgres is rejected at start.
SESSION_STORE=redis
# Swarm secret names are created by scripts/deploy.*; values live in secrets/.
DATABASE_URL_FILE=/run/secrets/database_url
CACHE_URL_FILE=/run/secrets/cache_url
# Idempotency-Key retention is fixed by the contract at 24 hours; no env knob.
+55
View File
@@ -0,0 +1,55 @@
# Сборка и рантайм разделены: в итоговый образ не попадают кэш pip и инструменты
# сборки, а зависимости ставятся по зафиксированному requirements.txt.
# Базовый образ закреплён по неизменяемому digest, а не только по тегу.
FROM python:3.11.9-slim-bookworm@sha256:8fb099199b9f2d70342674bd9dbccd3ed03a258f26bbd1d556822c6dfc60c317 AS builder
ENV PIP_NO_CACHE_DIR=1 \
PIP_DISABLE_PIP_VERSION_CHECK=1 \
PYTHONDONTWRITEBYTECODE=1
RUN python -m venv /opt/venv
COPY requirements.txt ./
RUN /opt/venv/bin/pip install --no-cache-dir --timeout 60 -r requirements.txt
FROM python:3.11.9-slim-bookworm@sha256:8fb099199b9f2d70342674bd9dbccd3ed03a258f26bbd1d556822c6dfc60c317 AS runtime
# Позволяет собрать новую ревизию того же исходника для проверки rolling update:
# метка меняет config образа, поэтому Swarm видит новую image ID и заменяет задачи.
ARG APP_REVISION=local
LABEL org.opencontainers.image.title="mtusi-messenger-lab3" \
org.opencontainers.image.description="API мессенджера на PostgreSQL и Valkey, лабораторная 3 (MTUSI HighLoad)" \
org.opencontainers.image.version="3.0.0" \
org.opencontainers.image.revision="${APP_REVISION:-local}"
ENV PYTHONUNBUFFERED=1 \
PYTHONDONTWRITEBYTECODE=1 \
PATH="/opt/venv/bin:$PATH" \
PYTHONPATH=/app/src \
APP_HOST=0.0.0.0 \
APP_PORT=8080
WORKDIR /app
RUN useradd --create-home --uid 10001 --shell /usr/sbin/nologin app
COPY --from=builder /opt/venv /opt/venv
# Миграции лежат в образе: роль контейнера задаётся командой (api или migrate).
COPY --chown=app:app src/ ./src/
COPY --chown=app:app alembic.ini ./
COPY --chown=app:app migrations/ ./migrations/
# Приложение работает без прав root: в образе нет ни компилятора, ни secrets.
USER 10001:10001
EXPOSE 8080
# SIGTERM доходит до PID 1 напрямую: uvicorn завершает запросы в своём бюджете.
STOPSIGNAL SIGTERM
HEALTHCHECK --interval=10s --timeout=3s --start-period=5s --retries=3 \
CMD ["python", "-m", "messenger.healthcheck"]
CMD ["python", "-m", "messenger"]
+16 -2
View File
@@ -4,10 +4,13 @@ CA_FILE ?=
ACTION_SCRIPT ?=
TLS_ARGS = $(if $(CA_FILE),--ca-file "$(CA_FILE)",)
.PHONY: help check validate test load test-persistence test-failover
.PHONY: help check validate test load test-persistence test-failover secrets student-test deploy stack-down
help:
@echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes"
@echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API"
@echo "deploy: build image + deploy stack.yaml (POSIX); secrets: create local files"
@echo "test-failover: ACTION_SCRIPT=scripts/stop-one.sh|scripts/stop-one.cmd"
@echo "student-test: own lab3 checks; load: closed-loop synthetic writes"
check:
$(PYTHON) scripts/check_contract.py
@@ -28,3 +31,14 @@ 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)
secrets:
sh scripts/bootstrap-secrets.sh
deploy:
sh scripts/deploy.sh
stack-down:
docker stack rm lab3
student-test:
$(PYTHON) student-tests/run_all.py --base-url "$(BASE_URL)"
+298 -16
View File
@@ -1,37 +1,319 @@
# Отчёт — лабораторная 3
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
- Автор, группа: Кокорин Денис, БВТ2301
- Целевая оценка: **4** — весь уровень 3 и весь уровень 4; трек 5 не заявляется
- Commit/PR: коммиты в этой сессии намеренно не создавались; решение лежит в
рабочем дереве ветки. Ссылка на PR появится после публикации автором.
- Использованные источники: skeleton лабораторной 3 (README, contracts, tests),
собственная реализация лабораторной 2 из `mtusi2026lab2`, документация Docker
Swarm, Traefik 3.5, PostgreSQL, FastAPI/SQLAlchemy.
## Запуск из чистого clone
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
### Версии и предпосылки
| Компонент | Версия | Примечание |
| --- | --- | --- |
| Python | 3.11.9 | приложение и миграции |
| Docker Engine | 28.0.1 | Docker Desktop, Linux containers |
| Docker Compose | 2.33.1 | вспомогательно; стенд разворачивается в Swarm |
| Docker Swarm | single manager + worker | `docker swarm init` при необходимости |
| Базовый образ | `python:3.11.9-slim-bookworm` | digest `sha256:8fb099199b9f2d70342674bd9dbccd3ed03a258f26bbd1d556822c6dfc60c317` |
| PostgreSQL | `postgres:16.15-bookworm` | digest `sha256:0ea6700a3b4f0ae6ce746519073558aed4d88a79d8d07622a9a644946c7319c4` |
| Valkey | `valkey/valkey:8.0.11-trixie` | digest `sha256:4436c94fc34ce4af0354b9379d433a1f258998fb955f995c89822f98c14a8cab` |
| Traefik | `traefik:v3.5.4` | фиксированный тег, не `latest` |
| Образ приложения | `mtusi-messenger-lab3:3.0.0` | собирается `Dockerfile` |
Стенд измерен на MAIBENBEN MaiBook X series, AMD Ryzen 7 5800H (16 logical CPUs,
16 GiB RAM). Docker Desktop Linux VM: 6 CPUs, ~4 GiB RAM. Лимиты контейнеров
заданы в `stack.yaml`: API 1.0 CPU / 384 MiB, PostgreSQL 2.0 CPU / 512 MiB,
Valkey 1.0 CPU / 256 MiB, Traefik 0.5 CPU / 128 MiB.
### Одна последовательность запуска (Swarm)
Выбран **Docker Swarm**: он даёт service discovery, readiness-фильтрацию,
start-first rolling update и явное управление задачами без `container_name`.
Linux / macOS:
```sh
git clone <URL fork> && cd mtusi2026lab3
chmod +x scripts/*.sh
sh scripts/bootstrap-secrets.sh # создаёт secrets/*, повторно не перезаписывает
sh scripts/deploy.sh # swarm init (если нужно), secret create, build, stack deploy
# ждём готовности; скрипт сам опрашивает /health/ready до 180 с
curl -fsS http://127.0.0.1:8080/health/ready
```
Windows PowerShell:
```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\hooks.ps1 -Mode deploy
```
Или через Make (POSIX):
```sh
make secrets
make deploy
```
### Доступность образа в Swarm
Для **одного** узла `deploy.sh` собирает образ локально и разворачивает стек с
`--resolve-image never`; это и проверено в evidence. Для нескольких узлов
локальный образ не виден остальным узлам, поэтому нужен registry:
```sh
REGISTRY=registry.example/mtusi
IMAGE="$REGISTRY/mtusi-messenger-lab3:3.0.0"
docker build -t "$IMAGE" .
docker push "$IMAGE"
API_IMAGE="$IMAGE" RESOLVE_IMAGE=always sh scripts/deploy.sh
```
На Windows то же через `$env:API_IMAGE`, `$env:RESOLVE_IMAGE='always'` и
`scripts\deploy.cmd`. В отчёте проверен одноузловой вариант; multi-node
поведение образа и registry описано как следующий шаг, а не как измеренный
результат.
Проверки:
```sh
make check
python3 -m venv .venv && .venv/bin/pip install -r requirements-dev.txt
make validate PYTHON=.venv/bin/python
make test BASE_URL=http://127.0.0.1:8080
make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://127.0.0.1:8080
make test-failover ACTION_SCRIPT=scripts/stop-one.sh BASE_URL=http://127.0.0.1:8080
make student-test BASE_URL=http://127.0.0.1:8080
```
На Windows публичные тесты запускают action-скрипт через `Popen([script])` без
shell, поэтому для них есть `.cmd`-двойники: `scripts/stop-one.cmd`,
`scripts/restart.cmd`, `scripts/restore.cmd`, `scripts/rolling-update.cmd`.
В этой среде MSYS-`make` под sandbox падал на создании signal pipe (Win32
error 5), поэтому те же цели запускались напрямую Python-интерпретатором; на
Linux команды выше выполняются штатно. Все фактические выводы — в `evidence/`.
### Остановка и удаление учебных данных
```sh
docker stack rm lab3 # убрать сервисы; named volumes остаются
docker volume rm lab3_pgdata lab3_valkeydata # только осознанно: удаляет данные
docker secret rm lab3_database_url lab3_cache_url lab3_postgres_password lab3_cursor_secret
```
`scripts/restart.sh|cmd` и `scripts/stop-one.sh|cmd` никогда не удаляют тома,
не пересоздают БД и не делают seed. `stop-one` останавливает ровно одну задачу
по `X-Instance-Id` (hostname контейнера); Swarm создаёт новую задачу с новым
hostname — это разрешено условиями лабораторной. `scripts/restore.sh|cmd`
возвращает сервис к двум задачам и ждёт готовности.
## Архитектура и решения
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
```
Клиент -> Traefik :8080 (единственная публикация, ingress)
| healthcheck /health/ready каждые 2 s, timeout 1 s
+--> api.1 (u=10001, 1 CPU/384 MiB) --\
+--> api.2 (u=10001, 1 CPU/384 MiB) ---+--> PostgreSQL (истина)
+--> Valkey (сессии, AOF)
migrate (одна задача) --> alembic upgrade head --> PostgreSQL
```
- **Источник истины** — PostgreSQL: пользователи, чаты, членство, сообщения,
записи идемпотентности. **Сессии** — только Valkey, ключ
`messenger:session:<sha256(token)>` с абсолютным TTL; API не хранит сессии
в памяти, поэтому любой экземпляр обслуживает токен, выданный другим.
- **X-Instance-Id** — hostname контейнера, стабильный на жизнь процесса.
`RequestContextMiddleware` добавляет его (и `X-Request-Id`) на все ответы,
включая ошибки; Traefik не переписывает значение.
- **Идемпотентность POST сообщения**. `message_idempotency` имеет PK
`(user_id, chat_id, idempotency_key)`, хранит `request_hash`, `message_id`,
`created_at`. Транзакция: `pg_advisory_xact_lock(hashtextextended(scope,0))`
сериализует одинаковый ключ, затем проверяется существующая строка; при
совпадении хэша возвращается тот же `Message`, при другом теле — 409. Новое
сообщение и строка идемпотентности коммитятся одной транзакцией. Срок 24 часа
считает PostgreSQL (`now() - INTERVAL '24 hours'`), а не часы приложения.
Область ключа — пользователь + чат; разные пользователи/чаты независимы.
- **Готовность** `/health/ready` проверяет PostgreSQL, наличие ревизии схемы
`0002_message_idempotency` и Valkey. `/health/live` не трогает зависимости.
Поэтому до завершения однократной миграции Traefik не направляет трафик в API.
- **Миграции** — отдельный сервис `migrate` с одной задачей и `restart_policy:
none`; `alembic upgrade head` идемпотентен и повторяется при повторном deploy.
Миграция 0002 аддитивна: новая таблица и индекс, существующие таблицы не
меняются. Новый код требует новую таблицу, поэтому readiness не пропускает
трафик до её появления; откат к старому коду возможен без изменения старых
данных, но старый код не умеет идемпотентность — это ограничение описано ниже.
- **Отказ и восстановление**: Swarm healthcheck API — interval 5 s, timeout 3 s,
retries 3, start_period 10 s. Traefik LB healthcheck — interval 2 s,
timeout 1 s, unhealthyinterval 1 s. Максимальное обнаружение отказа по
health-check: **до 3 s** (2 s + 1 s) плюс время уже начатого запроса.
`stop_grace_period` 15 s, приложение — `GRACEFUL_SHUTDOWN_SECONDS=5` +
`SHUTDOWN_DRAIN_SECONDS=2` (бюджет 7 s, меньше 10 s). SIGTERM получает PID 1
(uvicorn), завершает активные запросы и закрывает пулы.
- **Rolling update**: `update_config` — `order: start-first`, `parallelism: 1`,
`delay: 5s`, `monitor: 10s`, `failure_action: rollback`. Новая задача должна
стать healthy, затем останавливается старая; Traefik видит обе на время
перекрытия.
- **Ресурсы и изоляция**: у API нет опубликованных портов (`Endpoint.Ports=null`),
наружу смотрит только Traefik; PostgreSQL и Valkey тоже не публикуются.
Нет `container_name`, поэтому `replicas` масштабируются свободно. Секреты —
Docker secrets, монтируются файлами; значения не попадают в `stack config`,
`docker inspect` окружения и логи приложения. API работает под uid 10001,
CapEff=0.
### Соответствие переменных `.env.example`
| Переменная | Где используется | Значение/примечание |
| --- | --- | --- |
| `APP_PORT` | публикация Traefik | 8080; API слушает 8080 внутри |
| `API_IMAGE` | `stack.yaml` | `mtusi-messenger-lab3:3.0.0` |
| `API_REPLICAS` | декларация в `stack.yaml` | 2 (фактическое значение `deploy.replicas`) |
| `SESSION_TTL_SECONDS` | `SESSION_TTL_SECONDS` API | 3600; TTL хранится в Valkey |
| `SESSION_STORE` | `Config.session_store` | только `redis`; `postgres` отвергается при старте |
| `DATABASE_URL_FILE` | secret | `/run/secrets/database_url` |
| `CACHE_URL_FILE` | secret | `/run/secrets/cache_url` |
Дополнительно поддерживаются `INSTANCE_ID`, `LOG_LEVEL`, `DB_POOL_SIZE`,
`DB_MAX_OVERFLOW`, `DB_POOL_TIMEOUT_SECONDS`, `DB_CONNECT_TIMEOUT_SECONDS`,
`DB_COMMAND_TIMEOUT_SECONDS`, `DB_STATEMENT_TIMEOUT_MS`, `CACHE_TIMEOUT_SECONDS`,
`GRACEFUL_SHUTDOWN_SECONDS`, `SHUTDOWN_DRAIN_SECONDS`. Некорректное значение —
отказ старта с кодом 2, а не тихая подстановка.
### Что перенесено из lab2 и что изменено
Перенесены: FastAPI-приложение, модели/схемы, PostgreSQL-репозиторий, Valkey-сессии,
Alembic, argon2id, конверт ошибок, `X-Request-Id`, JSON-логи, healthchecks,
Dockerfile, тесты. Добавлены в lab3: `X-Instance-Id`, обязательный
`Idempotency-Key`, таблица идемпотентности с advisory lock, проверка ревизии схемы
в readiness, Swarm stack, Traefik, action-скрипты stop/restore/rolling update,
собственные проверки и evidence. `X-User-Id` по-прежнему не читается.
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
| Контракт и синтаксис skeleton не сломаны | `python scripts/check_contract.py`; `python scripts/validate_openapi.py` | PASS, PASS | `evidence/01-contract-and-openapi.txt` |
| Публичный smoke | `python tests/smoke.py --base-url http://127.0.0.1:8080` (make test запускает то же) | PASS lab3 | `evidence/02-public-smoke.txt` |
| ≥2 API-реплики за одной точкой входа, общая БД и сессии | `docker stack services lab3`; smoke/student | `lab3_api 2/2`, Traefik — единственный published port | `evidence/09-infrastructure.txt` |
| Разные запросы одного пользователя идут в разные реплики без повторного входа | `student-tests/test_lab3.py::test_01` | ≥2 разных `X-Instance-Id` на одном токене | `evidence/03-student-tests.txt` |
| Остановка одной реплики при работающей другой | `python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd` (make test-failover — та же команда) | PASS, 126/123 успешных записи за 15 s, 2/5 переходных ошибок, recovery 3.016/2.969 s | `evidence/05-failover-replica-1.txt`, `evidence/06-failover-replica-2.txt` |
| Остановлен именно контейнер, а не только заголовок | `docker service ps lab3_api --no-trunc` после hook | целевой task в `Shutdown`, новый task с новым hostname; target X-Instance-Id исчез | те же файлы |
| Повтор POST с тем же Idempotency-Key не создаёт дубль | smoke + `student-tests/test_lab3.py::test_03/06` | 201, тот же Message | `evidence/02-public-smoke.txt`, `evidence/03-student-tests.txt` |
| Конкурентный повтор с одним ключом через разные реплики | `python student-tests/idempotency_probe.py` | 32 запроса, 2 реплики, 1 message_id, 1 запись в истории | `evidence/04-idempotency-concurrency.json` |
| Одинаковый ключ + другой body → 409 | smoke, student test_03 | 409 `conflict` | `evidence/02-public-smoke.txt`, `evidence/03-student-tests.txt` |
| Persistence: данные и сессия переживают restart API/БД/Valkey | `python tests/resilience.py --mode persistence --action-script scripts/restart.cmd` (make test-persistence — та же команда) | PASS, тот же bearer-токен, сообщение на месте | `evidence/10-persistence.txt` |
| Health/live, readiness, timeouts, SIGTERM согласованы | `docker service inspect`; `evidence/09` | live не зависит от БД; ready проверяет БД+схему+Valkey; бюджет остановки 7 s, stop grace 15 s; Traefik 2 s/1 s/1 s | `evidence/09-infrastructure.txt` |
| Период проверок и максимальное обнаружение отказа | Traefik labels | до 3 s по health-check; наблюдаемое восстановление 2.97–3.02 s | `evidence/05`, `evidence/06`, `evidence/09` |
| Последовательная остановка каждой реплики с восстановлением | два прогона failover + restore | обе задачи останавливались по очереди, между ними 2/2 running | `evidence/05`, `evidence/06` |
| RPS/ошибки/время восстановления собраны | failover-прогоны | 126/15 ≈ 8.4 RPS и 123/15 ≈ 8.2 RPS только успешных POST во время отказа; ошибки переходного периода 2 и 5; recovery 3.016/2.969 s | `evidence/05`, `evidence/06` |
| CPU/RAM-лимиты, API не публикует порты, нет `container_name` | `docker service inspect`; `docker stack services` | limits/reservations заданы; API ports `null`; имя сервиса Swarm, не контейнера | `evidence/09-infrastructure.txt` |
| Секреты и хранилища общие только там, где нужно | `docker secret`, `docker service inspect` | Postgres/Valkey только backend, секреты файлами; API видит только свои секреты | `evidence/09` |
| Rolling update проверен под нагрузкой | `scripts/rolling-update.*` во время `tests/load.py` | 5351 успешных, 75 ошибок (1.38%), 212.7 RPS; обе задачи заменены start-first | `evidence/08-rolling-update-under-load.txt` |
| Миграции выполняются однократно и совместимы | одна задача `lab3_migrate`; `alembic current/upgrade/check` | Complete, head=0002, повторный upgrade без `Running upgrade`, `alembic check` чист | `evidence/09-infrastructure.txt` |
| Уровень 4: общая идемпотентность проверена параллельно | idempotency_probe + test_02 | 32/32 ответа 201, 1 message id | `evidence/04`, `evidence/03` |
## Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
### Нагрузочный профиль
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
Генератор `tests/load.py` — замкнутый цикл (closed loop), 4–6 потоков, каждый
поток делает последовательный POST и не повторяет ошибки. Это throughput
HTTP-подтверждений, а не точный счётчик COMMIT; генератор ограничен клиентом и
страдает coordinated omission. Все пользователи и сообщения синтетические.
| Профиль | Длительность | Concurrency | Успешные | Ошибки | RPS | p50 / p95 / p99, ms |
| --- | ---: | ---: | ---: | ---: | ---: | --- |
| Базовая линия, без вмешательства | 30 s | 4 | 6598 | 0 | 219.25 | 16 / 32 / 63 |
| Rolling update двух API-задач | 25 s | 6 | 5351 | 75 (1.38%) | 212.71 | 31 / 62 / 94 |
CPU/RAM во время базовой линии: API.1 92.7% CPU / 91 MiB, API.2 78.9% / 80 MiB,
PostgreSQL 26.1% / 51 MiB, Valkey 2.0% / 8.7 MiB, Traefik 15.7% / 33.6 MiB.
Набор данных на момент снятия: 48 users, 19 chats, 21 912 messages,
21 912 idempotency rows, БД 20 MB. Сырые JSON — `evidence/load-baseline.json`,
`evidence/rolling-load.json`; сводки — `evidence/07`, `evidence/08`.
### Отказы API-реплик
| Воздействие | Что ожидали | Что наблюдали | Восстановление / потери |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
| Остановлена реплика 1 (target `db8a74090b22`) | вторая реплика продолжает read/write, подтверждённые сообщения целы | 126 успешных POST за 15 s, 2 переходных отказа, целевой task `Shutdown`, новый task с новым hostname | первая успешная запись через 3.016 s; дублей нет |
| Остановлена реплика 2 (target `ab398ccdbed4`) | то же после restore | 123 успешных POST, 5 переходных отказов, target `Shutdown` | 2.969 s; дублей нет |
Публичный тест перед отказом наблюдал ровно 2 разных `X-Instance-Id`, после
отказа — только живую/новую задачу. Повторные POST с исходным ключом после
неопределённого результата не создали вторую строку: тест отдельно проверяет
уникальность текстов и сообщений в истории. Это отказ **процесса/задачи**, а не
узла: потеря Docker-хоста не тестировалась.
### Rolling update
Гипотеза: start-first замена по одной задаче не роняет весь API. Наблюдение:
новая задача 3.0.2 стала Running, затем старая 3.0.0 перешла в Shutdown;
обе задачи заменены, сервис остался 2/2. Во время замены 75 из 5426 запросов
(1.38%) не получили 201 — это окно, когда Traefik ещё держал старую задачу,
а её listener уже закрылся. Потери подтверждённых записей не было: ошибки
клиент мог безопасно повторить, идемпотентность защищает от дублей. Нулевого
простоя (zero downtime) не заявляю; это измеренный, а не идеализированный
результат.
### Идемпотентность
- 32 одновременных POST с одним `Idempotency-Key` и одинаковым телом через две
реплики: все 201, один `message_id`, одна запись в истории, ответы совпадают.
- Тот же ключ с другим телом: 409.
- Разные пользователи и разные чаты с одинаковым ключом: независимые сообщения.
- Ключи длиной 1 и 128 приняты; пустой, с пробелом, `/` и >128 — 400.
- Строка идемпотентности и сообщение пишутся одной транзакцией; повтор после
потери ответа возвращает исходный объект, а не создаёт новый.
## Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
- **Один Docker host**. Swarm из одного manager/worker не переживает потерю
узла; PostgreSQL, Valkey и Traefik — единственные экземпляры и остаются SPOF.
Это не трек 5 и не заявление об HA. Для отказоустойчивости нужны ≥3 manager
nodes, репликация PostgreSQL, кворум Valkey/Redis и внешний LB.
- **Traefik** — единственная публичная точка; его падение останавливает доступ.
Swarm перезапустит задачу, но на одном узле это не защищает от потери узла.
- **Rolling update не zero-downtime**: 1.38% ошибок в измеренном прогоне.
Причина — окно между закрытием listener старой задачи и её исключением из
Traefik. Следующий шаг — pre-stop drain через собственный SIGTERM hook
(сначала выставлять readiness 503 и ждать исключения из LB, затем закрывать
listener), после чего повторить профиль.
- **Идемпотентность**: строки старше 24 часов не удаляются фоновым GC, а
игнорируются (при повторном использовании ключа старая строка заменяется).
Это учебное упрощение; на больших объёмах нужен периодический cleanup.
Хэш тела в lab3 включает только `text` (полей вложений ещё нет); при lab4
канонизация должна включить `attachment_ids`.
- **Схема и откат**: миграция 0002 аддитивна, но новый код требует таблицу.
Откат образа к lab2-коду без идемпотентности технически возможен, однако
контракт lab3 тогда не выполняется; blue/green со смешанными версиями не
проверялся. Readiness блокирует трафик до head-ревизии.
- **Сессии и AOF**: `appendfsync everysec` допускает потерю примерно последней
секунды сессионных записей при аварии хоста; рестарт процесса/задачи этого не
вызывает. TTL не продлевается рестартом.
- **Измерения**: closed-loop генератор и Python-клиент на том же хосте,
Docker Desktop виртуализирован; абсолютные RPS не переносимы на другую
машину. Сравнивать можно только одинаковые профили на этом стенде.
- **Секреты**: локальные файлы `secrets/` и `.env` не входят в Git; при
публикации PR их нужно создать заново. В отчёте и evidence токенов нет.
## Ответы на вопросы защиты
- **Отказ процесса vs отказ узла.** В работе остановлена одна Swarm task
(контейнер): вторая task продолжает обслуживать трафик, а Swarm создаёт новую
с другим hostname. Отказ узла затронул бы и API, и единственные PostgreSQL,
Valkey и Traefik; этот стенд его не выдерживает.
- **Почему depends_on/healthcheck — не балансировщик.** Они управляют порядком
запуска и перезапуском, но не маршрутизируют запросы и не выводят backend из
ротации. Ротацию и проверку готовности выполняет Traefik, а Swarm —
перепланирование задач.
- **Какие POST можно повторять.** Повторять можно только POST сообщения с тем
же `Idempotency-Key`: сервер атомарно связывает ключ с сообщением и вернёт
тот же объект. POST создания чата и загрузки файла в lab3 не идемпотентны;
их прозрачный retry создал бы второй объект.
- **Что сломается при локальных сессиях.** При добавлении реплик токен,
выданный одной, не найдётся в памяти другой: пользователь получит 401 при
переключении LB. В этой работе сессии вынесены в общий Valkey, поэтому
токен работает на любой реплике.
+38
View File
@@ -0,0 +1,38 @@
# Конфигурация Alembic. URL базы здесь намеренно не задан: он приходит из
# окружения (DATABASE_URL или DATABASE_URL_FILE) и подставляется migrations/env.py.
[alembic]
script_location = migrations
prepend_sys_path = src
[loggers]
keys = root,sqlalchemy,alembic
[handlers]
keys = console
[formatters]
keys = plain
[logger_root]
level = WARNING
handlers = console
qualname =
[logger_sqlalchemy]
level = WARNING
handlers =
qualname = sqlalchemy.engine
[logger_alembic]
level = INFO
handlers =
qualname = alembic
[handler_console]
class = StreamHandler
args = (sys.stderr,)
level = NOTSET
formatter = plain
[formatter_plain]
format = %(levelname)s [%(name)s] %(message)s
+15
View File
@@ -0,0 +1,15 @@
Лабораторная 3 — offline проверки контракта
Дата: 2026-10-30, хост Windows 10 Pro, Python 3.11.9 (venv), Docker 28.0.1.
$ python scripts/check_contract.py
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.
$ python scripts/validate_openapi.py
PASS: full OpenAPI 3.1 and JSON Schema validation; application NOT tested.
Проверки не запускают приложение; они подтверждают, что skeleton-контракт и
Python-скрипты не изменены и синтаксически корректны.
Примечание: make в этом окружении (MSYS под sandbox) падает на создании signal pipe
(Win32 error 5), поэтому те же цели запущены напрямую интерпретатором Python.
На Linux/macOS команды make check и make validate выполняются как в README.
+12
View File
@@ -0,0 +1,12 @@
Лабораторная 3 — публичный smoke через единую точку входа
Дата: 2026-10-30, BASE_URL=http://127.0.0.1:8080 (Traefik -> 2 API tasks).
$ python tests/smoke.py --base-url http://127.0.0.1:8080
PASS: lab3 public API scenario; infrastructure and grading evidence remain separate.
Что проверено публичным сценарием: health/live и health/ready, регистрация,
Basic -> Bearer, X-User-Id не подменяет сессию, чат, два сообщения, keyset-пагинация,
ошибки 400/401/404/409, обязательный Idempotency-Key, повтор с тем же ключом
возвращает тот же Message, другой body с тем же ключом -> 409, отсутствие ключа -> 400,
logout. Клиент tests/client.py дополнительно требует непустые X-Request-Id и
X-Instance-Id на каждом ответе, включая ошибки.
+18
View File
@@ -0,0 +1,18 @@
Собственные проверки лабораторной 3
Дата: 2026-10-30, BASE_URL=http://127.0.0.1:8080.
$ python student-tests/run_all.py --base-url http://127.0.0.1:8080
BASE_URL = http://127.0.0.1:8080
test_01_at_least_two_instances_and_stable_header ... ok
test_02_concurrent_same_key_through_lb_creates_one_message ... ok
test_03_same_key_other_body_conflicts ... ok
test_04_key_scope_user_and_chat ... ok
test_05_key_validation ... ok
test_06_uncertain_retry_is_safe ... ok
Ran 6 tests in 1.737s
OK
test_02 одновременно отправляет 24 POST с одним Idempotency-Key через LB,
требует не менее двух разных X-Instance-Id и ровно одно сообщение в истории.
+13
View File
@@ -0,0 +1,13 @@
{
"command": "python student-tests/idempotency_probe.py",
"date": "2026-10-30",
"base_url": "http://127.0.0.1:8080",
"concurrent_requests": 32,
"elapsed_seconds": 0.812,
"statuses": [201],
"distinct_instances": ["1cacbb68717a", "79d280e76835"],
"distinct_message_ids": 1,
"history_matches": 1,
"all_responses_identical": true,
"note": "32 одновременных POST с одним ключом и одним телом прошли через две разные реплики; создано одно сообщение, все ответы побайтно совпадают."
}
+27
View File
@@ -0,0 +1,27 @@
Отказ первой API-реплики (public failover + прямое доказательство контейнера)
Дата: 2026-10-30, стек lab3, 2 API tasks за Traefik.
Public scenario (публичный тест не печатает target, только observed_instances/successes):
$ python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd --base-url http://127.0.0.1:8080
Executing explicit failover hook; hook output suppressed to avoid leaking secrets.
{"observed_instances_before": 2, "successful_writes": 126, "failed_attempts": 2, "first_recovery_seconds": 3.016}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
Operator evidence — остановлен именно контейнер, а не только заголовок:
$ TARGET_INSTANCE_ID=<X-Instance-Id из /health/live>
TARGET_INSTANCE_ID=db8a74090b22
stopping instance db8a74090b22 container db8a74090b22abb82912382eb619c8afe63c17c4e0074b6456cf0e06c1c14257
instance db8a74090b22 stopped
hook_seconds=3.172
$ docker service ps lab3_api --no-trunc
...
jp7oc0mllaoxx8trn9mibtn55 lab3_api.1 ... Running Running about a minute ago
kyybq2fofgzaom5jq42k564f6 lab3_api.2 ... Ready Pending less than a second ago
xujfndn4hslzoetuaepijcsx2 \_ lab3_api.2 ... Shutdown Complete less than a second ago
...
api restored: 2 running tasks and readiness OK
Наблюдение: target container id исчез из running, Swarm создал новую задачу с новым
hostname; X-Instance-Id остановленной реплики больше не встречается в ответах.
Ошибки переходного периода: 2 попытки POST, все повторены с исходным ключом.
+25
View File
@@ -0,0 +1,25 @@
Отказ второй API-реплики (public failover + прямое доказательство контейнера)
Дата: 2026-10-30, тот же стек после restore.
Public scenario (публичный тест не печатает target, только observed_instances/successes):
$ python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd --base-url http://127.0.0.1:8080
Executing explicit failover hook; hook output suppressed to avoid leaking secrets.
{"observed_instances_before": 2, "successful_writes": 123, "failed_attempts": 5, "first_recovery_seconds": 2.969}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
Operator evidence:
TARGET_INSTANCE_ID=ab398ccdbed4
stopping instance ab398ccdbed4 container ab398ccdbed4e4cb11f2ff896496619d8e6b3fa05c5257c6a7fa43b1f51e8df1
instance ab398ccdbed4 stopped
hook_seconds=2.872
$ docker service ps lab3_api --no-trunc
...
kks674tpkb604f4151ycyf8kp lab3_api.1 ... Ready Pending less than a second ago
jp7oc0mllaoxx8trn9mibtn55 \_ lab3_api.1 ... Shutdown Complete less than a second ago
kyybq2fofgzaom5jq42k564f6 lab3_api.2 ... Running Running 27 seconds ago
...
api restored: 2 running tasks and readiness OK
Последовательно остановлены обе наблюдаемые реплики; каждая остановка завершилась
возвратом к двум running tasks перед следующей.
+23
View File
@@ -0,0 +1,23 @@
Базовый профиль нагрузки без вмешательства
Дата: 2026-10-30, closed-loop POST /messages, concurrency 4, длительность 30 s.
$ python tests/load.py --base-url http://127.0.0.1:8080 --duration 30 --concurrency 4 --output evidence/load-baseline.json
{
"successful_requests": 6598,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 219.254,
"successful_latency_ms": {"p50": 16.0, "p95": 32.0, "p99": 63.0},
"elapsed_seconds": 30.093
}
$ docker stats --no-stream (фрагмент во время нагрузки)
lab3_api.1 cpu=92.67% mem=91.16MiB / 384MiB
lab3_api.2 cpu=78.91% mem=79.94MiB / 384MiB
lab3_valkey.1 cpu=2.00% mem=8.72MiB / 256MiB
lab3_postgres.1 cpu=26.09% mem=51.03MiB / 512MiB
lab3_traefik.1 cpu=15.68% mem=33.64MiB / 128MiB
Ограничения метода: closed-loop генератор ограничен клиентом и страдает coordinated
omission; это throughput HTTP-подтверждений, а не точное число COMMIT. Время
измерения включает Python-клиент на том же хосте.
+34
View File
@@ -0,0 +1,34 @@
Rolling update под нагрузкой (start-first, parallelism 1)
Дата: 2026-10-30.
До обновления:
$ docker service ps lab3_api --filter desired-state=running --format '{{.Name}} {{.CurrentState}}'
lab3_api.1 Running about a minute ago
lab3_api.2 Running 8 minutes ago
$ python tests/load.py --base-url http://127.0.0.1:8080 --duration 25 --concurrency 6 --output evidence/rolling-load.json &
$ powershell scripts/hooks.ps1 -Mode rollout # build 3.0.2 + docker service update --image ... --update-order start-first --update-parallelism 1 --update-delay 5s
rollout_exit=0
После обновления:
$ docker service ps lab3_api --no-trunc
lab3_api.1 ... mtusi-messenger-lab3:3.0.2 Running 22 seconds ago
lab3_api.1 \_ ... mtusi-messenger-lab3:3.0.0 Shutdown 16 seconds ago
lab3_api.2 ... mtusi-messenger-lab3:3.0.2 Running 10 seconds ago
lab3_api.2 \_ ... mtusi-messenger-lab3:3.0.0 Shutdown 4 seconds ago
Load summary во время замены:
{
"duration_seconds": 25,
"concurrency": 6,
"successful_requests": 5351,
"failed_requests": 75,
"error_ratio": 0.013822,
"successful_rps": 212.713,
"successful_latency_ms": {"p50": 31.0, "p95": 62.0, "p99": 94.0}
}
Swarm заменил обе задачи по одной, start-first: новая задача сначала стала healthy,
затем останавливалась старая. 75 ошибок (1.38%) — короткое окно, когда Traefik ещё
держал старую задачу в ротации, а её listener уже закрылся. После обновления обе
задачи работают на новом image ID; публичный smoke и student-tests снова PASS.
+66
View File
@@ -0,0 +1,66 @@
Инфраструктурные доказательства лабораторной 3
Дата: 2026-10-30. Хост: MAIBENBEN MaiBook X series, AMD Ryzen 7 5800H,
16 logical CPUs, 16 GiB RAM; Docker Desktop Linux VM: 6 CPUs / ~4 GiB,
Docker 28.0.1, Compose 2.33.1, Docker Swarm single manager + worker.
$ docker stack services lab3
ID NAME MODE REPLICAS IMAGE
boko201xtm13 lab3_api replicated 2/2 mtusi-messenger-lab3:3.0.0
ypbj98kgg7xc lab3_migrate replicated 0/1 mtusi-messenger-lab3:3.0.0
sw5pnexzicwb lab3_postgres replicated 1/1 postgres:16.15-bookworm
r1pqivnk4cav lab3_traefik replicated 1/1 traefik:v3.5.4 *:8080->8080/tcp
agf58r09tup9 lab3_valkey replicated 1/1 valkey/valkey:8.0.11-trixie
Migrate:
$ docker service ps lab3_migrate --no-trunc
jajruczmkdaz98ax8pxsz9a6o lab3_migrate.1 ... Shutdown Complete 25 minutes ago
$ docker exec <api> alembic current
0002_message_idempotency (head)
$ docker exec <api> alembic upgrade head
(no Running upgrade: схема уже на head)
$ docker exec <api> alembic check
No new upgrade operations detected.
API не публикует порты:
$ docker service inspect lab3_api --format '{{json .Endpoint.Ports}}'
null
Единственный опубликованный порт — Traefik:
$ docker service inspect lab3_traefik --format '{{json .Endpoint.Ports}}'
[{"Protocol":"tcp","TargetPort":8080,"PublishedPort":8080,"PublishMode":"ingress"}]
Ресурсы и политика:
$ docker service inspect lab3_api --format '{{json .Spec.TaskTemplate.Resources}}'
{"Limits":{"NanoCPUs":1000000000,"MemoryBytes":402653184},"Reservations":{"NanoCPUs":250000000,"MemoryBytes":134217728}}
то есть 1.0 CPU / 384 MiB limit, 0.25 CPU / 128 MiB reservation на реплику.
$ ... RestartPolicy
{"Condition":"any","Delay":1000000000,"MaxAttempts":0}
$ ... UpdateConfig
{"Parallelism":1,"Delay":5000000000,"FailureAction":"rollback","Monitor":10000000000,"MaxFailureRatio":0,"Order":"start-first"}
Traefik health/readiness:
$ docker service inspect lab3_api --format '{{json .Spec.Labels}}'
...
"traefik.http.services.messenger.loadbalancer.healthcheck.path":"/health/ready",
"traefik.http.services.messenger.loadbalancer.healthcheck.interval":"2s",
"traefik.http.services.messenger.loadbalancer.healthcheck.timeout":"1s",
"traefik.http.services.messenger.loadbalancer.healthcheck.unhealthyinterval":"1s",
...
Максимальное обнаружение отказа по health-check: interval 2 s + timeout 1 s = до 3 s
(плюс время уже начатого запроса). Наблюдённое восстановление записи: 2.97–3.02 s.
Процесс API:
$ docker exec <api> id
uid=10001(app) gid=10001(app) groups=10001(app)
$ docker exec <api> cat /proc/1/status
Uid: 10001 10001 10001 10001
CapEff: 0000000000000000
Схема идемпотентности:
$ docker exec <postgres> psql -U messenger -d messenger -c '\d message_idempotency'
user_id, chat_id, idempotency_key — составной PK;
request_hash text not null; message_id FK messages; created_at timestamptz;
CHECK длины ключа 1..128; индекс по created_at; FK на users/chats/messages.
Данные на момент снятия:
users=48, chats=19, messages=21912, idempotency_rows=21912, база 20 MB.
+20
View File
@@ -0,0 +1,20 @@
Проверка сохранности (persistence) лабораторной 3
Дата: 2026-10-30, стек lab3 на Docker Swarm.
$ python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://127.0.0.1:8080
Executing explicit persistence hook; hook output suppressed to avoid leaking secrets.
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.
Что сделал hook scripts/restart.cmd / scripts/restart.sh:
docker service update --force lab3_postgres
docker service update --force lab3_valkey
docker service update --force lab3_api
ожидание /health/ready до 120 s
Тома не удалялись: lab3_pgdata и lab3_valkeydata — named volumes Swarm.
После перезапуска тест прочитал ранее подтверждённое сообщение тем же bearer-токеном,
без повторного входа. TTL сессии принадлежит Valkey (AOF, appendfsync everysec),
поэтому рестарт процесса не продлевает и не сбрасывает срок.
Ограничение: это рестарт задач на одном host, а не отказ узла; потеря Docker-хоста
не покрыта. При аварии хоста возможна потеря последней секунды AOF-записей.
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 30.0,
"elapsed_seconds": 30.093,
"concurrency": 4,
"successful_requests": 6598,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 219.254,
"successful_latency_ms": {
"p50": 16.0,
"p95": 32.0,
"p99": 63.0
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 25.0,
"elapsed_seconds": 25.156,
"concurrency": 6,
"successful_requests": 5351,
"failed_requests": 75,
"error_ratio": 0.013822,
"successful_rps": 212.713,
"successful_latency_ms": {
"p50": 31.0,
"p95": 62.0,
"p99": 94.0
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+58
View File
@@ -0,0 +1,58 @@
"""Окружение Alembic: URL базы берётся из тех же переменных, что и у приложения."""
from __future__ import annotations
import asyncio
from logging.config import fileConfig
from alembic import context
from sqlalchemy import pool
from sqlalchemy.ext.asyncio import async_engine_from_config
from messenger.config import database_url_from_env
from messenger.schema import METADATA
config = context.config
if config.config_file_name is not None:
fileConfig(config.config_file_name)
# Сравнение идёт ровно с теми объектами, по которым работает приложение:
# расхождение между схемой и миграциями ловится на `alembic check`.
target_metadata = METADATA
def run_migrations_offline() -> None:
"""Режим без подключения: печатает SQL миграции, удобен для ревью."""
context.configure(
url=database_url_from_env(),
target_metadata=target_metadata,
literal_binds=True,
compare_type=True,
dialect_opts={"paramstyle": "named"},
)
with context.begin_transaction():
context.run_migrations()
def _run_migrations(connection) -> None:
context.configure(connection=connection, target_metadata=target_metadata, compare_type=True)
with context.begin_transaction():
context.run_migrations()
async def run_migrations_online() -> None:
"""Драйвер асинхронный (asyncpg), поэтому миграции идут через run_sync."""
section = config.get_section(config.config_ini_section, {})
section["sqlalchemy.url"] = database_url_from_env()
engine = async_engine_from_config(section, prefix="sqlalchemy.", poolclass=pool.NullPool)
try:
async with engine.connect() as connection:
await connection.run_sync(_run_migrations)
finally:
await engine.dispose()
if context.is_offline_mode():
run_migrations_offline()
else:
asyncio.run(run_migrations_online())
+24
View File
@@ -0,0 +1,24 @@
"""${message}
Revision ID: ${up_revision}
Revises: ${down_revision | comma,n}
Create Date: ${create_date}
"""
from __future__ import annotations
from alembic import op
import sqlalchemy as sa
${imports if imports else ""}
revision = ${repr(up_revision)}
down_revision = ${repr(down_revision)}
branch_labels = ${repr(branch_labels)}
depends_on = ${repr(depends_on)}
def upgrade() -> None:
${upgrades if upgrades else "pass"}
def downgrade() -> None:
${downgrades if downgrades else "pass"}
+103
View File
@@ -0,0 +1,103 @@
"""Начальная схема: пользователи, чаты, участники и сообщения
Revision ID: 0001_initial_schema
Revises:
Create Date: 2026-10-11
DDL написан вручную и повторяет src/messenger/schema.py: имена ограничений
и индексов совпадают, поэтому `alembic check` не находит расхождений между
схемой в базе и описанием, по которому работают запросы.
"""
from __future__ import annotations
import sqlalchemy as sa
from alembic import op
from sqlalchemy.dialects import postgresql
revision = "0001_initial_schema"
down_revision = None
branch_labels = None
depends_on = None
def upgrade() -> None:
op.create_table(
"users",
sa.Column("id", postgresql.UUID(as_uuid=True), 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",
postgresql.TIMESTAMP(timezone=True),
server_default=sa.text("now()"),
nullable=False,
),
sa.CheckConstraint(
"char_length(display_name) BETWEEN 1 AND 100", name="ck_users_display_name_length"
),
sa.CheckConstraint(r"username ~ '^[a-z0-9_]{3,32}$'", name="ck_users_username_format"),
sa.PrimaryKeyConstraint("id"),
sa.UniqueConstraint("username", name="uq_users_username"),
)
op.create_table(
"chats",
sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
sa.Column("title", sa.Text(), nullable=False),
sa.Column(
"created_at",
postgresql.TIMESTAMP(timezone=True),
server_default=sa.text("now()"),
nullable=False,
),
sa.CheckConstraint("char_length(title) BETWEEN 1 AND 100", name="ck_chats_title_length"),
sa.PrimaryKeyConstraint("id"),
)
op.create_table(
"chat_members",
sa.Column("chat_id", postgresql.UUID(as_uuid=True), nullable=False),
sa.Column("user_id", postgresql.UUID(as_uuid=True), nullable=False),
sa.ForeignKeyConstraint(
["chat_id"], ["chats.id"], name="fk_chat_members_chat", ondelete="CASCADE"
),
sa.ForeignKeyConstraint(
["user_id"], ["users.id"], name="fk_chat_members_user", ondelete="RESTRICT"
),
sa.PrimaryKeyConstraint("chat_id", "user_id"),
)
op.create_index("ix_chat_members_user_id_chat_id", "chat_members", ["user_id", "chat_id"])
op.create_table(
"messages",
sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
sa.Column("chat_id", postgresql.UUID(as_uuid=True), nullable=False),
sa.Column("sender_id", postgresql.UUID(as_uuid=True), nullable=False),
sa.Column("text", sa.Text(), nullable=False),
sa.Column(
"created_at",
postgresql.TIMESTAMP(timezone=True),
server_default=sa.text("now()"),
nullable=False,
),
sa.CheckConstraint(
"text <> '' AND char_length(text) <= 4000", name="ck_messages_text_length"
),
sa.ForeignKeyConstraint(["chat_id"], ["chats.id"], name="fk_messages_chat", ondelete="CASCADE"),
sa.ForeignKeyConstraint(
["sender_id"], ["users.id"], name="fk_messages_sender", ondelete="RESTRICT"
),
sa.PrimaryKeyConstraint("id"),
)
# Порядок истории (created_at, id) и keyset-предикат обслуживает один индекс.
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_chat_id", table_name="chat_members")
op.drop_table("chat_members")
op.drop_table("chats")
op.drop_table("users")
@@ -0,0 +1,61 @@
"""Общая идемпотентность отправки сообщения
Revision ID: 0002_message_idempotency
Revises: 0001_initial_schema
Create Date: 2026-10-30
Таблица описана в src/messenger/schema.py; DDL повторяет имена ограничений и
индексов, чтобы alembic check не находил расхождений.
"""
from __future__ import annotations
import sqlalchemy as sa
from alembic import op
from sqlalchemy.dialects import postgresql
revision = "0002_message_idempotency"
down_revision = "0001_initial_schema"
branch_labels = None
depends_on = None
def upgrade() -> None:
op.create_table(
"message_idempotency",
sa.Column("user_id", postgresql.UUID(as_uuid=True), nullable=False),
sa.Column("chat_id", postgresql.UUID(as_uuid=True), nullable=False),
sa.Column("idempotency_key", sa.Text(), nullable=False),
sa.Column("request_hash", sa.Text(), nullable=False),
sa.Column("message_id", postgresql.UUID(as_uuid=True), nullable=False),
sa.Column(
"created_at",
postgresql.TIMESTAMP(timezone=True),
server_default=sa.text("now()"),
nullable=False,
),
sa.CheckConstraint(
"char_length(idempotency_key) BETWEEN 1 AND 128",
name="ck_message_idempotency_key_length",
),
sa.ForeignKeyConstraint(
["chat_id"], ["chats.id"], name="fk_message_idempotency_chat", ondelete="CASCADE"
),
sa.ForeignKeyConstraint(
["message_id"],
["messages.id"],
name="fk_message_idempotency_message",
ondelete="CASCADE",
),
sa.ForeignKeyConstraint(
["user_id"], ["users.id"], name="fk_message_idempotency_user", ondelete="CASCADE"
),
sa.PrimaryKeyConstraint("user_id", "chat_id", "idempotency_key"),
)
op.create_index(
"ix_message_idempotency_created_at", "message_idempotency", ["created_at"]
)
def downgrade() -> None:
op.drop_index("ix_message_idempotency_created_at", table_name="message_idempotency")
op.drop_table("message_idempotency")
+28
View File
@@ -0,0 +1,28 @@
# Рантайм-зависимости лабораторной 3: точное замыкание (top-level и транзитивные),
# получено `pip freeze` после установки на Python 3.11.9:
# pip install fastapi==0.141.1 uvicorn==0.53.0 "sqlalchemy[asyncio]==2.0.44" \
# asyncpg==0.30.0 alembic==1.16.5 redis==6.4.0 argon2-cffi==25.1.0
alembic==1.16.5
annotated-doc==0.0.5
annotated-types==0.8.0
anyio==4.15.1
argon2-cffi==25.1.0
argon2-cffi-bindings==26.1.0
asyncpg==0.30.0
cffi==2.1.1
click==8.5.0
fastapi==0.141.1
greenlet==3.5.6
h11==0.16.0
idna==3.20
Mako==1.4.3
MarkupSafe==3.0.4
pycparser==3.11
pydantic==2.14.0
pydantic_core==2.50.0
redis==6.4.0
SQLAlchemy==2.0.44
starlette==1.7.0
typing-inspection==0.4.4
typing_extensions==4.16.0
uvicorn==0.53.0
+37
View File
@@ -0,0 +1,37 @@
#!/bin/sh
# Create local Compose secrets under secrets/ (gitignored, never printed).
# Existing files are never overwritten, so rerunning the script is safe.
# Usage: sh scripts/bootstrap-secrets.sh
set -eu
root=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
dir="$root/secrets"
# Files are created with mode 600: group and other have no access.
umask 077
mkdir -p "$dir"
random_hex() {
head -c 32 /dev/urandom | od -An -tx1 | tr -d ' \n'
}
# write <name> <value>: keeps the current file if it already has content.
write() {
name=$1
value=$2
if [ -s "$dir/$name" ]; then
printf 'keep secrets/%s\n' "$name"
return 0
fi
printf '%s\n' "$value" > "$dir/$name"
printf 'create secrets/%s\n' "$name"
}
write postgres_password "$(random_hex)"
write cursor_secret "$(random_hex)"
write cache_url 'redis://valkey:6379/0'
# The password is hex, so the URL needs no percent-encoding.
write database_url "postgresql+asyncpg://messenger:$(cat "$dir/postgres_password")@postgres:5432/messenger"
printf 'done: %s\n' "$dir"
printf 'next: docker compose up -d --build\n'
+4
View File
@@ -0,0 +1,4 @@
@echo off
rem Windows wrapper for scripts/hooks.ps1 (deploy).
powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0hooks.ps1" -Mode deploy %*
exit /b %ERRORLEVEL%
+48
View File
@@ -0,0 +1,48 @@
#!/bin/sh
# Build the application image, create local Swarm secrets once, deploy the stack.
#
# Prerequisites: Docker Engine with Swarm mode (docker swarm init is done here if
# needed) and the files created by scripts/bootstrap-secrets.sh. No secret value
# is printed. This is the one documented bootstrap sequence for stack.yaml.
set -eu
root=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
cd "$root"
# The public failover test invokes the action script without a shell; it must be
# executable on POSIX. Git may not preserve the mode on a Windows checkout.
chmod +x scripts/stop-one.sh scripts/restore.sh scripts/restart.sh scripts/rolling-update.sh scripts/deploy.sh 2>/dev/null || true
stack=${STACK_NAME:-lab3}
image=${API_IMAGE:-mtusi-messenger-lab3:3.0.0}
# Single host uses the locally built image; multi-node requires a registry and
# RESOLVE_IMAGE=always after `docker push` (see REPORT.md).
resolve=${RESOLVE_IMAGE:-never}
state=$(docker info --format '{{.Swarm.LocalNodeState}}')
if [ "$state" != "active" ]; then
docker swarm init >/dev/null
fi
sh scripts/bootstrap-secrets.sh
for name in database_url cache_url postgres_password cursor_secret; do
if ! docker secret inspect "${stack}_${name}" >/dev/null 2>&1; then
docker secret create "${stack}_${name}" "secrets/${name}" >/dev/null
fi
done
docker build -t "$image" .
API_IMAGE="$image" docker stack deploy --resolve-image "$resolve" -c stack.yaml "$stack"
i=0
while [ "$i" -lt 90 ]; do
if curl -fsS "http://127.0.0.1:${APP_PORT:-8080}/health/ready" >/dev/null 2>&1; then
printf 'deployed: http://127.0.0.1:%s (image %s)\n' "${APP_PORT:-8080}" "$image"
docker stack services "$stack"
exit 0
fi
i=$((i + 1))
sleep 2
done
printf 'stack did not become ready within 180s\n' >&2
docker stack services "$stack" >&2 || true
exit 1
+158
View File
@@ -0,0 +1,158 @@
# Windows twin of scripts/deploy.sh, stop-one.sh, restore.sh, restart.sh and
# rolling-update.sh. The public resilience test launches an action script with
# Popen([script]) without a shell; on native Windows a .cmd wrapper is required.
#
# X-Instance-Id is the Swarm task container hostname, so a target is resolved by
# inspecting running task containers, not by trusting the header alone.
param(
[Parameter(Mandatory = $true)]
[ValidateSet('deploy', 'stop-one', 'restore', 'restart', 'rollout')]
[string]$Mode,
[string]$Image = ''
)
$ErrorActionPreference = 'Stop'
$root = Split-Path -Parent (Split-Path -Parent $MyInvocation.MyCommand.Path)
Set-Location $root
$stack = if ($env:STACK_NAME) { $env:STACK_NAME } else { 'lab3' }
$service = "$stack" + '_api'
$port = if ($env:APP_PORT) { $env:APP_PORT } else { '8080' }
$resolveImage = if ($env:RESOLVE_IMAGE) { $env:RESOLVE_IMAGE } else { 'never' }
if (-not $Image) {
$Image = if ($env:API_IMAGE) { $env:API_IMAGE } else { 'mtusi-messenger-lab3:3.0.0' }
}
function Invoke-Docker {
param([Parameter(ValueFromRemainingArguments = $true)][string[]]$Arguments)
& docker @Arguments
if ($LASTEXITCODE -ne 0) {
throw "docker $($Arguments -join ' ') failed with exit code $LASTEXITCODE"
}
}
function Test-Ready {
try {
$response = Invoke-WebRequest -UseBasicParsing -Uri "http://127.0.0.1:$port/health/ready" -TimeoutSec 3
return $response.StatusCode -eq 200
} catch {
return $false
}
}
function Wait-Ready {
param([int]$Seconds = 180)
$deadline = (Get-Date).AddSeconds($Seconds)
while ((Get-Date) -lt $deadline) {
if (Test-Ready) { return }
Start-Sleep -Seconds 2
}
throw "stack did not become ready within $Seconds seconds"
}
function Get-RunningTasks {
return @(& docker service ps -q $service --filter desired-state=running)
}
function Find-TargetContainer {
param([string]$Target)
foreach ($task in (Get-RunningTasks)) {
$container = (& docker inspect -f '{{.Status.ContainerStatus.ContainerID}}' $task 2>$null)
if (-not $container) { continue }
$hostname = (& docker inspect -f '{{.Config.Hostname}}' $container 2>$null)
if ($hostname -eq $Target) { return $container }
}
return $null
}
function New-HexSecret {
$bytes = New-Object byte[] 32
[System.Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
return (-join ($bytes | ForEach-Object { $_.ToString('x2') }))
}
function Ensure-SecretFiles {
New-Item -ItemType Directory -Force -Path 'secrets' | Out-Null
$passwordPath = Join-Path 'secrets' 'postgres_password'
$password = if ((Test-Path $passwordPath) -and (Get-Item $passwordPath).Length -gt 0) {
(Get-Content $passwordPath -Raw).Trim()
} else {
New-HexSecret
}
$defaults = [ordered]@{
postgres_password = $password
cursor_secret = (New-HexSecret)
cache_url = 'redis://valkey:6379/0'
database_url = "postgresql+asyncpg://messenger:$password@postgres:5432/messenger"
}
foreach ($name in $defaults.Keys) {
$path = Join-Path 'secrets' $name
if (-not (Test-Path $path) -or (Get-Item $path).Length -eq 0) {
Set-Content -NoNewline -Encoding ascii -Path $path -Value $defaults[$name]
}
}
}
function Ensure-Secrets {
$names = @('database_url', 'cache_url', 'postgres_password', 'cursor_secret')
$existing = @(& docker secret ls --format '{{.Name}}')
foreach ($name in $names) {
$secret = "$stack" + '_' + $name
if ($existing -notcontains $secret) {
Invoke-Docker secret create $secret (Join-Path 'secrets' $name) | Out-Null
}
}
}
switch ($Mode) {
'deploy' {
$state = (& docker info --format '{{.Swarm.LocalNodeState}}').Trim()
if ($state -ne 'active') { Invoke-Docker swarm init | Out-Null }
Ensure-SecretFiles
Ensure-Secrets
Invoke-Docker build -t $Image . | Out-Null
$env:API_IMAGE = $Image
Invoke-Docker stack deploy --resolve-image $resolveImage -c stack.yaml $stack | Out-Null
Wait-Ready
& docker stack services $stack
}
'stop-one' {
$target = $env:TARGET_INSTANCE_ID
if (-not $target) { throw 'TARGET_INSTANCE_ID is required' }
$container = Find-TargetContainer $target
if (-not $container) { throw "target instance $target not found among running tasks" }
Write-Output "stopping instance $target container $container"
Invoke-Docker stop --time 15 $container | Out-Null
# Swarm may already be creating a replacement task; the target container
# itself was stopped by id and its X-Instance-Id will not be served again.
Write-Output "instance $target stopped"
}
'restore' {
Invoke-Docker service update --restart-condition any --replicas 2 $service | Out-Null
$running = @(Get-RunningTasks).Count
if ($running -lt 2) { Invoke-Docker service update --force $service | Out-Null }
$deadline = (Get-Date).AddSeconds(120)
while ((Get-Date) -lt $deadline) {
$running = @(Get-RunningTasks).Count
if ($running -ge 2 -and (Test-Ready)) {
Write-Output "api restored: $running running tasks and readiness OK"
exit 0
}
Start-Sleep -Seconds 2
}
throw 'api did not recover within 120s'
}
'restart' {
foreach ($name in @('postgres', 'valkey', 'api')) {
$svc = $stack + '_' + $name
Write-Output "restarting $svc"
Invoke-Docker service update --force $svc | Out-Null
}
Wait-Ready
Write-Output 'stack ready after restart'
}
'rollout' {
Invoke-Docker build --build-arg APP_REVISION=$Image -t $Image . | Out-Null
Invoke-Docker service update --image $Image --update-order start-first --update-parallelism 1 --update-delay 5s --update-failure-action rollback $service | Out-Null
& docker service ps $service --no-trunc
}
}
+4
View File
@@ -0,0 +1,4 @@
@echo off
rem Windows wrapper for scripts/hooks.ps1 (restart).
powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0hooks.ps1" -Mode restart %*
exit /b %ERRORLEVEL%
+23
View File
@@ -0,0 +1,23 @@
#!/bin/sh
# Restart API and every state store without deleting volumes.
#
# Used by make test-persistence. Sessions live in Valkey with AOF and users,
# chats and messages in PostgreSQL, so the same bearer token and data survive.
set -eu
stack=${STACK_NAME:-lab3}
for service in "${stack}_postgres" "${stack}_valkey" "${stack}_api"; do
printf 'restarting %s\n' "$service"
docker service update --force "$service" >/dev/null
done
i=0
while [ "$i" -lt 60 ]; do
if curl -fsS "http://127.0.0.1:${APP_PORT:-8080}/health/ready" >/dev/null 2>&1; then
printf 'stack ready after restart\n'
exit 0
fi
i=$((i + 1))
sleep 2
done
printf 'stack did not become ready within 120s\n' >&2
exit 1
+4
View File
@@ -0,0 +1,4 @@
@echo off
rem Windows wrapper for scripts/hooks.ps1 (restore).
powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0hooks.ps1" -Mode restore %*
exit /b %ERRORLEVEL%
+27
View File
@@ -0,0 +1,27 @@
#!/bin/sh
# Restore the API service to 2 replicas after scripts/stop-one.sh.
set -eu
stack=${STACK_NAME:-lab3}
service="${stack}_api"
# Swarm normally creates the replacement itself after stopping one task. This hook
# restores the declared replica count and waits for two healthy tasks; a forced
# rolling update is used only when the service is still under-replicated.
docker service update --restart-condition any --replicas 2 "$service" >/dev/null
running=$(docker service ps -q "$service" --filter desired-state=running | wc -l | tr -d ' ')
if [ "$running" -lt 2 ]; then
docker service update --force "$service" >/dev/null
fi
i=0
while [ "$i" -lt 60 ]; do
running=$(docker service ps -q "$service" --filter desired-state=running | wc -l | tr -d ' ')
if [ "$running" -ge 2 ] && curl -fsS "http://127.0.0.1:${APP_PORT:-8080}/health/ready" >/dev/null 2>&1; then
printf 'api restored: %s running tasks and readiness OK\n' "$running"
exit 0
fi
i=$((i + 1))
sleep 2
done
printf 'api did not recover within 120s\n' >&2
exit 1
+4
View File
@@ -0,0 +1,4 @@
@echo off
rem Windows wrapper for scripts/hooks.ps1 (rollout).
powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0hooks.ps1" -Mode rollout %*
exit /b %ERRORLEVEL%
+20
View File
@@ -0,0 +1,20 @@
#!/bin/sh
# Start-first rolling update of the API service under load.
#
# Swarm replaces one task at a time (parallelism 1), waiting for the new task's
# health check before removing the old one. Traefik keeps routing to ready tasks.
set -eu
root=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
cd "$root"
stack=${STACK_NAME:-lab3}
image=${API_IMAGE:-mtusi-messenger-lab3:3.0.1}
docker build --build-arg APP_REVISION="$image" -t "$image" .
docker service update \
--image "$image" \
--update-order start-first \
--update-parallelism 1 \
--update-delay 5s \
--update-failure-action rollback \
"${stack}_api"
docker service ps "${stack}_api" --no-trunc
+4
View File
@@ -0,0 +1,4 @@
@echo off
rem Windows wrapper for scripts/hooks.ps1 (stop-one).
powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0hooks.ps1" -Mode stop-one %*
exit /b %ERRORLEVEL%
+50
View File
@@ -0,0 +1,50 @@
#!/bin/sh
# Stop exactly one API replica selected by TARGET_INSTANCE_ID.
#
# The public failover test sets TARGET_INSTANCE_ID to the X-Instance-Id that served
# the test request. In this stack X-Instance-Id is the container hostname, so the
# target task is found by inspecting every running task's container and stopped by
# container id. Swarm then creates a *new* task (new hostname) after its restart
# delay: the laboratory explicitly allows that, and the test checks that the old
# X-Instance-Id disappears from responses. Restore with scripts/restore.sh.
set -eu
stack=${STACK_NAME:-lab3}
service="${stack}_api"
target=${TARGET_INSTANCE_ID:-}
if [ -z "$target" ]; then
printf 'TARGET_INSTANCE_ID is required\n' >&2
exit 2
fi
if ! docker service inspect "$service" >/dev/null 2>&1; then
printf 'service %s not found\n' "$service" >&2
exit 3
fi
find_container() {
# Prints the container id whose hostname equals $target; empty if not found.
for task in $(docker service ps -q "$service" --filter desired-state=running); do
container=$(docker inspect -f '{{.Status.ContainerStatus.ContainerID}}' "$task" 2>/dev/null || true)
[ -n "$container" ] || continue
hostname=$(docker inspect -f '{{.Config.Hostname}}' "$container" 2>/dev/null || true)
if [ "$hostname" = "$target" ]; then
printf '%s\n' "$container"
return 0
fi
done
return 0
}
container=$(find_container)
if [ -z "$container" ]; then
printf 'target instance %s not found among running tasks\n' "$target" >&2
exit 4
fi
printf 'stopping instance %s container %s\n' "$target" "$container"
docker stop --time 15 "$container" >/dev/null
# Swarm may already be creating a replacement task with a different hostname;
# the target container itself was stopped by id and is no longer served.
printf 'instance %s stopped\n' "$target"
+5
View File
@@ -0,0 +1,5 @@
"""Мессенджер на PostgreSQL и Valkey: лабораторная 3 курса HighLoad (MTUSI)."""
__all__ = ["__version__"]
__version__ = "3.0.0"
+38
View File
@@ -0,0 +1,38 @@
"""Точка входа: `python -m messenger` (в контейнере — PID 1)."""
from __future__ import annotations
import sys
import uvicorn
from .app import create_app
from .config import Config, ConfigError
def main() -> int:
try:
config = Config.from_env()
except ConfigError as exc:
print(f"config error: {exc}", file=sys.stderr)
return 2
uvicorn.run(
create_app(config),
host=config.host,
port=config.port,
# Свой формат логов: uvicorn не пишет access-лог с query-строкой.
log_config=None,
access_log=False,
# Верхняя граница ожидания активных запросов при остановке.
timeout_graceful_shutdown=config.graceful_shutdown_seconds,
# Один процесс: лимиты пула соединений заданы на процесс, а не на весь стенд.
workers=1,
server_header=False,
date_header=False,
proxy_headers=False,
)
return 0
if __name__ == "__main__":
raise SystemExit(main())
+16
View File
@@ -0,0 +1,16 @@
"""Правила доступа: чужой объект неотличим от отсутствующего (404, не 403)."""
from __future__ import annotations
from uuid import UUID
from .domain import ChatRecord, UserRecord
from .errors import not_found
from .repository import Repository
async def visible_chat(repository: Repository, chat_id: UUID, user: UserRecord) -> ChatRecord:
"""Возвращает чат, если пользователь его участник, иначе 404."""
chat = await repository.chat_for_member(chat_id, user.id)
if chat is None:
raise not_found("Чат не найден")
return chat
+127
View File
@@ -0,0 +1,127 @@
"""Сборка ASGI-приложения: жизненный цикл, обработчики ошибок, маршруты."""
from __future__ import annotations
import asyncio
import logging
from contextlib import asynccontextmanager
from typing import AsyncIterator, Awaitable, Callable
from fastapi import FastAPI
from . import __version__
from .config import Config
from .cursor import CursorCodec
from .db import Database
from .errorhandlers import register_error_handlers
from .logging_setup import configure_logging, log
from .middleware import RequestContextMiddleware
from .routers import auth, chats, health, messages, users
from .sessions import RedisSessionStore
ROUTERS = (health.router, auth.router, users.router, chats.router, messages.router)
async def _release(
logger: logging.Logger, resource: str, closer: Callable[[], Awaitable[None]]
) -> None:
"""Освобождает ресурс: отказ зависимости при остановке не должен мешать выходу."""
try:
await closer()
except Exception as exc:
log(
logger,
logging.WARNING,
"release_failed",
exc_info=exc,
resource=resource,
error=type(exc).__name__,
)
def build_fastapi(config: Config, logger: logging.Logger) -> FastAPI:
"""Создаёт приложение FastAPI с обработчиками ошибок и маршрутами."""
@asynccontextmanager
async def lifespan(app: FastAPI) -> AsyncIterator[None]:
# Клиенты создаются здесь, но к зависимостям не подключаются: старт не
# должен падать, если PostgreSQL или Valkey поднимаются одновременно с API.
# За трафик отвечает готовность, а не перезапуск контейнера.
database = Database(config)
sessions = RedisSessionStore(
config.cache_url, config.session_ttl_seconds, config.cache_timeout_seconds
)
app.state.database = database
app.state.sessions = sessions
app.state.cursors = CursorCodec(config.cursor_secret)
app.state.draining = False
log(
logger,
logging.INFO,
"startup",
version=__version__,
host=config.host,
port=config.port,
shutdown_budget_seconds=config.shutdown_budget_seconds,
storage="postgresql",
instance_id=config.instance_id,
session_store=config.session_store,
session_ttl_seconds=config.session_ttl_seconds,
db_pool_size=config.db_pool_size,
db_max_overflow=config.db_max_overflow,
db_pool_timeout_seconds=config.db_pool_timeout_seconds,
db_connect_timeout_seconds=config.db_connect_timeout_seconds,
db_command_timeout_seconds=config.db_command_timeout_seconds,
db_statement_timeout_ms=config.db_statement_timeout_ms,
cache_timeout_seconds=config.cache_timeout_seconds,
)
if config.binds_to_loopback:
# Bind на loopback внутри контейнера не виден через published port.
log(
logger,
logging.WARNING,
"loopback_bind",
detail="bind на loopback недоступен через published port контейнера",
)
try:
yield
finally:
app.state.draining = True
log(
logger,
logging.INFO,
"shutdown_begin",
drain_seconds=config.shutdown_drain_seconds,
note="слушающий сокет уже закрыт: новые соединения не принимаются",
)
if config.shutdown_drain_seconds > 0:
# Окно управляемого снятия с балансировки: процесс ещё жив,
# но трафик на него уже не идёт.
await asyncio.sleep(config.shutdown_drain_seconds)
await _release(logger, "sessions", sessions.close)
await _release(logger, "database", database.dispose)
app.state.draining = False
log(logger, logging.INFO, "shutdown_complete")
app = FastAPI(
title="MTUSI Messenger — лабораторная 3",
version=__version__,
lifespan=lifespan,
# Источник истины — contracts/openapi.json: свои /docs и /openapi.json не публикуются.
docs_url=None,
redoc_url=None,
openapi_url=None,
)
register_error_handlers(app, logger)
for router in ROUTERS:
app.include_router(router)
return app
def create_app(
config: Config | None = None,
logger: logging.Logger | None = None,
) -> RequestContextMiddleware:
"""Создаёт приложение; разбор окружения идёт здесь, а не при импорте модуля."""
config = Config.from_env() if config is None else config
logger = configure_logging(config.log_level, config.env) if logger is None else logger
return RequestContextMiddleware(build_fastapi(config, logger), logger, config.instance_id)
+290
View File
@@ -0,0 +1,290 @@
"""Конфигурация процесса: значения приходят только из переменных окружения.
Секреты читаются либо напрямую (`NAME`), либо из файла (`NAME_FILE`) — второй
вариант используется стендом Swarm и Docker secrets. Значения секретов
никогда не попадают в текст ошибки.
"""
from __future__ import annotations
import hashlib
import os
import re
import socket
import uuid
from dataclasses import dataclass
from pathlib import Path
from typing import Mapping
DEFAULT_HOST = "0.0.0.0"
DEFAULT_PORT = 8080
DEFAULT_ENV = "lab"
DEFAULT_LOG_LEVEL = "info"
DEFAULT_GRACEFUL_SHUTDOWN_SECONDS = 5
DEFAULT_SHUTDOWN_DRAIN_SECONDS = 0.0
MAX_SHUTDOWN_BUDGET_SECONDS = 10
DEFAULT_SESSION_TTL_SECONDS = 3600
MIN_SESSION_TTL_SECONDS = 1
MAX_SESSION_TTL_SECONDS = 86400
DEFAULT_DB_POOL_SIZE = 5
MAX_DB_POOL_SIZE = 32
DEFAULT_DB_MAX_OVERFLOW = 5
MAX_DB_MAX_OVERFLOW = 32
# Бюджет отказа: недоступный PostgreSQL обязан превращаться в 503 быстрее, чем
# клиент успеет отправить повтор. Установление соединения ограничено отдельно от
# запроса, потому что при остановленном контейнере тормозит именно разрешение
# имени `postgres` встроенным DNS Docker (замеры — в отчёте и в evidence).
DEFAULT_DB_POOL_TIMEOUT_SECONDS = 2.0
MAX_DB_POOL_TIMEOUT_SECONDS = 30.0
DEFAULT_DB_CONNECT_TIMEOUT_SECONDS = 1.5
MAX_DB_CONNECT_TIMEOUT_SECONDS = 30.0
DEFAULT_DB_COMMAND_TIMEOUT_SECONDS = 2.5
MAX_DB_COMMAND_TIMEOUT_SECONDS = 60.0
# Серверный предел строже клиентского: ошибку выдаёт PostgreSQL, а не asyncpg.
DEFAULT_DB_STATEMENT_TIMEOUT_MS = 2000
MAX_DB_STATEMENT_TIMEOUT_MS = 60000
DEFAULT_CACHE_TIMEOUT_SECONDS = 1.0
MAX_CACHE_TIMEOUT_SECONDS = 10.0
ENVIRONMENTS = ("lab", "dev", "prod")
LOG_LEVELS = ("debug", "info", "warning", "error")
# Хранилище сессий: в этой работе реализован только вариант с Valkey/Redis.
# Значение SESSION_STORE=postgres из .env.example стенду не соответствует —
# соответствие переменных описано в REPORT.md.
SESSION_STORES = ("redis",)
DEFAULT_SESSION_STORE = "redis"
DATABASE_URL_SCHEME = "postgresql+asyncpg://"
CACHE_URL_SCHEMES = ("redis://", "rediss://", "unix://")
LOOPBACK_HOSTS = ("127.0.0.1", "localhost", "::1")
# X-Instance-Id должен быть безопасным значением HTTP-заголовка. В Swarm
# контейнер получает hostname, стабильный на всё время жизни процесса; это же
# значение позволяет action-скрипту найти конкретную задачу service.
INSTANCE_ID_PATTERN = re.compile(r"^[A-Za-z0-9._:-]{1,128}$")
class ConfigError(RuntimeError):
"""Некорректная конфигурация. Текст не раскрывает значений переменных."""
def _choice(environ: Mapping[str, str], name: str, default: str, allowed: tuple[str, ...]) -> str:
value = environ.get(name, default).strip().lower()
if value not in allowed:
raise ConfigError(f"{name} must be one of: {', '.join(allowed)}")
return value
def _integer(environ: Mapping[str, str], name: str, default: int, minimum: int, maximum: int) -> int:
raw = environ.get(name, "").strip()
if not raw:
return default
try:
value = int(raw)
except ValueError:
raise ConfigError(f"{name} must be an integer") from None
if not minimum <= value <= maximum:
raise ConfigError(f"{name} must be within {minimum}..{maximum}")
return value
def _seconds(environ: Mapping[str, str], name: str, default: float, maximum: float) -> float:
raw = environ.get(name, "").strip()
if not raw:
return default
try:
value = float(raw)
except ValueError:
raise ConfigError(f"{name} must be a number of seconds") from None
if not 0.0 <= value <= maximum:
raise ConfigError(f"{name} must be within 0..{maximum}")
return value
def _secret(environ: Mapping[str, str], name: str) -> str | None:
"""Читает секрет из `NAME` или из файла `NAME_FILE`; иначе возвращает None."""
direct = environ.get(name, "").strip()
path = environ.get(f"{name}_FILE", "").strip()
if direct and path:
raise ConfigError(f"{name} and {name}_FILE must not be set together")
if direct:
return direct
if not path:
return None
try:
value = Path(path).read_text(encoding="utf-8").strip()
except OSError:
raise ConfigError(f"{name}_FILE must point to a readable file") from None
if not value:
raise ConfigError(f"{name}_FILE must not be empty")
return value
def _required_secret(environ: Mapping[str, str], name: str) -> str:
value = _secret(environ, name)
if value is None:
raise ConfigError(f"{name} or {name}_FILE is required")
return value
def _checked_url(value: str, *, name: str, schemes: tuple[str, ...]) -> str:
"""Схема проверяется до создания клиента: ошибка видна на старте процесса."""
if not value.startswith(schemes):
raise ConfigError(f"{name} must start with one of: {', '.join(schemes)}")
return value
def database_url_from_env(environ: Mapping[str, str] | None = None) -> str:
"""URL базы из окружения (`DATABASE_URL` или `DATABASE_URL_FILE`).
Отдельная функция нужна миграциям: Alembic не должен требовать переменные
Valkey и настройки сессий, которые к схеме отношения не имеют.
"""
source: Mapping[str, str] = os.environ if environ is None else environ
return _checked_url(
_required_secret(source, "DATABASE_URL"),
name="DATABASE_URL",
schemes=(DATABASE_URL_SCHEME,),
)
def instance_id_from_env(environ: Mapping[str, str]) -> str:
"""Стабильный идентификатор реплики для заголовка X-Instance-Id.
По умолчанию — hostname контейнера: Docker Swarm назначает его на время
жизни задачи, и по нему action-скрипт может однозначно найти контейнер.
Явный INSTANCE_ID удобен для локального запуска без Docker. Небезопасное
для HTTP-заголовка значение заменяется детерминированным хэшем.
"""
raw = environ.get("INSTANCE_ID", "").strip() or socket.gethostname().strip()
if not raw:
raw = "api-" + uuid.uuid4().hex[:12]
if INSTANCE_ID_PATTERN.fullmatch(raw):
return raw
return "api-" + hashlib.sha256(raw.encode("utf-8")).hexdigest()[:16]
@dataclass(frozen=True)
class Config:
"""Разобранная конфигурация процесса."""
host: str
port: int
env: str
instance_id: str
log_level: str
graceful_shutdown_seconds: int
shutdown_drain_seconds: float
database_url: str
cache_url: str
session_store: str
session_ttl_seconds: int
db_pool_size: int
db_max_overflow: int
db_pool_timeout_seconds: float
db_connect_timeout_seconds: float
db_command_timeout_seconds: float
db_statement_timeout_ms: int
cache_timeout_seconds: float
cursor_secret: bytes | None
def __post_init__(self) -> None:
"""Сумма остановки не должна превышать требование лабы."""
if self.shutdown_budget_seconds > MAX_SHUTDOWN_BUDGET_SECONDS:
raise ConfigError(
"GRACEFUL_SHUTDOWN_SECONDS + SHUTDOWN_DRAIN_SECONDS must be "
f"at most {MAX_SHUTDOWN_BUDGET_SECONDS} seconds"
)
@property
def shutdown_budget_seconds(self) -> float:
"""Худшее время от SIGTERM до выхода; требование лабы — не более 10 секунд."""
return self.graceful_shutdown_seconds + self.shutdown_drain_seconds
@property
def binds_to_loopback(self) -> bool:
return self.host in LOOPBACK_HOSTS
@classmethod
def from_env(cls, environ: Mapping[str, str] | None = None) -> "Config":
source: Mapping[str, str] = os.environ if environ is None else environ
env = _choice(source, "APP_ENV", DEFAULT_ENV, ENVIRONMENTS)
host = source.get("APP_HOST", DEFAULT_HOST).strip()
if not host:
raise ConfigError("APP_HOST must not be empty")
default_log_level = "debug" if env == "dev" else DEFAULT_LOG_LEVEL
database_url = database_url_from_env(source)
cache_url = _checked_url(
_required_secret(source, "CACHE_URL"),
name="CACHE_URL",
schemes=CACHE_URL_SCHEMES,
)
cursor_secret = _secret(source, "CURSOR_SECRET")
return cls(
host=host,
port=_integer(source, "APP_PORT", DEFAULT_PORT, 1, 65535),
env=env,
instance_id=instance_id_from_env(source),
log_level=_choice(source, "LOG_LEVEL", default_log_level, LOG_LEVELS),
graceful_shutdown_seconds=_integer(
source, "GRACEFUL_SHUTDOWN_SECONDS", DEFAULT_GRACEFUL_SHUTDOWN_SECONDS, 1, 10
),
shutdown_drain_seconds=_seconds(
source, "SHUTDOWN_DRAIN_SECONDS", DEFAULT_SHUTDOWN_DRAIN_SECONDS, 5.0
),
database_url=database_url,
cache_url=cache_url,
session_store=_choice(
source, "SESSION_STORE", DEFAULT_SESSION_STORE, SESSION_STORES
),
session_ttl_seconds=_integer(
source,
"SESSION_TTL_SECONDS",
DEFAULT_SESSION_TTL_SECONDS,
MIN_SESSION_TTL_SECONDS,
MAX_SESSION_TTL_SECONDS,
),
db_pool_size=_integer(
source, "DB_POOL_SIZE", DEFAULT_DB_POOL_SIZE, 1, MAX_DB_POOL_SIZE
),
db_max_overflow=_integer(
source, "DB_MAX_OVERFLOW", DEFAULT_DB_MAX_OVERFLOW, 0, MAX_DB_MAX_OVERFLOW
),
db_pool_timeout_seconds=_seconds(
source,
"DB_POOL_TIMEOUT_SECONDS",
DEFAULT_DB_POOL_TIMEOUT_SECONDS,
MAX_DB_POOL_TIMEOUT_SECONDS,
),
db_connect_timeout_seconds=_seconds(
source,
"DB_CONNECT_TIMEOUT_SECONDS",
DEFAULT_DB_CONNECT_TIMEOUT_SECONDS,
MAX_DB_CONNECT_TIMEOUT_SECONDS,
),
db_command_timeout_seconds=_seconds(
source,
"DB_COMMAND_TIMEOUT_SECONDS",
DEFAULT_DB_COMMAND_TIMEOUT_SECONDS,
MAX_DB_COMMAND_TIMEOUT_SECONDS,
),
db_statement_timeout_ms=_integer(
source,
"DB_STATEMENT_TIMEOUT_MS",
DEFAULT_DB_STATEMENT_TIMEOUT_MS,
1,
MAX_DB_STATEMENT_TIMEOUT_MS,
),
cache_timeout_seconds=_seconds(
source,
"CACHE_TIMEOUT_SECONDS",
DEFAULT_CACHE_TIMEOUT_SECONDS,
MAX_CACHE_TIMEOUT_SECONDS,
),
cursor_secret=None if cursor_secret is None else cursor_secret.encode("utf-8"),
)
+23
View File
@@ -0,0 +1,23 @@
"""Контекст одного HTTP-запроса: данные живут в ASGI-scope."""
from __future__ import annotations
from typing import Any, MutableMapping
CONTEXT_KEY = "messenger.request_context"
REQUEST_ID = "request_id"
USER_ID = "user_id"
def context_of(scope: MutableMapping[str, Any]) -> dict[str, Any]:
"""Возвращает (при необходимости создавая) словарь контекста запроса."""
context = scope.get(CONTEXT_KEY)
if context is None:
context = {}
scope[CONTEXT_KEY] = context
return context
def request_context(request: Any) -> dict[str, Any]:
"""Контекст по объекту Request/WebSocket."""
return context_of(request.scope)
+119
View File
@@ -0,0 +1,119 @@
"""Keyset-курсор: подписан ключом процесса и привязан к ресурсу (kind + scope)."""
from __future__ import annotations
import base64
import binascii
import hashlib
import hmac
import json
import secrets
from dataclasses import dataclass
from uuid import UUID
from .domain import Position, parse_rfc3339_z
CURSOR_VERSION = 1
SIGNATURE_BYTES = 16
SEPARATOR = "."
KIND_CHATS = "chats"
KIND_MESSAGES = "messages"
class InvalidCursor(ValueError):
"""Курсор повреждён, подделан или выпущен для другого ресурса."""
def _b64encode(raw: bytes) -> str:
return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
def _b64decode(value: str) -> bytes:
return base64.urlsafe_b64decode(value + "=" * (-len(value) % 4))
def _parse_timestamp(value: object) -> str:
"""Проверяет, что метка времени — RFC 3339 UTC с суффиксом Z."""
if not isinstance(value, str):
raise InvalidCursor("cursor timestamp is not a string")
try:
parse_rfc3339_z(value)
except ValueError:
raise InvalidCursor("cursor timestamp is not RFC 3339 UTC with Z suffix") from None
return value
@dataclass(frozen=True)
class Cursor:
"""Позиция последнего отданного элемента выборки."""
kind: str
scope: str
created_at: str
item_id: str
@property
def position(self) -> Position:
"""Место в порядке (created_at, id), с которого продолжается выборка."""
return (parse_rfc3339_z(self.created_at), UUID(self.item_id))
class CursorCodec:
"""Кодирует и проверяет курсоры ключом, известным только процессу."""
def __init__(self, key: bytes | None = None) -> None:
self._key = secrets.token_bytes(32) if key is None else key
def encode(self, kind: str, scope: str, created_at: str, item_id: str) -> str:
payload = json.dumps(
{
"v": CURSOR_VERSION,
"kind": kind,
"scope": scope,
"created_at": created_at,
"id": item_id,
},
ensure_ascii=False,
separators=(",", ":"),
sort_keys=True,
).encode("utf-8")
signature = hmac.new(self._key, payload, hashlib.sha256).digest()[:SIGNATURE_BYTES]
return _b64encode(payload) + SEPARATOR + _b64encode(signature)
def decode(self, token: str, *, kind: str, scope: str) -> Cursor:
"""Разбирает курсор или поднимает InvalidCursor — наружу это всегда 400."""
if not isinstance(token, str) or not token:
raise InvalidCursor("cursor is empty")
encoded_payload, separator, encoded_signature = token.partition(SEPARATOR)
if not separator:
raise InvalidCursor("cursor has no signature part")
try:
payload = _b64decode(encoded_payload)
signature = _b64decode(encoded_signature)
except (binascii.Error, ValueError):
raise InvalidCursor("cursor is not valid base64url") from None
expected = hmac.new(self._key, payload, hashlib.sha256).digest()[:SIGNATURE_BYTES]
if not hmac.compare_digest(signature, expected):
raise InvalidCursor("cursor signature mismatch")
try:
data = json.loads(payload.decode("utf-8"))
except (UnicodeDecodeError, ValueError):
raise InvalidCursor("cursor payload is not valid JSON") from None
if not isinstance(data, dict) or data.get("v") != CURSOR_VERSION:
raise InvalidCursor("unsupported cursor version")
cursor = Cursor(
kind=str(data.get("kind", "")),
scope=str(data.get("scope", "")),
created_at=_parse_timestamp(data.get("created_at")),
item_id=str(data.get("id", "")),
)
try:
UUID(cursor.item_id)
except ValueError:
raise InvalidCursor("cursor id is not a UUID") from None
if cursor.kind != kind or cursor.scope != scope:
raise InvalidCursor("cursor belongs to another resource")
return cursor
+74
View File
@@ -0,0 +1,74 @@
"""Асинхронный доступ к PostgreSQL: движок, ограниченный пул и таймауты."""
from __future__ import annotations
from contextlib import asynccontextmanager
from typing import AsyncIterator
from sqlalchemy import text
from sqlalchemy.exc import ProgrammingError
from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker, create_async_engine
from .config import Config
APPLICATION_NAME = "messenger"
# Незакоммиченная транзакция не должна держать соединение пула бесконечно.
IDLE_IN_TRANSACTION_TIMEOUT_MS = 10000
class Database:
"""Владеет пулом соединений; сессия живёт ровно один HTTP-запрос."""
def __init__(self, config: Config) -> None:
self._engine: AsyncEngine = create_async_engine(
config.database_url,
# Пул ограничен: лишние запросы ждут освобождения соединения.
pool_size=config.db_pool_size,
max_overflow=config.db_max_overflow,
pool_timeout=config.db_pool_timeout_seconds,
pool_pre_ping=True,
pool_recycle=1800,
connect_args={
# Границы на круг asyncpg, на установление соединения (включая
# разрешение имени) и на стороне сервера.
"timeout": config.db_connect_timeout_seconds,
"command_timeout": config.db_command_timeout_seconds,
"server_settings": {
"application_name": APPLICATION_NAME,
"statement_timeout": str(config.db_statement_timeout_ms),
"idle_in_transaction_session_timeout": str(IDLE_IN_TRANSACTION_TIMEOUT_MS),
},
},
)
self._sessions = async_sessionmaker(self._engine, expire_on_commit=False)
@asynccontextmanager
async def session(self) -> AsyncIterator[AsyncSession]:
"""Сессия на один запрос: закрывается всегда, откат делает SQLAlchemy."""
session = self._sessions()
try:
yield session
finally:
await session.close()
async def ping(self) -> None:
"""Проверка готовности: одно дешёвое обращение к серверу."""
async with self.session() as session:
await session.execute(text("SELECT 1"))
async def schema_revision(self) -> str | None:
"""Текущая ревизия Alembic; None, если таблицы версий ещё нет.
До завершения однократной миграции API обязан быть неготовым, иначе
Traefik отправит трафик на процесс, который не может писать в схему.
Отсутствие таблицы — это не отказ соединения, а нормальное состояние
холодного старта, поэтому исключение гасится здесь.
"""
async with self.session() as session:
try:
return await session.scalar(text("SELECT version_num FROM alembic_version"))
except ProgrammingError:
return None
async def dispose(self) -> None:
await self._engine.dispose()
+119
View File
@@ -0,0 +1,119 @@
"""Зависимости FastAPI: PostgreSQL, хранилище сессий и текущий пользователь.
Личность в этой работе определяется только сессией: заголовок X-User-Id из ЛР1
не читается нигде и не влияет на ответ.
"""
from __future__ import annotations
from collections.abc import AsyncIterator
from dataclasses import dataclass
from typing import Annotated
from fastapi import Depends, Header, Request
from sqlalchemy.ext.asyncio import AsyncSession
from .context import USER_ID, request_context
from .cursor import CursorCodec
from .db import Database
from .domain import UserRecord
from .errors import BASIC_CHALLENGE, unauthorized
from .repository import Repository
from .security import parse_basic, parse_bearer
from .sessions import SessionStore
AUTHORIZATION_HEADER = "Authorization"
@dataclass(frozen=True)
class BasicCredentials:
"""Разобранные учётные данные входа по Basic."""
username: str
password: str
def get_database(request: Request) -> Database:
"""Пул соединений живёт в состоянии приложения: один на процесс."""
return request.app.state.database
def get_sessions(request: Request) -> SessionStore:
"""Хранилище сессий живёт в состоянии приложения."""
return request.app.state.sessions
def get_cursors(request: Request) -> CursorCodec:
"""Кодек курсоров привязан к процессу: ключ подписи не покидает память."""
return request.app.state.cursors
DatabaseDep = Annotated[Database, Depends(get_database)]
SessionsDep = Annotated[SessionStore, Depends(get_sessions)]
CursorsDep = Annotated[CursorCodec, Depends(get_cursors)]
async def get_db_session(database: DatabaseDep) -> AsyncIterator[AsyncSession]:
"""Сессия БД на один запрос: закрывается вместе с ответом."""
async with database.session() as session:
yield session
DbSession = Annotated[AsyncSession, Depends(get_db_session)]
def get_repository(session: DbSession) -> Repository:
"""Репозиторий поверх сессии запроса: всё SQL живёт в нём."""
return Repository(session)
RepositoryDep = Annotated[Repository, Depends(get_repository)]
def basic_credentials(
authorization: Annotated[str | None, Header(alias=AUTHORIZATION_HEADER)] = None,
) -> BasicCredentials:
"""Учётные данные входа: единственное место, где принимается схема Basic."""
parsed = parse_basic(authorization)
if parsed is None:
raise unauthorized("Требуется Basic-аутентификация", challenge=BASIC_CHALLENGE)
return BasicCredentials(username=parsed[0], password=parsed[1])
BasicCredentialsDep = Annotated[BasicCredentials, Depends(basic_credentials)]
def bearer_token(
authorization: Annotated[str | None, Header(alias=AUTHORIZATION_HEADER)] = None,
) -> str:
"""Токен сессии из заголовка Authorization; иначе 401 с Bearer-челленджем."""
token = parse_bearer(authorization)
if token is None:
raise unauthorized("Требуется Bearer-токен сессии")
return token
BearerToken = Annotated[str, Depends(bearer_token)]
async def get_current_user(
request: Request,
sessions: SessionsDep,
repository: RepositoryDep,
token: BearerToken,
) -> UserRecord:
"""Владелец действующей сессии.
Порядок важен: сначала сессия в Valkey, потом пользователь в PostgreSQL.
Неизвестный или истёкший токен — это 401, а не «анонимный доступ».
"""
state = await sessions.resolve(token)
if state is None:
raise unauthorized("Сессия не найдена или истекла")
user = await repository.get_user(state.user_id)
if user is None:
raise unauthorized("Владелец сессии больше не существует")
request_context(request)[USER_ID] = str(user.id)
return user
CurrentUser = Annotated[UserRecord, Depends(get_current_user)]
+84
View File
@@ -0,0 +1,84 @@
"""Сущности предметной области, порядок сортировки и формат метки времени."""
from __future__ import annotations
from dataclasses import dataclass
from datetime import datetime, timezone
from typing import Protocol, Sequence
from uuid import UUID
def utc_now() -> datetime:
return datetime.now(timezone.utc)
def rfc3339_z(moment: datetime) -> str:
"""RFC 3339 в UTC с суффиксом Z и микросекундной точностью."""
return moment.astimezone(timezone.utc).isoformat(timespec="microseconds").replace("+00:00", "Z")
def parse_rfc3339_z(value: str) -> datetime:
"""Разбирает метку в формате `rfc3339_z`; иначе ValueError."""
if not value.endswith("Z"):
raise ValueError("timestamp is not UTC with Z suffix")
return datetime.fromisoformat(value[:-1] + "+00:00")
class Sortable(Protocol):
"""Общая часть записей: пара, по которой строится порядок и keyset-курсор.
Порядок выборок — (created_at, id) по возрастанию. UUID упорядочивается
своим целым значением (так же, как `uuid.UUID(x).int` в публичном smoke),
поэтому порядок PostgreSQL и порядок клиента совпадают.
"""
created_at: datetime
id: UUID
# Место в этом порядке, откуда продолжается выборка: пара (created_at, id).
Position = tuple[datetime, UUID]
class UsernameTaken(Exception):
"""username уже занят другим пользователем."""
class UnknownMembers(Exception):
"""В member_ids есть идентификаторы несуществующих пользователей."""
def __init__(self, member_ids: Sequence[UUID]) -> None:
super().__init__("unknown members")
self.member_ids = tuple(member_ids)
class IdempotencyConflict(Exception):
"""Тот же ключ идемпотентности использован с другим телом запроса."""
@dataclass(frozen=True)
class UserRecord:
id: UUID
username: str
display_name: str
created_at: datetime
@dataclass(frozen=True)
class ChatRecord:
id: UUID
title: str
member_ids: tuple[UUID, ...]
created_at: datetime
def has_member(self, user_id: UUID) -> bool:
"""Состав участников задаётся при создании и не меняется."""
return user_id in self.member_ids
@dataclass(frozen=True)
class MessageRecord:
id: UUID
chat_id: UUID
sender_id: UUID
text: str
created_at: datetime
+157
View File
@@ -0,0 +1,157 @@
"""Обработчики ошибок: единый конверт контракта и заголовки к нему."""
from __future__ import annotations
import logging
import uuid
from typing import Mapping
from fastapi import FastAPI, Request
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from redis.exceptions import RedisError
from sqlalchemy.exc import DataError, DisconnectionError, InterfaceError, OperationalError
from sqlalchemy.exc import TimeoutError as PoolTimeoutError
from starlette.exceptions import HTTPException as StarletteHTTPException
from .context import REQUEST_ID, request_context
from .errors import INTERNAL_ERROR, INVALID_REQUEST, UNAVAILABLE, ApiError, code_for_status
from .logging_setup import log
FALLBACK_MESSAGES: Mapping[int, str] = {
404: "Маршрут не найден",
405: "Метод не поддерживается для этого маршрута",
}
# Отказ критичной зависимости (PostgreSQL или Valkey): наружу 503 без деталей,
# подробности остаются в логе. Для клиента «сессии недоступны» и «база недоступна»
# выглядят одинаково — и это правильно, различать их он не должен.
#
# Здесь только отказы соединения и исчерпание пула. Более широкий SQLAlchemyError
# сюда не годится: он включает DataError, и тогда значение, которое PostgreSQL
# не может принять, выглядело бы как недоступность базы.
DEPENDENCY_ERRORS = (
OperationalError,
InterfaceError,
DisconnectionError,
PoolTimeoutError,
RedisError,
OSError,
)
DEPENDENCY_MESSAGE = "Сервис временно недоступен: критичная зависимость не отвечает"
DATA_ERROR_MESSAGE = "Значение поля не может быть сохранено"
def request_id_of(request: Request) -> str:
"""Идентификатор запроса; запасной вариант — если middleware не подключён."""
context = request_context(request)
identifier = context.get(REQUEST_ID)
if not identifier:
identifier = uuid.uuid4().hex
context[REQUEST_ID] = identifier
return identifier
def error_response(
request: Request,
status: int,
code: str,
message: str,
headers: Mapping[str, str] | None = None,
) -> JSONResponse:
"""Собирает конверт ошибки контракта; request_id совпадает с заголовком."""
identifier = request_id_of(request)
response_headers = {"X-Request-Id": identifier}
response_headers.update(headers or {})
return JSONResponse(
status_code=status,
content={"error": {"code": code, "message": message, "request_id": identifier}},
headers=response_headers,
)
def describe_validation_error(exc: RequestValidationError) -> str:
"""Краткое описание без значений полей: наружу уходит только расположение ошибки.
Значения сюда не попадают намеренно: среди них может быть пароль.
"""
errors = exc.errors()
if not errors:
return "Тело запроса не соответствует контракту"
first = errors[0]
if str(first.get("type", "")) == "json_invalid":
return "Тело запроса не является корректным JSON"
location = ".".join(
str(part)
for part in first.get("loc", ())
if part not in ("body", "query", "path", "header")
)
return f"Некорректный запрос: {location or 'body'}"
def register_error_handlers(app: FastAPI, logger: logging.Logger) -> None:
"""Ставит обработчики так, чтобы наружу не ушёл ответ без конверта."""
@app.exception_handler(ApiError)
async def handle_api_error(request: Request, exc: ApiError) -> JSONResponse:
return error_response(request, exc.status, exc.code, exc.message, exc.headers)
@app.exception_handler(RequestValidationError)
async def handle_validation_error(
request: Request, exc: RequestValidationError
) -> JSONResponse:
return error_response(request, 400, INVALID_REQUEST, describe_validation_error(exc))
@app.exception_handler(StarletteHTTPException)
async def handle_http_exception(
request: Request, exc: StarletteHTTPException
) -> JSONResponse:
status = exc.status_code
return error_response(
request,
status,
code_for_status(status),
FALLBACK_MESSAGES.get(status, "Запрос не может быть обработан"),
getattr(exc, "headers", None),
)
async def handle_dependency_failure(request: Request, exc: Exception) -> JSONResponse:
log(
logger,
logging.ERROR,
"dependency_unavailable",
exc_info=exc,
request_id=request_id_of(request),
error=type(exc).__name__,
)
return error_response(request, 503, UNAVAILABLE, DEPENDENCY_MESSAGE)
@app.exception_handler(DataError)
async def handle_data_error(request: Request, exc: DataError) -> JSONResponse:
"""Данные клиента, которые СУБД не в состоянии сохранить, — это 400.
На границе такие значения уже отсекаются; обработчик оставлен страховкой,
чтобы ошибка данных никогда не выдавалась за отказ зависимости.
"""
log(
logger,
logging.WARNING,
"invalid_stored_value",
request_id=request_id_of(request),
error=type(exc).__name__,
)
return error_response(request, 400, INVALID_REQUEST, DATA_ERROR_MESSAGE)
for error_type in DEPENDENCY_ERRORS:
app.add_exception_handler(error_type, handle_dependency_failure)
@app.exception_handler(Exception)
async def handle_unexpected(request: Request, exc: Exception) -> JSONResponse:
log(
logger,
logging.ERROR,
"unhandled_exception",
exc_info=exc,
request_id=request_id_of(request),
error=type(exc).__name__,
)
return error_response(request, 500, INTERNAL_ERROR, "Внутренняя ошибка сервера")
+78
View File
@@ -0,0 +1,78 @@
"""Ошибки API и единый конверт ответа контракта."""
from __future__ import annotations
from typing import Mapping
INVALID_REQUEST = "invalid_request"
UNAUTHORIZED = "unauthorized"
NOT_FOUND = "not_found"
CONFLICT = "conflict"
PAYLOAD_TOO_LARGE = "payload_too_large"
UNSUPPORTED_MEDIA_TYPE = "unsupported_media_type"
RATE_LIMITED = "rate_limited"
UNAVAILABLE = "unavailable"
INTERNAL_ERROR = "internal_error"
BASIC_CHALLENGE = 'Basic realm="messenger", charset="UTF-8"'
BEARER_CHALLENGE = 'Bearer realm="messenger"'
DEFAULT_CODE_BY_STATUS: Mapping[int, str] = {
400: INVALID_REQUEST,
401: UNAUTHORIZED,
403: UNAUTHORIZED,
404: NOT_FOUND,
405: INVALID_REQUEST,
409: CONFLICT,
413: PAYLOAD_TOO_LARGE,
415: UNSUPPORTED_MEDIA_TYPE,
429: RATE_LIMITED,
500: INTERNAL_ERROR,
503: UNAVAILABLE,
}
class ApiError(Exception):
"""Ошибка, которую можно безопасно показать клиенту в конверте контракта."""
def __init__(
self,
status: int,
code: str,
message: str,
headers: Mapping[str, str] | None = None,
) -> None:
super().__init__(message)
self.status = status
self.code = code
self.message = message
self.headers = dict(headers or {})
def code_for_status(status: int) -> str:
"""Подбирает код конверта для статуса, пришедшего извне контракта."""
if status in DEFAULT_CODE_BY_STATUS:
return DEFAULT_CODE_BY_STATUS[status]
return INTERNAL_ERROR if status >= 500 else INVALID_REQUEST
def invalid_request(message: str) -> ApiError:
return ApiError(400, INVALID_REQUEST, message)
def unauthorized(message: str, challenge: str = BEARER_CHALLENGE) -> ApiError:
"""401 с challenge схемы: Basic — только на создании сессии, иначе Bearer."""
return ApiError(401, UNAUTHORIZED, message, headers={"WWW-Authenticate": challenge})
def not_found(message: str) -> ApiError:
"""Чужой объект неотличим от отсутствующего: 403 не используется."""
return ApiError(404, NOT_FOUND, message)
def conflict(message: str) -> ApiError:
return ApiError(409, CONFLICT, message)
def unavailable(message: str) -> ApiError:
"""503: зависимость недоступна, отказ ограничен и не раскрывает внутренностей."""
return ApiError(503, UNAVAILABLE, message)
+26
View File
@@ -0,0 +1,26 @@
"""Проверка живости для Docker HEALTHCHECK: python -m messenger.healthcheck."""
from __future__ import annotations
import os
import urllib.error
import urllib.request
DEFAULT_PORT = "8080"
TIMEOUT_SECONDS = 2
def liveness_url() -> str:
port = os.environ.get("APP_PORT", DEFAULT_PORT).strip() or DEFAULT_PORT
return "http://127.0.0.1:%s/health/live" % port
def main() -> int:
try:
with urllib.request.urlopen(liveness_url(), timeout=TIMEOUT_SECONDS) as response:
return 0 if response.status == 200 else 1
except (urllib.error.URLError, OSError, ValueError):
return 1
if __name__ == "__main__":
raise SystemExit(main())
+36
View File
@@ -0,0 +1,36 @@
"""Идемпотентность POST сообщения: проверка ключа и канонический хэш тела."""
from __future__ import annotations
import hashlib
import json
import re
from .errors import invalid_request
# Контракт: ASCII [A-Za-z0-9._:-]{1,128}. Полное совпадение, а не поиск.
IDEMPOTENCY_KEY_PATTERN = re.compile(r"^[A-Za-z0-9._:-]{1,128}$")
def require_idempotency_key(value: str | None) -> str:
"""Возвращает валидный ключ или 400; отсутствие ключа — тоже 400."""
if value is None or not IDEMPOTENCY_KEY_PATTERN.fullmatch(value):
raise invalid_request(
"Idempotency-Key обязателен и должен соответствовать [A-Za-z0-9._:-]{1,128}"
)
return value
def message_request_hash(text: str) -> str:
"""Хэш семантически нормализованного тела запроса.
Порядок ключей JSON и отсутствие необязательных полей не должны менять
результат: в каноническую форму добавляется attachment_ids=[] (в lab3
вложений нет, но форма сохраняет совместимость с lab4).
"""
canonical = json.dumps(
{"attachment_ids": [], "text": text},
ensure_ascii=False,
separators=(",", ":"),
sort_keys=True,
)
return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+76
View File
@@ -0,0 +1,76 @@
"""Структурные логи в stdout: одна JSON-строка на событие, без тел и query-строки."""
from __future__ import annotations
import json
import logging
import sys
from datetime import datetime, timezone
class JsonFormatter(logging.Formatter):
"""Сериализует запись лога в компактный JSON без потери структуры."""
def format(self, record: logging.LogRecord) -> str:
payload: dict[str, object] = {
"ts": datetime.fromtimestamp(record.created, timezone.utc)
.isoformat(timespec="milliseconds")
.replace("+00:00", "Z"),
"level": record.levelname.lower(),
"logger": record.name,
"event": record.getMessage(),
}
payload.update(getattr(record, "fields", {}) or {})
if record.exc_info:
payload["exception"] = self.formatException(record.exc_info)
return json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
class _EnvironmentFilter(logging.Filter):
"""Добавляет метку окружения в каждую запись, включая логи uvicorn."""
def __init__(self, env: str) -> None:
super().__init__()
self._env = env
def filter(self, record: logging.LogRecord) -> bool:
fields = dict(getattr(record, "fields", {}) or {})
fields.setdefault("env", self._env)
record.fields = fields
return True
def configure_logging(level: str, env: str) -> logging.Logger:
"""Перенаправляет логи процесса в stdout в структурированном виде."""
handler = logging.StreamHandler(sys.stdout)
handler.setFormatter(JsonFormatter())
handler.addFilter(_EnvironmentFilter(env))
root = logging.getLogger()
root.handlers[:] = [handler]
root.setLevel(level.upper())
for name in ("uvicorn", "uvicorn.error", "uvicorn.access"):
logger = logging.getLogger(name)
logger.handlers[:] = []
logger.propagate = True
logging.getLogger("uvicorn.access").setLevel(logging.WARNING)
return logging.getLogger("messenger")
def log(
logger: logging.Logger,
level: int,
event: str,
exc_info: BaseException | None = None,
**fields: object,
) -> None:
"""Пишет событие с произвольными структурированными полями."""
if not logger.isEnabledFor(level):
return
logger.log(
level,
event,
extra={"fields": {k: v for k, v in fields.items() if v is not None}},
exc_info=exc_info,
)
+99
View File
@@ -0,0 +1,99 @@
"""Внешний ASGI-слой: X-Request-Id, X-Instance-Id (в том числе на 500) и access-лог."""
from __future__ import annotations
import logging
import re
import time
import uuid
from typing import Any, Awaitable, Callable, MutableMapping
from .context import REQUEST_ID, USER_ID, context_of
from .logging_setup import log
SAFE_REQUEST_ID = re.compile(r"^[A-Za-z0-9._:-]{1,128}$")
Scope = MutableMapping[str, Any]
Message = MutableMapping[str, Any]
Receive = Callable[[], Awaitable[Message]]
Send = Callable[[Message], Awaitable[None]]
ASGIApp = Callable[[Scope, Receive, Send], Awaitable[None]]
def incoming_request_id(scope: Scope) -> str | None:
"""Возвращает заголовок клиента, если он безопасен для логирования и ответа."""
for name, value in scope.get("headers") or ():
if name.lower() != b"x-request-id":
continue
try:
candidate = value.decode("ascii")
except UnicodeDecodeError:
return None
return candidate if SAFE_REQUEST_ID.match(candidate) else None
return None
def set_response_header(message: Message, name: bytes, value: bytes) -> None:
"""Идемпотентно выставляет заголовок в ASGI-сообщении ответа."""
headers = message.setdefault("headers", [])
lowered = name.lower()
for index, (key, _) in enumerate(headers):
if key.lower() == lowered:
headers[index] = (name, value)
return
headers.append((name, value))
class RequestContextMiddleware:
"""Присваивает запросу идентификатор, гарантирует заголовок и пишет access-лог."""
def __init__(self, app: ASGIApp, logger: logging.Logger, instance_id: str) -> None:
if not instance_id:
raise ValueError("instance_id must not be empty")
self._app = app
self._logger = logger
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 = incoming_request_id(scope) or uuid.uuid4().hex
context = context_of(scope)
context[REQUEST_ID] = request_id
started = time.perf_counter()
status_holder: dict[str, int] = {}
instance_id = self._instance_id.encode("ascii")
async def send_with_request_id(message: Message) -> None:
if message["type"] == "http.response.start":
status_holder["status"] = int(message["status"])
set_response_header(message, b"x-request-id", request_id.encode("ascii"))
# Значение стабильно на жизнь процесса; LB не переписывает его.
set_response_header(message, b"x-instance-id", instance_id)
await send(message)
try:
await self._app(scope, receive, send_with_request_id)
finally:
self._write_access_log(scope, status_holder.get("status"), started)
def _write_access_log(self, scope: Scope, status: int | None, started: float) -> None:
context = context_of(scope)
# Логируется шаблон маршрута, а не сырой путь: query-строка в лог не попадает.
route = getattr(scope.get("route"), "path", None)
endpoint = scope.get("endpoint")
log(
self._logger,
logging.INFO,
"request",
request_id=context.get(REQUEST_ID),
method=scope.get("method"),
route=route,
operation=None if endpoint is None else getattr(endpoint, "__name__", None),
matched=route is not None,
status=status,
duration_ms=round((time.perf_counter() - started) * 1000, 3),
user_id=context.get(USER_ID),
instance_id=self._instance_id,
)
+209
View File
@@ -0,0 +1,209 @@
"""Схемы запросов и ответов ровно по contracts/openapi.json."""
from __future__ import annotations
from typing import Literal
from uuid import UUID
from pydantic import BaseModel, ConfigDict, Field, field_validator
from .domain import ChatRecord, MessageRecord, UserRecord, rfc3339_z
from .sessions import IssuedSession
USERNAME_PATTERN = r"^[a-z0-9_]{3,32}$"
MIN_PASSWORD = 12
MAX_PASSWORD = 128
MAX_DISPLAY_NAME = 100
MAX_TITLE = 100
MAX_TEXT = 4000
MAX_MEMBERS = 100
MAX_LIMIT = 100
DEFAULT_LIMIT = 50
def _require_content(value: str, *, field: str) -> str:
"""Обязательная строка не может быть пустой или состоять из пробельных символов."""
if not value.strip():
raise ValueError(f"{field} must not be empty or contain only whitespace")
return value
def _visible(value: str, *, field: str, maximum: int) -> str:
"""Проверяет строку, которую предстоит сохранить в PostgreSQL.
U+0000 отвергается на границе: тип `text` его не хранит, и без этой проверки
ошибка данных клиента дошла бы до обработчика ошибок базы, где выглядела бы
отказом зависимости.
"""
_require_content(value, field=field)
if "\u0000" in value:
raise ValueError(f"{field} must not contain U+0000")
if len(value) > maximum:
raise ValueError(f"{field} must be at most {maximum} Unicode code points")
return value
class Health(BaseModel):
"""Тело ответа /health/live и /health/ready."""
model_config = ConfigDict(extra="forbid")
status: Literal["ok"] = "ok"
class User(BaseModel):
"""Публичное представление пользователя: ни пароля, ни сессий здесь нет."""
model_config = ConfigDict(extra="forbid")
id: UUID
username: str
display_name: str
created_at: str
@classmethod
def from_record(cls, record: UserRecord) -> "User":
return cls(
id=record.id,
username=record.username,
display_name=record.display_name,
created_at=rfc3339_z(record.created_at),
)
class CreateUser(BaseModel):
"""Регистрация: пароль приходит открытым текстом и дальше живёт только как хэш."""
model_config = ConfigDict(extra="forbid")
username: str = Field(pattern=USERNAME_PATTERN)
display_name: str
password: str = Field(min_length=MIN_PASSWORD, max_length=MAX_PASSWORD)
@field_validator("display_name")
@classmethod
def _check_display_name(cls, value: str) -> str:
return _visible(value, field="display_name", maximum=MAX_DISPLAY_NAME)
@field_validator("password")
@classmethod
def _check_password(cls, value: str) -> str:
"""Пароль из одних пробелов — пустое значение, а не секрет.
Пробелы внутри и по краям допустимы и не обрезаются: при входе пароль
сверяется целиком. U+0000 здесь не проверяется: в PostgreSQL попадает
только хэш, а не сам пароль.
"""
return _require_content(value, field="password")
class Session(BaseModel):
"""Выданная сессия: токен показывается клиенту один раз и в логи не попадает."""
model_config = ConfigDict(extra="forbid")
token: str
token_type: Literal["Bearer"] = "Bearer"
expires_at: str
user: User
@classmethod
def from_issued(cls, issued: IssuedSession, user: UserRecord) -> "Session":
return cls(
token=issued.token,
expires_at=rfc3339_z(issued.state.expires_at),
user=User.from_record(user),
)
class Chat(BaseModel):
model_config = ConfigDict(extra="forbid")
id: UUID
title: str
member_ids: list[UUID]
created_at: str
@classmethod
def from_record(cls, record: ChatRecord) -> "Chat":
return cls(
id=record.id,
title=record.title,
member_ids=list(record.member_ids),
created_at=rfc3339_z(record.created_at),
)
class CreateChat(BaseModel):
model_config = ConfigDict(extra="forbid")
title: str
member_ids: list[UUID]
@field_validator("title")
@classmethod
def _check_title(cls, value: str) -> str:
return _visible(value, field="title", maximum=MAX_TITLE)
@field_validator("member_ids")
@classmethod
def _check_member_ids(cls, value: list[UUID]) -> list[UUID]:
if not 1 <= len(value) <= MAX_MEMBERS:
raise ValueError(f"member_ids must contain 1..{MAX_MEMBERS} items")
if len(set(value)) != len(value):
raise ValueError("member_ids must not contain duplicates")
return value
class Message(BaseModel):
model_config = ConfigDict(extra="forbid")
id: UUID
chat_id: UUID
sender_id: UUID
text: str
created_at: str
@classmethod
def from_record(cls, record: MessageRecord) -> "Message":
return cls(
id=record.id,
chat_id=record.chat_id,
sender_id=record.sender_id,
text=record.text,
created_at=rfc3339_z(record.created_at),
)
class CreateMessage(BaseModel):
"""Поле sender_id не принимается: отправитель выводится из идентификации."""
model_config = ConfigDict(extra="forbid")
text: str
@field_validator("text")
@classmethod
def _check_text(cls, value: str) -> str:
return _visible(value, field="text", maximum=MAX_TEXT)
class ChatPage(BaseModel):
model_config = ConfigDict(extra="forbid")
items: list[Chat]
next_cursor: str | None
@classmethod
def from_records(cls, records: list[ChatRecord], next_cursor: str | None) -> "ChatPage":
return cls(items=[Chat.from_record(record) for record in records], next_cursor=next_cursor)
class MessagePage(BaseModel):
model_config = ConfigDict(extra="forbid")
items: list[Message]
next_cursor: str | None
@classmethod
def from_records(cls, records: list[MessageRecord], next_cursor: str | None) -> "MessagePage":
return cls(items=[Message.from_record(record) for record in records], next_cursor=next_cursor)
+38
View File
@@ -0,0 +1,38 @@
"""Keyset-пагинация: разбор курсора клиента и сборка следующего."""
from __future__ import annotations
from typing import Sequence
from .cursor import CursorCodec, InvalidCursor
from .domain import Position, Sortable, rfc3339_z
from .errors import invalid_request
def decoded_cursor(
cursors: CursorCodec,
token: str | None,
*,
kind: str,
scope: str,
) -> Position | None:
"""Позиция из курсора клиента; None означает «начать с начала выборки»."""
if token is None:
return None
try:
return cursors.decode(token, kind=kind, scope=scope).position
except InvalidCursor:
raise invalid_request("cursor недействителен для этого запроса") from None
def build_next_cursor(
cursors: CursorCodec,
kind: str,
scope: str,
records: Sequence[Sortable],
has_more: bool,
) -> str | None:
"""next_cursor равен null, если на момент чтения следующей записи нет."""
if not has_more or not records:
return None
last = records[-1]
return cursors.encode(kind, scope, rfc3339_z(last.created_at), str(last.id))
+358
View File
@@ -0,0 +1,358 @@
"""Запросы к PostgreSQL: единственное место, где выполняется SQL.
Все значения передаются bind-параметрами — строки запросов не собираются из
данных пользователя. Транзакционную границу задаёт репозиторий: операция,
меняющая несколько таблиц, выполняется целиком или не выполняется вовсе.
Единица работы — неявная транзакция сессии запроса: пишущие методы завершают
её `commit`, а незавершённую откатывает закрытие сессии. Поэтому чтение перед
записью (проверка доступа → вставка сообщения) идёт в той же транзакции.
"""
from __future__ import annotations
from typing import Sequence
from uuid import UUID, uuid4
from sqlalchemy import Row, Select, cast, delete, func, insert, literal, select, text, tuple_
from sqlalchemy.dialects.postgresql import TIMESTAMP, UUID as PGUUID
from sqlalchemy.dialects.postgresql import insert as pg_insert
from sqlalchemy.exc import IntegrityError
from sqlalchemy.ext.asyncio import AsyncSession
from .domain import (
ChatRecord,
IdempotencyConflict,
MessageRecord,
Position,
UnknownMembers,
UserRecord,
)
from .schema import CHAT_MEMBERS, CHATS, MESSAGE_IDEMPOTENCY, MESSAGES, USERS
FOREIGN_KEY_VIOLATION = "23503"
# Ключ идемпотентности живёт 24 часа; срок считает PostgreSQL, а не часы
# приложения, чтобы реплики с разными часами принимали одинаковое решение.
IDEMPOTENCY_FRESH_PREDICATE = MESSAGE_IDEMPOTENCY.c.created_at > (
func.now() - text("INTERVAL '24 hours'")
)
def _sqlstate(error: IntegrityError) -> str | None:
"""Код ошибки PostgreSQL: драйвер кладёт его в исходное исключение."""
return getattr(getattr(error, "orig", None), "sqlstate", None)
def _after_predicate(created_at_column, id_column, after: Position):
"""Keyset-условие «строго после пары (created_at, id)» одним сравнением строк.
Сравнение строк целиком — то, что умеет использовать составной индекс;
значение приводится к нужному типу явно, чтобы драйвер не угадывал его.
"""
moment, item_id = after
return tuple_(created_at_column, id_column) > tuple_(
cast(literal(moment), TIMESTAMP(timezone=True)),
cast(literal(item_id), PGUUID(as_uuid=True)),
)
def _user_record(row: Row) -> UserRecord:
return UserRecord(
id=row.id, username=row.username, display_name=row.display_name, created_at=row.created_at
)
def _chat_columns() -> tuple:
return (CHATS.c.id, CHATS.c.title, CHATS.c.created_at)
def _message_columns() -> tuple:
return (
MESSAGES.c.id,
MESSAGES.c.chat_id,
MESSAGES.c.sender_id,
MESSAGES.c.text,
MESSAGES.c.created_at,
)
class Repository:
"""Набор операций над PostgreSQL в рамках одной сессии (одного запроса)."""
def __init__(self, session: AsyncSession) -> None:
self._session = session
async def ping(self) -> None:
"""Дешёвая проверка живости соединения для /health/ready."""
await self._session.execute(select(literal(1)))
async def username_taken(self, username: str) -> bool:
"""Дешёвая предпроверка: занятый username отсекается до дорогого KDF."""
found = await self._session.scalar(
select(USERS.c.id).where(USERS.c.username == username).limit(1)
)
return found is not None
async def create_user(
self, username: str, display_name: str, password_hash: str
) -> UserRecord | None:
"""Создаёт пользователя; None — если username уже занят.
Гонку двух одновременных регистраций закрывает уникальный индекс:
`ON CONFLICT DO NOTHING` не поднимает ошибку и не портит транзакцию.
"""
row = (
await self._session.execute(
pg_insert(USERS)
.values(
id=uuid4(),
username=username,
display_name=display_name,
password_hash=password_hash,
)
.on_conflict_do_nothing(index_elements=[USERS.c.username])
.returning(*USERS.c)
)
).first()
await self._session.commit()
return None if row is None else _user_record(row)
async def credentials_for(self, username: str) -> tuple[UserRecord, str] | None:
"""Пользователь и его хэш пароля для проверки входа."""
row = (
await self._session.execute(
select(USERS.c.id, USERS.c.username, USERS.c.display_name, USERS.c.created_at,
USERS.c.password_hash)
.where(USERS.c.username == username)
.limit(1)
)
).first()
if row is None:
return None
return _user_record(row), row.password_hash
async def get_user(self, user_id: UUID) -> UserRecord | None:
row = (
await self._session.execute(
select(USERS.c.id, USERS.c.username, USERS.c.display_name, USERS.c.created_at)
.where(USERS.c.id == user_id)
.limit(1)
)
).first()
return None if row is None else _user_record(row)
async def create_chat(self, title: str, member_ids: Sequence[UUID]) -> ChatRecord:
"""Чат и его участники появляются одной транзакцией.
Неизвестный участник нарушает внешний ключ — транзакция откатывается
целиком, поэтому «чат без участников» или «чат с чужаком» не возникает.
"""
chat_id = uuid4()
row = (
await self._session.execute(
insert(CHATS).values(id=chat_id, title=title).returning(*_chat_columns())
)
).one()
try:
await self._session.execute(
insert(CHAT_MEMBERS),
[{"chat_id": chat_id, "user_id": member_id} for member_id in member_ids],
)
except IntegrityError as error:
if _sqlstate(error) != FOREIGN_KEY_VIOLATION:
raise
# Нарушенный внешний ключ обрывает транзакцию: откат снимает и уже
# вставленный чат, поэтому неполного чата в базе не остаётся.
await self._session.rollback()
raise UnknownMembers(member_ids) from None
await self._session.commit()
return ChatRecord(
id=row.id,
title=row.title,
member_ids=tuple(sorted(member_ids, key=lambda item: item.int)),
created_at=row.created_at,
)
async def chat_for_member(self, chat_id: UUID, user_id: UUID) -> ChatRecord | None:
"""Чат глазами участника: чужой чат неотличим от несуществующего (404)."""
row = (
await self._session.execute(
select(*_chat_columns())
.select_from(CHATS.join(CHAT_MEMBERS, CHAT_MEMBERS.c.chat_id == CHATS.c.id))
.where(CHATS.c.id == chat_id, CHAT_MEMBERS.c.user_id == user_id)
.limit(1)
)
).first()
if row is None:
return None
members = await self._members_of([chat_id])
return ChatRecord(
id=row.id, title=row.title, member_ids=members[chat_id], created_at=row.created_at
)
async def list_chats(
self, user_id: UUID, after: Position | None, limit: int
) -> tuple[list[ChatRecord], bool]:
"""Страница чатов пользователя в порядке (created_at, id) и признак «есть ещё»."""
statement = (
select(*_chat_columns())
.select_from(CHATS.join(CHAT_MEMBERS, CHAT_MEMBERS.c.chat_id == CHATS.c.id))
.where(CHAT_MEMBERS.c.user_id == user_id)
)
rows = await self._page(statement, CHATS, after, limit)
more = len(rows) > limit
rows = rows[:limit]
members = await self._members_of([row.id for row in rows])
chats = [
ChatRecord(
id=row.id, title=row.title, member_ids=members[row.id], created_at=row.created_at
)
for row in rows
]
return chats, more
async def append_message(self, chat_id: UUID, sender_id: UUID, text: str) -> MessageRecord:
"""Время и идентификатор назначает база: ответ возвращает то, что записано."""
row = (
await self._session.execute(
insert(MESSAGES)
.values(id=uuid4(), chat_id=chat_id, sender_id=sender_id, text=text)
.returning(*_message_columns())
)
).one()
await self._session.commit()
return MessageRecord(
id=row.id,
chat_id=row.chat_id,
sender_id=row.sender_id,
text=row.text,
created_at=row.created_at,
)
async def append_message_idempotent(
self,
chat_id: UUID,
sender_id: UUID,
text: str,
idempotency_key: str,
request_hash: str,
) -> MessageRecord:
"""Создаёт сообщение ровно один раз для ключа (пользователь, чат, ключ).
Транзакционная блокировка по хэшу ключа сериализует одновременные
повторы, пришедшие на разные реплики. Побочный эффект (строка messages)
и запись результата (message_idempotency) фиксируются одной транзакцией:
клиент либо видит подтверждённое сообщение, либо не видит ничего.
"""
lock_scope = f'{sender_id}:{chat_id}:{idempotency_key}'
await self._session.execute(
select(func.pg_advisory_xact_lock(func.hashtextextended(lock_scope, 0)))
)
fresh = IDEMPOTENCY_FRESH_PREDICATE
existing = (
await self._session.execute(
select(*_message_columns(), MESSAGE_IDEMPOTENCY.c.request_hash, fresh.label('fresh'))
.select_from(
MESSAGE_IDEMPOTENCY.join(
MESSAGES, MESSAGES.c.id == MESSAGE_IDEMPOTENCY.c.message_id
)
)
.where(
MESSAGE_IDEMPOTENCY.c.user_id == sender_id,
MESSAGE_IDEMPOTENCY.c.chat_id == chat_id,
MESSAGE_IDEMPOTENCY.c.idempotency_key == idempotency_key,
)
.limit(1)
)
).first()
if existing is not None:
if existing.fresh and existing.request_hash == request_hash:
record = MessageRecord(
id=existing.id,
chat_id=existing.chat_id,
sender_id=existing.sender_id,
text=existing.text,
created_at=existing.created_at,
)
await self._session.commit()
return record
if existing.fresh:
await self._session.rollback()
raise IdempotencyConflict()
# Срок хранения ключа истёк: старый ключ можно использовать снова.
await self._session.execute(
delete(MESSAGE_IDEMPOTENCY).where(
MESSAGE_IDEMPOTENCY.c.user_id == sender_id,
MESSAGE_IDEMPOTENCY.c.chat_id == chat_id,
MESSAGE_IDEMPOTENCY.c.idempotency_key == idempotency_key,
)
)
message_id = uuid4()
row = (
await self._session.execute(
insert(MESSAGES)
.values(id=message_id, chat_id=chat_id, sender_id=sender_id, text=text)
.returning(*_message_columns())
)
).one()
await self._session.execute(
insert(MESSAGE_IDEMPOTENCY).values(
user_id=sender_id,
chat_id=chat_id,
idempotency_key=idempotency_key,
request_hash=request_hash,
message_id=message_id,
)
)
await self._session.commit()
return MessageRecord(
id=row.id,
chat_id=row.chat_id,
sender_id=row.sender_id,
text=row.text,
created_at=row.created_at,
)
async def list_messages(
self, chat_id: UUID, after: Position | None, limit: int
) -> tuple[list[MessageRecord], bool]:
"""Страница истории чата от старых к новым и признак «есть ещё»."""
statement = select(*_message_columns()).where(MESSAGES.c.chat_id == chat_id)
rows = await self._page(statement, MESSAGES, after, limit)
more = len(rows) > limit
messages = [
MessageRecord(
id=row.id,
chat_id=row.chat_id,
sender_id=row.sender_id,
text=row.text,
created_at=row.created_at,
)
for row in rows[:limit]
]
return messages, more
async def _page(
self, statement: Select, table, after: Position | None, limit: int
) -> list[Row]:
"""Забирает limit+1 строк: лишняя строка и означает «есть ещё»."""
if after is not None:
statement = statement.where(_after_predicate(table.c.created_at, table.c.id, after))
result = await self._session.execute(
statement.order_by(table.c.created_at, table.c.id).limit(limit + 1)
)
return list(result)
async def _members_of(self, chat_ids: Sequence[UUID]) -> dict[UUID, tuple[UUID, ...]]:
"""Состав участников страницы чатов одним запросом, без N+1."""
if not chat_ids:
return {}
rows = await self._session.execute(
select(CHAT_MEMBERS.c.chat_id, CHAT_MEMBERS.c.user_id)
.where(CHAT_MEMBERS.c.chat_id.in_(chat_ids))
.order_by(CHAT_MEMBERS.c.chat_id, CHAT_MEMBERS.c.user_id)
)
grouped: dict[UUID, list[UUID]] = {}
for chat_id, user_id in rows:
grouped.setdefault(chat_id, []).append(user_id)
return {chat_id: tuple(members) for chat_id, members in grouped.items()}
+1
View File
@@ -0,0 +1 @@
"""Маршруты HTTP API: только разбор запроса, вызов зависимостей и сборка ответа."""
+51
View File
@@ -0,0 +1,51 @@
"""Вход по Basic и отзыв текущей сессии."""
from __future__ import annotations
from fastapi import APIRouter, Response, status
from ..deps import BasicCredentialsDep, BearerToken, RepositoryDep, SessionsDep
from ..errors import BASIC_CHALLENGE, unauthorized
from ..models import Session
from ..security import spend_verification_time, verify_password
router = APIRouter(prefix="/api/v1/auth/sessions", tags=["auth"])
INVALID_CREDENTIALS = "Неверный username или пароль"
@router.post("", status_code=status.HTTP_201_CREATED, summary="Вход: Basic username:password")
async def create_session(
credentials: BasicCredentialsDep,
repository: RepositoryDep,
sessions: SessionsDep,
) -> Session:
"""Проверяет пароль и выдаёт opaque-токен сессии; тело запроса не читается.
Неизвестный пользователь и неверный пароль неразличимы: одинаковый 401 с
Basic-челленджем и одинаковая затрата времени на KDF.
"""
found = await repository.credentials_for(credentials.username)
if found is None:
await spend_verification_time()
raise unauthorized(INVALID_CREDENTIALS, challenge=BASIC_CHALLENGE)
user, password_hash = found
if not await verify_password(credentials.password, password_hash):
raise unauthorized(INVALID_CREDENTIALS, challenge=BASIC_CHALLENGE)
issued = await sessions.create(user.id)
return Session.from_issued(issued, user)
@router.delete(
"/current",
status_code=status.HTTP_204_NO_CONTENT,
summary="Отозвать текущую сессию",
)
async def revoke_session(token: BearerToken, sessions: SessionsDep) -> Response:
"""Отзыв действует сразу: тот же токен после него даёт 401.
Ответ пустой (204), поэтому клиент не получает ни тела, ни нового состояния
сессии. Отзыв не трогает PostgreSQL: удаление ключа в Valkey атомарно.
"""
if not await sessions.revoke(token):
raise unauthorized("Сессия не найдена или истекла")
return Response(status_code=status.HTTP_204_NO_CONTENT)
+55
View File
@@ -0,0 +1,55 @@
"""Создание, список и чтение чатов."""
from __future__ import annotations
from typing import Annotated
from uuid import UUID
from fastapi import APIRouter, Path, Query, status
from ..access import visible_chat
from ..cursor import KIND_CHATS
from ..deps import CursorsDep, CurrentUser, RepositoryDep
from ..domain import UnknownMembers
from ..errors import invalid_request
from ..models import DEFAULT_LIMIT, MAX_LIMIT, Chat, ChatPage, CreateChat
from ..pagination import build_next_cursor, decoded_cursor
router = APIRouter(prefix="/api/v1/chats", tags=["chats"])
@router.post("", status_code=status.HTTP_201_CREATED, summary="Создать чат")
async def create_chat(payload: CreateChat, repository: RepositoryDep, user: CurrentUser) -> Chat:
"""Создаёт чат; состав участников задаётся при создании и не меняется."""
if user.id not in payload.member_ids:
raise invalid_request("Создатель чата обязан входить в member_ids")
try:
record = await repository.create_chat(payload.title, payload.member_ids)
except UnknownMembers:
raise invalid_request("member_ids содержит неизвестных пользователей") from None
return Chat.from_record(record)
@router.get("", summary="Чаты текущего пользователя")
async def list_chats(
repository: RepositoryDep,
cursors: CursorsDep,
user: CurrentUser,
limit: Annotated[int, Query(ge=1, le=MAX_LIMIT)] = DEFAULT_LIMIT,
cursor: Annotated[str | None, Query(min_length=1)] = None,
) -> ChatPage:
"""Список видимых чатов по (created_at, id) по возрастанию."""
scope = str(user.id)
after = decoded_cursor(cursors, cursor, kind=KIND_CHATS, scope=scope)
records, has_more = await repository.list_chats(user.id, after, limit)
return ChatPage.from_records(
records, build_next_cursor(cursors, KIND_CHATS, scope, records, has_more)
)
@router.get("/{chat_id}", summary="Получить доступный чат")
async def read_chat(
chat_id: Annotated[UUID, Path()],
repository: RepositoryDep,
user: CurrentUser,
) -> Chat:
return Chat.from_record(await visible_chat(repository, chat_id, user))
+42
View File
@@ -0,0 +1,42 @@
"""Проверки живости и готовности."""
from __future__ import annotations
from fastapi import APIRouter, Request
from ..deps import DatabaseDep, SessionsDep
from ..errors import unavailable
from ..models import Health
from ..schema import SCHEMA_REVISION
router = APIRouter(prefix="/health", tags=["health"])
@router.get("/live", summary="Процесс жив")
async def liveness() -> Health:
"""Проверяет только то, что процесс обслуживает запросы.
Зависимости здесь намеренно не проверяются: их отказ — не повод убивать
контейнер и устраивать цикл перезапусков.
"""
return Health()
@router.get("/ready", summary="Готов принимать трафик")
async def readiness(
request: Request,
database: DatabaseDep,
sessions: SessionsDep,
) -> Health:
"""Готовность = процесс не на остановке и критические зависимости отвечают.
Отказ зависимости превращается в 503 общим обработчиком: у готовности и у
бизнес-операций один и тот же признак неработоспособности.
"""
if getattr(request.app.state, "draining", False):
raise unavailable("Сервис завершает работу и не принимает новые запросы")
await database.ping()
revision = await database.schema_revision()
if revision != SCHEMA_REVISION:
raise unavailable("Схема базы данных ещё не готова")
await sessions.ping()
return Health()
+62
View File
@@ -0,0 +1,62 @@
"""Отправка и чтение истории сообщений."""
from __future__ import annotations
from typing import Annotated
from uuid import UUID
from fastapi import APIRouter, Header, Path, Query, status
from ..access import visible_chat
from ..cursor import KIND_MESSAGES
from ..deps import CursorsDep, CurrentUser, RepositoryDep
from ..domain import IdempotencyConflict
from ..errors import conflict
from ..idempotency import message_request_hash, require_idempotency_key
from ..models import DEFAULT_LIMIT, MAX_LIMIT, CreateMessage, Message, MessagePage
from ..pagination import build_next_cursor, decoded_cursor
router = APIRouter(prefix="/api/v1/chats/{chat_id}/messages", tags=["messages"])
@router.post("", status_code=status.HTTP_201_CREATED, summary="Отправить сообщение")
async def create_message(
chat_id: Annotated[UUID, Path()],
payload: CreateMessage,
repository: RepositoryDep,
user: CurrentUser,
idempotency_key: Annotated[str | None, Header(alias="Idempotency-Key")] = None,
) -> Message:
"""Отправитель выводится из идентификации; sender_id в теле не принимается.
Порядок проверок контракта: аутентификация (зависимость user), доступ к
чату (404 для чужого), затем ключ идемпотентности. Повтор с тем же ключом
и телом возвращает то же сообщение и тот же код 201.
"""
await visible_chat(repository, chat_id, user)
key = require_idempotency_key(idempotency_key)
try:
record = await repository.append_message_idempotent(
chat_id, user.id, payload.text, key, message_request_hash(payload.text)
)
except IdempotencyConflict:
raise conflict("Idempotency-Key уже использован с другим телом запроса") from None
return Message.from_record(record)
@router.get("", summary="Сообщения по (created_at, id) по возрастанию")
async def list_messages(
chat_id: Annotated[UUID, Path()],
repository: RepositoryDep,
cursors: CursorsDep,
user: CurrentUser,
limit: Annotated[int, Query(ge=1, le=MAX_LIMIT)] = DEFAULT_LIMIT,
cursor: Annotated[str | None, Query(min_length=1)] = None,
) -> MessagePage:
"""Keyset-пагинация: страница читается по индексу, предыдущие не повторяются."""
await visible_chat(repository, chat_id, user)
scope = str(chat_id)
after = decoded_cursor(cursors, cursor, kind=KIND_MESSAGES, scope=scope)
records, has_more = await repository.list_messages(chat_id, after, limit)
return MessagePage.from_records(
records, build_next_cursor(cursors, KIND_MESSAGES, scope, records, has_more)
)
+34
View File
@@ -0,0 +1,34 @@
"""Регистрация и текущий пользователь."""
from __future__ import annotations
from fastapi import APIRouter, status
from ..deps import CurrentUser, RepositoryDep
from ..errors import conflict
from ..models import CreateUser, User
from ..security import hash_password
router = APIRouter(prefix="/api/v1/users", tags=["users"])
USERNAME_TAKEN = "username уже занят"
@router.post("", status_code=status.HTTP_201_CREATED, summary="Создать пользователя")
async def register_user(payload: CreateUser, repository: RepositoryDep) -> User:
"""Регистрация публична; username уникален, повтор даёт 409."""
if await repository.username_taken(payload.username):
# Предпроверка экономит KDF на заведомо занятом username; гонку закрывает
# уникальный индекс в create_user, поэтому оба пути дают один и тот же 409.
raise conflict(USERNAME_TAKEN)
record = await repository.create_user(
payload.username, payload.display_name, await hash_password(payload.password)
)
if record is None:
raise conflict(USERNAME_TAKEN)
return User.from_record(record)
@router.get("/me", summary="Текущий пользователь")
async def read_current_user(user: CurrentUser) -> User:
"""Владелец Bearer-сессии; пароль и хэш пароля наружу не выходят."""
return User.from_record(user)
+124
View File
@@ -0,0 +1,124 @@
"""Описание таблиц PostgreSQL: один источник истины для запросов и миграций."""
from __future__ import annotations
from sqlalchemy import (
CheckConstraint,
Column,
ForeignKey,
Index,
MetaData,
Table,
Text,
UniqueConstraint,
text,
)
from sqlalchemy.dialects.postgresql import TIMESTAMP, UUID
METADATA = MetaData()
# Версия схемы, которую процесс считает совместимой с собой. Готовность
# проверяет её в alembic_version, поэтому API не начинает принимать трафик
# раньше однократной миграции.
SCHEMA_REVISION = "0002_message_idempotency"
USERS = Table(
"users",
METADATA,
Column("id", UUID(as_uuid=True), primary_key=True),
Column("username", Text, nullable=False),
Column("display_name", Text, nullable=False),
Column("password_hash", Text, nullable=False),
Column("created_at", TIMESTAMP(timezone=True), nullable=False, server_default=text("now()")),
UniqueConstraint("username", name="uq_users_username"),
CheckConstraint(r"username ~ '^[a-z0-9_]{3,32}$'", name="ck_users_username_format"),
CheckConstraint(
"char_length(display_name) BETWEEN 1 AND 100", name="ck_users_display_name_length"
),
)
CHATS = Table(
"chats",
METADATA,
Column("id", UUID(as_uuid=True), primary_key=True),
Column("title", Text, nullable=False),
Column("created_at", TIMESTAMP(timezone=True), nullable=False, server_default=text("now()")),
CheckConstraint("char_length(title) BETWEEN 1 AND 100", name="ck_chats_title_length"),
)
CHAT_MEMBERS = Table(
"chat_members",
METADATA,
Column(
"chat_id",
UUID(as_uuid=True),
ForeignKey("chats.id", name="fk_chat_members_chat", ondelete="CASCADE"),
primary_key=True,
),
Column(
"user_id",
UUID(as_uuid=True),
ForeignKey("users.id", name="fk_chat_members_user", ondelete="RESTRICT"),
primary_key=True,
),
Index("ix_chat_members_user_id_chat_id", "user_id", "chat_id"),
)
MESSAGES = Table(
"messages",
METADATA,
Column("id", UUID(as_uuid=True), primary_key=True),
Column(
"chat_id",
UUID(as_uuid=True),
ForeignKey("chats.id", name="fk_messages_chat", ondelete="CASCADE"),
nullable=False,
),
Column(
"sender_id",
UUID(as_uuid=True),
ForeignKey("users.id", name="fk_messages_sender", ondelete="RESTRICT"),
nullable=False,
),
Column("text", Text, nullable=False),
Column("created_at", TIMESTAMP(timezone=True), nullable=False, server_default=text("now()")),
CheckConstraint(
"text <> '' AND char_length(text) <= 4000", name="ck_messages_text_length"
),
# Порядок истории (created_at, id) и keyset-предикат обслуживает один индекс.
Index("ix_messages_chat_id_created_at_id", "chat_id", "created_at", "id"),
)
# Общая идемпотентность отправки сообщения. Область уникальности —
# (пользователь, чат, ключ); тело запроса сравнивается по каноническому хэшу.
# Строка и само сообщение пишутся одной транзакцией, поэтому подтверждённый
# ответ и побочный эффект не могут разойтись.
MESSAGE_IDEMPOTENCY = Table(
"message_idempotency",
METADATA,
Column(
"user_id",
UUID(as_uuid=True),
ForeignKey("users.id", name="fk_message_idempotency_user", ondelete="CASCADE"),
primary_key=True,
),
Column(
"chat_id",
UUID(as_uuid=True),
ForeignKey("chats.id", name="fk_message_idempotency_chat", ondelete="CASCADE"),
primary_key=True,
),
Column("idempotency_key", Text, primary_key=True),
Column("request_hash", Text, nullable=False),
Column(
"message_id",
UUID(as_uuid=True),
ForeignKey("messages.id", name="fk_message_idempotency_message", ondelete="CASCADE"),
nullable=False,
),
Column("created_at", TIMESTAMP(timezone=True), nullable=False, server_default=text("now()")),
CheckConstraint(
"char_length(idempotency_key) BETWEEN 1 AND 128",
name="ck_message_idempotency_key_length",
),
Index("ix_message_idempotency_created_at", "created_at"),
)
+119
View File
@@ -0,0 +1,119 @@
"""Пароли и токены: argon2id для пароля, случайный opaque-токен для доступа.
Пароль не хранится и не передаётся дальше: в базе лежит только строка argon2id.
KDF считает десятки миллисекунд, поэтому вызывается в рабочем потоке — цикл
событий не должен ждать хэширование.
"""
from __future__ import annotations
import base64
import binascii
import hashlib
import secrets
from functools import lru_cache
import anyio
from argon2 import PasswordHasher
from argon2.exceptions import Argon2Error, InvalidHashError
# Минимальные параметры Argon2id из OWASP Password Storage Cheat Sheet:
# m=19456 КиБ (19 МиБ), t=2, p=1. Память на проверку ограничена осознанно.
TIME_COST = 2
MEMORY_COST_KIB = 19456
PARALLELISM = 1
HASH_BYTES = 32
SALT_BYTES = 16
TOKEN_BYTES = 32
TOKEN_MIN_LENGTH = 32
BASIC_SCHEME = "basic"
BEARER_SCHEME = "bearer"
_DUMMY_PASSWORD = "messenger-dummy-password-never-matches"
_hasher = PasswordHasher(
time_cost=TIME_COST,
memory_cost=MEMORY_COST_KIB,
parallelism=PARALLELISM,
hash_len=HASH_BYTES,
salt_len=SALT_BYTES,
)
def _hash(password: str) -> str:
return _hasher.hash(password)
def _verify(password: str, stored_hash: str) -> bool:
"""True только при совпадении; неподходящий или испорченный хэш — тоже «нет»."""
try:
return _hasher.verify(stored_hash, password)
except (Argon2Error, InvalidHashError):
return False
@lru_cache(maxsize=1)
def _dummy_hash() -> str:
"""Хэш-заглушка: нужен, чтобы ответ про неизвестного пользователя стоил столько же."""
return _hash(_DUMMY_PASSWORD)
async def hash_password(password: str) -> str:
"""Хэширует пароль; длина пароля ограничена контрактом, усечения нет."""
return await anyio.to_thread.run_sync(_hash, password)
async def verify_password(password: str, stored_hash: str) -> bool:
return await anyio.to_thread.run_sync(_verify, password, stored_hash)
async def spend_verification_time() -> None:
"""Выполняет KDF впустую: время ответа не выдаёт существование пользователя."""
await anyio.to_thread.run_sync(_verify, _DUMMY_PASSWORD, _dummy_hash())
def new_token() -> str:
"""Opaque-токен сессии: 256 бит энтропии, длина не меньше требуемых 32 символов."""
return secrets.token_urlsafe(TOKEN_BYTES)
def token_fingerprint(token: str) -> str:
"""Ключ, под которым сессия лежит в хранилище: сам токен там не появляется."""
return hashlib.sha256(token.encode("utf-8")).hexdigest()
def _credentials(header: str | None, scheme: str) -> str | None:
"""Хвост заголовка Authorization, если схема совпала; иначе None."""
if not header:
return None
name, separator, value = header.strip().partition(" ")
if not separator or name.lower() != scheme:
return None
value = value.strip()
return value or None
def parse_basic(header: str | None) -> tuple[str, str] | None:
"""Разбирает `Authorization: Basic ...` в пару (username, password).
None означает «заголовка нет, схема не та или значение испорчено»; наружу все
эти случаи дают один и тот же 401, поэтому различать их незачем.
"""
encoded = _credentials(header, BASIC_SCHEME)
if encoded is None:
return None
try:
decoded = base64.b64decode(encoded + "=" * (-len(encoded) % 4), validate=True)
text = decoded.decode("utf-8")
except (binascii.Error, ValueError):
return None
username, separator, password = text.partition(":")
if not separator or not username:
return None
return username, password
def parse_bearer(header: str | None) -> str | None:
"""Токен из `Authorization: Bearer ...`; None — если заголовок не подходит."""
return _credentials(header, BEARER_SCHEME)
+122
View File
@@ -0,0 +1,122 @@
"""Хранилище сессий в Valkey: opaque-токен → состояние с абсолютным временем жизни.
Ключ строится из sha256 токена, поэтому в дампе и в `MONITOR` нет действующих
токенов — есть только их отпечатки. TTL выставляет сам сервер (`SET ... EX`),
а время истечения хранится абсолютным: перезапуск процесса или сервера срок
жизни сессии не продлевает.
"""
from __future__ import annotations
import json
from dataclasses import dataclass
from datetime import datetime, timedelta
from typing import Protocol
from uuid import UUID
from redis.asyncio import Redis
from .domain import parse_rfc3339_z, rfc3339_z, utc_now
from .security import new_token, token_fingerprint
SESSION_KEY_PREFIX = "messenger:session:"
@dataclass(frozen=True)
class SessionState:
"""Состояние сессии: владелец и границы жизни."""
user_id: UUID
created_at: datetime
expires_at: datetime
@dataclass(frozen=True)
class IssuedSession:
"""Выданная сессия: сам токен клиент видит ровно один раз."""
token: str
state: SessionState
class SessionStore(Protocol):
"""Контракт хранилища сессий: его выполняет Valkey, подменяется в тестах."""
async def create(self, user_id: UUID) -> IssuedSession: ...
async def resolve(self, token: str) -> SessionState | None: ...
async def revoke(self, token: str) -> bool: ...
async def ping(self) -> None: ...
async def close(self) -> None: ...
def _key(token: str) -> str:
return SESSION_KEY_PREFIX + token_fingerprint(token)
def _state_of(payload: str) -> SessionState | None:
"""Разбирает значение сессии; испорченное значение равносильно её отсутствию."""
try:
data = json.loads(payload)
return SessionState(
user_id=UUID(data["user_id"]),
created_at=parse_rfc3339_z(data["created_at"]),
expires_at=parse_rfc3339_z(data["expires_at"]),
)
except (ValueError, KeyError, TypeError):
return None
class RedisSessionStore:
"""Сессии в Valkey/Redis с постоянным хранением (AOF).
Таймауты на сокет ограничены: недоступная зависимость обязана отвечать
отказом быстро, а не держать запрос до таймаута клиента.
"""
def __init__(self, url: str, ttl_seconds: int, timeout_seconds: float) -> None:
self._ttl_seconds = ttl_seconds
self._client = Redis.from_url(
url,
decode_responses=True,
socket_timeout=timeout_seconds,
socket_connect_timeout=timeout_seconds,
)
async def create(self, user_id: UUID) -> IssuedSession:
token = new_token()
created_at = utc_now()
expires_at = created_at + timedelta(seconds=self._ttl_seconds)
payload = json.dumps(
{
"user_id": str(user_id),
"created_at": rfc3339_z(created_at),
"expires_at": rfc3339_z(expires_at),
},
separators=(",", ":"),
sort_keys=True,
)
await self._client.set(_key(token), payload, ex=self._ttl_seconds)
return IssuedSession(token=token, state=SessionState(user_id, created_at, expires_at))
async def resolve(self, token: str) -> SessionState | None:
"""Состояние действующей сессии; None — токен неизвестен или срок истёк."""
payload = await self._client.get(_key(token))
if payload is None:
return None
state = _state_of(payload)
if state is None or state.expires_at <= utc_now():
return None
return state
async def revoke(self, token: str) -> bool:
"""Отзыв: GETDEL проверяет и удаляет одной атомарной операцией."""
return await self._client.getdel(_key(token)) is not None
async def ping(self) -> None:
await self._client.ping()
async def close(self) -> None:
await self._client.aclose()
+223
View File
@@ -0,0 +1,223 @@
# Docker Swarm stack лабораторной 3.
#
# Роли: Traefik (единственная публичная точка входа), api (2+ взаимозаменяемые
# реплики), PostgreSQL (источник истины), Valkey (общие сессии), migrate
# (однократное применение схемы). API не публикует порты: снаружи виден только
# Traefik. Секреты создаются один раз скриптом scripts/bootstrap-secrets.sh и
# монтируются файлами, поэтому в stack.yaml нет значений секретов.
#
# Версии базовых образов закреплены; для приложения тег задаёт scripts/deploy.sh.
x-api-environment: &api-environment
APP_ENV: lab
APP_HOST: 0.0.0.0
APP_PORT: "8080"
LOG_LEVEL: info
SESSION_STORE: redis
SESSION_TTL_SECONDS: "${SESSION_TTL_SECONDS:-3600}"
DB_POOL_SIZE: "5"
DB_MAX_OVERFLOW: "5"
DB_POOL_TIMEOUT_SECONDS: "2"
DB_CONNECT_TIMEOUT_SECONDS: "1.5"
DB_COMMAND_TIMEOUT_SECONDS: "2.5"
DB_STATEMENT_TIMEOUT_MS: "2000"
CACHE_TIMEOUT_SECONDS: "1"
GRACEFUL_SHUTDOWN_SECONDS: "5"
SHUTDOWN_DRAIN_SECONDS: "2"
DATABASE_URL_FILE: /run/secrets/database_url
CACHE_URL_FILE: /run/secrets/cache_url
CURSOR_SECRET_FILE: /run/secrets/cursor_secret
services:
traefik:
image: traefik:v3.5.4
command:
- --providers.swarm=true
- --providers.swarm.endpoint=unix:///var/run/docker.sock
- --providers.swarm.exposedByDefault=false
- --providers.swarm.network=backend
- --providers.swarm.watch=true
- --entryPoints.web.address=:8080
- --log.level=INFO
- --accesslog=false
ports:
- target: 8080
published: ${APP_PORT:-8080}
protocol: tcp
mode: ingress
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
networks:
- backend
deploy:
replicas: 1
placement:
constraints:
- node.role == manager
resources:
limits:
cpus: "0.50"
memory: 128M
restart_policy:
condition: any
delay: 5s
postgres:
image: postgres:16.15-bookworm@sha256:0ea6700a3b4f0ae6ce746519073558aed4d88a79d8d07622a9a644946c7319c4
environment:
POSTGRES_USER: messenger
POSTGRES_DB: messenger
POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password
POSTGRES_INITDB_ARGS: "--auth-host=scram-sha-256"
secrets:
- source: lab3_postgres_password
target: postgres_password
volumes:
- pgdata:/var/lib/postgresql/data
networks:
- backend
healthcheck:
test: ["CMD-SHELL", "pg_isready -U messenger -d messenger"]
interval: 5s
timeout: 3s
retries: 12
start_period: 10s
deploy:
replicas: 1
resources:
limits:
cpus: "2.0"
memory: 512M
restart_policy:
condition: any
delay: 5s
valkey:
image: valkey/valkey:8.0.11-trixie@sha256:4436c94fc34ce4af0354b9379d433a1f258998fb955f995c89822f98c14a8cab
command:
- valkey-server
- --appendonly
- "yes"
- --appendfsync
- everysec
- --save
- ""
volumes:
- valkeydata:/data
networks:
- backend
healthcheck:
test: ["CMD", "valkey-cli", "ping"]
interval: 5s
timeout: 3s
retries: 12
start_period: 5s
deploy:
replicas: 1
resources:
limits:
cpus: "1.0"
memory: 256M
restart_policy:
condition: any
delay: 5s
migrate:
image: ${API_IMAGE:-mtusi-messenger-lab3:3.0.0}
# Одна задача, а не гонка всех реплик API. alembic upgrade head идемпотентен;
# цикл ждёт, пока PostgreSQL примет соединение после холодного старта.
command:
- /bin/sh
- -c
- "until alembic upgrade head; do echo migration waiting for postgres; sleep 2; done"
environment:
DATABASE_URL_FILE: /run/secrets/database_url
secrets:
- source: lab3_database_url
target: database_url
networks:
- backend
deploy:
replicas: 1
resources:
limits:
cpus: "1.0"
memory: 256M
restart_policy:
condition: none
api:
image: ${API_IMAGE:-mtusi-messenger-lab3:3.0.0}
environment:
<<: *api-environment
secrets:
- source: lab3_database_url
target: database_url
- source: lab3_cache_url
target: cache_url
- source: lab3_cursor_secret
target: cursor_secret
networks:
- backend
stop_grace_period: 15s
healthcheck:
test: ["CMD", "python", "-m", "messenger.healthcheck"]
interval: 5s
timeout: 3s
start_period: 10s
retries: 3
deploy:
replicas: ${API_REPLICAS:-2}
labels:
- traefik.enable=true
- traefik.swarm.network=backend
- traefik.http.routers.messenger.rule=PathPrefix(`/`)
- traefik.http.routers.messenger.entrypoints=web
- traefik.http.routers.messenger.service=messenger
- traefik.http.services.messenger.loadbalancer.server.port=8080
- traefik.http.services.messenger.loadbalancer.server.scheme=http
- traefik.http.services.messenger.loadbalancer.healthcheck.path=/health/ready
- traefik.http.services.messenger.loadbalancer.healthcheck.interval=2s
- traefik.http.services.messenger.loadbalancer.healthcheck.unhealthyinterval=1s
- traefik.http.services.messenger.loadbalancer.healthcheck.timeout=1s
- traefik.http.services.messenger.loadbalancer.healthcheck.scheme=http
update_config:
parallelism: 1
order: start-first
delay: 5s
monitor: 10s
failure_action: rollback
rollback_config:
parallelism: 1
order: start-first
delay: 5s
restart_policy:
condition: any
delay: 1s
max_attempts: 0
resources:
limits:
cpus: "1.0"
memory: 384M
reservations:
cpus: "0.25"
memory: 128M
secrets:
lab3_database_url:
external: true
lab3_cache_url:
external: true
lab3_postgres_password:
external: true
lab3_cursor_secret:
external: true
volumes:
pgdata:
valkeydata:
networks:
backend:
driver: overlay
attachable: true
+17
View File
@@ -0,0 +1,17 @@
# Собственные проверки лабораторной 3
```sh
make student-test BASE_URL=http://127.0.0.1:8080
python3 student-tests/idempotency_probe.py
```
| Файл | Что проверяет |
| --- | --- |
| `harness.py` | клиент публичного `tests/client.py`, сбор `X-Instance-Id`, история, ожидание готовности |
| `test_lab3.py` | ≥2 реплики на одном токене; 24 параллельных POST с одним ключом через LB; 409 на другое тело; область ключа; валидация ключа; безопасный повтор |
| `idempotency_probe.py` | 32 параллельных POST с одним ключом, печатает обезличенную JSON-сводку |
| `run_all.py` | запуск unittest-модулей |
Все проверки идут через `BASE_URL` (по умолчанию `http://127.0.0.1:8080`),
не печатают токены и не управляют Docker — это делает action-скрипт публичного
`tests/resilience.py`.
+74
View File
@@ -0,0 +1,74 @@
"""Общая обвязка собственных проверок лабораторной 3.
Публичный клиент из tests/ переиспользуется, а не копируется: он уже проверяет
схему ответа, X-Request-Id, X-Instance-Id, конверт ошибки и challenge. Здесь
живут только помощники, специфичные для балансировки и идемпотентности.
"""
from __future__ import annotations
import os
import sys
import time
import uuid
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
TESTS = ROOT / "tests"
HERE = Path(__file__).resolve().parent
for candidate in (str(TESTS), str(HERE)):
if candidate not in sys.path:
sys.path.insert(0, candidate)
from client import Client, Failure # noqa: E402
DEFAULT_BASE_URL = "http://127.0.0.1:8080"
DEFAULT_TIMEOUT = 10.0
def client(timeout: float = DEFAULT_TIMEOUT) -> Client:
return Client(os.environ.get("BASE_URL", DEFAULT_BASE_URL), None, timeout)
def instance_ids(api: Client, actor: dict, count: int = 40) -> set[str]:
"""Собирает X-Instance-Id разных ответов через LB, не доверяя одному запросу."""
seen: set[str] = set()
for _ in range(count):
seen.add(
api.call("GET", "/api/v1/users/me", actor=actor, schema="User")["headers"][
"X-Instance-Id"
]
)
return seen
def wait_ready(timeout: float = 120.0) -> None:
api = client(timeout=5)
deadline = time.monotonic() + timeout
last = "no attempts"
while time.monotonic() < deadline:
try:
api.call("GET", "/health/ready", schema="Health")
return
except (Failure, OSError) as exc:
last = str(exc)
time.sleep(0.5)
raise Failure("stand did not become ready within %.0fs: %s" % (timeout, last))
def history(api: Client, actor: dict, chat_id: str) -> list[dict]:
items: list[dict] = []
cursor = None
for _ in range(1000):
path = "/api/v1/chats/%s/messages?limit=100" % chat_id
if cursor is not None:
path += "&cursor=" + cursor
page = api.call("GET", path, actor=actor, schema="MessagePage")["json"]
items.extend(page["items"])
cursor = page["next_cursor"]
if cursor is None:
return items
raise Failure("history pagination exceeded safety bound")
def unique_key() -> str:
return uuid.uuid4().hex
+53
View File
@@ -0,0 +1,53 @@
#!/usr/bin/env python3
"""Печатает обезличенную сводку конкурентного повтора одного Idempotency-Key."""
from __future__ import annotations
import json
import threading
import time
from concurrent.futures import ThreadPoolExecutor
from uuid import uuid4
import harness
def main() -> int:
api = harness.client()
alice, bob, _, chat = api.bootstrap()
key = uuid4().hex
text = "probe-" + uuid4().hex
workers = 32
barrier = threading.Barrier(workers)
def worker(_: int) -> dict:
local = harness.client(10)
barrier.wait()
return local.message(alice, chat, text, key=key)
started = time.monotonic()
with ThreadPoolExecutor(max_workers=workers) as pool:
responses = list(pool.map(worker, range(workers)))
elapsed = time.monotonic() - started
bodies = [r["json"] for r in responses]
instances = sorted({r["headers"]["X-Instance-Id"] for r in responses})
messages = [m for m in harness.history(api, bob, chat["id"]) if m["text"] == text]
summary = {
"concurrent_requests": workers,
"elapsed_seconds": round(elapsed, 3),
"statuses": sorted({r["status"] for r in responses}),
"distinct_instances": instances,
"distinct_message_ids": len({b["id"] for b in bodies}),
"history_matches": len(messages),
"all_responses_identical": all(b == bodies[0] for b in bodies),
}
print(json.dumps(summary, ensure_ascii=False, indent=2))
return 0 if (
summary["statuses"] == [201]
and summary["distinct_message_ids"] == 1
and summary["history_matches"] == 1
and len(instances) >= 2
) else 1
if __name__ == "__main__":
raise SystemExit(main())
+32
View File
@@ -0,0 +1,32 @@
#!/usr/bin/env python3
"""Запуск собственных проверок лабораторной 3."""
from __future__ import annotations
import argparse
import os
import sys
import unittest
from pathlib import Path
HERE = Path(__file__).resolve().parent
def main() -> int:
parser = argparse.ArgumentParser(description="Собственные проверки лабораторной 3")
parser.add_argument("--base-url", default=os.environ.get("BASE_URL", "http://127.0.0.1:8080"))
arguments = parser.parse_args()
os.environ["BASE_URL"] = arguments.base_url
if str(HERE) not in sys.path:
sys.path.insert(0, str(HERE))
if hasattr(sys.stdout, "reconfigure"):
sys.stdout.reconfigure(line_buffering=True)
print("BASE_URL =", arguments.base_url, flush=True)
suite = unittest.defaultTestLoader.discover(
str(HERE), pattern="test_*.py", top_level_dir=str(HERE)
)
result = unittest.TextTestRunner(verbosity=2).run(suite)
return 0 if result.wasSuccessful() else 1
if __name__ == "__main__":
raise SystemExit(main())
+108
View File
@@ -0,0 +1,108 @@
"""Собственные проверки лабораторной 3: реплики, LB и общая идемпотентность."""
from __future__ import annotations
import threading
import unittest
from concurrent.futures import ThreadPoolExecutor
from uuid import uuid4
import harness
from client import Client
class Lab3Tests(unittest.TestCase):
@classmethod
def setUpClass(cls) -> None:
harness.wait_ready()
cls.api = harness.client()
cls.alice, cls.bob, cls.eve, cls.chat = cls.api.bootstrap()
def test_01_at_least_two_instances_and_stable_header(self) -> None:
"""LB действительно распределяет один и тот же токен между разными процессами."""
observed = harness.instance_ids(self.api, self.alice, 40)
self.assertGreaterEqual(len(observed), 2, "less than two X-Instance-Id values through LB")
for _ in range(10):
me = self.api.call("GET", "/api/v1/users/me", actor=self.alice, schema="User")["json"]
self.assertEqual(me["id"], self.alice["id"])
def test_02_concurrent_same_key_through_lb_creates_one_message(self) -> None:
"""Один ключ + одно тело одновременно через разные реплики = одно сообщение."""
key = uuid4().hex
text = "concurrent-idempotency-" + uuid4().hex
workers = 24
barrier = threading.Barrier(workers)
def worker(_: int) -> dict:
local = harness.client(10)
barrier.wait()
return local.message(self.alice, self.chat, text, key=key)
with ThreadPoolExecutor(max_workers=workers) as pool:
responses = list(pool.map(worker, range(workers)))
bodies = [response["json"] for response in responses]
instances = {response["headers"]["X-Instance-Id"] for response in responses}
self.assertGreaterEqual(len(instances), 2, "concurrent requests did not reach both replicas")
self.assertEqual(bodies, [bodies[0]] * workers, "replay returned a different Message")
messages = [m for m in harness.history(self.api, self.bob, self.chat["id"]) if m["text"] == text]
self.assertEqual(len(messages), 1, "idempotency key created %d messages" % len(messages))
self.assertEqual(messages[0], bodies[0])
def test_03_same_key_other_body_conflicts(self) -> None:
key = uuid4().hex
first = self.api.message(self.alice, self.chat, "first-" + uuid4().hex, key=key)["json"]
replay = self.api.message(self.alice, self.chat, first["text"], key=key)["json"]
self.assertEqual(replay, first)
self.api.call(
"POST",
"/api/v1/chats/" + self.chat["id"] + "/messages",
409,
actor=self.alice,
body={"text": "different body"},
headers={"Idempotency-Key": key},
)
def test_04_key_scope_user_and_chat(self) -> None:
key = uuid4().hex
text_alice = "scope-a-" + uuid4().hex
text_bob = "scope-b-" + uuid4().hex
alice_message = self.api.message(self.alice, self.chat, text_alice, key=key)["json"]
bob_message = self.api.message(self.bob, self.chat, text_bob, key=key)["json"]
self.assertNotEqual(alice_message["id"], bob_message["id"])
other_chat = self.api.call(
"POST",
"/api/v1/chats",
201,
actor=self.alice,
body={"title": "Другой чат", "member_ids": [self.alice["id"]]},
schema="Chat",
)["json"]
other = self.api.message(self.alice, other_chat, text_alice, key=key)["json"]
self.assertNotEqual(other["id"], alice_message["id"])
def test_05_key_validation(self) -> None:
path = "/api/v1/chats/" + self.chat["id"] + "/messages"
for bad in ("", "has space", "bad/slash", "x" * 129):
self.api.call(
"POST",
path,
400,
actor=self.alice,
body={"text": "bad-key"},
headers={"Idempotency-Key": bad},
)
self.api.call("POST", path, 400, actor=self.alice, body={"text": "no key"})
for good in ("a", "z" * 128):
self.api.message(self.alice, self.chat, "boundary-" + uuid4().hex, key=good)
def test_06_uncertain_retry_is_safe(self) -> None:
"""Повтор с тем же ключом после потери ответа не создаёт второй объект."""
key = uuid4().hex
text = "retry-after-conflict-" + uuid4().hex
first = self.api.message(self.alice, self.chat, text, key=key)["json"]
again = self.api.message(self.alice, self.chat, text, key=key)["json"]
self.assertEqual(first, again)
if __name__ == "__main__":
unittest.main(verbosity=2)