diff --git a/.env.example b/.env.example index d32b9be0..29bc03ec 100644 --- a/.env.example +++ b/.env.example @@ -4,10 +4,9 @@ APP_HOST=0.0.0.0 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_REPLICAS=2 -IDEMPOTENCY_TTL_SECONDS=86400 + +POSTGRES_USER=messenger +POSTGRES_PASSWORD=change-me-local +POSTGRES_DB=messenger +DATABASE_URL=postgresql+asyncpg://messenger:change-me-local@postgres:5432/messenger +REDIS_URL=redis://redis:6379/0 diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 00000000..2997c107 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,17 @@ +FROM python:3.13.15-slim + +WORKDIR /app +COPY requirements.txt . +RUN python -m pip install -r requirements.txt \ + && useradd --uid 10001 --user-group --no-create-home --shell /usr/sbin/nologin app +COPY app ./app +COPY alembic ./alembic +COPY alembic.ini . + +USER 10001:10001 +EXPOSE 8080 + +HEALTHCHECK --interval=10s --timeout=3s --start-period=5s --retries=3 \ + CMD ["python", "-c", "import urllib.request;urllib.request.urlopen('http://127.0.0.1:8080/health/ready',timeout=3).read()"] + +CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8080", "--timeout-graceful-shutdown", "5"] diff --git a/Dockerfile.test b/Dockerfile.test new file mode 100644 index 00000000..51c08a89 --- /dev/null +++ b/Dockerfile.test @@ -0,0 +1,14 @@ +FROM python:3.13.15-slim + +WORKDIR /tests +COPY requirements-dev.txt . +RUN python -m pip install --no-cache-dir -r requirements-dev.txt \ + && useradd --uid 10001 --user-group --no-create-home --shell /usr/sbin/nologin tests + +COPY lab.json . +COPY contracts ./contracts +COPY tests ./tests +RUN chown -R tests:tests /tests + +USER 10001:10001 +CMD ["pytest", "-q"] diff --git a/Makefile b/Makefile index 5d86d171..b32dc6d6 100644 --- a/Makefile +++ b/Makefile @@ -4,7 +4,7 @@ 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 test-idempotency load test-persistence test-failover help: @echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes" @@ -18,6 +18,9 @@ validate: test: $(PYTHON) tests/smoke.py --base-url "$(BASE_URL)" $(TLS_ARGS) +test-idempotency: + BASE_URL="$(BASE_URL)" CA_FILE="$(CA_FILE)" $(PYTHON) -m pytest -q tests/test_idempotency.py + load: $(PYTHON) tests/load.py --base-url "$(BASE_URL)" $(TLS_ARGS) diff --git a/REPORT.md b/REPORT.md index c2679005..e5237bd4 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,148 @@ # Отчёт — лабораторная 3 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- Автор, группа: Сергей Возжин, БПИ2301. +- Целевая оценка: 4; трек 5 не выбран. +- Merge Request: https://gitea.privcloud.tech/mtusi2026/mtusi2026lab3/pulls/48 +- Использованные источники: материалы и контракт репозитория, документация Docker Compose и HAProxy. +- Библиотеки: FastAPI, Uvicorn, SQLAlchemy, asyncpg, Alembic, redis-py, Argon2, pytest. +- Помощь ИИ: OpenAI Codex использовался для плана, реализации lab3, тестов, сценариев отказа и оформления отчёта; результат проверен исполняемыми тестами. ## Запуск из чистого clone -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +Требуются Docker Engine с Compose v2, Python 3.9+ для публичных тестов и свободный host-порт 8080. Проверенный стенд: Docker 28.0.4, Compose 2.34.0, API на Python 3.13.15. Образы: `python:3.13.15-slim`, `haproxy:3.2.26-alpine`, `postgres:17.4-alpine`, `redis:7.4.2-alpine`. + +Создать локальную конфигурацию, не добавляя её в Git: + +```sh +cp .env.example .env +``` + +Перед запуском заменить учебный пароль PostgreSQL в `.env` и ту же часть пароля в `DATABASE_URL`. Сам `.env` игнорируется Git. Все данные тестов должны быть синтетическими. + +Проверить конфигурацию, собрать образы, однократно применить миграции и дождаться готовности: + +```sh +docker compose --env-file .env config --quiet +docker compose --env-file .env up -d --build --wait +docker compose --env-file .env ps +``` + +`migrate` выполняет `alembic upgrade head` один раз. Две реплики `api` стартуют только после успешной миграции и готовности Redis; HAProxy стартует после готовности API. Единственная публичная точка входа — `http://localhost:8080`. + +Полный набор проверок: + +```sh +python3 -m venv .venv +.venv/bin/python -m pip install -r requirements-dev.txt +make check +make validate PYTHON=.venv/bin/python +make test +make test-idempotency PYTHON=.venv/bin/python +make test-persistence ACTION_SCRIPT=scripts/restart.sh +make test-failover ACTION_SCRIPT=scripts/stop-one.sh +``` + +После failover восстановить вторую реплику и дождаться готовности: + +```sh +docker compose --env-file .env up -d --wait --wait-timeout 60 api lb +``` + +Для проверки другой реплики повторить `make test-failover` после восстановления первой. Для поочерёдной замены под нагрузкой запустить `tests/load.py`, параллельно выполнить `scripts/rolling-update.sh` и сохранить агрегаты. + +Безопасная остановка с сохранением named volumes: + +```sh +docker compose --env-file .env down +``` + +Намеренное необратимое удаление всех учебных данных выполняется только оператором: + +```sh +docker compose --env-file .env down -v +``` ## Архитектура и решения -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +```text +HTTP client + | + v +HAProxy :8080 + | + +-- round-robin --> API replica 1 --+ + | +--> PostgreSQL + +-- round-robin --> API replica 2 --+--> Redis sessions +``` + +PostgreSQL — источник истины для пользователей, чатов, участников и сообщений. Redis — общее хранилище действующих сессий с AOF. Локального значимого состояния у API нет; sticky sessions не используются. + +Из lab2 перенесены REST API, PostgreSQL, Redis-сессии, password KDF и миграции. В lab3 добавлены HAProxy, две API-реплики, `X-Instance-Id`, обязательный `Idempotency-Key`, конкурентная проверка и сценарии отказа/замены. + +Каждый API-процесс один раз берёт `X-Instance-Id` из hostname контейнера. Middleware добавляет его во все созданные API ответы. Значение меняется при замене контейнера. + +Идемпотентность сообщения хранится в PostgreSQL. Уникальность `(sender_id, chat_id, idempotency_key)` соответствует области пользователь + метод отправки сообщения + путь чата + ключ. `INSERT ... ON CONFLICT DO NOTHING` и чтение существующей строки выполняются в одной транзакции. Одинаковое тело возвращает исходный `201 Message`, другое тело — `409`. Ограничение хранится дольше обязательных 24 часов. + +Миграция выполняется отдельно. Поле `idempotency_key` nullable: старая версия может продолжать писать `NULL`, новая читает старые записи. Создание unique constraint может блокировать большую production-таблицу; это ограничение учебной миграции описано и не маскируется. + +HAProxy использует round-robin и Docker DNS `127.0.0.11`. `/health/ready` проверяется каждую секунду с `fall 2`, `rise 2`, `timeout check 2s`. При быстром отказе типичное исключение занимает 2–3 секунды; консервативная верхняя оценка с двумя полными timeout — около 6 секунд. Наблюдавшееся восстановление записи — 2,560–3,248 секунды, что меньше требуемых 10 секунд. + +Таймауты HAProxy: connect/check 2 секунды, client/server 30 секунд. Uvicorn прекращает принимать новые соединения по SIGTERM, имеет graceful shutdown 5 секунд, Compose даёт API `stop_grace_period` 10 секунд. + +Лимиты контейнеров: + +| Сервис | CPU | RAM | +| --- | ---: | ---: | +| API, каждая реплика | 0,5 | 256 MiB | +| HAProxy | 0,25 | 128 MiB | +| PostgreSQL | 1,0 | 512 MiB | +| Redis | 0,25 | 128 MiB | +| migrate | 0,5 | 256 MiB | + +Наружу опубликован только порт HAProxy. PostgreSQL, Redis и API доступны только в Compose-сети. `DATABASE_URL` получают только API и migrate; настройки PostgreSQL — только сам PostgreSQL. `container_name` отсутствует. + +Переменные `.env.example`: `APP_PORT` задаёт host-порт HAProxy; `POSTGRES_*` настраивают PostgreSQL; `DATABASE_URL` используют API/migrate; `REDIS_URL` используют API/migrate; `SESSION_TTL_SECONDS` задаёт TTL серверной сессии; `LOG_LEVEL` задаёт логирование API. `APP_HOST` и `APP_ENV` оставлены как описательные учебные настройки и приложением не читаются. ## Доказательства критериев -| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | +| Критерий README | Команда/сценарий | Наблюдаемый результат | Доказательство | | --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | +| Публичный smoke | `make test` | `PASS: lab3 public API scenario` | `evidence/results.md` | +| Две реплики и одна точка входа | 20 запросов через `localhost:8080`, `docker compose ps` | два `X-Instance-Id`; host-порт есть только у HAProxy | `evidence/results.md` | +| Общая сессия | smoke/idempotency через HAProxy | одна Bearer-сессия работает на обеих репликах | `evidence/results.md` | +| Общая идемпотентность | `make test-idempotency PYTHON=.venv/bin/python` | 20 конкурентных запросов, две реплики, одно сообщение; `5 passed` | `evidence/results.md` | +| Persistence | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | данные и прежний token доступны после рестарта API/PostgreSQL/Redis | `evidence/results.md` | +| Отказ первой реплики | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | восстановление 3,248 с; 111 успешных записей за 15 с (≈7,40 RPS), 1 переходная ошибка | `evidence/results.md` | +| Отказ второй реплики | восстановление первой и повтор failover | восстановление 2,560 с; 110 успешных записей за 15 с (≈7,33 RPS), 1 переходная ошибка | `evidence/results.md` | +| Health/timeouts/SIGTERM | HAProxy checks и остановка выбранного контейнера | backend исключён, другая реплика продолжила чтение/запись | `evidence/results.md` | +| CPU/RAM и закрытые порты | `docker compose ps`, `docker stats --no-stream` | лимиты применены; наружу опубликован только 8080 HAProxy | `evidence/results.md` | +| Поочерёдная замена | `scripts/rolling-update.sh` во время `tests/load.py` | обе реплики получили новые container ID, 10 512 успешных запросов, 0 ошибок | `evidence/rolling-update.md`, `evidence/rolling-update-load.json` | -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +Трек оценки 5 не заявлен. ## Эксперименты и отказы -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. +Проверяемое ожидание: остановка любой одной API-реплики не приводит к потере подтверждённых сообщений или сессии, а новые чтения/записи возобновляются не позднее 10 секунд. + +Аппаратная конфигурация локального стенда: Apple M4 Pro, 12 CPU cores, 24 GB RAM; Docker Desktop. Основной профиль — closed-loop POST сообщений, 30 секунд, concurrency 4, без автоматических retry и отдельного временного прогрева. Bootstrap выполняется до измеряемого интервала. После профиля: 39 пользователей, 13 чатов, 18 448 сообщений, PostgreSQL 14 MB. + +Основной прогон: 9807 успешных запросов, 0 ошибок, 326,771 successful RPS, p50/p95/p99 6,436/52,344/63,559 мс. CPU/RAM по двум срезам приведены в `evidence/results.md`; обе API-реплики использовали около 50–52% CPU и 66–76 MiB RAM каждая. + +Числа двух failover-запусков взяты из JSON summary, который печатает `tests/resilience.py`: `successful_writes`, `failed_attempts` и `first_recovery_seconds`. Приблизительный RPS рассчитан как число успешных записей, делённое на 15 секунд нагрузки. Результат persistence взят из успешного завершения того же теста в режиме `persistence`. Числа поочерёдной замены взяты из `evidence/rolling-update-load.json`, записанного `tests/load.py` во время работы `scripts/rolling-update.sh`. | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +| Restart API + PostgreSQL + Redis | данные и token сохраняются | persistence PASS | время отдельно не замерялось; потерь нет | +| Остановка первой API-реплики | HAProxy оставляет вторую | 111 записей за 15 с (≈7,40 RPS), 1 краткая ошибка | 3,248 с; потерь и дублей нет | +| Остановка второй после восстановления первой | симметричный failover | 110 записей за 15 с (≈7,33 RPS), 1 краткая ошибка | 2,560 с; потерь и дублей нет | +| Поочерёдная замена двух API | трафик продолжается | 10 512 успешных запросов, 0 ошибок | явного перерыва не наблюдалось | + +`tests/load.py` — простой closed-loop генератор, ограниченный клиентом и подверженный coordinated omission. Перцентили учитывают только успешные запросы. Эти цифры описывают конкретный учебный стенд и не объявляются максимальной производительностью. ## Ограничения и следующие шаги -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +Стенд выдерживает остановку одного API-процесса при работающих HAProxy, второй API-реплике, PostgreSQL, Redis и Docker-host. Он не выдерживает потерю единственного HAProxy, PostgreSQL, Redis или всего host: это осознанные SPOF лабораторной работы. + +HAProxy и хранилища не реплицированы. Redis AOF снижает риск потери сессий при штатном перезапуске, но не является HA. Docker Compose обеспечивает локальную воспроизводимость, а не перенос контейнеров между узлами. HTTP используется только локально с синтетическими данными; TLS здесь не заявлен. Универсальная идемпотентность остальных POST, WebSocket, UI, мониторинг и требования оценки 5 намеренно не реализованы. + +Следующие возможные улучшения, не входящие в оценку 4: несколько Docker-узлов, HA для LB/БД/Redis, online-создание индекса на большой таблице и более строгий open-loop нагрузочный генератор. diff --git a/alembic.ini b/alembic.ini new file mode 100644 index 00000000..5c6d9f28 --- /dev/null +++ b/alembic.ini @@ -0,0 +1,36 @@ +[alembic] +script_location = alembic +prepend_sys_path = . +sqlalchemy.url = placeholder://configured-at-runtime + +[loggers] +keys = root,sqlalchemy,alembic + +[handlers] +keys = console + +[formatters] +keys = generic + +[logger_root] +level = WARN +handlers = console + +[logger_sqlalchemy] +level = WARN +handlers = +qualname = sqlalchemy.engine + +[logger_alembic] +level = INFO +handlers = +qualname = alembic + +[handler_console] +class = StreamHandler +args = (sys.stderr,) +level = NOTSET +formatter = generic + +[formatter_generic] +format = %(levelname)-5.5s [%(name)s] %(message)s diff --git a/alembic/env.py b/alembic/env.py new file mode 100644 index 00000000..24524a9f --- /dev/null +++ b/alembic/env.py @@ -0,0 +1,53 @@ +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 app.config import load_settings +from app.db.postgres import Base +from app import models # noqa: F401 - imports ORM models into Base.metadata + +config = context.config +if config.config_file_name is not None: + fileConfig(config.config_file_name) + +target_metadata = Base.metadata + + +def _url() -> str: + return load_settings().database_url + + +def run_migrations_offline() -> None: + context.configure(url=_url(), target_metadata=target_metadata, literal_binds=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) + with context.begin_transaction(): + context.run_migrations() + + +async def _run_migrations_async() -> None: + configuration = config.get_section(config.config_ini_section, {}) + configuration['sqlalchemy.url'] = _url() + connectable = async_engine_from_config(configuration, prefix='sqlalchemy.', poolclass=pool.NullPool) + async with connectable.connect() as connection: + await connection.run_sync(_run_migrations) + await connectable.dispose() + + +def run_migrations_online() -> None: + asyncio.run(_run_migrations_async()) + + +if context.is_offline_mode(): + run_migrations_offline() +else: + run_migrations_online() diff --git a/alembic/script.py.mako b/alembic/script.py.mako new file mode 100644 index 00000000..36cd8efe --- /dev/null +++ b/alembic/script.py.mako @@ -0,0 +1,22 @@ +"""${message} + +Revision ID: ${up_revision} +Revises: ${down_revision | comma,n} +Create Date: ${create_date} +""" +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/alembic/versions/20261019_0001_initial_schema.py b/alembic/versions/20261019_0001_initial_schema.py new file mode 100644 index 00000000..e72e2f09 --- /dev/null +++ b/alembic/versions/20261019_0001_initial_schema.py @@ -0,0 +1,64 @@ +"""Initial PostgreSQL schema for lab 2. + +Revision ID: 20261019_0001 +Revises: +Create Date: 2026-10-19 +""" +from alembic import op +import sqlalchemy as sa + + +revision = '20261019_0001' +down_revision = None +branch_labels = None +depends_on = None + + +def upgrade() -> None: + op.create_table( + 'users', + sa.Column('id', sa.Uuid(), nullable=False), + sa.Column('username', sa.String(length=32), nullable=False), + sa.Column('display_name', sa.String(length=100), nullable=False), + sa.Column('password_hash', sa.Text(), nullable=False), + sa.Column('created_at', sa.DateTime(timezone=True), nullable=False), + sa.PrimaryKeyConstraint('id'), + sa.UniqueConstraint('username'), + ) + op.create_table( + 'chats', + sa.Column('id', sa.Uuid(), nullable=False), + sa.Column('title', sa.String(length=100), nullable=False), + sa.Column('created_at', sa.DateTime(timezone=True), nullable=False), + sa.PrimaryKeyConstraint('id'), + ) + op.create_table( + 'chat_members', + sa.Column('chat_id', sa.Uuid(), nullable=False), + sa.Column('user_id', sa.Uuid(), nullable=False), + sa.ForeignKeyConstraint(['chat_id'], ['chats.id'], ondelete='CASCADE'), + sa.ForeignKeyConstraint(['user_id'], ['users.id'], ondelete='CASCADE'), + sa.PrimaryKeyConstraint('chat_id', 'user_id'), + ) + op.create_index('chat_members_user_chat_idx', 'chat_members', ['user_id', 'chat_id']) + op.create_table( + 'messages', + sa.Column('id', sa.Uuid(), nullable=False), + sa.Column('chat_id', sa.Uuid(), nullable=False), + sa.Column('sender_id', sa.Uuid(), nullable=False), + sa.Column('text', sa.String(length=4000), nullable=False), + sa.Column('created_at', sa.DateTime(timezone=True), nullable=False), + sa.ForeignKeyConstraint(['chat_id'], ['chats.id'], ondelete='CASCADE'), + sa.ForeignKeyConstraint(['sender_id'], ['users.id']), + sa.PrimaryKeyConstraint('id'), + ) + op.create_index('messages_history_idx', 'messages', ['chat_id', 'created_at', 'id']) + + +def downgrade() -> None: + op.drop_index('messages_history_idx', table_name='messages') + op.drop_table('messages') + op.drop_index('chat_members_user_chat_idx', table_name='chat_members') + op.drop_table('chat_members') + op.drop_table('chats') + op.drop_table('users') diff --git a/alembic/versions/20261023_0002_message_idempotency.py b/alembic/versions/20261023_0002_message_idempotency.py new file mode 100644 index 00000000..60d5eebe --- /dev/null +++ b/alembic/versions/20261023_0002_message_idempotency.py @@ -0,0 +1,35 @@ +"""Add shared message idempotency for lab 3. + +Revision ID: 20261023_0002 +Revises: 20261019_0001 +Create Date: 2026-10-23 +""" +from alembic import op +import sqlalchemy as sa + + +revision = '20261023_0002' +down_revision = '20261019_0001' +branch_labels = None +depends_on = None + + +def upgrade() -> None: + op.add_column( + 'messages', + sa.Column('idempotency_key', sa.String(length=128), nullable=True), + ) + op.create_unique_constraint( + 'messages_sender_chat_idempotency_key', + 'messages', + ['sender_id', 'chat_id', 'idempotency_key'], + ) + + +def downgrade() -> None: + op.drop_constraint( + 'messages_sender_chat_idempotency_key', + 'messages', + type_='unique', + ) + op.drop_column('messages', 'idempotency_key') diff --git a/app/__init__.py b/app/__init__.py new file mode 100644 index 00000000..af04c352 --- /dev/null +++ b/app/__init__.py @@ -0,0 +1 @@ +"""Мессенджер на PostgreSQL и Redis, лабораторная 2.""" diff --git a/app/api/__init__.py b/app/api/__init__.py new file mode 100644 index 00000000..97e2e0cc --- /dev/null +++ b/app/api/__init__.py @@ -0,0 +1 @@ +"""HTTP-граница: FastAPI, коды состояния, формат ошибок, курсоры.""" diff --git a/app/api/cursors.py b/app/api/cursors.py new file mode 100644 index 00000000..f0a93957 --- /dev/null +++ b/app/api/cursors.py @@ -0,0 +1,28 @@ +import base64 +import json +from uuid import UUID + +from ..domain.errors import Invalid +from ..domain.models import Keyset +from .timefmt import from_rfc3339, to_rfc3339 + +MAX_LENGTH = 512 + + +def encode(scope: str, position: Keyset) -> str: + payload = {'s': scope, 't': to_rfc3339(position.created_at), 'i': str(position.id)} + raw = json.dumps(payload, separators=(',', ':'), sort_keys=True).encode('utf-8') + return base64.urlsafe_b64encode(raw).decode('ascii').rstrip('=') + + +def decode(scope: str, value: str) -> Keyset: + if not value or len(value) > MAX_LENGTH: + raise Invalid('cursor недействителен для этого запроса') + try: + raw = base64.urlsafe_b64decode(value + '=' * (-len(value) % 4)) + payload = json.loads(raw) + if not isinstance(payload, dict) or payload.get('s') != scope: + raise ValueError('scope mismatch') + return Keyset(created_at=from_rfc3339(payload['t']), id=UUID(payload['i'])) + except Exception: + raise Invalid('cursor недействителен для этого запроса') from None diff --git a/app/api/deps.py b/app/api/deps.py new file mode 100644 index 00000000..10d16267 --- /dev/null +++ b/app/api/deps.py @@ -0,0 +1,72 @@ +from __future__ import annotations + +from dataclasses import dataclass + +from fastapi import Depends, Header, HTTPException, Request, status + +from ..db.redis import RedisSessionStore +from ..domain.errors import Unauthorized +from ..domain.models import User +from ..services.chats import ChatService +from ..services.messages import MessageService +from ..services.users import UserService + +_BEARER_CHALLENGE = 'Bearer realm="messenger"' + + +@dataclass(frozen=True, slots=True) +class Services: + users: UserService + chats: ChatService + messages: MessageService + sessions: RedisSessionStore + + +def services(request: Request) -> Services: + return request.app.state.services + + +def user_service(container: Services = Depends(services)) -> UserService: + return container.users + + +def chat_service(container: Services = Depends(services)) -> ChatService: + return container.chats + + +def message_service(container: Services = Depends(services)) -> MessageService: + return container.messages + + +def session_store(container: Services = Depends(services)) -> RedisSessionStore: + return container.sessions + + +def _bearer_error() -> HTTPException: + return HTTPException( + status_code=status.HTTP_401_UNAUTHORIZED, + detail='требуется действующая Bearer-сессия', + headers={'WWW-Authenticate': _BEARER_CHALLENGE}, + ) + + +async def bearer_token(authorization: str | None = Header(None)) -> str: + if not authorization: + raise _bearer_error() + scheme, separator, token = authorization.partition(' ') + if scheme.lower() != 'bearer' or not separator or not token or token.strip() != token: + raise _bearer_error() + return token + + +async def current_user( + token: str = Depends(bearer_token), + container: Services = Depends(services), +) -> User: + user_id = await container.sessions.get_user_id(token) + if user_id is None: + raise _bearer_error() + try: + return await container.users.identify(user_id) + except Unauthorized: + raise _bearer_error() from None diff --git a/app/api/errors.py b/app/api/errors.py new file mode 100644 index 00000000..85a7c8e4 --- /dev/null +++ b/app/api/errors.py @@ -0,0 +1,96 @@ +import logging + +from fastapi import FastAPI +from fastapi.exceptions import RequestValidationError +from fastapi.responses import JSONResponse +from sqlalchemy.exc import SQLAlchemyError +from starlette.exceptions import HTTPException as StarletteHTTPException + +from ..domain.errors import Conflict, DomainError, Invalid, NotFound, Unauthorized, Unavailable + +logger = logging.getLogger('app.error') + +CODE_BY_STATUS = { + 400: 'invalid_request', + 401: 'unauthorized', + 404: 'not_found', + 409: 'conflict', + 413: 'payload_too_large', + 415: 'unsupported_media_type', + 429: 'rate_limited', + 500: 'internal_error', + 503: 'unavailable', +} + +STATUS_BY_DOMAIN = { + Invalid: 400, + Unauthorized: 401, + NotFound: 404, + Conflict: 409, + Unavailable: 503, +} + + +def code_for(status: int) -> str: + if status in CODE_BY_STATUS: + return CODE_BY_STATUS[status] + return 'invalid_request' if status < 500 else 'internal_error' + + +def error_response(status: int, message: str, request_id: str, code: str = '') -> JSONResponse: + return JSONResponse( + status_code=status, + content={'error': {'code': code or code_for(status), 'message': message, 'request_id': request_id}}, + ) + + +def _domain_status(error: DomainError) -> int: + for kind, status in STATUS_BY_DOMAIN.items(): + if isinstance(error, kind): + return status + return 500 + + +def _describe(error: RequestValidationError) -> str: + """Краткое указание на пол, без stack trace и внутреннего устройства""" + for item in error.errors(): + if item.get('type') == 'json_invalid': + return 'тело запроса не является корректным JSON' + location = '.'.join(str(part) for part in item.get('loc', ()) if part != 'body') + return f'некорректное поле {location}' if location else 'некорректный запрос' + return 'некорректный запрос' + + +def request_id(request) -> str: + return getattr(request.state, 'request_id', 'unknown') + + +def install(app: FastAPI) -> None: + @app.exception_handler(DomainError) + async def _on_domain(request, error: DomainError) -> JSONResponse: + return error_response(_domain_status(error), error.message, request_id(request)) + + @app.exception_handler(RequestValidationError) + async def _on_validation(request, error: RequestValidationError) -> JSONResponse: + return error_response(400, _describe(error), request_id(request)) + + @app.exception_handler(SQLAlchemyError) + async def _on_database(request, error: SQLAlchemyError) -> JSONResponse: + logger.warning('database error request_id=%s type=%s', request_id(request), type(error).__name__) + return error_response(503, 'база данных недоступна', request_id(request)) + + @app.exception_handler(OSError) + async def _on_storage_socket(request, error: OSError) -> JSONResponse: + logger.warning('storage socket error request_id=%s type=%s', request_id(request), type(error).__name__) + return error_response(503, 'обязательное хранилище недоступно', request_id(request)) + + @app.exception_handler(StarletteHTTPException) + async def _on_http(request, error: StarletteHTTPException) -> JSONResponse: + message = error.detail if isinstance(error.detail, str) and error.detail else 'ошибка запроса' + response = error_response(error.status_code, message, request_id(request)) + for name, value in (error.headers or {}).items(): + response.headers[name] = value + return response + + +__all__ = ['code_for', 'error_response', 'install'] diff --git a/app/api/middleware.py b/app/api/middleware.py new file mode 100644 index 00000000..fb4e64f1 --- /dev/null +++ b/app/api/middleware.py @@ -0,0 +1,43 @@ +import logging +import os +import socket +from uuid import uuid4 + +from starlette.datastructures import MutableHeaders + +from .errors import error_response + +logger = logging.getLogger('app') + + +class RequestContext: + def __init__(self, app) -> None: + self.app = app + self.instance_id = os.getenv('INSTANCE_ID') or socket.gethostname() + + async def __call__(self, scope, receive, send) -> None: + if scope['type'] != 'http': + await self.app(scope, receive, send) + return + + request_id = uuid4().hex + scope.setdefault('state', {})['request_id'] = request_id + started = False + + async def send_wrapper(message) -> None: + nonlocal started + if message['type'] == 'http.response.start': + started = True + headers = MutableHeaders(scope=message) + headers['X-Request-Id'] = request_id + headers['X-Instance-Id'] = self.instance_id + await send(message) + + try: + await self.app(scope, receive, send_wrapper) + except Exception: + logger.exception(f'unhandled error request_id={request_id} path={scope.get("path")}') + if started: + raise + response = error_response(500, 'внутренняя ошибка', request_id) + await response(scope, receive, send_wrapper) diff --git a/app/api/routers/__init__.py b/app/api/routers/__init__.py new file mode 100644 index 00000000..dede845e --- /dev/null +++ b/app/api/routers/__init__.py @@ -0,0 +1,3 @@ +from . import auth, chats, health, messages, users + +__all__ = ['auth', 'chats', 'health', 'messages', 'users'] diff --git a/app/api/routers/auth.py b/app/api/routers/auth.py new file mode 100644 index 00000000..e41e8b1c --- /dev/null +++ b/app/api/routers/auth.py @@ -0,0 +1,71 @@ +from __future__ import annotations + +import base64 +from binascii import Error as Base64Error + +from fastapi import APIRouter, Depends, Header, HTTPException, status + +from ...auth.tokens import create_token +from ...db.redis import RedisSessionStore +from ...domain.models import User +from ...services.users import UserService +from ..deps import bearer_token, current_user, session_store, user_service +from ..schemas import SessionOut, UserOut +from ..timefmt import to_rfc3339 + +router = APIRouter(prefix='/api/v1/auth/sessions', tags=['auth']) + +_BASIC_CHALLENGE = 'Basic realm="messenger", charset="UTF-8"' + + +def _unauthorized_basic() -> HTTPException: + return HTTPException( + status_code=status.HTTP_401_UNAUTHORIZED, + detail='неверные учётные данные', + headers={'WWW-Authenticate': _BASIC_CHALLENGE}, + ) + + +def _parse_basic(authorization: str | None) -> tuple[str, str]: + if not authorization: + raise _unauthorized_basic() + scheme, separator, encoded = authorization.partition(' ') + if scheme.lower() != 'basic' or not separator or not encoded: + raise _unauthorized_basic() + try: + decoded = base64.b64decode(encoded, validate=True).decode('utf-8') + except (Base64Error, UnicodeDecodeError): + raise _unauthorized_basic() from None + username, separator, password = decoded.partition(':') + if not separator or not username: + raise _unauthorized_basic() + return username, password + + +@router.post('', status_code=status.HTTP_201_CREATED, response_model=SessionOut) +async def create_session( + authorization: str | None = Header(None), + users: UserService = Depends(user_service), + sessions: RedisSessionStore = Depends(session_store), +) -> SessionOut: + username, password = _parse_basic(authorization) + user = await users.authenticate(username, password) + if user is None: + raise _unauthorized_basic() + token = create_token() + expires_at = await sessions.create(user.id, token) + return SessionOut( + token=token, + token_type='Bearer', + expires_at=to_rfc3339(expires_at), + user=UserOut.from_domain(user), + ) + + +@router.delete('/current', status_code=status.HTTP_204_NO_CONTENT, response_model=None) +async def revoke_session( + token: str = Depends(bearer_token), + _: User = Depends(current_user), + sessions: RedisSessionStore = Depends(session_store), +) -> None: + await sessions.revoke(token) diff --git a/app/api/routers/chats.py b/app/api/routers/chats.py new file mode 100644 index 00000000..1dd5126c --- /dev/null +++ b/app/api/routers/chats.py @@ -0,0 +1,49 @@ +from typing import Optional +from uuid import UUID + +from fastapi import APIRouter, Depends, Query + +from ...domain.models import User +from ...services.chats import ChatService +from .. import cursors +from ..deps import chat_service, current_user +from ..schemas import ( + LIMIT_DEFAULT, + LIMIT_MAX, + LIMIT_MIN, + ChatOut, + ChatPageOut, + CreateChat, +) + +router = APIRouter(prefix='/api/v1/chats', tags=['chats']) + + +@router.post('', status_code=201, response_model=ChatOut) +async def create( + body: CreateChat, + actor: User = Depends(current_user), + chats: ChatService = Depends(chat_service), +) -> ChatOut: + return ChatOut.from_domain(await chats.create(actor, body.title, body.member_ids)) + + +@router.get('', response_model=ChatPageOut) +async def page( + actor: User = Depends(current_user), + chats: ChatService = Depends(chat_service), + limit: int = Query(LIMIT_DEFAULT, ge=LIMIT_MIN, le=LIMIT_MAX), + cursor: Optional[str] = Query(None, min_length=1, max_length=cursors.MAX_LENGTH), +) -> ChatPageOut: + scope = f'chats:{actor.id}' + after = cursors.decode(scope, cursor) if cursor is not None else None + return ChatPageOut.from_domain(await chats.page(actor, after, limit), scope) + + +@router.get('/{chat_id}', response_model=ChatOut) +async def get( + chat_id: UUID, + actor: User = Depends(current_user), + chats: ChatService = Depends(chat_service), +) -> ChatOut: + return ChatOut.from_domain(await chats.get(actor, chat_id)) diff --git a/app/api/routers/health.py b/app/api/routers/health.py new file mode 100644 index 00000000..a4e2029b --- /dev/null +++ b/app/api/routers/health.py @@ -0,0 +1,28 @@ +from fastapi import APIRouter, HTTPException, Request +from redis.exceptions import RedisError +from sqlalchemy import text +from sqlalchemy.exc import SQLAlchemyError + +from ...domain.errors import Unavailable + +from ..schemas import HealthOut + +router = APIRouter(tags=['health']) + + +@router.get('/health/live', response_model=HealthOut) +async def live() -> HealthOut: + return HealthOut(status='ok') + + +@router.get('/health/ready', response_model=HealthOut) +async def ready(request: Request) -> HealthOut: + if not request.app.state.ready: + raise HTTPException(status_code=503, detail='приложение не готово принимать трафик') + try: + async with request.app.state.engine.connect() as connection: + await connection.execute(text('SELECT 1')) + await request.app.state.redis.ping() + except (SQLAlchemyError, RedisError, Unavailable, OSError): + raise HTTPException(status_code=503, detail='обязательное хранилище недоступно') from None + return HealthOut(status='ok') diff --git a/app/api/routers/messages.py b/app/api/routers/messages.py new file mode 100644 index 00000000..b97f10f6 --- /dev/null +++ b/app/api/routers/messages.py @@ -0,0 +1,51 @@ +from typing import Annotated, Optional +from uuid import UUID + +from fastapi import APIRouter, Depends, Header, Query + +from ...domain.models import User +from ...services.messages import MessageService +from .. import cursors +from ..deps import current_user, message_service +from ..schemas import ( + LIMIT_DEFAULT, + LIMIT_MAX, + LIMIT_MIN, + CreateMessage, + MessageOut, + MessagePageOut, +) + +router = APIRouter(prefix='/api/v1/chats/{chat_id}/messages', tags=['messages']) + + +@router.post('', status_code=201, response_model=MessageOut) +async def send( + chat_id: UUID, + body: CreateMessage, + idempotency_key: Annotated[ + str, + Header( + alias='Idempotency-Key', + min_length=1, + max_length=128, + pattern=r'^[A-Za-z0-9._:-]+$', + ), + ], + actor: User = Depends(current_user), + messages: MessageService = Depends(message_service), +) -> MessageOut: + return MessageOut.from_domain(await messages.send(actor, chat_id, body.text, idempotency_key)) + + +@router.get('', response_model=MessagePageOut) +async def page( + chat_id: UUID, + actor: User = Depends(current_user), + messages: MessageService = Depends(message_service), + limit: int = Query(LIMIT_DEFAULT, ge=LIMIT_MIN, le=LIMIT_MAX), + cursor: Optional[str] = Query(None, min_length=1, max_length=cursors.MAX_LENGTH), +) -> MessagePageOut: + scope = f'messages:{chat_id}' + after = cursors.decode(scope, cursor) if cursor is not None else None + return MessagePageOut.from_domain(await messages.history(actor, chat_id, after, limit), scope) diff --git a/app/api/routers/users.py b/app/api/routers/users.py new file mode 100644 index 00000000..7da40af4 --- /dev/null +++ b/app/api/routers/users.py @@ -0,0 +1,18 @@ +from fastapi import APIRouter, Depends + +from ...domain.models import User +from ...services.users import UserService +from ..deps import current_user, user_service +from ..schemas import CreateUser, UserOut + +router = APIRouter(prefix='/api/v1', tags=['users']) + + +@router.post('/users', status_code=201, response_model=UserOut) +async def register(body: CreateUser, users: UserService = Depends(user_service)) -> UserOut: + return UserOut.from_domain(await users.register(body.username, body.display_name, body.password)) + + +@router.get('/users/me', response_model=UserOut) +async def me(actor: User = Depends(current_user)) -> UserOut: + return UserOut.from_domain(actor) diff --git a/app/api/schemas.py b/app/api/schemas.py new file mode 100644 index 00000000..145b0c0c --- /dev/null +++ b/app/api/schemas.py @@ -0,0 +1,147 @@ +from typing import Optional +from uuid import UUID + +from pydantic import BaseModel, ConfigDict, Field, field_validator + +from ..domain.models import Chat, Message, Page, User +from . import cursors +from .timefmt import to_rfc3339 + +NAME_MAX = 100 +TEXT_MAX = 4000 +MEMBERS_MAX = 100 +LIMIT_MIN = 1 +LIMIT_MAX = 100 +LIMIT_DEFAULT = 50 + + +def not_blank(value: str) -> str: + if not value.strip(): + raise ValueError('строка не может состоять только из пробельных символов') + return value + + +class Strict(BaseModel): + model_config = ConfigDict(extra='forbid') + + +class HealthOut(Strict): + status: str = 'ok' + + +class CreateUser(Strict): + username: str = Field(min_length=3, max_length=32, pattern=r'^[a-z0-9_]{3,32}$') + display_name: str = Field(min_length=1, max_length=NAME_MAX) + password: str = Field(min_length=12, max_length=128) + + @field_validator('display_name') + @classmethod + def _display_name(cls, value: str) -> str: + return not_blank(value) + + +class UserOut(Strict): + id: UUID + username: str + display_name: str + created_at: str + + @classmethod + def from_domain(cls, user: User) -> 'UserOut': + return cls( + id=user.id, + username=user.username, + display_name=user.display_name, + created_at=to_rfc3339(user.created_at), + ) + + +class SessionOut(Strict): + token: str = Field(min_length=32) + token_type: str = 'Bearer' + expires_at: str + user: UserOut + + +class CreateChat(Strict): + title: str = Field(min_length=1, max_length=NAME_MAX) + member_ids: list[UUID] = Field(min_length=1, max_length=MEMBERS_MAX) + + @field_validator('title') + @classmethod + def _title(cls, value: str) -> str: + return not_blank(value) + + @field_validator('member_ids') + @classmethod + def _members_unique(cls, value: list[UUID]) -> list[UUID]: + if len(set(value)) != len(value): + raise ValueError('member_ids не должен содержать дубликаты') + return value + + +class ChatOut(Strict): + id: UUID + title: str + member_ids: list[UUID] + created_at: str + + @classmethod + def from_domain(cls, chat: Chat) -> 'ChatOut': + return cls( + id=chat.id, + title=chat.title, + member_ids=list(chat.member_ids), + created_at=to_rfc3339(chat.created_at), + ) + + +class CreateMessage(Strict): + text: str = Field(min_length=1, max_length=TEXT_MAX) + + @field_validator('text') + @classmethod + def _text(cls, value: str) -> str: + return not_blank(value) + + +class MessageOut(Strict): + id: UUID + chat_id: UUID + sender_id: UUID + text: str + created_at: str + + @classmethod + def from_domain(cls, message: Message) -> 'MessageOut': + return cls( + id=message.id, + chat_id=message.chat_id, + sender_id=message.sender_id, + text=message.text, + created_at=to_rfc3339(message.created_at), + ) + + +class ChatPageOut(Strict): + items: list[ChatOut] + next_cursor: Optional[str] + + @classmethod + def from_domain(cls, page: Page, scope: str) -> 'ChatPageOut': + return cls( + items=[ChatOut.from_domain(chat) for chat in page.items], + next_cursor=cursors.encode(scope, page.next) if page.next else None, + ) + + +class MessagePageOut(Strict): + items: list[MessageOut] + next_cursor: Optional[str] + + @classmethod + def from_domain(cls, page: Page, scope: str) -> 'MessagePageOut': + return cls( + items=[MessageOut.from_domain(message) for message in page.items], + next_cursor=cursors.encode(scope, page.next) if page.next else None, + ) diff --git a/app/api/timefmt.py b/app/api/timefmt.py new file mode 100644 index 00000000..b9d7b101 --- /dev/null +++ b/app/api/timefmt.py @@ -0,0 +1,11 @@ +from datetime import datetime, timezone + + +def to_rfc3339(value: datetime) -> str: + return value.astimezone(timezone.utc).isoformat(timespec='microseconds').replace('+00:00', 'Z') + + +def from_rfc3339(value: str) -> datetime: + if not isinstance(value, str) or not value.endswith('Z'): + raise ValueError('timestamp must end with Z') + return datetime.fromisoformat(value[:-1]).replace(tzinfo=timezone.utc) diff --git a/app/auth/__init__.py b/app/auth/__init__.py new file mode 100644 index 00000000..9bd80fdb --- /dev/null +++ b/app/auth/__init__.py @@ -0,0 +1,4 @@ +from .passwords import hash_password, password_matches +from .tokens import create_token + +__all__ = ['create_token', 'hash_password', 'password_matches'] diff --git a/app/auth/passwords.py b/app/auth/passwords.py new file mode 100644 index 00000000..70576fc0 --- /dev/null +++ b/app/auth/passwords.py @@ -0,0 +1,15 @@ +from argon2 import PasswordHasher +from argon2.exceptions import VerificationError, VerifyMismatchError + +_hasher = PasswordHasher() + + +def hash_password(password: str) -> str: + return _hasher.hash(password) + + +def password_matches(stored_hash: str, password: str) -> bool: + try: + return _hasher.verify(stored_hash, password) + except (VerifyMismatchError, VerificationError): + return False diff --git a/app/auth/tokens.py b/app/auth/tokens.py new file mode 100644 index 00000000..c60beff0 --- /dev/null +++ b/app/auth/tokens.py @@ -0,0 +1,11 @@ +import hashlib +import secrets + + +def create_token() -> str: + return secrets.token_urlsafe(32) + + +def session_key(token: str) -> str: + digest = hashlib.sha256(token.encode('utf-8')).hexdigest() + return f'session:{digest}' diff --git a/app/config/__init__.py b/app/config/__init__.py new file mode 100644 index 00000000..e6b731e5 --- /dev/null +++ b/app/config/__init__.py @@ -0,0 +1,3 @@ +from .settings import Settings, load_settings + +__all__ = ['Settings', 'load_settings'] diff --git a/app/config/settings.py b/app/config/settings.py new file mode 100644 index 00000000..886023e0 --- /dev/null +++ b/app/config/settings.py @@ -0,0 +1,36 @@ +from __future__ import annotations + +import os +from dataclasses import dataclass +from pathlib import Path + + +def _read_value(name: str, file_name: str) -> str: + value = os.getenv(name) + if value: + return value + path = os.getenv(file_name) + if path: + return Path(path).read_text(encoding='utf-8').strip() + raise RuntimeError(f'не задана настройка {name} или {file_name}') + + +@dataclass(frozen=True, slots=True) +class Settings: + database_url: str + redis_url: str + session_ttl_seconds: int + + +def load_settings() -> Settings: + try: + ttl = int(os.getenv('SESSION_TTL_SECONDS', '3600')) + except ValueError as exc: + raise RuntimeError('SESSION_TTL_SECONDS должен быть целым числом') from exc + if ttl <= 0: + raise RuntimeError('SESSION_TTL_SECONDS должен быть больше нуля') + return Settings( + database_url=_read_value('DATABASE_URL', 'DATABASE_URL_FILE'), + redis_url=_read_value('REDIS_URL', 'CACHE_URL_FILE'), + session_ttl_seconds=ttl, + ) diff --git a/app/db/__init__.py b/app/db/__init__.py new file mode 100644 index 00000000..6e0b53d7 --- /dev/null +++ b/app/db/__init__.py @@ -0,0 +1,4 @@ +from .postgres import Base, create_engine, create_session_factory +from .redis import RedisSessionStore, create_redis + +__all__ = ['Base', 'RedisSessionStore', 'create_engine', 'create_redis', 'create_session_factory'] diff --git a/app/db/postgres.py b/app/db/postgres.py new file mode 100644 index 00000000..d3b31752 --- /dev/null +++ b/app/db/postgres.py @@ -0,0 +1,23 @@ +from __future__ import annotations + +from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker, create_async_engine +from sqlalchemy.orm import DeclarativeBase + + +class Base(DeclarativeBase): + pass + + +def create_engine(url: str) -> AsyncEngine: + return create_async_engine( + url, + pool_size=5, + max_overflow=5, + pool_timeout=5, + pool_pre_ping=True, + connect_args={'server_settings': {'statement_timeout': '5000'}}, + ) + + +def create_session_factory(engine: AsyncEngine) -> async_sessionmaker[AsyncSession]: + return async_sessionmaker(engine, expire_on_commit=False) diff --git a/app/db/redis.py b/app/db/redis.py new file mode 100644 index 00000000..fc9e3570 --- /dev/null +++ b/app/db/redis.py @@ -0,0 +1,51 @@ +from __future__ import annotations + +from datetime import datetime, timedelta, timezone +from uuid import UUID + +from redis.asyncio import Redis +from redis.exceptions import RedisError + +from ..auth.tokens import session_key +from ..domain.errors import Unavailable + + +def create_redis(url: str) -> Redis: + return Redis.from_url(url, decode_responses=True, socket_connect_timeout=3, socket_timeout=3) + + +class RedisSessionStore: + def __init__(self, client: Redis, ttl_seconds: int) -> None: + self._client = client + self._ttl_seconds = ttl_seconds + + async def create(self, user_id: UUID, token: str) -> datetime: + try: + await self._client.set(session_key(token), str(user_id), ex=self._ttl_seconds) + except RedisError as exc: + raise Unavailable('хранилище сессий недоступно') from exc + return datetime.now(timezone.utc) + timedelta(seconds=self._ttl_seconds) + + async def get_user_id(self, token: str) -> UUID | None: + try: + value = await self._client.get(session_key(token)) + except RedisError as exc: + raise Unavailable('хранилище сессий недоступно') from exc + if value is None: + return None + try: + return UUID(value) + except ValueError: + return None + + async def revoke(self, token: str) -> None: + try: + await self._client.delete(session_key(token)) + except RedisError as exc: + raise Unavailable('хранилище сессий недоступно') from exc + + async def ping(self) -> None: + try: + await self._client.ping() + except RedisError as exc: + raise Unavailable('хранилище сессий недоступно') from exc diff --git a/app/domain/__init__.py b/app/domain/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/app/domain/errors.py b/app/domain/errors.py new file mode 100644 index 00000000..d15b362b --- /dev/null +++ b/app/domain/errors.py @@ -0,0 +1,29 @@ +from __future__ import annotations + + +class DomainError(Exception): + """Сообщение попадает клиенту, поэтому не содержит внутренних деталей.""" + + def __init__(self, message: str) -> None: + super().__init__(message) + self.message = message + + +class Invalid(DomainError): + """Запрос нарушает правила предметной области.""" + + +class Unauthorized(DomainError): + """Нет действительной идентификации.""" + + +class NotFound(DomainError): + """Объекта нет либо он недоступен вызывающему: снаружи это неразличимо.""" + + +class Conflict(DomainError): + """Состояние не позволяет выполнить операцию.""" + + +class Unavailable(DomainError): + """Обязательная внешняя зависимость временно недоступна.""" diff --git a/app/domain/models.py b/app/domain/models.py new file mode 100644 index 00000000..33668bbd --- /dev/null +++ b/app/domain/models.py @@ -0,0 +1,56 @@ +from dataclasses import dataclass +from datetime import datetime +from typing import Optional +from uuid import UUID + + +@dataclass(frozen=True, slots=True) +class User: + id: UUID + username: str + display_name: str + created_at: datetime + + +@dataclass(frozen=True, slots=True) +class Chat: + 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, slots=True) +class Message: + id: UUID + chat_id: UUID + sender_id: UUID + text: str + created_at: datetime + + +@dataclass(frozen=True, slots=True) +class Keyset: + created_at: datetime + id: UUID + + @property + def order(self) -> tuple[datetime, int]: + return (self.created_at, self.id.int) + + @classmethod + def from_item(cls, item) -> 'Keyset': + return cls(created_at=item.created_at, id=item.id) + + +def order_key(item) -> tuple[datetime, int]: + return (item.created_at, item.id.int) + + +@dataclass(frozen=True, slots=True) +class Page: + items: tuple + next: Optional[Keyset] diff --git a/app/main.py b/app/main.py new file mode 100644 index 00000000..9426a9d1 --- /dev/null +++ b/app/main.py @@ -0,0 +1,87 @@ +"""Сборка FastAPI приложения и подключение обязательных хранилищ.""" +from __future__ import annotations + +import logging +import os +import sys +from contextlib import asynccontextmanager + +from fastapi import FastAPI +from sqlalchemy import text + +from .api import errors +from .api.deps import Services +from .api.middleware import RequestContext +from .api.routers import auth, chats, health, messages, users +from .config import load_settings +from .db import RedisSessionStore, create_engine, create_redis, create_session_factory +from .repositories import ChatRepository, MessageRepository, UserRepository +from .services.chats import ChatService +from .services.messages import MessageService +from .services.users import UserService + +logger = logging.getLogger('app') + +DESCRIPTION = 'PostgreSQL хранит данные мессенджера; Redis хранит активные сессии.' + + +def configure_logging() -> None: + logging.basicConfig( + level=os.getenv('LOG_LEVEL', 'info').upper(), + stream=sys.stdout, + format='%(asctime)s %(levelname)s %(name)s %(message)s', + force=True, + ) + + +def create_app() -> FastAPI: + configure_logging() + + @asynccontextmanager + async def lifespan(application: FastAPI): + application.state.ready = False + settings = load_settings() + engine = create_engine(settings.database_url) + redis = create_redis(settings.redis_url) + try: + async with engine.connect() as connection: + await connection.execute(text('SELECT 1')) + session_store = RedisSessionStore(redis, settings.session_ttl_seconds) + await session_store.ping() + session_factory = create_session_factory(engine) + user_repository = UserRepository(session_factory) + chat_repository = ChatRepository(session_factory) + message_repository = MessageRepository(session_factory) + application.state.services = Services( + users=UserService(user_repository), + chats=ChatService(chat_repository), + messages=MessageService(message_repository), + sessions=session_store, + ) + application.state.engine = engine + application.state.redis = redis + application.state.ready = True + logger.info('startup storage=postgres redis_sessions=true') + yield + finally: + application.state.ready = False + await redis.aclose() + await engine.dispose() + logger.info('shutdown complete') + + api = FastAPI( + title='MTUSI Messenger. LR 3', + version='1.3.0', + description=DESCRIPTION, + lifespan=lifespan, + ) + api.router.redirect_slashes = False + api.state.ready = False + api.add_middleware(RequestContext) + errors.install(api) + for router in (health.router, users.router, auth.router, chats.router, messages.router): + api.include_router(router) + return api + + +app = create_app() diff --git a/app/models/__init__.py b/app/models/__init__.py new file mode 100644 index 00000000..64b2f78f --- /dev/null +++ b/app/models/__init__.py @@ -0,0 +1,5 @@ +from .chat import ChatMemberRow, ChatRow +from .message import MessageRow +from .user import UserRow + +__all__ = ['ChatMemberRow', 'ChatRow', 'MessageRow', 'UserRow'] diff --git a/app/models/chat.py b/app/models/chat.py new file mode 100644 index 00000000..9c464ecd --- /dev/null +++ b/app/models/chat.py @@ -0,0 +1,26 @@ +from __future__ import annotations + +from datetime import datetime +from uuid import UUID + +from sqlalchemy import DateTime, ForeignKey, Index, String +from sqlalchemy.orm import Mapped, mapped_column +from sqlalchemy.types import Uuid + +from ..db.postgres import Base + + +class ChatRow(Base): + __tablename__ = 'chats' + + id: Mapped[UUID] = mapped_column(Uuid, primary_key=True) + title: Mapped[str] = mapped_column(String(100), nullable=False) + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False) + + +class ChatMemberRow(Base): + __tablename__ = 'chat_members' + __table_args__ = (Index('chat_members_user_chat_idx', 'user_id', 'chat_id'),) + + chat_id: Mapped[UUID] = mapped_column(ForeignKey('chats.id', ondelete='CASCADE'), primary_key=True) + user_id: Mapped[UUID] = mapped_column(ForeignKey('users.id', ondelete='CASCADE'), primary_key=True) diff --git a/app/models/message.py b/app/models/message.py new file mode 100644 index 00000000..96a716f5 --- /dev/null +++ b/app/models/message.py @@ -0,0 +1,30 @@ +from __future__ import annotations + +from datetime import datetime +from uuid import UUID + +from sqlalchemy import DateTime, ForeignKey, Index, String, UniqueConstraint +from sqlalchemy.orm import Mapped, mapped_column +from sqlalchemy.types import Uuid + +from ..db.postgres import Base + + +class MessageRow(Base): + __tablename__ = 'messages' + __table_args__ = ( + Index('messages_history_idx', 'chat_id', 'created_at', 'id'), + UniqueConstraint( + 'sender_id', + 'chat_id', + 'idempotency_key', + name='messages_sender_chat_idempotency_key', + ), + ) + + id: Mapped[UUID] = mapped_column(Uuid, primary_key=True) + chat_id: Mapped[UUID] = mapped_column(ForeignKey('chats.id', ondelete='CASCADE'), nullable=False) + sender_id: Mapped[UUID] = mapped_column(ForeignKey('users.id'), nullable=False) + text: Mapped[str] = mapped_column(String(4000), nullable=False) + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False) + idempotency_key: Mapped[str | None] = mapped_column(String(128), nullable=True) diff --git a/app/models/user.py b/app/models/user.py new file mode 100644 index 00000000..f4aeefd0 --- /dev/null +++ b/app/models/user.py @@ -0,0 +1,20 @@ +from __future__ import annotations + +from datetime import datetime +from uuid import UUID + +from sqlalchemy import DateTime, String, Text +from sqlalchemy.orm import Mapped, mapped_column +from sqlalchemy.types import Uuid + +from ..db.postgres import Base + + +class UserRow(Base): + __tablename__ = 'users' + + id: Mapped[UUID] = mapped_column(Uuid, primary_key=True) + username: Mapped[str] = mapped_column(String(32), unique=True, nullable=False) + display_name: Mapped[str] = mapped_column(String(100), nullable=False) + password_hash: Mapped[str] = mapped_column(Text, nullable=False) + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False) diff --git a/app/repositories/__init__.py b/app/repositories/__init__.py new file mode 100644 index 00000000..4d82b99c --- /dev/null +++ b/app/repositories/__init__.py @@ -0,0 +1,5 @@ +from .chats import ChatRepository +from .messages import MessageRepository +from .users import UserRepository + +__all__ = ['ChatRepository', 'MessageRepository', 'UserRepository'] diff --git a/app/repositories/chats.py b/app/repositories/chats.py new file mode 100644 index 00000000..04d4261a --- /dev/null +++ b/app/repositories/chats.py @@ -0,0 +1,69 @@ +from __future__ import annotations + +from datetime import datetime +from typing import Sequence +from uuid import UUID + +from sqlalchemy import select, tuple_ +from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker + +from ..domain.errors import Invalid +from ..domain.models import Chat, Keyset +from ..models.chat import ChatMemberRow, ChatRow +from ..models.user import UserRow + + +class ChatRepository: + def __init__(self, sessions: async_sessionmaker[AsyncSession]) -> None: + self._sessions = sessions + + @staticmethod + def _to_domain(row: ChatRow, member_ids: Sequence[UUID]) -> Chat: + return Chat(id=row.id, title=row.title, member_ids=tuple(member_ids), created_at=row.created_at) + + @staticmethod + async def _members(session: AsyncSession, chat_id: UUID) -> tuple[UUID, ...]: + result = await session.scalars( + select(ChatMemberRow.user_id) + .where(ChatMemberRow.chat_id == chat_id) + .order_by(ChatMemberRow.user_id) + ) + return tuple(result) + + async def create(self, chat_id: UUID, title: str, member_ids: Sequence[UUID], created_at: datetime) -> Chat: + async with self._sessions() as session: + async with session.begin(): + found = set(await session.scalars(select(UserRow.id).where(UserRow.id.in_(member_ids)))) + if len(found) != len(member_ids): + raise Invalid(f'member_ids содержит неизвестных участников: {len(member_ids) - len(found)}') + row = ChatRow(id=chat_id, title=title, created_at=created_at) + session.add(row) + await session.flush() + session.add_all(ChatMemberRow(chat_id=chat_id, user_id=user_id) for user_id in member_ids) + await session.flush() + return self._to_domain(row, member_ids) + + async def get_for_member(self, chat_id: UUID, user_id: UUID) -> Chat | None: + async with self._sessions() as session: + row = await session.scalar( + select(ChatRow) + .join(ChatMemberRow, ChatMemberRow.chat_id == ChatRow.id) + .where(ChatRow.id == chat_id, ChatMemberRow.user_id == user_id) + ) + if row is None: + return None + return self._to_domain(row, await self._members(session, row.id)) + + async def page_for_member(self, user_id: UUID, after: Keyset | None, limit: int) -> list[Chat]: + async with self._sessions() as session: + query = ( + select(ChatRow) + .join(ChatMemberRow, ChatMemberRow.chat_id == ChatRow.id) + .where(ChatMemberRow.user_id == user_id) + .order_by(ChatRow.created_at, ChatRow.id) + .limit(limit) + ) + if after is not None: + query = query.where(tuple_(ChatRow.created_at, ChatRow.id) > tuple_(after.created_at, after.id)) + rows = list((await session.scalars(query)).all()) + return [self._to_domain(row, await self._members(session, row.id)) for row in rows] diff --git a/app/repositories/messages.py b/app/repositories/messages.py new file mode 100644 index 00000000..f387e9a9 --- /dev/null +++ b/app/repositories/messages.py @@ -0,0 +1,104 @@ +from __future__ import annotations + +from datetime import datetime +from uuid import UUID + +from sqlalchemy import select, tuple_ +from sqlalchemy.dialects.postgresql import insert +from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker + +from ..domain.errors import Conflict +from ..domain.models import Keyset, Message +from ..models.chat import ChatMemberRow, ChatRow +from ..models.message import MessageRow + + +class MessageRepository: + def __init__(self, sessions: async_sessionmaker[AsyncSession]) -> None: + self._sessions = sessions + + @staticmethod + def _to_domain(row: MessageRow) -> Message: + return Message( + id=row.id, + chat_id=row.chat_id, + sender_id=row.sender_id, + text=row.text, + created_at=row.created_at, + ) + + @staticmethod + async def _accessible_chat_id(session: AsyncSession, chat_id: UUID, user_id: UUID) -> UUID | None: + return await session.scalar( + select(ChatRow.id) + .join(ChatMemberRow, ChatMemberRow.chat_id == ChatRow.id) + .where(ChatRow.id == chat_id, ChatMemberRow.user_id == user_id) + ) + + async def create_for_member( + self, + message_id: UUID, + chat_id: UUID, + sender_id: UUID, + text: str, + created_at: datetime, + idempotency_key: str, + ) -> Message | None: + async with self._sessions() as session: + async with session.begin(): + accessible_chat_id = await self._accessible_chat_id(session, chat_id, sender_id) + if accessible_chat_id is None: + return None + + statement = ( + insert(MessageRow) + .values( + id=message_id, + chat_id=accessible_chat_id, + sender_id=sender_id, + text=text, + created_at=created_at, + idempotency_key=idempotency_key, + ) + .on_conflict_do_nothing( + index_elements=[ + MessageRow.sender_id, + MessageRow.chat_id, + MessageRow.idempotency_key, + ] + ) + .returning(MessageRow.id) + ) + created_id = await session.scalar(statement) + if created_id is not None: + row = await session.get(MessageRow, created_id) + else: + row = await session.scalar( + select(MessageRow).where( + MessageRow.sender_id == sender_id, + MessageRow.chat_id == accessible_chat_id, + MessageRow.idempotency_key == idempotency_key, + ) + ) + if row is None: + raise RuntimeError('результат идемпотентной операции не найден') + if row.text != text: + raise Conflict('Idempotency-Key уже использован с другим сообщением') + return self._to_domain(row) + + async def page_for_member( + self, chat_id: UUID, user_id: UUID, after: Keyset | None, limit: int + ) -> list[Message] | None: + async with self._sessions() as session: + accessible_chat_id = await self._accessible_chat_id(session, chat_id, user_id) + if accessible_chat_id is None: + return None + query = ( + select(MessageRow) + .where(MessageRow.chat_id == accessible_chat_id) + .order_by(MessageRow.created_at, MessageRow.id) + .limit(limit) + ) + if after is not None: + query = query.where(tuple_(MessageRow.created_at, MessageRow.id) > tuple_(after.created_at, after.id)) + return [self._to_domain(row) for row in (await session.scalars(query)).all()] diff --git a/app/repositories/users.py b/app/repositories/users.py new file mode 100644 index 00000000..d65b165b --- /dev/null +++ b/app/repositories/users.py @@ -0,0 +1,53 @@ +from __future__ import annotations + +from datetime import datetime +from uuid import UUID + +from sqlalchemy import select +from sqlalchemy.exc import IntegrityError +from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker + +from ..domain.errors import Conflict +from ..domain.models import User +from ..models.user import UserRow + + +class UserRepository: + def __init__(self, sessions: async_sessionmaker[AsyncSession]) -> None: + self._sessions = sessions + + @staticmethod + def _to_domain(row: UserRow) -> User: + return User(id=row.id, username=row.username, display_name=row.display_name, created_at=row.created_at) + + async def register( + self, user_id: UUID, username: str, display_name: str, password_hash: str, created_at: datetime + ) -> User: + row = UserRow( + id=user_id, + username=username, + display_name=display_name, + password_hash=password_hash, + created_at=created_at, + ) + try: + async with self._sessions() as session: + async with session.begin(): + session.add(row) + await session.flush() + except IntegrityError as exc: + raise Conflict('username уже занят') from exc + return self._to_domain(row) + + async def get_by_id(self, user_id: UUID) -> User | None: + async with self._sessions() as session: + row = await session.get(UserRow, user_id) + return self._to_domain(row) if row is not None else None + + async def get_credentials(self, username: str) -> UserRow | None: + async with self._sessions() as session: + return await session.scalar(select(UserRow).where(UserRow.username == username)) + + @classmethod + def to_domain(cls, row: UserRow) -> User: + return cls._to_domain(row) diff --git a/app/services/__init__.py b/app/services/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/app/services/chats.py b/app/services/chats.py new file mode 100644 index 00000000..9b55f715 --- /dev/null +++ b/app/services/chats.py @@ -0,0 +1,35 @@ +from __future__ import annotations + +from datetime import datetime, timezone +from typing import Optional, Sequence +from uuid import UUID, uuid4 + +from ..domain.errors import Invalid, NotFound +from ..domain.models import Chat, Keyset, Page, User +from ..repositories import ChatRepository + + +class ChatService: + def __init__(self, repository: ChatRepository) -> None: + self._repository = repository + + async def create(self, actor: User, title: str, member_ids: Sequence[UUID]) -> Chat: + if actor.id not in member_ids: + raise Invalid('вызывающий должен входить в member_ids') + return await self._repository.create( + chat_id=uuid4(), + title=title, + member_ids=member_ids, + created_at=datetime.now(timezone.utc), + ) + + async def get(self, actor: User, chat_id: UUID) -> Chat: + chat = await self._repository.get_for_member(chat_id, actor.id) + if chat is None: + raise NotFound('чат не найден') + return chat + + async def page(self, actor: User, after: Optional[Keyset], limit: int) -> Page: + rows = await self._repository.page_for_member(actor.id, after, limit + 1) + items = tuple(rows[:limit]) + return Page(items=items, next=Keyset.from_item(items[-1]) if len(rows) > limit else None) diff --git a/app/services/messages.py b/app/services/messages.py new file mode 100644 index 00000000..ec3de200 --- /dev/null +++ b/app/services/messages.py @@ -0,0 +1,36 @@ +from __future__ import annotations + +from datetime import datetime, timezone +from typing import Optional +from uuid import UUID, uuid4 + +from ..domain.errors import NotFound +from ..domain.models import Keyset, Message, Page, User +from ..repositories import MessageRepository + + +class MessageService: + def __init__(self, repository: MessageRepository) -> None: + self._repository = repository + + async def send(self, actor: User, chat_id: UUID, text: str, idempotency_key: str) -> Message: + message = await self._repository.create_for_member( + message_id=uuid4(), + chat_id=chat_id, + sender_id=actor.id, + text=text, + created_at=datetime.now(timezone.utc), + idempotency_key=idempotency_key, + ) + if message is None: + raise NotFound('чат не найден') + return message + + async def history( + self, actor: User, chat_id: UUID, after: Optional[Keyset], limit: int + ) -> Page: + rows = await self._repository.page_for_member(chat_id, actor.id, after, limit + 1) + if rows is None: + raise NotFound('чат не найден') + items = tuple(rows[:limit]) + return Page(items=items, next=Keyset.from_item(items[-1]) if len(rows) > limit else None) diff --git a/app/services/users.py b/app/services/users.py new file mode 100644 index 00000000..9a516a86 --- /dev/null +++ b/app/services/users.py @@ -0,0 +1,35 @@ +from __future__ import annotations + +from datetime import datetime, timezone +from uuid import UUID, uuid4 + +from ..auth.passwords import hash_password, password_matches +from ..domain.errors import Unauthorized +from ..domain.models import User +from ..repositories import UserRepository + + +class UserService: + def __init__(self, repository: UserRepository) -> None: + self._repository = repository + + async def register(self, username: str, display_name: str, password: str) -> User: + return await self._repository.register( + user_id=uuid4(), + username=username, + display_name=display_name, + password_hash=hash_password(password), + created_at=datetime.now(timezone.utc), + ) + + async def identify(self, user_id: UUID) -> User: + user = await self._repository.get_by_id(user_id) + if user is None: + raise Unauthorized('требуется действующая сессия') + return user + + async def authenticate(self, username: str, password: str) -> User | None: + row = await self._repository.get_credentials(username) + if row is None or not password_matches(row.password_hash, password): + return None + return self._repository.to_domain(row) diff --git a/compose.example.yaml b/compose.example.yaml index dd4d3878..52524b0c 100644 --- a/compose.example.yaml +++ b/compose.example.yaml @@ -1,11 +1,10 @@ # Topology worksheet, deliberately NOT a runnable stack (no application supplied). # Implement compose.yaml or stack.yaml; do not submit this empty file as deployment. # Service names below are logical roles, not imposed container names. -x-lab-number: 3 +x-lab-number: 2 x-required-roles: - api - postgres - - load_balancer # TODO: implement real images/builds, network wiring, volumes, healthchecks, # credentials and bootstrap. Details: contracts/infrastructure.json and README.md. services: {} diff --git a/compose.tests.yaml b/compose.tests.yaml new file mode 100644 index 00000000..65e4f825 --- /dev/null +++ b/compose.tests.yaml @@ -0,0 +1,62 @@ +services: + postgres: + image: postgres:17.4-alpine + environment: + POSTGRES_USER: messenger_test + POSTGRES_PASSWORD: messenger_test + POSTGRES_DB: messenger_test + healthcheck: + test: ["CMD-SHELL", "pg_isready -U messenger_test -d messenger_test"] + interval: 2s + timeout: 2s + retries: 30 + + redis: + image: redis:7.4.2-alpine + command: ["redis-server", "--appendonly", "yes", "--appendfsync", "always"] + healthcheck: + test: ["CMD", "redis-cli", "ping"] + interval: 2s + timeout: 2s + retries: 30 + + migrate: + build: . + command: ["alembic", "upgrade", "head"] + environment: + DATABASE_URL: postgresql+asyncpg://messenger_test:messenger_test@postgres:5432/messenger_test + REDIS_URL: redis://redis:6379/0 + SESSION_TTL_SECONDS: 1 + depends_on: + postgres: + condition: service_healthy + restart: "no" + + api: + build: . + environment: + DATABASE_URL: postgresql+asyncpg://messenger_test:messenger_test@postgres:5432/messenger_test + REDIS_URL: redis://redis:6379/0 + SESSION_TTL_SECONDS: 1 + depends_on: + migrate: + condition: service_completed_successfully + redis: + condition: service_healthy + healthcheck: + test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/ready', timeout=3).read()"] + interval: 2s + timeout: 2s + retries: 30 + + tests: + build: + context: . + dockerfile: Dockerfile.test + environment: + BASE_URL: http://api:8080 + SESSION_TTL_SECONDS: 1 + depends_on: + api: + condition: service_healthy + restart: "no" diff --git a/compose.yaml b/compose.yaml new file mode 100644 index 00000000..0511f041 --- /dev/null +++ b/compose.yaml @@ -0,0 +1,90 @@ +services: + postgres: + image: postgres:17.4-alpine + cpus: "1.0" + mem_limit: 512m + environment: + POSTGRES_USER: ${POSTGRES_USER} + POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} + POSTGRES_DB: ${POSTGRES_DB} + volumes: + - postgres_data:/var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"] + interval: 5s + timeout: 3s + retries: 20 + + redis: + image: redis:7.4.2-alpine + cpus: "0.25" + mem_limit: 128m + command: ["redis-server", "--appendonly", "yes", "--appendfsync", "always"] + volumes: + - redis_data:/data + healthcheck: + test: ["CMD", "redis-cli", "ping"] + interval: 5s + timeout: 3s + retries: 20 + + migrate: + build: . + cpus: "0.5" + mem_limit: 256m + command: ["alembic", "upgrade", "head"] + environment: + DATABASE_URL: ${DATABASE_URL} + REDIS_URL: ${REDIS_URL} + SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS} + depends_on: + postgres: + condition: service_healthy + restart: "no" + + api: + build: . + cpus: "0.5" + mem_limit: 256m + environment: + DATABASE_URL: ${DATABASE_URL} + REDIS_URL: ${REDIS_URL} + SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS} + LOG_LEVEL: ${LOG_LEVEL:-info} + expose: + - "8080" + deploy: + replicas: 2 + depends_on: + migrate: + condition: service_completed_successfully + redis: + condition: service_healthy + healthcheck: + test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/ready', timeout=3).read()"] + interval: 2s + timeout: 2s + retries: 5 + stop_grace_period: 10s + + lb: + image: haproxy:3.2.26-alpine + cpus: "0.25" + mem_limit: 128m + ports: + - "${APP_PORT:-8080}:8080" + volumes: + - ./infra/haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro + depends_on: + api: + condition: service_healthy + healthcheck: + test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://127.0.0.1:8080/health/live"] + interval: 2s + timeout: 2s + retries: 5 + stop_grace_period: 5s + +volumes: + postgres_data: + redis_data: diff --git a/evidence/README.md b/evidence/README.md index 8df70015..cc69db40 100644 --- a/evidence/README.md +++ b/evidence/README.md @@ -3,3 +3,10 @@ Храните небольшие обезличенные результаты: команды и stdout проверок, JSON/CSV агрегатов нагрузки, EXPLAIN, dashboard JSON, текст разбора отказа. Укажите дату, commit, аппаратные лимиты и профиль нагрузки. Не добавляйте .env, session tokens, cookies, приватные ключи, credentials, реальные сообщения, raw dumps и signed URLs. Для скриншотов скрывайте секреты. Большие логи/бинарные traces сохраняйте отдельно по правилам преподавателя; одного скриншота без методики недостаточно. + +Собранные результаты lab3: + +- `results.md` — контракт, идемпотентность, persistence, failover, нагрузка и ресурсы; +- `load.json` — агрегаты отдельного 30-секундного нагрузочного прогона; +- `rolling-update.md` — методика и результат поочерёдной замены; +- `rolling-update-load.json` — агрегаты нагрузки во время замены. diff --git a/evidence/load.json b/evidence/load.json new file mode 100644 index 00000000..9b574ade --- /dev/null +++ b/evidence/load.json @@ -0,0 +1,17 @@ +{ + "lab": 3, + "workload": "closed-loop POST messages; no automatic retries", + "requested_duration_seconds": 30.0, + "elapsed_seconds": 30.012, + "concurrency": 4, + "successful_requests": 9807, + "failed_requests": 0, + "error_ratio": 0.0, + "successful_rps": 326.771, + "successful_latency_ms": { + "p50": 6.436, + "p95": 52.344, + "p99": 63.559 + }, + "note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead." +} diff --git a/evidence/results.md b/evidence/results.md new file mode 100644 index 00000000..c2f9bf9e --- /dev/null +++ b/evidence/results.md @@ -0,0 +1,87 @@ +# Результаты обязательных проверок lab3 + +Дата: 2026-10-23. + +## Стенд + +- Host: MacBook Pro, Apple M4 Pro, 12 CPU cores, 24 GB RAM. +- Docker Engine: 28.0.4. +- Docker Compose: 2.34.0. +- API runtime: Python 3.13.15. +- HAProxy: 3.2.26, образ `haproxy:3.2.26-alpine`. +- PostgreSQL: 17.4, образ `postgres:17.4-alpine`. +- Redis: 7.4.2, образ `redis:7.4.2-alpine`. + +Лимиты: API — 0,5 CPU и 256 MiB на реплику; HAProxy — 0,25 CPU и 128 MiB; PostgreSQL — 1 CPU и 512 MiB; Redis — 0,25 CPU и 128 MiB; migrate — 0,5 CPU и 256 MiB. + +## Контракт и идемпотентность + +До изменений lab3 базовый стенд lab2 собирался, а `make check` и OpenAPI validation проходили. Первый lab3 smoke завершался на `FAIL: missing X-Instance-Id`; в коде также отсутствовали обязательный `Idempotency-Key`, общая идемпотентность, HAProxy и вторая API-реплика. + +```sh +make test +make test-idempotency PYTHON=.venv/bin/python +``` + +Наблюдение: + +```text +PASS: lab3 public API scenario +5 passed +``` + +Конкурентный тест отправляет 20 запросов с одним `Idempotency-Key` через HAProxy. Ответы получены минимум от двух `X-Instance-Id`; все содержали один ID, и в истории осталось одно сообщение. + +Отдельная проверка воспроизводимости выполнена новым Compose-проектом `mtusi2026lab3-clean` с пустыми PostgreSQL/Redis volumes и host-портом 18080. Сборка, миграции, readiness двух реплик, публичный smoke и пять pytest-тестов прошли; после проверки временные контейнеры и volumes удалены. + +## Persistence + +```sh +make test-persistence ACTION_SCRIPT=scripts/restart.sh +``` + +Наблюдение: после перезапуска API, PostgreSQL и Redis с сохранением volumes подтверждённые данные и прежний session token остались доступны. + +## Последовательный failover реплик + +```sh +make test-failover ACTION_SCRIPT=scripts/stop-one.sh +``` + +| Реплика | Успешные записи за 15 с | Successful write RPS (≈) | Ошибки перехода | Первая успешная запись после воздействия | +| --- | ---: | ---: | ---: | ---: | +| Первая | 111 | 7,40 | 1 | 3,248 с | +| Вторая, после восстановления первой | 110 | 7,33 | 1 | 2,560 с | + +Оба запуска наблюдали две реплики до воздействия. RPS рассчитан как число успешных записей, делённое на 15 секунд нагрузки. Остановленная реплика не обслуживала последние ответы; подтверждённые сообщения сохранились, неопределённый POST не создал дубль. + +## Нагрузка + +```sh +python3 tests/load.py \ + --base-url http://localhost:8080 \ + --duration 30 \ + --concurrency 4 \ + --output evidence/load.json +``` + +- Длительность: 30,012 с. +- Concurrency: 4, closed-loop. +- Успешные запросы: 9807. +- Ошибки: 0; error ratio 0,0. +- Successful RPS: 326,771. +- p50/p95/p99 успешных запросов: 6,436 / 52,344 / 63,559 мс. +- Прогрев: отдельного временного прогрева нет; bootstrap выполнен до измеряемого интервала, стенд уже работал. +- Набор данных после теста: 39 пользователей, 13 чатов, 18 448 сообщений, PostgreSQL 14 MB. + +Два среза `docker stats` во время этого прогона: + +| Контейнер | CPU 1 / CPU 2 | RAM 1 / RAM 2 | Лимит RAM | +| --- | --- | --- | ---: | +| HAProxy | 12,98% / 14,26% | 82,59 / 82,62 MiB | 128 MiB | +| API replica 1 | 50,42% / 50,85% | 66,34 / 66,23 MiB | 256 MiB | +| API replica 2 | 52,31% / 51,00% | 66,40 / 76,12 MiB | 256 MiB | +| PostgreSQL | 20,22% / 19,96% | 44,47 / 45,44 MiB | 512 MiB | +| Redis | 1,31% / 1,33% | 3,71 / 3,70 MiB | 128 MiB | + +Генератор closed-loop ограничен клиентом и подвержен coordinated omission. Перцентили относятся только к успешным запросам, поэтому результат не является пределом производительности системы. diff --git a/evidence/rolling-update-load.json b/evidence/rolling-update-load.json new file mode 100644 index 00000000..20db2eb8 --- /dev/null +++ b/evidence/rolling-update-load.json @@ -0,0 +1,17 @@ +{ + "lab": 3, + "workload": "closed-loop POST messages; no automatic retries", + "requested_duration_seconds": 30.0, + "elapsed_seconds": 30.017, + "concurrency": 4, + "successful_requests": 10512, + "failed_requests": 0, + "error_ratio": 0.0, + "successful_rps": 350.206, + "successful_latency_ms": { + "p50": 5.169, + "p95": 50.037, + "p99": 61.382 + }, + "note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead." +} diff --git a/evidence/rolling-update.md b/evidence/rolling-update.md new file mode 100644 index 00000000..03ca75ba --- /dev/null +++ b/evidence/rolling-update.md @@ -0,0 +1,55 @@ +# Поочерёдная замена API под нагрузкой + +Дата: 2026-10-23. + +## Сценарий + +Нагрузка выполнялась через HAProxy на `http://localhost:8080`: + +```sh +python3 tests/load.py \ + --base-url http://localhost:8080 \ + --duration 30 \ + --concurrency 4 \ + --output evidence/rolling-update-load.json +``` + +Во время нагрузки выполнен `scripts/rolling-update.sh`. Скрипт по очереди удаляет одну API-реплику, создаёт замену и перед переходом ко второй ждёт две реплики в состоянии `healthy`. + +## Наблюдение реплик + +До замены: + +```text +486287bf812aecec7bba303bd502e06fe6758602ef248e5933ecfd02964a388a healthy +03f5832b4b2a570d245a01a308e7756db170b54caeeb7ec9e6c2a0e4cf2241a6 healthy +``` + +После замены: + +```text +c1fa8669e26796af661b85f947369a9be8245c18c5f560c74a24f772d1015bbd healthy +3d931568da47ff5723fd7089e876ea5d5825abe1ec73506b3625180686425cd4 healthy +``` + +Обе исходные реплики заменены новыми контейнерами. Одновременно останавливалась только одна реплика. + +## Результат нагрузки + +- Длительность: 30,017 с. +- Concurrency: 4. +- Успешные запросы: 10 512. +- Ошибки: 0. +- Error ratio: 0,0. +- Successful RPS: 350,206. +- p50: 5,169 мс. +- p95: 50,037 мс. +- p99: 61,382 мс. + +Машиночитаемый результат сохранён в `evidence/rolling-update-load.json`. + +## Совместимость миграции + +Миграция lab3 добавляет nullable-поле `idempotency_key` и уникальность `(sender_id, chat_id, idempotency_key)`. Старая версия API может продолжать записывать `NULL`, а новая версия читает старые сообщения без ключа. Поэтому схема совместима с поочерёдной заменой приложения. + +Ограничение: создание уникального ограничения может блокировать запись на большой таблице. В учебном стенде миграция выполняется отдельно до запуска API и проверена на малом наборе данных; online-миграция большой production-таблицы не заявляется. diff --git a/infra/haproxy.cfg b/infra/haproxy.cfg new file mode 100644 index 00000000..5bd0c142 --- /dev/null +++ b/infra/haproxy.cfg @@ -0,0 +1,31 @@ +global + log stdout format raw local0 + +defaults + log global + mode http + option httplog + timeout connect 2s + timeout client 30s + timeout server 30s + timeout check 2s + +resolvers docker + nameserver docker_dns 127.0.0.11:53 + resolve_retries 3 + timeout resolve 1s + timeout retry 1s + hold valid 1s + hold obsolete 1s + +frontend public + bind :8080 + default_backend api_backend + +backend api_backend + balance roundrobin + option httpchk + http-check send meth GET uri /health/ready ver HTTP/1.1 hdr Host api + http-check expect status 200 + default-server check inter 1s fastinter 500ms downinter 1s fall 2 rise 2 resolvers docker init-addr libc,none + server-template api 2 api:8080 diff --git a/requirements-dev.txt b/requirements-dev.txt index 6b103ddb..8d16cf19 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -1,2 +1,3 @@ # Only for full OpenAPI/JSON Schema validation; HTTP tests use stdlib. openapi-spec-validator==0.7.2 +pytest==8.3.5 diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 00000000..31148b51 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,7 @@ +fastapi==0.115.12 +uvicorn[standard]==0.34.2 +SQLAlchemy[asyncio]==2.0.40 +asyncpg==0.30.0 +alembic==1.15.2 +redis==5.2.1 +argon2-cffi==25.1.0 diff --git a/scripts/restart.sh b/scripts/restart.sh new file mode 100755 index 00000000..691598a3 --- /dev/null +++ b/scripts/restart.sh @@ -0,0 +1,12 @@ +#!/bin/sh +set -eu + +script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) +project_dir=$(dirname -- "$script_dir") +cd "$project_dir" + +# Останавливаем публичный маршрут до перезапуска общих хранилищ. +docker compose --env-file .env stop lb api >/dev/null +docker compose --env-file .env restart postgres redis >/dev/null +docker compose --env-file .env up -d --wait --wait-timeout 60 postgres redis >/dev/null +docker compose --env-file .env up -d --wait --wait-timeout 60 api lb >/dev/null diff --git a/scripts/rolling-update.sh b/scripts/rolling-update.sh new file mode 100755 index 00000000..a822c186 --- /dev/null +++ b/scripts/rolling-update.sh @@ -0,0 +1,42 @@ +#!/bin/sh +set -eu + +script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) +project_dir=$(dirname -- "$script_dir") +cd "$project_dir" + +wait_for_two_healthy() { + deadline=$(( $(date +%s) + 60 )) + while [ "$(date +%s)" -lt "$deadline" ]; do + ids=$(docker compose --env-file .env ps -q api) + set -- $ids + if [ "$#" -eq 2 ]; then + all_healthy=true + for container_id in "$@"; do + status=$(docker inspect --format '{{.State.Health.Status}}' "$container_id") + if [ "$status" != 'healthy' ]; then + all_healthy=false + break + fi + done + if [ "$all_healthy" = true ]; then + return 0 + fi + fi + sleep 1 + done + printf '%s\n' 'two healthy API replicas did not appear within 60 seconds' >&2 + return 1 +} + +wait_for_two_healthy +original_ids=$(docker compose --env-file .env ps -q api) + +for old_id in $original_ids; do + old_instance=$(docker inspect --format '{{.Config.Hostname}}' "$old_id") + docker stop --time 5 "$old_id" >/dev/null + docker rm "$old_id" >/dev/null + docker compose --env-file .env up -d --no-deps --no-recreate --scale api=2 api >/dev/null + wait_for_two_healthy + printf 'replaced API instance %s\n' "$old_instance" +done diff --git a/scripts/stop-one.sh b/scripts/stop-one.sh new file mode 100755 index 00000000..3f770799 --- /dev/null +++ b/scripts/stop-one.sh @@ -0,0 +1,24 @@ +#!/bin/sh +set -eu + +: "${TARGET_INSTANCE_ID:?test provides target API instance alias}" + +script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) +project_dir=$(dirname -- "$script_dir") +cd "$project_dir" + +target_container='' +for container_id in $(docker compose --env-file .env ps -q api); do + instance_id=$(docker inspect --format '{{.Config.Hostname}}' "$container_id") + if [ "$instance_id" = "$TARGET_INSTANCE_ID" ]; then + target_container=$container_id + break + fi +done + +if [ -z "$target_container" ]; then + printf '%s\n' 'API instance from TARGET_INSTANCE_ID was not found' >&2 + exit 1 +fi + +docker stop --time 5 "$target_container" >/dev/null diff --git a/tests/test_idempotency.py b/tests/test_idempotency.py new file mode 100644 index 00000000..96e0758d --- /dev/null +++ b/tests/test_idempotency.py @@ -0,0 +1,92 @@ +"""Pytest-проверки общей идемпотентности сообщений.""" +from concurrent.futures import ThreadPoolExecutor +import uuid + +import pytest + +from tests.client import Client + + +@pytest.fixture +def scenario(): + """Создаёт отдельного пользователя и чат для теста.""" + client = Client() + alice, _bob, _eve, chat = client.bootstrap() + return client, alice, chat + + +def test_replay_returns_original_message(scenario): + """Повтор ключа возвращает исходное сообщение.""" + client, alice, chat = scenario + key = uuid.uuid4().hex + + first = client.message(alice, chat, 'same-body', key=key)['json'] + replay = client.message(alice, chat, 'same-body', key=key)['json'] + + assert replay == first + + +def test_reused_key_with_different_body_returns_conflict(scenario): + """Повтор ключа с другим телом возвращает 409.""" + client, alice, chat = scenario + key = uuid.uuid4().hex + client.message(alice, chat, 'first-body', key=key) + + client.call( + 'POST', + '/api/v1/chats/' + chat['id'] + '/messages', + 409, + actor=alice, + body={'text': 'different-body'}, + headers={'Idempotency-Key': key}, + ) + + +@pytest.mark.parametrize( + 'headers', + [ + pytest.param({}, id='missing'), + pytest.param({'Idempotency-Key': 'invalid key'}, id='invalid'), + ], +) +def test_invalid_idempotency_key_returns_bad_request(scenario, headers): + """Отсутствующий или неверный ключ возвращает 400.""" + client, alice, chat = scenario + + client.call( + 'POST', + '/api/v1/chats/' + chat['id'] + '/messages', + 400, + actor=alice, + body={'text': 'validation'}, + headers=headers, + ) + + +def test_concurrent_retries_create_one_message(scenario): + """Конкурентные повторы через две реплики создают одно сообщение.""" + client, alice, chat = scenario + key = uuid.uuid4().hex + text = 'concurrent-idempotency-' + key + + def send(_index): + return Client(timeout=5).message(alice, chat, text, key=key) + + with ThreadPoolExecutor(max_workers=20) as pool: + responses = list(pool.map(send, range(20))) + + message_ids = {response['json']['id'] for response in responses} + instance_ids = {response['headers']['X-Instance-Id'] for response in responses} + assert len(message_ids) == 1 + assert len(instance_ids) >= 2 + + history = client.call( + 'GET', + '/api/v1/chats/' + chat['id'] + '/messages?limit=100', + actor=alice, + schema='MessagePage', + )['json']['items'] + matching = [message for message in history if message['text'] == text] + + assert len(matching) == 1 + assert matching[0]['id'] in message_ids