Добавить две реплики API за HAProxy и проверку отказа одной из них.

Общие сессии и ключ идемпотентности позволяют продолжать чтение и запись, когда одна реплика остановлена.
This commit is contained in:
2026-11-06 17:31:40 +03:00
parent 4303783848
commit d065cffb4e
31 changed files with 980 additions and 109 deletions
+14 -8
View File
@@ -1,13 +1,19 @@
# Copy to .env for your LOCAL synthetic test environment; never commit .env.
# These are logical interface suggestions; map actual framework names in REPORT.md.
# Скопируйте в .env. Файл .env не коммитится.
# Значения ниже — учебные заглушки локального стенда, не боевые секреты.
POSTGRES_USER=messenger
POSTGRES_PASSWORD=change-me
POSTGRES_DB=messenger
REDIS_PASSWORD=change-me
APP_HOST=0.0.0.0
APP_PORT=8080
APP_ENV=lab
SESSION_TTL_SECONDS=3600
# Choose credentials locally. File paths contain no secret values.
DATABASE_URL_FILE=/run/secrets/database_url
# Optional on 3, required use on 4 in lab2; Redis OR Valkey:
SESSION_STORE=postgres
CACHE_URL_FILE=/run/secrets/cache_url
API_REPLICAS=2
IDEMPOTENCY_TTL_SECONDS=86400
SHUTDOWN_TIMEOUT_SECONDS=8
API_REPLICAS=2
API_CPU_LIMIT=0.50
API_MEM_LIMIT=256M
DB_MAX_CONNS=8
ARGON2_TIME=2
ARGON2_MEMORY_KIB=19456
ARGON2_THREADS=1
+28 -14
View File
@@ -1,18 +1,32 @@
## Лабораторная 3
Автор / группа: TODO
Целевая оценка (3/4/5): TODO
Трек 5, если заявлен: TODO
Автор / группа: Колмычков Иван Сергеевич, БВТ2303
Целевая оценка (3/4/5): 4
Трек 5, если заявлен: не заявлен
Что реализовано и что перенесено: TODO
Команды запуска из чистого clone: TODO
Результаты проверок и ссылка на REPORT.md: TODO
Ограничения / известные ошибки: TODO
Источники и использование ИИ: TODO
Что реализовано и что перенесено: из lab2 перенесены PostgreSQL, Redis с AOF, Argon2id, Basic → Bearer и миграции. Добавлены HAProxy как единственная точка входа, две реплики API без published port, общий Redis для сессий, `X-Instance-Id`, обязательный `Idempotency-Key` на отправку сообщения и однократный сервис `migrate`. Отказ одной реплики, перезапуск стенда и поочерёдная замена контейнеров описаны скриптами `scripts/stop-one.sh`, `scripts/restart.sh`, `scripts/rolling-update.sh`.
- [ ] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами.
- [ ] Контракт и публичные тесты не ослаблены.
- [ ] make check и make test выполнены; приложен реальный вывод.
- [ ] Сценарии отказов/безопасности своего уровня воспроизведены.
- [ ] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens.
- [ ] README задания сохранён, REPORT.md содержит инструкцию именно моего решения.
Команды запуска из чистого clone:
```sh
cp .env.example .env
# Подставить локальные пароли в .env. Файл не коммитить.
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
```
Результаты проверок и ссылка на REPORT.md: подробности и числа в [REPORT.md](REPORT.md). `make check` и `make test` прошли. Persistence сохранил токен и сообщения. Failover каждой реплики: 2 экземпляра до отказа, восстановление записи за 0.209 с и 2.435 с, по одной ошибке. Гонка одного ключа: 12 параллельных POST, один id (`evidence/grade4.json`). Rolling update под нагрузкой: 14411 успешных и 61 ошибка (`evidence/rolling-load.json`).
Ограничения / известные ошибки: стенд переживает смерть одного процесса API и перезапуск контейнеров с теми же volumes. Потеря компьютера не переживается: HAProxy, PostgreSQL и Redis в одном экземпляре. `X-Instance-Id` равен hostname контейнера. Повтор после таймаута безопасен только для POST сообщения с тем же ключом и телом.
Источники и использование ИИ: контракт репозитория, документация HAProxy 2.8 и Docker Compose. Нейросети помогали с написанием кода, написанием отчета, написанием тестов. Числа в отчёте сняты на локальном стенде.
- [x] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами.
- [x] Контракт и публичные тесты не ослаблены.
- [x] make check и make test выполнены; приложен реальный вывод.
- [x] Сценарии отказов/безопасности своего уровня воспроизведены.
- [x] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens.
- [x] README задания сохранён, REPORT.md содержит инструкцию именно моего решения.
+8 -7
View File
@@ -4,10 +4,10 @@ CA_FILE ?=
ACTION_SCRIPT ?=
TLS_ARGS = $(if $(CA_FILE),--ca-file "$(CA_FILE)",)
.PHONY: help check validate test load test-own test-persistence
.PHONY: help check validate test load test-persistence test-failover
help:
@echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes; test-own: Go tests"
@echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes"
check:
$(PYTHON) scripts/check_contract.py
@@ -21,9 +21,10 @@ test:
load:
$(PYTHON) tests/load.py --base-url "$(BASE_URL)" $(TLS_ARGS)
test-own:
go test ./...
test-persistence:
test -n "$(ACTION_SCRIPT)"
$(PYTHON) tests/resilience.py --base-url "$(BASE_URL)" --mode persistence --action-script "$(ACTION_SCRIPT)" $(TLS_ARGS)
@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)
+82 -17
View File
@@ -1,37 +1,102 @@
# Отчёт — лабораторная 3
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
- Автор, группа: Колмычков Иван Сергеевич БВТ2303
- Целевая оценка: **4**. Трек 5 не заявлен.
- Commit/PR:
- Источники и помощь ИИ: контракт репозитория, документация HAProxy 2.8 (`server-template`, `http-check`) и Docker Compose. Нейросети помогали с написанием кода, написанием отчета, проверки качества кода. числа ниже сняты с этого компьютера.
## Запуск из чистого clone
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
Проверено 2026-11-05 на Linux 7.0.0-31-generic, x86_64, 8 логических CPU, 7.0 ГиБ RAM. Docker Engine 29.1.3, Compose v2.40.3, локальный Go 1.26.8, Python 3.14.4. Образы зафиксированы тегами, без `latest`:
| Роль | Образ |
| --- | --- |
| API | `messenger-api:lab3`, сборка из `Dockerfile`: `golang:1.26-bookworm`, runtime `gcr.io/distroless/static-debian12:nonroot@sha256:afa5c872c891853ca7fcf1f12c3edb23f7eeef36189728842dd51042ff57f7ab` |
| PostgreSQL | `postgres:16.10-bookworm`, лимит 1.00 CPU / 512 МиБ, `synchronous_commit=on`, `max_connections=50` |
| Redis | `redis:7.4.6-alpine`, AOF `appendfsync everysec`, лимит 0.25 CPU / 128 МиБ |
| Балансировщик | `haproxy:2.8.14`, лимит 0.25 CPU / 128 МиБ |
Рабочий стенд — 2 реплики API, у каждой лимит 0.50 CPU и 256 МиБ (сумма 1.00 CPU и 512 МиБ). Пул PostgreSQL — 8 соединений на реплику.
```sh
cp .env.example .env
# В .env замените change-me на локальные пароли. Файл не коммитить.
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
# Дождитесь healthy у haproxy. Порт API снаружи один: 127.0.0.1:8080.
make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
```
Остановка без удаления учебных данных: `docker compose --env-file .env stop`.
Удаление учебных volumes, если они больше не нужны: `docker compose --env-file .env down -v`.
`scripts/restart.sh` делает `restart` postgres, redis, api и haproxy и volumes не трогает.
Соответствие имён из исходного `.env.example`: `DATABASE_URL` собирается в `compose.yaml` из `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB` (отдельный файл секрета не используется). Сессии — Redis, не PostgreSQL: `REDIS_URL` из `REDIS_PASSWORD`. `SESSION_TTL_SECONDS`, `API_REPLICAS`, `IDEMPOTENCY_TTL_SECONDS` читает процесс API.
## Архитектура и решения
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
```text
клиент → HAProxy :8080 → API × N → PostgreSQL (пользователи, чаты, сообщения, ключи)
↘ Redis AOF (сессии)
```
Из lab2 перенесены PostgreSQL, Redis с AOF, Argon2id, Bearer-сессии и миграции. В этой работе API больше не применяет миграции сам: одноразовый сервис `migrate` выполняет `messenger migrate` после готовности PostgreSQL и до старта реплик. `Apply` держит `pg_advisory_lock` на одном соединении и пишет версию в `schema_migrations`. Повторный запуск SQL не исполняет. На стенде в таблице две строки: `001_init.sql` и `002_idempotency.sql`, обе с одним `applied_at`.
Реплики — один Compose-service `api` с `deploy.replicas`. `container_name` нет. Порт 8080 наружу публикует только HAProxy, на `127.0.0.1`. У API есть `expose`, published port нет.
`X-Instance-Id` — hostname контейнера. Он стабилен, пока жив процесс, и `scripts/stop-one.sh` находит по нему именно тот контейнер. Для lab7 это уже не подойдёт: hostname раскрывает идентификатор контейнера, там нужен отдельный случайный alias.
Sticky session нет. Баланс `roundrobin`. Сессия лежит в Redis, поэтому следующий запрос может попасть на другую реплику с тем же Bearer-токеном. Локальной памяти сессий у API нет.
Проверки и таймауты согласованы так:
- API: `ReadHeaderTimeout` 5 с, `ReadTimeout`/`WriteTimeout` 15 с, `SHUTDOWN_TIMEOUT_SECONDS` 8.
- HAProxy: `timeout connect` 2 с, `timeout server` 16 с, `retries 0`. Балансировщик не повторяет POST. Повтор сообщения делает клиент тем же ключом. Создание пользователя и чата не идемпотентно, прозрачный retry их размножил бы.
- Готовность backend: `GET /health/ready` должен вернуть 200. Период `inter 1s`, `fall 2`, `rise 1`. Недоступный backend выводится не позже чем за 2 с. DNS Compose перечитывается с `hold valid 1s`.
- SIGTERM: процесс сразу переводит `/health/ready` и новые бизнес-запросы в 503 и дорабатывает уже принятые в пределах 8 с. `docker stop -t 8` совпадает с этим бюджетом. `restart: unless-stopped` не поднимает контейнер обратно после явного `stop`.
`/health/ready` требует живые PostgreSQL и Redis. Живой процесс при мёртвой базе отвечает 503 и в пул HAProxy не входит.
Идемпотентность. Для `POST /api/v1/chats/{id}/messages` обязателен `Idempotency-Key` (`[A-Za-z0-9._:-]{1,128}`). Область — пользователь + чат + ключ. Отпечаток — уже разобранный текст, поэтому другой порядок ключей JSON и `\u`-экранирование не считаются другим телом. В одной транзакции пишутся строка `messages` и строка `message_idempotency`. Если вторая реплика успела занять тот же ключ, первая транзакция откатывается целиком: не остаётся ни сообщения без ключа, ни ключа без сообщения. Повтор с тем же текстом возвращает тот же `201` и ту же строку. Другой текст — `409`. Чужой ключ не хранится, если нет доступа к чату: членство проверяется до записи. Ключ живёт `IDEMPOTENCY_TTL_SECONDS` (86400). Ошибка 5xx клиенту можно повторить тем же ключом. Порядок истории задаёт `(created_at, id)`.
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| Критерий | Команда | Наблюдение | Файл |
| --- | --- | --- | --- |
| Публичный 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/smoke.txt` |
| Две реплики и одна сессия | 20× `GET /health/live` через HAProxy | два `X-Instance-Id`, они равны hostname контейнеров | `evidence/instances.txt` |
| Сохранность токена и данных | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | `PASS: persistence preserved confirmed data and existing session` | `evidence/persistence.txt` |
| Отказ первой реплики | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | 2 реплики до отказа, 121 успешная запись, 1 ошибка, первая успешная запись через 0.209 с. В `docker compose ps` остался один API | `evidence/failover-first.txt`, `evidence/failover-first-ps.txt` |
| Отказ второй реплики | тот же тест после `docker start` остановленного API | 120 успешных, 1 ошибка, восстановление 2.435 с. Остановлен уже другой контейнер | `evidence/failover-second.txt`, `evidence/failover-second-ps.txt` |
| Каждая реплика под нагрузкой | `python3 scripts/grade4.py` | hook 0.406 с и 0.431 с, после остановки 2613 и 2889 успешных ответов, целевой `X-Instance-Id` среди них 0. RPS 306 и 326, ошибки 45 и 57 за окно 12 с | `evidence/grade4.json` |
| Гонка одного ключа | тот же скрипт, 12 параллельных POST | 12 ответов 201, 1 id, в истории одна копия текста | `evidence/grade4.json` |
| Лимиты, порты, без container_name | `compose.yaml` | CPU/RAM заданы, наружу открыт только HAProxy `127.0.0.1:8080`, плюс localhost postgres/redis для проверки | `compose.yaml` |
| Rolling update под нагрузкой | `scripts/rolling-update.sh` во время `tests/load.py` 40 с, concurrency 4 | замена по одному контейнеру, 14411 успешных, 61 ошибка (доля 0.004), p50 6.6 мс, p95 45.9 мс, p99 85.4 мс. Один `curl /health/ready` поймал 503, затем готовность вернулась | `evidence/rolling-load.json` |
| Миграция один раз | `SELECT version FROM schema_migrations` | две строки, повторного применения нет | `evidence/schema-migrations.txt` |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
Юнит-тесты `go test ./...` проходят без базы: повтор ключа, конфликт тела, гонка из 16 запросов в памяти.
## Эксперименты и отказы
## Отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
Замеры отказа каждой реплики: `python3 scripts/grade4.py`, окно 12 с, 4 параллельных клиента. Это RPS подтверждённых ответов за всё окно, включая секунды до остановки. Rolling update: `tests/load.py` 40 с, concurrency 4, закрытый цикл без повторов клиента. Процентили только по успешным запросам.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| Воздействие | Что ожидаем | Что наблюдали | Восстановление / данные |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
| `stop-one.sh` одной реплики | вторая продолжает писать и читать, остановленный id пропадает из ответов | публичный тест: 1 ошибка, восстановление 0.209 с и 2.435 с | подтверждённые сообщения на месте, дублей нет |
| Та же остановка по очереди для обоих id | hook быстрее 10 с, после выхода целевой id не обслуживает | 0.406 с и 0.431 с, целевых ответов после остановки 0 | реплика поднята обратно `docker start`, данные не чистились |
| `restart.sh` всего пути | старый токен и старые сообщения живы | PASS persistence | volumes сохранены |
| Rolling replace двух контейнеров | короткие 5xx, запись продолжается | 61 ошибка на 14472 попытки | новые контейнеры healthy, схема не переигрывалась |
## Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
Стенд выдерживает смерть одного процесса API и перезапуск контейнеров с теми же volumes. Он не выдерживает потерю этого компьютера: HAProxy, PostgreSQL и Redis в одном экземпляре. Несколько реплик API не делают базу и балансировщик отказоустойчивыми. `depends_on` и healthcheck только задают порядок старта; запросы раскидывает HAProxy, а не Compose.
Повтор после таймаута безопасен для отправки сообщения: тот же `Idempotency-Key` и то же тело вернут исходный объект. `POST /users`, `POST /chats` и `POST /auth/sessions` таким ключом не защищены. Их автоматический retry создаст второй объект или вторую сессию.
Если сессии снова положить в память процесса, общий Redis перестанет быть источником сессии. Запрос на другую реплику получит 401, и sticky session это только замаскирует: после смерти «своей» реплики сессия исчезнет.
`X-Instance-Id` сейчас равен hostname. Для этой лабораторной так скрипт находит контейнер. На lab7 его надо заменить непрозрачным alias.
Вложение `attachment_ids` в контракте lab3 у сообщения ещё нет. Когда оно появится, отпечаток ключа нужно расширить отсортированным списком id, иначе тот же ключ с разными вложениями будет считаться тем же телом.
+66 -6
View File
@@ -1,5 +1,6 @@
# Локальный стенд лабораторной 2. Секреты только из .env, volumes не удаляются restart-скриптом.
name: messenger-lab2
# Локальный стенд лабораторной 3. Секреты только из .env, volumes не удаляются restart-скриптом.
# Клиент ходит в haproxy:8080. Реплики api порт наружу не публикуют.
name: messenger-lab3
services:
postgres:
@@ -24,6 +25,11 @@ services:
timeout: 3s
retries: 12
start_period: 5s
deploy:
resources:
limits:
cpus: "1.00"
memory: 512M
restart: unless-stopped
redis:
@@ -45,12 +51,37 @@ services:
timeout: 3s
retries: 12
start_period: 3s
deploy:
resources:
limits:
cpus: "0.25"
memory: 128M
restart: unless-stopped
migrate:
build: .
image: messenger-api:lab3
command: ["migrate"]
depends_on:
postgres:
condition: service_healthy
environment:
DATABASE_URL: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}?sslmode=disable
healthcheck:
disable: true
deploy:
resources:
limits:
cpus: "0.50"
memory: 128M
restart: "no"
api:
build: .
image: messenger-api:lab2
image: messenger-api:lab3
depends_on:
migrate:
condition: service_completed_successfully
postgres:
condition: service_healthy
redis:
@@ -63,18 +94,47 @@ services:
DATABASE_URL: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}?sslmode=disable
REDIS_URL: redis://:${REDIS_PASSWORD}@redis:6379/0
SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600}
DB_MAX_CONNS: ${DB_MAX_CONNS:-10}
IDEMPOTENCY_TTL_SECONDS: ${IDEMPOTENCY_TTL_SECONDS:-86400}
DB_MAX_CONNS: ${DB_MAX_CONNS:-8}
ARGON2_TIME: ${ARGON2_TIME:-2}
ARGON2_MEMORY_KIB: ${ARGON2_MEMORY_KIB:-19456}
ARGON2_THREADS: ${ARGON2_THREADS:-1}
ports:
- "127.0.0.1:8080:8080"
expose:
- "8080"
healthcheck:
test: ["CMD", "/messenger", "healthcheck"]
interval: 5s
timeout: 3s
retries: 12
start_period: 10s
deploy:
replicas: ${API_REPLICAS:-2}
resources:
limits:
cpus: "${API_CPU_LIMIT:-0.50}"
memory: ${API_MEM_LIMIT:-256M}
restart: unless-stopped
haproxy:
image: haproxy:2.8.14
depends_on:
api:
condition: service_healthy
volumes:
- ./deploy/haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro
ports:
- "127.0.0.1:8080:8080"
healthcheck:
test: ["CMD", "haproxy", "-c", "-f", "/usr/local/etc/haproxy/haproxy.cfg"]
interval: 5s
timeout: 3s
retries: 6
start_period: 3s
deploy:
resources:
limits:
cpus: "0.25"
memory: 128M
restart: unless-stopped
volumes:
+46
View File
@@ -0,0 +1,46 @@
# Единая точка входа. Sticky session нет: сессия лежит в Redis, любая реплика её читает.
# server-template берёт все A-записи DNS Compose (127.0.0.11) и сам выкидывает backend,
# у которого /health/ready перестал отвечать 200.
#
# Обнаружение отказа: inter 1s, fall 2 → не больше 2 с после 503/обрыва.
# hold valid 1s — как часто перечитываем адреса реплик после scale/stop.
# retries 0: балансировщик не повторяет POST. Повтор сообщения делает клиент тем же ключом.
# Создание пользователя и чата не идемпотентно, поэтому прозрачный retry на LB запрещён.
global
maxconn 256
resolvers docker
nameserver dns 127.0.0.11:53
resolve_retries 3
timeout resolve 1s
timeout retry 1s
hold valid 1s
hold other 1s
hold refused 1s
hold nx 1s
hold timeout 1s
hold obsolete 1s
accepted_payload_size 8192
defaults
mode http
timeout connect 2s
timeout client 20s
timeout server 16s
timeout http-request 10s
timeout check 2s
timeout queue 2s
retries 0
frontend http_in
bind *:8080
default_backend api
backend api
balance roundrobin
option httpchk
http-check send meth GET uri /health/ready ver HTTP/1.1 hdr Host api
http-check expect status 200
default-server inter 1s fall 2 rise 1 maxconn 64
server-template api 8 api:8080 check resolvers docker init-addr none resolve-prefer ipv4
+4
View File
@@ -0,0 +1,4 @@
messenger-lab3-api-1 Up 25 seconds (healthy)
messenger-lab3-haproxy-1 Up 25 seconds (healthy)
messenger-lab3-postgres-1 Up 25 seconds (healthy)
messenger-lab3-redis-1 Up 25 seconds (healthy)
+4
View File
@@ -0,0 +1,4 @@
python3 tests/resilience.py --mode failover --action-script "scripts/stop-one.sh" --base-url "http://localhost:8080"
Executing explicit failover hook; hook output suppressed to avoid leaking secrets.
{"observed_instances_before": 2, "successful_writes": 121, "failed_attempts": 1, "first_recovery_seconds": 0.209}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
+4
View File
@@ -0,0 +1,4 @@
messenger-lab3-api-2 Up 16 seconds (healthy)
messenger-lab3-haproxy-1 Up 42 seconds (healthy)
messenger-lab3-postgres-1 Up 42 seconds (healthy)
messenger-lab3-redis-1 Up 42 seconds (healthy)
+4
View File
@@ -0,0 +1,4 @@
python3 tests/resilience.py --mode failover --action-script "scripts/stop-one.sh" --base-url "http://localhost:8080"
Executing explicit failover hook; hook output suppressed to avoid leaking secrets.
{"observed_instances_before": 2, "successful_writes": 120, "failed_attempts": 1, "first_recovery_seconds": 2.435}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
+37
View File
@@ -0,0 +1,37 @@
{
"instances_before": [
"884d89d0d7f2",
"c785aa003e06"
],
"failover": [
{
"ok": 3678,
"fail": 45,
"after_ok": 2613,
"target_after_stop": 0,
"first_recovery_s": 0.002,
"hook_exit": 0,
"hook_seconds": 0.406,
"target": "884d89d0d7f2",
"successful_rps": 306.5
},
{
"ok": 3918,
"fail": 57,
"after_ok": 2889,
"target_after_stop": 0,
"first_recovery_s": 0.001,
"hook_exit": 0,
"hook_seconds": 0.431,
"target": "c785aa003e06",
"successful_rps": 326.5
}
],
"idempotency_race": {
"parallel_requests": 12,
"distinct_ids": 1,
"successes": 12,
"errors": [],
"history_copies": 1
}
}
+24
View File
@@ -0,0 +1,24 @@
GET /health/live via http://127.0.0.1:8080
d5e8c2b90b42
de5c28c8b010
d5e8c2b90b42
de5c28c8b010
d5e8c2b90b42
de5c28c8b010
d5e8c2b90b42
de5c28c8b010
d5e8c2b90b42
de5c28c8b010
d5e8c2b90b42
de5c28c8b010
d5e8c2b90b42
de5c28c8b010
d5e8c2b90b42
de5c28c8b010
d5e8c2b90b42
de5c28c8b010
d5e8c2b90b42
de5c28c8b010
--- container hostnames ---
/messenger-lab3-api-5 de5c28c8b010
/messenger-lab3-api-6 d5e8c2b90b42
+3
View File
@@ -0,0 +1,3 @@
python3 tests/resilience.py --mode persistence --action-script "scripts/restart.sh" --base-url "http://localhost:8080"
Executing explicit persistence hook; hook output suppressed to avoid leaking secrets.
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 40.0,
"elapsed_seconds": 40.013,
"concurrency": 4,
"successful_requests": 14411,
"failed_requests": 61,
"error_ratio": 0.004215,
"successful_rps": 360.155,
"successful_latency_ms": {
"p50": 6.583,
"p95": 45.927,
"p99": 85.417
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+6
View File
@@ -0,0 +1,6 @@
version | applied_at
---------------------+-------------------------------
001_init.sql | 2026-11-05 15:32:01.011829+00
002_idempotency.sql | 2026-11-05 15:32:01.026576+00
(2 rows)
+2
View File
@@ -0,0 +1,2 @@
python3 tests/smoke.py --base-url "http://localhost:8080"
PASS: lab3 public API scenario; infrastructure and grading evidence remain separate.
+9 -1
View File
@@ -222,6 +222,11 @@ func (a *API) createMessage(w http.ResponseWriter, r *http.Request, rawID string
if _, err := a.store.ChatFor(r.Context(), id, user.ID); a.writeStoreErr(w, r, err) {
return
}
idemKey := r.Header.Get("Idempotency-Key")
if !idemKeyRe.MatchString(idemKey) {
a.fail(w, r, http.StatusBadRequest, "invalid_request", "Нужен заголовок Idempotency-Key", 0)
return
}
var body struct {
Text string `json:"text"`
}
@@ -232,7 +237,8 @@ func (a *API) createMessage(w http.ResponseWriter, r *http.Request, rawID string
a.fail(w, r, http.StatusBadRequest, "invalid_request", "Некорректный текст сообщения", 0)
return
}
msg, err := a.store.AddMessage(r.Context(), id, user.ID, body.Text)
// Отпечаток — разобранный текст, а не сырые байты: порядок ключей JSON и \u-экранирование не создают другое сообщение.
msg, err := a.store.AddMessage(r.Context(), id, user.ID, body.Text, idemKey, body.Text)
if a.writeStoreErr(w, r, err) {
return
}
@@ -288,6 +294,8 @@ func (a *API) writeStoreErr(w http.ResponseWriter, r *http.Request, err error) b
switch {
case errors.Is(err, store.ErrUnavailable), errors.Is(err, session.ErrUnavailable):
a.fail(w, r, http.StatusServiceUnavailable, "unavailable", "Сервис временно недоступен", 1)
case errors.Is(err, store.ErrIdempotencyMismatch):
a.fail(w, r, http.StatusConflict, "conflict", "Этот ключ уже использован для другого сообщения", 0)
case errors.Is(err, store.ErrConflict):
a.fail(w, r, http.StatusConflict, "conflict", "Имя пользователя уже занято", 0)
case errors.Is(err, store.ErrNotFound):
+1
View File
@@ -22,6 +22,7 @@ var usernameRe = regexp.MustCompile(`^[a-z0-9_]{3,32}$`)
var uuidRe = regexp.MustCompile(`(?i)^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`)
var limitRe = regexp.MustCompile(`^[0-9]{1,3}$`)
var requestIDRe = regexp.MustCompile(`^[A-Za-z0-9._:-]{1,64}$`)
var idemKeyRe = regexp.MustCompile(`^[A-Za-z0-9._:-]{1,128}$`)
type errorEnvelope struct {
Error errorObject `json:"error"`
+7 -1
View File
@@ -20,19 +20,23 @@ type API struct {
hasher password.Params
dummyHash string
sessionTTL time.Duration
instanceID string
log *slog.Logger
shutting atomic.Bool
}
// New связывает HTTP с хранилищем и сессиями.
// dummyHash нужен, чтобы несуществующий username тратил столько же KDF, сколько существующий.
func New(st store.Repository, sessions session.Store, hasher password.Params, sessionTTL time.Duration, log *slog.Logger) *API {
func New(st store.Repository, sessions session.Store, hasher password.Params, sessionTTL time.Duration, instanceID string, log *slog.Logger) *API {
if log == nil {
log = slog.Default()
}
if sessionTTL <= 0 {
sessionTTL = time.Hour
}
if instanceID == "" {
instanceID = "api"
}
dummy, err := hasher.Hash("dummy-password-not-a-login")
if err != nil {
// Параметры KDF проверяются на старте. Пустая строка заставит Verify сразу вернуть false.
@@ -44,6 +48,7 @@ func New(st store.Repository, sessions session.Store, hasher password.Params, se
hasher: hasher,
dummyHash: dummy,
sessionTTL: sessionTTL,
instanceID: instanceID,
log: log,
}
}
@@ -61,6 +66,7 @@ func (a *API) ServeHTTP(w http.ResponseWriter, r *http.Request) {
start := time.Now()
id := requestID(r)
sw.Header().Set("X-Request-Id", id)
sw.Header().Set("X-Instance-Id", a.instanceID)
r = r.WithContext(context.WithValue(r.Context(), ctxKey{}, id))
defer func() {
+131 -3
View File
@@ -10,8 +10,10 @@ import (
"net/http"
"net/http/httptest"
"net/url"
"strconv"
"strings"
"sync"
"sync/atomic"
"testing"
"time"
@@ -38,7 +40,7 @@ func newServerTTL(t *testing.T, ttl time.Duration) *labServer {
t.Helper()
st := store.New()
sess := session.NewMemory()
application := New(st, sess, password.Params{Time: 1, Memory: 8, Threads: 1}, ttl, slog.New(slog.NewJSONHandler(io.Discard, nil)))
application := New(st, sess, password.Params{Time: 1, Memory: 8, Threads: 1}, ttl, "test-instance", slog.New(slog.NewJSONHandler(io.Discard, nil)))
srv := httptest.NewServer(application)
t.Cleanup(srv.Close)
return &labServer{URL: srv.URL, tokens: map[string]string{}, api: application, store: st, sess: sess}
@@ -54,7 +56,13 @@ func (e *labServer) bearer(user string) string {
return "unknown-session-token"
}
func do(t *testing.T, env *labServer, method, url, user string, body any, raw []byte, contentType string) (int, http.Header, []byte) {
var keySeq atomic.Uint64
func nextIdemKey() string {
return "k" + strconv.FormatUint(keySeq.Add(1), 36)
}
func do(t *testing.T, env *labServer, method, url, user string, body any, raw []byte, contentType string, extra ...map[string]string) (int, http.Header, []byte) {
t.Helper()
var rdr io.Reader
if raw != nil {
@@ -79,6 +87,14 @@ func do(t *testing.T, env *labServer, method, url, user string, body any, raw []
if tok := env.bearer(user); tok != "" {
req.Header.Set("Authorization", "Bearer "+tok)
}
if len(extra) > 0 {
for k, v := range extra[0] {
req.Header.Set(k, v)
}
}
if method == http.MethodPost && strings.Contains(url, "/messages") && req.Header.Get("Idempotency-Key") == "" {
req.Header.Set("Idempotency-Key", nextIdemKey())
}
resp, err := http.DefaultClient.Do(req)
if err != nil {
t.Fatal(err)
@@ -91,6 +107,9 @@ func do(t *testing.T, env *labServer, method, url, user string, body any, raw []
if resp.Header.Get("X-Request-Id") == "" {
t.Fatalf("%s %s: missing X-Request-Id", method, url)
}
if resp.Header.Get("X-Instance-Id") != "test-instance" {
t.Fatalf("%s %s: X-Instance-Id = %q", method, url, resp.Header.Get("X-Instance-Id"))
}
if resp.StatusCode >= 400 {
var env errorEnvelope
if err := json.Unmarshal(data, &env); err != nil {
@@ -402,6 +421,7 @@ func TestConcurrentHundredMessages(t *testing.T) {
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+env.tokens[user])
req.Header.Set("Idempotency-Key", user+"-"+strconv.Itoa(j))
resp, err := http.DefaultClient.Do(req)
if err != nil {
errCh <- err
@@ -559,7 +579,7 @@ func (downStore) User(context.Context, string) (store.User, error) {
func TestDependencyDownDoesNotTrustAnonymous(t *testing.T) {
env := newServer(t)
alice := createUser(t, env, "alice", "Алиса")
broken := New(downStore{env.store}, downSessions{env.sess}, password.Params{Time: 1, Memory: 8, Threads: 1}, time.Hour, slog.New(slog.NewJSONHandler(io.Discard, nil)))
broken := New(downStore{env.store}, downSessions{env.sess}, password.Params{Time: 1, Memory: 8, Threads: 1}, time.Hour, "test-instance", slog.New(slog.NewJSONHandler(io.Discard, nil)))
srv := httptest.NewServer(broken)
defer srv.Close()
@@ -604,6 +624,114 @@ func TestDependencyDownDoesNotTrustAnonymous(t *testing.T) {
}
}
func TestIdempotencyReplayConflictAndRace(t *testing.T) {
env := newServer(t)
alice := createUser(t, env, "alice", "Алиса")
bob := createUser(t, env, "bob", "Боб")
chat := createChat(t, env, alice.ID, "ключ", alice.ID, bob.ID)
path := env.URL + "/api/v1/chats/" + chat.ID + "/messages"
key := "same-key-1"
status, _, body := do(t, env, http.MethodPost, path, alice.ID, map[string]string{"text": "одно"}, nil, "", map[string]string{"Idempotency-Key": key})
if status != http.StatusCreated {
t.Fatalf("first: %d %s", status, body)
}
var first messageJSON
if err := json.Unmarshal(body, &first); err != nil {
t.Fatal(err)
}
status, _, body = do(t, env, http.MethodPost, path, alice.ID, nil, []byte(`{"text":"одно"}`), "application/json", map[string]string{"Idempotency-Key": key})
if status != http.StatusCreated {
t.Fatalf("replay: %d %s", status, body)
}
var replay messageJSON
if err := json.Unmarshal(body, &replay); err != nil {
t.Fatal(err)
}
if replay != first {
t.Fatalf("replay changed message: %+v vs %+v", replay, first)
}
status, _, _ = do(t, env, http.MethodPost, path, alice.ID, map[string]string{"text": "другое"}, nil, "", map[string]string{"Idempotency-Key": key})
if status != http.StatusConflict {
t.Fatalf("mismatch: %d", status)
}
req, err := http.NewRequest(http.MethodPost, path, strings.NewReader(`{"text":"без ключа"}`))
if err != nil {
t.Fatal(err)
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+env.tokens[alice.ID])
resp, err := http.DefaultClient.Do(req)
if err != nil {
t.Fatal(err)
}
resp.Body.Close()
if resp.StatusCode != http.StatusBadRequest {
t.Fatalf("missing key: %d", resp.StatusCode)
}
status, _, body = do(t, env, http.MethodPost, path, bob.ID, map[string]string{"text": "одно"}, nil, "", map[string]string{"Idempotency-Key": key})
if status != http.StatusCreated {
t.Fatalf("other user: %d %s", status, body)
}
var other messageJSON
if err := json.Unmarshal(body, &other); err != nil {
t.Fatal(err)
}
if other.ID == first.ID {
t.Fatal("same key for another user reused the message")
}
raceKey := "race-key"
var wg sync.WaitGroup
ids := make(chan string, 16)
errs := make(chan error, 16)
for i := 0; i < 16; i++ {
wg.Add(1)
go func() {
defer wg.Done()
req, err := http.NewRequest(http.MethodPost, path, strings.NewReader(`{"text":"гонка"}`))
if err != nil {
errs <- err
return
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+env.tokens[alice.ID])
req.Header.Set("Idempotency-Key", raceKey)
resp, err := http.DefaultClient.Do(req)
if err != nil {
errs <- err
return
}
defer resp.Body.Close()
raw, _ := io.ReadAll(resp.Body)
if resp.StatusCode != http.StatusCreated {
errs <- &statusErr{resp.StatusCode, raw}
return
}
var msg messageJSON
if err := json.Unmarshal(raw, &msg); err != nil {
errs <- err
return
}
ids <- msg.ID
}()
}
wg.Wait()
close(ids)
close(errs)
for err := range errs {
t.Fatal(err)
}
seen := map[string]struct{}{}
for id := range ids {
seen[id] = struct{}{}
}
if len(seen) != 1 {
t.Fatalf("concurrent same key created %d messages", len(seen))
}
}
type statusErr struct {
code int
body []byte
+12
View File
@@ -21,6 +21,8 @@ type Config struct {
Argon2Time uint32
Argon2Memory uint32
Argon2Threads uint8
InstanceID string
IdempotencyTTL time.Duration
}
// Addr — адрес прослушивания. В контейнере это 0.0.0.0:8080,
@@ -93,6 +95,16 @@ func Load() (Config, error) {
c.Argon2Time = uint32(argonTime)
c.Argon2Memory = uint32(argonMemory)
c.Argon2Threads = uint8(argonThreads)
c.InstanceID = getenv("INSTANCE_ID", "")
idemTTL, err := nonNeg("IDEMPOTENCY_TTL_SECONDS", 86400)
if err != nil {
return Config{}, err
}
if idemTTL < 86400 || idemTTL > 7*24*3600 {
return Config{}, fmt.Errorf("IDEMPOTENCY_TTL_SECONDS must be 86400..604800")
}
c.IdempotencyTTL = time.Duration(idemTTL) * time.Second
return c, nil
}
+21 -7
View File
@@ -13,15 +13,29 @@ import (
"messenger/migrations"
)
// Создаёт schema_migrations и выполняет ещё не записанные файлы.
// Повторный запуск не исполняет уже применённый SQL и не дублирует строки.
// advisoryLock сериализует миграции между процессами. Номер постоянный для этого приложения.
const advisoryLock int64 = 748392016
// Apply создаёт schema_migrations и выполняет ещё не записанные файлы.
// Замок держится на одном соединении: пул сам по себе не привязывает блокировку к сессии.
func Apply(ctx context.Context, pool *pgxpool.Pool) error {
_, err := pool.Exec(ctx, `
conn, err := pool.Acquire(ctx)
if err != nil {
return err
}
defer conn.Release()
if _, err := conn.Exec(ctx, `SELECT pg_advisory_lock($1)`, advisoryLock); err != nil {
return fmt.Errorf("advisory lock: %w", err)
}
defer func() {
_, _ = conn.Exec(context.Background(), `SELECT pg_advisory_unlock($1)`, advisoryLock)
}()
if _, err := conn.Exec(ctx, `
CREATE TABLE IF NOT EXISTS schema_migrations (
version text PRIMARY KEY,
applied_at timestamptz NOT NULL DEFAULT now()
)`)
if err != nil {
)`); err != nil {
return fmt.Errorf("schema_migrations: %w", err)
}
entries, err := fs.ReadDir(migrations.FS, ".")
@@ -38,7 +52,7 @@ func Apply(ctx context.Context, pool *pgxpool.Pool) error {
sort.Strings(names)
for _, name := range names {
var applied bool
if err := pool.QueryRow(ctx, `SELECT EXISTS(SELECT 1 FROM schema_migrations WHERE version = $1)`, name).Scan(&applied); err != nil {
if err := conn.QueryRow(ctx, `SELECT EXISTS(SELECT 1 FROM schema_migrations WHERE version = $1)`, name).Scan(&applied); err != nil {
return err
}
if applied {
@@ -48,7 +62,7 @@ func Apply(ctx context.Context, pool *pgxpool.Pool) error {
if err != nil {
return err
}
tx, err := pool.Begin(ctx)
tx, err := conn.Begin(ctx)
if err != nil {
return err
}
+98 -28
View File
@@ -14,7 +14,8 @@ import (
// PG — источник истины для пользователей, чатов и сообщений.
// Запросы только с параметрами. Пул ограничен, у сессии соединения есть statement_timeout.
type PG struct {
pool *pgxpool.Pool
pool *pgxpool.Pool
idemTTL time.Duration
}
func Open(ctx context.Context, databaseURL string, maxConns int32) (*PG, error) {
@@ -45,7 +46,14 @@ func Open(ctx context.Context, databaseURL string, maxConns int32) (*PG, error)
pool.Close()
return nil, err
}
return &PG{pool: pool}, nil
return &PG{pool: pool, idemTTL: 24 * time.Hour}, nil
}
// SetIdempotencyTTL задаёт, сколько хранить результат POST сообщения.
func (p *PG) SetIdempotencyTTL(ttl time.Duration) {
if ttl > 0 {
p.idemTTL = ttl
}
}
func (p *PG) Close() { p.pool.Close() }
@@ -214,37 +222,72 @@ func (p *PG) ListChats(ctx context.Context, userID string, cur *Cursor, limit in
return items, hasMore, nil
}
func (p *PG) AddMessage(ctx context.Context, chatID, senderID, text string) (Message, error) {
func (p *PG) AddMessage(ctx context.Context, chatID, senderID, text, idemKey, fingerprint string) (Message, error) {
if idemKey == "" || fingerprint == "" {
return Message{}, ErrInvalid
}
var last error
for attempt := 0; attempt < 5; attempt++ {
msg, retry, err := p.addMessageOnce(ctx, chatID, senderID, text, idemKey, fingerprint)
if !retry {
return msg, err
}
last = err
}
if last == nil {
last = ErrUnavailable
}
return Message{}, ErrUnavailable
}
// addMessageOnce пишет сообщение и ключ одной транзакцией.
// retry=true значит, что параллельная реплика заняла тот же ключ раньше: свою вставку откатываем и читаем её результат.
func (p *PG) addMessageOnce(ctx context.Context, chatID, senderID, text, idemKey, fingerprint string) (Message, bool, error) {
tx, err := p.pool.Begin(ctx)
if err != nil {
return Message{}, mapDB(err)
return Message{}, false, mapDB(err)
}
defer func() { _ = tx.Rollback(ctx) }()
// Блокировка строки чата сериализует writers одного чата.
var exists string
err = tx.QueryRow(ctx, `SELECT id::text FROM chats WHERE id = $1 FOR UPDATE`, chatID).Scan(&exists)
if err != nil {
return Message{}, mapDB(err)
}
var member int
if err := tx.QueryRow(ctx, `
SELECT 1 FROM chat_members WHERE chat_id = $1 AND user_id = $2`, chatID, senderID).Scan(&member); err != nil {
return Message{}, mapDB(err)
return Message{}, false, mapDB(err)
}
var last time.Time
var storedFP, messageID string
var expires time.Time
err = tx.QueryRow(ctx, `
SELECT created_at FROM messages WHERE chat_id = $1
ORDER BY created_at DESC LIMIT 1`, chatID).Scan(&last)
if errors.Is(err, pgx.ErrNoRows) {
last = time.Time{}
} else if err != nil {
return Message{}, mapDB(err)
SELECT fingerprint, message_id::text, expires_at
FROM message_idempotency
WHERE user_id = $1 AND chat_id = $2 AND idem_key = $3
FOR UPDATE`, senderID, chatID, idemKey).Scan(&storedFP, &messageID, &expires)
if err == nil {
if expires.After(time.Now()) {
if storedFP != fingerprint {
return Message{}, false, ErrIdempotencyMismatch
}
msg, err := scanMessage(tx.QueryRow(ctx, `
SELECT id::text, chat_id::text, sender_id::text, text, created_at
FROM messages WHERE id = $1`, messageID))
if err != nil {
return Message{}, false, err
}
if err := tx.Commit(ctx); err != nil {
return Message{}, false, mapDB(err)
}
return msg, false, nil
}
if _, err := tx.Exec(ctx, `
DELETE FROM message_idempotency
WHERE user_id = $1 AND chat_id = $2 AND idem_key = $3`, senderID, chatID, idemKey); err != nil {
return Message{}, false, mapDB(err)
}
} else if !errors.Is(err, pgx.ErrNoRows) {
return Message{}, false, mapDB(err)
}
now := time.Now().UTC().Truncate(time.Microsecond)
if !last.IsZero() && !now.After(last.UTC()) {
now = last.UTC().Add(time.Microsecond)
}
m := Message{
ID: newID(),
ChatID: chatID,
@@ -255,12 +298,31 @@ func (p *PG) AddMessage(ctx context.Context, chatID, senderID, text string) (Mes
if _, err := tx.Exec(ctx, `
INSERT INTO messages (id, chat_id, sender_id, text, created_at)
VALUES ($1, $2, $3, $4, $5)`, m.ID, m.ChatID, m.SenderID, m.Text, m.CreatedAt); err != nil {
return Message{}, mapDB(err)
return Message{}, retryable(err), mapDB(err)
}
recorded := time.Now().UTC().Truncate(time.Microsecond)
if _, err := tx.Exec(ctx, `
INSERT INTO message_idempotency
(user_id, chat_id, idem_key, fingerprint, message_id, created_at, expires_at)
VALUES ($1, $2, $3, $4, $5, $6, $7)`,
senderID, chatID, idemKey, fingerprint, m.ID, recorded, recorded.Add(p.idemTTL)); err != nil {
return Message{}, retryable(err), mapDB(err)
}
if err := tx.Commit(ctx); err != nil {
return Message{}, mapDB(err)
return Message{}, retryable(err), mapDB(err)
}
return m, nil
return m, false, nil
}
func retryable(err error) bool {
var pgErr *pgconn.PgError
if errors.As(err, &pgErr) {
switch pgErr.Code {
case "23505", "40001", "40P01":
return true
}
}
return false
}
func (p *PG) ListMessages(ctx context.Context, chatID, userID string, cur *Cursor, limit int) ([]Message, bool, error) {
@@ -302,11 +364,10 @@ func (p *PG) ListMessages(ctx context.Context, chatID, userID string, cur *Curso
defer rows.Close()
items := make([]Message, 0)
for rows.Next() {
var m Message
if err := rows.Scan(&m.ID, &m.ChatID, &m.SenderID, &m.Text, &m.CreatedAt); err != nil {
return nil, false, mapDB(err)
m, err := scanMessage(rows)
if err != nil {
return nil, false, err
}
m.CreatedAt = m.CreatedAt.UTC()
items = append(items, m)
}
if err := rows.Err(); err != nil {
@@ -350,6 +411,15 @@ func (p *PG) memberIDs(ctx context.Context, q queryer, chatIDs []string) (map[st
return out, nil
}
func scanMessage(row pgx.Row) (Message, error) {
var m Message
if err := row.Scan(&m.ID, &m.ChatID, &m.SenderID, &m.Text, &m.CreatedAt); err != nil {
return Message{}, mapDB(err)
}
m.CreatedAt = m.CreatedAt.UTC()
return m, nil
}
func scanUser(row pgx.Row) (User, error) {
var u User
err := row.Scan(&u.ID, &u.Username, &u.DisplayName, &u.CreatedAt)
+52
View File
@@ -121,6 +121,58 @@ func TestIntegrationChatRollback(t *testing.T) {
}
}
func TestIntegrationIdempotencyRace(t *testing.T) {
pg := openIntegration(t)
ctx := context.Background()
u, err := pg.CreateUser(ctx, "idm_"+newID()[:8], "Ключ", "hash")
if err != nil {
t.Fatal(err)
}
chat, err := pg.CreateChat(ctx, "идемпотентность", []string{u.ID}, u.ID)
if err != nil {
t.Fatal(err)
}
const n = 16
var wg sync.WaitGroup
ids := make(chan string, n)
errs := make(chan error, n)
for i := 0; i < n; i++ {
wg.Add(1)
go func() {
defer wg.Done()
msg, err := pg.AddMessage(ctx, chat.ID, u.ID, "одно", "key-1", "одно")
if err != nil {
errs <- err
return
}
ids <- msg.ID
}()
}
wg.Wait()
close(ids)
close(errs)
for err := range errs {
t.Fatal(err)
}
seen := map[string]struct{}{}
for id := range ids {
seen[id] = struct{}{}
}
if len(seen) != 1 {
t.Fatalf("concurrent key created %d messages", len(seen))
}
if _, err := pg.AddMessage(ctx, chat.ID, u.ID, "другое", "key-1", "другое"); !errors.Is(err, ErrIdempotencyMismatch) {
t.Fatalf("mismatch: %v", err)
}
var count int
if err := pg.Pool().QueryRow(ctx, `SELECT count(*) FROM messages WHERE chat_id = $1`, chat.ID).Scan(&count); err != nil {
t.Fatal(err)
}
if count != 1 {
t.Fatalf("messages = %d, want 1", count)
}
}
func TestPostgresUnreachable(t *testing.T) {
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()
+46 -7
View File
@@ -10,11 +10,12 @@ import (
)
var (
ErrConflict = errors.New("conflict")
ErrNotFound = errors.New("not found")
ErrInvalid = errors.New("invalid")
ErrBadCursor = errors.New("bad cursor")
ErrUnavailable = errors.New("unavailable")
ErrConflict = errors.New("conflict")
ErrIdempotencyMismatch = errors.New("idempotency mismatch")
ErrNotFound = errors.New("not found")
ErrInvalid = errors.New("invalid")
ErrBadCursor = errors.New("bad cursor")
ErrUnavailable = errors.New("unavailable")
)
// User — публичная карточка. Хеш пароля в неё не входит.
@@ -57,7 +58,10 @@ type Repository interface {
CreateChat(ctx context.Context, title string, memberIDs []string, caller string) (Chat, error)
ChatFor(ctx context.Context, chatID, userID string) (Chat, error)
ListChats(ctx context.Context, userID string, cur *Cursor, limit int) ([]Chat, bool, error)
AddMessage(ctx context.Context, chatID, senderID, text string) (Message, error)
// AddMessage создаёт сообщение или возвращает уже записанное для того же ключа.
// fingerprint — каноническое тело (текст). Другой fingerprint при живом ключе даёт ErrIdempotencyMismatch.
// Ключ живёт idempotencyTTL. Область: отправитель + чат + ключ (метод POST и путь чата).
AddMessage(ctx context.Context, chatID, senderID, text, idemKey, fingerprint string) (Message, error)
ListMessages(ctx context.Context, chatID, userID string, cur *Cursor, limit int) ([]Message, bool, error)
}
@@ -66,6 +70,12 @@ type chatRec struct {
members map[string]struct{}
}
type idemRec struct {
fingerprint string
messageID string
expires time.Time
}
// Memory сериализует записи мьютексом. Это двойник контракта для тестов без PostgreSQL.
type Memory struct {
mu sync.RWMutex
@@ -76,6 +86,8 @@ type Memory struct {
chatOrder []string
messages map[string][]Message
msgIndex map[string]map[string]int
idem map[string]idemRec
idemTTL time.Duration
last time.Time
}
@@ -87,9 +99,21 @@ func New() *Memory {
chats: make(map[string]*chatRec),
messages: make(map[string][]Message),
msgIndex: make(map[string]map[string]int),
idem: make(map[string]idemRec),
idemTTL: 24 * time.Hour,
}
}
// SetIdempotencyTTL меняет срок ключа. Нужен тестам; в PostgreSQL тот же смысл у IDEMPOTENCY_TTL_SECONDS.
func (s *Memory) SetIdempotencyTTL(d time.Duration) {
if d <= 0 {
return
}
s.mu.Lock()
s.idemTTL = d
s.mu.Unlock()
}
func (s *Memory) Ping(ctx context.Context) error {
if err := ctx.Err(); err != nil {
return ErrUnavailable
@@ -218,10 +242,13 @@ func (s *Memory) ListChats(ctx context.Context, userID string, cur *Cursor, limi
return append([]Chat(nil), filtered[start:end]...), end < len(filtered), nil
}
func (s *Memory) AddMessage(ctx context.Context, chatID, senderID, text string) (Message, error) {
func (s *Memory) AddMessage(ctx context.Context, chatID, senderID, text, idemKey, fingerprint string) (Message, error) {
if err := ctx.Err(); err != nil {
return Message{}, ErrUnavailable
}
if idemKey == "" || fingerprint == "" {
return Message{}, ErrInvalid
}
s.mu.Lock()
defer s.mu.Unlock()
rec, ok := s.chats[chatID]
@@ -231,6 +258,17 @@ func (s *Memory) AddMessage(ctx context.Context, chatID, senderID, text string)
if _, member := rec.members[senderID]; !member {
return Message{}, ErrNotFound
}
slot := senderID + "\x00" + chatID + "\x00" + idemKey
if prev, ok := s.idem[slot]; ok && prev.expires.After(time.Now()) {
if prev.fingerprint != fingerprint {
return Message{}, ErrIdempotencyMismatch
}
idx, ok := s.msgIndex[chatID][prev.messageID]
if !ok {
return Message{}, ErrNotFound
}
return s.messages[chatID][idx], nil
}
m := Message{
ID: newID(),
ChatID: chatID,
@@ -241,6 +279,7 @@ func (s *Memory) AddMessage(ctx context.Context, chatID, senderID, text string)
idx := len(s.messages[chatID])
s.messages[chatID] = append(s.messages[chatID], m)
s.msgIndex[chatID][m.ID] = idx
s.idem[slot] = idemRec{fingerprint: fingerprint, messageID: m.ID, expires: time.Now().Add(s.idemTTL)}
return m, nil
}
+41 -8
View File
@@ -22,8 +22,13 @@ import (
)
func main() {
if len(os.Args) > 1 && os.Args[1] == "healthcheck" {
os.Exit(runHealthcheck())
if len(os.Args) > 1 {
switch os.Args[1] {
case "healthcheck":
os.Exit(runHealthcheck())
case "migrate":
os.Exit(runMigrate())
}
}
// Инициализация
@@ -41,11 +46,7 @@ func main() {
os.Exit(1)
}
defer pg.Close()
if err := migrate.Apply(root, pg.Pool()); err != nil {
stop()
log.Error("migrate", "err", "apply failed")
os.Exit(1)
}
pg.SetIdempotencyTTL(cfg.IdempotencyTTL)
sessions, err := session.OpenRedis(cfg.RedisURL)
if err != nil {
stop()
@@ -59,11 +60,19 @@ func main() {
os.Exit(1)
}
stop()
instanceID := cfg.InstanceID
if instanceID == "" {
instanceID, err = os.Hostname()
if err != nil || instanceID == "" {
log.Error("hostname")
os.Exit(1)
}
}
application := api.New(pg, sessions, password.Params{
Time: cfg.Argon2Time,
Memory: cfg.Argon2Memory,
Threads: cfg.Argon2Threads,
}, cfg.SessionTTL, log)
}, cfg.SessionTTL, instanceID, log)
// http сервер
srv := &http.Server{
Addr: cfg.Addr(),
@@ -81,6 +90,7 @@ func main() {
log.Info("listening",
"addr", cfg.Addr(),
"env", cfg.Env,
"instance_id", instanceID,
"shutdown_timeout_seconds", int(cfg.ShutdownTimeout/time.Second),
)
err := srv.ListenAndServe()
@@ -111,6 +121,29 @@ func main() {
log.Info("shutdown complete")
}
func runMigrate() int {
db := os.Getenv("DATABASE_URL")
if db == "" {
slog.Error("migrate", "err", "DATABASE_URL is required")
return 2
}
log := slog.New(slog.NewJSONHandler(os.Stdout, nil))
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
pg, err := store.Open(ctx, db, 2)
if err != nil {
log.Error("migrate", "err", "connect failed")
return 1
}
defer pg.Close()
if err := migrate.Apply(ctx, pg.Pool()); err != nil {
log.Error("migrate", "err", "apply failed")
return 1
}
log.Info("migrate complete")
return 0
}
func runHealthcheck() int {
port := os.Getenv("APP_PORT")
if port == "" {
+18
View File
@@ -0,0 +1,18 @@
-- Общая идемпотентность POST сообщения. Область: пользователь + чат + ключ.
-- Строка пишется в той же транзакции, что и сообщение, поэтому 5xx не оставляет
-- «занятый» ключ без сообщения и не оставляет сообщение без ключа.
-- Повтор с тем же текстом читает message_id. Другой текст — конфликт на уровне API.
CREATE TABLE message_idempotency (
user_id uuid NOT NULL REFERENCES users (id),
chat_id uuid NOT NULL REFERENCES chats (id),
idem_key text NOT NULL,
fingerprint text NOT NULL,
message_id uuid NOT NULL REFERENCES messages (id),
created_at timestamptz NOT NULL,
expires_at timestamptz NOT NULL,
PRIMARY KEY (user_id, chat_id, idem_key),
CONSTRAINT message_idempotency_key_len CHECK (char_length(idem_key) BETWEEN 1 AND 128),
CONSTRAINT message_idempotency_fingerprint_present CHECK (char_length(fingerprint) > 0),
CONSTRAINT message_idempotency_expiry CHECK (expires_at > created_at)
);
+143
View File
@@ -0,0 +1,143 @@
#!/usr/bin/env python3
"""Поочерёдный отказ каждой API-реплики и гонка одного Idempotency-Key."""
import json
import os
import subprocess
import sys
import threading
import time
import uuid
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT / "tests"))
from client import Client, Failure # noqa: E402
def compose(*args):
subprocess.check_call(["docker", "compose", "--env-file", ".env", *args], cwd=ROOT)
def instances(samples=40):
client = Client("http://127.0.0.1:8080", timeout=2)
found = []
deadline = time.monotonic() + 60
while time.monotonic() < deadline:
found = []
seen = set()
try:
for _ in range(samples):
item = client.call("GET", "/health/live", schema="Health")["headers"]["X-Instance-Id"]
if item not in seen:
seen.add(item)
found.append(item)
if len(found) >= 2:
return found
except Failure:
pass
time.sleep(1)
raise SystemExit("expected at least two API instances, saw " + ",".join(found))
def restore_api():
compose("up", "-d", "--no-deps", "api")
ids = subprocess.check_output(
["docker", "compose", "--env-file", ".env", "ps", "-aq", "api"], cwd=ROOT, text=True
).split()
if ids:
subprocess.check_call(["docker", "start", *ids], cwd=ROOT)
instances()
def stop_and_measure(target):
client = Client("http://127.0.0.1:8080", timeout=2)
alice, _bob, _eve, chat = client.bootstrap()
end = time.monotonic() + 12
stats = {"ok": 0, "fail": 0, "after_ok": 0, "target_after_stop": 0, "first_recovery_s": None}
started = {}
stopped = {}
def worker():
local = Client("http://127.0.0.1:8080", timeout=2)
while time.monotonic() < end:
key = uuid.uuid4().hex
try:
response = local.message(alice, chat, "отказ " + key, key=key)
stats["ok"] += 1
mark = started.get("at")
if mark is not None and stats["first_recovery_s"] is None:
stats["first_recovery_s"] = round(time.monotonic() - mark, 3)
if stopped.get("at") is not None:
stats["after_ok"] += 1
if response["headers"].get("X-Instance-Id") == target:
stats["target_after_stop"] += 1
except Failure:
stats["fail"] += 1
threads = [threading.Thread(target=worker) for _ in range(4)]
for thread in threads:
thread.start()
time.sleep(2)
started["at"] = time.monotonic()
env = os.environ.copy()
env["TARGET_INSTANCE_ID"] = target
proc = subprocess.run([str(ROOT / "scripts" / "stop-one.sh")], cwd=ROOT, env=env, text=True, capture_output=True)
stopped["at"] = time.monotonic()
stats["hook_exit"] = proc.returncode
stats["hook_seconds"] = round(stopped["at"] - started["at"], 3)
for thread in threads:
thread.join()
stats["target"] = target
stats["successful_rps"] = round(stats["ok"] / 12, 3)
return stats
def idempotency_race():
client = Client("http://127.0.0.1:8080", timeout=5)
alice, bob, _eve, chat = client.bootstrap()
key = uuid.uuid4().hex
ids = []
errors = []
def once():
try:
ids.append(Client("http://127.0.0.1:8080", timeout=5).message(alice, chat, "гонка", key=key)["json"]["id"])
except Failure as exc:
errors.append(str(exc))
threads = [threading.Thread(target=once) for _ in range(12)]
for thread in threads:
thread.start()
for thread in threads:
thread.join()
page = client.call("GET", "/api/v1/chats/" + chat["id"] + "/messages?limit=100", actor=bob, schema="MessagePage")["json"]
texts = [item["text"] for item in page["items"] if item["text"] == "гонка"]
return {
"parallel_requests": 12,
"distinct_ids": len(set(ids)),
"successes": len(ids),
"errors": errors,
"history_copies": len(texts),
}
def main():
os.chdir(ROOT)
before = instances()
runs = []
for target in before:
runs.append(stop_and_measure(target))
restore_api()
race = idempotency_race()
report = {"instances_before": before, "failover": runs, "idempotency_race": race}
dest = ROOT / "evidence" / "grade4.json"
dest.write_text(json.dumps(report, ensure_ascii=False, indent=2) + "\n")
print(json.dumps(report, ensure_ascii=False, indent=2))
if any(item["hook_exit"] != 0 or item["after_ok"] < 1 or item["target_after_stop"] != 0 for item in runs):
raise SystemExit("failover measurement failed")
if race["distinct_ids"] != 1 or race["history_copies"] != 1 or race["errors"]:
raise SystemExit("idempotency race failed")
if __name__ == "__main__":
main()
+2 -2
View File
@@ -1,5 +1,5 @@
#!/bin/sh
# Перезапуск API и всех хранилищ с сохранением volumes. Данные не сидируются заново.
# Перезапуск API, балансировщика и всех хранилищ. Volumes не удаляются, данные не сидируются.
set -eu
cd "$(dirname "$0")/.."
docker compose --env-file .env restart api postgres redis
docker compose --env-file .env restart postgres redis api haproxy
+28
View File
@@ -0,0 +1,28 @@
#!/bin/sh
# Поочерёдная замена контейнеров api. Оставшаяся реплика продолжает принимать трафик.
# Новые контейнеры собираются из текущего Dockerfile; старые заменяются по одному.
set -eu
cd "$(dirname "$0")/.."
scale="${API_REPLICAS:-2}"
docker compose --env-file .env build api
ids=$(docker compose --env-file .env ps -q api)
for id in $ids; do
docker stop -t 8 "$id" >/dev/null
docker rm "$id" >/dev/null
docker compose --env-file .env up -d --no-deps --no-recreate --scale "api=$scale" api >/dev/null
ready=0
i=0
while [ "$i" -lt 40 ]; do
if curl -fsS http://127.0.0.1:8080/health/ready >/dev/null; then
ready=1
break
fi
i=$((i + 1))
sleep 1
done
if [ "$ready" -ne 1 ]; then
echo "ready did not return after replacing one replica" >&2
exit 1
fi
done
echo "rolling update finished"
+22
View File
@@ -0,0 +1,22 @@
#!/bin/sh
# Останавливает одну API-реплику и оставляет её остановленной.
# TARGET_INSTANCE_ID — значение X-Instance-Id (hostname контейнера).
set -eu
cd "$(dirname "$0")/.."
: "${TARGET_INSTANCE_ID:?TARGET_INSTANCE_ID is required}"
target=$(printf '%s' "$TARGET_INSTANCE_ID" | tr -d '[:space:]')
found=""
for id in $(docker compose --env-file .env ps -q api); do
host=$(docker inspect -f '{{.Config.Hostname}}' "$id")
full=$(docker inspect -f '{{.Id}}' "$id")
short=$(printf '%s' "$full" | cut -c1-12)
if [ "$host" = "$target" ] || [ "$short" = "$target" ] || [ "$full" = "$target" ]; then
found=$id
break
fi
done
if [ -z "$found" ]; then
echo "API replica not found" >&2
exit 1
fi
docker stop -t 8 "$found" >/dev/null