From 516bb095acee40bbe0b51d3c92f476983ec54510 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=9C=D0=B0=D1=82=D0=B2=D0=B5=D0=B9?= Date: Wed, 14 Oct 2026 15:25:51 +0300 Subject: [PATCH] add code for level 4 --- Makefile | 7 +- REPORT.md | 31 ++++++-- compose.yaml | 20 +++++ evidence/failover-api-a-2026-10-14.txt | 2 +- evidence/failover-api-b-2026-10-14.txt | 2 +- evidence/resource-limits-2026-10-14.txt | 5 ++ evidence/rolling-update-2026-10-14.txt | 4 + scripts/rolling-update.sh | 10 +++ src/main.py | 3 +- src/routes.py | 4 +- student-tests/rolling_update.py | 100 ++++++++++++++++++++++++ 11 files changed, 175 insertions(+), 13 deletions(-) create mode 100644 evidence/resource-limits-2026-10-14.txt create mode 100644 evidence/rolling-update-2026-10-14.txt create mode 100755 scripts/rolling-update.sh create mode 100755 student-tests/rolling_update.py diff --git a/Makefile b/Makefile index 5d86d171..48df5c00 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-persistence test-failover +.PHONY: help check validate test load test-persistence test-failover test-rolling help: - @echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes" + @echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes; test-rolling: sequential API replacement" check: $(PYTHON) scripts/check_contract.py @@ -28,3 +28,6 @@ test-persistence: test-failover: @test -n "$(ACTION_SCRIPT)" || (echo "Set ACTION_SCRIPT to your implemented executable stop-one hook"; exit 2) $(PYTHON) tests/resilience.py --mode failover --action-script "$(ACTION_SCRIPT)" --base-url "$(BASE_URL)" $(TLS_ARGS) + +test-rolling: + $(PYTHON) student-tests/rolling_update.py --base-url "$(BASE_URL)" $(TLS_ARGS) diff --git a/REPORT.md b/REPORT.md index 1d39065c..f962a563 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,7 +1,7 @@ # Отчёт — лабораторная 3 - Автор, группа: Матвей Козырев, БВТ2301 -- Целевая оценка; выбранный трек 5, если нужен: 3 +- Целевая оценка; выбранный трек 5, если нужен: 4 - Commit/PR: TODO после публикации - Использованные источники, библиотеки и помощь ИИ: FastAPI 0.141.1, Uvicorn 0.40.0, asyncpg 0.31.0, argon2-cffi 25.1.0; Docker Compose и Nginx. Код перенесён из собственной Lab2 и адаптирован для Lab3. @@ -23,6 +23,14 @@ make test Точка входа — `http://localhost:8080`; порты API и PostgreSQL на host не публикуются. Миграции выполняет одноразовый сервис `migrate` до запуска обеих API-реплик. Обычная остановка — `docker compose down`; она сохраняет volumes. Удаление учебных данных требует отдельной намеренной команды `docker compose down -v` и не выполняется restart/failover hooks. +Для уровня 4: + +```sh +make test-rolling +``` + +Скрипт `scripts/rolling-update.sh` поочерёдно пересоздаёт `api-a`, затем `api-b`; перед ним образ должен быть собран обычной командой `docker compose up -d --build`. Проверка одновременно пишет через LB и сравнивает набор `X-Instance-Id` до и после замены. + ## Архитектура и решения ```text @@ -31,6 +39,12 @@ make test PostgreSQL — общий источник истины для пользователей, сессий, чатов, сообщений и idempotency records. API не имеет локального состояния, определяющего корректность. `X-Instance-Id` берётся из hostname контейнера и стабилен до остановки процесса. Общий Docker secret задаёт ключ подписи курсоров, поэтому курсор, созданный одной репликой, проверяется другой. `Idempotency-Key` хранится в PostgreSQL в области user + method + path + key; создание сообщения и запись результата выполняются одной транзакцией. Nginx 1.27.5 повторно разрешает имена обеих реплик через Docker DNS каждые две секунды, а passive failure detection исключает backend после одной ошибки на две секунды. +`/health/live` отвечает, пока процесс запущен. `/health/ready` проверяет PostgreSQL и возвращает `503`, если приложение начало завершение. API healthcheck — каждые 5 с, timeout 3 с, 12 retries после start-period 10 с; Nginx при ошибке соединения немедленно пробует вторую реплику и исключает неответившую на `fail_timeout=2s`. Uvicorn получает до 8 с на graceful shutdown, а контейнеру задан `stop_grace_period=10s`. + +Фактические лимиты контейнеров: API — по 0,5 CPU / 256 MiB; PostgreSQL — 0,75 CPU / 512 MiB; Nginx — 0,25 CPU / 128 MiB. Они проверены через `docker inspect`, а не только заявлены в Compose. + +Миграции запускаются сервисом `migrate` один раз перед API. `001` создаёт исходную схему, `002` добавляет неиспользуемую после Lab2 колонку и сохранён как часть истории, `003` добавляет таблицу идемпотентности и индекс. Все изменения additive; предыдущая версия API не зависит от новой таблицы, а новая стартует только после завершения migrate. + ## Доказательства критериев | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | @@ -38,20 +52,23 @@ PostgreSQL — общий источник истины для пользова | Публичный smoke | `make test` | PASS: lab3 public API scenario | `evidence/smoke-2026-10-14.txt` | | Общая идемпотентность | `python3 student-tests/idempotency_concurrency.py` | 16 параллельных повторов через LB вернули одно сообщение; в истории одна запись | `evidence/idempotency-concurrency-2026-10-14.txt` | | Сохранность | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | PASS с прежней сессией и подтверждёнными данными после restart API, PostgreSQL и LB | `evidence/persistence-2026-10-14.txt` | -| Отказ api-b | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | 2 реплики до отказа; 130 успешных записей, 0 ошибок, первая успешная запись через 0,545 с | `evidence/failover-api-b-2026-10-14.txt` | -| Отказ api-a | Повтор после восстановления api-b | 2 реплики до отказа; 129 успешных записей, 0 ошибок, первая успешная запись через 0,559 с | `evidence/failover-api-a-2026-10-14.txt` | +| Отказ api-b | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | 2 реплики до отказа; 130 успешных записей, 0 ошибок, первая успешная запись через 0,765 с | `evidence/failover-api-b-2026-10-14.txt` | +| Отказ api-a | Повтор после восстановления api-b | 2 реплики до отказа; 129 успешных записей, 0 ошибок, первая успешная запись через 0,567 с | `evidence/failover-api-a-2026-10-14.txt` | +| Health, graceful shutdown и limits | `docker compose up -d --build --wait`; `docker inspect` | Обе API healthy; лимиты применены, API/DB порты наружу не опубликованы | `evidence/resource-limits-2026-10-14.txt` | +| Поочерёдная замена под записью | `make test-rolling` | 2 новых реплики; 380 успешных записей, 0 ошибок, 31,048 успешных RPS; все подтверждённые записи найдены в истории | `evidence/rolling-update-2026-10-14.txt` | После обеих failover-проверок вручную восстановлены `api-a` и `api-b`; финальный `docker compose ps` показал `healthy` для обеих API-реплик, Nginx и PostgreSQL. Скрипт persistence перезапускает PostgreSQL, обе API-реплики и LB; failover script останавливает только реплику, hostname которой совпадает с переданным `TARGET_INSTANCE_ID`. ## Эксперименты и отказы -Для уровня 3 проведены два 15-секундных сценария публичного `resilience.py` с его встроенным closed-loop потоком POST сообщений; это не нагрузочный бенчмарк. Параметры и ограничения генератора описаны в `tests/README.md`. +Для отказов проведены два 15-секундных сценария публичного `resilience.py` с его встроенным closed-loop потоком POST сообщений; это не нагрузочный бенчмарк. RPS рассчитан как `successful_writes / 15`: для api-b `130 / 15 = 8,667`, для api-a `129 / 15 = 8,600`. Параметры и ограничения генератора описаны в `tests/README.md`. Rolling-проверка длится 12,239 с: `380 / 12,239 = 31,048` успешных RPS; ошибок 0. Percentiles rolling-сценария относятся только к успешным POST. | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | --- | --- | --- | --- | -| Остановка api-b | Новые записи возобновляются не позднее 10 с, подтверждённые данные и сессия сохраняются | 130 успешных записей, 0 ошибок | 0,545 с / потерь не выявлено публичным тестом | -| Остановка api-a | То же после восстановления api-b | 129 успешных записей, 0 ошибок | 0,559 с / потерь не выявлено публичным тестом | +| Остановка api-b | Новые записи возобновляются не позднее 10 с, подтверждённые данные и сессия сохраняются | 130 успешных записей, 0 ошибок, 8,667 successful RPS | 0,765 с / потерь не выявлено публичным тестом | +| Остановка api-a | То же после восстановления api-b | 129 успешных записей, 0 ошибок, 8,600 successful RPS | 0,567 с / потерь не выявлено публичным тестом | +| Rolling update | Последовательная замена не останавливает запись через LB | 380 успехов, 0 ошибок, 31,048 successful RPS; p50/p95/p99 6,288/12,973/55,053 ms | 12,239 с / все подтверждённые записи найдены в истории | ## Ограничения и следующие шаги -Стенд выдерживает отказ одного API-процесса и перезапуск используемых stores с сохранёнными volumes. Он не заявляет выживание отказа host, Nginx или PostgreSQL: эти компоненты существуют в единственном экземпляре. Nginx использует passive failover; отдельная активная проверка backend на уровне LB не реализована. Уровни 4 и 5 не заявлены. +Стенд выдерживает отказ одного API-процесса, поочерёдную замену API и перезапуск PostgreSQL с сохранённым volume. Он не заявляет выживание отказа host, Nginx или PostgreSQL: эти компоненты существуют в единственном экземпляре. Nginx использует passive failover; отдельная активная проверка backend на уровне LB не реализована. Уровень 5 не заявлен. diff --git a/compose.yaml b/compose.yaml index f78c3306..2503e5af 100644 --- a/compose.yaml +++ b/compose.yaml @@ -24,6 +24,11 @@ x-api: &api timeout: 3s retries: 12 start_period: 10s + deploy: + resources: + limits: + cpus: "0.50" + memory: 256M services: postgres: @@ -42,6 +47,11 @@ services: timeout: 3s retries: 12 start_period: 5s + deploy: + resources: + limits: + cpus: "0.75" + memory: 512M migrate: build: @@ -57,6 +67,11 @@ services: postgres: condition: service_healthy restart: "no" + deploy: + resources: + limits: + cpus: "0.25" + memory: 128M api-a: <<: *api @@ -81,6 +96,11 @@ services: timeout: 3s retries: 12 start_period: 5s + deploy: + resources: + limits: + cpus: "0.25" + memory: 128M secrets: postgres_password: diff --git a/evidence/failover-api-a-2026-10-14.txt b/evidence/failover-api-a-2026-10-14.txt index 49e8b881..a843e5f7 100644 --- a/evidence/failover-api-a-2026-10-14.txt +++ b/evidence/failover-api-a-2026-10-14.txt @@ -1,6 +1,6 @@ $ make test-failover ACTION_SCRIPT=scripts/stop-one.sh Executing explicit failover hook; hook output suppressed to avoid leaking secrets. -{"observed_instances_before": 2, "successful_writes": 129, "failed_attempts": 0, "first_recovery_seconds": 0.559} +{"observed_instances_before": 2, "successful_writes": 129, "failed_attempts": 0, "first_recovery_seconds": 0.567} PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence. After the hook, `docker compose ps` showed api-b running and api-a stopped. api-a was then started and reached health=healthy. diff --git a/evidence/failover-api-b-2026-10-14.txt b/evidence/failover-api-b-2026-10-14.txt index dcc3a4e2..c178b59d 100644 --- a/evidence/failover-api-b-2026-10-14.txt +++ b/evidence/failover-api-b-2026-10-14.txt @@ -1,6 +1,6 @@ $ make test-failover ACTION_SCRIPT=scripts/stop-one.sh Executing explicit failover hook; hook output suppressed to avoid leaking secrets. -{"observed_instances_before": 2, "successful_writes": 130, "failed_attempts": 0, "first_recovery_seconds": 0.545} +{"observed_instances_before": 2, "successful_writes": 130, "failed_attempts": 0, "first_recovery_seconds": 0.765} PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence. After the hook, `docker compose ps` showed api-a running and api-b stopped. api-b was then started and reached health=healthy. diff --git a/evidence/resource-limits-2026-10-14.txt b/evidence/resource-limits-2026-10-14.txt new file mode 100644 index 00000000..4a6c887b --- /dev/null +++ b/evidence/resource-limits-2026-10-14.txt @@ -0,0 +1,5 @@ +$ docker inspect --format '{{.Name}} cpu_nano={{.HostConfig.NanoCpus}} memory_bytes={{.HostConfig.Memory}}' +/mtusi2026lab3-api-a-1 cpu_nano=500000000 memory_bytes=268435456 +/mtusi2026lab3-api-b-1 cpu_nano=500000000 memory_bytes=268435456 +/mtusi2026lab3-postgres-1 cpu_nano=750000000 memory_bytes=536870912 +/mtusi2026lab3-load_balancer-1 cpu_nano=250000000 memory_bytes=134217728 diff --git a/evidence/rolling-update-2026-10-14.txt b/evidence/rolling-update-2026-10-14.txt new file mode 100644 index 00000000..a26547a9 --- /dev/null +++ b/evidence/rolling-update-2026-10-14.txt @@ -0,0 +1,4 @@ +$ make test-rolling +python3 student-tests/rolling_update.py --base-url "http://localhost:8080" +{"instances_before": 2, "instances_after": 2, "successful_writes": 380, "failed_writes": 0, "elapsed_seconds": 12.239, "successful_rps": 31.048, "successful_latency_ms": {"p50": 6.288, "p95": 12.973, "p99": 55.053}} +PASS: sequential API replacement preserved writes through load balancer diff --git a/scripts/rolling-update.sh b/scripts/rolling-update.sh new file mode 100755 index 00000000..8c47717f --- /dev/null +++ b/scripts/rolling-update.sh @@ -0,0 +1,10 @@ +#!/bin/sh +set -eu + +# Equivalent to a rolling update for this two-replica Compose topology. +# Build the image separately; this hook only replaces one healthy API process at a time. +cd "$(dirname "$0")/.." + +for service in api-a api-b; do + docker compose up -d --no-deps --force-recreate --wait "$service" +done diff --git a/src/main.py b/src/main.py index f39c064a..0793eade 100644 --- a/src/main.py +++ b/src/main.py @@ -30,7 +30,6 @@ def logger(name: str) -> logging.Logger: access_logger = logger("messenger.access") -logger("messenger.cache") @asynccontextmanager @@ -41,9 +40,11 @@ async def lifespan(application: FastAPI): await store.connect() application.state.store = store application.state.settings = settings + application.state.accepting_requests = True try: yield finally: + application.state.accepting_requests = False await store.close() diff --git a/src/routes.py b/src/routes.py index e2e30799..2c1d4b67 100644 --- a/src/routes.py +++ b/src/routes.py @@ -79,7 +79,9 @@ async def liveness() -> dict[str, str]: return {"status": "ok"} @router.get("/health/ready") -async def readiness(store: PostgresStore = Depends(get_store)) -> dict[str, str]: +async def readiness(request: Request, store: PostgresStore = Depends(get_store)) -> dict[str, str]: + if not request.app.state.accepting_requests: + raise ApiError(503, "unavailable", "API завершает работу") await store.ready() return {"status": "ok"} diff --git a/student-tests/rolling_update.py b/student-tests/rolling_update.py new file mode 100755 index 00000000..fcd35444 --- /dev/null +++ b/student-tests/rolling_update.py @@ -0,0 +1,100 @@ +#!/usr/bin/env python3 +"""Проверяет поочерёдную замену двух API-реплик под записью через LB.""" +import json +import os +from pathlib import Path +import statistics +import subprocess +import sys +import time +import uuid +from urllib.parse import quote + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "tests")) +from client import Client, Failure, arguments, check, run # noqa: E402 + + +ROOT = Path(__file__).resolve().parents[1] + + +def history(client: Client, actor: dict, chat: dict) -> list[dict]: + path = "/api/v1/chats/" + chat["id"] + "/messages?limit=100" + messages, cursors = [], set() + while True: + page = client.call("GET", path, actor=actor, schema="MessagePage")["json"] + messages.extend(page["items"]) + cursor = page["next_cursor"] + if cursor is None: + return messages + check(cursor not in cursors, "history cursor cycle after rolling update") + cursors.add(cursor) + path = "/api/v1/chats/" + chat["id"] + "/messages?limit=100&cursor=" + quote(cursor, safe="") + + +def main() -> None: + args = arguments("Sequential API replacement under writes") + action = ROOT / "scripts" / "rolling-update.sh" + check(action.is_file() and os.access(action, os.X_OK), "rolling-update.sh must be executable") + client = Client(args.base_url, args.ca_file, timeout=2) + alice, _bob, _eve, chat = client.bootstrap() + + before = { + client.call("GET", "/api/v1/users/me", actor=alice, schema="User")["headers"]["X-Instance-Id"] + for _ in range(40) + } + check(len(before) >= 2, "less than two API instances observed before rolling update") + + process = subprocess.Popen([str(action)], cwd=ROOT) + started = time.monotonic() + latencies, failures, successful = [], 0, 0 + confirmed_ids = [] + try: + while process.poll() is None: + check(time.monotonic() - started < 90, "rolling update hook exceeded 90 seconds") + key = uuid.uuid4().hex + began = time.monotonic() + try: + message = client.message(alice, chat, "rolling-" + key, key=key)["json"] + successful += 1 + confirmed_ids.append(message["id"]) + latencies.append(time.monotonic() - began) + except Failure: + failures += 1 + time.sleep(0.02) + check(process.wait(timeout=5) == 0, "rolling update hook failed") + finally: + if process.poll() is None: + process.terminate() + process.wait(timeout=5) + + after = { + client.call("GET", "/api/v1/users/me", actor=alice, schema="User")["headers"]["X-Instance-Id"] + for _ in range(40) + } + check(len(after) >= 2, "less than two API instances observed after rolling update") + check(before.isdisjoint(after), "old API instance remained after sequential replacement") + check(successful > 0, "no writes succeeded during rolling update") + stored_ids = {message["id"] for message in history(client, alice, chat)} + check(all(message_id in stored_ids for message_id in confirmed_ids), "confirmed write lost during rolling update") + + elapsed = time.monotonic() - started + ordered = sorted(latencies) + def percentile(fraction: float) -> float | None: + if not ordered: + return None + return round(1000 * ordered[max(0, int(len(ordered) * fraction + 0.999999) - 1)], 3) + + print(json.dumps({ + "instances_before": len(before), + "instances_after": len(after), + "successful_writes": successful, + "failed_writes": failures, + "elapsed_seconds": round(elapsed, 3), + "successful_rps": round(successful / elapsed, 3), + "successful_latency_ms": {"p50": percentile(0.50), "p95": percentile(0.95), "p99": percentile(0.99)}, + }, ensure_ascii=False)) + print("PASS: sequential API replacement preserved writes through load balancer") + + +if __name__ == "__main__": + run(main)