feat: add replicated messenger and reproducible lab3 stand

This commit is contained in:
2026-10-15 13:43:39 +03:00
parent 0ab3a341aa
commit 84dd7fec0a
106 changed files with 17235 additions and 24 deletions
+210
View File
@@ -0,0 +1,210 @@
# src/ — устройство приложения
Дополняет корневой `AGENTS.md`. Правила конкретных слоёв — в
`api/AGENTS.md`, `services/AGENTS.md`, `storage/AGENTS.md`.
## Слои и направление зависимостей
```
api/ (routes, deps, identity, request_id, handlers, schemas)
↓
services/ (UserService, SessionService, ChatService, MessageService, access.py)
↓
storage/ (Storage Protocol → CachedStorage → PostgresStorage)
```
Общие модули нижнего уровня: `domain.py`, `errors.py`, `pagination.py`,
`clock.py`, `constants.py`, `log.py`, `config.py`. Инфраструктура —
тоже общие модули: `db.py` (PostgreSQL), `cache.py` (Valkey),
`passwords.py` (Argon2id). В них нет бизнес-правил.
| Модуль | Может импортировать | Не может импортировать |
|---|---|---|
| `api/*` | services, storage (только тип `Storage`), общие модули, fastapi/starlette | `storage.postgres`, `storage.cached`, `db`, `cache` (их собирает `main.py`) |
| `services/*` | `storage.Storage`, `passwords`, общие модули | `api/*`, `db`, `cache`, fastapi, starlette, pydantic, sqlalchemy |
| `storage/*` | `domain`, `errors`, `pagination`, `clock`, `constants`, `db`, `cache`, sqlalchemy | `api/*`, `services/*`, fastapi, `log` |
| `db`, `cache`, `passwords` | `config`, `constants`, `errors`, `log`, свой драйвер | `api/*`, `services/*`, `storage/*` |
| `domain`, `clock`, `constants` | только стандартную библиотеку | всё остальное из `src` |
| `errors` | `constants` | остальное |
| `pagination` | `domain`, `errors` | остальное |
| `main.py` | всё: он собирает приложение | — |
| `healthcheck.py` | только стандартную библиотеку | `src.*` (проверка должна быть дешёвой) |
| `early_stop.py` | только стандартную библиотеку | `src.*`: работает до импорта приложения и настройки журнала |
Цикл импортов или импорт «вверх» — признак, что код лежит не в том слое.
`migrations/env.py` импортирует `config`, `db.database_url`, `log` и
`storage.tables` — и ничего, что создаёт engine при импорте.
## Кто за что отвечает
- **Роут**: принять запрос (pydantic-модель, параметры пути и query),
взять сессию и сервис из зависимостей, вызвать сервис именованными
аргументами, превратить доменный объект в модель ответа. Бизнес-правил
нет.
- **Сервис**: правила контракта, которые не выражаются схемой (дубликаты
участников, вызывающий в чате, членство, курсор), пароль и сессия,
вызов хранилища, логи бизнес-событий.
- **Хранилище**: атомарная операция над данными — одна транзакция
PostgreSQL; назначение `id` и `created_at`; уникальность и внешние
ключи; перевод сработавшего ограничения в доменную ошибку. Кэш —
обёртка `CachedStorage` над тем же интерфейсом.
- **Инфраструктура**: пул, сроки, обход отказов, журнал отказов. Отказ
PostgreSQL → `Unavailable` (503) в `db.py`; отказ Valkey → промах в
`cache.py`.
## Ошибки (`errors.py`)
- У каждого класса свои `status_code`, `code`, `default_message` и, у
401, `challenge` (значение `WWW-Authenticate`). Перевод в ответ — один
обработчик `api/handlers.py` (`app_error_response`), его же зовёт
`AuthenticationMiddleware` через `identity.on_auth_error`.
- Новая ошибка: наследник подходящего класса (`InvalidRequest` → 400,
`NotFound` → 404, ...), `code` — только из enum `Error.code` в
`contracts/openapi.json`. Текст — английский, без id, путей, имён
классов, SQL и признаков существования чужого объекта.
- Нет чата и чат чужой — **одно и то же** `NotFound`.
- Тот же `Idempotency-Key` с другим телом — `IdempotencyConflict` (409
`conflict`); нет ключа или он не по шаблону — 400 из валидации
заголовка ручки. Ключ в текст ошибки не попадает.
- Вход: `InvalidCredentials` (вызов Basic) — одна ошибка на неверный
пароль, неизвестный username и битый Basic. Остальное: `Unauthorized`
(вызов Bearer). Недоступность хранилища — `Unavailable` (503), никогда
не 401.
## Время (`clock.py`)
- `created_at` назначает `MonotonicClock` внутри хранилища, перед
вставкой: строго возрастающее aware-время UTC с шагом ≥ 1 мкс внутри
**процесса**. С лабы 3 процессов несколько (реплики): между репликами
монотонности нет, порядок задают часы ВМ Docker (у реплик одного хоста
общие) и `id` при равенстве. Транзакции фиксируются не в порядке
времени: запись с меньшим `created_at` может стать видимой позже
соседней (REPORT.md, «Пагинация»).
- Срок сессии сравнивается с `utc_now()` — без монотонной поправки.
- Наружу — только `to_rfc3339()`: `2026-09-01T12:00:00.000000Z`; обратно
(значение из кэша) — `from_rfc3339()`. `datetime.now()` без UTC и
`isoformat()` в ответах не использовать: smoke требует суффикс `Z`.
## Пагинация (`pagination.py`)
- Порядок `(created_at, id)` по возрастанию; `sort_key()` — единственное
место, где он задан в Python; в SQL — `ORDER BY created_at, id` и
сравнение кортежей.
- Сервис просит у хранилища `limit + 1` строк и отдаёт их в
`make_page()`: лишняя строка значит, что есть следующая страница.
Страница ровно из `limit` при пустом остатке даёт `next_cursor=None`.
- Курсор — ключ последнего элемента страницы плюс область
(`history_scope(chat_id)`, `chat_list_scope(user_id)`). Курсор чужой
области, битый base64, не та структура → `InvalidCursor` (400).
Формат курсора внутренний: клиенты и тесты его не разбирают.
## Логи (`log.py`)
- Логгер модуля: `log = get_logger(__name__)` сразу после импортов.
`logging.getLogger` напрямую, `print` и `traceback.print_exc` не
использовать (исключение — строка `configuration error` в stderr при
неверном окружении, до настройки логов).
- Формат задаёт `logging_config()`, его применяет uvicorn
(`uvicorn.run(log_config=...)`); у процесса миграций — `migrations/env.py`.
Второй `dictConfig`/`basicConfig` в коде приложения не добавлять.
- Сообщение — английский, нижний регистр, данные — `key=value` через
`%`-подстановку: `log.info("chat created chat_id=%s members=%d", ...)`.
Не f-string: форматирование ленивое.
- `rid` добавляет фильтр из contextvar `request_id_var`; ставит его
только `RequestIdMiddleware`.
- Уровни: `info` — бизнес-событие (создан пользователь, сессия, чат,
сообщение; отказ по бизнес-правилу), старт и остановка, возврат кэша;
`warning` — обработано, но требует внимания (неудачный вход, отказ БД
или Valkey); `error` — операция не выполнена. 4xx — не ошибки сервера.
- **Нельзя в лог**: `text` сообщения, `display_name`, `title`, username,
пароль, токен, их хэши, `Authorization`, `Idempotency-Key` (его
выбирает клиент, в нём может быть что угодно; повтор виден по
`replayed=true`), тела, query-строку, параметры SQL. Engine создан с
`hide_parameters=True`: текст ошибки драйвера содержит SQL, но не
параметры. Вместо текста — `length=len(text)`.
## Конфигурация (`config.py`)
- `Settings.from_env()` читает только `os.environ`, без `.env` и файлов.
Экземпляр создаётся в `run()` и кладётся в `app.state.settings`;
модульного глобала `settings` нет.
- Подключения — вложенные `Database` и `Cache` (переменные `DB_*`,
`CACHE_*`). Пароли — поля с `repr=False`: в `repr()` настроек их нет.
- У dataclass со `slots=True` атрибут класса — дескриптор, а не значение:
умолчания в `from_env` берутся у экземпляра (`default = cls()`).
- Неверное значение — `ConfigError` с именем переменной; `run()`
печатает её в stderr и выходит с кодом 2.
- Новая настройка — поле `Settings` (или `Database`/`Cache`) с безопасным
дефолтом и границами, `environment` в `compose.yaml` (если её задают
контейнеру), строка в `.env.example` (если она приходит из `.env`),
строка в таблице ниже.
| Переменная | По умолчанию | Смысл |
|---|---|---|
| `APP_HOST` / `APP_PORT` | `127.0.0.1` (в образе `0.0.0.0`) / `8080` | адрес и порт прослушивания |
| `APP_INSTANCE_ID` | hostname (в контейнере — начало его ID) | значение `X-Instance-Id`; `[A-Za-z0-9._-]{1,64}`; по нему `scripts/stop-one.sh` находит реплику |
| `LOG_LEVEL` | `INFO` | `DEBUG`/`INFO`/`WARNING`/`ERROR` |
| `SHUTDOWN_TIMEOUT` | `5` | секунды дожидания запросов после SIGTERM, 1..9 (< `stop_grace_period` 10 с) |
| `KEEP_ALIVE_TIMEOUT` | `60` | секунды простаивающего keep-alive соединения uvicorn; больше `timeout http-keep-alive` HAProxy (10 с) — закрывает LB, а не реплика (`infra/AGENTS.md`) |
| `SESSION_TTL_SECONDS` | `3600` | срок сессии (контракт); в тесте истечения — 2 |
| `IDEMPOTENCY_TTL_SECONDS` | `86400` | сколько повтор с тем же `Idempotency-Key` отдаёт прежний результат (контракт: ≥ 24 ч); в тесте срока — 2 |
| `KDF_CONCURRENCY` | `4` | одновременных хэшей Argon2id (64 MiB на каждый) |
| `DB_HOST` / `DB_PORT` / `DB_NAME` / `DB_USER` / `DB_PASSWORD` | `127.0.0.1` / `5432` / `messenger` / `messenger` / пусто | подключение к PostgreSQL |
| `DB_POOL_SIZE` / `DB_POOL_OVERFLOW` / `DB_POOL_TIMEOUT` | `10` / `5` / `5` с | пул на процесс и ожидание соединения |
| `DB_CONNECT_TIMEOUT` / `DB_STATEMENT_TIMEOUT_MS` / `DB_OPERATION_TIMEOUT` | `3` с / `5000` / `6` с | подключение, серверный срок запроса, срок операции хранилища целиком |
| `CACHE_HOST` / `CACHE_PORT` / `CACHE_PASSWORD` | `127.0.0.1` / `6379` / пусто | подключение к Valkey |
| `CACHE_TIMEOUT` / `CACHE_RETRY_AFTER` / `CACHE_CHAT_TTL` / `CACHE_MAX_CONNECTIONS` | `0.2` с / `5` с / `3600` с / `10` | срок команды, окно пропуска после отказа, срок карточки, пул |
## Приложение (`main.py`)
- `create_app()` собирает `Db`, кэш (`create_cache`, пространство ключей
— имя базы), `CachedStorage(PostgresStorage(db), cache)` и
`Passwords`; кладёт их в `app.state`. Соединения открываются лениво:
без PostgreSQL процесс стартует, `/health/ready` отвечает 503.
- Порядок middleware (снаружи внутрь): `ServerErrorMiddleware` →
`RequestIdMiddleware` → `AuthenticationMiddleware` → роутер.
`add_middleware` добавляет **снаружи**, поэтому `RequestIdMiddleware`
регистрируется последним. Порядок не менять: иначе ответы 401/503 от
аутентификации не попадут в access-лог и получат случайный id вместо
входящего `X-Request-Id` (ловит `student-tests/test_request_id.py`).
- `lifespan`: первой строкой `early_stop.disarm()` (дальше сигналы —
забота uvicorn), фиктивный хэш пароля, `ready=True`; в начале остановки
`ready=False`, затем `engine.dispose()` и закрытие клиента Valkey.
Строки «messenger started instance=…» (там же пул, сроки, keep-alive) и
«messenger stopped instance=…»: по ним реплика в журнале
сопоставляется с `X-Instance-Id`. Долгих операций в остановке нет:
SIGTERM укладывается в `SHUTDOWN_TIMEOUT`.
- `RequestIdMiddleware(instance_id=...)` ставит `X-Request-Id` и
`X-Instance-Id` каждому ответу; ответам 500 их ставит
`handlers.error_response` (они формируются снаружи middleware).
- `uvicorn.run(app, ...)` — экземпляр, без `workers` и `reload`, с
`timeout_keep_alive`: один процесс, пул соединений считан на него.
Масштабирование — числом реплик за HAProxy, а не `--workers`.
- В памяти процесса нет ничего, от чего зависит корректность: сессии,
данные и ключи идемпотентности — в PostgreSQL, Valkey — общий кэш
неизменяемых карточек (лаба 3, реплики взаимозаменяемы).
## Точка входа (`__main__.py`, `early_stop.py`)
`python -m src` → `early_stop.install()` **до** импорта приложения →
`main.run()`. В контейнере сервер — PID 1, а ядро не доставляет PID 1
сигнал без обработчика: пока идёт импорт (почти весь старт), SIGTERM
терялся бы, и `docker stop` стартующей реплики ждал бы 10 с и SIGKILL.
Ранний обработчик пишет одну строку «stopped before startup» (формат
`log.py`, без rid) и завершает процесс с кодом 0. `early_stop.py` — только
stdlib. Проверка — `evidence/stand/early-stop.txt`.
## Рецепт: новая ручка
1. Найти путь, схемы и коды в `contracts/openapi.json`; если ручки там
нет — она не нужна для «4», спросить пользователя.
2. Модели запроса/ответа — в `api/schemas.py` с именами из контракта.
3. Операция данных — метод в `storage/base.py` (Protocol, докстринг: что
атомарно и какие ошибки), реализация в `storage/postgres.py`
(одна транзакция), делегирование в `storage/cached.py`. Нужна новая
колонка или индекс — сначала ревизия (`migrations/AGENTS.md`).
4. Правила — метод сервиса (keyword-only, async), лог события.
5. Роут — в `api/routes/<домен>.py`; новый файл роутов — зарегистрировать
в `api/routes/__init__.py`. Публичная ручка под `/api/v1` — добавить в
`PUBLIC_ENDPOINTS` (`api/identity.py`).
6. Тест в `student-tests/`, затем Definition of Done (корневой файл, раздел 8).
+7
View File
@@ -0,0 +1,7 @@
"""REST API мессенджера MTUSI, лабораторная 3: реплики за HAProxy.
PostgreSQL — источник истины (данные, сессии, ключи идемпотентности),
Valkey — общий кэш карточек чатов. Пакет намеренно пустой при импорте:
`import src.<модуль>` не поднимает приложение, не читает окружение и не
подключается к базе.
"""
+10
View File
@@ -0,0 +1,10 @@
if __name__ == "__main__":
# обработчик SIGTERM — до импорта приложения (src/early_stop.py):
# импорт и есть почти весь старт, а PID 1 без обработчика сигнал теряет
from src import early_stop
early_stop.install()
from src.main import run
run()
+146
View File
@@ -0,0 +1,146 @@
# src/api/ — HTTP-слой и контракт
Источник правды — `contracts/openapi.json` и `contracts/README.md`.
Сгенерированная FastAPI схема (`/openapi.json`) — только справка, но
схемы безопасности в ней совпадают с контрактом (это проверяет
`student-tests/test_auth.py`).
## Устройство
| Файл | Что делает |
|---|---|
| `routes/health.py` | `/health/live` (всегда 200), `/health/ready` (200, если старт завершён и PostgreSQL отвечает `SELECT 1` за 2 с, иначе 503; Valkey не проверяется). Вне `/api/v1`, без идентификации, в access-лог не пишутся. `/health/ready` раз в секунду опрашивает HAProxy: по нему реплика исключается из LB и возвращается |
| `routes/users.py`, `sessions.py`, `chats.py`, `messages.py` | ручки v1; префикс `/api/v1` добавляет `api_router` в `routes/__init__.py`; `messages.py` объявляет обязательный заголовок `Idempotency-Key` |
| `schemas.py` | все pydantic-модели; имена = схемы контракта (`CreateUser`, `User`, `Session`, `ChatPage`, ...) |
| `deps.py` | `get_storage`, `get_passwords`, фабрики сервисов, `current_identity` / `current_user`, разбор Basic (`basic_credentials`), `PageParams` |
| `identity.py` | `BearerBackend` для `AuthenticationMiddleware`, `PUBLIC_ENDPOINTS`, `on_auth_error` |
| `request_id.py` | чистое ASGI-middleware (`__call__`): id запроса, заголовки `X-Request-Id` и `X-Instance-Id`, access-лог |
| `handlers.py` | `error_response()`, `app_error_response()` (с `WWW-Authenticate`) и обработчики всех исключений |
## Правила ручек
- Ручки и зависимости — только `async def`: драйвер БД асинхронный, а
синхронная `def` ушла бы в threadpool.
- Ручка: зависимости → вызов сервиса именованными аргументами →
`Schema.model_validate(domain_obj)`. Логики, обращений к хранилищу и
`try/except` здесь нет.
- POST создания — `status_code=201` в декораторе; `response_model` —
модель контракта. `DELETE /auth/sessions/current` — 204 без тела
(`response_class=Response`).
- Текущий пользователь — `CurrentUser`, текущая сессия (для logout) —
`CurrentIdentity` из `deps.py`. Заголовки `Authorization` и `X-User-Id`
в ручках не читать и не объявлять `Header()`.
- Ошибки — исключения из `src/errors.py`. `HTTPException` не бросать,
`JSONResponse` с ошибкой руками не собирать — только `handlers.py`.
- Модели API в сервис не передавать: разбирать на именованные аргументы.
## Идентификация (лаба 2)
- Bearer проверяет `BearerBackend` в `AuthenticationMiddleware` **до
роутинга и разбора тела**: битый JSON без токена получает 401, а не
400 («сначала аутентификация», `contracts/README.md`). Не переносить
проверку в зависимость ручки — порядок сломается.
- Защищено всё под `/api/v1/`, кроме `PUBLIC_ENDPOINTS`:
`POST /api/v1/users` и `POST /api/v1/auth/sessions`. Health и `/docs`
— вне `/api/v1`.
- Токен — из `Authorization: Bearer <token>` (схема без учёта
регистра). Нет заголовка, другая схема (в том числе Basic на
бизнес-ручке), пустой, неизвестный, истёкший, отозванный токен —
одинаковый 401 `Unauthorized` с `WWW-Authenticate: Bearer
realm="messenger"`.
- PostgreSQL недоступен во время проверки токена — 503 `unavailable` без
`WWW-Authenticate`: бэкенд заворачивает любую `AppError` в
`AuthFailure`, и `on_auth_error` отвечает её статусом. Запрос никогда
не идёт дальше как анонимный.
- `X-User-Id` не читается нигде: не даёт доступа и не меняет владельца
сессии.
- `current_identity` объявляет `Security(HTTPBearer(scheme_name=
"bearerAuth", bearerFormat="opaque session token", auto_error=False))`
только ради схемы в `/openapi.json` и кнопки Authorize в `/docs`; сам
заголовок там не читается — сессию уже положил бэкенд в `request.user`.
## Вход по Basic (`POST /auth/sessions`)
- Путь публичный для middleware; Basic разбирает зависимость
`basic_credentials`. Схема объявлена через `HTTPBase(scheme="basic",
scheme_name="basicAuth", auto_error=False)` (импорт из
`fastapi.security.http`). **Не `HTTPBasic`**: он декодирует ASCII и на
пароле не из ASCII сам отвечает 401 мимо формата контракта.
- Разбор: схема `Basic` → base64 строго (`validate=True`) → UTF-8 →
`partition(":")` по **первому** двоеточию (в пароле двоеточие
допустимо). Username не по шаблону и пароль вне 12–128 code points
отсекаются здесь, до БД и KDF. Любой сбой — тот же 401
`InvalidCredentials` с `WWW-Authenticate: Basic realm="messenger",
charset="UTF-8"`, что и неверный пароль. Ответа 400 у входа нет.
- JSON-тело входа не читается.
## Ловушки FastAPI и что ждёт контракт
| Ситуация | FastAPI по умолчанию | Нужно |
|---|---|---|
| ошибка валидации тела/пути/query | 422 `{"detail": ...}` | 400 `invalid_request` в формате контракта (`on_validation_error`) |
| битый JSON, массив вместо объекта | 422 `json_invalid` | 400 (с токеном) или 401 (без токена: middleware раньше) |
| неизвестный путь / метод | 404 / 405 `{"detail"}` | формат контракта (`on_http_error`) |
| необработанное исключение | 500 text/plain без `X-Request-Id` | 500 `internal_error` + заголовок (`on_unexpected_error` ставит его сам) |
| `Authorization` как `Header()` | пропуск → 400 из валидации | только схемы безопасности с `auto_error=False` |
| `HTTPBasic` | ASCII, свой 401 | `HTTPBase` + свой разбор |
| `strict=True` на всю модель | UUID-строка из JSON не проходит | строгость на полях: `StrictStr`, `NonBlankStr` |
## Валидация (всё — 400)
- Модели запросов наследуют `_Request` (`extra="forbid"`): лишнее поле,
например `sender_id` в сообщении, — 400.
- Строки — `StrictStr`: число вместо строки — 400. Обязательные строки
(`display_name`, `title`, `text`, `password`) — `NonBlankStr`: одни
пробелы — 400, значение не обрезается и не нормализуется.
- Длины — в Unicode code points (`len(str)`): `display_name`, `title`
1–100, `text` 1–4000, `password` 12–128. `username` —
`^[a-z0-9_]{3,32}$` целиком.
- `member_ids`: 1–100 UUID; дубликаты, неизвестные и отсутствие
вызывающего — 400 из сервиса/хранилища (`InvalidMembers`).
- `chat_id` не UUID, `limit` вне 1–100 или не число, пустой или битый
`cursor` — 400.
- Лимиты — только из `src/constants.py`.
## Ответы
- Модели ответа наследуют `_Response` (`from_attributes=True`), время —
тип `Timestamp` (RFC 3339 с `Z`). Лишних полей нет: smoke сверяет
`additionalProperties: false`. В `User` нет пароля, хэша и сессии.
- `Session`: `token`, `token_type="Bearer"`, `expires_at`, `user`.
- Список — `{"items": [...], "next_cursor": null | "..."}`.
- `X-Request-Id` ставит `RequestIdMiddleware` каждому ответу; входящий
заголовок принимается, только если он `[A-Za-z0-9._-]{1,64}`.
- `X-Instance-Id` (лаба 3) — **в каждом ответе API**: успех, ошибки,
health, 401/503 от аутентификации, 404 неизвестного пути, 405, 500.
Одно значение на процесс (`Settings.instance_id`: `APP_INSTANCE_ID` или
hostname — в контейнере начало ID). Ответы самого HAProxy (502/503/504)
его не имеют — контракт допускает. Тест — `test_request_id.py`.
- Access-лог: одна строка `METHOD path -> status (ms)`, без query, тела
и заголовков. Второй access-лог (uvicorn) выключен.
## Отправка сообщения: `Idempotency-Key` (лаба 3)
- Заголовок обязателен только у `POST /api/v1/chats/{chat_id}/messages`:
параметр ручки `Header(alias="Idempotency-Key", pattern=...)` с
шаблоном `IDEMPOTENCY_KEY_PATTERN` (`^[A-Za-z0-9._:-]{1,128}$`). Нет
ключа, пустой, длиннее 128, недопустимый символ, не-ASCII — 400
`invalid_request` той же валидацией, что тело; значение ключа в текст
ошибки не попадает. Другие POST ключ не читают.
- Порядок кодов: 401 (сессия — middleware) → 400 (ключ и тело — схема
ручки) → 404 (не участник — сервис) → 409 (ключ занят другим телом —
хранилище). Без токена — 401 даже с битым JSON и без ключа:
аутентификация в middleware раньше разбора тела и заголовков ручки.
Закреплено `test_idempotency.py::test_codes_order_401_400_404_409`.
- Повтор того же тела — **тот же 201 и то же `Message`** (тот же `id`,
`created_at` до микросекунды): ручка не различает новое и повторное.
«То же тело» — семантически: пробелы и `\u`-экранирование не важны
(хэш канонического JSON в сервисе).
- Прозрачных повторов других POST нет ни в API, ни в LB.
## Проверка правок этого слоя
`make fmt && make lint && make test-isolated`. Для точечной проверки —
рабочий стенд (`make up`) и `curl -s -i` с выводом статуса,
`x-request-id`, `x-instance-id`, `www-authenticate` и тела. Токен в
вывод и отчёт не копировать.
View File
+170
View File
@@ -0,0 +1,170 @@
"""Зависимости ручек: хранилище, сервисы, текущая сессия, вход, страница."""
import base64
import binascii
import re
from dataclasses import dataclass, field
from typing import Annotated
from fastapi import Depends, Query, Request, Security
from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
from fastapi.security.http import HTTPBase
from src.constants import (
PAGE_LIMIT_DEFAULT,
PAGE_LIMIT_MAX,
PAGE_LIMIT_MIN,
PASSWORD_MAX_LENGTH,
PASSWORD_MIN_LENGTH,
USERNAME_PATTERN,
)
from src.domain import Identity, User
from src.errors import InvalidCredentials, Unauthorized
from src.passwords import Passwords
from src.services import ChatService, MessageService, SessionService, UserService
from src.storage import Storage
async def get_storage(request: Request) -> Storage:
return request.app.state.storage
async def get_passwords(request: Request) -> Passwords:
return request.app.state.passwords
StorageDep = Annotated[Storage, Depends(get_storage)]
PasswordsDep = Annotated[Passwords, Depends(get_passwords)]
async def get_user_service(storage: StorageDep, passwords: PasswordsDep) -> UserService:
return UserService(storage, passwords)
async def get_session_service(
request: Request,
storage: StorageDep,
passwords: PasswordsDep,
) -> SessionService:
return SessionService(
storage, passwords, ttl=request.app.state.settings.session_ttl
)
async def get_chat_service(storage: StorageDep) -> ChatService:
return ChatService(storage)
async def get_message_service(request: Request, storage: StorageDep) -> MessageService:
return MessageService(
storage,
key_ttl=request.app.state.settings.idempotency_ttl,
)
UserServiceDep = Annotated[UserService, Depends(get_user_service)]
SessionServiceDep = Annotated[SessionService, Depends(get_session_service)]
ChatServiceDep = Annotated[ChatService, Depends(get_chat_service)]
MessageServiceDep = Annotated[MessageService, Depends(get_message_service)]
# схемы bearerAuth и basicAuth из contracts/openapi.json: они есть в
# /openapi.json и дают кнопку Authorize в /docs. auto_error=False —
# FastAPI не отвечает сам своим 403/401 мимо формата контракта.
# Bearer проверяет BearerBackend (identity.py) ещё до роутинга.
bearer_scheme = HTTPBearer(
scheme_name="bearerAuth",
bearerFormat="opaque session token",
auto_error=False,
)
# HTTPBase, а не HTTPBasic: HTTPBasic декодирует credentials как ASCII и
# на пароле не из ASCII сам отвечает 401, а контракт требует UTF-8
basic_scheme = HTTPBase(scheme="basic", scheme_name="basicAuth", auto_error=False)
async def current_identity(
request: Request,
_credentials: Annotated[
HTTPAuthorizationCredentials | None, Security(bearer_scheme)
],
) -> Identity:
"""Сессия, которую нашёл BearerBackend.
`_credentials` здесь не читается: параметр только объявляет схему
bearerAuth в OpenAPI. Если ручку вдруг повесили на публичный путь,
сессии нет — 401, а не падение.
"""
identity = request.user
if not isinstance(identity, Identity):
raise Unauthorized
return identity
CurrentIdentity = Annotated[Identity, Depends(current_identity)]
async def current_user(identity: CurrentIdentity) -> User:
return identity.user
CurrentUser = Annotated[User, Depends(current_user)]
@dataclass(frozen=True, slots=True)
class BasicCredentials:
username: str
password: str = field(repr=False)
def parse_basic(
credentials: HTTPAuthorizationCredentials | None,
) -> BasicCredentials | None:
"""username и пароль из `Authorization: Basic`; `None` — разбор не удался.
base64 строго, UTF-8, разделитель — первое двоеточие: в username его
не бывает, в пароле оно допустимо. Значения, которые не могут быть
верными (формат username и длина пароля публичны), отсекаются здесь:
до БД и KDF не доходит ни мусор, ни пароль в мегабайт.
"""
if credentials is None or credentials.scheme.lower() != "basic":
return None
try:
decoded = base64.b64decode(credentials.credentials, validate=True)
username, separator, password = decoded.decode().partition(":")
except (binascii.Error, UnicodeDecodeError):
return None
if not separator or not re.fullmatch(USERNAME_PATTERN, username):
return None
if not PASSWORD_MIN_LENGTH <= len(password) <= PASSWORD_MAX_LENGTH:
return None
return BasicCredentials(username=username, password=password)
async def basic_credentials(
credentials: Annotated[HTTPAuthorizationCredentials | None, Security(basic_scheme)],
) -> BasicCredentials:
"""Учётные данные входа; любой сбой разбора — тот же 401, что неверный пароль."""
parsed = parse_basic(credentials)
if parsed is None:
raise InvalidCredentials
return parsed
BasicCredentialsDep = Annotated[BasicCredentials, Depends(basic_credentials)]
@dataclass(frozen=True, slots=True)
class PageParams:
limit: int
cursor: str | None
async def page_params(
limit: Annotated[int, Query(ge=PAGE_LIMIT_MIN, le=PAGE_LIMIT_MAX)] = (
PAGE_LIMIT_DEFAULT
),
cursor: Annotated[str | None, Query(min_length=1)] = None,
) -> PageParams:
return PageParams(limit=limit, cursor=cursor)
PageDep = Annotated[PageParams, Depends(page_params)]
+121
View File
@@ -0,0 +1,121 @@
"""Любая ошибка → `{"error": {"code", "message", "request_id"}}`.
- `AppError`: статус, `code` и `WWW-Authenticate` (у 401) берутся из
класса исключения.
- Ошибки валидации FastAPI → 400 `invalid_request` (422 не отдаётся).
- 404 неизвестного пути и 405 → формат контракта.
- Непредвиденное исключение → 500 без деталей. Traceback пишет uvicorn:
Starlette после ответа бросает исключение дальше.
"""
from uuid import uuid4
from fastapi import FastAPI, Request
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from starlette.exceptions import HTTPException as StarletteHTTPException
from starlette.requests import HTTPConnection
from src.api.schemas import ErrorBody, ErrorResponse
from src.constants import INSTANCE_ID_HEADER, REQUEST_ID_HEADER
from src.errors import AppError
_HTTP_ERRORS: dict[int, tuple[str, str]] = {
404: ("not_found", "Not found"),
405: ("invalid_request", "Method not allowed"),
}
def request_id_of(conn: HTTPConnection) -> str:
"""Id запроса от RequestIdMiddleware; запасной — если ошибка случилась раньше."""
return getattr(conn.state, "request_id", None) or uuid4().hex
def error_response(
conn: HTTPConnection,
*,
status_code: int,
code: str,
message: str,
headers: dict[str, str] | None = None,
) -> JSONResponse:
request_id = request_id_of(conn)
body = ErrorResponse(
error=ErrorBody(code=code, message=message, request_id=request_id),
)
return JSONResponse(
status_code=status_code,
content=body.model_dump(),
# заголовки ставит и middleware; здесь они нужны ответам 500,
# которые формируются снаружи всех middleware
headers={
**(headers or {}),
REQUEST_ID_HEADER: request_id,
INSTANCE_ID_HEADER: conn.app.state.settings.instance_id,
},
)
def app_error_response(conn: HTTPConnection, exc: AppError) -> JSONResponse:
"""Ответ на доменную ошибку; общий для ручек и AuthenticationMiddleware."""
return error_response(
conn,
status_code=exc.status_code,
code=exc.code,
message=str(exc),
headers={"WWW-Authenticate": exc.challenge} if exc.challenge else None,
)
async def on_app_error(request: Request, exc: AppError) -> JSONResponse:
return app_error_response(request, exc)
async def on_validation_error(
request: Request,
exc: RequestValidationError,
) -> JSONResponse:
# первая ошибка: где и что не так; входное значение в ответ не попадает
errors = exc.errors()
first = errors[0] if errors else {}
location = ".".join(str(part) for part in first.get("loc", ()))
reason = first.get("msg", "Invalid request")
return error_response(
request,
status_code=400,
code="invalid_request",
message=f"{location}: {reason}" if location else reason,
)
async def on_http_error(
request: Request,
exc: StarletteHTTPException,
) -> JSONResponse:
code, message = _HTTP_ERRORS.get(
exc.status_code,
("invalid_request", "Invalid request"),
)
return error_response(
request,
status_code=exc.status_code,
code=code,
message=message,
headers=exc.headers,
)
async def on_unexpected_error(request: Request, _exc: Exception) -> JSONResponse:
return error_response(
request,
status_code=500,
code="internal_error",
message="Internal server error",
)
def install(app: FastAPI) -> None:
app.add_exception_handler(AppError, on_app_error)
app.add_exception_handler(RequestValidationError, on_validation_error)
app.add_exception_handler(StarletteHTTPException, on_http_error)
app.add_exception_handler(Exception, on_unexpected_error)
+89
View File
@@ -0,0 +1,89 @@
"""Идентификация лабы 2: Bearer-сессия — до роутинга и разбора тела.
Работает через стандартный `AuthenticationMiddleware` Starlette.
`BearerBackend` вызывается на каждый запрос:
- публичный путь (health, docs, `POST /api/v1/users`,
`POST /api/v1/auth/sessions`) — `None`, запрос идёт дальше без
пользователя. Вход по Basic разбирает сама ручка входа (`deps.py`);
- защищённый путь — сессия по токену из `Authorization: Bearer <token>`
или отказ, и middleware сразу отвечает через `on_auth_error`.
Поэтому 401 приходит раньше любой проверки тела, пути и query: «сначала
аутентификация» из contracts/README.md выполняется даже для битого JSON.
Ручки берут готовую сессию из `request.user` (`deps.current_identity`).
`X-User-Id` больше не читается нигде: он не даёт доступа и не меняет
владельца сессии. Basic на бизнес-ручке — чужая схема, тот же 401 с
вызовом Bearer. Недоступность PostgreSQL — 503, а не 401 и не анонимный
доступ.
"""
from fastapi.responses import JSONResponse
from fastapi.security.utils import get_authorization_scheme_param
from starlette.authentication import (
AuthCredentials,
AuthenticationBackend,
AuthenticationError,
)
from starlette.requests import HTTPConnection
from src.api.handlers import app_error_response
from src.constants import API_PREFIX, AUTHORIZATION_HEADER, SESSIONS_PATH
from src.domain import Identity
from src.errors import AppError, Unauthorized
from src.services import SessionService
# публичные пути внутри API_PREFIX: регистрация и вход по Basic
PUBLIC_ENDPOINTS = frozenset(
{
("POST", f"{API_PREFIX}/users"),
("POST", SESSIONS_PATH),
},
)
def requires_identity(method: str, path: str) -> bool:
return path.startswith(f"{API_PREFIX}/") and (method, path) not in PUBLIC_ENDPOINTS
def bearer_token(header: str | None) -> str | None:
"""Токен из `Authorization: Bearer <token>`; другая схема — `None`."""
scheme, token = get_authorization_scheme_param(header)
if scheme.lower() != "bearer" or not token:
return None
return token
class AuthFailure(AuthenticationError):
"""Отказ бэкенда с доменной ошибкой: 401 или 503 (БД недоступна)."""
def __init__(self, error: AppError) -> None:
super().__init__(str(error))
self.error = error
class BearerBackend(AuthenticationBackend):
async def authenticate(
self,
conn: HTTPConnection,
) -> tuple[AuthCredentials, Identity] | None:
if not requires_identity(conn.scope.get("method", ""), conn.scope["path"]):
return None
state = conn.app.state
sessions = SessionService(
state.storage,
state.passwords,
ttl=state.settings.session_ttl,
)
token = bearer_token(conn.headers.get(AUTHORIZATION_HEADER))
try:
identity = await sessions.authenticate(token=token)
except AppError as exc:
raise AuthFailure(exc) from exc
return AuthCredentials(["authenticated"]), identity
def on_auth_error(conn: HTTPConnection, exc: AuthenticationError) -> JSONResponse:
error = exc.error if isinstance(exc, AuthFailure) else Unauthorized()
return app_error_response(conn, error)
+83
View File
@@ -0,0 +1,83 @@
"""X-Request-Id и X-Instance-Id на каждом ответе, одна строка access-лога.
Чистое ASGI-middleware: прямой вызов приложения и обёртка send.
Без дочерней задачи и потока сообщений на каждый запрос: это уменьшает
накладные расходы слоя, исследуемые в треке «5».
Id запроса: входящий `X-Request-Id`, если он короткий и безопасный
(`[A-Za-z0-9._-]{1,64}`), иначе новый uuid4. Так id проходит через
балансировщик, а мусор из заголовка не попадает в логи. Тот же id — в
заголовке ответа, в `request_id` тела ошибки и в каждой строке лога
этого запроса.
`X-Instance-Id` (лаба 3) — реплика, которая обслужила запрос: одно
значение на процесс (`Settings.instance_id`). Ответы, которые создаёт
сам HAProxy (502/503/504), его не имеют — контракт это допускает.
"""
import re
import time
from uuid import uuid4
from starlette.datastructures import Headers, MutableHeaders
from starlette.types import ASGIApp, Message, Receive, Scope, Send
from src.constants import HEALTH_PATHS, INSTANCE_ID_HEADER, REQUEST_ID_HEADER
from src.log import get_logger, request_id_var
log = get_logger("src.http")
_SAFE_REQUEST_ID = re.compile(r"[A-Za-z0-9._-]{1,64}")
def _request_id(scope: Scope) -> str:
incoming = Headers(scope=scope).get(REQUEST_ID_HEADER)
if incoming and _SAFE_REQUEST_ID.fullmatch(incoming):
return incoming
return uuid4().hex
class RequestIdMiddleware:
def __init__(self, app: ASGIApp, *, instance_id: str) -> None:
self.app = app
self.instance_id = instance_id
async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
if scope["type"] != "http":
await self.app(scope, receive, send)
return
request_id = _request_id(scope)
# request.state.request_id — для обработчиков ошибок
scope.setdefault("state", {})["request_id"] = request_id
# не сбрасывается: у каждого запроса в uvicorn своя задача, а
# traceback непредвиденной ошибки uvicorn пишет уже после выхода
# отсюда, и в нём тоже нужен rid
request_id_var.set(request_id)
status_code = 500
started = time.perf_counter()
async def send_with_ids(message: Message) -> None:
nonlocal status_code
if message["type"] == "http.response.start":
status_code = message["status"]
headers = MutableHeaders(scope=message)
if REQUEST_ID_HEADER not in headers:
headers.append(REQUEST_ID_HEADER, request_id)
if INSTANCE_ID_HEADER not in headers:
headers.append(INSTANCE_ID_HEADER, self.instance_id)
await send(message)
try:
await self.app(scope, receive, send_with_ids)
finally:
# health дёргают healthcheck и балансировщик: в лог не пишем.
# Путь без query; тела и заголовки идентификации не логируются
if scope["path"] not in HEALTH_PATHS:
log.info(
"%s %s -> %d (%.1f ms)",
scope["method"],
scope["path"],
status_code,
(time.perf_counter() - started) * 1000,
)
+24
View File
@@ -0,0 +1,24 @@
"""Роутеры. `api_router` собирает ручки версии 1 под API_PREFIX.
Новый домен регистрируется только здесь.
"""
from fastapi import APIRouter
from src.api.routes.chats import router as chats_router
from src.api.routes.health import router as health_router
from src.api.routes.messages import router as messages_router
from src.api.routes.sessions import router as sessions_router
from src.api.routes.users import router as users_router
from src.constants import API_PREFIX
api_router = APIRouter(prefix=API_PREFIX)
api_router.include_router(users_router)
api_router.include_router(sessions_router)
api_router.include_router(chats_router)
api_router.include_router(messages_router)
__all__ = [
"api_router",
"health_router",
]
+46
View File
@@ -0,0 +1,46 @@
from uuid import UUID
from fastapi import APIRouter
from src.api import schemas
from src.api.deps import ChatServiceDep, CurrentUser, PageDep
router = APIRouter(prefix="/chats", tags=["chats"])
@router.post("", status_code=201, response_model=schemas.Chat)
async def create_chat(
user: CurrentUser,
body: schemas.CreateChat,
chats: ChatServiceDep,
) -> schemas.Chat:
chat = await chats.create(
creator_id=user.id,
title=body.title,
member_ids=body.member_ids,
)
return schemas.Chat.model_validate(chat)
@router.get("", response_model=schemas.ChatPage)
async def list_chats(
user: CurrentUser,
page: PageDep,
chats: ChatServiceDep,
) -> schemas.ChatPage:
result = await chats.list_for(
user_id=user.id,
limit=page.limit,
cursor=page.cursor,
)
return schemas.ChatPage.model_validate(result)
@router.get("/{chat_id}", response_model=schemas.Chat)
async def get_chat(
user: CurrentUser,
chat_id: UUID,
chats: ChatServiceDep,
) -> schemas.Chat:
chat = await chats.get(chat_id=chat_id, user_id=user.id)
return schemas.Chat.model_validate(chat)
+32
View File
@@ -0,0 +1,32 @@
from fastapi import APIRouter, Request
from src.api.schemas import ErrorResponse, Health
from src.constants import HEALTH_LIVE_PATH, HEALTH_READY_PATH
from src.errors import Unavailable
# вне версии API, без идентификации, в access-лог не пишутся
router = APIRouter(tags=["health"])
@router.get(HEALTH_LIVE_PATH, response_model=Health)
async def live() -> Health:
"""Процесс жив и отвечает по HTTP. Хранилища не проверяются."""
return Health()
@router.get(
HEALTH_READY_PATH,
response_model=Health,
responses={503: {"model": ErrorResponse}},
)
async def ready(request: Request) -> Health:
"""Можно обслуживать обязательный путь; иначе 503.
Критичная зависимость — PostgreSQL (`SELECT 1` за 2 с): в нём данные
и сессии. Valkey не проверяется: это кэш, без него запросы идут в
PostgreSQL. До конца старта и с начала остановки — тоже 503.
"""
if not request.app.state.ready:
raise Unavailable
await request.app.state.storage.ping()
return Health()
+51
View File
@@ -0,0 +1,51 @@
from typing import Annotated
from uuid import UUID
from fastapi import APIRouter, Header
from src.api import schemas
from src.api.deps import CurrentUser, MessageServiceDep, PageDep
from src.constants import IDEMPOTENCY_KEY_HEADER, IDEMPOTENCY_KEY_PATTERN
router = APIRouter(prefix="/chats/{chat_id}/messages", tags=["messages"])
# обязательный заголовок (лаба 3). Проверяет схема ручки вместе с телом:
# нет ключа или он не по шаблону — 400 после 401 (middleware) и до 404
# (членство в сервисе). Значение в текст ошибки не попадает
IdempotencyKey = Annotated[
str,
Header(alias=IDEMPOTENCY_KEY_HEADER, pattern=IDEMPOTENCY_KEY_PATTERN),
]
@router.post("", status_code=201, response_model=schemas.Message)
async def send_message(
user: CurrentUser,
chat_id: UUID,
body: schemas.CreateMessage,
idempotency_key: IdempotencyKey,
messages: MessageServiceDep,
) -> schemas.Message:
message = await messages.send(
chat_id=chat_id,
sender_id=user.id,
text=body.text,
idempotency_key=idempotency_key,
)
return schemas.Message.model_validate(message)
@router.get("", response_model=schemas.MessagePage)
async def list_messages(
user: CurrentUser,
chat_id: UUID,
page: PageDep,
messages: MessageServiceDep,
) -> schemas.MessagePage:
result = await messages.history(
chat_id=chat_id,
user_id=user.id,
limit=page.limit,
cursor=page.cursor,
)
return schemas.MessagePage.model_validate(result)
+29
View File
@@ -0,0 +1,29 @@
from fastapi import APIRouter, Response
from src.api import schemas
from src.api.deps import BasicCredentialsDep, CurrentIdentity, SessionServiceDep
router = APIRouter(prefix="/auth/sessions", tags=["sessions"])
@router.post("", status_code=201, response_model=schemas.Session)
async def create_session(
credentials: BasicCredentialsDep,
sessions: SessionServiceDep,
) -> schemas.Session:
"""Вход по `Authorization: Basic`; тело запроса не читается."""
issued = await sessions.login(
username=credentials.username,
password=credentials.password,
)
return schemas.Session.model_validate(issued)
@router.delete("/current", status_code=204, response_class=Response)
async def revoke_current_session(
identity: CurrentIdentity,
sessions: SessionServiceDep,
) -> Response:
"""Выход: отзывается только сессия этого токена."""
await sessions.revoke(session_id=identity.session_id)
return Response(status_code=204)
+24
View File
@@ -0,0 +1,24 @@
from fastapi import APIRouter
from src.api import schemas
from src.api.deps import CurrentUser, UserServiceDep
router = APIRouter(prefix="/users", tags=["users"])
@router.post("", status_code=201, response_model=schemas.User)
async def register_user(
body: schemas.CreateUser,
users: UserServiceDep,
) -> schemas.User:
user = await users.register(
username=body.username,
display_name=body.display_name,
password=body.password,
)
return schemas.User.model_validate(user)
@router.get("/me", response_model=schemas.User)
async def get_me(user: CurrentUser) -> schemas.User:
return schemas.User.model_validate(user)
+133
View File
@@ -0,0 +1,133 @@
"""HTTP-модели. Имена и поля совпадают со схемами contracts/openapi.json.
Модели запросов строгие: лишнее поле или неверный тип — 400. Строгость
задаётся на уровне полей (`StrictStr`), а не `strict=True` на всю
модель: иначе UUID, пришедший строкой в JSON, не прошёл бы проверку.
"""
from datetime import datetime
from typing import Annotated, Literal
from uuid import UUID
from pydantic import (
AfterValidator,
BaseModel,
ConfigDict,
Field,
PlainSerializer,
StrictStr,
)
from src.clock import to_rfc3339
from src.constants import (
CHAT_MEMBERS_MAX,
CHAT_TITLE_MAX_LENGTH,
DISPLAY_NAME_MAX_LENGTH,
MESSAGE_TEXT_MAX_LENGTH,
PASSWORD_MAX_LENGTH,
PASSWORD_MIN_LENGTH,
USERNAME_PATTERN,
)
def _not_blank(value: str) -> str:
"""Строка из одних пробельных символов невалидна; значение не обрезается."""
if not value.strip():
raise ValueError("must not be blank")
return value
# строгая непустая строка: число не превращается в строку, пробелы — 400
NonBlankStr = Annotated[StrictStr, AfterValidator(_not_blank)]
# время в ответе: RFC 3339 UTC с микросекундами и Z
Timestamp = Annotated[datetime, PlainSerializer(to_rfc3339, return_type=str)]
class _Request(BaseModel):
model_config = ConfigDict(extra="forbid")
class _Response(BaseModel):
model_config = ConfigDict(from_attributes=True)
class CreateUser(_Request):
username: StrictStr = Field(pattern=USERNAME_PATTERN)
display_name: NonBlankStr = Field(min_length=1, max_length=DISPLAY_NAME_MAX_LENGTH)
# длина в code points; значение не обрезается и не нормализуется
password: NonBlankStr = Field(
min_length=PASSWORD_MIN_LENGTH,
max_length=PASSWORD_MAX_LENGTH,
json_schema_extra={"writeOnly": True},
)
class User(_Response):
"""Пароля, его хэша и данных сессии здесь нет и быть не может."""
id: UUID
username: str
display_name: str
created_at: Timestamp
class Session(_Response):
"""Ответ на вход. Токен клиент видит только здесь, один раз."""
token: str
token_type: Literal["Bearer"] = "Bearer"
expires_at: Timestamp
user: User
class CreateChat(_Request):
title: NonBlankStr = Field(min_length=1, max_length=CHAT_TITLE_MAX_LENGTH)
# только форма списка; дубликаты, существование участников и
# вызывающего в списке проверяет ChatService.create
member_ids: list[UUID] = Field(min_length=1, max_length=CHAT_MEMBERS_MAX)
class Chat(_Response):
id: UUID
title: str
member_ids: list[UUID]
created_at: Timestamp
class ChatPage(_Response):
items: list[Chat]
next_cursor: str | None
class CreateMessage(_Request):
"""Отправитель берётся из идентификации: поле sender_id даёт 400."""
text: NonBlankStr = Field(min_length=1, max_length=MESSAGE_TEXT_MAX_LENGTH)
class Message(_Response):
id: UUID
chat_id: UUID
sender_id: UUID
text: str
created_at: Timestamp
class MessagePage(_Response):
items: list[Message]
next_cursor: str | None
class Health(BaseModel):
status: Literal["ok"] = "ok"
class ErrorBody(BaseModel):
code: str
message: str
request_id: str
class ErrorResponse(BaseModel):
error: ErrorBody
+128
View File
@@ -0,0 +1,128 @@
"""Valkey: кэш со сроком на команду и обходом при отказе.
Кэш — не источник истины, поэтому его отказ — промах, а не ошибка:
`get` отдаёт `None`, `set` — `False`, и запрос идёт в PostgreSQL с тем
же ответом. Вся команда — ожидание пула, соединение, повтор и ответ —
ограничена `CACHE_TIMEOUT`. После отказа кэш пропускается на
`CACHE_RETRY_AFTER` секунд: следующие запросы не ждут срок заново.
redis-py по умолчанию повторяет команду с паузами, и замороженный
Valkey держал бы запрос секунды. Здесь повтор один, без паузы и только
на обрыв соединения: так старое соединение пула после рестарта Valkey
открывается заново сразу, а таймаут не повторяется.
В журнал — одна строка `warning` на отказ и `info` при возврате. Пароль
есть только в настройках пула и в журнал не попадает.
"""
import asyncio
import time
from redis.asyncio import BlockingConnectionPool, Redis
from redis.asyncio.retry import Retry
from redis.backoff import NoBackoff
from redis.exceptions import ConnectionError as RedisConnectionError
from redis.exceptions import RedisError
from src.config import Cache as CacheSettings
from src.log import get_logger
log = get_logger(__name__)
class Cache:
"""Строковый кэш поверх клиента Valkey: отказ — промах.
`namespace` — имя базы PostgreSQL, из которой взяты значения: на одном
Valkey ключи разных баз (рабочей и тестовой) не пересекаются.
"""
def __init__(
self,
client: Redis,
*,
namespace: str,
timeout: float,
retry_after: float,
) -> None:
self.namespace = namespace
self._client = client
self._timeout = timeout
self._retry_after = retry_after
# monotonic-время конца пропуска; None — кэш работает
self._skip_until: float | None = None
async def get(self, key: str) -> str | None:
"""Значение ключа; `None` — промах, в том числе из-за отказа."""
if self._skipping():
return None
try:
async with asyncio.timeout(self._timeout):
value = await self._client.get(key)
except (RedisError, OSError) as exc:
self._failed(exc)
return None
self._succeeded()
return value
async def set(self, key: str, value: str, *, ttl: int) -> bool:
"""Записать со сроком в секундах; `False` — не записано из-за отказа."""
if self._skipping():
return False
try:
async with asyncio.timeout(self._timeout):
await self._client.set(key, value, ex=ttl)
except (RedisError, OSError) as exc:
self._failed(exc)
return False
self._succeeded()
return True
async def close(self) -> None:
await self._client.aclose()
def _skipping(self) -> bool:
return self._skip_until is not None and time.monotonic() < self._skip_until
def _failed(self, error: Exception) -> None:
# одна строка на отказ: неудачные пробы после окна пропуска молчат.
# TimeoutError от asyncio.timeout без текста — тогда repr
if self._skip_until is None:
log.warning(
"cache unavailable error_type=%s error=%s retry_after=%.1fs",
type(error).__name__,
str(error) or repr(error),
self._retry_after,
)
self._skip_until = time.monotonic() + self._retry_after
def _succeeded(self) -> None:
if self._skip_until is not None:
self._skip_until = None
log.info("cache available again")
def create_cache(settings: CacheSettings, *, namespace: str) -> Cache:
"""Кэш с пулом и сроками из настроек; соединения открываются лениво."""
# BlockingConnectionPool: при всплеске запросов команда ждёт свободное
# соединение, а обычный пул сразу бросал бы MaxConnectionsError, и
# здоровый Valkey пропускался бы как отказавший.
# Retry — из redis.asyncio: синхронный класс асинхронное соединение
# принимает молча, но повтор с ним не выполняется
pool = BlockingConnectionPool(
host=settings.host,
port=settings.port,
password=settings.password or None,
max_connections=settings.max_connections,
timeout=settings.timeout,
socket_timeout=settings.timeout,
socket_connect_timeout=settings.timeout,
retry=Retry(NoBackoff(), 1, supported_errors=(RedisConnectionError,)),
decode_responses=True,
)
return Cache(
Redis.from_pool(pool),
namespace=namespace,
timeout=settings.timeout,
retry_after=settings.retry_after,
)
+51
View File
@@ -0,0 +1,51 @@
"""Время сервера: монотонные часы и формат RFC 3339.
`created_at` задаёт порядок истории `(created_at, id)`. Системные часы
могут шагнуть назад (NTP) или выдать одно значение двум записям подряд.
`MonotonicClock` отдаёт строго возрастающее время с шагом не меньше 1 мкс.
Хранилище берёт время у него перед вставкой. Процесс один, event loop
один, а `now()` не содержит `await`: два вызова не перемешаются.
Строгий рост — внутри одного процесса. Транзакции фиксируются не в том
порядке, в каком получили время, поэтому запись с меньшим `created_at`
может стать видимой чуть позже соседней (REPORT.md, «Пагинация»).
"""
from datetime import UTC, datetime, timedelta
# RFC 3339 в UTC: всегда шесть знаков микросекунд и суффикс Z
RFC3339_FORMAT = "%Y-%m-%dT%H:%M:%S.%fZ"
_TICK = timedelta(microseconds=1)
class MonotonicClock:
"""Строго возрастающее aware-время UTC.
Не потокобезопасен: вызывается только из event loop процесса.
"""
def __init__(self) -> None:
self._last: datetime | None = None
def now(self) -> datetime:
current = datetime.now(UTC)
if self._last is not None and current <= self._last:
current = self._last + _TICK
self._last = current
return current
def utc_now() -> datetime:
"""Текущее время UTC без монотонной поправки: для сравнения со сроком."""
return datetime.now(UTC)
def to_rfc3339(value: datetime) -> str:
"""Время для ответа API: `2026-09-01T12:00:00.000000Z`."""
return value.astimezone(UTC).strftime(RFC3339_FORMAT)
def from_rfc3339(value: str) -> datetime:
"""Обратно из `to_rfc3339()`: aware-время UTC с микросекундами."""
return datetime.strptime(value, RFC3339_FORMAT).replace(tzinfo=UTC)
+287
View File
@@ -0,0 +1,287 @@
"""Настройки процесса — только из переменных окружения.
Файлов конфигурации нет. В compose переменные задаёт `environment`
(значения подставляются из `.env`), `make run` передаёт их приложению на
хосте сам; без них действуют значения по умолчанию. Полный список
переменных — AGENTS.md, раздел «Конфигурация».
Пароли PostgreSQL и Valkey тоже приходят переменными: в `repr()`
настроек их нет, в лог они не пишутся.
"""
import os
import re
import socket
from collections.abc import Mapping
from dataclasses import dataclass, field
from typing import Self
LOG_LEVELS = ("DEBUG", "INFO", "WARNING", "ERROR")
DEFAULT_HOST = "127.0.0.1"
DEFAULT_PORT = 8080
DEFAULT_LOG_LEVEL = "INFO"
DEFAULT_SHUTDOWN_TIMEOUT = 5
# секунды, которые uvicorn держит простаивающее keep-alive соединение.
# Больше timeout http-keep-alive HAProxy (10 с): простаивающее соединение
# LB → реплика закрывает LB, а не реплика (infra/AGENTS.md, «Цепочка
# таймаутов»)
DEFAULT_KEEP_ALIVE = 60
# контракт: SESSION_TTL_SECONDS, по умолчанию 3600
DEFAULT_SESSION_TTL = 3600
# контракт: результат отправки по ключу хранится не меньше 24 ч
DEFAULT_IDEMPOTENCY_TTL = 24 * 3600
# одновременных хэшей Argon2id: каждый берёт 64 MiB памяти
DEFAULT_KDF_CONCURRENCY = 4
# срок сессии и ключа не больше 30 суток: длиннее учебному стенду не нужно
MAX_SESSION_TTL = 30 * 24 * 3600
# X-Instance-Id: в compose это hostname контейнера (начало его ID)
_INSTANCE_ID = re.compile(r"[A-Za-z0-9._-]{1,64}")
class ConfigError(ValueError):
"""Переменная окружения задана, но её значение неверно."""
def _text(env: Mapping[str, str], name: str, default: str) -> str:
value = env.get(name, "").strip()
return value or default
def _int(env: Mapping[str, str], name: str, default: int, low: int, high: int) -> int:
raw = env.get(name, "").strip()
if not raw:
return default
try:
value = int(raw)
except ValueError:
raise ConfigError(f"{name} must be an integer, got {raw!r}") from None
if not low <= value <= high:
raise ConfigError(f"{name} must be within {low}..{high}, got {value}")
return value
def _instance_id(env: Mapping[str, str]) -> str:
"""`APP_INSTANCE_ID` или hostname: стабилен, пока жив процесс.
В контейнере hostname — короткий ID контейнера: по нему
`scripts/stop-one.sh` находит реплику, ответившую тесту.
"""
raw = env.get("APP_INSTANCE_ID", "").strip()
if not raw:
return socket.gethostname() or "local"
if not _INSTANCE_ID.fullmatch(raw):
raise ConfigError(
f"APP_INSTANCE_ID must match {_INSTANCE_ID.pattern}, got {raw!r}",
)
return raw
def _float(
env: Mapping[str, str],
name: str,
default: float,
low: float,
high: float,
) -> float:
raw = env.get(name, "").strip()
if not raw:
return default
try:
value = float(raw)
except ValueError:
raise ConfigError(f"{name} must be a number, got {raw!r}") from None
if not low <= value <= high:
raise ConfigError(f"{name} must be within {low}..{high}, got {value}")
return value
@dataclass(frozen=True, slots=True)
class Database:
"""Подключение к PostgreSQL, пул и сроки (переменные `DB_*`)."""
host: str = "127.0.0.1"
port: int = 5432
name: str = "messenger"
user: str = "messenger"
password: str = field(default="", repr=False)
# соединений в пуле и сверх него: пул считается на один процесс
pool_size: int = 10
pool_overflow: int = 5
# секунды ожидания свободного соединения пула
pool_timeout: float = 5.0
# секунды на установку соединения
connect_timeout: float = 3.0
# серверный statement_timeout, мс; 0 — без ограничения
statement_timeout_ms: int = 5000
# секунды на одну операцию хранилища целиком: зависший сервер или
# обрыв сети, где серверный таймаут не сработает
operation_timeout: float = 6.0
@classmethod
def from_env(cls, env: Mapping[str, str]) -> Self:
# у dataclass со slots атрибут класса — дескриптор, не значение:
# значения по умолчанию берутся у экземпляра
default = cls()
return cls(
host=_text(env, "DB_HOST", default.host),
port=_int(env, "DB_PORT", default.port, 1, 65535),
name=_text(env, "DB_NAME", default.name),
user=_text(env, "DB_USER", default.user),
password=env.get("DB_PASSWORD", ""),
pool_size=_int(env, "DB_POOL_SIZE", default.pool_size, 1, 100),
pool_overflow=_int(
env,
"DB_POOL_OVERFLOW",
default.pool_overflow,
0,
100,
),
pool_timeout=_float(
env,
"DB_POOL_TIMEOUT",
default.pool_timeout,
0.1,
60,
),
connect_timeout=_float(
env,
"DB_CONNECT_TIMEOUT",
default.connect_timeout,
0.1,
60,
),
statement_timeout_ms=_int(
env,
"DB_STATEMENT_TIMEOUT_MS",
default.statement_timeout_ms,
0,
600_000,
),
operation_timeout=_float(
env,
"DB_OPERATION_TIMEOUT",
default.operation_timeout,
0.1,
120,
),
)
@dataclass(frozen=True, slots=True)
class Cache:
"""Подключение к Valkey (кэш карточек чатов, переменные `CACHE_*`)."""
host: str = "127.0.0.1"
port: int = 6379
password: str = field(default="", repr=False)
# секунды на всю команду: ожидание пула, соединение, повтор, ответ;
# дольше — запрос идёт в PostgreSQL
timeout: float = 0.2
# секунды, на которые кэш пропускается после отказа Valkey
retry_after: float = 5.0
# секунды жизни карточки чата в кэше
chat_ttl: int = 3600
# соединений в пуле клиента
max_connections: int = 10
@classmethod
def from_env(cls, env: Mapping[str, str]) -> Self:
default = cls()
return cls(
host=_text(env, "CACHE_HOST", default.host),
port=_int(env, "CACHE_PORT", default.port, 1, 65535),
password=env.get("CACHE_PASSWORD", ""),
timeout=_float(env, "CACHE_TIMEOUT", default.timeout, 0.01, 10),
retry_after=_float(
env,
"CACHE_RETRY_AFTER",
default.retry_after,
0.1,
600,
),
chat_ttl=_int(env, "CACHE_CHAT_TTL", default.chat_ttl, 1, 86_400),
max_connections=_int(
env,
"CACHE_MAX_CONNECTIONS",
default.max_connections,
1,
1000,
),
)
@dataclass(frozen=True, slots=True)
class Settings:
# адрес прослушивания: локально только loopback, в образе ENV APP_HOST=0.0.0.0
host: str = DEFAULT_HOST
port: int = DEFAULT_PORT
log_level: str = DEFAULT_LOG_LEVEL
# секунды, которые uvicorn дорабатывает начатые запросы после SIGTERM;
# docker stop шлёт SIGKILL через 10 с, поэтому не больше 9
shutdown_timeout: int = DEFAULT_SHUTDOWN_TIMEOUT
keep_alive: int = DEFAULT_KEEP_ALIVE
# X-Instance-Id этого процесса; from_env берёт APP_INSTANCE_ID или
# hostname
instance_id: str = "local"
# секунды жизни сессии с момента входа; запросы и рестарт не продлевают
session_ttl: int = DEFAULT_SESSION_TTL
# секунды, в течение которых повтор с тем же Idempotency-Key отдаёт
# прежний результат; позже ключ можно занять заново
idempotency_ttl: int = DEFAULT_IDEMPOTENCY_TTL
kdf_concurrency: int = DEFAULT_KDF_CONCURRENCY
database: Database = Database()
cache: Cache = Cache()
@classmethod
def from_env(cls, env: Mapping[str, str] | None = None) -> Self:
"""Настройки из окружения; неверное значение — `ConfigError`."""
env = os.environ if env is None else env
log_level = _text(env, "LOG_LEVEL", DEFAULT_LOG_LEVEL).upper()
if log_level not in LOG_LEVELS:
raise ConfigError(
f"LOG_LEVEL must be one of {', '.join(LOG_LEVELS)}, got {log_level!r}",
)
return cls(
host=_text(env, "APP_HOST", DEFAULT_HOST),
port=_int(env, "APP_PORT", DEFAULT_PORT, 1, 65535),
log_level=log_level,
shutdown_timeout=_int(
env,
"SHUTDOWN_TIMEOUT",
DEFAULT_SHUTDOWN_TIMEOUT,
1,
9,
),
keep_alive=_int(
env,
"KEEP_ALIVE_TIMEOUT",
DEFAULT_KEEP_ALIVE,
1,
3600,
),
instance_id=_instance_id(env),
session_ttl=_int(
env,
"SESSION_TTL_SECONDS",
DEFAULT_SESSION_TTL,
1,
MAX_SESSION_TTL,
),
idempotency_ttl=_int(
env,
"IDEMPOTENCY_TTL_SECONDS",
DEFAULT_IDEMPOTENCY_TTL,
1,
MAX_SESSION_TTL,
),
kdf_concurrency=_int(
env,
"KDF_CONCURRENCY",
DEFAULT_KDF_CONCURRENCY,
1,
64,
),
database=Database.from_env(env),
cache=Cache.from_env(env),
)
+67
View File
@@ -0,0 +1,67 @@
"""Константы, одинаковые на всех установках.
Лимиты взяты из contracts/openapi.json и contracts/README.md. Это часть
контракта: значения не меняются и не выносятся в настройки.
"""
# пути
API_PREFIX = "/api/v1"
HEALTH_LIVE_PATH = "/health/live"
HEALTH_READY_PATH = "/health/ready"
HEALTH_PATHS = frozenset({HEALTH_LIVE_PATH, HEALTH_READY_PATH})
SESSIONS_PATH = f"{API_PREFIX}/auth/sessions"
# заголовки
REQUEST_ID_HEADER = "X-Request-Id"
AUTHORIZATION_HEADER = "Authorization"
# с лабы 3: какая реплика ответила (каждый ответ API) и ключ повтора
# отправки сообщения
INSTANCE_ID_HEADER = "X-Instance-Id"
IDEMPOTENCY_KEY_HEADER = "Idempotency-Key"
# пользователь
USERNAME_PATTERN = r"^[a-z0-9_]{3,32}$"
DISPLAY_NAME_MAX_LENGTH = 100
# пароль: 12–128 Unicode code points, хэшируется целиком как UTF-8
PASSWORD_MIN_LENGTH = 12
PASSWORD_MAX_LENGTH = 128
# начало строки Argon2id: CHECK в БД не даёт записать пароль иначе
PASSWORD_HASH_PREFIX = "$argon2id$"
# сессия
# байты случайности токена: 256 бит, 43 символа base64url
SESSION_TOKEN_BYTES = 32
# в БД хранится SHA-256 токена, а не токен
TOKEN_HASH_BYTES = 32
# realm в WWW-Authenticate у ответов 401
AUTH_REALM = "messenger"
# чат
CHAT_TITLE_MAX_LENGTH = 100
CHAT_MEMBERS_MAX = 100
# сообщение
MESSAGE_TEXT_MAX_LENGTH = 4000
# ключ идемпотентности отправки (лаба 3): ASCII, 1–128 символов целиком
IDEMPOTENCY_KEY_PATTERN = r"^[A-Za-z0-9._:-]{1,128}$"
# в БД хранится SHA-256 канонического тела запроса, а не тело
REQUEST_HASH_BYTES = 32
# пагинация
PAGE_LIMIT_MIN = 1
PAGE_LIMIT_MAX = 100
PAGE_LIMIT_DEFAULT = 50
# PostgreSQL
# имя соединений сервиса в pg_stat_activity
DB_APPLICATION_NAME = "mtusi-messenger"
# секунды на SELECT 1 в /health/ready
READINESS_TIMEOUT = 2.0
# секунды на мягкое закрытие соединения; дальше asyncpg обрывает его
DB_CLOSE_TIMEOUT = 2.0
# кэш (Valkey)
# начало ключей; v1 — формат значения: новый формат — v2, старые ключи
# тогда просто не читаются
CACHE_KEY_PREFIX = "messenger:v1"
+168
View File
@@ -0,0 +1,168 @@
"""PostgreSQL: engine с ограниченным пулом, срок операции, отказ → 503.
`Db` — то, через что хранилище ходит в базу. Одна операция хранилища —
одна транзакция `transaction()`: commit при выходе, откат при ошибке. Вся
операция — ожидание пула, подключение, запросы и commit — ограничена
`DB_OPERATION_TIMEOUT`: зависший сервер не держит запрос бесконечно.
Ошибки, которые значат «базы нет или она не отвечает», превращаются в
`Unavailable` (503) со строкой `warning` в журнале; остальные (нарушение
ограничения, синтаксис) идут дальше как есть: это дефект или доменная
ошибка, а не отказ хранилища.
Engine открывает соединения лениво: без PostgreSQL процесс стартует,
а `/health/ready` отвечает 503.
"""
import asyncio
from collections.abc import AsyncIterator
from contextlib import asynccontextmanager
import asyncpg
from sqlalchemy import URL, text
from sqlalchemy import exc as sa_exc
from sqlalchemy.ext.asyncio import AsyncConnection, AsyncEngine, create_async_engine
from src.config import Database as DatabaseSettings
from src.constants import DB_APPLICATION_NAME, DB_CLOSE_TIMEOUT, READINESS_TIMEOUT
from src.errors import Unavailable
from src.log import get_logger
log = get_logger(__name__)
# SQLSTATE «база недоступна»: класс 08 — ошибки соединения, 57014 —
# сработал statement_timeout, 57P01–57P03 — сервер останавливается или
# ещё не принимает подключения
UNAVAILABLE_SQLSTATES = ("08", "57014", "57P01", "57P02", "57P03")
# длина текста ошибки в журнале: одна строка, без простыни SQLAlchemy
_ERROR_TEXT_LIMIT = 300
class BoundedCloseConnection(asyncpg.Connection):
"""Соединение asyncpg, мягкое закрытие которого ограничено сроком.
Прерванный по сроку запрос SQLAlchemy закрывает соединение мягко, а
asyncpg при этом ждёт ответа сервера без ограничения: замёрзший
PostgreSQL держал бы запрос до разморозки. Здесь закрытие ограничено
`DB_CLOSE_TIMEOUT`, дальше asyncpg обрывает соединение.
"""
# сигнатура — как у asyncpg.Connection.close: SQLAlchemy зовёт её так
async def close(self, *, timeout: float | None = None) -> None: # noqa: ASYNC109
await asyncio.wait_for(
super().close(timeout=timeout), timeout or DB_CLOSE_TIMEOUT
)
def database_url(settings: DatabaseSettings) -> URL:
"""URL драйвера asyncpg; пароль экранирует `URL.create`, строку не собираем."""
return URL.create(
"postgresql+asyncpg",
username=settings.user,
password=settings.password,
host=settings.host,
port=settings.port,
database=settings.name,
)
def create_engine(settings: DatabaseSettings) -> AsyncEngine:
"""Engine с ограниченным пулом и таймаутами из настроек."""
return create_async_engine(
database_url(settings),
pool_size=settings.pool_size,
max_overflow=settings.pool_overflow,
pool_timeout=settings.pool_timeout,
# после рестарта PostgreSQL соединения пула мертвы: проверка при
# выдаче не даёт первому запросу получить ошибку
pool_pre_ping=True,
# текст ошибки драйвера уходит в журнал: без этого в нём были бы
# параметры SQL — тексты сообщений, хэши паролей и токенов
hide_parameters=True,
connect_args={
"timeout": settings.connect_timeout,
# command_timeout asyncpg не задан: на зависшем сервере он
# отменяет запрос через новое соединение и ждёт без срока
"connection_class": BoundedCloseConnection,
"server_settings": {
"application_name": DB_APPLICATION_NAME,
"statement_timeout": str(settings.statement_timeout_ms),
},
},
)
def is_unavailable(error: BaseException) -> bool:
"""Ошибка значит «PostgreSQL недоступен» (→ 503), а не дефект (→ 500).
Остановленный сервер — `ConnectionRefusedError`, неразрешимое имя —
`socket.gaierror`, срок операции — `TimeoutError`: всё это `OSError`.
Пул исчерпан — `sqlalchemy.exc.TimeoutError`. Оборванное соединение и
statement_timeout — `DBAPIError` с признаком или SQLSTATE.
"""
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
def _one_line(error: BaseException) -> str:
# TimeoutError от asyncio.timeout без текста — тогда repr
raw = " ".join(str(error).split()) or repr(error)
return raw[:_ERROR_TEXT_LIMIT]
class Db:
"""Engine процесса и границы транзакций хранилища."""
def __init__(self, settings: DatabaseSettings) -> None:
# имя базы: им же разделяются ключи кэша разных баз на одном Valkey
self.name = settings.name
self.engine = create_engine(settings)
self._operation_timeout = settings.operation_timeout
@asynccontextmanager
async def transaction(self) -> AsyncIterator[AsyncConnection]:
"""Одна транзакция со сроком; недоступность базы — `Unavailable`.
На сроке asyncio отменяет ожидание драйвера: SQLAlchemy считает
такое соединение испорченным и не возвращает его в пул, а его
закрытие ограничено `BoundedCloseConnection`. Поэтому замёрзший
сервер даёт 503 через `DB_OPERATION_TIMEOUT` + `DB_CLOSE_TIMEOUT`.
"""
try:
async with (
asyncio.timeout(self._operation_timeout),
self.engine.begin() as connection,
):
yield connection
except Exception as exc:
if not is_unavailable(exc):
raise
log.warning(
"database unavailable error_type=%s error=%s",
type(exc).__name__,
_one_line(exc),
)
raise Unavailable from exc
async def ping(self) -> None:
"""`SELECT 1` за `READINESS_TIMEOUT`; иначе `Unavailable`.
Не логирует: healthcheck спрашивает каждые несколько секунд.
Любая ошибка — 503: готовность не отвечает 500.
"""
try:
async with (
asyncio.timeout(READINESS_TIMEOUT),
self.engine.connect() as connection,
):
await connection.execute(text("SELECT 1"))
except Exception as exc:
raise Unavailable from exc
async def dispose(self) -> None:
await self.engine.dispose()
+90
View File
@@ -0,0 +1,90 @@
"""Доменные записи. Неизменяемые: хранилище отдаёт их наружу без копирования.
Пароль, его хэш и токен сессии в `User` не входят: хэш живёт только в
`Credentials` (вход), токен — только в `IssuedSession` (ответ на вход).
"""
from dataclasses import dataclass, field
from datetime import datetime
from uuid import UUID
@dataclass(frozen=True, slots=True)
class User:
id: UUID
username: str
display_name: str
created_at: datetime
@dataclass(frozen=True, slots=True)
class Credentials:
"""Пользователь и хэш его пароля: только для проверки при входе."""
user: User
password_hash: str = field(repr=False)
@dataclass(frozen=True, slots=True)
class Session:
"""Серверная сессия входа. Срок фиксируется при создании."""
id: UUID
user_id: UUID
expires_at: datetime
created_at: datetime
@dataclass(frozen=True, slots=True)
class IssuedSession:
"""Ответ на вход: токен отдаётся клиенту один раз и нигде не хранится."""
token: str = field(repr=False)
expires_at: datetime
user: User
@dataclass(frozen=True, slots=True)
class Identity:
"""Кто прислал запрос: действующая сессия и её владелец."""
session_id: UUID
user: User
@dataclass(frozen=True, slots=True)
class Chat:
id: UUID
title: str
# в порядке, переданном при создании
member_ids: tuple[UUID, ...]
created_at: datetime
@dataclass(frozen=True, slots=True)
class Message:
id: UUID
chat_id: UUID
sender_id: UUID
text: str
created_at: datetime
@dataclass(frozen=True, slots=True)
class SentMessage:
"""Итог отправки с ключом: новое сообщение или сохранённое прежнее.
`replayed` — ответ на повтор того же тела; клиенту оба случая
отдаются одинаково (201 и то же `Message`), флаг нужен журналу.
"""
message: Message
replayed: bool
@dataclass(frozen=True, slots=True)
class Page[T]:
"""Страница списка в порядке `(created_at, id)`."""
items: tuple[T, ...]
next_cursor: str | None
+63
View File
@@ -0,0 +1,63 @@
"""Остановка до старта сервера: SIGTERM и SIGINT во время импорта.
В контейнере `python -m src` — PID 1, а ядро не доставляет PID 1 сигнал,
для которого нет обработчика. Пока импортируется приложение (почти весь
старт, сотни миллисекунд при лимите в 1 CPU), обработчик uvicorn ещё не
стоит, и `docker stop` стартующей реплики ждал бы `stop_grace_period`
(10 с) и кончался SIGKILL. Это бьёт по поочерёдной замене: сбой на
середине убирает только что запущенную реплику (`scripts/rolling-update.sh`).
`install()` ставится первым делом в `src/__main__.py`, до импорта
приложения: сигнал до старта сервера пишет одну строку журнала и
завершает процесс с кодом 0 (запросов и соединений ещё нет).
`disarm()` — первая строка lifespan: дальше сигналы обрабатывает
uvicorn. После остановки сервера uvicorn возвращает этот обработчик и
повторяет пойманный сигнал — снятый обработчик его игнорирует, и
процесс выходит штатно, с кодом 0.
Только стандартная библиотека: модуль работает до настройки журнала и
до импорта `src.config`. Строка — в формате `src/log.py`, без rid.
"""
import contextlib
import os
import signal
import socket
import time
from types import FrameType
_armed = False
def _line(signum: int) -> bytes:
now = time.time()
stamp = time.strftime("%Y-%m-%dT%H:%M:%S", time.gmtime(now))
millis = int(now % 1 * 1000)
instance = os.environ.get("APP_INSTANCE_ID", "").strip() or socket.gethostname()
return (
f"{stamp}.{millis:03d}Z INFO src.early_stop [rid=-] "
f"stopped before startup signal={signal.Signals(signum).name} "
f"instance={instance}\n"
).encode()
def _stop(signum: int, _frame: FrameType | None) -> None:
if not _armed:
return
# ошибка записи выходу не мешает
with contextlib.suppress(OSError):
os.write(1, _line(signum))
os._exit(0)
def install() -> None:
global _armed
_armed = True
signal.signal(signal.SIGTERM, _stop)
signal.signal(signal.SIGINT, _stop)
def disarm() -> None:
"""Сервер стартовал: дальше сигналы — забота uvicorn."""
global _armed
_armed = False
+96
View File
@@ -0,0 +1,96 @@
"""Ошибки приложения. Каждая сама знает свой HTTP-статус и `code` контракта.
Сервисы, хранилище и пагинация бросают только их (не `HTTPException`).
В ответ `{"error": {...}}` их переводит один обработчик в
src/api/handlers.py. Текст ошибки уходит клиенту в `error.message`:
по-английски, без деталей реализации и без признаков существования
чужого объекта. У ответов 401 есть ещё `WWW-Authenticate`: вызов той
схемы, которой клиенту повторить запрос (`challenge`).
"""
from src.constants import AUTH_REALM
class AppError(Exception):
status_code: int = 400
code: str = "invalid_request"
default_message: str = "Invalid request"
# значение WWW-Authenticate; только у 401
challenge: str | None = None
def __init__(self, message: str | None = None) -> None:
super().__init__(message or self.default_message)
class InvalidRequest(AppError):
"""Запрос синтаксически верен, но нарушает правила контракта."""
class InvalidMembers(InvalidRequest):
"""Дубликаты в member_ids, неизвестный участник или нет вызывающего."""
default_message = "Invalid chat members"
class InvalidCursor(InvalidRequest):
"""Курсор повреждён или выдан для другого списка."""
default_message = "Invalid cursor"
class InvalidCredentials(AppError):
"""Вход отклонён: неверный пароль, неизвестный username или битый Basic.
Все причины — один ответ: по нему не узнать, есть ли пользователь.
"""
status_code = 401
code = "unauthorized"
default_message = "Invalid username or password"
challenge = f'Basic realm="{AUTH_REALM}", charset="UTF-8"'
class Unauthorized(AppError):
"""Нет Bearer-токена, он неизвестен, истёк или отозван."""
status_code = 401
code = "unauthorized"
default_message = "Valid bearer token is required"
challenge = f'Bearer realm="{AUTH_REALM}"'
class NotFound(AppError):
"""Объекта нет или он чужой: оба случая неразличимы для клиента."""
status_code = 404
code = "not_found"
default_message = "Not found"
class UsernameTaken(AppError):
status_code = 409
code = "conflict"
default_message = "Username is already taken"
class IdempotencyConflict(AppError):
"""Тот же `Idempotency-Key` уже принят с другим телом сообщения.
Ключ в текст не попадает: его выбирает клиент.
"""
status_code = 409
code = "conflict"
default_message = "Idempotency key was already used with a different request"
class Unavailable(AppError):
"""PostgreSQL недоступен или не ответил вовремя; приложение не готово.
Ограниченная ошибка вместо 500 и никогда не пропуск запроса как
анонимного: недоступность хранилища сессий — не отказ в доступе.
"""
status_code = 503
code = "unavailable"
default_message = "Service is temporarily unavailable"
+25
View File
@@ -0,0 +1,25 @@
"""HEALTHCHECK образа: `python -m src.healthcheck`.
Код выхода 0 — `/health/ready` ответил 200, иначе 1. Только стандартная
библиотека и без импорта приложения: в slim-образе нет curl, а проверка
должна быть дешёвой.
"""
import os
import sys
import urllib.error
import urllib.request
def main() -> int:
port = os.environ.get("APP_PORT", "8080")
url = f"http://127.0.0.1:{port}/health/ready"
try:
with urllib.request.urlopen(url, timeout=2) as response:
return 0 if response.status == 200 else 1
except (urllib.error.URLError, OSError):
return 1
if __name__ == "__main__":
sys.exit(main())
+81
View File
@@ -0,0 +1,81 @@
"""Логи обычным текстом в stdout: одна строка на событие.
Формат строки (перенос — только здесь, в логе строка одна):
2026-09-30T12:00:00.123Z INFO src.http [rid=3f2a...]
POST /api/v1/users -> 201 (1.4 ms)
`rid` — id запроса из contextvar, тот же, что в заголовке `X-Request-Id`
и в теле ошибки; вне запроса (старт, остановка) там `-`. Время — UTC.
Логи uvicorn идут через тот же handler и формат: по строкам «Shutting
down» и «Finished server process» видно, сколько заняла остановка.
"""
import logging
import time
from contextvars import ContextVar
from typing import Any
# ставит только RequestIdMiddleware
request_id_var: ContextVar[str] = ContextVar("request_id", default="-")
LOG_FORMAT = "%(asctime)s %(levelname)-7s %(name)s [rid=%(request_id)s] %(message)s"
class UtcFormatter(logging.Formatter):
"""Время записи в UTC с миллисекундами и суффиксом Z."""
converter = time.gmtime
default_time_format = "%Y-%m-%dT%H:%M:%S"
default_msec_format = "%s.%03dZ"
class RequestIdFilter(logging.Filter):
"""Добавляет в каждую запись поле `request_id` из contextvar."""
def filter(self, record: logging.LogRecord) -> bool:
record.request_id = request_id_var.get()
return True
def get_logger(name: str) -> logging.Logger:
"""Логгер модуля приложения: `get_logger(__name__)`."""
return logging.getLogger(name)
def logging_config(level: str) -> dict[str, Any]:
"""Конфиг для `uvicorn.run(log_config=...)`.
uvicorn применяет его сам через `logging.config.dictConfig` до старта
приложения, поэтому второй настройки логирования в коде нет.
"""
return {
"version": 1,
"disable_existing_loggers": False,
"filters": {"request_id": {"()": RequestIdFilter}},
"formatters": {"text": {"()": UtcFormatter, "fmt": LOG_FORMAT}},
"handlers": {
"stdout": {
"class": "logging.StreamHandler",
"stream": "ext://sys.stdout",
"formatter": "text",
"filters": ["request_id"],
},
},
"loggers": {
"src": {
"level": level,
"handlers": ["stdout"],
"propagate": False,
},
# uvicorn.error наследует handler от uvicorn: свой дал бы дубли
"uvicorn": {"level": "INFO", "handlers": ["stdout"], "propagate": False},
# access-лог пишет RequestIdMiddleware, у uvicorn он выключен
"uvicorn.access": {"level": "WARNING", "handlers": [], "propagate": False},
# сервис migrate: строки «Running upgrade ...» тем же форматом
"alembic": {"level": "INFO", "handlers": ["stdout"], "propagate": False},
# SQL и его параметры в журнал не идут: только предупреждения
"sqlalchemy": {"level": "WARNING"},
},
"root": {"level": "WARNING", "handlers": ["stdout"]},
}
+143
View File
@@ -0,0 +1,143 @@
"""Сборка приложения и запуск uvicorn.
Порядок middleware (снаружи внутрь): ServerErrorMiddleware Starlette →
RequestIdMiddleware → AuthenticationMiddleware (Bearer) →
ExceptionMiddleware → роутер. Последний `add_middleware` оказывается
снаружи, поэтому RequestIdMiddleware добавляется последним: ответ 401
получает тот же id, что и остальные ответы, и попадает в access-лог.
Хранилище собирается здесь: `CachedStorage` (Valkey) поверх
`PostgresStorage`. Engine и клиент Valkey открывают соединения лениво:
без PostgreSQL процесс стартует, а `/health/ready` отвечает 503.
С лабы 3 процессов несколько — реплики за HAProxy. В памяти процесса нет
ничего, от чего зависит корректность: сессии, данные и ключи
идемпотентности — в PostgreSQL, Valkey — общий кэш неизменяемых карточек.
Каждый процесс по-прежнему один, с одним event loop: масштабирование —
числом реплик, а не `--workers`.
"""
import os
import sys
from collections.abc import AsyncIterator
from contextlib import asynccontextmanager
import uvicorn
from fastapi import FastAPI
from starlette.middleware.authentication import AuthenticationMiddleware
from src import early_stop
from src.api import handlers
from src.api.identity import BearerBackend, on_auth_error
from src.api.request_id import RequestIdMiddleware
from src.api.routes import api_router, health_router
from src.cache import create_cache
from src.config import ConfigError, Settings
from src.db import Db
from src.log import get_logger, logging_config
from src.passwords import Passwords
from src.storage import CachedStorage, PostgresStorage
log = get_logger(__name__)
@asynccontextmanager
async def lifespan(app: FastAPI) -> AsyncIterator[None]:
# сервер стартовал: сигналы дальше обрабатывает uvicorn
early_stop.disarm()
settings: Settings = app.state.settings
if not settings.database.password:
log.warning("database password is empty")
if not settings.cache.password:
log.warning("cache password is empty")
# десятки миллисекунд CPU при старте: время ответа на вход с
# неизвестным username ровное с первого запроса
await app.state.passwords.prepare()
# instance — значение X-Instance-Id: по этой строке реплика в журнале
# сопоставляется с ответами, которые видел клиент
log.info(
"messenger started instance=%s host=%s port=%d pid=%d db=%s:%d/%s "
"cache=%s:%d pool=%d+%d session_ttl=%ds idempotency_ttl=%ds "
"shutdown_timeout=%ds keep_alive=%ds",
settings.instance_id,
settings.host,
settings.port,
os.getpid(),
settings.database.host,
settings.database.port,
settings.database.name,
settings.cache.host,
settings.cache.port,
settings.database.pool_size,
settings.database.pool_overflow,
settings.session_ttl,
settings.idempotency_ttl,
settings.shutdown_timeout,
settings.keep_alive,
)
app.state.ready = True
try:
yield
finally:
app.state.ready = False
# сюда uvicorn приходит после SIGTERM, когда начатые запросы
# закончились или вышел SHUTDOWN_TIMEOUT; данные уже в PostgreSQL
await app.state.db.dispose()
await app.state.cache.close()
log.info("messenger stopped instance=%s", settings.instance_id)
def create_app(settings: Settings | None = None) -> FastAPI:
"""Приложение с хранилищем на PostgreSQL и кэшем в Valkey."""
settings = settings or Settings.from_env()
app = FastAPI(
title="MTUSI Messenger — лабораторная 3",
version="1.3.0",
lifespan=lifespan,
)
db = Db(settings.database)
# ключи кэша — по имени базы: тестовая база не видит карточек рабочей
cache = create_cache(settings.cache, namespace=db.name)
app.state.settings = settings
app.state.db = db
app.state.cache = cache
app.state.storage = CachedStorage(
PostgresStorage(db),
cache,
chat_ttl=settings.cache.chat_ttl,
)
app.state.passwords = Passwords(settings.kdf_concurrency)
app.state.ready = False
handlers.install(app)
app.add_middleware(
AuthenticationMiddleware,
backend=BearerBackend(),
on_error=on_auth_error,
)
app.add_middleware(RequestIdMiddleware, instance_id=settings.instance_id)
app.include_router(health_router)
app.include_router(api_router)
return app
def run() -> None:
"""Точка входа `python -m src`: один процесс, один event loop."""
try:
settings = Settings.from_env()
except ConfigError as exc:
print(f"configuration error: {exc}", file=sys.stderr)
raise SystemExit(2) from None
# экземпляр, а не строка импорта: без reload и без --workers. Пул
# соединений считается на один процесс; процессов — число реплик
uvicorn.run(
create_app(settings),
host=settings.host,
port=settings.port,
log_config=logging_config(settings.log_level),
access_log=False,
server_header=False,
timeout_graceful_shutdown=settings.shutdown_timeout,
timeout_keep_alive=settings.keep_alive,
)
+88
View File
@@ -0,0 +1,88 @@
"""Keyset-пагинация по `(created_at, id)` и непрозрачный курсор.
Курсор — base64url без `=` от строки `<scope>|<микросекунды>|<id hex>`:
ключ последнего элемента страницы плюс область списка. Область —
`chat:<id>` для истории чата и `chats-of:<id>` для списка чатов
пользователя, поэтому курсор другого чата или пользователя не
принимается (400). Клиент курсор не разбирает, формат можно менять.
"""
import base64
import binascii
from collections.abc import Sequence
from datetime import UTC, datetime, timedelta
from typing import Protocol
from uuid import UUID
from src.domain import Page
from src.errors import InvalidCursor
type SortKey = tuple[datetime, UUID]
_EPOCH = datetime(1970, 1, 1, tzinfo=UTC)
_MICROSECOND = timedelta(microseconds=1)
_SEPARATOR = "|"
class Keyed(Protocol):
@property
def id(self) -> UUID: ...
@property
def created_at(self) -> datetime: ...
def sort_key(item: Keyed) -> SortKey:
"""Порядок контракта: `created_at`, при равенстве — `id` как UUID."""
return item.created_at, item.id
def history_scope(chat_id: UUID) -> str:
return f"chat:{chat_id}"
def chat_list_scope(user_id: UUID) -> str:
return f"chats-of:{user_id}"
def encode_cursor(scope: str, key: SortKey) -> str:
created_at, item_id = key
micros = (created_at - _EPOCH) // _MICROSECOND
raw = _SEPARATOR.join((scope, str(micros), item_id.hex))
return base64.urlsafe_b64encode(raw.encode()).rstrip(b"=").decode("ascii")
def decode_cursor(cursor: str | None, scope: str) -> SortKey | None:
"""Ключ, после которого начинается страница; нет курсора — `None`.
Битый курсор или курсор другой области — `InvalidCursor`.
"""
if cursor is None:
return None
try:
padded = cursor + "=" * (-len(cursor) % 4)
# Нестрогий декодер молча игнорировал посторонние символы курсора.
raw = base64.b64decode(
padded.encode("ascii"), altchars=b"-_", validate=True
).decode()
cursor_scope, micros, item_hex = raw.split(_SEPARATOR)
created_at = _EPOCH + int(micros) * _MICROSECOND
item_id = UUID(hex=item_hex)
except (ValueError, UnicodeError, binascii.Error, OverflowError):
raise InvalidCursor from None
if cursor_scope != scope:
raise InvalidCursor
return created_at, item_id
def make_page[T: Keyed](rows: Sequence[T], *, limit: int, scope: str) -> Page[T]:
"""Страница из выборки длиной до `limit + 1`.
Лишний элемент значит, что дальше есть ещё записи. Курсор строится по
последнему элементу страницы, а не по лишнему: тот придёт первым на
следующей странице.
"""
items = tuple(rows[:limit])
if len(rows) <= limit:
return Page(items=items, next_cursor=None)
return Page(items=items, next_cursor=encode_cursor(scope, sort_key(items[-1])))
+74
View File
@@ -0,0 +1,74 @@
"""Хэширование паролей: Argon2id в потоке с отдельным лимитом.
Профиль RFC 9106 low-memory (t=3, m=64 MiB, p=4) назван явно, а не взят
умолчанием argon2-cffi: обновление библиотеки не поменяет его молча. Один
хэш — десятки миллисекунд CPU и 64 MiB памяти, поэтому он считается в
потоке, а не в event loop (иначе один вход останавливал бы все запросы
процесса), и не больше `KDF_CONCURRENCY` хэшей одновременно: общий пул
потоков anyio на 40 потоков дал бы до 2,5 GiB памяти.
Пароль хэшируется целиком как UTF-8, без обрезки: bcrypt не подходит,
он режет пароль на 72 байтах, а 128 code points занимают до 512 байт.
"""
import secrets
import anyio
from anyio import to_thread
from argon2 import PasswordHasher, profiles
from argon2.exceptions import VerifyMismatchError
class Passwords:
def __init__(self, concurrency: int) -> None:
self._hasher = PasswordHasher.from_parameters(profiles.RFC_9106_LOW_MEMORY)
self._limiter = anyio.CapacityLimiter(concurrency)
# хэш для неизвестного username; считает lifespan при старте
self._dummy_hash: str | None = None
async def hash(self, password: str) -> str:
"""Строка Argon2id с параметрами и солью."""
return await to_thread.run_sync(
self._hasher.hash,
password,
limiter=self._limiter,
)
async def verify(self, *, password: str, password_hash: str | None) -> bool:
"""Подходит ли пароль к хэшу.
`password_hash=None` — пользователя нет. Пароль всё равно
проверяется, против фиктивного хэша: время ответа не выдаёт,
существует ли username.
"""
if password_hash is None:
await to_thread.run_sync(
self._matches,
await self.prepare(),
password,
limiter=self._limiter,
)
return False
return await to_thread.run_sync(
self._matches,
password_hash,
password,
limiter=self._limiter,
)
async def prepare(self) -> str:
"""Фиктивный хэш, один на процесс.
Lifespan вызывает его при старте: иначе первый вход с неизвестным
username считал бы хэш и проверку — вдвое дольше неверного пароля.
"""
if self._dummy_hash is None:
self._dummy_hash = await self.hash(secrets.token_urlsafe(16))
return self._dummy_hash
def _matches(self, password_hash: str, password: str) -> bool:
# повреждённый хэш (InvalidHashError) — дефект, а не неверный пароль
try:
return self._hasher.verify(password_hash, password)
except VerifyMismatchError:
return False
+93
View File
@@ -0,0 +1,93 @@
# src/services/ — бизнес-логика
## Правила
- Класс на домен: `UserService`, `SessionService`, `ChatService`,
`MessageService`. Конструктор принимает `Storage` (Protocol), не
реализацию; `UserService` и `SessionService` — ещё `Passwords`,
`SessionService` — срок сессии. Сервис создаётся на запрос фабрикой из
`api/deps.py` (`SessionService` — ещё и `BearerBackend` в
`api/identity.py`); состояния у него нет.
- Публичные методы — `async def` и keyword-only (`*,`).
- Сервис не знает про HTTP и про SQL: не импортирует fastapi, starlette,
pydantic, sqlalchemy, `src.db`, `src.cache`; не принимает модели API и
`Request`, не возвращает словари. Вход — примитивы и `UUID`, выход —
объекты `src/domain.py`.
- Ошибки — только классы из `src/errors.py`. `Unavailable` из хранилища
сервис не ловит: 503 должен дойти до клиента.
- Проверка доступа к чату — одна функция `access.chat_of_member()`.
Сервисы не вызывают друг друга: общий код — в функции модуля
`access.py` или новом модуле рядом.
- `id` и `created_at` сервис не назначает: это делает хранилище внутри
своей транзакции.
## Пароли и сессии
- Пароль хэшируется `Passwords.hash()` (Argon2id в потоке, лимит
`KDF_CONCURRENCY`) **до** обращения к БД: соединение пула не ждёт KDF.
- Вход (`SessionService.login`) — две операции хранилища: чтение хэша
(своя транзакция закрыта до KDF), проверка пароля вне БД, затем
создание сессии. Неизвестный username проверяется против фиктивного
хэша: время ответа не выдаёт, есть ли пользователь. Ошибка одна —
`InvalidCredentials`.
- Токен — `secrets.token_urlsafe(32)`; в хранилище уходит только
`hash_token(token)` (SHA-256). Токен возвращается клиенту один раз
(`IssuedSession`) и больше нигде не живёт.
- `authenticate` — один запрос хранилища по хэшу токена; нет токена или
сессии — `Unauthorized`. Срок не продлевается.
- `revoke` удаляет только текущую сессию; повторный выход тем же токеном
до сервиса не дойдёт (401 в middleware).
## Отправка с ключом идемпотентности (лаба 3)
- `MessageService(storage, key_ttl=IDEMPOTENCY_TTL_SECONDS)`;
`send(chat_id, sender_id, text, idempotency_key)`.
- Порядок: сессию уже проверил middleware, ключ и тело — схема ручки;
здесь членство (`chat_of_member` → `NotFound`, 404), затем один вызов
`storage.create_message(..., key, request_hash, key_ttl)`. Повтор
проходит членство и сессию заново: посторонний с чужим ключом — 404,
отозванный токен — 401.
- `request_hash(text=...)` — SHA-256 канонического JSON тела
(`sort_keys`, без пробелов, UTF-8), собранного из **разобранных** полей:
другая запись того же JSON — тот же хэш. Новое поле тела (с лабы 4 —
`attachment_ids`) добавляется сюда со значением по умолчанию, иначе
отсутствующее поле и явное значение по умолчанию дадут разные хэши.
- Решение «новое / повтор / 409», срок ключа и атомарность — в
хранилище, одной транзакцией (`storage/AGENTS.md`). Сервис не держит ни
ключей, ни результатов в памяти процесса: повтор может прийти на другую
реплику.
- Лог: `message created …` или `message replayed …` с `message_id`,
`chat_id`, `length`, `replayed`; ключ и текст — никогда.
## Что проверяет сервис, а что — другие
| Правило | Где |
|---|---|
| форма тела, длины, пустые строки, лишние поля, длина пароля | `api/schemas.py` |
| формат Basic, длина пароля при входе | `api/deps.py` (`parse_basic`) |
| дубликаты в `member_ids`, вызывающий в списке | `ChatService.create` |
| участники существуют | хранилище (`create_chat`, в той же транзакции) |
| username уникален | хранилище (`create_user`, уникальный индекс) |
| пользователь — участник чата (GET чата, история, отправка) | `access.chat_of_member` (карточка из кэша или БД) |
| отправитель — участник (страховка) | внешний ключ `messages → chat_members` |
| `Idempotency-Key` есть и по шаблону | схема ручки (`api/routes/messages.py`) |
| повтор того же тела / другое тело / срок ключа | хранилище (`create_message`, одна транзакция) |
| курсор разбирается и относится к этому списку | `pagination.decode_cursor` из сервиса |
| пароль верный, сессия действует | `SessionService` |
## Логи
- Логгер модуля: `log = get_logger(__name__)`.
- `info` на каждое изменение состояния (пользователь, сессия, чат,
сообщение созданы; сессия отозвана) и на отказ по бизнес-правилу
(username занят, неверные участники); `warning` — неудачный вход.
Чтения не логируются: access-строку и так пишет middleware.
- В строке — id и счётчики: `user_id=`, `session_id=`, `chat_id=`,
`message_id=`, `members=`, `length=`, `ttl=`. Никогда — `text`,
`display_name`, `title`, `username`, пароль, токен и их хэши.
## Тесты
Новое правило сервиса — тест в `student-tests/` через HTTP (статус и
форма ошибки). Юнит-тесты сервиса с подменой хранилища допустимы, но
не заменяют HTTP-тест.
+11
View File
@@ -0,0 +1,11 @@
from src.services.chats import ChatService
from src.services.messages import MessageService
from src.services.sessions import SessionService
from src.services.users import UserService
__all__ = [
"ChatService",
"MessageService",
"SessionService",
"UserService",
]
+21
View File
@@ -0,0 +1,21 @@
"""Проверка доступа к чату — общая для сервисов чатов и сообщений."""
from uuid import UUID
from src.domain import Chat
from src.errors import NotFound
from src.storage import Storage
async def chat_of_member(storage: Storage, *, chat_id: UUID, user_id: UUID) -> Chat:
"""Чат, если пользователь в нём состоит; иначе `NotFound`.
Несуществующий и чужой чат неразличимы: 404 не раскрывает, что чат
есть. Состав чата после создания не меняется, поэтому результат
проверки (в том числе по карточке из кэша) не устаревает до конца
запроса.
"""
chat = await storage.get_chat(chat_id)
if chat is None or user_id not in chat.member_ids:
raise NotFound
return chat
+56
View File
@@ -0,0 +1,56 @@
from collections.abc import Sequence
from uuid import UUID
from src.domain import Chat, Page
from src.errors import InvalidMembers
from src.log import get_logger
from src.pagination import chat_list_scope, decode_cursor, make_page
from src.services.access import chat_of_member
from src.storage import Storage
log = get_logger(__name__)
class ChatService:
def __init__(self, storage: Storage) -> None:
self._storage = storage
async def create(
self,
*,
creator_id: UUID,
title: str,
member_ids: Sequence[UUID],
) -> Chat:
if len(set(member_ids)) != len(member_ids):
log.info("chat rejected: duplicate members count=%d", len(member_ids))
raise InvalidMembers
if creator_id not in member_ids:
log.info("chat rejected: creator is not a member")
raise InvalidMembers
try:
chat = await self._storage.create_chat(title=title, member_ids=member_ids)
except InvalidMembers:
log.info("chat rejected: unknown members")
raise
log.info(
"chat created chat_id=%s members=%d",
chat.id,
len(chat.member_ids),
)
return chat
async def get(self, *, chat_id: UUID, user_id: UUID) -> Chat:
return await chat_of_member(self._storage, chat_id=chat_id, user_id=user_id)
async def list_for(
self,
*,
user_id: UUID,
limit: int,
cursor: str | None,
) -> Page[Chat]:
scope = chat_list_scope(user_id)
after = decode_cursor(cursor, scope)
rows = await self._storage.list_chats_of(user_id, after=after, limit=limit + 1)
return make_page(rows, limit=limit, scope=scope)
+87
View File
@@ -0,0 +1,87 @@
import hashlib
import json
from datetime import timedelta
from uuid import UUID
from src.domain import Message, Page
from src.log import get_logger
from src.pagination import decode_cursor, history_scope, make_page
from src.services.access import chat_of_member
from src.storage import Storage
log = get_logger(__name__)
def request_hash(*, text: str) -> bytes:
"""SHA-256 канонического JSON тела отправки.
Тело собирается из уже разобранных полей: пробелы, `\\u`-экранирование
и порядок ключей исходного JSON на хэш не влияют — это «тот же JSON»
из контракта. Новое поле тела (с лабы 4 — `attachment_ids`)
добавляется сюда со значением по умолчанию: отсутствующее поле должно
давать тот же хэш, что явное значение по умолчанию.
"""
canonical = json.dumps(
{"text": text},
ensure_ascii=False,
sort_keys=True,
separators=(",", ":"),
)
return hashlib.sha256(canonical.encode()).digest()
class MessageService:
def __init__(self, storage: Storage, *, key_ttl: int) -> None:
self._storage = storage
self._key_ttl = timedelta(seconds=key_ttl)
async def send(
self,
*,
chat_id: UUID,
sender_id: UUID,
text: str,
idempotency_key: str,
) -> Message:
"""Отправка с ключом идемпотентности.
Порядок проверок: сессию уже проверил middleware (401), ключ и
тело — схема ручки (400), здесь членство (404) и ключ (409).
Повтор проходит членство заново, как и проверку сессии.
"""
# членство — по карточке чата (из кэша, если она там есть); состав
# чата не меняется, а внешние ключи сообщения и ключа — страховка
await chat_of_member(self._storage, chat_id=chat_id, user_id=sender_id)
sent = await self._storage.create_message(
chat_id=chat_id,
sender_id=sender_id,
text=text,
key=idempotency_key,
request_hash=request_hash(text=text),
key_ttl=self._key_ttl,
)
# ни текст, ни ключ в лог не пишутся: ключ выбирает клиент, в нём
# может оказаться что угодно; повтор виден по replayed
log.info(
"message %s message_id=%s chat_id=%s length=%d replayed=%s",
"replayed" if sent.replayed else "created",
sent.message.id,
chat_id,
len(text),
str(sent.replayed).lower(),
)
return sent.message
async def history(
self,
*,
chat_id: UUID,
user_id: UUID,
limit: int,
cursor: str | None,
) -> Page[Message]:
await chat_of_member(self._storage, chat_id=chat_id, user_id=user_id)
scope = history_scope(chat_id)
after = decode_cursor(cursor, scope)
rows = await self._storage.list_messages(chat_id, after=after, limit=limit + 1)
return make_page(rows, limit=limit, scope=scope)
+93
View File
@@ -0,0 +1,93 @@
"""Вход по паролю, проверка Bearer-токена, выход.
Токен — `secrets.token_urlsafe(32)`: 256 бит случайности, ничего не
кодирует (не username, не UUID, не JWT). В БД хранится только SHA-256
токена: быстрого хэша достаточно, перебирать 256 бит нечего. Медленный
KDF нужен паролю, который выбирает человек.
Срок сессии фиксируется при входе (`SESSION_TTL_SECONDS`). Ни запросы,
ни рестарт его не продлевают. Каждый запрос — поиск сессии в PostgreSQL,
без кэша: отзыв действует мгновенно.
"""
import hashlib
import secrets
from datetime import timedelta
from uuid import UUID
from src.constants import SESSION_TOKEN_BYTES
from src.domain import Identity, IssuedSession
from src.errors import InvalidCredentials, Unauthorized
from src.log import get_logger
from src.passwords import Passwords
from src.storage import Storage
log = get_logger(__name__)
def hash_token(token: str) -> bytes:
"""SHA-256 токена: по нему ищется сессия, сам токен не хранится."""
return hashlib.sha256(token.encode()).digest()
class SessionService:
def __init__(self, storage: Storage, passwords: Passwords, *, ttl: int) -> None:
self._storage = storage
self._passwords = passwords
self._ttl = timedelta(seconds=ttl)
async def login(self, *, username: str, password: str) -> IssuedSession:
"""Проверка пароля и новая сессия.
Две операции хранилища: чтение хэша закрывает свою транзакцию до
KDF, поэтому соединение пула не ждёт хэш и очередь лимита.
Пароли и пользователи не меняются: между операциями проверять
нечего.
"""
credentials = await self._storage.get_credentials(username)
# неизвестный username проверяется против фиктивного хэша: время
# ответа то же, что у неверного пароля
valid = await self._passwords.verify(
password=password,
password_hash=credentials.password_hash if credentials else None,
)
if credentials is None or not valid:
# без username и пароля: по журналу не перебрать имена
log.warning("login failed")
raise InvalidCredentials
token = secrets.token_urlsafe(SESSION_TOKEN_BYTES)
session = await self._storage.create_session(
user_id=credentials.user.id,
token_hash=hash_token(token),
ttl=self._ttl,
)
log.info(
"session created user_id=%s session_id=%s ttl=%ds",
session.user_id,
session.id,
self._ttl.total_seconds(),
)
return IssuedSession(
token=token,
expires_at=session.expires_at,
user=credentials.user,
)
async def authenticate(self, *, token: str | None) -> Identity:
"""Действующая сессия по Bearer-токену; иначе `Unauthorized`.
Недоступность БД сюда не превращается: `Unavailable` идёт дальше
(503) — отказ хранилища не делает токен недействительным и не
пропускает запрос как анонимный.
"""
if not token:
raise Unauthorized
identity = await self._storage.get_identity(hash_token(token))
if identity is None:
raise Unauthorized
return identity
async def revoke(self, *, session_id: UUID) -> None:
deleted = await self._storage.delete_session(session_id)
# False — параллельный выход тем же токеном уже удалил сессию
log.info("session revoked session_id=%s already=%s", session_id, not deleted)
+30
View File
@@ -0,0 +1,30 @@
from src.domain import User
from src.errors import UsernameTaken
from src.log import get_logger
from src.passwords import Passwords
from src.storage import Storage
log = get_logger(__name__)
class UserService:
def __init__(self, storage: Storage, passwords: Passwords) -> None:
self._storage = storage
self._passwords = passwords
async def register(
self, *, username: str, display_name: str, password: str
) -> User:
# KDF до обращения к БД: соединение пула не ждёт хэш
password_hash = await self._passwords.hash(password)
try:
user = await self._storage.create_user(
username=username,
display_name=display_name,
password_hash=password_hash,
)
except UsernameTaken:
log.info("registration rejected: username taken")
raise
log.info("user registered user_id=%s", user.id)
return user
+108
View File
@@ -0,0 +1,108 @@
# src/storage/ — хранилище
`base.py` — `Storage` (Protocol): что сервисы могут просить у слоя
данных. `postgres.py` — `PostgresStorage`, источник истины.
`cached.py` — `CachedStorage`: тот же интерфейс, карточка чата через
Valkey, остальное — делегирование в PostgreSQL. `tables.py` — схема в
SQLAlchemy Core для запросов и `alembic check`. Собирает цепочку
`main.py`: `CachedStorage(PostgresStorage(db), cache)`.
## Инварианты `PostgresStorage` (атомарность и гонки — рубрика «4»)
1. **Один публичный метод — одна транзакция** `self._db.transaction()`:
проверка → назначение `id`/`created_at` → все вставки → commit до
возврата. 201 уходит клиенту только после commit. Исключение внутри —
откат целиком: чат не останется без участников (проверяет
`test_members_failure_rolls_back_chat`).
2. **Гонки закрывают ограничения PostgreSQL**, а не «сначала SELECT,
потом INSERT»: username — `INSERT ... ON CONFLICT (username) DO
NOTHING RETURNING` (пустой RETURNING → `UsernameTaken`); отправитель
— составной внешний ключ `(chat_id, sender_id) → chat_members`
(нарушение 23503 → `NotFound`). Явных блокировок нет: пользователи и
участники не меняются и не удаляются.
3. **`created_at` — `self._clock.now()`** перед вставкой; у участника —
копия времени чата (по ней keyset списка чатов). Время БД (`now()`)
не используется: порядок, который видит клиент, зависит от одних
часов.
4. **Запросы — SQLAlchemy Core с параметрами** (`select`, `insert`,
`pg_insert`, `tuple_`). SQL из f-строк и конкатенации запрещён;
`text()` — только без пользовательских значений.
5. **Keyset без OFFSET и count(\*)**: `WHERE chat_id = :id AND
(created_at, id) > (:t, :i) ORDER BY created_at, id LIMIT :n` по
индексу `ix_messages_chat_id_created_at_id`; список чатов — по
`ix_chat_members_user_id_created_at_chat_id`. Страница не читает
историю до курсора — это доказали планы `EXPLAIN (ANALYZE, BUFFERS)`
лабы 2 (её репозиторий, `evidence/bench/`).
6. **Хранилище бросает доменные ошибки** там, где сработало
ограничение: `UsernameTaken`, `InvalidMembers` (участника нет),
`NotFound` (внешний ключ сообщения или ключа идемпотентности),
`IdempotencyConflict` (ключ занят другим телом). Бизнес-правил
(членство, дубликаты в запросе) здесь нет — они в сервисах.
7. **Отказ базы — не здесь**: `Db.transaction()` (`src/db.py`) переводит
недоступность (остановлен, завис, пул исчерпан, `statement_timeout`,
обрыв) в `Unavailable` и пишет одну строку `warning`. Остальные
`DBAPIError` (нарушенный `CHECK`, синтаксис) — дефект, 500.
8. Хранилище не логирует и не импортирует `src.log`, fastapi, сервисы и
API. Наружу — только объекты `src/domain.py`, не `Row`.
## Отправка с ключом идемпотентности (`create_message`, лаба 3)
Одна транзакция, ключ — **раньше** сообщения:
1. Захват ключа одним выражением: `INSERT INTO idempotency_keys … ON
CONFLICT (user_id, chat_id, key) DO UPDATE SET request_hash,
message_id, created_at WHERE idempotency_keys.created_at < now − ttl
RETURNING message_id`. RETURNING не пуст — ключ новый или просроченный
(заменён тем же выражением, без DELETE и второй гонки); пуст — ключ
действует, а его строка заблокирована до конца транзакции.
2. Захватили — вставка сообщения с тем же `message_id`; внешний ключ
ключа на сообщение `DEFERRABLE INITIALLY DEFERRED` проверяется при
commit. Итог — `SentMessage(message, replayed=False)`.
3. Не захватили — чтение сохранённого (`request_hash` + сообщение через
JOIN). Хэш совпал — `SentMessage(сохранённое, replayed=True)`: тот же
`id` и `created_at`, ничего не пишется. Не совпал —
`IdempotencyConflict`, откат снимает блокировку.
Гонки: одновременные запросы с одним ключом (в том числе с разных
реплик) ждут друг друга на уникальном индексе; второй после commit
первого видит его строку и отдаёт повтор. Сбой до commit (отказ БД,
ошибка вставки сообщения) откатывает и ключ, и сообщение: транзиентная
ошибка результатом не фиксируется, повтор с тем же ключом безопасен.
Внешние ключи `(chat_id, автор) → chat_members` у ключа и сообщения —
страховка членства (нарушение → `NotFound`). Срок ключа считается по
часам приложения (`utc_now()`), как срок сессии. Просроченные ключи не
удаляются сами: занятый заново ключ заменяется, остальные копятся
(уборка — `DELETE … WHERE created_at < …` по индексу; ограничение в
`REPORT.md`). Ключи — только в PostgreSQL: в кэш их не класть.
## `CachedStorage` (кэш Valkey, уровень «4»)
- Кэшируется только неизменяемое — карточка чата (`id`, `title`,
`member_ids` в порядке создания, `created_at`), JSON под ключом
`messenger:v1:<имя базы>:chat:<id>`. Сессии, история и списки — нет:
logout должен действовать мгновенно, история меняется с каждой записью.
- Чтение: Valkey → при промахе PostgreSQL и запись в кэш. Отсутствующий
чат не кэшируется. Новый чат пишется в кэш **после** commit.
- Инвалидации нет: контракт не меняет и не удаляет чаты. Правка базы в
обход API (восстановление из backup) требует `FLUSHALL` после неё.
- Отказ Valkey — промах (`src/cache.py`): ответ тот же, из PostgreSQL.
- Новый метод `Storage` — делегирование здесь обязательно: класс
реализует протокол целиком, явными методами.
## Изменение интерфейса
Новый метод — сначала в `Storage` (`base.py`) с докстрингом: что
атомарно и какие ошибки, затем реализация в `postgres.py` (одна
транзакция), делегирование в `cached.py`. Сигнатура — только `domain`,
`UUID`, `SortKey`, `timedelta`, примитивы. Новая колонка, индекс,
ограничение — сначала в `tables.py` и новой ревизии
(`migrations/AGENTS.md`), `alembic check` без расхождений.
## Проверка
`make test-isolated` (в том числе `test_race.py`: 100 сообщений от 10
клиентов, гонка регистрации и гонка одного ключа через реплики) и `make
failure-checks` (откат чата и ключа, отказы БД и Valkey, пул, срок
ключа). Правка запроса истории, записи или индексов — ещё `make
bench-scaling-quick`: стоимость на запрос видна в `runs.csv`
(`db_cpu_us_per_req`).
+9
View File
@@ -0,0 +1,9 @@
from src.storage.base import Storage
from src.storage.cached import CachedStorage
from src.storage.postgres import PostgresStorage
__all__ = [
"CachedStorage",
"PostgresStorage",
"Storage",
]
+120
View File
@@ -0,0 +1,120 @@
"""Интерфейс хранилища: что сервисы могут просить у слоя данных.
Сервисы зависят от этого протокола, а не от реализации. Реализация —
`PostgresStorage` (`postgres.py`), поверх неё — `CachedStorage`
(`cached.py`) с кэшем карточек чатов в Valkey.
Каждый метод — одна атомарная операция: одна транзакция PostgreSQL. Id и
`created_at` назначает хранилище в той же операции, что и вставку, как
это делал бы `DEFAULT` в базе данных. Недоступность PostgreSQL —
`Unavailable` из любого метода.
"""
from collections.abc import Sequence
from datetime import timedelta
from typing import Protocol
from uuid import UUID
from src.domain import (
Chat,
Credentials,
Identity,
Message,
SentMessage,
Session,
User,
)
from src.pagination import SortKey
class Storage(Protocol):
async def ping(self) -> None:
"""Хранилище может обслуживать запросы; иначе `Unavailable`."""
...
async def create_user(
self,
*,
username: str,
display_name: str,
password_hash: str,
) -> User:
"""Новый пользователь; занятый username — `UsernameTaken`."""
...
async def get_credentials(self, username: str) -> Credentials | None:
"""Пользователь и хэш пароля для входа; нет такого — `None`."""
...
async def create_session(
self,
*,
user_id: UUID,
token_hash: bytes,
ttl: timedelta,
) -> Session:
"""Новая сессия; срок `created_at + ttl` фиксируется сейчас."""
...
async def get_identity(self, token_hash: bytes) -> Identity | None:
"""Действующая сессия по хэшу токена вместе с владельцем.
Неизвестный, истёкший и отозванный токен — одинаково `None`.
"""
...
async def delete_session(self, session_id: UUID) -> bool:
"""Отзыв; `False` — сессию уже удалил параллельный запрос."""
...
async def create_chat(self, *, title: str, member_ids: Sequence[UUID]) -> Chat:
"""Чат и все его участники — одной транзакцией.
Хотя бы один участник не существует — `InvalidMembers`, ничего не
создаётся. Сбой посреди операции откатывает и чат, и участников.
"""
...
async def get_chat(self, chat_id: UUID) -> Chat | None: ...
async def list_chats_of(
self,
user_id: UUID,
*,
after: SortKey | None,
limit: int,
) -> list[Chat]:
"""До `limit` чатов пользователя строго после ключа `after`."""
...
async def create_message(
self,
*,
chat_id: UUID,
sender_id: UUID,
text: str,
key: str,
request_hash: bytes,
key_ttl: timedelta,
) -> SentMessage:
"""Отправка с ключом идемпотентности — одной транзакцией.
Ключ `(sender_id, chat_id, key)` свободен или старше `key_ttl` —
ключ и новое сообщение фиксируются вместе. Ключ занят тем же
`request_hash` — прежнее сообщение (`replayed=True`), ничего не
пишется; другим — `IdempotencyConflict`. Конкурентные запросы с
одним ключом (с любых реплик) дают одно сообщение. Чата нет или
автор не участник — `NotFound`. Сбой до commit не оставляет ни
ключа, ни сообщения: повтор с тем же ключом безопасен.
"""
...
async def list_messages(
self,
chat_id: UUID,
*,
after: SortKey | None,
limit: int,
) -> list[Message]:
"""До `limit` сообщений чата строго после ключа `after`."""
...
+177
View File
@@ -0,0 +1,177 @@
"""Хранилище с кэшем карточек чатов в Valkey (уровень «4»).
`CachedStorage` реализует тот же `Storage` поверх `PostgresStorage`:
сервисы не знают, есть ли кэш. Кэшируется только карточка чата — `id`,
`title`, `member_ids` в порядке создания, `created_at`. Её читают три
самых частых запроса: `GET /chats/{id}`, `POST .../messages` и
`GET .../messages` (проверка членства).
- Источник истины — PostgreSQL. Чтение: Valkey → при промахе PostgreSQL
и запись в кэш (cache-aside). Чата нет — в кэш ничего не пишется.
- Новый чат пишется в кэш после commit: откат создания не оставит в кэше
чата, которого нет в базе.
- Инвалидации нет: по контракту чат и участники после создания не
меняются и не удаляются. Граница допущения — правка базы в обход API
(восстановление из backup): после неё кэш очищают `FLUSHALL`.
- Срок записи `CACHE_CHAT_TTL` ограничивает память, а не свежесть;
чтения его не продлевают.
- Сессии, история и списки чатов не кэшируются: сессию должен мгновенно
отзывать logout, история меняется с каждой записью.
- Отказ Valkey — промах (`src/cache.py`): ответ тот же, из PostgreSQL.
Ключ — `messenger:v1:<имя базы>:chat:<chat_id>`, значение — JSON.
"""
import json
from collections.abc import Sequence
from datetime import timedelta
from uuid import UUID
from src.cache import Cache
from src.clock import from_rfc3339, to_rfc3339
from src.constants import CACHE_KEY_PREFIX
from src.domain import (
Chat,
Credentials,
Identity,
Message,
SentMessage,
Session,
User,
)
from src.pagination import SortKey
from src.storage.base import Storage
def chat_key(namespace: str, chat_id: UUID) -> str:
return f"{CACHE_KEY_PREFIX}:{namespace}:chat:{chat_id}"
def dump_chat(chat: Chat) -> str:
return json.dumps(
{
"id": str(chat.id),
"title": chat.title,
"member_ids": [str(member_id) for member_id in chat.member_ids],
"created_at": to_rfc3339(chat.created_at),
},
ensure_ascii=False,
separators=(",", ":"),
)
def load_chat(value: str) -> Chat:
data = json.loads(value)
return Chat(
id=UUID(data["id"]),
title=data["title"],
member_ids=tuple(UUID(member_id) for member_id in data["member_ids"]),
created_at=from_rfc3339(data["created_at"]),
)
class CachedStorage:
def __init__(self, storage: Storage, cache: Cache, *, chat_ttl: int) -> None:
self._storage = storage
self._cache = cache
self._chat_ttl = chat_ttl
async def get_chat(self, chat_id: UUID) -> Chat | None:
key = chat_key(self._cache.namespace, chat_id)
cached = await self._cache.get(key)
if cached is not None:
return load_chat(cached)
chat = await self._storage.get_chat(chat_id)
if chat is not None:
await self._cache.set(key, dump_chat(chat), ttl=self._chat_ttl)
return chat
async def create_chat(self, *, title: str, member_ids: Sequence[UUID]) -> Chat:
chat = await self._storage.create_chat(title=title, member_ids=member_ids)
# чат уже зафиксирован: следующее чтение карточки попадёт в кэш
await self._cache.set(
chat_key(self._cache.namespace, chat.id),
dump_chat(chat),
ttl=self._chat_ttl,
)
return chat
# --- остальное — без кэша -----------------------------------------------
async def ping(self) -> None:
# кэш не критичен: без него обязательный путь идёт в PostgreSQL
await self._storage.ping()
async def create_user(
self,
*,
username: str,
display_name: str,
password_hash: str,
) -> User:
return await self._storage.create_user(
username=username,
display_name=display_name,
password_hash=password_hash,
)
async def get_credentials(self, username: str) -> Credentials | None:
return await self._storage.get_credentials(username)
async def create_session(
self,
*,
user_id: UUID,
token_hash: bytes,
ttl: timedelta,
) -> Session:
return await self._storage.create_session(
user_id=user_id,
token_hash=token_hash,
ttl=ttl,
)
async def get_identity(self, token_hash: bytes) -> Identity | None:
return await self._storage.get_identity(token_hash)
async def delete_session(self, session_id: UUID) -> bool:
return await self._storage.delete_session(session_id)
async def list_chats_of(
self,
user_id: UUID,
*,
after: SortKey | None,
limit: int,
) -> list[Chat]:
return await self._storage.list_chats_of(user_id, after=after, limit=limit)
async def create_message(
self,
*,
chat_id: UUID,
sender_id: UUID,
text: str,
key: str,
request_hash: bytes,
key_ttl: timedelta,
) -> SentMessage:
# ключи идемпотентности — только в PostgreSQL, в одной транзакции с
# сообщением: кэш отказывает и теряет данные, ему их не доверить
return await self._storage.create_message(
chat_id=chat_id,
sender_id=sender_id,
text=text,
key=key,
request_hash=request_hash,
key_ttl=key_ttl,
)
async def list_messages(
self,
chat_id: UUID,
*,
after: SortKey | None,
limit: int,
) -> list[Message]:
return await self._storage.list_messages(chat_id, after=after, limit=limit)
+386
View File
@@ -0,0 +1,386 @@
"""Хранилище лабы 2: PostgreSQL — источник истины.
Каждый публичный метод — одна транзакция `Db.transaction()`: проверка,
назначение id и времени, вставки — и commit до возврата. Ответ 201 уходит
клиенту только после commit. Ошибка внутри — откат целиком: создание
чата не оставит ни чата без участников, ни участников без чата.
Защиту от гонок дают ограничения PostgreSQL, а не проверки «сначала
SELECT, потом INSERT»: уникальность username — `ON CONFLICT DO NOTHING`
по уникальному индексу, участник и отправитель — внешние ключи. Запросы
— SQLAlchemy Core с параметрами, SQL из строк не собирается.
Хранилище бросает доменные ошибки там, где сработало ограничение:
`UsernameTaken` (уникальность), `InvalidMembers` (участника нет),
`NotFound` (внешний ключ сообщения или ключа идемпотентности),
`IdempotencyConflict` (ключ занят другим телом). Бизнес-правил
(членство, дубликаты в запросе) здесь нет — они в сервисах. Хранилище
не логирует: отказ базы пишет в журнал `Db.transaction()`.
"""
from collections.abc import Sequence
from datetime import timedelta
from uuid import UUID, uuid4
from sqlalchemy import Row, func, insert, select, tuple_
from sqlalchemy import delete as sa_delete
from sqlalchemy import exc as sa_exc
from sqlalchemy.dialects.postgresql import aggregate_order_by
from sqlalchemy.dialects.postgresql import insert as pg_insert
from src.clock import MonotonicClock, utc_now
from src.db import Db
from src.domain import (
Chat,
Credentials,
Identity,
Message,
SentMessage,
Session,
User,
)
from src.errors import IdempotencyConflict, InvalidMembers, NotFound, UsernameTaken
from src.pagination import SortKey
from src.storage.tables import (
chat_members,
chats,
idempotency_keys,
messages,
sessions,
users,
)
# SQLSTATE foreign_key_violation
_FK_VIOLATION = "23503"
_USER_COLUMNS = (users.c.id, users.c.username, users.c.display_name, users.c.created_at)
# участники в порядке member_ids при создании; отдельный алиас, чтобы не
# смешаться с chat_members внешнего запроса списка чатов
_member = chat_members.alias("member")
_MEMBER_IDS = (
select(func.array_agg(aggregate_order_by(_member.c.user_id, _member.c.position)))
.where(_member.c.chat_id == chats.c.id)
.scalar_subquery()
.label("member_ids")
)
_CHAT_COLUMNS = (chats.c.id, chats.c.title, _MEMBER_IDS, chats.c.created_at)
_MESSAGE_COLUMNS = (
messages.c.id,
messages.c.chat_id,
messages.c.sender_id,
messages.c.text,
messages.c.created_at,
)
def _user(row: Row) -> User:
return User(
id=row.id,
username=row.username,
display_name=row.display_name,
created_at=row.created_at,
)
def _chat(row: Row) -> Chat:
return Chat(
id=row.id,
title=row.title,
member_ids=tuple(row.member_ids),
created_at=row.created_at,
)
def _message(row: Row) -> Message:
return Message(
id=row.id,
chat_id=row.chat_id,
sender_id=row.sender_id,
text=row.text,
created_at=row.created_at,
)
class PostgresStorage:
def __init__(self, db: Db, clock: MonotonicClock | None = None) -> None:
self._db = db
self._clock = clock or MonotonicClock()
async def ping(self) -> None:
await self._db.ping()
# --- пользователи и сессии ---------------------------------------------
async def create_user(
self,
*,
username: str,
display_name: str,
password_hash: str,
) -> User:
user = User(
id=uuid4(),
username=username,
display_name=display_name,
created_at=self._clock.now(),
)
# уникальность держит индекс: из гонки регистраций одного username
# строку вставит ровно одна, остальные получат пустой RETURNING
statement = (
pg_insert(users)
.values(
id=user.id,
username=user.username,
display_name=user.display_name,
password_hash=password_hash,
created_at=user.created_at,
)
.on_conflict_do_nothing(index_elements=[users.c.username])
.returning(users.c.id)
)
async with self._db.transaction() as connection:
inserted = (await connection.execute(statement)).first()
if inserted is None:
raise UsernameTaken
return user
async def get_credentials(self, username: str) -> Credentials | None:
statement = select(*_USER_COLUMNS, users.c.password_hash).where(
users.c.username == username,
)
async with self._db.transaction() as connection:
row = (await connection.execute(statement)).first()
if row is None:
return None
return Credentials(user=_user(row), password_hash=row.password_hash)
async def create_session(
self,
*,
user_id: UUID,
token_hash: bytes,
ttl: timedelta,
) -> Session:
created_at = self._clock.now()
session = Session(
id=uuid4(),
user_id=user_id,
expires_at=created_at + ttl,
created_at=created_at,
)
statement = insert(sessions).values(
id=session.id,
user_id=session.user_id,
token_hash=token_hash,
created_at=session.created_at,
expires_at=session.expires_at,
)
async with self._db.transaction() as connection:
await connection.execute(statement)
return session
async def get_identity(self, token_hash: bytes) -> Identity | None:
# один запрос по уникальному индексу token_hash; срок сравнивается
# по часам приложения, которые его и поставили
statement = (
select(sessions.c.id.label("session_id"), *_USER_COLUMNS)
.join_from(sessions, users, sessions.c.user_id == users.c.id)
.where(
sessions.c.token_hash == token_hash, sessions.c.expires_at > utc_now()
)
)
async with self._db.transaction() as connection:
row = (await connection.execute(statement)).first()
if row is None:
return None
return Identity(session_id=row.session_id, user=_user(row))
async def delete_session(self, session_id: UUID) -> bool:
statement = (
sa_delete(sessions)
.where(sessions.c.id == session_id)
.returning(sessions.c.id)
)
async with self._db.transaction() as connection:
deleted = (await connection.execute(statement)).first()
return deleted is not None
# --- чаты ------------------------------------------------------------------
async def create_chat(self, *, title: str, member_ids: Sequence[UUID]) -> Chat:
chat = Chat(
id=uuid4(),
title=title,
member_ids=tuple(member_ids),
created_at=self._clock.now(),
)
# member_ids без дубликатов (проверил сервис), поэтому сравнение
# числа найденных пользователей с длиной списка точное
known = (
select(func.count()).select_from(users).where(users.c.id.in_(member_ids))
)
async with self._db.transaction() as connection:
# пользователей не удаляют: проверка до вставки не устареет,
# а внешний ключ участника — страховка на уровне БД
if await connection.scalar(known) != len(member_ids):
raise InvalidMembers
await connection.execute(
insert(chats).values(
id=chat.id, title=chat.title, created_at=chat.created_at
),
)
await connection.execute(
insert(chat_members).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 chat
async def get_chat(self, chat_id: UUID) -> Chat | None:
statement = select(*_CHAT_COLUMNS).where(chats.c.id == chat_id)
async with self._db.transaction() as connection:
row = (await connection.execute(statement)).first()
return None if row is None else _chat(row)
async def list_chats_of(
self,
user_id: UUID,
*,
after: SortKey | None,
limit: int,
) -> list[Chat]:
# keyset по индексу (user_id, created_at, chat_id) участников: их
# created_at равен времени чата, поэтому порядок — (created_at, id)
statement = (
select(*_CHAT_COLUMNS)
.join_from(chat_members, chats, chat_members.c.chat_id == chats.c.id)
.where(chat_members.c.user_id == user_id)
.order_by(chat_members.c.created_at, chat_members.c.chat_id)
.limit(limit)
)
if after is not None:
statement = statement.where(
tuple_(chat_members.c.created_at, chat_members.c.chat_id)
> tuple_(*after),
)
async with self._db.transaction() as connection:
rows = (await connection.execute(statement)).all()
return [_chat(row) for row in rows]
# --- сообщения -------------------------------------------------------------
async def create_message(
self,
*,
chat_id: UUID,
sender_id: UUID,
text: str,
key: str,
request_hash: bytes,
key_ttl: timedelta,
) -> SentMessage:
message = Message(
id=uuid4(),
chat_id=chat_id,
sender_id=sender_id,
text=text,
created_at=self._clock.now(),
)
# захват ключа под новое сообщение — одним выражением. Ключа нет или
# он просрочен — строка вставлена или заменена, RETURNING не пуст.
# Ключ действует — RETURNING пуст, а строка заблокирована до конца
# транзакции. Конкурентный захват того же ключа (с любой реплики)
# ждёт commit или отката первой транзакции на уникальном индексе
claim = pg_insert(idempotency_keys).values(
user_id=sender_id,
chat_id=chat_id,
key=key,
request_hash=request_hash,
message_id=message.id,
created_at=message.created_at,
)
claim = claim.on_conflict_do_update(
index_elements=[
idempotency_keys.c.user_id,
idempotency_keys.c.chat_id,
idempotency_keys.c.key,
],
set_={
"request_hash": claim.excluded.request_hash,
"message_id": claim.excluded.message_id,
"created_at": claim.excluded.created_at,
},
where=idempotency_keys.c.created_at < utc_now() - key_ttl,
).returning(idempotency_keys.c.message_id)
saved = (
select(idempotency_keys.c.request_hash, *_MESSAGE_COLUMNS)
.join_from(
idempotency_keys,
messages,
messages.c.id == idempotency_keys.c.message_id,
)
.where(
idempotency_keys.c.user_id == sender_id,
idempotency_keys.c.chat_id == chat_id,
idempotency_keys.c.key == key,
)
)
try:
async with self._db.transaction() as connection:
if (await connection.execute(claim)).first() is not None:
# ключ — первым: повтор не пишет и не откатывает
# сообщение, а ссылка ключа на него проверяется при commit
await connection.execute(
insert(messages).values(
id=message.id,
chat_id=message.chat_id,
sender_id=message.sender_id,
text=message.text,
created_at=message.created_at,
),
)
return SentMessage(message=message, replayed=False)
row = (await connection.execute(saved)).one()
# другое тело с тем же ключом: транзакция откатывается,
# блокировка строки ключа снимается
if row.request_hash != request_hash:
raise IdempotencyConflict
return SentMessage(message=_message(row), replayed=True)
except sa_exc.IntegrityError as exc:
# составные внешние ключи (chat_id, автор) → участники: чата нет
# или автор в нём не состоит
if getattr(exc.orig, "sqlstate", None) == _FK_VIOLATION:
raise NotFound from None
raise
async def list_messages(
self,
chat_id: UUID,
*,
after: SortKey | None,
limit: int,
) -> list[Message]:
# keyset по индексу (chat_id, created_at, id), без OFFSET: страница
# не просматривает историю до курсора
statement = (
select(*_MESSAGE_COLUMNS)
.where(messages.c.chat_id == chat_id)
.order_by(messages.c.created_at, messages.c.id)
.limit(limit)
)
if after is not None:
statement = statement.where(
tuple_(messages.c.created_at, messages.c.id) > tuple_(*after),
)
async with self._db.transaction() as connection:
rows = (await connection.execute(statement)).all()
return [_message(row) for row in rows]
+204
View File
@@ -0,0 +1,204 @@
"""Схема PostgreSQL в SQLAlchemy Core: по ней пишутся запросы хранилища.
Схему в базе создают миграции (`migrations/versions/`), этот файл её
описывает для запросов и для `alembic check`: расхождение с миграциями —
дефект. Имена ограничений и индексов заданы явно, их же видно в планах
запроса (`ix_messages_chat_id_created_at_id`) и в `\\d` psql.
`CHECK` дублируют контракт: первым отвечает API (400), сработавший
`CHECK` — дефект валидации. Время назначает приложение
(`MonotonicClock`), а не `DEFAULT now()`: порядок, который видит
клиент, зависит от одних часов.
"""
from sqlalchemy import (
CheckConstraint,
Column,
DateTime,
ForeignKeyConstraint,
Index,
LargeBinary,
MetaData,
PrimaryKeyConstraint,
SmallInteger,
Table,
Text,
UniqueConstraint,
Uuid,
)
from src.constants import (
CHAT_TITLE_MAX_LENGTH,
DISPLAY_NAME_MAX_LENGTH,
IDEMPOTENCY_KEY_PATTERN,
MESSAGE_TEXT_MAX_LENGTH,
PASSWORD_HASH_PREFIX,
REQUEST_HASH_BYTES,
TOKEN_HASH_BYTES,
USERNAME_PATTERN,
)
metadata = MetaData()
def _timestamp(name: str) -> Column:
return Column(name, DateTime(timezone=True), nullable=False)
users = Table(
"users",
metadata,
Column("id", Uuid, nullable=False),
Column("username", Text, nullable=False),
Column("display_name", Text, nullable=False),
# строка Argon2id с параметрами и солью; наружу уходит только при входе
Column("password_hash", Text, nullable=False),
_timestamp("created_at"),
PrimaryKeyConstraint("id", name="pk_users"),
UniqueConstraint("username", name="uq_users_username"),
CheckConstraint(
f"username ~ '{USERNAME_PATTERN}'", name="ck_users_username_format"
),
CheckConstraint(
f"char_length(display_name) BETWEEN 1 AND {DISPLAY_NAME_MAX_LENGTH}",
name="ck_users_display_name_length",
),
# защита в глубину: открытый пароль или быстрый хэш не запишется
CheckConstraint(
f"password_hash LIKE '{PASSWORD_HASH_PREFIX}%'",
name="ck_users_password_hash_argon2id",
),
)
sessions = Table(
"sessions",
metadata,
Column("id", Uuid, nullable=False),
Column("user_id", Uuid, nullable=False),
# SHA-256 токена: по таблице действующий токен не восстановить
Column("token_hash", LargeBinary, nullable=False),
_timestamp("created_at"),
_timestamp("expires_at"),
PrimaryKeyConstraint("id", name="pk_sessions"),
ForeignKeyConstraint(["user_id"], ["users.id"], name="fk_sessions_user_id_users"),
# проверка токена на каждом запросе — поиск по этому индексу
UniqueConstraint("token_hash", name="uq_sessions_token_hash"),
CheckConstraint(
f"octet_length(token_hash) = {TOKEN_HASH_BYTES}",
name="ck_sessions_token_hash_length",
),
CheckConstraint(
"expires_at > created_at", name="ck_sessions_expires_after_created"
),
)
chats = Table(
"chats",
metadata,
Column("id", Uuid, nullable=False),
Column("title", Text, nullable=False),
_timestamp("created_at"),
PrimaryKeyConstraint("id", name="pk_chats"),
CheckConstraint(
f"char_length(title) BETWEEN 1 AND {CHAT_TITLE_MAX_LENGTH}",
name="ck_chats_title_length",
),
)
# участник чата. `position` — место в member_ids запроса: контракт отдаёт
# участников в порядке создания. `created_at` — копия времени чата: по ней
# список чатов пользователя идёт keyset-ом по индексу, без сортировки
# всех его чатов
chat_members = Table(
"chat_members",
metadata,
Column("chat_id", Uuid, nullable=False),
Column("user_id", Uuid, nullable=False),
Column("position", SmallInteger, nullable=False),
_timestamp("created_at"),
PrimaryKeyConstraint("chat_id", "user_id", name="pk_chat_members"),
ForeignKeyConstraint(
["chat_id"],
["chats.id"],
name="fk_chat_members_chat_id_chats",
),
ForeignKeyConstraint(
["user_id"],
["users.id"],
name="fk_chat_members_user_id_users",
),
UniqueConstraint("chat_id", "position", name="uq_chat_members_chat_id_position"),
CheckConstraint("position >= 0", name="ck_chat_members_position_non_negative"),
# keyset списка чатов: WHERE user_id = ... AND (created_at, chat_id) > (...)
Index(
"ix_chat_members_user_id_created_at_chat_id",
"user_id",
"created_at",
"chat_id",
),
)
messages = Table(
"messages",
metadata,
Column("id", Uuid, nullable=False),
Column("chat_id", Uuid, nullable=False),
Column("sender_id", Uuid, nullable=False),
Column("text", Text, nullable=False),
_timestamp("created_at"),
PrimaryKeyConstraint("id", name="pk_messages"),
# отправитель — участник этого чата: проверяет сама БД
ForeignKeyConstraint(
["chat_id", "sender_id"],
["chat_members.chat_id", "chat_members.user_id"],
name="fk_messages_chat_id_sender_id_chat_members",
),
CheckConstraint(
f"char_length(text) BETWEEN 1 AND {MESSAGE_TEXT_MAX_LENGTH}",
name="ck_messages_text_length",
),
# keyset истории: WHERE chat_id = ... AND (created_at, id) > (...)
# ORDER BY created_at, id LIMIT n — страница без чтения всей истории
Index("ix_messages_chat_id_created_at_id", "chat_id", "created_at", "id"),
)
# ключ идемпотентности отправки (лаба 3, ревизия 0002). Область — автор,
# чат и ключ: метод и путь у ключа один (POST сообщения). Ключ пишется в
# той же транзакции, что и сообщение, и раньше него: ссылка на сообщение
# проверяется при commit (DEFERRABLE INITIALLY DEFERRED)
idempotency_keys = Table(
"idempotency_keys",
metadata,
Column("user_id", Uuid, nullable=False),
Column("chat_id", Uuid, nullable=False),
Column("key", Text, nullable=False),
# SHA-256 канонического тела: повтор сравнивается с ним, не с текстом
Column("request_hash", LargeBinary, nullable=False),
Column("message_id", Uuid, nullable=False),
# время захвата ключа; по нему истекает срок IDEMPOTENCY_TTL_SECONDS
_timestamp("created_at"),
PrimaryKeyConstraint("user_id", "chat_id", "key", name="pk_idempotency_keys"),
# ключ бывает только у участника чата: заодно ссылки на чат и автора
ForeignKeyConstraint(
["chat_id", "user_id"],
["chat_members.chat_id", "chat_members.user_id"],
name="fk_idempotency_keys_chat_id_user_id_chat_members",
),
ForeignKeyConstraint(
["message_id"],
["messages.id"],
name="fk_idempotency_keys_message_id_messages",
deferrable=True,
initially="DEFERRED",
),
CheckConstraint(
f"key ~ '{IDEMPOTENCY_KEY_PATTERN}'",
name="ck_idempotency_keys_key_format",
),
CheckConstraint(
f"octet_length(request_hash) = {REQUEST_HASH_BYTES}",
name="ck_idempotency_keys_request_hash_length",
),
# ручная уборка просроченных ключей: DELETE ... WHERE created_at < ...
Index("ix_idempotency_keys_created_at", "created_at"),
)