From 40fa0fe23f001fb64e187727d5a0fb6f922a22d9 Mon Sep 17 00:00:00 2001 From: 0pavel1 Date: Tue, 17 Nov 2026 02:34:05 +0300 Subject: [PATCH] feat(lab3): HAProxy LB, stateless API replicas, X-Instance-Id, Idempotency-Key, Grade 5 Track 1 --- .gitattributes | 2 + Dockerfile | 38 + Makefile | 12 +- REPORT.md | 179 +- cmd/server/main.go | 207 +++ compose.yaml | 153 ++ evidence/grade4_checks.json | 100 + evidence/load.json | 17 + evidence/track1_scaling.json | 475 +++++ evidence/track1_scaling_chart.svg | 37 + go.mod | 21 + go.sum | 42 + infra/haproxy.cfg | 40 + infra/redis.conf | 14 + internal/auth/password.go | 108 ++ internal/auth/password_test.go | 43 + internal/handler/handler.go | 451 +++++ internal/handler/middleware.go | 168 ++ internal/handler/openapi.json | 2528 ++++++++++++++++++++++++++ internal/model/types.go | 75 + internal/store/postgres.go | 1042 +++++++++++ internal/store/store.go | 105 ++ migrations/001_init.sql | 53 + migrations/002_idempotency.sql | 17 + scripts/restart.sh | 8 + scripts/seed.py | 80 + scripts/stop-one.sh | 25 + student-tests/test_grade4.py | 444 +++++ student-tests/test_track1_scaling.py | 372 ++++ 29 files changed, 6835 insertions(+), 21 deletions(-) create mode 100644 .gitattributes create mode 100644 Dockerfile create mode 100644 cmd/server/main.go create mode 100644 compose.yaml create mode 100644 evidence/grade4_checks.json create mode 100644 evidence/load.json create mode 100644 evidence/track1_scaling.json create mode 100644 evidence/track1_scaling_chart.svg create mode 100644 go.mod create mode 100644 go.sum create mode 100644 infra/haproxy.cfg create mode 100644 infra/redis.conf create mode 100644 internal/auth/password.go create mode 100644 internal/auth/password_test.go create mode 100644 internal/handler/handler.go create mode 100644 internal/handler/middleware.go create mode 100644 internal/handler/openapi.json create mode 100644 internal/model/types.go create mode 100644 internal/store/postgres.go create mode 100644 internal/store/store.go create mode 100644 migrations/001_init.sql create mode 100644 migrations/002_idempotency.sql create mode 100755 scripts/restart.sh create mode 100644 scripts/seed.py create mode 100755 scripts/stop-one.sh create mode 100644 student-tests/test_grade4.py create mode 100644 student-tests/test_track1_scaling.py diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..72e9c40e --- /dev/null +++ b/.gitattributes @@ -0,0 +1,2 @@ +*.sh text eol=lf +*.sql text eol=lf diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 00000000..ef92a383 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,38 @@ +# syntax=docker/dockerfile:1 + +# Stage 1: Build static Go binary +FROM golang:1.24-alpine AS builder +WORKDIR /src + +ENV GOPROXY=https://goproxy.io,direct +ENV GOSUMDB=off + +# Cache dependencies first +COPY go.mod go.sum ./ +RUN go mod download + +# Copy application source and migrations +COPY cmd/ ./cmd/ +COPY internal/ ./internal/ +COPY migrations/ ./migrations/ + +# Build stripped static binary +RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -ldflags="-s -w" -o /out/messenger ./cmd/server + +# Stage 2: Minimal non-root runtime image +FROM alpine:3.21 +RUN addgroup -g 10001 -S appgroup && \ + adduser -u 10001 -S appuser -G appgroup + +WORKDIR /app +COPY --from=builder /out/messenger /app/messenger +COPY --from=builder /src/migrations /app/migrations +RUN chown -R appuser:appgroup /app + +USER 10001:10001 +EXPOSE 8080 + +HEALTHCHECK --interval=2s --timeout=2s --start-period=2s --retries=10 \ + CMD wget -q -O /dev/null http://127.0.0.1:8080/health/ready || exit 1 + +ENTRYPOINT ["/app/messenger"] diff --git a/Makefile b/Makefile index 5d86d171..7da60c32 100644 --- a/Makefile +++ b/Makefile @@ -4,7 +4,7 @@ CA_FILE ?= ACTION_SCRIPT ?= TLS_ARGS = $(if $(CA_FILE),--ca-file "$(CA_FILE)",) -.PHONY: help check validate test load test-persistence test-failover +.PHONY: help check validate test load test-persistence test-failover test-grade4 test-track1 seed help: @echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes" @@ -28,3 +28,13 @@ test-persistence: test-failover: @test -n "$(ACTION_SCRIPT)" || (echo "Set ACTION_SCRIPT to your implemented executable stop-one hook"; exit 2) $(PYTHON) tests/resilience.py --mode failover --action-script "$(ACTION_SCRIPT)" --base-url "$(BASE_URL)" $(TLS_ARGS) + + +test-grade4: + $(PYTHON) student-tests/test_grade4.py "$(BASE_URL)" + +test-track1: + $(PYTHON) student-tests/test_track1_scaling.py "$(BASE_URL)" + +seed: + $(PYTHON) scripts/seed.py "$(BASE_URL)" diff --git a/REPORT.md b/REPORT.md index c2679005..a8c66e09 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,176 @@ # Отчёт — лабораторная 3 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- **Автор, группа:** Заморский Павел, БВТ2302 +- **Целевая оценка; трек 5:** **5** (выполнены уровни 3, 4 и **Трек 1 «Цена масштабирования»**) +- **Commit/PR:** ветка `solution/bvt2302-zamorskiy` +- **Использованные источники, библиотеки и помощь ИИ:** Go 1.24 (`jackc/pgx/v5`, `redis/go-redis/v9`, `golang.org/x/crypto/argon2`, `golang.org/x/sync/singleflight`, `google/uuid`), PostgreSQL 18 (`postgres:18-alpine`), Redis 7.4 (`redis:7.4-alpine`), HAProxy 3.0 (`haproxy:3.0-alpine`), документация Docker Compose (services, healthcheck, deploy resources), PostgreSQL transactions / advisory locks, RFC 7617. Помощь ИИ (Google Antigravity) при генерации шаблонов тестов, нагрузочных скриптов и оформлении отчёта. -## Запуск из чистого clone +--- -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +## 1. Запуск из чистого clone -## Архитектура и решения +### 1.1. Версии runtime и контейнерных образов +- **Go runtime / builder:** `golang:1.24-alpine`, финальный non-root runtime-образ: `alpine:3.21` (UID/GID `10001`). +- **PostgreSQL:** `postgres:18-alpine` (именованный volume `mtusi_lab3_pgdata`, `PGDATA=/var/lib/postgresql/data/pgdata`). +- **Redis:** `redis:7.4-alpine` (AOF `appendonly yes`, `appendfsync everysec`, volume `mtusi_lab3_redisdata`). +- **Load Balancer:** `haproxy:3.0-alpine` (`infra/haproxy.cfg`, единственная публичная точка входа `8080 -> 80`). -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +### 1.2. Команды подготовки и запуска стенда -## Доказательства критериев +```sh +# 1. Скопировать локальную конфигурацию (секреты не коммитятся в Git) +cp .env.example .env -| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | +# 2. Проверить валидность Compose-топологии и статический контракт +docker compose --env-file .env config --quiet +make check + +# 3. Собрать и поднять стенд (PostgreSQL 18 -> Redis 7.4 -> one-shot migrate -> API x2 -> HAProxy LB) +docker compose --env-file .env up -d --build +docker compose --env-file .env ps + +# 4. Дождаться готовности и наполнить демо-данные (опционально для Swagger UI /docs) +curl -fsS http://localhost:8080/health/ready +make seed + +# 5. Запустить обязательные публичные проверки (уровень 3) +make test +make test-persistence ACTION_SCRIPT=scripts/restart.sh +make test-failover ACTION_SCRIPT=scripts/stop-one.sh +# После failover-теста восстановить остановленную реплику: +docker compose --env-file .env up -d --no-deps api + +# 6. Запустить проверки уровня 4 и эксперимент уровня 5 (Трек 1) +make test-grade4 +make test-track1 +make load +``` + +### 1.3. Остановка и сброс данных + +- **Безопасная остановка (с сохранением volumes):** + ```sh + docker compose --env-file .env down + ``` +- **Намеренное удаление учебных данных и томов:** + ```sh + docker compose --env-file .env down -v + ``` + +--- + +## 2. Архитектура и решения + +### 2.1. Перенос из ЛР2 и изменения ЛР3 + +Из ЛР2 перенесены `cmd/server`, `internal/auth` (Argon2id + SHA-256 токены), `internal/model`, `internal/store`, `internal/handler`, `migrations/001_init.sql`, `Dockerfile` и `infra/redis.conf`. + +**Ключевые изменения ЛР3:** +1. **Единая точка входа — HAProxy 3.0 (`lb`) + масштабируемый сервис `api`:** + - Реплики `api` запускаются через `deploy.replicas: ${API_REPLICAS:-2}` без `container_name` и **без проброшенных наружу портов** — весь внешний трафик идёт через `lb` (`0.0.0.0:8080->80/tcp`). + - Все контейнеры ограничены по CPU/RAM (`deploy.resources.limits`: `api` `1.0 CPU / 256M`, `postgres` `1.0 CPU / 512M`, `redis` `0.5 CPU / 256M`, `lb` `0.5 CPU / 128M`). +2. **`X-Instance-Id` и отсутствие локального состояния (Stateless API):** + - Каждая реплика при старте фиксирует свой `instanceID` (`os.Hostname()`, равный 12-символьному ID Docker-контейнера) и добавляет заголовок `X-Instance-Id` ко **всем** HTTP-ответам через `InstanceIDMiddleware` (включая `4xx/5xx`, `204` и `/health/*`). + - Сессии хранятся в PostgreSQL (`sessions` — источник истины) и кэшируются в общем Redis (`sess:` с `EXPIREAT`); кэш истории сообщений (`msg_page::v:...`) версионируется общим счётчиком `chat_ver:` в Redis (`INCR` при каждой новой записи). + - Sticky sessions в HAProxy **намеренно отключены** (`balance roundrobin`) — любой запрос одной и той же сессии обслуживается любой здоровой репликой. +3. **Согласованный запуск миграций без гонки реплик:** + - Добавлен одноразовый init-сервис `migrate` (`entrypoint: ["/app/messenger", "-migrate-only"]`), который запускается после `postgres (healthy)` и завершается до старта реплик `api` (`depends_on: migrate: condition: service_completed_successfully`). + - На самих репликах `RUN_MIGRATIONS="false"`, а внутри `RunMigrations` дополнительно используется транзакционная рекомендательная блокировка PostgreSQL `SELECT pg_advisory_xact_lock(20260301)`. + - Новая миграция [`migrations/002_idempotency.sql`](migrations/002_idempotency.sql) строго аддитивна (совместима с работающими репликами при rolling-обновлении). +4. **Атомарная межрепликовая идемпотентность `POST /api/v1/chats/{chat_id}/messages`:** + - Обязателен заголовок `Idempotency-Key` (`^[A-Za-z0-9._:-]{1,128}$`), иначе `400 invalid_request`. + - Область уникальности в PostgreSQL (`idempotency_keys`): `PRIMARY KEY (user_id, chat_id, idempotency_key)`, срок жизни `IDEMPOTENCY_TTL_SECONDS=86400` (24 часа). + - Проверка прав участника (`404`) и валидация JSON/текста (`400`) выполняются **до** фиксации ключа. + - Канонический хеш тела (`SHA-256` от нормализованного `{"text": ...}`) гарантирует семантическое равенство при разном форматировании JSON и возвращает `409 conflict` при другом теле. + - **Конкурентные повторы через разные реплики:** вставка сообщения в `messages` и регистрация ключа `INSERT INTO idempotency_keys ... ON CONFLICT DO NOTHING` выполняются в **одной** PostgreSQL-транзакции (в режиме `pipeline` через `pgx.Batch` в одном сетевом roundtrip). При конкурентном запросе проигравшая транзакция блокируется PostgreSQL на PK до исхода победителя, получает `RowsAffected() == 0`, откатывает дублирующий `INSERT INTO messages` через `tx.Rollback()` и возвращает сообщение победителя (либо `409`). Если победитель упал до `COMMIT`, БД снимает блокировку и второй запрос успешно завершает запись. +5. **Согласованность Health/Readiness, таймаутов и `SIGTERM` Graceful Drain:** + - **API:** при получении `SIGTERM` мгновенно переводит `draining = true` -> `GET /health/ready` начинает отвечать `503 unavailable`, при этом существующий listener остаётся открытым `SHUTDOWN_DRAIN_DELAY_MS=1500` мс для завершения активных запросов, после чего вызывается `srv.Shutdown(5s)` (`stop_grace_period: 10s`). + - **HAProxy:** активный healthcheck `GET /health/ready` с параметрами `inter 1s fastinter 500ms downinter 1s fall 2 rise 1 timeout check 1500ms` + `resolvers docker_dns` (`hold valid 2s`). + - **Максимальное время обнаружения отказа (без `SIGTERM`, резкое падение):** `inter 1s` + `fastinter 500ms` при `fall 2` ≈ **1.5–2.0 сек** (а при штатном `SIGTERM` drain за 1.5 сек реплика выводится из ротации с **0 потерянных соединений**). + +### 2.2. Соответствие `.env.example` + +| Переменная `.env.example` | Использование в стенде | Значение по умолчанию | +| --- | --- | --- | +| `APP_HOST`, `APP_PORT` | Порт API внутри сети (`8080`) и публичный порт HAProxy (`${APP_PORT:-8080}:80`) | `0.0.0.0`, `8080` | +| `APP_ENV` | Метка окружения в логах старта API | `lab` | +| `SESSION_TTL_SECONDS` | Срок жизни Bearer-сессий в PostgreSQL и Redis (`EXPIREAT`) | `3600` | +| `DATABASE_URL_FILE` / `DATABASE_URL` | Строка подключения PostgreSQL 18 (чтение файла секрета с fallback на `DATABASE_URL`) | `.../messenger` | +| `SESSION_STORE` | Режим хранения/кэша сессий | `redis` | +| `CACHE_URL_FILE` / `CACHE_URL` | Подключение к общему Redis 7.4 | `redis://redis:6379/0` | +| `API_REPLICAS` | Количество реплик `api` в `deploy.replicas` | `2` | +| `IDEMPOTENCY_TTL_SECONDS` | Срок хранения записей `idempotency_keys` (24 ч) | `86400` | + +--- + +## 3. Доказательства критериев + +| Критерий README | Команда / сценарий | Наблюдаемый результат | Файл доказательства | | --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | +| Офлайн-структура и OpenAPI-контракт | `make check` | `PASS: offline skeleton structure, local refs and Python syntax` | `scripts/check_contract.py` | +| Публичный сквозной smoke (Уровень 3) | `make test` | `PASS: lab3 public API scenario` (`X-Instance-Id`, `Idempotency-Key` 201/409/400) | `tests/smoke.py` | +| Рестарт всего стенда с сохранением томов | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | Перезапущены `postgres`, `redis`, `api`, `lb`; прежний токен и данные сохранены (`PASS`) | `scripts/restart.sh` | +| Отказ одной API-реплики (Уровень 3) | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | `observed_instances_before=2`, `successful_writes=143`, `failed_attempts=0`, `first_recovery_seconds=2.758`, остановлена `lab3-api-2` (`Exited 0`) | `scripts/stop-one.sh` | +| Инфраструктура, лимиты, изоляция портов, миграции (Уровень 4) | `make test-grade4` (`infra_and_migrations`) | 2 реплики (`1.0 CPU / 256M RAM`), `0` открытых портов API мимо LB, ровно 2 миграции в `schema_migrations` | [`evidence/grade4_checks.json`](evidence/grade4_checks.json) | +| Межрепликовые сессии и общий logout (Уровень 4) | `make test-grade4` (`stateless_sessions`) | 30 запросов с одним токеном обслужены обеими репликами; после `DELETE` все реплики сразу отдают `401` | [`evidence/grade4_checks.json`](evidence/grade4_checks.json) | +| Параллельная идемпотентность и изоляция scope (Уровень 4) | `make test-grade4` (`concurrent_idempotency`) | 20 параллельных POST с одним ключом на разные реплики создали строго 1 сообщение; `409` на другое тело; независимые ключи у Bob и в другом чате | [`evidence/grade4_checks.json`](evidence/grade4_checks.json) | +| Последовательный отказ каждой реплики под нагрузкой (Уровень 4) | `make test-grade4` (`sequential_failover`) | Остановка replica 1: `1354/1354` OK (`0` ошибок, `135.4 RPS`, `0.0s` downtime); остановка replica 2: `1354/1354` OK (`0` ошибок, `135.4 RPS`) | [`evidence/grade4_checks.json`](evidence/grade4_checks.json) | +| Поочерёдное rolling-обновление под нагрузкой (Уровень 4) | `make test-grade4` (`rolling_update`) | Оба старых контейнера заменены на новые (через scale 2→3→2): `1476/1476` успешных записей, `0` ошибок (`error_rate=0.0`) | [`evidence/grade4_checks.json`](evidence/grade4_checks.json) | +| Базовая нагрузка `tests/load.py` | `python3 tests/load.py --duration 15 --concurrency 4 --output evidence/load.json` | `11922` успешных POST за 15s, `794.485 RPS`, `0` ошибок, `p50=4.182ms`, `p95=8.602ms`, `p99=20.762ms` | [`evidence/load.json`](evidence/load.json) | +| Трек 1: Цена масштабирования и улучшение (Уровень 5) | `make test-track1` | Полные серии A (фиксированный бюджет), B (рост ресурсов + saturation point на PostgreSQL), C (`+37.59%` RPS и `-5.86x` p50) | [`evidence/track1_scaling.json`](evidence/track1_scaling.json), [`evidence/track1_scaling_chart.svg`](evidence/track1_scaling_chart.svg) | -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +--- -## Эксперименты и отказы +## 4. Эксперименты и отказы -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. +### 4.1. Матрица проверенных отказов и переключений | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +| `scripts/stop-one.sh` (`make test-failover`) | Остановка целевой реплики, переключение HAProxy на вторую за `<= 10s`, повтор неопределённых POST без дублей | `143` записи за 15s, `failed_attempts=0`, `first_recovery_seconds=2.758`, целевой контейнер остался остановленным | Переход без сбоев клиентов (`0` ошибок), `0` потерь и `0` дублей | +| Последовательный стоп `lab3-api-1`, затем `lab3-api-2` под нагрузкой | Сохранение обслуживания на оставшейся реплике (`~1.5s` drain) | В обоих этапах: `1354` записей за 10s, `135.4 RPS`, `0` ошибок, трафик полностью ушёл на живую реплику | `0.0s` клиентского простоя, `0` потерь данных | +| Rolling-обновление (scale 2→3, замена по 1 реплике, 3→2) | Замена всех экземпляров без прерывания записей | Все 5 наблюдаемых экземпляров отработали штатно; `1476/1476` успешных POST | `0.0s` простоя, `error_rate = 0.0` | +| Полный рестарт `postgres + redis + api + lb` (`scripts/restart.sh`) | Сессия и подтверждённые сообщения сохраняются на volumes | Прежний Bearer-токен продолжил читать историю без повторного входа | Штатный рестарт (~5s), `0` потерь данных | -## Ограничения и следующие шаги +### 4.2. Трек 1 — Исследование «Цена масштабирования» -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +- **Гипотеза:** + 1. При **фиксированном суммарном бюджете CPU/RAM** на API разбиение на 1 → 2 → 4 реплики не увеличит RPS (и может ухудшить хвостовую задержку из-за CPU throttling Argon2id и накладных расходов на GC/пулы соединений). + 2. При **росте ресурсов на каждую новую реплику** масштабирование сначала даст резкий прирост RPS (пока узким местом является CPU API на Argon2id), но упрётся в **saturation point PostgreSQL**, после которого добавление реплик перестанет повышать пропускную способность и лишь увеличит конкуренцию пулов соединений. + 3. Снижение числа SQL roundtrips в транзакции записи (`pgx.Batch` pipeline: 5 RTT → 2 RTT) и приведение размера `pgxpool` в соответствие ресурсам БД (`DB_MAX_CONNS: 25 → 8`) поднимет потолок RPS в точке насыщения. +- **Профиль нагрузки и условия:** `concurrency=16` (серия A) / `20` (серии B/C), `warmup=2s`, `duration=10s`, HTTP/1.1 keep-alive через HAProxy: **5% `POST /api/v1/auth/sessions`** (Argon2id `m=19 MiB, p=2`), **75% `POST /messages`** (транзакционная запись с `Idempotency-Key` + `INCR chat_ver`), **20% `GET /messages?limit=20`** (версионированный кэш Redis). Замеры CPU/RAM контейнеров сняты в середине прогона (`docker stats`). + +#### Серия A: Фиксированный суммарный бюджет API (`2.0 CPU`, `512M RAM`; `DB=1.0 CPU, 512M RAM`) + +| Топология API | Сумм. ресурсы API | Успешный RPS | Ошибки | p50 (ms) | p95 (ms) | p99 (ms) | CPU PostgreSQL (midpoint) | +| --- | --- | --- | --- | --- | --- | --- | --- | +| `1 × (2.0 CPU, 512M)` | `2.0 CPU / 512M` | **1016.7** | `0` | 7.74 | 64.20 | 76.24 | `90.21%` (из `100%`) | +| `2 × (1.0 CPU, 256M)` | `2.0 CPU / 512M` | **825.1** | `0` | 8.61 | 70.59 | 83.03 | `98.70%` | +| `4 × (0.5 CPU, 128M)` | `2.0 CPU / 512M` | **413.6** | `15` (`0.36%`) | 6.48 | 96.02 | 381.83 | `79.92%` | + +**Вывод по серии A:** при фиксированном бюджете дробление до `4 × (0.5 CPU, 128M)` снизило пропускную способность в **2.46×** (`1016.7 → 413.6 RPS`) и дало всплеск `p99` до `381.8 ms`. Причина — накладные расходы 4 отдельных Go-рантаймов/пулов (`50–89 MiB` RAM на процесс против `109.5 MiB` у 1 процесса) и жёсткий CFS CPU throttling при всплесках Argon2id (`19 MiB, p=2`) в квоте `0.5 CPU`. + +#### Серия B и C: Рост ресурсов API (`0.5 CPU, 256M` на реплику) против ограниченной БД (`DB=0.5 CPU, 256M`), поиск saturation point и улучшение + +| Конфигурация | Режим записи / пул БД | Успешный RPS | Ошибки | p50 (ms) | p95 (ms) | p99 (ms) | Загрузка CPU (midpoint, квота 50% = 0.5 CPU) | +| --- | --- | --- | --- | --- | --- | --- | --- | +| `1 × 0.5 CPU` (до улушч.) | `sequential`, `DB_MAX_CONNS=25` | **47.5** | `20` (`4.04%`) | 99.28 | 798.93 | 2700.52 | **API `49.44%` (упор!)**, DB `5.02%` | +| `2 × 0.5 CPU` (до улучш.) | `sequential`, `DB_MAX_CONNS=25` | **353.5** | `0` | 34.67 | 178.07 | 304.30 | API `50.45% + 40.02%`, **DB `48.57%` (упор!)** | +| `4 × 0.5 CPU` (до улучш.) | `sequential`, `DB_MAX_CONNS=25` | **370.8** | `0` | 77.49 | 102.15 | 201.12 | API `18.8–35.1%` (простой), **DB `48.70%` (насыщение)** | +| **`4 × 0.5 CPU` (ПОСЛЕ улучш.)** | **`pipeline` (`pgx.Batch`), `DB_MAX_CONNS=8`** | **510.2** (**`+37.59%`**) | **`0`** | **13.23** (**`5.86×` ниже!**) | **97.00** (`-5.04%`) | **144.24** (`-28.3%`) | API `30.0–35.2%`, DB `55.39%` | + +**Анализ saturation point и подтверждённого улучшения:** +1. При `1` реплике (`0.5 CPU`) система упирается в CPU API (Argon2id + runtime занимают все `49.44%` из лимита `50%`), в то время как PostgreSQL загружен всего на `5.02%`. Удвоение реплик до `2` (`1.0 CPU` на API) даёт **7.4×** рост RPS (`47.5 → 353.5 RPS`). +2. Уже при переходе `2 → 4` реплик (`1.0 → 2.0 CPU` на API) наступает **saturation point в PostgreSQL**: БД полностью упирается в свой лимит `0.5 CPU` (`48.57–48.70%`), поэтому пропускная способность почти не растёт (`+4.9%`, `353.5 → 370.8 RPS`), а медианная задержка **более чем удваивается** (`34.67 → 77.49 ms`) из-за очередей к БД и 4 пулов по 25 соединений (до `100` коннектов). +3. **Подтверждённое улучшение:** переход на конвейерную отправку SQL внутри транзакции (`pgx.Batch` в `CreateMessage`: 5 последовательных сетевых RTT сведены к 2) и настройка `DB_MAX_CONNS=8` (`32` суммарных соединения вместо `100`) снизили накладные расходы переключения контекста и ожидания в PostgreSQL — на той же точке насыщения (`4` реплики, `0.5 CPU DB`) RPS вырос на **`+37.59%`** (`370.8 → 510.2`), а медианная задержка `p50` снизилась с **`77.49 ms` до `13.23 ms`** (при записи сообщений `84.73 → 16.82 ms`). + +График измерений: [`evidence/track1_scaling_chart.svg`](evidence/track1_scaling_chart.svg). + +--- + +## 5. Ограничения и следующие шаги + +- **Что выдерживает стенд:** остановку и/или rolling-замену любой API-реплики с автоматическим переключением HAProxy, полный рестарт контейнеров (`postgres`, `redis`, `api`, `lb`) с сохранением томов, конкурентные повторы `POST /messages` через разные реплики без дублей. +- **Что остаётся SPOF:** вся система развёрнута на одном Docker-хосте; PostgreSQL 18, Redis 7.4 и один экземпляр HAProxy являются едиными точками отказа (отказ узла целиком или отказ PostgreSQL приводит к `503 unavailable` на путях записи и холодных чтениях). +- **Упрощения измерений:** `tests/load.py` и `test_track1_scaling.py` — closed-loop генераторы на том же локальном хосте (присутствует coordinated omission и конкуренция клиента и контейнеров за CPU хоста), поэтому абсолютные RPS отражают поведение стенда на данном ноутбуке, а достоверной ценностью обладают относительные сдвиги между режимами и точки насыщения по метрикам `docker stats`. +- **Следующий шаг (ЛР4):** добавить приватное S3-совместимое объектное хранилище и эндпоинты вложений без публикации бакета напрямую. diff --git a/cmd/server/main.go b/cmd/server/main.go new file mode 100644 index 00000000..aa616d3d --- /dev/null +++ b/cmd/server/main.go @@ -0,0 +1,207 @@ +package main + +import ( + "context" + "errors" + "flag" + "fmt" + "log" + "net/http" + "os" + "os/signal" + "path/filepath" + "sort" + "strconv" + "strings" + "syscall" + "time" + + "github.com/google/uuid" + "messenger/internal/handler" + "messenger/internal/store" +) + +func getEnv(key, defaultVal string) string { + if val := strings.TrimSpace(os.Getenv(key)); val != "" { + return val + } + return defaultVal +} + +func getEnvInt(key string, defaultVal int) int { + if val := strings.TrimSpace(os.Getenv(key)); val != "" { + if n, err := strconv.Atoi(val); err == nil { + return n + } + } + return defaultVal +} + +func getEnvBool(key string, defaultVal bool) bool { + if val := strings.TrimSpace(os.Getenv(key)); val != "" { + if b, err := strconv.ParseBool(val); err == nil { + return b + } + } + return defaultVal +} + +func resolveSecretOrEnv(fileEnvKey, directEnvKey, defaultVal string) string { + if filePath := strings.TrimSpace(os.Getenv(fileEnvKey)); filePath != "" { + if data, err := os.ReadFile(filePath); err == nil { + if trimmed := strings.TrimSpace(string(data)); trimmed != "" { + return trimmed + } + } + } + if direct := strings.TrimSpace(os.Getenv(directEnvKey)); direct != "" { + return direct + } + return defaultVal +} + +func resolveInstanceID() string { + if id := strings.TrimSpace(os.Getenv("INSTANCE_ID")); id != "" { + return id + } + if host, err := os.Hostname(); err == nil && strings.TrimSpace(host) != "" { + return strings.TrimSpace(host) + } + return "api-" + uuid.New().String()[:12] +} + +func loadMigrations(dir string) ([]store.MigrationFile, error) { + entries, err := os.ReadDir(dir) + if err != nil { + return nil, fmt.Errorf("read migrations dir %s: %w", dir, err) + } + var names []string + for _, entry := range entries { + if !entry.IsDir() && strings.HasSuffix(entry.Name(), ".sql") { + names = append(names, entry.Name()) + } + } + sort.Strings(names) + if len(names) == 0 { + return nil, fmt.Errorf("no .sql migration files found in %s", dir) + } + + migrations := make([]store.MigrationFile, 0, len(names)) + for _, name := range names { + raw, err := os.ReadFile(filepath.Join(dir, name)) + if err != nil { + return nil, fmt.Errorf("read migration %s: %w", name, err) + } + migrations = append(migrations, store.MigrationFile{ + Version: name, + SQL: string(raw), + }) + } + return migrations, nil +} + +func main() { + migrateOnly := flag.Bool("migrate-only", false, "Run database migrations and exit") + flag.Parse() + + host := getEnv("APP_HOST", "0.0.0.0") + port := getEnv("APP_PORT", "8080") + appEnv := getEnv("APP_ENV", "lab") + sessionTTL := getEnvInt("SESSION_TTL_SECONDS", 3600) + idempotencyTTL := getEnvInt("IDEMPOTENCY_TTL_SECONDS", 86400) + maxConns := int32(getEnvInt("DB_MAX_CONNS", 12)) + minConns := int32(getEnvInt("DB_MIN_CONNS", 2)) + queryTimeoutMs := getEnvInt("DB_QUERY_TIMEOUT_MS", 5000) + drainDelayMs := getEnvInt("SHUTDOWN_DRAIN_DELAY_MS", 1500) + cacheMode := getEnv("CACHE_MODE", "write_through_versioned") + writeMode := getEnv("WRITE_MODE", "pipeline") + migrationsDir := getEnv("MIGRATIONS_DIR", "migrations") + runMigrations := *migrateOnly || getEnvBool("RUN_MIGRATIONS", true) + instanceID := resolveInstanceID() + + dbURL := resolveSecretOrEnv("DATABASE_URL_FILE", "DATABASE_URL", "postgres://messenger:messenger_lab3_pass@localhost:5432/messenger?sslmode=disable") + cacheURL := resolveSecretOrEnv("CACHE_URL_FILE", "CACHE_URL", "redis://localhost:6379/0") + + ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) + defer stop() + + st, err := store.NewPostgresStore(ctx, store.Config{ + DatabaseURL: dbURL, + CacheURL: cacheURL, + MaxConns: maxConns, + MinConns: minConns, + QueryTimeout: time.Duration(queryTimeoutMs) * time.Millisecond, + CacheMode: cacheMode, + WriteMode: writeMode, + }) + if err != nil { + log.Fatalf("Failed to initialize store: %v", err) + } + defer st.Close() + + if runMigrations { + migrations, err := loadMigrations(migrationsDir) + if err != nil { + log.Fatalf("Failed to load migrations: %v", err) + } + + var migErr error + for attempt := 1; attempt <= 30; attempt++ { + migErr = st.RunMigrations(ctx, migrations) + if migErr == nil { + break + } + log.Printf("Waiting for PostgreSQL to apply migrations (attempt %d/30): %v", attempt, migErr) + select { + case <-ctx.Done(): + log.Fatalf("Interrupted while waiting for database migrations") + case <-time.After(1 * time.Second): + } + } + if migErr != nil { + log.Fatalf("Could not apply database migrations after 30 attempts: %v", migErr) + } + } + + if *migrateOnly { + log.Println("Migrate-only flag set; exiting 0.") + return + } + + h, apiHandler := handler.RegisterRoutes(st, sessionTTL, idempotencyTTL, instanceID) + + addr := fmt.Sprintf("%s:%s", host, port) + srv := &http.Server{ + Addr: addr, + Handler: h, + ReadHeaderTimeout: 5 * time.Second, + ReadTimeout: 15 * time.Second, + WriteTimeout: 15 * time.Second, + IdleTimeout: 60 * time.Second, + } + + go func() { + log.Printf("Starting messenger server (Lab 3, instance=%s) on %s (env=%s, sessionTTL=%ds, idempotencyTTL=%ds, dbMaxConns=%d, writeMode=%s, cacheMode=%s)", + instanceID, addr, appEnv, sessionTTL, idempotencyTTL, maxConns, writeMode, cacheMode) + if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) { + log.Fatalf("ListenAndServe error: %v", err) + } + }() + + <-ctx.Done() + log.Printf("Instance %s received termination signal: marking /health/ready=503 and draining...", instanceID) + apiHandler.SetDraining(true) + + if drainDelayMs > 0 { + time.Sleep(time.Duration(drainDelayMs) * time.Millisecond) + } + + shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + + if err := srv.Shutdown(shutdownCtx); err != nil { + log.Printf("Server shutdown error: %v", err) + } else { + log.Printf("Instance %s stopped gracefully", instanceID) + } +} diff --git a/compose.yaml b/compose.yaml new file mode 100644 index 00000000..5fd28e16 --- /dev/null +++ b/compose.yaml @@ -0,0 +1,153 @@ +x-lab-number: 3 +x-required-roles: + - api + - postgres + - redis + - load_balancer + +services: + postgres: + image: postgres:18-alpine + restart: unless-stopped + environment: + POSTGRES_USER: ${POSTGRES_USER:-messenger} + POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-messenger_lab3_pass} + POSTGRES_DB: ${POSTGRES_DB:-messenger} + PGDATA: /var/lib/postgresql/data/pgdata + volumes: + - pgdata:/var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER:-messenger} -d $${POSTGRES_DB:-messenger}"] + interval: 2s + timeout: 2s + retries: 15 + start_period: 2s + deploy: + resources: + limits: + cpus: "${DB_CPU_LIMIT:-1.0}" + memory: "${DB_MEM_LIMIT:-512M}" + networks: + - backend + + redis: + image: redis:7.4-alpine + restart: unless-stopped + command: ["redis-server", "/usr/local/etc/redis/redis.conf"] + volumes: + - redisdata:/data + - ./infra/redis.conf:/usr/local/etc/redis/redis.conf:ro + healthcheck: + test: ["CMD", "redis-cli", "ping"] + interval: 2s + timeout: 2s + retries: 15 + start_period: 2s + deploy: + resources: + limits: + cpus: "${REDIS_CPU_LIMIT:-0.5}" + memory: "${REDIS_MEM_LIMIT:-256M}" + networks: + - backend + + migrate: + build: + context: . + dockerfile: Dockerfile + image: mtusi-messenger:lab3 + entrypoint: ["/app/messenger", "-migrate-only"] + restart: "no" + environment: + DATABASE_URL_FILE: ${DATABASE_URL_FILE:-/run/secrets/database_url} + DATABASE_URL: ${DATABASE_URL:-postgres://messenger:messenger_lab3_pass@postgres:5432/messenger?sslmode=disable} + CACHE_URL_FILE: ${CACHE_URL_FILE:-/run/secrets/cache_url} + CACHE_URL: ${CACHE_URL:-redis://redis:6379/0} + MIGRATIONS_DIR: /app/migrations + depends_on: + postgres: + condition: service_healthy + deploy: + resources: + limits: + cpus: "0.5" + memory: "128M" + networks: + - backend + + api: + build: + context: . + dockerfile: Dockerfile + image: mtusi-messenger:lab3 + restart: unless-stopped + stop_grace_period: 10s + environment: + APP_HOST: 0.0.0.0 + APP_PORT: 8080 + APP_ENV: ${APP_ENV:-lab} + SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600} + IDEMPOTENCY_TTL_SECONDS: ${IDEMPOTENCY_TTL_SECONDS:-86400} + SESSION_STORE: ${SESSION_STORE:-redis} + RUN_MIGRATIONS: "false" + MIGRATIONS_DIR: /app/migrations + SHUTDOWN_DRAIN_DELAY_MS: ${SHUTDOWN_DRAIN_DELAY_MS:-1500} + DATABASE_URL_FILE: ${DATABASE_URL_FILE:-/run/secrets/database_url} + DATABASE_URL: ${DATABASE_URL:-postgres://messenger:messenger_lab3_pass@postgres:5432/messenger?sslmode=disable} + CACHE_URL_FILE: ${CACHE_URL_FILE:-/run/secrets/cache_url} + CACHE_URL: ${CACHE_URL:-redis://redis:6379/0} + DB_MAX_CONNS: ${DB_MAX_CONNS:-12} + DB_MIN_CONNS: ${DB_MIN_CONNS:-2} + DB_QUERY_TIMEOUT_MS: ${DB_QUERY_TIMEOUT_MS:-5000} + CACHE_MODE: ${CACHE_MODE:-write_through_versioned} + WRITE_MODE: ${WRITE_MODE:-pipeline} + depends_on: + postgres: + condition: service_healthy + redis: + condition: service_healthy + migrate: + condition: service_completed_successfully + deploy: + replicas: ${API_REPLICAS:-2} + resources: + limits: + cpus: "${API_CPU_LIMIT:-1.0}" + memory: "${API_MEM_LIMIT:-256M}" + networks: + - backend + + lb: + image: haproxy:3.0-alpine + restart: unless-stopped + ports: + - "${APP_PORT:-8080}:80" + volumes: + - ./infra/haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro + healthcheck: + test: ["CMD-SHELL", "haproxy -c -f /usr/local/etc/haproxy/haproxy.cfg && kill -0 1"] + interval: 2s + timeout: 2s + retries: 10 + start_period: 1s + depends_on: + api: + condition: service_healthy + deploy: + resources: + limits: + cpus: "${LB_CPU_LIMIT:-0.5}" + memory: "${LB_MEM_LIMIT:-128M}" + networks: + - backend + +volumes: + pgdata: + name: mtusi_lab3_pgdata + redisdata: + name: mtusi_lab3_redisdata + +networks: + backend: + name: mtusi_lab3_backend + driver: bridge diff --git a/evidence/grade4_checks.json b/evidence/grade4_checks.json new file mode 100644 index 00000000..f4f4f0b9 --- /dev/null +++ b/evidence/grade4_checks.json @@ -0,0 +1,100 @@ +{ + "timestamp_utc": "2026-11-16T23:23:25Z", + "base_url": "http://localhost:8080", + "checks": { + "infra_and_migrations": { + "status": "PASS", + "api_replicas": 2, + "containers": [ + { + "name": "lab3-api-1", + "short_id": "c867ff33ee47", + "nano_cpus": 1000000000, + "memory": 268435456 + }, + { + "name": "lab3-api-2", + "short_id": "a8fb03f322c9", + "nano_cpus": 1000000000, + "memory": 268435456 + } + ], + "applied_migrations": [ + "001_init.sql", + "002_idempotency.sql" + ] + }, + "stateless_sessions": { + "status": "PASS", + "observed_instances": [ + "a8fb03f322c9", + "c867ff33ee47" + ] + }, + "concurrent_idempotency": { + "status": "PASS", + "concurrent_requests": 20, + "unique_message_ids": 1, + "replicas_involved": [ + "a8fb03f322c9", + "c867ff33ee47" + ], + "canonical_json_replay": "201_same_id", + "different_body_conflict": 409, + "scope_isolation_verified": true + }, + "sequential_failover": { + "status": "PASS", + "replica_1_failover": { + "stopped_container": "lab3-api-1", + "stopped_short_id": "c867ff33ee47", + "stop_duration_s": 1.976, + "total_requests": 1354, + "successful_writes": 1354, + "failed_requests": 0, + "error_rate": 0.0, + "rps": 135.4, + "recovery_seconds_after_stop": 0.0, + "serving_instances_after_failover": [ + "a8fb03f322c9" + ] + }, + "replica_2_failover": { + "stopped_container": "lab3-api-2", + "stopped_short_id": "a8fb03f322c9", + "stop_duration_s": 1.952, + "total_requests": 1354, + "successful_writes": 1354, + "failed_requests": 0, + "error_rate": 0.0, + "rps": 135.4, + "recovery_seconds_after_stop": 0.0, + "serving_instances_after_failover": [ + "c867ff33ee47" + ] + } + }, + "rolling_update": { + "status": "PASS", + "old_replicas": [ + "c867ff33ee47", + "a8fb03f322c9" + ], + "new_replicas": [ + "6ab8d90bddf4", + "ce8d6d71f25b" + ], + "total_requests_during_rollout": 1476, + "successful_writes": 1476, + "failed_requests": 0, + "error_rate": 0.0, + "observed_serving_instances": [ + "6ab8d90bddf4", + "a8fb03f322c9", + "bad8d000caaf", + "c867ff33ee47", + "ce8d6d71f25b" + ] + } + } +} diff --git a/evidence/load.json b/evidence/load.json new file mode 100644 index 00000000..82755fb1 --- /dev/null +++ b/evidence/load.json @@ -0,0 +1,17 @@ +{ + "lab": 3, + "workload": "closed-loop POST messages; no automatic retries", + "requested_duration_seconds": 15.0, + "elapsed_seconds": 15.006, + "concurrency": 4, + "successful_requests": 11922, + "failed_requests": 0, + "error_ratio": 0.0, + "successful_rps": 794.485, + "successful_latency_ms": { + "p50": 4.182, + "p95": 8.602, + "p99": 20.762 + }, + "note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead." +} diff --git a/evidence/track1_scaling.json b/evidence/track1_scaling.json new file mode 100644 index 00000000..632a6c57 --- /dev/null +++ b/evidence/track1_scaling.json @@ -0,0 +1,475 @@ +{ + "timestamp_utc": "2026-11-16T23:28:36Z", + "base_url": "http://localhost:8080", + "series_a_fixed_budget": [ + { + "label": "A_fixed_1x2.0cpu", + "concurrency": 16, + "warmup_s": 2.0, + "duration_s": 10.0, + "successful_requests": 10167, + "failed_requests": 0, + "error_rate": 0.0, + "successful_rps": 1016.7, + "latency_ms": { + "p50": 7.743, + "p95": 64.197, + "p99": 76.235 + }, + "write_latency_ms": { + "p50": 8.103, + "p95": 61.874, + "p99": 72.681 + }, + "observed_instances": [ + "d1f5ae9c67a0" + ], + "container_stats_midpoint": { + "lab3-api-4": { + "cpu": "204.46%", + "mem": "109.5MiB / 512MiB" + }, + "lab3-postgres-1": { + "cpu": "90.21%", + "mem": "60.12MiB / 512MiB" + }, + "lab3-lb-1": { + "cpu": "23.66%", + "mem": "12.02MiB / 128MiB" + }, + "lab3-redis-1": { + "cpu": "18.14%", + "mem": "10.02MiB / 256MiB" + } + }, + "config": { + "replicas": 1, + "api_cpu": "2.0", + "api_mem": "512M", + "db_cpu": "1.0", + "db_max_conns": 12, + "write_mode": "pipeline" + } + }, + { + "label": "A_fixed_2x1.0cpu", + "concurrency": 16, + "warmup_s": 2.0, + "duration_s": 10.0, + "successful_requests": 8251, + "failed_requests": 0, + "error_rate": 0.0, + "successful_rps": 825.1, + "latency_ms": { + "p50": 8.609, + "p95": 70.592, + "p99": 83.034 + }, + "write_latency_ms": { + "p50": 8.723, + "p95": 69.283, + "p99": 78.026 + }, + "observed_instances": [ + "47f831cff243", + "e2833dd332ac" + ], + "container_stats_midpoint": { + "lab3-api-4": { + "cpu": "66.98%", + "mem": "72.71MiB / 256MiB" + }, + "lab3-api-5": { + "cpu": "77.18%", + "mem": "111.4MiB / 256MiB" + }, + "lab3-postgres-1": { + "cpu": "98.70%", + "mem": "92.31MiB / 512MiB" + }, + "lab3-lb-1": { + "cpu": "20.98%", + "mem": "12.11MiB / 128MiB" + }, + "lab3-redis-1": { + "cpu": "14.07%", + "mem": "16.46MiB / 256MiB" + } + }, + "config": { + "replicas": 2, + "api_cpu": "1.0", + "api_mem": "256M", + "db_cpu": "1.0", + "db_max_conns": 12, + "write_mode": "pipeline" + } + }, + { + "label": "A_fixed_4x0.5cpu", + "concurrency": 16, + "warmup_s": 2.0, + "duration_s": 10.0, + "successful_requests": 4136, + "failed_requests": 15, + "error_rate": 0.00361, + "successful_rps": 413.6, + "latency_ms": { + "p50": 6.478, + "p95": 96.023, + "p99": 381.832 + }, + "write_latency_ms": { + "p50": 6.604, + "p95": 93.106, + "p99": 291.795 + }, + "observed_instances": [ + "013ea6fc7ada", + "27e20311dd72", + "34f340969648", + "7308b4384c4e" + ], + "container_stats_midpoint": { + "lab3-api-7": { + "cpu": "48.76%", + "mem": "89.36MiB / 128MiB" + }, + "lab3-api-6": { + "cpu": "41.39%", + "mem": "66.79MiB / 128MiB" + }, + "lab3-api-4": { + "cpu": "31.12%", + "mem": "50.61MiB / 128MiB" + }, + "lab3-api-5": { + "cpu": "47.21%", + "mem": "50.73MiB / 128MiB" + }, + "lab3-postgres-1": { + "cpu": "79.92%", + "mem": "127.8MiB / 512MiB" + }, + "lab3-lb-1": { + "cpu": "22.45%", + "mem": "12.26MiB / 128MiB" + }, + "lab3-redis-1": { + "cpu": "15.51%", + "mem": "13.5MiB / 256MiB" + } + }, + "config": { + "replicas": 4, + "api_cpu": "0.5", + "api_mem": "128M", + "db_cpu": "1.0", + "db_max_conns": 12, + "write_mode": "pipeline" + } + } + ], + "series_b_resource_growth": [ + { + "label": "B_growth_1x0.5cpu", + "concurrency": 20, + "warmup_s": 2.0, + "duration_s": 10.0, + "successful_requests": 475, + "failed_requests": 20, + "error_rate": 0.0404, + "successful_rps": 47.5, + "latency_ms": { + "p50": 99.276, + "p95": 798.93, + "p99": 2700.523 + }, + "write_latency_ms": { + "p50": 99.501, + "p95": 686.458, + "p99": 1105.625 + }, + "observed_instances": [ + "a97c17fb53be" + ], + "container_stats_midpoint": { + "lab3-api-7": { + "cpu": "49.44%", + "mem": "256MiB / 256MiB" + }, + "lab3-postgres-1": { + "cpu": "5.02%", + "mem": "79.31MiB / 256MiB" + }, + "lab3-lb-1": { + "cpu": "1.23%", + "mem": "12.05MiB / 128MiB" + }, + "lab3-redis-1": { + "cpu": "2.24%", + "mem": "11.62MiB / 256MiB" + } + }, + "config": { + "replicas": 1, + "api_cpu": "0.5", + "api_mem": "256M", + "db_cpu": "0.5", + "db_max_conns": 25, + "write_mode": "sequential" + } + }, + { + "label": "B_growth_2x0.5cpu", + "concurrency": 20, + "warmup_s": 2.0, + "duration_s": 10.0, + "successful_requests": 3535, + "failed_requests": 0, + "error_rate": 0.0, + "successful_rps": 353.5, + "latency_ms": { + "p50": 34.665, + "p95": 178.069, + "p99": 304.304 + }, + "write_latency_ms": { + "p50": 42.344, + "p95": 172.567, + "p99": 242.902 + }, + "observed_instances": [ + "75a22aba6330", + "e3031c19102f" + ], + "container_stats_midpoint": { + "lab3-api-8": { + "cpu": "50.45%", + "mem": "110MiB / 256MiB" + }, + "lab3-api-7": { + "cpu": "40.02%", + "mem": "92.32MiB / 256MiB" + }, + "lab3-postgres-1": { + "cpu": "48.57%", + "mem": "121.2MiB / 256MiB" + }, + "lab3-lb-1": { + "cpu": "14.47%", + "mem": "12.23MiB / 128MiB" + }, + "lab3-redis-1": { + "cpu": "9.09%", + "mem": "7.293MiB / 256MiB" + } + }, + "config": { + "replicas": 2, + "api_cpu": "0.5", + "api_mem": "256M", + "db_cpu": "0.5", + "db_max_conns": 25, + "write_mode": "sequential" + } + }, + { + "label": "B_growth_4x0.5cpu", + "concurrency": 20, + "warmup_s": 2.0, + "duration_s": 10.0, + "successful_requests": 3708, + "failed_requests": 0, + "error_rate": 0.0, + "successful_rps": 370.8, + "latency_ms": { + "p50": 77.491, + "p95": 102.152, + "p99": 201.116 + }, + "write_latency_ms": { + "p50": 84.726, + "p95": 101.072, + "p99": 197.338 + }, + "observed_instances": [ + "3cd92787b764", + "7ad8aa4cd84d", + "c482f4ae4a13", + "fde039fce7f3" + ], + "container_stats_midpoint": { + "lab3-api-9": { + "cpu": "22.60%", + "mem": "81.24MiB / 256MiB" + }, + "lab3-api-7": { + "cpu": "19.11%", + "mem": "52.75MiB / 256MiB" + }, + "lab3-api-8": { + "cpu": "18.79%", + "mem": "49.17MiB / 256MiB" + }, + "lab3-api-10": { + "cpu": "35.11%", + "mem": "51.89MiB / 256MiB" + }, + "lab3-postgres-1": { + "cpu": "48.70%", + "mem": "129.6MiB / 256MiB" + }, + "lab3-lb-1": { + "cpu": "13.64%", + "mem": "12.3MiB / 128MiB" + }, + "lab3-redis-1": { + "cpu": "7.01%", + "mem": "8.988MiB / 256MiB" + } + }, + "config": { + "replicas": 4, + "api_cpu": "0.5", + "api_mem": "256M", + "db_cpu": "0.5", + "db_max_conns": 25, + "write_mode": "sequential" + } + } + ], + "confirmed_improvement": { + "change": "Enabled pgx.Batch SQL pipelining in CreateMessage tx (5 RTT -> 2 RTT) and tuned DB_MAX_CONNS per replica (25 -> 8, limiting total connections from 100 to 32 against 0.5 CPU PostgreSQL)", + "before": { + "label": "B_growth_4x0.5cpu", + "concurrency": 20, + "warmup_s": 2.0, + "duration_s": 10.0, + "successful_requests": 3708, + "failed_requests": 0, + "error_rate": 0.0, + "successful_rps": 370.8, + "latency_ms": { + "p50": 77.491, + "p95": 102.152, + "p99": 201.116 + }, + "write_latency_ms": { + "p50": 84.726, + "p95": 101.072, + "p99": 197.338 + }, + "observed_instances": [ + "3cd92787b764", + "7ad8aa4cd84d", + "c482f4ae4a13", + "fde039fce7f3" + ], + "container_stats_midpoint": { + "lab3-api-9": { + "cpu": "22.60%", + "mem": "81.24MiB / 256MiB" + }, + "lab3-api-7": { + "cpu": "19.11%", + "mem": "52.75MiB / 256MiB" + }, + "lab3-api-8": { + "cpu": "18.79%", + "mem": "49.17MiB / 256MiB" + }, + "lab3-api-10": { + "cpu": "35.11%", + "mem": "51.89MiB / 256MiB" + }, + "lab3-postgres-1": { + "cpu": "48.70%", + "mem": "129.6MiB / 256MiB" + }, + "lab3-lb-1": { + "cpu": "13.64%", + "mem": "12.3MiB / 128MiB" + }, + "lab3-redis-1": { + "cpu": "7.01%", + "mem": "8.988MiB / 256MiB" + } + }, + "config": { + "replicas": 4, + "api_cpu": "0.5", + "api_mem": "256M", + "db_cpu": "0.5", + "db_max_conns": 25, + "write_mode": "sequential" + } + }, + "after": { + "label": "C_optimized_4x0.5cpu", + "concurrency": 20, + "warmup_s": 2.0, + "duration_s": 10.0, + "successful_requests": 5102, + "failed_requests": 0, + "error_rate": 0.0, + "successful_rps": 510.2, + "latency_ms": { + "p50": 13.231, + "p95": 97.004, + "p99": 144.243 + }, + "write_latency_ms": { + "p50": 16.821, + "p95": 96.413, + "p99": 111.9 + }, + "observed_instances": [ + "29eecd023183", + "9a2732d149d4", + "a0778eaa9365", + "c60ed1a08b60" + ], + "container_stats_midpoint": { + "lab3-api-8": { + "cpu": "29.98%", + "mem": "45.44MiB / 256MiB" + }, + "lab3-api-7": { + "cpu": "34.58%", + "mem": "68.11MiB / 256MiB" + }, + "lab3-api-9": { + "cpu": "32.71%", + "mem": "73.15MiB / 256MiB" + }, + "lab3-api-10": { + "cpu": "35.22%", + "mem": "51.48MiB / 256MiB" + }, + "lab3-postgres-1": { + "cpu": "55.39%", + "mem": "112.9MiB / 256MiB" + }, + "lab3-lb-1": { + "cpu": "18.64%", + "mem": "12.34MiB / 128MiB" + }, + "lab3-redis-1": { + "cpu": "11.78%", + "mem": "10.29MiB / 256MiB" + } + }, + "config": { + "replicas": 4, + "api_cpu": "0.5", + "api_mem": "256M", + "db_cpu": "0.5", + "db_max_conns": 8, + "write_mode": "pipeline" + } + }, + "rps_change_percent": 37.59, + "p95_latency_change_percent": -5.04 + } +} diff --git a/evidence/track1_scaling_chart.svg b/evidence/track1_scaling_chart.svg new file mode 100644 index 00000000..30d8b0ef --- /dev/null +++ b/evidence/track1_scaling_chart.svg @@ -0,0 +1,37 @@ + + Lab 3 Track 1: Cost of Scaling & Saturation Point (RPS) + + + + 0 + + 254 + + 508 + + 763 + + 1017 + + 1016.7 + A: 1x2.0c + + 825.1 + A: 2x1.0c + + 413.6 + A: 4x0.5c + + 47.5 + B: 1x0.5c + + 353.5 + B: 2x0.5c + + 370.8 + B: 4x0.5c + + 510.2 + Opt: 4x0.5c + Blue: Fixed 2.0 CPU Budget | Green: Resource Growth | Orange: DB Saturation | Purple: Batch Pipeline + Pool Tuning + diff --git a/go.mod b/go.mod new file mode 100644 index 00000000..116e71f6 --- /dev/null +++ b/go.mod @@ -0,0 +1,21 @@ +module messenger + +go 1.24 + +require ( + github.com/google/uuid v1.6.0 + github.com/jackc/pgx/v5 v5.7.2 + github.com/redis/go-redis/v9 v9.17.2 + golang.org/x/crypto v0.33.0 + golang.org/x/sync v0.11.0 +) + +require ( + github.com/cespare/xxhash/v2 v2.3.0 // indirect + github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f // indirect + github.com/jackc/pgpassfile v1.0.0 // indirect + github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect + github.com/jackc/puddle/v2 v2.2.2 // indirect + golang.org/x/sys v0.30.0 // indirect + golang.org/x/text v0.22.0 // indirect +) diff --git a/go.sum b/go.sum new file mode 100644 index 00000000..83239343 --- /dev/null +++ b/go.sum @@ -0,0 +1,42 @@ +github.com/bsm/ginkgo/v2 v2.12.0 h1:Ny8MWAHyOepLGlLKYmXG4IEkioBysk6GpaRTLC8zwWs= +github.com/bsm/ginkgo/v2 v2.12.0/go.mod h1:SwYbGRRDovPVboqFv0tPTcG1sN61LM1Z4ARdbAV9g4c= +github.com/bsm/gomega v1.27.10 h1:yeMWxP2pV2fG3FgAODIY8EiRE3dy0aeFYt4l7wh6yKA= +github.com/bsm/gomega v1.27.10/go.mod h1:JyEr/xRbxbtgWNi8tIEVPUYZ5Dzef52k01W3YH0H+O0= +github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs= +github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs= +github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= +github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= +github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= +github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f h1:lO4WD4F/rVNCu3HqELle0jiPLLBs70cWOduZpkS1E78= +github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f/go.mod h1:cuUVRXasLTGF7a8hSLbxyZXjz+1KgoB3wDUb6vlszIc= +github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0= +github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo= +github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM= +github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg= +github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo= +github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM= +github.com/jackc/pgx/v5 v5.7.2 h1:mLoDLV6sonKlvjIEsV56SkWNCnuNv531l94GaIzO+XI= +github.com/jackc/pgx/v5 v5.7.2/go.mod h1:ncY89UGWxg82EykZUwSpUKEfccBGGYq1xjrOpsbsfGQ= +github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo= +github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4= +github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= +github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= +github.com/redis/go-redis/v9 v9.17.2 h1:P2EGsA4qVIM3Pp+aPocCJ7DguDHhqrXNhVcEp4ViluI= +github.com/redis/go-redis/v9 v9.17.2/go.mod h1:u410H11HMLoB+TP67dz8rL9s6QW2j76l0//kSOd3370= +github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME= +github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI= +github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg= +github.com/stretchr/testify v1.8.1 h1:w7B6lhMri9wdJUVmEZPGGhZzrYTPvgJArz7wNPgYKsk= +github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4= +golang.org/x/crypto v0.33.0 h1:IOBPskki6Lysi0lo9qQvbxiQ+FvsCC/YWOecCHAixus= +golang.org/x/crypto v0.33.0/go.mod h1:bVdXmD7IV/4GdElGPozy6U7lWdRXA4qyRVGJV57uQ5M= +golang.org/x/sync v0.11.0 h1:GGz8+XQP4FvTTrjZPzNKTMFtSXH80RAzG+5ghFPgK9w= +golang.org/x/sync v0.11.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk= +golang.org/x/sys v0.30.0 h1:QjkSwP/36a20jFYWkSue1YwXzLmsV5Gfq7Eiy72C1uc= +golang.org/x/sys v0.30.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA= +golang.org/x/text v0.22.0 h1:bofq7m3/HAFvbF51jz3Q9wLg3jkvSPuiZu/pD1XwgtM= +golang.org/x/text v0.22.0/go.mod h1:YRoo4H8PVmsu+E3Ou7cqLVH8oXWIHVoX0jqUWALQhfY= +gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= +gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= +gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= +gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= diff --git a/infra/haproxy.cfg b/infra/haproxy.cfg new file mode 100644 index 00000000..5202e2f8 --- /dev/null +++ b/infra/haproxy.cfg @@ -0,0 +1,40 @@ +global + log stdout format raw local0 + maxconn 4096 + +defaults + mode http + log global + option httplog + option dontlognull + option redispatch + retries 2 + timeout connect 2s + timeout client 30s + timeout server 30s + timeout check 1500ms + +resolvers docker_dns + nameserver dns 127.0.0.11:53 + resolve_retries 3 + timeout resolve 1s + timeout retry 1s + hold other 2s + hold refused 2s + hold nx 2s + hold timeout 2s + hold valid 2s + hold obsolete 2s + +frontend http_front + bind *:80 + default_backend api_back + +backend api_back + balance roundrobin + http-reuse safe + option httpchk + http-check send meth GET uri /health/ready ver HTTP/1.1 hdr Host localhost + http-check expect status 200 + default-server inter 1s fastinter 500ms downinter 1s fall 2 rise 1 resolvers docker_dns resolve-prefer ipv4 init-addr none maxconn 256 + server-template api 1-8 api:8080 check diff --git a/infra/redis.conf b/infra/redis.conf new file mode 100644 index 00000000..5be985c3 --- /dev/null +++ b/infra/redis.conf @@ -0,0 +1,14 @@ +# Redis 7.4 configuration for MTUCI Lab 3 (Shared Sessions + History Cache) +bind 0.0.0.0 +port 6379 +protected-mode no + +# Durable persistence (AOF + RDB snapshot) so cached sessions survive container restarts +appendonly yes +appendfilename "appendonly.aof" +appendfsync everysec +save 60 1 + +# Memory limits +maxmemory 128mb +maxmemory-policy volatile-lru diff --git a/internal/auth/password.go b/internal/auth/password.go new file mode 100644 index 00000000..93a39697 --- /dev/null +++ b/internal/auth/password.go @@ -0,0 +1,108 @@ +package auth + +import ( + "crypto/rand" + "crypto/sha256" + "crypto/subtle" + "encoding/base64" + "encoding/hex" + "errors" + "fmt" + "strings" + + "golang.org/x/crypto/argon2" +) + +const ( + argonTime uint32 = 1 + argonMemory uint32 = 19 * 1024 // 19 MiB (OWASP interactive recommendation) + argonThreads uint8 = 2 + argonKeyLen uint32 = 32 + argonSaltLen int = 16 +) + +var dummyHash string + +func init() { + h, err := HashPassword("dummy-password-for-constant-time-check") + if err == nil { + dummyHash = h + } +} + +// HashPassword hashes a UTF-8 password using Argon2id and returns a PHC-formatted string. +func HashPassword(password string) (string, error) { + salt := make([]byte, argonSaltLen) + if _, err := rand.Read(salt); err != nil { + return "", fmt.Errorf("failed to generate salt: %w", err) + } + + hash := argon2.IDKey([]byte(password), salt, argonTime, argonMemory, argonThreads, argonKeyLen) + + b64Salt := base64.RawStdEncoding.EncodeToString(salt) + b64Hash := base64.RawStdEncoding.EncodeToString(hash) + + encoded := fmt.Sprintf("$argon2id$v=%d$m=%d,t=%d,p=%d$%s$%s", + argon2.Version, argonMemory, argonTime, argonThreads, b64Salt, b64Hash) + return encoded, nil +} + +// VerifyPassword compares a UTF-8 password against an Argon2id PHC string in constant time. +func VerifyPassword(password, encodedHash string) (bool, error) { + parts := strings.Split(encodedHash, "$") + if len(parts) != 6 || parts[1] != "argon2id" { + return false, errors.New("invalid argon2id hash format") + } + + var version int + if _, err := fmt.Sscanf(parts[2], "v=%d", &version); err != nil { + return false, err + } + + var memory, timeCost uint32 + var threads uint8 + if _, err := fmt.Sscanf(parts[3], "m=%d,t=%d,p=%d", &memory, &timeCost, &threads); err != nil { + return false, err + } + + salt, err := base64.RawStdEncoding.DecodeString(parts[4]) + if err != nil { + return false, err + } + + expectedHash, err := base64.RawStdEncoding.DecodeString(parts[5]) + if err != nil { + return false, err + } + + computedHash := argon2.IDKey([]byte(password), salt, timeCost, memory, threads, uint32(len(expectedHash))) + if subtle.ConstantTimeCompare(computedHash, expectedHash) == 1 { + return true, nil + } + return false, nil +} + +// VerifyDummy runs an Argon2id verification against a dummy hash to prevent timing attacks on unknown usernames. +func VerifyDummy(password string) { + if dummyHash != "" { + _, _ = VerifyPassword(password, dummyHash) + } +} + +// GenerateSessionToken generates an opaque 256-bit (32-byte) random token encoded as 64 hex chars, +// along with its SHA-256 hex digest for storage. +func GenerateSessionToken() (rawToken string, tokenHash string, err error) { + buf := make([]byte, 32) // 256 bits of entropy + if _, err := rand.Read(buf); err != nil { + return "", "", fmt.Errorf("failed to generate random token: %w", err) + } + rawToken = hex.EncodeToString(buf) + tokenHash = HashToken(rawToken) + return rawToken, tokenHash, nil +} + +// HashToken returns the lowercase SHA-256 hex digest of an opaque session token. +func HashToken(rawToken string) string { + sum := sha256.Sum256([]byte(rawToken)) + return hex.EncodeToString(sum[:]) +} diff --git a/internal/auth/password_test.go b/internal/auth/password_test.go new file mode 100644 index 00000000..61e06519 --- /dev/null +++ b/internal/auth/password_test.go @@ -0,0 +1,43 @@ +package auth + +import ( + "strings" + "testing" +) + +func TestHashAndVerifyPassword(t *testing.T) { + pw := "Сложный:Пароль:С:Двоеточиями:2026!🚀" + hash, err := HashPassword(pw) + if err != nil { + t.Fatalf("HashPassword failed: %v", err) + } + if !strings.HasPrefix(hash, "$argon2id$v=19$") { + t.Fatalf("expected Argon2id PHC prefix, got: %s", hash) + } + + ok, err := VerifyPassword(pw, hash) + if err != nil || !ok { + t.Fatalf("expected password verification to succeed, err=%v, ok=%v", err, ok) + } + + okWrong, err := VerifyPassword("WrongPassword-12345!", hash) + if err != nil || okWrong { + t.Fatalf("expected wrong password to fail verification") + } +} + +func TestGenerateSessionToken(t *testing.T) { + raw, hash, err := GenerateSessionToken() + if err != nil { + t.Fatalf("GenerateSessionToken failed: %v", err) + } + if len(raw) != 64 { + t.Fatalf("expected 64-char hex raw token (256-bit), got len=%d", len(raw)) + } + if len(hash) != 64 { + t.Fatalf("expected 64-char SHA-256 hex digest, got len=%d", len(hash)) + } + if HashToken(raw) != hash { + t.Fatalf("HashToken mismatch") + } +} diff --git a/internal/handler/handler.go b/internal/handler/handler.go new file mode 100644 index 00000000..4f1734a7 --- /dev/null +++ b/internal/handler/handler.go @@ -0,0 +1,451 @@ +package handler + +import ( + _ "embed" + "encoding/base64" + "encoding/json" + "errors" + "fmt" + "io" + "net/http" + "strconv" + "strings" + "sync/atomic" + "unicode/utf8" + + "github.com/google/uuid" + "messenger/internal/model" + "messenger/internal/store" +) + +//go:embed openapi.json +var openAPISpec []byte + +const swaggerUIHTML = ` + + + + + MTUCI Messenger API (Lab 3) - Swagger UI + + + + +
+ + + +` + +type APIHandler struct { + store store.Store + sessionTTL int + idempotencyTTL int + instanceID string + draining atomic.Bool +} + +func NewAPIHandler(st store.Store, sessionTTL, idempotencyTTL int, instanceID string) *APIHandler { + if sessionTTL <= 0 { + sessionTTL = 3600 + } + if idempotencyTTL <= 0 { + idempotencyTTL = 86400 + } + return &APIHandler{ + store: st, + sessionTTL: sessionTTL, + idempotencyTTL: idempotencyTTL, + instanceID: instanceID, + } +} + +func (h *APIHandler) SetDraining(v bool) { + h.draining.Store(v) +} + +func (h *APIHandler) IsDraining() bool { + return h.draining.Load() +} + +func decodeJSON(r *http.Request, dst interface{}) error { + if r.Body == nil { + return errors.New("request body is missing") + } + defer r.Body.Close() + + dec := json.NewDecoder(r.Body) + dec.DisallowUnknownFields() + + if err := dec.Decode(dst); err != nil { + if errors.Is(err, io.EOF) { + return errors.New("request body is empty") + } + var unmarshalTypeError *json.UnmarshalTypeError + if errors.As(err, &unmarshalTypeError) { + return fmt.Errorf("field '%s' has incorrect type (expected %s)", unmarshalTypeError.Field, unmarshalTypeError.Type) + } + return fmt.Errorf("malformed JSON or unexpected field: %v", err) + } + + if dec.More() { + return errors.New("request body contains multiple JSON values") + } + + return nil +} + +func writeStoreError(w http.ResponseWriter, r *http.Request, err error) { + switch { + case errors.Is(err, store.ErrConflict): + WriteError(w, r, http.StatusConflict, "conflict", "resource conflict") + case errors.Is(err, store.ErrNotFound): + WriteError(w, r, http.StatusNotFound, "not_found", "resource not found or access denied") + case errors.Is(err, store.ErrUnauthorized): + WriteBearerUnauthorized(w, r, "unauthorized") + case errors.Is(err, store.ErrUnavailable): + WriteError(w, r, http.StatusServiceUnavailable, "unavailable", "storage dependency is temporarily unavailable") + case errors.Is(err, store.ErrBadRequest): + WriteError(w, r, http.StatusBadRequest, "invalid_request", err.Error()) + default: + WriteError(w, r, http.StatusInternalServerError, "internal_error", "internal server error") + } +} + +func (h *APIHandler) HandleLiveness(w http.ResponseWriter, r *http.Request) { + WriteJSON(w, r, http.StatusOK, model.HealthResponse{Status: "ok"}) +} + +func (h *APIHandler) HandleReadiness(w http.ResponseWriter, r *http.Request) { + if h.IsDraining() { + WriteError(w, r, http.StatusServiceUnavailable, "unavailable", "instance is draining") + return + } + if err := h.store.Ready(r.Context()); err != nil { + WriteError(w, r, http.StatusServiceUnavailable, "unavailable", "database dependency is not ready") + return + } + WriteJSON(w, r, http.StatusOK, model.HealthResponse{Status: "ok"}) +} + +func (h *APIHandler) HandleRegisterUser(w http.ResponseWriter, r *http.Request) { + var req model.CreateUserRequest + if err := decodeJSON(r, &req); err != nil { + WriteError(w, r, http.StatusBadRequest, "invalid_request", err.Error()) + return + } + + user, err := h.store.CreateUser(r.Context(), req) + if err != nil { + writeStoreError(w, r, err) + return + } + + WriteJSON(w, r, http.StatusCreated, user) +} + +func (h *APIHandler) HandleCreateSession(w http.ResponseWriter, r *http.Request) { + // Contract: POST /auth/sessions accepts ONLY Authorization: Basic , without JSON body. + if r.Body != nil { + defer r.Body.Close() + var buf [1]byte + n, _ := r.Body.Read(buf[:]) + if n > 0 { + WriteError(w, r, http.StatusBadRequest, "invalid_request", "POST /api/v1/auth/sessions must not include a request body") + return + } + } + + authHeader := strings.TrimSpace(r.Header.Get("Authorization")) + if authHeader == "" { + WriteBasicUnauthorized(w, r, "invalid credentials") + return + } + + parts := strings.SplitN(authHeader, " ", 2) + if len(parts) != 2 || !strings.EqualFold(parts[0], "Basic") { + WriteBasicUnauthorized(w, r, "invalid credentials") + return + } + + b64Payload := strings.TrimSpace(parts[1]) + decoded, err := base64.StdEncoding.DecodeString(b64Payload) + if err != nil || !utf8.Valid(decoded) { + WriteBasicUnauthorized(w, r, "invalid credentials") + return + } + + credParts := strings.SplitN(string(decoded), ":", 2) + if len(credParts) != 2 { + WriteBasicUnauthorized(w, r, "invalid credentials") + return + } + + username := credParts[0] + password := credParts[1] + + sess, err := h.store.AuthenticateAndCreateSession(r.Context(), username, password, h.sessionTTL) + if err != nil { + if errors.Is(err, store.ErrUnavailable) { + WriteError(w, r, http.StatusServiceUnavailable, "unavailable", "storage dependency is temporarily unavailable") + return + } + WriteBasicUnauthorized(w, r, "invalid credentials") + return + } + + WriteJSON(w, r, http.StatusCreated, sess) +} + +func (h *APIHandler) HandleRevokeSession(w http.ResponseWriter, r *http.Request) { + rawToken := GetAuthToken(r.Context()) + if rawToken == "" { + WriteBearerUnauthorized(w, r, "unauthenticated") + return + } + + if err := h.store.RevokeSession(r.Context(), rawToken); err != nil { + if errors.Is(err, store.ErrUnavailable) { + WriteError(w, r, http.StatusServiceUnavailable, "unavailable", "storage dependency is temporarily unavailable") + return + } + WriteBearerUnauthorized(w, r, "session already revoked or expired") + return + } + + reqID := GetRequestID(r.Context()) + w.Header().Set("X-Request-Id", reqID) + w.WriteHeader(http.StatusNoContent) +} + +func (h *APIHandler) HandleCurrentUser(w http.ResponseWriter, r *http.Request) { + user := GetAuthUser(r.Context()) + if user == nil { + WriteBearerUnauthorized(w, r, "unauthenticated") + return + } + WriteJSON(w, r, http.StatusOK, user) +} + +func (h *APIHandler) HandleCreateChat(w http.ResponseWriter, r *http.Request) { + caller := GetAuthUser(r.Context()) + if caller == nil { + WriteBearerUnauthorized(w, r, "unauthenticated") + return + } + + var req model.CreateChatRequest + if err := decodeJSON(r, &req); err != nil { + WriteError(w, r, http.StatusBadRequest, "invalid_request", err.Error()) + return + } + + chat, err := h.store.CreateChat(r.Context(), caller.ID, req) + if err != nil { + writeStoreError(w, r, err) + return + } + + WriteJSON(w, r, http.StatusCreated, chat) +} + +func (h *APIHandler) HandleListChats(w http.ResponseWriter, r *http.Request) { + caller := GetAuthUser(r.Context()) + if caller == nil { + WriteBearerUnauthorized(w, r, "unauthenticated") + return + } + + limit := 50 + limitStr := r.URL.Query().Get("limit") + if limitStr != "" { + l, err := strconv.Atoi(limitStr) + if err != nil || l < 1 || l > 100 { + WriteError(w, r, http.StatusBadRequest, "invalid_request", "limit must be an integer between 1 and 100") + return + } + limit = l + } + + cursor := r.URL.Query().Get("cursor") + page, err := h.store.ListChats(r.Context(), caller.ID, limit, cursor) + if err != nil { + writeStoreError(w, r, err) + return + } + + WriteJSON(w, r, http.StatusOK, page) +} + +func (h *APIHandler) HandleGetChat(w http.ResponseWriter, r *http.Request) { + caller := GetAuthUser(r.Context()) + if caller == nil { + WriteBearerUnauthorized(w, r, "unauthenticated") + return + } + + chatID := r.PathValue("chat_id") + if _, err := uuid.Parse(chatID); err != nil { + WriteError(w, r, http.StatusBadRequest, "invalid_request", "invalid chat id UUID") + return + } + + chat, err := h.store.GetChat(r.Context(), caller.ID, chatID) + if err != nil { + writeStoreError(w, r, err) + return + } + + WriteJSON(w, r, http.StatusOK, chat) +} + +func (h *APIHandler) HandleCreateMessage(w http.ResponseWriter, r *http.Request) { + caller := GetAuthUser(r.Context()) + if caller == nil { + WriteBearerUnauthorized(w, r, "unauthenticated") + return + } + + chatID := r.PathValue("chat_id") + if _, err := uuid.Parse(chatID); err != nil { + WriteError(w, r, http.StatusBadRequest, "invalid_request", "invalid chat id UUID") + return + } + + idemKey := r.Header.Get("Idempotency-Key") + if !store.IdempotencyKeyRegex.MatchString(idemKey) { + WriteError(w, r, http.StatusBadRequest, "invalid_request", "Idempotency-Key header is required and must match ^[A-Za-z0-9._:-]{1,128}$") + return + } + + var req model.CreateMessageRequest + if err := decodeJSON(r, &req); err != nil { + WriteError(w, r, http.StatusBadRequest, "invalid_request", err.Error()) + return + } + + msg, err := h.store.CreateMessage(r.Context(), caller.ID, chatID, idemKey, h.idempotencyTTL, req) + if err != nil { + writeStoreError(w, r, err) + return + } + + WriteJSON(w, r, http.StatusCreated, msg) +} + +func (h *APIHandler) HandleListMessages(w http.ResponseWriter, r *http.Request) { + caller := GetAuthUser(r.Context()) + if caller == nil { + WriteBearerUnauthorized(w, r, "unauthenticated") + return + } + + chatID := r.PathValue("chat_id") + if _, err := uuid.Parse(chatID); err != nil { + WriteError(w, r, http.StatusBadRequest, "invalid_request", "invalid chat id UUID") + return + } + + limit := 50 + limitStr := r.URL.Query().Get("limit") + if limitStr != "" { + l, err := strconv.Atoi(limitStr) + if err != nil || l < 1 || l > 100 { + WriteError(w, r, http.StatusBadRequest, "invalid_request", "limit must be an integer between 1 and 100") + return + } + limit = l + } + + cursor := r.URL.Query().Get("cursor") + page, err := h.store.ListMessages(r.Context(), caller.ID, chatID, limit, cursor) + if err != nil { + writeStoreError(w, r, err) + return + } + + WriteJSON(w, r, http.StatusOK, page) +} + +func (h *APIHandler) HandleInternalStats(w http.ResponseWriter, r *http.Request) { + if r.URL.Query().Get("reset") == "1" { + h.store.ResetStats() + } + if mode := r.URL.Query().Get("mode"); mode != "" { + h.store.SetCacheMode(mode) + } + WriteJSON(w, r, http.StatusOK, h.store.Stats(r.Context())) +} + +func (h *APIHandler) HandleOpenAPISpec(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Content-Type", "application/json; charset=utf-8") + w.Header().Set("X-Request-Id", GetRequestID(r.Context())) + w.WriteHeader(http.StatusOK) + _, _ = w.Write(openAPISpec) +} + +func (h *APIHandler) HandleSwaggerUI(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Content-Type", "text/html; charset=utf-8") + w.Header().Set("X-Request-Id", GetRequestID(r.Context())) + w.WriteHeader(http.StatusOK) + _, _ = w.Write([]byte(swaggerUIHTML)) +} + +func (h *APIHandler) HandleNotFound(w http.ResponseWriter, r *http.Request) { + WriteError(w, r, http.StatusNotFound, "not_found", fmt.Sprintf("route %s %s not found", r.Method, r.URL.Path)) +} + +func RegisterRoutes(st store.Store, sessionTTL, idempotencyTTL int, instanceID string) (http.Handler, *APIHandler) { + api := NewAPIHandler(st, sessionTTL, idempotencyTTL, instanceID) + mux := http.NewServeMux() + + // Documentation & schema + mux.HandleFunc("GET /docs", api.HandleSwaggerUI) + mux.HandleFunc("GET /docs/", api.HandleSwaggerUI) + mux.HandleFunc("GET /openapi.json", api.HandleOpenAPISpec) + + // Internal diagnostics for experiments + mux.HandleFunc("GET /internal/stats", api.HandleInternalStats) + mux.HandleFunc("POST /internal/stats", api.HandleInternalStats) + + // Public routes + mux.HandleFunc("GET /health/live", api.HandleLiveness) + mux.HandleFunc("GET /health/ready", api.HandleReadiness) + mux.HandleFunc("POST /api/v1/users", api.HandleRegisterUser) + mux.HandleFunc("POST /api/v1/auth/sessions", api.HandleCreateSession) + + // Protected Bearer routes + mux.HandleFunc("DELETE /api/v1/auth/sessions/current", RequireBearerAuth(st, api.HandleRevokeSession)) + mux.HandleFunc("GET /api/v1/users/me", RequireBearerAuth(st, api.HandleCurrentUser)) + mux.HandleFunc("POST /api/v1/chats", RequireBearerAuth(st, api.HandleCreateChat)) + mux.HandleFunc("GET /api/v1/chats", RequireBearerAuth(st, api.HandleListChats)) + mux.HandleFunc("GET /api/v1/chats/{chat_id}", RequireBearerAuth(st, api.HandleGetChat)) + mux.HandleFunc("POST /api/v1/chats/{chat_id}/messages", RequireBearerAuth(st, api.HandleCreateMessage)) + mux.HandleFunc("GET /api/v1/chats/{chat_id}/messages", RequireBearerAuth(st, api.HandleListMessages)) + + // Fallback 404 handler + mux.HandleFunc("/", api.HandleNotFound) + + var handler http.Handler = mux + handler = LoggingMiddleware(instanceID, handler) + handler = RequestIDMiddleware(handler) + handler = InstanceIDMiddleware(instanceID, handler) + + return handler, api +} diff --git a/internal/handler/middleware.go b/internal/handler/middleware.go new file mode 100644 index 00000000..e496fdd7 --- /dev/null +++ b/internal/handler/middleware.go @@ -0,0 +1,168 @@ +package handler + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "net/http" + "os" + "strings" + "time" + + "github.com/google/uuid" + "messenger/internal/model" + "messenger/internal/store" +) + +type contextKey string + +const ( + requestIDContextKey contextKey = "request_id" + userContextKey contextKey = "user" + tokenContextKey contextKey = "token" +) + +type loggingResponseWriter struct { + http.ResponseWriter + statusCode int +} + +func (lrw *loggingResponseWriter) WriteHeader(code int) { + lrw.statusCode = code + lrw.ResponseWriter.WriteHeader(code) +} + +func InstanceIDMiddleware(instanceID string, next http.Handler) http.Handler { + return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("X-Instance-Id", instanceID) + next.ServeHTTP(w, r) + }) +} + +func RequestIDMiddleware(next http.Handler) http.Handler { + return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + reqID := strings.TrimSpace(r.Header.Get("X-Request-Id")) + if reqID == "" { + reqID = uuid.New().String() + } + w.Header().Set("X-Request-Id", reqID) + ctx := context.WithValue(r.Context(), requestIDContextKey, reqID) + next.ServeHTTP(w, r.WithContext(ctx)) + }) +} + +func LoggingMiddleware(instanceID string, next http.Handler) http.Handler { + return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + start := time.Now() + lrw := &loggingResponseWriter{ResponseWriter: w, statusCode: http.StatusOK} + + next.ServeHTTP(lrw, r) + + reqID, _ := r.Context().Value(requestIDContextKey).(string) + duration := time.Since(start) + + logEntry := map[string]interface{}{ + "time": time.Now().UTC().Format(time.RFC3339Nano), + "instance_id": instanceID, + "method": r.Method, + "path": r.URL.Path, + "status": lrw.statusCode, + "duration_ms": float64(duration.Microseconds()) / 1000.0, + "request_id": reqID, + "remote_ip": r.RemoteAddr, + } + logBytes, _ := json.Marshal(logEntry) + fmt.Fprintln(os.Stdout, string(logBytes)) + }) +} + +func GetRequestID(ctx context.Context) string { + if val, ok := ctx.Value(requestIDContextKey).(string); ok && val != "" { + return val + } + return uuid.New().String() +} + +func WriteError(w http.ResponseWriter, r *http.Request, status int, code, message string) { + reqID := GetRequestID(r.Context()) + w.Header().Set("Content-Type", "application/json") + w.Header().Set("X-Request-Id", reqID) + w.WriteHeader(status) + _ = json.NewEncoder(w).Encode(model.ErrorResponse{ + Error: model.ErrorDetail{ + Code: code, + Message: message, + RequestID: reqID, + }, + }) +} + +func WriteBasicUnauthorized(w http.ResponseWriter, r *http.Request, message string) { + w.Header().Set("WWW-Authenticate", `Basic realm="messenger", charset="UTF-8"`) + WriteError(w, r, http.StatusUnauthorized, "unauthorized", message) +} + +func WriteBearerUnauthorized(w http.ResponseWriter, r *http.Request, message string) { + w.Header().Set("WWW-Authenticate", `Bearer realm="messenger"`) + WriteError(w, r, http.StatusUnauthorized, "unauthorized", message) +} + +func WriteJSON(w http.ResponseWriter, r *http.Request, status int, data interface{}) { + reqID := GetRequestID(r.Context()) + w.Header().Set("Content-Type", "application/json") + w.Header().Set("X-Request-Id", reqID) + w.WriteHeader(status) + _ = json.NewEncoder(w).Encode(data) +} + +func RequireBearerAuth(st store.Store, next http.HandlerFunc) http.HandlerFunc { + return func(w http.ResponseWriter, r *http.Request) { + // Note: X-User-Id is intentionally ignored in Lab 2+ per contract. + authHeader := strings.TrimSpace(r.Header.Get("Authorization")) + if authHeader == "" { + WriteBearerUnauthorized(w, r, "missing Authorization header") + return + } + + parts := strings.SplitN(authHeader, " ", 2) + if len(parts) != 2 || !strings.EqualFold(parts[0], "Bearer") { + WriteBearerUnauthorized(w, r, "Bearer authentication required") + return + } + + rawToken := strings.TrimSpace(parts[1]) + if rawToken == "" || strings.ContainsAny(rawToken, " \t\r\n") { + WriteBearerUnauthorized(w, r, "invalid Bearer token") + return + } + + user, err := st.GetUserByToken(r.Context(), rawToken) + if err != nil { + if errors.Is(err, store.ErrUnavailable) { + WriteError(w, r, http.StatusServiceUnavailable, "unavailable", "storage dependency is temporarily unavailable") + return + } + WriteBearerUnauthorized(w, r, "invalid, expired, or revoked session token") + return + } + + ctx := context.WithValue(r.Context(), userContextKey, user) + ctx = context.WithValue(ctx, tokenContextKey, rawToken) + next(w, r.WithContext(ctx)) + } +} + +func GetAuthUser(ctx context.Context) *model.User { + if user, ok := ctx.Value(userContextKey).(*model.User); ok { + return user + } + return nil +} + +func GetAuthToken(ctx context.Context) string { + if tok, ok := ctx.Value(tokenContextKey).(string); ok { + return tok + } + return "" +} diff --git a/internal/handler/openapi.json b/internal/handler/openapi.json new file mode 100644 index 00000000..da4d1cc7 --- /dev/null +++ b/internal/handler/openapi.json @@ -0,0 +1,2528 @@ +{ + "openapi": "3.1.0", + "info": { + "title": "MTUSI Messenger — лабораторная 3", + "version": "1.3.0", + "description": "Нормативный минимум на 3. Семантика: contracts/README.md. Расширения на 4/5 не должны менять этот API. Наличие кода ошибки в схеме не требует реализовать факультативную причину его выдачи." + }, + "servers": [ + { + "url": "http://localhost:8080", + "description": "Локальный учебный стенд" + } + ], + "security": [ + { + "bearerAuth": [] + } + ], + "paths": { + "/health/live": { + "get": { + "operationId": "liveness", + "summary": "Процесс жив", + "responses": { + "200": { + "description": "Успех", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Health" + } + } + } + }, + "500": { + "description": "Неожиданная ошибка без внутренних деталей", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + }, + "security": [] + } + }, + "/health/ready": { + "get": { + "operationId": "readiness", + "summary": "Готов принимать трафик", + "responses": { + "200": { + "description": "Успех", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Health" + } + } + } + }, + "503": { + "description": "Зависимость недоступна", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "500": { + "description": "Неожиданная ошибка без внутренних деталей", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + }, + "security": [] + } + }, + "/api/v1/users": { + "post": { + "operationId": "registerUser", + "summary": "Создать пользователя", + "responses": { + "201": { + "description": "Успех", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/User" + } + } + } + }, + "400": { + "description": "Неверный запрос", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Конфликт", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "description": "Ограничение частоты запросов", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "Retry-After": { + "description": "Положительное число секунд.", + "schema": { + "type": "integer", + "minimum": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "503": { + "description": "Зависимость недоступна", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "500": { + "description": "Неожиданная ошибка без внутренних деталей", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + }, + "security": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateUser" + } + } + } + } + } + }, + "/api/v1/users/me": { + "get": { + "operationId": "currentUser", + "summary": "Текущий пользователь", + "responses": { + "200": { + "description": "Успех", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/User" + } + } + } + }, + "400": { + "description": "Неверный запрос", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Нет действительной аутентификации", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "WWW-Authenticate": { + "description": "Basic realm=\"messenger\", charset=\"UTF-8\" для входа; Bearer realm=\"messenger\" для защищённого API lab2+.", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Объект отсутствует или недоступен", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Конфликт", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "description": "Ограничение частоты запросов", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "Retry-After": { + "description": "Положительное число секунд.", + "schema": { + "type": "integer", + "minimum": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "503": { + "description": "Зависимость недоступна", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "500": { + "description": "Неожиданная ошибка без внутренних деталей", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/v1/chats": { + "post": { + "operationId": "createChat", + "summary": "Создать чат; вызывающий должен входить в member_ids", + "responses": { + "201": { + "description": "Успех", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Chat" + } + } + } + }, + "400": { + "description": "Неверный запрос", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Нет действительной аутентификации", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "WWW-Authenticate": { + "description": "Basic realm=\"messenger\", charset=\"UTF-8\" для входа; Bearer realm=\"messenger\" для защищённого API lab2+.", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Объект отсутствует или недоступен", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Конфликт", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "description": "Ограничение частоты запросов", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "Retry-After": { + "description": "Положительное число секунд.", + "schema": { + "type": "integer", + "minimum": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "503": { + "description": "Зависимость недоступна", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "500": { + "description": "Неожиданная ошибка без внутренних деталей", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateChat" + } + } + } + } + }, + "get": { + "operationId": "listChats", + "summary": "Чаты текущего пользователя", + "responses": { + "200": { + "description": "Успех", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChatPage" + } + } + } + }, + "400": { + "description": "Неверный запрос", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Нет действительной аутентификации", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "WWW-Authenticate": { + "description": "Basic realm=\"messenger\", charset=\"UTF-8\" для входа; Bearer realm=\"messenger\" для защищённого API lab2+.", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Объект отсутствует или недоступен", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Конфликт", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "description": "Ограничение частоты запросов", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "Retry-After": { + "description": "Положительное число секунд.", + "schema": { + "type": "integer", + "minimum": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "503": { + "description": "Зависимость недоступна", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "500": { + "description": "Неожиданная ошибка без внутренних деталей", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + }, + "parameters": [ + { + "name": "limit", + "in": "query", + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 50 + } + }, + { + "name": "cursor", + "in": "query", + "schema": { + "type": "string", + "minLength": 1 + } + } + ] + } + }, + "/api/v1/chats/{chat_id}": { + "get": { + "operationId": "getChat", + "summary": "Получить доступный чат", + "responses": { + "200": { + "description": "Успех", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Chat" + } + } + } + }, + "400": { + "description": "Неверный запрос", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Нет действительной аутентификации", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "WWW-Authenticate": { + "description": "Basic realm=\"messenger\", charset=\"UTF-8\" для входа; Bearer realm=\"messenger\" для защищённого API lab2+.", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Объект отсутствует или недоступен", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Конфликт", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "description": "Ограничение частоты запросов", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "Retry-After": { + "description": "Положительное число секунд.", + "schema": { + "type": "integer", + "minimum": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "503": { + "description": "Зависимость недоступна", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "500": { + "description": "Неожиданная ошибка без внутренних деталей", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + }, + "parameters": [ + { + "name": "chat_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ] + } + }, + "/api/v1/chats/{chat_id}/messages": { + "post": { + "operationId": "createMessage", + "summary": "Отправить сообщение", + "responses": { + "201": { + "description": "Успех", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Message" + } + } + } + }, + "400": { + "description": "Неверный запрос", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Нет действительной аутентификации", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "WWW-Authenticate": { + "description": "Basic realm=\"messenger\", charset=\"UTF-8\" для входа; Bearer realm=\"messenger\" для защищённого API lab2+.", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Объект отсутствует или недоступен", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Конфликт", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "description": "Ограничение частоты запросов", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "Retry-After": { + "description": "Положительное число секунд.", + "schema": { + "type": "integer", + "minimum": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "503": { + "description": "Зависимость недоступна", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "500": { + "description": "Неожиданная ошибка без внутренних деталей", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + }, + "parameters": [ + { + "name": "chat_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "Idempotency-Key", + "in": "header", + "required": true, + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 128, + "pattern": "^[A-Za-z0-9._:-]+$" + }, + "description": "Обязателен с lab3. Область: пользователь + метод + путь + ключ; хранить результат не менее 24 ч. Повтор того же JSON возвращает исходный 201 и то же сообщение, другой JSON — 409." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateMessage" + } + } + } + } + }, + "get": { + "operationId": "listMessages", + "summary": "Сообщения по (created_at, id) по возрастанию", + "responses": { + "200": { + "description": "Успех", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MessagePage" + } + } + } + }, + "400": { + "description": "Неверный запрос", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Нет действительной аутентификации", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "WWW-Authenticate": { + "description": "Basic realm=\"messenger\", charset=\"UTF-8\" для входа; Bearer realm=\"messenger\" для защищённого API lab2+.", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Объект отсутствует или недоступен", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Конфликт", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "description": "Ограничение частоты запросов", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "Retry-After": { + "description": "Положительное число секунд.", + "schema": { + "type": "integer", + "minimum": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "503": { + "description": "Зависимость недоступна", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "500": { + "description": "Неожиданная ошибка без внутренних деталей", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + }, + "parameters": [ + { + "name": "chat_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "limit", + "in": "query", + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 50 + } + }, + { + "name": "cursor", + "in": "query", + "schema": { + "type": "string", + "minLength": 1 + } + } + ] + } + }, + "/api/v1/auth/sessions": { + "post": { + "operationId": "createSession", + "summary": "Вход: Basic username:password; выдаёт сессию", + "responses": { + "201": { + "description": "Успех", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Session" + } + } + } + }, + "400": { + "description": "Неверный запрос", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Нет действительной аутентификации", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "WWW-Authenticate": { + "description": "Basic realm=\"messenger\", charset=\"UTF-8\" для входа; Bearer realm=\"messenger\" для защищённого API lab2+.", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "description": "Ограничение частоты запросов", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "Retry-After": { + "description": "Положительное число секунд.", + "schema": { + "type": "integer", + "minimum": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "503": { + "description": "Зависимость недоступна", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "500": { + "description": "Неожиданная ошибка без внутренних деталей", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + }, + "security": [ + { + "basicAuth": [] + } + ] + } + }, + "/api/v1/auth/sessions/current": { + "delete": { + "operationId": "revokeSession", + "summary": "Отозвать текущую сессию", + "responses": { + "204": { + "description": "Успех", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + } + }, + "401": { + "description": "Нет действительной аутентификации", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "WWW-Authenticate": { + "description": "Basic realm=\"messenger\", charset=\"UTF-8\" для входа; Bearer realm=\"messenger\" для защищённого API lab2+.", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "description": "Ограничение частоты запросов", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "Retry-After": { + "description": "Положительное число секунд.", + "schema": { + "type": "integer", + "minimum": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "503": { + "description": "Зависимость недоступна", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "500": { + "description": "Неожиданная ошибка без внутренних деталей", + "headers": { + "X-Request-Id": { + "description": "Непустой идентификатор запроса; обязателен во всех ответах.", + "schema": { + "type": "string", + "minLength": 1 + } + }, + "X-Instance-Id": { + "description": "Идентификатор обслужившей API-реплики; стабилен в пределах жизни процесса. В lab7 используйте непрозрачный alias, без hostname/IP.", + "schema": { + "type": "string", + "minLength": 1 + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + } + }, + "components": { + "securitySchemes": { + "basicAuth": { + "type": "http", + "scheme": "basic" + }, + "bearerAuth": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "opaque session token" + } + }, + "schemas": { + "Error": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "invalid_request", + "unauthorized", + "not_found", + "conflict", + "payload_too_large", + "unsupported_media_type", + "rate_limited", + "unavailable", + "internal_error" + ] + }, + "message": { + "type": "string", + "minLength": 1 + }, + "request_id": { + "type": "string", + "minLength": 1 + } + }, + "required": [ + "code", + "message", + "request_id" + ], + "additionalProperties": false + } + }, + "required": [ + "error" + ], + "additionalProperties": false, + "examples": [ + { + "error": { + "code": "not_found", + "message": "Объект не найден", + "request_id": "example-request-id" + } + } + ] + }, + "Health": { + "type": "object", + "properties": { + "status": { + "type": "string", + "enum": [ + "ok" + ] + } + }, + "required": [ + "status" + ], + "additionalProperties": false + }, + "User": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "username": { + "type": "string", + "pattern": "^[a-z0-9_]{3,32}$" + }, + "display_name": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "created_at": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "id", + "username", + "display_name", + "created_at" + ], + "additionalProperties": false, + "examples": [ + { + "id": "11111111-1111-4111-8111-111111111111", + "username": "alice", + "display_name": "Алиса", + "created_at": "2026-09-01T12:00:00Z" + } + ] + }, + "CreateUser": { + "type": "object", + "properties": { + "username": { + "type": "string", + "pattern": "^[a-z0-9_]{3,32}$" + }, + "display_name": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "password": { + "type": "string", + "minLength": 12, + "maxLength": 128, + "writeOnly": true + } + }, + "required": [ + "username", + "display_name", + "password" + ], + "additionalProperties": false, + "examples": [ + { + "username": "alice", + "display_name": "Алиса", + "password": "Example-only-not-a-real-secret-123" + } + ] + }, + "Chat": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "title": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "member_ids": { + "type": "array", + "items": { + "type": "string", + "format": "uuid" + }, + "minItems": 1, + "maxItems": 100, + "uniqueItems": true + }, + "created_at": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "id", + "title", + "member_ids", + "created_at" + ], + "additionalProperties": false, + "examples": [ + { + "title": "Проект по ВНП", + "member_ids": [ + "11111111-1111-4111-8111-111111111111", + "22222222-2222-4222-8222-222222222222" + ], + "id": "33333333-3333-4333-8333-333333333333", + "created_at": "2026-09-01T12:00:00Z" + } + ] + }, + "CreateChat": { + "type": "object", + "properties": { + "title": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "member_ids": { + "type": "array", + "items": { + "type": "string", + "format": "uuid" + }, + "minItems": 1, + "maxItems": 100, + "uniqueItems": true + } + }, + "required": [ + "title", + "member_ids" + ], + "additionalProperties": false, + "examples": [ + { + "title": "Проект по ВНП", + "member_ids": [ + "11111111-1111-4111-8111-111111111111", + "22222222-2222-4222-8222-222222222222" + ] + } + ] + }, + "Message": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "chat_id": { + "type": "string", + "format": "uuid" + }, + "sender_id": { + "type": "string", + "format": "uuid" + }, + "text": { + "type": "string", + "minLength": 1, + "maxLength": 4000 + }, + "created_at": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "id", + "chat_id", + "sender_id", + "text", + "created_at" + ], + "additionalProperties": false, + "examples": [ + { + "id": "44444444-4444-4444-8444-444444444444", + "chat_id": "33333333-3333-4333-8333-333333333333", + "sender_id": "11111111-1111-4111-8111-111111111111", + "text": "Привет, Боб!", + "created_at": "2026-09-01T12:00:00Z" + } + ] + }, + "CreateMessage": { + "type": "object", + "properties": { + "text": { + "type": "string", + "minLength": 1, + "maxLength": 4000 + } + }, + "required": [ + "text" + ], + "additionalProperties": false, + "examples": [ + { + "text": "Привет, Боб!" + } + ] + }, + "ChatPage": { + "type": "object", + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Chat" + } + }, + "next_cursor": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "items", + "next_cursor" + ], + "additionalProperties": false + }, + "MessagePage": { + "type": "object", + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Message" + } + }, + "next_cursor": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "items", + "next_cursor" + ], + "additionalProperties": false, + "examples": [ + { + "items": [ + { + "id": "44444444-4444-4444-8444-444444444444", + "chat_id": "33333333-3333-4333-8333-333333333333", + "sender_id": "11111111-1111-4111-8111-111111111111", + "text": "Привет, Боб!", + "created_at": "2026-09-01T12:00:00Z" + } + ], + "next_cursor": null + } + ] + }, + "Session": { + "type": "object", + "properties": { + "token": { + "type": "string", + "minLength": 32 + }, + "token_type": { + "type": "string", + "const": "Bearer" + }, + "expires_at": { + "type": "string", + "format": "date-time" + }, + "user": { + "$ref": "#/components/schemas/User" + } + }, + "required": [ + "token", + "token_type", + "expires_at", + "user" + ], + "additionalProperties": false + } + } + } +} diff --git a/internal/model/types.go b/internal/model/types.go new file mode 100644 index 00000000..9621dfd9 --- /dev/null +++ b/internal/model/types.go @@ -0,0 +1,75 @@ +package model + +type User struct { + ID string `json:"id"` + Username string `json:"username"` + DisplayName string `json:"display_name"` + CreatedAt string `json:"created_at"` +} + +type CreateUserRequest struct { + Username string `json:"username"` + DisplayName string `json:"display_name"` + Password string `json:"password"` +} + +type Session struct { + Token string `json:"token"` + TokenType string `json:"token_type"` + ExpiresAt string `json:"expires_at"` + User User `json:"user"` +} + +type Chat struct { + ID string `json:"id"` + Title string `json:"title"` + MemberIDs []string `json:"member_ids"` + CreatedAt string `json:"created_at"` +} + +type CreateChatRequest struct { + Title string `json:"title"` + MemberIDs []string `json:"member_ids"` +} + +type Message struct { + ID string `json:"id"` + ChatID string `json:"chat_id"` + SenderID string `json:"sender_id"` + Text string `json:"text"` + CreatedAt string `json:"created_at"` +} + +type CreateMessageRequest struct { + Text string `json:"text"` +} + +type ChatPage struct { + Items []Chat `json:"items"` + NextCursor *string `json:"next_cursor"` +} + +type MessagePage struct { + Items []Message `json:"items"` + NextCursor *string `json:"next_cursor"` +} + +type ErrorDetail struct { + Code string `json:"code"` + Message string `json:"message"` + RequestID string `json:"request_id"` +} + +type ErrorResponse struct { + Error ErrorDetail `json:"error"` +} + +type HealthResponse struct { + Status string `json:"status"` +} + +type CursorData struct { + Scope string `json:"s"` + Time string `json:"t"` + ID string `json:"i"` +} diff --git a/internal/store/postgres.go b/internal/store/postgres.go new file mode 100644 index 00000000..e16223f9 --- /dev/null +++ b/internal/store/postgres.go @@ -0,0 +1,1042 @@ +package store + +import ( + "context" + "crypto/sha256" + "encoding/hex" + "encoding/json" + "errors" + "fmt" + "log" + "strings" + "sync" + "sync/atomic" + "time" + "unicode/utf8" + + "github.com/google/uuid" + "github.com/jackc/pgx/v5" + "github.com/jackc/pgx/v5/pgconn" + "github.com/jackc/pgx/v5/pgxpool" + "github.com/redis/go-redis/v9" + "golang.org/x/sync/singleflight" + + "messenger/internal/auth" + "messenger/internal/model" +) + +type cachedSession struct { + User model.User `json:"user"` + ExpiresAt time.Time `json:"expires_at"` +} + +type PostgresStore struct { + pool *pgxpool.Pool + rdb *redis.Client + queryTimeout time.Duration + + sfGroup singleflight.Group + + mu sync.RWMutex + cacheMode string + writeMode string + + sqlQueries atomic.Int64 + cacheHits atomic.Int64 + cacheMisses atomic.Int64 + singleflightShared atomic.Int64 +} + +type Config struct { + DatabaseURL string + CacheURL string + MaxConns int32 + MinConns int32 + QueryTimeout time.Duration + CacheMode string + WriteMode string +} + +func NewPostgresStore(ctx context.Context, cfg Config) (*PostgresStore, error) { + poolCfg, err := pgxpool.ParseConfig(cfg.DatabaseURL) + if err != nil { + return nil, fmt.Errorf("invalid database URL: %w", err) + } + + if cfg.MaxConns <= 0 { + cfg.MaxConns = 12 + } + if cfg.MinConns <= 0 { + cfg.MinConns = 2 + } + if cfg.QueryTimeout <= 0 { + cfg.QueryTimeout = 5 * time.Second + } + if cfg.CacheMode == "" { + cfg.CacheMode = "write_through_versioned" + } + if cfg.WriteMode == "" { + cfg.WriteMode = "pipeline" + } + + poolCfg.MaxConns = cfg.MaxConns + poolCfg.MinConns = cfg.MinConns + poolCfg.MaxConnLifetime = 30 * time.Minute + poolCfg.MaxConnIdleTime = 5 * time.Minute + poolCfg.HealthCheckPeriod = 15 * time.Second + poolCfg.ConnConfig.ConnectTimeout = 3 * time.Second + + pool, err := pgxpool.NewWithConfig(ctx, poolCfg) + if err != nil { + return nil, fmt.Errorf("failed to create pgx pool: %w", err) + } + + var rdb *redis.Client + if cfg.CacheURL != "" { + opt, err := redis.ParseURL(cfg.CacheURL) + if err != nil { + pool.Close() + return nil, fmt.Errorf("invalid cache URL: %w", err) + } + opt.DialTimeout = 500 * time.Millisecond + opt.ReadTimeout = 500 * time.Millisecond + opt.WriteTimeout = 500 * time.Millisecond + opt.PoolSize = 30 + opt.MaxRetries = 1 + rdb = redis.NewClient(opt) + } + + return &PostgresStore{ + pool: pool, + rdb: rdb, + queryTimeout: cfg.QueryTimeout, + cacheMode: cfg.CacheMode, + writeMode: cfg.WriteMode, + }, nil +} + +func (s *PostgresStore) RunMigrations(ctx context.Context, migrations []MigrationFile) error { + qCtx, cancel := context.WithTimeout(ctx, 20*time.Second) + defer cancel() + + tx, err := s.pool.Begin(qCtx) + if err != nil { + return fmt.Errorf("begin migration tx: %w", err) + } + defer func() { _ = tx.Rollback(qCtx) }() + + // Serialize concurrent migration runners via PostgreSQL advisory transaction lock. + if _, err := tx.Exec(qCtx, `SELECT pg_advisory_xact_lock(20260301)`); err != nil { + return fmt.Errorf("acquire migration advisory lock: %w", err) + } + + _, err = tx.Exec(qCtx, ` + CREATE TABLE IF NOT EXISTS schema_migrations ( + version VARCHAR(64) PRIMARY KEY, + applied_at TIMESTAMPTZ NOT NULL DEFAULT NOW() + ); + `) + if err != nil { + return fmt.Errorf("create schema_migrations: %w", err) + } + + for _, mig := range migrations { + var alreadyApplied bool + err = tx.QueryRow(qCtx, `SELECT EXISTS (SELECT 1 FROM schema_migrations WHERE version = $1)`, mig.Version).Scan(&alreadyApplied) + if err != nil { + return fmt.Errorf("check migration version %s: %w", mig.Version, err) + } + + if !alreadyApplied { + if _, err := tx.Exec(qCtx, mig.SQL); err != nil { + return fmt.Errorf("apply migration %s: %w", mig.Version, err) + } + if _, err := tx.Exec(qCtx, `INSERT INTO schema_migrations (version, applied_at) VALUES ($1, NOW())`, mig.Version); err != nil { + return fmt.Errorf("record migration %s: %w", mig.Version, err) + } + log.Printf("Migration %s applied successfully", mig.Version) + } else { + log.Printf("Migration %s already applied (idempotent skip)", mig.Version) + } + } + + return tx.Commit(qCtx) +} + +func (s *PostgresStore) Ready(ctx context.Context) error { + qCtx, cancel := context.WithTimeout(ctx, 2*time.Second) + defer cancel() + + var ok int + if err := s.pool.QueryRow(qCtx, `SELECT 1 FROM schema_migrations WHERE version = '002_idempotency.sql' LIMIT 1`).Scan(&ok); err != nil { + return ErrUnavailable + } + return nil +} + +func (s *PostgresStore) Close() { + if s.rdb != nil { + _ = s.rdb.Close() + } + if s.pool != nil { + s.pool.Close() + } +} + +func (s *PostgresStore) getCacheMode() string { + s.mu.RLock() + defer s.mu.RUnlock() + return s.cacheMode +} + +func (s *PostgresStore) SetCacheMode(mode string) { + s.mu.Lock() + defer s.mu.Unlock() + s.cacheMode = mode +} + +func (s *PostgresStore) ResetStats() { + s.sqlQueries.Store(0) + s.cacheHits.Store(0) + s.cacheMisses.Store(0) + s.singleflightShared.Store(0) +} + +func (s *PostgresStore) Stats(ctx context.Context) StoreStats { + redisOK := false + if s.rdb != nil { + rCtx, cancel := context.WithTimeout(ctx, 300*time.Millisecond) + defer cancel() + if err := s.rdb.Ping(rCtx).Err(); err == nil { + redisOK = true + } + } + return StoreStats{ + SQLQueries: s.sqlQueries.Load(), + CacheHits: s.cacheHits.Load(), + CacheMisses: s.cacheMisses.Load(), + SingleflightShared: s.singleflightShared.Load(), + CacheMode: s.getCacheMode(), + WriteMode: s.writeMode, + RedisConnected: redisOK, + } +} + +func classifyDBError(err error) error { + if err == nil { + return nil + } + var pgErr *pgconn.PgError + if errors.As(err, &pgErr) { + switch pgErr.Code { + case "23505": // unique_violation + return fmt.Errorf("%w: resource already exists", ErrConflict) + case "23503": // foreign_key_violation + return fmt.Errorf("%w: referenced entity does not exist", ErrBadRequest) + case "23514": // check_violation + return fmt.Errorf("%w: check constraint failed", ErrBadRequest) + case "22P02": // invalid_text_representation (e.g. bad UUID) + return fmt.Errorf("%w: invalid identifier format", ErrBadRequest) + } + } + if errors.Is(err, pgx.ErrNoRows) { + return ErrNotFound + } + return fmt.Errorf("%w: database operation failed", ErrUnavailable) +} + +func (s *PostgresStore) CreateUser(ctx context.Context, req model.CreateUserRequest) (*model.User, error) { + if !usernameRegex.MatchString(req.Username) { + return nil, fmt.Errorf("%w: username must match ^[a-z0-9_]{3,32}$", ErrBadRequest) + } + dnLen := utf8.RuneCountInString(req.DisplayName) + if dnLen < 1 || dnLen > 100 || strings.TrimSpace(req.DisplayName) == "" { + return nil, fmt.Errorf("%w: display_name must be 1..100 characters and not only whitespace", ErrBadRequest) + } + pwLen := utf8.RuneCountInString(req.Password) + if pwLen < 12 || pwLen > 128 || strings.TrimSpace(req.Password) == "" { + return nil, fmt.Errorf("%w: password must be 12..128 characters and not only whitespace", ErrBadRequest) + } + + pwHash, err := auth.HashPassword(req.Password) + if err != nil { + return nil, fmt.Errorf("%w: failed to hash password", ErrUnavailable) + } + + qCtx, cancel := context.WithTimeout(ctx, s.queryTimeout) + defer cancel() + + id := uuid.New().String() + now := NowUTC() + + s.sqlQueries.Add(1) + _, err = s.pool.Exec(qCtx, ` + INSERT INTO users (id, username, display_name, password_hash, created_at) + VALUES ($1::uuid, $2, $3, $4, $5::timestamptz) + `, id, req.Username, req.DisplayName, pwHash, now) + if err != nil { + return nil, classifyDBError(err) + } + + return &model.User{ + ID: id, + Username: req.Username, + DisplayName: req.DisplayName, + CreatedAt: FormatTime(now), + }, nil +} + +func (s *PostgresStore) AuthenticateAndCreateSession(ctx context.Context, username, password string, ttlSeconds int) (*model.Session, error) { + if !usernameRegex.MatchString(username) { + auth.VerifyDummy(password) + return nil, ErrUnauthorized + } + pwLen := utf8.RuneCountInString(password) + if pwLen < 1 || pwLen > 256 { + auth.VerifyDummy(password) + return nil, ErrUnauthorized + } + + qCtx, cancel := context.WithTimeout(ctx, s.queryTimeout) + defer cancel() + + var user model.User + var pwHash string + var createdAt time.Time + + s.sqlQueries.Add(1) + err := s.pool.QueryRow(qCtx, ` + SELECT id::text, username, display_name, password_hash, created_at + FROM users + WHERE username = $1 + `, username).Scan(&user.ID, &user.Username, &user.DisplayName, &pwHash, &createdAt) + if err != nil { + if errors.Is(err, pgx.ErrNoRows) { + auth.VerifyDummy(password) + return nil, ErrUnauthorized + } + return nil, classifyDBError(err) + } + user.CreatedAt = FormatTime(createdAt) + + valid, err := auth.VerifyPassword(password, pwHash) + if err != nil || !valid { + return nil, ErrUnauthorized + } + + rawToken, tokenHash, err := auth.GenerateSessionToken() + if err != nil { + return nil, ErrUnavailable + } + + if ttlSeconds <= 0 { + ttlSeconds = 3600 + } + now := NowUTC() + expiresAt := now.Add(time.Duration(ttlSeconds) * time.Second) + + s.sqlQueries.Add(1) + _, err = s.pool.Exec(qCtx, ` + INSERT INTO sessions (token_hash, user_id, expires_at, created_at) + VALUES ($1, $2::uuid, $3::timestamptz, $4::timestamptz) + `, tokenHash, user.ID, expiresAt, now) + if err != nil { + return nil, classifyDBError(err) + } + + s.cacheSession(ctx, tokenHash, user, expiresAt) + + return &model.Session{ + Token: rawToken, + TokenType: "Bearer", + ExpiresAt: FormatTime(expiresAt), + User: user, + }, nil +} + +func (s *PostgresStore) cacheSession(ctx context.Context, tokenHash string, user model.User, expiresAt time.Time) { + if s.rdb == nil { + return + } + remaining := time.Until(expiresAt) + if remaining <= 0 { + return + } + payload, err := json.Marshal(cachedSession{ + User: user, + ExpiresAt: expiresAt, + }) + if err != nil { + return + } + rCtx, cancel := context.WithTimeout(ctx, 300*time.Millisecond) + defer cancel() + key := "sess:" + tokenHash + if err := s.rdb.Set(rCtx, key, payload, remaining).Err(); err != nil { + log.Printf("WARN: redis session write failed (graceful bypass): %v", err) + return + } + _ = s.rdb.ExpireAt(rCtx, key, expiresAt).Err() +} + +func (s *PostgresStore) GetUserByToken(ctx context.Context, rawToken string) (*model.User, error) { + if len(rawToken) < 32 || len(rawToken) > 256 { + return nil, ErrUnauthorized + } + tokenHash := auth.HashToken(rawToken) + now := NowUTC() + + // 1. Check Valkey/Redis session cache first + if s.rdb != nil { + rCtx, cancel := context.WithTimeout(ctx, 300*time.Millisecond) + val, err := s.rdb.Get(rCtx, "sess:"+tokenHash).Bytes() + cancel() + if err == nil { + var cs cachedSession + if jsonErr := json.Unmarshal(val, &cs); jsonErr == nil { + if now.Before(cs.ExpiresAt) { + s.cacheHits.Add(1) + return &cs.User, nil + } + } + } else if !errors.Is(err, redis.Nil) { + log.Printf("WARN: redis session read failed (falling back to PostgreSQL): %v", err) + } + s.cacheMisses.Add(1) + } + + // 2. Fallback to PostgreSQL source of truth + qCtx, cancel := context.WithTimeout(ctx, s.queryTimeout) + defer cancel() + + var user model.User + var userCreatedAt, expiresAt time.Time + + s.sqlQueries.Add(1) + err := s.pool.QueryRow(qCtx, ` + SELECT u.id::text, u.username, u.display_name, u.created_at, s.expires_at + FROM sessions s + JOIN users u ON u.id = s.user_id + WHERE s.token_hash = $1 + `, tokenHash).Scan(&user.ID, &user.Username, &user.DisplayName, &userCreatedAt, &expiresAt) + if err != nil { + if errors.Is(err, pgx.ErrNoRows) { + return nil, ErrUnauthorized + } + return nil, classifyDBError(err) + } + + expiresAt = expiresAt.UTC().Truncate(time.Microsecond) + if !now.Before(expiresAt) { + // Session expired: clean up lazily and reject + _, _ = s.pool.Exec(qCtx, `DELETE FROM sessions WHERE token_hash = $1`, tokenHash) + return nil, ErrUnauthorized + } + + user.CreatedAt = FormatTime(userCreatedAt) + // Repopulate Valkey/Redis with original expires_at (never extending TTL!) + s.cacheSession(ctx, tokenHash, user, expiresAt) + + return &user, nil +} + +func (s *PostgresStore) RevokeSession(ctx context.Context, rawToken string) error { + if len(rawToken) < 32 || len(rawToken) > 256 { + return ErrUnauthorized + } + tokenHash := auth.HashToken(rawToken) + + if s.rdb != nil { + rCtx, cancel := context.WithTimeout(ctx, 300*time.Millisecond) + if err := s.rdb.Del(rCtx, "sess:"+tokenHash).Err(); err != nil { + log.Printf("WARN: redis session delete failed: %v", err) + } + cancel() + } + + qCtx, cancel := context.WithTimeout(ctx, s.queryTimeout) + defer cancel() + + s.sqlQueries.Add(1) + tag, err := s.pool.Exec(qCtx, ` + DELETE FROM sessions + WHERE token_hash = $1 AND expires_at > $2::timestamptz + `, tokenHash, NowUTC()) + if err != nil { + return classifyDBError(err) + } + if tag.RowsAffected() == 0 { + return ErrUnauthorized + } + return nil +} + +func (s *PostgresStore) CreateChat(ctx context.Context, callerID string, req model.CreateChatRequest) (*model.Chat, error) { + titleLen := utf8.RuneCountInString(req.Title) + if titleLen < 1 || titleLen > 100 || strings.TrimSpace(req.Title) == "" { + return nil, fmt.Errorf("%w: title must be 1..100 characters and not only whitespace", ErrBadRequest) + } + if len(req.MemberIDs) < 1 || len(req.MemberIDs) > 100 { + return nil, fmt.Errorf("%w: member_ids must contain 1..100 items", ErrBadRequest) + } + + seen := make(map[string]struct{}, len(req.MemberIDs)) + callerIncluded := false + for _, mid := range req.MemberIDs { + if _, err := uuid.Parse(mid); err != nil { + return nil, fmt.Errorf("%w: invalid UUID in member_ids", ErrBadRequest) + } + if _, exists := seen[mid]; exists { + return nil, fmt.Errorf("%w: duplicate user in member_ids", ErrBadRequest) + } + seen[mid] = struct{}{} + if mid == callerID { + callerIncluded = true + } + } + if !callerIncluded { + return nil, fmt.Errorf("%w: caller must be included in member_ids", ErrBadRequest) + } + + qCtx, cancel := context.WithTimeout(ctx, s.queryTimeout) + defer cancel() + + // Composite atomic transaction: insert chat + insert all chat_members + tx, err := s.pool.Begin(qCtx) + if err != nil { + return nil, classifyDBError(err) + } + defer func() { _ = tx.Rollback(qCtx) }() + + chatID := uuid.New().String() + now := NowUTC() + + s.sqlQueries.Add(1) + _, err = tx.Exec(qCtx, ` + INSERT INTO chats (id, title, created_at) + VALUES ($1::uuid, $2, $3::timestamptz) + `, chatID, req.Title, now) + if err != nil { + return nil, classifyDBError(err) + } + + for idx, mid := range req.MemberIDs { + s.sqlQueries.Add(1) + _, err = tx.Exec(qCtx, ` + INSERT INTO chat_members (chat_id, user_id, ord) + VALUES ($1::uuid, $2::uuid, $3) + `, chatID, mid, idx) + if err != nil { + // If any member does not exist in users, FK constraint 23503 triggers and rolls back the entire chat creation! + return nil, classifyDBError(err) + } + } + + if err := tx.Commit(qCtx); err != nil { + return nil, classifyDBError(err) + } + + membersCopy := make([]string, len(req.MemberIDs)) + copy(membersCopy, req.MemberIDs) + + return &model.Chat{ + ID: chatID, + Title: req.Title, + MemberIDs: membersCopy, + CreatedAt: FormatTime(now), + }, nil +} + +func (s *PostgresStore) ListChats(ctx context.Context, callerID string, limit int, cursorStr string) (*model.ChatPage, error) { + if limit < 1 || limit > 100 { + return nil, fmt.Errorf("%w: limit must be between 1 and 100", ErrBadRequest) + } + + scope := "chats:" + callerID + var hasCursor bool + var cursorTime time.Time + var cursorID string + if cursorStr != "" { + var err error + cursorTime, cursorID, err = DecodeCursor(cursorStr, scope) + if err != nil { + return nil, err + } + hasCursor = true + } + + qCtx, cancel := context.WithTimeout(ctx, s.queryTimeout) + defer cancel() + + var rows pgx.Rows + var err error + s.sqlQueries.Add(1) + if !hasCursor { + rows, err = s.pool.Query(qCtx, ` + SELECT c.id::text, c.title, c.created_at, + array_agg(cm_all.user_id::text ORDER BY cm_all.ord ASC) AS member_ids + FROM chats c + JOIN chat_members cm_me ON cm_me.chat_id = c.id AND cm_me.user_id = $1::uuid + JOIN chat_members cm_all ON cm_all.chat_id = c.id + GROUP BY c.id, c.title, c.created_at + ORDER BY c.created_at ASC, c.id ASC + LIMIT $2 + `, callerID, limit+1) + } else { + rows, err = s.pool.Query(qCtx, ` + SELECT c.id::text, c.title, c.created_at, + array_agg(cm_all.user_id::text ORDER BY cm_all.ord ASC) AS member_ids + FROM chats c + JOIN chat_members cm_me ON cm_me.chat_id = c.id AND cm_me.user_id = $1::uuid + JOIN chat_members cm_all ON cm_all.chat_id = c.id + WHERE (c.created_at, c.id) > ($2::timestamptz, $3::uuid) + GROUP BY c.id, c.title, c.created_at + ORDER BY c.created_at ASC, c.id ASC + LIMIT $4 + `, callerID, cursorTime, cursorID, limit+1) + } + if err != nil { + return nil, classifyDBError(err) + } + defer rows.Close() + + items := make([]model.Chat, 0, limit) + for rows.Next() { + var ch model.Chat + var createdAt time.Time + if err := rows.Scan(&ch.ID, &ch.Title, &createdAt, &ch.MemberIDs); err != nil { + return nil, classifyDBError(err) + } + ch.CreatedAt = FormatTime(createdAt) + items = append(items, ch) + } + if err := rows.Err(); err != nil { + return nil, classifyDBError(err) + } + + var nextCursor *string + if len(items) > limit { + items = items[:limit] + last := items[limit-1] + c := EncodeCursor(scope, last.CreatedAt, last.ID) + nextCursor = &c + } + + return &model.ChatPage{ + Items: items, + NextCursor: nextCursor, + }, nil +} + +func (s *PostgresStore) GetChat(ctx context.Context, callerID, chatID string) (*model.Chat, error) { + qCtx, cancel := context.WithTimeout(ctx, s.queryTimeout) + defer cancel() + + var ch model.Chat + var createdAt time.Time + + s.sqlQueries.Add(1) + err := s.pool.QueryRow(qCtx, ` + SELECT c.id::text, c.title, c.created_at, + array_agg(cm.user_id::text ORDER BY cm.ord ASC) AS member_ids + FROM chats c + JOIN chat_members cm ON cm.chat_id = c.id + WHERE c.id = $1::uuid + AND EXISTS ( + SELECT 1 FROM chat_members WHERE chat_id = c.id AND user_id = $2::uuid + ) + GROUP BY c.id, c.title, c.created_at + `, chatID, callerID).Scan(&ch.ID, &ch.Title, &createdAt, &ch.MemberIDs) + if err != nil { + return nil, classifyDBError(err) + } + ch.CreatedAt = FormatTime(createdAt) + return &ch, nil +} + +func (s *PostgresStore) lookupIdempotency(ctx context.Context, callerID, chatID, idempotencyKey, reqHash string, now time.Time) (*model.Message, bool, error) { + qCtx, cancel := context.WithTimeout(ctx, s.queryTimeout) + defer cancel() + + var existingHash string + var msg model.Message + var createdAt time.Time + + s.sqlQueries.Add(1) + err := s.pool.QueryRow(qCtx, ` + SELECT ik.request_hash, m.id::text, m.chat_id::text, m.sender_id::text, m.text, m.created_at + FROM idempotency_keys ik + JOIN messages m ON m.id = ik.message_id + WHERE ik.user_id = $1::uuid + AND ik.chat_id = $2::uuid + AND ik.idempotency_key = $3 + AND ik.expires_at > $4::timestamptz + `, callerID, chatID, idempotencyKey, now).Scan(&existingHash, &msg.ID, &msg.ChatID, &msg.SenderID, &msg.Text, &createdAt) + if err != nil { + if errors.Is(err, pgx.ErrNoRows) { + return nil, false, nil + } + return nil, false, classifyDBError(err) + } + if existingHash != reqHash { + return nil, true, fmt.Errorf("%w: idempotency key already used with different request body", ErrConflict) + } + msg.CreatedAt = FormatTime(createdAt) + return &msg, true, nil +} + +func canonicalMessageHash(text string) string { + canonicalBytes, _ := json.Marshal(struct { + Text string `json:"text"` + }{Text: text}) + sum := sha256.Sum256(canonicalBytes) + return hex.EncodeToString(sum[:]) +} + +func (s *PostgresStore) CreateMessage(ctx context.Context, callerID, chatID, idempotencyKey string, idempotencyTTLSeconds int, req model.CreateMessageRequest) (*model.Message, error) { + if !IdempotencyKeyRegex.MatchString(idempotencyKey) { + return nil, fmt.Errorf("%w: invalid or missing Idempotency-Key header", ErrBadRequest) + } + textLen := utf8.RuneCountInString(req.Text) + if textLen < 1 || textLen > 4000 || strings.TrimSpace(req.Text) == "" { + return nil, fmt.Errorf("%w: text must be 1..4000 characters and not only whitespace", ErrBadRequest) + } + if idempotencyTTLSeconds <= 0 { + idempotencyTTLSeconds = 86400 + } + + mode := s.getCacheMode() + // Always verify membership/chat existence first so outsiders get 404 without touching idempotency_keys. + isMember, err := s.checkChatMembership(ctx, chatID, callerID, mode) + if err != nil { + return nil, err + } + if !isMember { + return nil, ErrNotFound + } + + reqHash := canonicalMessageHash(req.Text) + now := NowUTC() + + // Fast-path replay lookup + if existing, found, err := s.lookupIdempotency(ctx, callerID, chatID, idempotencyKey, reqHash, now); err != nil { + return nil, err + } else if found { + return existing, nil + } + + qCtx, cancel := context.WithTimeout(ctx, s.queryTimeout) + defer cancel() + + tx, err := s.pool.Begin(qCtx) + if err != nil { + return nil, classifyDBError(err) + } + defer func() { _ = tx.Rollback(qCtx) }() + + msgID := uuid.New().String() + expiresAt := now.Add(time.Duration(idempotencyTTLSeconds) * time.Second) + var claimed int64 + + if s.writeMode == "sequential" { + s.sqlQueries.Add(1) + if _, err = tx.Exec(qCtx, ` + DELETE FROM idempotency_keys + WHERE user_id = $1::uuid AND chat_id = $2::uuid AND idempotency_key = $3 AND expires_at <= $4::timestamptz + `, callerID, chatID, idempotencyKey, now); err != nil { + return nil, classifyDBError(err) + } + + s.sqlQueries.Add(1) + if _, err = tx.Exec(qCtx, ` + INSERT INTO messages (id, chat_id, sender_id, text, created_at) + VALUES ($1::uuid, $2::uuid, $3::uuid, $4, $5::timestamptz) + `, msgID, chatID, callerID, req.Text, now); err != nil { + return nil, classifyDBError(err) + } + + s.sqlQueries.Add(1) + tag, execErr := tx.Exec(qCtx, ` + INSERT INTO idempotency_keys (user_id, chat_id, idempotency_key, request_hash, message_id, created_at, expires_at) + VALUES ($1::uuid, $2::uuid, $3, $4, $5::uuid, $6::timestamptz, $7::timestamptz) + ON CONFLICT (user_id, chat_id, idempotency_key) DO NOTHING + `, callerID, chatID, idempotencyKey, reqHash, msgID, now, expiresAt) + if execErr != nil { + return nil, classifyDBError(execErr) + } + claimed = tag.RowsAffected() + } else { + s.sqlQueries.Add(3) + batch := &pgx.Batch{} + batch.Queue(` + DELETE FROM idempotency_keys + WHERE user_id = $1::uuid AND chat_id = $2::uuid AND idempotency_key = $3 AND expires_at <= $4::timestamptz + `, callerID, chatID, idempotencyKey, now) + batch.Queue(` + INSERT INTO messages (id, chat_id, sender_id, text, created_at) + VALUES ($1::uuid, $2::uuid, $3::uuid, $4, $5::timestamptz) + `, msgID, chatID, callerID, req.Text, now) + batch.Queue(` + INSERT INTO idempotency_keys (user_id, chat_id, idempotency_key, request_hash, message_id, created_at, expires_at) + VALUES ($1::uuid, $2::uuid, $3, $4, $5::uuid, $6::timestamptz, $7::timestamptz) + ON CONFLICT (user_id, chat_id, idempotency_key) DO NOTHING + `, callerID, chatID, idempotencyKey, reqHash, msgID, now, expiresAt) + + br := tx.SendBatch(qCtx, batch) + _, err1 := br.Exec() + _, err2 := br.Exec() + tag3, err3 := br.Exec() + closeErr := br.Close() + if err1 != nil { + return nil, classifyDBError(err1) + } + if err2 != nil { + return nil, classifyDBError(err2) + } + if err3 != nil { + return nil, classifyDBError(err3) + } + if closeErr != nil { + return nil, classifyDBError(closeErr) + } + claimed = tag3.RowsAffected() + } + + if claimed == 0 { + // Another replica won the concurrent idempotency race; roll back duplicate message insert and read winner. + _ = tx.Rollback(qCtx) + existing, found, lErr := s.lookupIdempotency(ctx, callerID, chatID, idempotencyKey, reqHash, now) + if lErr != nil { + return nil, lErr + } + if !found { + return nil, ErrUnavailable + } + return existing, nil + } + + if err := tx.Commit(qCtx); err != nil { + return nil, classifyDBError(err) + } + + // Invalidate chat history cache immediately on write so any replica reads fresh history (Read-After-Write). + if s.rdb != nil && mode == "write_through_versioned" { + rCtx, rCancel := context.WithTimeout(ctx, 300*time.Millisecond) + verKey := "chat_ver:" + chatID + if err := s.rdb.Incr(rCtx, verKey).Err(); err != nil { + log.Printf("WARN: redis cache version increment failed: %v", err) + } else { + _ = s.rdb.Expire(rCtx, verKey, 24*time.Hour).Err() + } + rCancel() + } + + return &model.Message{ + ID: msgID, + ChatID: chatID, + SenderID: callerID, + Text: req.Text, + CreatedAt: FormatTime(now), + }, nil +} + +func (s *PostgresStore) checkChatMembership(ctx context.Context, chatID, callerID, mode string) (bool, error) { + memKey := fmt.Sprintf("chat_mem:%s:%s", chatID, callerID) + if s.rdb != nil && mode != "disabled" { + rCtx, rCancel := context.WithTimeout(ctx, 200*time.Millisecond) + val, err := s.rdb.Get(rCtx, memKey).Result() + rCancel() + if err == nil { + return val == "1", nil + } + } + + queryMembership := func() (bool, error) { + qCtx, cancel := context.WithTimeout(ctx, s.queryTimeout) + defer cancel() + var isMember bool + s.sqlQueries.Add(1) + err := s.pool.QueryRow(qCtx, ` + SELECT EXISTS ( + SELECT 1 FROM chat_members WHERE chat_id = $1::uuid AND user_id = $2::uuid + ) + `, chatID, callerID).Scan(&isMember) + if err != nil { + return false, classifyDBError(err) + } + if s.rdb != nil && mode != "disabled" { + rCtx, rCancel := context.WithTimeout(ctx, 200*time.Millisecond) + strVal := "0" + if isMember { + strVal = "1" + } + _ = s.rdb.Set(rCtx, memKey, strVal, 10*time.Minute).Err() + rCancel() + } + return isMember, nil + } + + if mode == "write_through_versioned" { + res, err, _ := s.sfGroup.Do(memKey, func() (interface{}, error) { + return queryMembership() + }) + if err != nil { + return false, err + } + return res.(bool), nil + } + return queryMembership() +} + +func (s *PostgresStore) ListMessages(ctx context.Context, callerID, chatID string, limit int, cursorStr string) (*model.MessagePage, error) { + if limit < 1 || limit > 100 { + return nil, fmt.Errorf("%w: limit must be between 1 and 100", ErrBadRequest) + } + + scope := "msgs:" + chatID + var hasCursor bool + var cursorTime time.Time + var cursorID string + if cursorStr != "" { + var err error + cursorTime, cursorID, err = DecodeCursor(cursorStr, scope) + if err != nil { + return nil, err + } + hasCursor = true + } + + mode := s.getCacheMode() + + // 1. Always enforce membership check before returning cached or DB history + isMember, err := s.checkChatMembership(ctx, chatID, callerID, mode) + if err != nil { + return nil, err + } + if !isMember { + return nil, ErrNotFound + } + + // 2. Determine cache key + var cacheKey string + if s.rdb != nil && mode != "disabled" { + if mode == "naive_ttl" { + cacheKey = fmt.Sprintf("msg_page:%s:naive:l%d:c%s", chatID, limit, cursorStr) + } else { + rCtx, rCancel := context.WithTimeout(ctx, 200*time.Millisecond) + ver, err := s.rdb.Get(rCtx, "chat_ver:"+chatID).Int64() + rCancel() + if err != nil && !errors.Is(err, redis.Nil) { + log.Printf("WARN: redis version read failed (bypassing cache): %v", err) + cacheKey = "" + } else { + cacheKey = fmt.Sprintf("msg_page:%s:v%d:l%d:c%s", chatID, ver, limit, cursorStr) + } + } + } + + // 3. Check cache + if cacheKey != "" { + rCtx, rCancel := context.WithTimeout(ctx, 200*time.Millisecond) + cachedBytes, err := s.rdb.Get(rCtx, cacheKey).Bytes() + rCancel() + if err == nil { + var page model.MessagePage + if json.Unmarshal(cachedBytes, &page) == nil { + s.cacheHits.Add(1) + return &page, nil + } + } else if !errors.Is(err, redis.Nil) { + log.Printf("WARN: redis page read failed (falling back to PostgreSQL): %v", err) + } + s.cacheMisses.Add(1) + } + + fetchFromDB := func() (*model.MessagePage, error) { + dbCtx, dbCancel := context.WithTimeout(ctx, s.queryTimeout) + defer dbCancel() + + var rows pgx.Rows + var qErr error + s.sqlQueries.Add(1) + if !hasCursor { + rows, qErr = s.pool.Query(dbCtx, ` + SELECT id::text, chat_id::text, sender_id::text, text, created_at + FROM messages + WHERE chat_id = $1::uuid + ORDER BY created_at ASC, id ASC + LIMIT $2 + `, chatID, limit+1) + } else { + rows, qErr = s.pool.Query(dbCtx, ` + SELECT id::text, chat_id::text, sender_id::text, text, created_at + FROM messages + WHERE chat_id = $1::uuid + AND (created_at, id) > ($2::timestamptz, $3::uuid) + ORDER BY created_at ASC, id ASC + LIMIT $4 + `, chatID, cursorTime, cursorID, limit+1) + } + if qErr != nil { + return nil, classifyDBError(qErr) + } + defer rows.Close() + + items := make([]model.Message, 0, limit) + for rows.Next() { + var m model.Message + var createdAt time.Time + if err := rows.Scan(&m.ID, &m.ChatID, &m.SenderID, &m.Text, &createdAt); err != nil { + return nil, classifyDBError(err) + } + m.CreatedAt = FormatTime(createdAt) + items = append(items, m) + } + if err := rows.Err(); err != nil { + return nil, classifyDBError(err) + } + + var nextCursor *string + if len(items) > limit { + items = items[:limit] + last := items[limit-1] + c := EncodeCursor(scope, last.CreatedAt, last.ID) + nextCursor = &c + } + + page := &model.MessagePage{ + Items: items, + NextCursor: nextCursor, + } + + if cacheKey != "" && s.rdb != nil { + if payload, mErr := json.Marshal(page); mErr == nil { + rCtx, rCancel := context.WithTimeout(ctx, 200*time.Millisecond) + ttl := 30 * time.Second + if mode == "naive_ttl" { + ttl = 5 * time.Second + } + _ = s.rdb.Set(rCtx, cacheKey, payload, ttl).Err() + rCancel() + } + } + + return page, nil + } + + // 4. Use singleflight in write_through_versioned mode to prevent cache stampede! + if mode == "write_through_versioned" && cacheKey != "" { + res, err, shared := s.sfGroup.Do(cacheKey, func() (interface{}, error) { + return fetchFromDB() + }) + if shared { + s.singleflightShared.Add(1) + } + if err != nil { + return nil, err + } + return res.(*model.MessagePage), nil + } + + return fetchFromDB() +} diff --git a/internal/store/store.go b/internal/store/store.go new file mode 100644 index 00000000..97e5a3f4 --- /dev/null +++ b/internal/store/store.go @@ -0,0 +1,105 @@ +package store + +import ( + "context" + "encoding/base64" + "encoding/json" + "errors" + "regexp" + "time" + + "github.com/google/uuid" + "messenger/internal/model" +) + +var ( + ErrConflict = errors.New("conflict") + ErrNotFound = errors.New("not found") + ErrBadRequest = errors.New("bad request") + ErrUnauthorized = errors.New("unauthorized") + ErrUnavailable = errors.New("service unavailable") + + usernameRegex = regexp.MustCompile(`^[a-z0-9_]{3,32}$`) + IdempotencyKeyRegex = regexp.MustCompile(`^[A-Za-z0-9._:-]{1,128}$`) +) + +const TimestampFormat = "2006-01-02T15:04:05.000000Z" + +func FormatTime(t time.Time) string { + return t.UTC().Truncate(time.Microsecond).Format(TimestampFormat) +} + +func NowUTC() time.Time { + return time.Now().UTC().Truncate(time.Microsecond) +} + +type MigrationFile struct { + Version string + SQL string +} + +type StoreStats struct { + SQLQueries int64 `json:"sql_queries"` + CacheHits int64 `json:"cache_hits"` + CacheMisses int64 `json:"cache_misses"` + SingleflightShared int64 `json:"singleflight_shared"` + CacheMode string `json:"cache_mode"` + WriteMode string `json:"write_mode"` + RedisConnected bool `json:"redis_connected"` +} + +type Store interface { + Ready(ctx context.Context) error + RunMigrations(ctx context.Context, migrations []MigrationFile) error + CreateUser(ctx context.Context, req model.CreateUserRequest) (*model.User, error) + AuthenticateAndCreateSession(ctx context.Context, username, password string, ttlSeconds int) (*model.Session, error) + GetUserByToken(ctx context.Context, rawToken string) (*model.User, error) + RevokeSession(ctx context.Context, rawToken string) error + CreateChat(ctx context.Context, callerID string, req model.CreateChatRequest) (*model.Chat, error) + ListChats(ctx context.Context, callerID string, limit int, cursorStr string) (*model.ChatPage, error) + GetChat(ctx context.Context, callerID, chatID string) (*model.Chat, error) + CreateMessage(ctx context.Context, callerID, chatID, idempotencyKey string, idempotencyTTLSeconds int, req model.CreateMessageRequest) (*model.Message, error) + ListMessages(ctx context.Context, callerID, chatID string, limit int, cursorStr string) (*model.MessagePage, error) + Stats(ctx context.Context) StoreStats + ResetStats() + SetCacheMode(mode string) + Close() +} + +func EncodeCursor(scope, timestamp, id string) string { + data := model.CursorData{ + Scope: scope, + Time: timestamp, + ID: id, + } + b, _ := json.Marshal(data) + return base64.RawURLEncoding.EncodeToString(b) +} + +func DecodeCursor(cursorStr, expectedScope string) (time.Time, string, error) { + b, err := base64.RawURLEncoding.DecodeString(cursorStr) + if err != nil { + b, err = base64.URLEncoding.DecodeString(cursorStr) + if err != nil { + b, err = base64.StdEncoding.DecodeString(cursorStr) + if err != nil { + return time.Time{}, "", ErrBadRequest + } + } + } + var data model.CursorData + if err := json.Unmarshal(b, &data); err != nil { + return time.Time{}, "", ErrBadRequest + } + if data.Scope != expectedScope || data.Time == "" || data.ID == "" { + return time.Time{}, "", ErrBadRequest + } + if _, err := uuid.Parse(data.ID); err != nil { + return time.Time{}, "", ErrBadRequest + } + t, err := time.Parse(time.RFC3339Nano, data.Time) + if err != nil { + return time.Time{}, "", ErrBadRequest + } + return t.UTC().Truncate(time.Microsecond), data.ID, nil +} diff --git a/migrations/001_init.sql b/migrations/001_init.sql new file mode 100644 index 00000000..cbdae46f --- /dev/null +++ b/migrations/001_init.sql @@ -0,0 +1,53 @@ +-- Migration 001: Initial schema for Lab 2 (PostgreSQL, Sessions, Chats, Messages) +-- Idempotent DDL with primary/foreign keys, constraints, and keyset pagination indexes. + +CREATE TABLE IF NOT EXISTS users ( + id UUID PRIMARY KEY, + username VARCHAR(32) NOT NULL UNIQUE + CONSTRAINT chk_users_username CHECK (username ~ '^[a-z0-9_]{3,32}$'), + display_name VARCHAR(100) NOT NULL + CONSTRAINT chk_users_display_name CHECK (char_length(btrim(display_name)) >= 1 AND char_length(display_name) <= 100), + password_hash TEXT NOT NULL, + created_at TIMESTAMPTZ NOT NULL +); + +CREATE TABLE IF NOT EXISTS sessions ( + token_hash CHAR(64) PRIMARY KEY, + user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE, + expires_at TIMESTAMPTZ NOT NULL, + created_at TIMESTAMPTZ NOT NULL +); + +CREATE INDEX IF NOT EXISTS idx_sessions_user_id ON sessions (user_id); +CREATE INDEX IF NOT EXISTS idx_sessions_expires_at ON sessions (expires_at); + +CREATE TABLE IF NOT EXISTS chats ( + id UUID PRIMARY KEY, + title VARCHAR(100) NOT NULL + CONSTRAINT chk_chats_title CHECK (char_length(btrim(title)) >= 1 AND char_length(title) <= 100), + created_at TIMESTAMPTZ NOT NULL +); + +CREATE INDEX IF NOT EXISTS idx_chats_created_id ON chats (created_at ASC, id ASC); + +CREATE TABLE IF NOT EXISTS chat_members ( + chat_id UUID NOT NULL REFERENCES chats(id) ON DELETE CASCADE, + user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE, + ord INT NOT NULL DEFAULT 0, + PRIMARY KEY (chat_id, user_id) +); + +CREATE INDEX IF NOT EXISTS idx_chat_members_user_chat ON chat_members (user_id, chat_id); + +CREATE TABLE IF NOT EXISTS messages ( + id UUID PRIMARY KEY, + chat_id UUID NOT NULL REFERENCES chats(id) ON DELETE CASCADE, + sender_id UUID NOT NULL REFERENCES users(id) ON DELETE RESTRICT, + text TEXT NOT NULL + CONSTRAINT chk_messages_text CHECK (char_length(btrim(text)) >= 1 AND char_length(text) <= 4000), + created_at TIMESTAMPTZ NOT NULL +); + +-- Composite B-Tree index supporting keyset pagination: +-- WHERE chat_id = $1 AND (created_at, id) > ($2, $3) ORDER BY created_at ASC, id ASC LIMIT $4 +CREATE INDEX IF NOT EXISTS idx_messages_chat_created_id ON messages (chat_id, created_at ASC, id ASC); diff --git a/migrations/002_idempotency.sql b/migrations/002_idempotency.sql new file mode 100644 index 00000000..fb692457 --- /dev/null +++ b/migrations/002_idempotency.sql @@ -0,0 +1,17 @@ +-- Migration 002: Idempotency keys for POST /api/v1/chats/{chat_id}/messages (Lab 3) +-- Scope: (user_id, chat_id, idempotency_key), TTL 24h by default. +-- Message creation and idempotency key registration happen atomically in one PostgreSQL transaction. + +CREATE TABLE IF NOT EXISTS idempotency_keys ( + user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE, + chat_id UUID NOT NULL REFERENCES chats(id) ON DELETE CASCADE, + idempotency_key VARCHAR(128) NOT NULL + CONSTRAINT chk_idempotency_key_format CHECK (idempotency_key ~ '^[A-Za-z0-9._:-]{1,128}$'), + request_hash CHAR(64) NOT NULL, + message_id UUID NOT NULL REFERENCES messages(id) ON DELETE CASCADE, + created_at TIMESTAMPTZ NOT NULL, + expires_at TIMESTAMPTZ NOT NULL, + PRIMARY KEY (user_id, chat_id, idempotency_key) +); + +CREATE INDEX IF NOT EXISTS idx_idempotency_keys_expires_at ON idempotency_keys (expires_at); diff --git a/scripts/restart.sh b/scripts/restart.sh new file mode 100755 index 00000000..a1f67222 --- /dev/null +++ b/scripts/restart.sh @@ -0,0 +1,8 @@ +#!/bin/sh +set -eu + +SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) +ROOT_DIR=$(CDPATH= cd -- "$SCRIPT_DIR/.." && pwd) +cd "$ROOT_DIR" + +docker compose --env-file .env restart postgres redis api lb >/dev/null diff --git a/scripts/seed.py b/scripts/seed.py new file mode 100644 index 00000000..e1b70bcf --- /dev/null +++ b/scripts/seed.py @@ -0,0 +1,80 @@ +#!/usr/bin/env python3 +"""Helper script to populate synthetic demo data for Lab 3 defense in Swagger UI.""" +import base64 +import json +import sys +import urllib.request +import uuid + +BASE_URL = sys.argv[1] if len(sys.argv) > 1 else "http://localhost:8080" + + +def req(method, path, body=None, headers=None): + h = {"Accept": "application/json"} + data = None + if body is not None: + data = json.dumps(body).encode("utf-8") + h["Content-Type"] = "application/json" + if headers: + h.update(headers) + r = urllib.request.Request(BASE_URL + path, data=data, headers=h, method=method) + with urllib.request.urlopen(r, timeout=10) as resp: + raw = resp.read() + inst = resp.headers.get("X-Instance-Id", "") + return (json.loads(raw.decode("utf-8")) if raw else None), inst + + +def main(): + suffix = uuid.uuid4().hex[:6] + alice_username = f"alice_{suffix}" + bob_username = f"bob_{suffix}" + password = "DemoPassword-2026!" + + alice, inst1 = req("POST", "/api/v1/users", { + "username": alice_username, + "display_name": "Alice Zamorskaya", + "password": password, + }) + bob, inst2 = req("POST", "/api/v1/users", { + "username": bob_username, + "display_name": "Bob Bobrov", + "password": password, + }) + + alice_basic = base64.b64encode(f"{alice_username}:{password}".encode("utf-8")).decode("ascii") + bob_basic = base64.b64encode(f"{bob_username}:{password}".encode("utf-8")).decode("ascii") + + alice_sess, _ = req("POST", "/api/v1/auth/sessions", headers={"Authorization": f"Basic {alice_basic}"}) + bob_sess, _ = req("POST", "/api/v1/auth/sessions", headers={"Authorization": f"Basic {bob_basic}"}) + + alice_bearer = {"Authorization": f"Bearer {alice_sess['token']}"} + bob_bearer = {"Authorization": f"Bearer {bob_sess['token']}"} + + chat, _ = req("POST", "/api/v1/chats", { + "title": "Lab 3 Defense Chat", + "member_ids": [alice["id"], bob["id"]], + }, headers=alice_bearer) + + _, inst3 = req("POST", f"/api/v1/chats/{chat['id']}/messages", { + "text": "Hello Bob! Sent with Idempotency-Key through HAProxy.", + }, headers={**alice_bearer, "Idempotency-Key": f"seed-msg-1-{suffix}"}) + + _, inst4 = req("POST", f"/api/v1/chats/{chat['id']}/messages", { + "text": "Hi Alice! Served across balanced API replicas.", + }, headers={**bob_bearer, "Idempotency-Key": f"seed-msg-2-{suffix}"}) + + print("=== LAB 3 DEMO DATA CREATED ===") + print(f"Swagger UI: {BASE_URL}/docs") + print(f"Observed IDs: {sorted({x for x in [inst1, inst2, inst3, inst4] if x})}") + print(f"Password: {password}") + print(f"Alice Username: {alice_username}") + print(f"Alice User ID: {alice['id']}") + print(f"Alice Token: {alice_sess['token']}") + print(f"Bob Username: {bob_username}") + print(f"Bob User ID: {bob['id']}") + print(f"Bob Token: {bob_sess['token']}") + print(f"Chat ID: {chat['id']}") + + +if __name__ == "__main__": + main() diff --git a/scripts/stop-one.sh b/scripts/stop-one.sh new file mode 100755 index 00000000..16db8ae4 --- /dev/null +++ b/scripts/stop-one.sh @@ -0,0 +1,25 @@ +#!/bin/sh +set -eu + +: "${TARGET_INSTANCE_ID:?test provides target API instance alias}" + +SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) +ROOT_DIR=$(CDPATH= cd -- "$SCRIPT_DIR/.." && pwd) +cd "$ROOT_DIR" + +TARGET_CID="" +for cid in $(docker compose --env-file .env ps -q api); do + short_id=$(printf '%s' "$cid" | cut -c1-12) + hostname_val=$(docker inspect -f '{{.Config.Hostname}}' "$cid" 2>/dev/null || true) + if [ "$short_id" = "$TARGET_INSTANCE_ID" ] || [ "$cid" = "$TARGET_INSTANCE_ID" ] || [ "$hostname_val" = "$TARGET_INSTANCE_ID" ]; then + TARGET_CID="$cid" + break + fi +done + +if [ -z "$TARGET_CID" ]; then + printf 'API container matching X-Instance-Id=%s not found\n' "$TARGET_INSTANCE_ID" >&2 + exit 1 +fi + +docker stop -t 5 "$TARGET_CID" >/dev/null diff --git a/student-tests/test_grade4.py b/student-tests/test_grade4.py new file mode 100644 index 00000000..764b9579 --- /dev/null +++ b/student-tests/test_grade4.py @@ -0,0 +1,444 @@ +#!/usr/bin/env python3 +"""Grade 4 verification suite for Lab 3: +1. Resource limits, no exposed API ports bypassing LB, single migration execution. +2. Cross-replica stateless sessions & shared logout. +3. Concurrent Idempotency-Key across multiple replicas, canonical JSON replay, 409 conflict, scope isolation. +4. Sequential failover of each API replica under load with RPS, error count, and recovery time. +5. Rolling replacement of API replicas under active write load. +""" +import base64 +from concurrent.futures import ThreadPoolExecutor +import datetime as dt +import json +from pathlib import Path +import subprocess +import sys +import threading +import time +import urllib.error +import urllib.request +import uuid + +ROOT = Path(__file__).resolve().parents[1] +EVIDENCE_PATH = ROOT / "evidence" / "grade4_checks.json" +BASE_URL = sys.argv[1] if len(sys.argv) > 1 else "http://localhost:8080" + + +def run_cmd(cmd): + return subprocess.run(cmd, cwd=str(ROOT), text=True, capture_output=True, check=True) + + +def http_call(method, path, body=None, raw_bytes=None, headers=None, timeout=5): + h = {"Accept": "application/json"} + data = raw_bytes + if body is not None: + data = json.dumps(body).encode("utf-8") + h["Content-Type"] = "application/json" + elif raw_bytes is not None: + h["Content-Type"] = "application/json" + if headers: + h.update(headers) + req = urllib.request.Request(BASE_URL + path, data=data, headers=h, method=method) + start = time.monotonic() + try: + with urllib.request.urlopen(req, timeout=timeout) as resp: + raw = resp.read() + return ( + resp.code, + {k.lower(): v for k, v in resp.headers.items()}, + json.loads(raw.decode("utf-8")) if raw else None, + time.monotonic() - start, + ) + except urllib.error.HTTPError as err: + raw = err.read() + return ( + err.code, + {k.lower(): v for k, v in err.headers.items()}, + json.loads(raw.decode("utf-8")) if raw else None, + time.monotonic() - start, + ) + + +def register_and_login(label): + username = f"g4_{label}_{uuid.uuid4().hex[:8]}" + password = f"Grade4Pass-{uuid.uuid4().hex}" + st, _, user, _ = http_call("POST", "/api/v1/users", { + "username": username, + "display_name": f"Student {label}", + "password": password, + }) + assert st == 201, f"register failed: {st}" + basic = base64.b64encode(f"{username}:{password}".encode("utf-8")).decode("ascii") + st, _, sess, _ = http_call("POST", "/api/v1/auth/sessions", headers={"Authorization": f"Basic {basic}"}) + assert st == 201, f"login failed: {st}" + return {"id": user["id"], "username": username, "token": sess["token"], "headers": {"Authorization": f"Bearer {sess['token']}"}} + + +def wait_ready(timeout_s=45): + deadline = time.monotonic() + timeout_s + while time.monotonic() < deadline: + try: + st, _, _, _ = http_call("GET", "/health/ready", timeout=2) + if st == 200: + return + except Exception: + pass + time.sleep(0.5) + raise RuntimeError("LB/API did not become ready within timeout") + + +def get_api_containers(): + out = run_cmd(["docker", "compose", "--env-file", ".env", "ps", "-q", "api"]).stdout.strip().splitlines() + result = [] + for cid in out: + cid = cid.strip() + if not cid: + continue + info = json.loads(run_cmd(["docker", "inspect", cid]).stdout)[0] + result.append({ + "id": cid, + "short_id": cid[:12], + "name": info["Name"].lstrip("/"), + "hostname": info["Config"]["Hostname"], + "running": info["State"]["Running"], + "nano_cpus": info["HostConfig"]["NanoCpus"], + "memory": info["HostConfig"]["Memory"], + "ports": info["NetworkSettings"]["Ports"], + }) + return result + + +def wait_two_instances(headers, timeout_s=30): + deadline = time.monotonic() + timeout_s + seen = set() + while time.monotonic() < deadline: + try: + st, hdrs, _, _ = http_call("GET", "/api/v1/users/me", headers=headers, timeout=2) + if st == 200: + inst = hdrs.get("x-instance-id", "") + if inst: + seen.add(inst) + if len(seen) >= 2: + return sorted(seen) + except Exception: + pass + time.sleep(0.2) + raise RuntimeError(f"Expected >=2 active instances behind LB, saw {seen}") + + +def test_infra_and_migrations(): + containers = get_api_containers() + assert len(containers) >= 2, f"Expected >=2 API replicas, got {len(containers)}" + for c in containers: + assert c["nano_cpus"] > 0, f"{c['name']} missing CPU limit" + assert c["memory"] > 0, f"{c['name']} missing Memory limit" + for port_key, bindings in (c["ports"] or {}).items(): + assert not bindings, f"{c['name']} exposes host port {port_key}: {bindings}" + + pg_cid = run_cmd(["docker", "compose", "--env-file", ".env", "ps", "-q", "postgres"]).stdout.strip() + migs = run_cmd([ + "docker", "exec", pg_cid, "psql", "-U", "messenger", "-d", "messenger", "-tA", + "-c", "SELECT version FROM schema_migrations ORDER BY version;", + ]).stdout.strip().splitlines() + assert migs == ["001_init.sql", "002_idempotency.sql"], f"Unexpected schema_migrations: {migs}" + return { + "status": "PASS", + "api_replicas": len(containers), + "containers": [{"name": c["name"], "short_id": c["short_id"], "nano_cpus": c["nano_cpus"], "memory": c["memory"]} for c in containers], + "applied_migrations": migs, + } + + +def test_stateless_sessions(): + alice = register_and_login("stateless") + instances = set() + for _ in range(30): + st, hdrs, data, _ = http_call("GET", "/api/v1/users/me", headers=alice["headers"]) + assert st == 200 and data["id"] == alice["id"] + instances.add(hdrs.get("x-instance-id", "")) + assert len(instances) >= 2, f"Expected >=2 instances serving single session, saw {instances}" + + # Logout once -> must immediately invalidate across all replicas + st, _, _, _ = http_call("DELETE", "/api/v1/auth/sessions/current", headers=alice["headers"]) + assert st == 204 + for _ in range(10): + st, _, _, _ = http_call("GET", "/api/v1/users/me", headers=alice["headers"]) + assert st == 401 + return {"status": "PASS", "observed_instances": sorted(instances)} + + +def test_concurrent_idempotency(): + alice = register_and_login("idem_a") + bob = register_and_login("idem_b") + st, _, chat1, _ = http_call("POST", "/api/v1/chats", { + "title": "Idempotency Race Chat 1", + "member_ids": [alice["id"], bob["id"]], + }, headers=alice["headers"]) + assert st == 201 + st, _, chat2, _ = http_call("POST", "/api/v1/chats", { + "title": "Idempotency Race Chat 2", + "member_ids": [alice["id"], bob["id"]], + }, headers=alice["headers"]) + assert st == 201 + + shared_key = f"race-{uuid.uuid4().hex}" + text = f"Concurrent payload {shared_key}" + + def send_once(_i): + return http_call("POST", f"/api/v1/chats/{chat1['id']}/messages", {"text": text}, headers={ + **alice["headers"], + "Idempotency-Key": shared_key, + }) + + with ThreadPoolExecutor(max_workers=20) as pool: + results = list(pool.map(send_once, range(20))) + + msg_ids = set() + insts = set() + for st, hdrs, msg, _ in results: + assert st == 201, f"Expected 201 on concurrent idempotent send, got {st}" + msg_ids.add(msg["id"]) + insts.add(hdrs.get("x-instance-id", "")) + assert len(msg_ids) == 1, f"Expected single message ID across 20 concurrent calls, got {msg_ids}" + assert len(insts) >= 2, f"Expected >=2 replicas handling concurrent retries, saw {insts}" + winning_id = next(iter(msg_ids)) + + # Canonical JSON formatting equivalence (escaped unicode / whitespace) + escaped_text = "".join(f"\\u{ord(ch):04x}" if ch.isalpha() else ch for ch in text) + raw_equiv = ('{ "text" : "' + escaped_text + '" }').encode("utf-8") + st, _, msg_equiv, _ = http_call( + "POST", + f"/api/v1/chats/{chat1['id']}/messages", + raw_bytes=raw_equiv, + headers={**alice["headers"], "Idempotency-Key": shared_key}, + ) + assert st == 201 and msg_equiv["id"] == winning_id, f"Canonical JSON replay mismatch: {st}" + + # Different body with same key -> 409 conflict + st, _, err_body, _ = http_call( + "POST", + f"/api/v1/chats/{chat1['id']}/messages", + {"text": text + " altered"}, + headers={**alice["headers"], "Idempotency-Key": shared_key}, + ) + assert st == 409 and err_body["error"]["code"] == "conflict", f"Expected 409 conflict, got {st}" + + # Different user with SAME key in SAME chat -> independent message (201, new ID) + st, _, bob_msg, _ = http_call( + "POST", + f"/api/v1/chats/{chat1['id']}/messages", + {"text": "Bob message with same key"}, + headers={**bob["headers"], "Idempotency-Key": shared_key}, + ) + assert st == 201 and bob_msg["id"] != winning_id + + # Same user + same key in DIFFERENT chat -> independent message (201, new ID) + st, _, c2_msg, _ = http_call( + "POST", + f"/api/v1/chats/{chat2['id']}/messages", + {"text": text}, + headers={**alice["headers"], "Idempotency-Key": shared_key}, + ) + assert st == 201 and c2_msg["id"] != winning_id + + # Verify history of chat1 has strictly 2 messages (alice once + bob once) + st, _, page, _ = http_call("GET", f"/api/v1/chats/{chat1['id']}/messages?limit=100", headers=alice["headers"]) + assert st == 200 and len(page["items"]) == 2, f"Expected 2 messages in chat1, got {len(page['items'])}" + + return { + "status": "PASS", + "concurrent_requests": 20, + "unique_message_ids": len(msg_ids), + "replicas_involved": sorted(insts), + "canonical_json_replay": "201_same_id", + "different_body_conflict": 409, + "scope_isolation_verified": True, + } + + +def stop_and_measure_failover(actor, chat, target_container, duration_s=10.0): + stop_flag = threading.Event() + results = [] + lock = threading.Lock() + started = time.monotonic() + + def worker(wid): + idx = 0 + while not stop_flag.is_set(): + key = f"seq-{target_container['short_id']}-{wid}-{idx}" + idx += 1 + t0 = time.monotonic() + try: + st, hdrs, msg, lat = http_call("POST", f"/api/v1/chats/{chat['id']}/messages", { + "text": f"Failover msg {key}", + }, headers={**actor["headers"], "Idempotency-Key": key}, timeout=3) + with lock: + results.append((t0 - started, st == 201, st, hdrs.get("x-instance-id", ""), lat)) + except Exception: + with lock: + results.append((t0 - started, False, 0, "", time.monotonic() - t0)) + time.sleep(0.03) + + threads = [threading.Thread(target=worker, args=(i,)) for i in range(4)] + for th in threads: + th.start() + + time.sleep(1.5) + t_stop_start = time.monotonic() + run_cmd(["docker", "stop", "-t", "5", target_container["id"]]) + t_stop_done = time.monotonic() + + # Continue load after stop + time.sleep(duration_s - 1.5) + stop_flag.set() + for th in threads: + th.join() + + total = len(results) + ok = [r for r in results if r[1]] + errs = [r for r in results if not r[1]] + # Find recovery window: last error timestamp relative to stop start (or 0 if 0 errors) + post_stop_errs = [r[0] - (t_stop_start - started) for r in errs if r[0] >= (t_stop_start - started)] + recovery_s = max(post_stop_errs) if post_stop_errs else 0.0 + after_stop_insts = sorted({r[3] for r in ok if r[0] > (t_stop_done - started) + 2.0 and r[3]}) + assert target_container["short_id"] not in after_stop_insts, f"Stopped container still served after 2s: {after_stop_insts}" + + return { + "stopped_container": target_container["name"], + "stopped_short_id": target_container["short_id"], + "stop_duration_s": round(t_stop_done - t_stop_start, 3), + "total_requests": total, + "successful_writes": len(ok), + "failed_requests": len(errs), + "error_rate": round(len(errs) / total, 5) if total else 0.0, + "rps": round(len(ok) / duration_s, 2), + "recovery_seconds_after_stop": round(max(0.0, recovery_s), 3), + "serving_instances_after_failover": after_stop_insts, + } + + +def test_sequential_failover(): + alice = register_and_login("seq_fail") + st, _, chat, _ = http_call("POST", "/api/v1/chats", { + "title": "Sequential Failover Chat", + "member_ids": [alice["id"]], + }, headers=alice["headers"]) + assert st == 201 + + wait_two_instances(alice["headers"]) + containers = get_api_containers() + assert len(containers) == 2 + + step1 = stop_and_measure_failover(alice, chat, containers[0], duration_s=10.0) + run_cmd(["docker", "start", containers[0]["id"]]) + wait_two_instances(alice["headers"]) + + step2 = stop_and_measure_failover(alice, chat, containers[1], duration_s=10.0) + run_cmd(["docker", "start", containers[1]["id"]]) + wait_two_instances(alice["headers"]) + + return {"status": "PASS", "replica_1_failover": step1, "replica_2_failover": step2} + + +def test_rolling_update(): + alice = register_and_login("rolling") + st, _, chat, _ = http_call("POST", "/api/v1/chats", { + "title": "Rolling Update Chat", + "member_ids": [alice["id"]], + }, headers=alice["headers"]) + assert st == 201 + + wait_two_instances(alice["headers"]) + old_containers = get_api_containers() + old_ids = [c["id"] for c in old_containers] + + stop_flag = threading.Event() + stats = {"ok": 0, "err": 0, "insts": set()} + lock = threading.Lock() + + def writer(wid): + idx = 0 + while not stop_flag.is_set(): + key = f"roll-{wid}-{idx}" + idx += 1 + try: + st_c, hdrs, _, _ = http_call("POST", f"/api/v1/chats/{chat['id']}/messages", { + "text": f"Rolling msg {key}", + }, headers={**alice["headers"], "Idempotency-Key": key}, timeout=4) + with lock: + if st_c == 201: + stats["ok"] += 1 + stats["insts"].add(hdrs.get("x-instance-id", "")) + else: + stats["err"] += 1 + except Exception: + with lock: + stats["err"] += 1 + time.sleep(0.05) + + threads = [threading.Thread(target=writer, args=(i,)) for i in range(4)] + for th in threads: + th.start() + + try: + # Step 1: Surge capacity 2 -> 3 before replacing old replicas one by one + run_cmd(["docker", "compose", "--env-file", ".env", "up", "-d", "--no-deps", "--scale", "api=3", "--no-recreate", "api"]) + time.sleep(3.5) + + # Step 2: Gracefully replace each old replica one at a time + for cid in old_ids: + run_cmd(["docker", "stop", "-t", "8", cid]) + run_cmd(["docker", "rm", cid]) + run_cmd(["docker", "compose", "--env-file", ".env", "up", "-d", "--no-deps", "--scale", "api=3", "--no-recreate", "api"]) + time.sleep(3.5) + + # Step 3: Scale back down cleanly 3 -> 2 + current = get_api_containers() + extra = [c for c in current if c["id"] not in old_ids][-1] + run_cmd(["docker", "stop", "-t", "8", extra["id"]]) + run_cmd(["docker", "rm", extra["id"]]) + finally: + stop_flag.set() + for th in threads: + th.join() + + new_ids = sorted(c["short_id"] for c in get_api_containers()) + assert set(new_ids).isdisjoint({c["short_id"] for c in old_containers}), "Old containers were not all replaced" + total = stats["ok"] + stats["err"] + return { + "status": "PASS", + "old_replicas": [c["short_id"] for c in old_containers], + "new_replicas": new_ids, + "total_requests_during_rollout": total, + "successful_writes": stats["ok"], + "failed_requests": stats["err"], + "error_rate": round(stats["err"] / total, 5) if total else 0.0, + "observed_serving_instances": sorted(x for x in stats["insts"] if x), + } + + +def main(): + wait_ready() + report = { + "timestamp_utc": dt.datetime.now(dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"), + "base_url": BASE_URL, + "checks": {}, + } + report["checks"]["infra_and_migrations"] = test_infra_and_migrations() + print("PASS: infra_and_migrations") + report["checks"]["stateless_sessions"] = test_stateless_sessions() + print("PASS: stateless_sessions") + report["checks"]["concurrent_idempotency"] = test_concurrent_idempotency() + print("PASS: concurrent_idempotency") + report["checks"]["sequential_failover"] = test_sequential_failover() + print("PASS: sequential_failover") + report["checks"]["rolling_update"] = test_rolling_update() + print("PASS: rolling_update") + + EVIDENCE_PATH.parent.mkdir(parents=True, exist_ok=True) + EVIDENCE_PATH.write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8") + print(f"PASS: all Grade 4 checks succeeded; evidence saved to {EVIDENCE_PATH}") + + +if __name__ == "__main__": + main() diff --git a/student-tests/test_track1_scaling.py b/student-tests/test_track1_scaling.py new file mode 100644 index 00000000..9a03003f --- /dev/null +++ b/student-tests/test_track1_scaling.py @@ -0,0 +1,372 @@ +#!/usr/bin/env python3 +"""Grade 5 Track 1: Cost of Scaling experiment for Lab 3. +Measures: +- Series A: Fixed total API resource budget (2.0 CPU, 512M RAM) across 1/2/4 replicas. +- Series B: Scaling with resource growth (0.5 CPU, 256M RAM per replica) against 0.5 CPU DB to locate saturation point. +- Series C: Confirmed optimization at 4-replica saturation (WRITE_MODE=sequential, DB_MAX_CONNS=25 -> WRITE_MODE=pipeline, DB_MAX_CONNS=8). +Restores the default 2-replica stand on completion. +""" +import base64 +from concurrent.futures import ThreadPoolExecutor +import datetime as dt +import http.client +import json +import math +import os +from pathlib import Path +import subprocess +import sys +import threading +import time +import urllib.parse +import uuid + +ROOT = Path(__file__).resolve().parents[1] +EVIDENCE_JSON = ROOT / "evidence" / "track1_scaling.json" +EVIDENCE_SVG = ROOT / "evidence" / "track1_scaling_chart.svg" +BASE_URL = sys.argv[1] if len(sys.argv) > 1 else "http://localhost:8080" + + +def run_cmd(cmd, env=None): + merged_env = os.environ.copy() + if env: + merged_env.update(env) + return subprocess.run(cmd, cwd=str(ROOT), env=merged_env, text=True, capture_output=True, check=True) + + +def wait_ready(min_replicas=1, timeout_s=60): + parsed = urllib.parse.urlparse(BASE_URL) + host = parsed.hostname or "localhost" + port = parsed.port or 80 + deadline = time.monotonic() + timeout_s + seen = set() + while time.monotonic() < deadline: + try: + conn = http.client.HTTPConnection(host, port, timeout=2) + conn.request("GET", "/health/ready") + resp = conn.getresponse() + _ = resp.read() + if resp.status == 200: + inst = resp.getheader("X-Instance-Id", "") + if inst: + seen.add(inst) + if len(seen) >= min_replicas: + conn.close() + return sorted(seen) + conn.close() + except Exception: + pass + time.sleep(0.3) + raise RuntimeError(f"Expected >= {min_replicas} ready replicas, observed {seen}") + + +def apply_topology(replicas, api_cpu, api_mem, db_cpu, db_mem, db_max_conns, write_mode): + env_overrides = { + "API_REPLICAS": str(replicas), + "API_CPU_LIMIT": str(api_cpu), + "API_MEM_LIMIT": str(api_mem), + "DB_CPU_LIMIT": str(db_cpu), + "DB_MEM_LIMIT": str(db_mem), + "DB_MAX_CONNS": str(db_max_conns), + "WRITE_MODE": str(write_mode), + } + run_cmd( + ["docker", "compose", "--env-file", ".env", "up", "-d", "--no-deps", "--force-recreate", "--scale", f"api={replicas}", "postgres", "api"], + env=env_overrides, + ) + run_cmd(["docker", "compose", "--env-file", ".env", "restart", "lb"], env=env_overrides) + time.sleep(2.0) + return wait_ready(min_replicas=replicas, timeout_s=60) + + +def sample_docker_stats(): + out = run_cmd(["docker", "stats", "--no-stream", "--format", "{{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}"]).stdout.strip().splitlines() + stats = {} + for line in out: + parts = line.split("\t") + if len(parts) != 3: + continue + name, cpu, mem = parts + if not name.startswith("lab3-"): + continue + stats[name] = {"cpu": cpu.strip(), "mem": mem.strip()} + return stats + + +def percentile(sorted_vals, p): + if not sorted_vals: + return None + idx = max(0, math.ceil(p * len(sorted_vals)) - 1) + return round(sorted_vals[idx] * 1000.0, 3) + + +def bootstrap_actor(host, port): + conn = http.client.HTTPConnection(host, port, timeout=10) + uname = f"bench_{uuid.uuid4().hex[:10]}" + pw = f"ScaleBench-{uuid.uuid4().hex}" + body = json.dumps({"username": uname, "display_name": "Bench", "password": pw}).encode("utf-8") + conn.request("POST", "/api/v1/users", body, {"Content-Type": "application/json", "Accept": "application/json"}) + r1 = conn.getresponse() + u = json.loads(r1.read().decode("utf-8")) + assert r1.status == 201 + + basic = base64.b64encode(f"{uname}:{pw}".encode("utf-8")).decode("ascii") + conn.request("POST", "/api/v1/auth/sessions", None, {"Authorization": f"Basic {basic}", "Accept": "application/json"}) + r2 = conn.getresponse() + s = json.loads(r2.read().decode("utf-8")) + assert r2.status == 201 + + chat_body = json.dumps({"title": "Scale Chat", "member_ids": [u["id"]]}).encode("utf-8") + conn.request("POST", "/api/v1/chats", chat_body, { + "Authorization": f"Bearer {s['token']}", + "Content-Type": "application/json", + "Accept": "application/json", + }) + r3 = conn.getresponse() + chat = json.loads(r3.read().decode("utf-8")) + assert r3.status == 201 + + # Seed one message so GET /messages returns data immediately + msg_body = json.dumps({"text": "Initial message"}).encode("utf-8") + conn.request("POST", f"/api/v1/chats/{chat['id']}/messages", msg_body, { + "Authorization": f"Bearer {s['token']}", + "Content-Type": "application/json", + "Idempotency-Key": f"init-{uuid.uuid4().hex}", + }) + r4 = conn.getresponse() + _ = r4.read() + assert r4.status == 201 + conn.close() + return {"username": uname, "basic": basic, "token": s["token"], "chat_id": chat["id"]} + + +def run_benchmark(label, concurrency=20, warmup_s=2.0, duration_s=10.0, login_every=20): + """Mixed messenger workload: + - 1 in `login_every` (5%): POST /api/v1/auth/sessions (Argon2id CPU bound) + - ~75%: POST /api/v1/chats/{id}/messages (DB transactional write + Idempotency-Key + Redis INCR) + - ~20%: GET /api/v1/chats/{id}/messages?limit=20 (Redis/DB read) + """ + parsed = urllib.parse.urlparse(BASE_URL) + host = parsed.hostname or "localhost" + port = parsed.port or 80 + + actor = bootstrap_actor(host, port) + barrier = threading.Barrier(concurrency + 2) + stop_at = time.monotonic() + warmup_s + duration_s + 0.2 + record_after = time.monotonic() + warmup_s + + captured_stats = {} + stats_done = threading.Event() + + def stats_sampler(): + barrier.wait() + time.sleep(warmup_s + duration_s * 0.5) + try: + captured_stats.update(sample_docker_stats()) + except Exception as exc: + captured_stats["error"] = str(exc) + stats_done.set() + + def worker(wid): + conn = http.client.HTTPConnection(host, port, timeout=10) + latencies = [] + write_latencies = [] + errors = 0 + insts = set() + i = 0 + barrier.wait() + while time.monotonic() < stop_at: + t0 = time.monotonic() + ok = False + is_write = False + try: + if i % login_every == 0: + conn.request("POST", "/api/v1/auth/sessions", None, { + "Authorization": f"Basic {actor['basic']}", + "Accept": "application/json", + }) + resp = conn.getresponse() + _ = resp.read() + ok = resp.status == 201 + elif i % 5 == 1: + conn.request("GET", f"/api/v1/chats/{actor['chat_id']}/messages?limit=20", None, { + "Authorization": f"Bearer {actor['token']}", + "Accept": "application/json", + }) + resp = conn.getresponse() + _ = resp.read() + ok = resp.status == 200 + else: + is_write = True + payload = json.dumps({"text": f"m-{wid}-{i}"}).encode("utf-8") + conn.request("POST", f"/api/v1/chats/{actor['chat_id']}/messages", payload, { + "Authorization": f"Bearer {actor['token']}", + "Content-Type": "application/json", + "Accept": "application/json", + "Idempotency-Key": f"k-{wid}-{i}-{uuid.uuid4().hex[:8]}", + }) + resp = conn.getresponse() + _ = resp.read() + ok = resp.status == 201 + inst = resp.getheader("X-Instance-Id", "") + if inst: + insts.add(inst) + except Exception: + ok = False + try: + conn.close() + conn = http.client.HTTPConnection(host, port, timeout=10) + except Exception: + pass + t1 = time.monotonic() + if t0 >= record_after: + if ok: + lat = t1 - t0 + latencies.append(lat) + if is_write: + write_latencies.append(lat) + else: + errors += 1 + i += 1 + conn.close() + return latencies, write_latencies, errors, insts + + sampler_th = threading.Thread(target=stats_sampler) + sampler_th.start() + with ThreadPoolExecutor(max_workers=concurrency) as pool: + futs = [pool.submit(worker, wid) for wid in range(concurrency)] + barrier.wait() + res = [f.result() for f in futs] + sampler_th.join() + + all_lat = sorted(x for lat, _, _, _ in res for x in lat) + w_lat = sorted(x for _, wl, _, _ in res for x in wl) + total_err = sum(e for _, _, e, _ in res) + all_inst = sorted({inst for _, _, _, insts in res for inst in insts}) + total_ok = len(all_lat) + rps = round(total_ok / duration_s, 2) + + result = { + "label": label, + "concurrency": concurrency, + "warmup_s": warmup_s, + "duration_s": duration_s, + "successful_requests": total_ok, + "failed_requests": total_err, + "error_rate": round(total_err / (total_ok + total_err), 5) if (total_ok + total_err) else 0.0, + "successful_rps": rps, + "latency_ms": { + "p50": percentile(all_lat, 0.50), + "p95": percentile(all_lat, 0.95), + "p99": percentile(all_lat, 0.99), + }, + "write_latency_ms": { + "p50": percentile(w_lat, 0.50), + "p95": percentile(w_lat, 0.95), + "p99": percentile(w_lat, 0.99), + }, + "observed_instances": all_inst, + "container_stats_midpoint": captured_stats, + } + print(f"[{label}] RPS={rps} ok={total_ok} err={total_err} p50={result['latency_ms']['p50']}ms p95={result['latency_ms']['p95']}ms p99={result['latency_ms']['p99']}ms instances={len(all_inst)}", flush=True) + return result + + +def generate_svg_chart(series_a, series_b, improvement): + # Clean SVG bar chart comparing Series A (Fixed Budget), Series B (Scaling + Saturation), Series C (Improvement) + items = ( + [("A: 1x2.0c", series_a[0]["successful_rps"], "#3b82f6"), + ("A: 2x1.0c", series_a[1]["successful_rps"], "#3b82f6"), + ("A: 4x0.5c", series_a[2]["successful_rps"], "#3b82f6"), + ("B: 1x0.5c", series_b[0]["successful_rps"], "#10b981"), + ("B: 2x0.5c", series_b[1]["successful_rps"], "#10b981"), + ("B: 4x0.5c", series_b[2]["successful_rps"], "#f59e0b"), + ("Opt: 4x0.5c", improvement["after"]["successful_rps"], "#8b5cf6")] + ) + max_rps = max(v for _, v, _ in items) or 100.0 + width, height = 780, 360 + pad_l, pad_b, pad_t = 70, 65, 50 + chart_w = width - pad_l - 40 + chart_h = height - pad_b - pad_t + bar_w = 64 + gap = (chart_w - len(items) * bar_w) / (len(items) + 1) + + lines = [ + f'', + ' Lab 3 Track 1: Cost of Scaling & Saturation Point (RPS)', + f' ', + f' ', + ] + for i in range(5): + y = pad_t + chart_h - (chart_h * i / 4.0) + val = int(round(max_rps * i / 4.0)) + lines.append(f' ') + lines.append(f' {val}') + + for idx, (label, val, color) in enumerate(items): + x = pad_l + gap + idx * (bar_w + gap) + bh = (val / max_rps) * chart_h * 0.92 + y = pad_t + chart_h - bh + lines.append(f' ') + lines.append(f' {val:.1f}') + lines.append(f' {label}') + + lines.append(' Blue: Fixed 2.0 CPU Budget | Green: Resource Growth | Orange: DB Saturation | Purple: Batch Pipeline + Pool Tuning') + lines.append("") + EVIDENCE_SVG.write_text("\n".join(lines) + "\n", encoding="utf-8") + + +def main(): + report = { + "timestamp_utc": dt.datetime.now(dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"), + "base_url": BASE_URL, + "series_a_fixed_budget": [], + "series_b_resource_growth": [], + "confirmed_improvement": {}, + } + + try: + # Series A: Fixed total API CPU=2.0, RAM=512M, DB=1.0 CPU + print("=== Series A: Fixed Total Budget (2.0 CPU, 512M RAM) ===") + for replicas, cpu, mem in [(1, "2.0", "512M"), (2, "1.0", "256M"), (4, "0.5", "128M")]: + apply_topology(replicas, cpu, mem, db_cpu="1.0", db_mem="512M", db_max_conns=12, write_mode="pipeline") + res = run_benchmark(f"A_fixed_{replicas}x{cpu}cpu", concurrency=16, warmup_s=2.0, duration_s=10.0) + res["config"] = {"replicas": replicas, "api_cpu": cpu, "api_mem": mem, "db_cpu": "1.0", "db_max_conns": 12, "write_mode": "pipeline"} + report["series_a_fixed_budget"].append(res) + + # Series B: Resource growth per replica (0.5 CPU, 256M RAM each) vs DB=0.5 CPU (unoptimized sequential + pool=25) + print("=== Series B: Scaling with Resource Growth (0.5 CPU/replica vs 0.5 CPU DB) ===") + for replicas in [1, 2, 4]: + apply_topology(replicas, "0.5", "256M", db_cpu="0.5", db_mem="256M", db_max_conns=25, write_mode="sequential") + res = run_benchmark(f"B_growth_{replicas}x0.5cpu", concurrency=20, warmup_s=2.0, duration_s=10.0) + res["config"] = {"replicas": replicas, "api_cpu": "0.5", "api_mem": "256M", "db_cpu": "0.5", "db_max_conns": 25, "write_mode": "sequential"} + report["series_b_resource_growth"].append(res) + + # Series C: Confirmed Improvement at 4-replica saturation point (same 4x0.5 CPU API vs 0.5 CPU DB) + print("=== Series C: Confirmed Improvement at 4-replica Saturation ===") + before = report["series_b_resource_growth"][-1] + apply_topology(4, "0.5", "256M", db_cpu="0.5", db_mem="256M", db_max_conns=8, write_mode="pipeline") + after = run_benchmark("C_optimized_4x0.5cpu", concurrency=20, warmup_s=2.0, duration_s=10.0) + after["config"] = {"replicas": 4, "api_cpu": "0.5", "api_mem": "256M", "db_cpu": "0.5", "db_max_conns": 8, "write_mode": "pipeline"} + + rps_gain_pct = round(((after["successful_rps"] - before["successful_rps"]) / before["successful_rps"]) * 100.0, 2) + p95_delta_pct = round(((after["latency_ms"]["p95"] - before["latency_ms"]["p95"]) / before["latency_ms"]["p95"]) * 100.0, 2) + report["confirmed_improvement"] = { + "change": "Enabled pgx.Batch SQL pipelining in CreateMessage tx (5 RTT -> 2 RTT) and tuned DB_MAX_CONNS per replica (25 -> 8, limiting total connections from 100 to 32 against 0.5 CPU PostgreSQL)", + "before": before, + "after": after, + "rps_change_percent": rps_gain_pct, + "p95_latency_change_percent": p95_delta_pct, + } + + EVIDENCE_JSON.parent.mkdir(parents=True, exist_ok=True) + EVIDENCE_JSON.write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8") + generate_svg_chart(report["series_a_fixed_budget"], report["series_b_resource_growth"], report["confirmed_improvement"]) + print(f"PASS: Track 1 scaling benchmark complete. RPS delta: {rps_gain_pct:+.2f}%, p95 delta: {p95_delta_pct:+.2f}%") + finally: + print("Restoring default 2-replica Lab 3 topology...") + apply_topology(2, "1.0", "256M", db_cpu="1.0", db_mem="512M", db_max_conns=12, write_mode="pipeline") + + +if __name__ == "__main__": + main() -- 2.54.0