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 <noreply@anthropic.com>
This commit is contained in:
2026-10-01 15:33:49 +03:00
co-authored by Claude Opus 5.5
parent 93b699a478
commit 4921afa39d
47 changed files with 2648 additions and 169 deletions
+31 -4
View File
@@ -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
+5 -1
View File
@@ -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
+53 -17
View File
@@ -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_<POSTGRES_DB>: сборка, миграции, отдельный
# контейнер 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 .
+13
View File
@@ -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-<rev>_<slug>.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
+1 -1
View File
@@ -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
+14
View File
@@ -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
+80 -13
View File
@@ -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:
+68
View File
@@ -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())
+27
View File
@@ -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"}
@@ -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")
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-10-01
+465
View File
@@ -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_<db>" WITH (FORCE)
1. docker compose build api
2. CREATE DATABASE "test_<db>"
3. docker compose run --rm --no-deps -e DATABASE__NAME=test_<db> migrate
4. docker compose run -d --no-deps --name <тестовый контейнер>
-e DATABASE__NAME=test_<db>
-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_<db>" 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`: это настройки, спеки и план от них не зависят.
@@ -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_<db>` в
том же 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/`.
@@ -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** миграции применяются без доступа к исходникам на хосте
@@ -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`.
@@ -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.
@@ -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
@@ -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
@@ -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 и видят одни и
те же данные
@@ -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_<db>`, ни
тестового контейнера после команды нет, число строк в таблицах
рабочей базы не изменилось, а рабочий API продолжает отвечать
#### Scenario: Упавшие тесты
- **WHEN** во время `make test_isolated` падает хотя бы один тест
- **THEN** код выхода ненулевой, журнал тестового контейнера выведен,
контейнер удалён, база `test_<db>` удалена
#### Scenario: Прерывание
- **WHEN** `make test_isolated` прерван Ctrl+C
- **THEN** тестовый контейнер остановлен и удалён, база `test_<db>`
удалена
#### Scenario: Хвост прошлого прогона
- **WHEN** тестовый контейнер или база `test_<db>` остались от прогона,
убитого без уборки
- **THEN** следующий `make test_isolated` удаляет их и начинает заново
#### Scenario: Сохранить базу для разбора
- **WHEN** выполнен `make test_isolated KEEP_TEST_DB=1`
- **THEN** после прогона тестовый контейнер удалён, база `test_<db>`
остаётся, а команда печатает её имя
+210
View File
@@ -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_<db>` (`\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 .`.
Проверка: все команды без ошибок.
+6 -1
View File
@@ -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]
+16
View File
@@ -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
+67 -15
View File
@@ -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)]
+3 -3
View File
@@ -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")
+42 -1
View File
@@ -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(
+3 -2
View File
@@ -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"
+84 -22
View File
@@ -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]
+31 -17
View File
@@ -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]
+28 -12
View File
@@ -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())
+18 -7
View File
@@ -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,
+14 -8
View File
@@ -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,
+15 -5
View File
@@ -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
+9
View File
@@ -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",
]
+75
View File
@@ -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"))
+33
View File
@@ -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
+15
View File
@@ -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",
]
+30
View File
@@ -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
}
+55
View File
@@ -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)
+33
View File
@@ -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)
+32
View File
@@ -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)
+6
View File
@@ -177,6 +177,12 @@ def configure_logger() -> None:
"handlers": [],
"propagate": False,
},
# сервис миграций: «Running upgrade ...» видны в журнале
"alembic": {
"level": "INFO",
"handlers": ["json"],
"propagate": False,
},
},
},
)
-35
View File
@@ -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,
)
+15 -5
View File
@@ -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)
+9
View File
@@ -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
+224
View File
@@ -0,0 +1,224 @@
"""`make test_isolated`: образ на временной базе `test_<db>`.
Создаёт базу в 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())
Generated
+93
View File
@@ -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"