From 8f89c7c43b66be8f0fde1a401e3f4c5be8b37294 Mon Sep 17 00:00:00 2001 From: denis Date: Fri, 6 Nov 2026 18:09:01 +0300 Subject: [PATCH 1/2] solution --- .dockerignore | 10 + .env.example | 25 +- Dockerfile | 55 +++ Makefile | 18 +- REPORT.md | 314 ++++++++++++++- alembic.ini | 38 ++ evidence/01-contract-and-openapi.txt | 15 + evidence/02-public-smoke.txt | 12 + evidence/03-student-tests.txt | 18 + evidence/04-idempotency-concurrency.json | 13 + evidence/05-failover-replica-1.txt | 27 ++ evidence/06-failover-replica-2.txt | 25 ++ evidence/07-load-baseline.txt | 23 ++ evidence/08-rolling-update-under-load.txt | 34 ++ evidence/09-infrastructure.txt | 66 ++++ evidence/10-persistence.txt | 20 + evidence/load-baseline.json | 17 + evidence/rolling-load.json | 17 + migrations/env.py | 58 +++ migrations/script.py.mako | 24 ++ migrations/versions/0001_initial_schema.py | 103 +++++ .../versions/0002_message_idempotency.py | 61 +++ requirements.txt | 28 ++ scripts/bootstrap-secrets.sh | 37 ++ scripts/deploy.cmd | 4 + scripts/deploy.sh | 48 +++ scripts/hooks.ps1 | 158 ++++++++ scripts/restart.cmd | 4 + scripts/restart.sh | 23 ++ scripts/restore.cmd | 4 + scripts/restore.sh | 27 ++ scripts/rolling-update.cmd | 4 + scripts/rolling-update.sh | 20 + scripts/stop-one.cmd | 4 + scripts/stop-one.sh | 50 +++ src/messenger/__init__.py | 5 + src/messenger/__main__.py | 38 ++ src/messenger/access.py | 16 + src/messenger/app.py | 127 +++++++ src/messenger/config.py | 290 ++++++++++++++ src/messenger/context.py | 23 ++ src/messenger/cursor.py | 119 ++++++ src/messenger/db.py | 74 ++++ src/messenger/deps.py | 119 ++++++ src/messenger/domain.py | 84 ++++ src/messenger/errorhandlers.py | 157 ++++++++ src/messenger/errors.py | 78 ++++ src/messenger/healthcheck.py | 26 ++ src/messenger/idempotency.py | 36 ++ src/messenger/logging_setup.py | 76 ++++ src/messenger/middleware.py | 99 +++++ src/messenger/models.py | 209 ++++++++++ src/messenger/pagination.py | 38 ++ src/messenger/repository.py | 358 ++++++++++++++++++ src/messenger/routers/__init__.py | 1 + src/messenger/routers/auth.py | 51 +++ src/messenger/routers/chats.py | 55 +++ src/messenger/routers/health.py | 42 ++ src/messenger/routers/messages.py | 62 +++ src/messenger/routers/users.py | 34 ++ src/messenger/schema.py | 124 ++++++ src/messenger/security.py | 119 ++++++ src/messenger/sessions.py | 122 ++++++ stack.yaml | 223 +++++++++++ student-tests/README.md | 17 + student-tests/harness.py | 74 ++++ student-tests/idempotency_probe.py | 53 +++ student-tests/test_lab3.py | 108 ++++++ 68 files changed, 4432 insertions(+), 29 deletions(-) create mode 100644 Dockerfile create mode 100644 alembic.ini create mode 100644 evidence/01-contract-and-openapi.txt create mode 100644 evidence/02-public-smoke.txt create mode 100644 evidence/03-student-tests.txt create mode 100644 evidence/04-idempotency-concurrency.json create mode 100644 evidence/05-failover-replica-1.txt create mode 100644 evidence/06-failover-replica-2.txt create mode 100644 evidence/07-load-baseline.txt create mode 100644 evidence/08-rolling-update-under-load.txt create mode 100644 evidence/09-infrastructure.txt create mode 100644 evidence/10-persistence.txt create mode 100644 evidence/load-baseline.json create mode 100644 evidence/rolling-load.json create mode 100644 migrations/env.py create mode 100644 migrations/script.py.mako create mode 100644 migrations/versions/0001_initial_schema.py create mode 100644 migrations/versions/0002_message_idempotency.py create mode 100644 requirements.txt create mode 100644 scripts/bootstrap-secrets.sh create mode 100644 scripts/deploy.cmd create mode 100644 scripts/deploy.sh create mode 100644 scripts/hooks.ps1 create mode 100644 scripts/restart.cmd create mode 100644 scripts/restart.sh create mode 100644 scripts/restore.cmd create mode 100644 scripts/restore.sh create mode 100644 scripts/rolling-update.cmd create mode 100644 scripts/rolling-update.sh create mode 100644 scripts/stop-one.cmd create mode 100644 scripts/stop-one.sh create mode 100644 src/messenger/__init__.py create mode 100644 src/messenger/__main__.py create mode 100644 src/messenger/access.py create mode 100644 src/messenger/app.py create mode 100644 src/messenger/config.py create mode 100644 src/messenger/context.py create mode 100644 src/messenger/cursor.py create mode 100644 src/messenger/db.py create mode 100644 src/messenger/deps.py create mode 100644 src/messenger/domain.py create mode 100644 src/messenger/errorhandlers.py create mode 100644 src/messenger/errors.py create mode 100644 src/messenger/healthcheck.py create mode 100644 src/messenger/idempotency.py create mode 100644 src/messenger/logging_setup.py create mode 100644 src/messenger/middleware.py create mode 100644 src/messenger/models.py create mode 100644 src/messenger/pagination.py create mode 100644 src/messenger/repository.py create mode 100644 src/messenger/routers/__init__.py create mode 100644 src/messenger/routers/auth.py create mode 100644 src/messenger/routers/chats.py create mode 100644 src/messenger/routers/health.py create mode 100644 src/messenger/routers/messages.py create mode 100644 src/messenger/routers/users.py create mode 100644 src/messenger/schema.py create mode 100644 src/messenger/security.py create mode 100644 src/messenger/sessions.py create mode 100644 stack.yaml create mode 100644 student-tests/README.md create mode 100644 student-tests/harness.py create mode 100644 student-tests/idempotency_probe.py create mode 100644 student-tests/test_lab3.py diff --git a/.dockerignore b/.dockerignore index bc16e556..4b96220f 100644 --- a/.dockerignore +++ b/.dockerignore @@ -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 diff --git a/.env.example b/.env.example index d32b9be0..aa0b1fd0 100644 --- a/.env.example +++ b/.env.example @@ -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. \ No newline at end of file diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 00000000..79ffc3c8 --- /dev/null +++ b/Dockerfile @@ -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"] \ No newline at end of file diff --git a/Makefile b/Makefile index 5d86d171..1bd7a630 100644 --- a/Makefile +++ b/Makefile @@ -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)" diff --git a/REPORT.md b/REPORT.md index c2679005..d95b8bf0 100644 --- a/REPORT.md +++ b/REPORT.md @@ -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 && 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:` с абсолютным 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, поэтому + токен работает на любой реплике. \ No newline at end of file diff --git a/alembic.ini b/alembic.ini new file mode 100644 index 00000000..e299f789 --- /dev/null +++ b/alembic.ini @@ -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 diff --git a/evidence/01-contract-and-openapi.txt b/evidence/01-contract-and-openapi.txt new file mode 100644 index 00000000..40cdc60b --- /dev/null +++ b/evidence/01-contract-and-openapi.txt @@ -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. diff --git a/evidence/02-public-smoke.txt b/evidence/02-public-smoke.txt new file mode 100644 index 00000000..69128028 --- /dev/null +++ b/evidence/02-public-smoke.txt @@ -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 на каждом ответе, включая ошибки. diff --git a/evidence/03-student-tests.txt b/evidence/03-student-tests.txt new file mode 100644 index 00000000..9240917c --- /dev/null +++ b/evidence/03-student-tests.txt @@ -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 и ровно одно сообщение в истории. diff --git a/evidence/04-idempotency-concurrency.json b/evidence/04-idempotency-concurrency.json new file mode 100644 index 00000000..3b8fcfdf --- /dev/null +++ b/evidence/04-idempotency-concurrency.json @@ -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 с одним ключом и одним телом прошли через две разные реплики; создано одно сообщение, все ответы побайтно совпадают." +} diff --git a/evidence/05-failover-replica-1.txt b/evidence/05-failover-replica-1.txt new file mode 100644 index 00000000..10fbf0e2 --- /dev/null +++ b/evidence/05-failover-replica-1.txt @@ -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= +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, все повторены с исходным ключом. \ No newline at end of file diff --git a/evidence/06-failover-replica-2.txt b/evidence/06-failover-replica-2.txt new file mode 100644 index 00000000..9d37a685 --- /dev/null +++ b/evidence/06-failover-replica-2.txt @@ -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 перед следующей. \ No newline at end of file diff --git a/evidence/07-load-baseline.txt b/evidence/07-load-baseline.txt new file mode 100644 index 00000000..148ad9d4 --- /dev/null +++ b/evidence/07-load-baseline.txt @@ -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-клиент на том же хосте. diff --git a/evidence/08-rolling-update-under-load.txt b/evidence/08-rolling-update-under-load.txt new file mode 100644 index 00000000..9c04ab16 --- /dev/null +++ b/evidence/08-rolling-update-under-load.txt @@ -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. diff --git a/evidence/09-infrastructure.txt b/evidence/09-infrastructure.txt new file mode 100644 index 00000000..6225cd30 --- /dev/null +++ b/evidence/09-infrastructure.txt @@ -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 alembic current +0002_message_idempotency (head) +$ docker exec alembic upgrade head +(no Running upgrade: схема уже на head) +$ docker exec 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 id +uid=10001(app) gid=10001(app) groups=10001(app) +$ docker exec cat /proc/1/status +Uid: 10001 10001 10001 10001 +CapEff: 0000000000000000 + +Схема идемпотентности: +$ docker exec 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. diff --git a/evidence/10-persistence.txt b/evidence/10-persistence.txt new file mode 100644 index 00000000..458450bc --- /dev/null +++ b/evidence/10-persistence.txt @@ -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-записей. diff --git a/evidence/load-baseline.json b/evidence/load-baseline.json new file mode 100644 index 00000000..c49ec1a7 --- /dev/null +++ b/evidence/load-baseline.json @@ -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." +} diff --git a/evidence/rolling-load.json b/evidence/rolling-load.json new file mode 100644 index 00000000..27101214 --- /dev/null +++ b/evidence/rolling-load.json @@ -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." +} diff --git a/migrations/env.py b/migrations/env.py new file mode 100644 index 00000000..8478d568 --- /dev/null +++ b/migrations/env.py @@ -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()) diff --git a/migrations/script.py.mako b/migrations/script.py.mako new file mode 100644 index 00000000..c6284cb9 --- /dev/null +++ b/migrations/script.py.mako @@ -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"} diff --git a/migrations/versions/0001_initial_schema.py b/migrations/versions/0001_initial_schema.py new file mode 100644 index 00000000..4cdd21cf --- /dev/null +++ b/migrations/versions/0001_initial_schema.py @@ -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") diff --git a/migrations/versions/0002_message_idempotency.py b/migrations/versions/0002_message_idempotency.py new file mode 100644 index 00000000..56f714ed --- /dev/null +++ b/migrations/versions/0002_message_idempotency.py @@ -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") diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 00000000..192b634b --- /dev/null +++ b/requirements.txt @@ -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 \ No newline at end of file diff --git a/scripts/bootstrap-secrets.sh b/scripts/bootstrap-secrets.sh new file mode 100644 index 00000000..9f88e539 --- /dev/null +++ b/scripts/bootstrap-secrets.sh @@ -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 : 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' diff --git a/scripts/deploy.cmd b/scripts/deploy.cmd new file mode 100644 index 00000000..77170029 --- /dev/null +++ b/scripts/deploy.cmd @@ -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% diff --git a/scripts/deploy.sh b/scripts/deploy.sh new file mode 100644 index 00000000..fd241ccb --- /dev/null +++ b/scripts/deploy.sh @@ -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 \ No newline at end of file diff --git a/scripts/hooks.ps1 b/scripts/hooks.ps1 new file mode 100644 index 00000000..07f746c4 --- /dev/null +++ b/scripts/hooks.ps1 @@ -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 + } +} \ No newline at end of file diff --git a/scripts/restart.cmd b/scripts/restart.cmd new file mode 100644 index 00000000..bd5a8b23 --- /dev/null +++ b/scripts/restart.cmd @@ -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% diff --git a/scripts/restart.sh b/scripts/restart.sh new file mode 100644 index 00000000..0a4c95ce --- /dev/null +++ b/scripts/restart.sh @@ -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 \ No newline at end of file diff --git a/scripts/restore.cmd b/scripts/restore.cmd new file mode 100644 index 00000000..0d72b653 --- /dev/null +++ b/scripts/restore.cmd @@ -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% diff --git a/scripts/restore.sh b/scripts/restore.sh new file mode 100644 index 00000000..1a8984b3 --- /dev/null +++ b/scripts/restore.sh @@ -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 \ No newline at end of file diff --git a/scripts/rolling-update.cmd b/scripts/rolling-update.cmd new file mode 100644 index 00000000..62f46a43 --- /dev/null +++ b/scripts/rolling-update.cmd @@ -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% diff --git a/scripts/rolling-update.sh b/scripts/rolling-update.sh new file mode 100644 index 00000000..e2b1c15e --- /dev/null +++ b/scripts/rolling-update.sh @@ -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 \ No newline at end of file diff --git a/scripts/stop-one.cmd b/scripts/stop-one.cmd new file mode 100644 index 00000000..a7838d62 --- /dev/null +++ b/scripts/stop-one.cmd @@ -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% diff --git a/scripts/stop-one.sh b/scripts/stop-one.sh new file mode 100644 index 00000000..be99a2dc --- /dev/null +++ b/scripts/stop-one.sh @@ -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" \ No newline at end of file diff --git a/src/messenger/__init__.py b/src/messenger/__init__.py new file mode 100644 index 00000000..4db26456 --- /dev/null +++ b/src/messenger/__init__.py @@ -0,0 +1,5 @@ +"""Мессенджер на PostgreSQL и Valkey: лабораторная 3 курса HighLoad (MTUSI).""" + +__all__ = ["__version__"] + +__version__ = "3.0.0" \ No newline at end of file diff --git a/src/messenger/__main__.py b/src/messenger/__main__.py new file mode 100644 index 00000000..df116f9f --- /dev/null +++ b/src/messenger/__main__.py @@ -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()) diff --git a/src/messenger/access.py b/src/messenger/access.py new file mode 100644 index 00000000..a03d541e --- /dev/null +++ b/src/messenger/access.py @@ -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 diff --git a/src/messenger/app.py b/src/messenger/app.py new file mode 100644 index 00000000..e4237f17 --- /dev/null +++ b/src/messenger/app.py @@ -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) \ No newline at end of file diff --git a/src/messenger/config.py b/src/messenger/config.py new file mode 100644 index 00000000..ddab9b21 --- /dev/null +++ b/src/messenger/config.py @@ -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"), + ) diff --git a/src/messenger/context.py b/src/messenger/context.py new file mode 100644 index 00000000..78f326f4 --- /dev/null +++ b/src/messenger/context.py @@ -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) diff --git a/src/messenger/cursor.py b/src/messenger/cursor.py new file mode 100644 index 00000000..7f55bc15 --- /dev/null +++ b/src/messenger/cursor.py @@ -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 diff --git a/src/messenger/db.py b/src/messenger/db.py new file mode 100644 index 00000000..a03d7d57 --- /dev/null +++ b/src/messenger/db.py @@ -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() \ No newline at end of file diff --git a/src/messenger/deps.py b/src/messenger/deps.py new file mode 100644 index 00000000..f93ea2d6 --- /dev/null +++ b/src/messenger/deps.py @@ -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)] diff --git a/src/messenger/domain.py b/src/messenger/domain.py new file mode 100644 index 00000000..f35f6419 --- /dev/null +++ b/src/messenger/domain.py @@ -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 \ No newline at end of file diff --git a/src/messenger/errorhandlers.py b/src/messenger/errorhandlers.py new file mode 100644 index 00000000..2e0048a7 --- /dev/null +++ b/src/messenger/errorhandlers.py @@ -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, "Внутренняя ошибка сервера") diff --git a/src/messenger/errors.py b/src/messenger/errors.py new file mode 100644 index 00000000..42dfd951 --- /dev/null +++ b/src/messenger/errors.py @@ -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) diff --git a/src/messenger/healthcheck.py b/src/messenger/healthcheck.py new file mode 100644 index 00000000..d0585bd0 --- /dev/null +++ b/src/messenger/healthcheck.py @@ -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()) diff --git a/src/messenger/idempotency.py b/src/messenger/idempotency.py new file mode 100644 index 00000000..b3bfc358 --- /dev/null +++ b/src/messenger/idempotency.py @@ -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() diff --git a/src/messenger/logging_setup.py b/src/messenger/logging_setup.py new file mode 100644 index 00000000..88ee2cd1 --- /dev/null +++ b/src/messenger/logging_setup.py @@ -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, + ) diff --git a/src/messenger/middleware.py b/src/messenger/middleware.py new file mode 100644 index 00000000..63b4365d --- /dev/null +++ b/src/messenger/middleware.py @@ -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, + ) \ No newline at end of file diff --git a/src/messenger/models.py b/src/messenger/models.py new file mode 100644 index 00000000..c96972de --- /dev/null +++ b/src/messenger/models.py @@ -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) diff --git a/src/messenger/pagination.py b/src/messenger/pagination.py new file mode 100644 index 00000000..4a342dc2 --- /dev/null +++ b/src/messenger/pagination.py @@ -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)) diff --git a/src/messenger/repository.py b/src/messenger/repository.py new file mode 100644 index 00000000..c65a7cda --- /dev/null +++ b/src/messenger/repository.py @@ -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()} \ No newline at end of file diff --git a/src/messenger/routers/__init__.py b/src/messenger/routers/__init__.py new file mode 100644 index 00000000..acd99363 --- /dev/null +++ b/src/messenger/routers/__init__.py @@ -0,0 +1 @@ +"""Маршруты HTTP API: только разбор запроса, вызов зависимостей и сборка ответа.""" diff --git a/src/messenger/routers/auth.py b/src/messenger/routers/auth.py new file mode 100644 index 00000000..c9ccb566 --- /dev/null +++ b/src/messenger/routers/auth.py @@ -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) diff --git a/src/messenger/routers/chats.py b/src/messenger/routers/chats.py new file mode 100644 index 00000000..dee42e57 --- /dev/null +++ b/src/messenger/routers/chats.py @@ -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)) diff --git a/src/messenger/routers/health.py b/src/messenger/routers/health.py new file mode 100644 index 00000000..bf921f46 --- /dev/null +++ b/src/messenger/routers/health.py @@ -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() \ No newline at end of file diff --git a/src/messenger/routers/messages.py b/src/messenger/routers/messages.py new file mode 100644 index 00000000..1cf8d9ef --- /dev/null +++ b/src/messenger/routers/messages.py @@ -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) + ) \ No newline at end of file diff --git a/src/messenger/routers/users.py b/src/messenger/routers/users.py new file mode 100644 index 00000000..86dfb6bc --- /dev/null +++ b/src/messenger/routers/users.py @@ -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) diff --git a/src/messenger/schema.py b/src/messenger/schema.py new file mode 100644 index 00000000..328b7da9 --- /dev/null +++ b/src/messenger/schema.py @@ -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"), +) diff --git a/src/messenger/security.py b/src/messenger/security.py new file mode 100644 index 00000000..ea0e343a --- /dev/null +++ b/src/messenger/security.py @@ -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) diff --git a/src/messenger/sessions.py b/src/messenger/sessions.py new file mode 100644 index 00000000..e9e5700a --- /dev/null +++ b/src/messenger/sessions.py @@ -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() diff --git a/stack.yaml b/stack.yaml new file mode 100644 index 00000000..b25ad6b6 --- /dev/null +++ b/stack.yaml @@ -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 \ No newline at end of file diff --git a/student-tests/README.md b/student-tests/README.md new file mode 100644 index 00000000..33b86a94 --- /dev/null +++ b/student-tests/README.md @@ -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`. diff --git a/student-tests/harness.py b/student-tests/harness.py new file mode 100644 index 00000000..af5c5223 --- /dev/null +++ b/student-tests/harness.py @@ -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 diff --git a/student-tests/idempotency_probe.py b/student-tests/idempotency_probe.py new file mode 100644 index 00000000..42dcdc56 --- /dev/null +++ b/student-tests/idempotency_probe.py @@ -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()) \ No newline at end of file diff --git a/student-tests/test_lab3.py b/student-tests/test_lab3.py new file mode 100644 index 00000000..4519bb70 --- /dev/null +++ b/student-tests/test_lab3.py @@ -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) \ No newline at end of file -- 2.54.0 From 94732d2ceee248506973d12c9b7a34ecd6ba71cf Mon Sep 17 00:00:00 2001 From: denis Date: Fri, 6 Nov 2026 18:09:08 +0300 Subject: [PATCH 2/2] solution --- student-tests/run_all.py | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 student-tests/run_all.py diff --git a/student-tests/run_all.py b/student-tests/run_all.py new file mode 100644 index 00000000..6d3731ef --- /dev/null +++ b/student-tests/run_all.py @@ -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()) -- 2.54.0