feat: add replicated messenger and reproducible lab3 stand
This commit is contained in:
+210
@@ -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).
|
||||
@@ -0,0 +1,7 @@
|
||||
"""REST API мессенджера MTUSI, лабораторная 3: реплики за HAProxy.
|
||||
|
||||
PostgreSQL — источник истины (данные, сессии, ключи идемпотентности),
|
||||
Valkey — общий кэш карточек чатов. Пакет намеренно пустой при импорте:
|
||||
`import src.<модуль>` не поднимает приложение, не читает окружение и не
|
||||
подключается к базе.
|
||||
"""
|
||||
@@ -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()
|
||||
@@ -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` и тела. Токен в
|
||||
вывод и отчёт не копировать.
|
||||
+170
@@ -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)]
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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,
|
||||
)
|
||||
@@ -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",
|
||||
]
|
||||
@@ -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)
|
||||
@@ -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()
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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
@@ -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,
|
||||
)
|
||||
@@ -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
@@ -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),
|
||||
)
|
||||
@@ -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"
|
||||
@@ -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()
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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"
|
||||
@@ -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
@@ -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
@@ -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,
|
||||
)
|
||||
@@ -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])))
|
||||
@@ -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
|
||||
@@ -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-тест.
|
||||
@@ -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",
|
||||
]
|
||||
@@ -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
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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
|
||||
@@ -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`).
|
||||
@@ -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",
|
||||
]
|
||||
@@ -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`."""
|
||||
...
|
||||
@@ -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)
|
||||
@@ -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]
|
||||
@@ -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"),
|
||||
)
|
||||
Reference in New Issue
Block a user