ЛР 3 — БВТ2302 — Заморский — на 5 #168

Open
0pavel1 wants to merge 1 commits from 0pavel1/mtusi2026lab3:solution/bvt2302-zamorskiy into main
29 changed files with 6835 additions and 21 deletions
+2
View File
@@ -0,0 +1,2 @@
*.sh text eol=lf
*.sql text eol=lf
+38
View File
@@ -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"]
+11 -1
View File
@@ -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)"
+159 -20
View File
@@ -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:<token_hash>` с `EXPIREAT`); кэш истории сообщений (`msg_page:<chat_id>:v<ver>:...`) версионируется общим счётчиком `chat_ver:<chat_id>` в 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-совместимое объектное хранилище и эндпоинты вложений без публикации бакета напрямую.
+207
View File
@@ -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)
}
}
+153
View File
@@ -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
+100
View File
@@ -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"
]
}
}
}
+17
View File
@@ -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."
}
+475
View File
@@ -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
}
}
+37
View File
@@ -0,0 +1,37 @@
<svg xmlns="http://www.w3.org/2000/svg" width="780" height="360" viewBox="0 0 780 360" style="background:#ffffff;font-family:sans-serif">
<text x="390" y="28" text-anchor="middle" font-size="16" font-weight="bold" fill="#111827">Lab 3 Track 1: Cost of Scaling &amp; Saturation Point (RPS)</text>
<line x1="70" y1="50" x2="70" y2="295" stroke="#9ca3af" stroke-width="1"/>
<line x1="70" y1="295" x2="750" y2="295" stroke="#9ca3af" stroke-width="1"/>
<line x1="70" y1="295.0" x2="750" y2="295.0" stroke="#e5e7eb" stroke-width="1"/>
<text x="62" y="299.0" text-anchor="end" font-size="11" fill="#4b5563">0</text>
<line x1="70" y1="233.8" x2="750" y2="233.8" stroke="#e5e7eb" stroke-width="1"/>
<text x="62" y="237.8" text-anchor="end" font-size="11" fill="#4b5563">254</text>
<line x1="70" y1="172.5" x2="750" y2="172.5" stroke="#e5e7eb" stroke-width="1"/>
<text x="62" y="176.5" text-anchor="end" font-size="11" fill="#4b5563">508</text>
<line x1="70" y1="111.2" x2="750" y2="111.2" stroke="#e5e7eb" stroke-width="1"/>
<text x="62" y="115.2" text-anchor="end" font-size="11" fill="#4b5563">763</text>
<line x1="70" y1="50.0" x2="750" y2="50.0" stroke="#e5e7eb" stroke-width="1"/>
<text x="62" y="54.0" text-anchor="end" font-size="11" fill="#4b5563">1017</text>
<rect x="97.8" y="69.6" width="64" height="225.4" rx="4" fill="#3b82f6"/>
<text x="129.8" y="63.6" text-anchor="middle" font-size="11" font-weight="bold" fill="#111827">1016.7</text>
<text x="129.8" y="313" text-anchor="middle" font-size="11" fill="#374151">A: 1x2.0c</text>
<rect x="189.5" y="112.1" width="64" height="182.9" rx="4" fill="#3b82f6"/>
<text x="221.5" y="106.1" text-anchor="middle" font-size="11" font-weight="bold" fill="#111827">825.1</text>
<text x="221.5" y="313" text-anchor="middle" font-size="11" fill="#374151">A: 2x1.0c</text>
<rect x="281.2" y="203.3" width="64" height="91.7" rx="4" fill="#3b82f6"/>
<text x="313.2" y="197.3" text-anchor="middle" font-size="11" font-weight="bold" fill="#111827">413.6</text>
<text x="313.2" y="313" text-anchor="middle" font-size="11" fill="#374151">A: 4x0.5c</text>
<rect x="373.0" y="284.5" width="64" height="10.5" rx="4" fill="#10b981"/>
<text x="405.0" y="278.5" text-anchor="middle" font-size="11" font-weight="bold" fill="#111827">47.5</text>
<text x="405.0" y="313" text-anchor="middle" font-size="11" fill="#374151">B: 1x0.5c</text>
<rect x="464.8" y="216.6" width="64" height="78.4" rx="4" fill="#10b981"/>
<text x="496.8" y="210.6" text-anchor="middle" font-size="11" font-weight="bold" fill="#111827">353.5</text>
<text x="496.8" y="313" text-anchor="middle" font-size="11" fill="#374151">B: 2x0.5c</text>
<rect x="556.5" y="212.8" width="64" height="82.2" rx="4" fill="#f59e0b"/>
<text x="588.5" y="206.8" text-anchor="middle" font-size="11" font-weight="bold" fill="#111827">370.8</text>
<text x="588.5" y="313" text-anchor="middle" font-size="11" fill="#374151">B: 4x0.5c</text>
<rect x="648.2" y="181.9" width="64" height="113.1" rx="4" fill="#8b5cf6"/>
<text x="680.2" y="175.9" text-anchor="middle" font-size="11" font-weight="bold" fill="#111827">510.2</text>
<text x="680.2" y="313" text-anchor="middle" font-size="11" fill="#374151">Opt: 4x0.5c</text>
<text x="390" y="346" text-anchor="middle" font-size="11" fill="#6b7280">Blue: Fixed 2.0 CPU Budget | Green: Resource Growth | Orange: DB Saturation | Purple: Batch Pipeline + Pool Tuning</text>
</svg>

After

Width:  |  Height:  |  Size: 3.4 KiB

+21
View File
@@ -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
)
+42
View File
@@ -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=
+40
View File
@@ -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
+14
View File
@@ -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
+108
View File
@@ -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[:])
}
+43
View File
@@ -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")
}
}
+451
View File
@@ -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 = `<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>MTUCI Messenger API (Lab 3) - Swagger UI</title>
<link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css" />
<style>
body { margin: 0; background: #fafafa; }
.swagger-ui .topbar { display: none; }
</style>
</head>
<body>
<div id="swagger-ui"></div>
<script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
<script>
window.onload = function() {
SwaggerUIBundle({
url: "/openapi.json",
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIBundle.SwaggerUIStandalonePreset
],
layout: "BaseLayout"
});
};
</script>
</body>
</html>`
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 <base64(username:password)>, 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
}
+168
View File
@@ -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 ""
}
File diff suppressed because it is too large Load Diff
+75
View File
@@ -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"`
}
File diff suppressed because it is too large Load Diff
+105
View File
@@ -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
}
+53
View File
@@ -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);
+17
View File
@@ -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);
+8
View File
@@ -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
+80
View File
@@ -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()
+25
View File
@@ -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
+444
View File
@@ -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()
+372
View File
@@ -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'<svg xmlns="http://www.w3.org/2000/svg" width="{width}" height="{height}" viewBox="0 0 {width} {height}" style="background:#ffffff;font-family:sans-serif">',
' <text x="390" y="28" text-anchor="middle" font-size="16" font-weight="bold" fill="#111827">Lab 3 Track 1: Cost of Scaling &amp; Saturation Point (RPS)</text>',
f' <line x1="{pad_l}" y1="{pad_t}" x2="{pad_l}" y2="{pad_t + chart_h}" stroke="#9ca3af" stroke-width="1"/>',
f' <line x1="{pad_l}" y1="{pad_t + chart_h}" x2="{width - 30}" y2="{pad_t + chart_h}" stroke="#9ca3af" stroke-width="1"/>',
]
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' <line x1="{pad_l}" y1="{y:.1f}" x2="{width - 30}" y2="{y:.1f}" stroke="#e5e7eb" stroke-width="1"/>')
lines.append(f' <text x="{pad_l - 8}" y="{y + 4:.1f}" text-anchor="end" font-size="11" fill="#4b5563">{val}</text>')
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' <rect x="{x:.1f}" y="{y:.1f}" width="{bar_w}" height="{bh:.1f}" rx="4" fill="{color}"/>')
lines.append(f' <text x="{x + bar_w / 2:.1f}" y="{y - 6:.1f}" text-anchor="middle" font-size="11" font-weight="bold" fill="#111827">{val:.1f}</text>')
lines.append(f' <text x="{x + bar_w / 2:.1f}" y="{pad_t + chart_h + 18}" text-anchor="middle" font-size="11" fill="#374151">{label}</text>')
lines.append(' <text x="390" y="346" text-anchor="middle" font-size="11" fill="#6b7280">Blue: Fixed 2.0 CPU Budget | Green: Resource Growth | Orange: DB Saturation | Purple: Batch Pipeline + Pool Tuning</text>')
lines.append("</svg>")
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()