Files
mtusi2026lab3/scripts/build_defense_pdf.py

748 lines
45 KiB
Python
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# -*- coding: utf-8 -*-
"""Собрать шпаргалку к защите lab3 (кириллица, Windows Arial)."""
from pathlib import Path
from fpdf import FPDF
ROOT = Path(__file__).resolve().parents[1]
OUT = ROOT / "DEFENSE.pdf"
FONT = Path(r"C:\Windows\Fonts\arial.ttf")
FONT_B = Path(r"C:\Windows\Fonts\arialbd.ttf")
FONT_I = Path(r"C:\Windows\Fonts\ariali.ttf")
FONT_C = Path(r"C:\Windows\Fonts\consola.ttf")
if not FONT_C.exists():
FONT_C = Path(r"C:\Windows\Fonts\cour.ttf")
class Pdf(FPDF):
def header(self):
if self.page_no() == 1:
return
self.set_font("Body", "", 8)
self.set_text_color(90, 90, 90)
self.set_x(self.l_margin)
self.cell(0, 6, "Lab3 zashchita | Shcherbatsevich | BPI2302 | 5 track 1", align="L")
self.ln(8)
self.set_text_color(0, 0, 0)
self.set_x(self.l_margin)
def footer(self):
self.set_y(-12)
self.set_font("Body", "", 8)
self.set_text_color(90, 90, 90)
self.set_x(self.l_margin)
self.cell(0, 8, str(self.page_no()), align="C")
self.set_text_color(0, 0, 0)
def _w(pdf):
pdf.set_x(pdf.l_margin)
return pdf.epw
def h1(pdf, text):
pdf.ln(4)
pdf.set_font("Body", "B", 16)
pdf.multi_cell(_w(pdf), 8, text)
pdf.ln(1)
def h2(pdf, text):
pdf.ln(3)
pdf.set_font("Body", "B", 13)
pdf.multi_cell(_w(pdf), 7, text)
pdf.ln(1)
def h3(pdf, text):
pdf.ln(2)
pdf.set_font("Body", "B", 11)
pdf.multi_cell(_w(pdf), 6, text)
def body(pdf, text):
pdf.set_font("Body", "", 10)
pdf.multi_cell(_w(pdf), 5.2, text)
pdf.ln(0.8)
def speak(pdf, text):
pdf.set_fill_color(235, 243, 255)
pdf.set_font("Body", "I", 10)
pdf.multi_cell(_w(pdf), 5.2, "ГОВОРИТЬ: " + text, fill=True)
pdf.ln(1.5)
def warn(pdf, text):
pdf.set_fill_color(255, 243, 220)
pdf.set_font("Body", "B", 10)
pdf.multi_cell(_w(pdf), 5.2, "НЕ ВРАТЬ: " + text, fill=True)
pdf.ln(1.5)
def show(pdf, text):
pdf.set_fill_color(232, 245, 233)
pdf.set_font("Body", "B", 10)
pdf.multi_cell(_w(pdf), 5.2, "ПОКАЗАТЬ: " + text, fill=True)
pdf.ln(1.5)
def code(pdf, text):
pdf.set_font("Code", "", 7.5)
pdf.set_fill_color(245, 245, 245)
pdf.multi_cell(_w(pdf), 4.0, text.rstrip() + "\n", fill=True)
pdf.ln(1.2)
def bullet(pdf, text):
pdf.set_font("Body", "", 10)
pdf.multi_cell(_w(pdf), 5.2, "- " + text)
pdf.ln(0.3)
def qa(pdf, q, a):
pdf.set_font("Body", "B", 10)
pdf.multi_cell(_w(pdf), 5.2, "В: " + q)
pdf.set_font("Body", "", 10)
pdf.multi_cell(_w(pdf), 5.2, "О: " + a)
pdf.ln(1.5)
def build():
pdf = Pdf(format="A4", unit="mm")
pdf.set_auto_page_break(auto=True, margin=16)
pdf.add_font("Body", "", str(FONT))
pdf.add_font("Body", "B", str(FONT_B))
pdf.add_font("Body", "I", str(FONT_I))
pdf.add_font("Code", "", str(FONT_C))
pdf.add_page()
pdf.set_font("Body", "B", 22)
pdf.multi_cell(_w(pdf), 10, "Методичка к защите")
pdf.set_font("Body", "B", 16)
pdf.multi_cell(_w(pdf), 8, "Лабораторная 3 — балансировка и отказ API-реплики")
pdf.ln(2)
pdf.set_font("Body", "", 11)
for line in [
"Автор: Щербацевич Владислав Сергеевич",
"Группа: БПИ2302",
"Целевая оценка: 5",
"Трек: 1 — цена масштабирования (Compose + HAProxy, не Swarm, не трек 2)",
"Вход: http://127.0.0.1:8080 и http://localhost:8080 (оба должны отвечать)",
"Этот файл — шпаргалка. Не читать с листа целиком: открывать нужный раздел.",
]:
pdf.multi_cell(_w(pdf), 6, line)
pdf.ln(3)
body(
pdf,
"Как пользоваться на защите. Сначала 90 секунд «что это за система». Потом живой стенд: "
"два X-Instance-Id, docker ps, stop-one. Код показывают только когда спрашивают «где». "
"Цифры трека 1 — из REPORT.md и evidence/, не из головы. Если не помните число — откройте JSON.",
)
h1(pdf, "0. Карта выступления (10–15 минут)")
bullet(pdf, "1 мин — задача лабы и схема Клиент → HAProxy → api×2 → Postgres + Redis.")
bullet(pdf, "1 мин — живой стенд: curl/браузер, два разных X-Instance-Id, одна сессия.")
bullet(pdf, "2 мин — docker compose ps: API без host-порта, имена api-N, лимиты.")
bullet(pdf, "2 мин — идемпотентность: ключ в заголовке, таблица в Postgres, гонка 12 потоков.")
bullet(pdf, "2 мин — отказ: stop-one, recovery ~2.5 с, вторая реплика.")
bullet(pdf, "2 мин — уровень 4: ready 1 с fall 2, SIGTERM, rolling, migrate one-shot.")
bullet(pdf, "3 мин — трек 1: гипотеза, 128/107/69 и 49/105/221, честно про saturation, IPv6.")
bullet(pdf, "Оставшееся — вопросы.")
h1(pdf, "1. Что говорить в первые 90 секунд")
speak(
pdf,
"Это мессенджер с lab2: пользователи, чаты, сообщения, сессии. В lab3 я не размножаю данные, "
"а размножаю процессы API. Снаружи одна дверь — HAProxy на порту 8080. За ней минимум два "
"одинаковых контейнера api. Сообщения пишет PostgreSQL, сессии лежат в Redis, не в памяти "
"процесса. Поэтому можно убить один api — логин не слетает, дублей сообщения нет, если клиент "
"повторил тот же Idempotency-Key. Sticky-сессий нет: один пользователь разными запросами "
"попадает на разные реплики — это видно по заголовку X-Instance-Id. Для пятёрки выбран трек 1: "
"не «ещё узлов», а цена лишних реплик при фиксированном CPU.",
)
warn(
pdf,
"Не говорить «у нас высокая доступность системы». Выдерживается отказ ОДНОГО процесса API. "
"Хост, HAProxy, Postgres, Redis — точки отказа. Трек 2 не делался.",
)
h1(pdf, "2. Схема и роли файлов")
body(
pdf,
"Клиент (браузер, smoke, level3) бьёт в localhost:8080. Контейнер lb — HAProxy. Он round-robin "
"раздаёт на контейнеры сервиса api. Имя api в Docker DNS имеет несколько IP. Postgres — источник "
"истины (users, chats, messages, idempotency_records, schema_migrations). Redis — сессии, AOF "
"appendfsync always. Контейнер migrate один раз накатывает SQL и выходит. API сами DDL не гоняют.",
)
h3(pdf, "Куда ткнуть курсор, если просят «покажи файл»")
bullet(pdf, "compose.yaml — весь стенд: сервисы, реплики, лимиты, секреты, нет ports у api, нет container_name.")
bullet(pdf, "infra/haproxy.cfg — roundrobin, httpchk /health/ready, inter 1s fall 2, live отвечает сам LB.")
bullet(pdf, "src/app/middleware.py — X-Request-Id и X-Instance-Id, 503 при shutdown.")
bullet(pdf, "src/app/config.py — instance_id из HOSTNAME.")
bullet(pdf, "src/app/api/health.py — live vs ready.")
bullet(pdf, "src/app/main.py — accepting, lifespan SIGTERM.")
bullet(pdf, "src/app/__main__.py — uvicorn timeout_graceful_shutdown=5.")
bullet(pdf, "src/app/sessions.py — Redis PXAT, не память процесса.")
bullet(pdf, "src/app/api/messages.py и src/app/crud/messages.py — Idempotency-Key.")
bullet(pdf, "migrations/002_idempotency.sql — таблица ключей.")
bullet(pdf, "src/app/migrate.py и сервис migrate в compose — one-shot.")
bullet(pdf, "scripts/stop-one.sh (.cmd) — стоп по X-Instance-Id.")
bullet(pdf, "scripts/rolling-update.sh — новый контейнер до удаления старого.")
bullet(pdf, "student-tests/level3.py — две реплики + гонка ключа.")
bullet(pdf, "student-tests/track1.py и evidence/track1.json — пятёрка.")
bullet(pdf, "REPORT.md — цифры, которые можно зачитать.")
h1(pdf, "3. Команды: стенд, тесты, доказательства")
body(
pdf,
"Защита на Windows. В PowerShell из корня репозитория. PYTHONUTF8=1 — чтобы make/python не падали на кириллице. "
"Секреты не печатать в чат и не открывать на проекторе содержимое secrets/.",
)
h3(pdf, "3.1. Поднять с нуля (если стенд ещё нет)")
code(
pdf,
"cd C:\\Users\\Admin\\PycharmProjects\\mtusi2026lab3\n"
"powershell -ExecutionPolicy Bypass -File scripts\\bootstrap.ps1\n"
"docker compose --env-file .env config --quiet\n"
"docker compose --env-file .env up -d --build --wait --scale api=2",
)
body(
pdf,
"bootstrap создаёт .env и файлы секретов, не коммитятся. config --quiet проверяет compose. "
"--wait ждёт healthcheck. scale api=2 обязательно: дефолт тоже 2, но на защите произнесите число.",
)
h3(pdf, "3.2. Живой пульс")
code(
pdf,
"curl.exe -i http://127.0.0.1:8080/health/live\n"
"curl.exe -i http://127.0.0.1:8080/health/ready\n"
"docker compose --env-file .env ps",
)
body(
pdf,
"live с улицы отдаёт HAProxy: X-Instance-Id: load-balancer — это касса, не реплика. "
"ready идёт на API. В ps у api колонка PORTS должна быть 8080/tcp БЕЗ 0.0.0.0:xxxx — порты на хост не проброшены. "
"Доказательство уже снято: evidence/compose-ps.txt.",
)
warn(pdf, "Не доказывать разные реплики через /health/live. Только /api/v1/users/me или POST сообщения.")
h3(pdf, "3.3. Два instance id одной сессией (сценарий README пункт 1)")
body(pdf, "Проще всего готовый тест — он логинится сам и 40 раз бьёт /users/me:")
code(pdf, "$env:PYTHONUTF8='1'\npython student-tests/level3.py")
body(
pdf,
"PASS и evidence/level3.json: unique_instance_ids длина ≥2. Если хотят руками: зарегистрировать пользователя "
"(examples/requests.http), взять Bearer, повторять GET /api/v1/users/me — заголовок X-Instance-Id должен чередоваться.",
)
h3(pdf, "3.4. Публичные проверки курса")
code(
pdf,
"python tests/smoke.py --base-url http://127.0.0.1:8080\n"
"python student-tests/persistence_hook.py\n"
"python student-tests/failover.py\n"
"scripts\\restore-api.cmd\n"
"python student-tests/failover.py\n"
"python student-tests/rolling.py",
)
body(
pdf,
"smoke — контракт lab3 (ключ, replay, 409). persistence — restart стенда, тот же токен, volumes на месте "
"(scripts/restart.cmd внутри хука). failover — stop-one.cmd по TARGET_INSTANCE_ID. "
"После первого failover реплик станет 1 — restore-api.cmd возвращает scale 2, второй прогон бьёт уже другую. "
"На POSIX в README: make test-failover ACTION_SCRIPT=scripts/stop-one.sh. У вас Windows, поэтому .cmd.",
)
show(pdf, "Готовые логи: evidence/smoke.txt, persistence.txt, failover.txt, sequential_failover.json, rolling.json, level3.json.")
h3(pdf, "3.5. Трек 1 (долго, на защите обычно НЕ гонять заново)")
code(
pdf,
"python student-tests/track1.py\n"
"python tests/load.py --duration 20 --concurrency 8 --output evidence/load_ipv4.json",
)
body(pdf, "Открыть evidence/track1.json и SVG. Повтор прогона — много минут и сменит цифры; для защиты достаточно снятого замера 2026-10-30.")
h3(pdf, "3.6. Остановить / поднять")
code(
pdf,
"docker compose --env-file .env down # данные в volumes остаются\n"
"docker compose --env-file .env down -v # учебное обнуление БД — на защите не делать",
)
h1(pdf, "4. Оценка 3 — что говорить и какой код")
h2(pdf, "4.1. Стенд в одном compose, две реплики, одна дверь")
speak(
pdf,
"Весь стенд в compose.yaml, не Swarm. Имя проекта mtusi-lab3. Сервисы: postgres, redis, migrate, api, lb. "
"Реплик api две. С хоста торчит только lb 127.0.0.1:8080 и [::1]:8080. База и redis на loopback для отладки, "
"это не API. Образы с digest, не latest.",
)
show(pdf, "compose.yaml — services api и lb; блок deploy.replicas; отсутствие ports у api.")
code(
pdf,
" api:\n"
" deploy:\n"
" replicas: ${API_REPLICAS:-2}\n"
" # НЕТ ports: и НЕТ container_name\n"
" lb:\n"
" ports:\n"
" - \"127.0.0.1:8080:8080\"\n"
" - \"[::1]:8080:8080\"",
)
body(
pdf,
"Зачем нет container_name: имя контейнера в Docker уникально. Если написать messenger-api, вторую реплику "
"scale не создаст. Compose сам даёт mtusi-lab3-api-1, api-2.",
)
h2(pdf, "4.2. HAProxy: очередь без прилипания")
speak(
pdf,
"HAProxy — касса с одной дверью. Клиент не знает про два официанта. Алгоритм roundrobin: запросы по кругу. "
"Cookie нет, IP не клеим — sticky запрещён заданием, иначе скрыли бы, что сессия не общая. "
"Список бэкендов не руками: server-template спрашивает Docker DNS имя api, до 4 слотов. "
"Проверка живости — GET /health/ready каждые 1 с, два провала — вон из круга.",
)
show(pdf, "infra/haproxy.cfg целиком, особенно backend api.")
code(
pdf,
"frontend public\n"
" bind *:8080\n"
" http-request return status 200 ... hdr X-Instance-Id \"load-balancer\" ... if { path /health/live }\n"
" default_backend api\n"
"backend api\n"
" balance roundrobin\n"
" option httpchk\n"
" http-check send meth GET uri /health/ready ...\n"
" http-check expect status 200\n"
" default-server inter 1s fall 2 rise 1 resolvers docker ...\n"
" server-template api 4 api:8080 check",
)
body(
pdf,
"Почему не Nginx: свободный выбор, взяли HAProxy 3.2 с docker resolvers. Почему live на LB: контракт хочет, "
"чтобы публичный live проверял процесс ВХОДА. Ready — можно ли давать работу этой реплике (БД+Redis+accepting).",
)
h2(pdf, "4.3. X-Instance-Id и X-Request-Id")
speak(
pdf,
"Request-Id — имя письма, каждый запрос новый UUID, его клеит middleware. Instance-Id — имя почтальона: "
"пока жив процесс, строка одна. Берётся из переменной INSTANCE_ID, иначе HOSTNAME контейнера. "
"В базу не пишется. Нужен, чтобы доказать две реплики и чтобы stop-one нашёл контейнер. "
"Request-Id для docker stop бесполезен.",
)
show(pdf, "src/app/config.py функция _instance_id; src/app/middleware.py; src/app/main.py app.state.instance_id")
code(
pdf,
"# config.py\n"
"configured = os.environ.get(\"INSTANCE_ID\", \"\").strip()\n"
"if configured: return configured\n"
"host = os.environ.get(\"HOSTNAME\", \"\").strip() or socket.gethostname()\n"
"return host\n"
"\n"
"# middleware.py\n"
"response.headers[\"X-Request-Id\"] = request_id\n"
"response.headers[\"X-Instance-Id\"] = _instance_id(request)",
)
h2(pdf, "4.4. Общие сессии — почему не память API")
speak(
pdf,
"Если сессию хранить в словаре Python, второй контейнер не узнает токен — после round-robin будет 401, "
"придётся логиниться снова. Redis общий. Ключ sess:sha256(token), TTL абсолютный PXAT, чтобы после "
"рестарта Redis из AOF срок не продлился. AOF appendfsync always — учебная сохранность при restart.",
)
show(pdf, "src/app/sessions.py create_session / resolve_session; compose redis command --appendonly yes")
code(
pdf,
"token = secrets.token_urlsafe(32)\n"
"await redis.set(session_key(token), payload, pxat=int(expires_at.timestamp() * 1000))",
)
h2(pdf, "4.5. Идемпотентность POST сообщения")
speak(
pdf,
"Ключ придумывает клиент, не человек в UI и не сервер. Сервер только читает заголовок Idempotency-Key. "
"Без него 400. Область: пользователь + POST + путь чата + строка ключа. Хранится в Postgres таблица "
"idempotency_records. Повтор того же текста — тот же message id. Другой текст — 409. Другой пользователь "
"с тем же ключом — другое сообщение. Параллель: pg_advisory_xact_lock, чтобы два API не вставили два сообщения. "
"Пишем Message, flush, потом запись ключа — в одной транзакции. 5xx не сохраняем: если упали до INSERT ключа, "
"клиент может повторить тот же ключ.",
)
show(pdf, "src/app/api/messages.py require_idempotency_key; crud/messages.py create_message; migrations/002_idempotency.sql")
code(
pdf,
"# api: без заголовка — 400\n"
"value = request.headers.get(\"idempotency-key\")\n"
"\n"
"# crud: замок по user+path+key, потом SELECT ключа\n"
"SELECT pg_advisory_xact_lock(:a, :b)\n"
"# тот же hash текста → вернуть старое сообщение\n"
"# другой hash → 409\n"
"# нет записи → INSERT messages, INSERT idempotency_records status 201",
)
body(
pdf,
"Генерация ключа в тестах: tests/client.py — uuid.uuid4().hex если вызывающий не передал key. "
"Гонка: student-tests/level3.py функция test_concurrent_key — Barrier на 12 потоков, один ключ, "
"ожидаем 12×201 и один id, в истории одна копия. Запускается внутри python student-tests/level3.py.",
)
h2(pdf, "4.6. Failover ≤ 10 секунд")
speak(
pdf,
"Тест читает X-Instance-Id из ответа, кладёт в TARGET_INSTANCE_ID, вызывает scripts/stop-one.cmd. "
"Скрипт сверяет hostname/имя/id контейнера и docker stop -t 5. HAProxy за ~2 с (1 с × fall 2) выкидывает "
"труп из круга. Живая реплика продолжает. Сессия в Redis, сообщения в Postgres — повторный логин не нужен. "
"Измеренный recovery 2.46 с, ошибок 2 из 93. Курс просит не больше 10 с. Краткие ошибки в момент обнаружения допустимы.",
)
show(pdf, "scripts/stop-one.sh и stop-one.cmd; student-tests/failover.py; evidence/failover.txt и sequential_failover.json")
code(
pdf,
"# stop-one.sh\n"
"hostname=$(docker inspect -f '{{.Config.Hostname}}' \"$id\")\n"
"if [ \"$TARGET_INSTANCE_ID\" = \"$hostname\" ] || ...; then found=$id; fi\n"
"docker stop -t 5 \"$found\"",
)
body(
pdf,
"После первого стопа restore-api.cmd поднимает вторую реплику. Повтор failover.py бьёт уже её. "
"Отдельно в отчёте docker stop второй: пишет оставшийся api, recovery почти 0, потому что касса уже на живом. "
"Показать docker compose ps — один Exited, второй healthy.",
)
h1(pdf, "5. Оценка 4")
h2(pdf, "5.1. Health, таймауты, SIGTERM, период проверки")
speak(
pdf,
"Live — процесс существует. Ready — принимаем работу: accepting=True, SELECT 1 в Postgres, ping Redis. "
"HAProxy проверяет ready, не live: иначе труп без базы остался бы в круге. "
"Период проверок: inter 1s. Максимум обнаружения отказа: fall 2 → около 2 секунд; с DNS hold valid 2s верхняя оценка около 4 с. "
"SIGTERM: compose stop_signal SIGTERM, stop_grace_period 8s, uvicorn timeout_graceful_shutdown 5. "
"В finally lifespan accepting=False — ready и бизнес отдают 503, касса выкидывает бэкенд до убийства процесса.",
)
show(pdf, "health.py; main.py lifespan; __main__.py uvicorn; compose stop_grace_period; haproxy inter/fall")
code(
pdf,
"# health.py ready\n"
"if not request.app.state.accepting: 503\n"
"SELECT 1; redis.ping()\n"
"\n"
"# main.py finally\n"
"app.state.accepting = False\n"
"\n"
"# middleware: если not accepting и путь не /health/live → 503",
)
h2(pdf, "5.2. По очереди обе реплики, RPS, идемпотентность параллельно")
body(
pdf,
"Цифры зачитать из REPORT / sequential_failover.json, не путать с 128 RPS трека 1 — другой клиент.",
)
bullet(pdf, "stop той, что ответила: recovery 2.46 с, 91 успех / 2 ошибки, 6.07 RPS, окно 15 с.")
bullet(pdf, "restore + ещё раз: 2.74 с, 90/2, 6.00 RPS.")
bullet(pdf, "stop второй: ~0.03 с, 46/1, 3.83 RPS.")
bullet(pdf, "параллельный ключ: level3, 12 потоков, один id.")
h2(pdf, "5.3. Лимиты, секреты, нет порта API")
speak(
pdf,
"У каждого сервиса deploy.resources.limits. api 0.50 CPU / 256M каждая. Секреты Docker: postgres_password "
"только postgres, database_url — migrate и api, cache_url только api. HAProxy паролей не видит. "
"Volume только postgres_data и redis_data — у api своего диска с чатами нет.",
)
show(pdf, "compose.yaml secrets, volumes, deploy.resources, отсутствие ports у api, отсутствие container_name.")
h2(pdf, "5.4. Rolling и миграции один раз")
speak(
pdf,
"Rolling не равен failover. Failover — убили живого. Rolling — сначала подняли нового, потом стопнули старого, "
"по одной штуке, под нагрузкой. Скрипт: scale N+1, wait, docker stop -t 5 старого, rm, вернуть scale N. "
"Замер: rolling.json, 1980 ok / 24 err (1.2%), оба старых instance id исчезли. Ненулевые ошибки на стыке DNS нормальны.",
)
show(pdf, "scripts/rolling-update.sh; student-tests/rolling.py")
speak(
pdf,
"Миграции: сервис migrate, restart no, python -m app.migrate, API depends_on service_completed_successfully, "
"RUN_MIGRATIONS=0. API ждут schema_migrations. Совместимость: rolling одной версии API; схему заранее накатил migrate. "
"Не обещаем lab2 и lab3 одновременно. Ограничение честно: откат схемы не делали.",
)
show(pdf, "compose.yaml service migrate; src/app/migrate.py pg_advisory_xact_lock; main.py wait_for_schema")
h1(pdf, "6. Оценка 5 — трек 1")
h2(pdf, "6.1. Речь 2–3 минуты")
speak(
pdf,
"Трек 1 — цена масштабирования. Гипотеза: при фиксированном суммарном CPU добавление реплик не ускоряет POST, "
"потому что режется CPU каждого процесса, а не потому что кончилась база. "
"Методика: один профиль, 8 closed-loop клиентов через HAProxy, прогрев 5 с, замер 20 с. "
"Серия A: всегда 1.0 CPU и 512 MiB на все API, реплик 1, 2, 4. "
"Серия B: всегда 2 реплики, CPU растёт 0.5 → 1 → 2 суммарно. "
"A: 128 → 107 → 69 RPS. Четыре реплики на том же ватте почти вдвое медленнее одной. Ошибок 0. "
"B: 49 → 105 → 221. Дали CPU — почти линейно. Значит запас по Postgres был. "
"Улучшение: bind [::1]:8080, иначе Windows localhost давал p50 две секунды.",
)
h2(pdf, "6.2. Где цифры")
show(pdf, "REPORT.md таблица; evidence/track1.json; графики track1_fixed_budget.svg и track1_growing_cpu.svg")
bullet(pdf, "fixed-1: 1×1.00 CPU, 128.1 RPS, p50 52 мс")
bullet(pdf, "fixed-2: 2×0.50, 107.5 RPS, p50 72 мс")
bullet(pdf, "fixed-4: 4×0.25, 69.3 RPS, p50 95 мс")
bullet(pdf, "grow-2×0.25: сумма 0.50 CPU, 49.1 RPS")
bullet(pdf, "grow-2×0.50: сумма 1.00, 105.5 RPS")
bullet(pdf, "grow-2×1.00: сумма 2.00, 221.0 RPS")
body(
pdf,
"Скрипт student-tests/track1.py: scale_api, docker update --cpus/--memory, run_load 8 потоков POST /messages. "
"Closed-loop: следующий запрос только после ответа, RPS ≈ 8 / среднее время.",
)
h2(pdf, "6.3. Saturation point — как не попасть")
warn(
pdf,
"В README написано «найдите saturation point БД/LB/пула». Классического плато этих трёх НЕТ. "
"Серия B ещё растёт до 221, postgres в docker stats доли процента, пул 10+10 на реплику, при 4 репликах до 80 "
"соединений при max_connections 100, ошибок 0. Мы НЕ дожали базу до потолка. Это дырка по букве задания. "
"Закрываем её честным текстом, не выдуманным «Postgres на 100%».",
)
speak(
pdf,
"Искали насыщение Postgres, HAProxy и пула. На этом профиле они не насытились: stats пустые, при росте CPU "
"RPS ещё линейный. То, что видно: при фиксированном бюджете рост ЧИСЛА реплик перестаёт помогать и вредит — "
"это нарезка CPU API. Чтобы поймать плато базы, нужен более жёсткий профиль, его нет в evidence. "
"Это ограничение опыта, записано в конце REPORT.md.",
)
body(
pdf,
"Где «показано» в работе: абзац под таблицей в REPORT.md и массивы docker_stats в track1.json "
"(имена postgres-1, lb-1, api-*). Отрицательный результат: они не bottleneck. "
"Не ищите слайд «база 100%» — его нет.",
)
h2(pdf, "6.4. Подтверждённое улучшение")
body(
pdf,
"Задание не требует конкретно IPv6. Требует одно измеренное до/после. В отчёте взяли вход. "
"Было только 127.0.0.1:8080. Windows localhost идёт в ::1, p50 ≈ 2 с, ≈1.9 RPS. "
"Добавили [::1]:8080. После: localhost 87.6 RPS p50 75 мс, 127.0.0.1 94.7 RPS. "
"Файлы: compose.yaml ports lb; evidence/load_localhost.json. "
"Это не «серия B». Серия B — обязательный второй опыт, не фикс.",
)
h2(pdf, "6.5. Ограничения трека, которые сами назвать первым")
bullet(pdf, "Один Docker-host. Отказ VM/ноутбука не переживается.")
bullet(pdf, "Один HAProxy, одна Postgres, один Redis — SPOF.")
bullet(pdf, "Closed-loop занижает абсолютный RPS; сравнивать отношения точек, не 128 с одногруппником.")
bullet(pdf, "docker stats --no-stream — кадр в конце, не среднее; не объяснять 24% vs 0.7% как «вторая не работала».")
bullet(pdf, "Две реплики для failover, не для скорости при 1 CPU. Это разные оси.")
bullet(pdf, "Гипотеза в исходнике track1.py чуть старая про Postgres; в JSON и REPORT исправлена — читать REPORT.")
h1(pdf, "7. Живой сценарий защиты (чеклист)")
bullet(pdf, "Стенд уже up --scale api=2, ready 200.")
bullet(pdf, "docker compose ps — два api healthy без host-порта, lb 8080.")
bullet(pdf, "python student-tests/level3.py — две реплики + идемпотентность. Открыть level3.json.")
bullet(pdf, "По желанию: два curl GET /api/v1/users/me с одним Bearer — разные X-Instance-Id.")
bullet(pdf, "python student-tests/failover.py — не паниковать из-за 1–2 ошибок. Потом docker ps: один Exited.")
bullet(pdf, "scripts\\restore-api.cmd, второй failover или руками docker stop второго имени из ps.")
bullet(pdf, "Открыть REPORT таблицу трека 1 и два SVG. Произнести 128/107/69 и 49/105/221.")
bullet(pdf, "Если просят код HAProxy / идемпотентности / stop-one — разделы 4–5 этой методички.")
bullet(pdf, "Не гонять track1.py с нуля, если нет 15+ минут.")
h1(pdf, "8. Примерные вопросы и ответы")
qa(
pdf,
"Чем отказ процесса отличается от отказа узла?",
"Процесс — один контейнер api, docker stop. Второй api на том же host + общие Redis/Postgres живут. "
"Узел — вся ВМ/ноутбук/Docker Desktop: вместе падают LB, обе реплики, база. Это трек 2, мы его не заявляем.",
)
qa(
pdf,
"Почему depends_on и healthcheck — не балансировщик?",
"depends_on решает порядок СТАРТА (сначала postgres healthy, потом api). Healthcheck Compose красит контейнер "
"healthy для --wait. Трафик клиентов они не делят. Делит HAProxy: у него свой httpchk и roundrobin. "
"Без LB клиент должен был бы сам знать два IP.",
)
qa(
pdf,
"Какие POST можно повторять после timeout и что защищает Idempotency-Key?",
"Клиент не знает, записалось ли сообщение. Имеет право повторить ТОТ ЖЕ POST с ТЕМ ЖЕ ключом и тем же телом. "
"Сервер вернёт старый id. Другое тело с тем же ключом — 409, это уже другое сообщение, новый ключ. "
"Ключ обязателен только у POST сообщения. Регистрацию/чаты так не защищали.",
)
qa(
pdf,
"Что сломается, если сессии в локальной памяти, а API станет больше?",
"Round-robin отправит следующий запрос на соседний процесс — токена там нет — 401. Sticky это запрещённый костыль: "
"убили «свою» реплику — сессия всё равно умерла. Поэтому Redis.",
)
qa(
pdf,
"Зачем X-Instance-Id, если есть X-Request-Id?",
"Request-Id уникален на каждый хит даже на одном процессе. Им нельзя доказать две реплики и нельзя docker stop. "
"Instance-Id стабилен на жизнь процесса и равен hostname.",
)
qa(
pdf,
"Как HAProxy выбирает первое или второе API?",
"Счётчик round-robin + кто проходит ready. «Второе вместо первого» — следующий слот, не баг. "
"Порядок слотов из DNS, не «api-1 важнее».",
)
qa(
pdf,
"Период проверок и максимальное время обнаружения отказа?",
"inter 1s, fall 2 → типично ~2 с после 503/смерти. timeout check 1s. DNS hold valid 2s → верх ~4 с. "
"Измерили recovery 2.46 с. Бюджет курса 10 с.",
)
qa(
pdf,
"Где генерируется Idempotency-Key?",
"На клиенте. В сервере генерации нет, иначе сервер не отличит повтор от нового. Тесты: uuid4 в tests/client.py "
"и student-tests/level3.py. Человек в чате ключ не печатает.",
)
qa(
pdf,
"Почему 12 параллельных POST не делают 12 сообщений?",
"Оба API идут в одну таблицу. Замок advisory на время транзакции: второй ждёт и видит ключ первого. "
"UNIQUE на (user, method, path, key) — страховка. Тест test_concurrent_key.",
)
qa(
pdf,
"Почему публичный live отвечает HAProxy?",
"Live входа = жива ли касса. Если live отдавать API, при мёртвом LB клиент не достучится, а при живом LB и мёртвых "
"API live всё равно можно отдать с кассы. Ready специально идёт на API.",
)
qa(
pdf,
"Зачем два одинаковых контейнера, если трек 1 показал, что один быстрее?",
"Скорость при фиксированном 1 CPU и выживаемость — разные цели. Один толстый процесс быстрее на этом профиле. "
"Два нужны, чтобы docker stop одного не обнулил сервис. На защите развести оси.",
)
qa(
pdf,
"Где saturation point БД/LB/пула?",
"Не найден как плато. Stats postgres/lb ≈0%, серия grow ещё линейна до 221 RPS, пул не упёрся. "
"Нашли другое: при фиксированном CPU рост реплик вреден. Классическое насыщение склада не показали — "
"ограничение профиля 8×20с. Так и написано в REPORT.",
)
qa(
pdf,
"Почему не нулевые ошибки на failover/rolling?",
"Между SIGTERM и исключением из LB есть запросы в умирающий процесс. Курс это разрешает, если измеряли. "
"У нас единицы процентов, recovery секунды.",
)
qa(
pdf,
"Миграции на каждой реплике?",
"Нет. Отдельный one-shot migrate, API RUN_MIGRATIONS=0. Иначе гонка CREATE TABLE.",
)
qa(
pdf,
"Почему нет sticky?",
"Sticky прячет раздельное состояние. Задание прямо запрещает чинить им локальные сессии. "
"Состояние общее — прилипать незачем.",
)
qa(
pdf,
"Что будет, если убить Postgres?",
"Все api станут unready (ping БД падает), HAProxy перестанет слать бизнес-трафик, сервис ляжет. "
"Две реплики API базу не спасают. Не заявлять обратное.",
)
qa(
pdf,
"Что будет, если убить Redis?",
"Новые логины и проверка Bearer не работают (503). Старые сообщения в Postgres живы, но API без сессии их не отдаст. "
"Redis SPOF для аутентификации.",
)
qa(
pdf,
"Closed-loop / coordinated omission?",
"Клиент ждёт ответа, медленные запросы уменьшают число попыток. Для сравнения 1/2/4 одним клиентом ок. "
"Это не абсолютный потолок стенда как open-loop.",
)
qa(
pdf,
"Почему в stats одна реплика 24%, сосед 0.7%?",
"Один кадр docker stats в конце прогона, не интеграл за 20 с. Не строить на этом теорию. Смотреть RPS и лимиты.",
)
qa(
pdf,
"Зачем [::1], это же не про реплики?",
"На Windows localhost ≠ 127.0.0.1. Без IPv6-bind измерение «через localhost» врало бы ~2 с на запрос. "
"Это подтверждённое улучшение входа, без него трек 1 на localhost не про API.",
)
qa(
pdf,
"Можно ли сравнить ваш 128 RPS с чужим ноутбуком?",
"Нет. Курс: универсального проходного RPS нет. Сравнивают отношения на одной машине: 128:107:69.",
)
qa(
pdf,
"workers uvicorn больше 1?",
"workers=1. Несколько воркеров в одном контейнере — уже не наш X-Instance-Id=hostname на всех. "
"Горизонталь — отдельные контейнеры.",
)
qa(
pdf,
"Как stop-one понимает, кого убивать?",
"Тест передаёт TARGET_INSTANCE_ID = значение заголовка. Скрипт сравнивает с Hostname контейнера "
"(мы как раз кладём hostname в заголовок).",
)
qa(
pdf,
"Rolling под нагрузкой зачем, если есть failover?",
"Обновление образа без «выключить всех». Сначала лишний здоровый, потом убрать старого. Иначе дыра на время сборки.",
)
qa(
pdf,
"Совместимы ли миграции с работающей версией?",
"Additive: новая таблица ключей. Rolling гоняет одну версию API после migrate. Не заявляем blue-green двух схем.",
)
qa(
pdf,
"Почему Postgres слушает 5433 на хосте, это же дырка?",
"Учебный отладочный bind на 127.0.0.1, не публикация API. Снаружи интернет не торчит. Можно признать упрощением.",
)
qa(
pdf,
"Аргон2 и lab2?",
"Пароли как в lab2, Basic только на создание сессии, дальше Bearer. Это не тема lab3, но контракт сохранён.",
)
qa(
pdf,
"Что в PR / отчёте ещё TODO?",
"В REPORT строка Commit/PR: TODO после публикации. Если PR не открыт — сказать как есть, не выдумывать номер.",
)
h1(pdf, "9. Мини-шпаргалка чисел")
bullet(pdf, "Реплики: 2. Вход: 8080. Ready LB: 1 с, fall 2, обнаружение ~2 с (верх ~4 с). Failover recovery ~2.5 с.")
bullet(pdf, "Grace: stop -t 5, uvicorn 5, compose 8 с.")
bullet(pdf, "TTL сессии 3600, ключа идемпотентности 86400.")
bullet(pdf, "Лимит api: 0.50 CPU / 256M. Трек1 fixed сумма всегда 1 CPU / 512M.")
bullet(pdf, "Трек1 RPS: 128 / 107 / 69 и 49 / 105 / 221. Ошибки 0.")
bullet(pdf, "IPv6 фикс: ~1.9 RPS → ~88 RPS на localhost.")
bullet(pdf, "Гонка: 12 POST, 1 message id. Rolling: ~1.2% ошибок.")
h1(pdf, "10. Если что-то пойдёт не так на защите")
bullet(pdf, "Стенд не ready: docker compose ps, логи docker compose logs api --tail 80, часто migrate не прошёл или Docker Desktop спал.")
bullet(pdf, "Один instance id: реплика одна — compose up --scale api=2; или смотрите live вместо /users/me.")
bullet(pdf, "localhost тупит, 127.0.0.1 быстрый: проверяйте, что в compose есть [::1]:8080 и контейнер lb пересоздан.")
bullet(pdf, "failover не находит TARGET: instance id должен совпасть с hostname (inspect). Не сравнивать с load-balancer.")
bullet(pdf, "Не лезьте чинить публичные tests/ и contracts/ на глазах — это запрещено курсом.")
pdf.ln(4)
body(
pdf,
"Конец методички. Источник цифр: REPORT.md и evidence/ на дату 2026-10-30. Если перегоните тесты — замените числа, "
"не зубрите старые. Код открывать из репозитория, не из памяти.",
)
pdf.output(str(OUT))
print("wrote", OUT)
if __name__ == "__main__":
build()