From 8267d7d34559ca87646d51befc1997a85ce41484 Mon Sep 17 00:00:00 2001 From: celis Date: Thu, 29 Oct 2026 20:49:57 +0300 Subject: [PATCH] =?UTF-8?q?=D0=9B=D0=A0=202=20=E2=80=94=20=D0=91=D0=9F?= =?UTF-8?q?=D0=982303=20=E2=80=94=20=D0=9C=D0=BE=D1=80=D0=B0=D1=80=D1=83?= =?UTF-8?q?=20=E2=80=94=20=D0=BD=D0=B0=205=20(=D1=82=D1=80=D0=B5=D0=BA=202?= =?UTF-8?q?)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit TypeScript/Node API на PostgreSQL с сессиями в Valkey (AOF), миграции, compose-стенд, restart hook, тесты уровня 4 и эксперимент трека 2 (планы запроса на 240k сообщений, стоимость записи, backup/restore). --- .dockerignore | 3 + .gitignore | 1 + Dockerfile | 21 + REPORT.md | 137 ++++- compose.yaml | 86 +++ evidence/check_and_migrations.txt | 8 + evidence/level4.txt | 7 + evidence/load.json | 17 + evidence/persistence.txt | 14 + evidence/pool.txt | 1 + evidence/smoke.txt | 3 + .../track2/explain_api_middle_page_V0.txt | 20 + .../track2/explain_api_middle_page_V1.txt | 25 + .../track2/explain_api_middle_page_V2.txt | 16 + .../track2/explain_api_middle_page_V3.txt | 9 + evidence/track2/results.json | 495 ++++++++++++++++++ evidence/track2/results.md | 53 ++ experiments/track2/generate.sql | 37 ++ experiments/track2/run.py | 293 +++++++++++ infra/valkey.conf | 8 + migrations/001_init.sql | 36 ++ package-lock.json | 307 +++++++++++ package.json | 20 + scripts/init-secrets.sh | 20 + scripts/restart.sh | 7 + src/auth/passwords.ts | 25 + src/auth/sessions.ts | 43 ++ src/config.ts | 17 + src/http/errors.ts | 21 + src/http/router.ts | 61 +++ src/http/validation.ts | 69 +++ src/infra/db.ts | 55 ++ src/infra/valkey.ts | 23 + src/main.ts | 23 + src/migrate.ts | 38 ++ src/models.ts | 29 + src/repositories/chats.ts | 45 ++ src/repositories/messages.ts | 31 ++ src/repositories/users.ts | 32 ++ src/routes/auth.ts | 39 ++ src/routes/chats.ts | 36 ++ src/routes/health.ts | 18 + src/routes/index.ts | 21 + src/routes/messages.ts | 26 + src/routes/users.ts | 23 + student-tests/test_lab2.py | 161 ++++++ tsconfig.json | 12 + 47 files changed, 2473 insertions(+), 19 deletions(-) create mode 100644 Dockerfile create mode 100644 compose.yaml create mode 100644 evidence/check_and_migrations.txt create mode 100644 evidence/level4.txt create mode 100644 evidence/load.json create mode 100644 evidence/persistence.txt create mode 100644 evidence/pool.txt create mode 100644 evidence/smoke.txt create mode 100644 evidence/track2/explain_api_middle_page_V0.txt create mode 100644 evidence/track2/explain_api_middle_page_V1.txt create mode 100644 evidence/track2/explain_api_middle_page_V2.txt create mode 100644 evidence/track2/explain_api_middle_page_V3.txt create mode 100644 evidence/track2/results.json create mode 100644 evidence/track2/results.md create mode 100644 experiments/track2/generate.sql create mode 100644 experiments/track2/run.py create mode 100644 infra/valkey.conf create mode 100644 migrations/001_init.sql create mode 100644 package-lock.json create mode 100644 package.json create mode 100755 scripts/init-secrets.sh create mode 100755 scripts/restart.sh create mode 100644 src/auth/passwords.ts create mode 100644 src/auth/sessions.ts create mode 100644 src/config.ts create mode 100644 src/http/errors.ts create mode 100644 src/http/router.ts create mode 100644 src/http/validation.ts create mode 100644 src/infra/db.ts create mode 100644 src/infra/valkey.ts create mode 100644 src/main.ts create mode 100644 src/migrate.ts create mode 100644 src/models.ts create mode 100644 src/repositories/chats.ts create mode 100644 src/repositories/messages.ts create mode 100644 src/repositories/users.ts create mode 100644 src/routes/auth.ts create mode 100644 src/routes/chats.ts create mode 100644 src/routes/health.ts create mode 100644 src/routes/index.ts create mode 100644 src/routes/messages.ts create mode 100644 src/routes/users.ts create mode 100755 student-tests/test_lab2.py create mode 100644 tsconfig.json diff --git a/.dockerignore b/.dockerignore index bc16e556..c7cf4ca7 100644 --- a/.dockerignore +++ b/.dockerignore @@ -18,3 +18,6 @@ __pycache__ node_modules evidence .DS_Store +dist +student-tests +experiments diff --git a/.gitignore b/.gitignore index b5a71896..ad6f84c7 100644 --- a/.gitignore +++ b/.gitignore @@ -30,3 +30,4 @@ coverage/ .vscode/ # Keep small, sanitized evidence summaries in evidence/ under version control. # Inspect git diff --cached: ignore rules are not a secret scanner. +dist/ diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 00000000..2d513d00 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,21 @@ +FROM node:24.11.1-alpine3.22 AS build +WORKDIR /app +COPY package.json package-lock.json ./ +RUN npm ci --no-audit --no-fund +COPY tsconfig.json ./ +COPY src/ src/ +RUN npx tsc && npm prune --omit=dev + +FROM node:24.11.1-alpine3.22 +WORKDIR /app +ENV NODE_ENV=production +COPY package.json ./ +COPY --from=build /app/node_modules/ node_modules/ +COPY --from=build /app/dist/ dist/ +COPY migrations/ migrations/ +USER node +EXPOSE 8080 +HEALTHCHECK --interval=5s --timeout=3s --retries=5 \ + CMD ["node", "-e", "fetch('http://127.0.0.1:8080/health/ready').then(r => process.exit(r.ok ? 0 : 1), () => process.exit(1))"] +# exec-форма: node — PID 1 и сам обрабатывает SIGTERM (закрывает HTTP, пул и Valkey) +CMD ["node", "dist/main.js"] diff --git a/REPORT.md b/REPORT.md index e42f2b05..80691542 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,136 @@ # Отчёт — лабораторная 2 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO +- Автор, группа: Морару С.С., БПИ2303 +- Целевая оценка: **5**, трек 5 — **Трек 2. План запроса и восстановление** - Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO - +- Источники, библиотеки: Node.js 24, TypeScript 5.9, `pg` 8.23 (node-postgres), `ioredis` 5.11; документация PostgreSQL (EXPLAIN, pg_dump), Valkey persistence, RFC 7617. ## Запуск из чистого clone -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +Требования: Docker Engine + Compose v2 (проверено Docker 29.8 / Compose 5.5 на OrbStack, Apple M3 Pro, VM 11 CPU / 9 GiB), Python 3.9+ для тестов. Node.js локально не нужен: сборка TypeScript идёт в Dockerfile. + +Образы (закреплены): `node:24.11.1-alpine3.22` (build + runtime), `postgres:17.6-alpine3.22`, `valkey/valkey:8.1.4-alpine3.22`. + +```sh +./scripts/init-secrets.sh # случайные пароли в ./secrets (git-ignored), значения не печатаются +docker compose up -d --build --wait # postgres, valkey -> migrate (one-shot) -> api; --wait ждёт healthcheck /health/ready +make test BASE_URL=http://127.0.0.1:8080 +make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://127.0.0.1:8080 +python3 student-tests/test_lab2.py --base-url http://127.0.0.1:8080 # уровень 4 (останавливает/запускает valkey и postgres) +python3 experiments/track2/run.py # трек 2, ~5 мин, результаты в evidence/track2/ +docker compose stop # безопасная остановка, данные остаются в volumes +docker compose down -v # НАМЕРЕННОЕ удаление всех учебных данных +``` + +`.env` не обязателен: compose имеет значения по умолчанию (`SESSION_TTL_SECONDS=3600`, `APP_PORT=8080`). API публикуется только на `127.0.0.1:8080`. На моей машине IPv6 `*:8080` занят посторонним процессом, поэтому `localhost` попадал не туда — тесты запускаются с `BASE_URL=http://127.0.0.1:8080`; на чистой машине подходит и значение по умолчанию. ## Архитектура и решения -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab1, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +``` +клиент ──HTTP──> api (Node, node:http, 1 процесс) ──pool ≤8, timeouts──> postgres (volume pgdata) — источник истины + └──ioredis, 1 s timeout──> valkey (volume valkeydata, AOF) — сессии +migrate (тот же образ, one-shot) ──> postgres +``` + +**Структура кода** (`src/`, слои зависят только «вниз»): + +| Слой | Файлы | Ответственность | +|---|---|---| +| Точка входа | `main.ts`, `migrate.ts` | HTTP-сервер, graceful shutdown по SIGTERM; применение миграций | +| Маршруты | `routes/index.ts`, `routes/{health,users,auth,chats,messages}.ts` | таблица маршрутов; обработчик = валидация → вызов репозитория → ответ | +| HTTP | `http/router.ts`, `http/errors.ts`, `http/validation.ts` | конвейер запроса (`X-Request-Id`, тело ≤1 MiB, формат ошибок, access-лог), коды ошибок контракта, строгий JSON, UUID, limit, курсоры | +| Аутентификация | `auth/passwords.ts`, `auth/sessions.ts` | scrypt; создание/проверка/отзыв Bearer-сессий в Valkey | +| Данные | `repositories/{users,chats,messages}.ts`, `models.ts` | весь SQL (только параметры `$n`), транзакция создания чата, типы ответов | +| Инфраструктура | `infra/db.ts`, `infra/valkey.ts`, `config.ts` | пул PostgreSQL и транзакции, клиент Valkey, перевод сбоев зависимостей в 503, настройки из Docker secrets | + +| Роль | Service | Health/readiness | Volume | Порт | Credentials | +|---|---|---|---|---|---| +| API | `api` (`api_short_ttl` в profile `ttl` для теста expiry, порт 8081) | `/health/ready` = `SELECT 1` + `PING` | — | 127.0.0.1:8080 | secrets `database_url`, `cache_url` | +| БД | `postgres` | `pg_isready` | `pgdata` | не публикуется | secret `postgres_password` (`POSTGRES_PASSWORD_FILE`) | +| Сессии | `valkey` | `valkey-cli ping` с паролем | `valkeydata` | не публикуется | `requirepass` из secret `valkey_auth.conf` (`include` в `infra/valkey.conf`) | +| Миграции | `migrate` | exit 0 | — | — | secret `database_url` | + +**Что перенесено из lab1 / что изменено.** Тот же REST-контракт (пользователи, чаты, сообщения, keyset-пагинация, формат ошибок, `X-Request-Id`). Изменено: in-memory → PostgreSQL; регистрация требует `password` (scrypt); `POST /auth/sessions` по Basic выдаёт opaque Bearer-токен; `X-User-Id` игнорируется. + +**Схема** (`migrations/001_init.sql`): `users` (UNIQUE username + CHECK формата), `chats`, `chat_members` (PK `(chat_id,user_id)`, FK на оба), `messages` с составным FK `(chat_id, sender_id) → chat_members` — БД сама гарантирует, что отправитель — участник. Индексы: `chat_members(user_id, chat_id)` для списка чатов, `messages(chat_id, created_at, id)` для истории (обоснование — трек 2). `created_at timestamptz(3)`: миллисекунды точно проходят через JS `Date` и cursor; порядок `(created_at, id)`, время назначает часы БД (`now()`), одни для всех реплик. + +**Миграции** — `src/migrate.ts`: таблица `schema_migrations`, `pg_advisory_lock` против параллельного запуска, каждый файл в своей транзакции (DDL в PostgreSQL транзакционен). Повторный запуск: `skip 001_init` (`evidence/check_and_migrations.txt`). Seed-данных нет. + +**Транзакционные границы.** Создание чата = одна транзакция `INSERT chats` + `INSERT chat_members SELECT unnest(...)`; неизвестный участник → FK violation → ROLLBACK → 400. Отправка сообщения — один `INSERT`; FK violation → 404 (нет чата или не участник, без раскрытия). Гонка регистрации решается UNIQUE-ограничением (23505 → 409). Все запросы параметризованы (`$1..$n`). + +**Сессии (роль Valkey).** Valkey — **единственное хранилище сессий** и их источник истины. Ключ `session:` (в Valkey нет пригодного токена; токен 256 бит, поэтому быстрого хэша достаточно — в отличие от пароля, где нужен медленный KDF). Значение `{uid, exp}`, `SET ... PXAT exp` — абсолютный срок: рестарт не продлевает TTL. Expiry — TTL ключа + проверка `exp` в приложении. Инвалидация — `DEL` при logout (0 удалённых → 401, поэтому двойной logout = 401). Persistence: `appendonly yes`, `appendfsync always` — 201 на вход означает, что сессия на диске; поэтому сессии переживают рестарт Valkey. + +**Отказы.** pg Pool `max=8`, `connectionTimeoutMillis=2000`, `statement_timeout=3000`, `query_timeout=4000`; ioredis `commandTimeout=1000`, без offline-очереди. Потеря соединения/таймаут → `503 unavailable` за ≤2 с; ошибка ограничений → свой код; прочее → `500 internal_error` без деталей. Valkey недоступен → защищённые endpoint 503 (запрос не становится анонимным/доверенным), регистрация работает. PostgreSQL недоступен → 503 всё, кроме liveness. Критичные для `/health/ready` зависимости: PostgreSQL и Valkey. + +**Пароли:** `crypto.scrypt` N=2^14, r=8, p=1, соль 16 байт, `timingSafeEqual`; для неизвестного username считается тот же KDF по фиктивному хэшу — одинаковый 401 и сопоставимое время. + +**Переменные `.env.example` → реальная конфигурация:** `APP_HOST`/`APP_PORT` — то же имя; `SESSION_TTL_SECONDS` — то же; `DATABASE_URL_FILE`/`CACHE_URL_FILE` — то же (`/run/secrets/...`); `SESSION_STORE` не используется — сессии всегда в Valkey; `APP_ENV` не используется. Дополнительно `DB_POOL_MAX`, `DB_POOL_TIMEOUT_MS`. ## Доказательства критериев -| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | -| --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | +| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл | +|---|---|---|---| +| Публичный smoke | `make test` | PASS lab2 | `evidence/smoke.txt` | +| Структура/контракт | `make check` | PASS | `evidence/check_and_migrations.txt` | +| Данные и сессии переживают рестарт API+PG+Valkey | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | PASS; `StartedAt` всех трёх контейнеров изменился, volumes те же | `evidence/persistence.txt` | +| PK/FK/UNIQUE, миграции с нуля и повторно | `docker compose run --rm migrate` | `skip 001_init`, без дублей | `evidence/check_and_migrations.txt` | +| Атомарное создание чата / rollback | `test_chat_rollback` | 400, ни строки в `chats`/`chat_members` | `evidence/level4.txt` | +| Basic только на `/auth/sessions`, Bearer, X-User-Id не даёт доступ, KDF | smoke + `test_wrong_password_and_logout` | 401 с правильным `WWW-Authenticate` | `evidence/smoke.txt`, `evidence/level4.txt` | +| Secrets/volumes не в Git | `git check-ignore` | `secrets/`, `.env`, `backups/`, `dist/` игнорируются | `evidence/check_and_migrations.txt` | +| Valkey с ролью, TTL, persistence | persistence-тест + `test_valkey_outage` | сессия жива после рестарта Valkey (AOF) | `evidence/persistence.txt`, `evidence/level4.txt` | +| Гонка регистрации | `test_registration_race` | 20 параллельных → 1×201, 19×409, 1 строка | `evidence/level4.txt` | +| Ограниченный pool | 32 клиента `tests/load.py` | максимум 8 соединений API в `pg_stat_activity` | `evidence/pool.txt`, `evidence/load.json` | +| Индекс истории + EXPLAIN на ≥10k, keyset без full scan | `experiments/track2/run.py` | 51 строка/11 буферов на странице чата 60k сообщений | `evidence/track2/results.md`, `explain_api_middle_page_V3.txt` | +| Expiry при коротком TTL | `test_expiry` (`api_short_ttl`, TTL=2) | 200 → через 3 с 401 на обоих API | `evidence/level4.txt` | +| Logout, неверный пароль | `test_wrong_password_and_logout` | 204, затем 401 ×2; неверный пароль/пользователь — одинаковый 401 | `evidence/level4.txt` | +| Недоступность Valkey / PostgreSQL | `test_valkey_outage`, `test_postgres_outage` | 503 `unavailable` за 0.02 с / 2.01 с, аноним 401, восстановление с тем же токеном | `evidence/level4.txt` | +| Трек 2 | `experiments/track2/run.py` | см. ниже | `evidence/track2/` | -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +## Эксперименты и отказы — трек 2 -## Эксперименты и отказы +**Гипотеза.** Для keyset-страницы истории нужен индекс `(chat_id, created_at, id)`: цена страницы ≈ `limit` строк и не зависит ни от размера чата, ни от глубины страницы; индекс только по `chat_id` читает весь чат и сортирует, `OFFSET` растёт с глубиной. Дополнительный индекс заметно не ухудшает запись (её цена определяется fsync коммита). Логический dump восстанавливается в новое хранилище без расхождений; потеря данных ограничена моментом начала dump. -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. +**Методика** (`experiments/track2/run.py`, `generate.sql`, seed фиксирован). 239 717 сообщений: 300 синтетических чатов с размерами `round(60000/k^1.2)` (60 000 … 64, медиана 146, 10 крупнейших — 62 %), случайный физический порядок за 90 дней, 1000 пользователей без возможности входа. Варианты индекса: V0 только PK, V1 `(chat_id)`, V2 `(chat_id, created_at)`, V3 `(chat_id, created_at, id)` (индекс миграции, создаётся последним — БД заканчивает в состоянии миграции). Запросы: первая страница и середина чата запросом API (row comparison), тот же с дополнительным `created_at >= $ts`, и `OFFSET`; чаты large/medium/small. Каждый запрос — 5 × `EXPLAIN (ANALYZE, BUFFERS)`, медиана. Запись: 3 × bulk INSERT 50k строк в одной транзакции и 3 × pgbench 10 с, 8 клиентов, 1-row INSERT (коммит на каждую строку), после каждого прогона DELETE + VACUUM. Окружение: PostgreSQL 17.6, shared_buffers 128 MB, synchronous_commit on, OrbStack VM 11 CPU / 9 GiB, без CPU-лимитов, прогрев — повторы (горячий кэш). -| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | -| --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +**Результаты чтения** (медиана мс / буферы / прочитанные строки, полная таблица — `evidence/track2/results.md`): + +| запрос / чат | V0 PK | V1 chat_id | V2 chat_id,created_at | V3 chat_id,created_at,id | +|---|---|---|---|---| +| середина, keyset API / large 60k | 25.2 / 9030 / 239 718 | 24.6 / 9055 / 60 000 | 0.19 / 21 / 53 | **0.26 / 11 / 51** | +| середина, keyset API / small 64 | 21.3 / 9030 / 239 715 | 0.64 / 72 / 64 | 0.37 / 44 / 32 | 0.49 / 35 / 31 | +| середина, OFFSET / large | 81.4 / 9088 | 42.2 / 9055 | 80.2 / 9088 | 15.3 / 6145 / 30 051 | + +Планы запроса API для large: V0 `Sort > Seq Scan`, V1 `Sort > Bitmap Heap Scan`, V2 `Incremental Sort > Index Scan`, V3 `Limit > Index Scan messages_chat_created_id_idx` с `Index Cond: chat_id = … AND ROW(created_at, id) > ROW(…)` — без сортировки и без полного сканирования истории. + +**Стоимость записи:** + +| вариант | размер индекса | bulk 50k, мс | pgbench TPS | latency, мс | +|---|---|---|---|---| +| V0 PK | — | 2158 | 2237 | 3.58 | +| V1 | 1.7 MiB | 1174 | 1820 | 4.40 | +| V2 | 9.3 MiB | 1748 | 1338 | 5.98 | +| V3 | 13.5 MiB | 1062 | 1659 | 4.82 | + +**Backup → restore → сверка.** `pg_dump -Fc` 3.37 с, 16.1 MB; восстановление в **новый контейнер с новым volume** без сети: `pg_restore -j1` 3.76 с, `-j4` 4.01 с. Отпечатки (count + md5 по всем строкам каждой таблицы, 20 выбранных сообщений) совпали; страница API крупнейшего чата на обеих БД идентична; на восстановленной БД план тот же (`Index Scan messages_chat_created_id_idx`). Во время dump параллельный писатель закоммитил 13 сообщений — в восстановленной БД из них 1 (закоммиченное до снимка): dump — согласованный снимок на момент старта. + +**Выводы.** +1. Гипотеза о чтении подтверждена: V3 читает 51 строку и ~11 буферов независимо от размера чата (60 000 vs 64) и глубины страницы; V1 читает весь чат (60 000 строк, ~25 мс), V0 — всю таблицу. V2 почти так же быстр на этих данных, но только потому, что дубли `created_at` редки: при совпадении миллисекунд ему нужна Incremental Sort, а row comparison не становится условием индекса — V3 надёжнее. Переписывание с `created_at >=` V2 не помогло существенно, V3 его не требует. +2. `OFFSET` даже с V3 читает `offset+limit` строк (30 051, 15 мс) — поэтому API использует keyset cursor. +3. Запись: с fsync на каждом коммите pgbench показывает падение TPS на ~25 % для V3 относительно V0 (2237 → 1659); bulk-вставка в одной транзакции разницы не показала (разброс прогонов больше эффекта — первый вариант пришёлся на «холодный» кэш после генерации). Гипотеза «индекс почти бесплатен» подтверждена лишь частично: цена есть, но на порядок меньше выигрыша чтения. +4. RTO на этом объёме ≈ 4 с восстановления + старт контейнера; `-j4` не ускорил (мало таблиц, восстановление ограничено одним крупным индексом/таблицей). RPO логического dump = время с начала последнего dump; всё, что закоммичено после снимка, теряется. Для меньшего RPO нужен `pg_basebackup` + архив WAL (PITR) — не реализовано. Сессии в dump не входят (Valkey AOF — отдельная резервная копия); при восстановлении PG с тем же содержимым действующие токены продолжают работать, так как ссылаются на те же UUID пользователей. + +**Ограничения измерения.** Один хост, виртуализированный fsync OrbStack — абсолютные TPS не переносимы. Горячий кэш (данные 74 MB < RAM), холодное чтение не измерялось. 5/3 повтора, медианы; разброс записи заметен. Данные синтетические, вставлены SQL-ом в обход API. + +| Воздействие | Что ожидаем | Что наблюдали | Восстановление / потеря данных | +|---|---|---|---| +| `scripts/restart.sh`: stop+start api, postgres, valkey | данные и токен сохранены | PASS persistence | ~5 с, потерь нет | +| stop valkey | 503 на защищённых, регистрация работает | 503 за 0.02 с, POST /users 201 | после start тот же токен работает | +| stop postgres | 503 за ограниченное время | 503 за 2.01 с | после start восстановление, токен жив | +| пишущий клиент во время pg_dump | записи после снимка не в backup | 13 записано, 1 в restore | потеря = записи после старта dump | ## Ограничения и следующие шаги -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +- Один API-процесс и одна БД/Valkey на одном Docker-хосте: потеря хоста или volume не переживается. HA и балансировка — lab3. +- `appendfsync always` замедляет вход (каждая сессия — fsync); при `everysec` можно потерять до 1 с выданных сессий. +- HTTP без TLS — только локальный стенд с синтетическими данными. Argon2id и TLS — lab7. +- Нет CI-job для сборки стенда и `make test`; проверки запускаются локально командами выше. +- Нет rate limiting на вход (перебор паролей ограничен только стоимостью scrypt). diff --git a/compose.yaml b/compose.yaml new file mode 100644 index 00000000..b1f595a2 --- /dev/null +++ b/compose.yaml @@ -0,0 +1,86 @@ +name: messenger-lab2 + +x-api: &api + build: . + image: messenger-lab2-api:local + environment: &api-env + APP_HOST: 0.0.0.0 + APP_PORT: 8080 + SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600} + DATABASE_URL_FILE: /run/secrets/database_url + CACHE_URL_FILE: /run/secrets/cache_url + DB_POOL_MAX: 8 + DB_POOL_TIMEOUT_MS: 2000 + secrets: [database_url, cache_url] + depends_on: + migrate: { condition: service_completed_successfully } + postgres: { condition: service_healthy } + valkey: { condition: service_healthy } + restart: unless-stopped + +services: + postgres: + image: postgres:17.6-alpine3.22 + environment: + POSTGRES_USER: messenger + POSTGRES_DB: messenger + POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password + secrets: [postgres_password] + volumes: [pgdata:/var/lib/postgresql/data] + healthcheck: + test: ["CMD-SHELL", "pg_isready -U messenger -d messenger"] + interval: 2s + timeout: 3s + retries: 30 + stop_grace_period: 30s + restart: unless-stopped + + valkey: + image: valkey/valkey:8.1.4-alpine3.22 + command: ["valkey-server", "/usr/local/etc/valkey/valkey.conf"] + volumes: + - valkeydata:/data + - ./infra/valkey.conf:/usr/local/etc/valkey/valkey.conf:ro + secrets: + - source: valkey_auth + target: valkey_auth.conf + healthcheck: + test: ["CMD-SHELL", "REDISCLI_AUTH=$$(sed -n 's/^requirepass //p' /run/secrets/valkey_auth.conf) valkey-cli ping | grep -q PONG"] + interval: 2s + timeout: 3s + retries: 30 + restart: unless-stopped + + migrate: + build: . + image: messenger-lab2-api:local + command: ["node", "dist/migrate.js"] + environment: + DATABASE_URL_FILE: /run/secrets/database_url + secrets: [database_url] + depends_on: + postgres: { condition: service_healthy } + restart: "no" + + api: + <<: *api + ports: ["127.0.0.1:${APP_PORT:-8080}:8080"] + + # Второй процесс API с TTL 2 с для автотеста истечения сессии (те же БД и Valkey). + api_short_ttl: + <<: *api + profiles: [ttl] + environment: + <<: *api-env + SESSION_TTL_SECONDS: 2 + ports: ["127.0.0.1:8081:8080"] + +secrets: + postgres_password: { file: ./secrets/postgres_password } + database_url: { file: ./secrets/database_url } + cache_url: { file: ./secrets/cache_url } + valkey_auth: { file: ./secrets/valkey_auth.conf } + +volumes: + pgdata: + valkeydata: diff --git a/evidence/check_and_migrations.txt b/evidence/check_and_migrations.txt new file mode 100644 index 00000000..49ad2896 --- /dev/null +++ b/evidence/check_and_migrations.txt @@ -0,0 +1,8 @@ +# 2026-10-29T17:42:34Z commit 65003b6+wip +python3 scripts/check_contract.py +PASS: offline skeleton structure, local refs and Python syntax; application NOT tested. +skip 001_init +.gitignore:5:secrets/ secrets/database_url +.gitignore:2:.env .env +.gitignore:15:backups/ backups/ +.gitignore:33:dist/ dist/ diff --git a/evidence/level4.txt b/evidence/level4.txt new file mode 100644 index 00000000..1ef88cc6 --- /dev/null +++ b/evidence/level4.txt @@ -0,0 +1,7 @@ +PASS test_registration_race - 20 parallel registrations of one username -> 1x201, 19x409, 1 row +PASS test_chat_rollback - chat with unknown member -> 400, no chat/member rows (transaction rolled back) +PASS test_pagination_and_injection - 57 messages over limit=7 pages: exact order, no dupes; foreign/garbage cursor -> 400; SQL text stored verbatim +PASS test_wrong_password_and_logout - wrong password / unknown user -> identical 401 Basic; logout -> 204, then 401 twice +PASS test_expiry - SESSION_TTL_SECONDS=2: 200 right after login, 401 after 3 s on both API processes +PASS test_valkey_outage - valkey stopped -> ready/me 503 unavailable in 0.00s, anonymous 401, registration 201; recovered with same token +PASS test_postgres_outage - postgres stopped -> ready/me 503 unavailable in 2.01s, anonymous 401, registration 503; recovered with same token diff --git a/evidence/load.json b/evidence/load.json new file mode 100644 index 00000000..840f28f0 --- /dev/null +++ b/evidence/load.json @@ -0,0 +1,17 @@ +{ + "lab": 2, + "workload": "closed-loop POST messages; no automatic retries", + "requested_duration_seconds": 15.0, + "elapsed_seconds": 15.15, + "concurrency": 32, + "successful_requests": 7553, + "failed_requests": 0, + "error_ratio": 0.0, + "successful_rps": 498.545, + "successful_latency_ms": { + "p50": 54.672, + "p95": 123.874, + "p99": 213.309 + }, + "note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead." +} diff --git a/evidence/persistence.txt b/evidence/persistence.txt new file mode 100644 index 00000000..b8185efc --- /dev/null +++ b/evidence/persistence.txt @@ -0,0 +1,14 @@ +# до +api 2026-10-29T19:24:06.025293463Z +postgres 2026-10-29T17:47:05.59081531Z +valkey 2026-10-29T17:46:58.822273137Z +python3 tests/resilience.py --mode persistence --action-script "scripts/restart.sh" --base-url "http://127.0.0.1:8080" +Executing explicit persistence hook; hook output suppressed to avoid leaking secrets. +PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence. +# после (StartedAt всех трёх изменился, volumes те же) +api 2026-10-29T19:24:22.684206123Z +postgres 2026-10-29T19:24:19.291967372Z +valkey 2026-10-29T19:24:19.294812208Z +DRIVER VOLUME NAME +local messenger-lab2_pgdata +local messenger-lab2_valkeydata diff --git a/evidence/pool.txt b/evidence/pool.txt new file mode 100644 index 00000000..0e457428 --- /dev/null +++ b/evidence/pool.txt @@ -0,0 +1 @@ +max API connections observed during 32-client load: 8 (DB_POOL_MAX=8) diff --git a/evidence/smoke.txt b/evidence/smoke.txt new file mode 100644 index 00000000..1efe0027 --- /dev/null +++ b/evidence/smoke.txt @@ -0,0 +1,3 @@ +# 2026-10-29T19:24:17Z +python3 tests/smoke.py --base-url "http://127.0.0.1:8080" +PASS: lab2 public API scenario; infrastructure and grading evidence remain separate. diff --git a/evidence/track2/explain_api_middle_page_V0.txt b/evidence/track2/explain_api_middle_page_V0.txt new file mode 100644 index 00000000..df4e57dc --- /dev/null +++ b/evidence/track2/explain_api_middle_page_V0.txt @@ -0,0 +1,20 @@ +Limit (cost=12317.65..12323.60 rows=51 width=269) (actual time=18.151..22.092 rows=51 loops=1) + Buffers: shared hit=9184 + -> Gather Merge (cost=12317.65..15225.19 rows=24920 width=269) (actual time=18.150..22.087 rows=51 loops=1) + Workers Planned: 2 + Workers Launched: 2 + Buffers: shared hit=9184 + -> Sort (cost=11317.63..11348.78 rows=12460 width=269) (actual time=15.433..15.437 rows=39 loops=3) + Sort Key: created_at, id + Sort Method: top-N heapsort Memory: 57kB + Buffers: shared hit=9184 + Worker 0: Sort Method: top-N heapsort Memory: 64kB + Worker 1: Sort Method: top-N heapsort Memory: 64kB + -> Parallel Seq Scan on messages (cost=0.00..10901.94 rows=12460 width=269) (actual time=0.013..13.836 rows=10000 loops=3) + Filter: ((chat_id = '43815b30-3214-43ab-907b-8302428adf62'::uuid) AND (ROW(created_at, id) > ROW('2026-09-14 15:04:07.432+00'::timestamp with time zone, 'b4df760e-4412-48fc-90cc-814d6b6c9617'::uuid))) + Rows Removed by Filter: 69906 + Buffers: shared hit=9154 +Planning: + Buffers: shared hit=121 +Planning Time: 1.035 ms +Execution Time: 22.224 ms diff --git a/evidence/track2/explain_api_middle_page_V1.txt b/evidence/track2/explain_api_middle_page_V1.txt new file mode 100644 index 00000000..5d6c15b0 --- /dev/null +++ b/evidence/track2/explain_api_middle_page_V1.txt @@ -0,0 +1,25 @@ +Limit (cost=11649.09..11655.04 rows=51 width=269) (actual time=31.363..35.221 rows=51 loops=1) + Buffers: shared hit=9056 + -> Gather Merge (cost=11649.09..14602.13 rows=25310 width=269) (actual time=31.361..35.215 rows=51 loops=1) + Workers Planned: 2 + Workers Launched: 2 + Buffers: shared hit=9056 + -> Sort (cost=10649.07..10680.71 rows=12655 width=269) (actual time=26.965..26.970 rows=42 loops=3) + Sort Key: created_at, id + Sort Method: top-N heapsort Memory: 57kB + Buffers: shared hit=9056 + Worker 0: Sort Method: top-N heapsort Memory: 57kB + Worker 1: Sort Method: top-N heapsort Memory: 57kB + -> Parallel Bitmap Heap Scan on messages (cost=783.77..10226.87 rows=12655 width=269) (actual time=2.405..24.972 rows=10000 loops=3) + Recheck Cond: (chat_id = '43815b30-3214-43ab-907b-8302428adf62'::uuid) + Filter: (ROW(created_at, id) > ROW('2026-09-14 15:04:07.432+00'::timestamp with time zone, 'b4df760e-4412-48fc-90cc-814d6b6c9617'::uuid)) + Rows Removed by Filter: 10000 + Heap Blocks: exact=3179 + Buffers: shared hit=9026 + -> Bitmap Index Scan on exp_idx (cost=0.00..776.18 rows=60768 width=0) (actual time=3.679..3.680 rows=60000 loops=1) + Index Cond: (chat_id = '43815b30-3214-43ab-907b-8302428adf62'::uuid) + Buffers: shared hit=55 +Planning: + Buffers: shared hit=134 +Planning Time: 0.990 ms +Execution Time: 35.634 ms diff --git a/evidence/track2/explain_api_middle_page_V2.txt b/evidence/track2/explain_api_middle_page_V2.txt new file mode 100644 index 00000000..90acae23 --- /dev/null +++ b/evidence/track2/explain_api_middle_page_V2.txt @@ -0,0 +1,16 @@ +Limit (cost=1.71..69.21 rows=51 width=268) (actual time=0.158..0.183 rows=51 loops=1) + Buffers: shared hit=21 + -> Incremental Sort (cost=1.71..40391.63 rows=30516 width=268) (actual time=0.145..0.168 rows=51 loops=1) + Sort Key: created_at, id + Presorted Key: created_at + Full-sort Groups: 2 Sort Method: quicksort Average Memory: 41kB Peak Memory: 41kB + Buffers: shared hit=21 + -> Index Scan using exp_idx on messages (cost=0.42..39018.41 rows=30516 width=268) (actual time=0.039..0.070 rows=52 loops=1) + Index Cond: ((chat_id = '43815b30-3214-43ab-907b-8302428adf62'::uuid) AND (created_at >= '2026-09-14 15:04:07.432+00'::timestamp with time zone)) + Filter: (ROW(created_at, id) > ROW('2026-09-14 15:04:07.432+00'::timestamp with time zone, 'b4df760e-4412-48fc-90cc-814d6b6c9617'::uuid)) + Rows Removed by Filter: 1 + Buffers: shared hit=12 +Planning: + Buffers: shared hit=150 +Planning Time: 1.476 ms +Execution Time: 0.278 ms diff --git a/evidence/track2/explain_api_middle_page_V3.txt b/evidence/track2/explain_api_middle_page_V3.txt new file mode 100644 index 00000000..027374bd --- /dev/null +++ b/evidence/track2/explain_api_middle_page_V3.txt @@ -0,0 +1,9 @@ +Limit (cost=0.42..64.91 rows=51 width=267) (actual time=0.032..0.059 rows=51 loops=1) + Buffers: shared hit=11 + -> Index Scan using messages_chat_created_id_idx on messages (cost=0.42..38137.55 rows=30161 width=267) (actual time=0.030..0.054 rows=51 loops=1) + Index Cond: ((chat_id = '43815b30-3214-43ab-907b-8302428adf62'::uuid) AND (ROW(created_at, id) > ROW('2026-09-14 15:04:07.432+00'::timestamp with time zone, 'b4df760e-4412-48fc-90cc-814d6b6c9617'::uuid))) + Buffers: shared hit=11 +Planning: + Buffers: shared hit=144 +Planning Time: 1.388 ms +Execution Time: 0.107 ms diff --git a/evidence/track2/results.json b/evidence/track2/results.json new file mode 100644 index 00000000..415ef9b3 --- /dev/null +++ b/evidence/track2/results.json @@ -0,0 +1,495 @@ +{ + "env": { + "postgres": "17.6", + "shared_buffers": "128MB", + "synchronous_commit": "on", + "docker": "OrbStack, 11 CPU, 9434726400 B RAM" + }, + "dataset": { + "messages_total": 239717, + "track2_chats": 300, + "chat_size_max": 60000, + "chat_size_p50": 146, + "chat_size_min": 64, + "top10_share": 0.618, + "messages_table_bytes": 73785344, + "pk_index_bytes": 9633792 + }, + "chats": { + "large": { + "size": 60000, + "offset": 30000 + }, + "medium": { + "size": 1013, + "offset": 506 + }, + "small": { + "size": 64, + "offset": 32 + } + }, + "variants": { + "V0 PK only": { + "index_build_s": 0.0, + "index_bytes": 0, + "queries": { + "first page (API) / large": { + "median_ms": 25.559, + "min_ms": 22.098, + "buffers": 9030, + "rows_touched": 239718, + "plan": "Limit > Gather Merge > Sort > Seq Scan" + }, + "first page (API) / medium": { + "median_ms": 25.16, + "min_ms": 21.963, + "buffers": 9030, + "rows_touched": 239718, + "plan": "Limit > Gather Merge > Sort > Seq Scan" + }, + "first page (API) / small": { + "median_ms": 29.764, + "min_ms": 23.438, + "buffers": 9030, + "rows_touched": 239715, + "plan": "Limit > Gather Merge > Sort > Seq Scan" + }, + "middle page keyset (API) / large": { + "median_ms": 25.172, + "min_ms": 23.475, + "buffers": 9030, + "rows_touched": 239718, + "plan": "Limit > Gather Merge > Sort > Seq Scan" + }, + "middle page keyset (API) / medium": { + "median_ms": 23.408, + "min_ms": 19.072, + "buffers": 9030, + "rows_touched": 239718, + "plan": "Limit > Gather Merge > Sort > Seq Scan" + }, + "middle page keyset (API) / small": { + "median_ms": 21.248, + "min_ms": 18.796, + "buffers": 9030, + "rows_touched": 239715, + "plan": "Limit > Gather Merge > Sort > Seq Scan" + }, + "middle page keyset + created_at >= / large": { + "median_ms": 28.129, + "min_ms": 26.33, + "buffers": 9030, + "rows_touched": 239718, + "plan": "Limit > Gather Merge > Sort > Seq Scan" + }, + "middle page keyset + created_at >= / medium": { + "median_ms": 26.974, + "min_ms": 23.012, + "buffers": 9030, + "rows_touched": 239718, + "plan": "Limit > Gather Merge > Sort > Seq Scan" + }, + "middle page keyset + created_at >= / small": { + "median_ms": 24.638, + "min_ms": 23.061, + "buffers": 9030, + "rows_touched": 239715, + "plan": "Limit > Gather Merge > Sort > Seq Scan" + }, + "middle page OFFSET / large": { + "median_ms": 81.353, + "min_ms": 64.787, + "buffers": 9088, + "rows_touched": 239718, + "plan": "Limit > Gather Merge > Sort > Seq Scan" + }, + "middle page OFFSET / medium": { + "median_ms": 25.937, + "min_ms": 25.476, + "buffers": 9088, + "rows_touched": 239718, + "plan": "Limit > Gather Merge > Sort > Seq Scan" + }, + "middle page OFFSET / small": { + "median_ms": 32.843, + "min_ms": 25.142, + "buffers": 9088, + "rows_touched": 239715, + "plan": "Limit > Gather Merge > Sort > Seq Scan" + } + }, + "write": { + "bulk_50k_ms_median": 2158.3, + "bulk_50k_ms": [ + 1779.713, + 2495.609, + 2158.347 + ], + "pgbench_tps_median": 2237.1, + "pgbench_tps": [ + 717.137925, + 2237.08345, + 2524.645924 + ], + "pgbench_latency_ms_median": 3.576 + } + }, + "V1 (chat_id)": { + "index_build_s": 0.299, + "index_bytes": 1744896, + "queries": { + "first page (API) / large": { + "median_ms": 35.605, + "min_ms": 31.245, + "buffers": 9055, + "rows_touched": 60000, + "plan": "Limit > Gather Merge > Sort > Bitmap Heap Scan > Bitmap Index Scan exp_idx" + }, + "first page (API) / medium": { + "median_ms": 4.349, + "min_ms": 4.113, + "buffers": 965, + "rows_touched": 1013, + "plan": "Limit > Sort > Bitmap Heap Scan > Bitmap Index Scan exp_idx" + }, + "first page (API) / small": { + "median_ms": 0.547, + "min_ms": 0.416, + "buffers": 72, + "rows_touched": 64, + "plan": "Limit > Sort > Bitmap Heap Scan > Bitmap Index Scan exp_idx" + }, + "middle page keyset (API) / large": { + "median_ms": 24.591, + "min_ms": 22.198, + "buffers": 9055, + "rows_touched": 60000, + "plan": "Limit > Gather Merge > Sort > Bitmap Heap Scan > Bitmap Index Scan exp_idx" + }, + "middle page keyset (API) / medium": { + "median_ms": 3.597, + "min_ms": 2.878, + "buffers": 965, + "rows_touched": 1013, + "plan": "Limit > Sort > Bitmap Heap Scan > Bitmap Index Scan exp_idx" + }, + "middle page keyset (API) / small": { + "median_ms": 0.638, + "min_ms": 0.396, + "buffers": 72, + "rows_touched": 64, + "plan": "Limit > Sort > Bitmap Heap Scan > Bitmap Index Scan exp_idx" + }, + "middle page keyset + created_at >= / large": { + "median_ms": 35.804, + "min_ms": 32.3, + "buffers": 9031, + "rows_touched": 60000, + "plan": "Limit > Sort > Bitmap Heap Scan > Bitmap Index Scan exp_idx" + }, + "middle page keyset + created_at >= / medium": { + "median_ms": 3.128, + "min_ms": 2.654, + "buffers": 965, + "rows_touched": 1013, + "plan": "Limit > Sort > Bitmap Heap Scan > Bitmap Index Scan exp_idx" + }, + "middle page keyset + created_at >= / small": { + "median_ms": 0.437, + "min_ms": 0.35, + "buffers": 72, + "rows_touched": 64, + "plan": "Limit > Sort > Bitmap Heap Scan > Bitmap Index Scan exp_idx" + }, + "middle page OFFSET / large": { + "median_ms": 42.147, + "min_ms": 36.78, + "buffers": 9055, + "rows_touched": 60000, + "plan": "Limit > Gather Merge > Sort > Bitmap Heap Scan > Bitmap Index Scan exp_idx" + }, + "middle page OFFSET / medium": { + "median_ms": 3.011, + "min_ms": 2.724, + "buffers": 965, + "rows_touched": 1013, + "plan": "Limit > Sort > Bitmap Heap Scan > Bitmap Index Scan exp_idx" + }, + "middle page OFFSET / small": { + "median_ms": 0.399, + "min_ms": 0.367, + "buffers": 72, + "rows_touched": 64, + "plan": "Limit > Sort > Bitmap Heap Scan > Bitmap Index Scan exp_idx" + } + }, + "write": { + "bulk_50k_ms_median": 1173.6, + "bulk_50k_ms": [ + 1173.602, + 1115.078, + 1515.873 + ], + "pgbench_tps_median": 1820.2, + "pgbench_tps": [ + 1820.161379, + 2070.254695, + 915.294613 + ], + "pgbench_latency_ms_median": 4.395 + } + }, + "V2 (chat_id, created_at)": { + "index_build_s": 0.345, + "index_bytes": 9756672, + "queries": { + "first page (API) / large": { + "median_ms": 0.143, + "min_ms": 0.134, + "buffers": 25, + "rows_touched": 52, + "plan": "Limit > Incremental Sort > Index Scan exp_idx" + }, + "first page (API) / medium": { + "median_ms": 0.344, + "min_ms": 0.299, + "buffers": 63, + "rows_touched": 52, + "plan": "Limit > Incremental Sort > Index Scan exp_idx" + }, + "first page (API) / small": { + "median_ms": 0.386, + "min_ms": 0.342, + "buffers": 63, + "rows_touched": 52, + "plan": "Limit > Incremental Sort > Index Scan exp_idx" + }, + "middle page keyset (API) / large": { + "median_ms": 0.193, + "min_ms": 0.151, + "buffers": 21, + "rows_touched": 53, + "plan": "Limit > Incremental Sort > Index Scan exp_idx" + }, + "middle page keyset (API) / medium": { + "median_ms": 0.604, + "min_ms": 0.307, + "buffers": 66, + "rows_touched": 53, + "plan": "Limit > Incremental Sort > Index Scan exp_idx" + }, + "middle page keyset (API) / small": { + "median_ms": 0.37, + "min_ms": 0.279, + "buffers": 44, + "rows_touched": 32, + "plan": "Limit > Incremental Sort > Index Scan exp_idx" + }, + "middle page keyset + created_at >= / large": { + "median_ms": 0.345, + "min_ms": 0.203, + "buffers": 21, + "rows_touched": 53, + "plan": "Limit > Incremental Sort > Index Scan exp_idx" + }, + "middle page keyset + created_at >= / medium": { + "median_ms": 0.488, + "min_ms": 0.365, + "buffers": 66, + "rows_touched": 53, + "plan": "Limit > Incremental Sort > Index Scan exp_idx" + }, + "middle page keyset + created_at >= / small": { + "median_ms": 0.425, + "min_ms": 0.389, + "buffers": 41, + "rows_touched": 32, + "plan": "Limit > Sort > Bitmap Heap Scan > Bitmap Index Scan exp_idx" + }, + "middle page OFFSET / large": { + "median_ms": 80.175, + "min_ms": 70.332, + "buffers": 9088, + "rows_touched": 239718, + "plan": "Limit > Gather Merge > Sort > Seq Scan" + }, + "middle page OFFSET / medium": { + "median_ms": 2.533, + "min_ms": 2.31, + "buffers": 554, + "rows_touched": 558, + "plan": "Limit > Incremental Sort > Index Scan exp_idx" + }, + "middle page OFFSET / small": { + "median_ms": 0.738, + "min_ms": 0.45, + "buffers": 75, + "rows_touched": 64, + "plan": "Limit > Incremental Sort > Index Scan exp_idx" + } + }, + "write": { + "bulk_50k_ms_median": 1747.7, + "bulk_50k_ms": [ + 2169.21, + 1747.667, + 1210.19 + ], + "pgbench_tps_median": 1337.9, + "pgbench_tps": [ + 1337.947649, + 1265.008351, + 1626.184355 + ], + "pgbench_latency_ms_median": 5.979 + } + }, + "V3 (chat_id, created_at, id)": { + "index_build_s": 0.485, + "index_bytes": 14139392, + "queries": { + "first page (API) / large": { + "median_ms": 0.223, + "min_ms": 0.129, + "buffers": 15, + "rows_touched": 51, + "plan": "Limit > Index Scan messages_chat_created_id_idx" + }, + "first page (API) / medium": { + "median_ms": 0.422, + "min_ms": 0.242, + "buffers": 53, + "rows_touched": 51, + "plan": "Limit > Index Scan messages_chat_created_id_idx" + }, + "first page (API) / small": { + "median_ms": 0.541, + "min_ms": 0.322, + "buffers": 53, + "rows_touched": 51, + "plan": "Limit > Index Scan messages_chat_created_id_idx" + }, + "middle page keyset (API) / large": { + "median_ms": 0.262, + "min_ms": 0.115, + "buffers": 11, + "rows_touched": 51, + "plan": "Limit > Index Scan messages_chat_created_id_idx" + }, + "middle page keyset (API) / medium": { + "median_ms": 0.454, + "min_ms": 0.433, + "buffers": 55, + "rows_touched": 51, + "plan": "Limit > Index Scan messages_chat_created_id_idx" + }, + "middle page keyset (API) / small": { + "median_ms": 0.491, + "min_ms": 0.455, + "buffers": 35, + "rows_touched": 31, + "plan": "Limit > Index Scan messages_chat_created_id_idx" + }, + "middle page keyset + created_at >= / large": { + "median_ms": 0.116, + "min_ms": 0.097, + "buffers": 11, + "rows_touched": 51, + "plan": "Limit > Index Scan messages_chat_created_id_idx" + }, + "middle page keyset + created_at >= / medium": { + "median_ms": 0.233, + "min_ms": 0.194, + "buffers": 55, + "rows_touched": 51, + "plan": "Limit > Index Scan messages_chat_created_id_idx" + }, + "middle page keyset + created_at >= / small": { + "median_ms": 0.35, + "min_ms": 0.237, + "buffers": 41, + "rows_touched": 31, + "plan": "Limit > Sort > Bitmap Heap Scan > Bitmap Index Scan messages_chat_created_id_idx" + }, + "middle page OFFSET / large": { + "median_ms": 15.321, + "min_ms": 13.814, + "buffers": 6145, + "rows_touched": 30051, + "plan": "Limit > Index Scan messages_chat_created_id_idx" + }, + "middle page OFFSET / medium": { + "median_ms": 1.883, + "min_ms": 1.576, + "buffers": 545, + "rows_touched": 557, + "plan": "Limit > Index Scan messages_chat_created_id_idx" + }, + "middle page OFFSET / small": { + "median_ms": 0.377, + "min_ms": 0.248, + "buffers": 67, + "rows_touched": 64, + "plan": "Limit > Index Scan messages_chat_created_id_idx" + } + }, + "write": { + "bulk_50k_ms_median": 1061.7, + "bulk_50k_ms": [ + 899.73, + 1367.955, + 1061.711 + ], + "pgbench_tps_median": 1659.2, + "pgbench_tps": [ + 1851.131479, + 981.989419, + 1659.177954 + ], + "pgbench_latency_ms_median": 4.822 + } + } + }, + "backup_restore": { + "dump_bytes": 16135498, + "dump_s": 3.37, + "restore_s": { + "jobs_1": 3.76, + "jobs_4": 4.01 + }, + "messages_before_dump": 239717, + "during_dump_committed_in_source": 13, + "during_dump_in_restore": 1, + "fingerprint_equal": true, + "api_page_equal": true, + "fingerprint": [ + [ + "users", + "1019", + "42d7e548b2d4ee91736961faca386d0a" + ], + [ + "chats", + "306", + "d2541ecae4fa59a1f1192498d0f5b4e0" + ], + [ + "chat_members", + "3295", + "4f1cf6a7c65e7a56c072c20877d7d28f" + ], + [ + "messages", + "239717", + "1c0251c775eecc3ffc43c28b81084eea" + ], + [ + "schema_migrations", + "1", + "550e0a1f7ef8568bdbe21b29ffb5399b" + ] + ], + "restored_plan_middle_page_large": "Limit > Index Scan messages_chat_created_id_idx" + } +} diff --git a/evidence/track2/results.md b/evidence/track2/results.md new file mode 100644 index 00000000..e16a11cb --- /dev/null +++ b/evidence/track2/results.md @@ -0,0 +1,53 @@ +# Track 2 results + +Generated by experiments/track2/run.py from results.json. Environment: OrbStack, 11 CPU, 9434726400 B RAM; PostgreSQL 17.6, shared_buffers 128MB, synchronous_commit on. + +Dataset: 239717 messages, 300 synthetic chats, sizes max 60000 / median 146 / min 64, top-10 chats hold 0.618 of track2 messages, table 73785344 B. + +## Read: median ms of 5 EXPLAIN ANALYZE runs / shared buffers / rows read by scans + +| query / chat | V0 PK only | V1 (chat_id) | V2 (chat_id, created_at) | V3 (chat_id, created_at, id) | +|---|---|---|---|---| +| first page (API) / large | 25.56 / 9030 / 239718 | 35.60 / 9055 / 60000 | 0.14 / 25 / 52 | 0.22 / 15 / 51 | +| first page (API) / medium | 25.16 / 9030 / 239718 | 4.35 / 965 / 1013 | 0.34 / 63 / 52 | 0.42 / 53 / 51 | +| first page (API) / small | 29.76 / 9030 / 239715 | 0.55 / 72 / 64 | 0.39 / 63 / 52 | 0.54 / 53 / 51 | +| middle page keyset (API) / large | 25.17 / 9030 / 239718 | 24.59 / 9055 / 60000 | 0.19 / 21 / 53 | 0.26 / 11 / 51 | +| middle page keyset (API) / medium | 23.41 / 9030 / 239718 | 3.60 / 965 / 1013 | 0.60 / 66 / 53 | 0.45 / 55 / 51 | +| middle page keyset (API) / small | 21.25 / 9030 / 239715 | 0.64 / 72 / 64 | 0.37 / 44 / 32 | 0.49 / 35 / 31 | +| middle page keyset + created_at >= / large | 28.13 / 9030 / 239718 | 35.80 / 9031 / 60000 | 0.34 / 21 / 53 | 0.12 / 11 / 51 | +| middle page keyset + created_at >= / medium | 26.97 / 9030 / 239718 | 3.13 / 965 / 1013 | 0.49 / 66 / 53 | 0.23 / 55 / 51 | +| middle page keyset + created_at >= / small | 24.64 / 9030 / 239715 | 0.44 / 72 / 64 | 0.42 / 41 / 32 | 0.35 / 41 / 31 | +| middle page OFFSET / large | 81.35 / 9088 / 239718 | 42.15 / 9055 / 60000 | 80.17 / 9088 / 239718 | 15.32 / 6145 / 30051 | +| middle page OFFSET / medium | 25.94 / 9088 / 239718 | 3.01 / 965 / 1013 | 2.53 / 554 / 558 | 1.88 / 545 / 557 | +| middle page OFFSET / small | 32.84 / 9088 / 239715 | 0.40 / 72 / 64 | 0.74 / 75 / 64 | 0.38 / 67 / 64 | + +Plans of the API query (middle page, large chat): + +- V0 PK only: `Limit > Gather Merge > Sort > Seq Scan` +- V1 (chat_id): `Limit > Gather Merge > Sort > Bitmap Heap Scan > Bitmap Index Scan exp_idx` +- V2 (chat_id, created_at): `Limit > Incremental Sort > Index Scan exp_idx` +- V3 (chat_id, created_at, id): `Limit > Index Scan messages_chat_created_id_idx` + +## Write cost + +| variant | index size, MiB | build, s | bulk 50k INSERT, ms (median of 3) | pgbench 1-row INSERT, TPS (median of 3x10 s, 8 clients) | avg latency, ms | +|---|---|---|---|---|---| +| V0 PK only | 0.0 | 0.00 | 2158 | 2237 | 3.576 | +| V1 (chat_id) | 1.7 | 0.30 | 1174 | 1820 | 4.395 | +| V2 (chat_id, created_at) | 9.3 | 0.34 | 1748 | 1338 | 5.979 | +| V3 (chat_id, created_at, id) | 13.5 | 0.48 | 1062 | 1659 | 4.822 | + +## Backup -> restore into new storage -> reconcile + +- pg_dump -Fc: 3.37 s, 16135498 B; pg_restore into a new container + new volume: {'jobs_1': 3.76, 'jobs_4': 4.01} +- fingerprints (count + md5 of every table, 20 sampled messages) equal: True; API page of the large chat equal: True +- writes committed during pg_dump: 13 in source, 1 in restore +- restored plan of the API query: `Limit > Index Scan messages_chat_created_id_idx` + +| table | rows | md5 | +|---|---|---| +| users | 1019 | 42d7e548b2d4ee91736961faca386d0a | +| chats | 306 | d2541ecae4fa59a1f1192498d0f5b4e0 | +| chat_members | 3295 | 4f1cf6a7c65e7a56c072c20877d7d28f | +| messages | 239717 | 1c0251c775eecc3ffc43c28b81084eea | +| schema_migrations | 1 | 550e0a1f7ef8568bdbe21b29ffb5399b | diff --git a/experiments/track2/generate.sql b/experiments/track2/generate.sql new file mode 100644 index 00000000..bab83cba --- /dev/null +++ b/experiments/track2/generate.sql @@ -0,0 +1,37 @@ +-- Синтетические данные трека 2 (фиксированный seed): 1000 пользователей, 300 чатов с размерами по закону Ципфа +-- round(60000 / k^1.2) -> от 60000 до 64 сообщений, всего ~240k, случайный физический порядок за 90 дней. +-- У пользователей случайный корректный scrypt-хэш: войти под ними невозможно. +BEGIN; +SELECT setseed(0.2026); + +CREATE TEMP TABLE t_users AS SELECT i, gen_random_uuid() AS id FROM generate_series(0, 999) i; +INSERT INTO users (id, username, display_name, password_hash) +SELECT id, 'track2_u' || i, 'Track2 user ' || i, + 'scrypt$16384$8$1$' || md5(random()::text) || '$' || md5(random()::text) || md5(random()::text) +FROM t_users; + +CREATE TEMP TABLE t_chats AS +SELECT k, gen_random_uuid() AS id, greatest(1, round(60000 / power(k, 1.2)))::int AS size, 2 + k % 19 AS n_members +FROM generate_series(1, 300) k; +INSERT INTO chats (id, title, created_at) SELECT id, 'track2-' || k, now() - interval '91 days' FROM t_chats; +INSERT INTO chat_members (chat_id, user_id) +SELECT c.id, u.id FROM t_chats c JOIN t_users u ON u.i BETWEEN (c.k * 13) % 980 AND (c.k * 13) % 980 + c.n_members - 1; + +CREATE TEMP TABLE t_members AS +SELECT chat_id, array_agg(user_id ORDER BY user_id) AS ids FROM chat_members +WHERE chat_id IN (SELECT id FROM t_chats) GROUP BY chat_id; + +INSERT INTO messages (chat_id, sender_id, text, created_at) +SELECT c.id, + m.ids[1 + floor(random() * cardinality(m.ids))::int], + left(repeat(md5(random()::text), 13), 20 + floor(random() * 380)::int), + now() - random() * interval '90 days' +FROM t_chats c JOIN t_members m ON m.chat_id = c.id, generate_series(1, c.size) +ORDER BY random(); + +-- пары (чат, отправитель) для бенчмарка записи: поиск по PK, одинаковый для всех вариантов индекса +CREATE TABLE track2_pairs AS +SELECT c.k, c.id AS chat_id, m.ids[1] AS sender_id FROM t_chats c JOIN t_members m ON m.chat_id = c.id; +ALTER TABLE track2_pairs ADD PRIMARY KEY (k); +COMMIT; +VACUUM ANALYZE; diff --git a/experiments/track2/run.py b/experiments/track2/run.py new file mode 100644 index 00000000..f77f7f6c --- /dev/null +++ b/experiments/track2/run.py @@ -0,0 +1,293 @@ +#!/usr/bin/env python3 +"""Трек 2: планы запроса истории на >=100k сообщений, цена записи индексов, backup -> restore -> сверка. + +Работает со стендом compose (сервис postgres). Во время эксперимента меняет ТОЛЬКО вторичные индексы `messages` +и всегда заканчивает индексом из миграции. Синтетические данные track2_* добавляются один раз. + python3 experiments/track2/run.py # результаты -> evidence/track2/ + python3 experiments/track2/run.py --render # пересобрать results.md из results.json +""" +import json +import re +import secrets +import statistics +import subprocess +import sys +import threading +import time +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[2] +OUT = ROOT / 'evidence' / 'track2' +IMAGE = 'postgres:17.6-alpine3.22' +PSQL = ['psql', '-U', 'messenger', '-X', '-q', '-At', '-v', 'ON_ERROR_STOP=1'] +SRC = ['docker', 'compose', 'exec', '-T', 'postgres'] +RESTORE = 'messenger-track2-restore' +RUNS = 5 + +VARIANTS = { # вторичный индекс messages; PK(id) есть всегда + 'V0 PK only': None, + 'V1 (chat_id)': 'CREATE INDEX exp_idx ON messages (chat_id)', + 'V2 (chat_id, created_at)': 'CREATE INDEX exp_idx ON messages (chat_id, created_at)', + 'V3 (chat_id, created_at, id)': 'CREATE INDEX messages_chat_created_id_idx ON messages (chat_id, created_at, id)', +} +COLS = 'SELECT id, chat_id, sender_id, text, created_at FROM messages WHERE chat_id = {chat} ' +QUERIES = { + # запрос API (pg шлёт его безымянным prepared statement -> план строится под конкретные значения) + 'first page (API)': COLS + "AND (created_at, id) > ('-infinity'::timestamptz, '00000000-0000-0000-0000-000000000000'::uuid) " + 'ORDER BY created_at, id LIMIT 51', + 'middle page keyset (API)': COLS + 'AND (created_at, id) > ({ts}::timestamptz, {id}::uuid) ORDER BY created_at, id LIMIT 51', + 'middle page keyset + created_at >=': COLS + 'AND created_at >= {ts}::timestamptz ' + 'AND (created_at, id) > ({ts}::timestamptz, {id}::uuid) ORDER BY created_at, id LIMIT 51', + 'middle page OFFSET': COLS + 'ORDER BY created_at, id OFFSET {offset} LIMIT 51', +} +PGBENCH = ("\\set k random(1, 300)\n" + "INSERT INTO messages (chat_id, sender_id, text) SELECT chat_id, sender_id, 'bench' FROM track2_pairs WHERE k = :k;\n") +BULK = ("INSERT INTO messages (chat_id, sender_id, text) SELECT p.chat_id, p.sender_id, 'bench' " + 'FROM generate_series(1, 50000) g JOIN track2_pairs p ON p.k = 1 + g % 300;') +FINGERPRINT = """SET TimeZone = 'UTC'; +SELECT 'users', count(*), md5(string_agg(id::text || username || display_name || password_hash || created_at::text, ',' ORDER BY id)) FROM users +UNION ALL SELECT 'chats', count(*), md5(string_agg(id::text || title || created_at::text, ',' ORDER BY id)) FROM chats +UNION ALL SELECT 'chat_members', count(*), md5(string_agg(chat_id::text || user_id::text, ',' ORDER BY chat_id, user_id)) FROM chat_members +UNION ALL SELECT 'messages', count(*), md5(string_agg(id::text || chat_id::text || sender_id::text || md5(text) || created_at::text, ',' ORDER BY id)) + FROM messages WHERE text <> 'during-dump' +UNION ALL SELECT 'schema_migrations', count(*), md5(string_agg(version, ',' ORDER BY version)) FROM schema_migrations; +SELECT 'sample', id, chat_id, sender_id, md5(text), created_at FROM messages WHERE text <> 'during-dump' ORDER BY md5(id::text) LIMIT 20; +""" + + +def run(cmd, stdin=None): + return subprocess.run(cmd, cwd=ROOT, input=stdin, capture_output=True, text=True, check=True).stdout + + +def sql(query, prefix=SRC, db='messenger'): + return run(prefix + PSQL + ['-d', db], stdin=query).strip() + + +def lit(value): + return "'" + str(value).replace("'", "''") + "'" + + +def shape(node): + name = node['Node Type'] + (' ' + node['Index Name'] if 'Index Name' in node else '') + kids = node.get('Plans', []) + return name + (' > ' + ' + '.join(shape(k) for k in kids) if kids else '') + + +def rows_touched(node): + """Строки, прочитанные узлами сканирования (возвращённые + отфильтрованные), с учётом числа циклов.""" + own = 0 + if 'Scan' in node['Node Type'] and node['Node Type'] != 'Bitmap Index Scan': + own = (node['Actual Rows'] + node.get('Rows Removed by Filter', 0) + + node.get('Rows Removed by Index Recheck', 0)) * node['Actual Loops'] + return round(own + sum(rows_touched(k) for k in node.get('Plans', []))) + + +def explain(query, prefix=SRC): + times = [] + for _ in range(RUNS): + plan = json.loads(sql('EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) ' + query, prefix))[0] + times.append(plan['Execution Time']) + top = plan['Plan'] + return {'median_ms': round(statistics.median(times), 3), 'min_ms': round(min(times), 3), + 'buffers': top['Shared Hit Blocks'] + top['Shared Read Blocks'], 'rows_touched': rows_touched(top), + 'plan': shape(top)} + + +def set_variant(ddl): + sql('DROP INDEX IF EXISTS exp_idx, messages_chat_created_id_idx;') + if ddl is None: + return 0.0, 0 + started = time.monotonic() + sql(ddl + ';') + build = time.monotonic() - started + sql('ANALYZE messages;') + name = 'messages_chat_created_id_idx' if 'messages_chat_created_id_idx' in ddl else 'exp_idx' + return round(build, 3), int(sql("SELECT pg_relation_size('%s')" % name)) + + +def cleanup_bench(): + sql("DELETE FROM messages WHERE text = 'bench'; VACUUM ANALYZE messages;") + + +def write_cost(): + bulk = [] + for _ in range(3): + out = sql('\\timing on\n' + BULK) + bulk.append(float(re.search(r'Time: ([0-9.]+) ms', out).group(1))) + cleanup_bench() + tps, latency = [], [] + run(SRC + ['sh', '-c', 'cat > /tmp/track2_insert.sql'], stdin=PGBENCH) + for _ in range(3): + out = run(SRC + ['pgbench', '-n', '-U', 'messenger', '-d', 'messenger', '-f', '/tmp/track2_insert.sql', + '-T', '10', '-c', '8', '-j', '4']) + tps.append(float(re.search(r'tps = ([0-9.]+)', out).group(1))) + latency.append(float(re.search(r'latency average = ([0-9.]+) ms', out).group(1))) + cleanup_bench() + return {'bulk_50k_ms_median': round(statistics.median(bulk), 1), 'bulk_50k_ms': bulk, + 'pgbench_tps_median': round(statistics.median(tps), 1), 'pgbench_tps': tps, + 'pgbench_latency_ms_median': round(statistics.median(latency), 3)} + + +def dataset(): + if sql("SELECT count(*) FROM chats WHERE title = 'track2-1'") == '0': + started = time.monotonic() + sql((Path(__file__).parent / 'generate.sql').read_text()) + print('generated dataset in %.1fs' % (time.monotonic() - started), flush=True) + sizes = [int(x) for x in sql("SELECT count(*) FROM messages m JOIN chats c ON c.id = m.chat_id " + "WHERE c.title LIKE 'track2-%' GROUP BY c.id ORDER BY 1 DESC").split()] + return {'messages_total': int(sql('SELECT count(*) FROM messages')), 'track2_chats': len(sizes), + 'chat_size_max': sizes[0], 'chat_size_p50': sizes[len(sizes) // 2], 'chat_size_min': sizes[-1], + 'top10_share': round(sum(sizes[:10]) / sum(sizes), 3), + 'messages_table_bytes': int(sql("SELECT pg_table_size('messages')")), + 'pk_index_bytes': int(sql("SELECT pg_relation_size('messages_pkey')"))} + + +def targets(): + out = {} + for label, k in (('large', 1), ('medium', 30), ('small', 300)): + chat, size = sql("SELECT c.id, count(*) FROM chats c JOIN messages m ON m.chat_id = c.id " + "WHERE c.title = 'track2-%d' GROUP BY c.id" % k).split('|') + ts, mid = sql("SELECT created_at, id FROM messages WHERE chat_id = '%s' ORDER BY created_at, id " + "OFFSET %d LIMIT 1" % (chat, int(size) // 2)).split('|') + out[label] = {'chat': lit(chat), 'ts': lit(ts), 'id': lit(mid), 'offset': int(size) // 2, 'size': int(size)} + return out + + +def plans_and_writes(chats): + results = {} + for variant, ddl in VARIANTS.items(): # V3 последним: БД остаётся в состоянии миграции + build_s, index_bytes = set_variant(ddl) + row = {'index_build_s': build_s, 'index_bytes': index_bytes, 'queries': {}} + for qname, template in QUERIES.items(): + for label, t in chats.items(): + row['queries'][qname + ' / ' + label] = explain(template.format(**t)) + row['write'] = write_cost() + results[variant] = row + print('done', variant, flush=True) + # текстовый план запроса API на самом большом чате для каждого варианта + text = sql('EXPLAIN (ANALYZE, BUFFERS) ' + QUERIES['middle page keyset (API)'].format(**chats['large'])) + (OUT / ('explain_api_middle_page_%s.txt' % variant.split()[0])).write_text(text + '\n') + return results + + +def wait_restore_ready(): + deadline = time.monotonic() + 120 + while True: + logs = subprocess.run(['docker', 'logs', RESTORE], capture_output=True, text=True) + ready = subprocess.run(['docker', 'exec', RESTORE, 'pg_isready', '-U', 'messenger', '-d', 'messenger'], + capture_output=True).returncode == 0 + if ready and 'PostgreSQL init process complete' in logs.stdout + logs.stderr: + return + if time.monotonic() > deadline: + raise SystemExit('restore container did not initialise') + time.sleep(0.5) + + +def backup_restore(chats): + dump = ROOT / 'backups' / 'track2.dump' + dump.parent.mkdir(exist_ok=True) + before = int(sql('SELECT count(*) FROM messages')) + stop, written = threading.Event(), [0] + + def writer(): # коммиты параллельно с pg_dump: показывают границу потери данных логического dump + while not stop.is_set(): + sql("INSERT INTO messages (chat_id, sender_id, text) SELECT chat_id, sender_id, 'during-dump' FROM track2_pairs WHERE k = 1;") + written[0] += 1 + + started = time.monotonic() + with dump.open('wb') as f: + proc = subprocess.Popen(SRC + ['pg_dump', '-U', 'messenger', '-d', 'messenger', '-Fc'], cwd=ROOT, stdout=f) + thread = threading.Thread(target=writer) + thread.start() + code = proc.wait() + dump_s = time.monotonic() - started + stop.set() + thread.join() + assert code == 0, 'pg_dump failed' + + subprocess.run(['docker', 'rm', '-f', RESTORE], capture_output=True) + subprocess.run(['docker', 'volume', 'rm', RESTORE + '-data'], capture_output=True) + # новое хранилище: новый контейнер + новый именованный volume, без сети + run(['docker', 'run', '-d', '--name', RESTORE, '--network', 'none', '-v', RESTORE + '-data:/var/lib/postgresql/data', + '-e', 'POSTGRES_USER=messenger', '-e', 'POSTGRES_DB=messenger', '-e', 'POSTGRES_PASSWORD=' + secrets.token_urlsafe(18), + IMAGE]) + wait_restore_ready() + run(['docker', 'cp', str(dump), RESTORE + ':/tmp/track2.dump']) + target = ['docker', 'exec', '-i', RESTORE] + restore_s = {} + for jobs, db in ((1, 'restore_j1'), (4, 'messenger')): + if db != 'messenger': + run(target + ['createdb', '-U', 'messenger', db]) + t0 = time.monotonic() + run(target + ['pg_restore', '-U', 'messenger', '-d', db, '--no-owner', '-j', str(jobs), '/tmp/track2.dump']) + restore_s['jobs_%d' % jobs] = round(time.monotonic() - t0, 2) + + src_fp, dst_fp = sql(FINGERPRINT), sql(FINGERPRINT, target) + t = chats['large'] + page = QUERIES['middle page keyset (API)'].format(**t) + src_page, dst_page = sql(page), sql(page, target) + return { + 'dump_bytes': dump.stat().st_size, 'dump_s': round(dump_s, 2), 'restore_s': restore_s, + 'messages_before_dump': before, 'during_dump_committed_in_source': written[0], + 'during_dump_in_restore': int(sql("SELECT count(*) FROM messages WHERE text = 'during-dump'", target)), + 'fingerprint_equal': src_fp == dst_fp, 'api_page_equal': src_page == dst_page and src_page.count('\n') == 50, + 'fingerprint': [line.split('|') for line in dst_fp.splitlines() if not line.startswith('sample')], + 'restored_plan_middle_page_large': explain(page, target)['plan'], + } + + +def render(r): + names = list(r['variants']) + lines = ['# Track 2 results', '', 'Generated by experiments/track2/run.py from results.json. Environment: %s; PostgreSQL %s, ' + 'shared_buffers %s, synchronous_commit %s.' % (r['env']['docker'], r['env']['postgres'], r['env']['shared_buffers'], + r['env']['synchronous_commit']), + '', 'Dataset: %(messages_total)d messages, %(track2_chats)d synthetic chats, sizes max %(chat_size_max)d / ' + 'median %(chat_size_p50)d / min %(chat_size_min)d, top-10 chats hold %(top10_share)s of track2 messages, ' + 'table %(messages_table_bytes)d B.' % r['dataset'], '', + '## Read: median ms of %d EXPLAIN ANALYZE runs / shared buffers / rows read by scans' % RUNS, '', + '| query / chat | ' + ' | '.join(names) + ' |', '|---' * (len(names) + 1) + '|'] + for q in r['variants'][names[0]]['queries']: + cells = ['%.2f / %d / %d' % (v['queries'][q]['median_ms'], v['queries'][q]['buffers'], v['queries'][q]['rows_touched']) + for v in r['variants'].values()] + lines.append('| ' + q + ' | ' + ' | '.join(cells) + ' |') + lines += ['', 'Plans of the API query (middle page, large chat):', ''] + lines += ['- %s: `%s`' % (n, v['queries']['middle page keyset (API) / large']['plan']) for n, v in r['variants'].items()] + lines += ['', '## Write cost', '', '| variant | index size, MiB | build, s | bulk 50k INSERT, ms (median of 3) | ' + 'pgbench 1-row INSERT, TPS (median of 3x10 s, 8 clients) | avg latency, ms |', '|---|---|---|---|---|---|'] + for n, v in r['variants'].items(): + w = v['write'] + lines.append('| %s | %.1f | %.2f | %.0f | %.0f | %.3f |' % (n, v['index_bytes'] / 2 ** 20, v['index_build_s'], + w['bulk_50k_ms_median'], w['pgbench_tps_median'], w['pgbench_latency_ms_median'])) + b = r['backup_restore'] + lines += ['', '## Backup -> restore into new storage -> reconcile', '', + '- pg_dump -Fc: %.2f s, %d B; pg_restore into a new container + new volume: %s' % (b['dump_s'], b['dump_bytes'], b['restore_s']), + '- fingerprints (count + md5 of every table, 20 sampled messages) equal: %s; API page of the large chat equal: %s' + % (b['fingerprint_equal'], b['api_page_equal']), + '- writes committed during pg_dump: %d in source, %d in restore' % (b['during_dump_committed_in_source'], b['during_dump_in_restore']), + '- restored plan of the API query: `%s`' % b['restored_plan_middle_page_large'], '', + '| table | rows | md5 |', '|---|---|---|'] + lines += ['| %s | %s | %s |' % tuple(f) for f in b['fingerprint']] + (OUT / 'results.md').write_text('\n'.join(lines) + '\n') + + +def main(): + OUT.mkdir(parents=True, exist_ok=True) + if sys.argv[1:] == ['--render']: + return render(json.loads((OUT / 'results.json').read_text())) + env = {'postgres': sql('SHOW server_version'), 'shared_buffers': sql('SHOW shared_buffers'), + 'synchronous_commit': sql('SHOW synchronous_commit'), + 'docker': run(['docker', 'info', '--format', '{{.OperatingSystem}}, {{.NCPU}} CPU, {{.MemTotal}} B RAM']).strip()} + data = dataset() + print(json.dumps(data), flush=True) + chats = targets() + results = {'env': env, 'dataset': data, 'chats': {k: {'size': v['size'], 'offset': v['offset']} for k, v in chats.items()}, + 'variants': plans_and_writes(chats)} + results['backup_restore'] = backup_restore(chats) + (OUT / 'results.json').write_text(json.dumps(results, ensure_ascii=False, indent=2) + '\n') + render(results) + print(json.dumps(results['backup_restore'], ensure_ascii=False, indent=2)) + run(['docker', 'rm', '-f', RESTORE]) # временный контейнер восстановления; volume остаётся для проверки + + +if __name__ == '__main__': + main() diff --git a/infra/valkey.conf b/infra/valkey.conf new file mode 100644 index 00000000..40c6df0e --- /dev/null +++ b/infra/valkey.conf @@ -0,0 +1,8 @@ +# Valkey — единственное хранилище сессий, поэтому оно обязано переживать рестарт. +# AOF с fsync на каждую запись: ответ 201 на POST /auth/sessions значит, что сессия уже на диске. +appendonly yes +appendfsync always +save "" +dir /data +# requirepass лежит в локальном секрете, его создаёт scripts/init-secrets.sh +include /run/secrets/valkey_auth.conf diff --git a/migrations/001_init.sql b/migrations/001_init.sql new file mode 100644 index 00000000..4e0ef3ae --- /dev/null +++ b/migrations/001_init.sql @@ -0,0 +1,36 @@ +-- Пользователи, чаты, участники и сообщения. PostgreSQL — источник истины. +-- timestamptz(3): миллисекунды без потерь проходят через JS Date и keyset-курсоры. +CREATE TABLE users ( + id uuid PRIMARY KEY DEFAULT gen_random_uuid(), + username text NOT NULL UNIQUE CHECK (username ~ '^[a-z0-9_]{3,32}$'), + display_name text NOT NULL CHECK (char_length(display_name) BETWEEN 1 AND 100), + password_hash text NOT NULL, + created_at timestamptz(3) NOT NULL DEFAULT now() +); + +CREATE TABLE chats ( + id uuid PRIMARY KEY DEFAULT gen_random_uuid(), + title text NOT NULL CHECK (char_length(title) BETWEEN 1 AND 100), + created_at timestamptz(3) NOT NULL DEFAULT now() +); + +CREATE TABLE chat_members ( + chat_id uuid NOT NULL REFERENCES chats (id), + user_id uuid NOT NULL REFERENCES users (id), + PRIMARY KEY (chat_id, user_id) +); +-- GET /chats: чаты одного пользователя. +CREATE INDEX chat_members_user_idx ON chat_members (user_id, chat_id); + +CREATE TABLE messages ( + id uuid PRIMARY KEY DEFAULT gen_random_uuid(), + chat_id uuid NOT NULL, + sender_id uuid NOT NULL, + text text NOT NULL CHECK (char_length(text) BETWEEN 1 AND 4000), + created_at timestamptz(3) NOT NULL DEFAULT now(), + -- отправитель обязан быть участником чата; заодно проверяется существование чата и пользователя + FOREIGN KEY (chat_id, sender_id) REFERENCES chat_members (chat_id, user_id) +); +-- История (keyset): WHERE chat_id = $1 AND (created_at, id) > ($2, $3) ORDER BY created_at, id LIMIT $4. +-- Выбор обоснован в evidence/track2 (EXPLAIN ANALYZE на 240k сообщений). +CREATE INDEX messages_chat_created_id_idx ON messages (chat_id, created_at, id); diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 00000000..d5a2f37d --- /dev/null +++ b/package-lock.json @@ -0,0 +1,307 @@ +{ + "name": "messenger-lab2", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "messenger-lab2", + "dependencies": { + "ioredis": "5.11.1", + "pg": "8.23.1" + }, + "devDependencies": { + "@types/node": "24.19.2", + "@types/pg": "8.23.1", + "typescript": "5.9.3" + }, + "engines": { + "node": ">=24" + } + }, + "node_modules/@ioredis/commands": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/@ioredis/commands/-/commands-1.10.0.tgz", + "integrity": "sha512-UmeW7z4LfctwoQ5wkhVzgq8tXkreED2xZGpX+Bg+zA+WJFZCT6c062AfCK/Dfk81xZnnwdhJCUMkitihRaoC2Q==", + "license": "MIT" + }, + "node_modules/@types/node": { + "version": "24.19.2", + "resolved": "https://registry.npmjs.org/@types/node/-/node-24.19.2.tgz", + "integrity": "sha512-93d49wCWJkCyN87MxLpNN6KXPCwFw7bVUg79mGUV1OS40JGWwVCr8n61DXCSqz7CV6/VfPkb7xec7uP2M+QHWQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "undici-types": ">=7.24.0 <7.24.7" + } + }, + "node_modules/@types/pg": { + "version": "8.23.1", + "resolved": "https://registry.npmjs.org/@types/pg/-/pg-8.23.1.tgz", + "integrity": "sha512-fKVHpikPdg4GKks3JuLEhvwSyvwzF23hnabPy6DD8ljVbC7+6J5dQzdv4arV6jqq57djnMgs1HKBxX4P8aBI3A==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/node": "*", + "pg-protocol": "*", + "pg-types": "^2.2.0" + } + }, + "node_modules/cluster-key-slot": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/cluster-key-slot/-/cluster-key-slot-1.1.1.tgz", + "integrity": "sha512-rwHwUfXL40Chm1r08yrhU3qpUvdVlgkKNeyeGPOxnW8/SyVDvgRaed/Uz54AqWNaTCAThlj6QAs3TZcKI0xDEw==", + "license": "Apache-2.0", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/debug": { + "version": "4.4.3", + "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz", + "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==", + "license": "MIT", + "dependencies": { + "ms": "^2.1.3" + }, + "engines": { + "node": ">=6.0" + }, + "peerDependenciesMeta": { + "supports-color": { + "optional": true + } + } + }, + "node_modules/denque": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/denque/-/denque-2.1.0.tgz", + "integrity": "sha512-HVQE3AAb/pxF8fQAoiqpvg9i3evqug3hoiwakOyZAwJm+6vZehbkYXZ0l4JxS+I3QxM97v5aaRNhj8v5oBhekw==", + "license": "Apache-2.0", + "engines": { + "node": ">=0.10" + } + }, + "node_modules/ioredis": { + "version": "5.11.1", + "resolved": "https://registry.npmjs.org/ioredis/-/ioredis-5.11.1.tgz", + "integrity": "sha512-ehuGcf94bQXhfagULNXrJdfnWO38v070jxSx/qE87Kjzmu2fU7ro5EFAb+OPituLqgfyuQaym5DlrNydW2sJ9A==", + "license": "MIT", + "dependencies": { + "@ioredis/commands": "1.10.0", + "cluster-key-slot": "1.1.1", + "debug": "4.4.3", + "denque": "2.1.0", + "redis-errors": "1.2.0", + "redis-parser": "3.0.0", + "standard-as-callback": "2.1.0" + }, + "engines": { + "node": ">=12.22.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/ioredis" + } + }, + "node_modules/ms": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", + "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==", + "license": "MIT" + }, + "node_modules/pg": { + "version": "8.23.1", + "resolved": "https://registry.npmjs.org/pg/-/pg-8.23.1.tgz", + "integrity": "sha512-aL96AHANtWjPLDOLqnhx+ngp9+UK7ETEU8VJrDCGvsSSi/mGLcWYsS6Herg7lmaBJe4uwrfqsa7gTEFaSizDoQ==", + "license": "MIT", + "dependencies": { + "pg-connection-string": "^2.14.1", + "pg-pool": "^3.14.0", + "pg-protocol": "^1.16.1", + "pg-types": "2.2.0", + "pgpass": "1.0.5" + }, + "engines": { + "node": ">= 16.0.0" + }, + "optionalDependencies": { + "pg-cloudflare": "^1.4.1" + }, + "peerDependencies": { + "pg-native": ">=3.0.1" + }, + "peerDependenciesMeta": { + "pg-native": { + "optional": true + } + } + }, + "node_modules/pg-cloudflare": { + "version": "1.4.1", + "resolved": "https://registry.npmjs.org/pg-cloudflare/-/pg-cloudflare-1.4.1.tgz", + "integrity": "sha512-6PQbsFWZcp9EmJEwy5cGQ2La+AMWpP46lgbb8X+U/XsHIUweYDNCpeuKck5RxL2MdVFi7krbbEi5nX4Zh7JhrQ==", + "license": "MIT", + "optional": true + }, + "node_modules/pg-connection-string": { + "version": "2.14.1", + "resolved": "https://registry.npmjs.org/pg-connection-string/-/pg-connection-string-2.14.1.tgz", + "integrity": "sha512-qR3kGNPBLpCNtz0evbKA0Y/MRFXwSSdT+pTJvYp/bXTcReZbvX1kzF0IyTc1QnxqF7AZbOeBhNL8R5mYQZV/MA==", + "license": "MIT" + }, + "node_modules/pg-int8": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/pg-int8/-/pg-int8-1.0.1.tgz", + "integrity": "sha512-WCtabS6t3c8SkpDBUlb1kjOs7l66xsGdKpIPZsg4wR+B3+u9UAum2odSsF9tnvxg80h4ZxLWMy4pRjOsFIqQpw==", + "license": "ISC", + "engines": { + "node": ">=4.0.0" + } + }, + "node_modules/pg-pool": { + "version": "3.14.0", + "resolved": "https://registry.npmjs.org/pg-pool/-/pg-pool-3.14.0.tgz", + "integrity": "sha512-gKtPkFdQPU3DksooVLi9LsjZxrsBUZIpa+7aVx+LV5pNh0KzP4Zleud2po+ConrxbuXGBJ6Hfer6hdgpIBpBaw==", + "license": "MIT", + "peerDependencies": { + "pg": ">=8.0" + } + }, + "node_modules/pg-protocol": { + "version": "1.16.1", + "resolved": "https://registry.npmjs.org/pg-protocol/-/pg-protocol-1.16.1.tgz", + "integrity": "sha512-p9VOFMiHB/ZbJATetbg+99PxssTVSQRnyuPSQ67mN1+1KBOjZaZ83ZQzltnxPhJwSsC3nwVjJ10DVJlerbFzLg==", + "license": "MIT" + }, + "node_modules/pg-types": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/pg-types/-/pg-types-2.2.0.tgz", + "integrity": "sha512-qTAAlrEsl8s4OiEQY69wDvcMIdQN6wdz5ojQiOy6YRMuynxenON0O5oCpJI6lshc6scgAY8qvJ2On/p+CXY0GA==", + "license": "MIT", + "dependencies": { + "pg-int8": "1.0.1", + "postgres-array": "~2.0.0", + "postgres-bytea": "~1.0.0", + "postgres-date": "~1.0.4", + "postgres-interval": "^1.1.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/pgpass": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/pgpass/-/pgpass-1.0.5.tgz", + "integrity": "sha512-FdW9r/jQZhSeohs1Z3sI1yxFQNFvMcnmfuj4WBMUTxOrAyLMaTcE1aAMBiTlbMNaXvBCQuVi0R7hd8udDSP7ug==", + "license": "MIT", + "dependencies": { + "split2": "^4.1.0" + } + }, + "node_modules/postgres-array": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/postgres-array/-/postgres-array-2.0.0.tgz", + "integrity": "sha512-VpZrUqU5A69eQyW2c5CA1jtLecCsN2U/bD6VilrFDWq5+5UIEVO7nazS3TEcHf1zuPYO/sqGvUvW62g86RXZuA==", + "license": "MIT", + "engines": { + "node": ">=4" + } + }, + "node_modules/postgres-bytea": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/postgres-bytea/-/postgres-bytea-1.0.1.tgz", + "integrity": "sha512-5+5HqXnsZPE65IJZSMkZtURARZelel2oXUEO8rH83VS/hxH5vv1uHquPg5wZs8yMAfdv971IU+kcPUczi7NVBQ==", + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/postgres-date": { + "version": "1.0.7", + "resolved": "https://registry.npmjs.org/postgres-date/-/postgres-date-1.0.7.tgz", + "integrity": "sha512-suDmjLVQg78nMK2UZ454hAG+OAW+HQPZ6n++TNDUX+L0+uUlLywnoxJKDou51Zm+zTCjrCl0Nq6J9C5hP9vK/Q==", + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/postgres-interval": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/postgres-interval/-/postgres-interval-1.2.0.tgz", + "integrity": "sha512-9ZhXKM/rw350N1ovuWHbGxnGh/SNJ4cnxHiM0rxE4VN41wsg8P8zWn9hv/buK00RP4WvlOyr/RBDiptyxVbkZQ==", + "license": "MIT", + "dependencies": { + "xtend": "^4.0.0" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/redis-errors": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/redis-errors/-/redis-errors-1.2.0.tgz", + "integrity": "sha512-1qny3OExCf0UvUV/5wpYKf2YwPcOqXzkwKKSmKHiE6ZMQs5heeE/c8eXK+PNllPvmjgAbfnsbpkGZWy8cBpn9w==", + "license": "MIT", + "engines": { + "node": ">=4" + } + }, + "node_modules/redis-parser": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/redis-parser/-/redis-parser-3.0.0.tgz", + "integrity": "sha512-DJnGAeenTdpMEH6uAJRK/uiyEIH9WVsUmoLwzudwGJUwZPp80PDBWPHXSAGNPwNvIXAbe7MSUB1zQFugFml66A==", + "license": "MIT", + "dependencies": { + "redis-errors": "^1.0.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/split2": { + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/split2/-/split2-4.2.0.tgz", + "integrity": "sha512-UcjcJOWknrNkF6PLX83qcHM6KHgVKNkV62Y8a5uYDVv9ydGQVwAHMKqHdJje1VTWpljG0WYpCDhrCdAOYH4TWg==", + "license": "ISC", + "engines": { + "node": ">= 10.x" + } + }, + "node_modules/standard-as-callback": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/standard-as-callback/-/standard-as-callback-2.1.0.tgz", + "integrity": "sha512-qoRRSyROncaz1z0mvYqIE4lCd9p2R90i6GxW3uZv5ucSu8tU7B5HXUP1gG8pVZsYNVaXjk8ClXHPttLyxAL48A==", + "license": "MIT" + }, + "node_modules/typescript": { + "version": "5.9.3", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz", + "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==", + "dev": true, + "license": "Apache-2.0", + "bin": { + "tsc": "bin/tsc", + "tsserver": "bin/tsserver" + }, + "engines": { + "node": ">=14.17" + } + }, + "node_modules/undici-types": { + "version": "7.24.6", + "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.24.6.tgz", + "integrity": "sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg==", + "dev": true, + "license": "MIT" + }, + "node_modules/xtend": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/xtend/-/xtend-4.0.2.tgz", + "integrity": "sha512-LKYU1iAXJXUgAXn9URjiu+MWhyUXHsvfp7mcuYm9dSUKK0/CjtrUwFAxD82/mCWbtLsGjFIad0wIsod4zrTAEQ==", + "license": "MIT", + "engines": { + "node": ">=0.4" + } + } + } +} diff --git a/package.json b/package.json new file mode 100644 index 00000000..22f86c78 --- /dev/null +++ b/package.json @@ -0,0 +1,20 @@ +{ + "name": "messenger-lab2", + "private": true, + "type": "module", + "engines": { "node": ">=24" }, + "scripts": { + "build": "tsc", + "start": "node dist/main.js", + "migrate": "node dist/migrate.js" + }, + "dependencies": { + "ioredis": "5.11.1", + "pg": "8.23.1" + }, + "devDependencies": { + "@types/node": "24.19.2", + "@types/pg": "8.23.1", + "typescript": "5.9.3" + } +} diff --git a/scripts/init-secrets.sh b/scripts/init-secrets.sh new file mode 100755 index 00000000..006b248e --- /dev/null +++ b/scripts/init-secrets.sh @@ -0,0 +1,20 @@ +#!/bin/sh +# Создаёт локальные синтетические пароли в ./secrets (в .gitignore). Повторный запуск безопасен: существующие файлы не трогает. +set -eu +cd "$(dirname "$0")/.." +mkdir -p secrets +umask 077 +rand() { python3 -c 'import secrets; print(secrets.token_urlsafe(24))'; } +if [ ! -f secrets/postgres_password ]; then + pg=$(rand) + printf '%s' "$pg" > secrets/postgres_password + printf 'postgresql://messenger:%s@postgres:5432/messenger' "$pg" > secrets/database_url +fi +if [ ! -f secrets/valkey_auth.conf ]; then + vk=$(rand) + printf 'requirepass %s\n' "$vk" > secrets/valkey_auth.conf + printf 'redis://:%s@valkey:6379/0' "$vk" > secrets/cache_url +fi +# контейнеры работают не от root и читают секреты через bind-mount +chmod 644 secrets/* +echo "секреты готовы в ./secrets (значения не печатаются)" diff --git a/scripts/restart.sh b/scripts/restart.sh new file mode 100755 index 00000000..6b2e0dd3 --- /dev/null +++ b/scripts/restart.sh @@ -0,0 +1,7 @@ +#!/bin/sh +# Полный рестарт API и всех хранилищ (PostgreSQL, Valkey) с сохранением именованных volumes. +# Никаких down -v, flush и повторного seed. +set -eu +cd "$(dirname "$0")/.." +docker compose stop api valkey postgres +docker compose start postgres valkey api diff --git a/src/auth/passwords.ts b/src/auth/passwords.ts new file mode 100644 index 00000000..915a91e2 --- /dev/null +++ b/src/auth/passwords.ts @@ -0,0 +1,25 @@ +// Хэширование паролей. scrypt — медленный KDF с солью: перебор пароля дорог, в отличие от быстрого SHA-256. +import { randomBytes, scrypt, timingSafeEqual } from 'node:crypto'; + +// N=2^14, r=8, p=1: ~16 MiB памяти и десятки мс на хэш; считается в пуле потоков libuv, event loop не блокируется. +const PARAMS = { N: 16384, r: 8, p: 1 }; + +const kdf = (password: string, salt: Buffer, params: typeof PARAMS, length: number) => + new Promise((ok, fail) => scrypt(password, salt, length, params, (e, key) => (e ? fail(e) : ok(key)))); + +/** Формат: scrypt$N$r$p$соль$ключ (hex) — параметры хранятся рядом с хэшем, их можно менять со временем. */ +export async function hashPassword(password: string): Promise { + const salt = randomBytes(16); + const key = await kdf(password, salt, PARAMS, 32); + return ['scrypt', PARAMS.N, PARAMS.r, PARAMS.p, salt.toString('hex'), key.toString('hex')].join('$'); +} + +export async function verifyPassword(password: string, stored: string): Promise { + const [, N, r, p, salt, key] = stored.split('$'); + const expected = Buffer.from(key, 'hex'); + const actual = await kdf(password, Buffer.from(salt, 'hex'), { N: +N, r: +r, p: +p }, expected.length); + return timingSafeEqual(actual, expected); // сравнение за постоянное время +} + +/** Хэш-заглушка: для несуществующего пользователя считаем тот же KDF, чтобы время ответа его не выдавало. */ +export const DUMMY_HASH = await hashPassword('timing-equaliser-for-unknown-users'); diff --git a/src/auth/sessions.ts b/src/auth/sessions.ts new file mode 100644 index 00000000..348b0706 --- /dev/null +++ b/src/auth/sessions.ts @@ -0,0 +1,43 @@ +// Bearer-сессии в Valkey. Valkey — единственное хранилище сессий, persistence через AOF (infra/valkey.conf). +import { createHash, randomBytes } from 'node:crypto'; +import { setting } from '../config.js'; +import { unauthorized } from '../http/errors.js'; +import type { Ctx } from '../http/router.js'; +import { guard, valkey } from '../infra/valkey.js'; + +const TTL_MS = Number(setting('SESSION_TTL_SECONDS', '3600')) * 1000; +const BEARER = /^[A-Za-z0-9_-]{32,128}$/; + +// В Valkey лежит только SHA-256 токена: утечка дампа не даёт рабочих токенов. +// У токена 256 бит случайности, поэтому быстрого хэша достаточно (в отличие от пароля). +const keyOf = (token: string) => 'session:' + createHash('sha256').update(token).digest('hex'); + +/** Создаёт сессию; срок абсолютный (PXAT), поэтому рестарт API или Valkey его не продлевает. */ +export async function createSession(userId: string): Promise<{ token: string; expiresAt: Date }> { + const token = randomBytes(32).toString('base64url'); // непрозрачный случайный токен, 256 бит + const exp = Date.now() + TTL_MS; + await guard(valkey.set(keyOf(token), JSON.stringify({ uid: userId, exp }), 'PXAT', exp)); + return { token, expiresAt: new Date(exp) }; +} + +/** Проверяет Authorization: Bearer и возвращает ключ сессии и id пользователя, иначе 401. + * Если Valkey недоступен — 503: запрос никогда не считается анонимным или доверенным. */ +async function bearerSession(ctx: Ctx): Promise<{ key: string; userId: string }> { + const [scheme, token = ''] = (ctx.req.headers.authorization ?? '').split(' ', 2); + if (scheme.toLowerCase() !== 'bearer' || !BEARER.test(token)) throw unauthorized(); + const key = keyOf(token); + const raw = await guard(valkey.get(key)); + if (raw === null) throw unauthorized(); // неизвестный, отозванный или истёкший по TTL + const session = JSON.parse(raw); + if (session.exp <= Date.now()) throw unauthorized(); // страховка, если ключ ещё не удалён + return { key, userId: session.uid }; +} + +/** id текущего пользователя для защищённых маршрутов. X-User-Id не читается вообще. */ +export const requireUser = async (ctx: Ctx) => (await bearerSession(ctx)).userId; + +/** Отзывает текущую сессию. DEL атомарен: из двух одновременных logout успешен только один. */ +export async function revokeCurrentSession(ctx: Ctx): Promise { + const { key } = await bearerSession(ctx); + if (!(await guard(valkey.del(key)))) throw unauthorized(); +} diff --git a/src/config.ts b/src/config.ts new file mode 100644 index 00000000..01d12160 --- /dev/null +++ b/src/config.ts @@ -0,0 +1,17 @@ +// Настройки приложения из переменных окружения и Docker secrets. +import { readFileSync } from 'node:fs'; + +/** Читает настройку: сначала файл из NAME_FILE (Docker secret), затем NAME, затем значение по умолчанию. + * Значения секретов никогда не пишутся в лог. */ +export function setting(name: string, fallback?: string): string { + const file = process.env[name + '_FILE']; + if (file) return readFileSync(file, 'utf8').trim(); + const value = process.env[name] ?? fallback; + if (value === undefined) throw new Error('не задана настройка ' + name); + return value; +} + +/** Одна строка JSON на событие: удобно читать в docker compose logs и разбирать машинно. */ +export function log(entry: object) { + console.log(JSON.stringify({ ts: new Date().toISOString(), ...entry })); +} diff --git a/src/http/errors.ts b/src/http/errors.ts new file mode 100644 index 00000000..440720ee --- /dev/null +++ b/src/http/errors.ts @@ -0,0 +1,21 @@ +// Ошибки API. Любая из них превращается в тело {"error":{code,message,request_id}} в router.ts. + +/** Ожидаемая ошибка с HTTP-статусом и машинным кодом из контракта. */ +export class ApiError extends Error { + constructor(readonly status: number, readonly code: string, message: string, readonly challenge?: string) { + super(message); + } +} + +/** Зависимость (PostgreSQL или Valkey) недоступна или не ответила вовремя -> 503. */ +export class Unavailable extends Error {} + +export const badRequest = (message: string) => new ApiError(400, 'invalid_request', message); + +// 404 и для несуществующего, и для чужого объекта: не раскрываем, что чужой чат существует. +export const notFound = () => new ApiError(404, 'not_found', 'Объект не найден'); + +/** 401 с вызовом нужной схемы: Basic только для входа, Bearer для всего остального. */ +export const unauthorized = (scheme: 'Basic' | 'Bearer' = 'Bearer') => + new ApiError(401, 'unauthorized', 'Требуется действительная аутентификация', + scheme === 'Basic' ? 'Basic realm="messenger", charset="UTF-8"' : 'Bearer realm="messenger"'); diff --git a/src/http/router.ts b/src/http/router.ts new file mode 100644 index 00000000..a45e4c04 --- /dev/null +++ b/src/http/router.ts @@ -0,0 +1,61 @@ +// Маршрутизация и общий конвейер запроса: X-Request-Id, чтение тела, ошибки в формате контракта, access-лог. +import { randomUUID } from 'node:crypto'; +import type { IncomingMessage, ServerResponse } from 'node:http'; +import { log } from '../config.js'; +import { ApiError, notFound, Unavailable } from './errors.js'; + +const MAX_BODY = 1024 * 1024; + +/** Всё, что нужно обработчику: исходный запрос, разобранный URL, тело и параметры пути. */ +export type Ctx = { req: IncomingMessage; url: URL; body: Buffer; params: string[] }; +/** Обработчик возвращает [HTTP-статус, тело]; undefined — ответ без тела (204). */ +export type Handler = (ctx: Ctx) => Promise<[number, unknown]>; +export type Route = [method: string, path: RegExp, handler: Handler]; + +async function readBody(req: IncomingMessage): Promise { + const chunks: Buffer[] = []; + let size = 0; + for await (const chunk of req) { + size += chunk.length; + if (size > MAX_BODY) throw new ApiError(413, 'payload_too_large', 'Тело запроса слишком большое'); + chunks.push(chunk); + } + return Buffer.concat(chunks); +} + +/** Превращает исключение в статус и тело ошибки. Внутренние детали клиенту не отдаются, только в лог. */ +function toError(e: unknown, rid: string): [number, unknown, string | undefined] { + const body = (code: string, message: string) => ({ error: { code, message, request_id: rid } }); + if (e instanceof ApiError) return [e.status, body(e.code, e.message), e.challenge]; + if (e instanceof Unavailable) { + log({ event: 'dependency_unavailable', rid, error: e.message }); + return [503, body('unavailable', 'Сервис временно недоступен'), undefined]; + } + log({ event: 'unexpected_error', rid, error: e instanceof Error ? e.stack : String(e) }); + return [500, body('internal_error', 'Внутренняя ошибка'), undefined]; +} + +export function createRouter(routes: Route[]) { + return async (req: IncomingMessage, res: ServerResponse) => { + const rid = randomUUID(); + const started = performance.now(); + let status: number; + let payload: unknown; + let challenge: string | undefined; + try { + const url = new URL(req.url ?? '/', 'http://localhost'); + let match: RegExpExecArray | null = null; + const route = routes.find(([method, path]) => method === req.method && (match = path.exec(url.pathname))); + if (!route || !match) throw notFound(); + [status, payload] = await route[2]({ req, url, body: await readBody(req), params: (match as RegExpExecArray).slice(1) }); + } catch (e) { + [status, payload, challenge] = toError(e, rid); + } + const headers: Record = { 'X-Request-Id': rid }; + if (challenge) headers['WWW-Authenticate'] = challenge; + if (payload !== undefined) headers['Content-Type'] = 'application/json; charset=utf-8'; + res.writeHead(status, headers).end(payload === undefined ? undefined : JSON.stringify(payload)); + // в лог не попадают заголовки, тело и query-строка: там могут быть credentials и курсоры + log({ rid, method: req.method, path: req.url?.split('?')[0], status, ms: +(performance.now() - started).toFixed(1) }); + }; +} diff --git a/src/http/validation.ts b/src/http/validation.ts new file mode 100644 index 00000000..52aecbe9 --- /dev/null +++ b/src/http/validation.ts @@ -0,0 +1,69 @@ +// Проверка входных данных: строгий JSON, строки, UUID, limit и курсоры пагинации. +import type { Position } from '../models.js'; +import { badRequest } from './errors.js'; +import type { Ctx } from './router.js'; + +export const USERNAME = /^[a-z0-9_]{3,32}$/; +const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i; +const START: Position = { created_at: '-infinity', id: '00000000-0000-0000-0000-000000000000' }; + +/** JSON-объект в UTF-8 ровно с перечисленными полями: лишнее или отсутствующее поле — 400. */ +export function jsonBody(ctx: Ctx, fields: string[]): Record { + let data: unknown; + try { + data = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(ctx.body)); + } catch { + throw badRequest('Тело должно быть JSON-объектом в UTF-8'); + } + if (typeof data !== 'object' || data === null || Array.isArray(data)) throw badRequest('Тело должно быть JSON-объектом'); + const keys = Object.keys(data); + if (keys.length !== fields.length || !fields.every((k) => keys.includes(k))) throw badRequest('Неверный набор полей'); + return data as Record; +} + +/** Непустая (не только пробелы) строка длиной min..max символов Unicode. + * NUL и одиночные суррогаты отклоняются: PostgreSQL не может сохранить их в text. */ +export function textField(value: unknown, name: string, min: number, max: number): string { + const length = typeof value === 'string' ? [...value].length : -1; // кодовые точки, а не UTF-16 + if (typeof value !== 'string' || !value.isWellFormed() || value.includes('\0') || !value.trim() + || length < min || length > max) throw badRequest('Неверное поле ' + name); + return value; +} + +export function usernameField(value: unknown): string { + if (typeof value !== 'string' || !USERNAME.test(value)) throw badRequest('Неверное поле username'); + return value; +} + +/** UUID в каноническом виде, приводится к нижнему регистру для сравнения. */ +export function parseUuid(value: unknown): string { + if (typeof value !== 'string' || !UUID.test(value)) throw badRequest('Неверный UUID'); + return value.toLowerCase(); +} + +/** limit — целое 1..100, по умолчанию 50. */ +export function pageLimit(ctx: Ctx): number { + const raw = ctx.url.searchParams.get('limit') ?? '50'; + if (!/^[0-9]{1,3}$/.test(raw) || +raw < 1 || +raw > 100) throw badRequest('limit должен быть целым 1..100'); + return +raw; +} + +// Курсор — base64url от "scope|created_at|id". Scope привязывает курсор к своему списку: +// курсор от другого чата или другого пользователя — 400. +export function afterCursor(ctx: Ctx, scope: string): Position { + const raw = ctx.url.searchParams.get('cursor'); + if (raw === null) return START; + const [got, createdAt, id, extra] = Buffer.from(raw, 'base64url').toString().split('|'); + if (got !== scope || extra !== undefined || Number.isNaN(Date.parse(createdAt)) || !UUID.test(id ?? '')) { + throw badRequest('Неверный cursor'); + } + return { created_at: createdAt, id }; +} + +/** Из limit+1 прочитанных строк делает страницу: лишняя строка значит, что дальше есть данные. */ +export function page(rows: T[], limit: number, scope: string) { + const items = rows.slice(0, limit); + const last = items[items.length - 1]; + const next = rows.length > limit ? Buffer.from([scope, last.created_at, last.id].join('|')).toString('base64url') : null; + return { items, next_cursor: next }; +} diff --git a/src/infra/db.ts b/src/infra/db.ts new file mode 100644 index 00000000..98976aec --- /dev/null +++ b/src/infra/db.ts @@ -0,0 +1,55 @@ +// Пул соединений PostgreSQL и обёртки для запросов и транзакций. +import pg from 'pg'; +import { log, setting } from '../config.js'; +import { Unavailable } from '../http/errors.js'; + +// Ограниченный пул и таймауты: упавшая БД превращается в 503 примерно за 2 с, а не в зависший запрос. +const pool = new pg.Pool({ + connectionString: setting('DATABASE_URL'), + max: Number(setting('DB_POOL_MAX', '8')), + connectionTimeoutMillis: Number(setting('DB_POOL_TIMEOUT_MS', '2000')), // ожидание свободного/нового соединения + idleTimeoutMillis: 30_000, + statement_timeout: 3000, // таймаут на стороне сервера + query_timeout: 4000, // таймаут на стороне клиента +}); +// При рестарте БД простаивающие соединения обрываются: пул их выбрасывает, процесс не должен падать. +pool.on('error', (e) => log({ event: 'db_idle_client_error', error: e.message })); + +export type Row = Record; +export type Query = (text: string, values?: unknown[]) => Promise; + +/** Ошибки ограничений и SQL пробрасываются вызывающему; обрыв связи и таймауты (классы 08, 53, 57, 58) -> Unavailable. */ +async function guard(promise: Promise): Promise { + try { + return await promise; + } catch (e) { + if (e instanceof pg.DatabaseError && !/^(08|53|57|58)/.test(e.code ?? '')) throw e; + throw new Unavailable(e instanceof Error ? e.message : String(e)); + } +} + +/** Один запрос вне явной транзакции. Только параметры $1..$n, никакой склейки значений в SQL. */ +export const sql: Query = async (text, values = []) => (await guard(pool.query(text, values))).rows; + +/** Выполняет fn в транзакции: COMMIT при успехе, ROLLBACK при любой ошибке. */ +export async function transaction(fn: (q: Query) => Promise): Promise { + const client = await guard(pool.connect()); + const q: Query = async (text, values = []) => (await guard(client.query(text, values))).rows; + try { + await q('BEGIN'); + const result = await fn(q); + await q('COMMIT'); + client.release(); + return result; + } catch (e) { + const broken = await client.query('ROLLBACK').then(() => undefined, (err: Error) => err); + client.release(broken); // соединение, которое не смогло откатиться, уничтожается, а не возвращается в пул + throw e; + } +} + +/** Нарушено ли ограничение с данным SQLSTATE: 23505 — уникальность, 23503 — внешний ключ. */ +export const violates = (e: unknown, sqlstate: '23505' | '23503') => e instanceof pg.DatabaseError && e.code === sqlstate; + +export const pingDb = () => sql('SELECT 1'); +export const closeDb = () => pool.end(); diff --git a/src/infra/valkey.ts b/src/infra/valkey.ts new file mode 100644 index 00000000..4f8cefed --- /dev/null +++ b/src/infra/valkey.ts @@ -0,0 +1,23 @@ +// Клиент Valkey (протокол Redis), где хранятся сессии. +import { Redis } from 'ioredis'; +import { log, setting } from '../config.js'; +import { Unavailable } from '../http/errors.js'; + +// Без offline-очереди: пока Valkey недоступен, команда сразу падает (-> 503), а не ждёт переподключения. +export const valkey = new Redis(setting('CACHE_URL'), { + connectTimeout: 1000, commandTimeout: 1000, enableOfflineQueue: false, maxRetriesPerRequest: 0, +}); +// Клиент сам переподключается; ошибки только логируем (URL с паролем не пишем). +valkey.on('error', (e) => log({ event: 'valkey_error', error: e.message })); + +/** Любая ошибка Valkey означает недоступность хранилища сессий -> 503. */ +export async function guard(promise: Promise): Promise { + try { + return await promise; + } catch (e) { + throw new Unavailable(e instanceof Error ? e.message : String(e)); + } +} + +export const pingValkey = () => guard(valkey.ping()); +export const closeValkey = () => valkey.quit(); diff --git a/src/main.ts b/src/main.ts new file mode 100644 index 00000000..09e2ceef --- /dev/null +++ b/src/main.ts @@ -0,0 +1,23 @@ +// Точка входа API мессенджера (lab2): HTTP-сервер и корректная остановка. +// PostgreSQL — источник истины для пользователей, чатов и сообщений; Valkey хранит Bearer-сессии. +import { createServer } from 'node:http'; +import { log, setting } from './config.js'; +import { createRouter } from './http/router.js'; +import { closeDb } from './infra/db.js'; +import { closeValkey } from './infra/valkey.js'; +import { routes } from './routes/index.js'; + +const port = Number(setting('APP_PORT', '8080')); +const handle = createRouter(routes); +const server = createServer((req, res) => void handle(req, res)); +server.requestTimeout = 10_000; // медленный клиент не держит соединение бесконечно +server.listen(port, setting('APP_HOST', '0.0.0.0'), () => log({ event: 'listening', port })); + +// SIGTERM от docker stop: дожидаемся текущих запросов, закрываем пул и Valkey; через 10 с выходим принудительно. +function shutdown() { + log({ event: 'shutdown' }); + setTimeout(() => process.exit(1), 10_000).unref(); + server.close(() => void Promise.allSettled([closeDb(), closeValkey()]).then(() => process.exit(0))); +} +process.on('SIGTERM', shutdown); +process.on('SIGINT', shutdown); diff --git a/src/migrate.ts b/src/migrate.ts new file mode 100644 index 00000000..7e851648 --- /dev/null +++ b/src/migrate.ts @@ -0,0 +1,38 @@ +// Применяет версионируемые SQL-миграции из migrations/ по одному разу: node dist/migrate.js +import { readdirSync, readFileSync } from 'node:fs'; +import { join } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import pg from 'pg'; +import { setting } from './config.js'; + +const dir = process.env.MIGRATIONS_DIR ?? fileURLToPath(new URL('../migrations', import.meta.url)); + +const client = new pg.Client({ connectionString: setting('DATABASE_URL'), connectionTimeoutMillis: 5000 }); +await client.connect(); +try { + // advisory lock: два одновременных запуска не применят миграцию дважды — второй подождёт и пропустит её + await client.query('SELECT pg_advisory_lock(20262)'); + await client.query('CREATE TABLE IF NOT EXISTS schema_migrations ' + + '(version text PRIMARY KEY, applied_at timestamptz NOT NULL DEFAULT now())'); + const done = new Set((await client.query('SELECT version FROM schema_migrations')).rows.map((r) => r.version)); + for (const file of readdirSync(dir).filter((f) => f.endsWith('.sql')).sort()) { + const version = file.slice(0, -4); + if (done.has(version)) { + console.log('skip', version); + continue; + } + // DDL в PostgreSQL транзакционен: миграция и запись о ней применяются целиком или никак + await client.query('BEGIN'); + try { + await client.query(readFileSync(join(dir, file), 'utf8')); + await client.query('INSERT INTO schema_migrations (version) VALUES ($1)', [version]); + await client.query('COMMIT'); + } catch (e) { + await client.query('ROLLBACK'); + throw e; + } + console.log('applied', version); + } +} finally { + await client.end(); +} diff --git a/src/models.ts b/src/models.ts new file mode 100644 index 00000000..f604fe99 --- /dev/null +++ b/src/models.ts @@ -0,0 +1,29 @@ +// Объекты в том виде, в каком их возвращает API (см. contracts/openapi.json). + +export interface User { + id: string; + username: string; + display_name: string; + created_at: string; // RFC 3339 UTC с Z +} + +export interface Chat { + id: string; + title: string; + member_ids: string[]; + created_at: string; +} + +export interface Message { + id: string; + chat_id: string; + sender_id: string; + text: string; + created_at: string; +} + +/** Позиция в списке для keyset-пагинации: порядок (created_at, id). */ +export interface Position { + created_at: string; + id: string; +} diff --git a/src/repositories/chats.ts b/src/repositories/chats.ts new file mode 100644 index 00000000..7e9c1147 --- /dev/null +++ b/src/repositories/chats.ts @@ -0,0 +1,45 @@ +// SQL для таблиц chats и chat_members. +import { sql, transaction, type Row, violates } from '../infra/db.js'; +import type { Chat, Position } from '../models.js'; + +// Участники собираются подзапросом, отсортированными по UUID: порядок стабилен между запросами. +const CHAT_COLUMNS = 'c.id, c.title, c.created_at, ' + + '(SELECT array_agg(user_id::text ORDER BY user_id) FROM chat_members WHERE chat_id = c.id) AS member_ids'; + +const toChat = (r: Row): Chat => ({ + id: r.id, title: r.title, member_ids: r.member_ids, created_at: r.created_at.toISOString(), +}); + +/** Создаёт чат со всеми участниками атомарно; null, если какого-то участника нет (транзакция уже откатана). */ +export async function createChat(title: string, memberIds: string[]): Promise { + try { + return await transaction(async (q) => { + const [chat] = await q('INSERT INTO chats (title) VALUES ($1) RETURNING id', [title]); + // неизвестный участник нарушит внешний ключ -> вся транзакция откатится, чат не останется + await q('INSERT INTO chat_members (chat_id, user_id) SELECT $1, unnest($2::uuid[])', [chat.id, memberIds]); + return toChat((await q('SELECT ' + CHAT_COLUMNS + ' FROM chats c WHERE c.id = $1', [chat.id]))[0]); + }); + } catch (e) { + if (violates(e, '23503')) return null; + throw e; + } +} + +/** Чат, если пользователь его участник; для постороннего — null, как для несуществующего. */ +export async function findChatForMember(chatId: string, userId: string): Promise { + const [row] = await sql('SELECT ' + CHAT_COLUMNS + ' FROM chats c JOIN chat_members m ON m.chat_id = c.id ' + + 'WHERE c.id = $1 AND m.user_id = $2', [chatId, userId]); + return row ? toChat(row) : null; +} + +export async function isMember(chatId: string, userId: string): Promise { + return (await sql('SELECT 1 FROM chat_members WHERE chat_id = $1 AND user_id = $2', [chatId, userId])).length > 0; +} + +/** Чаты пользователя после позиции after по (created_at, id); индекс chat_members_user_idx. */ +export async function listChatsOfUser(userId: string, after: Position, count: number): Promise { + const rows = await sql('SELECT ' + CHAT_COLUMNS + ' FROM chat_members m JOIN chats c ON c.id = m.chat_id ' + + 'WHERE m.user_id = $1 AND (c.created_at, c.id) > ($2::timestamptz, $3::uuid) ' + + 'ORDER BY c.created_at, c.id LIMIT $4', [userId, after.created_at, after.id, count]); + return rows.map(toChat); +} diff --git a/src/repositories/messages.ts b/src/repositories/messages.ts new file mode 100644 index 00000000..e85c3ad1 --- /dev/null +++ b/src/repositories/messages.ts @@ -0,0 +1,31 @@ +// SQL для таблицы messages. +import { sql, type Row, violates } from '../infra/db.js'; +import type { Message, Position } from '../models.js'; + +const COLUMNS = 'id, chat_id, sender_id, text, created_at'; + +const toMessage = (r: Row): Message => ({ + id: r.id, chat_id: r.chat_id, sender_id: r.sender_id, text: r.text, created_at: r.created_at.toISOString(), +}); + +/** Сохраняет сообщение; null, если чата нет или отправитель не участник. + * Это проверяет сама БД составным внешним ключом (chat_id, sender_id) -> chat_members. */ +export async function createMessage(chatId: string, senderId: string, text: string): Promise { + try { + const [row] = await sql('INSERT INTO messages (chat_id, sender_id, text) VALUES ($1, $2, $3) RETURNING ' + COLUMNS, + [chatId, senderId, text]); + return toMessage(row); + } catch (e) { + if (violates(e, '23503')) return null; + throw e; + } +} + +/** Страница истории после позиции after. Индекс messages_chat_created_id_idx читает count записей, + * а не всю историю чата (обоснование — evidence/track2). */ +export async function listMessages(chatId: string, after: Position, count: number): Promise { + const rows = await sql('SELECT ' + COLUMNS + ' FROM messages ' + + 'WHERE chat_id = $1 AND (created_at, id) > ($2::timestamptz, $3::uuid) ' + + 'ORDER BY created_at, id LIMIT $4', [chatId, after.created_at, after.id, count]); + return rows.map(toMessage); +} diff --git a/src/repositories/users.ts b/src/repositories/users.ts new file mode 100644 index 00000000..86418550 --- /dev/null +++ b/src/repositories/users.ts @@ -0,0 +1,32 @@ +// SQL для таблицы users. +import { sql, type Row, violates } from '../infra/db.js'; +import type { User } from '../models.js'; + +const toUser = (r: Row): User => ({ + id: r.id, username: r.username, display_name: r.display_name, created_at: r.created_at.toISOString(), +}); + +/** Создаёт пользователя; null, если username уже занят. */ +export async function createUser(username: string, displayName: string, passwordHash: string): Promise { + try { + const [row] = await sql('INSERT INTO users (username, display_name, password_hash) VALUES ($1, $2, $3) ' + + 'RETURNING id, username, display_name, created_at', [username, displayName, passwordHash]); + return toUser(row); + } catch (e) { + // гонку одновременных регистраций одного имени решает UNIQUE-ограничение, а не проверка в коде + if (violates(e, '23505')) return null; + throw e; + } +} + +export async function findUserById(id: string): Promise { + const [row] = await sql('SELECT id, username, display_name, created_at FROM users WHERE id = $1', [id]); + return row ? toUser(row) : null; +} + +/** Пользователь вместе с хэшем пароля — только для входа, наружу хэш не отдаётся. */ +export async function findCredentials(username: string): Promise<{ user: User; passwordHash: string } | null> { + const [row] = await sql('SELECT id, username, display_name, created_at, password_hash FROM users WHERE username = $1', + [username]); + return row ? { user: toUser(row), passwordHash: row.password_hash } : null; +} diff --git a/src/routes/auth.ts b/src/routes/auth.ts new file mode 100644 index 00000000..4cdd5713 --- /dev/null +++ b/src/routes/auth.ts @@ -0,0 +1,39 @@ +// POST /auth/sessions — вход по Basic; DELETE /auth/sessions/current — выход. +import { DUMMY_HASH, verifyPassword } from '../auth/passwords.js'; +import { createSession, revokeCurrentSession } from '../auth/sessions.js'; +import { badRequest, unauthorized } from '../http/errors.js'; +import type { Handler } from '../http/router.js'; +import { USERNAME } from '../http/validation.js'; +import { findCredentials } from '../repositories/users.js'; + +const BASE64 = /^[A-Za-z0-9+/]+={0,2}$/; + +/** Разбирает Authorization: Basic base64(username:password) по RFC 7617; пароль может содержать двоеточие. */ +function basicCredentials(header: string | undefined): { username: string; password: string } { + const [scheme, credential = ''] = (header ?? '').split(' ', 2); + if (scheme.toLowerCase() !== 'basic' || !BASE64.test(credential)) throw unauthorized('Basic'); + let decoded: string; + try { + decoded = new TextDecoder('utf-8', { fatal: true }).decode(Buffer.from(credential, 'base64')); + } catch { + throw unauthorized('Basic'); + } + const colon = decoded.indexOf(':'); + return { username: colon > 0 ? decoded.slice(0, colon) : '', password: decoded.slice(colon + 1) }; +} + +export const login: Handler = async (ctx) => { + const { username, password } = basicCredentials(ctx.req.headers.authorization); + if (ctx.body.length) throw badRequest('Тело запроса не принимается'); + const found = USERNAME.test(username) ? await findCredentials(username) : null; + // KDF считается всегда, ответ на любую ошибку одинаковый: нельзя узнать, существует ли пользователь + const ok = await verifyPassword(password, found?.passwordHash ?? DUMMY_HASH); + if (!ok || !found) throw unauthorized('Basic'); + const { token, expiresAt } = await createSession(found.user.id); + return [201, { token, token_type: 'Bearer', expires_at: expiresAt.toISOString(), user: found.user }]; +}; + +export const logout: Handler = async (ctx) => { + await revokeCurrentSession(ctx); + return [204, undefined]; +}; diff --git a/src/routes/chats.ts b/src/routes/chats.ts new file mode 100644 index 00000000..59d79814 --- /dev/null +++ b/src/routes/chats.ts @@ -0,0 +1,36 @@ +// Чаты: создание, список своих чатов, один чат. Посторонний получает 404, а не 403. +import { requireUser } from '../auth/sessions.js'; +import { badRequest, notFound } from '../http/errors.js'; +import type { Handler } from '../http/router.js'; +import { afterCursor, jsonBody, page, pageLimit, parseUuid, textField } from '../http/validation.js'; +import { createChat, findChatForMember, listChatsOfUser } from '../repositories/chats.js'; + +export const create: Handler = async (ctx) => { + const userId = await requireUser(ctx); + const data = jsonBody(ctx, ['title', 'member_ids']); + const title = textField(data.title, 'title', 1, 100); + if (!Array.isArray(data.member_ids) || data.member_ids.length < 1 || data.member_ids.length > 100) { + throw badRequest('member_ids: 1..100 UUID'); + } + const members = data.member_ids.map(parseUuid); + if (new Set(members).size !== members.length || !members.includes(userId)) { + throw badRequest('member_ids: без повторов и с вызывающим пользователем'); + } + const chat = await createChat(title, members); + if (!chat) throw badRequest('Неизвестный участник'); + return [201, chat]; +}; + +export const list: Handler = async (ctx) => { + const userId = await requireUser(ctx); + const limit = pageLimit(ctx); + const scope = 'u:' + userId; + return [200, page(await listChatsOfUser(userId, afterCursor(ctx, scope), limit + 1), limit, scope)]; +}; + +export const get: Handler = async (ctx) => { + const userId = await requireUser(ctx); + const chat = await findChatForMember(parseUuid(ctx.params[0]), userId); + if (!chat) throw notFound(); + return [200, chat]; +}; diff --git a/src/routes/health.ts b/src/routes/health.ts new file mode 100644 index 00000000..8349b04c --- /dev/null +++ b/src/routes/health.ts @@ -0,0 +1,18 @@ +// /health/live — процесс жив; /health/ready — можно обслуживать запросы. +import { ApiError } from '../http/errors.js'; +import type { Handler } from '../http/router.js'; +import { pingDb } from '../infra/db.js'; +import { pingValkey } from '../infra/valkey.js'; + +export const live: Handler = async () => [200, { status: 'ok' }]; + +// Обе зависимости на синхронном пути: данные в PostgreSQL, сессии в Valkey. +export const ready: Handler = async () => { + try { + await pingDb(); + await pingValkey(); + } catch { + throw new ApiError(503, 'unavailable', 'Зависимость недоступна'); + } + return [200, { status: 'ok' }]; +}; diff --git a/src/routes/index.ts b/src/routes/index.ts new file mode 100644 index 00000000..2089ce86 --- /dev/null +++ b/src/routes/index.ts @@ -0,0 +1,21 @@ +// Таблица маршрутов: метод, путь, обработчик. Группы в скобках пути передаются в ctx.params. +import type { Route } from '../http/router.js'; +import * as auth from './auth.js'; +import * as chats from './chats.js'; +import * as health from './health.js'; +import * as messages from './messages.js'; +import * as users from './users.js'; + +export const routes: Route[] = [ + ['GET', /^\/health\/live$/, health.live], + ['GET', /^\/health\/ready$/, health.ready], + ['POST', /^\/api\/v1\/users$/, users.register], + ['GET', /^\/api\/v1\/users\/me$/, users.me], + ['POST', /^\/api\/v1\/auth\/sessions$/, auth.login], + ['DELETE', /^\/api\/v1\/auth\/sessions\/current$/, auth.logout], + ['POST', /^\/api\/v1\/chats$/, chats.create], + ['GET', /^\/api\/v1\/chats$/, chats.list], + ['GET', /^\/api\/v1\/chats\/([^/]+)$/, chats.get], + ['POST', /^\/api\/v1\/chats\/([^/]+)\/messages$/, messages.send], + ['GET', /^\/api\/v1\/chats\/([^/]+)\/messages$/, messages.history], +]; diff --git a/src/routes/messages.ts b/src/routes/messages.ts new file mode 100644 index 00000000..8ef87bf7 --- /dev/null +++ b/src/routes/messages.ts @@ -0,0 +1,26 @@ +// Сообщения чата: отправка и история с keyset-пагинацией. Отправитель берётся из сессии, не из тела. +import { requireUser } from '../auth/sessions.js'; +import { notFound } from '../http/errors.js'; +import type { Handler } from '../http/router.js'; +import { afterCursor, jsonBody, page, pageLimit, parseUuid, textField } from '../http/validation.js'; +import { isMember } from '../repositories/chats.js'; +import { createMessage, listMessages } from '../repositories/messages.js'; + +export const send: Handler = async (ctx) => { + const userId = await requireUser(ctx); + const chatId = parseUuid(ctx.params[0]); + const text = textField(jsonBody(ctx, ['text']).text, 'text', 1, 4000); + const message = await createMessage(chatId, userId, text); + if (!message) throw notFound(); // чата нет или пользователь в нём не состоит + return [201, message]; +}; + +export const history: Handler = async (ctx) => { + const userId = await requireUser(ctx); + const chatId = parseUuid(ctx.params[0]); + const limit = pageLimit(ctx); + const scope = 'c:' + chatId; + const after = afterCursor(ctx, scope); + if (!(await isMember(chatId, userId))) throw notFound(); + return [200, page(await listMessages(chatId, after, limit + 1), limit, scope)]; +}; diff --git a/src/routes/users.ts b/src/routes/users.ts new file mode 100644 index 00000000..159b892b --- /dev/null +++ b/src/routes/users.ts @@ -0,0 +1,23 @@ +// POST /users — публичная регистрация; GET /users/me — текущий пользователь. +import { hashPassword } from '../auth/passwords.js'; +import { requireUser } from '../auth/sessions.js'; +import { ApiError, unauthorized } from '../http/errors.js'; +import type { Handler } from '../http/router.js'; +import { jsonBody, textField, usernameField } from '../http/validation.js'; +import { createUser, findUserById } from '../repositories/users.js'; + +export const register: Handler = async (ctx) => { + const data = jsonBody(ctx, ['username', 'display_name', 'password']); + const username = usernameField(data.username); + const displayName = textField(data.display_name, 'display_name', 1, 100); + const password = textField(data.password, 'password', 12, 128); + const user = await createUser(username, displayName, await hashPassword(password)); + if (!user) throw new ApiError(409, 'conflict', 'Имя пользователя занято'); + return [201, user]; +}; + +export const me: Handler = async (ctx) => { + const user = await findUserById(await requireUser(ctx)); + if (!user) throw unauthorized(); + return [200, user]; +}; diff --git a/student-tests/test_lab2.py b/student-tests/test_lab2.py new file mode 100755 index 00000000..81658067 --- /dev/null +++ b/student-tests/test_lab2.py @@ -0,0 +1,161 @@ +#!/usr/bin/env python3 +"""Проверки уровня 4: гонки, откат, пагинация, истечение сессии, logout, неверный пароль, отказ зависимостей. + +Использует помощники из публичного tests/client.py. Останавливает и запускает сервисы compose (volumes сохраняются): + python3 student-tests/test_lab2.py --base-url http://127.0.0.1:8080 +""" +import base64 +import subprocess +import sys +import time +import uuid +from concurrent.futures import ThreadPoolExecutor +from pathlib import Path +from urllib.parse import quote + +ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(ROOT / 'tests')) +from client import Client, arguments, check, run # noqa: E402 + + +def compose(*args): + subprocess.run(['docker', 'compose', *args], cwd=ROOT, check=True, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL) + + +def psql(query): + out = subprocess.run(['docker', 'compose', 'exec', '-T', 'postgres', 'psql', '-U', 'messenger', '-d', 'messenger', + '-tAc', query], cwd=ROOT, check=True, capture_output=True, text=True) + return out.stdout.strip() + + +def basic(username, password): + return {'Authorization': 'Basic ' + base64.b64encode((username + ':' + password).encode()).decode()} + + +def wait_ready(c, seconds=60): + deadline = time.monotonic() + seconds + while True: + try: + return c.call('GET', '/health/ready', schema='Health') + except Exception: + check(time.monotonic() < deadline, 'API did not become ready') + time.sleep(0.5) + + +def test_registration_race(c): + body = {'username': 'race_' + uuid.uuid4().hex[:12], 'display_name': 'Гонка', 'password': 'Race-password-123'} + with ThreadPoolExecutor(20) as pool: + codes = list(pool.map(lambda _: Client(c.base).call('POST', '/api/v1/users', [201, 409], body=body)['status'], + range(20))) + check(codes.count(201) == 1 and codes.count(409) == 19, 'race: expected one 201 and 19x409, got %r' % codes) + check(psql("SELECT count(*) FROM users WHERE username = '%s'" % body['username']) == '1', 'race: duplicate row') + return '20 parallel registrations of one username -> 1x201, 19x409, 1 row' + + +def test_chat_rollback(c): + alice = c.user('rb') + title = 'rollback-' + uuid.uuid4().hex + before = psql('SELECT count(*) FROM chats') + # запрос проходит валидацию; неизвестный участник нарушает FK уже после вставки строки чата + c.call('POST', '/api/v1/chats', 400, actor=alice, body={'title': title, 'member_ids': [alice['id'], str(uuid.uuid4())]}) + check(psql("SELECT count(*) FROM chats WHERE title = '%s'" % title) == '0', 'rollback: orphan chat row left') + check(psql('SELECT count(*) FROM chat_members m LEFT JOIN chats c ON c.id = m.chat_id WHERE c.id IS NULL') == '0', + 'rollback: orphan members') + check(psql('SELECT count(*) FROM chats') == before, 'rollback: chat count changed') + return 'chat with unknown member -> 400, no chat/member rows (transaction rolled back)' + + +def test_pagination_and_injection(c): + alice, bob = c.user('pa'), c.user('pb') + chat = c.call('POST', '/api/v1/chats', 201, actor=alice, body={'title': 'Пагинация', 'member_ids': [alice['id'], bob['id']]}, schema='Chat')['json'] + other = c.call('POST', '/api/v1/chats', 201, actor=alice, body={'title': 'Другой', 'member_ids': [alice['id']]}, schema='Chat')['json'] + sent = [c.message(alice if i % 2 else bob, chat, "msg %03d'); DROP TABLE messages;--" % i)['json'] for i in range(57)] + path = '/api/v1/chats/' + chat['id'] + '/messages?limit=7' + got, cursor = [], None + while True: + page = c.call('GET', path + ('&cursor=' + quote(cursor, safe='') if cursor else ''), actor=bob, schema='MessagePage')['json'] + got += page['items'] + cursor = page['next_cursor'] + if cursor is None: + break + # порядок по контракту — (created_at, id); два сообщения в одну миллисекунду упорядочены по id + check(got == sorted(sent, key=lambda m: (m['created_at'], uuid.UUID(m['id']).int)), 'pagination: lost/duplicated/reordered') + first = c.call('GET', path, actor=alice, schema='MessagePage')['json'] + c.call('GET', '/api/v1/chats/' + other['id'] + '/messages?cursor=' + quote(first['next_cursor'], safe=''), 400, actor=alice) + c.call('GET', path + '&cursor=garbage', 400, actor=alice) + check(psql("SELECT to_regclass('messages') IS NOT NULL") == 't', 'injection text affected schema') + return '57 messages over limit=7 pages: exact order, no dupes; foreign/garbage cursor -> 400; SQL text stored verbatim' + + +def test_wrong_password_and_logout(c): + alice = c.user('lo') + reg = alice['registration'] + for creds in (basic(reg['username'], reg['password'] + 'x'), basic('nobody_' + uuid.uuid4().hex[:8], reg['password'])): + r = c.call('POST', '/api/v1/auth/sessions', 401, headers=creds) + check(r['headers']['WWW-Authenticate'] == 'Basic realm="messenger", charset="UTF-8"', 'wrong challenge') + c.call('GET', '/api/v1/users/me', 401, headers={'X-User-Id': alice['id']}) + c.call('DELETE', '/api/v1/auth/sessions/current', 204, actor=alice) + c.call('GET', '/api/v1/users/me', 401, actor=alice) + c.call('DELETE', '/api/v1/auth/sessions/current', 401, actor=alice) + return 'wrong password / unknown user -> identical 401 Basic; logout -> 204, then 401 twice' + + +def test_expiry(c): + compose('--profile', 'ttl', 'up', '-d', '--wait', 'api_short_ttl') + try: + short = Client('http://127.0.0.1:8081') + wait_ready(short) + alice = short.user('ttl') + short.call('GET', '/api/v1/users/me', actor=alice, schema='User') + time.sleep(3) + r = short.call('GET', '/api/v1/users/me', 401, actor=alice) + check(r['headers']['WWW-Authenticate'] == 'Bearer realm="messenger"', 'wrong challenge') + # Valkey общий, поэтому основной API тоже должен отклонить токен + c.call('GET', '/api/v1/users/me', 401, actor=alice) + finally: + compose('--profile', 'ttl', 'stop', 'api_short_ttl') + return 'SESSION_TTL_SECONDS=2: 200 right after login, 401 after 3 s on both API processes' + + +def outage(c, service, survives): + alice = c.user('out' + service[:2]) + compose('stop', service) + try: + for path in ('/health/ready', '/api/v1/users/me'): + started = time.monotonic() + r = c.call('GET', path, 503, actor=alice) + elapsed = time.monotonic() - started + check(r['json']['error']['code'] == 'unavailable' and elapsed < 5, service + ': not a bounded 503') + # анонимный запрос по-прежнему 401, а не обслуживается как доверенный + c.call('GET', '/api/v1/users/me', 401) + survivor = c.call('POST', '/api/v1/users', [201, 503], body={'username': 'o_' + uuid.uuid4().hex[:12], + 'display_name': 'x', 'password': 'Outage-password-1'}) + check(survivor['status'] == (201 if survives else 503), service + ': unexpected registration result') + finally: + compose('start', service) + wait_ready(c) + c.call('GET', '/api/v1/users/me', actor=alice, schema='User') # тот же токен после восстановления + return '%s stopped -> ready/me 503 unavailable in %.2fs, anonymous 401, registration %s; recovered with same token' % ( + service, elapsed, '201' if survives else '503') + + +def test_valkey_outage(c): + return outage(c, 'valkey', survives=True) + + +def test_postgres_outage(c): + return outage(c, 'postgres', survives=False) + + +def main(): + args = arguments('Student level-4 checks (stops/starts compose services)') + c = Client(args.base_url or 'http://127.0.0.1:8080') + wait_ready(c) + tests = [test_registration_race, test_chat_rollback, test_pagination_and_injection, test_wrong_password_and_logout, + test_expiry, test_valkey_outage, test_postgres_outage] + for test in tests: + print('PASS', test.__name__, '-', test(c), flush=True) + + +if __name__ == '__main__': + run(main) diff --git a/tsconfig.json b/tsconfig.json new file mode 100644 index 00000000..c3ba1b5c --- /dev/null +++ b/tsconfig.json @@ -0,0 +1,12 @@ +{ + "compilerOptions": { + "target": "ES2024", + "module": "NodeNext", + "moduleResolution": "NodeNext", + "rootDir": "src", + "outDir": "dist", + "strict": true, + "skipLibCheck": true + }, + "include": ["src"] +} -- 2.54.0