add code for level 4

This commit is contained in:
Матвей
2026-10-14 15:25:51 +03:00
parent 6e7b8007ac
commit 516bb095ac
11 changed files with 175 additions and 13 deletions
+5 -2
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-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)
+24 -7
View File
@@ -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 не заявлен.
+20
View File
@@ -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:
+1 -1
View File
@@ -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.
+1 -1
View File
@@ -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.
+5
View File
@@ -0,0 +1,5 @@
$ docker inspect --format '{{.Name}} cpu_nano={{.HostConfig.NanoCpus}} memory_bytes={{.HostConfig.Memory}}' <containers>
/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
+4
View File
@@ -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
+10
View File
@@ -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
+2 -1
View File
@@ -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()
+3 -1
View File
@@ -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"}
+100
View File
@@ -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)