forked from mtusi2026/mtusi2026lab3
docs: DEFENSE и WINDOWS под lab3, модель данных, CI, сбор доказательств
- DEFENSE: что изменилось с lab2, путь POST с ключом, ответы на вопросы README, ловушки из чужих PR, периоды проверок и время обнаружения. - WINDOWS: запуск на ноутбуке, make из PowerShell (нужен sh из Git), сценарий защиты по шагам README. - DATA_MODEL: idempotency_keys и функция post_message. - CI: test-failover с восстановлением, свои тесты. - scripts/collect_evidence.py: все проверки на чистом clone -> evidence/. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
8964c9b554
commit
55210c6e9c
@@ -1,11 +1,11 @@
|
||||
name: Application (lab2)
|
||||
name: Application (lab3)
|
||||
on: [push, pull_request]
|
||||
permissions:
|
||||
contents: read
|
||||
jobs:
|
||||
app:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 30
|
||||
timeout-minutes: 40
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-python@v5
|
||||
@@ -13,20 +13,24 @@ jobs:
|
||||
python-version: '3.13'
|
||||
- name: Synthetic secrets and env (CI only, never committed)
|
||||
run: python scripts/init_secrets.py && cp .env.example .env
|
||||
- name: Build, migrate, start and wait for healthy services
|
||||
- name: Build, migrate once, start 2 API replicas behind HAProxy, wait for healthy
|
||||
run: docker compose --env-file .env up -d --build --wait
|
||||
- name: Contract and public smoke
|
||||
run: make check test PYTHON=python
|
||||
- name: Persistence across restart of API and stores
|
||||
- name: Persistence across restart of LB, API replicas and stores
|
||||
run: make test-persistence ACTION_SCRIPT=scripts/restart.sh PYTHON=python
|
||||
- name: Own tests (unit + stand, failures restored in finally)
|
||||
- name: Failover of the replica that served the test, then restore it
|
||||
run: |
|
||||
make test-failover ACTION_SCRIPT=scripts/stop-one.sh PYTHON=python
|
||||
sh scripts/restore-api.sh && python scripts/lbctl.py wait-up 2
|
||||
- name: Own tests (unit + stand; every failure is restored in finally)
|
||||
run: |
|
||||
python -m pip install --require-hashes --no-deps -r requirements.txt
|
||||
python -m pip install -r requirements-test.txt
|
||||
make student-test PYTHON=python
|
||||
- name: Logs
|
||||
if: always()
|
||||
run: docker compose logs --tail 100
|
||||
run: docker compose logs --tail 100 api lb
|
||||
- name: Remove CI stand and its synthetic data
|
||||
if: always()
|
||||
run: docker compose down -v
|
||||
|
||||
+5
-3
@@ -1,6 +1,6 @@
|
||||
# Модель данных lab2
|
||||
# Модель данных lab3
|
||||
|
||||
Схема: [migrations/0001_init.sql](../migrations/0001_init.sql). Источник истины для пользователей, чатов, участников и сообщений — PostgreSQL 18. Для сессий источник истины — хранилище, выбранное через `SESSION_STORE`. По умолчанию это Valkey с AOF, его можно переключить на таблицу `sessions` в PostgreSQL.
|
||||
Схема: [0001_init.sql](../migrations/0001_init.sql) (lab2), [0002_idempotency_keys.sql](../migrations/0002_idempotency_keys.sql) и [0003_post_message_function.sql](../migrations/0003_post_message_function.sql) (lab3). Миграции применяет один раз отдельный сервис `migrate` до старта реплик API; обе миграции lab3 только добавляют объекты, поэтому совместимы с работающей предыдущей версией (rolling update). Источник истины для пользователей, чатов, участников и сообщений — PostgreSQL 18. Для сессий источник истины — хранилище, выбранное через `SESSION_STORE`. По умолчанию это Valkey с AOF, его можно переключить на таблицу `sessions` в PostgreSQL.
|
||||
|
||||
## Таблицы и ограничения
|
||||
|
||||
@@ -11,6 +11,7 @@
|
||||
| `chat_members` | `(chat_id, user_id)` | FK на `chats` и `users`, `UNIQUE (chat_id, position)` | `position` хранит порядок `member_ids`; `chat_created_at` — копия времени чата для keyset-списка чатов |
|
||||
| `messages` | `id uuid` | FK `(chat_id, sender_id) → chat_members`, длина `text` | отправитель обязан быть участником — это гарантирует сама БД |
|
||||
| `sessions` | `token_hash bytea` | FK `user_id → users`, длина хеша 32 байта | хранится SHA-256 токена; сам токен не хранится нигде |
|
||||
| `idempotency_keys` | `(user_id, chat_id, key)` | FK на `users`, `chats`; `message_id → messages` (DEFERRABLE, `UNIQUE`); `CHECK` формата ключа и длины SHA-256 | общая для всех реплик идемпотентность отправки: ключ → отпечаток тела → сообщение. Хранится ≥ `IDEMPOTENCY_TTL_SECONDS` (24 ч), очистка — пачками раз в 10 мин под advisory-замком |
|
||||
| `schema_migrations` | `version` | checksum файла | какие миграции применены; изменённую задним числом миграцию мигратор не применит |
|
||||
|
||||
**Почему `bytea` для текста.** Контракт разрешает символ U+0000, а тип `text` в PostgreSQL не может содержать байт NUL (`DataError`). Поэтому `display_name`, `title` и `text` хранятся как байты UTF-8. Длину в code points проверяет API, а `CHECK` в байтах — страховка (1 code point ≤ 4 байта).
|
||||
@@ -28,7 +29,8 @@
|
||||
| --- | --- | --- |
|
||||
| Регистрация | один `INSERT` | `UniqueViolation` → 409; ровно одна строка при гонке |
|
||||
| Создание чата | `INSERT chats` → `INSERT chat_members` (все участники одним запросом) → `COMMIT` | неизвестный участник вызывает FK-ошибку **после** вставки чата; откат удаляет и чат, и частичное членство |
|
||||
| Сообщение | проверка членства → `UPDATE chats SET last_message_at = greatest(clock_timestamp(), last_message_at + 1 мкс) RETURNING` → `INSERT messages` → `COMMIT` | строка чата заблокирована до конца транзакции, поэтому писатели одного чата идут по очереди. Время сообщений строго растёт **в порядке коммитов**: страница по cursor не пропустит сообщение, закоммиченное «задним числом» |
|
||||
| Сообщение (lab3, с ключом) | проверка членства → `INSERT idempotency_keys … ON CONFLICT DO UPDATE … WHERE ключ старше 24 ч` → если вставлен: `UPDATE chats … RETURNING` → `INSERT messages`; если нет: прочитать сохранённое сообщение и сравнить отпечаток → `COMMIT`. По умолчанию всё это — одна SQL-функция `post_message` в autocommit (одно обращение к БД) | ключ, сообщение и «результат» коммитятся вместе или не коммитятся вовсе: «висящего» ключа нет. Конкурентный повтор ждёт на уникальном индексе завершения первой транзакции и затем видит её результат (READ COMMITTED, новый снимок на каждый оператор). Другое тело → 409, тот же — тот же Message |
|
||||
| Сообщение (lab2-часть) | проверка членства → `UPDATE chats SET last_message_at = greatest(clock_timestamp(), last_message_at + 1 мкс) RETURNING` → `INSERT messages` → `COMMIT` | строка чата заблокирована до конца транзакции, поэтому писатели одного чата идут по очереди. Время сообщений строго растёт **в порядке коммитов**: страница по cursor не пропустит сообщение, закоммиченное «задним числом» |
|
||||
| Вход | `SELECT` пользователя, проверка Argon2id, запись сессии | неверный пароль ничего не пишет |
|
||||
| Logout | `DELETE` сессии (или `DEL` в Valkey) | повтор с тем же токеном — 401 |
|
||||
|
||||
|
||||
+83
-63
@@ -1,83 +1,103 @@
|
||||
# Шпаргалка к защите ЛР 2
|
||||
# Шпаргалка к защите ЛР 3
|
||||
|
||||
Отчёт с доказательствами — [REPORT.md](../REPORT.md), модель данных — [DATA_MODEL.md](DATA_MODEL.md).
|
||||
Отчёт с доказательствами — [REPORT.md](../REPORT.md), команды на ноутбуке — [WINDOWS.md](WINDOWS.md), модель данных — [DATA_MODEL.md](DATA_MODEL.md).
|
||||
|
||||
## Что изменилось по сравнению с lab1
|
||||
## Что изменилось по сравнению с lab2
|
||||
|
||||
| Было в lab1 | Стало в lab2 | Где |
|
||||
| Было в lab2 | Стало в lab3 | Где |
|
||||
| --- | --- | --- |
|
||||
| словари в памяти (`store.py`) | PostgreSQL 18, данные переживают рестарт | [repo.py](../src/messenger/repo.py), [migrations/0001_init.sql](../migrations/0001_init.sql) |
|
||||
| `X-User-Id` | вход по `Basic` → opaque `Bearer` с expiry, logout | [authhdr.py](../src/messenger/authhdr.py), [sessions.py](../src/messenger/sessions.py), [app.py](../src/messenger/app.py) |
|
||||
| нет паролей | Argon2id (m=19 MiB, t=2, p=1) в отдельном потоке | [passwords.py](../src/messenger/passwords.py) |
|
||||
| `threading.Lock` + свой счётчик времени | блокировка строки чата `UPDATE chats … RETURNING` в транзакции | `add_message` в repo.py |
|
||||
| `bisect` по списку | индекс `(chat_id, created_at, id)` и row-comparison в `Index Cond` | `HISTORY_AFTER` в repo.py |
|
||||
| один контейнер | `compose.yaml`: postgres, valkey, migrate, api; secrets-файлы; named volumes | [compose.yaml](../compose.yaml) |
|
||||
| один контейнер `api`, порт 8080 наружу | сервис `api` × N (`deploy.replicas`, без `ports` и `container_name`), вход только через HAProxy | [compose.yaml](../compose.yaml), [haproxy.cfg](../infra/haproxy/haproxy.cfg) |
|
||||
| — | `X-Instance-Id` = hostname контейнера (короткий container ID) на **каждом** ответе, включая 500/503 | `RequestContextMiddleware` в [app.py](../src/messenger/app.py) |
|
||||
| POST сообщения без ключа | `Idempotency-Key` обязателен; ключ, сообщение и результат — одна транзакция | [repo.py](../src/messenger/repo.py), [0002](../migrations/0002_idempotency_keys.sql), [0003](../migrations/0003_post_message_function.sql) |
|
||||
| SIGTERM → сразу закрыть сокет | SIGTERM → readiness 503 и 3 с drain (запросы ещё обслуживаются) → graceful stop | [__main__.py](../src/messenger/__main__.py) |
|
||||
| миграции — сервис `migrate` | так же один раз до старта реплик; реплики сами не мигрируют | `migrate` в compose.yaml |
|
||||
| одна сеть | `edge` (lb↔api) и internal `data` (api/migrate↔postgres/valkey) | compose.yaml |
|
||||
| дедлайн БД отменял задачу psycopg | задача не отменяется (cancel в libpq блокировал event loop), мёртвые сокеты рвёт `tcp_user_timeout` | [db.py](../src/messenger/db.py) |
|
||||
|
||||
Что осталось из lab1: формат ошибок и `X-Request-Id`, строгая валидация, cursor (теперь с проверкой диапазона времени), JSON-логи, graceful SIGTERM, healthcheck, Swagger на `/docs`.
|
||||
Осталось из lab2: сессии только в Valkey (AOF `always`), Argon2id, cursor с привязкой к ресурсу, строгая валидация, `bytea` для текста с U+0000, дедлайны БД/Valkey, 503 вместо 401 при отказе хранилищ.
|
||||
|
||||
## Путь запроса `GET /chats/{id}/messages?cursor=…` в lab2
|
||||
## Схема
|
||||
|
||||
1. `parse_bearer`: в заголовке ровно `Bearer <43 символа>`, иначе 401 с `WWW-Authenticate: Bearer`.
|
||||
2. `sessions.user_id_for`: в Valkey ключ `session:<sha256(token)>`, проверка `expires_at`. Valkey недоступен — 503, нет ключа — 401.
|
||||
3. `path_uuid` → 400; `ensure_member` (`SELECT 1 FROM chat_members …`) → 404 для чужого чата.
|
||||
4. `cursor.decode` → `(время в мкс, id)`, привязка к чату → иначе 400.
|
||||
5. `HISTORY_AFTER`: `WHERE chat_id=$1 AND (created_at, id) > ($2,$3) ORDER BY … LIMIT 51` — индекс начинает чтение прямо с cursor.
|
||||
6. Каждая работа с БД — `db.run(...)`: отдельная задача, транзакция, дедлайн 3 с. Отказ или зависание БД → 503 ровно через дедлайн.
|
||||
```
|
||||
клиент ──127.0.0.1:8080──▶ HAProxy (lb) ──edge──▶ api-1, api-2 … (Starlette/uvicorn, без состояния)
|
||||
│ check GET /health/ready каждую 1 с │
|
||||
│ fall 2 / rise 2, Docker DNS каждые 1 с └──data──▶ PostgreSQL 18 (источник истины)
|
||||
└─ свои 502/503/504 в формате ошибки контракта Valkey 8 (сессии, AOF always)
|
||||
```
|
||||
|
||||
## Путь `POST /chats/{id}/messages` с `Idempotency-Key`
|
||||
|
||||
1. HAProxy: ставит `X-Request-Id` (если у клиента нет валидного), выбирает следующую `UP`-реплику (roundrobin).
|
||||
2. API: `parse_bearer` → Valkey `session:<sha256>` (общий для всех реплик) → 401/503.
|
||||
3. UUID чата → 400. Посторонний → **404 всегда**, даже при повторе чужого ключа (членство проверяется до ключа).
|
||||
4. Ключ `[A-Za-z0-9._:-]{1,128}` и ровно один заголовок → иначе 400. Тело: строгий JSON (дубли ключей, лишние поля — 400), `attachment_ids: []` = отсутствие поля.
|
||||
5. Отпечаток тела = SHA-256 канонического JSON (`sort_keys`, `attachment_ids` по умолчанию `[]`).
|
||||
6. Запись — **одна транзакция** (функция `post_message`, миграция 0003, или прежний многооператорный путь `MESSAGE_WRITE_PATH=multi`):
|
||||
- `INSERT INTO idempotency_keys … ON CONFLICT DO UPDATE … WHERE ключ старше 24 ч`;
|
||||
- вставили ключ → `UPDATE chats` (часы чата под блокировкой строки) → `INSERT messages` → `created`;
|
||||
- не вставили → ключ уже есть: тот же отпечаток → **тот же Message, 201** (`replayed`), другой → **409**.
|
||||
7. Конкурентный повтор с тем же ключом через другую реплику ждёт на уникальном индексе, пока первая транзакция не завершится: после COMMIT он видит результат, после ROLLBACK вставляет сам. Отдельного «pending»-состояния нет, поэтому сбой не оставляет «висящий» ключ (это был главный блокер у других).
|
||||
|
||||
## Вопросы из README
|
||||
|
||||
**Что подтверждает COMMIT и какие гарантии зависят от настройки durability?**
|
||||
COMMIT возвращается клиенту, когда запись транзакции в WAL сброшена на диск (`fsync=on`, `synchronous_commit=on`, это значения по умолчанию). Транзакция переживёт падение процесса PostgreSQL или ОС: при старте PostgreSQL проиграет WAL. От настроек зависит:
|
||||
- `synchronous_commit=off` — ответ приходит раньше сброса, и последние ~0,6 с подтверждённых транзакций могут пропасть (база при этом останется целой);
|
||||
- `fsync=off` — после сбоя возможна порча данных;
|
||||
- кэш записи диска, который «врёт» о сбросе, ломает и то, и другое.
|
||||
**Чем отказ процесса отличается от отказа узла?**
|
||||
- **Процесс** (у нас — API-реплика): остальные процессы, сеть, диск и Docker живы. Его можно перезапустить рядом, а LB перестаёт слать на него запросы: соединение отклонено → HAProxy сразу повторяет на другой (`retry-on conn-failure` + `redispatch`), readiness не отвечает → через ≈ 1,5–3,5 с `DOWN`. Данные в PostgreSQL/Valkey не страдают.
|
||||
- **Узел** (хост/VM): пропадает всё, что на нём: все реплики, LB, БД, volumes и сам Docker. Пережить это можно только если копии каждого нужного компонента живут на **других** узлах: реплики API, второй LB (VIP/DNS), реплицированная БД с переключением, хранилище не на этом диске.
|
||||
- У нас один Docker-host: стенд выдерживает отказ **одной API-реплики** (доказано `make test-failover` и серией в REPORT), но не отказ узла. LB, PostgreSQL и Valkey — единичные точки отказа (SPOF), это записано в ограничениях.
|
||||
|
||||
COMMIT на одном узле не защищает от потери самого диска или хоста: для этого нужны реплики (`synchronous_standby_names`) или резервные копии с архивом WAL (трек 2).
|
||||
**Почему `depends_on`/`healthcheck` сами по себе не являются балансировщиком?**
|
||||
- `depends_on` действует **только при старте**: в каком порядке запускать и чего ждать. После запуска он ничего не делает.
|
||||
- `healthcheck` Docker только **помечает** контейнер `unhealthy`. Трафик он не перенаправляет и контейнер не перезапускает (в Compose без Swarm). Пометка появляется через `interval × retries`.
|
||||
- Распределение запросов, исключение неготовой реплики и повтор на другую — работа LB. У нас HAProxy сам опрашивает `/health/ready` каждую секунду и не шлёт бизнес-запросы реплике, которая жива (`/health/live` 200), но не готова (нет БД или Valkey, идёт drain). Проверено тестом: у одной реплики отнят PostgreSQL (`pg_hba reject`) или вся сеть `data` (`docker network disconnect`) — через 3–4 с ни одного запроса к ней, вторая обслуживает всё (`test_lb_stops_routing_to_a_replica_that_is_alive_but_not_ready`). Резервных серверов «без проверки» нет.
|
||||
|
||||
У Valkey свой аналог — `appendfsync`:
|
||||
- у нас `always`: fsync до ответа, ничего не теряется;
|
||||
- `everysec`: можно потерять до 1 с записей;
|
||||
- `no`: когда сбросить на диск, решает ОС.
|
||||
**Какие POST можно повторять после timeout и что защищает `Idempotency-Key`?**
|
||||
- Timeout = **неизвестный исход**: запрос мог не дойти, мог выполниться без ответа, мог выполниться и ответ потерялся.
|
||||
- Повторять без вреда можно то, что идемпотентно: **отправку сообщения с тем же ключом и тем же телом**. Сервер вернёт исходный 201 и тот же Message, дубля не будет. Это проверено и для повтора через другую реплику, и для 24 одновременных повторов, и для случая, когда клиент сдался через 0,4 с, а сервер закоммитил позже.
|
||||
- Регистрацию, создание чата, вход повторять «прозрачно» нельзя: без ключа сервер не отличит повтор от нового запроса (второй чат, `409` на username). Поэтому HAProxy повторяет **только** запросы, которые не были отправлены на реплику (`retry-on conn-failure`); всё, что могло дойти до API, повторяет клиент сам и осознанно.
|
||||
- Ключ защищает от **дубля при повторе**, но не от другого тела с тем же ключом (409), не от чужого пользователя (у каждого своя область ключей) и не делает запрос «успешным»: временная 5xx не сохраняется как результат, повтор может снова получить 503.
|
||||
- Область ключа: пользователь + метод + путь чата + ключ; результат хранится ≥ 24 ч (`IDEMPOTENCY_TTL_SECONDS`, меньше 86 400 нельзя).
|
||||
|
||||
**Где хранятся сессии и что будет после flush/restart Redis (Valkey)?**
|
||||
По умолчанию (`SESSION_STORE=valkey`) сессия существует **только** в Valkey: ключ `session:<sha256>`, значение `{user_id, expires_at}` и абсолютный срок `PXAT`.
|
||||
- **Restart:** Valkey перечитывает AOF с volume, сессии на месте (тест `make test-persistence`). TTL не продлевается.
|
||||
- **FLUSHALL** или потеря volume: все сессии исчезают, все пользователи получают 401 и входят заново. Отказ безопасный: доступ не выдаётся никому.
|
||||
- **Valkey недоступен:** 503 на защищённые запросы и на logout. Анонимный доступ не открывается.
|
||||
|
||||
Почему не кэш над PostgreSQL: у одной копии нечему расходиться. У студентов с кэшем отозванный токен «оживал» после восстановления Redis, у нас такой ситуации быть не может (тест `test_logout_during_valkey_outage_is_never_lost`). Альтернатива `SESSION_STORE=postgres` хранит сессии в таблице `sessions`.
|
||||
|
||||
**Чем аутентификация отличается от доступа к конкретному чату?**
|
||||
- **Аутентификация** — кто ты: действительная Bearer-сессия → `user_id`. Нет или недействительна → 401.
|
||||
- **Авторизация доступа** — можно ли этому пользователю этот чат: есть ли строка в `chat_members`. Нет → 404, а не 403, чтобы не раскрывать существование чужого чата.
|
||||
|
||||
Сначала всегда аутентификация, потом доступ. Отправитель сообщения берётся из сессии, а БД сама проверяет `FOREIGN KEY (chat_id, sender_id) → chat_members`.
|
||||
|
||||
**Почему hash пароля и быстрый checksum имеют разные задачи?**
|
||||
- **Checksum или быстрый хеш (SHA-256)** — контроль целостности и быстрый поиск. Он должен быть быстрым.
|
||||
- **Хеш пароля** — защита низкоэнтропийного секрета на случай утечки базы. Он должен быть медленным, с солью и memory-hard (Argon2id), чтобы перебор словаря стоил дорого и не ускорялся на GPU.
|
||||
|
||||
Токен сессии — 256 бит случайности, перебрать его невозможно. Поэтому для токена хватает SHA-256: храним хеш, чтобы утечка базы не дала готовых токенов. Для пароля SHA-256 нельзя: миллиарды попыток в секунду на GPU.
|
||||
**Что сломается при увеличении числа API, если сессии находятся в локальной памяти?**
|
||||
- Вход на реплике A, следующий запрос на B → B сессии не знает → **401**: пользователь «разлогинивается» через раз (у нас запросы одного токена идут по очереди на все реплики, это проверяет тест).
|
||||
- Logout на A не отзывает токен на B → отозванный токен продолжает работать (нарушение контракта и безопасности).
|
||||
- Рестарт или rolling update реплики теряет все её сессии.
|
||||
- Попытка «починить» это sticky-сессиями маскирует проблему: при отказе реплики её пользователи всё равно теряют сессии, а нагрузка распределяется неравномерно. README это запрещает.
|
||||
- То же касается любой локальной корректностно-важной памяти: кэш истории без инвалидации, локальная идемпотентность (две реплики вставили бы два сообщения), локальные счётчики. У нас в процессе API нет ничего, кроме пула соединений.
|
||||
|
||||
## Частые ловушки (на чём преподаватель ловил других) и наш ответ
|
||||
|
||||
| Проверка преподавателя | У нас | Тест |
|
||||
| --- | --- | --- |
|
||||
| logout при упавшем Redis → после восстановления токен снова 200 | logout при упавшем Valkey = 503 (ничего не отозвано); после восстановления logout → 401, и после рестарта Valkey и API тоже 401 | `test_logout_during_valkey_outage_is_never_lost` |
|
||||
| истёкшая сессия живёт в кэше | expiry проверяется при каждом чтении, ключ живёт до абсолютного `PXAT` | `test_short_ttl_expires[valkey/postgres]` |
|
||||
| `docker pause postgres` → запрос висит 8+ с | клиентский дедлайн в отдельной задаче: 503 через 3,0 с | `test_postgres_failure[pause]` |
|
||||
| БД упала → 401 вместо 503 | 503 `unavailable`, анонимный — 401 | `test_postgres_failure`, `test_postgres_session_store` |
|
||||
| cursor в `Filter` при generic plan | два запроса без `IS NULL OR`, cursor в `Index Cond` | `test_explain.py`, `evidence/explain-history.txt` |
|
||||
| `\u0000` → 500 | текст в `bytea`, NUL сохраняется | `test_unicode_limits_are_code_points_and_nul_is_stored` |
|
||||
| пароль из пробелов, `Basic é` → 500 | 400 и 401 | `test_bad_password_on_registration_is_400`, `test_malformed_basic_is_401_not_500` |
|
||||
| гонка регистрации считает любые ошибки за 409 | проверяются коды: ровно `[201] + [409]*7`, в БД 1 строка | `test_registration_race_exactly_one_201_and_seven_409` |
|
||||
| rollback «до первого INSERT» | чат вставляется первым, FK участника падает после; `n_tup_ins` вырос, строк нет | `test_create_chat_rolls_back_after_the_chat_row_was_inserted` |
|
||||
| `SESSION_TTL_SECONDS` не доходит до контейнера | compose передаёт его из `.env`, тест читает `printenv` внутри контейнера | `test_short_ttl_expires` |
|
||||
| нет команды создания secrets | `python scripts/init_secrets.py` (идемпотентно) | раздел «Запуск из чистого clone» |
|
||||
| после сбоя ключ остаётся «pending», повтор висит/504/409 | ключ и сообщение в одной транзакции, сбой после первого INSERT → нет ни ключа, ни сообщения, повтор → 201 | `test_failure_after_the_key_insert_rolls_everything_back` |
|
||||
| одновременные повторы: 19×201 + 1×409 | 24 запроса через ≥ 2 реплики → 24×201, одно тело, одна строка в БД; три раунда | `test_concurrent_same_key_through_different_replicas_creates_exactly_one` |
|
||||
| посторонний: 404, потом 409 | членство проверяется до ключа: всегда 404 | `test_outsider_and_revoked_session_never_see_the_stored_result` |
|
||||
| `X-Instance-Id: unknown` / нет на 500 и 413 | hostname контейнера, middleware на всех ответах | `test_every_api_response_carries_instance_and_request_id`, `Api.call` проверяет на каждом ответе |
|
||||
| LB шлёт запросы неготовой реплике (pg отнят, сеть отключена, пул забит) | активная проверка `/health/ready`, без backup-слотов | `test_lb_stops_routing_…[pg_hba/network]` |
|
||||
| после общего restart LB видит одну реплику | HAProxy re-resolve Docker DNS каждую 1 с | `test_full_restart_lb_rediscovers_all_replicas` |
|
||||
| «rolling update» останавливает обе API | +1 новая реплика (healthy и UP), затем graceful stop старой | `bench/rolling_under_load.py`: 0 ошибок |
|
||||
| миграции в каждой API | только сервис `migrate`, API логов миграции нет | `test_migrations_ran_once_by_the_migrate_service` |
|
||||
| нет лимитов у LB/migrate/PG/Redis | лимиты у всех 5 сервисов, проверка и config, и реальных контейнеров | `test_compose_policy_…`, `test_running_containers_…` |
|
||||
| cursor с `[]`, `{}`, числом, `null`, пустой, пробел → 500/200 | 400 на обоих списках | `test_malformed_cursor_values_are_400_on_both_lists` |
|
||||
| `attachment_ids: []` при повторе → 400 | равно отсутствию поля, тот же 201 | `test_key_order_and_missing_attachment_ids_are_the_same_body` |
|
||||
| `{"text":"a","TEXT":"b"}`, байт FF, `Bearer é`, UUID в разном регистре, тело при входе | 400 / 400 / 401 / 400 / 400 | `test_api.py`, раздел lab 3 |
|
||||
|
||||
## Трек 2 — коротко
|
||||
## Обнаружение отказа: периоды и максимумы
|
||||
|
||||
- **Гипотеза.** С индексом `(chat_id, created_at, id)` и keyset-запросом стоимость страницы не зависит от размера чата и позиции. С индексом только по `chat_id` нужна сортировка всего чата, с OFFSET — чтение всего префикса. Каждый индекс удорожает запись.
|
||||
- **Методика.** Отдельный PostgreSQL (2 CPU / 2 GiB), 121 120 сообщений, чаты 60 000 / 15 000 / 2 000 / 80. pgbench с prepared statements; генератор нагрузки — в своём контейнере. 3 повтора. Плюс EXPLAIN для поздней страницы.
|
||||
- **Backup.** `pg_dump -Fc` живой БД во время записи через API → новый контейнер и новый volume → `pg_restore` → сверка MD5 по каждому чату и по первым/последним сообщениям → наше же API на восстановленной БД читает чат после нового входа.
|
||||
- **RPO и RTO.** `pg_dump` — снимок на момент старта. Всё подтверждённое после старта дампа в копию не попадает; это и есть граница потери данных (на практике — время с последнего дампа). RTO — время `pg_restore` с перестройкой индексов плюс переключение приложения. Чтобы уменьшить RPO до секунд, нужен архив WAL и PITR или реплика.
|
||||
| Что | Настройка | Максимум |
|
||||
| --- | --- | --- |
|
||||
| проверка HAProxy | `inter 1s`, `fastinter 500ms`, `fall 2`, `rise 2`, `timeout check 1s` | — |
|
||||
| реплика ответила 503 на ready (drain, нет БД) | 1 с до проверки + 0,5 с + ответ ≤ 1 с | ≈ 3,5 с (измерено 3,2–4,1 с) |
|
||||
| процесс убит (SIGKILL) / порт закрыт | следующий запрос получает отказ соединения → повтор на другую реплику в HAProxy | новые запросы — сразу; рвутся только запросы «в полёте» (3 за 0,17 с в серии) |
|
||||
| процесс заморожен (`docker pause`) | соединения висят до `timeout check` | ≈ 3,5 с до `DOWN`; запросы, попавшие на него раньше, ждут клиентский таймаут |
|
||||
| DNS: новая/пропавшая реплика | `hold valid 1s` | ≈ 1–2 с |
|
||||
| graceful stop | readiness 503 сразу, 3 с drain, ≤ 8 с на запросы «в полёте», `stop_grace_period` 15 с | 0 ошибок (серия, тесты) |
|
||||
|
||||
## Трек 1 — коротко
|
||||
|
||||
Числа и графики — в REPORT.md и [evidence/track1/summary.md](../evidence/track1/summary.md).
|
||||
|
||||
- **Методика.** k6 в отдельном контейнере в сети `edge` (как внешний клиент, без проброса портов Windows), open-loop `constant-arrival-rate`, только `201` считаются успехом, `dropped_iterations` — неудовлетворённый спрос. Ступени нагрузки, прогрев 10 с + замер 20 с. На каждую конфигурацию и повтор — **свежий стенд** с пустой БД, образ API собирается из конкретного коммита. CPU закреплены `cpuset`: k6 0–1, LB+Valkey 2, PostgreSQL 3–4, API 5–7. Три повтора.
|
||||
- **Фиксированный суммарный CPU (2,0):** 1 × 2,0 упирается в одно ядро — один процесс Python исполняет байткод одним потоком (GIL), второе ядро почти простаивает. 2 × 1,0 и 4 × 0,5 используют весь бюджет; дальнейшее дробление не добавляет производительности, только накладные расходы.
|
||||
- **Рост ресурсов:** реплики помогают, пока не упрёмся в общий ресурс. С БД 0,5 CPU потолок перестаёт расти после 2 реплик — CPU PostgreSQL у предела; добавление CPU БД поднимает потолок, значит, узкое место — БД. LB при этом занят на десятки процентов одного ядра.
|
||||
- **Где тратится CPU API:** py-spy показал ~57 % времени реплики в драйвере psycopg — накладные расходы на каждый оператор (около 11 обращений к БД на одно сообщение).
|
||||
- **Улучшение:** вся идемпотентная запись — один вызов SQL-функции `post_message` (миграция 0003) в autocommit. Семантика та же (те же тесты проходят в обоих режимах), A/B на одном образе через `MESSAGE_WRITE_PATH=multi|function`.
|
||||
|
||||
+67
-63
@@ -1,134 +1,138 @@
|
||||
# Запуск на ноутбуке с Windows и сценарий защиты
|
||||
# Запуск на ноутбуке с Windows и сценарий защиты ЛР 3
|
||||
|
||||
Все команды — в **PowerShell**, из папки проекта. Внутри одного окна PowerShell переменные `$env:...` действуют до его закрытия.
|
||||
Команды — в **PowerShell** из папки проекта (где лежит `compose.yaml`). Переменные `$env:...` действуют до закрытия окна.
|
||||
|
||||
## 1. Что установить один раз
|
||||
|
||||
| Программа | Зачем | Важно |
|
||||
| --- | --- | --- |
|
||||
| [Git for Windows](https://git-scm.com/download/win) | clone и Git Bash | ставить в путь по умолчанию `C:\Program Files\Git`: оттуда `scripts\restart.cmd` запускает `restart.sh` |
|
||||
| [Docker Desktop](https://www.docker.com/products/docker-desktop/) | PostgreSQL, Valkey, API | backend WSL 2; в BIOS включена виртуализация; после установки перезагрузка |
|
||||
| [Python 3.12+](https://www.python.org/downloads/windows/) | secrets, публичные тесты, свои тесты | галочка **Add python.exe to PATH**. Если `python` открывает Microsoft Store — отключить «Псевдонимы выполнения приложений» для python в настройках Windows |
|
||||
| [Git for Windows](https://git-scm.com/download/win) | clone и Git Bash | путь по умолчанию `C:\Program Files\Git`: оттуда `scripts\*.cmd` запускают `.sh`-хуки |
|
||||
| [Docker Desktop](https://www.docker.com/products/docker-desktop/) | PostgreSQL, Valkey, HAProxy, API | backend WSL 2, виртуализация в BIOS; для трека 1 в Settings → Resources дать **8 CPU** |
|
||||
| [Python 3.12+](https://www.python.org/downloads/windows/) | secrets, публичные и свои тесты, скрипты замеров | галочка **Add python.exe to PATH** |
|
||||
| GNU make (необязательно) | `make check/test/test-failover …` | `winget install ezwinports.make`, затем **новое** окно PowerShell. Рецептам Makefile нужен `sh`: в каждом окне PowerShell один раз `$env:Path += ";C:\Program Files\Git\usr\bin"` (или запускать make из Git Bash). Без make те же команды есть в таблице REPORT.md |
|
||||
|
||||
Проверка:
|
||||
|
||||
```powershell
|
||||
git --version; docker version --format '{{.Server.Version}}'; docker compose version; python --version
|
||||
git --version; docker version --format '{{.Server.Version}}'; docker compose version; python --version; make --version
|
||||
```
|
||||
|
||||
Docker Desktop должен быть **запущен** (кит в трее не мигает).
|
||||
|
||||
## 2. Развернуть проект (дома, заранее — нужен интернет)
|
||||
|
||||
```powershell
|
||||
git clone https://gitea.privcloud.tech/wfa/mtusi2026lab2 mtusi2026lab2
|
||||
cd mtusi2026lab2
|
||||
git clone https://gitea.privcloud.tech/wfa/mtusi2026lab3 mtusi2026lab3
|
||||
cd mtusi2026lab3
|
||||
git checkout solution/bvt2302-bodanyuk
|
||||
python scripts\init_secrets.py
|
||||
python scripts\init_secrets.py # случайные пароли в .\secrets (не в Git)
|
||||
Copy-Item .env.example .env
|
||||
docker compose --env-file .env config --quiet # конфигурация собирается без ошибок
|
||||
docker compose --env-file .env up -d --build --wait
|
||||
```
|
||||
|
||||
Первый запуск скачивает образы (~700 МБ) и собирает API — 3–10 минут. Сделайте это **дома**: в аудитории сеть может быть медленной. Последняя команда завершается, когда все сервисы `healthy`.
|
||||
Первый запуск качает образы (~800 МБ) и собирает API — 3–10 минут. Команда завершается, когда postgres, valkey, обе реплики api и lb в состоянии `healthy`, а `migrate` завершился с кодом 0.
|
||||
|
||||
Проверка в браузере: http://127.0.0.1:8080/health/ready → `{"status":"ok"}`, Swagger — http://127.0.0.1:8080/docs.
|
||||
|
||||
Окружение для своих тестов (один раз):
|
||||
Окружение для своих тестов и скриптов (один раз):
|
||||
|
||||
```powershell
|
||||
python -m venv .venv
|
||||
.venv\Scripts\python -m pip install --require-hashes --no-deps -r requirements.txt
|
||||
.venv\Scripts\python -m pip install -r requirements-test.txt -r requirements-dev.txt
|
||||
$env:PYTHONUTF8 = "1" # публичные тесты читают UTF-8 JSON
|
||||
```
|
||||
|
||||
Активировать venv не нужно: везде вызывается `.venv\Scripts\python` напрямую, поэтому политика выполнения PowerShell не мешает.
|
||||
Проверка в браузере: http://127.0.0.1:8080/health/ready → `{"status":"ok"}`; Swagger — http://127.0.0.1:8080/docs; состояние балансировщика (какие реплики UP/DOWN) — http://127.0.0.1:8404/.
|
||||
|
||||
## 3. Перед защитой (в аудитории)
|
||||
|
||||
```powershell
|
||||
cd mtusi2026lab2
|
||||
docker compose up -d --wait # если стенд был остановлен
|
||||
$env:PYTHONUTF8 = "1" # публичные тесты читают UTF-8 JSON
|
||||
python tests\smoke.py # PASS: lab2 public API scenario
|
||||
cd mtusi2026lab3
|
||||
$env:PYTHONUTF8 = "1"
|
||||
$env:Path += ";C:\Program Files\Git\usr\bin" # sh для рецептов Makefile
|
||||
docker compose up -d --wait # если стенд был остановлен
|
||||
make check test PYTHON=python # или: python scripts\check_contract.py; python tests\smoke.py
|
||||
python scripts\lbctl.py status # обе реплики UP
|
||||
```
|
||||
|
||||
## 4. Сценарий защиты из README — команды по шагам
|
||||
## 4. Сценарий защиты из README — по шагам
|
||||
|
||||
**Шаг 1. Миграции к пустому volume, пользователи, вход, сообщение.**
|
||||
**Шаг 1. ≥ 2 разных `X-Instance-Id` через LB с одной сессией.**
|
||||
|
||||
```powershell
|
||||
docker compose down -v # стереть учебные данные (volumes)
|
||||
docker compose up -d --wait # postgres и valkey пустые -> migrate применяет схему
|
||||
docker compose logs migrate # "0001_init: applied"
|
||||
docker compose run --rm migrate # повтор: "already applied, skipped"
|
||||
python scripts\lbctl.py replicas # контейнеры api: имя, X-Instance-Id (= hostname), PID, IP
|
||||
# Один пользователь, один токен, 6 запросов подряд через LB — номера реплик чередуются:
|
||||
$u = "demo_" + (Get-Random); $p = "Demo-password-123"
|
||||
Invoke-RestMethod -Method Post http://127.0.0.1:8080/api/v1/users -ContentType 'application/json' -Body (@{username=$u; display_name='Демо'; password=$p} | ConvertTo-Json)
|
||||
$basic = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("${u}:${p}"))
|
||||
$t = (Invoke-RestMethod -Method Post http://127.0.0.1:8080/api/v1/auth/sessions -Headers @{Authorization="Basic $basic"}).token
|
||||
1..6 | ForEach-Object { (Invoke-WebRequest http://127.0.0.1:8080/api/v1/users/me -Headers @{Authorization="Bearer $t"} -UseBasicParsing).Headers['X-Instance-Id'] }
|
||||
```
|
||||
|
||||
Дальше в Swagger (http://127.0.0.1:8080/docs):
|
||||
1. `POST /api/v1/users` — создать двух пользователей (пароль 12+ символов).
|
||||
2. **Authorize → basicAuth**: логин и пароль первого; `POST /api/v1/auth/sessions` — скопировать `token`.
|
||||
3. **Authorize → bearerAuth**: вставить токен.
|
||||
4. `POST /api/v1/chats` (в `member_ids` — оба id) → `POST /api/v1/chats/{chat_id}/messages` → `GET` истории.
|
||||
Повторный вход не нужен: сессия лежит в общем Valkey. То же автоматически: `.venv\Scripts\python -m pytest student-tests\test_balancing.py -k one_session -v`.
|
||||
|
||||
**Шаги 2–3. Перезапуск API и хранилищ с сохранением volumes, тот же токен; logout → 401; короткий TTL.**
|
||||
**Шаг 2. Отказ реплики публичным тестом.**
|
||||
|
||||
```powershell
|
||||
python tests\resilience.py --mode persistence --action-script scripts\restart.cmd # PASS
|
||||
docker compose ps # у api, postgres, valkey свежее время запуска
|
||||
make test-failover ACTION_SCRIPT=scripts/stop-one.cmd PYTHON=python
|
||||
# без make: python tests\resilience.py --mode failover --action-script scripts\stop-one.cmd
|
||||
```
|
||||
|
||||
В Swagger тот же токен по-прежнему работает. `DELETE /api/v1/auth/sessions/current` → 204, затем любой запрос → 401.
|
||||
Тест сам выбирает реплику, обслужившую его первое сообщение, и передаёт её `X-Instance-Id` хуку. Хук останавливает именно этот контейнер и оставляет его остановленным. Вариант «падение процесса» — `$env:STOP_MODE = "kill"` перед командой (SIGKILL), вернуть — `Remove-Item Env:STOP_MODE`.
|
||||
|
||||
Короткий TTL:
|
||||
**Шаг 3. Показать, какой контейнер действительно остановлен, и повторить для второй.**
|
||||
|
||||
```powershell
|
||||
$env:SESSION_TTL_SECONDS = "2"; docker compose up -d --wait api
|
||||
docker compose exec api printenv SESSION_TTL_SECONDS # 2
|
||||
# в Swagger: войти, сразу GET /users/me -> 200, через 3 секунды -> 401
|
||||
Remove-Item Env:SESSION_TTL_SECONDS; docker compose up -d --wait api # вернуть 3600
|
||||
python scripts\lbctl.py replicas # у остановленной: exited, exit_code 0 (stop) или 137 (kill)
|
||||
python scripts\lbctl.py status # её слот в HAProxy — MAINT/DOWN, вторая UP
|
||||
docker compose logs --tail 20 api # drain_started -> shutdown_requested -> stopped у остановленной
|
||||
make restore PYTHON=python # или: & "C:\Program Files\Git\bin\bash.exe" scripts/restore-api.sh; python scripts\lbctl.py wait-up 2
|
||||
make test-failover ACTION_SCRIPT=scripts/stop-one.cmd PYTHON=python
|
||||
```
|
||||
|
||||
**Шаг 4. Роль Valkey, план SQL, ошибка зависимости.**
|
||||
Тест останавливает ту реплику, которая обслужила его первое сообщение, поэтому для второй он может снова выбрать прежнюю. Детерминированно по очереди каждую реплику останавливает серия уровня 4 (~5 мин): `python bench\failover_series.py --output evidence\failover` (stop, kill и pause для каждой реплики, с восстановлением предыдущей).
|
||||
|
||||
**Шаг 4. Restart всего стенда с сохранением volumes и прежним токеном.**
|
||||
|
||||
```powershell
|
||||
# Сессии лежат только в Valkey: ключи session:<sha256 токена>, самих токенов там нет
|
||||
# (без двойных кавычек внутри: PowerShell 5.1 ломает их при передаче в docker)
|
||||
docker compose exec valkey sh -c 'REDISCLI_AUTH=$(cat /run/secrets/valkey_password) valkey-cli --scan --pattern ''session:*'''
|
||||
|
||||
# План: поздняя страница по индексу (Index Cond) против IS NULL OR и OFFSET, 20 000 сообщений
|
||||
.venv\Scripts\python scripts\explain_history.py
|
||||
|
||||
# Ошибка зависимости: с действующим токеном -> 503, без токена -> 401, после старта всё работает
|
||||
docker compose stop valkey # или: docker compose pause postgres
|
||||
# в Swagger: GET /users/me -> 503 unavailable; GET /health/ready -> 503
|
||||
docker compose start valkey # или: docker compose unpause postgres
|
||||
make test-persistence ACTION_SCRIPT=scripts/restart.cmd PYTHON=python
|
||||
python scripts\lbctl.py replicas # у всех api свежий started и новый PID; LB снова видит обе реплики
|
||||
docker compose ps # postgres, valkey, lb — тоже «Up N seconds»
|
||||
```
|
||||
|
||||
Всё то же автоматически, с восстановлением в `finally`, около 1 минуты:
|
||||
**Уровень 4 вживую.**
|
||||
|
||||
```powershell
|
||||
.venv\Scripts\python -m pytest student-tests\test_failures.py -v
|
||||
# Неготовая, но живая реплика исключается из LB (pg_hba reject и docker network disconnect), ~1 мин:
|
||||
.venv\Scripts\python -m pytest student-tests\test_balancing.py -k not_ready -v -s
|
||||
# Rolling update под нагрузкой (~1,5 мин): новая ревизия на обеих репликах, 0 ошибок
|
||||
python bench\rolling_under_load.py --output evidence\rolling-update
|
||||
# Одновременные повторы с одним ключом через разные реплики:
|
||||
.venv\Scripts\python -m pytest student-tests\test_idempotency.py -k concurrent -v
|
||||
```
|
||||
|
||||
**Трек 2 вживую.**
|
||||
**Трек 1.** Полная серия идёт часы, поэтому на защите — готовые результаты: [evidence/track1/summary.md](../evidence/track1/summary.md) и графики `evidence/track1/*/*/throughput.svg`. Вживую можно показать профиль одной реплики (~2 мин) и одну короткую серию (~6 мин):
|
||||
|
||||
```powershell
|
||||
.venv\Scripts\python bench\track2\backup_restore.py --repeats 1 # ~1 мин: dump во время записи -> restore в новый контейнер -> сверка
|
||||
docker compose stop # основной стенд не должен мешать замеру
|
||||
python bench\track1\profile.py --label demo --rate 240
|
||||
python bench\track1\run.py --series demo --label now --rates 150,250,350 --repeats 1 --config replicas=2,MESSAGE_WRITE_PATH=multi --config replicas=2,MESSAGE_WRITE_PATH=function
|
||||
docker compose up -d --wait # вернуть основной стенд
|
||||
```
|
||||
|
||||
Скрипт печатает время дампа и восстановления, `reconciled: true` и сколько сообщений записано после снимка (RPO). Полный замер планов идёт ~25 минут, поэтому на защите показывайте готовые результаты: `evidence\track2\summary.md` и `evidence\track2\plans.png`. При желании можно запустить `.venv\Scripts\python bench\track2\index_sizes.py` (~2 мин).
|
||||
|
||||
**Все свои тесты** (~3,5 мин): `.venv\Scripts\python -m pytest student-tests -v`.
|
||||
**Все свои тесты** (~8 мин): `.venv\Scripts\python -m pytest student-tests -v`.
|
||||
|
||||
## 5. Если что-то пошло не так
|
||||
|
||||
| Симптом | Что сделать |
|
||||
| --- | --- |
|
||||
| `error during connect … dockerDesktopLinuxEngine` | Docker Desktop не запущен — запустить и подождать минуту |
|
||||
| `port is already allocated` на 8080 | в `.env` поставить `APP_PUBLISH_PORT=8081`; дальше тесты с `--base-url http://127.0.0.1:8081` (smoke и resilience), для pytest — `$env:BASE_URL="http://127.0.0.1:8081"` |
|
||||
| `port is already allocated` на 8080/8404 | занято другим стендом (lab2: `docker compose -p mtusi-lab2 stop`) или в `.env` поставить `APP_PUBLISH_PORT=8081`, `LB_STATS_PORT=8405`; тестам — `--base-url http://127.0.0.1:8081` / `$env:BASE_URL` |
|
||||
| `secrets/... not found` при `up` | не выполнен `python scripts\init_secrets.py` |
|
||||
| `UnicodeDecodeError` в `tests\*.py` | не задан `$env:PYTHONUTF8 = "1"` |
|
||||
| `restart.cmd`: «не удаётся найти путь» | Git установлен не в `C:\Program Files\Git` — поправить путь в `scripts\restart.cmd` |
|
||||
| api `unhealthy` после сна ноутбука | `docker compose restart` и подождать `docker compose ps` |
|
||||
| нужно начать с чистого листа | `docker compose down -v` (удаляет учебные данные) → `docker compose up -d --wait` |
|
||||
| `*.cmd`: «не удаётся найти путь» | Git установлен не в `C:\Program Files\Git` — поправить путь в `scripts\*.cmd` |
|
||||
| `make: command not found` | новое окно PowerShell после установки make или команды без make из REPORT.md |
|
||||
| make: `'test' is not recognized` | в этом окне не добавлен `C:\Program Files\Git\usr\bin` в `$env:Path` (рецептам нужен `sh`) |
|
||||
| после `stop-one` в LB одна реплика | так и задумано; вернуть: `make restore PYTHON=python` |
|
||||
| api `unhealthy` после сна ноутбука | `docker compose restart` и `python scripts\lbctl.py wait-up 2` |
|
||||
| нужно начать с чистого листа | `docker compose down -v` (удаляет учебные данные) → `docker compose up -d --build --wait` |
|
||||
|
||||
Остановить стенд после защиты: `docker compose down` (данные сохранятся) или `docker compose down -v` (данные удаляются).
|
||||
|
||||
@@ -0,0 +1,153 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Run every check of REPORT.md on the current checkout and save the real output in evidence/.
|
||||
|
||||
python scripts/collect_evidence.py # ~25 min; the stand must NOT be running yet
|
||||
|
||||
Intended for a CLEAN CLONE (fresh volumes): it creates secrets and .env, builds and starts the
|
||||
stand, then runs make check/validate/test/test-persistence/test-failover, the own tests, the
|
||||
level 4 experiments, and records container states before/after every hook. Prints no secrets
|
||||
(hook output is shown by the public tests as suppressed; our scripts print names and states only).
|
||||
On Windows the hooks are the scripts/*.cmd wrappers (Git Bash) and make needs Git's usr/bin.
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import datetime as dt
|
||||
import json
|
||||
import os
|
||||
import shutil
|
||||
import subprocess
|
||||
import sys
|
||||
import time
|
||||
from pathlib import Path
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[1]
|
||||
EVIDENCE = ROOT / "evidence"
|
||||
WINDOWS = os.name == "nt"
|
||||
HOOK = ".cmd" if WINDOWS else ".sh"
|
||||
PYTHON = sys.executable
|
||||
VENV_PY = str(ROOT / ".venv" / ("Scripts/python.exe" if WINDOWS else "bin/python"))
|
||||
ENV = {**os.environ, "PYTHONUTF8": "1"}
|
||||
if WINDOWS:
|
||||
ENV["PATH"] = ENV["PATH"] + os.pathsep + r"C:\Program Files\Git\usr\bin"
|
||||
|
||||
|
||||
def now() -> str:
|
||||
return dt.datetime.now(dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
|
||||
|
||||
|
||||
def sh(cmd: list[str], timeout: float = 1800, env: dict | None = None) -> tuple[int, str]:
|
||||
started = time.monotonic()
|
||||
result = subprocess.run(cmd, cwd=ROOT, capture_output=True, text=True, encoding="utf-8", errors="replace",
|
||||
timeout=timeout, env={**ENV, **(env or {})})
|
||||
took = time.monotonic() - started
|
||||
return result.returncode, (result.stdout + result.stderr).rstrip() + f"\n[exit {result.returncode}, {took:.1f} s]\n"
|
||||
|
||||
|
||||
class Log:
|
||||
def __init__(self, name: str, title: str):
|
||||
self.path = EVIDENCE / name
|
||||
self.path.parent.mkdir(parents=True, exist_ok=True)
|
||||
commit = subprocess.run(["git", "log", "-1", "--format=%h %s"], cwd=ROOT, capture_output=True, text=True,
|
||||
encoding="utf-8").stdout.strip()
|
||||
self.text = f"# {title}\n# {now()}, commit {commit}\n"
|
||||
|
||||
def run(self, cmd: list[str], shown: str | None = None, **kwargs) -> int:
|
||||
code, out = sh(cmd, **kwargs)
|
||||
self.text += f"\n$ {shown or ' '.join(cmd)}\n{out}"
|
||||
self.save()
|
||||
print(f" {self.path.name}: {shown or ' '.join(cmd[:4])} -> exit {code}", flush=True)
|
||||
return code
|
||||
|
||||
def note(self, text: str) -> None:
|
||||
self.text += f"\n{text}\n"
|
||||
self.save()
|
||||
|
||||
def save(self) -> None:
|
||||
self.path.write_text(self.text, encoding="utf-8")
|
||||
|
||||
|
||||
def states() -> list[str]:
|
||||
ids = subprocess.run(["docker", "compose", "ps", "-a", "-q"], cwd=ROOT, capture_output=True, text=True).stdout.split()
|
||||
rows = []
|
||||
for item in json.loads(subprocess.run(["docker", "inspect", *ids], capture_output=True, text=True).stdout or "[]"):
|
||||
st = item["State"]
|
||||
rows.append(f"{item['Name'].lstrip('/'):24} host={item['Config']['Hostname']:13} {st['Status']:8} "
|
||||
f"exit={st['ExitCode']:<3} pid={st['Pid']:<6} started={st['StartedAt'][:23]}")
|
||||
return sorted(rows)
|
||||
|
||||
|
||||
def main() -> int:
|
||||
EVIDENCE.mkdir(exist_ok=True)
|
||||
make = shutil.which("make", path=ENV["PATH"]) or "make"
|
||||
# 1. Clean clone -> secrets -> build -> start
|
||||
log = Log("clean-clone.txt", "Clean clone: secrets, config, build, migrations from zero, start, versions")
|
||||
log.run(["git", "status", "--short", "--branch"])
|
||||
log.run([PYTHON, "--version"]); log.run(["docker", "version", "--format", "client {{.Client.Version}} / server {{.Server.Version}}"])
|
||||
log.run(["docker", "compose", "version"]); log.run([make, "--version"], shown="make --version")
|
||||
log.run([PYTHON, "scripts/init_secrets.py"], shown="python scripts/init_secrets.py")
|
||||
if not (ROOT / ".env").exists():
|
||||
shutil.copy(ROOT / ".env.example", ROOT / ".env")
|
||||
log.note("$ cp .env.example .env")
|
||||
log.run(["docker", "compose", "--env-file", ".env", "config", "--quiet"])
|
||||
log.run(["docker", "compose", "--env-file", ".env", "up", "-d", "--build", "--wait"], timeout=1800)
|
||||
log.run(["docker", "compose", "ps", "-a", "--format", "table {{.Service}}\t{{.Image}}\t{{.Status}}"])
|
||||
log.run(["docker", "compose", "logs", "--no-log-prefix", "migrate"])
|
||||
log.run([PYTHON, "scripts/lbctl.py", "replicas"]); log.run([PYTHON, "scripts/lbctl.py", "status"])
|
||||
# venv for validate / own tests
|
||||
if not Path(VENV_PY).exists():
|
||||
log.run([PYTHON, "-m", "venv", ".venv"])
|
||||
log.run([VENV_PY, "-m", "pip", "install", "-q", "--require-hashes", "--no-deps", "-r", "requirements.txt"], timeout=1800)
|
||||
log.run([VENV_PY, "-m", "pip", "install", "-q", "-r", "requirements-test.txt", "-r", "requirements-dev.txt"], timeout=1800)
|
||||
|
||||
# 2. make check / validate / test
|
||||
log = Log("make-check-validate-test.txt", "make check, make validate (venv), make test")
|
||||
log.run([make, "check", f"PYTHON={PYTHON}"], shown="make check")
|
||||
log.run([make, "validate", f"PYTHON={VENV_PY}"], shown="make validate PYTHON=.venv/python")
|
||||
log.run([make, "test", f"PYTHON={PYTHON}"], shown="make test")
|
||||
|
||||
# 3. persistence with states before/after
|
||||
log = Log("test-persistence.txt", "make test-persistence: restart of LB, all API replicas, PostgreSQL, Valkey")
|
||||
log.note("Containers BEFORE:\n" + "\n".join(states()))
|
||||
log.run([make, "test-persistence", f"ACTION_SCRIPT=scripts/restart{HOOK}", f"PYTHON={PYTHON}"],
|
||||
shown=f"make test-persistence ACTION_SCRIPT=scripts/restart{HOOK}")
|
||||
log.note("Containers AFTER (new pid/started for lb, api-*, postgres, valkey; volumes kept):\n" + "\n".join(states()))
|
||||
log.run([PYTHON, "scripts/lbctl.py", "wait-up", "2"])
|
||||
|
||||
# 4. failover: until BOTH replicas have been the stopped one (each run is a real public test)
|
||||
log = Log("test-failover.txt", "make test-failover with scripts/stop-one: which container is really stopped, restore, repeat")
|
||||
stopped: set[str] = set()
|
||||
for attempt in range(1, 7):
|
||||
before = {r for r in states() if "-api-" in r and " running " in r}
|
||||
log.note(f"--- run {attempt}; running API replicas BEFORE:\n" + "\n".join(sorted(before)))
|
||||
log.run([make, "test-failover", f"ACTION_SCRIPT=scripts/stop-one{HOOK}", f"PYTHON={PYTHON}"],
|
||||
shown=f"make test-failover ACTION_SCRIPT=scripts/stop-one{HOOK}")
|
||||
after = states()
|
||||
gone = [r for r in after if "-api-" in r and " exited " in r]
|
||||
log.note("AFTER (the stopped replica, left stopped by the hook):\n" + "\n".join(gone))
|
||||
log.run([PYTHON, "scripts/lbctl.py", "status"])
|
||||
stopped.update(r.split()[0] for r in gone)
|
||||
log.run(["sh" if not WINDOWS else r"C:\Program Files\Git\bin\bash.exe", "scripts/restore-api.sh"],
|
||||
shown="sh scripts/restore-api.sh")
|
||||
log.run([PYTHON, "scripts/lbctl.py", "wait-up", "2"])
|
||||
if len(stopped) >= 2:
|
||||
break
|
||||
log.note(f"Replicas stopped by the public test across runs: {sorted(stopped)}")
|
||||
|
||||
# 5. own tests
|
||||
log = Log("student-tests.txt", "Own tests: unit + stand (pytest -v); failures restored in finally")
|
||||
log.run([VENV_PY, "-m", "pytest", "student-tests", "-v", "-p", "no:cacheprovider"], shown="python -m pytest student-tests -v",
|
||||
timeout=3600)
|
||||
|
||||
# 6. level 4 experiments and the public load script
|
||||
log = Log("level4-runs.txt", "Level 4: failover series, rolling update under load, public load.py")
|
||||
log.run([PYTHON, "bench/failover_series.py", "--output", "evidence/failover"], timeout=1800)
|
||||
log.run([PYTHON, "bench/rolling_under_load.py", "--output", "evidence/rolling-update"], timeout=1800)
|
||||
log.run([PYTHON, "scripts/lbctl.py", "wait-up", "2"])
|
||||
log.run([PYTHON, "tests/load.py", "--duration", "30", "--concurrency", "4", "--output", "evidence/load.json"])
|
||||
log.run(["docker", "compose", "ps", "-a", "--format", "table {{.Service}}\t{{.Status}}"])
|
||||
print("done:", EVIDENCE)
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
Reference in New Issue
Block a user