From 4921afa39d85d0e43c925e424b484a8f92c14f9b Mon Sep 17 00:00:00 2001 From: roman Date: Thu, 1 Oct 2026 15:33:49 +0300 Subject: [PATCH] feat: store messenger data in PostgreSQL Replace the in-memory store with PostgreSQL 18.6: SQLAlchemy 2.1 async engine on asyncpg, alembic migrations with an async env.py, repos on AsyncSession and services that own the transaction. Username uniqueness is enforced by the database (ON CONFLICT), a chat and its members are created in one transaction, member order is kept in chat_members.position, and a composite foreign key makes the sender a member of the chat. History and chat lists use keyset pagination on (chat_id, created_at, id) and (user_id, created_at, chat_id). The compose stand runs postgres, a one-shot migrate service on the API image and the API. All Postgres addresses come from .env without literals; only the 127.0.0.1 publish address stays literal. make run_dev starts Postgres and applies migrations before the server, and make env_setup generates a random Postgres password. Unavailable PostgreSQL yields 503: get_db_session bounds the request with asyncio and classifies driver errors. BoundedCloseConnection limits asyncpg's graceful close, which otherwise waited without limit on a frozen server and held the request until it was resumed. Add scripts/restart.sh for make test-persistence and make test_isolated, which runs the image on a throwaway test database. Remove make run_no_compose. X-User-Id identification is unchanged until the session-auth change. Co-Authored-By: Claude Opus 5.5 --- .env.example | 35 +- Dockerfile | 6 +- Makefile | 70 ++- alembic.ini | 13 + bench/inproc.py | 2 +- config_example.toml | 14 + docker-compose.yml | 93 +++- migrations/env.py | 68 +++ migrations/script.py.mako | 27 + ...135-16c279725564_added_messenger_tables.py | 127 +++++ .../changes/postgres-storage/.openspec.yaml | 2 + openspec/changes/postgres-storage/design.md | 465 ++++++++++++++++++ openspec/changes/postgres-storage/proposal.md | 99 ++++ .../specs/container-image/spec.md | 49 ++ .../specs/container-run/spec.md | 139 ++++++ .../specs/data-storage/spec.md | 126 +++++ .../specs/db-migrations/spec.md | 69 +++ .../postgres-storage/specs/health/spec.md | 24 + .../specs/service-configuration/spec.md | 40 ++ .../specs/student-tests/spec.md | 50 ++ openspec/changes/postgres-storage/tasks.md | 210 ++++++++ pyproject.toml | 7 +- scripts/restart.sh | 16 + src/api/dependencies.py | 82 ++- src/api/routers/health.py | 6 +- src/config/settings.py | 43 +- src/core/exceptions/service.py | 5 +- src/core/repos/chat.py | 106 +++- src/core/repos/message.py | 48 +- src/core/repos/user.py | 40 +- src/core/services/chat.py | 25 +- src/core/services/message.py | 22 +- src/core/services/user.py | 20 +- src/infra/db/__init__.py | 9 + src/infra/db/engine.py | 75 +++ src/infra/db/errors.py | 33 ++ src/infra/db/models/__init__.py | 15 + src/infra/db/models/base.py | 30 ++ src/infra/db/models/chat.py | 55 +++ src/infra/db/models/message.py | 33 ++ src/infra/db/models/user.py | 32 ++ src/infra/logger.py | 6 + src/infra/memory.py | 35 -- src/main.py | 20 +- src/utils/constants.py | 9 + student-tests/run_isolated.py | 224 +++++++++ uv.lock | 93 ++++ 47 files changed, 2648 insertions(+), 169 deletions(-) create mode 100644 alembic.ini create mode 100644 migrations/env.py create mode 100644 migrations/script.py.mako create mode 100644 migrations/versions/2026_10_01_0135-16c279725564_added_messenger_tables.py create mode 100644 openspec/changes/postgres-storage/.openspec.yaml create mode 100644 openspec/changes/postgres-storage/design.md create mode 100644 openspec/changes/postgres-storage/proposal.md create mode 100644 openspec/changes/postgres-storage/specs/container-image/spec.md create mode 100644 openspec/changes/postgres-storage/specs/container-run/spec.md create mode 100644 openspec/changes/postgres-storage/specs/data-storage/spec.md create mode 100644 openspec/changes/postgres-storage/specs/db-migrations/spec.md create mode 100644 openspec/changes/postgres-storage/specs/health/spec.md create mode 100644 openspec/changes/postgres-storage/specs/service-configuration/spec.md create mode 100644 openspec/changes/postgres-storage/specs/student-tests/spec.md create mode 100644 openspec/changes/postgres-storage/tasks.md create mode 100755 scripts/restart.sh create mode 100644 src/infra/db/__init__.py create mode 100644 src/infra/db/engine.py create mode 100644 src/infra/db/errors.py create mode 100644 src/infra/db/models/__init__.py create mode 100644 src/infra/db/models/base.py create mode 100644 src/infra/db/models/chat.py create mode 100644 src/infra/db/models/message.py create mode 100644 src/infra/db/models/user.py delete mode 100644 src/infra/memory.py create mode 100644 student-tests/run_isolated.py diff --git a/.env.example b/.env.example index 0a6ce7ae..3d1a1858 100644 --- a/.env.example +++ b/.env.example @@ -1,6 +1,7 @@ -# Шаблон .env: `make env_setup` копирует его, не перезаписывая -# существующий файл. .env не коммитить. .env читают compose, Makefile -# (make run_no_compose) и приложение (pydantic-settings). +# Шаблон .env: `make env_setup` создаёт из него .env, не перезаписывая +# существующий файл, и подставляет случайный POSTGRES_PASSWORD. .env не +# коммитить. .env читают compose, Makefile и приложение +# (pydantic-settings); в контейнеры он не попадает. # Параметры приложения — в формате настроек SECTION__FIELD, без секции — # только то, что приложение не читает. Комментарии — только отдельными # строками: make оставляет хвостовой комментарий частью значения. @@ -9,8 +10,34 @@ # в REPORT.md, «Архитектура и решения». # порт сервиса ([app] port): на нём слушает приложение, его же -# публикуют compose и make run_no_compose, на нём же healthcheck +# публикует compose, на нём же healthcheck APP__PORT=8080 # порт на 127.0.0.1 хоста, куда публикуется сервис; приложение его # не читает APP_OUT_PORT=8080 + +# PostgreSQL. POSTGRES_USER, POSTGRES_PASSWORD и POSTGRES_DB читает и +# образ postgres; пароль задаётся только при первом создании volume. +# Пустой пароль образ postgres не принимает: make env_setup подставляет +# случайный +POSTGRES_USER=messenger +POSTGRES_PASSWORD= +POSTGRES_DB=messenger +# адрес и порт Postgres внутри сети compose: по ним ходят API и миграции +# в docker, порт слушает сам сервер (PGPORT) +POSTGRES_HOST=postgres +POSTGRES_PORT=5432 +# порт на 127.0.0.1 хоста, куда публикуется Postgres: к нему подключается +# приложение в console +POSTGRES_OUT_PORT=5433 +# мосты для console: приложение на хосте берёт значения отсюда, в docker +# их задаёт environment compose +DATABASE__HOST=127.0.0.1 +DATABASE__PORT=${POSTGRES_OUT_PORT} +DATABASE__USER=${POSTGRES_USER} +DATABASE__PASSWORD=${POSTGRES_PASSWORD} +DATABASE__NAME=${POSTGRES_DB} + +# make test_isolated: порт на 127.0.0.1, куда публикуется тестовый +# контейнер API +TEST_APP_PORT=18088 diff --git a/Dockerfile b/Dockerfile index 3c2a2a1d..d37ddf98 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,4 +1,5 @@ -# Образ API мессенджера (лаба 1). Правила — .claude/rules/docker.md. +# Образ API мессенджера (лаба 2): сервер и миграции. Правила — +# .claude/rules/docker.md. # Пины: тег + digest индекса (amd64 и arm64). Обновление версии — новый # тег и digest из `docker buildx imagetools inspect <тег>`. @@ -38,6 +39,9 @@ WORKDIR /app # код и .venv принадлежат root: пользователю app — только чтение COPY --from=builder /app/.venv /app/.venv COPY src ./src +# сервис migrate compose запускает этот же образ: alembic upgrade head +COPY alembic.ini ./ +COPY migrations ./migrations USER app diff --git a/Makefile b/Makefile index 1191112d..e3354ae6 100644 --- a/Makefile +++ b/Makefile @@ -30,15 +30,18 @@ test-persistence: # Приложение на хосте (свои цели; цели skeleton выше не менять) # ------------------------- +# Postgres из compose и миграции, затем сервис на хосте: +# 127.0.0.1:APP__PORT, reload по src/ .PHONY: run_dev -run_dev: +run_dev: upgrade APP__RUN_MODE=console uv run python -m src # шаблоны копируются только если файла ещё нет: локальные значения -# не затираются +# не затираются. В новый .env подставляется случайный пароль Postgres: +# в шаблоне он пустой, общего пароля стенда в git нет .PHONY: env_setup env_setup: - @test -f .env || cp .env.example .env + @test -f .env || sed "s/^POSTGRES_PASSWORD=$$/POSTGRES_PASSWORD=$$(openssl rand -hex 16)/" .env.example > .env @test -f config.toml || cp config_example.toml config.toml @echo "env ready: .env, config.toml" @@ -52,21 +55,10 @@ env_setup: APP__PORT ?= 8080 APP_OUT_PORT ?= 8080 DC=docker compose -DOCKER_IMAGE=mtusi-messenger:lab2 -DOCKER_CONTAINER=mtusi-messenger-lab2 -# без compose: команды README, контейнер на переднем плане; -# стоп — Ctrl+C или docker stop mtusi-messenger-lab2. -# env_setup создаёт недостающий .env: без него --env-file падает -.PHONY: run_no_compose -run_no_compose: env_setup - DOCKER_BUILDKIT=1 docker build -t $(DOCKER_IMAGE) . - docker run --rm --name $(DOCKER_CONTAINER) \ - -p 127.0.0.1:$(APP_OUT_PORT):$(APP__PORT) \ - --env-file .env $(DOCKER_IMAGE) - -# env_setup создаёт недостающие .env и config.toml из шаблонов: без -# config.toml compose не запустится (bind с create_host_path: false) +# стенд: postgres -> migrate -> api. env_setup создаёт недостающие .env +# и config.toml из шаблонов: без config.toml compose не запустится +# (bind с create_host_path: false), без пароля — тоже .PHONY: run_docker run_docker: env_setup DOCKER_BUILDKIT=1 $(DC) build @@ -76,6 +68,7 @@ run_docker: env_setup stop: $(DC) stop +# контейнеры удаляются, volume с данными остаётся (удаление — wipe_data) .PHONY: down down: $(DC) down @@ -86,6 +79,42 @@ logs: $(DC) logs -f --no-log-prefix api +# ------------------------- +# PostgreSQL и миграции +# ------------------------- + +# Postgres стенда; --wait ждёт его healthcheck +.PHONY: start_db +start_db: env_setup + $(DC) up -d --wait postgres + +.PHONY: stop_db +stop_db: + $(DC) stop postgres + +# миграции с хоста: 127.0.0.1:POSTGRES_OUT_PORT из .env +.PHONY: upgrade +upgrade: start_db + uv run alembic upgrade head + +# новая ревизия autogenerate; база сначала доводится до head, иначе +# autogenerate сравнит модели не с той схемой +.PHONY: revision +revision: upgrade + @read -p "Сообщение миграции (англ., прошедшее время): " msg; \ + uv run alembic revision --autogenerate -m "$$msg" + +# удалить контейнеры стенда и volume с данными: только после ввода yes +.PHONY: wipe_data +wipe_data: + @read -p "Удалить все данные стенда (volume Postgres)? Введите yes: " answer; \ + if [ "$$answer" = "yes" ]; then \ + $(DC) down -v --remove-orphans; \ + else \ + echo "cancelled, nothing removed"; exit 1; \ + fi + + # ------------------------- # Load benchmark (трек 1) # ------------------------- @@ -135,6 +164,13 @@ bench_ab: student_test: BASE_URL=$(BASE_URL) uv run pytest +# образ на временной базе test_: сборка, миграции, отдельный +# контейнер api на 127.0.0.1:TEST_APP_PORT, make test и make student_test, +# затем уборка при любом исходе. KEEP_TEST_DB=1 оставляет базу для разбора +.PHONY: test_isolated +test_isolated: env_setup start_db + uv run python student-tests/run_isolated.py $(if $(KEEP_TEST_DB),--keep-db,) + .PHONY: lint lint: @ruff format . diff --git a/alembic.ini b/alembic.ini new file mode 100644 index 00000000..c0e463a5 --- /dev/null +++ b/alembic.ini @@ -0,0 +1,13 @@ +# Миграции alembic, правила — .claude/rules/migrations.md. +# URL подключения migrations/env.py берёт из настроек приложения (секция +# [database]), поэтому sqlalchemy.url здесь нет. Секций logging тоже нет: +# журнал идёт через src/infra/logger.py в JSON, как у сервиса. + +[alembic] +script_location = %(here)s/migrations +# имя ревизии: YYYY_MM_DD_HHMM-_.py +file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s +truncate_slug_length = 40 +# импорт src из корня репозитория и из /app в образе +prepend_sys_path = . +path_separator = os diff --git a/bench/inproc.py b/bench/inproc.py index 12727670..ea63d56e 100644 --- a/bench/inproc.py +++ b/bench/inproc.py @@ -305,10 +305,10 @@ async def measure(args: argparse.Namespace) -> dict[str, Any]: # приложение импортируется только здесь: на хосте скрипт — stdlib sys.path.insert(0, os.getcwd()) from pydantic import PlainSerializer + from src.infra.memory import MemoryStore from src.api.schemas import Message, MessagePage from src.core.services import MessageService - from src.infra.memory import MemoryStore from src.main import app from src.utils.utc import from_rfc3339, to_rfc3339 diff --git a/config_example.toml b/config_example.toml index eb947f76..062badb4 100644 --- a/config_example.toml +++ b/config_example.toml @@ -9,3 +9,17 @@ log_level = "INFO" # сколько секунд uvicorn ждёт текущие запросы после SIGTERM graceful_shutdown_seconds = 8 + +[database] +# Адрес, порт, пользователь, пароль и имя базы приходят из .env (мосты к +# POSTGRES_*) и из environment compose; здесь их не указывать. +pool_size = 10 +max_overflow = 5 +# секунды ожидания свободного соединения пула +pool_timeout_seconds = 5 +# секунды на установку соединения +connect_timeout_seconds = 3 +# миллисекунды, серверный statement_timeout; 0 — без ограничения +statement_timeout_ms = 5000 +# секунды на всю работу запроса с БД: зависший сервер, обрыв сети +request_timeout_seconds = 6 diff --git a/docker-compose.yml b/docker-compose.yml index e145f4c0..a52824aa 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,24 +1,91 @@ -# Стенд лабы 1: один процесс API, состояние в памяти. Правила — -# .claude/rules/docker.md. Переменные — из .env (шаблон .env.example). +# Стенд лабы 2: PostgreSQL, одноразовые миграции и API. Правила — +# .claude/rules/docker.md. Значения — из .env (шаблон .env.example); +# литералы только у адреса публикации 127.0.0.1 и у режима docker. +name: mtusi-lab2 + +# окружение приложения: одно для api и migrate, чтобы они не разъехались +x-app-env: &app-env + APP__RUN_MODE: docker + APP__PORT: ${APP__PORT:-8080} + DATABASE__HOST: ${POSTGRES_HOST:-postgres} + DATABASE__PORT: ${POSTGRES_PORT:-5432} + DATABASE__USER: ${POSTGRES_USER:?POSTGRES_USER is not set, run make env_setup} + DATABASE__PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is empty, run make env_setup} + DATABASE__NAME: ${POSTGRES_DB:?POSTGRES_DB is not set, run make env_setup} + +# config.toml только на чтение, длинной записью: без файла запуск падает, +# а не создаёт на хосте каталог config.toml/ +x-config-toml: &config-toml + type: bind + source: ./config.toml + target: /app/config.toml + read_only: true + bind: + create_host_path: false + services: + postgres: + image: postgres:18.6-trixie@sha256:5a5a84b19854a9ffaa54082c166ff4ec27473a361e496e5ea167f298f2da9722 + restart: unless-stopped + environment: + POSTGRES_USER: ${POSTGRES_USER:?POSTGRES_USER is not set, run make env_setup} + POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is empty, run make env_setup} + POSTGRES_DB: ${POSTGRES_DB:?POSTGRES_DB is not set, run make env_setup} + # порт самого сервера; его же берут pg_isready и psql в контейнере + PGPORT: ${POSTGRES_PORT:-5432} + ports: + # только localhost: к нему подключается приложение в console + - "127.0.0.1:${POSTGRES_OUT_PORT:-5433}:${POSTGRES_PORT:-5432}" + volumes: + # с 18.x данные в /var/lib/postgresql/18/docker, volume образа — + # весь /var/lib/postgresql (Config.Volumes) + - postgres_data:/var/lib/postgresql + networks: + default: + # любое значение POSTGRES_HOST указывает на этот сервис + aliases: + - ${POSTGRES_HOST:-postgres} + healthcheck: + # по TCP, а не через сокет: при инициализации образ поднимает + # временный сервер только на сокете, и проверка через сокет + # сказала бы «готов» раньше времени. $$ — переменная контейнера + test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U \"$$POSTGRES_USER\" -d \"$$POSTGRES_DB\""] + interval: 5s + timeout: 3s + retries: 10 + start_period: 30s + start_interval: 1s + + migrate: + # образ собирает сервис api (make run_docker, make test_isolated) + image: mtusi-messenger:lab2 + pull_policy: never + command: ["alembic", "upgrade", "head"] + restart: "no" + environment: *app-env + volumes: + - *config-toml + depends_on: + postgres: + condition: service_healthy + api: build: . - # тот же тег, что у docker build из README и make run_no_compose image: mtusi-messenger:lab2 restart: unless-stopped ports: # только localhost: стенд учебный - "127.0.0.1:${APP_OUT_PORT:-8080}:${APP__PORT:-8080}" - environment: - - APP__RUN_MODE=docker - - APP__PORT=${APP__PORT:-8080} + environment: *app-env volumes: - # длинная запись: без файла запуск падает, а не создаёт каталог - - type: bind - source: ./config.toml - target: /app/config.toml - read_only: true - bind: - create_host_path: false + - *config-toml + depends_on: + postgres: + condition: service_healthy + migrate: + condition: service_completed_successfully # healthcheck — из образа; SIGKILL не раньше, чем через 10 с stop_grace_period: 10s + +volumes: + postgres_data: diff --git a/migrations/env.py b/migrations/env.py new file mode 100644 index 00000000..cb05a9fa --- /dev/null +++ b/migrations/env.py @@ -0,0 +1,68 @@ +"""Окружение alembic: асинхронный шаблон, URL и журнал — из приложения. + +URL берётся из `settings.database.url` и не проходит через ConfigParser +alembic, поэтому `%` в пароле ничего не ломает. Журнал — JSON через +`src/infra/logger.py`, как у сервиса. Асинхронное здесь только +подключение: ревизии остаются синхронным кодом `op.*`. +""" + +import asyncio + +from alembic import context +from sqlalchemy import pool +from sqlalchemy.engine import Connection +from sqlalchemy.ext.asyncio import create_async_engine + +from src.config import settings +from src.infra.db.models import Base +from src.infra.logger import AbstractLogger, get_logger + +logger: AbstractLogger = get_logger().bind(module="migrations") + +target_metadata = Base.metadata + + +def run_migrations_offline() -> None: + """SQL без подключения: `alembic upgrade head --sql`.""" + context.configure( + url=settings.database.url, + target_metadata=target_metadata, + literal_binds=True, + dialect_opts={"paramstyle": "named"}, + ) + with context.begin_transaction(): + context.run_migrations() + + +def do_run_migrations(connection: Connection) -> None: + context.configure(connection=connection, target_metadata=target_metadata) + with context.begin_transaction(): + context.run_migrations() + + +async def run_async_migrations() -> None: + database = settings.database + # адрес и имя базы — чтобы по журналу было видно, какую базу мигрировали + logger.info( + "Running alembic", + host=database.host, + port=database.port, + database=database.name, + ) + engine = create_async_engine( + database.url, + poolclass=pool.NullPool, + connect_args={"timeout": database.connect_timeout_seconds}, + ) + try: + async with engine.connect() as connection: + await connection.run_sync(do_run_migrations) + finally: + await engine.dispose() + logger.info("Finished alembic", database=database.name) + + +if context.is_offline_mode(): + run_migrations_offline() +else: + asyncio.run(run_async_migrations()) diff --git a/migrations/script.py.mako b/migrations/script.py.mako new file mode 100644 index 00000000..46d8fd4b --- /dev/null +++ b/migrations/script.py.mako @@ -0,0 +1,27 @@ +"""${message} + +Revision ID: ${up_revision} +Revises: ${down_revision | comma,n} +Create Date: ${create_date} + +""" + +from collections.abc import Sequence + +import sqlalchemy as sa +from alembic import op +${imports if imports else ""} + +# revision identifiers, used by Alembic. +revision: str = ${repr(up_revision)} +down_revision: str | Sequence[str] | None = ${repr(down_revision)} +branch_labels: str | Sequence[str] | None = ${repr(branch_labels)} +depends_on: str | Sequence[str] | None = ${repr(depends_on)} + + +def upgrade() -> None: + ${upgrades if upgrades else "pass"} + + +def downgrade() -> None: + ${downgrades if downgrades else "pass"} diff --git a/migrations/versions/2026_10_01_0135-16c279725564_added_messenger_tables.py b/migrations/versions/2026_10_01_0135-16c279725564_added_messenger_tables.py new file mode 100644 index 00000000..84615545 --- /dev/null +++ b/migrations/versions/2026_10_01_0135-16c279725564_added_messenger_tables.py @@ -0,0 +1,127 @@ +"""added messenger tables + +Revision ID: 16c279725564 +Revises: +Create Date: 2026-10-01 01:35:56.145855 + +""" + +from collections.abc import Sequence + +import sqlalchemy as sa +from alembic import op + +# revision identifiers, used by Alembic. +revision: str = "16c279725564" +down_revision: str | Sequence[str] | None = None +branch_labels: str | Sequence[str] | None = None +depends_on: str | Sequence[str] | None = None + + +def upgrade() -> None: + # CHECK записаны литералами, а не константами src: применённая + # ревизия не должна меняться вместе с кодом + op.create_table( + "chats", + sa.Column("id", sa.Uuid(), nullable=False), + sa.Column("title", sa.Text(), nullable=False), + sa.Column("created_at", sa.DateTime(timezone=True), nullable=False), + sa.CheckConstraint( + "char_length(title) BETWEEN 1 AND 100", + name=op.f("ck_chats_title_length"), + ), + sa.PrimaryKeyConstraint("id", name=op.f("pk_chats")), + ) + op.create_table( + "users", + sa.Column("id", sa.Uuid(), nullable=False), + sa.Column("username", sa.Text(), nullable=False), + sa.Column("display_name", sa.Text(), nullable=False), + sa.Column("created_at", sa.DateTime(timezone=True), nullable=False), + sa.CheckConstraint( + "username ~ '^[a-z0-9_]{3,32}$'", + name=op.f("ck_users_username_format"), + ), + sa.CheckConstraint( + "char_length(display_name) BETWEEN 1 AND 100", + name=op.f("ck_users_display_name_length"), + ), + sa.PrimaryKeyConstraint("id", name=op.f("pk_users")), + sa.UniqueConstraint("username", name=op.f("uq_users_username")), + ) + op.create_table( + "chat_members", + sa.Column("chat_id", sa.Uuid(), nullable=False), + sa.Column("user_id", sa.Uuid(), nullable=False), + sa.Column("position", sa.SmallInteger(), nullable=False), + sa.Column("created_at", sa.DateTime(timezone=True), nullable=False), + sa.CheckConstraint( + "position >= 0", + name=op.f("ck_chat_members_position_non_negative"), + ), + sa.ForeignKeyConstraint( + ["chat_id"], + ["chats.id"], + name=op.f("fk_chat_members_chat_id_chats"), + ), + sa.ForeignKeyConstraint( + ["user_id"], + ["users.id"], + name=op.f("fk_chat_members_user_id_users"), + ), + sa.PrimaryKeyConstraint( + "chat_id", + "user_id", + name=op.f("pk_chat_members"), + ), + sa.UniqueConstraint( + "chat_id", + "position", + name=op.f("uq_chat_members_chat_id_position"), + ), + ) + op.create_index( + op.f("ix_chat_members_user_id_created_at_chat_id"), + "chat_members", + ["user_id", "created_at", "chat_id"], + unique=False, + ) + op.create_table( + "messages", + sa.Column("id", sa.Uuid(), nullable=False), + sa.Column("chat_id", sa.Uuid(), nullable=False), + sa.Column("sender_id", sa.Uuid(), nullable=False), + sa.Column("text", sa.Text(), nullable=False), + sa.Column("created_at", sa.DateTime(timezone=True), nullable=False), + sa.CheckConstraint( + "char_length(text) BETWEEN 1 AND 4000", + name=op.f("ck_messages_text_length"), + ), + sa.ForeignKeyConstraint( + ["chat_id", "sender_id"], + ["chat_members.chat_id", "chat_members.user_id"], + name=op.f("fk_messages_chat_id_sender_id_chat_members"), + ), + sa.PrimaryKeyConstraint("id", name=op.f("pk_messages")), + ) + op.create_index( + op.f("ix_messages_chat_id_created_at_id"), + "messages", + ["chat_id", "created_at", "id"], + unique=False, + ) + + +def downgrade() -> None: + op.drop_index( + op.f("ix_messages_chat_id_created_at_id"), + table_name="messages", + ) + op.drop_table("messages") + op.drop_index( + op.f("ix_chat_members_user_id_created_at_chat_id"), + table_name="chat_members", + ) + op.drop_table("chat_members") + op.drop_table("users") + op.drop_table("chats") diff --git a/openspec/changes/postgres-storage/.openspec.yaml b/openspec/changes/postgres-storage/.openspec.yaml new file mode 100644 index 00000000..480ad4de --- /dev/null +++ b/openspec/changes/postgres-storage/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-10-01 diff --git a/openspec/changes/postgres-storage/design.md b/openspec/changes/postgres-storage/design.md new file mode 100644 index 00000000..6711e018 --- /dev/null +++ b/openspec/changes/postgres-storage/design.md @@ -0,0 +1,465 @@ +# Design + +## Context + +Мотивация — `proposal.md`, раздел Why. Требования — `specs/`. + +Сейчас всё состояние — `MemoryStore` (`src/infra/memory.py`): dict-ы и +отсортированные списки, атомарность держится на отсутствии `await` +внутри repo-функций. Сервисы получают `store` в конструкторе, repo — +первым параметром. Правила слоёв уже описывают целевое состояние +лабы 2 (`.claude/rules/`, commit `93b699a`), их здесь не пересказываем. + +Решения обсуждены в `/opsx:explore` перед этим change: трек «5» — 2, +сессии — Postgres без кэша (change `session-auth`), Redis/Valkey — кэш +состава чатов (change `membership-cache`), конфиг без комментирования, +литерал только у адреса публикации `127.0.0.1`. + +Проверено на версиях этого change пробными скриптами: + +- SQLAlchemy 2.1.1 ставит greenlet только через extra `asyncio` + (`Requires-Dist: greenlet>=1; extra == "asyncio"`); без него + асинхронный engine не работает. +- В SQLAlchemy 2.1.1 флага `async_fallback` нет (в 2.0 он устарел). + Синхронный `env.py` bp_proxies с asyncpg на 2.1 не заработает. +- FastAPI 0.141.1: исключение из ручки попадает в `except` зависимости + с `yield`, а исключение, брошенное оттуда, обрабатывает + зарегистрированный обработчик (получен 503 из своего обработчика). + +## Goals / Non-Goals + +**Goals:** + +- `student-tests/` проходят против `make run_dev` и `make run_docker` + без правки тестов поведения: 78 из 79. Исключение — + `test_security_scheme_in_openapi`. Он сверяет схему `devUser` на + сервере со схемой в `contracts/openapi.json`, а в контракте lab2 её + нет (переход 1 → 2). Тест падал с момента переноса кода, чинится + вместе со спеком `identification` в `session-auth`. +- `make test_isolated` проверяет образ и связку compose и не оставляет + данных в рабочей базе. Здесь проверяется его механика: база, + контейнер, уборка при любом исходе. Зелёный прогон и evidence набора + против контейнера возможны только после `session-auth`: smoke lab2 + требует вход и Bearer, а тест выше падает до тех пор. +- Консоль и docker работают от одного `.env` без переключений. +- Каждая мутация — одна транзакция, уникальность и связи держит БД. + +**Non-Goals:** + +- Аутентификация, пароли, сессии, `WWW-Authenticate` — `session-auth`. + Здесь `X-User-Id` и `devUser` остаются как есть. +- Redis/Valkey и кэш — `membership-cache`. +- Автоматические проверки отказов (остановка БД, откат составной + операции) — `failure-checks`; здесь поведение реализуется и + проверяется вручную с записью в `evidence/`. +- `bench/` под Postgres, EXPLAIN на ≥10 000 — `bench-postgres`. +- Производительность сверх индекса истории и keyset без `OFFSET`. + +## Decisions + +### 1. Хранилище меняется раньше аутентификации + +Change не трогает HTTP-контракт лабы 1. Тогда `student-tests` — +готовая регрессия: красный тест поведения значит дефект хранилища. +Меняются только записи исключений в `spec_coverage.py`, которые +следуют за дельтами `data-storage` и `health`. + +*Альтернатива:* хранилище и вход одним change. Отвергнута: красный +тест не отличал бы дефект БД от дефекта аутентификации. + +### 2. Стек доступа к данным + +`sqlalchemy[asyncio]` 2.1 + `asyncpg` + `alembic`, все три в основной +группе зависимостей: сервис миграций работает в runtime-образе, а он +собирается с `--no-dev`. + +*Альтернативы:* psycopg 3 (второй знакомый вариант, но bp_proxies и +правила уже на asyncpg); голый asyncpg без SQLAlchemy (правила слоёв +опираются на `AsyncSession`, `pg_insert`, `tuple_`, а параметризация +через SQLAlchemy закрывает требование уровня 4 без самодельного SQL). + +### 3. Схема + +``` +users chats + id uuid PK id uuid PK + username text UQ title text + display_name text created_at timestamptz + created_at timestamptz + ^ ^ + | | +chat_members messages + chat_id uuid FK -> chats --+ id uuid PK + user_id uuid FK -> users | PK chat_id --+ FK (chat_id, sender_id) + position smallint | sender_id --+ -> chat_members + created_at timestamptz (= chats.created_at) text text + PK (chat_id, user_id) created_at timestamptz + UQ (chat_id, position) + IX (user_id, created_at, chat_id) IX (chat_id, created_at, id) +``` + +- Все ограничения именованные (`migrations.md`). `CHECK` дублируют + контракт как защиту в глубину: шаблон `username`, длины + `display_name`, `title` и `text` в code points (`char_length`). + Первым всё равно отвечает API (400); сработавший `CHECK` — это дефект + валидации, и он даст 500, а не тихую запись. +- `position` хранит порядок `member_ids` из запроса: `test_chats.py` + сверяет его дословно. `member_ids` чата собирается + `array_agg(user_id ORDER BY position)`. +- Внешний ключ сообщения — составной, на `chat_members (chat_id, + user_id)`: сообщение от не участника невозможно на уровне БД, а не + только проверкой в сервисе. +- `chat_members.created_at` — копия `chats.created_at` (у `Base` это + поле есть у всех моделей, `migrations.md`). Благодаря ей список чатов + пользователя идёт keyset-ом по индексу + `(user_id, created_at, chat_id)` без сортировки всех его чатов. + Значение неизменяемо, рассинхрону неоткуда взяться. +- `id` и `created_at` назначает сервис (`uuid4()`, `utcnow()`), БД + их не генерирует: иначе порядок, который видит клиент, зависел бы от + двух часов. + +*Альтернатива для списка чатов:* `JOIN` без копии даты и сортировка +всех чатов пользователя. Проще, но это полный просмотр чатов +пользователя на каждую страницу — ровно то, что рубрика уровня 4 +запрещает для истории. + +### 4. Транзакции и repo + +Одна `AsyncSession` на запрос, commit — только в сервисе +(`service-layer.md`). Уровень изоляции — `READ COMMITTED`, явных +блокировок нет. + +| Операция | Шаги в одной транзакции | +|---|---| +| регистрация | `INSERT ... ON CONFLICT (username) DO NOTHING RETURNING` → `None` = 409 → commit | +| создание чата | `SELECT id FROM users WHERE id = ANY(...)` → `INSERT chats` → `INSERT chat_members` (одна многострочная вставка) → commit | +| сообщение | чат с участниками → проверка членства → `INSERT messages` → commit | +| чтения | один `SELECT`; commit не нужен, сессия закрывается откатом | + +Блокировки не нужны: пользователи и участники не удаляются и не +меняются, значит проверка перед вставкой не устаревает, а гонку +регистрации закрывает уникальный индекс. Составной внешний ключ и +внешние ключи участников — страховка на случай ошибки в сервисе. + +Keyset: `tuple_(created_at, id) > tuple_(:t, :id)`, `ORDER BY +created_at, id`, `LIMIT limit + 1`. `uuid` Postgres сравнивает +побайтно — тот же порядок, что `UUID.int` у smoke. Формат курсора +(`src/utils/cursor.py`) не меняется. + +Семантика при конкурентных вставках (в `REPORT.md`): повторов при +обходе нет. Сообщение, которое закоммитилось позже, но с `created_at` +меньше уже пройденного курсора, текущий обход пропустит; новый обход +с начала его увидит. Время ставит один процесс API с часами хоста. + +### 5. Engine, пул и таймауты + +`create_async_engine` в lifespan, `engine.dispose()` в shutdown. +Параметры — секция `[database]`, значения по умолчанию: + +| Параметр | По умолчанию | Зачем | +|---|---|---| +| `pool_size` / `max_overflow` | 10 / 5 | ограниченный пул (уровень 4) | +| `pool_timeout_seconds` | 5 | ожидание соединения → 503, а не очередь без конца | +| `connect_timeout_seconds` | 3 | недоступный хост не держит запрос | +| `statement_timeout_ms` | 5000 | серверный `statement_timeout` через `server_settings` | +| `request_timeout_seconds` | 6 | срок всей работы запроса с БД (`asyncio.timeout` в `get_db_session`): зависший сервер или обрыв сети, где серверный таймаут не сработает | + +`command_timeout` asyncpg не используется: задача 5.1 показала, что +зависший сервер он не ограничивает (решение 6). + +`pool_pre_ping=True`: после рестарта Postgres соединения пула мертвы, и +без проверки первый запрос после `scripts/restart.sh` получил бы 503. +Цена — один короткий round trip на выдачу соединения из пула. +`application_name=mtusi-messenger` — чтобы соединения были видны в +`pg_stat_activity`. URL — `sqlalchemy.engine.URL.create(...)` в +`Database.url`: пароль со спецсимволами экранируется, строку никто не +собирает руками. + +### 6. Недоступность БД → 503 + +Зависимость `get_db_session` (с `yield`) ставит срок +`request_timeout_seconds` на всю работу запроса с БД, ловит ошибки +недоступности (`src/infra/db/errors.py`), закрывает сессию с +`invalidate()`, пишет `warning` и бросает `ServiceUnavailable`; таблица +`errors.py` отдаёт 503 `unavailable`. Так перевод в одном месте, с +логом, и ни один сервис не оборачивает каждый вызов. + +Классы исключений сняты задачей 5.1 на SQLAlchemy 2.1.1 и asyncpg 0.31: + +| Отказ | Исключение | Время до ответа | +|---|---|---| +| Postgres остановлен | `ConnectionRefusedError` (SQLAlchemy не оборачивает) | сразу | +| сервер не отвечает на подключение | `TimeoutError` (`connect_timeout_seconds`) | 3 с | +| сработал `statement_timeout` | `DBAPIError`, SQLSTATE `57014` | по таймауту | +| пул исчерпан | `sqlalchemy.exc.TimeoutError` | `pool_timeout_seconds` | +| соединение оборвано | `DBAPIError` с `connection_invalidated` | сразу | +| сервер завис, соединение из пула | `TimeoutError` срока запроса | 6 + 2 с | + +Перехватываются `OSError` (сюда входит `TimeoutError`), +`sqlalchemy.exc.TimeoutError` и `DBAPIError` с `connection_invalidated` +или SQLSTATE класса `08`, `57014`, `57P01`–`57P03`. Остальные +`DBAPIError` (ограничения, синтаксис) — дефект, им положен 500. + +Зависший сервер (`docker compose pause`) нашёл дефект в связке +библиотек. На отмене запроса asyncpg шлёт серверу CancelRequest через +новое соединение без срока, а SQLAlchemy закрывает прерванное +соединение мягко и ждёт этой отмены. Без поправки запрос висел до +разморозки сервера (169 с в замере), и `command_timeout` asyncpg его не +ограничивал. Поправка — `BoundedCloseConnection` (публичный +`connection_class` asyncpg): мягкое закрытие ограничено 2 с, после чего +asyncpg обрывает соединение. Отсюда «6 + 2 с» в таблице. + +`/health/ready` не ходит через эту зависимость: отдельная проверка +`SELECT 1` с таймаутом через engine из `app.state`. + +*Альтернативы:* обработчик исключений SQLAlchemy в `errors.py` — +отвергнут, `errors.py` не логирует (`logging.md`), а потеря БД в логе +нужна; `try/except` в каждом методе сервиса — шум без пользы. + +### 7. Конфигурация: консоль и docker из одного `.env` + +``` +.env (шаблон .env.example) + POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB <- их читает и образ postgres + POSTGRES_HOST=postgres адрес Postgres в сети compose (docker) + POSTGRES_PORT=5432 порт, который слушает сервер (PGPORT) + POSTGRES_OUT_PORT=5433 порт публикации на 127.0.0.1 (console) + DATABASE__HOST=127.0.0.1 \ + DATABASE__PORT=${POSTGRES_OUT_PORT} мосты для console: + DATABASE__USER=${POSTGRES_USER} приложение на хосте читает .env + DATABASE__PASSWORD=${POSTGRES_PASSWORD} + DATABASE__NAME=${POSTGRES_DB} / + +docker-compose.yml + x-app-env: &app-env api и migrate — одно окружение + APP__RUN_MODE: docker литерал: это определение режима + DATABASE__HOST: ${POSTGRES_HOST:-postgres} + DATABASE__PORT: ${POSTGRES_PORT:-5432} + DATABASE__USER / __PASSWORD / __NAME: ${POSTGRES_*} + postgres: + environment: POSTGRES_USER / _PASSWORD / _DB, PGPORT: ${POSTGRES_PORT:-5432} + ports: "127.0.0.1:${POSTGRES_OUT_PORT:-5433}:${POSTGRES_PORT:-5432}" + networks.default.aliases: ["${POSTGRES_HOST:-postgres}"] +``` + +- `.env` в контейнер не попадает, поэтому консольные `DATABASE__*` из + него не конфликтуют с docker-значениями из `environment`. +- Алиас в сети делает любое значение `POSTGRES_HOST` рабочим для + Postgres стенда; внешний адрес уводит API во внешнюю БД. +- `PGPORT` меняет порт самого сервера (так его читает `postgres`) и + `pg_isready` в healthcheck; иначе смена `POSTGRES_PORT` сломала бы + стенд. Проверяется сценарием «Другой порт Postgres». +- `127.0.0.1` — литерал: требование безопасности, а не параметр. +- В `.env.example` пароль пустой. `make env_setup` при создании `.env` + подставляет случайный (`openssl rand -hex 16`), существующий `.env` + не трогает. С пустым паролем образ postgres не стартует — забытый + шаг проявится сразу, а в git не лежит общий пароль стенда. +- В `config_example.toml` — только то, что читает одно приложение: + пул и таймауты `[database]`. Адрес и учётные данные там не + дублируются (`settings.md`). + +*Альтернатива:* блоки `[database]` для консоли и docker с +комментированием, как в bp_proxies. Отвергнута: ручное переключение, +пароль в двух местах, `config.toml` здесь не запекается в образ. + +### 8. Миграции + +- `alembic.ini`: `script_location = migrations`, `file_template` из + `migrations.md`, `prepend_sys_path = .`, без `sqlalchemy.url`. +- `env.py` — асинхронный шаблон alembic: `create_async_engine( + settings.database.url)`, затем `await conn.run_sync(do_run_migrations)`. + Ревизии остаются синхронным кодом `op.*`. URL не проходит через + ConfigParser alembic, поэтому `%` в пароле ничего не ломает. +- Логи миграций — через `src/infra/logger.py` (JSON), а не `fileConfig` + из `alembic.ini`: у сервиса миграций тот же формат журнала, что у API. + Логгер `alembic` — уровень `INFO`, чтобы строки «Running upgrade» + были видны. +- Первая ревизия пишется autogenerate и дописывается руками: + autogenerate не видит `CHECK` (`migrations.md`). + +Запуск: + +``` +console make run_dev + start_db docker compose up -d --wait postgres + upgrade uv run alembic upgrade head --> 127.0.0.1:${POSTGRES_OUT_PORT} + APP__RUN_MODE=console uv run python -m src + +docker make run_docker + postgres --healthy--> migrate --exit 0--> api + (образ API, depends_on: + alembic upgrade migrate: service_completed_successfully + head, restart: no) +``` + +`make revision` зависит от `upgrade`: autogenerate сравнивает модели с +базой на `head`. + +### 9. Compose и образ + +- Postgres — последняя 18.x, тег с патч-версией и digest индекса + (`docker.md`). Точку монтирования volume берём из метаданных образа + (`docker image inspect` → `Config.Volumes`): у 18.x она изменилась + относительно 17.x. +- Именованный volume `postgres_data`; верхнеуровневое `name:` проекта, + чтобы имена volume и контейнеров не зависели от имени каталога. +- `Dockerfile`: в runtime дополнительно `COPY migrations alembic.ini`. +- `make run_no_compose` удаляется вместе с переменными `DOCKER_IMAGE` и + `DOCKER_CONTAINER` в `Makefile`: без Postgres один контейнер API не + обслуживает запросы, а мосты `${...}` из `.env` голый `docker run + --env-file` не раскрывает. Образ собирает `make run_docker`, сборку из + чистого clone проверяет команда из `docker.md`. Healthcheck остаётся + в образе: его берут compose и стенд `bench/`. + + *Альтернатива:* оставить цель как проверку образа (live 200, ready + 503). Отвергнута: цель, которая по построению поднимает неготовый + сервис, — лишнее, что нужно поддерживать и описывать. + +### 10. `scripts/restart.sh` + +`docker compose stop api` → `docker compose restart postgres` → +`docker compose up -d --wait postgres` (тот же контейнер, ожидание +healthcheck) → `docker compose start api`. Volume не трогается. +`start api` запускает и зависимость `migrate` (задача 6.1 увидела это +по `StartedAt`): повторный прогон миграций — no-op (`db-migrations`). +Hook отрабатывает за ~4 с. Готовность API он не ждёт — это делает тест. +В `evidence/` — `docker compose ps` и `StartedAt` из `docker inspect` +до и после. + +### 11. Что ещё меняется вокруг кода + +- `MemoryStore` и `get_store` удаляются, `health.py` зависит от проверки + БД. DTO остаются frozen; `ChatFullDTO.member_ids` собирается из + `array_agg`. +- Скилл `run-mtusi-messenger`: `driver.py start` перед сервером + выполняет `make start_db upgrade`; в `SKILL.md` убираются «рестарт = + пустое состояние» и примеры с `MemoryStore`. +- Правила: `settings.md` — консольный адрес Postgres в `.env`, а не в + `config.toml`; `infra.md` — перевод ошибок драйвера в + `get_db_session`; `run-modes.md` — именованный volume вместо + `POSTGRES_VOLUME`, `run_dev` с миграциями; `docker.md` — переменные + Postgres в compose. Из `settings.md`, `run-modes.md`, `docker.md` и + `AGENTS.md` уходят упоминания `make run_no_compose`. +- `AGENTS.md`: из «Переходного состояния» уходят пункты про + `MemoryStore`, `migrations/`, `scripts/restart.sh`; `X-User-Id` + остаётся до `session-auth`. + +### 12. `make test_isolated`: образ на временной базе + +Тесты ходят в API по HTTP, поэтому временной базе нужен свой API. Им +становится отдельный контейнер из того же определения сервиса compose, +что и рабочий: так один прогон проверяет код, образ и связку compose, а +рабочий стенд и рабочая база не трогаются. + +``` +make test_isolated (зависит от env_setup и start_db) + uv run python student-tests/run_isolated.py + 0. docker rm -f <тестовый контейнер> хвост прошлого прогона + DROP DATABASE IF EXISTS "test_" WITH (FORCE) + 1. docker compose build api + 2. CREATE DATABASE "test_" + 3. docker compose run --rm --no-deps -e DATABASE__NAME=test_ migrate + 4. docker compose run -d --no-deps --name <тестовый контейнер> + -e DATABASE__NAME=test_ + -p 127.0.0.1:$TEST_APP_PORT:$APP__PORT api + 5. ждать GET http://127.0.0.1:$TEST_APP_PORT/health/ready = 200 (не дольше 60 с) + 6. make test BASE_URL=http://127.0.0.1:$TEST_APP_PORT + make student_test BASE_URL=http://127.0.0.1:$TEST_APP_PORT + finally (и по Ctrl+C): + при неудаче: docker logs --tail 50 <тестовый контейнер> + docker stop -> docker rm <тестовый контейнер> + DROP DATABASE "test_" WITH (FORCE) (кроме KEEP_TEST_DB=1) + код выхода: первый ненулевой из smoke, набора, уборки +``` + +- **`docker compose run` берёт определение сервиса целиком:** образ, + `x-app-env`, монтирование `config.toml`, сеть и алиас Postgres. + Подменяется только `DATABASE__NAME`, поэтому ошибки в якоре окружения, + в `PGPORT`, в алиасе или в составе образа роняют и этот прогон. +- **`--no-deps`**, чтобы `run` не прогнал `migrate` по рабочей базе и + не пересоздал рабочие контейнеры. Postgres уже поднят `start_db`. +- **Публикация — явным `-p` на `127.0.0.1`.** `compose run` без + `--service-ports` порты сервиса не публикует, поэтому с рабочим API + на `APP_OUT_PORT` конфликта нет. Порт внутри контейнера тот же + `APP__PORT`, healthcheck образа работает как обычно. +- **Сборка перед прогоном.** Проверяется образ ровно из рабочего дерева, + а не устаревший. `migrate` использует тот же тег образа, что и `api`, + поэтому одна сборка покрывает оба. С кэшем слоя зависимостей это + секунды. +- **`CREATE` и `DROP` — через `docker compose exec -T postgres psql`** + под `POSTGRES_USER` по локальному сокету контейнера. Скрипту не нужны + ни `psql` на хосте, ни драйвер БД, он остаётся на stdlib, как + `bench/`. Имя базы проверяется по `^[a-z0-9_]+$` и берётся в кавычки. +- **`WITH (FORCE)`** (Postgres 13+) рвёт оставшиеся соединения. Базу + можно удалить, даже если контейнер не остановился штатно. +- **`TEST_APP_PORT`** в `.env`, по умолчанию 18088. Не пересекается с + рабочим API (8080) и портами драйвера скилла `run-mtusi-messenger` + (18080, 18090). Имя без секции: приложение его не читает. +- **Имя тестового контейнера фиксировано** (`<проект>-test-api`): + хвост прошлого прогона находится и удаляется без поиска. +- **Evidence.** Вывод `make test_isolated` — это прогон набора против + контейнера, которого требует спек `student-tests`, «Результат прогона + сохраняется». Отдельный прогон против `make run_docker` для evidence + не нужен. `make student_test` не меняется и работает против любого + `BASE_URL`. Успешный прогон снимает `session-auth`: в этом change + smoke lab2 и `test_security_scheme_in_openapi` ещё падают (Goals). + +*Альтернативы:* сервис на хосте (`uv run python -m src` с временной +базой) — быстрее, но не проверяет образ и compose и требует настройки, +выключающей reload в режиме console; оба режима сразу — больше кода в +скрипте ради цикла, который и так даёт `make run_dev` + +`make student_test`; отдельный контейнер Postgres на tmpfs — второй +сервис в compose ради мусора тестов; чистка через `DELETE` из тестов — +ломает black-box и правило `student-tests.md`. + +## Risks / Trade-offs + +- [Два `make test_isolated` одновременно удалят базу друг друга] → + Параллельный запуск не поддерживается (спек `student-tests`); прогон + занимает секунды, одному разработчику этого хватает. +- [Каждый `make test_isolated` пересобирает образ: цикл «поправил → + проверил» медленнее, чем на хосте] → Быстрая итерация — `make run_dev` + и `make student_test`; `test_isolated` — итоговая проверка перед + коммитом и evidence. +- [Проверки отказов из `failure-checks` с остановкой Postgres положат и + рабочую базу: сервер общий] → Временная база решает проблему мусора, + а не изоляцию отказов; `failure-checks` выберет для них отдельный + контейнер. +- [До `session-auth` ни один прогон не зелёный: падают smoke lab2 и + `test_security_scheme_in_openapi`] → Регрессию хранилища видно по + остальным 78 тестам; известное падение записано в «Переходном + состоянии» `AGENTS.md`, успешный `test_isolated` — задача + `session-auth`. +- [Пользователи из этого change без пароля, а `session-auth` добавит + `password_hash`] → Данные стенда синтетические. `session-auth` решает + сам: колонка `NOT NULL` после `make wipe_data` или nullable с отказом + во входе. Отмечено здесь, чтобы не стало сюрпризом. +- [`pool_pre_ping` — лишний round trip на выдачу соединения] → + Приемлемо для учебного стенда; альтернатива `pool_recycle` не спасает + от рестарта БД между выдачами. +- [Время ставит приложение, а не БД] → Одна реплика API на одном хосте; + при репликах лабы 3 часы общие (один Docker-host). Ограничение в + `REPORT.md`. +- [`CHECK` на `text` 1–4000 помешает lab4, где разрешён пустой текст с + вложениями] → Новая миграция в lab4, применённую не трогаем. +- [SQLAlchemy 2.1 — свежая ветка] → Асинхронный `env.py` и код repo + работают и на 2.0; при дефекте 2.1 откат на `<2.1` без правок кода. +- [Прогоны против рабочего стенда (`make student_test`, `make test`) + копят данные в volume] → Обычный прогон — `make test_isolated` + (решение 12); для чистого рабочего стенда — `make wipe_data`. +- [Точный набор исключений драйвера для 503 неизвестен заранее] → + Задача с остановленным Postgres фиксирует его до написания + перехвата. + +## Migration Plan + +Данных для переноса нет: лаба 1 хранила всё в памяти. Порядок: +зависимости и настройки → модели и первая ревизия → repo и сервисы → +lifespan, health, 503 → compose, Makefile, restart hook → тесты и +evidence → документы. Откат: `git revert` коммитов change и +`make wipe_data`. + +## Open Questions + +- Значения пула и таймаутов по умолчанию могут уточниться по замерам + `bench-postgres`: это настройки, спеки и план от них не зависят. diff --git a/openspec/changes/postgres-storage/proposal.md b/openspec/changes/postgres-storage/proposal.md new file mode 100644 index 00000000..4fd40e7a --- /dev/null +++ b/openspec/changes/postgres-storage/proposal.md @@ -0,0 +1,99 @@ +# Proposal + +## Why + +Лаба 2 требует, чтобы подтверждённые данные переживали перезапуск, а +источником истины был PostgreSQL (`README.md`, уровень «3»). Сейчас +пользователи, чаты и сообщения живут в `MemoryStore` одного процесса и +пропадают при рестарте. Это первый шаг перехода на лабу 2. Хранилище +меняется отдельно от аутентификации: API остаётся прежним (`X-User-Id`), +и перенесённые из лабы 1 `student-tests` проверяют замену без правок +тестов поведения. + +## What Changes + +- **BREAKING (для оператора):** стенд запускается только вместе с + PostgreSQL. Compose поднимает `postgres`, одноразовый сервис + миграций и `api`; данные лежат в именованном volume. +- `MemoryStore` удаляется. Repo работают через `AsyncSession` + (SQLAlchemy async, драйвер asyncpg), сервисы управляют транзакциями. + Уникальность `username` держит ограничение БД, создание чата с + участниками — одна транзакция. +- Схема версионируется alembic: `users`, `chats`, `chat_members` (с + позицией участника), `messages`; первичные и внешние ключи, уникальный + `username`, индекс истории `(chat_id, created_at, id)`. `env.py` — + асинхронный шаблон alembic, URL берётся из настроек. +- Миграции применяются до старта API: в docker — отдельный сервис того + же образа, в консоли `make run_dev` сам поднимает БД и накатывает + миграции. Добавляются цели `start_db`, `stop_db`, `upgrade`, + `revision`, `wipe_data`. +- Секция настроек `[database]`: адрес, учётные данные, пул, таймауты. + Значения для консоли и для docker приходят из одного `.env` без + переключения конфига комментариями. В compose нет литералов адреса и + порта Postgres, кроме адреса публикации `127.0.0.1`. +- `/health/ready` проверяет Postgres. Потеря связи с БД на + бизнес-запросе даёт 503 `unavailable`, а после возврата БД сервис + работает без перезапуска. +- **BREAKING (для защиты):** рестарт контейнеров больше не стирает + состояние. Прежний `X-User-Id` после рестарта стенда получает 200. + Появляется `scripts/restart.sh`: перезапуск API и Postgres с + сохранением volume. +- Образ содержит `migrations/` и `alembic.ini`. +- `make test_isolated`: тесты образа на временной базе `test_` в + том же Postgres. Команда собирает образ, создаёт базу, накатывает на + неё миграции сервисом миграций compose, поднимает отдельный контейнер + API из определения сервиса compose с подменой только имени базы, + прогоняет публичный smoke и `student-tests`, затем удаляет контейнер + и базу. Одна команда проверяет код, образ и связку compose, а рабочая + база не копит данные тестов. +- **BREAKING (для оператора):** цель `make run_no_compose` удаляется: + без PostgreSQL один контейнер API запросы не обслуживает, а сборку + образа проверяет `make run_docker`. + +Вне этого change: пароли, Basic → Bearer и сессии (`session-auth`), +Redis/Valkey, проверки отказов уровня «4», доработка `bench/`. + +## Capabilities + +### New Capabilities + +- `db-migrations`: версионируемая схема, миграции с нуля и повторный + запуск без дублей, применение миграций до старта API в docker и в + консоли. + +### Modified Capabilities + +- `data-storage`: хранение в PostgreSQL вместо памяти процесса, + сохранность после рестарта, целостность в БД, транзакция составной + операции, недоступность БД → 503, ограниченный пул и таймауты. +- `health`: readiness проверяет доступность PostgreSQL. +- `container-run`: стенд compose из `api`, `postgres` и миграций; + данные переживают рестарт; порты Postgres из `.env`; удаление данных + — отдельной явной командой; запуска одного контейнера без compose + (`make run_no_compose`) больше нет. +- `container-image`: образ собирается с тегом лабы 2 и содержит + миграции. +- `service-configuration`: параметры подключения к PostgreSQL; консоль + и docker без правки файлов и без литералов в compose. +- `student-tests`: прогон образа на временной базе, которая удаляется + после прогона. + +## Impact + +- Код: `src/infra/db/` (engine, модели), `src/core/repos/*`, + `src/core/services/*`, `src/api/dependencies.py`, + `src/api/routers/health.py`, `src/main.py` (lifespan), + `src/config/settings.py`; удаляется `src/infra/memory.py`. +- Новые файлы: `alembic.ini`, `migrations/`, `scripts/restart.sh`, + `student-tests/run_isolated.py`. +- Зависимости: `sqlalchemy[asyncio]`, `asyncpg`, `alembic` в основной + группе; `uv.lock`. +- Инфраструктура: `docker-compose.yml`, `Dockerfile`, `.env.example`, + `config_example.toml`, `Makefile`. +- Тесты: тесты поведения в `student-tests/` не меняются; записи + исключений в `spec_coverage.py` следуют за дельтами `data-storage` и + `health`. +- Документы: `AGENTS.md` (переходное состояние, карта кода), + `.claude/rules/` (settings, infra, run-modes, docker), скилл + `run-mtusi-messenger`, `REPORT.md` (архитектура, запуск, + доказательства хранения), `evidence/`. diff --git a/openspec/changes/postgres-storage/specs/container-image/spec.md b/openspec/changes/postgres-storage/specs/container-image/spec.md new file mode 100644 index 00000000..a6b0dd23 --- /dev/null +++ b/openspec/changes/postgres-storage/specs/container-image/spec.md @@ -0,0 +1,49 @@ +# Spec Delta + +## MODIFIED Requirements + +### Requirement: Сборка из чистого clone + +`docker build` в корне свежего clone SHALL собирать образ без +предварительных шагов: без `make env_setup`, без `config.toml` и `.env`. +Зависимости SHALL устанавливаться строго по `uv.lock`. Если lock не +соответствует `pyproject.toml`, сборка MUST завершаться ошибкой, а не +пересчитывать версии. + +#### Scenario: Свежий clone + +- **WHEN** в новом clone репозитория выполняется + `docker build -t mtusi-messenger:lab2 .` +- **THEN** образ собирается без ошибок + +#### Scenario: Устаревший lock + +- **WHEN** в `pyproject.toml` добавлена зависимость, а `uv.lock` не + обновлён +- **THEN** сборка завершается ошибкой проверки lock + +### Requirement: Состав образа + +Образ SHALL содержать только то, что нужно для работы сервиса и +применения миграций: интерпретатор, зависимости времени выполнения, +исходники `src/`, каталог миграций и конфигурацию инструмента миграций. +В образе MUST NOT быть `config.toml`, `.env`, публичных и собственных +тестов, контрактов, файлов `.claude` и `openspec`, а также инструментов +сборки: uv и компиляторов. + +#### Scenario: Нет конфигов и лишних каталогов + +- **WHEN** в образе просматривается рабочий каталог приложения +- **THEN** в нём есть только исходники, миграции с их конфигурацией и + окружение зависимостей, а `config.toml` и `.env` отсутствуют + +#### Scenario: Нет uv в runtime + +- **WHEN** в контейнере запрашивается `uv` +- **THEN** команда не найдена + +#### Scenario: Миграции из образа + +- **WHEN** контейнер из этого образа запускается командой применения + миграций с настройками подключения к Postgres +- **THEN** миграции применяются без доступа к исходникам на хосте diff --git a/openspec/changes/postgres-storage/specs/container-run/spec.md b/openspec/changes/postgres-storage/specs/container-run/spec.md new file mode 100644 index 00000000..d4a552b2 --- /dev/null +++ b/openspec/changes/postgres-storage/specs/container-run/spec.md @@ -0,0 +1,139 @@ +# Spec Delta + +## ADDED Requirements + +### Requirement: Данные переживают рестарт стенда + +Данные PostgreSQL SHALL храниться в именованном volume. Скрипт +`scripts/restart.sh` SHALL перезапускать API и все используемые +хранилища, сохраняя volume, схему и данные: без удаления volume, +очистки и повторного наполнения. Скрипт SHALL быть исполняемым, +завершаться с кодом 0 только после перезапуска, укладываться в 90 с и +MUST NOT печатать секреты. + +#### Scenario: Рестарт hook-ом + +- **WHEN** пользователь создан, отправил сообщение, затем выполнен + `scripts/restart.sh` +- **THEN** контейнеры API и Postgres перезапущены (новое время старта в + `docker inspect`), а после готовности запрос с прежним `X-User-Id` + получает 200 и видит своё сообщение + +### Requirement: Удаление учебных данных + +`make stop` и `make down` MUST NOT удалять volume с данными. Удаление +данных стенда SHALL выполняться отдельной явной командой +`make wipe_data`, которая запрашивает подтверждение. + +#### Scenario: down сохраняет данные + +- **WHEN** выполнены `make down`, затем `make run_docker` +- **THEN** ранее созданные пользователи и сообщения на месте + +#### Scenario: Явное удаление + +- **WHEN** выполнен `make wipe_data` и удаление подтверждено +- **THEN** volume Postgres удалён, и следующий `make run_docker` + поднимает пустую базу со схемой из миграций + +## MODIFIED Requirements + +### Requirement: Запуск через compose + +`make run_docker` SHALL собирать образ и поднимать стенд через +`docker compose`: PostgreSQL, одноразовый сервис миграций и API. API +SHALL стартовать после готовности PostgreSQL и успешных миграций. +Перед этим цель SHALL создавать недостающие `.env` и `config.toml` из +шаблонов (`make env_setup`) и MUST NOT перезаписывать существующие. +`make stop` SHALL останавливать сервисы, `make down` — удалять +контейнеры, сохраняя volume, `make logs` — показывать журнал API. + +#### Scenario: Штатный запуск + +- **WHEN** в свежем clone выполнен `make run_docker` +- **THEN** сервис отвечает на `http://localhost:8080/health/ready`, и + `make student_test` проходит + +### Requirement: Порты из .env + +Порты стенда и консольного запуска SHALL браться из одного `.env`: +- внутренний порт API — `APP__PORT`: параметр приложения `[app] port` в + формате настроек, на нём же работает healthcheck; +- внешний порт API — `APP_OUT_PORT`: порт на `127.0.0.1` хоста, + приложение его не читает; +- порт PostgreSQL внутри сети compose — `POSTGRES_PORT`, его слушает + сам сервер и использует API в docker; +- внешний порт PostgreSQL — `POSTGRES_OUT_PORT`: порт на `127.0.0.1` + хоста для запуска в консоли. + +Если переменная порта API не задана, SHALL действовать 8080. Параметры +приложения в `.env` SHALL записываться в формате настроек +(`SECTION__FIELD`). Имя без секции допускается только для переменных, +которые приложение не читает. Адрес и порт PostgreSQL MUST NOT быть +записаны в compose литералами. + +#### Scenario: Другой внешний порт + +- **WHEN** в `.env` задано `APP_OUT_PORT=8090`, и выполнен + `make run_docker` +- **THEN** API доступно на `localhost:8090`, а внутри контейнера + сервис слушает `APP__PORT` + +#### Scenario: Другой внутренний порт + +- **WHEN** в `.env` задано `APP__PORT=9090` +- **THEN** сервис внутри контейнера слушает 9090, контейнер становится + `healthy`, а API доступно на `localhost:$APP_OUT_PORT` + +#### Scenario: Другой порт Postgres + +- **WHEN** в `.env` заданы `POSTGRES_PORT=5544` и + `POSTGRES_OUT_PORT=5545`, а compose не правился +- **THEN** `make run_docker` поднимает стенд, `/health/ready` отвечает + 200, а `make run_dev` подключается к Postgres на `127.0.0.1:5545` + +### Requirement: Оба способа запуска описаны в REPORT.md + +Раздел «Запуск из чистого clone» в `REPORT.md` SHALL описывать два +способа запуска стенда: `make run_docker` (всё в compose) и +`make run_dev` (Postgres в compose, сервис на хосте). Для каждого SHALL +быть указаны подготовка (`make env_setup`), команды, которые выполняет +цель Makefile, применение миграций, ожидание готовности, проверки и +остановка. + +#### Scenario: Запуск по отчёту + +- **WHEN** проверяющий в свежем clone выполняет команды из `REPORT.md` + для любого из двух способов +- **THEN** `/health/ready` отвечает 200, а `make student_test` проходит + +### Requirement: Публикация только на localhost + +Порты API и PostgreSQL SHALL публиковаться в compose только на +`127.0.0.1` хоста. Адрес публикации SHALL быть записан литералом, а не +переменной. Учебный стенд MUST NOT быть +доступен с других машин сети. + +#### Scenario: Адрес публикации + +- **WHEN** для запущенных контейнеров API и Postgres выполняется + `docker port` +- **THEN** порты опубликованы на `127.0.0.1`, а не на `0.0.0.0` + +## REMOVED Requirements + +### Requirement: Запуск командами из README + +**Reason**: README лабы 2 не содержит команд запуска одного контейнера, +а API без PostgreSQL не обслуживает запросы. Цель `make run_no_compose` +удаляется. +**Migration**: стенд — `make run_docker`, консоль — `make run_dev`. +Сборку образа проверяет `make run_docker`, сборку из чистого clone — +требование «Сборка из чистого clone» capability `container-image`. + +### Requirement: Состояние теряется при рестарте контейнера + +**Reason**: на лабе 2 данные хранятся в PostgreSQL с volume и обязаны +переживать рестарт. +**Migration**: требование «Данные переживают рестарт стенда» и +`scripts/restart.sh`. diff --git a/openspec/changes/postgres-storage/specs/data-storage/spec.md b/openspec/changes/postgres-storage/specs/data-storage/spec.md new file mode 100644 index 00000000..b0f2a003 --- /dev/null +++ b/openspec/changes/postgres-storage/specs/data-storage/spec.md @@ -0,0 +1,126 @@ +# Spec Delta + +## ADDED Requirements + +### Requirement: Хранение в PostgreSQL + +Пользователи, чаты, участники чатов и сообщения SHALL храниться в +PostgreSQL, он — источник истины. Сервис MUST NOT хранить эти данные в +памяти процесса, файлах или SQLite. Подтверждённая запись (ответ 201) +SHALL быть зафиксирована в БД до ответа и видна следующему чтению. + +#### Scenario: Созданное видно сразу + +- **WHEN** клиент создал пользователя и следующим запросом использует + его `id` в `X-User-Id` +- **THEN** пользователь найден + +### Requirement: Данные переживают рестарт + +После перезапуска сервиса и PostgreSQL с сохранённым volume все ранее +подтверждённые пользователи, чаты, участники и сообщения SHALL быть +доступны в прежнем виде. + +#### Scenario: Прежний пользователь после рестарта + +- **WHEN** стенд перезапущен `scripts/restart.sh`, и клиент использует + `X-User-Id`, созданный до рестарта +- **THEN** ответ 200, а история чата этого пользователя содержит те же + сообщения в том же порядке + +### Requirement: Целостность данных в БД + +Ограничения SHALL проверяться самой БД, а не только сервисом: +уникальность `username`, существование пользователей и чатов, на +которые ссылаются участники и сообщения, уникальность участника в +чате, членство отправителя в чате сообщения. Порядок `member_ids`, +заданный при создании чата, SHALL сохраняться. + +#### Scenario: Порядок участников + +- **WHEN** чат создан с `member_ids` в порядке `[bob, alice]` +- **THEN** `GET` этого чата и список чатов возвращают `member_ids` в + том же порядке, в том числе после рестарта стенда + +### Requirement: Составная операция в одной транзакции + +Создание чата вместе с участниками SHALL выполняться одной +транзакцией: при ошибке на любом шаге в БД MUST NOT остаться ни чата, +ни части его участников. + +#### Scenario: Сбой при добавлении участников + +- **WHEN** чат уже записан в транзакции, а запись участников + завершается ошибкой +- **THEN** транзакция откатывается, чата нет ни в `GET` по его `id`, ни + в списках чатов участников + +### Requirement: Недоступность PostgreSQL + +Если PostgreSQL недоступен или не ответил за отведённое время, +запрос SHALL завершаться ответом 503 с `code` `unavailable` в формате +ошибки, а не 500 и не зависанием. Частично выполненная операция MUST +NOT фиксироваться. Когда PostgreSQL снова доступен, сервис SHALL +обслуживать запросы без перезапуска. + +#### Scenario: БД остановлена + +- **WHEN** PostgreSQL остановлен, и клиент отправляет сообщение +- **THEN** ответ 503 `unavailable` без деталей в `message` + +#### Scenario: БД вернулась + +- **WHEN** PostgreSQL остановлен, затем снова запущен, а сервис не + перезапускался +- **THEN** следующие запросы после готовности БД обслуживаются штатно + +### Requirement: Ограниченный пул соединений и таймауты + +Число соединений сервиса с PostgreSQL SHALL быть ограничено настройкой. +Ожидание свободного соединения, подключение и выполнение запроса SHALL +иметь таймауты из настроек. Истёкший таймаут SHALL давать 503 +`unavailable`. + +#### Scenario: Соединения исчерпаны + +- **WHEN** все соединения пула заняты дольше таймаута ожидания +- **THEN** новый запрос получает 503 `unavailable` не позже этого + таймаута, а не ждёт бесконечно + +## MODIFIED Requirements + +### Requirement: Параллельные запросы не повреждают состояние + +Параллельные запросы MUST NOT терять, дублировать или повреждать +записи. Уникальность `username` SHALL обеспечиваться ограничением БД, +а не проверкой перед вставкой, поэтому одновременная регистрация +одного имени создаёт ровно одного пользователя. + +#### Scenario: 100 сообщений от 10 клиентов + +- **WHEN** 10 клиентов одновременно отправляют по 10 сообщений в один + чат +- **THEN** получено 100 ответов 201, а полный обход истории возвращает + ровно 100 сообщений с уникальными `id` + +#### Scenario: Гонка за username + +- **WHEN** несколько клиентов одновременно регистрируют одинаковый + `username` +- **THEN** создан ровно один пользователь + +## REMOVED Requirements + +### Requirement: Состояние только в памяти одного процесса + +**Reason**: лаба 2 требует PostgreSQL как источник истины; память +процесса больше не хранит данные. +**Migration**: требование «Хранение в PostgreSQL». Сценарий «Созданное +видно сразу» перенесён туда без изменений. + +### Requirement: Потеря состояния при рестарте + +**Reason**: на лабе 2 подтверждённые данные обязаны переживать +рестарт; пустое состояние после рестарта теперь дефект. +**Migration**: требование «Данные переживают рестарт», сценарий +«Прежний пользователь после рестарта» теперь ждёт 200. diff --git a/openspec/changes/postgres-storage/specs/db-migrations/spec.md b/openspec/changes/postgres-storage/specs/db-migrations/spec.md new file mode 100644 index 00000000..aaf0f69d --- /dev/null +++ b/openspec/changes/postgres-storage/specs/db-migrations/spec.md @@ -0,0 +1,69 @@ +# Spec Delta + +## Purpose + +Как схема PostgreSQL появляется и меняется: версионируемые миграции, +применение с нуля и повторно без побочных эффектов, запуск миграций до +старта API в docker и в консоли. + +## ADDED Requirements + +### Requirement: Схема версионируется миграциями + +Таблицы, ограничения и индексы SHALL создаваться только миграциями из +репозитория. Сервис MUST NOT создавать или менять схему при старте. +Применённая миграция MUST NOT редактироваться: изменение схемы — новая +миграция поверх. + +#### Scenario: Схема с нуля + +- **WHEN** миграции применяются к пустой базе на новом volume +- **THEN** создаются все таблицы, ограничения и индексы, и сервис + обслуживает обязательные запросы без ручных шагов + +### Requirement: Повторный запуск миграций + +Повторное применение миграций к актуальной схеме SHALL завершаться +успешно и MUST NOT менять схему или данные. Миграции MUST NOT +создавать пользовательские данные. + +#### Scenario: Второй прогон + +- **WHEN** миграции применены, в базе есть пользователи, чаты и + сообщения, и миграции применяются ещё раз +- **THEN** команда завершается с кодом 0, а число строк во всех таблицах + не меняется + +### Requirement: Миграции до старта API в docker + +В стенде compose миграции SHALL применяться отдельным одноразовым +сервисом на образе приложения после готовности PostgreSQL. API SHALL +стартовать только после успешного завершения миграций. Если миграции +завершились ошибкой, API MUST NOT стартовать. + +#### Scenario: Порядок запуска + +- **WHEN** стенд поднимается командой `make run_docker` +- **THEN** сервис миграций завершается с кодом 0 раньше, чем стартует + API, а `/health/ready` отвечает 200 + +#### Scenario: Ошибка миграции + +- **WHEN** применение миграций завершается ошибкой +- **THEN** контейнер API не запускается, а ошибка видна в журнале + сервиса миграций + +### Requirement: Миграции до старта API в консоли + +`make run_dev` SHALL одной командой поднимать PostgreSQL из compose, +дожидаться его готовности, применять миграции и запускать сервис на +хосте. Отдельно миграции SHALL применяться командой `make upgrade`, +новая ревизия SHALL создаваться командой `make revision` на базе с +актуальной схемой. + +#### Scenario: Консольный запуск с нуля + +- **WHEN** в свежем clone после `make env_setup` выполняется + `make run_dev` +- **THEN** Postgres запущен, миграции применены, сервис отвечает на + `http://127.0.0.1:8080/health/ready` кодом 200 diff --git a/openspec/changes/postgres-storage/specs/health/spec.md b/openspec/changes/postgres-storage/specs/health/spec.md new file mode 100644 index 00000000..30faefe3 --- /dev/null +++ b/openspec/changes/postgres-storage/specs/health/spec.md @@ -0,0 +1,24 @@ +# Spec Delta + +## MODIFIED Requirements + +### Requirement: Readiness + +`GET /health/ready` SHALL отвечать 200 с телом `{"status": "ok"}`, +когда сервис может безопасно обслуживать обязательные запросы, и 503 с +`code` `unavailable` в формате ошибки, когда не может. На лабе 2 +критичная зависимость — PostgreSQL: проверка SHALL выполнять запрос к +нему с коротким таймаутом при каждом обращении. Проверка MUST NOT +требовать идентификации. + +#### Scenario: Сервис запущен + +- **WHEN** запуск сервиса завершён, PostgreSQL доступен, и клиент + запрашивает `GET /health/ready` +- **THEN** ответ 200, тело `{"status": "ok"}` + +#### Scenario: Хранилище не готово + +- **WHEN** PostgreSQL недоступен +- **THEN** ответ 503 с `code` `unavailable` в формате ошибки не позже + таймаута проверки, а `GET /health/live` при этом отвечает 200 diff --git a/openspec/changes/postgres-storage/specs/service-configuration/spec.md b/openspec/changes/postgres-storage/specs/service-configuration/spec.md new file mode 100644 index 00000000..61172d6b --- /dev/null +++ b/openspec/changes/postgres-storage/specs/service-configuration/spec.md @@ -0,0 +1,40 @@ +# Spec Delta + +## ADDED Requirements + +### Requirement: Подключение к PostgreSQL + +Параметры подключения SHALL задаваться в секции `[database]`: адрес, +порт, пользователь, пароль, имя базы, размер пула и таймауты. Пароль +SHALL иметь один источник — `POSTGRES_PASSWORD` в `.env`, который +читает и контейнер Postgres. Значения параметров MUST NOT печататься в +журнал целиком: пароль и строка подключения с паролем в журнал не +попадают. + +#### Scenario: Пароль в одном месте + +- **WHEN** в `.env` меняется `POSTGRES_PASSWORD`, и стенд пересоздаётся + на новом volume +- **THEN** и Postgres, и сервис в консоли и в docker используют новый + пароль без правки других файлов + +#### Scenario: Пароль не в журнале + +- **WHEN** сервис стартует и подключается к Postgres +- **THEN** в журнале нет значения пароля + +### Requirement: Консоль и docker без правки конфигурации + +Переключение между запуском в консоли и в docker MUST NOT требовать +правки `.env`, `config.toml` или compose, в том числе +комментирования и раскомментирования блоков. В консоли сервис SHALL +подключаться к Postgres по адресу публикации на хосте из `.env`, в +docker — по адресу и порту Postgres внутри сети compose, которые compose +передаёт в окружение контейнера из переменных `.env`. + +#### Scenario: Консоль, затем docker + +- **WHEN** выполнен `make run_dev`, затем он остановлен и выполнен + `make run_docker`, а файлы конфигурации между запусками не менялись +- **THEN** оба запуска доходят до `/health/ready` 200 и видят одни и + те же данные diff --git a/openspec/changes/postgres-storage/specs/student-tests/spec.md b/openspec/changes/postgres-storage/specs/student-tests/spec.md new file mode 100644 index 00000000..d8f2388c --- /dev/null +++ b/openspec/changes/postgres-storage/specs/student-tests/spec.md @@ -0,0 +1,50 @@ +# Spec Delta + +## ADDED Requirements + +### Requirement: Прогон на временной базе + +`make test_isolated` SHALL проверять образ, собранный из рабочего +дерева, в связке compose на временной базе `test_<имя рабочей базы>` в +PostgreSQL стенда. Команда SHALL: собрать образ, создать базу заново, +применить к ней миграции сервисом миграций compose, запустить отдельный +контейнер API из определения сервиса compose, в котором подменено только +имя базы, опубликовать его на `127.0.0.1:TEST_APP_PORT` из `.env`, +дождаться готовности, выполнить публичный smoke (`make test`) и весь +набор (`make student_test`) против этого контейнера, затем остановить и +удалить контейнер и удалить базу. Код выхода SHALL быть ненулевым, если +не прошёл smoke, набор или уборка. Рабочая база и рабочий контейнер API +MUST NOT затрагиваться. Параллельный запуск двух прогонов не +поддерживается. + +#### Scenario: Успешный прогон + +- **WHEN** в рабочей базе есть данные, рабочий стенд запущен, и + выполнен `make test_isolated` +- **THEN** smoke и набор прошли, код выхода 0, ни базы `test_`, ни + тестового контейнера после команды нет, число строк в таблицах + рабочей базы не изменилось, а рабочий API продолжает отвечать + +#### Scenario: Упавшие тесты + +- **WHEN** во время `make test_isolated` падает хотя бы один тест +- **THEN** код выхода ненулевой, журнал тестового контейнера выведен, + контейнер удалён, база `test_` удалена + +#### Scenario: Прерывание + +- **WHEN** `make test_isolated` прерван Ctrl+C +- **THEN** тестовый контейнер остановлен и удалён, база `test_` + удалена + +#### Scenario: Хвост прошлого прогона + +- **WHEN** тестовый контейнер или база `test_` остались от прогона, + убитого без уборки +- **THEN** следующий `make test_isolated` удаляет их и начинает заново + +#### Scenario: Сохранить базу для разбора + +- **WHEN** выполнен `make test_isolated KEEP_TEST_DB=1` +- **THEN** после прогона тестовый контейнер удалён, база `test_` + остаётся, а команда печатает её имя diff --git a/openspec/changes/postgres-storage/tasks.md b/openspec/changes/postgres-storage/tasks.md new file mode 100644 index 00000000..91a03c00 --- /dev/null +++ b/openspec/changes/postgres-storage/tasks.md @@ -0,0 +1,210 @@ +# Tasks + +Как строить — `design.md` (дальше «решение N»), что должно получиться — +дельты в `specs/`. Перед первым файлом слоя прочитать его правило: +`migrations.md` (модели, `migrations/`, `alembic.ini`), `repo-layer.md`, +`service-layer.md`, `infra.md`, `settings.md`, `docker.md`, +`run-modes.md`. Нужен запущенный Docker и свободные порты 8080 и 5433. +Состояние кода, по которому снимается доказательство для отчёта, +коммитится перед замером (`bench.md`, «Измеренное состояние — +commit»). + +## 1. Зависимости и настройки + +- [x] 1.1 `uv add "sqlalchemy[asyncio]>=2.1,<2.2" asyncpg alembic` в + основную группу; описание в `pyproject.toml` — лаба 2 (решение 2). + Проверка: `uv lock --check` проходит, `uv run python -c "import + sqlalchemy, asyncpg, alembic, greenlet"` без ошибок. +- [x] 1.2 Секция `Database` в `src/config/settings.py`: адрес, + учётные данные, пул и таймауты из таблицы решения 5, `url` через + `URL.create`. Проверка: без `.env` и `config.toml` `Settings` + загружается на дефолтах; пароль `p@ss%word` даёт рабочий URL, а + `url.render_as_string(hide_password=True)` его не показывает. +- [x] 1.3 `.env.example` по схеме решения 7 (пустой + `POSTGRES_PASSWORD`) и `TEST_APP_PORT=18088` (решение 12), + `config_example.toml` — пул и таймауты `[database]`, `make env_setup` + подставляет случайный пароль при создании `.env`. Проверка: после + `make env_setup` в свежем каталоге `POSTGRES_PASSWORD` непустой, + повторный `make env_setup` его не меняет; `uv run python -c "from + src.config import settings; print(settings.database.host, + settings.database.port)"` печатает `127.0.0.1 5433`. + +## 2. Модели и миграции + +- [x] 2.1 `src/infra/db/`: `Base` (`created_at`, `to_dict()`), модели + `users`, `chats`, `chat_members`, `messages` с ограничениями и + индексами из решения 3; фабрика engine и `async_sessionmaker` + (решение 5). Проверка: `Base.metadata.sorted_tables` — четыре + таблицы; у всех ограничений есть имена. +- [x] 2.2 `alembic.ini` и асинхронный `migrations/env.py` (решение 8): + URL из `settings.database.url`, логи через `src/infra/logger.py`, + логгер `alembic` на `INFO`. Проверка: при запущенном Postgres + `uv run alembic current` печатает JSON-строки, пароля в выводе нет. +- [x] 2.3 Первая ревизия: autogenerate, затем руками `CHECK` и + проверка имён ограничений; `downgrade` зеркалит `upgrade`. + Проверка: на пустом volume `make upgrade` создаёт таблицы (`\d+` в + `psql`), `alembic downgrade base` и снова `upgrade head` проходят, + повторный `make upgrade` ничего не меняет. + +## 3. Compose, образ, Makefile + +- [x] 3.1 Выбрать тег Postgres 18.x с патч-версией и digest индекса + (`docker buildx imagetools inspect`), точку монтирования volume + взять из `Config.Volumes` образа (решение 9). Проверка: тег, digest + и путь записаны в `docker-compose.yml`, путь совпадает с метаданными. +- [x] 3.2 `docker-compose.yml`: `name:`, якорь `x-app-env`, сервисы + `postgres` (`PGPORT`, алиас, `pg_isready`, volume `postgres_data`, + публикация `127.0.0.1`), `migrate`, `api` с `depends_on` (решения 7, + 8, 9). Проверка: `docker compose --env-file .env config --quiet` + проходит; в `environment` и `ports` нет адреса и порта Postgres + литералами, кроме `127.0.0.1`. +- [x] 3.3 `Dockerfile`: `COPY migrations alembic.ini` в runtime, + комментарий — лаба 2. Проверка: образ из контекста чистого clone + (`docker.md`) собирается; в `/app` есть `migrations/` и + `alembic.ini`, `alembic --help` работает, `uv` не найден. +- [x] 3.4 `Makefile`: `start_db` (`up -d --wait postgres`), `stop_db`, + `upgrade`, `revision` (зависит от `upgrade`, `read -p`), `run_dev` + (`start_db`, `upgrade`, сервис), `wipe_data` с подтверждением; + `down` без `-v`; удалить `run_no_compose`, `DOCKER_IMAGE` и + `DOCKER_CONTAINER` (решение 9). Проверка: `make -n` для каждой цели + печатает ожидаемые команды; `make wipe_data` без подтверждения ничего + не удаляет; `grep -n run_no_compose Makefile` пусто. +- [x] 3.5 `student-tests/run_isolated.py` (stdlib: `docker compose + build`, `exec psql`, `run` для `migrate` и `api`, ожидание готовности, + уборка в `finally`) и цель `test_isolated: env_setup start_db` по + решению 12; `KEEP_TEST_DB` передаётся из аргумента make. Проверка: + `make -n test_isolated` печатает запуск скрипта; `uv run pytest + --collect-only` не собирает `run_isolated.py`; `make lint` чистый. + +## 4. Repo, сервисы, API + +- [x] 4.1 Repo `user`, `chat`, `message` на `AsyncSession` (решения 3, + 4): `ON CONFLICT`, `array_agg(... ORDER BY position)`, keyset через + `tuple_` для истории и списка чатов. Проверка: на запущенном стенде + `EXPLAIN` запросов истории и списка чатов с `SET enable_seqscan = + off` использует индексы `(chat_id, created_at, id)` и + `(user_id, created_at, chat_id)` без `Sort` всей выборки. +- [x] 4.2 Сервисы на `db_session`, commit в сервисе, создание чата — + одна транзакция (решение 4); удалить `MemoryStore`, `get_store` и + `src/infra/memory.py`. Проверка: `grep -rn MemoryStore src` пусто, + `make lint` чистый. +- [x] 4.3 `src/main.py`: engine в lifespan, `dispose()` при остановке; + `dependencies.py`: `get_db_session`, фабрики сервисов; + `get_current_user` по-прежнему по `X-User-Id`. Проверка: `make + run_dev` поднимается до `/health/ready` 200; по SIGTERM в журнале + «Stopped API» и «Finished server process»; пароля в журнале нет. + +## 5. Недоступность БД и readiness + +- [x] 5.1 Определить классы исключений: API запущен, Postgres + остановлен (`docker compose stop postgres`), затем приостановлен + (`docker compose pause postgres`); записать исключения из traceback + для отказа в соединении, клиентского таймаута и таймаута пула. + Проверка: список внесён в решение 6 `design.md`. +- [ ] 5.2 Перехват в `get_db_session` (решение 6): откат, `warning`, + `ServiceUnavailable`. Проверка: сценарии «БД остановлена» и «БД + вернулась» (`data-storage`) — 503 `unavailable` без деталей, после + `docker compose start postgres` запросы проходят без рестарта API; + вывод в `evidence/storage/db-unavailable.txt`. +- [ ] 5.3 `/health/ready`: `SELECT 1` с таймаутом через engine. + Проверка: при остановленном Postgres `/health/ready` — 503 не позже + таймаута, `/health/live` — 200. +- [ ] 5.4 Сценарий «Соединения исчерпаны»: `DATABASE__POOL_SIZE=1`, + `DATABASE__MAX_OVERFLOW=0`, `DATABASE__POOL_TIMEOUT_SECONDS=1`, + Postgres на паузе, два одновременных запроса. Проверка: второй + получает 503 примерно через 1 с, первый — 503 после + `request_timeout_seconds` и закрытия соединения (6 + 2 с); вывод в + `evidence/storage/pool-timeout.txt`. + +## 6. Рестарт стенда + +- [ ] 6.1 `scripts/restart.sh` по решению 10, исполняемый бит в git. + Проверка: `git ls-files -s scripts/restart.sh` — режим `100755`; + скрипт укладывается в 90 с; по журналу записано, прогоняет ли `up` + сервис `migrate` заново. +- [ ] 6.2 Сценарий «Рестарт hook-ом» (`container-run`) и «Прежний + пользователь после рестарта» (`data-storage`): пользователь, чат с + `member_ids` в порядке `[bob, alice]`, сообщения; `StartedAt` до и + после `scripts/restart.sh`. Проверка: после рестарта тот же + `X-User-Id` получает 200, история и порядок участников прежние; + вывод в `evidence/storage/restart.txt`. + +## 7. Проверки стенда + +- [ ] 7.1 Сценарий «Консоль и контейнер» (`student-tests`): `make + student_test` против `make run_dev` и против `make run_docker`. + Проверка: в обоих прогонах прошли все тесты, кроме + `test_security_scheme_in_openapi` (переход контракта, design, Goals). + Evidence набора против контейнера снимает `session-auth`. +- [ ] 7.2 Миграции с нуля и повторно (`db-migrations`): `make + wipe_data`, `make run_docker`, журнал `migrate`; затем повторный + прогон миграций при данных в базе. Проверка: `migrate` завершился + с кодом 0 раньше старта API; число строк во всех таблицах до и после + повтора одинаково; вывод в `evidence/migrations/from-zero-and-rerun.txt`. +- [ ] 7.3 Сценарий «Другой порт Postgres»: `POSTGRES_PORT=5544`, + `POSTGRES_OUT_PORT=5545` в `.env`, compose не правится. Проверка: + `make run_docker` доходит до `/health/ready` 200, `make run_dev` + подключается к `127.0.0.1:5545`; `.env` возвращён; вывод в + `evidence/storage/postgres-port.txt`. +- [ ] 7.4 Сценарий «Консоль, затем docker» (`service-configuration`) и + «down сохраняет данные» (`container-run`). Проверка: данные, + созданные через `make run_dev`, видны после `make run_docker` и после + `make down` + `make run_docker`, файлы конфигурации не менялись. +- [ ] 7.5 Сценарий «Адрес публикации» (`container-run`). Проверка: + `docker port` для API и Postgres стенда показывает `127.0.0.1`, а не + `0.0.0.0`. +- [ ] 7.6 Механика «Прогон на временной базе» (`student-tests`) при + запущенном рабочем стенде с данными: обычный прогон (до + `session-auth` он заканчивается падением smoke — это сценарий + «Упавшие тесты»); остановка тестового контейнера во время прогона; + Ctrl+C; хвост после `kill -9` скрипта; `KEEP_TEST_DB=1`. Проверка: в + каждом случае код выхода, наличие базы `test_` (`\l` в `psql`) и + тестового контейнера (`docker ps -a`) соответствуют сценарию; число + строк рабочей базы до и после одинаково, рабочий API отвечает; после + разбора `KEEP_TEST_DB` база удалена руками; вывод в + `evidence/tests/test-isolated-mechanics.txt`. Сценарий «Успешный + прогон» и evidence набора против контейнера — задача `session-auth`. +- [ ] 7.7 Перенести дельты в основные спеки (`/opsx:sync`) и в том же + шаге обновить `student-tests/spec_coverage.py`: тексты исключений + «Прежний пользователь после рестарта» и «Хранилище не готово», + исключения для «Сбой при добавлении участников», «БД остановлена», + «БД вернулась», «Соединения исчерпаны» со ссылками на evidence и + change `failure-checks`; тест сценария «Порядок участников» в + `test_data_storage.py`. Purpose основного спека `container-run` + переписать руками: в нём «голый `docker run` из README (`make + run_no_compose`)», а дельта Purpose не меняет. Проверка: `make + student_test` против стенда — прошли все тесты, кроме + `test_security_scheme_in_openapi`, в том числе `test_coverage.py`; + `grep -rn run_no_compose openspec/specs` пусто. + +## 8. Документы и инструменты + +- [ ] 8.1 Правила по решениям 11 и 12: `settings.md`, `infra.md`, + `run-modes.md` (плюс `test_isolated`), `docker.md`, `student-tests.md` + (обычный прогон и evidence — `make test_isolated`, против любого + стенда — `make student_test`). Проверка: `grep -n "POSTGRES_VOLUME\|решает + design change" .claude/rules` — только там, где решение ещё не + принято (`membership-cache`); `grep -rn run_no_compose .claude` + пусто. +- [ ] 8.2 `AGENTS.md`: «Переходное состояние» без закрытых пунктов и с + известным падением `test_security_scheme_in_openapi` до + `session-auth`, + карта кода, команды `start_db`, `stop_db`, `upgrade`, `revision`, + `wipe_data`, `test_isolated`, без `run_no_compose`. Проверка: каждая команда из + таблицы есть в `Makefile` (`make -n <цель>`). +- [ ] 8.3 Скилл `run-mtusi-messenger`: `driver.py start` перед + сервером выполняет `make start_db upgrade`; `SKILL.md` без «рестарт = + пустое состояние» и `MemoryStore`. Проверка: `python3 + .claude/skills/run-mtusi-messenger/driver.py all` завершается с кодом + 0. +- [ ] 8.4 `REPORT.md`: запуск из чистого clone (`make run_docker`, + `make run_dev`, остановка, `make wipe_data`), проверки (`make + test_isolated`; `make student_test` против любого стенда); + архитектура — схема, транзакционные границы, + источник истины, семантика при конкурентных вставках, ограничение + часов, соответствие переменных `.env.example` skeleton; строки + доказательств уровня «3» по хранению со ссылками на `evidence/`. + Проверка: у каждой строки есть команда, наблюдение и путь к файлу. +- [ ] 8.5 Финальная проверка: `make lint`, `make check`, + `openspec validate postgres-storage --strict`, `graphify update .`. + Проверка: все команды без ошибок. diff --git a/pyproject.toml b/pyproject.toml index 46b3be87..5b8ce36c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,7 +1,7 @@ [project] name = "mtusi-messenger" version = "0.1.0" -description = "Lab 1: Docker and in-memory messenger" +description = "Lab 2: PostgreSQL storage, sessions and Redis/Valkey" requires-python = "==3.12.*" dependencies = [ @@ -11,6 +11,11 @@ dependencies = [ "fastapi[all]>=0.137.2,<1.0.0", "uvicorn>=0.29.0,<1.0.0", "structlog>=24.1.0,<25.0.0", + # asyncio-extra ставит greenlet: без него асинхронный engine 2.1 не работает + "sqlalchemy[asyncio]>=2.1.1,<2.2", + "asyncpg>=0.31.0,<0.32", + # в основной группе: сервис миграций работает в runtime-образе (--no-dev) + "alembic>=1.20.0,<2", ] [project.optional-dependencies] diff --git a/scripts/restart.sh b/scripts/restart.sh new file mode 100755 index 00000000..6c996850 --- /dev/null +++ b/scripts/restart.sh @@ -0,0 +1,16 @@ +#!/bin/sh +set -eu +# Restart hook для make test-persistence (tests/README.md) по образцу +# scripts/restart.example.sh; правила — .claude/rules/docker.md. +# Перезапускает API и все хранилища стенда (на лабе 2 — Postgres) с +# сохранением volume, схемы и данных: без down -v, очистки и повторного +# наполнения. start api запускает и его зависимость migrate: повторный +# прогон миграций ничего не меняет. Готовность API ждёт сам тест. +# Секреты не печатает. +cd "$(dirname "$0")/.." + +docker compose stop api +docker compose restart postgres +# тот же контейнер: --wait только дожидается его healthcheck +docker compose up -d --wait postgres +docker compose start api diff --git a/src/api/dependencies.py b/src/api/dependencies.py index fabebd3c..284f5b4a 100644 --- a/src/api/dependencies.py +++ b/src/api/dependencies.py @@ -1,45 +1,97 @@ -"""Зависимости ручек: хранилище, сервисы, текущий пользователь, страница.""" +"""Зависимости ручек: сессия БД, сервисы, текущий пользователь, страница.""" +import asyncio +from collections.abc import AsyncIterator from dataclasses import dataclass from typing import Annotated from fastapi import Depends, Query, Request, Security from fastapi.security import APIKeyHeader +from sqlalchemy.ext.asyncio import ( + AsyncEngine, + AsyncSession, + async_sessionmaker, +) +from src.config import settings from src.core import exceptions from src.core.services import ChatService, MessageService, UserService -from src.infra.logger import current_user_id -from src.infra.memory import MemoryStore +from src.infra.db import is_db_unavailable, ping +from src.infra.logger import AbstractLogger, current_user_id, get_logger from src.schemas import dataclasses from src.utils.constants import ( PAGE_LIMIT_DEFAULT, PAGE_LIMIT_MAX, PAGE_LIMIT_MIN, + READINESS_DB_TIMEOUT_SECONDS, USER_ID_HEADER, ) +logger: AbstractLogger = get_logger().bind(module="api_dependencies") -async def get_store(request: Request) -> MemoryStore: - """Хранилище из lifespan; до его создания — 503.""" - store: MemoryStore | None = getattr(request.app.state, "store", None) - if store is None: + +async def get_db_session(request: Request) -> AsyncIterator[AsyncSession]: + """Одна сессия БД на запрос; commit делает сервис. + + Незакоммиченное при выходе откатывается. Вся работа запроса с БД + ограничена `[database] request_timeout_seconds`: зависший Postgres не + держит запрос бесконечно. Недоступность БД (`is_db_unavailable`) — + 503 `unavailable`, а соединение не возвращается в пул: его состояние + неизвестно, а откат на зависшем сервере повис бы. + """ + session_factory: async_sessionmaker[AsyncSession] | None = getattr( + request.app.state, + "session_factory", + None, + ) + if session_factory is None: raise exceptions.ServiceUnavailable - return store + async with session_factory() as db_session: + try: + async with asyncio.timeout( + settings.database.request_timeout_seconds, + ): + yield db_session + except Exception as e: + if not is_db_unavailable(e): + raise + await db_session.invalidate() + logger.warning( + "Database is unavailable", + error_type=type(e).__name__, + error=str(e), + ) + raise exceptions.ServiceUnavailable from e -StoreDep = Annotated[MemoryStore, Depends(get_store)] +DbSessionDep = Annotated[AsyncSession, Depends(get_db_session)] -async def get_user_service(store: StoreDep) -> UserService: - return UserService(store=store) +async def require_database(request: Request) -> None: + """Readiness: Postgres отвечает на `SELECT 1` за отведённое время. + + Любая ошибка — 503: готовность не должна отвечать 500. Не логирует: + healthcheck спрашивает каждые несколько секунд. + """ + engine: AsyncEngine | None = getattr(request.app.state, "engine", None) + if engine is None: + raise exceptions.ServiceUnavailable + try: + await ping(engine, timeout=READINESS_DB_TIMEOUT_SECONDS) + except Exception as e: + raise exceptions.ServiceUnavailable from e -async def get_chat_service(store: StoreDep) -> ChatService: - return ChatService(store=store) +async def get_user_service(db_session: DbSessionDep) -> UserService: + return UserService(db_session=db_session) -async def get_message_service(store: StoreDep) -> MessageService: - return MessageService(store=store) +async def get_chat_service(db_session: DbSessionDep) -> ChatService: + return ChatService(db_session=db_session) + + +async def get_message_service(db_session: DbSessionDep) -> MessageService: + return MessageService(db_session=db_session) UserServiceDep = Annotated[UserService, Depends(get_user_service)] diff --git a/src/api/routers/health.py b/src/api/routers/health.py index f27f7fa5..92d102f1 100644 --- a/src/api/routers/health.py +++ b/src/api/routers/health.py @@ -1,6 +1,6 @@ from fastapi import APIRouter, Depends -from src.api.dependencies import get_store +from src.api.dependencies import require_database from src.api.schemas import Error, Health from src.utils.constants import HEALTH_LIVE_PATH, HEALTH_READY_PATH @@ -18,8 +18,8 @@ async def liveness() -> Health: HEALTH_READY_PATH, response_model=Health, responses={503: {"model": Error}}, - dependencies=[Depends(get_store)], + dependencies=[Depends(require_database)], ) async def readiness() -> Health: - """Хранилище создано — можно обслуживать запросы; иначе 503.""" + """Postgres отвечает — можно обслуживать запросы; иначе 503.""" return Health(status="ok") diff --git a/src/config/settings.py b/src/config/settings.py index 5ef87d97..d9c9314d 100644 --- a/src/config/settings.py +++ b/src/config/settings.py @@ -1,13 +1,14 @@ from pathlib import Path from typing import Annotated, Literal -from pydantic import BaseModel, BeforeValidator, Field +from pydantic import BaseModel, BeforeValidator, Field, SecretStr from pydantic_settings import ( BaseSettings, PydanticBaseSettingsSource, SettingsConfigDict, TomlConfigSettingsSource, ) +from sqlalchemy.engine import URL from src.schemas.enums import RunModeEnum @@ -39,6 +40,45 @@ class App(BaseModel): return "127.0.0.1" +class Database(BaseModel): + """Подключение к PostgreSQL. + + Адрес и учётные данные приходят из `.env`: в console — мостами к + `POSTGRES_*`, в docker — из `environment` compose. Пул и таймауты — + из `config.toml`. + """ + + host: str = "127.0.0.1" + port: int = Field(default=5432, ge=1, le=65535) + user: str = "messenger" + password: SecretStr = SecretStr("") + name: str = "messenger" + + pool_size: int = Field(default=10, ge=1) + max_overflow: int = Field(default=5, ge=0) + # секунды ожидания свободного соединения пула + pool_timeout_seconds: float = Field(default=5, gt=0) + # секунды на установку соединения + connect_timeout_seconds: float = Field(default=3, gt=0) + # миллисекунды, серверный statement_timeout; 0 — без ограничения + statement_timeout_ms: int = Field(default=5000, ge=0) + # секунды на всю работу запроса с БД (asyncio): зависший сервер или + # обрыв сети, где серверный таймаут не сработает + request_timeout_seconds: float = Field(default=6, gt=0) + + @property + def url(self) -> URL: + """URL asyncpg; пароль экранирует `URL.create`, строку не собираем.""" + return URL.create( + drivername="postgresql+asyncpg", + username=self.user, + password=self.password.get_secret_value(), + host=self.host, + port=self.port, + database=self.name, + ) + + class Settings(BaseSettings): model_config = SettingsConfigDict( extra="ignore", @@ -49,6 +89,7 @@ class Settings(BaseSettings): ) app: App = App() + database: Database = Database() @classmethod def settings_customise_sources( diff --git a/src/core/exceptions/service.py b/src/core/exceptions/service.py index a6c3cce0..309d967f 100644 --- a/src/core/exceptions/service.py +++ b/src/core/exceptions/service.py @@ -2,6 +2,7 @@ from .base import DomainError class ServiceUnavailable(DomainError): - """Сервис ещё не готов обслуживать запросы: хранилище не создано.""" + """Сервис не может обслужить запрос: PostgreSQL недоступен, не ответил + вовремя или engine ещё не создан.""" - default_message = "Service is not ready" + default_message = "Service is temporarily unavailable" diff --git a/src/core/repos/chat.py b/src/core/repos/chat.py index 6d552431..dadc23e8 100644 --- a/src/core/repos/chat.py +++ b/src/core/repos/chat.py @@ -1,50 +1,112 @@ -import bisect from uuid import UUID -from src.infra.memory import MemoryStore +from sqlalchemy import Row, func, insert, select, tuple_ +from sqlalchemy.dialects.postgresql import aggregate_order_by +from sqlalchemy.ext.asyncio import AsyncSession +from sqlalchemy.orm import aliased + +from src.infra.db.models import Chat, ChatMember from src.schemas import dataclasses from src.utils.cursor import CursorKey +# участники чата в порядке member_ids при создании; отдельный алиас, чтобы +# не смешаться с ChatMember внешнего запроса списка чатов +_member = aliased(ChatMember) +_MEMBER_IDS = ( + select( + func.array_agg(aggregate_order_by(_member.user_id, _member.position)), + ) + .where(_member.chat_id == Chat.id) + .scalar_subquery() + .label("member_ids") +) +_CHAT_COLUMNS = (Chat.id, Chat.title, _MEMBER_IDS, Chat.created_at) -def _chat_key(chat: dataclasses.ChatFullDTO) -> CursorKey: - return (chat.created_at, chat.id) + +def _to_dto(row: Row) -> dataclasses.ChatFullDTO: + return dataclasses.ChatFullDTO( + id=row.id, + title=row.title, + member_ids=tuple(row.member_ids), + created_at=row.created_at, + ) async def insert_chat( - store: MemoryStore, + db_session: AsyncSession, *, chat: dataclasses.ChatFullDTO, ) -> dataclasses.ChatFullDTO: - """Чат, его место в списках всех участников и пустая история — разом.""" - store.chats[chat.id] = chat - for member_id in chat.member_ids: - bisect.insort( - store.chats_by_user.setdefault(member_id, []), - chat, - key=_chat_key, - ) - store.messages_by_chat[chat.id] = [] + """Только строка чата; участников пишет `insert_chat_members`.""" + await db_session.execute( + insert(Chat).values( + id=chat.id, + title=chat.title, + created_at=chat.created_at, + ), + ) return chat +async def insert_chat_members( + db_session: AsyncSession, + *, + chat: dataclasses.ChatFullDTO, +) -> int: + """Все участники одной вставкой; позиция — порядок в `member_ids`. + + `created_at` участника — копия времени чата: по нему идёт keyset + списка чатов пользователя. + """ + result = await db_session.execute( + insert(ChatMember).values( + [ + { + "chat_id": chat.id, + "user_id": user_id, + "position": position, + "created_at": chat.created_at, + } + for position, user_id in enumerate(chat.member_ids) + ], + ), + ) + return result.rowcount + + async def get_chat( - store: MemoryStore, + db_session: AsyncSession, *, chat_id: UUID, ) -> dataclasses.ChatFullDTO | None: - return store.chats.get(chat_id) + statement = select(*_CHAT_COLUMNS).where(Chat.id == chat_id) + row = (await db_session.execute(statement)).one_or_none() + return None if row is None else _to_dto(row) async def get_user_chats_page( - store: MemoryStore, + db_session: AsyncSession, *, user_id: UUID, after: CursorKey | None, limit: int, ) -> list[dataclasses.ChatFullDTO]: - """До `limit + 1` чатов пользователя строго после ключа `after`.""" - chats = store.chats_by_user.get(user_id, []) - start = 0 + """До `limit + 1` чатов пользователя строго после ключа `after`. + + Keyset по индексу `(user_id, created_at, chat_id)` участников: их + `created_at` равен времени чата, поэтому порядок — `(created_at, id)` + чатов. + """ + statement = ( + select(*_CHAT_COLUMNS) + .join(ChatMember, ChatMember.chat_id == Chat.id) + .where(ChatMember.user_id == user_id) + .order_by(ChatMember.created_at, ChatMember.chat_id) + .limit(limit + 1) + ) if after is not None: - start = bisect.bisect_right(chats, after, key=_chat_key) - return chats[start : start + limit + 1] + statement = statement.where( + tuple_(ChatMember.created_at, ChatMember.chat_id) > tuple_(*after), + ) + rows = (await db_session.execute(statement)).all() + return [_to_dto(row) for row in rows] diff --git a/src/core/repos/message.py b/src/core/repos/message.py index 4792d6aa..d65c64d4 100644 --- a/src/core/repos/message.py +++ b/src/core/repos/message.py @@ -1,38 +1,52 @@ -import bisect +from dataclasses import asdict from uuid import UUID -from src.infra.memory import MemoryStore +from sqlalchemy import insert, select, tuple_ +from sqlalchemy.ext.asyncio import AsyncSession + +from src.infra.db.models import Message from src.schemas import dataclasses from src.utils.cursor import CursorKey - -def _message_key(message: dataclasses.MessageFullDTO) -> CursorKey: - return (message.created_at, message.id) +_MESSAGE_COLUMNS = ( + Message.id, + Message.chat_id, + Message.sender_id, + Message.text, + Message.created_at, +) async def insert_message( - store: MemoryStore, + db_session: AsyncSession, *, message: dataclasses.MessageFullDTO, ) -> dataclasses.MessageFullDTO: - bisect.insort( - store.messages_by_chat[message.chat_id], - message, - key=_message_key, - ) + await db_session.execute(insert(Message).values(**asdict(message))) return message async def get_chat_messages_page( - store: MemoryStore, + db_session: AsyncSession, *, chat_id: UUID, after: CursorKey | None, limit: int, ) -> list[dataclasses.MessageFullDTO]: - """До `limit + 1` сообщений чата строго после ключа `after`.""" - messages = store.messages_by_chat.get(chat_id, []) - start = 0 + """До `limit + 1` сообщений чата строго после ключа `after`. + + Keyset по индексу `(chat_id, created_at, id)`, без OFFSET: страница + не просматривает историю до курсора. + """ + statement = ( + select(*_MESSAGE_COLUMNS) + .where(Message.chat_id == chat_id) + .order_by(Message.created_at, Message.id) + .limit(limit + 1) + ) if after is not None: - start = bisect.bisect_right(messages, after, key=_message_key) - return messages[start : start + limit + 1] + statement = statement.where( + tuple_(Message.created_at, Message.id) > tuple_(*after), + ) + rows = (await db_session.execute(statement)).all() + return [dataclasses.MessageFullDTO(**row._mapping) for row in rows] diff --git a/src/core/repos/user.py b/src/core/repos/user.py index 0466c878..833824ff 100644 --- a/src/core/repos/user.py +++ b/src/core/repos/user.py @@ -1,36 +1,52 @@ from collections.abc import Iterable +from dataclasses import asdict from uuid import UUID -from src.infra.memory import MemoryStore +from sqlalchemy import select +from sqlalchemy.dialects.postgresql import insert as pg_insert +from sqlalchemy.ext.asyncio import AsyncSession + +from src.infra.db.models import User from src.schemas import dataclasses +_USER_COLUMNS = (User.id, User.username, User.display_name, User.created_at) + async def insert_user( - store: MemoryStore, + db_session: AsyncSession, *, user: dataclasses.UserFullDTO, ) -> dataclasses.UserFullDTO | None: - """Вставка с проверкой уникальности username; конфликт — None.""" - if user.username in store.user_id_by_username: + """Вставка; занятый username — None (уникальность держит БД).""" + statement = ( + pg_insert(User) + .values(**asdict(user)) + .on_conflict_do_nothing(index_elements=[User.username]) + .returning(*_USER_COLUMNS) + ) + row = (await db_session.execute(statement)).one_or_none() + if row is None: return None - store.users[user.id] = user - store.user_id_by_username[user.username] = user.id - store.chats_by_user[user.id] = [] - return user + return dataclasses.UserFullDTO(**row._mapping) async def get_user( - store: MemoryStore, + db_session: AsyncSession, *, user_id: UUID, ) -> dataclasses.UserFullDTO | None: - return store.users.get(user_id) + statement = select(*_USER_COLUMNS).where(User.id == user_id) + row = (await db_session.execute(statement)).one_or_none() + if row is None: + return None + return dataclasses.UserFullDTO(**row._mapping) async def get_existing_user_ids( - store: MemoryStore, + db_session: AsyncSession, *, user_ids: Iterable[UUID], ) -> set[UUID]: """Те из переданных id, для которых пользователь существует.""" - return {user_id for user_id in user_ids if user_id in store.users} + statement = select(User.id).where(User.id.in_(list(user_ids))) + return set((await db_session.scalars(statement)).all()) diff --git a/src/core/services/chat.py b/src/core/services/chat.py index 71221ace..e17b28b4 100644 --- a/src/core/services/chat.py +++ b/src/core/services/chat.py @@ -1,12 +1,13 @@ from collections.abc import Sequence from uuid import UUID, uuid4 +from sqlalchemy.ext.asyncio import AsyncSession + from src.core import exceptions from src.core.repos import chat as chat_repo from src.core.repos import user as user_repo from src.core.services.pagination import decode_page_cursor, split_page from src.infra.logger import AbstractLogger, get_logger -from src.infra.memory import MemoryStore from src.schemas import dataclasses from src.utils.cursor import user_chats_scope from src.utils.utc import utcnow @@ -15,8 +16,8 @@ logger: AbstractLogger = get_logger().bind(module="chat_service") class ChatService: - def __init__(self, store: MemoryStore) -> None: - self.store = store + def __init__(self, db_session: AsyncSession) -> None: + self.db_session = db_session async def create_chat( self, @@ -25,6 +26,8 @@ class ChatService: title: str, member_ids: Sequence[UUID], ) -> dataclasses.ChatFullDTO: + """Чат с участниками — одна транзакция: при ошибке не остаётся ни + чата, ни части участников.""" log = logger.bind(method="create_chat", members_count=len(member_ids)) unique_ids = set(member_ids) if ( @@ -35,7 +38,7 @@ class ChatService: raise exceptions.InvalidChatMembers # пользователей не удаляют, поэтому проверка до вставки не устареет existing_ids = await user_repo.get_existing_user_ids( - store=self.store, + db_session=self.db_session, user_ids=unique_ids, ) if existing_ids != unique_ids: @@ -48,7 +51,12 @@ class ChatService: member_ids=tuple(member_ids), created_at=utcnow(), ) - await chat_repo.insert_chat(store=self.store, chat=chat) + await chat_repo.insert_chat(db_session=self.db_session, chat=chat) + await chat_repo.insert_chat_members( + db_session=self.db_session, + chat=chat, + ) + await self.db_session.commit() log.info("Created chat", chat_id=chat.id) return chat @@ -62,7 +70,10 @@ class ChatService: Нет чата и чужой чат неразличимы: 404 не раскрывает существование. """ - chat = await chat_repo.get_chat(store=self.store, chat_id=chat_id) + chat = await chat_repo.get_chat( + db_session=self.db_session, + chat_id=chat_id, + ) if chat is None or user_id not in chat.member_ids: raise exceptions.ChatNotFound return chat @@ -77,7 +88,7 @@ class ChatService: scope = user_chats_scope(user_id) after = decode_page_cursor(cursor, scope=scope) rows = await chat_repo.get_user_chats_page( - store=self.store, + db_session=self.db_session, user_id=user_id, after=after, limit=limit, diff --git a/src/core/services/message.py b/src/core/services/message.py index 77a1ce8e..f0ecb989 100644 --- a/src/core/services/message.py +++ b/src/core/services/message.py @@ -1,10 +1,11 @@ from uuid import UUID, uuid4 +from sqlalchemy.ext.asyncio import AsyncSession + from src.core.repos import message as message_repo from src.core.services.chat import ChatService from src.core.services.pagination import decode_page_cursor, split_page from src.infra.logger import AbstractLogger, get_logger -from src.infra.memory import MemoryStore from src.schemas import dataclasses from src.utils.cursor import chat_messages_scope from src.utils.utc import utcnow @@ -13,8 +14,8 @@ logger: AbstractLogger = get_logger().bind(module="message_service") class MessageService: - def __init__(self, store: MemoryStore) -> None: - self.store = store + def __init__(self, db_session: AsyncSession) -> None: + self.db_session = db_session async def send_message( self, @@ -24,8 +25,9 @@ class MessageService: text: str, ) -> dataclasses.MessageFullDTO: log = logger.bind(method="send_message", chat_id=chat_id) - # состав чата не меняется, поэтому проверка членства не устареет - await ChatService(store=self.store).get_chat_for_member( + # состав чата не меняется, поэтому проверка членства не устареет; + # составной внешний ключ сообщения — страховка на уровне БД + await ChatService(db_session=self.db_session).get_chat_for_member( chat_id=chat_id, user_id=sender_id, ) @@ -36,7 +38,11 @@ class MessageService: text=text, created_at=utcnow(), ) - await message_repo.insert_message(store=self.store, message=message) + await message_repo.insert_message( + db_session=self.db_session, + message=message, + ) + await self.db_session.commit() log.info( "Created message", message_id=message.id, @@ -52,14 +58,14 @@ class MessageService: limit: int, cursor: str | None, ) -> dataclasses.MessagePageDTO: - await ChatService(store=self.store).get_chat_for_member( + await ChatService(db_session=self.db_session).get_chat_for_member( chat_id=chat_id, user_id=user_id, ) scope = chat_messages_scope(chat_id) after = decode_page_cursor(cursor, scope=scope) rows = await message_repo.get_chat_messages_page( - store=self.store, + db_session=self.db_session, chat_id=chat_id, after=after, limit=limit, diff --git a/src/core/services/user.py b/src/core/services/user.py index 989dc7dc..83864893 100644 --- a/src/core/services/user.py +++ b/src/core/services/user.py @@ -1,9 +1,10 @@ from uuid import UUID, uuid4 +from sqlalchemy.ext.asyncio import AsyncSession + from src.core import exceptions from src.core.repos import user as user_repo from src.infra.logger import AbstractLogger, get_logger -from src.infra.memory import MemoryStore from src.schemas import dataclasses from src.utils.utc import utcnow @@ -11,8 +12,8 @@ logger: AbstractLogger = get_logger().bind(module="user_service") class UserService: - def __init__(self, store: MemoryStore) -> None: - self.store = store + def __init__(self, db_session: AsyncSession) -> None: + self.db_session = db_session async def register( self, @@ -27,10 +28,16 @@ class UserService: display_name=display_name, created_at=utcnow(), ) - created = await user_repo.insert_user(store=self.store, user=user) + # уникальность держит ограничение БД: гонка регистрации одного + # username даёт ровно одну строку, остальным — None + created = await user_repo.insert_user( + db_session=self.db_session, + user=user, + ) if created is None: log.info("Username is already taken") raise exceptions.UsernameTaken + await self.db_session.commit() log.info("Created user", created_user_id=created.id) return created @@ -50,7 +57,10 @@ class UserService: user_id = UUID(raw_user_id) except ValueError: raise exceptions.Unidentified from None - user = await user_repo.get_user(store=self.store, user_id=user_id) + user = await user_repo.get_user( + db_session=self.db_session, + user_id=user_id, + ) if user is None: raise exceptions.Unidentified return user diff --git a/src/infra/db/__init__.py b/src/infra/db/__init__.py new file mode 100644 index 00000000..ba3f9df3 --- /dev/null +++ b/src/infra/db/__init__.py @@ -0,0 +1,9 @@ +from src.infra.db.engine import create_engine, create_session_factory, ping +from src.infra.db.errors import is_db_unavailable + +__all__ = [ + "create_engine", + "create_session_factory", + "is_db_unavailable", + "ping", +] diff --git a/src/infra/db/engine.py b/src/infra/db/engine.py new file mode 100644 index 00000000..ddb5e840 --- /dev/null +++ b/src/infra/db/engine.py @@ -0,0 +1,75 @@ +"""Engine, фабрика сессий и проверка связи с PostgreSQL. + +Engine создаётся один раз в lifespan (`src/main.py`) и закрывается при +остановке; при импорте модуля соединений нет. +""" + +import asyncio + +import asyncpg +from sqlalchemy import text +from sqlalchemy.ext.asyncio import ( + AsyncEngine, + AsyncSession, + async_sessionmaker, + create_async_engine, +) + +from src.config.settings import Database +from src.utils.constants import DB_APPLICATION_NAME, DB_CLOSE_TIMEOUT_SECONDS + + +class BoundedCloseConnection(asyncpg.Connection): + """Соединение asyncpg, мягкое закрытие которого ограничено сроком. + + Прерванный запрос asyncpg отменяет и на сервере: открывает новое + соединение для CancelRequest и в `close()` ждёт его без срока. + SQLAlchemy при отмене задачи закрывает соединение мягко, поэтому + замёрзший Postgres держал бы запрос до разморозки. Здесь всё + закрытие ограничено: по истечении asyncpg обрывает соединение, а + SQLAlchemy переходит к принудительному закрытию. + """ + + async def close(self, *, timeout: float | None = None) -> None: + limit = timeout or DB_CLOSE_TIMEOUT_SECONDS + await asyncio.wait_for(super().close(timeout=timeout), limit) + + +def create_engine(database: Database) -> AsyncEngine: + """Engine с ограниченным пулом и таймаутами из `[database]`.""" + return create_async_engine( + database.url, + pool_size=database.pool_size, + max_overflow=database.max_overflow, + pool_timeout=database.pool_timeout_seconds, + # после рестарта Postgres соединения пула мертвы: проверка при + # выдаче не даёт первому запросу получить ошибку + pool_pre_ping=True, + # command_timeout asyncpg не задан: зависший сервер он не + # ограничивает (см. BoundedCloseConnection). Срок всей работы + # запроса с БД ставит asyncio в get_db_session + connect_args={ + "timeout": database.connect_timeout_seconds, + "connection_class": BoundedCloseConnection, + "server_settings": { + "application_name": DB_APPLICATION_NAME, + "statement_timeout": str(database.statement_timeout_ms), + }, + }, + ) + + +def create_session_factory( + engine: AsyncEngine, +) -> async_sessionmaker[AsyncSession]: + # после commit DTO уже собраны, перечитывать объекты незачем + return async_sessionmaker(engine, expire_on_commit=False) + + +async def ping(engine: AsyncEngine, *, timeout: float) -> None: + """`SELECT 1`; бросает исключение драйвера или `TimeoutError`. + + Соединение, прерванное сроком, SQLAlchemy сам не возвращает в пул. + """ + async with asyncio.timeout(timeout), engine.connect() as connection: + await connection.execute(text("SELECT 1")) diff --git a/src/infra/db/errors.py b/src/infra/db/errors.py new file mode 100644 index 00000000..4657d008 --- /dev/null +++ b/src/infra/db/errors.py @@ -0,0 +1,33 @@ +"""Какие ошибки драйвера означают «PostgreSQL недоступен» (→ 503). + +Классы проверены на SQLAlchemy 2.1.1 и asyncpg 0.31 (задача 5.1 change +`postgres-storage`, решение 6 его design): + +- Postgres остановлен — `ConnectionRefusedError`, его SQLAlchemy не + оборачивает; сервер не отвечает на подключение — `TimeoutError`; оба — + `OSError`, как и срок запроса из `get_db_session`; +- пул исчерпан — `sqlalchemy.exc.TimeoutError`; +- сработал `statement_timeout` — `DBAPIError` с SQLSTATE `57014`; +- соединение оборвано (рестарт, `pg_terminate_backend`) — `DBAPIError` + с `connection_invalidated`. + +Остальные `DBAPIError` (нарушение ограничения, синтаксис) — дефект +сервиса, им положен 500, а не 503. +""" + +from sqlalchemy import exc as sa_exc + +# класс 08 — ошибки соединения; 57014 — query_canceled (statement_timeout); +# 57P01–57P03 — сервер останавливается или ещё не принимает подключения +UNAVAILABLE_SQLSTATES = ("08", "57014", "57P01", "57P02", "57P03") + + +def is_db_unavailable(error: BaseException) -> bool: + if isinstance(error, OSError | sa_exc.TimeoutError): + return True + if isinstance(error, sa_exc.DBAPIError): + if error.connection_invalidated: + return True + sqlstate = getattr(error.orig, "sqlstate", None) or "" + return sqlstate.startswith(UNAVAILABLE_SQLSTATES) + return False diff --git a/src/infra/db/models/__init__.py b/src/infra/db/models/__init__.py new file mode 100644 index 00000000..d08d6230 --- /dev/null +++ b/src/infra/db/models/__init__.py @@ -0,0 +1,15 @@ +"""Модели БД. Новая модель импортируется здесь, иначе autogenerate её +не видит.""" + +from src.infra.db.models.base import Base +from src.infra.db.models.chat import Chat, ChatMember +from src.infra.db.models.message import Message +from src.infra.db.models.user import User + +__all__ = [ + "Base", + "Chat", + "ChatMember", + "Message", + "User", +] diff --git a/src/infra/db/models/base.py b/src/infra/db/models/base.py new file mode 100644 index 00000000..31b3a7c9 --- /dev/null +++ b/src/infra/db/models/base.py @@ -0,0 +1,30 @@ +"""Базовая модель: общий `created_at`, `to_dict()`, имена ограничений.""" + +from datetime import datetime +from typing import Any + +from sqlalchemy import DateTime, MetaData +from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column + +# имена ограничений по шаблону: downgrade снимает их по имени +NAMING_CONVENTION = { + "pk": "pk_%(table_name)s", + "fk": "fk_%(table_name)s_%(column_0_N_name)s_%(referred_table_name)s", + "uq": "uq_%(table_name)s_%(column_0_N_name)s", + "ix": "ix_%(table_name)s_%(column_0_N_name)s", + "ck": "ck_%(table_name)s_%(constraint_name)s", +} + + +class Base(DeclarativeBase): + metadata = MetaData(naming_convention=NAMING_CONVENTION) + + # время назначает сервис (utcnow), а не БД: порядок, который видит + # клиент, зависит от одних часов + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True)) + + def to_dict(self) -> dict[str, Any]: + return { + column.key: getattr(self, column.key) + for column in self.__table__.columns + } diff --git a/src/infra/db/models/chat.py b/src/infra/db/models/chat.py new file mode 100644 index 00000000..93b7ce5d --- /dev/null +++ b/src/infra/db/models/chat.py @@ -0,0 +1,55 @@ +from uuid import UUID + +from sqlalchemy import ( + CheckConstraint, + ForeignKey, + Index, + SmallInteger, + Text, + UniqueConstraint, +) +from sqlalchemy.orm import Mapped, mapped_column + +from src.infra.db.models.base import Base +from src.utils.constants import CHAT_TITLE_MAX_LENGTH, CHAT_TITLE_MIN_LENGTH + + +class Chat(Base): + __tablename__ = "chats" + __table_args__ = ( + CheckConstraint( + "char_length(title) BETWEEN " + f"{CHAT_TITLE_MIN_LENGTH} AND {CHAT_TITLE_MAX_LENGTH}", + name="title_length", + ), + ) + + id: Mapped[UUID] = mapped_column(primary_key=True) + title: Mapped[str] = mapped_column(Text) + + +class ChatMember(Base): + """Участник чата. + + `position` — место в `member_ids` из запроса: контракт отдаёт их в + порядке создания. `created_at` — копия времени создания чата: по ней + список чатов пользователя идёт keyset-ом по индексу, без сортировки + всех его чатов. + """ + + __tablename__ = "chat_members" + __table_args__ = ( + UniqueConstraint("chat_id", "position"), + CheckConstraint("position >= 0", name="position_non_negative"), + Index(None, "user_id", "created_at", "chat_id"), + ) + + chat_id: Mapped[UUID] = mapped_column( + ForeignKey("chats.id"), + primary_key=True, + ) + user_id: Mapped[UUID] = mapped_column( + ForeignKey("users.id"), + primary_key=True, + ) + position: Mapped[int] = mapped_column(SmallInteger) diff --git a/src/infra/db/models/message.py b/src/infra/db/models/message.py new file mode 100644 index 00000000..d54fa559 --- /dev/null +++ b/src/infra/db/models/message.py @@ -0,0 +1,33 @@ +from uuid import UUID + +from sqlalchemy import CheckConstraint, ForeignKeyConstraint, Index, Text +from sqlalchemy.orm import Mapped, mapped_column + +from src.infra.db.models.base import Base +from src.utils.constants import ( + MESSAGE_TEXT_MAX_LENGTH, + MESSAGE_TEXT_MIN_LENGTH, +) + + +class Message(Base): + __tablename__ = "messages" + __table_args__ = ( + # отправитель — участник этого чата: проверяет сама БД + ForeignKeyConstraint( + ["chat_id", "sender_id"], + ["chat_members.chat_id", "chat_members.user_id"], + ), + CheckConstraint( + "char_length(text) BETWEEN " + f"{MESSAGE_TEXT_MIN_LENGTH} AND {MESSAGE_TEXT_MAX_LENGTH}", + name="text_length", + ), + # keyset истории: WHERE chat_id = ... AND (created_at, id) > (...) + Index(None, "chat_id", "created_at", "id"), + ) + + id: Mapped[UUID] = mapped_column(primary_key=True) + chat_id: Mapped[UUID] + sender_id: Mapped[UUID] + text: Mapped[str] = mapped_column(Text) diff --git a/src/infra/db/models/user.py b/src/infra/db/models/user.py new file mode 100644 index 00000000..4b142ed9 --- /dev/null +++ b/src/infra/db/models/user.py @@ -0,0 +1,32 @@ +from uuid import UUID + +from sqlalchemy import CheckConstraint, Text, UniqueConstraint +from sqlalchemy.orm import Mapped, mapped_column + +from src.infra.db.models.base import Base +from src.utils.constants import ( + DISPLAY_NAME_MAX_LENGTH, + DISPLAY_NAME_MIN_LENGTH, + USERNAME_PATTERN, +) + + +class User(Base): + __tablename__ = "users" + __table_args__ = ( + UniqueConstraint("username"), + # CHECK дублируют контракт: первым отвечает API (400) + CheckConstraint( + f"username ~ '{USERNAME_PATTERN}'", + name="username_format", + ), + CheckConstraint( + "char_length(display_name) BETWEEN " + f"{DISPLAY_NAME_MIN_LENGTH} AND {DISPLAY_NAME_MAX_LENGTH}", + name="display_name_length", + ), + ) + + id: Mapped[UUID] = mapped_column(primary_key=True) + username: Mapped[str] = mapped_column(Text) + display_name: Mapped[str] = mapped_column(Text) diff --git a/src/infra/logger.py b/src/infra/logger.py index 7ca7ba82..fbc1ee6d 100644 --- a/src/infra/logger.py +++ b/src/infra/logger.py @@ -177,6 +177,12 @@ def configure_logger() -> None: "handlers": [], "propagate": False, }, + # сервис миграций: «Running upgrade ...» видны в журнале + "alembic": { + "level": "INFO", + "handlers": ["json"], + "propagate": False, + }, }, }, ) diff --git a/src/infra/memory.py b/src/infra/memory.py deleted file mode 100644 index 5fb06d60..00000000 --- a/src/infra/memory.py +++ /dev/null @@ -1,35 +0,0 @@ -"""Хранилище лабы 1: состояние в памяти одного процесса. - -Инвариант атомарности: repo-функции меняют и читают `MemoryStore` без -единого `await` внутри. Все ручки — `async def`, worker один, event loop -один, поэтому такую функцию не прерывает другой запрос, и составная -операция (проверка уникальности + вставка) атомарна без блокировок. -Добавить `await` в repo-функцию — значит сломать защиту от гонок. - -Меняют хранилище только repo-функции (`src/core/repos/`). Записи — -frozen DTO: их отдают наружу без копирования. После рестарта процесса -состояние пустое — так задумано на лабе 1. -""" - -from dataclasses import dataclass, field -from uuid import UUID - -from src.schemas import dataclasses - - -@dataclass(slots=True) -class MemoryStore: - # user_id → пользователь - users: dict[UUID, dataclasses.UserFullDTO] = field(default_factory=dict) - # username → user_id владельца; уникальность username - user_id_by_username: dict[str, UUID] = field(default_factory=dict) - # chat_id → чат - chats: dict[UUID, dataclasses.ChatFullDTO] = field(default_factory=dict) - # user_id участника → его чаты по (created_at, chat_id) - chats_by_user: dict[UUID, list[dataclasses.ChatFullDTO]] = field( - default_factory=dict, - ) - # chat_id → сообщения этого чата по (created_at, message_id) - messages_by_chat: dict[UUID, list[dataclasses.MessageFullDTO]] = field( - default_factory=dict, - ) diff --git a/src/main.py b/src/main.py index 86b7659e..cc128157 100644 --- a/src/main.py +++ b/src/main.py @@ -8,8 +8,8 @@ from src.api import errors from src.api.middlewares import RequestContextMiddleware from src.api.routers import health_router, v1_router from src.config import settings +from src.infra.db import create_engine, create_session_factory from src.infra.logger import AbstractLogger, get_logger -from src.infra.memory import MemoryStore from src.schemas.enums import RunModeEnum logger: AbstractLogger = get_logger().bind(module="startup") @@ -17,17 +17,27 @@ logger: AbstractLogger = get_logger().bind(module="startup") @asynccontextmanager async def lifespan(app: FastAPI) -> AsyncIterator[None]: - # состояние лабы 1: живёт до остановки процесса - app.state.store = MemoryStore() + database = settings.database + # engine не подключается при создании: без Postgres сервис стартует, + # а /health/ready отвечает 503 + engine = create_engine(database) + app.state.engine = engine + app.state.session_factory = create_session_factory(engine) + if not database.password.get_secret_value(): + logger.warning("Database password is empty") logger.info( "Started API", host=settings.app.host, port=settings.app.port, run_mode=settings.app.run_mode, + database_host=database.host, + database_port=database.port, + database_name=database.name, ) try: yield finally: + await engine.dispose() logger.info("Stopped API") @@ -52,8 +62,8 @@ def main() -> None: reload=reload, # без reload uvicorn пишет warning на reload_dirs при каждом старте reload_dirs=["src"] if reload else None, - # один процесс: состояние лабы 1 в памяти, второй worker = второе - # независимое состояние + # один процесс: реплики — лаба 3, пул соединений рассчитан на один + # процесс workers=1, timeout_graceful_shutdown=settings.app.graceful_shutdown_seconds, # логи uvicorn идут через наш JSON-форматтер (src/infra/logger.py) diff --git a/src/utils/constants.py b/src/utils/constants.py index d1bf3949..5637bbaf 100644 --- a/src/utils/constants.py +++ b/src/utils/constants.py @@ -33,3 +33,12 @@ MESSAGE_TEXT_MAX_LENGTH = 4000 PAGE_LIMIT_MIN = 1 PAGE_LIMIT_MAX = 100 PAGE_LIMIT_DEFAULT = 50 + +# база данных +# имя соединений сервиса в pg_stat_activity +DB_APPLICATION_NAME = "mtusi-messenger" +# секунды на проверку Postgres в /health/ready +READINESS_DB_TIMEOUT_SECONDS = 2 +# секунды на мягкое закрытие соединения, если SQLAlchemy не передал свой +# срок; дальше соединение обрывается +DB_CLOSE_TIMEOUT_SECONDS = 2 diff --git a/student-tests/run_isolated.py b/student-tests/run_isolated.py new file mode 100644 index 00000000..0b0b575f --- /dev/null +++ b/student-tests/run_isolated.py @@ -0,0 +1,224 @@ +"""`make test_isolated`: образ на временной базе `test_`. + +Создаёт базу в Postgres стенда, накатывает на неё миграции сервисом +`migrate`, поднимает отдельный контейнер `api` из определения compose с +подменой только `DATABASE__NAME`, прогоняет `make test` и +`make student_test`, затем удаляет контейнер и базу — при любом исходе, +в том числе по Ctrl+C. Рабочая база и рабочий контейнер API не +трогаются. Только stdlib: всё через docker compose и make. Решение 12 +design change `postgres-storage`. +""" + +import argparse +import json +import re +import subprocess +import sys +import time +import urllib.error +import urllib.request +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +ENV_FILE = ROOT / ".env" +DB_NAME_RE = re.compile(r"^[a-z0-9_]+$") +READY_TIMEOUT_S = 60 +LOG_TAIL_LINES = 50 + + +def say(message: str) -> None: + print(f"[test_isolated] {message}", flush=True) + + +def run( + *args: str, + check: bool = True, + stdin: str | None = None, + quiet: bool = False, +) -> subprocess.CompletedProcess[str]: + """Команда из корня репозитория; вывод — в терминал, если не quiet.""" + return subprocess.run( + args, + cwd=ROOT, + check=check, + input=stdin, + text=True, + capture_output=quiet, + ) + + +def read_env() -> dict[str, str]: + """`KEY=VALUE` из `.env`; подстановок `${...}` нужные ключи не имеют.""" + values: dict[str, str] = {} + for line in ENV_FILE.read_text(encoding="utf-8").splitlines(): + line = line.strip() + if not line or line.startswith("#") or "=" not in line: + continue + key, value = line.split("=", 1) + values[key.strip()] = value.strip() + return values + + +def compose_project() -> str: + config = run( + "docker", + "compose", + "config", + "--format", + "json", + quiet=True, + ) + return json.loads(config.stdout)["name"] + + +def psql(sql: str) -> None: + """SQL в служебной базе `postgres` под `POSTGRES_USER` контейнера.""" + run( + "docker", + "compose", + "exec", + "-T", + "postgres", + "sh", + "-c", + 'exec psql -U "$POSTGRES_USER" -d postgres -v ON_ERROR_STOP=1 -X -q', + stdin=sql, + ) + + +def drop_database(name: str) -> None: + # WITH (FORCE) рвёт оставшиеся соединения, если контейнер не ушёл + psql(f'DROP DATABASE IF EXISTS "{name}" WITH (FORCE);\n') + + +def remove_container(name: str) -> None: + run("docker", "rm", "-f", name, check=False, quiet=True) + + +def wait_ready(url: str, container: str) -> None: + deadline = time.monotonic() + READY_TIMEOUT_S + while time.monotonic() < deadline: + try: + with urllib.request.urlopen(url, timeout=2) as response: + if response.status == 200: + return + except (urllib.error.URLError, OSError): + pass + state = run( + "docker", + "inspect", + "-f", + "{{.State.Running}}", + container, + check=False, + quiet=True, + ) + if state.stdout.strip() != "true": + raise RuntimeError(f"container {container} is not running") + time.sleep(1) + raise RuntimeError(f"{url} not ready in {READY_TIMEOUT_S}s") + + +def main() -> int: + parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) + parser.add_argument( + "--keep-db", + action="store_true", + help="не удалять базу после прогона (KEEP_TEST_DB=1)", + ) + args = parser.parse_args() + + env = read_env() + test_db = f"test_{env['POSTGRES_DB']}" + if not DB_NAME_RE.fullmatch(test_db): + say(f"unsupported database name: {test_db}") + return 2 + port = env["TEST_APP_PORT"] + app_port = env.get("APP__PORT", "8080") + container = f"{compose_project()}-test-api" + base_url = f"http://127.0.0.1:{port}" + + say(f"database={test_db} container={container} base_url={base_url}") + remove_container(container) + drop_database(test_db) + + results: dict[str, int] = {} + failed = True + try: + say("build image") + run("docker", "compose", "build", "api") + say(f"create database {test_db}") + psql(f'CREATE DATABASE "{test_db}";\n') + say("migrations") + run( + "docker", + "compose", + "run", + "--rm", + "--no-deps", + "-e", + f"DATABASE__NAME={test_db}", + "migrate", + ) + say("start api container") + run( + "docker", + "compose", + "run", + "-d", + "--no-deps", + "--name", + container, + "-e", + f"DATABASE__NAME={test_db}", + "-p", + f"127.0.0.1:{port}:{app_port}", + "api", + quiet=True, + ) + wait_ready(f"{base_url}/health/ready", container) + say("ready") + for target in ("test", "student_test"): + say(f"make {target}") + results[target] = run( + "make", + target, + f"BASE_URL={base_url}", + check=False, + ).returncode + failed = any(results.values()) + except KeyboardInterrupt: + say("interrupted") + results["interrupted"] = 130 + except (subprocess.CalledProcessError, RuntimeError) as e: + say(f"setup failed: {e}") + results["setup"] = 1 + finally: + if failed: + say(f"last {LOG_TAIL_LINES} lines of {container}") + run( + "docker", + "logs", + "--tail", + str(LOG_TAIL_LINES), + container, + check=False, + ) + say("cleanup") + run("docker", "stop", container, check=False, quiet=True) + remove_container(container) + try: + if args.keep_db: + say(f"kept database {test_db}") + else: + drop_database(test_db) + except subprocess.CalledProcessError as e: + say(f"cleanup failed: {e}") + results["cleanup"] = 1 + + say(f"results: {results}") + return next((code for code in results.values() if code), 0) + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/uv.lock b/uv.lock index e3fa2a68..c35a9703 100644 --- a/uv.lock +++ b/uv.lock @@ -11,6 +11,20 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/72/15/504337e302d070bd2ff2f39418bb17d2ad73c662c403a4f37cb4e5c5b237/agent_detector-2.0.0-py3-none-any.whl", hash = "sha256:22c6a1c9c23894a12f55aea625f060b8d3330fba774de72d02d5442bb580417f", size = 9352, upload-time = "2026-09-02T14:19:50.971Z" }, ] +[[package]] +name = "alembic" +version = "1.20.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "mako" }, + { name = "sqlalchemy" }, + { name = "typing-extensions" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/ed/aa/02910bdb8e2f1444f6654d5b296cd827d126f82209050ee7b1000f92ac4b/alembic-1.20.0.tar.gz", hash = "sha256:db505480647bc60386c5369402f4a57a506b7539c9e9ef5e270d45cbbe4939bf", size = 2093272, upload-time = "2026-09-11T19:09:11.126Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/3f/27/78a89b55b0904d222183164e079b4ca56208e94eff1d35ad1f1ad5be9b06/alembic-1.20.0-py3-none-any.whl", hash = "sha256:77eb101048d95f982c0353e9233404889dcd7a6fc244c107836c0e2fc9cf7d9d", size = 268719, upload-time = "2026-09-11T19:09:12.88Z" }, +] + [[package]] name = "annotated-doc" version = "0.0.5" @@ -42,6 +56,22 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/12/b8/4bd346e22b28902df4d651910f5242c28d84e4a5c2435ca5c3f797ed7e2e/anyio-4.15.1-py3-none-any.whl", hash = "sha256:6152fdbbf9a77fdec97731721bebf7c4c44f7c29b424b0065826173efc7ed101", size = 132079, upload-time = "2026-09-05T10:42:37.923Z" }, ] +[[package]] +name = "asyncpg" +version = "0.31.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/fe/cc/d18065ce2380d80b1bcce927c24a2642efd38918e33fd724bc4bca904877/asyncpg-0.31.0.tar.gz", hash = "sha256:c989386c83940bfbd787180f2b1519415e2d3d6277a70d9d0f0145ac73500735", size = 993667, upload-time = "2025-11-24T23:27:00.812Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/2a/a6/59d0a146e61d20e18db7396583242e32e0f120693b67a8de43f1557033e2/asyncpg-0.31.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:b44c31e1efc1c15188ef183f287c728e2046abb1d26af4d20858215d50d91fad", size = 662042, upload-time = "2025-11-24T23:25:49.578Z" }, + { url = "https://files.pythonhosted.org/packages/36/01/ffaa189dcb63a2471720615e60185c3f6327716fdc0fc04334436fbb7c65/asyncpg-0.31.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:0c89ccf741c067614c9b5fc7f1fc6f3b61ab05ae4aaa966e6fd6b93097c7d20d", size = 638504, upload-time = "2025-11-24T23:25:51.501Z" }, + { url = "https://files.pythonhosted.org/packages/9f/62/3f699ba45d8bd24c5d65392190d19656d74ff0185f42e19d0bbd973bb371/asyncpg-0.31.0-cp312-cp312-manylinux_2_28_aarch64.whl", hash = "sha256:12b3b2e39dc5470abd5e98c8d3373e4b1d1234d9fbdedf538798b2c13c64460a", size = 3426241, upload-time = "2025-11-24T23:25:53.278Z" }, + { url = "https://files.pythonhosted.org/packages/8c/d1/a867c2150f9c6e7af6462637f613ba67f78a314b00db220cd26ff559d532/asyncpg-0.31.0-cp312-cp312-manylinux_2_28_x86_64.whl", hash = "sha256:aad7a33913fb8bcb5454313377cc330fbb19a0cd5faa7272407d8a0c4257b671", size = 3520321, upload-time = "2025-11-24T23:25:54.982Z" }, + { url = "https://files.pythonhosted.org/packages/7a/1a/cce4c3f246805ecd285a3591222a2611141f1669d002163abef999b60f98/asyncpg-0.31.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:3df118d94f46d85b2e434fd62c84cb66d5834d5a890725fe625f498e72e4d5ec", size = 3316685, upload-time = "2025-11-24T23:25:57.43Z" }, + { url = "https://files.pythonhosted.org/packages/40/ae/0fc961179e78cc579e138fad6eb580448ecae64908f95b8cb8ee2f241f67/asyncpg-0.31.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:bd5b6efff3c17c3202d4b37189969acf8927438a238c6257f66be3c426beba20", size = 3471858, upload-time = "2025-11-24T23:25:59.636Z" }, + { url = "https://files.pythonhosted.org/packages/52/b2/b20e09670be031afa4cbfabd645caece7f85ec62d69c312239de568e058e/asyncpg-0.31.0-cp312-cp312-win32.whl", hash = "sha256:027eaa61361ec735926566f995d959ade4796f6a49d3bde17e5134b9964f9ba8", size = 527852, upload-time = "2025-11-24T23:26:01.084Z" }, + { url = "https://files.pythonhosted.org/packages/b5/f0/f2ed1de154e15b107dc692262395b3c17fc34eafe2a78fc2115931561730/asyncpg-0.31.0-cp312-cp312-win_amd64.whl", hash = "sha256:72d6bdcbc93d608a1158f17932de2321f68b1a967a13e014998db87a72ed3186", size = 597175, upload-time = "2025-11-24T23:26:02.564Z" }, +] + [[package]] name = "attrs" version = "26.1.0" @@ -294,6 +324,24 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/7a/6d/db8b86e168fef0cf904737e275bccb683558088ef971e92d3b41ce980699/filelock-4.0.3-py3-none-any.whl", hash = "sha256:30cd166e2aee2c7534ce2c33c6367c4cd051b8368e20e2c4eb0c34f699bacfab", size = 108444, upload-time = "2026-09-23T23:40:20.819Z" }, ] +[[package]] +name = "greenlet" +version = "3.5.6" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/3e/6e/0091f175ccd02b02bc8811bbcbcc6ac2e980be116e3b2f7a736ca322bf84/greenlet-3.5.6.tar.gz", hash = "sha256:8e67c43bdfc88d5fee6db0d3e40175b362fc95fb85f0412d233b9b203c53a575", size = 207653, upload-time = "2026-09-14T15:42:51.806Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/72/18/3fc6d951466ae9a2a688edcddde3b2e388da0a8244e0caf7117bbeb0eb95/greenlet-3.5.6-cp312-cp312-macosx_11_0_universal2.whl", hash = "sha256:a5876d0a60355af98d535c47f6cd6eb0f8a432396dab26845d380b92f8412422", size = 295668, upload-time = "2026-09-14T14:22:33.241Z" }, + { url = "https://files.pythonhosted.org/packages/27/89/366d2af5061eeefa5012f510d95a99c8620dcc457609838db4d538820318/greenlet-3.5.6-cp312-cp312-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:e85880b538e59a59f55117b81f208a6660ad5ac328aad9305f812d9b8bc67a0f", size = 611700, upload-time = "2026-09-14T15:12:01.962Z" }, + { url = "https://files.pythonhosted.org/packages/54/1c/07f133f865fd58ae593dd2bbec3144acaee9b04ffe2eb48c6e121747ceef/greenlet-3.5.6-cp312-cp312-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:f0ba7c2a329d650628f4c8572fd1db29f0a59dd70a3e3e0710dcf18a35cce9d8", size = 624223, upload-time = "2026-09-14T15:20:42.459Z" }, + { url = "https://files.pythonhosted.org/packages/a7/f2/844dc823ff2752ad049caa6b59d57e4572f9c445934b02d3518f4c67197c/greenlet-3.5.6-cp312-cp312-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:ee7d9da3bf493909cf811a3f038840cb34fab5ae2956b8a263919f6e289ab188", size = 629529, upload-time = "2026-09-14T15:25:06.354Z" }, + { url = "https://files.pythonhosted.org/packages/66/6a/1594f3869c57c149abdb380492529e04d4c0229b5e4d79572c5bd0aaa673/greenlet-3.5.6-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:975736b002ed080d124cf81a79cb7e05cb26d6b3f5c7a7b651c0fcce70353aa1", size = 621404, upload-time = "2026-09-14T14:35:59.027Z" }, + { url = "https://files.pythonhosted.org/packages/c0/42/b1f8dbc89a53b9e77859fc1ad1627d106fc361daa3ea4bdf43a91ebb4338/greenlet-3.5.6-cp312-cp312-manylinux_2_39_riscv64.whl", hash = "sha256:71890d5247020c25c21a6b65202782bfc281d4e6e244842419d30e3492bb6dcc", size = 432385, upload-time = "2026-09-14T15:28:37.369Z" }, + { url = "https://files.pythonhosted.org/packages/a2/f5/33e5c9e48178b9259fd000f8f45caa4a65036f65d3d0c06a602f570f025d/greenlet-3.5.6-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:0616b8f878098c5681fd8f0dc92d887551717402342a70f0abcbfea5f5ad8a44", size = 1584998, upload-time = "2026-09-14T15:10:06.653Z" }, + { url = "https://files.pythonhosted.org/packages/ef/31/9b4e140bc24d0ad7927ebd651f5608b0acc2334d061748c3b6ad19085cfa/greenlet-3.5.6-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:3dbb4596a6a4e5d47121a33ff20533a81e60f302d9e67b69909a8bc21a43f0a7", size = 1647568, upload-time = "2026-09-14T14:35:49.787Z" }, + { url = "https://files.pythonhosted.org/packages/c3/71/d79f1791f824f8ff15c2978746640467ae932a2365e0201069f7f272395f/greenlet-3.5.6-cp312-cp312-win_amd64.whl", hash = "sha256:7ac4abb3877c43af320392c664774eef6fa2cc063c79a55fc02d844a3cbe7395", size = 324203, upload-time = "2026-09-14T14:22:54.504Z" }, + { url = "https://files.pythonhosted.org/packages/63/af/42aca4d56e8cb321912203069d8d34734cb288222f10ad2ae102718cc577/greenlet-3.5.6-cp312-cp312-win_arm64.whl", hash = "sha256:301102a49120b095e72a7838792b41233975fc1c155daec6d98f81c00c9280e0", size = 308310, upload-time = "2026-09-14T14:24:03.008Z" }, +] + [[package]] name = "h11" version = "0.16.0" @@ -450,6 +498,18 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/5d/aa/f02be9bbfb270e13ee608c2b28b8771f20a5f64356c6d9317b20043c6129/lazy_object_proxy-1.12.0-cp312-cp312-win_amd64.whl", hash = "sha256:53c7fd99eb156bbb82cbc5d5188891d8fdd805ba6c1e3b92b90092da2a837073", size = 26563, upload-time = "2025-08-22T13:42:43.685Z" }, ] +[[package]] +name = "mako" +version = "1.4.3" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "markupsafe" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/5a/09/e07c4b5579a79f4b16f8d4f29f6c54514ac787c4ad506b8c4f28a0e6b0bf/mako-1.4.3.tar.gz", hash = "sha256:cd6537fe88d5fec315c55c2f8529bc4ce7a9a352ad7db3eeaa6a66e2dd4ec37a", size = 412799, upload-time = "2026-09-22T20:54:31.509Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/6d/a0/053d6af3e8f871e0073b4a36732d9e65be77a72e5434c31b94f6af78a6bb/mako-1.4.3-py3-none-any.whl", hash = "sha256:723296007c870bfd6b3f0c3230dba7198096e5269297ebf5e4eff9e7ffa39d4f", size = 80164, upload-time = "2026-09-22T20:54:33.128Z" }, +] + [[package]] name = "markdown-it-py" version = "4.2.0" @@ -495,9 +555,12 @@ name = "mtusi-messenger" version = "0.1.0" source = { editable = "." } dependencies = [ + { name = "alembic" }, + { name = "asyncpg" }, { name = "fastapi", extra = ["all"] }, { name = "pydantic" }, { name = "pydantic-settings" }, + { name = "sqlalchemy", extra = ["asyncio"] }, { name = "structlog" }, { name = "uvicorn" }, ] @@ -519,10 +582,13 @@ dev = [ [package.metadata] requires-dist = [ + { name = "alembic", specifier = ">=1.20.0,<2" }, + { name = "asyncpg", specifier = ">=0.31.0,<0.32" }, { name = "fastapi", extras = ["all"], specifier = ">=0.137.2,<1.0.0" }, { name = "pydantic", specifier = ">=2.6.3,<3.0.0" }, { name = "pydantic-settings", specifier = ">=2.15.0,<3.0.0" }, { name = "ruff", marker = "extra == 'dev'", specifier = ">=0.11.13,<1.0.0" }, + { name = "sqlalchemy", extras = ["asyncio"], specifier = ">=2.1.1,<2.2" }, { name = "structlog", specifier = ">=24.1.0,<25.0.0" }, { name = "uvicorn", specifier = ">=0.29.0,<1.0.0" }, ] @@ -981,6 +1047,33 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/b7/ce/149a00dd41f10bc29e5921b496af8b574d8413afcd5e30dfa0ed46c2cc5e/six-1.17.0-py2.py3-none-any.whl", hash = "sha256:4721f391ed90541fddacab5acf947aa0d3dc7d27b2e1e8eda2be8970586c3274", size = 11050, upload-time = "2024-12-04T17:35:26.475Z" }, ] +[[package]] +name = "sqlalchemy" +version = "2.1.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "typing-extensions" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/a8/cb/7c68da82239ffae9378eca076afe14c310e17a4f01e3d315112f266e26c7/sqlalchemy-2.1.1.tar.gz", hash = "sha256:fcf3cbb33bb23bad75d2150157c21804618745731e9931ab27e61879a9f6123b", size = 10503203, upload-time = "2026-09-25T14:59:00.117Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/c8/44/950ac8e093784fdd5fd4fc385d110e0cf1d1d2bae781dc7be659bf3e7af3/sqlalchemy-2.1.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:1abf1acecd4d0fc34d4ab7e9cda9e849ce95b647e1a5f76db7d2a5a0bea4e1e5", size = 2458475, upload-time = "2026-09-25T15:17:05.018Z" }, + { url = "https://files.pythonhosted.org/packages/20/13/ade5c1da6221e865a57ee45132a3c61528bb244d7b22ddbbddd589989754/sqlalchemy-2.1.1-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:61333b2f806f64a08a1edf0b0e4271905f73c1f7e525c23da7a491f74c109835", size = 4653012, upload-time = "2026-09-25T15:25:47.467Z" }, + { url = "https://files.pythonhosted.org/packages/b2/95/37b6846549a76c69beca71974905446130d78bddd88a4414b5b88c88af16/sqlalchemy-2.1.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0fad3dc37851b096ef72538b18152a5c1ae9c8b2013cd89f51eca83fc6eba36b", size = 4701803, upload-time = "2026-09-25T15:25:55.644Z" }, + { url = "https://files.pythonhosted.org/packages/57/88/abdc1ce5daa0af77c5d27183625ab7bb1155de41067fd77db4fb1cdc9616/sqlalchemy-2.1.1-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:8a3126c1203cdfc0f00884f9e8dbe95307b813f883ee9d9691983a563ebc96f8", size = 4351745, upload-time = "2026-09-25T15:31:43.337Z" }, + { url = "https://files.pythonhosted.org/packages/7b/28/4375244fc658c95033593429bc6dfc61df96beb9b64c8bf57821fdebf85d/sqlalchemy-2.1.1-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:f90e517b2eb9c4c40fcc978c8c242789fa6cb0064c501fd8c1515145ed5fe23d", size = 4576898, upload-time = "2026-09-25T15:25:49.478Z" }, + { url = "https://files.pythonhosted.org/packages/4e/ce/0aa3c294150a7a018e61af42462cf299022ad71b4b94384be36fff6ec567/sqlalchemy-2.1.1-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:054a2c2b6cbe3ca7cb88aba9c5e2ecdbfc43656bea22326a41d09e5398c86ec4", size = 4346156, upload-time = "2026-09-25T15:31:45.624Z" }, + { url = "https://files.pythonhosted.org/packages/bd/17/cf00fdbcdd8f1933aa4b33d499218a8d470ec9fd935a2f33ec55dcef4fdc/sqlalchemy-2.1.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:ea049f3e2702967414bc79f58a484dab191359267726607e6c1579a09ef93788", size = 4650545, upload-time = "2026-09-25T15:25:57.819Z" }, + { url = "https://files.pythonhosted.org/packages/48/9b/8b4a17884e2b286d5f89e3b93bc2be928c6d86d7bfeadf9ae4459d64c244/sqlalchemy-2.1.1-cp312-cp312-win32.whl", hash = "sha256:842a5c00ca9719cc26fba6f401f70e4bac19dc8cc4dc36350803a03954d6aea2", size = 2369166, upload-time = "2026-09-25T15:36:05.081Z" }, + { url = "https://files.pythonhosted.org/packages/ed/5a/c91c3cf7f0e65ae7ad9ebc87ec4cc68f6d163fddaa36736621a00dac5905/sqlalchemy-2.1.1-cp312-cp312-win_amd64.whl", hash = "sha256:0220e0d1d1ad2391a03cd6713ca5d795419033cc40baa1233f9ad454dffa25e6", size = 2421474, upload-time = "2026-09-25T15:36:07.069Z" }, + { url = "https://files.pythonhosted.org/packages/e3/65/fc72cd55397792553b72a8c43e14531baa436d08f832486d2cff9e806f36/sqlalchemy-2.1.1-cp312-cp312-win_arm64.whl", hash = "sha256:af189bd861bd31a84f0ba244d6db0c8aeae9e56448c9001bf02ee6a93758b39e", size = 2381060, upload-time = "2026-09-25T15:11:45.018Z" }, + { url = "https://files.pythonhosted.org/packages/c5/7a/7d1879d78c086737acee5f3250cbff9d285e5bd7cb6bc2c730f24e8d400e/sqlalchemy-2.1.1-py3-none-any.whl", hash = "sha256:4357c1a222e141662251a59d3702f9b124294941171dfa6bd570513e9f4905ee", size = 2047471, upload-time = "2026-09-25T15:20:37.797Z" }, +] + +[package.optional-dependencies] +asyncio = [ + { name = "greenlet" }, +] + [[package]] name = "starlette" version = "1.7.0"