diff --git a/.dockerignore b/.dockerignore index bc16e55..c7cf4ca 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 b5a7189..ad6f84c 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 0000000..2c77c0c --- /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 form: node is PID 1 and handles SIGTERM itself (graceful close of HTTP, pool and Valkey) +CMD ["node", "dist/app.js"] diff --git a/REPORT.md b/REPORT.md index e42f2b0..cad1095 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,126 @@ # Отчёт — лабораторная 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. Код и эксперимент подготовлены с помощью ИИ-ассистента (Claude), проверены прогоном всех тестов ниже; решение объясняю и меняю сам. ## Запуск из чистого 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 +``` + +| Роль | 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 0000000..c3a2577 --- /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"] + + # Second API process with a 2 s TTL for the automatic expiry test (same DB and 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 0000000..49ad289 --- /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 0000000..3597799 --- /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.02s, 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 0000000..840f28f --- /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 0000000..6f213dd --- /dev/null +++ b/evidence/persistence.txt @@ -0,0 +1,14 @@ +# before +api 2026-10-29T17:36:26.445238878Z +postgres 2026-10-29T17:37:54.996532602Z +valkey 2026-10-29T17:37:48.230161722Z +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. +# after (all three StartedAt changed, volumes kept) +api 2026-10-29T17:46:36.369988683Z +postgres 2026-10-29T17:46:31.719791235Z +valkey 2026-10-29T17:46:31.735641919Z +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 0000000..0e45742 --- /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 0000000..44253b8 --- /dev/null +++ b/evidence/smoke.txt @@ -0,0 +1,3 @@ +# 2026-10-29T17:46:26Z +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 0000000..df4e57d --- /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 0000000..5d6c15b --- /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 0000000..90acae2 --- /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 0000000..027374b --- /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 0000000..415ef9b --- /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 0000000..e16a11c --- /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 0000000..9733ea3 --- /dev/null +++ b/experiments/track2/generate.sql @@ -0,0 +1,37 @@ +-- Track 2 synthetic dataset (deterministic seed): 1000 users, 300 chats with Zipf-like sizes +-- round(60000 / k^1.2) -> 60000 ... 64 messages, ~240k messages total, random physical order over 90 days. +-- Users get a random, well-formed scrypt hash: nobody can log in as them. +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(); + +-- (chat, sender) pairs for write benchmarks: a primary-key lookup, the same for every index variant +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 0000000..edc0f71 --- /dev/null +++ b/experiments/track2/run.py @@ -0,0 +1,293 @@ +#!/usr/bin/env python3 +"""Track 2: history query plans on >=100k messages, index write cost, backup -> restore -> reconcile. + +Runs against the compose stack (service postgres). Changes ONLY the secondary indexes of `messages` +during the experiment and always ends with the migration index. Adds synthetic track2_* data once. + python3 experiments/track2/run.py # results -> evidence/track2/ + python3 experiments/track2/run.py --render # rebuild results.md from 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 = { # secondary index of messages; PK(id) is always there + '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 = { + # the API query (pg sends it as an unnamed prepared statement -> custom plan with these values) + '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): + """Rows read by scan nodes (returned + filtered out); per-loop figures times loops.""" + 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 last: the database ends in the migration state + 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) + # human-readable plan of the API query on the largest chat for every variant + 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(): # commits that race with pg_dump: show the data-loss boundary of a logical 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) + # new storage: fresh container + fresh named volume, no network at all + 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]) # throwaway restore target; its volume stays for inspection + + +if __name__ == '__main__': + main() diff --git a/infra/valkey.conf b/infra/valkey.conf new file mode 100644 index 0000000..d2c43ce --- /dev/null +++ b/infra/valkey.conf @@ -0,0 +1,8 @@ +# Valkey is the only session store, so it must survive a restart. +# AOF with fsync on every write: a 201 from POST /auth/sessions means the session is on disk. +appendonly yes +appendfsync always +save "" +dir /data +# requirepass lives in a local secret generated by 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 0000000..bc2c4f4 --- /dev/null +++ b/migrations/001_init.sql @@ -0,0 +1,36 @@ +-- Users, chats, membership and messages. PostgreSQL is the source of truth. +-- timestamptz(3): millisecond precision round-trips exactly through JS Date and keyset cursors. +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: chats of one user. +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(), + -- the sender must be a member of the chat; also covers chat/user existence + FOREIGN KEY (chat_id, sender_id) REFERENCES chat_members (chat_id, user_id) +); +-- History keyset: WHERE chat_id = $1 AND (created_at, id) > ($2, $3) ORDER BY created_at, id LIMIT $4. +-- Choice justified in evidence/track2 (EXPLAIN ANALYZE on 200k messages). +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 0000000..d5a2f37 --- /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 0000000..2cb45dc --- /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/app.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 0000000..d663c4d --- /dev/null +++ b/scripts/init-secrets.sh @@ -0,0 +1,20 @@ +#!/bin/sh +# Generates local synthetic credentials in ./secrets (git-ignored). Safe to re-run: keeps existing files. +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 +# containers run as non-root users and read these via bind-mounted secrets +chmod 644 secrets/* +echo "secrets ready in ./secrets (values not printed)" diff --git a/scripts/restart.sh b/scripts/restart.sh new file mode 100755 index 0000000..666a889 --- /dev/null +++ b/scripts/restart.sh @@ -0,0 +1,7 @@ +#!/bin/sh +# Full restart of API and every state store (PostgreSQL, Valkey) keeping named volumes. +# Never down -v / flush / re-seed. +set -eu +cd "$(dirname "$0")/.." +docker compose stop api valkey postgres +docker compose start postgres valkey api diff --git a/src/app.ts b/src/app.ts new file mode 100644 index 0000000..d4411ba --- /dev/null +++ b/src/app.ts @@ -0,0 +1,393 @@ +// Messenger API, lab2: PostgreSQL is the source of truth, Valkey stores Bearer sessions. +import { createHash, randomBytes, randomUUID, scrypt, timingSafeEqual } from 'node:crypto'; +import { createServer, type IncomingMessage, type ServerResponse } from 'node:http'; +import { Redis } from 'ioredis'; +import pg from 'pg'; +import { setting } from './migrate.js'; + +const SESSION_TTL_MS = Number(setting('SESSION_TTL_SECONDS', '3600')) * 1000; +const USERNAME = /^[a-z0-9_]{3,32}$/; +const BEARER = /^[A-Za-z0-9_-]{32,128}$/; +const BASE64 = /^[A-Za-z0-9+/]+={0,2}$/; +const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i; +const MAX_BODY = 1024 * 1024; + +// Bounded pool and timeouts: a dead DB turns into 503 within ~2 s instead of a hanging request. +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, +}); +// a DB restart kills idle clients: the pool drops them, the process must not crash +pool.on('error', (e) => log({ event: 'db_idle_client_error', error: e.message })); + +// No offline queue: while Valkey is down a command fails at once (-> 503) instead of waiting. +const sessions = new Redis(setting('CACHE_URL'), { + connectTimeout: 1000, commandTimeout: 1000, enableOfflineQueue: false, maxRetriesPerRequest: 0, +}); +sessions.on('error', (e) => log({ event: 'valkey_error', error: e.message })); + +function log(entry: object) { + console.log(JSON.stringify({ ts: new Date().toISOString(), ...entry })); +} + +class ApiError extends Error { + constructor(readonly status: number, readonly code: string, message: string, readonly challenge?: string) { + super(message); + } +} +class Unavailable extends Error {} + +const bad = (message: string) => new ApiError(400, 'invalid_request', message); +const NOT_FOUND = new ApiError(404, 'not_found', 'Объект не найден'); +const unauthorized = (scheme = 'Bearer') => new ApiError(401, 'unauthorized', 'Требуется действительная аутентификация', + scheme === 'Basic' ? 'Basic realm="messenger", charset="UTF-8"' : 'Bearer realm="messenger"'); + +/** Constraint/SQL errors pass through for the caller; connection loss and timeouts become 503. */ +async function dep(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)); + } +} + +type Row = Record; +type Query = (text: string, values?: unknown[]) => Promise; + +const sql: Query = async (text, values = []) => (await dep(pool.query(text, values))).rows; + +async function transaction(fn: (q: Query) => Promise): Promise { + const client = await dep(pool.connect()); + const q: Query = async (text, values = []) => (await dep(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); // a client that cannot roll back is destroyed, not reused + throw e; + } +} + +const isConstraint = (e: unknown, code: string) => e instanceof pg.DatabaseError && e.code === code; + +// ---- validation ---------------------------------------------------------------- + +type Ctx = { req: IncomingMessage; url: URL; body: Buffer; params: string[] }; + +function jsonBody(ctx: Ctx, required: string[]): Row { + let data: unknown; + try { + data = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(ctx.body)); + } catch { + throw bad('Тело должно быть JSON-объектом в UTF-8'); + } + if (typeof data !== 'object' || data === null || Array.isArray(data)) throw bad('Тело должно быть JSON-объектом'); + const keys = Object.keys(data); + if (keys.length !== required.length || !required.every((k) => keys.includes(k))) throw bad('Неверный набор полей'); + return data as Row; +} + +function textField(value: unknown, name: string, min: number, max: number): string { + // code points, not UTF-16 units; NUL and lone surrogates cannot be stored as PostgreSQL text + if (typeof value !== 'string' || !value.isWellFormed() || value.includes('\0') || !value.trim() + || [...value].length < min || [...value].length > max) throw bad('Неверное поле ' + name); + return value; +} + +function parseUuid(value: unknown): string { + if (typeof value !== 'string' || !UUID.test(value)) throw bad('Неверный UUID'); + return value.toLowerCase(); +} + +function pageLimit(url: URL): number { + const raw = url.searchParams.get('limit') ?? '50'; + if (!/^[0-9]{1,3}$/.test(raw) || +raw < 1 || +raw > 100) throw bad('limit должен быть целым 1..100'); + return +raw; +} + +// Opaque keyset cursor (created_at, id), bound to its list: a cursor of another chat is 400. +const encodeCursor = (scope: string, row: Row) => + Buffer.from([scope, row.created_at.toISOString(), row.id].join('|')).toString('base64url'); + +function decodeCursor(url: URL, scope: string): [string, string] { + const raw = url.searchParams.get('cursor'); + if (raw === null) return ['-infinity', '00000000-0000-0000-0000-000000000000']; + 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 bad('Неверный cursor'); + } + return [createdAt, id]; +} + +const userOut = (r: Row) => ({ id: r.id, username: r.username, display_name: r.display_name, + created_at: r.created_at.toISOString() }); +const chatOut = (r: Row) => ({ id: r.id, title: r.title, member_ids: r.member_ids, created_at: r.created_at.toISOString() }); +const messageOut = (r: Row) => ({ id: r.id, chat_id: r.chat_id, sender_id: r.sender_id, text: r.text, + created_at: r.created_at.toISOString() }); + +// ---- passwords and sessions ------------------------------------------------------ + +// scrypt N=2^14, r=8, p=1 (16 MiB, tens of ms, libuv thread pool): a password KDF, unlike fast SHA-256 +const SCRYPT = { N: 16384, r: 8, p: 1 }; +const kdf = (password: string, salt: Buffer, params: { N: number; r: number; p: number }, length: number) => + new Promise((ok, fail) => scrypt(password, salt, length, params, (e, key) => (e ? fail(e) : ok(key)))); + +async function hashPassword(password: string): Promise { + const salt = randomBytes(16); + const key = await kdf(password, salt, SCRYPT, 32); + return ['scrypt', SCRYPT.N, SCRYPT.r, SCRYPT.p, salt.toString('hex'), key.toString('hex')].join('$'); +} + +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); +} + +const DUMMY_HASH = await hashPassword('timing-equaliser-for-unknown-users'); + +// token has 256 bits of entropy, so a fast hash is enough; Valkey never holds a usable token +const sessionKey = (token: string) => 'session:' + createHash('sha256').update(token).digest('hex'); + +async function bearerSession(ctx: Ctx): Promise<{ key: string; uid: string }> { + const [scheme, token = ''] = (ctx.req.headers.authorization ?? '').split(' ', 2); + if (scheme.toLowerCase() !== 'bearer' || !BEARER.test(token)) throw unauthorized(); + const key = sessionKey(token); + const raw = await dep(sessions.get(key)); // Valkey down -> 503, never an anonymous pass + if (raw === null) throw unauthorized(); + const session = JSON.parse(raw); + if (session.exp <= Date.now()) throw unauthorized(); + return { key, uid: session.uid }; +} + +const currentUser = async (ctx: Ctx) => (await bearerSession(ctx)).uid; + +// ---- routes ------------------------------------------------------------------------ + +type Result = [number, unknown]; + +async function ready(): Promise { + // both are on the synchronous path: data in PostgreSQL, sessions in Valkey + try { + await dep(pool.query('SELECT 1')); + await dep(sessions.ping()); + } catch { + throw new ApiError(503, 'unavailable', 'Зависимость недоступна'); + } + return [200, { status: 'ok' }]; +} + +async function register(ctx: Ctx): Promise { + const data = jsonBody(ctx, ['username', 'display_name', 'password']); + if (typeof data.username !== 'string' || !USERNAME.test(data.username)) throw bad('Неверное поле username'); + textField(data.display_name, 'display_name', 1, 100); + textField(data.password, 'password', 12, 128); + try { + const [row] = await sql('INSERT INTO users (username, display_name, password_hash) VALUES ($1, $2, $3) ' + + 'RETURNING id, username, display_name, created_at', + [data.username, data.display_name, await hashPassword(data.password)]); + return [201, userOut(row)]; + } catch (e) { + // the UNIQUE constraint settles concurrent registrations of one username + if (isConstraint(e, '23505')) throw new ApiError(409, 'conflict', 'Имя пользователя занято'); + throw e; + } +} + +async function login(ctx: Ctx): Promise { + const [scheme, credential = ''] = (ctx.req.headers.authorization ?? '').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'); + } + if (ctx.body.length) throw bad('Тело запроса не принимается'); + const colon = decoded.indexOf(':'); + const username = decoded.slice(0, colon); + const password = decoded.slice(colon + 1); + const [row] = colon > 0 && USERNAME.test(username) + ? await sql('SELECT id, username, display_name, created_at, password_hash FROM users WHERE username = $1', [username]) + : []; + // same KDF work for unknown users, same 401 for every failure + if (!(await verifyPassword(password, row?.password_hash ?? DUMMY_HASH)) || !row) throw unauthorized('Basic'); + const token = randomBytes(32).toString('base64url'); + const exp = Date.now() + SESSION_TTL_MS; + // absolute expiry (PXAT): restarting the API or Valkey never extends a session + await dep(sessions.set(sessionKey(token), JSON.stringify({ uid: row.id, exp }), 'PXAT', exp)); + return [201, { token, token_type: 'Bearer', expires_at: new Date(exp).toISOString(), user: userOut(row) }]; +} + +async function logout(ctx: Ctx): Promise { + const { key } = await bearerSession(ctx); + if (!(await dep(sessions.del(key)))) throw unauthorized(); // concurrent logout: only one wins + return [204, undefined]; +} + +async function me(ctx: Ctx): Promise { + const [row] = await sql('SELECT id, username, display_name, created_at FROM users WHERE id = $1', [await currentUser(ctx)]); + if (!row) throw unauthorized(); + return [200, userOut(row)]; +} + +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'; + +async function createChat(ctx: Ctx): Promise { + const uid = await currentUser(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 bad('member_ids: 1..100 UUID'); + } + const members = data.member_ids.map(parseUuid); + if (new Set(members).size !== members.length || !members.includes(uid)) { + throw bad('member_ids: без повторов и с вызывающим пользователем'); + } + try { + const row = await transaction(async (q) => { // chat + all members, or nothing + 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, members]); + return (await q('SELECT ' + CHAT_COLUMNS + ' FROM chats c WHERE c.id = $1', [chat.id]))[0]; + }); + return [201, chatOut(row)]; + } catch (e) { + if (isConstraint(e, '23503')) throw bad('Неизвестный участник'); // already rolled back + throw e; + } +} + +async function listChats(ctx: Ctx): Promise { + const uid = await currentUser(ctx); + const limit = pageLimit(ctx.url); + const [afterTs, afterId] = decodeCursor(ctx.url, 'u:' + uid); + 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', [uid, afterTs, afterId, limit + 1]); + const next = rows.length > limit ? encodeCursor('u:' + uid, rows[limit - 1]) : null; + return [200, { items: rows.slice(0, limit).map(chatOut), next_cursor: next }]; +} + +async function getChat(ctx: Ctx): Promise { + const uid = await currentUser(ctx); + 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', [parseUuid(ctx.params[0]), uid]); + if (!row) throw NOT_FOUND; + return [200, chatOut(row)]; +} + +async function createMessage(ctx: Ctx): Promise { + const uid = await currentUser(ctx); + const chatId = parseUuid(ctx.params[0]); + const text = textField(jsonBody(ctx, ['text']).text, 'text', 1, 4000); + try { + const [row] = await sql('INSERT INTO messages (chat_id, sender_id, text) VALUES ($1, $2, $3) ' + + 'RETURNING id, chat_id, sender_id, text, created_at', [chatId, uid, text]); + return [201, messageOut(row)]; + } catch (e) { + if (isConstraint(e, '23503')) throw NOT_FOUND; // (chat_id, sender_id) not in chat_members + throw e; + } +} + +async function listMessages(ctx: Ctx): Promise { + const uid = await currentUser(ctx); + const chatId = parseUuid(ctx.params[0]); + const limit = pageLimit(ctx.url); + const [afterTs, afterId] = decodeCursor(ctx.url, 'c:' + chatId); + const member = await sql('SELECT 1 FROM chat_members WHERE chat_id = $1 AND user_id = $2', [chatId, uid]); + if (!member.length) throw NOT_FOUND; + // keyset page on messages_chat_created_id_idx: reads limit+1 index entries, not the whole history + const rows = await sql('SELECT id, chat_id, sender_id, text, created_at FROM messages ' + + 'WHERE chat_id = $1 AND (created_at, id) > ($2::timestamptz, $3::uuid) ' + + 'ORDER BY created_at, id LIMIT $4', [chatId, afterTs, afterId, limit + 1]); + const next = rows.length > limit ? encodeCursor('c:' + chatId, rows[limit - 1]) : null; + return [200, { items: rows.slice(0, limit).map(messageOut), next_cursor: next }]; +} + +const routes: Array<[string, RegExp, (ctx: Ctx) => Promise]> = [ + ['GET', /^\/health\/live$/, async () => [200, { status: 'ok' }]], + ['GET', /^\/health\/ready$/, ready], + ['POST', /^\/api\/v1\/users$/, register], + ['GET', /^\/api\/v1\/users\/me$/, me], + ['POST', /^\/api\/v1\/auth\/sessions$/, login], + ['DELETE', /^\/api\/v1\/auth\/sessions\/current$/, logout], + ['POST', /^\/api\/v1\/chats$/, createChat], + ['GET', /^\/api\/v1\/chats$/, listChats], + ['GET', /^\/api\/v1\/chats\/([^/]+)$/, getChat], + ['POST', /^\/api\/v1\/chats\/([^/]+)\/messages$/, createMessage], + ['GET', /^\/api\/v1\/chats\/([^/]+)\/messages$/, listMessages], +]; + +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); +} + +async function handle(req: IncomingMessage, res: ServerResponse) { + const rid = randomUUID(); + const started = performance.now(); + let status = 500; + let payload: unknown; + let challenge: string | undefined; + try { + const url = new URL(req.url ?? '/', 'http://localhost'); + let found: [RegExpExecArray, (ctx: Ctx) => Promise] | undefined; + for (const [method, pattern, handler] of routes) { + const match = req.method === method ? pattern.exec(url.pathname) : null; + if (match) { + found = [match, handler]; + break; + } + } + if (!found) throw NOT_FOUND; + [status, payload] = await found[1]({ req, url, body: await readBody(req), params: found[0].slice(1) }); + } catch (e) { + if (e instanceof ApiError) { + [status, challenge] = [e.status, e.challenge]; + payload = { error: { code: e.code, message: e.message, request_id: rid } }; + } else if (e instanceof Unavailable) { + log({ event: 'dependency_unavailable', rid, error: e.message }); + [status, payload] = [503, { error: { code: 'unavailable', message: 'Сервис временно недоступен', request_id: rid } }]; + } else { + log({ event: 'unexpected_error', rid, error: e instanceof Error ? e.stack : String(e) }); + [status, payload] = [500, { error: { code: 'internal_error', message: 'Внутренняя ошибка', request_id: 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)); + // access log without headers, bodies or query (no credentials, no cursors) + log({ rid, method: req.method, path: req.url?.split('?')[0], status, ms: +(performance.now() - started).toFixed(1) }); +} + +const server = createServer((req, res) => void handle(req, res)); +server.requestTimeout = 10_000; +server.listen(Number(setting('APP_PORT', '8080')), setting('APP_HOST', '0.0.0.0'), + () => log({ event: 'listening', port: setting('APP_PORT', '8080') })); + +function shutdown() { + log({ event: 'shutdown' }); + setTimeout(() => process.exit(1), 10_000).unref(); + server.close(() => void Promise.allSettled([pool.end(), sessions.quit()]).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 0000000..e84576e --- /dev/null +++ b/src/migrate.ts @@ -0,0 +1,49 @@ +// Apply versioned SQL migrations once each: node dist/migrate.js +import { readdirSync, readFileSync } from 'node:fs'; +import { join } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import pg from 'pg'; + +/** NAME_FILE (Docker secret path) wins over NAME; secret values are never logged. */ +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('missing setting ' + name); + return value; +} + +const dir = process.env.MIGRATIONS_DIR ?? fileURLToPath(new URL('../migrations', import.meta.url)); + +async function migrate() { + const client = new pg.Client({ connectionString: setting('DATABASE_URL'), connectionTimeoutMillis: 5000 }); + await client.connect(); + try { + // one runner at a time; a concurrent runner waits and then skips what is applied + 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; + } + await client.query('BEGIN'); // DDL is transactional in PostgreSQL: all or nothing + 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(); + } +} + +if (process.argv[1] === fileURLToPath(import.meta.url)) await migrate(); diff --git a/student-tests/test_lab2.py b/student-tests/test_lab2.py new file mode 100755 index 0000000..3b3a9c4 --- /dev/null +++ b/student-tests/test_lab2.py @@ -0,0 +1,161 @@ +#!/usr/bin/env python3 +"""Level-4 checks of my solution: races, rollback, pagination, expiry, logout, wrong password, dependency loss. + +Uses the public tests/client.py helpers. Stops/starts compose services (volumes are kept): + 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') + # caller passes validation; the unknown member fails the FK after the chat row was inserted + 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 + # contract order is (created_at, id); two messages in one millisecond are ordered by 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') + # the same Valkey is shared, so the main API must reject it too + 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') + # an anonymous request is still 401, never served as trusted + 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') # same token after recovery + 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 0000000..c3ba1b5 --- /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"] +}