feat(app) lab 3 implemented

This commit is contained in:
imadev
2026-10-30 18:11:30 +03:00
parent f731f9b460
commit 48a616e910
57 changed files with 1390 additions and 303 deletions
+25 -8
View File
@@ -1,9 +1,10 @@
# Copy to .env for your LOCAL synthetic test environment; never commit .env.
# compose.yaml reads these values. Only POSTGRES_PASSWORD is a secret.
# AGENT: Copy to .env for your LOCAL synthetic test environment; never commit
# .env. compose.yaml reads these values. Only POSTGRES_PASSWORD is a secret.
APP_HOST=0.0.0.0
APP_PORT=8080
APP_ENV=lab
SESSION_TTL_SECONDS=3600
IDEMPOTENCY_TTL_SECONDS=86400
DB_POOL_MAX_CONNS=10
# Local PostgreSQL. The API receives a full DATABASE_URL built by compose.yaml.
@@ -11,14 +12,30 @@ POSTGRES_USER=messenger
POSTGRES_PASSWORD=replace-with-a-local-password
POSTGRES_DB=messenger
# Host port for the API. 8081 is used only by the optional short-TTL check.
APP_PORT_PUBLISH=8080
APP_SHORT_TTL_PORT=8081
# Redis is the session store (lab 2 grade 4); PostgreSQL stays the source of
# truth for users, chats, memberships and messages.
# Redis is the shared session store. AOF keeps absolute session TTLs.
SESSION_STORE=redis
# HAProxy is the only public API entrypoint. API replicas use expose, not ports.
LB_PORT=8080
HAPROXY_STATS_PORT=8404
# Per-replica and other services' resource limits.
API_REPLICAS=2
API_CPU_LIMIT=0.50
API_MEM_LIMIT=256M
POSTGRES_CPU_LIMIT=1.0
POSTGRES_MEM_LIMIT=512M
REDIS_CPU_LIMIT=0.50
REDIS_MEM_LIMIT=256M
HAPROXY_CPU_LIMIT=0.50
HAPROXY_MEM_LIMIT=128M
# K6 for detailed tests
K6_VUS=10
K6_DURATION=60
K6_CPU_LIMIT=1.0
K6_MEM_LIMIT=512M
# Optional overrides instead of the compose-generated URLs. A *_FILE value is
# read from a file, which is how Docker/Compose secrets are usually mounted.
# DATABASE_URL=postgres://messenger:password@localhost:5432/messenger?sslmode=disable
+39 -9
View File
@@ -1,18 +1,48 @@
## Лабораторная 3
Автор / группа: TODO
Целевая оценка (3/4/5): TODO
Трек 5, если заявлен: TODO
Целевая оценка: 4
Commit/PR: ``TODO``
Что реализовано и что перенесено: TODO
Команды запуска из чистого clone: TODO
Результаты проверок и ссылка на REPORT.md: TODO
Ограничения / известные ошибки: TODO
Источники и использование ИИ: TODO
Что реализовано и что перенесено:
- Go/Fiber API перенесён из lab2; PostgreSQL остаётся источником истины,
Redis хранит общие сессии.
- Добавлены HAProxy как единственная публичная точка входа, две API-реплики
без публикации портов, общий `X-Instance-Id` и graceful shutdown.
- Реализована общая идемпотентность POST сообщения в PostgreSQL; миграции
вынесены в отдельный one-shot сервис `migrate`.
- Добавлены `scripts/restart.sh`, `scripts/stop-one.sh` и
`scripts/rolling-update.sh`; rolling update проверен под нагрузкой k6.
Команды запуска из чистого clone:
```sh
cp .env.example .env
# задать POSTGRES_PASSWORD
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
make wait
make test
```
Результаты проверок и ссылка на REPORT.md: `make check`, `make validate`,
`make test`, `make test-persistence`, `make test-failover`,
`make test-concurrency`; сводка — в `REPORT.md` и
`evidence/grade-3-4.md`.
Ограничения / известные ошибки: один Docker-host; PostgreSQL, Redis и HAProxy
остаются единичными точками отказа; TLS и вложения не входят в lab3. Ветки
проверки пароля и «пользователь не найден» имеют разное время выполнения —
теоретическая временная атака описана в `REPORT.md`.
Источники и использование ИИ: официальная документация Docker Compose,
HAProxy, Go/Fiber; код и инфраструктура подготовлены с помощью
DeepSeek V4.1 Flash + OpenCode.
- [ ] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами.
- [ ] Контракт и публичные тесты не ослаблены.
- [ ] make check и make test выполнены; приложен реальный вывод.
- [ ] `make check` и `make test` выполнены; приложен реальный вывод.
- [ ] Сценарии отказов/безопасности своего уровня воспроизведены.
- [ ] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens.
- [ ] README задания сохранён, REPORT.md содержит инструкцию именно моего решения.
- [ ] README задания сохранён, `REPORT.md` содержит инструкцию именно этого решения.
+6 -2
View File
@@ -13,6 +13,7 @@ certs/private/
volumes/
data/
backups/
# Runtime/build artifacts
.venv/
__pycache__/
@@ -28,9 +29,12 @@ coverage/
.DS_Store
.idea/
.vscode/
# Keep small, sanitized evidence summaries in evidence/ under version control.
# Inspect git diff --cached: ignore rules are not a secret scanner.
# Local application builds
app/tmp/
app/server
# Agent workflow artifacts
AGENTS.md
TASKS.md
CHANGELOG.md
-3
View File
@@ -1,6 +1,3 @@
# syntax=docker/dockerfile:1.7
# AGENT: Two-stage build. The final image contains only the static binary and a
# CA bundle, runs as a non-root user and keeps the server as PID 1 for signals.
FROM golang:1.27.1-alpine AS build
WORKDIR /src
+39 -2
View File
@@ -2,12 +2,18 @@ PYTHON ?= python3
BASE_URL ?= http://localhost:8080
CA_FILE ?=
ACTION_SCRIPT ?=
COMPOSE ?= docker compose --env-file .env
VUS ?= 10
DURATION ?= 60s
TLS_ARGS = $(if $(CA_FILE),--ca-file "$(CA_FILE)",)
.PHONY: help check validate test load test-persistence
.PHONY: help check validate test load test-persistence test-failover test-concurrency app-test app-build up down wait k6
help:
@echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes"
@echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API"
@echo "test-concurrency: cross-replica idempotency race; test-failover/persistence: explicit hooks"
@echo "load: synthetic writes via tests/load.py; k6: k6 write load through HAProxy"
@echo "up/down/wait: compose lifecycle; app-test: Go unit tests"
check:
$(PYTHON) scripts/check_contract.py
@@ -24,3 +30,34 @@ load:
test-persistence:
@test -n "$(ACTION_SCRIPT)" || (echo "Set ACTION_SCRIPT to your implemented executable restart hook"; exit 2)
$(PYTHON) tests/resilience.py --mode persistence --action-script "$(ACTION_SCRIPT)" --base-url "$(BASE_URL)" $(TLS_ARGS)
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)
# ---------------------------
# Custom convenience commands
# ---------------------------
test-concurrency:
$(PYTHON) tests/custom/idempotency.py --base-url "$(BASE_URL)" $(TLS_ARGS)
app-test:
cd app && go test ./...
app-build:
cd app && go build ./cmd/server
up:
$(COMPOSE) up -d --build
down:
$(COMPOSE) down
wait:
@echo "waiting for $(BASE_URL)/health/ready"
@until curl -fsS "$(BASE_URL)/health/ready" >/dev/null; do sleep 1; done
@echo "ready"
k6:
$(COMPOSE) --profile load run --rm k6 run -e VUS=$(VUS) -e DURATION=$(DURATION) --summary-export /results/last.json /scripts/messages.js
+241 -21
View File
@@ -1,37 +1,257 @@
# Отчёт — лабораторная 3
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
- Автор, группа: ``<TODO LATER>``
- Целевая оценка: **4**
- Commit/PR: ``TODO``
- Источники, библиотеки и помощь ИИ: официальная документация Docker Compose,
HAProxy, Go/Fiber; код и инфраструктура подготовлены с помощью
DeepSeek V4.1 Flash + OpenCode
## Запуск из чистого clone
## 1. Что сделано
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
Рабочая база lab2 (Go + Fiber v3, PostgreSQL, Redis-сессии, миграции) доведена
до lab3:
## Архитектура и решения
- HAProxy стал единственной публичной точкой входа;
- запущены две API-реплики без публикации их портов;
- сессии и идемпотентность сообщений вынесены в общие хранилища;
- `X-Instance-Id` добавлен во все ответы API;
- миграции вынесены в отдельный one-shot сервис;
- настроены readiness, graceful shutdown и ограничения CPU/RAM;
- добавлены action-скрипты для restart/failover и rolling replacement;
- подготовлен профиль k6 для проверки rolling update под нагрузкой.
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
Обязательный контракт, `lab.json` и публичные тесты не изменялись. Существующие
неочевидные решения отмечены в коде комментариями `AGENT:`; перечень файлов
для их проверки и удаления находится в `LEFT_TO_REVIEW.md`. Новые комментарии
`AGENT:` в этой итерации не добавлялись: изменения и их обоснование записаны в
`CHANGELOG.md`.
## Доказательства критериев
## 2. Запуск из чистого clone
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
Требуется Docker Engine с Compose v2 и свободный порт `8080` (или другой
`LB_PORT`). Версии образов зафиксированы в `compose.yaml`.
```sh
cp .env.example .env
# задать локальный POSTGRES_PASSWORD; остальное можно оставить по умолчанию
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
make wait
```
Порядок запуска:
1. PostgreSQL и Redis проходят healthcheck.
2. Сервис `migrate` один раз применяет миграции и завершается.
3. Запускаются API-реплики с `RUN_MIGRATIONS=false`.
4. HAProxy начинает отдавать `/health/ready` только после готовности API.
Проверки:
```sh
make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
make test-concurrency
```
Дополнительно:
```sh
make k6 VUS=20 DURATION=60s # нагрузка через HAProxy
make validate PYTHON=.venv/bin/python
```
Остановка без удаления данных:
```sh
docker compose --env-file .env down
```
Намеренное удаление учебных данных (только отдельный стенд):
```sh
docker compose --env-file .env down -v
```
`.env` в репозиторий не попадает; в `.env.example` лежит только placeholder
пароля.
## 3. Архитектура и решения
```text
клиент
│ HTTP :8080
▼
HAProxy ── readiness /health/ready, retries, stats :8404, Prometheus /metrics
│ Docker DNS, server-template api 1..4
├──────────────┐
▼ ▼
API-1 API-2 ... API-N (Go/Fiber, без публикации портов)
│ │
└──────┬───────┘
▼
PostgreSQL ← users/chats/messages + message_idempotency
Redis ← общие сессии (AOF)
migrate — one-shot, RUN_MIGRATIONS / MIGRATE_ONLY
```
### 3.1. Компоненты и лимиты
| Компонент | Роль | Решение |
| --- | --- | --- |
| `haproxy` | LB и публичная точка входа | `server-template api 4 api:8080 resolvers docker`; health check `/health/ready` каждые 1 с, `fall 2` |
| `api` | бизнес-API | `deploy.replicas: ${API_REPLICAS:-2}`, `expose: 8080`, без `ports` |
| `migrate` | миграции | тот же образ, `MIGRATE_ONLY=true`, `restart: "no"` |
| `postgres` | источник истины | named volume `pgdata`, healthcheck, версия 16.10 |
| `redis` | общие сессии | AOF `everysec`, named volume `redisdata` |
| `k6` | нагрузка | профиль `load`, подключается только при явном запуске |
У API, PostgreSQL, Redis и HAProxy есть CPU/RAM-лимиты
(`deploy.resources.limits`, значения из `.env`). У API нет `container_name`,
поэтому Compose может масштабировать сервис.
### 3.2. Миграции
`app/cmd/server/main.go` поддерживает два режима:
- обычный API: `RUN_MIGRATIONS=false`, схемой занимается отдельный сервис;
- `MIGRATE_ONLY=true`: применить миграции, закрыть пул и выйти, не открывая
Redis.
Это убирает гонку миграций при старте нескольких реплик и при rolling update.
Миграция `0002_message_idempotency` аддитивная: старая версия приложения может
работать с уже созданной таблицей, новая версия требует её наличия. Поэтому
порядок «сначала migrate, потом новые API» безопасен.
### 3.3. `X-Instance-Id`
Middleware в `app/internal/app.go` ставит заголовок на каждый ответ, включая
health и ошибки. Значение берётся из `INSTANCE_ID`, а если он не задан — из
hostname процесса. В Compose hostname уникален для контейнера, поэтому
реплики различимы; значение не меняется в течение жизни процесса.
Если hostname получить нельзя и `INSTANCE_ID` не задан, конфигурация
завершается ошибкой. Раньше в этом случае молча подставлялось литеральное
значение `api`, из-за чего несколько процессов могли получить одинаковый
идентификатор.
### 3.4. Идемпотентность сообщений
Таблица `message_idempotency`:
- PK `(sender_id, chat_id, idempotency_key)` — ровно область «пользователь +
путь чата + ключ»; метод в текущем API только один;
- `request_hash` — SHA-256 текста сообщения;
- `message_id` — ссылка на уже созданное сообщение;
- `created_at`, `expires_at` — окно хранения (по умолчанию 24 часа).
Алгоритм в `app/internal/store/messages.go`:
1. Быстрый lookup по ключу. Если запись не истекла и hash совпал — вернуть тот же
`Message` с `201`.
2. Иначе открыть транзакцию, вставить сообщение с проверкой членства в чате,
вставить ключ через `ON CONFLICT`.
3. Если конкурентная реплика уже вставила этот ключ, транзакция текущего
запроса откатывается, и читается результат победившей реплики. При другом
hash — `409`.
4. Транзиентная ошибка не фиксирует ключ: транзакция откатывается, клиент может
повторить с тем же ключом.
Так один ключ создаёт ровно одно сообщение даже при параллельных запросах через
разные реплики. Повтор снова проходит аутентификацию и проверку доступа к чату.
### 3.5. HAProxy и graceful shutdown
- backend discovery: Docker DNS `127.0.0.11:53`, `server-template api 4`, поэтому
`docker compose up --scale api=N` не требует правки конфига;
- health check: `GET /health/ready`, `inter 1s`, `fall 2` — обнаружение отказа
около 2 секунд (при бюджете 10 секунд);
- `retries 2`, `option redispatch` — короткие ошибки соединения не роняют запрос;
- при SIGTERM приложение сначала перестаёт отдавать `200` на readiness, затем
ждёт до 10 секунд; у контейнера `stop_grace_period: 15s`;
- stats UI/CSV на `:8404/stats`, Prometheus на `:8404/metrics`.
### 3.6. Readiness и транзакции
`/health/ready` проверяет PostgreSQL и Redis и не захватывает прикладных
блокировок. `pgxpool.Ping` берёт соединение из пула и возвращает его через
`defer`; `store.Ping` ограничивает проверку двумя секундами.
Отдельно проверены транзакции в `CreateChat` и `CreateMessage`. Откат больше не
выполняется на неограниченном `context.Background()`: используется контекст с
таймаутом. Если PostgreSQL перестал отвечать, соединение закрывается, а
PostgreSQL трактует закрытие соединения как откат и снимает блокировки строк.
Это не даёт неудачной транзакции удерживать соединение пула и мешать readiness
других запросов. Единственная явная advisory-блокировка — миграционная; она
снимается в `defer` с собственным таймаутом.
## 4. Доказательства критериев
| Критерий | Команда/сценарий | Наблюдаемый результат | Файл |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
| Публичный smoke | `make test` | `PASS: lab3 public API scenario` | `evidence/grade-3-4.md` |
| Офлайн-проверки | `make check` | `PASS: offline skeleton...` | `evidence/grade-3-4.md` |
| OpenAPI | `make validate PYTHON=.venv/bin/python` | `PASS: full OpenAPI 3.1...` | `evidence/grade-3-4.md` |
| ≥2 реплики, одна сессия | 10 запросов `/health/live` через LB | 2 разных `X-Instance-Id` | `evidence/grade-3-4.md` |
| Остановка одной реплики | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | 120–121 запись, 0–1 ошибка, восстановление 2.54–2.93 с | `evidence/grade-3-4.md` |
| Сохранность после restart | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | данные и bearer-токен сохранились | `evidence/grade-3-4.md` |
| Конкурентная идемпотентность | `make test-concurrency` | 12 запросов, 2 реплики, 1 сообщение, другой body → 409 | `evidence/grade-3-4.md` |
| CPU/RAM-лимиты, API без host ports | `compose.yaml`, `docker compose ps` | API только `expose`, лимиты заданы | `compose.yaml` |
| Rolling update под нагрузкой | `scripts/rolling-update.sh 2` + k6 20 VU/60 с | 41 605 итераций, 0 failed checks, p95 55.27 мс | `evidence/k6-rolling-20vu-60s.json` |
| Миграции однократно | `migrate` service, API `RUN_MIGRATIONS=false` | `migrate` завершился, API healthy | `compose.yaml`, `app/cmd/server/main.go` |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
Проверки HTTP запускались из контейнера в сети стенда: в рабочей оболочке
published ports были изолированы от хоста. Это ограничение среды, а не
приложения; на обычной машине команды `make test`/`make test-failover`
запускаются с хоста.
## Эксперименты и отказы
## 5. Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
### 5.1. Отказ одной API-реплики
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| Что сделано | Ожидание | Наблюдение | Восстановление |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
| Остановлена одна API-реплика при живой второй | LB исключает её, подтверждённые данные и сессия целы | 2 реплики до отказа; 120–121 успешная запись; 0–1 краткая ошибка | 2.54–2.93 с до первой успешной записи |
| Вручную остановлена вторая реплика | Трафик переходит на оставшуюся | 1698 успешных записей, 1 ошибка; обе реплики наблюдались до отказа | вторая реплика восстановлена через `up` |
## Ограничения и следующие шаги
Ошибка на границе отказа ожидаема: клиент мог отправить запрос в момент, когда
процесс уже остановлен, но HAProxy ещё не убрал backend. Повтор с тем же
`Idempotency-Key` не создал дубль.
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
### 5.2. Rolling update под нагрузкой
`scripts/rolling-update.sh 2` собирает образ и поочерёдно заменяет контейнеры:
останавливает один, удаляет, создаёт replacement, ждёт health и только потом
переходит к следующему. Во время этого k6 писал сообщения 20 VU в течение 60 с.
| Метрика | Значение |
| --- | ---: |
| Всего запросов | 41 608 |
| Итераций | 41 605 |
| Ошибок проверок | 0 |
| p95 | 55.27 мс |
| p99 | 71.15 мс |
Это подтверждает, что последовательная замена не рвёт поток целиком: HAProxy
успевает исключить остановленный backend. Сырой summary:
`evidence/k6-rolling-20vu-60s.json`.
## 6. Ограничения
- Один Docker-host: потеря узла не переживается. HAProxy, PostgreSQL и Redis
остаются единичными точками отказа; API-реплики не делают БД
высокодоступной.
- PostgreSQL не реплицирован. При потере `pgdata` данные теряются; Redis AOF
спасает сессии от рестарта, но не от потери диска.
- Compose — не Swarm: rolling-скрипт делает поочерёдную замену, но не даёт
маршрутизации между узлами.
- Профиль k6 — write-only. Он выбран намеренно: проверяется запись,
идемпотентность и БД; чтение и смешанный профиль — отдельный эксперимент.
- `X-Instance-Id` здесь — hostname контейнера, не скрыт.
- Проверка пароля и ветка «пользователь не найден» имеют разное время
выполнения: для неизвестного username Argon2 не запускается. Теоретически
это позволяет перечислять имена по времени ответа. Контракт требует только
одинаковый `401` и challenge; в lab3 временная атака не устраняется.
+18 -9
View File
@@ -1,3 +1,5 @@
// Command server starts the messenger HTTP API, applies optional migrations,
// and shuts down gracefully on SIGINT/SIGTERM.
package main
import (
@@ -8,10 +10,10 @@ import (
"syscall"
"time"
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal"
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/config"
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/database"
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/session"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/config"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/database"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/session"
)
func main() {
@@ -29,11 +31,18 @@ func main() {
}
defer pool.Close()
migrateCtx, cancelMigrate := context.WithTimeout(rootCtx, 60*time.Second)
err = database.Migrate(migrateCtx, pool, cfg.DatabaseURL)
cancelMigrate()
if err != nil {
log.Fatalf("migrations: %v", err)
if cfg.MigrateOnly || cfg.RunMigrations {
migrateCtx, cancelMigrate := context.WithTimeout(rootCtx, 60*time.Second)
err = database.Migrate(migrateCtx, pool, cfg.DatabaseURL)
cancelMigrate()
if err != nil {
log.Fatalf("migrations: %v", err)
}
}
if cfg.MigrateOnly {
log.Printf("migrations applied; migrate-only process exiting")
return
}
sessions, err := session.New(cfg.CacheURL, cfg.SessionTTL, cfg.RedisTimeout)
+1 -1
View File
@@ -1,4 +1,4 @@
module gitflic.ru/project/bulla-max/mtusi2026lab2
module gitflic.ru/project/bulla-max/mtusi2026lab
go 1.27.1
+18 -16
View File
@@ -1,18 +1,20 @@
// Package internal wires HTTP routes, middleware and storage into one Fiber
// application and owns the process-wide error handler.
package internal
import (
"errors"
"time"
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/auth"
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/chats"
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/common"
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/config"
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/health"
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/messages"
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/session"
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/store"
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/users"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/auth"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/chats"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/common"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/config"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/health"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/messages"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/session"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/store"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/users"
"github.com/gofiber/fiber/v3"
"github.com/gofiber/fiber/v3/middleware/recover"
"github.com/gofiber/fiber/v3/middleware/requestid"
@@ -24,7 +26,7 @@ func SignalGracefulShutdown() {
}
func New(cfg config.Config, pool *pgxpool.Pool, sessions *session.Store) *fiber.App {
st := store.New(pool, cfg.DBTimeout)
st := store.New(pool, cfg.DBTimeout, cfg.IdempotencyTTL)
app := fiber.New(fiber.Config{
ReadTimeout: 10 * time.Second,
@@ -36,6 +38,10 @@ func New(cfg config.Config, pool *pgxpool.Pool, sessions *session.Store) *fiber.
app.Use(recover.New())
app.Use(requestid.New())
app.Use(func(c fiber.Ctx) error {
c.Set("X-Instance-Id", cfg.InstanceID)
return c.Next()
})
health.RegisterRoutes(app.Group("/health"), st, sessions)
@@ -53,16 +59,12 @@ func New(cfg config.Config, pool *pgxpool.Pool, sessions *session.Store) *fiber.
return app
}
// handleError keeps every failure in the contract error envelope, including
// Fiber's own errors (404, 405, 413) and recovered panics.
func handleError(c fiber.Ctx, err error) error {
var appErr *common.AppError
if errors.As(err, &appErr) {
if appErr, ok := errors.AsType[*common.AppError](err); ok {
return common.SendError(c, appErr.Status, appErr.Code, appErr.Message)
}
var fiberErr *fiber.Error
if errors.As(err, &fiberErr) {
if fiberErr, ok := errors.AsType[*fiber.Error](err); ok {
return common.SendError(c, fiberErr.Code,
common.ErrorCodeFromStatus(fiberErr.Code), fiberErr.Message)
}
+15 -15
View File
@@ -1,3 +1,5 @@
// Package auth implements password hashing, Basic login, Bearer session
// middleware and the authentication routes.
package auth
import (
@@ -5,16 +7,18 @@ import (
"errors"
"strings"
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/common"
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/model"
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/session"
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/store"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/common"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/model"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/session"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/store"
"github.com/gofiber/fiber/v3"
"github.com/gofiber/fiber/v3/log"
)
const basicChallenge = `Basic realm="messenger", charset="UTF-8"`
const bearerChallenge = `Bearer realm="messenger"`
const (
basicChallenge = `Basic realm="messenger", charset="UTF-8"`
bearerChallenge = `Bearer realm="messenger"`
)
type Handler struct {
store *store.Store
@@ -25,9 +29,6 @@ func NewHandler(st *store.Store, sessions *session.Store) *Handler {
return &Handler{store: st, sessions: sessions}
}
// AGENT: CreateSession is the only endpoint that accepts Basic auth. It reads
// no JSON body and returns the same 401 for an unknown user and a wrong
// password, so the response does not reveal which usernames exist.
func (h *Handler) CreateSession(c fiber.Ctx) error {
username, password, ok := parseBasic(c.Get(fiber.HeaderAuthorization))
if !ok {
@@ -37,6 +38,11 @@ func (h *Handler) CreateSession(c fiber.Ctx) error {
user, err := h.store.GetUserByUsername(c.Context(), username)
if err != nil {
if common.IsCode(err, common.ErrorCodeNotFound) {
// An unknown username returns before Argon2 runs, while a known
// username with a wrong password runs VerifyPassword. The branches
// therefore take different time, so username enumeration through
// response timing is theoretically possible. The contract only
// requires the same 401 body and challenge.
return common.SendChallenge(c, basicChallenge, "invalid credentials")
}
return common.SendAppError(c, err)
@@ -62,8 +68,6 @@ func (h *Handler) CreateSession(c fiber.Ctx) error {
})
}
// RevokeSession deletes the current token. The middleware has already proven
// that the token exists, so a repeated DELETE is a 401, not a 204.
func (h *Handler) RevokeSession(c fiber.Ctx) error {
token, ok := common.SessionToken(c)
if !ok {
@@ -79,8 +83,6 @@ func (h *Handler) RevokeSession(c fiber.Ctx) error {
return c.SendStatus(fiber.StatusNoContent)
}
// BearerAuth accepts only an opaque Bearer token. X-User-Id is deliberately
// never read: with lab 2 it can neither create nor override an identity.
func BearerAuth(sessions *session.Store) fiber.Handler {
return func(c fiber.Ctx) error {
header := strings.TrimSpace(c.Get(fiber.HeaderAuthorization))
@@ -95,8 +97,6 @@ func BearerAuth(sessions *session.Store) fiber.Handler {
if errors.Is(err, session.ErrNotFound) {
return common.SendChallenge(c, bearerChallenge, "session expired or revoked")
}
// AGENT: A dead Redis must not degrade to "anonymous allowed".
// Protected calls get a bounded 503 instead of a 401 or a bypass.
log.Errorf("session lookup: %v", err)
return common.SendError(c, fiber.StatusServiceUnavailable,
common.ErrorCodeUnavailable, "session store unavailable")
+8 -7
View File
@@ -1,6 +1,3 @@
// AGENT: Argon2id is used instead of bcrypt because the contract allows 128
// Unicode code points and bcrypt silently truncates at 72 bytes. Salt and
// parameters are stored inside the encoded hash string.
package auth
import (
@@ -38,8 +35,6 @@ func HashPassword(password string) (string, error) {
base64.RawStdEncoding.EncodeToString(key)), nil
}
// VerifyPassword recomputes the digest with the stored parameters and compares
// in constant time.
func VerifyPassword(encoded, password string) (bool, error) {
parts := strings.Split(encoded, "$")
if len(parts) != 6 || parts[1] != "argon2id" {
@@ -57,13 +52,19 @@ func VerifyPassword(encoded, password string) (bool, error) {
if _, err := fmt.Sscanf(parts[3], "m=%d,t=%d,p=%d", &memory, &iterations, &parallelism); err != nil {
return false, ErrInvalidHash
}
// argon2.IDKey panics when the cost parameters are outside its supported
// range. A corrupted row or an attacker-supplied encoding must be rejected
// with ErrInvalidHash instead of taking the process down.
if iterations < 1 || parallelism < 1 || memory < 8*uint32(parallelism) {
return false, ErrInvalidHash
}
salt, err := base64.RawStdEncoding.DecodeString(parts[4])
if err != nil {
if err != nil || len(salt) == 0 {
return false, ErrInvalidHash
}
expected, err := base64.RawStdEncoding.DecodeString(parts[5])
if err != nil {
if err != nil || len(expected) == 0 {
return false, ErrInvalidHash
}
+18
View File
@@ -44,3 +44,21 @@ func TestPasswordHashIsSalted(t *testing.T) {
t.Fatal("invalid encoded hash was accepted")
}
}
func TestVerifyPasswordRejectsMalformedCostAndEmptyDigest(t *testing.T) {
malformed := []string{
// Empty digest would make argon2 derive a zero-length key.
"$argon2id$v=19$m=65536,t=2,p=4$c2FsdA$",
// Zero cost parameters are outside argon2's supported range and would
// otherwise panic inside the KDF.
"$argon2id$v=19$m=65536,t=0,p=4$c2FsdA$YWJjZA",
"$argon2id$v=19$m=65536,t=2,p=0$c2FsdA$YWJjZA",
"$argon2id$v=19$m=1,t=2,p=4$c2FsdA$YWJjZA",
}
for _, encoded := range malformed {
ok, err := VerifyPassword(encoded, "same-password-123")
if err == nil || ok {
t.Fatalf("VerifyPassword(%q) = (%v, %v), want ErrInvalidHash", encoded, ok, err)
}
}
}
+2 -2
View File
@@ -1,8 +1,8 @@
package auth
import (
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/session"
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/store"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/session"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/store"
"github.com/gofiber/fiber/v3"
)
+3 -2
View File
@@ -1,8 +1,9 @@
// Package chats implements chat creation, lookup and cursor-paginated listing.
package chats
import (
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/common"
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/store"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/common"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/store"
"github.com/gofiber/fiber/v3"
"github.com/google/uuid"
)
+1 -1
View File
@@ -1,7 +1,7 @@
package chats
import (
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/store"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/store"
"github.com/gofiber/fiber/v3"
)
-9
View File
@@ -9,15 +9,6 @@ import (
"github.com/gofiber/fiber/v3"
)
// AGENT: Field-level validation is deliberately not delegated to a generic
// struct validator. The contract needs specific messages for blank strings,
// Unicode length and duplicate member IDs, so handlers call the Validators in
// validation.go after this strict JSON decoding step.
//
// BindJSON enforces the request format from the contract: JSON content type,
// exactly one JSON value, no unknown fields and correct Go types. Field-level
// rules (non-blank strings, lengths, UUID lists) stay in the handlers so their
// messages can be specific.
func BindJSON(c fiber.Ctx, dst any) error {
if contentType := c.Get(fiber.HeaderContentType); !strings.HasPrefix(contentType, "application/json") {
return UnsupportedMedia("invalid JSON body")
+5 -6
View File
@@ -1,3 +1,5 @@
// Package common contains cross-cutting HTTP helpers: contract errors, JSON
// binding, validation, cursor pagination and timestamp formatting.
package common
import (
@@ -87,8 +89,8 @@ func Unavailable(message string) *AppError {
// IsCode reports whether err is an AppError with the given contract code.
func IsCode(err error, code string) bool {
var appErr *AppError
return errors.As(err, &appErr) && appErr.Code == code
appErr, ok := errors.AsType[*AppError](err)
return ok && appErr.Code == code
}
func ErrorCodeFromStatus(status int) string {
@@ -126,8 +128,7 @@ func SendError(c fiber.Ctx, status int, code, message string) error {
}
func SendAppError(c fiber.Ctx, err error) error {
var appErr *AppError
if errors.As(err, &appErr) {
if appErr, ok := errors.AsType[*AppError](err); ok {
return SendError(c, appErr.Status, appErr.Code, appErr.Message)
}
@@ -135,8 +136,6 @@ func SendAppError(c fiber.Ctx, err error) error {
ErrorCodeInternal, "Internal server error")
}
// SendChallenge emits a 401 with the WWW-Authenticate value required by the
// contract: Basic for login, Bearer for every protected endpoint.
func SendChallenge(c fiber.Ctx, challenge, message string) error {
c.Set(fiber.HeaderWWWAuthenticate, challenge)
return SendError(c, fiber.StatusUnauthorized, ErrorCodeUnauthorized, message)
@@ -0,0 +1,30 @@
package common
import (
"strings"
"testing"
)
func TestValidateIdempotencyKey(t *testing.T) {
tests := []struct {
name string
key string
ok bool
}{
{name: "hex", key: "4f8c2d1e", ok: true},
{name: "allowed punctuation", key: "load-1_a.b:c", ok: true},
{name: "empty", key: "", ok: false},
{name: "space", key: "two words", ok: false},
{name: "slash", key: "a/b", ok: false},
{name: "too long", key: strings.Repeat("a", 129), ok: false},
}
for _, test := range tests {
t.Run(test.name, func(t *testing.T) {
got := ValidateIdempotencyKey(test.key) == ""
if got != test.ok {
t.Fatalf("ValidateIdempotencyKey(%q) valid = %v, want %v", test.key, got, test.ok)
}
})
}
}
+1 -8
View File
@@ -6,21 +6,15 @@ import (
)
const (
// KeyUserID is the request-scoped key set by the Bearer middleware.
KeyUserID = "userID"
// KeySessionToken is the raw token of the current request.
KeyUserID = "userID"
KeySessionToken = "sessionToken"
)
// UserID returns the authenticated user ID and whether the middleware set it.
func UserID(c fiber.Ctx) (uuid.UUID, bool) {
userID, ok := c.Locals(KeyUserID).(uuid.UUID)
return userID, ok
}
// MustUserID is for handlers mounted behind BearerAuth, where the middleware
// guarantees the local. A missing value is a programming error, not a client
// error, so it becomes a recovered 500 instead of an anonymous request.
func MustUserID(c fiber.Ctx) uuid.UUID {
userID, ok := UserID(c)
if !ok {
@@ -29,7 +23,6 @@ func MustUserID(c fiber.Ctx) uuid.UUID {
return userID
}
// SessionToken returns the raw bearer token of the current request.
func SessionToken(c fiber.Ctx) (string, bool) {
token, ok := c.Locals(KeySessionToken).(string)
return token, ok && token != ""
-6
View File
@@ -10,9 +10,6 @@ import (
"github.com/google/uuid"
)
// CursorKeyCtx is the opaque keyset position: (created_at, id) plus the
// resource/user the cursor belongs to. ContextID stops a cursor from one chat
// or user list being replayed against another.
type CursorKeyCtx struct {
Time time.Time
ID uuid.UUID
@@ -88,9 +85,6 @@ func DecodeCursor(cursor string) (*CursorKeyCtx, bool) {
return &CursorKeyCtx{Time: parsedTime, ID: parsedID, ContextID: parsedContext}, true
}
// NextCursor returns a cursor pointing at the last item of a page when more
// rows exist. limit+1 rows are fetched by the store, so a non-nil cursor means
// the next page is known to be non-empty at read time.
func NextCursor[T interface {
GetID() uuid.UUID
GetCreatedAt() time.Time
-18
View File
@@ -29,21 +29,3 @@ func TestCursorRoundTrip(t *testing.T) {
}
}
}
func TestValidatePasswordRange(t *testing.T) {
cases := []struct {
password string
valid bool
}{
{"short", false},
{"12345678901", false},
{"123456789012", true},
{"пароль-из-двенадцати", true},
{"😀", false},
}
for _, tc := range cases {
if got := ValidatePassword(tc.password) == ""; got != tc.valid {
t.Fatalf("ValidatePassword(%q) valid=%v, want %v", tc.password, got, tc.valid)
}
}
}
+21
View File
@@ -0,0 +1,21 @@
package common
import "testing"
func TestValidatePasswordRange(t *testing.T) {
cases := []struct {
password string
valid bool
}{
{"short", false},
{"12345678901", false},
{"123456789012", true},
{"пароль-из-двенадцати", true},
{"😀", false},
}
for _, tc := range cases {
if got := ValidatePassword(tc.password) == ""; got != tc.valid {
t.Fatalf("ValidatePassword(%q) valid=%v, want %v", tc.password, got, tc.valid)
}
}
}
+4 -13
View File
@@ -5,19 +5,15 @@ import (
"time"
)
// storageTimePrecision is the maximum precision shared by PostgreSQL
// timestamptz columns and the JSON representation. PostgreSQL stores
// microseconds, so keeping the same boundary in Go prevents a create response
// from showing more precision than a later read can reproduce.
// PostgreSQL stores microseconds, so keeping the same boundary in Go
// prevents a create response from showing more precision
// than a later read can reproduce.
const storageTimePrecision = time.Microsecond
type RFCFormTime time.Time
func (t RFCFormTime) MarshalJSON() ([]byte, error) {
// RFC 3339 permits an optional fractional second. Use all six digits that
// PostgreSQL can store, and omit the fraction only for an exact second.
// A fixed six-digit fraction is also accepted by strict consumers that only
// understand 3- or 6-digit fractions (for example Python 3.9's parser).
// RFC 3339 permits an optional fractional second.
utc := time.Time(t).UTC().Truncate(storageTimePrecision)
layout := "2006-01-02T15:04:05Z"
if utc.Nanosecond() != 0 {
@@ -27,10 +23,5 @@ func (t RFCFormTime) MarshalJSON() ([]byte, error) {
}
func NowUTC() RFCFormTime {
// AGENT: The API used to truncate timestamps to whole seconds to keep
// keyset ordering consistent with JSON. RFC 3339 supports fractional seconds
// and PostgreSQL has microsecond precision, so use that precision end to end:
// timestamps remain ordered after serialization without discarding sub-second
// information.
return RFCFormTime(time.Now().UTC().Truncate(storageTimePrecision))
}
+14 -1
View File
@@ -8,7 +8,10 @@ import (
"github.com/google/uuid"
)
var usernameRegex = regexp.MustCompile(`^[a-z0-9_]{3,32}$`)
var (
usernameRegex = regexp.MustCompile(`^[a-z0-9_]{3,32}$`)
idempotencyKeyRegex = regexp.MustCompile(`^[A-Za-z0-9._:-]{1,128}$`)
)
func blank(s string) bool {
return strings.TrimSpace(s) == ""
@@ -71,6 +74,16 @@ func ValidateMessageText(text string) string {
return ""
}
func ValidateIdempotencyKey(key string) string {
if key == "" {
return "Idempotency-Key header is required"
}
if !idempotencyKeyRegex.MatchString(key) {
return "Idempotency-Key must match ^[A-Za-z0-9._:-]{1,128}$"
}
return ""
}
func ValidateMemberIDs(ids []uuid.UUID, callerID uuid.UUID) string {
if len(ids) < 1 || len(ids) > 100 {
return "member_ids must contain between 1 and 100 members"
+71 -18
View File
@@ -1,6 +1,5 @@
// AGENT: All runtime configuration is read here so every other package receives
// explicit values instead of calling os.Getenv. Values are compatible with
// .env.example and support the *_FILE convention used by Compose secrets.
// Package config loads and validates process configuration from environment
// variables and optional *_FILE secrets.
package config
import (
@@ -12,25 +11,36 @@ import (
)
type Config struct {
Host string
Port string
SessionTTL time.Duration
DatabaseURL string
CacheURL string
DBMaxConns int32
DBTimeout time.Duration
RedisTimeout time.Duration
StartupWait time.Duration
Host string
Port string
InstanceID string
SessionTTL time.Duration
IdempotencyTTL time.Duration
DatabaseURL string
CacheURL string
DBMaxConns int32
DBTimeout time.Duration
RedisTimeout time.Duration
StartupWait time.Duration
RunMigrations bool
MigrateOnly bool
}
func Load() (Config, error) {
instance, err := instanceID()
if err != nil {
return Config{}, err
}
cfg := Config{
Host: envOr("APP_HOST", "0.0.0.0"),
Port: envOr("APP_PORT", "8080"),
DBMaxConns: 10,
DBTimeout: 5 * time.Second,
RedisTimeout: 2 * time.Second,
StartupWait: 30 * time.Second,
Host: envOr("APP_HOST", "0.0.0.0"),
Port: envOr("APP_PORT", "8080"),
InstanceID: instance,
DBMaxConns: 10,
DBTimeout: 5 * time.Second,
RedisTimeout: 2 * time.Second,
StartupWait: 30 * time.Second,
RunMigrations: true,
}
ttlSeconds, err := strconv.Atoi(envOr("SESSION_TTL_SECONDS", "3600"))
@@ -39,6 +49,19 @@ func Load() (Config, error) {
}
cfg.SessionTTL = time.Duration(ttlSeconds) * time.Second
idempotencySeconds, err := strconv.Atoi(envOr("IDEMPOTENCY_TTL_SECONDS", "86400"))
if err != nil || idempotencySeconds < 1 {
return cfg, fmt.Errorf("IDEMPOTENCY_TTL_SECONDS must be a positive integer")
}
cfg.IdempotencyTTL = time.Duration(idempotencySeconds) * time.Second
if cfg.RunMigrations, err = envBool("RUN_MIGRATIONS", true); err != nil {
return cfg, err
}
if cfg.MigrateOnly, err = envBool("MIGRATE_ONLY", false); err != nil {
return cfg, err
}
if value := envOr("DB_POOL_MAX_CONNS", ""); value != "" {
n, convErr := strconv.Atoi(value)
if convErr != nil || n < 1 || n > 100 {
@@ -55,6 +78,10 @@ func Load() (Config, error) {
return cfg, fmt.Errorf("DATABASE_URL or DATABASE_URL_FILE is required")
}
if cfg.MigrateOnly {
return cfg, nil
}
cfg.CacheURL, err = secret("CACHE_URL")
if err != nil {
return cfg, err
@@ -76,6 +103,32 @@ func Load() (Config, error) {
return cfg, nil
}
func instanceID() (string, error) {
if value := strings.TrimSpace(os.Getenv("INSTANCE_ID")); value != "" {
return value, nil
}
name, err := os.Hostname()
if err != nil {
return "", fmt.Errorf("determine INSTANCE_ID: %w", err)
}
if name = strings.TrimSpace(name); name == "" {
return "", fmt.Errorf("determine INSTANCE_ID: hostname is empty and INSTANCE_ID is not set")
}
return name, nil
}
func envBool(name string, fallback bool) (bool, error) {
value := os.Getenv(name)
if value == "" {
return fallback, nil
}
parsed, err := strconv.ParseBool(value)
if err != nil {
return false, fmt.Errorf("%s must be true or false", name)
}
return parsed, nil
}
func envOr(name, fallback string) string {
if value := os.Getenv(name); value != "" {
return value
+27
View File
@@ -0,0 +1,27 @@
package config
import "testing"
func TestInstanceIDUsesConfiguredValue(t *testing.T) {
t.Setenv("INSTANCE_ID", " api-1 ")
got, err := instanceID()
if err != nil {
t.Fatalf("instanceID: %v", err)
}
if got != "api-1" {
t.Fatalf("instanceID = %q, want api-1", got)
}
}
func TestInstanceIDFallsBackToHostname(t *testing.T) {
t.Setenv("INSTANCE_ID", " ")
got, err := instanceID()
if err != nil {
t.Fatalf("instanceID: %v", err)
}
if got == "" {
t.Fatal("instanceID returned an empty value")
}
}
-2
View File
@@ -27,8 +27,6 @@ func Connect(ctx context.Context, url string, maxConns int32, wait time.Duration
return nil, fmt.Errorf("create pool: %w", err)
}
// AGENT: Compose may start the API while PostgreSQL is still booting. A bounded
// retry keeps the container from crash-looping without hiding a permanent error.
deadline := time.Now().Add(wait)
for {
pingCtx, cancel := context.WithTimeout(ctx, 2*time.Second)
+6 -13
View File
@@ -1,6 +1,3 @@
// AGENT: golang-migrate now runs the embedded SQL files instead of the previous
// hand-written runner. The legacy table upgrade below keeps existing lab 2
// volumes usable, so switching engines does not require deleting data.
package database
import (
@@ -22,16 +19,10 @@ import (
var migrationFiles embed.FS
const (
// The old in-house runner used this advisory lock. We keep the same key for
// the one-time table upgrade so an upgrade cannot race a still-running old
// instance that is applying the baseline migration.
legacyMigrationLockID int64 = 728_2026
migrationsTable = "schema_migrations"
)
// Migrate applies the embedded golang-migrate migrations. golang-migrate takes
// its own PostgreSQL advisory lock, records the current version and dirty flag
// in schema_migrations, and wraps each migration file in one transaction.
func Migrate(ctx context.Context, pool *pgxpool.Pool, databaseURL string) error {
if err := upgradeLegacyMigrationsTable(ctx, pool); err != nil {
return err
@@ -47,8 +38,6 @@ func Migrate(ctx context.Context, pool *pgxpool.Pool, databaseURL string) error
_ = source.Close()
return fmt.Errorf("parse DATABASE_URL for migrations: %w", err)
}
// golang-migrate acquires its lock with context.Background(). A PostgreSQL
// lock timeout keeps startup bounded if another instance never releases it.
if connConfig.RuntimeParams == nil {
connConfig.RuntimeParams = make(map[string]string)
}
@@ -89,7 +78,7 @@ func Migrate(ctx context.Context, pool *pgxpool.Pool, databaseURL string) error
// upgradeLegacyMigrationsTable replaces the table written by the previous
// in-house runner (version text, applied_at) with the golang-migrate schema
// (version bigint, dirty boolean). The schema itself is left untouched and the
// (version bigint, dirty boolean). The data schema itself is left untouched and the
// highest applied version is carried over, so a preserved volume does not need
// to be recreated. The migration DDL is idempotent, but preserving the version
// keeps the migration history truthful.
@@ -132,7 +121,11 @@ func upgradeLegacyMigrationsTable(ctx context.Context, pool *pgxpool.Pool) error
if err != nil {
return fmt.Errorf("begin migration table upgrade: %w", err)
}
defer func() { _ = tx.Rollback(context.Background()) }()
defer func() {
rollbackCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
_ = tx.Rollback(rollbackCtx)
}()
const upgrade = `
DROP TABLE IF EXISTS schema_migrations_migrate_tmp;
@@ -1,5 +1,3 @@
-- AGENT: Local rollback for the baseline schema. The application only runs Up
-- migrations; this file exists so golang-migrate can also step down in tests.
DROP TABLE IF EXISTS messages;
DROP TABLE IF EXISTS chat_members;
DROP TABLE IF EXISTS chats;
@@ -1,8 +1,3 @@
-- AGENT: Single versioned baseline migration for lab 2. The application records
-- applied versions in schema_migrations, so rerunning it never duplicates rows.
-- The unique username constraint is the authoritative defence against the
-- concurrent-registration race, not a SELECT followed by an INSERT.
CREATE TABLE IF NOT EXISTS users (
id uuid PRIMARY KEY,
username text NOT NULL,
@@ -39,8 +34,5 @@ CREATE TABLE IF NOT EXISTS messages (
CONSTRAINT messages_text_len CHECK (char_length(text) BETWEEN 1 AND 4000)
);
-- AGENT: This composite index matches the only history predicate and sort order:
-- (chat_id, created_at, id). It lets each keyset page seek directly to the cursor
-- instead of scanning the chat history from the beginning.
CREATE INDEX IF NOT EXISTS messages_chat_created_id_idx
ON messages (chat_id, created_at, id);
@@ -0,0 +1 @@
DROP TABLE IF EXISTS message_idempotency;
@@ -0,0 +1,14 @@
CREATE TABLE IF NOT EXISTS message_idempotency (
sender_id uuid NOT NULL REFERENCES users(id) ON DELETE CASCADE,
chat_id uuid NOT NULL REFERENCES chats(id) ON DELETE CASCADE,
idempotency_key text NOT NULL,
request_hash bytea 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 (sender_id, chat_id, idempotency_key),
CONSTRAINT message_idempotency_key_len CHECK (char_length(idempotency_key) BETWEEN 1 AND 128)
);
CREATE INDEX IF NOT EXISTS message_idempotency_expires_at_idx
ON message_idempotency (expires_at);
+12 -2
View File
@@ -18,7 +18,10 @@ func TestEmbeddedMigrationsParse(t *testing.T) {
for _, entry := range entries {
names[entry.Name()] = true
}
for _, want := range []string{"0001_init.up.sql", "0001_init.down.sql"} {
for _, want := range []string{
"0001_init.up.sql", "0001_init.down.sql",
"0002_message_idempotency.up.sql", "0002_message_idempotency.down.sql",
} {
if !names[want] {
t.Fatalf("migration %q is missing from the embedded filesystem", want)
}
@@ -37,7 +40,14 @@ func TestEmbeddedMigrationsParse(t *testing.T) {
if version != 1 {
t.Fatalf("first migration version = %d, want 1", version)
}
version, err = source.Next(version)
if err != nil {
t.Fatalf("read second migration: %v", err)
}
if version != 2 {
t.Fatalf("second migration version = %d, want 2", version)
}
if _, err := source.Next(version); !errors.Is(err, fs.ErrNotExist) {
t.Fatalf("expected the baseline to be the last migration, got %v", err)
t.Fatalf("expected 0002 to be the last migration, got %v", err)
}
}
+5 -6
View File
@@ -1,11 +1,13 @@
// Package health exposes liveness and readiness endpoints plus the process
// shutdown flag used by readiness.
package health
import (
"sync/atomic"
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/common"
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/session"
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/store"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/common"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/session"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/store"
"github.com/gofiber/fiber/v3"
)
@@ -32,9 +34,6 @@ func (h *Handler) Live(c fiber.Ctx) error {
return c.JSON(Status{Status: "ok"})
}
// Ready answers whether the synchronous mandatory path can be served. Both
// PostgreSQL and Redis are critical here: business data and sessions live in
// them respectively.
func (h *Handler) Ready(c fiber.Ctx) error {
if shuttingDown.Load() {
return common.SendError(c, fiber.StatusServiceUnavailable,
+2 -2
View File
@@ -1,8 +1,8 @@
package health
import (
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/session"
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/store"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/session"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/store"
"github.com/gofiber/fiber/v3"
)
+10 -3
View File
@@ -1,8 +1,10 @@
// Package messages implements message creation with idempotency and message
// history pagination.
package messages
import (
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/common"
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/store"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/common"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/store"
"github.com/gofiber/fiber/v3"
"github.com/google/uuid"
)
@@ -28,6 +30,11 @@ func (h *Handler) CreateMessage(c fiber.Ctx) error {
common.ErrorCodeInvalidRequest, "invalid chat_id format")
}
idempotencyKey := c.Get("Idempotency-Key")
if msg := common.ValidateIdempotencyKey(idempotencyKey); msg != "" {
return common.SendError(c, fiber.StatusBadRequest, common.ErrorCodeInvalidRequest, msg)
}
var req CreateMessageRequest
if err := common.BindJSON(c, &req); err != nil {
return common.SendAppError(c, err)
@@ -36,7 +43,7 @@ func (h *Handler) CreateMessage(c fiber.Ctx) error {
return common.SendError(c, fiber.StatusBadRequest, common.ErrorCodeInvalidRequest, msg)
}
message, err := h.store.CreateMessage(c.Context(), chatID, userID, req.Text)
message, err := h.store.CreateMessage(c.Context(), chatID, userID, req.Text, idempotencyKey)
if err != nil {
return common.SendAppError(c, err)
}
+1 -1
View File
@@ -1,7 +1,7 @@
package messages
import (
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/store"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/store"
"github.com/gofiber/fiber/v3"
)
+3 -1
View File
@@ -1,9 +1,11 @@
// Package model defines the JSON-facing domain types shared by handlers,
// storage and the public contract.
package model
import (
"time"
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/common"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/common"
"github.com/google/uuid"
)
+2 -5
View File
@@ -1,7 +1,5 @@
// AGENT: Redis is the single session store for lab 2 grade 4. PostgreSQL stays
// the source of truth for business data. The token itself is never stored: Redis
// holds SHA-256(token) -> user id with a TTL, so a leaked Redis dump does not
// hand out usable bearer tokens.
// Package session stores bearer sessions in Redis. Tokens are hashed before
// they become keys, and the configured TTL is absolute.
package session
import (
@@ -57,7 +55,6 @@ func (s *Store) Ping(ctx context.Context) error {
return s.client.Ping(pingCtx).Err()
}
// Create returns the raw token exactly once and stores only its digest.
func (s *Store) Create(ctx context.Context, userID uuid.UUID) (string, time.Time, error) {
raw := make([]byte, 32)
if _, err := rand.Read(raw); err != nil {
+3 -6
View File
@@ -5,15 +5,12 @@ import (
"errors"
"time"
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/common"
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/model"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/common"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/model"
"github.com/google/uuid"
"github.com/jackc/pgx/v5"
)
// CreateChat inserts the chat and every membership row in one transaction.
// Any unknown member aborts the whole transaction, so a partially created chat
// can never be observed.
func (s *Store) CreateChat(ctx context.Context, title string, memberIDs []uuid.UUID) (model.Chat, error) {
ctx, cancel := s.withTimeout(ctx)
defer cancel()
@@ -22,7 +19,7 @@ func (s *Store) CreateChat(ctx context.Context, title string, memberIDs []uuid.U
if err != nil {
return model.Chat{}, dbError(err)
}
defer func() { _ = tx.Rollback(context.Background()) }()
defer rollback(tx)
for _, memberID := range memberIDs {
var exists int
+5 -9
View File
@@ -5,25 +5,22 @@ import (
"errors"
"net"
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/common"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/common"
"github.com/jackc/pgx/v5"
"github.com/jackc/pgx/v5/pgconn"
)
func isUniqueViolation(err error) bool {
var pgErr *pgconn.PgError
return errors.As(err, &pgErr) && pgErr.Code == "23505"
pgErr, ok := errors.AsType[*pgconn.PgError](err)
return ok && pgErr.Code == "23505"
}
// dbError separates a drained dependency (503) from a real bug (500). SQL
// details never reach the client; callers only emit the AppError message.
func dbError(err error) error {
if err == nil {
return nil
}
var pgErr *pgconn.PgError
if errors.As(err, &pgErr) {
if pgErr, ok := errors.AsType[*pgconn.PgError](err); ok {
switch pgErr.Code {
case "23505":
return common.Conflict("resource already exists")
@@ -32,8 +29,7 @@ func dbError(err error) error {
}
}
var netErr net.Error
if errors.As(err, &netErr) || errors.Is(err, context.DeadlineExceeded) ||
if _, ok := errors.AsType[net.Error](err); ok || errors.Is(err, context.DeadlineExceeded) ||
errors.Is(err, context.Canceled) ||
pgconn.SafeToRetry(err) ||
errors.Is(err, pgx.ErrTxClosed) {
+85 -9
View File
@@ -1,21 +1,30 @@
package store
import (
"bytes"
"context"
"crypto/sha256"
"errors"
"time"
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/common"
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/model"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/common"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/model"
"github.com/google/uuid"
"github.com/jackc/pgx/v5"
)
// CreateMessage uses INSERT ... SELECT so the membership check and the insert
// are a single atomic statement: no window where the user is removed between
// check and write. Zero affected rows means the chat is missing or foreign.
func (s *Store) CreateMessage(ctx context.Context, chatID, senderID uuid.UUID, text string) (model.Message, error) {
func (s *Store) CreateMessage(ctx context.Context, chatID, senderID uuid.UUID, text, idempotencyKey string) (model.Message, error) {
ctx, cancel := s.withTimeout(ctx)
defer cancel()
fingerprint := sha256.Sum256([]byte(text))
if message, found, err := s.findIdempotentMessage(ctx, senderID, chatID, idempotencyKey, fingerprint[:]); err != nil {
return model.Message{}, err
} else if found {
return message, nil
}
message := model.Message{
ID: uuid.New(),
ChatID: chatID,
@@ -24,7 +33,13 @@ func (s *Store) CreateMessage(ctx context.Context, chatID, senderID uuid.UUID, t
CreatedAt: common.NowUTC(),
}
tag, err := s.pool.Exec(ctx, `
tx, err := s.pool.Begin(ctx)
if err != nil {
return model.Message{}, dbError(err)
}
defer rollback(tx)
tag, err := tx.Exec(ctx, `
INSERT INTO messages (id, chat_id, sender_id, text, created_at)
SELECT $1, $2, $3, $4, $5
WHERE EXISTS (SELECT 1 FROM chat_members WHERE chat_id = $2 AND user_id = $3)`,
@@ -36,9 +51,72 @@ func (s *Store) CreateMessage(ctx context.Context, chatID, senderID uuid.UUID, t
return model.Message{}, common.NotFound("chat not found")
}
expiresAt := time.Time(message.CreatedAt).Add(s.idempotencyTTL)
tag, err = tx.Exec(ctx, `
INSERT INTO message_idempotency
(sender_id, chat_id, idempotency_key, request_hash, message_id, created_at, expires_at)
VALUES ($1, $2, $3, $4, $5, $6, $7)
ON CONFLICT (sender_id, chat_id, idempotency_key) DO UPDATE
SET request_hash = EXCLUDED.request_hash,
message_id = EXCLUDED.message_id,
created_at = EXCLUDED.created_at,
expires_at = EXCLUDED.expires_at
WHERE message_idempotency.expires_at <= now()`,
senderID, chatID, idempotencyKey, fingerprint[:], message.ID,
time.Time(message.CreatedAt), expiresAt)
if err != nil {
return model.Message{}, dbError(err)
}
if tag.RowsAffected() == 0 {
rollback(tx)
stored, found, lookupErr := s.findIdempotentMessage(ctx, senderID, chatID, idempotencyKey, fingerprint[:])
if lookupErr != nil {
return model.Message{}, lookupErr
}
if !found {
return model.Message{}, common.Internal()
}
return stored, nil
}
if err = tx.Commit(ctx); err != nil {
return model.Message{}, dbError(err)
}
return message, nil
}
func (s *Store) findIdempotentMessage(ctx context.Context, senderID, chatID uuid.UUID, idempotencyKey string, expectedHash []byte) (model.Message, bool, error) {
var message model.Message
var createdAt time.Time
var storedHash []byte
err := s.pool.QueryRow(ctx, `
SELECT m.id, m.chat_id, m.sender_id, m.text, m.created_at, i.request_hash
FROM message_idempotency i
JOIN messages m ON m.id = i.message_id
JOIN chat_members cm ON cm.chat_id = i.chat_id AND cm.user_id = i.sender_id
WHERE i.sender_id = $1
AND i.chat_id = $2
AND i.idempotency_key = $3
AND i.expires_at > now()`,
senderID, chatID, idempotencyKey).Scan(
&message.ID, &message.ChatID, &message.SenderID, &message.Text, &createdAt, &storedHash)
if errors.Is(err, pgx.ErrNoRows) {
return model.Message{}, false, nil
}
if err != nil {
return model.Message{}, false, dbError(err)
}
if !bytes.Equal(storedHash, expectedHash) {
return model.Message{}, false, common.Conflict("idempotency key reused with a different message")
}
message.CreatedAt = common.RFCFormTime(createdAt.UTC())
return message, true, nil
}
func (s *Store) ListMessages(ctx context.Context, userID, chatID uuid.UUID, limit int, cursor *common.CursorKeyCtx) (*common.Page[model.Message], error) {
isMember, err := s.IsMember(ctx, userID, chatID)
if err != nil {
@@ -56,8 +134,6 @@ func (s *Store) ListMessages(ctx context.Context, userID, chatID uuid.UUID, limi
ctx, cancel := s.withTimeout(ctx)
defer cancel()
// AGENT: limit+1 is fetched so next_cursor is known to be non-null without a
// second COUNT query; the extra row is never returned to the client.
cursorTime, cursorID := cursorValues(cursor)
rows, err := s.pool.Query(ctx, `
SELECT id, chat_id, sender_id, text, created_at
+1 -1
View File
@@ -3,7 +3,7 @@ package store
import (
"time"
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/common"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/common"
"github.com/google/uuid"
)
+5 -9
View File
@@ -2,10 +2,6 @@
// parameterized SQL, one bounded pool and explicit transaction boundaries.
// Contract errors are returned as common.AppError so HTTP status mapping stays
// in one place.
//
// AGENT: Persistence was split from one large file by aggregate (users, chats,
// messages). Queries, transaction boundaries and error mapping are unchanged;
// only file organization and scan helpers changed.
package store
import (
@@ -16,12 +12,13 @@ import (
)
type Store struct {
pool *pgxpool.Pool
timeout time.Duration
pool *pgxpool.Pool
timeout time.Duration
idempotencyTTL time.Duration
}
func New(pool *pgxpool.Pool, timeout time.Duration) *Store {
return &Store{pool: pool, timeout: timeout}
func New(pool *pgxpool.Pool, timeout, idempotencyTTL time.Duration) *Store {
return &Store{pool: pool, timeout: timeout, idempotencyTTL: idempotencyTTL}
}
func (s *Store) withTimeout(ctx context.Context) (context.Context, context.CancelFunc) {
@@ -34,7 +31,6 @@ func (s *Store) Ping(ctx context.Context) error {
return s.pool.Ping(pingCtx)
}
// rowScanner is the common subset of pgx.Row and pgx.Rows used by scan helpers.
type rowScanner interface {
Scan(dest ...any) error
}
+16
View File
@@ -0,0 +1,16 @@
package store
import (
"context"
"time"
"github.com/jackc/pgx/v5"
)
const rollbackTimeout = 5 * time.Second
func rollback(tx pgx.Tx) {
ctx, cancel := context.WithTimeout(context.Background(), rollbackTimeout)
defer cancel()
_ = tx.Rollback(ctx)
}
+2 -5
View File
@@ -5,8 +5,8 @@ import (
"errors"
"time"
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/common"
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/model"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/common"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/model"
"github.com/google/uuid"
"github.com/jackc/pgx/v5"
)
@@ -28,9 +28,6 @@ func (s *Store) CreateUser(ctx context.Context, username, displayName, passwordH
VALUES ($1, $2, $3, $4, $5)`,
user.ID, user.Username, user.DisplayName, user.PasswordHash, time.Time(user.CreatedAt))
if err != nil {
// AGENT: The unique index is the real guard. Two concurrent registrations
// with the same username both reach INSERT; exactly one commits, the other
// gets SQLSTATE 23505 and is mapped to 409 instead of a 500.
if isUniqueViolation(err) {
return model.User{}, common.Conflict("username already taken")
}
+4 -3
View File
@@ -1,9 +1,10 @@
// Package users implements registration and the current-user endpoint.
package users
import (
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/auth"
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/common"
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/store"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/auth"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/common"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/store"
"github.com/gofiber/fiber/v3"
)
+1 -1
View File
@@ -1,7 +1,7 @@
package users
import (
"gitflic.ru/project/bulla-max/mtusi2026lab2/internal/store"
"gitflic.ru/project/bulla-max/mtusi2026lab/internal/store"
"github.com/gofiber/fiber/v3"
)
+96 -38
View File
@@ -1,7 +1,10 @@
# AGENT: Single local stack for lab 2 grade 4. PostgreSQL is the source of
# truth, Redis stores sessions with AOF persistence. Both have named volumes,
# so `docker compose restart` preserves data and `down -v` is never needed.
name: mtusi2026lab2
name: mtusi2026lab
x-api-build: &api-build
image: mtusi2026lab-api:local
build:
context: .
dockerfile: Dockerfile
x-api-environment: &api-environment
APP_HOST: 0.0.0.0
@@ -9,6 +12,8 @@ x-api-environment: &api-environment
DB_POOL_MAX_CONNS: ${DB_POOL_MAX_CONNS:-10}
DATABASE_URL: postgres://${POSTGRES_USER:-messenger}:${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}@postgres:5432/${POSTGRES_DB:-messenger}?sslmode=disable
CACHE_URL: redis://redis:6379/0
SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600}
IDEMPOTENCY_TTL_SECONDS: ${IDEMPOTENCY_TTL_SECONDS:-86400}
services:
postgres:
@@ -26,13 +31,25 @@ services:
timeout: 3s
retries: 20
start_period: 5s
deploy:
resources:
limits:
cpus: "${POSTGRES_CPU_LIMIT:-1.0}"
memory: "${POSTGRES_MEM_LIMIT:-512M}"
redis:
image: redis:7.4.7-alpine
restart: unless-stopped
# AOF survives a container restart and keeps absolute key TTLs, which is
# exactly what the session-persistence check needs.
command: ["redis-server", "--appendonly", "yes", "--appendfsync", "everysec", "--save", ""]
command:
[
"redis-server",
"--appendonly",
"yes",
"--appendfsync",
"everysec",
"--save",
"",
]
volumes:
- redisdata:/data
healthcheck:
@@ -41,55 +58,96 @@ services:
timeout: 3s
retries: 20
start_period: 3s
deploy:
resources:
limits:
cpus: "${REDIS_CPU_LIMIT:-0.50}"
memory: "${REDIS_MEM_LIMIT:-256M}"
migrate:
<<: *api-build
restart: "no"
depends_on:
postgres:
condition: service_healthy
environment:
<<: *api-environment
MIGRATE_ONLY: "true"
api:
build:
context: .
dockerfile: Dockerfile
<<: *api-build
restart: unless-stopped
depends_on:
postgres:
condition: service_healthy
redis:
condition: service_healthy
migrate:
condition: service_completed_successfully
environment:
<<: *api-environment
SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600}
ports:
- "${APP_PORT_PUBLISH:-8080}:8080"
RUN_MIGRATIONS: "false"
expose:
- "8080"
healthcheck:
test: ["CMD", "wget", "-q", "-O", "-", "http://127.0.0.1:8080/health/ready"]
interval: 5s
timeout: 4s
retries: 12
start_period: 15s
test:
["CMD", "wget", "-q", "-O", "-", "http://127.0.0.1:8080/health/ready"]
interval: 2s
timeout: 2s
retries: 10
start_period: 10s
stop_grace_period: 15s
deploy:
replicas: ${API_REPLICAS:-2}
resources:
limits:
cpus: "${API_CPU_LIMIT:-0.50}"
memory: "${API_MEM_LIMIT:-256M}"
# AGENT: Only for the short-TTL expiry check. It shares PostgreSQL and Redis
# with the main API, so its 2-second sessions are visible to every instance.
api-short-ttl:
profiles: ["checks"]
build:
context: .
dockerfile: Dockerfile
haproxy:
image: haproxy:3.2.6-alpine
restart: unless-stopped
depends_on:
postgres:
api:
condition: service_healthy
redis:
condition: service_healthy
environment:
<<: *api-environment
SESSION_TTL_SECONDS: "2"
ports:
- "${APP_SHORT_TTL_PORT:-8081}:8080"
- "${LB_PORT:-8080}:8080"
- "${HAPROXY_STATS_PORT:-8404}:8404"
volumes:
- ./infra/haproxy/haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro
healthcheck:
test: ["CMD", "wget", "-q", "-O", "-", "http://127.0.0.1:8080/health/ready"]
interval: 5s
timeout: 4s
retries: 12
start_period: 15s
stop_grace_period: 15s
test:
["CMD", "wget", "-q", "-O", "/dev/null", "http://127.0.0.1:8404/stats"]
interval: 2s
timeout: 2s
retries: 10
start_period: 5s
deploy:
resources:
limits:
cpus: "${HAPROXY_CPU_LIMIT:-0.50}"
memory: "${HAPROXY_MEM_LIMIT:-128M}"
k6:
image: grafana/k6:1.3.0
profiles: ["load"]
depends_on:
haproxy:
condition: service_healthy
user: "0:0"
environment:
BASE_URL: http://haproxy:8080
VUS: ${K6_VUS:-10}
DURATION: ${K6_DURATION:-60s}
volumes:
- ./load:/scripts:ro
- ./evidence:/results
command: ["run", "/scripts/messages.js"]
deploy:
resources:
limits:
cpus: "${K6_CPU_LIMIT:-1.0}"
memory: "${K6_MEM_LIMIT:-512M}"
volumes:
pgdata:
+68
View File
@@ -0,0 +1,68 @@
# Доказательства уровней 3/4
Дата: 2026-10-26. Хост: 4 vCPU, 7.5 GiB RAM, Docker 29.3.0, Compose 5.6.0.
Стенд: 2 API-реплики, PostgreSQL 16.10, Redis 7.4.7, HAProxy 3.2.6.
Секреты и токены в файлы не сохранялись.
## Публичный smoke и сохранность
```text
make check
PASS: offline skeleton structure, local refs and Python syntax
make validate PYTHON=.venv/bin/python
PASS: full OpenAPI 3.1 and JSON Schema validation
make test
PASS: lab3 public API scenario; infrastructure and grading evidence remain separate.
make test-persistence ACTION_SCRIPT=scripts/restart.sh
PASS: persistence preserved confirmed data and existing session.
```
В рабочей оболочке published ports были изолированы от хоста, поэтому
HTTP-тесты запускались из контейнера в сети `mtusi2026lab_default`. Команды
`Makefile` и проверяемые сценарии те же; на обычной машине они запускаются с
хоста.
## Отказ реплики
Команда: `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`
(эквивалентный запуск из контейнера в сети стенда).
| Прогон | Реплик до отказа | Успешных записей | Ошибок | Восстановление, с |
| --- | ---: | ---: | ---: | ---: |
| 1 | 2 | 121 | 1 | 2.538 |
| 2 | 2 | 121 | 0 | 2.932 |
| 3 | 2 | 120 | 1 | 2.787 |
| 4 | 2 | 121 | 1 | 2.661 |
Дополнительно вручную остановлен второй контейнер (`api-10`) через
`TARGET_INSTANCE_ID=<hostname> scripts/stop-one.sh`: 1698 успешных записей,
1 ошибка, после остановки трафик продолжила вторая реплика. Оба контейнера
восстановлены командой `docker compose ... up -d --no-deps --scale api=2 api`.
## Конкурентная идемпотентность
`tests/custom/idempotency.py` отправил 12 одновременных POST с одним
`Idempotency-Key` через HAProxy. Наблюдались 2 разные реплики; все ответы `201`
с одним `message.id`; в истории ровно одна запись; повтор с другим телом — `409`.
```text
PASS: 12 concurrent requests used 2 replicas and stored one message
```
## Rolling update под нагрузкой
`k6`: 20 VU, 60 с, запись сообщений; во время прогона `scripts/rolling-update.sh 2`
поочерёдно заменил обе API-реплики.
```text
http_reqs: 41608
iterations: 41605
failed checks: 0
p95: 55.27 ms
p99: 71.15 ms
```
Сырой summary: `evidence/k6-rolling-20vu-60s.json`.
+173
View File
@@ -0,0 +1,173 @@
{
"metrics": {
"checks": {
"fails": 0,
"passes": 83213,
"value": 1
},
"data_received": {
"count": 18932152,
"rate": 310938.9713237004
},
"data_sent": {
"count": 15354668,
"rate": 252182.88300965153
},
"http_req_blocked": {
"avg": 0.019555880263410815,
"max": 16.957181,
"med": 0.006217,
"min": 0.002294,
"p(50)": 0.006217,
"p(95)": 0.011781500000000014,
"p(99)": 0.24456504000000032
},
"http_req_connecting": {
"avg": 0.0001791579023264757,
"max": 1.169158,
"med": 0,
"min": 0,
"p(50)": 0,
"p(95)": 0,
"p(99)": 0
},
"http_req_duration": {
"avg": 28.19379073502721,
"max": 1244.395337,
"med": 23.995004,
"min": 1.917426,
"p(50)": 23.995004,
"p(95)": 55.274196450000005,
"p(99)": 71.1459338
},
"http_req_duration{expected_response:true}": {
"avg": 28.19379073502721,
"max": 1244.395337,
"med": 23.995004,
"min": 1.917426,
"p(50)": 23.995004,
"p(95)": 55.274196450000005,
"p(99)": 71.1459338
},
"http_req_failed": {
"fails": 41608,
"passes": 0,
"value": 0
},
"http_req_receiving": {
"avg": 0.18104418227264027,
"max": 18.158135,
"med": 0.064632,
"min": 0.020427,
"p(50)": 0.064632,
"p(95)": 0.6289225000000005,
"p(99)": 2.5293797500000004
},
"http_req_sending": {
"avg": 0.09656115958469512,
"max": 28.421382,
"med": 0.0250795,
"min": 0.010067,
"p(50)": 0.0250795,
"p(95)": 0.2945132000000001,
"p(99)": 1.6073071800000003
},
"http_req_tls_handshaking": {
"avg": 0,
"max": 0,
"med": 0,
"min": 0,
"p(50)": 0,
"p(95)": 0,
"p(99)": 0
},
"http_req_waiting": {
"avg": 27.91618539316964,
"max": 1244.2995,
"med": 23.724883,
"min": 1.841486,
"p(50)": 23.724883,
"p(95)": 54.91490730000001,
"p(99)": 70.85231543
},
"http_reqs": {
"count": 41608,
"rate": 683.3638732055672
},
"iteration_duration": {
"avg": 28.79506371409711,
"max": 1244.572308,
"med": 24.606595,
"min": 2.078469,
"p(50)": 24.606595,
"p(95)": 55.85472899999998,
"p(99)": 71.58917543999998
},
"iterations": {
"count": 41605,
"rate": 683.3146016323213
},
"vus": {
"max": 20,
"min": 20,
"value": 20
},
"vus_max": {
"max": 20,
"min": 20,
"value": 20
}
},
"root_group": {
"checks": {
"instance header": {
"fails": 0,
"id": "5eee12e230ebaeb27a5ba544fcce920f",
"name": "instance header",
"passes": 41605,
"path": "::instance header"
},
"message 201": {
"fails": 0,
"id": "6445aff337e1ade0bc10402fbac79882",
"name": "message 201",
"passes": 41605,
"path": "::message 201"
}
},
"groups": {
"setup": {
"checks": {
"chat 201": {
"fails": 0,
"id": "1e2d5cbe7afc66d31563ad87ae39a13f",
"name": "chat 201",
"passes": 1,
"path": "::setup::chat 201"
},
"login 201": {
"fails": 0,
"id": "6b4ee6c971082051e34713d1c1baafa1",
"name": "login 201",
"passes": 1,
"path": "::setup::login 201"
},
"register 201": {
"fails": 0,
"id": "09b4317cf1f0cccb084b00576cc103e4",
"name": "register 201",
"passes": 1,
"path": "::setup::register 201"
}
},
"groups": {},
"id": "5c0f8025f7e0b6654089e5b00e950f1a",
"name": "setup",
"path": "::setup"
}
},
"id": "d41d8cd98f00b204e9800998ecf8427e",
"name": "",
"path": ""
}
}
+40
View File
@@ -0,0 +1,40 @@
global
log stdout format raw local0
maxconn 4096
defaults
log global
mode http
option httplog
option dontlognull
timeout connect 2s
timeout client 30s
timeout server 30s
timeout http-request 10s
timeout http-keep-alive 30s
retries 2
option redispatch
resolvers docker
nameserver dns 127.0.0.11:53
resolve_retries 3
timeout resolve 1s
timeout retry 1s
frontend api_frontend
bind *:8080
default_backend api
backend api
balance roundrobin
option httpchk GET /health/ready
http-check expect status 200
default-server check inter 1s fastinter 500ms downinter 1s fall 2 rise 2
server-template api 4 api:8080 resolvers docker init-addr last,libc,none
frontend stats
bind *:8404
http-request use-service prometheus-exporter if { path /metrics }
stats enable
stats uri /stats
stats refresh 5s
+70
View File
@@ -0,0 +1,70 @@
import http from 'k6/http';
import encoding from 'k6/encoding';
import { check } from 'k6';
const baseURL = __ENV.BASE_URL || 'http://localhost:8080';
const vus = Number(__ENV.VUS || 10);
const duration = __ENV.DURATION || '60s';
export const options = {
scenarios: {
writes: {
executor: 'constant-vus',
vus,
duration,
},
},
summaryTrendStats: ['avg', 'min', 'med', 'p(50)', 'p(95)', 'p(99)', 'max'],
};
function headers(token) {
return {
Authorization: `Bearer ${token}`,
'Content-Type': 'application/json',
Accept: 'application/json',
};
}
export function setup() {
const suffix = `${Date.now()}_${Math.floor(Math.random() * 1e6)}`;
const username = `u_load_${suffix}`.slice(0, 32);
const password = `Load-${suffix}-pass`;
const registration = http.post(
`${baseURL}/api/v1/users`,
JSON.stringify({ username, display_name: 'Load test', password }),
{ headers: { 'Content-Type': 'application/json', Accept: 'application/json' } },
);
check(registration, { 'register 201': (r) => r.status === 201 });
const user = registration.json();
const basic = encoding.b64encode(`${username}:${password}`);
const login = http.post(`${baseURL}/api/v1/auth/sessions`, null, {
headers: { Authorization: `Basic ${basic}`, Accept: 'application/json' },
});
check(login, { 'login 201': (r) => r.status === 201 });
const token = login.json('token');
const chat = http.post(
`${baseURL}/api/v1/chats`,
JSON.stringify({ title: 'Load profile', member_ids: [user.id] }),
{ headers: headers(token) },
);
check(chat, { 'chat 201': (r) => r.status === 201 });
return { token, chatID: chat.json('id') };
}
export default function (data) {
const key = `${__VU}-${__ITER}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
const response = http.post(
`${baseURL}/api/v1/chats/${data.chatID}/messages`,
JSON.stringify({ text: `load message ${key}` }),
{ headers: { ...headers(data.token), 'Idempotency-Key': key } },
);
check(response, {
'message 201': (r) => r.status === 201,
'instance header': (r) => Boolean(r.headers['X-Instance-Id'] || r.headers['x-instance-id']),
});
}
+4
View File
@@ -0,0 +1,4 @@
#!/bin/sh
set -eu
cd "$(dirname "$0")/.."
docker compose --env-file .env restart postgres redis haproxy api
+42
View File
@@ -0,0 +1,42 @@
#!/bin/sh
set -eu
cd "$(dirname "$0")/.."
COMPOSE="docker compose --env-file .env"
N=${1:-$($COMPOSE ps -q api | wc -l)}
[ "$N" -ge 2 ] || {
echo "need at least two API replicas; got $N" >&2
exit 2
}
wait_healthy() {
attempts=0
while [ "$attempts" -lt 90 ]; do
ids=$($COMPOSE ps -q api)
count=$(printf '%s\n' "$ids" | sed '/^$/d' | wc -l)
healthy=$(for id in $ids; do docker inspect -f '{{.State.Health.Status}}' "$id"; done | grep -c '^healthy$' || true)
if [ "$count" -eq "$N" ] && [ "$healthy" -eq "$N" ]; then
return 0
fi
attempts=$((attempts + 1))
sleep 1
done
echo "API replicas did not become healthy in time" >&2
return 1
}
$COMPOSE build api
i=0
while [ "$i" -lt "$N" ]; do
target=$($COMPOSE ps -q api | head -n 1)
[ -n "$target" ] || {
echo "no API container to replace" >&2
exit 2
}
echo "replacing $target"
docker stop --time 10 "$target" >/dev/null
docker rm "$target" >/dev/null
$COMPOSE up -d --no-deps --no-recreate --scale api="$N" api
wait_healthy
i=$((i + 1))
done
echo "rolling replacement complete for $N replicas"
+20
View File
@@ -0,0 +1,20 @@
#!/bin/sh
set -eu
: "${TARGET_INSTANCE_ID:?test provides target API instance alias}"
cd "$(dirname "$0")/.."
target=""
for id in $(docker compose --env-file .env ps -q api); do
hostname=$(docker inspect -f '{{.Config.Hostname}}' "$id")
if [ "$hostname" = "$TARGET_INSTANCE_ID" ]; then
target="$id"
break
fi
done
if [ -z "$target" ]; then
echo "no running API replica has instance id $TARGET_INSTANCE_ID" >&2
exit 2
fi
docker stop --time 5 "$target" >/dev/null
+92
View File
@@ -0,0 +1,92 @@
#!/usr/bin/env python3
# The public smoke checks sequential replay;
# this test checks the cross-replica race.
import argparse
import sys
import threading
import uuid
from pathlib import Path
ROOT = Path(__file__).resolve().parents[2]
sys.path.insert(0, str(ROOT / "tests"))
from client import Client, Failure, check # noqa: E402
def main():
parser = argparse.ArgumentParser(
description="Concurrent idempotency check through the load balancer"
)
parser.add_argument("--base-url", default="http://localhost:8080")
parser.add_argument("--ca-file", default=None)
parser.add_argument("--requests", type=int, default=12)
args = parser.parse_args()
setup = Client(args.base_url, args.ca_file)
alice, _, _, chat = setup.bootstrap()
key = "concurrent-" + uuid.uuid4().hex
body = {"text": "one concurrent message"}
path = f"/api/v1/chats/{chat['id']}/messages"
results = []
lock = threading.Lock()
def worker():
client = Client(args.base_url, args.ca_file)
try:
response = client.call(
"POST",
path,
201,
actor=alice,
body=body,
headers={"Idempotency-Key": key},
schema="Message",
)
with lock:
results.append(
(response["json"], response["headers"].get("X-Instance-Id"))
)
except Failure as error:
with lock:
results.append((error, None))
threads = [threading.Thread(target=worker) for _ in range(args.requests)]
for thread in threads:
thread.start()
for thread in threads:
thread.join()
check(len(results) == args.requests, "not every concurrent request finished")
check(
all(isinstance(message, dict) for message, _ in results),
"a concurrent request failed",
)
ids = {message["id"] for message, _ in results}
check(len(ids) == 1, "concurrent requests returned different message IDs")
instances = {instance for _, instance in results if instance}
check(
len(instances) >= 2, "expected the load balancer to use at least two replicas"
)
page = setup.call("GET", path + "?limit=100", actor=alice, schema="MessagePage")[
"json"
]
stored = [message for message in page["items"] if message["id"] == next(iter(ids))]
check(len(stored) == 1, "concurrent requests stored more than one message")
setup.call(
"POST",
path,
409,
actor=alice,
body={"text": "different body"},
headers={"Idempotency-Key": key},
)
print(
f"PASS: {args.requests} concurrent requests used {len(instances)} replicas and stored one message"
)
if __name__ == "__main__":
main()