From 6c7892f4ff0b96a72286daed000a682f3dc5c57a Mon Sep 17 00:00:00 2001 From: Sergey Lyakhonov Date: Fri, 9 Oct 2026 14:31:07 +0300 Subject: [PATCH] =?UTF-8?q?=D0=97=D0=B0=D0=BF=D0=BE=D0=BB=D0=BD=D0=B8?= =?UTF-8?q?=D0=BB=20=D0=BE=D1=82=D1=87=D1=91=D1=82=20=D0=BB=D0=B0=D0=B1?= =?UTF-8?q?=D0=BE=D1=80=D0=B0=D1=82=D0=BE=D1=80=D0=BD=D0=BE=D0=B9=202=20?= =?UTF-8?q?=D1=81=20=D1=80=D0=B5=D0=B7=D1=83=D0=BB=D1=8C=D1=82=D0=B0=D1=82?= =?UTF-8?q?=D0=B0=D0=BC=D0=B8=20=D0=BF=D1=80=D0=BE=D0=B2=D0=B5=D1=80=D0=BE?= =?UTF-8?q?=D0=BA=20=D0=B8=20=D0=B8=D1=81=D1=81=D0=BB=D0=B5=D0=B4=D0=BE?= =?UTF-8?q?=D0=B2=D0=B0=D0=BD=D0=B8=D1=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- REPORT.md | 276 +++++++++++++++++++++++++++++--- evidence/clean_clone.json | 23 +++ evidence/environment.json | 21 +++ evidence/lifecycle.json | 7 + evidence/openapi_validation.txt | 2 + 5 files changed, 311 insertions(+), 18 deletions(-) create mode 100644 evidence/clean_clone.json create mode 100644 evidence/environment.json create mode 100644 evidence/lifecycle.json create mode 100644 evidence/openapi_validation.txt diff --git a/REPORT.md b/REPORT.md index e42f2b05..884e2b83 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,277 @@ # Отчёт — лабораторная 2 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- Автор: Ляхонов Сергей, группа БВТ2301. +- Целевая оценка: **5**, трек 2 — «План запроса и восстановление». +- Дата проверок: 9 октября 2026 года. +- Ветка: `solution/BVT2301-lyakhonov`. +- Репозиторий: https://gitea.privcloud.tech/lyakhonov/mtusi2026lab2 +- PR пока не открыт; адрес будет добавлен после публикации ветки и создания PR. +- Перенос основы: `6e19f1d`; уровень 3: `6fba941`; уровень 4: `64f2a5b`; уровень 5: `358ef4a`; итоговое уточнение аутентификации: `509161e`. +- Использование ИИ: Codex помог написать и проверить приложение, инфраструктуру, собственные тесты и исследовательские сценарии, разобрать измерения и оформить этот отчёт. Исходной основой была моя принятая лабораторная 1. Публичные проверки и обязательный контракт преподавателя не изменялись. ## Запуск из чистого clone -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +### Окружение + +Проверено на Windows, Docker Desktop 4.49.0 с Linux containers, Docker Engine 28.5.1, Compose v2.40.3-desktop.1, Python 3.13.7 на машине запуска. Компьютер: Intel Core i5-1340P, 12 ядер / 16 логических процессоров, 16 778 182 656 байт оперативной памяти (около 15,63 GiB). Все зависимости PostgreSQL и Redis запускаются из репозитория; установленные на хосте БД не нужны. + +Runtime приложения: Python 3.11.10, образ `python:3.11.10-slim-bookworm`; PostgreSQL `postgres:16.6-alpine`; Redis `redis:7.4.1-alpine`. Основные библиотеки: FastAPI 0.115.0, Uvicorn 0.32.0, Pydantic 2.9.2, psycopg 3.2.3, psycopg-pool 3.2.4, argon2-cffi 23.1.0, redis-py 5.2.0. Все фактические зависимости образа закреплены в `requirements.lock.txt`; Dockerfile устанавливает именно этот файл. `requirements.txt` перечисляет прямые зависимости. Linux lock содержит uvloop: для Windows основной путь запуска — Docker, не установка Linux lock в системный Python. + +| Сервис | CPU | RAM | Том | Порты и готовность | +| --- | --- | --- | --- | --- | +| `api` | 1 CPU | 512 MiB | нет данных на диске | localhost:8080; `/health/ready` проверяет PostgreSQL | +| `db` | 1 CPU | 512 MiB | `postgres_data` | только сеть Compose; `pg_isready` | +| `redis` | 0,5 CPU | 128 MiB | `redis_data` | только сеть Compose; `redis-cli ping` | + +У Redis отдельно установлен `maxmemory=64mb`, политика `allkeys-lru`. Его том не является источником сохранности: RDB/AOF отключены, потому что в нём только восстанавливаемый кэш профилей. Все сессии сохраняются в PostgreSQL. + +### Команды запуска + +Из корня клона, в Git Bash, PowerShell или Linux shell: + +```sh +python scripts/bootstrap.py +docker compose config --quiet +docker compose up -d --build --wait --wait-timeout 90 +python scripts/wait_ready.py +python scripts/check_contract.py +python tests/smoke.py +python student-tests/test_lab2.py +``` + +`bootstrap.py` создаёт случайный локальный пароль и URL БД в `secrets/`, не печатает значения и не перезаписывает существующие файлы. Compose передаёт их через `/run/secrets/db_password` и `/run/secrets/database_url`. Каталог исключён из Git. Повтор bootstrap безопасен. Если удалить секреты при сохранённом томе БД и сгенерировать другой пароль, нужно отдельно согласовать новый пароль с БД: автоматической смены пароля существующего PostgreSQL нет. + +При каждом запуске API сначала выполняется `python -m src.migrate`, затем Uvicorn становится основным процессом контейнера через `exec`. Миграции применяются к пустой БД; повторный запуск не создаёт данные заново. Отдельная проверка повторного запуска: + +```sh +docker compose exec -T api python -m src.migrate +``` + +Локальный `.env` необязателен. Для короткого TTL основного стенда можно создать исключённый из Git `.env` с `SESSION_TTL_SECONDS=2` и пересоздать API; перед публичным smoke и persistence вернуть не менее 300 секунд (по умолчанию 3600). Автотест expiry запускает отдельный временный API на 8082 и не меняет TTL основного стенда. + +### Соответствие конфигурации + +| Настройка | Реальное использование | +| --- | --- | +| `SESSION_TTL_SECONDS` | Compose передаёт в API, по умолчанию 3600; абсолютное expiry рассчитывается PostgreSQL | +| `DATABASE_URL_FILE` | Чтение секрета URL через `src/config.py` | +| `DATABASE_URL` | Альтернативное прямое значение для самостоятельного запуска; секрет предпочтительнее | +| `CACHE_URL` / `CACHE_URL_FILE` | В Compose задан внутренний `redis://redis:6379/0`; конфигурация также поддерживает файл | +| `PROFILE_CACHE_TTL_SECONDS` | TTL профиля, в Compose 60 секунд | +| `SESSION_STORE` из примера | Выбор альтернативного backend не реализован: источник сессий всегда PostgreSQL | +| `APP_HOST`, `APP_PORT` | Поддерживаются самостоятельной точкой входа `src/main.py`; Docker запускает Uvicorn явно на 0.0.0.0:8080 | +| `APP_ENV` | Информационная подсказка заготовки, на поведение реализации не влияет | + +### Проверки и остановка + +На Windows (включая Git Bash с Windows Python): + +```sh +python tests/resilience.py --mode persistence --action-script scripts/restart.cmd +``` + +На Linux: + +```sh +chmod +x scripts/restart.sh +python tests/resilience.py --mode persistence --action-script scripts/restart.sh +``` + +Windows Python не исполняет Unix shebang как Linux, поэтому добавлен эквивалентный `.cmd`. Оба hook перезапускают **db, redis и api**, не удаляют volumes, не перезаполняют БД и не меняют тестовые данные. + +Если установлен Make, эквивалентные цели: + +```sh +make check PYTHON=python +make test PYTHON=python +make student-test PYTHON=python +make test-persistence PYTHON=python ACTION_SCRIPT=scripts/restart.cmd +# Linux: ACTION_SCRIPT=scripts/restart.sh +make level4-test PYTHON=python +make explain PYTHON=python +make research PYTHON=python +``` + +В сохранённых результатах выполнялись непосредственно Python-команды, которые вызываются этими целями; это явно отмечено, а не заявлено как запуск отсутствующего на Windows Make. + +```sh +# Дополнительные проверки уровня 4 — явно останавливают зависимости учебного стенда: +python student-tests/test_level4.py +python student-tests/explain_level4.py + +# Исследование и восстановление: +python scripts/research.py + +# Безопасная остановка без удаления данных: +docker compose down + +# Повторный запуск: +docker compose up -d --wait --wait-timeout 90 + +# Только для намеренного удаления данных именно этого учебного Compose-проекта: +docker compose down --volumes +``` + +Последняя команда приведена для оператора и в проверках не выполнялась. Исследовательские БД и отдельные тома восстановления создаются с уникальными именами и не удаляются автоматически; их имена записаны в evidence. Повтор исследования расходует дополнительное место. Архивы находятся в `backups/` вне Git. Перед запуском уровня 4 порт 8082 должен быть свободен. + +Для полной валидации OpenAPI: + +```sh +python -m pip install -r requirements-dev.txt +python scripts/validate_openapi.py +``` + +На стенде валидатор запускался в отдельном одноразовом контейнере, не меняющем рабочий образ приложения. ## Архитектура и решения -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab1, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +```text +Клиент → FastAPI/Uvicorn → PostgreSQL (пользователи, чаты, участники, сообщения, сессии) + → Redis (необязательный кэш публичных профилей) +``` + +Из lab1 перенесены маршруты и модели REST API, обработка ошибок с X-Request-Id, проверки членства, формат курсора, ограничение одновременных запросов и основа контейнера. Словари заменены PostgreSQL, собственные тесты адаптированы. Старые тесты с X-User-Id и сборщик token bucket удалены после переноса полезных сценариев в test_lab2.py. Эксперимент деградации lab1 не заявляется доказательством lab2. + +### Схема, ограничения и транзакции + +`migrations/001_initial.sql` содержит users, chats, chat_members, messages, sessions. У каждого объекта UUID PK; username уникален. Участники имеют PK `(chat_id,user_id)`. Сообщение связано FK с чатом и пользователем, а составной FK `(chat_id,sender_id)` гарантирует членство отправителя. Ограничения длины и непустоты дополняют HTTP-валидацию. + +Создание чата и всех участников выполняется одной транзакцией. Неизвестный участник нарушает FK, вся транзакция откатывается, клиент получает 400. Гонка регистрации разрешается уникальным ограничением PostgreSQL: один 201, остальные 409. Параметры передаются отдельно от SQL; пользовательский текст не подставляется в строку запроса. + +Пул: от 1 до 10 соединений, не более 32 ожидающих; timeout получения 3 секунды, connect_timeout 3 секунды, statement_timeout 3 секунды, lock_timeout 2 секунды. Ошибка критичного хранилища возвращает 503 без SQL/stack trace. Синхронные маршруты исполняются в пуле потоков; KDF входа вынесен из цикла событий. + +`schema_migrations` хранит применённые версии. Миграции выполняются в транзакции под advisory lock, поэтому повторный и параллельный запуск не применяет их дважды. Предварительное описание схемы и границ — `infra/schema.md`. + +### Аутентификация и сохранность + +Регистрация требует password длиной 12–128 Unicode code points. Пароль хешируется Argon2id (time_cost=2, memory_cost=19 456 KiB, parallelism=1), соль создаёт библиотека. Хеш не входит в публичный User. Basic используется только для POST `/api/v1/auth/sessions`; пароль разбирается по первому двоеточию, поэтому двоеточия в пароле сохраняются. Неверные учётные данные дают одинаковый 401 с WWW-Authenticate Basic. Для неизвестного пользователя также выполняется проверка KDF на служебном хеше. + +Токен создаётся `secrets.token_urlsafe(32)`: 32 случайных байта, 256 бит энтропии. В БД хранится только SHA-256 токена, UUID пользователя и абсолютное expires_at. SHA-256 используется для случайного токена, **не для пароля**. Каждая Bearer-сессия проверяется в PostgreSQL с текущим временем БД. Logout удаляет строку, повторный запрос даёт 401 с WWW-Authenticate Bearer. Basic на бизнес-маршруте не принимается. X-User-Id игнорируется и не меняет владельца Bearer-сессии. + +После успешного контекста psycopg выполняется COMMIT, и только после его завершения возвращается созданный объект. На проверенном PostgreSQL `fsync=on`, `synchronous_commit=on`, `full_page_writes=on`. Это даёт обычные гарантии PostgreSQL в рамках доступного устойчивого тома, но не резервирует диск и host. Перезапуск API не продлевает expires_at. Сессии, ещё действующие после рестарта, читают прежние данные. + +### Кэш профиля + +Redis работает по cache-aside. Ключ `profile:v1:`, TTL 60 секунд, значение — только публичный User. Промах читает PostgreSQL и заполняет Redis; ошибка Redis обходит кэш. Профиль в обязательном API нельзя редактировать или удалить, поэтому кэшируемые данные неизменяемы. Если такие операции появятся, потребуется явная инвалидация. Очистка/рестарт Redis не теряет сессии: они в PostgreSQL. История сообщений и решения об авторизации не кэшируются, поэтому кэш не нарушает read-after-write и немедленный logout. + +Readiness зависит от PostgreSQL и не зависит от Redis. Liveness проверяет только процесс. Дополнительная диагностика GET `/stats` описана в `infra/extensions.md`; обязательный contracts/ не изменялся. + +### Курсор и индекс + +Курсор — URL-safe Base64 JSON с `scope`, `resource_id`, `created_at`, `id`. Он проверяется на структуру, UUID, время, правильный ресурс и существование маркера. Для списка чатов ресурс — пользователь, для истории — чат. Курсор не подписан и не заменяет авторизацию. + +Время PostgreSQL возвращается в UTC с микросекундами. SQL выбирает записи после пары `(created_at,id)` и запрашивает `limit+1`, чтобы узнать, есть ли следующая страница: + +```sql +SELECT * FROM messages +WHERE chat_id = $1 AND (created_at, id) > ($2, $3) +ORDER BY created_at, id +LIMIT $4; +``` + +Индекс: `(chat_id,created_at,id)`. В приложении нет OFFSET и сортировки всей истории в Python. Для одной страницы достаточно индексного диапазона. Между несколькими запросами нет snapshot: конкурентная вставка с ключом до курсора не попадёт в уже продолжаемый обход. UUID разрешает одинаковое время, но не задаёт очерёдность отправки при равном timestamp. ## Доказательства критериев -| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | +| Критерий | Команда/проверка | Наблюдение | Доказательство | | --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | +| Структура и обязательный контракт | `python scripts/check_contract.py` | PASS; публичные tests/ и contracts/ не менялись | `evidence/final_checks.json` | +| Полная OpenAPI 3.1 / JSON Schema | `python scripts/validate_openapi.py` | PASS в одноразовом контейнере | `evidence/openapi_validation.txt` | +| Публичный сценарий lab2 | `python tests/smoke.py` | PASS: регистрация, Basic/Bearer, чат, сообщения, курсор, доступ, logout | `evidence/level3.json`, `evidence/final_checks.json` | +| PostgreSQL, FK, уникальность и атомарный чат | миграция + test_level4.py | 1×201, 7×409; неизвестный участник не оставляет чат | `migrations/001_initial.sql`, `evidence/level4.json` | +| Полный рестарт, прежний токен и данные | `python tests/resilience.py --mode persistence --action-script scripts/restart.cmd` | PASS; изменились StartedAt db/redis/api, том PostgreSQL прежний | `evidence/final_checks.json` | +| Повтор миграций | `docker compose exec -T api python -m src.migrate` | одна версия 001_initial.sql, повтор без изменений | `evidence/level3.json` | +| Воспроизводимая сборка | чистый локальный clone, новые секреты и тома, отдельный порт 8083 | сборка + smoke + собственные тесты PASS | `evidence/clean_clone.json` | +| Конкурентная запись и отрицательные сценарии | `python student-tests/test_lab2.py` | 100 уникальных сообщений от 10 клиентов, полный обход, чужой/битый cursor → 400 | `evidence/final_checks.json` | +| Непривилегированный процесс и SIGTERM | docker stop --timeout 10, проверка exit code и закрытого порта | appuser; exit 0; остановка за 0.729 с | `evidence/lifecycle.json` | +| Реальный Redis, TTL и обход при отказе | `python student-tests/test_level4.py` | профиль присутствует, TTL 59 с; при остановке Redis авторизованный запрос проходит | `evidence/level4.json` | +| Пул, параметры, timeout и отказ БД | тот же тест | live=200; ready и защищённый запрос=503; после запуска БД прежняя сессия работает | `src/storage.py`, `evidence/level4.json` | +| Expiry, logout, неверный пароль | отдельный API TTL=2 + публичный smoke | после 2,2 с — 401; logout — 401; неверный пароль — 401 | `evidence/level4.json`, `evidence/final_checks.json` | +| Индекс истории на ≥10 000 | `python student-tests/explain_level4.py` | messages_history_idx; Execution Time 0,080 мс | `evidence/explain_10000.json` | +| Трек 2: ≥100 000, ≥2 индекса, стоимость записи | `python scripts/research.py` | 100 000 сообщений, 13 чатов, 3 индекса, SQL-планы и latency | `evidence/research.json` | +| Трек 2: backup → новое хранилище → сверка | та же команда | 100 000 сообщений совпали по количеству и общей контрольной сумме; 39 выборочных строк равны | `evidence/recovery.json` | -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +Имена контейнеров, UUID и названия томов в evidence относятся к конкретному запуску; они не нужны для запуска нового клона. Токены, пароли и бинарные дампы в Git не включены. Чистый clone проверялся на коммите 509161e; последующее заполнение отчёта не изменяет runtime. -## Эксперименты и отказы +## Исследование уровня 5, трек 2 -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. +### Гипотеза и методика -| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | +Гипотеза: индекс только по chat_id вынужден читать и сортировать много строк большого чата; составной B-tree `(chat_id,created_at,id)` позволяет сразу найти диапазон после курсора. Покрывающий индекс с INCLUDE может уменьшить heap fetches, но увеличит память и стоимость записи; его выигрыш нужно измерить. + +Исследование выполняется в отдельной БД с уникальным именем в том же PostgreSQL, не в таблицах API. Создано **ровно 100 000 сообщений**: чаты на 70 000, 20 000, 9 000 сообщений и десять чатов по 100. Текст — 128 символов x и порядковый номер. Время задаётся детерминированно с шагом 1 микросекунда; UUID случайные. Все три варианта проверяются на одном наборе данных и с теми же лимитами контейнера. + +Сравниваются: + +1. `chat_only`: B-tree `(chat_id)`. +2. `composite`: B-tree `(chat_id,created_at,id)`. +3. `covering`: B-tree `(chat_id,created_at,id) INCLUDE(sender_id,text)`. + +Для размеров 70 000, 20 000, 9 000 и 100 проверяются границы на 10%, 50% и 90% истории. В каждом случае три прогревочных запроса и 100 измеряемых запросов, всего **3 600 успешных чтений**, ошибок 0. Конкуренция 1, closed-loop без заданного arrival rate. Один SQL-запрос возвращает до 51 строки. Latency измеряется клиентом psycopg в контейнере API, включает выполнение SQL и передачу результата; отдельный EXPLAIN фиксирует серверное время и buffers. Это **SQL-throughput, не HTTP RPS и не предел производительности сервера**. + +Для каждого индекса дополнительно три транзакции вставки по 1 000 сообщений с COMMIT. После каждого измерения строки write_probe удаляются вне измеряемого интервала. Составной FK и PK одинаковы во всех вариантах. Записаны время построения и размер индекса. Перед измерениями выполняется VACUUM ANALYZE. OFFSET используется только для подготовки позиции эксперимента, не в измеряемом запросе и не в API. + +### Результаты + +Большой чат (70 000 сообщений), граница на 90% истории; latency в мс, throughput — успешные SQL-запросы/с. Стоимость записи — медиана трёх транзакций по 1 000 строк с COMMIT: + +| Индекс | p50, мс | p95, мс | p99, мс | SQL-запросов/с | Размер, MiB | Запись, строк/с | +| --- | --- | --- | --- | --- | --- | --- | +| chat_only | 6.727 | 8.431 | 9.563 | 144 | 0.70 | 19896 | +| composite | 0.377 | 0.587 | 0.657 | 2453 | 5.95 | 19496 | +| covering | 0.552 | 1.057 | 1.521 | 1060 | 23.44 | 18088 | + +При chat_only планировщик выбрал Seq Scan + top-N Sort: 93 001 строка отфильтрована, 2 811 shared hit blocks. Составной индекс дал Index Scan без Sort: 51 строка и 6 shared hit blocks. Покрывающий дал Index Only Scan, Heap Fetches=0 и 5 shared hit blocks. Уменьшение heap-доступов само по себе не гарантировало меньшую клиентскую задержку. + +Для составного индекса p95 снизился примерно в 14,4 раза относительно chat_only. Покрывающий индекс занял около 23,44 MiB против 5,95 MiB составного (примерно в 3,94 раза больше); стоимость записи оказалась выше, а latency в выбранном случае хуже. Поэтому в приложении оставлен обычный составной индекс. Это локальный вывод для данного профиля, не универсальный запрет INCLUDE. + +Полный исследовательский запуск вместе с созданием набора и сбором метрик занял 14.29 с. По пяти выборкам Docker stats PostgreSQL наблюдалось до 98,84% CPU (при лимите 1 CPU) и до 88,77 MiB памяти из 512 MiB. Это метрика памяти контейнера Docker, не точный RSS отдельного backend. Выборки примерно раз в 3 секунды: короткие пики могли быть пропущены. Для каждого из 36 сочетаний в JSON сохранены duration, успешные запросы/с, ошибки, p50/p95/p99 и полный EXPLAIN (ANALYZE, BUFFERS). + +### Backup и восстановление + +После исследования создан логический архив `pg_dump -Fc` всей исследовательской БД. Затем запущен **новый контейнер PostgreSQL с новым пустым именованным томом**, теми же CPU/RAM и версией образа. Архив скопирован и восстановлен через `pg_restore --exit-on-error --no-owner`. Это не повторное чтение исходной БД и не восстановление в старый том. + +- Размер архива: 2991247 байт. +- Создание дампа и копирование на хост: 1.304 с. +- Сам `pg_restore`: 0.814 с. +- Запуск нового хранилища, ожидание готовности, копирование архива и restore: 3.166 с. +- Количества: 1 пользователь, 13 чатов, 13 членств, 100 000 сообщений, 0 сессий в отдельной исследовательской БД. +- Совпали количества всех таблиц, MD5-отпечаток упорядоченного содержимого **всех сообщений** и 39 выбранных строк (начало, середина, конец каждого чата). +- Потеря сообщений относительно снимка дампа: 0. + +MD5 здесь — техническая сверка синтетических данных, не защита от намеренной подмены. Сохранность действующих сессий отдельно проверена публичным persistence на основной БД, в которой сессии реально есть. + +После сверки восстановленный контейнер остановлен, новый том оставлен для демонстрации. Его имя и имя исходной исследовательской БД записаны в `evidence/recovery.json` и `evidence/research.json`. Архив находится в `backups/`, исключённом из Git. Для повтора не нужен мой архив: `scripts/research.py` создаёт новый набор, архив и новый том. + +## Отказы и границы решения + +| Воздействие | Ожидание | Наблюдение | Восстановление / потеря | | --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +| Рестарт API, PostgreSQL, Redis | прежний токен и подтверждённые данные сохраняются | публичный persistence PASS, StartedAt всех трёх изменился | данные не потеряны, expiry не продлён | +| Остановка Redis | чтение профиля через PostgreSQL | запрос с Bearer прошёл, анонимный получил 401 | кэш заполняется заново; данные и сессии сохранены | +| Остановка PostgreSQL | ограниченный 503; live остаётся 200 | два ошибочных запроса заняли суммарно 6,05 с | после старта БД прежняя сессия работает | +| Expiry при TTL=2 | токен становится недействительным | после 2,2 с получен 401 | нужен новый вход | +| Logout | немедленный отзыв | прежний токен получает 401 | нужен новый вход | +| Ошибка участника при создании чата | полный rollback | количество чатов не увеличилось | неполный чат не создан | +| SIGTERM | завершение ≤10 с, новые запросы не принимаются | exit 0, 0.729 с, порт перестал отвечать | данные в PostgreSQL сохранены | +| Восстановление логического дампа | совпадение снимка в новом хранилище | полная сверка PASS | 0 потерь относительно снимка, restore 0.814 с | -## Ограничения и следующие шаги +Время 8,617 с в level4.json включает команду остановки Redis и запрос, поэтому это не задержка одного fallback-запроса. Для отказа БД зафиксировано суммарное время двух запросов, а не production SLA восстановления. Публичный тест ждёт готовности в своём бюджете; более строгий RTO после полной аварии host не исследован. -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +Один Docker-host и один PostgreSQL не обеспечивают HA. Именованный том выдерживает проверенный restart контейнера, но не утрату диска. `pg_dump` даёт согласованный снимок: новые записи после этого снимка в архив не входят. Без архивирования WAL и PITR возможная потеря при аварии равна изменениям после последнего успешного backup; нулевая потеря в эксперименте относится только к замороженному исследовательскому набору. Архив на том же физическом компьютере не защищает от потери этого компьютера. + +Ограничения измерений: один компьютер, тёплый кэш, один клиентский поток, три индекса запускались последовательно без рандомизации; 100 повторов каждого чтения, три повтора записи. Набор сообщений синтетический, нет длительного смешанного read/write и сетевой задержки удалённого стенда. Результаты не являются оценкой максимальных HTTP RPS. Для повторного исследования следует менять порядок вариантов и увеличивать длительность/число независимых прогонов. + +Учебные упрощения: HTTP только на localhost, нет TLS и ограничения попыток входа; роль PostgreSQL, созданная стандартным образом, имеет административные права для миграций и исследовательских БД. Для production нужны отдельные роли приложения/миграций/backup, мониторинг, управление секретами, ротация и внешнее резервное хранилище. Истёкшие строки сессий не очищаются фоновым процессом, но никогда не принимаются как действующие. Список чатов делает дополнительные запросы участников по числу чатов страницы; индекс истории решает именно чтение сообщений. + +В Gitea эта работа проверена локально. Workflow заготовки в `.github/` сохранён, автоматический запуск Gitea Actions не заявляется. Оценка подтверждается воспроизводимыми сценариями и защитой, а не наличием зелёного CI. + +## Источники + +- [Документация PostgreSQL 16: составные индексы](https://www.postgresql.org/docs/16/indexes-multicolumn.html). +- [Документация PostgreSQL 16: EXPLAIN](https://www.postgresql.org/docs/16/using-explain.html). +- [pg_dump](https://www.postgresql.org/docs/16/app-pgdump.html), [pg_restore](https://www.postgresql.org/docs/16/app-pgrestore.html). +- [psycopg: connection pools и границы транзакций](https://www.psycopg.org/psycopg3/docs/advanced/pool.html). +- [Redis: cache-aside](https://redis.io/docs/latest/develop/use-cases/cache-aside/). +- [argon2-cffi](https://argon2-cffi.readthedocs.io/en/stable/howto.html). +- [RFC 7617: Basic Authentication](https://www.rfc-editor.org/rfc/rfc7617). diff --git a/evidence/clean_clone.json b/evidence/clean_clone.json new file mode 100644 index 00000000..9eb70ce1 --- /dev/null +++ b/evidence/clean_clone.json @@ -0,0 +1,23 @@ +{ + "source_commit": "509161edcabe7f99a67d9a3fbd3c35ae077d9cd4", + "clone": "C:\\Users\\User\\AppData\\Local\\Temp\\lyakhonov-lab2-clean-p6og92bu", + "project": "lyakhonov-lab2-clean", + "fresh_secrets": true, + "fresh_volumes": true, + "port": 8083, + "build_and_checks_seconds": 30.772888699983014, + "checks": [ + { + "command": "python scripts/check_contract.py", + "output": "PASS: offline skeleton structure, local refs and Python syntax; application NOT tested." + }, + { + "command": "python tests/smoke.py --base-url http://localhost:8083", + "output": "PASS: lab2 public API scenario; infrastructure and grading evidence remain separate." + }, + { + "command": "python student-tests/test_lab2.py --base-url http://localhost:8083", + "output": "PASS: strict validation, access, cursor binding, 100 messages / 10 clients, complete pagination" + } + ] +} diff --git a/evidence/environment.json b/evidence/environment.json new file mode 100644 index 00000000..9d4b4142 --- /dev/null +++ b/evidence/environment.json @@ -0,0 +1,21 @@ +{ + "date": "2026-10-09", + "author": "Ляхонов Сергей", + "group": "БВТ2301", + "grade": 5, + "track": 2, + "tested_runtime_commit": "509161edcabe7f99a67d9a3fbd3c35ae077d9cd4", + "research_worker_sha256": "a87d5a83a9046521a101ad6b46911502ecb5bf5b16fef72adfa4eccaec16b09d", + "cpu": "Intel Core i5-1340P", + "cores": 12, + "logical_processors": 16, + "host_ram_bytes": 16778182656, + "docker": "28.5.1", + "docker_desktop": "4.49.0", + "compose": "2.40.3-desktop.1", + "postgres_durability": { + "fsync": "on", + "synchronous_commit": "on", + "full_page_writes": "on" + } +} diff --git a/evidence/lifecycle.json b/evidence/lifecycle.json new file mode 100644 index 00000000..90afee66 --- /dev/null +++ b/evidence/lifecycle.json @@ -0,0 +1,7 @@ +{ + "stop_seconds": 0.7288908000045922, + "exit_code": 0, + "new_requests_refused": true, + "container_user": "uid=999(appuser) gid=999(appuser) groups=999(appuser)", + "graceful_timeout_seconds": 8 +} diff --git a/evidence/openapi_validation.txt b/evidence/openapi_validation.txt new file mode 100644 index 00000000..830f0726 --- /dev/null +++ b/evidence/openapi_validation.txt @@ -0,0 +1,2 @@ +Команда во временном контейнере: python scripts/validate_openapi.py +PASS: full OpenAPI 3.1 and JSON Schema validation; application NOT tested.