- lifespan computes the dummy Argon2id hash: first unknown-user login takes as long as a wrong password - evidence for session TTL from config.toml, default and environment - REPORT.md: manual /docs check, TTL configuration row - tasks.md: why checks ran on a separate dev database Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
344 lines
33 KiB
Markdown
344 lines
33 KiB
Markdown
# Отчёт — лабораторная 2
|
||
|
||
- Автор, группа: Сафронов Роман Николаевич, БВТ2301
|
||
- Целевая оценка 5; выбранный трек 5: 2 (план запроса и восстановление)
|
||
- Commit/PR: TODO после публикации
|
||
- Использованные источники, библиотеки и помощь ИИ: раздел «Источники, библиотеки и использование ИИ» в конце отчёта
|
||
|
||
Отчёт заполняется по мере работы. Готово: хранение в PostgreSQL (change
|
||
`postgres-storage`), пароли, вход по Basic и Bearer-сессии
|
||
(`session-auth`). Впереди: кэш Redis/Valkey (`membership-cache`),
|
||
автоматические проверки отказов уровня 4 (`failure-checks`), EXPLAIN и
|
||
стенд под Postgres (`bench-postgres`), трек 2 (`track2-query-plans`,
|
||
`track2-backup-restore`).
|
||
|
||
## Запуск из чистого clone
|
||
|
||
**Версии.** Образ API: `python:3.12.14-slim-trixie` и `uv 0.12.17`,
|
||
Postgres: `postgres:18.6-trixie`; все закреплены тегом и digest индекса
|
||
(amd64 + arm64) в `Dockerfile` и `docker-compose.yml`. Приложение:
|
||
Python 3.12, FastAPI 0.141.1, SQLAlchemy 2.1.1 (async), asyncpg 0.31.0,
|
||
alembic 1.20.0, argon2-cffi 25.1.0 и остальное строго по `uv.lock`. Проверено на Docker
|
||
Desktop 29.8.1 (VM linux/arm64), Compose v5.5.1, macOS на Apple M3 Pro.
|
||
|
||
**Нужно на машине:** Docker с BuildKit, `make`, `python3` (3.9+) для
|
||
публичных проверок и `make test_isolated`, свободные порты
|
||
`127.0.0.1:8080` (API) и `127.0.0.1:5433` (Postgres). uv на хосте нужен
|
||
только для запуска сервиса без контейнера (`make run_dev`).
|
||
|
||
**Подготовка и секреты.** `make env_setup` создаёт `.env` из
|
||
`.env.example` и `config.toml` из `config_example.toml`; существующие
|
||
файлы не трогает. В шаблоне пароль Postgres пустой, в новый `.env`
|
||
подставляется случайный (`openssl rand -hex 16`), так что общего пароля
|
||
стенда в git нет. Отдельно запускать `env_setup` не нужно: его вызывают
|
||
`make run_docker`, `make run_dev` и `make test_isolated`. Пароль задаётся
|
||
Postgres только при создании volume: после смены `POSTGRES_PASSWORD`
|
||
нужен `make wipe_data`.
|
||
|
||
```sh
|
||
git clone <fork> && cd <каталог clone>
|
||
git checkout solution/bvt2301-safronov
|
||
```
|
||
|
||
### Способ 1. Всё в compose: `make run_docker`
|
||
|
||
```sh
|
||
make run_docker
|
||
# make env_setup (только недостающие .env и config.toml)
|
||
# DOCKER_BUILDKIT=1 docker compose build
|
||
# docker compose up -d postgres -> migrate (alembic upgrade head) -> api
|
||
```
|
||
|
||
Порядок задают `depends_on`: `migrate` стартует после healthcheck
|
||
Postgres (`pg_isready` по TCP), API — после того, как `migrate`
|
||
завершился с кодом 0. Готовность — `GET http://127.0.0.1:8080/health/ready`
|
||
→ 200 (несколько секунд после команды). Журнал API — `make logs`,
|
||
миграций — `docker compose logs migrate`.
|
||
|
||
### Способ 2. Сервис на хосте: `make run_dev`
|
||
|
||
```sh
|
||
make run_dev
|
||
# docker compose up -d --wait postgres
|
||
# uv run alembic upgrade head -> 127.0.0.1:5433
|
||
# APP__RUN_MODE=console uv run python -m src
|
||
```
|
||
|
||
Сервис слушает `127.0.0.1:8080` с reload по `src/`, Postgres — тот же
|
||
контейнер и тот же volume, что у способа 1. Переключение между способами
|
||
не требует правки файлов (раздел «Конфигурация»).
|
||
|
||
### Проверки
|
||
|
||
```sh
|
||
make check # структура skeleton
|
||
make validate PYTHON=.venv/bin/python # OpenAPI 3.1 (после uv sync --all-extras)
|
||
make test_isolated # образ на временной базе: smoke + student-tests, уборка
|
||
make student_test # собственные тесты против запущенного стенда (BASE_URL)
|
||
make test # публичный smoke против запущенного стенда
|
||
make test-persistence ACTION_SCRIPT=scripts/restart.sh # данные и прежний токен после рестарта
|
||
```
|
||
|
||
Ожидаемо: `make test` и `make test-persistence` — `PASS`,
|
||
`make test_isolated` — код 0 и `99 passed` (`evidence/tests/test-isolated.md`).
|
||
|
||
### Сценарий защиты
|
||
|
||
```sh
|
||
echo yes | make wipe_data && make run_docker # миграции на пустом volume
|
||
# регистрация, вход, сообщение — тем же сценарием, что в tests/smoke.py:
|
||
make test # PASS
|
||
make test-persistence ACTION_SCRIPT=scripts/restart.sh # рестарт API и Postgres, тот же токен
|
||
# logout и повтор прежним токеном: test_logout, test_logout_twice в make test_isolated
|
||
# короткий срок сессии — отдельным экземпляром в консоли:
|
||
AUTH__SESSION_TTL_SECONDS=2 python3 .claude/skills/run-mtusi-messenger/driver.py --port 18080 start
|
||
```
|
||
|
||
Вручную вход и запрос выглядят так (пароль и токен — свои):
|
||
|
||
```sh
|
||
curl -s -X POST localhost:8080/api/v1/users -H 'Content-Type: application/json' \
|
||
-d '{"username":"alice_demo","display_name":"Алиса","password":"<пароль 12–128>"}'
|
||
curl -s -X POST localhost:8080/api/v1/auth/sessions -u 'alice_demo:<пароль>' # 201 Session
|
||
curl -s localhost:8080/api/v1/users/me -H 'Authorization: Bearer <token>' # 200
|
||
curl -s -X DELETE localhost:8080/api/v1/auth/sessions/current -H 'Authorization: Bearer <token>' # 204
|
||
```
|
||
|
||
**Миграция `42bc3b9be38f` удаляет данные лабы 1.** У пользователей,
|
||
созданных до `session-auth`, нет пароля, войти они не смогут, а хэш
|
||
теперь обязателен. Поэтому при первом `make run_docker` или
|
||
`make run_dev` на старом volume миграция удаляет таких пользователей
|
||
вместе с чатами, участниками и сообщениями и пишет их число в журнал
|
||
`migrate` (`warning`). Данные стенда синтетические
|
||
(`evidence/migrations/drop-lab1-data.md`).
|
||
|
||
### Остановка и удаление данных
|
||
|
||
- `make stop` — остановить контейнеры; `make down` — удалить контейнеры,
|
||
volume `postgres_data` с данными остаётся;
|
||
- `make wipe_data` — удалить контейнеры и volume, только после ввода
|
||
`yes`; следующий `make run_docker` поднимает пустую базу со схемой.
|
||
|
||
## Архитектура и решения
|
||
|
||
```
|
||
клиент --HTTP--> api (FastAPI, 1 процесс) --asyncpg, пул--> postgres (volume postgres_data)
|
||
^
|
||
migrate (тот же образ, alembic upgrade head, до старта api)
|
||
```
|
||
|
||
**Источник истины** — PostgreSQL. Пользователи, чаты, участники,
|
||
сообщения и сессии хранятся только в нём; память процесса, файлы и SQLite
|
||
не используются. Подтверждённая запись (201, 204) зафиксирована commit до
|
||
ответа.
|
||
|
||
**Схема** (миграции `migrations/versions/…_added_messenger_tables.py` и
|
||
`…_added_sessions_and_password_hashes.py`):
|
||
|
||
| Таблица | Ключи и ограничения | Индексы |
|
||
|---|---|---|
|
||
| `users` | PK `id`; UNIQUE `username`; CHECK шаблона `username` и длины `display_name`; `password_hash` NOT NULL, CHECK `LIKE '$argon2id$%'` — открытый пароль или быстрый хэш не запишется | `uq_users_username` |
|
||
| `sessions` | PK `id`; FK `user_id` → `users`; UNIQUE `token_hash` (SHA-256 токена, `bytea`, CHECK 32 байта); CHECK `expires_at > created_at` | `uq_sessions_token_hash` — проверка токена |
|
||
| `chats` | PK `id`; CHECK длины `title` | — |
|
||
| `chat_members` | PK `(chat_id, user_id)`; FK на `chats` и `users`; UNIQUE `(chat_id, position)`; `position` хранит порядок `member_ids` | `(user_id, created_at, chat_id)` — keyset списка чатов |
|
||
| `messages` | PK `id`; составной FK `(chat_id, sender_id)` → `chat_members`: отправитель обязан быть участником; CHECK длины `text` | `(chat_id, created_at, id)` — keyset истории |
|
||
|
||
`id` и `created_at` назначает сервис (`uuid4()`, `utcnow()`), а не БД.
|
||
`chat_members.created_at` — копия времени чата, по ней список чатов идёт
|
||
keyset-ом по индексу без сортировки всех чатов пользователя. `CHECK`
|
||
дублируют контракт: первым отвечает API (400), сработавший `CHECK` —
|
||
дефект валидации.
|
||
|
||
**Транзакционные границы.** Одна `AsyncSession` на запрос, commit делает
|
||
сервис, изоляция `READ COMMITTED`:
|
||
|
||
| Операция | Шаги в одной транзакции |
|
||
|---|---|
|
||
| регистрация | хэш пароля (до БД) → `INSERT … ON CONFLICT (username) DO NOTHING RETURNING`; конфликт → 409 |
|
||
| вход | транзакция 1: `SELECT` учётных данных → commit (соединение возвращается в пул); проверка пароля вне БД; транзакция 2: `INSERT sessions` → commit |
|
||
| запрос с токеном | один `SELECT sessions JOIN users WHERE token_hash = … AND expires_at > now` |
|
||
| выход | `DELETE FROM sessions WHERE id = …` → commit |
|
||
| создание чата | проверка существования участников → `INSERT chats` → `INSERT chat_members` (одна вставка) → commit; ошибка до commit — откат, не остаётся ни чата, ни участников |
|
||
| сообщение | проверка членства → `INSERT messages` → commit |
|
||
| чтения | один `SELECT` |
|
||
|
||
Явные блокировки не нужны: пользователи и участники не меняются и не
|
||
удаляются, гонку регистрации закрывает уникальный индекс (тест
|
||
`test_same_username_at_once`: из 10 одновременных регистраций одна 201,
|
||
девять 409).
|
||
|
||
**Пагинация.** Курсор — ключ `(created_at, id)` последнего элемента;
|
||
запрос — сравнение кортежей по индексу, без `OFFSET`. Повторов при обходе
|
||
нет. Сообщение, которое закоммитилось позже, но с `created_at` меньше уже
|
||
пройденного курсора, текущий обход пропустит, а новый обход с начала
|
||
увидит. Время ставит один процесс API с часами хоста; при нескольких
|
||
репликах лабы 3 часы общие (один Docker-host).
|
||
|
||
**Недоступность БД.** Критичная зависимость `/health/ready` — PostgreSQL
|
||
(`SELECT 1` с таймаутом 2 с). Ошибки соединения и таймауты на
|
||
бизнес-запросе дают 503 `unavailable` без деталей, причина пишется в
|
||
журнал (`warning`), после возврата Postgres запросы обслуживаются без
|
||
рестарта API. Таймауты: подключение 3 с, ожидание соединения пула 5 с,
|
||
серверный `statement_timeout` 5 с, срок всей работы запроса с БД 6 с;
|
||
пул 10 + 5 соединений. При замёрзшем сервере ответ приходит через 6 + 2 с:
|
||
2 с — ограниченное мягкое закрытие прерванного соединения. Без этого
|
||
ограничения asyncpg и SQLAlchemy ждали разморозки сервера (169 с в
|
||
замере); подробности — design change `postgres-storage`, решение 6.
|
||
|
||
**Пароли и сессии.**
|
||
|
||
- **Пароль** — Argon2id (argon2-cffi), профиль RFC 9106 low-memory назван
|
||
в коде явно: t = 3, m = 64 MiB, p = 4, соль 16 байт, хэш 32 байта.
|
||
Около 30 мс на хэш или проверку. Пароль хэшируется целиком как UTF-8,
|
||
без обрезки: 128 кириллических символов (256 байт) сравниваются
|
||
полностью, поэтому не bcrypt (72 байта). Lab7 требует Argon2id.
|
||
- **KDF не в event loop**: в потоке через `anyio.to_thread.run_sync` со
|
||
своим лимитом `[auth] kdf_concurrency` = 4. Пик памяти 4 × 64 MiB, а не
|
||
40 × 64 MiB при общем пуле потоков anyio. Пока считается пароль,
|
||
соединение БД отпущено.
|
||
- **Неизвестный username** проверяется против фиктивного хэша: время
|
||
ответа то же, что у неверного пароля (26,0 и 26,4 мс в медиане,
|
||
`evidence/auth/passwords-and-tokens.md`). Ответ одинаковый: 401 с
|
||
`WWW-Authenticate: Basic realm="messenger", charset="UTF-8"`.
|
||
- **Вход** — только `Authorization: Basic` на `POST /auth/sessions`.
|
||
Разбор свой: FastAPI `HTTPBasic` декодирует ASCII и на пароле не из
|
||
ASCII сам отвечает 401 мимо формата контракта. Схема объявлена через
|
||
`HTTPBase`, base64 строго, UTF-8, первое двоеточие. Username не по
|
||
шаблону и пароль вне 12–128 отсекаются до БД и KDF тем же 401. Ответа
|
||
400 у входа нет: любой сбой Basic — 401.
|
||
- **Токен** — `secrets.token_urlsafe(32)`: 256 бит, 43 символа, ничего не
|
||
кодирует. В БД — только его SHA-256: быстрого хэша достаточно, перебирать
|
||
256 бит нечего.
|
||
- **Сессия** — строка `sessions` с `expires_at`, фиксированным при входе.
|
||
Срок не продлевают ни запросы, ни рестарт. Каждый запрос — один `SELECT`
|
||
по `token_hash`, поэтому отзыв мгновенный: `DELETE` строки, кэша нет.
|
||
Истёкший, отозванный или неизвестный токен, Basic на бизнес-ручке —
|
||
401 с `WWW-Authenticate: Bearer realm="messenger"`. `X-User-Id`
|
||
игнорируется.
|
||
- **Недоступность Postgres** при запросе с токеном — 503 `unavailable`,
|
||
не 401 и не анонимный доступ (`evidence/auth/expiry.md`).
|
||
- **Журнал** не содержит паролей, токенов, их хэшей, `Authorization` и
|
||
username. Вход, неудачный вход и выход пишутся с `user_id` и `id`
|
||
сессии. Параметры SQL в ошибках драйвера скрыты (`hide_parameters`).
|
||
|
||
**Конфигурация.** Адреса, порты и учётные данные — из `.env`, пул,
|
||
таймауты и срок сессии — из `config.toml`. Переключение консоль ↔ docker
|
||
— без правки файлов. Консольный сервис читает `.env` с мостами
|
||
`DATABASE__*`; в контейнер `.env` не попадает, адрес и порт Postgres
|
||
приходят из `environment` compose. В compose нет литералов адреса и
|
||
порта Postgres, литерал — только адрес публикации `127.0.0.1`.
|
||
|
||
| Переменная skeleton (`.env.example`) | В этом проекте |
|
||
|---|---|
|
||
| `APP_HOST` | режим `APP__RUN_MODE`: console — `127.0.0.1`, docker — `0.0.0.0` |
|
||
| `APP_PORT` | `APP__PORT` (внутри), `APP_OUT_PORT` (публикация на `127.0.0.1`) |
|
||
| `APP_ENV` | не используется: окружение одно — учебный стенд |
|
||
| `SESSION_TTL_SECONDS` | `[auth] session_ttl_seconds` в `config.toml`, по умолчанию 3600; разовая подмена — окружением `AUTH__SESSION_TTL_SECONDS` (так короткий срок 2 с для проверки истечения). Мостом из `.env` не заводится: его читает только приложение, а окружение мост по исходному имени не перекрывает |
|
||
| `DATABASE_URL_FILE` | не используется: URL собирает приложение из `[database]`, пароль — мостом из `POSTGRES_PASSWORD` |
|
||
| `SESSION_STORE` | `postgres`: таблица `sessions`, без кэша — отзыв мгновенный |
|
||
| `CACHE_URL_FILE` | TODO, change `membership-cache` |
|
||
|
||
**Что перенесено из лабы 1 и что изменено.** Хранилище `MemoryStore`
|
||
заменено PostgreSQL, repo и сервисы переписаны на `AsyncSession`, цель
|
||
`make run_no_compose` удалена: API без Postgres не обслуживает запросы.
|
||
Переход API 1 → 2 (`COURSE.md`): `X-User-Id` заменён Bearer-сессией,
|
||
регистрация требует пароль, `student-tests` идентифицируются токеном.
|
||
Данные лабы 1 без паролей удаляет миграция (см. «Сценарий защиты»).
|
||
Согласования с преподавателем из лабы 1 действуют: FastAPI с его
|
||
расхождениями и конфиг через `config.toml` (AGENTS.md).
|
||
|
||
## Доказательства критериев
|
||
|
||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||
| --- | --- | --- | --- |
|
||
| Публичный smoke | `make test_isolated` (внутри — `make test` против образа) | `PASS: lab2 public API scenario` | `evidence/tests/test-isolated.md` |
|
||
| PostgreSQL содержит пользователей, чаты, участников и сообщения; PK/FK, уникальный `username` | `\d` в `psql`, `alembic check` после миграций | 4 таблицы, ограничения и индексы по таблице выше; модели совпадают со схемой | `evidence/migrations/from-zero-and-rerun.md`, `migrations/versions/` |
|
||
| Миграции с нуля и повторно без дублирования | `make wipe_data`, `make run_docker`, `docker compose run --rm migrate` | `migrate` завершился с кодом 0 до старта API; повтор — no-op, число строк не изменилось | `evidence/migrations/from-zero-and-rerun.md` |
|
||
| API не стартует при ошибке миграции | `migrate` с несуществующей базой через override-файл compose | `up` — код 1, `migrate` Exited (1), `api` создан, но не запущен; ошибка в журнале `migrate` | `evidence/migrations/migration-error.md` |
|
||
| Запуск из чистого clone: консоль, затем docker | `git clone`, `make env_setup`, `make run_dev`, `make run_docker`, `make down` + `make run_docker` | консоль с нуля: Postgres, миграции и ready 200 одной командой; docker видит данные из консоли без правки файлов; после `make down` данные на месте | `evidence/storage/fresh-clone.md` |
|
||
| Данные и действующие сессии переживают рестарт API и хранилищ без удаления volumes | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | `PASS`: прежний токен читает те же данные; у API и Postgres новые `StartedAt` | `evidence/storage/test-persistence.md`; порядок участников и истории — `evidence/storage/restart.md` (снят до `session-auth`, с `X-User-Id`) |
|
||
| Миграция к паролям на старой базе | `make run_docker` на volume с данными лабы 1, затем `docker compose run --rm migrate` | `warning` «Deleted lab 1 data without passwords: 225 users…», `password_hash` NOT NULL, таблица `sessions`; повтор — no-op | `evidence/migrations/drop-lab1-data.md` |
|
||
| Составная операция создания чата атомарна | код `ChatService.create_chat`: один commit | автоматическая проверка отката — change `failure-checks` | TODO |
|
||
| Basic только на `POST /auth/sessions`, остальное — Bearer; `X-User-Id` не даёт доступ | smoke и `test_identification.py`, `test_sessions.py` в `make test_isolated` | Basic на `/users/me` — 401 с вызовом Bearer; только `X-User-Id` — 401; Bearer alice с `X-User-Id` eve — alice; битый Basic — 401 с вызовом Basic | `evidence/tests/test-isolated.md` |
|
||
| Схемы `bearerAuth` и `basicAuth` в документации API | `test_security_schemes_in_openapi`; вручную в `/docs` | `/openapi.json` совпадает с контрактом, `devUser` нет; в `/docs` вход через Authorize (Basic, пароль из ASCII) и запрос с Bearer работают — проверено автором 2026-10-01 | `evidence/tests/test-isolated.md` |
|
||
| Срок жизни сессии | сервис с `AUTH__SESSION_TTL_SECONDS=2` | 200 сразу, 401 через 2,1 с; запросы каждые 0,5 с срок не продлевают | `evidence/auth/expiry.md` |
|
||
| Срок сессии — настройка (`SESSION_TTL_SECONDS` контракта) | сервис с разными `config.toml` и окружением | без `[auth]` — 3600 с, `session_ttl_seconds = 600` — 600 с, окружение `AUTH__SESSION_TTL_SECONDS=2` поверх файла — 2 с; `abc` и `0` — запуск останавливается | `evidence/auth/ttl-config.md` |
|
||
| Отзыв сессии | `DELETE /auth/sessions/current`: `test_logout`, `test_logout_twice`, `test_other_session_survives_logout` | 204 без тела, дальше этот токен — 401 везде; вторая сессия работает | `evidence/tests/test-isolated.md` |
|
||
| Пароли — password KDF | `psql`, `pg_dump --data-only`, журнал API | `$argon2id$v=19$m=65536,t=3,p=4$…`, у одинаковых паролей разные хэши; пароля и токена нет ни в БД, ни в журнале; в `sessions` — SHA-256 токена | `evidence/auth/passwords-and-tokens.md` |
|
||
| Secrets и volumes не в git | `.gitignore`, `make env_setup` | `.env`, `config.toml` игнорируются; пароль Postgres генерируется локально | `.gitignore` |
|
||
| Собственные тесты против контейнера | `make test_isolated` | код 0: smoke `PASS`, 99 passed; 96 сценариев спеков: 81 тестом, 15 исключениями; база и контейнер убираются при любом исходе | `evidence/tests/test-isolated.md`, `evidence/tests/test-isolated-mechanics.md` |
|
||
| Конфигурация из `.env`, без литералов адреса и порта Postgres в compose | `POSTGRES_PORT` и `POSTGRES_OUT_PORT` изменены в `.env`, `make run_docker`, `make run_dev` | оба способа запуска подключились к новому порту, compose не правился | `evidence/storage/postgres-port.md` |
|
||
| Уровень 4: ограниченный пул и таймауты | пул из одного соединения, Postgres на паузе | второй запрос — 503 через 1 с (`pool_timeout`), первый — 503 через 6 + 2 с | `evidence/storage/pool-timeout.md` |
|
||
| Уровень 4: таймаут запроса и логи без содержимого сообщений | `messages` под `ACCESS EXCLUSIVE`, `POST` сообщения | 503 через 5 с по `statement_timeout`; в журнале SQL и причина, параметры скрыты (`hide_parameters`), текста сообщения нет; до исправления он там был | `evidence/storage/statement-timeout.md` |
|
||
| Уровень 4: недоступность БД | `docker compose stop` и `pause postgres` | 503 `unavailable` без деталей, `/health/live` 200, после возврата — без рестарта API | `evidence/storage/db-unavailable.md` |
|
||
| Уровень 4: недоступность БД при запросе с токеном | `docker compose stop postgres`, `GET /users/me` и вход | 503 `unavailable`, не 401 и не анонимный доступ; после `start` тот же токен — 200 | `evidence/auth/expiry.md` |
|
||
| Уровень 4: автоматические проверки logout и неверного пароля | `test_logout`, `test_wrong_password` (`test_rubric.py`) в `make test_isolated` | выход — 204, повтор — 401 Bearer; неверный пароль — 401 Basic без токена | `evidence/tests/test-isolated.md` |
|
||
| Уровень 4: гонка регистрации одного `username` | `test_same_username_at_once` в `make test_isolated` | 10 клиентов, в полёте одновременно 10: одна 201, девять 409 | `evidence/tests/test-isolated.md` |
|
||
| Уровень 4: параметризованные запросы | код repo | SQLAlchemy Core/ORM с параметрами, SQL из строк нет | `src/core/repos/` |
|
||
| Остальные пункты уровня 4 | — | TODO: Redis/Valkey, EXPLAIN на ≥10 000, автоматические проверки expiry и недоступности БД и Redis (`failure-checks`) | TODO |
|
||
| Трек 5 | — | TODO | TODO |
|
||
|
||
## Эксперименты и отказы
|
||
|
||
Стенд: Docker Desktop 29.8.1 на macOS (Apple M3 Pro), ВМ Docker 12 CPU и
|
||
7 GiB RAM, лимиты контейнерам не задавались; таймауты — по умолчанию из
|
||
`config_example.toml`.
|
||
|
||
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|
||
| --- | --- | --- | --- |
|
||
| `docker compose stop postgres` | 503 вместо 500, ready 503, live 200 | 503 через 0,01 с; ready 503, live 200 | после `start` — сразу, без рестарта API; подтверждённые данные на месте |
|
||
| `docker compose pause postgres` (сервер завис) | 503 не позже срока запроса и закрытия соединения (6 + 2 с) | 503 через 8,0 с, ready 503 через 2 с | после `unpause` — сразу |
|
||
| пул исчерпан (1 соединение, сервер завис) | ожидание не дольше `pool_timeout` | 503 через 1,0 с | после `unpause` — сразу |
|
||
| `messages` под `ACCESS EXCLUSIVE` 8 с | 503 по `statement_timeout`, в журнале нет параметров SQL | 503 через 5,0 с, параметры скрыты | после снятия блокировки — сразу |
|
||
| `migrate` завершился ошибкой | API не стартует | `api` в состоянии `Created`, `up` — код 1 | `make run_docker` с верной базой — сразу |
|
||
| `scripts/restart.sh` (API и Postgres) | данные и порядок на месте | hook 3,5 с, готовность через 1 с после него | потерь нет |
|
||
| `make test-persistence` с тем же hook | прежний токен работает | `PASS`, вся проверка 4,9 с | сессии и данные на месте |
|
||
| срок сессии 2 с (`AUTH__SESSION_TTL_SECONDS=2`) | 401 после срока, запросы не продлевают | первый 401 через 2,1 с при запросах каждые 0,5 с | — |
|
||
| Postgres остановлен, токен действующий | 503, не 401 | 503 `unavailable` на `/users/me` и на вход | после `start` тот же токен — 200 |
|
||
| миграция к паролям на базе лабы 1 | данные без паролей удалены, это видно в журнале | `warning` с числом 225, `password_hash` NOT NULL | данные лабы 1 удалены намеренно (синтетические) |
|
||
|
||
## Ограничения и следующие шаги
|
||
|
||
- Сервер, замёрзший при открытом соединении, держит запрос 8 с, а не
|
||
6: 2 с уходят на ограниченное закрытие соединения.
|
||
- Время сообщений ставит процесс API: порядок истории зависит от часов
|
||
хоста; конкурентные вставки могут быть пропущены текущим обходом
|
||
(раздел «Пагинация»).
|
||
- Срок запроса может истечь на самом `commit`. Тогда сервер мог уже
|
||
зафиксировать запись, а клиент получит 503: это не частичная запись,
|
||
но исход для клиента неизвестен, и повтор создаст дубль. Безопасный
|
||
повтор появится с `Idempotency-Key` в лабе 3.
|
||
- Один Docker-host: потерю хоста стенд не переживает, Postgres без
|
||
реплик.
|
||
- Прогоны `make student_test` и `make test` против рабочего стенда
|
||
оставляют данные в рабочей базе; обычный прогон — `make test_isolated`.
|
||
- Истёкшие сессии остаются в таблице: их не читает ни один запрос, рост —
|
||
одна строка на вход. Чистка — фоновая задача с лабы 5.
|
||
- Вход ограничен лимитом KDF (4 хэша одновременно), но частота входа не
|
||
ограничена (429 не реализован). Очередь из сотен входов дольше 6 с
|
||
дала бы 503 с записью «Database is unavailable», хотя БД в порядке.
|
||
- Защита от перебора имён по времени касается только входа: регистрация
|
||
по контракту отвечает 409 на занятый `username`.
|
||
- Swagger UI кодирует Basic через `btoa`: войти из `/docs` можно только
|
||
с паролем из ASCII. API принимает любой UTF-8, это проверяют тесты.
|
||
- Не реализовано: Redis/Valkey, автоматические проверки истечения и
|
||
отказов, EXPLAIN и трек 2 — следующие changes.
|
||
|
||
## Источники, библиотеки и использование ИИ
|
||
|
||
- Документация: PostgreSQL 18 (транзакции, `statement_timeout`,
|
||
`pg_isready`), SQLAlchemy 2.1 (asyncio, пул, обработка разрывов),
|
||
alembic (async-шаблон `env.py`), asyncpg (параметры подключения,
|
||
`connection_class`), Docker Compose (`depends_on`, `--wait`, сети).
|
||
- Документация по аутентификации: RFC 7617 (Basic), RFC 9106 (Argon2) и
|
||
argon2-cffi (профили параметров), anyio (`to_thread.run_sync`,
|
||
`CapacityLimiter`), FastAPI security (`HTTPBase`, `HTTPBearer`).
|
||
- Библиотеки: FastAPI, pydantic, pydantic-settings, structlog,
|
||
SQLAlchemy, asyncpg, alembic, argon2-cffi, uvicorn; в тестах — pytest и
|
||
httpx.
|
||
- ИИ: Claude (Claude Code) помогал проектировать changes
|
||
`postgres-storage` и `session-auth` (OpenSpec), писать код, правила и
|
||
отчёт, а также проверял поведение на стенде. Решения и все правки
|
||
просмотрены автором; поведение подтверждено командами, выводы которых
|
||
лежат в `evidence/`.
|