This commit is contained in:
Матвей
2026-10-16 11:48:49 +03:00
parent f2c4395693
commit 4aba163f7a
14 changed files with 284 additions and 14 deletions
+32 -9
View File
@@ -3,7 +3,7 @@
- Автор, группа: Матвей Козырев, БВТ2301
- Целевая оценка: 5; трек 1 «Цена масштабирования»
- Commit/PR: TODO после публикации
- Использованные библиотеки: FastAPI, Uvicorn, asyncpg, argon2-cffi, Docker Compose, Nginx.
- Использованные библиотеки: FastAPI, Uvicorn, asyncpg, argon2-cffi, Docker Compose, HAProxy. До исправления замечаний 16.10.2026 использовался Nginx.
## Запуск из чистого clone
@@ -40,21 +40,23 @@ make track1
## Архитектура и решения
```text
Клиент → Nginx load_balancer → api-a / api-b → PostgreSQL
Клиент → HAProxy load_balancer → api-a / api-b → PostgreSQL
```
PostgreSQL — общий источник истины для пользователей, сессий, чатов, сообщений и idempotency records. API не хранит локального состояния, от которого зависит корректность. `X-Instance-Id` берётся из hostname контейнера. Общий Docker secret задаёт ключ подписи курсоров, поэтому курсор одной реплики проверяется другой. `Idempotency-Key` хранится в PostgreSQL в области user + method + path + key; создание сообщения и запись результата происходят в одной транзакции.
Nginx повторно разрешает имена API через Docker DNS каждые две секунды. Passive failure detection исключает backend после одной ошибки на две секунды. `/health/live` отвечает, пока процесс запущен; `/health/ready` проверяет PostgreSQL и при завершении приложения возвращает `503`.
HAProxy проверяет каждую API-реплику через `GET /health/ready` каждые 2 с: только статус 200 считается успехом. Одна неуспешная проверка исключает backend (`fall=1`), две успешные возвращают его (`rise=2`). Timeout проверки — 2 с, соединения — 1 с. Ожидаемое обнаружение отказа — следующий интервал плюс время проверки (около 4–5 с с учётом соединения, без гарантии времени планирования ОС). Проверки работают независимо от Docker health status и клиентского трафика. DNS обновляется через Docker resolver. Конфигурация: [haproxy.cfg](infra/haproxy.cfg); механизм: [HAProxy health checks](https://www.haproxy.com/documentation/haproxy-configuration-tutorials/reliability/health-checks/).
API healthcheck выполняется каждые 5 с, имеет timeout 3 с, `retries=12` и `start_period=10 с`. Uvicorn получает до 8 с на graceful shutdown; контейнеру задан `stop_grace_period=10 с`. Nginx повторяет запрос на второй backend при `error`, `timeout`, `502`, `503` и `504`.
API healthcheck выполняется каждые 5 с, имеет timeout 3 с, `retries=12` и `start_period=10 с`. Uvicorn получает до 8 с на graceful shutdown; контейнеру задан `stop_grace_period=10 с`. В HAProxy не включён повтор уже отправленных POST по HTTP-ошибкам: это защищает регистрации от неявного повторения.
Фактические лимиты основной конфигурации: API — по 0,5 CPU / 256 MiB; PostgreSQL — 0,75 CPU / 512 MiB; Nginx — 0,25 CPU / 128 MiB. Они подтверждены через `docker inspect`: [resource-limits-2026-10-14.txt](evidence/resource-limits-2026-10-14.txt).
Лимиты основной конфигурации: API — по 0,5 CPU / 256 MiB; PostgreSQL — 0,75 CPU / 512 MiB; LB — 0,25 CPU / 128 MiB. [Замер docker inspect от 14.10](evidence/resource-limits-2026-10-14.txt) относится к прежнему Nginx; лимиты сохранены в [compose.yaml](compose.yaml).
Миграции выполняет отдельный одноразовый сервис `migrate` до API. Миграции `001`, `002` и `003` additive: предыдущая версия API не зависит от добавленной таблицы идемпотентности, а новая стартует после завершения migrate.
## Проверка уровня 3 и 4
Следующая таблица содержит исторические результаты 14.10.2026 для Nginx. Регрессии после замены LB описаны в разделе «Исправления по ревью».
| Проверка | Команда | Результат | Доказательство |
| --- | --- | --- | --- |
| Публичный API-сценарий | `make test` | PASS | [smoke](evidence/smoke-2026-10-14.txt) |
@@ -68,18 +70,20 @@ RPS failover-сценариев: `130 / 15 = 8,667 RPS` для `api-b` и `129 /
## Уровень 5, трек 1 — цена масштабирования
Приведённые ниже данные и график получены 14.10.2026 с Nginx на версии `f2c4395`. Они не являются замерами HAProxy. После исправления readiness текущая команда `make track1` запускает HAProxy с активными проверками; для сравнения новой конфигурации требуется отдельная серия измерений.
### Гипотеза
При фиксированных суммарных ресурсах API (2 CPU / 1024 MiB) деление сервиса на две или четыре реплики не даст роста throughput, если PostgreSQL с лимитом 0,75 CPU станет ограничивающим компонентом. Увеличение только API-бюджета до 4 CPU / 2048 MiB также не должно помочь, пока лимит PostgreSQL не меняется.
### Методика
Для эксперимента добавлен [compose.benchmark.yaml](compose.benchmark.yaml). Он создаёт отдельный проект `mtusi2026lab3bench`: Nginx опубликован на `:8081`, PostgreSQL использует отдельный volume, API масштабируется параметром `--scale`.
Для эксперимента добавлен [compose.benchmark.yaml](compose.benchmark.yaml). Он создаёт отдельный проект `mtusi2026lab3bench`: LB опубликован на `:8081`, PostgreSQL использует отдельный volume, API масштабируется параметром `--scale`.
Скрипт [student-tests/track1_benchmark.py](student-tests/track1_benchmark.py) для каждой точки:
1. удаляет только временный volume benchmark-проекта;
2. запускает PostgreSQL, миграцию, заданное число API и Nginx;
2. запускает PostgreSQL, миграцию, заданное число API и LB;
3. запускает [tests/load.py](tests/load.py): 32 параллельных closed-loop клиента в течение 15 секунд отправляют POST сообщений без автоматических повторов;
4. примерно раз в секунду сохраняет `docker stats` всех benchmark-контейнеров;
5. записывает конфигурацию, метрики нагрузки и сэмплы ресурсов в JSON.
@@ -124,5 +128,24 @@ RPS failover-сценариев: `130 / 15 = 8,667 RPS` для `api-b` и `129 /
- Нагрузочный генератор closed-loop; он может быть ограничен клиентом и допускает coordinated omission. Latency в JSON относится только к успешным операциям.
- Каждая точка длится 15 секунд и выполнена один раз. Для статистического вывода нужны повторы, более длинные прогоны и доверительные интервалы.
- `docker stats` снимается примерно раз в секунду: этого достаточно для наблюдения CPU-лимита, но недостаточно для анализа SQL, lock waits и ожиданий пула соединений.
- PostgreSQL и Nginx существуют в одном экземпляре. Стенд не заявляет выживание отказа host, LB или PostgreSQL.
- Nginx использует passive failover; отдельная активная проверка API на уровне LB не реализована.
- PostgreSQL и HAProxy существуют в одном экземпляре. Стенд не заявляет выживание отказа host, LB или PostgreSQL.
## Исправления по ревью 16.10.2026
Результаты: [review-regressions-2026-10-16.txt](evidence/review-regressions-2026-10-16.txt). Новые регрессии, smoke, идемпотентность и persistence прошли. Rolling update: 318 успешных записей и 1 ошибка за 12,26 с; подтверждённые сообщения сохранены. Краткая ошибка до обнаружения остановленной реплики допустима, отсутствие ошибок во время замены не заявляется.
- Bearer с не-ASCII символами отклоняется до вычисления ASCII-хеша: 401, `WWW-Authenticate: Bearer …`, контрактный Error.
- Ошибки декодирования тела, которые FastAPI передаёт как HTTPException, преобразуются в Error. Для байта FF в JSON: 400, `invalid_request`, одинаковый request ID в теле и заголовке.
- Вместо passive-only Nginx применяется HAProxy с активным опросом готовности. Проверка зависимости от БД исключает API, даже если её процесс и `/health/live` продолжают работать.
Воспроизведение:
```sh
docker compose up -d --build --wait
python3 student-tests/review_regressions.py
python3 student-tests/readiness_failover.py
make test
make test-rolling
```
[readiness_failover.py](student-tests/readiness_failover.py) временно запрещает подключения IP api-a через pg_hba, закрывает её существующие подключения, проверяет 503 у api-a и 200 у api-b, затем выполняет 40 liveness-запросов и 20 регистраций через LB. В блоке finally восстанавливает исходный pg_hba, после чего проверяет возврат обеих реплик в балансировку. Запускать на учебном стенде, отдельно от других тестов отказа.
+2 -2
View File
@@ -70,11 +70,11 @@ services:
<<: *api
load_balancer:
image: nginx:1.27.5-alpine
image: haproxy:3.0.11-alpine
ports:
- "8081:8080"
volumes:
- ./infra/nginx.benchmark.conf:/etc/nginx/conf.d/default.conf:ro
- ./infra/haproxy.benchmark.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro
depends_on:
api:
condition: service_healthy
+2 -2
View File
@@ -80,11 +80,11 @@ services:
<<: *api
load_balancer:
image: nginx:1.27.5-alpine
image: haproxy:3.0.11-alpine
ports:
- "8080:8080"
volumes:
- ./infra/nginx.conf:/etc/nginx/conf.d/default.conf:ro
- ./infra/haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro
depends_on:
api-a:
condition: service_healthy
@@ -0,0 +1,30 @@
Review fixes, 2026-10-16. API behind haproxy:3.0.11-alpine.
$ python3 student-tests/review_regressions.py
PASS: non-ASCII Bearer returns 401/challenge; malformed JSON returns contract Error/400
$ python3 student-tests/readiness_failover.py
PASS: api-a ready=503, api-b ready=200; 40/40 live and 20/20 registrations use api-b
PASS: database access restored; both API replicas returned to LB
$ make test
PASS: lab3 public API scenario; infrastructure and grading evidence remain separate.
$ python3 student-tests/idempotency_concurrency.py
PASS: concurrent idempotency through load balancer
$ make test-rolling
{"instances_before": 2, "instances_after": 2, "successful_writes": 318, "failed_writes": 1, "elapsed_seconds": 12.26, "successful_rps": 25.938, "successful_latency_ms": {"p50": 6.652, "p95": 13.944, "p99": 50.718}}
PASS: sequential API replacement preserved writes through load balancer
$ make test-persistence ACTION_SCRIPT=scripts/restart.sh
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.
$ make check
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.
$ make validate PYTHON=.venv/bin/python
PASS: full OpenAPI 3.1 and JSON Schema validation; application NOT tested.
Final docker compose ps: api-a, api-b, load_balancer and postgres healthy.
Historical track1 results were NOT rerun and refer to Nginx, not HAProxy.
+34
View File
@@ -0,0 +1,34 @@
global
log stdout format raw local0
defaults
mode http
log global
option httplog
option forwardfor
timeout connect 1s
timeout client 30s
timeout server 10s
timeout check 2s
retries 2
resolvers docker
nameserver dns 127.0.0.11:53
resolve_retries 3
timeout resolve 1s
timeout retry 1s
hold valid 2s
hold obsolete 2s
frontend http
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 localhost
http-check expect status 200
default-server check inter 2s fall 1 rise 2 resolvers docker resolve-prefer ipv4 init-addr libc,none
server-template api 4 api:8080
+35
View File
@@ -0,0 +1,35 @@
global
log stdout format raw local0
defaults
mode http
log global
option httplog
option forwardfor
timeout connect 1s
timeout client 30s
timeout server 10s
timeout check 2s
retries 2
resolvers docker
nameserver dns 127.0.0.11:53
resolve_retries 3
timeout resolve 1s
timeout retry 1s
hold valid 2s
hold obsolete 2s
frontend http
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 localhost
http-check expect status 200
default-server check inter 2s fall 1 rise 2 resolvers docker resolve-prefer ipv4 init-addr libc,none
server api-a api-a:8080
server api-b api-b:8080
+2
View File
@@ -1,3 +1,5 @@
# Historical configuration used for evidence/track1/raw from 2026-10-14.
# Current compose.benchmark.yaml uses haproxy.benchmark.cfg.
upstream messenger_api {
zone messenger_api 64k;
resolver 127.0.0.11 valid=2s ipv6=off;
+2
View File
@@ -1,3 +1,5 @@
# Historical configuration used for evidence dated 2026-10-14.
# Current compose.yaml uses haproxy.cfg with active readiness checks.
upstream messenger_api {
zone messenger_api 64k;
resolver 127.0.0.11 valid=2s ipv6=off;
+20
View File
@@ -8,6 +8,7 @@ from fastapi import FastAPI, Request
from fastapi.exceptions import RequestValidationError
import uvicorn
from starlette.responses import JSONResponse, Response
from starlette.exceptions import HTTPException
from .errors import ApiError
from .cursor import configure_secret
@@ -116,6 +117,25 @@ async def handle_validation_error(
return error_response(request, 400, "invalid_request", "Некорректный запрос")
@app.exception_handler(HTTPException)
async def handle_http_error(request: Request, error: HTTPException) -> JSONResponse:
"""Включает ошибки декодирования тела, возникающие до Pydantic."""
codes = {
400: "invalid_request",
401: "unauthorized",
403: "forbidden",
404: "not_found",
405: "method_not_allowed",
503: "unavailable",
}
code = codes.get(error.status_code, "internal_error")
return error_response(
request, error.status_code, code,
"Некорректный запрос" if error.status_code < 500 else "Ошибка сервера",
error.headers,
)
@app.exception_handler(Exception)
async def handle_unexpected_error(request: Request, error: Exception) -> JSONResponse:
"""Не раскрывает внутренние детали при непредвиденной ошибке приложения."""
+1 -1
View File
@@ -36,7 +36,7 @@ async def get_current_user(
if authorization is None or not authorization.startswith("Bearer "):
raise ApiError(401, "unauthorized", "Требуется Bearer-сессия", BEARER_CHALLENGE)
token = authorization[7:]
if not token or token.strip() != token:
if not token or not token.isascii() or token.strip() != token:
raise ApiError(401, "unauthorized", "Требуется Bearer-сессия", BEARER_CHALLENGE)
user = await store.user_for_token(token)
if user is None:
+2
View File
@@ -138,6 +138,8 @@ class PostgresStore:
return {"token": token, "token_type": "Bearer", "expires_at": row["expires_at"], "user": user}
async def user_for_token(self, token: str) -> dict | None:
if not token.isascii():
return None
token_hash = sha256(token.encode("ascii")).hexdigest()
try:
row = await self.pool.fetchrow(
+89
View File
@@ -0,0 +1,89 @@
#!/usr/bin/env python3
"""Запрет БД только для api-a через pg_hba; восстановление в finally."""
import ipaddress
import json
from pathlib import Path
import subprocess
import sys
import time
import uuid
ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT / "tests"))
from client import Client, check, run
def compose(*args):
return subprocess.check_output(["docker", "compose", *args], cwd=ROOT, text=True).strip()
def sql(statement):
return compose("exec", "-T", "postgres", "psql", "-U", "messenger", "-d",
"messenger", "-v", "ON_ERROR_STOP=1", "-Atc", statement)
def ready(service):
code = """import urllib.request, urllib.error
try:
print(urllib.request.urlopen('http://127.0.0.1:8080/health/ready', timeout=7).status)
except urllib.error.HTTPError as error:
print(error.code)
"""
return compose("exec", "-T", service, "/app/.venv/bin/python", "-c", code)
def main():
client = Client()
container = json.loads(subprocess.check_output(
["docker", "inspect", compose("ps", "-q", "api-a")], text=True))[0]
addresses = list(container["NetworkSettings"]["Networks"].values())
check(len(addresses) == 1, "test expects one API network")
address = str(ipaddress.IPv4Address(addresses[0]["IPAddress"]))
bad_id = container["Config"]["Hostname"]
before = {client.call("GET", "/health/live")["headers"]["X-Instance-Id"] for _ in range(40)}
check(len(before) == 2 and bad_id in before, "both API replicas must be reachable")
check(ready("api-a") == ready("api-b") == "200", "both APIs must be ready")
# Сохраняем исходный pg_hba; чужую оставшуюся резервную копию не перезаписываем.
compose("exec", "-T", "postgres", "sh", "-ec",
'test ! -e "$PGDATA/pg_hba.conf.readiness-backup"; '
'cp -p "$PGDATA/pg_hba.conf" "$PGDATA/pg_hba.conf.readiness-backup"')
try:
compose("exec", "-T", "postgres", "sh", "-ec",
'{ printf "host all all %s/32 reject\\n" "$1"; '
'cat "$PGDATA/pg_hba.conf.readiness-backup"; } > "$PGDATA/pg_hba.conf"',
"sh", address)
sql("SELECT pg_reload_conf()")
time.sleep(0.5)
sql(f"SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE client_addr = '{address}'::inet")
check(ready("api-a") == "503", "api-a must be unready")
check(ready("api-b") == "200", "api-b must remain ready")
# 2s interval + 2s check timeout, с запасом на планировщик Docker Desktop.
time.sleep(6)
for _ in range(40):
result = client.call("GET", "/health/live", 200)
check(result["headers"]["X-Instance-Id"] != bad_id, "LB selected unready api-a")
for _ in range(20):
result = client.call("POST", "/api/v1/users", 201, body={
"username": "r_" + uuid.uuid4().hex[:16],
"display_name": "Readiness regression",
"password": "Test-password-" + uuid.uuid4().hex,
}, schema="User")
check(result["headers"]["X-Instance-Id"] != bad_id, "registration reached api-a")
print("PASS: api-a ready=503, api-b ready=200; 40/40 live and 20/20 registrations use api-b")
finally:
compose("exec", "-T", "postgres", "sh", "-ec",
'mv "$PGDATA/pg_hba.conf.readiness-backup" "$PGDATA/pg_hba.conf"')
sql("SELECT pg_reload_conf()")
deadline = time.monotonic() + 20
while time.monotonic() < deadline:
observed = {client.call("GET", "/health/live")["headers"]["X-Instance-Id"] for _ in range(10)}
if observed == before:
check(ready("api-a") == "200", "restored api-a must be ready")
print("PASS: database access restored; both API replicas returned to LB")
return
time.sleep(0.5)
raise AssertionError("api-a did not return to LB")
if __name__ == "__main__":
run(main)
+32
View File
@@ -0,0 +1,32 @@
#!/usr/bin/env python3
"""Регрессии ревью: не-ASCII Bearer и невалидная кодировка JSON через LB."""
from pathlib import Path
import sys
sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "tests"))
from client import Client, arguments, check, run
def main():
args = arguments(__doc__)
client = Client(args.base_url, args.ca_file)
for path in ("/api/v1/users/me", "/api/v1/auth/sessions/current"):
method = "DELETE" if path.endswith("/current") else "GET"
result = client.call(method, path, 401,
headers={"Authorization": "Bearer é"}, schema="Error")
check(result["headers"].get("WWW-Authenticate", "").startswith("Bearer"),
"missing Bearer challenge")
check(result["json"]["error"]["code"] == "unauthorized", "wrong error code")
check(result["json"]["error"]["request_id"] == result["headers"]["X-Request-Id"],
"request IDs differ")
for raw in (b"\xff", b"{", b'{"username":'):
result = client.call("POST", "/api/v1/users", 400, raw=raw,
headers={"Content-Type": "application/json"}, schema="Error")
check(result["json"]["error"]["code"] == "invalid_request", "wrong JSON error code")
check(result["json"]["error"]["request_id"] == result["headers"]["X-Request-Id"],
"request IDs differ")
print("PASS: non-ASCII Bearer returns 401/challenge; malformed JSON returns contract Error/400")
if __name__ == "__main__":
run(main)
+1
View File
@@ -74,6 +74,7 @@ def main() -> None:
report = {
"label": args.label,
"topology": {
"load_balancer_image": "haproxy:3.0.11-alpine",
"api_replicas": args.replicas,
"api_cpu_per_replica": args.api_cpus,
"api_memory_per_replica": args.api_memory,