From 370d947132544da8b6c2c09f2be750e54da11633 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=90=D0=BD=D0=B0=D1=81=D1=82=D0=B0=D1=81=D0=B8=D1=8F=20?= =?UTF-8?q?=D0=9C=D0=B0=D1=80=D1=82=D0=B8=D0=BD=D0=B5=D1=81?= Date: Thu, 19 Nov 2026 10:47:21 +0300 Subject: [PATCH] Implement lab 2 PostgreSQL sessions and Redis profile cache --- .dockerignore | 1 + .gitattributes | 5 + .github/workflows/application.yml | 23 ++ Dockerfile | 14 ++ PR_DESCRIPTION.md | 38 +++ REPORT.md | 164 +++++++++++-- compose.yaml | 48 ++++ docs/defense.md | 48 ++++ docs/design.md | 38 +++ evidence/contract.txt | 1 + evidence/environment.json | 7 + evidence/load.json | 17 ++ evidence/load.txt | 17 ++ evidence/persistence.txt | 2 + evidence/query-plan.json | 79 +++++++ evidence/resources.json | 30 +++ evidence/restart.json | 42 ++++ evidence/smoke.txt | 1 + evidence/student-tests.json | 42 ++++ evidence/student-tests.txt | 10 + migrations/001_initial.sql | 34 +++ requirements.txt | 19 ++ scripts/bootstrap.py | 21 ++ scripts/explain.py | 30 +++ scripts/restart.cmd | 3 + scripts/restart.sh | 4 + scripts/verify.py | 77 +++++++ src/__init__.py | 0 src/app.py | 369 ++++++++++++++++++++++++++++++ src/db.py | 52 +++++ student-tests/acceptance.py | 164 +++++++++++++ 31 files changed, 1381 insertions(+), 19 deletions(-) create mode 100644 .gitattributes create mode 100644 .github/workflows/application.yml create mode 100644 Dockerfile create mode 100644 PR_DESCRIPTION.md create mode 100644 compose.yaml create mode 100644 docs/defense.md create mode 100644 docs/design.md create mode 100644 evidence/contract.txt create mode 100644 evidence/environment.json create mode 100644 evidence/load.json create mode 100644 evidence/load.txt create mode 100644 evidence/persistence.txt create mode 100644 evidence/query-plan.json create mode 100644 evidence/resources.json create mode 100644 evidence/restart.json create mode 100644 evidence/smoke.txt create mode 100644 evidence/student-tests.json create mode 100644 evidence/student-tests.txt create mode 100644 migrations/001_initial.sql create mode 100644 requirements.txt create mode 100644 scripts/bootstrap.py create mode 100644 scripts/explain.py create mode 100644 scripts/restart.cmd create mode 100755 scripts/restart.sh create mode 100644 scripts/verify.py create mode 100644 src/__init__.py create mode 100644 src/app.py create mode 100644 src/db.py create mode 100644 student-tests/acceptance.py diff --git a/.dockerignore b/.dockerignore index bc16e556..00d63edc 100644 --- a/.dockerignore +++ b/.dockerignore @@ -15,6 +15,7 @@ backups *.jks .venv __pycache__ +**/__pycache__ node_modules evidence .DS_Store diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..f49c19ef --- /dev/null +++ b/.gitattributes @@ -0,0 +1,5 @@ +*.sh text eol=lf +*.py text eol=lf +*.sql text eol=lf +*.yaml text eol=lf +Dockerfile text eol=lf diff --git a/.github/workflows/application.yml b/.github/workflows/application.yml new file mode 100644 index 00000000..bcc0321f --- /dev/null +++ b/.github/workflows/application.yml @@ -0,0 +1,23 @@ +name: Application acceptance +on: [push, pull_request] +permissions: + contents: read +jobs: + acceptance: + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: '3.12' + - run: python scripts/bootstrap.py + - run: docker compose up -d --build --wait + - run: python scripts/verify.py + - uses: actions/upload-artifact@v4 + if: always() + with: + name: acceptance-evidence + path: evidence/ + - run: docker compose down + if: always() diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 00000000..0c1da8e8 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,14 @@ +FROM python:3.12.8-slim-bookworm +WORKDIR /app +COPY requirements.txt . +RUN pip install --no-cache-dir -r requirements.txt && useradd --uid 10001 --create-home app +COPY src/ src/ +COPY migrations/ migrations/ +COPY scripts/ scripts/ +COPY tests/ tests/ +COPY contracts/ contracts/ +COPY lab.json . +ENV PYTHONUNBUFFERED=1 PYTHONDONTWRITEBYTECODE=1 +USER app +EXPOSE 8080 +CMD ["sh", "-c", "python -m src.db && exec gunicorn --bind 0.0.0.0:8080 --workers 2 --threads 4 --timeout 30 src.app:app"] diff --git a/PR_DESCRIPTION.md b/PR_DESCRIPTION.md new file mode 100644 index 00000000..243d3634 --- /dev/null +++ b/PR_DESCRIPTION.md @@ -0,0 +1,38 @@ +# ЛР 2 — БПИ2303 — Мартинес — на 4 + +Автор / группа: Мартинес Анастасия / БПИ2303. +Целевая оценка: 4. Трек 5 не заявлен. + +Реализован REST-мессенджер по контракту lab2: PostgreSQL с миграциями, +атомарным созданием чата и keyset-пагинацией; Argon2id, Basic-вход, +opaque Bearer-сессии с expiry/logout. Данные и сессии сохраняются после рестарта. +Redis кэширует неизменяемые профили с TTL, отказ кэша даёт fallback в БД. +Пул и время обращения к зависимостям ограничены, включая DNS кэша. + +Отдельный проект lab1 не предоставлялся; текстовый API реализован с нуля с +объявленным переходом lab2. Чужие студенческие решения не переносились. + +Запуск из чистого clone: + +```sh +python scripts/bootstrap.py +docker compose up -d --build --wait +python -X utf8 scripts/verify.py +``` + +Проверены публичные smoke/persistence, гонка регистрации, rollback, строгая +валидация, пагинация, expiry/logout, отказы Redis/PostgreSQL и повторные миграции. +EXPLAIN на 12 000 сообщениях использует messages_history и читает 51 строку. +Команды, результаты, нагрузочный замер и ограничения: [REPORT.md](REPORT.md), +сырые доказательства — [evidence/](evidence/). + +Ограничения: один PostgreSQL/host, нет TLS/backup/HA/rate limiting; +HTTP опубликован только на loopback. Источники — skeleton и библиотеки из +requirements.txt. Codex использован для реализации, тестов и отчёта. + +- [x] Обязательный минимум сохранён с объявленным переходом аутентификации. +- [x] Контракт и публичные тесты не ослаблены. +- [x] Выполнены Python-команды, эквивалентные make check/test; приложен вывод. +- [x] Сценарии сохранности и отказов уровня 4 воспроизведены. +- [x] Секреты вне Git, токены в evidence не записываются. +- [x] README задания сохранён, REPORT.md содержит инструкцию решения. diff --git a/REPORT.md b/REPORT.md index e42f2b05..48e0552a 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,163 @@ # Отчёт — лабораторная 2 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +Автор: Мартинес Анастасия, БПИ2303. Целевая оценка: **4**; трек 5 не заявлен. +Ветка: `solution/bpi2303-martines`. Публикация PR ожидает доступа к fork. ## Запуск из чистого clone -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +Нужны Git, Python 3.9+ и работающий Docker Engine с Compose v2. +На Windows — Docker Desktop в режиме Linux containers. Все команды выполняются +из корня этого репозитория; соседние лабы и внешняя БД не нужны. + +```sh +python scripts/bootstrap.py +docker compose config --quiet +docker compose up -d --build --wait +python -X utf8 scripts/verify.py +``` + +Bootstrap генерирует локальные случайные credentials и создаёт игнорируемые +`secrets/db_password`, `secrets/database_url`, `.env`. Повторный запуск +их не перезаписывает. Не коммитить эти файлы. API: http://127.0.0.1:8080, +готовность: /health/ready. Библиотеки на хост для этих проверок не нужны. +Стенд использует только синтетические тестовые данные. + +Версии: Python 3.12.8 slim-bookworm, PostgreSQL 16.6 bookworm, Redis 7.4.1 +bookworm. Все Python-зависимости закреплены в requirements.txt. +Gunicorn: 2 worker × 4 thread. Миграции выполняются до запуска API. + +Отдельные проверки: + +```sh +python scripts/check_contract.py +python tests/smoke.py --base-url http://127.0.0.1:8080 +python tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://127.0.0.1:8080 +python student-tests/acceptance.py +docker compose exec -T api python scripts/explain.py +``` + +В Windows для persistence использовать `scripts/restart.cmd`; verify.py +выбирает hook автоматически. restart.sh хранится с executable bit. +GNU Make запускает те же проверки: `make check`, +`make test BASE_URL=http://127.0.0.1:8080`, +`make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://127.0.0.1:8080`. +Полная OpenAPI-валидация: установить requirements-dev.txt в отдельный venv, +затем `python scripts/validate_openapi.py`. + +Остановка с сохранением данных: `docker compose down`. +Намеренное удаление **всех учебных данных этой лабы**: `docker compose down -v`. +Hook перезапуска volumes не удаляет. Новый запуск после удаления volume создаёт +пустую схему; прежние пользователи и токены не восстанавливаются. ## Архитектура и решения -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab1, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +Клиент → Flask/Gunicorn → PostgreSQL; Redis кэширует публичный профиль. +Схема, ограничения, индексы и границы транзакций: [docs/design.md](docs/design.md). + +Реализованы текстовые endpoint lab1 с переходом lab2 на password/Basic/Bearer. +Отдельный исходный проект lab1 не предоставлялся: код написан с нуля по контракту +lab2, чужие студенческие решения не переносились. Контракт и публичные tests +остались без изменений. + +PostgreSQL — источник истины для пользователей, чатов, членства, сообщений, +сессий; данные сохраняются в именованном pgdata. Пароли — Argon2id (19 MiB, +2 прохода, parallelism=1), opaque-токены — 32 случайных байта, в БД только SHA-256. +SESSION_TTL_SECONDS задаёт абсолютный expiry, по умолчанию 3600. Logout удаляет +текущую сессию; рестарт не продлевает её срок. + +Redis хранит неизменяемый публичный профиль `profile:v1:` на 60 с. +Редактирования профиля в API нет: инвалидация по TTL и версии ключа; при добавлении +редактирования понадобится отдельная стратегия. Сессии и история не кэшируются. +Каждый защищённый запрос проверяет PostgreSQL, поэтому тёплый кэш не отменяет +logout/expiry. Подтверждённые сообщения сразу видны новому чтению истории. +Redis persistence не нужен: потеря кэша вызывает чтение из PostgreSQL. + +Пул: максимум 8 соединений на worker, суммарно 16; очередь до 32 на worker. +Pool/connect/statement timeout 3 с, lock timeout 2 с. Redis socket timeout 0.2 с; +wall timeout операции 0.25 с также ограничивает ожидание DNS. Фоновых операций +кэша максимум две на worker, очереди нет; при исчерпании слотов кэш пропускается. +SQL параметризован. Составные операции выполняются в транзакциях, 201 — после COMMIT. + +Сопоставление .env.example: DATABASE_URL_FILE используется напрямую; +CACHE_URL_FILE поддерживается загрузчиком, Compose задаёт несекретный CACHE_URL; +SESSION_STORE=postgres фиксирован архитектурой. APP_HOST/APP_PORT заменены +явным bind Gunicorn 0.0.0.0:8080; хостовый порт только 127.0.0.1. APP_ENV +не влияет на поведение. Секреты и volumes исключены из Git и build context. ## Доказательства критериев -| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | -| --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | +Общий воспроизводимый запуск: `python -X utf8 scripts/verify.py`. +PASS учитывается только после завершения соответствующей команды; +сырые результаты сохраняются в evidence/. -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +| Критерий | Сценарий | Доказательство | +| --- | --- | --- | +| Контракт и текстовый API | Публичный smoke | evidence/smoke.txt | +| Сохранность данных и прежнего токена | Публичный persistence, restart api/db/redis | evidence/persistence.txt, evidence/restart.json | +| PK/FK/UNIQUE и атомарность | FK-ошибка второго участника; число чатов/участников не меняется | migrations/001_initial.sql, evidence/student-tests.json | +| Гонка регистрации | 8 одновременных запросов: один 201, семь 409 | evidence/student-tests.json | +| Повторяемые миграции | Повторное применение; число пользователей/версий не меняется | evidence/student-tests.json | +| KDF, expiry, logout | Unicode/двоеточие в пароле, неверный пароль, TTL=2, тёплый кэш | src/app.py, evidence/student-tests.json | +| Реальное использование Redis | TTL профиля ≤60, остановка и восстановление | evidence/student-tests.json | +| Пул/таймауты/отказы | Остановка БД: ограниченный 503, live=200, затем прежняя сессия | src/db.py, evidence/student-tests.json | +| Индекс на ≥10 000 сообщений | EXPLAIN ANALYZE BUFFERS на 12 000 сообщений | evidence/query-plan.json | +| Keyset и доступ | Изменение limit, чужой cursor, совпадение timestamp, чужой чат | evidence/student-tests.json | +| Структура skeleton | check_contract.py | evidence/contract.txt | ## Эксперименты и отказы -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. +Гипотеза: индекс (chat_id,created_at,id) позволяет читать позднюю страницу +без сканирования всей истории. scripts/explain.py создаёт 12 000 сообщений, +делает ANALYZE, выбирает pivot после 10 000 строк и выполняет реальный запрос +API с LIMIT 51. OFFSET используется только при выборе экспериментального +pivot, в API его нет. Фикстуры откатываются после измерения. JSON содержит +actual rows/time и buffers; это эксперимент уровня 4, сравнение индексов +и backup/restore уровня 5 не заявлены. -| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | -| --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +Наблюдение: Index Scan по messages_history, actual rows=51, shared hit blocks=4, +shared read blocks=0, Execution Time=0.278 мс. Прогретые страницы находились +в памяти; время не характеризует холодный диск. Полного Seq Scan/Sort в плане нет. -## Ограничения и следующие шаги +Нагрузка: один closed-loop запуск, 30 с, concurrency=4, POST сообщений, +без прозрачных retry и без отдельного фиксированного прогрева. Стенд перед +замером уже выполнял functional tests; история нагрузочного чата растёт. +evidence/load.json содержит successes/errors, RPS, p50/p95/p99. +CPU/RAM снимаются во время нагрузки в evidence/resources.json. -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +Результат 19.11.2026: 6843 успешных запроса за 30.141 с, ошибок 0, +227.033 успешных RPS; p50=16 мс, p95=32 мс, p99=47 мс. +По семи выборкам Docker stats: API до 129.85% CPU и 198.5 MiB RAM, +PostgreSQL до 36.85% CPU и 39.2 MiB, Redis до 0.49% CPU и 8.312 MiB. +100% в Docker stats соответствует одному логическому CPU; выборки не являются +непрерывным измерением пиков. В нагрузочном чате создано 6843 сообщения. + +Хост: Windows, около 15.75 GiB доступной ОС физической RAM (16 GiB номинально); +CPU/ОС — evidence/environment.json. Docker Engine 26.1.4, Compose 2.27.1. +Лимиты: API 2 CPU/512 MiB, PostgreSQL 1 CPU/512 MiB, Redis 0.5 CPU/128 MiB. + +| Воздействие | Ожидание | Проверка | +| --- | --- | --- | +| Перезапуск API, БД, Redis | Прежний токен читает прежнее сообщение | persistence и StartedAt всех трёх контейнеров | +| Остановка Redis | Fallback в БД, ready=200, анонимный запрос не получает профиль | acceptance, затем start redis | +| Остановка PostgreSQL | 503 для me/ready, live=200; восстановление с прежним токеном | acceptance, затем start db | +| TTL=2 | После ожидания 401 даже с тёплым кэшем | Отдельный временный API на 8081 | + +В первом прогоне отказ Redis выявил, что socket timeout не ограничивает +разрешение Docker DNS. Добавлен wall timeout с ограниченным executor; +окончательные evidence соответствуют успешному повторному прогону исправления. +Один нагрузочный повтор на ноутбуке не измеряет максимум производительности: +closed-loop страдает coordinated omission, latency учитывает успешные запросы. + +## Ограничения и источники + +Один host и один PostgreSQL не обеспечивают HA. Проверяется перезапуск +с сохранением диска, а не потеря узла/volume. Нет backup, TLS, rate limiting, +автоматической очистки истёкших сессий и ротации секретов. +Cursor не фиксирует snapshot между запросами: поздний COMMIT с ранним timestamp +может оказаться позади cursor; детали — docs/design.md. + +Источники: контракт/публичные проверки skeleton; Flask, Gunicorn, Psycopg, +Redis-py, argon2-cffi; материалы по PostgreSQL и Redis из README задания. +Помощь ИИ: Codex подготовил код, инфраструктуру, собственные тесты, выполнение +проверок и отчёт. Автору необходимо понимать решение для защиты; +памятка: [docs/defense.md](docs/defense.md). diff --git a/compose.yaml b/compose.yaml new file mode 100644 index 00000000..088a2f72 --- /dev/null +++ b/compose.yaml @@ -0,0 +1,48 @@ +name: vp-lab2 +services: + api: + build: . + ports: + - "127.0.0.1:8080:8080" + environment: + DATABASE_URL_FILE: /run/secrets/database_url + CACHE_URL: redis://redis:6379/0 + SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600} + secrets: [database_url] + depends_on: + db: + condition: service_healthy + healthcheck: + test: [CMD, python, -c, "import urllib.request; urllib.request.urlopen('http://localhost:8080/health/ready', timeout=5)"] + interval: 5s + timeout: 6s + retries: 12 + mem_limit: 512m + cpus: 2 + db: + image: postgres:16.6-bookworm + environment: + POSTGRES_USER: messenger + POSTGRES_DB: messenger + POSTGRES_PASSWORD_FILE: /run/secrets/db_password + secrets: [db_password] + volumes: [pgdata:/var/lib/postgresql/data] + healthcheck: + test: [CMD-SHELL, "pg_isready -U messenger -d messenger"] + interval: 3s + timeout: 3s + retries: 20 + mem_limit: 512m + cpus: 1 + redis: + image: redis:7.4.1-bookworm + command: [redis-server, --maxmemory, 64mb, --maxmemory-policy, allkeys-lru, --save, "", --appendonly, "no"] + mem_limit: 128m + cpus: 0.5 +volumes: + pgdata: +secrets: + db_password: + file: ./secrets/db_password + database_url: + file: ./secrets/database_url diff --git a/docs/defense.md b/docs/defense.md new file mode 100644 index 00000000..ff071fa7 --- /dev/null +++ b/docs/defense.md @@ -0,0 +1,48 @@ +# Коротко для защиты + +## Что реализовано + +REST-мессенджер без интерфейса: регистрация, вход, чаты, сообщения, история, +выход. Flask принимает HTTP, PostgreSQL хранит данные, Redis ускоряет чтение +публичного профиля. Контракт лабораторной 2 сохранён. + +## Основные вопросы + +**Почему PostgreSQL, а не словарь в Python?** Словарь пропадёт при перезапуске +и будет разным у разных процессов. PostgreSQL сохраняет подтверждённые записи +в WAL; именованный Docker volume сохраняет файлы при пересоздании контейнера. + +**Что означает COMMIT?** Транзакция завершена. При стандартных fsync=on и +synchronous_commit=on PostgreSQL ждёт записи WAL. Это не резервная копия: +потеря диска/volume или всего компьютера всё ещё может уничтожить данные. + +**Аутентификация и авторизация?** Bearer-сессия отвечает «кто ты», членство в +чате — «доступен ли тебе этот чат». Чужой чат возвращает 404, чтобы не выдавать +его существование. Переданный X-User-Id игнорируется. + +**Что хранится вместо пароля?** Argon2id с солью, 19 MiB памяти, два прохода, +parallelism=1. Соль хранится в кодированной строке вместе с параметрами. +SHA-256 здесь непригоден для пароля: слишком быстро перебирается. +Для случайного токена с 256 битами энтропии SHA-256 допустим. + +**Почему Basic только при входе?** Basic передаёт кодированный username:password. +После входа клиент получает случайный Bearer token. Ни Basic, ни Bearer сами +по себе не шифруют сеть; стенд слушает только loopback, вне ноутбука нужен TLS. + +**Что при flush или остановке Redis?** Исчезает только кэш профилей. Проверка +сессии и её expiry идёт в PostgreSQL на каждом запросе. Профиль читается из БД. +Сессии не становятся бессрочными, отозванный токен не оживает. + +**Зачем составной индекс?** WHERE ограничивает chat_id; далее индекс уже +упорядочен по created_at,id. Можно начать после cursor и прочитать 51 запись, +вместо пропуска тысяч строк через OFFSET. UUID разрешает совпадения времени. + +**Почему создание чата атомарно?** Вставка чата и всех членов находится в одной +транзакции. Ошибка последнего FK откатывает также чат и предыдущих членов. + +**Что обеспечивает гонку регистрации?** UNIQUE(username) в БД. Проверка +SELECT перед INSERT сама по себе была бы недостаточна: два потока могли бы +одновременно увидеть отсутствие имени. Один INSERT проходит, остальные — 409. + +**Что ещё не production-ready?** Нет HA БД, backup, rate limiting, очистки +истёкших сессий, TLS и ротации секретов. Это предмет следующих улучшений. diff --git a/docs/design.md b/docs/design.md new file mode 100644 index 00000000..391f7451 --- /dev/null +++ b/docs/design.md @@ -0,0 +1,38 @@ +# Схема и границы транзакций + +План до реализации SQL: пользователи → участники ← чаты → сообщения; +пользователи → сессии. PostgreSQL — источник истины всех этих данных. +UUID назначает приложение, UTC-время — PostgreSQL. Пароль — Argon2id; +сессия содержит только SHA-256 случайного 256-битного токена и абсолютный expiry. + +Ограничения: PK у объектов, UNIQUE username, составной PK членства, +FK сообщений на чат и членство отправителя, NOT NULL и ограничения длины. +Индексы: members(user_id,chat_id) для списка чатов; +messages(chat_id,created_at,id) для истории; sessions(token_hash) для входа. + +Транзакции: регистрация; создание сессии; отзыв сессии; создание чата вместе +со всеми участниками; запись сообщения. Ответ 201 формируется после COMMIT. +Ошибка FK участника откатывает чат и уже вставленных участников. +Уникальность username разрешает гонку на уровне БД, проигравший получает 409. +Миграции сериализованы advisory lock, версия и checksum сохраняются в БД. + +История: keyset `(created_at,id) > (...)`, LIMIT n+1, без OFFSET. Cursor содержит +область запроса (чат либо пользователь списка чатов), время и UUID. Cursor не +предоставляет права доступа. Каждое чтение повторно проверяет членство. +READ COMMITTED не даёт snapshot между страницами: поздно завершившаяся вставка +с более ранним временем может оказаться позади cursor. Подтверждённые записи +видны новому чтению с начала истории; часы не заменяют уникальность UUID. + +Redis кэширует только публичный неизменяемый профиль на 60 секунд. В API нет +редактирования профиля: инвалидация по TTL и версии ключа `profile:v1`. +Если добавить редактирование, понадобится отдельная стратегия инвалидации. +Авторизация всегда проверяет PostgreSQL, даже при cache hit. Logout удаляет +сессию из БД; кэш профиля не является доказательством входа. Redis не требует +persistence: cache miss/рестарт/отказ дают чтение из PostgreSQL. Socket timeout +Redis 0.2 с. Дополнительно wall timeout 0.25 с на GET/SET включает зависание DNS: +не более двух фоновых операций на worker, без очереди. При занятых слотах +кэш пропускается. История сообщений не кэшируется. + +Пул: максимум 8 соединений на worker, 2 worker, очередь до 32 на worker, +ожидание до 3 секунд. connect/statement timeout 3 секунды, lock timeout 2. +Недоступная БД — 503, readiness — 503, liveness остаётся 200. diff --git a/evidence/contract.txt b/evidence/contract.txt new file mode 100644 index 00000000..b62af9c5 --- /dev/null +++ b/evidence/contract.txt @@ -0,0 +1 @@ +PASS: offline skeleton structure, local refs and Python syntax; application NOT tested. diff --git a/evidence/environment.json b/evidence/environment.json new file mode 100644 index 00000000..b56ba4b6 --- /dev/null +++ b/evidence/environment.json @@ -0,0 +1,7 @@ +{ + "observed_at": "2026-11-19T07:45:37.469958+00:00", + "platform": "Windows-11-10.0.26200-SP0", + "cpu": "Intel64 Family 6 Model 186 Stepping 2, GenuineIntel", + "logical_cpus": 16, + "python": "3.12.3" +} \ No newline at end of file diff --git a/evidence/load.json b/evidence/load.json new file mode 100644 index 00000000..623fa77b --- /dev/null +++ b/evidence/load.json @@ -0,0 +1,17 @@ +{ + "lab": 2, + "workload": "closed-loop POST messages; no automatic retries", + "requested_duration_seconds": 30.0, + "elapsed_seconds": 30.141, + "concurrency": 4, + "successful_requests": 6843, + "failed_requests": 0, + "error_ratio": 0.0, + "successful_rps": 227.033, + "successful_latency_ms": { + "p50": 16.0, + "p95": 32.0, + "p99": 47.0 + }, + "note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead." +} diff --git a/evidence/load.txt b/evidence/load.txt new file mode 100644 index 00000000..623fa77b --- /dev/null +++ b/evidence/load.txt @@ -0,0 +1,17 @@ +{ + "lab": 2, + "workload": "closed-loop POST messages; no automatic retries", + "requested_duration_seconds": 30.0, + "elapsed_seconds": 30.141, + "concurrency": 4, + "successful_requests": 6843, + "failed_requests": 0, + "error_ratio": 0.0, + "successful_rps": 227.033, + "successful_latency_ms": { + "p50": 16.0, + "p95": 32.0, + "p99": 47.0 + }, + "note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead." +} diff --git a/evidence/persistence.txt b/evidence/persistence.txt new file mode 100644 index 00000000..749fd29b --- /dev/null +++ b/evidence/persistence.txt @@ -0,0 +1,2 @@ +Executing explicit persistence hook; hook output suppressed to avoid leaking secrets. +PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence. diff --git a/evidence/query-plan.json b/evidence/query-plan.json new file mode 100644 index 00000000..a5290e83 --- /dev/null +++ b/evidence/query-plan.json @@ -0,0 +1,79 @@ +{ + "dataset_messages": 12000, + "cursor_position": 10001, + "page_size_with_lookahead": 51, + "plan": [ + { + "Plan": { + "Node Type": "Limit", + "Parallel Aware": false, + "Async Capable": false, + "Startup Cost": 0.29, + "Total Cost": 9.88, + "Plan Rows": 51, + "Plan Width": 69, + "Actual Startup Time": 0.034, + "Actual Total Time": 0.07, + "Actual Rows": 51, + "Actual Loops": 1, + "Shared Hit Blocks": 4, + "Shared Read Blocks": 0, + "Shared Dirtied Blocks": 0, + "Shared Written Blocks": 0, + "Local Hit Blocks": 0, + "Local Read Blocks": 0, + "Local Dirtied Blocks": 0, + "Local Written Blocks": 0, + "Temp Read Blocks": 0, + "Temp Written Blocks": 0, + "Plans": [ + { + "Node Type": "Index Scan", + "Parent Relationship": "Outer", + "Parallel Aware": false, + "Async Capable": false, + "Scan Direction": "Forward", + "Index Name": "messages_history", + "Relation Name": "messages", + "Alias": "messages", + "Startup Cost": 0.29, + "Total Cost": 376.82, + "Plan Rows": 2002, + "Plan Width": 69, + "Actual Startup Time": 0.031, + "Actual Total Time": 0.055, + "Actual Rows": 51, + "Actual Loops": 1, + "Index Cond": "((chat_id = 'eae5d1d7-e003-4d8c-a4c1-f37ad80710a2'::uuid) AND (ROW(created_at, id) > ROW('2026-01-01 00:00:00.010001+00'::timestamp with time zone, 'f0612713-b9fe-4956-aa1c-cf82a0a2b6d1'::uuid)))", + "Rows Removed by Index Recheck": 0, + "Shared Hit Blocks": 4, + "Shared Read Blocks": 0, + "Shared Dirtied Blocks": 0, + "Shared Written Blocks": 0, + "Local Hit Blocks": 0, + "Local Read Blocks": 0, + "Local Dirtied Blocks": 0, + "Local Written Blocks": 0, + "Temp Read Blocks": 0, + "Temp Written Blocks": 0 + } + ] + }, + "Planning": { + "Shared Hit Blocks": 6, + "Shared Read Blocks": 0, + "Shared Dirtied Blocks": 0, + "Shared Written Blocks": 0, + "Local Hit Blocks": 0, + "Local Read Blocks": 0, + "Local Dirtied Blocks": 0, + "Local Written Blocks": 0, + "Temp Read Blocks": 0, + "Temp Written Blocks": 0 + }, + "Planning Time": 0.444, + "Triggers": [], + "Execution Time": 0.278 + } + ] +} diff --git a/evidence/resources.json b/evidence/resources.json new file mode 100644 index 00000000..80965bcb --- /dev/null +++ b/evidence/resources.json @@ -0,0 +1,30 @@ +[ + { + "at": "2026-11-19T07:45:07.042984+00:00", + "stats": "vp-lab2-api-1: CPU=51.83% RAM=191.3MiB / 512MiB\nvp-lab2-db-1: CPU=30.30% RAM=36.62MiB / 512MiB\nvp-lab2-redis-1: CPU=0.35% RAM=8.184MiB / 128MiB" + }, + { + "at": "2026-11-19T07:45:11.716348+00:00", + "stats": "vp-lab2-api-1: CPU=129.85% RAM=191.4MiB / 512MiB\nvp-lab2-db-1: CPU=31.61% RAM=36.92MiB / 512MiB\nvp-lab2-redis-1: CPU=0.30% RAM=8.309MiB / 128MiB" + }, + { + "at": "2026-11-19T07:45:16.440752+00:00", + "stats": "vp-lab2-api-1: CPU=120.48% RAM=198.5MiB / 512MiB\nvp-lab2-db-1: CPU=28.59% RAM=37.76MiB / 512MiB\nvp-lab2-redis-1: CPU=0.30% RAM=8.18MiB / 128MiB" + }, + { + "at": "2026-11-19T07:45:21.214682+00:00", + "stats": "vp-lab2-api-1: CPU=116.05% RAM=194.3MiB / 512MiB\nvp-lab2-db-1: CPU=36.85% RAM=38.11MiB / 512MiB\nvp-lab2-redis-1: CPU=0.34% RAM=8.312MiB / 128MiB" + }, + { + "at": "2026-11-19T07:45:26.096036+00:00", + "stats": "vp-lab2-api-1: CPU=110.50% RAM=194.3MiB / 512MiB\nvp-lab2-db-1: CPU=32.46% RAM=38.22MiB / 512MiB\nvp-lab2-redis-1: CPU=0.46% RAM=8.184MiB / 128MiB" + }, + { + "at": "2026-11-19T07:45:30.786451+00:00", + "stats": "vp-lab2-api-1: CPU=106.21% RAM=194.3MiB / 512MiB\nvp-lab2-db-1: CPU=25.58% RAM=39.02MiB / 512MiB\nvp-lab2-redis-1: CPU=0.49% RAM=8.184MiB / 128MiB" + }, + { + "at": "2026-11-19T07:45:35.469509+00:00", + "stats": "vp-lab2-api-1: CPU=97.16% RAM=194.4MiB / 512MiB\nvp-lab2-db-1: CPU=25.32% RAM=39.2MiB / 512MiB\nvp-lab2-redis-1: CPU=0.35% RAM=8.184MiB / 128MiB" + } +] \ No newline at end of file diff --git a/evidence/restart.json b/evidence/restart.json new file mode 100644 index 00000000..098040c6 --- /dev/null +++ b/evidence/restart.json @@ -0,0 +1,42 @@ +{ + "before": [ + { + "name": "/vp-lab2-api-1", + "id": "51df1ca0997fb8365713bda1153f7b7ebef1318d8fe7ae6114cc4279bd83114f", + "started_at": "2026-11-19T07:44:22.242015528Z", + "image": "vp-lab2-api" + }, + { + "name": "/vp-lab2-db-1", + "id": "a4de1828985dbb6c23694508e62dbd58e8fac0c8227dbee0b86af55b7f6d7296", + "started_at": "2026-11-19T07:40:10.782456786Z", + "image": "postgres:16.6-bookworm" + }, + { + "name": "/vp-lab2-redis-1", + "id": "cdd92a6517e3be5377b268f66e5ddf3ac650e3e60c87ef091555f25dc25e7440", + "started_at": "2026-11-19T07:41:58.069227011Z", + "image": "redis:7.4.1-bookworm" + } + ], + "after": [ + { + "name": "/vp-lab2-api-1", + "id": "51df1ca0997fb8365713bda1153f7b7ebef1318d8fe7ae6114cc4279bd83114f", + "started_at": "2026-11-19T07:44:33.62888078Z", + "image": "vp-lab2-api" + }, + { + "name": "/vp-lab2-db-1", + "id": "a4de1828985dbb6c23694508e62dbd58e8fac0c8227dbee0b86af55b7f6d7296", + "started_at": "2026-11-19T07:44:33.00388505Z", + "image": "postgres:16.6-bookworm" + }, + { + "name": "/vp-lab2-redis-1", + "id": "cdd92a6517e3be5377b268f66e5ddf3ac650e3e60c87ef091555f25dc25e7440", + "started_at": "2026-11-19T07:44:33.018097101Z", + "image": "redis:7.4.1-bookworm" + } + ] +} \ No newline at end of file diff --git a/evidence/smoke.txt b/evidence/smoke.txt new file mode 100644 index 00000000..92154196 --- /dev/null +++ b/evidence/smoke.txt @@ -0,0 +1 @@ +PASS: lab2 public API scenario; infrastructure and grading evidence remain separate. diff --git a/evidence/student-tests.json b/evidence/student-tests.json new file mode 100644 index 00000000..422ea7a9 --- /dev/null +++ b/evidence/student-tests.json @@ -0,0 +1,42 @@ +[ + { + "test": "concurrent registration: one 201, seven 409", + "result": "PASS" + }, + { + "test": "foreign-key failure rolls back chat and first member", + "result": "PASS" + }, + { + "test": "strict payload validation and authentication before resource access", + "result": "PASS" + }, + { + "test": "keyset pagination, changing limit, cross-chat cursor rejection", + "result": "PASS" + }, + { + "test": "equal timestamps use UUID tie breaker", + "result": "PASS" + }, + { + "test": "Unicode/colon password, wrong password, cache TTL and logout with warm cache", + "result": "PASS" + }, + { + "test": "Redis outage falls back safely and cache recovers", + "result": "PASS" + }, + { + "test": "DB outage fails closed with 503; same session works after recovery", + "result": "PASS" + }, + { + "test": "SESSION_TTL_SECONDS=2 expires a warm-cache session", + "result": "PASS" + }, + { + "test": "migrations are repeatable without duplicate data", + "result": "PASS" + } +] diff --git a/evidence/student-tests.txt b/evidence/student-tests.txt new file mode 100644 index 00000000..a155e9ee --- /dev/null +++ b/evidence/student-tests.txt @@ -0,0 +1,10 @@ +PASS: concurrent registration: one 201, seven 409 +PASS: foreign-key failure rolls back chat and first member +PASS: strict payload validation and authentication before resource access +PASS: keyset pagination, changing limit, cross-chat cursor rejection +PASS: equal timestamps use UUID tie breaker +PASS: Unicode/colon password, wrong password, cache TTL and logout with warm cache +PASS: Redis outage falls back safely and cache recovers +PASS: DB outage fails closed with 503; same session works after recovery +PASS: SESSION_TTL_SECONDS=2 expires a warm-cache session +PASS: migrations are repeatable without duplicate data diff --git a/migrations/001_initial.sql b/migrations/001_initial.sql new file mode 100644 index 00000000..093ce411 --- /dev/null +++ b/migrations/001_initial.sql @@ -0,0 +1,34 @@ +CREATE TABLE users ( + id uuid PRIMARY KEY, + username varchar(32) NOT NULL UNIQUE CHECK (username ~ '^[a-z0-9_]{3,32}$'), + display_name varchar(100) NOT NULL CHECK (length(trim(display_name)) > 0), + password_hash text NOT NULL, + created_at timestamptz NOT NULL DEFAULT clock_timestamp() +); +CREATE TABLE chats ( + id uuid PRIMARY KEY, + title varchar(100) NOT NULL CHECK (length(trim(title)) > 0), + created_at timestamptz NOT NULL DEFAULT clock_timestamp() +); +CREATE TABLE members ( + chat_id uuid NOT NULL REFERENCES chats(id), + user_id uuid NOT NULL REFERENCES users(id), + PRIMARY KEY (chat_id, user_id) +); +CREATE INDEX members_user_chat ON members(user_id, chat_id); +CREATE INDEX chats_history ON chats(created_at, id); +CREATE TABLE messages ( + id uuid PRIMARY KEY, + chat_id uuid NOT NULL REFERENCES chats(id), + sender_id uuid NOT NULL REFERENCES users(id), + text varchar(4000) NOT NULL CHECK (length(trim(text)) > 0), + created_at timestamptz NOT NULL DEFAULT clock_timestamp(), + FOREIGN KEY (chat_id, sender_id) REFERENCES members(chat_id, user_id) +); +CREATE INDEX messages_history ON messages(chat_id, created_at, id); +CREATE TABLE sessions ( + token_hash char(64) PRIMARY KEY, + user_id uuid NOT NULL REFERENCES users(id), + expires_at timestamptz NOT NULL +); +CREATE INDEX sessions_expiry ON sessions(expires_at); diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 00000000..474e8e80 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,19 @@ +Flask==3.1.0 +gunicorn==23.0.0 +psycopg[binary,pool]==3.2.3 +redis==5.2.1 +argon2-cffi==23.1.0 +# Transitive dependencies pinned to the verified Linux/Python 3.12 environment. +argon2-cffi-bindings==26.2.0 +blinker==1.9.0 +cffi==2.1.1 +click==8.5.1 +itsdangerous==2.2.0 +Jinja2==3.1.6 +MarkupSafe==3.0.4 +packaging==26.3 +psycopg-binary==3.2.3 +psycopg-pool==3.3.3 +pycparser==3.12 +typing_extensions==4.16.0 +Werkzeug==3.1.9 diff --git a/scripts/bootstrap.py b/scripts/bootstrap.py new file mode 100644 index 00000000..e22aeaa7 --- /dev/null +++ b/scripts/bootstrap.py @@ -0,0 +1,21 @@ +"""Create local synthetic secrets once; never overwrite existing credentials.""" +import secrets +from pathlib import Path + +root = Path(__file__).resolve().parents[1] +directory = root / 'secrets' +directory.mkdir(exist_ok=True) +password_file = directory / 'db_password' +if not password_file.exists(): + with password_file.open('x', encoding='utf-8') as file: + file.write(secrets.token_urlsafe(32)) +password = password_file.read_text(encoding='utf-8').strip() +url_file = directory / 'database_url' +if not url_file.exists(): + with url_file.open('x', encoding='utf-8') as file: + file.write('postgresql://messenger:' + password + '@db:5432/messenger') +env = root / '.env' +if not env.exists(): + with env.open('x', encoding='utf-8') as file: + file.write('SESSION_TTL_SECONDS=3600\n') +print('Local configuration ready; credentials are not printed.') diff --git a/scripts/explain.py b/scripts/explain.py new file mode 100644 index 00000000..dabd1e87 --- /dev/null +++ b/scripts/explain.py @@ -0,0 +1,30 @@ +"""Real query-plan experiment with 12,000 messages; transaction rolls back fixtures.""" +import json +import sys +import uuid +from pathlib import Path +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) +from src.db import make_pool + +pool = make_pool() +with pool.connection() as conn: + user_id, chat_id = uuid.uuid4(), uuid.uuid4() + conn.execute('INSERT INTO users(id,username,display_name,password_hash) VALUES (%s,%s,%s,%s)', + (user_id, 'plan_' + uuid.uuid4().hex[:20], 'Synthetic EXPLAIN', 'no-login')) + conn.execute('INSERT INTO chats(id,title) VALUES (%s,%s)', (chat_id, 'EXPLAIN dataset')) + conn.execute('INSERT INTO members VALUES (%s,%s)', (chat_id, user_id)) + conn.execute("INSERT INTO messages(id,chat_id,sender_id,text,created_at) " + "SELECT gen_random_uuid(),%s,%s,'message ' || n, " + "'2026-01-01'::timestamptz + n * interval '1 microsecond' " + "FROM generate_series(1,12000) n", (chat_id, user_id)) + conn.execute('ANALYZE messages') + pivot = conn.execute('SELECT created_at,id FROM messages WHERE chat_id=%s ' + 'ORDER BY created_at,id OFFSET 10000 LIMIT 1', (chat_id,)).fetchone() + plan = conn.execute('EXPLAIN (ANALYZE,BUFFERS,FORMAT JSON) SELECT * FROM messages ' + 'WHERE chat_id=%s AND (created_at,id)>(%s,%s) ' + 'ORDER BY created_at,id LIMIT 51', + (chat_id, pivot['created_at'], pivot['id'])).fetchone()['QUERY PLAN'] + print(json.dumps({'dataset_messages': 12000, 'cursor_position': 10001, + 'page_size_with_lookahead': 51, 'plan': plan}, indent=2, default=str)) + conn.rollback() +pool.close() diff --git a/scripts/restart.cmd b/scripts/restart.cmd new file mode 100644 index 00000000..9d62a46d --- /dev/null +++ b/scripts/restart.cmd @@ -0,0 +1,3 @@ +@echo off +cd /d "%~dp0.." +docker compose restart api db redis diff --git a/scripts/restart.sh b/scripts/restart.sh new file mode 100755 index 00000000..6bde700e --- /dev/null +++ b/scripts/restart.sh @@ -0,0 +1,4 @@ +#!/bin/sh +set -eu +cd "$(dirname "$0")/.." +docker compose restart api db redis diff --git a/scripts/verify.py b/scripts/verify.py new file mode 100644 index 00000000..eff7c02c --- /dev/null +++ b/scripts/verify.py @@ -0,0 +1,77 @@ +"""Run acceptance evidence on the local Compose stack; no secrets in artifacts.""" +import json +import os +import platform +import subprocess +import sys +import time +from datetime import datetime, timezone +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +EVIDENCE = ROOT / 'evidence' +ENV = {**os.environ, 'PYTHONUTF8': '1', + 'BASE_URL': os.environ.get('BASE_URL', 'http://127.0.0.1:8080')} + + +def run(args, artifact=None): + result = subprocess.run(args, cwd=ROOT, text=True, encoding='utf-8', errors='replace', + capture_output=True, env=ENV) + output = result.stdout + result.stderr + print(output, end='', flush=True) + if artifact: + (EVIDENCE / artifact).write_text(output, encoding='utf-8') + if result.returncode: + raise SystemExit(result.returncode) + return result.stdout + + +def containers(): + ids = run(['docker', 'compose', 'ps', '-q']).split() + result = subprocess.run(['docker', 'inspect', *ids], cwd=ROOT, text=True, + capture_output=True, check=True) + return [{'name': item['Name'], 'id': item['Id'], + 'started_at': item['State']['StartedAt'], 'image': item['Config']['Image']} + for item in json.loads(result.stdout)] + + +def main(): + run([sys.executable, 'scripts/check_contract.py'], 'contract.txt') + run([sys.executable, 'tests/smoke.py'], 'smoke.txt') + before = containers() + hook = 'scripts/restart.cmd' if os.name == 'nt' else 'scripts/restart.sh' + run([sys.executable, 'tests/resilience.py', '--mode', 'persistence', + '--action-script', hook], 'persistence.txt') + after = containers() + prior = {item['id']: item for item in before} + assert len(after) == 3 and all(item['id'] in prior and + item['started_at'] != prior[item['id']]['started_at'] + for item in after), 'All three containers must really restart' + (EVIDENCE / 'restart.json').write_text(json.dumps({'before': before, 'after': after}, indent=2), encoding='utf-8') + run([sys.executable, 'student-tests/acceptance.py'], 'student-tests.txt') + run(['docker', 'compose', 'exec', '-T', 'api', 'python', 'scripts/explain.py'], 'query-plan.json') + process = subprocess.Popen([sys.executable, 'tests/load.py', '--duration', '30', '--concurrency', '4', + '--output', 'evidence/load.json'], cwd=ROOT, + stdout=subprocess.PIPE, stderr=subprocess.STDOUT, + text=True, encoding='utf-8', env=ENV) + ids = [item['id'] for item in after] + samples = [] + while process.poll() is None: + stats = subprocess.run(['docker', 'stats', '--no-stream', '--format', + '{{.Name}}: CPU={{.CPUPerc}} RAM={{.MemUsage}}', *ids], + capture_output=True, text=True, check=True) + samples.append({'at': datetime.now(timezone.utc).isoformat(), 'stats': stats.stdout.strip()}) + time.sleep(2) + output = process.communicate()[0] + print(output, end='', flush=True) + (EVIDENCE / 'load.txt').write_text(output, encoding='utf-8') + (EVIDENCE / 'resources.json').write_text(json.dumps(samples, indent=2), encoding='utf-8') + if process.returncode: + raise SystemExit(process.returncode) + system = {'observed_at': datetime.now(timezone.utc).isoformat(), 'platform': platform.platform(), + 'cpu': platform.processor(), 'logical_cpus': os.cpu_count(), 'python': platform.python_version()} + (EVIDENCE / 'environment.json').write_text(json.dumps(system, indent=2), encoding='utf-8') + + +if __name__ == '__main__': + main() diff --git a/src/__init__.py b/src/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/src/app.py b/src/app.py new file mode 100644 index 00000000..9091838d --- /dev/null +++ b/src/app.py @@ -0,0 +1,369 @@ +"""Lab 2 API: PostgreSQL is authoritative; Redis caches immutable public profiles.""" +import base64 +import binascii +import hashlib +import json +import os +import re +import secrets +import uuid +from concurrent.futures import ThreadPoolExecutor, TimeoutError as FutureTimeout +from datetime import datetime +from threading import BoundedSemaphore + +import psycopg +import redis +from argon2 import PasswordHasher +from argon2.exceptions import VerificationError +from flask import Flask, g, jsonify, request +from psycopg_pool import PoolTimeout, TooManyRequests +from werkzeug.exceptions import HTTPException + +from src.db import make_pool, setting + +app = Flask(__name__) +app.config['MAX_CONTENT_LENGTH'] = 65536 +pool = make_pool() +cache = redis.Redis.from_url(setting('CACHE_URL'), socket_connect_timeout=0.2, + socket_timeout=0.2, decode_responses=True) +cache_executor = ThreadPoolExecutor(max_workers=2, thread_name_prefix='cache') +cache_slots = BoundedSemaphore(2) +hasher = PasswordHasher(time_cost=2, memory_cost=19456, parallelism=1) +dummy_hash = hasher.hash(secrets.token_urlsafe(32)) +SESSION_TTL = int(os.getenv('SESSION_TTL_SECONDS', '3600')) +if SESSION_TTL < 1: + raise ValueError('SESSION_TTL_SECONDS must be positive') +USER_FIELDS = 'id, username, display_name, created_at' + + +class APIError(Exception): + def __init__(self, status, code, message, challenge=None): + self.status, self.code, self.message, self.challenge = status, code, message, challenge + + +def invalid(): + raise APIError(400, 'invalid_request', 'Invalid request') + + +def unauthorized(basic=False): + challenge = 'Basic realm="messenger", charset="UTF-8"' if basic else 'Bearer realm="messenger"' + raise APIError(401, 'unauthorized', 'Authentication required', challenge) + + +def serial(value): + if isinstance(value, dict): + return {key: serial(item) for key, item in value.items()} + if isinstance(value, list): + return [serial(item) for item in value] + if isinstance(value, uuid.UUID): + return str(value) + if isinstance(value, datetime): + return value.isoformat().replace('+00:00', 'Z') + return value + + +def response(value, status=200): + return jsonify(serial(value)), status + + +@app.before_request +def identify_request(): + g.request_id = uuid.uuid4().hex + + +@app.after_request +def headers(result): + result.headers['X-Request-Id'] = g.request_id + result.headers['Cache-Control'] = 'no-store' + return result + + +@app.errorhandler(Exception) +def error(exc): + if isinstance(exc, APIError): + problem = exc + elif isinstance(exc, psycopg.errors.UniqueViolation): + problem = APIError(409, 'conflict', 'Username already exists') + elif isinstance(exc, psycopg.errors.ForeignKeyViolation): + problem = APIError(400, 'invalid_request', 'Invalid member list') + elif isinstance(exc, (psycopg.OperationalError, PoolTimeout, TooManyRequests, + psycopg.errors.QueryCanceled, psycopg.errors.LockNotAvailable)): + problem = APIError(503, 'unavailable', 'Database temporarily unavailable') + elif isinstance(exc, HTTPException): + status = exc.code if exc.code in (400, 404, 413, 415) else 400 + code = {400: 'invalid_request', 404: 'not_found', 413: 'payload_too_large', + 415: 'unsupported_media_type'}[status] + problem = APIError(status, code, 'Request cannot be processed') + else: + app.logger.error('Unhandled error type=%s request_id=%s', type(exc).__name__, g.request_id) + problem = APIError(500, 'internal_error', 'Internal error') + result = jsonify(error={'code': problem.code, 'message': problem.message, + 'request_id': g.request_id}) + result.status_code = problem.status + if problem.challenge: + result.headers['WWW-Authenticate'] = problem.challenge + return result + + +def body(fields): + if request.mimetype != 'application/json': + raise APIError(415, 'unsupported_media_type', 'Expected application/json') + value = request.get_json() + if not isinstance(value, dict) or set(value) != set(fields): + invalid() + return value + + +def string(value, minimum, maximum): + if not isinstance(value, str) or not minimum <= len(value) <= maximum or not value.strip(): + invalid() + try: + value.encode('utf-8') + except UnicodeError: + invalid() + if '\x00' in value: + invalid() + return value + + +def uid(value): + try: + if not isinstance(value, str) or not re.fullmatch( + r'[0-9a-fA-F]{8}(?:-[0-9a-fA-F]{4}){3}-[0-9a-fA-F]{12}', value): + invalid() + return uuid.UUID(value) + except ValueError: + invalid() + + +def cached_operation(operation, *args, **kwargs): + # Socket timeouts do not bound DNS resolution when a Compose service is down. + # At most two background operations per worker, no unbounded queue. + if not cache_slots.acquire(blocking=False): + return None + future = cache_executor.submit(operation, *args, **kwargs) + future.add_done_callback(lambda _: cache_slots.release()) + try: + return future.result(timeout=0.25) + except (redis.RedisError, FutureTimeout): + return None + + +def profile(conn, user_id): + key = 'profile:v1:' + str(user_id) + cached = cached_operation(cache.get, key) + if cached: + try: + return json.loads(cached) + except ValueError: + pass + user = serial(conn.execute('SELECT ' + USER_FIELDS + ' FROM users WHERE id=%s', + (user_id,)).fetchone()) + if user is None: + unauthorized() + cached_operation(cache.set, key, json.dumps(user), ex=60) + return user + + +def actor(conn): + auth = request.headers.get('Authorization', '').split() + if len(auth) != 2 or auth[0].lower() != 'bearer' or len(auth[1]) > 256: + unauthorized() + digest = hashlib.sha256(auth[1].encode()).hexdigest() + session = conn.execute('SELECT user_id FROM sessions WHERE token_hash=%s ' + 'AND expires_at > clock_timestamp()', (digest,)).fetchone() + if not session: + unauthorized() + g.token_hash = digest + return session['user_id'] + + +def chat_access(conn, chat_id, user_id): + chat = conn.execute('SELECT c.* FROM chats c JOIN members m ON m.chat_id=c.id ' + 'WHERE c.id=%s AND m.user_id=%s', (chat_id, user_id)).fetchone() + if not chat: + raise APIError(404, 'not_found', 'Resource not found') + return chat + + +def chat_members(conn, chat): + chat['member_ids'] = [row['user_id'] for row in conn.execute( + 'SELECT user_id FROM members WHERE chat_id=%s ORDER BY user_id', (chat['id'],))] + return chat + + +def page_args(scope): + limit = request.args.get('limit', '50') + if not re.fullmatch(r'[0-9]{1,3}', limit) or not 1 <= int(limit) <= 100: + invalid() + cursor = request.args.get('cursor') + after = None + if cursor is not None: + try: + if len(cursor) > 1024: + invalid() + data = json.loads(base64.b64decode(cursor, altchars=b'-_', validate=True)) + if not isinstance(data, list) or len(data) != 3 or data[0] != scope: + invalid() + date = datetime.fromisoformat(data[1]) + if date.tzinfo is None: + invalid() + after = (date, uid(data[2])) + except (ValueError, TypeError, binascii.Error): + invalid() + return int(limit), after + + +def page(rows, limit, scope): + more = len(rows) > limit + items = rows[:limit] + cursor = None + if more: + last = serial(items[-1]) + cursor = base64.urlsafe_b64encode(json.dumps( + [scope, last['created_at'], last['id']]).encode()).decode() + return {'items': items, 'next_cursor': cursor} + + +@app.get('/health/live') +def live(): + return response({'status': 'ok'}) + + +@app.get('/health/ready') +def ready(): + with pool.connection() as conn: + conn.execute('SELECT 1 FROM schema_migrations LIMIT 1') + return response({'status': 'ok'}) + + +@app.post('/api/v1/users') +def register(): + data = body(('username', 'display_name', 'password')) + name = string(data['username'], 3, 32) + if not re.fullmatch('[a-z0-9_]{3,32}', name): + invalid() + display = string(data['display_name'], 1, 100) + password = string(data['password'], 12, 128) + encoded = hasher.hash(password) + with pool.connection() as conn: + user = conn.execute('INSERT INTO users (id,username,display_name,password_hash) ' + 'VALUES (%s,%s,%s,%s) RETURNING ' + USER_FIELDS, + (uuid.uuid4(), name, display, encoded)).fetchone() + return response(user, 201) + + +@app.post('/api/v1/auth/sessions') +def login(): + auth = request.headers.get('Authorization', '').split() + if len(auth) != 2 or auth[0].lower() != 'basic' or len(auth[1]) > 2048: + unauthorized(True) + try: + name, password = base64.b64decode(auth[1], validate=True).decode('utf-8').split(':', 1) + except (ValueError, UnicodeError, binascii.Error): + unauthorized(True) + if not re.fullmatch('[a-z0-9_]{3,32}', name) or not 12 <= len(password) <= 128: + unauthorized(True) + if request.get_data(): + invalid() + with pool.connection() as conn: + user = conn.execute('SELECT * FROM users WHERE username=%s', (name,)).fetchone() + try: + hasher.verify(user['password_hash'] if user else dummy_hash, password) + except VerificationError: + unauthorized(True) + if not user: + unauthorized(True) + token = secrets.token_urlsafe(32) + with pool.connection() as conn: + expiry = conn.execute('INSERT INTO sessions VALUES (%s,%s,clock_timestamp() ' + '+ %s * interval \'1 second\') RETURNING expires_at', + (hashlib.sha256(token.encode()).hexdigest(), user['id'], + SESSION_TTL)).fetchone()['expires_at'] + user.pop('password_hash') + return response({'token': token, 'token_type': 'Bearer', 'expires_at': expiry, 'user': user}, 201) + + +@app.delete('/api/v1/auth/sessions/current') +def logout(): + with pool.connection() as conn: + actor(conn) + conn.execute('DELETE FROM sessions WHERE token_hash=%s', (g.token_hash,)) + return '', 204 + + +@app.get('/api/v1/users/me') +def me(): + with pool.connection() as conn: + user = profile(conn, actor(conn)) + return response(user) + + +@app.post('/api/v1/chats') +def create_chat(): + with pool.connection() as conn: + user = actor(conn) + data = body(('title', 'member_ids')) + title = string(data['title'], 1, 100) + if not isinstance(data['member_ids'], list) or not 1 <= len(data['member_ids']) <= 100: + invalid() + members = [uid(item) for item in data['member_ids']] + if len(set(members)) != len(members) or user not in members: + invalid() + chat = conn.execute('INSERT INTO chats(id,title) VALUES (%s,%s) RETURNING *', + (uuid.uuid4(), title)).fetchone() + for member in members: + conn.execute('INSERT INTO members VALUES (%s,%s)', (chat['id'], member)) + chat['member_ids'] = sorted(members) + return response(chat, 201) + + +@app.get('/api/v1/chats') +def list_chats(): + with pool.connection() as conn: + user = actor(conn) + scope = 'chats:' + str(user) + limit, after = page_args(scope) + sql = 'SELECT c.* FROM chats c JOIN members m ON m.chat_id=c.id WHERE m.user_id=%s' + params = [user] + if after: + sql += ' AND (c.created_at,c.id) > (%s,%s)' + params.extend(after) + rows = conn.execute(sql + ' ORDER BY c.created_at,c.id LIMIT %s', params + [limit+1]).fetchall() + result = page(rows, limit, scope) + for chat in result['items']: + chat_members(conn, chat) + return response(result) + + +@app.get('/api/v1/chats/') +def get_chat(chat_id): + with pool.connection() as conn: + user = actor(conn) + result = chat_members(conn, chat_access(conn, uid(chat_id), user)) + return response(result) + + +@app.route('/api/v1/chats//messages', methods=['GET', 'POST']) +def messages(chat_id): + with pool.connection() as conn: + user = actor(conn) + chat_id = uid(chat_id) + chat_access(conn, chat_id, user) + if request.method == 'POST': + text = string(body(('text',))['text'], 1, 4000) + result = conn.execute('INSERT INTO messages(id,chat_id,sender_id,text) ' + 'VALUES (%s,%s,%s,%s) RETURNING *', + (uuid.uuid4(), chat_id, user, text)).fetchone() + status = 201 + else: + scope = 'messages:' + str(chat_id) + limit, after = page_args(scope) + sql = 'SELECT * FROM messages WHERE chat_id=%s' + params = [chat_id] + if after: + sql += ' AND (created_at,id) > (%s,%s)' + params.extend(after) + rows = conn.execute(sql + ' ORDER BY created_at,id LIMIT %s', params + [limit+1]).fetchall() + result, status = page(rows, limit, scope), 200 + return response(result, status) diff --git a/src/db.py b/src/db.py new file mode 100644 index 00000000..19cf69cb --- /dev/null +++ b/src/db.py @@ -0,0 +1,52 @@ +"""Bounded PostgreSQL pool and serialized, versioned migrations.""" +import hashlib +import os +import time +from pathlib import Path + +import psycopg +from psycopg.rows import dict_row +from psycopg_pool import ConnectionPool + + +def setting(name): + path = os.getenv(name + '_FILE') + return Path(path).read_text().strip() if path else os.environ[name] + + +def migrate(): + with psycopg.connect(setting('DATABASE_URL'), connect_timeout=3) as conn: + conn.execute('SELECT pg_advisory_xact_lock(202602)') + conn.execute('CREATE TABLE IF NOT EXISTS schema_migrations ' + '(version text PRIMARY KEY, checksum text NOT NULL)') + for file in sorted(Path('migrations').glob('*.sql')): + sql = file.read_text(encoding='utf-8') + digest = hashlib.sha256(sql.encode()).hexdigest() + row = conn.execute('SELECT checksum FROM schema_migrations WHERE version=%s', + (file.name,)).fetchone() + if row: + if row[0] != digest: + raise RuntimeError('Applied migration changed') + continue + conn.execute(sql) + conn.execute('INSERT INTO schema_migrations VALUES (%s,%s)', (file.name, digest)) + + +def make_pool(): + return ConnectionPool(setting('DATABASE_URL'), min_size=1, max_size=8, + timeout=3, max_waiting=32, + check=ConnectionPool.check_connection, + kwargs={'connect_timeout': 3, 'row_factory': dict_row, + 'options': '-c statement_timeout=3000 -c lock_timeout=2000'}) + + +if __name__ == '__main__': + for attempt in range(30): + try: + migrate() + break + except psycopg.OperationalError: + if attempt == 29: + raise RuntimeError('Database did not become available') from None + time.sleep(2) + print('Migrations applied successfully') diff --git a/student-tests/acceptance.py b/student-tests/acceptance.py new file mode 100644 index 00000000..f4cd08d5 --- /dev/null +++ b/student-tests/acceptance.py @@ -0,0 +1,164 @@ +"""Additional black-box checks. Run against this repository's synthetic stack.""" +import base64 +import json +import subprocess +import sys +import time +import uuid +from concurrent.futures import ThreadPoolExecutor +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(ROOT / 'tests')) +from client import Client, check + + +def docker(*args, input=None): + result = subprocess.run(['docker', 'compose', *args], cwd=ROOT, input=input, + text=True, capture_output=True, timeout=120) + check(result.returncode == 0, 'Docker operation failed: ' + ' '.join(args[:2])) + return result.stdout.strip() + + +def sql(query): + return docker('exec', '-T', 'db', 'psql', '-U', 'messenger', '-d', 'messenger', + '-At', '-v', 'ON_ERROR_STOP=1', input=query) + + +def wait_ready(client): + end = time.monotonic() + 90 + while time.monotonic() < end: + try: + client.call('GET', '/health/ready', schema='Health') + return + except Exception: + time.sleep(0.5) + raise AssertionError('API did not recover') + + +def main(): + c = Client() + results = [] + + def passed(name): + results.append({'test': name, 'result': 'PASS'}) + print('PASS:', name, flush=True) + + alice, bob, eve, chat = c.bootstrap() + endpoint = '/api/v1/chats/' + chat['id'] + '/messages' + registration = {'username': 'race_' + uuid.uuid4().hex[:16], + 'display_name': 'Гонка', 'password': 'Synthetic:пароль-1234'} + + def register(_): + return Client().call('POST', '/api/v1/users', [201, 409], body=registration)['status'] + + with ThreadPoolExecutor(max_workers=8) as executor: + codes = list(executor.map(register, range(8))) + check(codes.count(201) == 1 and codes.count(409) == 7, 'Registration race') + passed('concurrent registration: one 201, seven 409') + + before = sql('SELECT (SELECT count(*) FROM chats), (SELECT count(*) FROM members);') + c.call('POST', '/api/v1/chats', 400, actor=alice, + body={'title': 'Rollback', 'member_ids': [alice['id'], str(uuid.uuid4())]}) + after = sql('SELECT (SELECT count(*) FROM chats), (SELECT count(*) FROM members);') + check(before == after, 'Partial chat or membership committed') + passed('foreign-key failure rolls back chat and first member') + + for bad in ({'text': ' '}, {'text': 42}, {'text': 'x', 'sender_id': eve['id']}, + {'text': 'x' * 4001}): + c.call('POST', endpoint, 400, actor=alice, body=bad) + c.call('POST', endpoint, 400, actor=alice, raw=b'{broken', + headers={'Content-Type': 'application/json'}) + c.call('POST', endpoint, 415, actor=alice, raw=b'text', + headers={'Content-Type': 'text/plain'}) + c.call('GET', '/api/v1/chats/bad/messages', 401) + c.call('GET', '/api/v1/chats/bad/messages', 400, actor=alice) + c.call('POST', endpoint, 404, actor=eve, body={'text': 'hidden'}) + passed('strict payload validation and authentication before resource access') + + messages = [c.message(alice, chat, 'Пагинация ' + str(i))['json'] for i in range(7)] + first = c.call('GET', endpoint + '?limit=2', actor=bob, schema='MessagePage')['json'] + other = c.call('POST', '/api/v1/chats', 201, actor=alice, + body={'title': 'Другой', 'member_ids': [alice['id']]}, schema='Chat')['json'] + from urllib.parse import quote + cursor = quote(first['next_cursor'], safe='') + c.call('GET', '/api/v1/chats/' + other['id'] + '/messages?cursor=' + cursor, 400, actor=alice) + collected = first['items'] + while first['next_cursor']: + first = c.call('GET', endpoint + '?limit=3&cursor=' + quote(first['next_cursor'], safe=''), + actor=bob, schema='MessagePage')['json'] + collected.extend(first['items']) + check(collected == messages, 'Pagination duplicated or skipped data') + passed('keyset pagination, changing limit, cross-chat cursor rejection') + + # Identical timestamps exercise UUID as the second ordering component. + sql("UPDATE messages SET created_at='2026-01-01T00:00:00Z' WHERE chat_id='" + chat['id'] + "';") + current, collected = endpoint + '?limit=2', [] + while current: + chunk = c.call('GET', current, actor=alice, schema='MessagePage')['json'] + collected.extend(chunk['items']) + current = endpoint + '?limit=2&cursor=' + quote(chunk['next_cursor'], safe='') if chunk['next_cursor'] else None + check([x['id'] for x in collected] == sorted(x['id'] for x in messages), 'Timestamp tie pagination') + passed('equal timestamps use UUID tie breaker') + + basic = base64.b64encode((registration['username'] + ':' + registration['password']).encode()).decode() + c.call('POST', '/api/v1/auth/sessions', 201, headers={'Authorization': 'Basic ' + basic}, schema='Session') + bad = base64.b64encode((registration['username'] + ':wrong-password-long').encode()).decode() + c.call('POST', '/api/v1/auth/sessions', 401, headers={'Authorization': 'Basic ' + bad}) + c.call('GET', '/api/v1/users/me', actor=alice, schema='User') + ttl = int(docker('exec', '-T', 'redis', 'redis-cli', 'TTL', 'profile:v1:' + alice['id'])) + check(0 < ttl <= 60, 'Redis profile cache has no bounded TTL') + c.call('DELETE', '/api/v1/auth/sessions/current', 204, actor=alice) + c.call('GET', '/api/v1/users/me', 401, actor=alice) + passed('Unicode/colon password, wrong password, cache TTL and logout with warm cache') + + try: + docker('stop', 'redis') + start = time.monotonic() + c.call('GET', '/api/v1/users/me', actor=bob, schema='User') + check(time.monotonic() - start < 5, 'Unbounded Redis failure') + c.call('GET', '/api/v1/users/me', 401) + c.call('GET', '/health/ready', schema='Health') + finally: + docker('start', 'redis') + c.call('GET', '/api/v1/users/me', actor=bob, schema='User') + passed('Redis outage falls back safely and cache recovers') + + try: + docker('stop', 'db') + start = time.monotonic() + c.call('GET', '/api/v1/users/me', 503, actor=bob) + check(time.monotonic() - start < 8, 'Unbounded DB failure') + c.call('GET', '/health/ready', 503) + c.call('GET', '/health/live', schema='Health') + finally: + docker('start', 'db') + wait_ready(c) + c.call('GET', '/api/v1/users/me', actor=bob, schema='User') + passed('DB outage fails closed with 503; same session works after recovery') + + # A separate short-TTL process leaves the normal API configuration unchanged. + container = docker('run', '--rm', '-d', '--no-deps', '-p', '127.0.0.1:8081:8080', + '-e', 'SESSION_TTL_SECONDS=2', 'api') + try: + short = Client('http://127.0.0.1:8081') + wait_ready(short) + actor = short.user('expiry') + short.call('GET', '/api/v1/users/me', actor=actor, schema='User') + time.sleep(2.2) + short.call('GET', '/api/v1/users/me', 401, actor=actor) + finally: + subprocess.run(['docker', 'stop', container], check=True, capture_output=True, timeout=30) + passed('SESSION_TTL_SECONDS=2 expires a warm-cache session') + + counts = sql('SELECT (SELECT count(*) FROM users), (SELECT count(*) FROM schema_migrations);') + docker('exec', '-T', 'api', 'python', '-m', 'src.db') + check(counts == sql('SELECT (SELECT count(*) FROM users), (SELECT count(*) FROM schema_migrations);'), + 'Repeated migration changed data') + passed('migrations are repeatable without duplicate data') + (ROOT / 'evidence' / 'student-tests.json').write_text( + json.dumps(results, ensure_ascii=False, indent=2) + '\n', encoding='utf-8') + + +if __name__ == '__main__': + main() -- 2.54.0