Author SHA1 Message Date
Антон Архипов 98dd709eda [+] Completed lab 3 2026-11-16 16:15:08 +03:00
52 changed files with 4713 additions and 49 deletions
+6 -11
View File
@@ -1,13 +1,8 @@
# Copy to .env for your LOCAL synthetic test environment; never commit .env.
# These are logical interface suggestions; map actual framework names in REPORT.md.
APP_HOST=0.0.0.0
APP_PORT=8080
# Run scripts/init-env.sh to create local credentials and .env.
APP_BIND_PORT=8080
APP_ENV=lab
LOG_LEVEL=info
SESSION_TTL_SECONDS=3600
# Choose credentials locally. File paths contain no secret values.
DATABASE_URL_FILE=/run/secrets/database_url
# Optional on 3, required use on 4 in lab2; Redis OR Valkey:
SESSION_STORE=postgres
CACHE_URL_FILE=/run/secrets/cache_url
API_REPLICAS=2
IDEMPOTENCY_TTL_SECONDS=86400
POSTGRES_USER=messenger
POSTGRES_DB=messenger
POSTGRES_PASSWORD=
+4 -14
View File
@@ -1,18 +1,8 @@
## Лабораторная 3
Автор / группа: TODO
Целевая оценка (3/4/5): TODO
Трек 5, если заявлен: TODO
Автор / группа — Архипов Антон Андреевич, БПИ2304
Целевая оценка — 3
Что реализовано и что перенесено: TODO
Команды запуска из чистого clone: TODO
Результаты проверок и ссылка на REPORT.md: TODO
Ограничения / известные ошибки: TODO
Источники и использование ИИ: TODO
Из lab2 перенесены API, PostgreSQL, миграции и сессии Bearer. Добавлены HAProxy, две реплики, общий реестр ключей сообщений и сценарий отказа конкретной реплики.
- [ ] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами.
- [ ] Контракт и публичные тесты не ослаблены.
- [ ] make check и make test выполнены; приложен реальный вывод.
- [ ] Сценарии отказов/безопасности своего уровня воспроизведены.
- [ ] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens.
- [ ] README задания сохранён, REPORT.md содержит инструкцию именно моего решения.
Запуск — `./scripts/init-env.sh && docker compose build migrate && docker compose up -d --no-build --wait`. Сценарии проверок и измерения переключения — в [REPORT.md](../REPORT.md).
+22 -2
View File
@@ -12,5 +12,25 @@ jobs:
python-version: '3.12'
- run: python -m pip install -r requirements-dev.txt
- run: make check validate PYTHON=python
# This job validates the skeleton, not a student solution.
# Add build, readiness and make test in a separate application job.
application:
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- uses: actions/checkout@v4
- name: Build and start the stand
run: |
sh scripts/init-env.sh
docker compose config --quiet
docker compose build migrate
docker compose up -d --no-build --wait --wait-timeout 90
- name: Check public API and persistence
run: |
make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
- name: Check API replica failover
run: make test-failover ACTION_SCRIPT=scripts/stop-one.sh
- name: Show services and remove test data
if: always()
run: |
docker compose ps --all || true
docker compose down -v
+2
View File
@@ -30,3 +30,5 @@ coverage/
.vscode/
# Keep small, sanitized evidence summaries in evidence/ under version control.
# Inspect git diff --cached: ignore rules are not a secret scanner.
src/generated/
+22
View File
@@ -0,0 +1,22 @@
FROM node:22.16.0-alpine3.22 AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --no-audit --no-fund
COPY tsconfig.json tsoa.json ./
COPY src ./src
RUN npm run build && npm prune --omit=dev
FROM node:22.16.0-alpine3.22 AS runtime
ENV NODE_ENV=production \
APP_HOST=0.0.0.0 \
APP_PORT=8080
WORKDIR /app
COPY --from=build --chown=node:node /app/package.json ./
COPY --from=build --chown=node:node /app/node_modules ./node_modules
COPY --from=build --chown=node:node /app/dist ./dist
COPY --chown=node:node migrations ./migrations
COPY --chown=node:node contracts/openapi.json ./contracts/openapi.json
USER node
EXPOSE 8080
HEALTHCHECK --interval=2s --timeout=3s --start-period=3s --retries=3 CMD node -e "fetch('http://127.0.0.1:'+(process.env.APP_PORT||8080)+'/health/ready').then(r=>{if(!r.ok)process.exit(1)}).catch(()=>process.exit(1))"
CMD ["node", "dist/server.js"]
+53 -22
View File
@@ -1,37 +1,68 @@
# Отчёт — лабораторная 3
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
- Автор, группа — **Архипов Антон Андреевич, БПИ2304**
- Целевая оценка — **«3»**
- Commit/PR — указать после публикации в своём fork.
- Использованные библиотеки и инструменты — TypeScript, Express, tsoa, Zod, UUID, Pino, Swagger UI, node-postgres, Node.js `crypto`, Docker Compose и HAProxy. Материалы — `README.md`, `COURSE.md`, `contracts/README.md` и OpenAPI из задания.
- ИИ использовался для разбора требований, проектирования структуры приложения, проверки соответствия контракту и подготовки отчёта.
## Запуск из чистого clone
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
Нужны Docker Engine с Docker Compose v2, shell, GNU Make и Python 3.9+. Версии образов — Node.js `22.16.0-alpine3.22`, `postgres:15.18-bookworm` и `haproxy:3.0.11-alpine`.
```sh
chmod +x scripts/init-env.sh scripts/restart.sh scripts/stop-one.sh
./scripts/init-env.sh
docker compose config --quiet
docker compose build migrate
docker compose up -d --no-build --wait
curl -fsS http://localhost:8080/health/ready
make check
make test
python3 student-tests/auth_and_chat.py
python3 student-tests/idempotency.py
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
docker compose ps --all api-a api-b
docker compose start api-a api-b
```
Миграции запускает сервис `migrate`. Повторить вручную можно командой `docker compose run --rm migrate`. После отказа скрипт оставляет целевую реплику остановленной. `docker compose start api-a api-b` возвращает стенд в исходное состояние. Для ручного выбора используйте `TARGET_INSTANCE_ID=api-b ./scripts/stop-one.sh` при готовой `api-a`.
`docker compose down` сохраняет данные. `docker compose down -v` намеренно удаляет учебный том. При изменении `APP_BIND_PORT` передайте соответствующий `BASE_URL` проверкам. Swagger UI доступен через HAProxy по `/docs`.
## Архитектура и решения
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
Сохранены PostgreSQL, Bearer-сессии, миграция `001_core.sql`, таблицы и API из лабораторной 2. Между клиентом и API добавлен HAProxy. `api-a` и `api-b` запускают один образ и читают одну базу, в которой хранятся и сессии. HAProxy распределяет запросы round-robin без привязки сессии к реплике.
| Роль | Сервис | Готовность | Данные и доступ |
| --- | --- | --- | --- |
| PostgreSQL | `postgres` | `pg_isready` по TCP | Именованный том `postgres_data`, внутренняя сеть |
| Миграции | `migrate` | Успешное завершение SQL | Один запуск перед обеими репликами |
| API | `api-a`, `api-b` | `/health/ready` проверяет PostgreSQL и миграцию | Внутренний порт 8080, свой `X-Instance-Id` |
| Балансировщик | `lb` | HTTP-проверки backend `/health/ready` | Единственный порт хоста `127.0.0.1:8080` |
`.env` содержит `POSTGRES_USER`, `POSTGRES_DB`, `POSTGRES_PASSWORD`, длительность сессии и настройки локального порта и логов. В Compose каждому API присвоен собственный `INSTANCE_ID`, соответствующий имени сервиса. HAProxy использует DNS Compose для обновления адресов и проверяет готовность раз в секунду, исключая реплику после двух неудач. Таймаут подключения — 1 секунда. При SIGTERM API закрывает HTTP-сервер, дожидается активных запросов и освобождает пул соединений.
Миграция `002_idempotency.sql` добавляет общий реестр ключей POST сообщений. Область ключа — пользователь и чат для этого метода. PostgreSQL сериализует конкурентное занятие одинакового ключа по составному первичному ключу. Запись сообщения и привязка результата к ключу фиксируются одной транзакцией. Повтор с тем же телом в течение 24 часов возвращает тот же объект с 201. Другое тело получает 409. Если транзакция прервётся, резервирование ключа откатывается.
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
16.11.2026 проверены локальные процессы Node.js 22.16.0, PostgreSQL 15.18 и HAProxy 3.0.11. Маршрут HTTP шёл через реальный HAProxy. В локальной проверке имена backend заменены loopback-адресами, а hooks управляли PID. Compose-манифест проверен отдельно через `config --quiet` (Compose v2.36.2).
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
| Критерий уровня 3 | Команда или сценарий | Результат |
| --- | --- | --- |
| Один вход и две реплики с общей сессией | `make test-failover` | До отказа клиент с одним токеном увидел два разных `X-Instance-Id` |
| Контракт с обязательным ключом | `make test` | Пройдены smoke, replay и конфликт изменённого тела |
| Конкурентный повтор | `python3 student-tests/idempotency.py` | 16 запросов через две реплики вернули один и тот же объект. В истории осталась одна запись |
| Перезапуск всей схемы | `make test-persistence` с локальным hook | HAProxy, PostgreSQL и обе реплики сменили PID. Сохранились токен и подтверждённое сообщение |
| Отказ API-реплики | `make test-failover` с локальным hook | Остановлена `api-a`. За 15 секунд теста подтверждено 125 записей, 8 попыток завершились ошибкой. Первый успешный POST после hook зафиксирован через 0,231 сек. Дублей и потери подтверждений не обнаружено |
| Контракт и конфигурация | `make check`, `docker compose config --quiet`, проверка HAProxy | Команды завершились успешно |
В отдельном прогоне была остановлена `api-b`. После остановки `api-a` подтвердила запись и чтение обеих записей за 1,224 секунды.
Вывод команд и PID — [local-verification.txt](evidence/local-verification.txt) и [second-replica.txt](evidence/second-replica.txt).
## Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
## Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
При остановке одного API база, HAProxy и второй API продолжают работать. Возможны ошибки нескольких запросов во время пересчёта готовности. Клиент повторяет неопределённый POST сообщения с прежним ключом. В стенде один PostgreSQL и один HAProxy, поэтому их отказ затрагивает весь сервис. Метрика одного прогона описывает локальное переключение между процессами на одном хосте. Истёкшие ключи можно использовать заново, старые записи остаются в таблице до повторного использования или обслуживания.
+70
View File
@@ -0,0 +1,70 @@
x-app: &app
image: mtusi-messenger:lab3
pull_policy: never
environment: &app-env
APP_HOST: 0.0.0.0
APP_PORT: 8080
APP_ENV: ${APP_ENV:-lab}
LOG_LEVEL: ${LOG_LEVEL:-info}
DB_HOST: postgres
SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600}
POSTGRES_USER: ${POSTGRES_USER:-messenger}
POSTGRES_DB: ${POSTGRES_DB:-messenger}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Run scripts/init-env.sh first}
x-api: &api
<<: *app
stop_grace_period: 10s
depends_on:
migrate:
condition: service_completed_successfully
services:
postgres:
image: postgres:15.18-bookworm
environment:
POSTGRES_USER: ${POSTGRES_USER:-messenger}
POSTGRES_DB: ${POSTGRES_DB:-messenger}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Run scripts/init-env.sh first}
volumes:
- postgres_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U \"$$POSTGRES_USER\" -d \"$$POSTGRES_DB\""]
interval: 2s
timeout: 2s
retries: 20
migrate:
<<: *app
build: .
command: ["node", "dist/migrate.js"]
healthcheck:
disable: true
depends_on:
postgres:
condition: service_healthy
api-a:
<<: *api
environment:
<<: *app-env
INSTANCE_ID: api-a
api-b:
<<: *api
environment:
<<: *app-env
INSTANCE_ID: api-b
lb:
image: haproxy:3.0.11-alpine
volumes:
- ./infra/haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro
ports:
- "127.0.0.1:${APP_BIND_PORT:-8080}:8080"
depends_on:
- api-a
- api-b
volumes:
postgres_data:
+87
View File
@@ -0,0 +1,87 @@
$ npm run build
npm warn Unknown env config "http-proxy". This will stop working in the next major version of npm.
> mtusi-messenger-lab3@1.0.0 build
> npm run generate && tsc -p tsconfig.json
npm warn Unknown env config "http-proxy". This will stop working in the next major version of npm.
> mtusi-messenger-lab3@1.0.0 generate
> tsoa routes
$ docker-compose config --quiet
$ make check
python3 scripts/check_contract.py
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.
The files belonging to this database system will be owned by user "agent".
This user must also own the server process.
The database cluster will be initialized with locale "C.UTF-8".
The default database encoding has accordingly been set to "UTF8".
The default text search configuration will be set to "english".
Data page checksums are disabled.
creating directory /workspace/scratch/503693051415/runtime/state3/database ... ok
creating subdirectories ... ok
selecting dynamic shared memory implementation ... posix
selecting default max_connections ... 100
selecting default shared_buffers ... 128MB
selecting default time zone ... Europe/Moscow
creating configuration files ... ok
running bootstrap script ... ok
performing post-bootstrap initialization ... ok
syncing data to disk ... ok
Success. You can now start the database server using:
/workspace/scratch/503693051415/runtime/pg/usr/lib/postgresql/15/bin/pg_ctl -D /workspace/scratch/503693051415/runtime/state3/database -l logfile start
waiting for server to start.... done
server started
PostgreSQL started pid=88
Applied 001_core.sql
Applied 002_idempotency.sql
Migrations up to date
api-a started pid=112 on TCP 18081
api-b started pid=113 on TCP 18082
[NOTICE] (114) : config : [infra/haproxy.cfg:31] : 'server api/api-a' : could not resolve address 'api-a', disabling server.
[NOTICE] (114) : config : [infra/haproxy.cfg:32] : 'server api/api-b' : could not resolve address 'api-b', disabling server.
lb started pid=129
$ make test
python3 tests/smoke.py --base-url "http://localhost:8080"
PASS: lab3 public API scenario; infrastructure and grading evidence remain separate.
$ python3 student-tests/auth_and_chat.py
PASS: UTF-8 password with colon, strict JSON, and atomic chat creation
$ python3 student-tests/idempotency.py
PASS: 16 concurrent requests on 2 replicas yielded one message
$ make test-persistence ACTION_SCRIPT=<local process restart>
python3 tests/resilience.py --mode persistence --action-script "/workspace/scratch/503693051415/runtime/replicated-local.sh" --base-url "http://localhost: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.
lb stopped pid=129
api-a stopped pid=112
api-b stopped pid=113
PostgreSQL stopping pid=88
waiting for server to shut down.... done
server stopped
waiting for server to start.... done
server started
PostgreSQL started pid=239
Migrations up to date
api-a started pid=261 on TCP 18081
api-b started pid=262 on TCP 18082
[NOTICE] (263) : config : [infra/haproxy.cfg:31] : 'server api/api-a' : could not resolve address 'api-a', disabling server.
[NOTICE] (263) : config : [infra/haproxy.cfg:32] : 'server api/api-b' : could not resolve address 'api-b', disabling server.
lb started pid=278
$ make test-failover ACTION_SCRIPT=<local targeted process stop>
python3 tests/resilience.py --mode failover --action-script "/workspace/scratch/503693051415/runtime/stop-replica-local.sh" --base-url "http://localhost:8080"
Executing explicit failover hook; hook output suppressed to avoid leaking secrets.
{"observed_instances_before": 2, "successful_writes": 125, "failed_attempts": 8, "first_recovery_seconds": 0.231}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
api-a stopped pid=261
lb stopped pid=278
api-b stopped pid=262
PostgreSQL stopping pid=239
waiting for server to shut down.... done
server stopped
+16
View File
@@ -0,0 +1,16 @@
waiting for server to start.... done
server started
PostgreSQL started pid=14
Migrations up to date
api-a started pid=36 on TCP 18081
api-b started pid=37 on TCP 18082
[NOTICE] (38) : config : [infra/haproxy.cfg:31] : 'server api/api-a' : could not resolve address 'api-a', disabling server.
[NOTICE] (38) : config : [infra/haproxy.cfg:32] : 'server api/api-b' : could not resolve address 'api-b', disabling server.
lb started pid=53
PASS: api-b stopped; api-a served writes and reads in 1.224s
api-b stopped pid=37
lb stopped pid=53
api-a stopped pid=36
PostgreSQL stopping pid=14
waiting for server to shut down.... done
server stopped
+32
View File
@@ -0,0 +1,32 @@
global
log stdout format raw local0
defaults
mode http
log global
option dontlog-normal
timeout http-request 10s
timeout connect 1s
timeout client 30s
timeout server 30s
timeout check 2s
retries 0
resolvers docker
nameserver dns 127.0.0.11:53
resolve_retries 3
timeout resolve 1s
timeout retry 1s
hold valid 2s
frontend messenger
bind :8080
default_backend api
backend api
balance roundrobin
option httpchk GET /health/ready
http-check expect status 200
default-server check inter 1s fall 2 rise 1
server api-a api-a:8080 resolvers docker init-addr last,libc,none
server api-b api-b:8080 resolvers docker init-addr last,libc,none
+39
View File
@@ -0,0 +1,39 @@
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 clock_timestamp()
);
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 clock_timestamp()
);
CREATE TABLE chat_members (
chat_id uuid NOT NULL REFERENCES chats (id),
user_id uuid NOT NULL REFERENCES users (id),
position integer NOT NULL CHECK (position >= 1),
PRIMARY KEY (chat_id, user_id),
UNIQUE (chat_id, position)
);
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 REFERENCES chats (id),
sender_id uuid NOT NULL,
text text NOT NULL CHECK (char_length(text) <= 4000),
created_at timestamptz(3) NOT NULL DEFAULT clock_timestamp(),
FOREIGN KEY (chat_id, sender_id) REFERENCES chat_members (chat_id, user_id)
);
CREATE INDEX messages_history_idx ON messages (chat_id, created_at, id);
CREATE TABLE sessions (
token_hash text PRIMARY KEY,
user_id uuid NOT NULL REFERENCES users (id),
expires_at timestamptz(3) NOT NULL
);
CREATE INDEX sessions_expiry_idx ON sessions (expires_at);
+10
View File
@@ -0,0 +1,10 @@
CREATE TABLE message_idempotency (
user_id uuid NOT NULL,
chat_id uuid NOT NULL,
idempotency_key text NOT NULL CHECK (idempotency_key ~ '^[A-Za-z0-9._:-]{1,128}$'),
request_hash text NOT NULL,
message_id uuid REFERENCES messages (id),
expires_at timestamptz(3) NOT NULL,
PRIMARY KEY (user_id, chat_id, idempotency_key),
FOREIGN KEY (chat_id, user_id) REFERENCES chat_members (chat_id, user_id)
);
+3165
View File
File diff suppressed because it is too large Load Diff
+36
View File
@@ -0,0 +1,36 @@
{
"name": "mtusi-messenger-lab3",
"version": "1.0.0",
"private": true,
"description": "MTUSI lab3 replicated messenger API",
"main": "dist/server.js",
"scripts": {
"dev": "npm run generate && tsx watch src/server.ts",
"generate": "tsoa routes",
"build": "npm run generate && tsc -p tsconfig.json",
"start": "node dist/server.js",
"typecheck": "npm run generate && tsc -p tsconfig.json --noEmit",
"migrate": "node dist/migrate.js"
},
"dependencies": {
"express": "4.21.2",
"pg": "8.16.3",
"pino": "9.9.5",
"swagger-ui-express": "5.0.1",
"tsoa": "6.6.0",
"uuid": "11.1.0",
"zod": "3.24.2"
},
"devDependencies": {
"@types/express": "4.17.25",
"@types/express-serve-static-core": "^5.1.3",
"@types/node": "^22.18.6",
"@types/pg": "8.15.5",
"@types/swagger-ui-express": "4.1.8",
"tsx": "4.20.6",
"typescript": "5.8.3"
},
"engines": {
"node": ">=22 <23"
}
}
+14
View File
@@ -0,0 +1,14 @@
#!/bin/sh
set -eu
cd "$(dirname "$0")/.."
if [ -e .env ]; then
printf '%s\n' 'Using existing .env'
exit 0
fi
umask 077
set -C
password=$(python3 -c 'import secrets; print(secrets.token_hex(24))')
sed "s/^POSTGRES_PASSWORD=$/POSTGRES_PASSWORD=$password/" .env.example > .env
printf '%s\n' 'Created .env for the local stand'
Executable → Regular
View File
+8
View File
@@ -0,0 +1,8 @@
#!/bin/sh
set -eu
cd "$(dirname "$0")/.."
docker compose ps
docker compose down
docker compose up -d --no-build --wait --wait-timeout 55
docker compose ps
Executable → Regular
View File
+11
View File
@@ -0,0 +1,11 @@
#!/bin/sh
set -eu
cd "$(dirname "$0")/.."
case "${TARGET_INSTANCE_ID:-}" in
api-a|api-b) service=$TARGET_INSTANCE_ID ;;
*) printf '%s\n' 'TARGET_INSTANCE_ID must be api-a or api-b' >&2; exit 2 ;;
esac
docker compose stop -t 5 "$service"
docker compose ps --all "$service"
+45
View File
@@ -0,0 +1,45 @@
import express, { type Express } from 'express';
import swaggerUi from 'swagger-ui-express';
import { join } from 'node:path';
import { readFileSync } from 'node:fs';
import { RegisterRoutes } from './generated/routes';
import { requireAuthenticatedUser } from './middleware/auth';
import { requireJsonContentType } from './middleware/content-type';
import { errorHandler } from './middleware/error-handler';
import { notFoundHandler } from './middleware/not-found';
import { requestContext } from './middleware/request-context';
import { requestLogger } from './middleware/request-logger';
const contractPath = join(__dirname, '..', 'contracts', 'openapi.json');
const swaggerDocument = JSON.parse(readFileSync(contractPath, 'utf8'));
const parseJson = express.json({ limit: '64kb', strict: true });
export function createApp(): Express {
const app = express();
app.disable('x-powered-by');
app.set('query parser', 'simple');
app.use(requestContext);
app.use(requestLogger);
app.use('/api/v1/users/me', requireAuthenticatedUser);
app.use('/api/v1/chats', requireAuthenticatedUser);
app.use('/api/v1/auth/sessions/current', requireAuthenticatedUser);
app.use(requireJsonContentType);
app.use((req, res, next) => {
if (/^\/api\/v1\/auth\/sessions\/?$/i.test(req.path)) {
next();
return;
}
parseJson(req, res, next);
});
app.get('/docs/openapi.json', (_req, res) => res.json(swaggerDocument));
app.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
RegisterRoutes(app);
app.use(notFoundHandler);
app.use(errorHandler);
return app;
}
+19
View File
@@ -0,0 +1,19 @@
import { z } from 'zod';
const envSchema = z.object({
APP_HOST: z.string().min(1).default('0.0.0.0'),
APP_PORT: z.coerce.number().int().min(1).max(65535).default(8080),
APP_ENV: z.string().min(1).default('lab'),
DB_HOST: z.string().min(1).default('127.0.0.1'),
DB_PORT: z.coerce.number().int().min(1).max(65535).default(5432),
POSTGRES_USER: z.string().min(1).default('messenger'),
POSTGRES_DB: z.string().min(1).default('messenger'),
POSTGRES_PASSWORD: z.string().min(1),
SESSION_TTL_SECONDS: z.coerce.number().int().min(1).max(31_536_000).default(3600),
INSTANCE_ID: z.string().regex(/^[A-Za-z0-9._-]{1,96}$/).optional(),
LOG_LEVEL: z
.enum(['fatal', 'error', 'warn', 'info', 'debug', 'trace', 'silent'])
.default('info'),
});
export const env = envSchema.parse(process.env);
+8
View File
@@ -0,0 +1,8 @@
import pino from 'pino';
import { env } from './env';
export const logger = pino({
level: env.LOG_LEVEL,
base: undefined,
timestamp: pino.stdTimeFunctions.isoTime,
});
+26
View File
@@ -0,0 +1,26 @@
import type { Request as ExpressRequest } from 'express';
import { Controller, Delete, Post, Request, Route, SuccessResponse, Tags } from 'tsoa';
import type { Session } from '../domain/models';
import { invalidRequest } from '../errors/api-error';
import type { SessionRequest } from '../middleware/auth';
import { createSession, revokeSession } from '../services/auth.service';
@Route('api/v1/auth/sessions')
@Tags('Auth')
export class AuthController extends Controller {
@Post()
@SuccessResponse(201, 'Created')
public async login(@Request() req: ExpressRequest): Promise<Session> {
if (req.get('Transfer-Encoding') || Number(req.get('Content-Length') ?? '0') !== 0) {
throw invalidRequest('Вход принимает только заголовок Authorization');
}
this.setStatus(201);
return createSession(req.get('Authorization'));
}
@Delete('current')
@SuccessResponse(204, 'No content')
public async logout(@Request() req: SessionRequest): Promise<void> {
await revokeSession(req.session);
}
}
+25
View File
@@ -0,0 +1,25 @@
import { Controller, Get, Path, Post, Request, Route, SuccessResponse, Tags } from 'tsoa';
import type { Chat, Page } from '../domain/models';
import type { SessionRequest } from '../middleware/auth';
import { createChat, listChats, requireAccessibleChat } from '../services/chat.service';
@Route('api/v1/chats')
@Tags('Chats')
export class ChatsController extends Controller {
@Post()
@SuccessResponse(201, 'Created')
public async createChat(@Request() req: SessionRequest): Promise<Chat> {
this.setStatus(201);
return createChat(req.session.user, req.body);
}
@Get()
public async listChats(@Request() req: SessionRequest): Promise<Page<Chat>> {
return listChats(req.session.user, req.query.limit, req.query.cursor);
}
@Get('{chat_id}')
public async getChat(@Path() chat_id: string, @Request() req: SessionRequest): Promise<Chat> {
return requireAccessibleChat(req.session.user, chat_id);
}
}
+26
View File
@@ -0,0 +1,26 @@
import { Controller, Get, Route, Tags } from 'tsoa';
import type { Health } from '../domain/models';
import { unavailable } from '../errors/api-error';
import { db } from '../repositories/postgres';
@Route('health')
@Tags('Health')
export class HealthController extends Controller {
@Get('live')
public liveness(): Health {
return { status: 'ok' };
}
@Get('ready')
public async readiness(): Promise<Health> {
try {
const { rows } = await db.query(
"SELECT 1 FROM schema_migrations WHERE version = '002_idempotency.sql'",
);
if (!rows.length) throw unavailable();
return { status: 'ok' };
} catch {
throw unavailable();
}
}
}
+20
View File
@@ -0,0 +1,20 @@
import { Controller, Get, Path, Post, Request, Route, SuccessResponse, Tags } from 'tsoa';
import type { Message, Page } from '../domain/models';
import type { SessionRequest } from '../middleware/auth';
import { createMessage, listMessages } from '../services/message.service';
@Route('api/v1/chats/{chat_id}/messages')
@Tags('Messages')
export class MessagesController extends Controller {
@Post()
@SuccessResponse(201, 'Created')
public async createMessage(@Path() chat_id: string, @Request() req: SessionRequest): Promise<Message> {
this.setStatus(201);
return createMessage(req.session.user, chat_id, req.body, req.get('Idempotency-Key'));
}
@Get()
public async listMessages(@Path() chat_id: string, @Request() req: SessionRequest): Promise<Page<Message>> {
return listMessages(req.session.user, chat_id, req.query.limit, req.query.cursor);
}
}
+21
View File
@@ -0,0 +1,21 @@
import type { Request as ExpressRequest } from 'express';
import { Controller, Get, Post, Request, Route, SuccessResponse, Tags } from 'tsoa';
import type { User } from '../domain/models';
import type { SessionRequest } from '../middleware/auth';
import { createUser } from '../services/user.service';
@Route('api/v1/users')
@Tags('Users')
export class UsersController extends Controller {
@Post()
@SuccessResponse(201, 'Created')
public async registerUser(@Request() req: ExpressRequest): Promise<User> {
this.setStatus(201);
return createUser(req.body);
}
@Get('me')
public currentUser(@Request() req: SessionRequest): User {
return req.session.user;
}
}
+71
View File
@@ -0,0 +1,71 @@
export interface User {
id: string;
username: string;
display_name: string;
created_at: string;
}
export interface CreateUserBody {
password: string;
username: string;
display_name: string;
}
export interface Session {
token: string;
token_type: 'Bearer';
expires_at: string;
user: User;
}
export interface Chat {
id: string;
title: string;
member_ids: string[];
created_at: string;
}
export interface CreateChatBody {
title: string;
member_ids: string[];
}
export interface Message {
id: string;
chat_id: string;
sender_id: string;
text: string;
created_at: string;
}
export interface CreateMessageBody {
text: string;
}
export interface Page<T> {
items: T[];
next_cursor: string | null;
}
export interface Health {
status: 'ok';
}
export type ErrorCode =
| 'invalid_request'
| 'unauthorized'
| 'not_found'
| 'conflict'
| 'payload_too_large'
| 'unsupported_media_type'
| 'rate_limited'
| 'unavailable'
| 'internal_error';
export interface ErrorResponse {
error: {
code: ErrorCode;
message: string;
request_id: string;
};
}
+36
View File
@@ -0,0 +1,36 @@
import type { ErrorCode } from '../domain/models';
export class ApiError extends Error {
public constructor(
public readonly status: number,
public readonly code: ErrorCode,
message: string,
public readonly challenge?: string,
) {
super(message);
this.name = 'ApiError';
}
}
export const invalidRequest = (message = 'Некорректный запрос') =>
new ApiError(400, 'invalid_request', message);
export const unauthorized = (scheme: 'Basic' | 'Bearer') =>
new ApiError(401, 'unauthorized', 'Требуются действительные учётные данные',
scheme === 'Basic' ? 'Basic realm="messenger", charset="UTF-8"' : 'Bearer realm="messenger"');
export const notFound = () =>
new ApiError(404, 'not_found', 'Объект не найден');
export const conflict = (message = 'Конфликт') =>
new ApiError(409, 'conflict', message);
export const unsupportedMediaType = () =>
new ApiError(
415,
'unsupported_media_type',
'Неподдерживаемый Content-Type или кодировка',
);
export const unavailable = (message = 'Сервис временно недоступен') =>
new ApiError(503, 'unavailable', message);
+11
View File
@@ -0,0 +1,11 @@
import type { Request, RequestHandler } from 'express';
import { requireSession, type AuthenticatedSession } from '../services/auth.service';
export type SessionRequest = Request & { session: AuthenticatedSession };
export const requireAuthenticatedUser: RequestHandler = (req, _res, next) => {
void requireSession(req.get('Authorization')).then((session) => {
(req as SessionRequest).session = session;
next();
}, next);
};
+25
View File
@@ -0,0 +1,25 @@
import type { RequestHandler } from 'express';
import { unsupportedMediaType } from '../errors/api-error';
const jsonPostRoutes = [
/^\/api\/v1\/users\/?$/,
/^\/api\/v1\/chats\/?$/,
/^\/api\/v1\/chats\/[^/]+\/messages\/?$/,
];
export const requireJsonContentType: RequestHandler = (req, _res, next) => {
if (
req.method !== 'POST' ||
!jsonPostRoutes.some((pattern) => pattern.test(req.path))
) {
next();
return;
}
if (req.get('Content-Type')?.split(';')[0]?.trim().toLowerCase() !== 'application/json') {
next(unsupportedMediaType());
return;
}
next();
};
+82
View File
@@ -0,0 +1,82 @@
import type { ErrorRequestHandler } from 'express';
import { ValidateError } from 'tsoa';
import { logger } from '../config/logger';
import type { ErrorResponse } from '../domain/models';
import {
ApiError,
invalidRequest,
unsupportedMediaType,
unavailable,
} from '../errors/api-error';
interface BodyParserError extends Error {
status?: number;
type?: string;
code?: string;
}
export const errorHandler: ErrorRequestHandler = (
error: unknown,
_req,
res,
next,
): void => {
if (res.headersSent) {
next(error);
return;
}
const requestId = String(res.locals.requestId ?? 'unknown');
let apiError: ApiError;
if (error instanceof ApiError) {
apiError = error;
} else if (error instanceof ValidateError || error instanceof URIError) {
apiError = invalidRequest('Некорректные параметры запроса');
} else if (
error instanceof SyntaxError &&
((error as BodyParserError).status === 400 ||
(error as BodyParserError).type === 'entity.parse.failed')
) {
apiError = invalidRequest('Некорректный JSON');
} else if ((error as BodyParserError | undefined)?.status === 415) {
apiError = unsupportedMediaType();
} else if (
(error as BodyParserError | undefined)?.type === 'entity.too.large'
) {
apiError = new ApiError(
413,
'payload_too_large',
'Тело запроса слишком большое',
);
} else if ((error as BodyParserError | undefined)?.status === 400) {
apiError = invalidRequest();
} else if (/^(08...|57P0[123]|57014|ECONNREFUSED|ECONNRESET|ETIMEDOUT|EAI_AGAIN|ENOTFOUND)$/.test(
(error as BodyParserError | undefined)?.code ?? '',
) || (error instanceof Error && /^Connection terminated|^timeout exceeded when trying to connect/.test(error.message))) {
apiError = unavailable();
} else {
logger.error(
{
request_id: requestId,
error_name:
error instanceof Error ? error.name : 'UnknownError',
},
'unhandled request error',
);
apiError = new ApiError(
500,
'internal_error',
'Внутренняя ошибка сервера',
);
}
if (apiError.challenge) res.setHeader('WWW-Authenticate', apiError.challenge);
const body: ErrorResponse = {
error: {
code: apiError.code,
message: apiError.message,
request_id: requestId,
},
};
res.status(apiError.status).json(body);
};
+10
View File
@@ -0,0 +1,10 @@
import type { NextFunction, Request, Response } from 'express';
import { notFound } from '../errors/api-error';
export function notFoundHandler(
_req: Request,
_res: Response,
next: NextFunction,
): void {
next(notFound());
}
+17
View File
@@ -0,0 +1,17 @@
import type { NextFunction, Request, Response } from 'express';
import { v4 as uuidv4 } from 'uuid';
import { env } from '../config/env';
const instanceId = env.INSTANCE_ID ?? uuidv4();
export function requestContext(
_req: Request,
res: Response,
next: NextFunction,
): void {
const requestId = uuidv4();
res.locals.requestId = requestId;
res.setHeader('X-Request-Id', requestId);
res.setHeader('X-Instance-Id', instanceId);
next();
}
+24
View File
@@ -0,0 +1,24 @@
import type { NextFunction, Request, Response } from 'express';
import { logger } from '../config/logger';
export function requestLogger(
req: Request,
res: Response,
next: NextFunction,
): void {
const started = process.hrtime.bigint();
res.once('finish', () => {
const elapsedMs = Number(process.hrtime.bigint() - started) / 1_000_000;
logger.info(
{
request_id: res.locals.requestId,
method: req.method,
path: req.path,
status: res.statusCode,
duration_ms: Math.round(elapsedMs * 100) / 100,
},
'request completed',
);
});
next();
}
+43
View File
@@ -0,0 +1,43 @@
import { createHash } from 'node:crypto';
import { readdir, readFile } from 'node:fs/promises';
import { join } from 'node:path';
import { db, transaction } from './repositories/postgres';
async function migrate(): Promise<void> {
const directory = join(__dirname, '..', 'migrations');
const files = (await readdir(directory)).filter((name) => /^\d{3}_.+\.sql$/.test(name)).sort();
if (files.length === 0) throw new Error('No migrations found');
await transaction(async (client) => {
await client.query('SELECT pg_advisory_xact_lock(20261116, 1)');
await client.query(`
CREATE TABLE IF NOT EXISTS schema_migrations (
version text PRIMARY KEY,
checksum text NOT NULL,
applied_at timestamptz NOT NULL DEFAULT now()
)
`);
for (const version of files) {
const sql = await readFile(join(directory, version), 'utf8');
const checksum = createHash('sha256').update(sql).digest('hex');
const previous = await client.query<{ checksum: string }>(
'SELECT checksum FROM schema_migrations WHERE version = $1', [version],
);
if (previous.rows[0]) {
if (previous.rows[0].checksum !== checksum) throw new Error(`Migration changed: ${version}`);
continue;
}
await client.query(sql);
await client.query(
'INSERT INTO schema_migrations (version, checksum) VALUES ($1, $2)', [version, checksum],
);
console.log(`Applied ${version}`);
}
});
console.log('Migrations up to date');
}
migrate().catch((error: unknown) => {
console.error(error instanceof Error ? error.message : 'Migration failed');
process.exitCode = 1;
}).finally(() => db.end());
+40
View File
@@ -0,0 +1,40 @@
import { Pool, types, type PoolClient } from 'pg';
import { env } from '../config/env';
import { logger } from '../config/logger';
const parseTimestamp = types.getTypeParser(types.builtins.TIMESTAMPTZ);
types.setTypeParser(types.builtins.TIMESTAMPTZ, (value) => parseTimestamp(value).toISOString());
export const db = new Pool({
host: env.DB_HOST,
port: env.DB_PORT,
user: env.POSTGRES_USER,
password: env.POSTGRES_PASSWORD,
database: env.POSTGRES_DB,
max: 8,
connectionTimeoutMillis: 2_000,
statement_timeout: 4_000,
idle_in_transaction_session_timeout: 5_000,
});
db.on('error', () => logger.warn('idle PostgreSQL connection lost'));
export async function transaction<T>(work: (client: PoolClient) => Promise<T>): Promise<T> {
const client = await db.connect();
let discardConnection = false;
try {
await client.query('BEGIN');
const result = await work(client);
await client.query('COMMIT');
return result;
} catch (error) {
try {
await client.query('ROLLBACK');
} catch {
discardConnection = true;
}
throw error;
} finally {
client.release(discardConnection);
}
}
+42
View File
@@ -0,0 +1,42 @@
import type { Server } from 'node:http';
import { createApp } from './app';
import { env } from './config/env';
import { logger } from './config/logger';
import { db } from './repositories/postgres';
const app = createApp();
const server: Server = app.listen(env.APP_PORT, env.APP_HOST, () => {
logger.info(
{ host: env.APP_HOST, port: env.APP_PORT, environment: env.APP_ENV },
'server started',
);
});
let shuttingDown = false;
function shutdown(signal: NodeJS.Signals): void {
if (shuttingDown) return;
shuttingDown = true;
logger.info({ signal }, 'graceful shutdown started');
const forceTimer = setTimeout(() => {
logger.error('graceful shutdown timed out');
server.closeAllConnections();
process.exit(1);
}, 9_000);
forceTimer.unref();
server.close((error) => {
void db.end().finally(() => {
clearTimeout(forceTimer);
if (error) {
logger.error({ error_name: error.name }, 'server close failed');
process.exitCode = 1;
} else {
logger.info('server stopped');
}
}).catch(() => { process.exitCode = 1; });
});
}
process.on('SIGTERM', () => shutdown('SIGTERM'));
process.on('SIGINT', () => shutdown('SIGINT'));
+86
View File
@@ -0,0 +1,86 @@
import { createHash, randomBytes } from 'node:crypto';
import type { Session, User } from '../domain/models';
import { unauthorized } from '../errors/api-error';
import { env } from '../config/env';
import { db } from '../repositories/postgres';
import { passwordSchema, usernameSchema } from '../validation/schemas';
import { verifyPassword } from './password.service';
interface Account extends User {
password_hash: string;
}
export interface AuthenticatedSession {
user: User;
tokenHash: string;
}
const hashToken = (token: string): string =>
createHash('sha256').update(token, 'ascii').digest('hex');
function basicCredentials(authorization: string | undefined): { username: string; password: string } {
const encoded = /^Basic +([A-Za-z0-9+/]+={0,2})$/i.exec(authorization ?? '')?.[1];
if (!encoded || encoded.length > 800) throw unauthorized('Basic');
const bytes = Buffer.from(encoded, 'base64');
if (bytes.toString('base64') !== encoded) throw unauthorized('Basic');
let value: string;
try {
value = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
} catch {
throw unauthorized('Basic');
}
const separator = value.indexOf(':');
const username = value.slice(0, separator);
const password = value.slice(separator + 1);
if (separator < 0 || !usernameSchema.safeParse(username).success || !passwordSchema.safeParse(password).success) {
throw unauthorized('Basic');
}
return { username, password };
}
export async function createSession(authorization: string | undefined): Promise<Session> {
const { username, password } = basicCredentials(authorization);
const result = await db.query<Account>(
'SELECT id, username, display_name, created_at, password_hash FROM users WHERE username = $1',
[username],
);
const account = result.rows[0];
if (!(await verifyPassword(password, account?.password_hash)) || !account) throw unauthorized('Basic');
const token = randomBytes(32).toString('base64url');
const { rows } = await db.query<{ expires_at: string }>(
`INSERT INTO sessions (token_hash, user_id, expires_at)
VALUES ($1, $2, clock_timestamp() + $3::int * interval '1 second') RETURNING expires_at`,
[hashToken(token), account.id, env.SESSION_TTL_SECONDS],
);
const session = rows[0];
if (!session) throw new Error('Session not returned');
const { id, display_name, created_at } = account;
return { token, token_type: 'Bearer', expires_at: session.expires_at,
user: { id, username, display_name, created_at } };
}
export async function requireSession(authorization: string | undefined): Promise<AuthenticatedSession> {
const token = /^Bearer +([A-Za-z0-9_-]{43})$/i.exec(authorization ?? '')?.[1];
if (!token) throw unauthorized('Bearer');
const tokenHash = hashToken(token);
const { rows } = await db.query<User>(
`SELECT u.id, u.username, u.display_name, u.created_at
FROM sessions s JOIN users u ON u.id = s.user_id
WHERE s.token_hash = $1 AND s.expires_at > clock_timestamp()`,
[tokenHash],
);
const user = rows[0];
if (!user) throw unauthorized('Bearer');
return { user, tokenHash };
}
export async function revokeSession(session: AuthenticatedSession): Promise<void> {
const result = await db.query(
'DELETE FROM sessions WHERE token_hash = $1 AND expires_at > clock_timestamp()',
[session.tokenHash],
);
if (result.rowCount !== 1) throw unauthorized('Bearer');
}
+59
View File
@@ -0,0 +1,59 @@
import type { Chat, Page, User } from '../domain/models';
import { invalidRequest, notFound } from '../errors/api-error';
import { db, transaction } from '../repositories/postgres';
import { parseWith } from '../validation/parse';
import { createChatSchema, uuidSchema } from '../validation/schemas';
import { makePage, parsePage } from './cursor.service';
const chatFields = `
c.id, c.title, c.created_at,
ARRAY(SELECT user_id FROM chat_members
WHERE chat_id = c.id ORDER BY position) AS member_ids
`;
export async function createChat(actor: User, input: unknown): Promise<Chat> {
const { title, member_ids } = parseWith(createChatSchema, input);
if (!member_ids.includes(actor.id)) {
throw invalidRequest('Текущий пользователь должен входить в member_ids');
}
return transaction(async (client) => {
const ids = await client.query('SELECT id FROM users WHERE id = ANY($1::uuid[])', [member_ids]);
if (ids.rowCount !== member_ids.length) {
throw invalidRequest('member_ids содержит неизвестного пользователя');
}
const { rows } = await client.query<Omit<Chat, 'member_ids'>>(
'INSERT INTO chats (title) VALUES ($1) RETURNING id, title, created_at', [title],
);
const chat = rows[0];
if (!chat) throw new Error('Chat not returned');
await client.query(
`INSERT INTO chat_members (chat_id, user_id, position)
SELECT $1, id, position FROM unnest($2::uuid[]) WITH ORDINALITY AS m(id, position)`,
[chat.id, member_ids],
);
return { ...chat, member_ids };
});
}
export async function requireAccessibleChat(actor: User, chatId: string): Promise<Chat> {
const id = parseWith(uuidSchema, chatId);
const { rows } = await db.query<Chat>(
`SELECT ${chatFields} FROM chats c JOIN chat_members m ON m.chat_id = c.id
WHERE c.id = $1 AND m.user_id = $2`,
[id, actor.id],
);
if (!rows[0]) throw notFound();
return rows[0];
}
export async function listChats(actor: User, limit: unknown, cursor: unknown): Promise<Page<Chat>> {
const scope = { kind: 'chats', resource: actor.id } as const;
const page = parsePage(limit, cursor, scope);
const { rows } = await db.query<Chat>(
`SELECT ${chatFields} FROM chats c JOIN chat_members m ON m.chat_id = c.id
WHERE m.user_id = $1 AND ($2::timestamptz IS NULL OR (c.created_at, c.id) > ($2, $3))
ORDER BY c.created_at, c.id LIMIT $4`,
[actor.id, page.after?.created_at, page.after?.id, page.limit + 1],
);
return makePage(rows, page.limit, scope);
}
+45
View File
@@ -0,0 +1,45 @@
import type { Page } from '../domain/models';
import { invalidRequest } from '../errors/api-error';
import { parseWith } from '../validation/parse';
import { cursorPayloadSchema, paginationSchema, type CursorPayload } from '../validation/schemas';
type CursorScope = Pick<CursorPayload, 'kind' | 'resource'>;
export function encodeCursor(payload: CursorPayload): string {
return Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url');
}
export function decodeCursor(cursor: string): CursorPayload {
try {
const bytes = Buffer.from(cursor, 'base64url');
if (bytes.toString('base64url') !== cursor) throw new Error('Invalid encoding');
return cursorPayloadSchema.parse(JSON.parse(bytes.toString('utf8')));
} catch {
throw invalidRequest('Некорректный cursor');
}
}
export function parsePage(limit: unknown, cursor: unknown, scope: CursorScope) {
if (limit !== undefined && (typeof limit !== 'string' || !/^[0-9]+$/.test(limit))) {
throw invalidRequest('Некорректный limit');
}
const query = parseWith(paginationSchema, { limit: limit === undefined ? undefined : Number(limit), cursor });
const after = query.cursor === undefined ? null : decodeCursor(query.cursor);
if (after && (after.kind !== scope.kind || after.resource !== scope.resource)) {
throw invalidRequest('Cursor не относится к этому списку');
}
return { limit: query.limit, after };
}
export function makePage<T extends { id: string; created_at: string }>(
rows: T[],
limit: number,
scope: CursorScope,
): Page<T> {
const items = rows.slice(0, limit);
const last = items.at(-1);
const next_cursor = last && rows.length > limit
? encodeCursor({ v: 1, ...scope, id: last.id, created_at: new Date(last.created_at).toISOString() })
: null;
return { items, next_cursor };
}
+52
View File
@@ -0,0 +1,52 @@
import { createHash } from 'node:crypto';
import type { PoolClient } from 'pg';
import { conflict, invalidRequest } from '../errors/api-error';
interface Identity {
userId: string;
chatId: string;
key: string;
}
export function parseIdempotencyKey(value: string | undefined): string {
if (!value || !/^[A-Za-z0-9._:-]{1,128}$/.test(value)) {
throw invalidRequest('Требуется корректный Idempotency-Key');
}
return value;
}
export async function reserveMessageKey(
client: PoolClient, identity: Identity, body: object,
): Promise<string | null> {
const hash = createHash('sha256').update(JSON.stringify(body)).digest('hex');
const values = [identity.userId, identity.chatId, identity.key];
// A conflicting insertion waits for the transaction holding this unique key.
const reserved = await client.query(
`INSERT INTO message_idempotency (user_id, chat_id, idempotency_key, request_hash, expires_at)
VALUES ($1, $2, $3, $4, clock_timestamp() + interval '24 hours')
ON CONFLICT (user_id, chat_id, idempotency_key) DO UPDATE
SET request_hash = EXCLUDED.request_hash, message_id = NULL, expires_at = EXCLUDED.expires_at
WHERE message_idempotency.expires_at <= clock_timestamp()
RETURNING idempotency_key`,
[...values, hash],
);
if (reserved.rowCount === 1) return null;
const { rows } = await client.query<{ request_hash: string; message_id: string | null }>(
`SELECT request_hash, message_id FROM message_idempotency
WHERE user_id = $1 AND chat_id = $2 AND idempotency_key = $3`,
values,
);
const record = rows[0];
if (!record?.message_id) throw new Error('Idempotency record incomplete');
if (record.request_hash !== hash) throw conflict('Ключ уже связан с другим сообщением');
return record.message_id;
}
export async function rememberMessage(client: PoolClient, identity: Identity, messageId: string): Promise<void> {
await client.query(
`UPDATE message_idempotency SET message_id = $4, expires_at = clock_timestamp() + interval '24 hours'
WHERE user_id = $1 AND chat_id = $2 AND idempotency_key = $3`,
[identity.userId, identity.chatId, identity.key, messageId],
);
}
+48
View File
@@ -0,0 +1,48 @@
import type { Message, Page, User } from '../domain/models';
import { db, transaction } from '../repositories/postgres';
import { parseWith } from '../validation/parse';
import { createMessageSchema } from '../validation/schemas';
import { requireAccessibleChat } from './chat.service';
import { makePage, parsePage } from './cursor.service';
import { parseIdempotencyKey, rememberMessage, reserveMessageKey } from './idempotency.service';
export async function createMessage(
actor: User, chatId: string, input: unknown, keyHeader: string | undefined,
): Promise<Message> {
const chat = await requireAccessibleChat(actor, chatId);
const body = parseWith(createMessageSchema, input);
const identity = { userId: actor.id, chatId: chat.id, key: parseIdempotencyKey(keyHeader) };
return transaction(async (client) => {
const replayId = await reserveMessageKey(client, identity, body);
if (replayId) {
const { rows } = await client.query<Message>(
'SELECT id, chat_id, sender_id, text, created_at FROM messages WHERE id = $1', [replayId],
);
if (!rows[0]) throw new Error('Saved message not found');
return rows[0];
}
const { rows } = await client.query<Message>(
`INSERT INTO messages (chat_id, sender_id, text) VALUES ($1, $2, $3)
RETURNING id, chat_id, sender_id, text, created_at`,
[chat.id, actor.id, body.text],
);
const message = rows[0];
if (!message) throw new Error('Message not returned');
await rememberMessage(client, identity, message.id);
return message;
});
}
export async function listMessages(actor: User, chatId: string, limit: unknown, cursor: unknown): Promise<Page<Message>> {
const chat = await requireAccessibleChat(actor, chatId);
const scope = { kind: 'messages', resource: chat.id } as const;
const page = parsePage(limit, cursor, scope);
const { rows } = await db.query<Message>(
`SELECT id, chat_id, sender_id, text, created_at FROM messages
WHERE chat_id = $1 AND ($2::timestamptz IS NULL OR (created_at, id) > ($2, $3))
ORDER BY created_at, id LIMIT $4`,
[chat.id, page.after?.created_at, page.after?.id, page.limit + 1],
);
return makePage(rows, page.limit, scope);
}
+19
View File
@@ -0,0 +1,19 @@
import { randomBytes, scrypt, timingSafeEqual } from 'node:crypto';
import { promisify } from 'node:util';
const derive = promisify(scrypt);
const dummyHash = 'scrypt$00000000000000000000000000000000$' + '0'.repeat(128);
export async function hashPassword(password: string): Promise<string> {
const salt = randomBytes(16);
const key = (await derive(password, salt, 64)) as Buffer;
return `scrypt$${salt.toString('hex')}$${key.toString('hex')}`;
}
export async function verifyPassword(password: string, stored: string | undefined): Promise<boolean> {
const [, salt, hash] = (stored ?? dummyHash).split('$');
if (!salt || !hash) throw new Error('Invalid password hash');
const expected = Buffer.from(hash, 'hex');
const actual = (await derive(password, Buffer.from(salt, 'hex'), expected.length)) as Buffer;
return timingSafeEqual(actual, expected) && stored !== undefined;
}
+19
View File
@@ -0,0 +1,19 @@
import type { User } from '../domain/models';
import { conflict } from '../errors/api-error';
import { db } from '../repositories/postgres';
import { parseWith } from '../validation/parse';
import { createUserSchema } from '../validation/schemas';
import { hashPassword } from './password.service';
export async function createUser(input: unknown): Promise<User> {
const body = parseWith(createUserSchema, input);
const hash = await hashPassword(body.password);
const { rows } = await db.query<User>(
`INSERT INTO users (username, display_name, password_hash) VALUES ($1, $2, $3)
ON CONFLICT (username) DO NOTHING RETURNING id, username, display_name, created_at`,
[body.username, body.display_name, hash],
);
const user = rows[0];
if (!user) throw conflict('Username уже занят');
return user;
}
+1
View File
@@ -0,0 +1 @@
export {};
+16
View File
@@ -0,0 +1,16 @@
import { z } from 'zod';
import { invalidRequest } from '../errors/api-error';
export function parseWith<T extends z.ZodTypeAny>(
schema: T,
value: unknown,
): z.output<T> {
const result = schema.safeParse(value);
if (result.success) {
return result.data;
}
const issue = result.error.issues[0];
throw invalidRequest(issue?.message ?? 'Некорректный запрос');
}
+65
View File
@@ -0,0 +1,65 @@
import { z } from 'zod';
const codePointLength = (value: string): number => Array.from(value).length;
const validUnicode = (value: string): boolean => !/[\u0000\uD800-\uDFFF]/u.test(value);
const nonBlank = (value: string): boolean => value.trim().length > 0;
const boundedUnicodeString = (max: number, label: string) =>
z
.string()
.refine(validUnicode, 'Недопустимый символ')
.refine(nonBlank, `${label} не может состоять только из пробелов`)
.refine(
(value) => codePointLength(value) <= max,
`${label} слишком длинное`,
);
export const uuidSchema = z.string().uuid('Ожидался UUID').transform((id) => id.toLowerCase());
export const usernameSchema = z.string().regex(/^[a-z0-9_]{3,32}$/, 'Некорректный username');
export const passwordSchema = boundedUnicodeString(128, 'password')
.refine((value) => codePointLength(value) >= 12, 'password слишком короткий');
export const createUserSchema = z
.object({
username: usernameSchema,
password: passwordSchema,
display_name: boundedUnicodeString(100, 'display_name'),
})
.strict();
export const createChatSchema = z
.object({
title: boundedUnicodeString(100, 'title'),
member_ids: z
.array(uuidSchema)
.min(1)
.max(100)
.refine(
(ids) => new Set(ids).size === ids.length,
'member_ids содержит дубликаты',
),
})
.strict();
export const createMessageSchema = z
.object({
text: boundedUnicodeString(4000, 'text'),
})
.strict();
export const paginationSchema = z.object({
limit: z.number().int().min(1).max(100).default(50),
cursor: z.string().min(1).max(512).optional(),
});
export const cursorPayloadSchema = z
.object({
v: z.literal(1),
kind: z.enum(['chats', 'messages']),
resource: z.string().min(1),
created_at: z.string().datetime({ precision: 3 }),
id: uuidSchema,
})
.strict();
export type CursorPayload = z.infer<typeof cursorPayloadSchema>;
+47
View File
@@ -0,0 +1,47 @@
"""Test UTF-8 Basic credentials, exact JSON validation and chat membership."""
import base64
from pathlib import Path
import sys
import uuid
sys.path.insert(0, str(Path(__file__).resolve().parents[1] / 'tests'))
from client import Client, arguments, check, run
def main():
args = arguments('Student checks: Basic and chat validation')
client = Client(args.base_url, args.ca_file)
username = 'u_colon_' + uuid.uuid4().hex[:12]
password = 'Пароль:🔑' * 3
user = client.call('POST', '/api/v1/users', 201, schema='User',
body={'username': username, 'display_name': 'Студент', 'password': password})['json']
basic = base64.b64encode(f'{username}:{password}'.encode()).decode()
auth = {'Authorization': 'Basic ' + basic}
session = client.call('POST', '/api/v1/auth/sessions', 201,
headers=auth, schema='Session')['json']
check(session['user'] == user, 'UTF-8 password with colon failed')
client.call('POST', '/api/v1/auth/sessions', 400, headers=auth, body={})
alice = {'id': user['id'], 'token': session['token']}
bob = client.user('bob')
path = '/api/v1/chats'
title = 'Проверка участников'
members = [alice['id'], bob['id']]
for body in (
{'title': title, 'member_ids': [alice['id'], str(uuid.uuid4())]},
{'title': title, 'member_ids': [alice['id'], alice['id'].upper()]},
{'title': title, 'member_ids': [bob['id']]},
{'title': 123, 'member_ids': members},
{'title': title, 'member_ids': members, 'unexpected': True},
):
client.call('POST', path, 400, actor=alice, body=body)
page = client.call('GET', path, actor=alice, schema='ChatPage')['json']
check(page['items'] == [], 'invalid creation left a visible chat')
chat = client.call('POST', path, 201, actor=alice,
body={'title': title, 'member_ids': members}, schema='Chat')['json']
listed = client.call('GET', path, actor=bob, schema='ChatPage')['json']
check(listed['items'] == [chat], 'valid chat or membership is missing')
print('PASS: UTF-8 password with colon, strict JSON, and atomic chat creation')
if __name__ == '__main__':
run(main)
+37
View File
@@ -0,0 +1,37 @@
"""Exercise concurrent retries through the shared load balancer."""
from concurrent.futures import ThreadPoolExecutor
from pathlib import Path
import sys
import uuid
sys.path.insert(0, str(Path(__file__).resolve().parents[1] / 'tests'))
from client import Client, arguments, check, run
def main():
args = arguments('Student checks: concurrent idempotency on two replicas')
client = Client(args.base_url, args.ca_file)
alice, bob, _, chat = client.bootstrap()
key = uuid.uuid4().hex
def send(_):
return Client(args.base_url, args.ca_file).message(alice, chat, 'Повтор', key=key)
with ThreadPoolExecutor(max_workers=8) as executor:
responses = list(executor.map(send, range(16)))
first = responses[0]['json']
instances = {item['headers']['X-Instance-Id'] for item in responses}
check(len(instances) >= 2, 'concurrent requests did not reach two API replicas')
check(all(item['json'] == first for item in responses), 'replays differ')
path = '/api/v1/chats/' + chat['id'] + '/messages'
page = client.call('GET', path, actor=bob, schema='MessagePage')['json']
check(page['items'] == [first], 'duplicate persisted message')
client.call('POST', path, 409, actor=alice, body={'text': 'Другой текст'},
headers={'Idempotency-Key': key})
independent = client.message(bob, chat, 'Повтор', key=key)['json']
check(independent['id'] != first['id'], 'key incorrectly shared between users')
print(f'PASS: {len(responses)} concurrent requests on {len(instances)} replicas yielded one message')
if __name__ == '__main__':
run(main)
+21
View File
@@ -0,0 +1,21 @@
{
"compilerOptions": {
"target": "ES2022",
"module": "CommonJS",
"moduleResolution": "node",
"rootDir": "src",
"outDir": "dist",
"strict": true,
"esModuleInterop": true,
"experimentalDecorators": true,
"emitDecoratorMetadata": true,
"resolveJsonModule": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"noUncheckedIndexedAccess": true,
"noImplicitOverride": true,
"sourceMap": true
},
"include": ["src/**/*.ts", "src/**/*.json"],
"exclude": ["node_modules", "dist", "src/**/*.test.ts"]
}
+10
View File
@@ -0,0 +1,10 @@
{
"entryFile": "src/tsoa-entry.ts",
"noImplicitAdditionalProperties": "throw-on-extras",
"controllerPathGlobs": ["src/controllers/*.controller.ts"],
"spec": {"outputDirectory": "src/generated", "specVersion": 3},
"routes": {
"routesDir": "src/generated",
"middleware": "express"
}
}