diff --git a/.env.example b/.env.example index d32b9be0..b5a1baa3 100644 --- a/.env.example +++ b/.env.example @@ -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 diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index e6e63eb2..7e639937 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -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 содержит инструкцию именно моего решения. diff --git a/Makefile b/Makefile index 02f133b4..5d86d171 100644 --- a/Makefile +++ b/Makefile @@ -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) diff --git a/REPORT.md b/REPORT.md index c2679005..1a15de40 100644 --- a/REPORT.md +++ b/REPORT.md @@ -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, иначе тот же ключ с разными вложениями будет считаться тем же телом. diff --git a/compose.yaml b/compose.yaml index c7cc885d..ad78da88 100644 --- a/compose.yaml +++ b/compose.yaml @@ -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: diff --git a/deploy/haproxy.cfg b/deploy/haproxy.cfg new file mode 100644 index 00000000..a7f75c7b --- /dev/null +++ b/deploy/haproxy.cfg @@ -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 diff --git a/evidence/failover-first-ps.txt b/evidence/failover-first-ps.txt new file mode 100644 index 00000000..ae28fb3b --- /dev/null +++ b/evidence/failover-first-ps.txt @@ -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) diff --git a/evidence/failover-first.txt b/evidence/failover-first.txt new file mode 100644 index 00000000..18806869 --- /dev/null +++ b/evidence/failover-first.txt @@ -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. diff --git a/evidence/failover-second-ps.txt b/evidence/failover-second-ps.txt new file mode 100644 index 00000000..02e29ce0 --- /dev/null +++ b/evidence/failover-second-ps.txt @@ -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) diff --git a/evidence/failover-second.txt b/evidence/failover-second.txt new file mode 100644 index 00000000..36a22d62 --- /dev/null +++ b/evidence/failover-second.txt @@ -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. diff --git a/evidence/grade4.json b/evidence/grade4.json new file mode 100644 index 00000000..f7d05fdb --- /dev/null +++ b/evidence/grade4.json @@ -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 + } +} diff --git a/evidence/instances.txt b/evidence/instances.txt new file mode 100644 index 00000000..c50dedc3 --- /dev/null +++ b/evidence/instances.txt @@ -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 diff --git a/evidence/persistence.txt b/evidence/persistence.txt new file mode 100644 index 00000000..793b001d --- /dev/null +++ b/evidence/persistence.txt @@ -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. diff --git a/evidence/rolling-load.json b/evidence/rolling-load.json new file mode 100644 index 00000000..843cddd0 --- /dev/null +++ b/evidence/rolling-load.json @@ -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." +} diff --git a/evidence/schema-migrations.txt b/evidence/schema-migrations.txt new file mode 100644 index 00000000..6b9786a9 --- /dev/null +++ b/evidence/schema-migrations.txt @@ -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) + diff --git a/evidence/smoke.txt b/evidence/smoke.txt new file mode 100644 index 00000000..44e41deb --- /dev/null +++ b/evidence/smoke.txt @@ -0,0 +1,2 @@ +python3 tests/smoke.py --base-url "http://localhost:8080" +PASS: lab3 public API scenario; infrastructure and grading evidence remain separate. diff --git a/internal/api/handlers.go b/internal/api/handlers.go index 28966f7c..b68bc36d 100644 --- a/internal/api/handlers.go +++ b/internal/api/handlers.go @@ -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): diff --git a/internal/api/http.go b/internal/api/http.go index ac688c49..b4ffbc4f 100644 --- a/internal/api/http.go +++ b/internal/api/http.go @@ -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"` diff --git a/internal/api/server.go b/internal/api/server.go index f43570f3..96cacf29 100644 --- a/internal/api/server.go +++ b/internal/api/server.go @@ -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() { diff --git a/internal/api/server_test.go b/internal/api/server_test.go index 5c76e91b..55d12ebc 100644 --- a/internal/api/server_test.go +++ b/internal/api/server_test.go @@ -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 diff --git a/internal/config/config.go b/internal/config/config.go index 603a00ea..6c9cf3c8 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -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 } diff --git a/internal/migrate/migrate.go b/internal/migrate/migrate.go index 79b339d4..0e99ebcc 100644 --- a/internal/migrate/migrate.go +++ b/internal/migrate/migrate.go @@ -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 } diff --git a/internal/store/postgres.go b/internal/store/postgres.go index c2cbba2c..194b9a42 100644 --- a/internal/store/postgres.go +++ b/internal/store/postgres.go @@ -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) diff --git a/internal/store/postgres_test.go b/internal/store/postgres_test.go index 7ee018ba..2ab49ce6 100644 --- a/internal/store/postgres_test.go +++ b/internal/store/postgres_test.go @@ -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() diff --git a/internal/store/store.go b/internal/store/store.go index 181ed1ce..bc8cf01e 100644 --- a/internal/store/store.go +++ b/internal/store/store.go @@ -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 } diff --git a/messenger/main.go b/messenger/main.go index 946bc76b..dc7ce550 100644 --- a/messenger/main.go +++ b/messenger/main.go @@ -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 == "" { diff --git a/migrations/002_idempotency.sql b/migrations/002_idempotency.sql new file mode 100644 index 00000000..61b38837 --- /dev/null +++ b/migrations/002_idempotency.sql @@ -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) +); diff --git a/scripts/grade4.py b/scripts/grade4.py new file mode 100755 index 00000000..94661449 --- /dev/null +++ b/scripts/grade4.py @@ -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() diff --git a/scripts/restart.sh b/scripts/restart.sh index 303ee2c1..315748f9 100755 --- a/scripts/restart.sh +++ b/scripts/restart.sh @@ -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 diff --git a/scripts/rolling-update.sh b/scripts/rolling-update.sh new file mode 100755 index 00000000..d22b0ba4 --- /dev/null +++ b/scripts/rolling-update.sh @@ -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" diff --git a/scripts/stop-one.sh b/scripts/stop-one.sh new file mode 100755 index 00000000..d1c7dbbb --- /dev/null +++ b/scripts/stop-one.sh @@ -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