1 Commits
Author SHA1 Message Date
Polina_Zhirnova 256d8b9035 merge done project from github
Skeleton contracts / contracts (pull_request) Canceled after 0s
2026-11-13 10:56:52 +03:00
30 changed files with 1261 additions and 46 deletions
+1 -13
View File
@@ -1,20 +1,8 @@
.git
.github
.env
.env.*
!.env.example
secrets
certs
volumes
data
backups
*.key
*.pem
*.p12
*.pfx
*.jks
.venv
__pycache__
node_modules
*.pyc
evidence
.DS_Store
+3 -9
View File
@@ -1,11 +1,5 @@
# Copy to .env for your LOCAL synthetic test environment; never commit .env.
# These are logical interface suggestions; map actual framework names in REPORT.md.
APP_HOST=0.0.0.0
# Generate actual local values using python scripts/init_env.py
APP_PORT=8080
APP_ENV=lab
SESSION_TTL_SECONDS=3600
# Choose credentials locally. File paths contain no secret values.
DATABASE_URL_FILE=/run/secrets/database_url
# Optional on 3, required use on 4 in lab2; Redis OR Valkey:
SESSION_STORE=postgres
CACHE_URL_FILE=/run/secrets/cache_url
POSTGRES_PASSWORD=GENERATE_WITH_INIT_ENV
CURSOR_SECRET=GENERATE_WITH_INIT_ENV
+2
View File
@@ -0,0 +1,2 @@
*.sh text eol=lf
*.py text eol=lf
+28
View File
@@ -0,0 +1,28 @@
# Что сделано и что встретилось при проверке
## Изменения приложения
1. Перенесено поведение Python-версии ЛР1 на PostgreSQL; словари не используются как хранилище.
2. Добавлены пароли Argon2id, Basic-вход, Bearer-сессии, срок действия и выход.
3. Добавлены FK/UNIQUE, атомарный чат, параметризованные запросы и ограниченный пул.
4. Добавлен реальный Redis-кэш публичного профиля с TTL и обходом при недоступности.
5. Пагинация перенесена из сортировки Python-списков в индексированный SQL.
6. Добавлены миграции, Dockerfile, Compose, генерация .env, сценарии перезапуска и проверки.
7. Исходный контракт и публичные тесты сохранены побайтово.
## Практические замечания из подготовки
- В среде подготовки не было Docker: вместо выдуманного результата сборки проверен
отдельный native-стенд с PostgreSQL/Redis. Compose остаётся проверить на компьютере студентки.
- Среда не позволяла Unix-сокет PostgreSQL. Для native-проверки оставлено TCP 127.0.0.1.
В Compose такое специальное изменение не требуется.
- Обычный SIGTERM PostgreSQL выполняет smart shutdown и ждёт клиентов. В native-тесте
используется SIGINT (fast shutdown), завершающий соединения перед остановкой.
- Redis в пакете ОС запускался через символическую ссылку. Разрешение ссылки меняло
имя запуска на redis-check-rdb и включало другой режим программы. Native-скрипт
сохраняет имя redis-server. Контейнерный запуск этого обхода не требует.
- Redis-пул ограничен 16 соединениями, автоматические повторы выключены: отказ кэша
не должен вызывать долгие повторные подключения перед чтением PostgreSQL.
- Не включён встроенный limit_concurrency Uvicorn: его собственный 503 обходил бы
формат ошибки и X-Request-Id приложения. Ограничены пул БД и дорогие парольные операции.
- Проблема использования порта 8080 связанная с разработкой на PHP
+9
View File
@@ -0,0 +1,9 @@
FROM python:3.12.10-slim-bookworm
WORKDIR /app
ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1
COPY requirements.txt requirements.lock.txt ./
RUN pip install --no-cache-dir -r requirements.lock.txt && useradd --uid 10001 --create-home appuser
COPY . .
USER 10001
EXPOSE 8080
CMD ["python", "run.py"]
+167
View File
@@ -0,0 +1,167 @@
# Лабораторная 2 простыми словами
## Главная идея
В первой лабораторной сервер держал пользователей, чаты и сообщения в словарях Python.
Закрыли процесс — содержимое памяти пропало. Во второй лабораторной данные находятся
в PostgreSQL: перезапускаем программу, а история остаётся. Кроме того, теперь нельзя
просто написать чужой ID в заголовке и стать этим человеком: нужен пароль и сессия.
Сервер по-прежнему не рисует окошко мессенджера. Он получает HTTP-запросы и возвращает JSON.
Проверяющая программа играет роль клиента: регистрируется, входит, создаёт чат и пишет сообщения.
Alice, Bob и Eve — вымышленные пользователи теста; Eve проверяет доступ постороннего.
## Кто за что отвечает
| Часть | Простое объяснение | Где смотреть |
| --- | --- | --- |
| FastAPI | Принимает запрос и вызывает подходящую Python-функцию | main.py |
| Uvicorn | Процесс, который слушает порт 8080 и запускает FastAPI | run.py |
| PostgreSQL | Постоянное хранилище всех важных данных | migrations/001_initial.sql |
| Psycopg | Передаёт SQL-запросы из Python в PostgreSQL | db.py и main.py |
| Redis | Быстрая временная копия публичного профиля | profile() в main.py |
| Argon2id | Превращает пароль в специальный проверочный хеш | create_user(), login() |
| Docker Compose | Запускает API, PostgreSQL и Redis вместе | compose.yaml |
## Как работает вход
1. При регистрации передаём имя, отображаемое имя и пароль.
2. Сервер получает Argon2id-хеш пароля и записывает его в users. Сам пароль не сохраняет.
3. При входе клиент отправляет `Authorization: Basic ...` — закодированные имя и пароль.
Base64 НЕ шифрует данные. Здесь HTTP используется только на локальном учебном стенде.
4. Сервер проверяет пароль и выдаёт случайный токен. Это как временный пропуск.
5. Следующие запросы передают `Authorization: Bearer <токен>`.
6. Сервер ищет хеш токена в sessions и проверяет срок действия. По умолчанию пропуск на час.
7. При выходе запись сессии удаляется. Старый токен больше не работает.
В таблице sessions лежит SHA-256 токена, а не сам токен. Здесь быстрый SHA-256 допустим:
токен уже содержит 256 бит случайности. Для придуманного человеком пароля нужен медленный
password KDF: пароли гораздо проще перебирать. Argon2id добавляет случайную соль самостоятельно.
Одинаковые пароли поэтому не обязаны иметь одинаковые сохранённые хеши.
## Аутентификация и права — разные проверки
Аутентификация отвечает: «Кто ты?» — проверяется сессия.
Авторизация отвечает: «Можно ли тебе в этот чат?» — проверяется таблица members.
Даже настоящий пользователь с правильным токеном не может читать чужой чат.
Для постороннего возвращаем 404, чтобы не раскрывать даже существование этого чата.
Нет действительной сессии — 401. Сначала проверяем сессию, затем конкретный ресурс.
## Что лежит в таблицах
- users: ID, уникальное имя, отображаемое имя, хеш пароля и время регистрации.
- sessions: хеш пропуска, владелец, время окончания действия.
- chats: ID, название, время создания.
- members: пары «чат — участник».
- messages: ID сообщения, чат, отправитель, текст и время.
- schema_migrations: список уже применённых версий схемы и их контрольные суммы.
Первичный ключ — уникальный идентификатор строки. Внешний ключ — ссылка на существующую
строку другой таблицы. Например, участником нельзя записать несуществующего пользователя.
UNIQUE(username) не позволяет двум регистрациям одновременно занять одно имя.
Проверка «сначала посмотрим, свободно ли имя» сама по себе от гонки не защищает:
два запроса могут одновременно увидеть «свободно». Последнее слово за ограничением БД.
## Зачем транзакция
Создание чата состоит из нескольких INSERT: сам чат и его участники.
Если третий участник оказался несуществующим, оставлять половину чата нельзя.
Транзакция объединяет действия: либо все сохраняются (COMMIT), либо все отменяются (ROLLBACK).
В коде блок `async with app.state.pool.connection() as conn` выдаёт соединение.
При нормальном выходе незавершённая транзакция фиксируется; при исключении откатывается.
Ответ 201 для записи возвращаем после выхода из блока — то есть после успешного COMMIT.
Это не гарантия против потери всего диска: сохранность также зависит от диска, настроек БД и backup.
## Что такое pool
Соединение с БД — канал общения. Создавать новый канал для каждого запроса дорого.
Пул хранит несколько готовых каналов и выдаёт их запросам по очереди.
У нас максимум 10 соединений на процесс API, ожидание до 3 секунд и очередь до 32 ожиданий.
SQL выполняется с таймаутом 3 секунды, ожидание блокировки — до 2 секунд.
Это ограничивает потребление ресурсов и не позволяет зависнуть бесконечно.
`async/await` позволяет обслуживать другие запросы, пока один ждёт ответ БД.
Тяжёлая проверка пароля вынесена в отдельный поток; одновременно допускается до четырёх таких операций.
## Зачем Redis, если есть PostgreSQL
После входа клиент может часто спрашивать «покажи мой профиль». В Redis на 60 секунд
кладём копию публичных данных профиля. Следующий запрос может получить её оттуда.
Источник истины — PostgreSQL. Кэш можно потерять и восстановить из БД.
Проверку сессии всё равно делаем в PostgreSQL на каждом защищённом запросе.
Поэтому Redis не может превратить отозванный токен в действующий.
Профили в этом API не редактируются: инвалидация сейчас — TTL 60 секунд или удаление ключа.
Если добавить редактирование профиля, потребуется согласовать обновление БД и сброс кэша.
Историю сообщений не кэшируем, поэтому после подтверждённой записи читаем свежую БД.
Redis здесь помогает только с чтением профиля, а не устраняет все запросы к БД.
Ускорение всего сервиса не измерялось; не надо говорить на защите, что он стал «в разы быстрее».
## Почему история читается страницами
В одном чате может быть очень много сообщений. Возвращать их все сразу тяжело.
Клиент просит, например, 50 сообщений. Сервер отдаёт их и cursor — закладку для следующей страницы.
Внутри закладки — время и ID последнего сообщения, чат и подпись от подделки.
Клиенту не нужно понимать этот формат: он просто возвращает строку серверу.
SQL ищет сообщения нужного чата ПОСЛЕ пары `(created_at, id)` из закладки.
Индекс `(chat_id, created_at, id)` похож на заранее отсортированный указатель.
Он позволяет перейти к нужному месту. Для этого не нужно каждый раз пропускать первые
9000 сообщений, как при OFFSET 9000. В эксперименте OFFSET используется только один раз
для выбора тестовой закладки, в рабочих endpoint его нет.
EXPLAIN ANALYZE показывает, что БД действительно сделала, а не то, что мы надеялись получить.
В приложенном эксперименте 12 000 сообщений: используется Index Scan по messages_history.
Время из этого эксперимента — не универсальная скорость сервера и не результат нагрузочного теста.
Порядок задаётся временем БД и UUID. На неизменной истории повторов при обходе нет.
При одновременных записях это не снимок на всё время чтения: поздно завершённая транзакция
или перевод часов назад могут добавить запись раньше уже выданной закладки.
## Что будет при сбоях
| Ситуация | Результат |
| --- | --- |
| Перезапустили API | Данные и действующие сессии сохранились в PostgreSQL |
| Перезапустили все контейнеры | Именованные volumes сохраняют данные |
| Redis остановлен | Профиль читаем из PostgreSQL; доступ не становится анонимным |
| PostgreSQL остановлен | Защищённые запросы дают 503; выдавать данные только по кэшу нельзя |
| Токен просрочен или отозван | 401 |
| Чужой чат | 404 |
| Занятое имя | 409 |
`/health/live` говорит «процесс жив». `/health/ready` говорит «БД доступна, могу работать».
Поэтому при выключенной БД live возвращает 200, ready — 503.
## Что изменилось по сравнению с первой лабораторной
Сохранены пользователи, чаты, сообщения, проверка участников, ошибки JSON, request ID,
лимиты полей и постраничное чтение. Словари и общий Python-lock заменены таблицами,
ограничениями и транзакциями. X-User-Id больше не даёт доступ.
Лимиты общего числа записей из in-memory версии убраны: теперь ограничение — ресурсы хранилища.
Старый локальный token-bucket не переносился: rate limiting в обязательный минимум не входит.
Имеющиеся в старом архиве данные автоматически не импортируются: формат и аутентификация изменились.
## Короткие ответы для защиты
**Почему PostgreSQL, а не файл или SQLite?** Так требует задание; БД даёт транзакции,
ограничения связности, индексы и работу нескольких клиентов.
**Зачем миграции?** Это версии структуры БД: из пустой БД получаем нужные таблицы.
Повторный запуск видит, что 001 уже применена, и не создаёт всё заново.
Старую применённую миграцию не редактируем: для изменений добавляем следующую.
**Как защищаемся от SQL-инъекций?** Значения передаются отдельно от текста SQL через `%s`.
Это параметры Psycopg, а не Python-подстановка строки. Имена таблиц не берём от клиента.
**Почему не хранить сессии только в памяти?** Они исчезнут при перезапуске и не будут общими
для разных процессов. Здесь сессии и их исходный expires_at сохранены в PostgreSQL.
**TTL продлевается при рестарте?** Нет. Сохранено абсолютное время окончания сессии.
**Что доказывает smoke?** Один основной сценарий API. Он не доказывает все отказы,
производительность или Docker-запуск. Поэтому есть дополнительные проверки и evidence.
**Почему оценка 4, а не 5?** Для 5 нужно отдельное законченное исследование из README,
а здесь реализованы критерии 3 и 4 и подготовлены их проверки.
+143 -22
View File
@@ -1,37 +1,158 @@
# Отчёт — лабораторная 2
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
- Автор, группа: Жирнова Полина БВТ2304.
- Целевая оценка: **4**. Исследовательский трек на 5 не заявлен.
- Commit/PR: заполнить после публикации.
- Основа: контракт ЛР2 и Python/FastAPI-реализация из приложенного архива ЛР1.
## Запуск из чистого clone
## Запуск
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
Подробная инструкция: Docker Desktop/Engine с Compose v2 (поддержкой --wait),
Python 3.9+ для внешних проверок. API в образе использует Python 3.12.10.
Образы: postgres:17.5-bookworm, redis:7.4.4-bookworm. Версии закреплены тегами, не digest.
Библиотеки сервера закреплены в requirements.txt, полный проверенный набор — requirements.lock.txt.
## Архитектура и решения
```sh
python3 scripts/init_env.py
docker compose config --quiet
docker compose up -d --build --wait
python3 tests/smoke.py
python3 scripts/verify.py
```
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab1, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
Windows: `py` вместо `python3`. Проверки запускаются из корня проекта.
Миграции применяются при старте API, вручную создавать таблицы не нужно.
Повторно проверяются контрольные суммы; изменение применённого SQL останавливает старт.
Локальный .env создаётся один раз со случайными паролем PostgreSQL и ключом подписи cursor.
Файлы секретов также поддерживаются для DATABASE_URL, CACHE_URL, CURSOR_SECRET через суффикс _FILE.
Compose передаёт эти значения через environment. APP_HOST и APP_PORT читает run.py;
APP_ENV=lab — обозначение среды, поведение не переключает. SESSION_STORE не используется:
источник сессий всегда PostgreSQL. CACHE_URL — адрес Redis, не хранилища сессий.
## Доказательства критериев
Остановка: `docker compose down`. Возобновление: `docker compose up -d --wait`.
**Намеренное удаление всех учебных данных: `docker compose down -v`.** Для рестарта не использовать.
PostgreSQL и Redis не публикуют порты на хост; API опубликован только на 127.0.0.1.
API работает под UID 10001. Пользователь PostgreSQL в учебном образе владеет БД;
разделение роли мигратора и ограниченной роли приложения — дальнейшее улучшение.
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
## Архитектура и схема
Клиент обращается к API. API проверяет сессию в PostgreSQL и участника в members.
Все важные данные и действующие сессии — в PostgreSQL. Redis содержит только
неизменяемые публичные профили (`profile:v1:<uuid>`, TTL 60 секунд).
История не кэшируется; read-after-write обеспечивается чтением той же основной БД после COMMIT.
| Таблица | Ключи и ограничения | Назначение |
| --- | --- | --- |
| users | PK id; UNIQUE username; CHECK формата имени | Пользователь и Argon2id-хеш |
| sessions | PK token_hash; FK user_id → users | Пропуск и абсолютный expires_at |
| chats | PK id | Чат |
| members | PK(chat_id,user_id); FK в chats и users | Состав чата |
| messages | PK id; FK chat_id, sender_id; составной FK(chat_id,sender_id) → members | Сообщения участников |
| schema_migrations | PK version; checksum | Версии структуры |
Индексы: messages_history(chat_id,created_at,id), members_user(user_id,chat_id),
chats_order(created_at,id), sessions_expiry(expires_at), плюс индексы PK и UNIQUE.
Индекс сессий по сроку оставлен для будущей пакетной очистки; текущий доступ идёт по PK токена.
Строковые поля, размеры, JSON и UUID проверяются API. БД дополнительно защищает
уникальность имён, обязательные поля и связи даже при конкурирующих запросах.
### Транзакционные границы
Регистрация — один INSERT, конфликт UNIQUE становится 409.
Чат + все members — одна транзакция: отсутствующий пользователь вызывает FK violation,
и весь чат откатывается. Сообщение — отдельный INSERT/COMMIT до ответа 201.
Вход — проверка хеша вне соединения БД, затем INSERT сессии; выход — DELETE/COMMIT.
Миграции — транзакция с advisory lock, последовательностью версий и контрольными суммами.
Обычная изоляция — READ COMMITTED. Явные глобальные Python-lock больше не нужны.
В ЛР1 сохранены формы объектов, Unicode, ограничения полей, права участников, ошибки,
request ID и keyset-пагинация. Изменены регистрация (добавлен пароль), идентификация
(Bearer вместо X-User-Id), хранилище и управление конкурентностью. Старые in-memory
лимиты количества пользователей/сообщений и локальный rate limiter не переносились.
Автоматический импорт содержимого ЛР1 не реализован и заданием не требуется.
### Кэш, сессии и отказ
Кэш не участвует в решении о доступе. Сессия каждый раз проверяется в PostgreSQL;
её expires_at вычисляется временем БД. Logout удаляет запись, expiry не продлевается.
Токен — secrets.token_urlsafe(32), хранится только SHA-256 случайного токена.
Пароли — Argon2id, параметры time_cost=2, memory_cost=19456 KiB, parallelism=1.
У профиля нет API изменения/удаления: естественная инвалидация — TTL 60 секунд.
При добавлении PATCH профиля понадобится стратегия сброса/версионирования кэша.
Redis можно очистить: профили восстановятся из PostgreSQL. AOF и volume включены,
но корректность приложения не зависит от сохранности кэша.
Пул PostgreSQL: 1–10 соединений, до 32 ожидающих, pool timeout 3 s,
connect timeout 3 s, statement timeout 3 s, lock timeout 2 s.
Redis: максимум 16 соединений, connect/read timeout 0.2 s, без автоматических повторов.
При ошибке Redis чтение профиля идёт в PostgreSQL. При ошибке PostgreSQL — 503.
Это не жёсткий общий дедлайн всего HTTP-запроса; отдельные ожидания могут суммироваться.
Парольные операции: до четырёх одновременно, очередь допуска ожидания до 1 s.
### Пагинация
История: `WHERE chat_id=%s AND (created_at,id)>(%s,%s) ORDER BY created_at,id LIMIT %s`.
Параметры передаются Psycopg отдельно от SQL. Cursor содержит scope, время, UUID и HMAC;
ключ подписи сохраняется в .env, поэтому курсор не ломается от обычного рестарта.
Для next_cursor читается limit+1. OFFSET в endpoint отсутствует.
В конкурентной истории нет общего snapshot между страницами. Поздний COMMIT записи
с более ранним created_at или перевод часов назад может поместить её до уже выданной закладки.
На неизменной истории порядок стабилен; UUID разрешает совпадения timestamp.
## Выполненные проверки и границы доказательств
В среде подготовки **Docker отсутствовал**. Проверки выполнены с настоящими локальными
процессами PostgreSQL **17.11**, Redis **8.0.2**, Python **3.12**, с закреплёнными библиотеками API.
Это не запуск контейнеров с версиями из compose.yaml. Docker build, `compose up`,
`scripts/verify.py` и публичный `tests/resilience.py` с Docker-hook **здесь не запускались**.
Их требуется выполнить на компьютере студентки. Ниже native означает реальные отдельные
процессы с постоянным каталогом данных, не mocks и не SQLite.
| Критерий | Команда/сценарий | Полученный результат | Доказательство |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
| Основной API, неправильный пароль, logout, X-User-Id | tests/smoke.py | PASS на native-стенде | evidence/local-integration.txt |
| Повторное применение миграций | student-tests/database.py | PASS, два повторных вызова | evidence/local-explain-and-rollback.txt |
| Гонка одинакового username | student-tests/extra.py, 4 параллельных запроса | один 201, три 409 | evidence/local-integration.txt |
| Откат составной операции | student-tests/database.py | число чатов не изменилось после FK failure | evidence/local-explain-and-rollback.txt |
| Redis реально используется | проверка EXISTS ключа профиля | PASS | evidence/local-integration.txt |
| Сохранность данных/сессий | native_verify.py: остановка и запуск всех трёх процессов | прежний токен читает прежнее сообщение | evidence/local-integration.txt |
| Короткий TTL | student-tests/expiry.py, API с TTL=2 | сначала 200, через 2.5 s — 401 | evidence/local-integration.txt |
| Отказ Redis | native_verify.py: остановка процесса | 200 из БД, неизвестный токен 401 | evidence/local-integration.txt |
| Отказ БД | native_verify.py: остановка процесса | защищённый запрос 503; live 200; ready 503 | evidence/local-integration.txt |
| Индекс истории, ≥10 000 сообщений | EXPLAIN ANALYZE BUFFERS, 12 000 сообщений, страница после 9001-й строки | Index Scan по messages_history | evidence/local-explain-and-rollback.txt |
| JSON, границы, пароль UTF-8 с двоеточием, чужой cursor | student-tests/extra.py | PASS | evidence/local-integration.txt |
| Неизменность задания/контракта/public tests | побайтовая сверка с архивом skeleton | PASS | evidence/protected-files.sha256 |
| Полный Compose и Docker restart hook | scripts/verify.py и tests/resilience.py | **выполнить локально** | evidence/compose-verification.txt и restart-before/after.txt после запуска |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
Native-методика сохранена в student-tests/native_verify.py. Она принимает пути через
PG_BIN, REDIS_SERVER, NATIVE_DATA; запускается Python из окружения requirements.txt.
PG_BIN — каталог с postgres и initdb. NATIVE_DATA — отдельная папка временного стенда.
Пример Linux: `PG_BIN=/path/to/pgsql/bin REDIS_SERVER=/path/to/redis-server NATIVE_DATA=/tmp/lab2-test .venv/bin/python student-tests/native_verify.py`.
Библиотеки ОС для выбранных бинарников должны быть установлены. Рекомендуемый для сдачи путь — Compose.
## Эксперименты и отказы
Эксперимент SQL использует 12 000 синтетических сообщений в одном чате, ANALYZE,
затем запрос страницы 51 запись после 9001-й. Синтетические строки откатываются.
Результат доказывает выбор индекса для данного набора, но не производительность при боевой нагрузке.
Нагрузочный эксперимент, p95/p99, CPU/RAM и аппаратная ёмкость не заявляются.
Время отказов из лога — единичный локальный замер, не SLA и не верхняя гарантия задержки.
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
## Ограничения
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
Один PostgreSQL и один хост: отказ БД временно делает API неготовым. Репликации, failover,
backup и восстановления на другой диск нет. COMMIT использует обычные durability-настройки PostgreSQL;
сохранение volume не защищает от удаления volume или потери физического диска.
Нет UI, вложений, очередей, идемпотентных повторов сообщений и исследовательского трека 5.
Истёкшие сессии проверяются корректно, но автоматическая уборка строк пока не реализована.
Ограничен размер тела JSON, но отдельный timeout медленной загрузки тела не реализован.
Учебный HTTP предназначен только для localhost; для удалённого доступа нужен TLS.
Не публиковать .env, реальные пароли, токены и полные дампы БД.
## Ограничения и следующие шаги
## Источники и библиотеки
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
- Задание: README.md, contracts/README.md, contracts/openapi.json.
- Psycopg pool и транзакции: https://www.psycopg.org/psycopg3/docs/advanced/pool.html
- PostgreSQL составные индексы: https://www.postgresql.org/docs/17/indexes-multicolumn.html
- Redis asyncio: https://redis.readthedocs.io/en/v6.4.0/examples/asyncio_examples.html
- FastAPI/Uvicorn — HTTP; Psycopg — SQL/pool; redis-py — кэш; argon2-cffi — password KDF.
+52
View File
@@ -0,0 +1,52 @@
services:
api:
build: .
ports:
- "127.0.0.1:${APP_PORT:-8080}:8080"
environment:
APP_HOST: 0.0.0.0
APP_PORT: 8080
APP_ENV: lab
DATABASE_URL: postgresql://messenger:${POSTGRES_PASSWORD:?Run python scripts/init_env.py}@db:5432/messenger
CACHE_URL: redis://cache:6379/0
CURSOR_SECRET: ${CURSOR_SECRET:?Run python scripts/init_env.py}
SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600}
depends_on:
db:
condition: service_healthy
cache:
condition: service_healthy
healthcheck:
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8080/health/ready', timeout=5)"]
interval: 3s
timeout: 6s
retries: 20
restart: unless-stopped
db:
image: postgres:17.5-bookworm
environment:
POSTGRES_DB: messenger
POSTGRES_USER: messenger
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Run python scripts/init_env.py}
volumes:
- postgres_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U messenger -d messenger"]
interval: 2s
timeout: 3s
retries: 30
restart: unless-stopped
cache:
image: redis:7.4.4-bookworm
command: ["redis-server", "--appendonly", "yes", "--maxmemory", "64mb", "--maxmemory-policy", "allkeys-lru"]
volumes:
- redis_data:/data
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 2s
timeout: 3s
retries: 30
restart: unless-stopped
volumes:
postgres_data:
redis_data:
+35
View File
@@ -0,0 +1,35 @@
"""A bounded pool and atomic, versioned migrations."""
import hashlib
import os
from pathlib import Path
import psycopg
from psycopg.rows import dict_row
from psycopg_pool import AsyncConnectionPool
def setting(name):
path = os.getenv(name + '_FILE')
return Path(path).read_text().strip() if path else os.environ[name]
def make_pool():
return AsyncConnectionPool(setting('DATABASE_URL'), min_size=1, max_size=10,
timeout=3, max_waiting=32, open=False,
kwargs={'row_factory': dict_row, 'connect_timeout': 3,
'options': '-c statement_timeout=3000 -c lock_timeout=2000 -c timezone=UTC'})
async def migrate(pool):
async with pool.connection() as conn:
await conn.execute('SELECT pg_advisory_xact_lock(202602)')
await conn.execute('CREATE TABLE IF NOT EXISTS schema_migrations (version text PRIMARY KEY, checksum text NOT NULL)')
for path in sorted((Path(__file__).parent / 'migrations').glob('*.sql')):
content = path.read_text()
checksum = hashlib.sha256(content.encode()).hexdigest()
row = await (await conn.execute('SELECT checksum FROM schema_migrations WHERE version=%s', (path.name,))).fetchone()
if row:
if row['checksum'] != checksum:
raise RuntimeError('Applied migration was modified')
else:
await conn.execute(content)
await conn.execute('INSERT INTO schema_migrations VALUES (%s,%s)', (path.name, checksum))
+10 -2
View File
@@ -1,5 +1,13 @@
# Доказательства
Храните небольшие обезличенные результаты: команды и stdout проверок, JSON/CSV агрегатов нагрузки, EXPLAIN, dashboard JSON, текст разбора отказа. Укажите дату, commit, аппаратные лимиты и профиль нагрузки.
local-integration.txt — фактический успешный запуск student-tests/native_verify.py:
Python 3.12, PostgreSQL 17.11, Redis 8.0.2, зависимости requirements.lock.txt.
local-explain-and-rollback.txt — реальный план SQL, повтор миграций и откат.
protected-files.sha256 — контрольные суммы неизменённых файлов skeleton.
Не добавляйте .env, session tokens, cookies, приватные ключи, credentials, реальные сообщения, raw dumps и signed URLs. Для скриншотов скрывайте секреты. Большие логи/бинарные traces сохраняйте отдельно по правилам преподавателя; одного скриншота без методики недостаточно.
Эти данные относятся к native-процессам, НЕ к Docker Compose.
Для собственного стенда сохраните вывод scripts/verify.py в compose-verification.txt.
Скрипт создаст explain-and-rollback.txt и restart-before.txt/restart-after.txt.
Публичный persistence с scripts/restart.sh запускайте отдельно на Linux/WSL.
Не добавляйте пароли, .env, токены, Authorization или дампы пользовательских данных.
Binary file not shown.
+13
View File
@@ -0,0 +1,13 @@
PASS: migrations applied twice
PASS: rollback removes partial chat
EXPLAIN: 12000 messages; cursor after row 9001; page 51
Limit (cost=0.29..8.89 rows=51 width=69) (actual time=0.017..0.048 rows=51 loops=1)
Buffers: shared hit=4
-> Index Scan using messages_history on messages (cost=0.29..507.33 rows=3006 width=69) (actual time=0.015..0.037 rows=51 loops=1)
Index Cond: ((chat_id = '2e792f72-9441-47f1-bf88-18cb19132cdb'::uuid) AND (ROW(created_at, id) > ROW('2026-01-01 00:00:00.009001+00'::timestamp with time zone, '1a322347-8a32-4b05-9695-5a34b1440088'::uuid)))
Buffers: shared hit=4
Planning:
Buffers: shared hit=6
Planning Time: 0.267 ms
Execution Time: 0.149 ms
PASS: history uses messages_history index
+13
View File
@@ -0,0 +1,13 @@
PASS: migrations applied twice
PASS: rollback removes partial chat
EXPLAIN: 12000 messages; cursor after row 9001; page 51
Limit (cost=0.29..13.92 rows=51 width=69) (actual time=0.010..0.021 rows=51 loops=1)
Buffers: shared hit=4
-> Index Scan using messages_history on messages (cost=0.29..805.74 rows=3012 width=69) (actual time=0.010..0.017 rows=51 loops=1)
Index Cond: ((chat_id = '72bcdf0e-3925-4d4d-b65f-d1b13c025935'::uuid) AND (ROW(created_at, id) > ROW('2026-01-01 00:00:00.009001+00'::timestamp with time zone, '843e3f43-24f4-4509-9082-6abb79d91871'::uuid)))
Buffers: shared hit=4
Planning:
Buffers: shared hit=6
Planning Time: 0.209 ms
Execution Time: 0.046 ms
PASS: history uses messages_history index
+27
View File
@@ -0,0 +1,27 @@
PASS: lab2 public API scenario; infrastructure and grading evidence remain separate.
PASS: concurrent registration: 1 x 201, 3 x 409
PASS: Unicode password with colon
PASS: validation, cursor isolation, logout
PASS: migrations applied twice
PASS: rollback removes partial chat
EXPLAIN: 12000 messages; cursor after row 9001; page 51
Limit (cost=0.29..13.92 rows=51 width=69) (actual time=0.010..0.021 rows=51 loops=1)
Buffers: shared hit=4
-> Index Scan using messages_history on messages (cost=0.29..805.74 rows=3012 width=69) (actual time=0.010..0.017 rows=51 loops=1)
Index Cond: ((chat_id = '72bcdf0e-3925-4d4d-b65f-d1b13c025935'::uuid) AND (ROW(created_at, id) > ROW('2026-01-01 00:00:00.009001+00'::timestamp with time zone, '843e3f43-24f4-4509-9082-6abb79d91871'::uuid)))
Buffers: shared hit=4
Planning:
Buffers: shared hit=6
Planning Time: 0.209 ms
Execution Time: 0.046 ms
PASS: history uses messages_history index
PASS: actual API/PostgreSQL/Redis process restart preserves data and existing tokens
PASS: actual Redis cache key exists
PASS: Redis outage fallback 0.013s; invalid token rejected
PASS: PostgreSQL outage 503 0.009s; live 200, ready 503
PASS: short session expires (expected configured TTL=2)
PASS: native integration suite (Docker not available)
+14
View File
@@ -0,0 +1,14 @@
2c01dd698cc9653dece49a94c9fd3f58d36e84764aaa643b46e26d7e599dc12e CONTRIBUTING.md
c34d53cd082d194aa4b58f504c4e0348d25b6afec3d6a9c0963dd01c9c81e971 COURSE.md
59a70ede89ba308a782f0695f8441dfa4b75479d155966303ab86addc36f8d1f MAINTAINERS.md
4f14a97911bd3ea335868d37fec187d1738b42f91a7d4780d33b721edf25b6dc README.md
72df27a559f88ffa3fd8c3c79d3c32f6db2c5986a0602677c51994c434a3fc4f contracts/README.md
0a71cec72903af556df85f939c7e347fc73a86a1a4ffc39fb9c8ded169b7df45 contracts/examples.json
7efd8b1e6023ddc3ff9747d4f663ee772c1293b782bb9e74bd1c3fbcca9c68d8 contracts/infrastructure.json
cff3aa6b34855b573401b0ac393fdfe327b6a12da51f315fbbd67168ce3762c4 contracts/openapi.json
d63eac8df585a63153cff0c632e6b81b2088316b53d531eecc856ec1da7855e4 lab.json
e0bfa7e196797f6a5bf6e44d8ad2ffeb82651927ff5d8484eb1c2dda1ec7dec5 tests/README.md
8d50976fc7c7bbb81e88a152f613c61ab25eaf53dba33c6a9dfab19f868d546d tests/client.py
6d3511ea719c7a7e841083e73d435c86dcbfd9f4e5c2a07d62eb9614b01d9933 tests/load.py
1f96663a174b3978d24eff66f2741f5f8c9b788d3242261d37a972720c52788b tests/resilience.py
52ac38eb343ff7d43e7543588e1da58ca06c9fce74b2b0d0bf0e4982bc23c1db tests/smoke.py
+3
View File
@@ -0,0 +1,3 @@
/lab2-api-1 2026-11-13T07:24:06.731303647Z
/lab2-cache-1 2026-11-13T07:24:06.443371797Z
/lab2-db-1 2026-11-13T07:24:06.5139748Z
+3
View File
@@ -0,0 +1,3 @@
/lab2-api-1 2026-11-13T07:19:48.194614314Z
/lab2-cache-1 2026-11-13T07:15:56.963253379Z
/lab2-db-1 2026-11-13T07:15:57.286672521Z
+371
View File
@@ -0,0 +1,371 @@
"""Lab2. PostgreSQL is authoritative; Redis caches immutable public profiles only."""
import asyncio
import base64
import hashlib
import hmac
import json
import logging
import os
import re
import secrets
import time
import uuid
from contextlib import asynccontextmanager
from datetime import datetime
import psycopg
from psycopg_pool import PoolTimeout, TooManyRequests
from argon2 import PasswordHasher
from argon2.exceptions import VerificationError
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse, Response
from redis.asyncio import Redis
from redis.exceptions import RedisError
from redis.retry import Retry
from redis.backoff import NoBackoff
from starlette.exceptions import HTTPException
from db import make_pool, migrate, setting
log = logging.getLogger('uvicorn.error')
ph = PasswordHasher(time_cost=2, memory_cost=19456, parallelism=1)
dummy_hash = ph.hash('dummy-password-never-used')
CODES = {400:'invalid_request',401:'unauthorized',404:'not_found',409:'conflict',
413:'payload_too_large',415:'unsupported_media_type',429:'rate_limited',
503:'unavailable',500:'internal_error'}
class Problem(Exception):
def __init__(self, status, message):
self.status, self.message = status, message
def uid(value):
try:
if not isinstance(value, str):
raise ValueError()
return str(uuid.UUID(value))
except (ValueError, AttributeError):
raise Problem(400, 'Invalid UUID') from None
def field(body, key, maximum, minimum=1):
value = body[key]
if not isinstance(value, str) or not minimum <= len(value) <= maximum or not value.strip() or '\x00' in value:
raise Problem(400, 'Invalid ' + key)
try:
value.encode('utf-8')
except UnicodeError:
raise Problem(400, 'Invalid Unicode') from None
return value
def wire(value):
if isinstance(value, dict):
return {k:wire(v) for k,v in value.items()}
if isinstance(value, list):
return [wire(v) for v in value]
if isinstance(value, uuid.UUID):
return str(value)
if isinstance(value, datetime):
return value.isoformat(timespec='microseconds').replace('+00:00','Z')
return value
@asynccontextmanager
async def lifespan(app):
app.state.pool = make_pool()
app.state.secret = setting('CURSOR_SECRET').encode()
if len(app.state.secret) < 32:
raise RuntimeError('CURSOR_SECRET must contain at least 32 characters')
app.state.ttl = int(os.getenv('SESSION_TTL_SECONDS','3600'))
if app.state.ttl <= 0:
raise RuntimeError('SESSION_TTL_SECONDS must be positive')
app.state.kdf_slots = asyncio.Semaphore(4)
app.state.cache = Redis.from_url(setting('CACHE_URL'), socket_timeout=.2,
socket_connect_timeout=.2, decode_responses=True,
max_connections=16, retry=Retry(NoBackoff(), 0))
await app.state.pool.open()
try:
await app.state.pool.wait(timeout=15)
await migrate(app.state.pool)
yield
finally:
await app.state.cache.aclose()
await app.state.pool.close()
app = FastAPI(lifespan=lifespan, docs_url=None, redoc_url=None, openapi_url=None)
def error(request, status, message):
headers = {}
if status == 401:
headers['WWW-Authenticate'] = ('Basic realm="messenger", charset="UTF-8"' if request.url.path == '/api/v1/auth/sessions' else 'Bearer realm="messenger"')
return JSONResponse({'error':{'code':CODES.get(status,'invalid_request'),
'message':message,'request_id':request.state.rid}}, status_code=status, headers=headers)
@app.middleware('http')
async def boundary(request, call_next):
request.state.rid = str(uuid.uuid4())
start = time.monotonic()
try:
response = await call_next(request)
except (psycopg.OperationalError, psycopg.InterfaceError, psycopg.errors.QueryCanceled,
psycopg.errors.LockNotAvailable, PoolTimeout, TooManyRequests):
response = error(request,503,'Database temporarily unavailable')
except Exception:
log.error('Unhandled failure request_id=%s',request.state.rid)
response = error(request,500,'Internal server error')
response.headers['X-Request-Id'] = request.state.rid
log.info('method=%s route=%s status=%s elapsed_ms=%.2f request_id=%s',request.method,
getattr(request.scope.get('route'),'path','unmatched'),response.status_code,
(time.monotonic()-start)*1000,request.state.rid)
return response
@app.exception_handler(Problem)
async def problem(request, exc):
return error(request,exc.status,exc.message)
@app.exception_handler(HTTPException)
async def http_error(request,exc):
return error(request,exc.status_code,'Invalid request')
async def payload(request, fields):
if request.headers.get('content-type','').split(';')[0].strip().lower() != 'application/json':
raise Problem(415,'Expected application/json')
raw = bytearray()
async for part in request.stream():
raw.extend(part)
if len(raw) > 65536:
raise Problem(413,'Request body too large')
try:
body = json.loads(raw)
except (ValueError,UnicodeError,RecursionError):
raise Problem(400,'Malformed JSON') from None
if not isinstance(body,dict) or set(body) != set(fields):
raise Problem(400,'Missing or extra fields')
return body
async def kdf(function, *args):
# Admission is bounded; expensive password operations never run on the event loop.
try:
await asyncio.wait_for(app.state.kdf_slots.acquire(), timeout=1)
except TimeoutError:
raise Problem(503,'Password service busy') from None
try:
return await asyncio.to_thread(function, *args)
finally:
app.state.kdf_slots.release()
def bearer(request):
parts = request.headers.get('authorization','').split()
if len(parts) != 2 or parts[0].lower() != 'bearer' or not re.fullmatch(r'[A-Za-z0-9_-]{43}',parts[1]):
raise Problem(401,'Invalid session')
return hashlib.sha256(parts[1].encode()).hexdigest()
async def actor(conn, request):
token_hash = bearer(request)
row = await (await conn.execute('SELECT user_id FROM sessions WHERE token_hash=%s AND expires_at>clock_timestamp()', (token_hash,))).fetchone()
if not row:
raise Problem(401,'Invalid session')
return row['user_id']
async def accessible(conn, chat_id, user_id):
chat_id = uid(chat_id)
row = await (await conn.execute('SELECT 1 FROM members WHERE chat_id=%s AND user_id=%s',(chat_id,user_id))).fetchone()
if not row:
raise Problem(404,'Chat not found')
return chat_id
async def profile(conn, user_id):
key = 'profile:v1:' + str(user_id)
try:
cached = await app.state.cache.get(key)
if cached:
return json.loads(cached)
except (RedisError,ValueError):
pass
row = wire(await (await conn.execute('SELECT id,username,display_name,created_at FROM users WHERE id=%s',(user_id,))).fetchone())
try:
await app.state.cache.set(key,json.dumps(row),ex=60)
except RedisError:
pass
return row
def paging(request, scope):
raw = request.query_params.get('limit','50')
if not re.fullmatch('[0-9]{1,3}',raw) or not 1 <= int(raw) <= 100:
raise Problem(400,'Invalid limit')
cursor = request.query_params.get('cursor')
after = None
if cursor is not None:
try:
if len(cursor)>1024:
raise ValueError()
data, signature = cursor.split('.')
expected = hmac.new(app.state.secret,data.encode(),hashlib.sha256).hexdigest()
if not hmac.compare_digest(signature,expected):
raise ValueError()
resource,stamp,ident = json.loads(base64.urlsafe_b64decode(data+'='*(-len(data)%4)))
if resource != scope:
raise ValueError()
after = (datetime.fromisoformat(stamp.replace('Z','+00:00')),uuid.UUID(ident))
except (ValueError,TypeError,UnicodeError):
raise Problem(400,'Invalid cursor') from None
return int(raw),after
def page(rows, limit, scope):
rows = wire(rows)
cursor = None
if len(rows)>limit:
last = rows[limit-1]
data = base64.urlsafe_b64encode(json.dumps([scope,last['created_at'],last['id']]).encode()).decode().rstrip('=')
cursor = data+'.'+hmac.new(app.state.secret,data.encode(),hashlib.sha256).hexdigest()
return {'items':rows[:limit],'next_cursor':cursor}
@app.get('/health/live')
async def live():
return {'status':'ok'}
@app.get('/health/ready')
async def ready():
async with app.state.pool.connection() as conn:
await conn.execute('SELECT 1')
return {'status':'ok'}
@app.post('/api/v1/users',status_code=201)
async def create_user(request:Request):
body = await payload(request,['username','display_name','password'])
name = field(body,'username',32)
display = field(body,'display_name',100)
password = field(body,'password',128,12)
if not re.fullmatch('[a-z0-9_]{3,32}',name):
raise Problem(400,'Invalid username')
hashed = await kdf(ph.hash,password)
try:
async with app.state.pool.connection() as conn:
row = await (await conn.execute('INSERT INTO users(id,username,display_name,password_hash) VALUES (%s,%s,%s,%s) RETURNING id,username,display_name,created_at',(uuid.uuid4(),name,display,hashed))).fetchone()
return wire(row)
except psycopg.errors.UniqueViolation:
raise Problem(409,'Username already exists') from None
@app.post('/api/v1/auth/sessions',status_code=201)
async def login(request:Request):
async for part in request.stream():
if part:
raise Problem(400,'Login does not accept a body')
try:
scheme,encoded = request.headers.get('authorization','').split()
if scheme.lower() != 'basic' or len(encoded)>1024:
raise ValueError()
name,password = base64.b64decode(encoded,validate=True).decode('utf-8').split(':',1)
if not re.fullmatch('[a-z0-9_]{3,32}',name) or not 12<=len(password)<=128:
raise ValueError()
except (ValueError,UnicodeError):
raise Problem(401,'Invalid credentials') from None
async with app.state.pool.connection() as conn:
row = await (await conn.execute('SELECT id,password_hash FROM users WHERE username=%s',(name,))).fetchone()
try:
await kdf(ph.verify,row['password_hash'] if row else dummy_hash,password)
except VerificationError:
raise Problem(401,'Invalid credentials') from None
if not row:
raise Problem(401,'Invalid credentials')
token = secrets.token_urlsafe(32)
async with app.state.pool.connection() as conn:
expiry = await (await conn.execute("INSERT INTO sessions VALUES (%s,%s,clock_timestamp() + %s * interval '1 second') RETURNING expires_at",(hashlib.sha256(token.encode()).hexdigest(),row['id'],app.state.ttl))).fetchone()
user = await profile(conn,row['id'])
return {'token':token,'token_type':'Bearer','expires_at':wire(expiry['expires_at']),'user':user}
@app.delete('/api/v1/auth/sessions/current',status_code=204)
async def logout(request:Request):
async with app.state.pool.connection() as conn:
row = await (await conn.execute('DELETE FROM sessions WHERE token_hash=%s AND expires_at>clock_timestamp() RETURNING user_id',(bearer(request),))).fetchone()
if not row:
raise Problem(401,'Invalid session')
return Response(status_code=204)
@app.get('/api/v1/users/me')
async def me(request:Request):
async with app.state.pool.connection() as conn:
return await profile(conn,await actor(conn,request))
CHAT_SQL = '''SELECT c.id,c.title,c.created_at,
ARRAY(SELECT user_id FROM members WHERE chat_id=c.id ORDER BY user_id) AS member_ids FROM chats c'''
@app.post('/api/v1/chats',status_code=201)
async def create_chat(request:Request):
async with app.state.pool.connection() as conn:
user_id = await actor(conn,request)
body = await payload(request,['title','member_ids'])
title = field(body,'title',100)
members = body['member_ids']
if not isinstance(members,list) or not 1<=len(members)<=100:
raise Problem(400,'Invalid member_ids')
members = [uid(x) for x in members]
if len(set(members))!=len(members) or str(user_id) not in members:
raise Problem(400,'Invalid member_ids')
chat_id = uuid.uuid4()
try:
async with app.state.pool.connection() as conn:
# First INSERT may succeed; a missing member then rolls back the WHOLE operation.
await conn.execute('INSERT INTO chats(id,title) VALUES (%s,%s)',(chat_id,title))
for member in members:
await conn.execute('INSERT INTO members VALUES (%s,%s)',(chat_id,member))
row = await (await conn.execute(CHAT_SQL+' WHERE c.id=%s',(chat_id,))).fetchone()
return wire(row)
except psycopg.errors.ForeignKeyViolation:
raise Problem(400,'Invalid member_ids') from None
@app.get('/api/v1/chats')
async def list_chats(request:Request):
async with app.state.pool.connection() as conn:
user_id = await actor(conn,request)
scope = 'chats:'+str(user_id)
limit,after = paging(request,scope)
sql = CHAT_SQL+' WHERE EXISTS (SELECT 1 FROM members m WHERE m.chat_id=c.id AND m.user_id=%s)'
args = [user_id]
if after:
sql += ' AND (c.created_at,c.id)>(%s,%s)'
args.extend(after)
rows = await (await conn.execute(sql+' ORDER BY c.created_at,c.id LIMIT %s',args+[limit+1])).fetchall()
return page(rows,limit,scope)
@app.get('/api/v1/chats/{chat_id}')
async def get_chat(chat_id:str,request:Request):
async with app.state.pool.connection() as conn:
chat_id = await accessible(conn,chat_id,await actor(conn,request))
return wire(await (await conn.execute(CHAT_SQL+' WHERE c.id=%s',(chat_id,))).fetchone())
@app.post('/api/v1/chats/{chat_id}/messages',status_code=201)
async def send(chat_id:str,request:Request):
async with app.state.pool.connection() as conn:
user_id = await actor(conn,request)
chat_id = await accessible(conn,chat_id,user_id)
body = await payload(request,['text'])
content = field(body,'text',4000)
async with app.state.pool.connection() as conn:
row = await (await conn.execute('INSERT INTO messages(id,chat_id,sender_id,text) VALUES (%s,%s,%s,%s) RETURNING *',(uuid.uuid4(),chat_id,user_id,content))).fetchone()
return wire(row)
@app.get('/api/v1/chats/{chat_id}/messages')
async def history(chat_id:str,request:Request):
async with app.state.pool.connection() as conn:
chat_id = await accessible(conn,chat_id,await actor(conn,request))
scope = 'messages:'+chat_id
limit,after = paging(request,scope)
sql,args = 'SELECT * FROM messages WHERE chat_id=%s',[chat_id]
if after:
sql += ' AND (created_at,id)>(%s,%s)'
args.extend(after)
rows = await (await conn.execute(sql+' ORDER BY created_at,id LIMIT %s',args+[limit+1])).fetchall()
return page(rows,limit,scope)
+27
View File
@@ -0,0 +1,27 @@
CREATE TABLE users (
id uuid PRIMARY KEY, username text NOT NULL UNIQUE CHECK (username ~ '^[a-z0-9_]{3,32}$'),
display_name text NOT NULL, password_hash text NOT NULL,
created_at timestamptz NOT NULL DEFAULT clock_timestamp()
);
CREATE TABLE sessions (
token_hash text PRIMARY KEY, user_id uuid NOT NULL REFERENCES users(id),
expires_at timestamptz NOT NULL
);
CREATE INDEX sessions_expiry ON sessions(expires_at);
CREATE TABLE chats (
id uuid PRIMARY KEY, title text NOT NULL,
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 ON members(user_id,chat_id);
CREATE INDEX chats_order 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 text NOT NULL,
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);
Submodule
+1
Submodule mtusi2026lab2 added at 65003b6119
+20
View File
@@ -0,0 +1,20 @@
annotated-types==0.8.0
anyio==4.16.0
argon2-cffi==25.1.0
argon2-cffi-bindings==26.1.0
cffi==2.1.1
click==8.5.1
fastapi==0.115.12
h11==0.16.0
idna==3.20
psycopg==3.2.10
psycopg-binary==3.2.10
psycopg-pool==3.2.6
pycparser==3.12
pydantic==2.14.3
pydantic_core==2.50.4
redis==6.4.0
starlette==0.46.2
typing-inspection==0.4.5
typing_extensions==4.16.0
uvicorn==0.34.3
+6
View File
@@ -0,0 +1,6 @@
fastapi==0.115.12
uvicorn==0.34.3
psycopg[binary]==3.2.10
psycopg-pool==3.2.6
redis==6.4.0
argon2-cffi==25.1.0
+7
View File
@@ -0,0 +1,7 @@
import os
import uvicorn
if __name__ == '__main__':
uvicorn.run('main:app', host=os.getenv('APP_HOST','0.0.0.0'),
port=int(os.getenv('APP_PORT','8080')), workers=1,
access_log=False, timeout_keep_alive=2)
+12
View File
@@ -0,0 +1,12 @@
"""Create secrets locally, never overwrite an existing configuration."""
from pathlib import Path
import secrets
path = Path(__file__).resolve().parents[1] / '.env'
try:
with path.open('x') as f:
f.write('APP_PORT=8080\nSESSION_TTL_SECONDS=3600\nPOSTGRES_PASSWORD='+secrets.token_hex(24)+'\nCURSOR_SECRET='+secrets.token_hex(32)+'\n')
path.chmod(0o600)
print('Created .env (local secrets; do not commit)')
except FileExistsError:
print('.env already exists; left unchanged')
+7
View File
@@ -0,0 +1,7 @@
#!/bin/sh
set -eu
cd "$(dirname "$0")/.."
mkdir -p evidence
docker compose ps -q | xargs -r docker inspect --format '{{.Name}} {{.State.StartedAt}}' > evidence/restart-before.txt
docker compose restart db cache api
docker compose ps -q | xargs -r docker inspect --format '{{.Name}} {{.State.StartedAt}}' > evidence/restart-after.txt
+100
View File
@@ -0,0 +1,100 @@
"""Full Docker checks, Python stdlib only; works on Windows and Linux.
Stops/restarts ONLY services belonging to this Compose project. Keeps volumes.
Run against an idle disposable teaching stand, not during other tests.
"""
import os
from pathlib import Path
import subprocess
import sys
import time
ROOT=Path(__file__).resolve().parents[1]
sys.path.insert(0,str(ROOT/'tests'))
from client import Client,Failure,check
from resilience import history
def compose(*args, capture=False):
result=subprocess.run(['docker','compose',*args],cwd=ROOT,text=True,capture_output=capture)
if result.returncode:
raise RuntimeError('Compose failed: '+args[0])
return result.stdout if capture else None
def wait(c):
deadline=time.monotonic()+60
while time.monotonic()<deadline:
try:
c.call('GET','/health/ready',schema='Health')
return
except Failure:
time.sleep(.5)
raise RuntimeError('API did not become ready')
def stamp(filename):
ids=compose('ps','-q',capture=True).split()
data=subprocess.check_output(['docker','inspect','--format','{{.Name}} {{.State.StartedAt}}',*ids],text=True)
(ROOT/'evidence'/filename).write_text(data)
def main():
os.chdir(ROOT)
(ROOT/'evidence').mkdir(exist_ok=True)
c=Client()
wait(c)
for script in ('tests/smoke.py','student-tests/extra.py'):
subprocess.run([sys.executable,script],check=True)
output=compose('exec','-T','api','python','student-tests/database.py',capture=True)
(ROOT/'evidence/explain-and-rollback.txt').write_text(output)
print(output)
alice,bob,eve,chat=c.bootstrap()
original=c.message(alice,chat,'restart proof')['json']
stamp('restart-before.txt')
compose('restart','db','cache','api')
wait(c)
stamp('restart-after.txt')
check(original in history(c,bob,chat),'message lost on restart')
c.call('GET','/api/v1/users/me',actor=alice,schema='User')
print('PASS: all three services restarted; old tokens and message survive')
c.call('GET','/api/v1/users/me',actor=alice,schema='User')
cached=compose('exec','-T','cache','redis-cli','EXISTS','profile:v1:'+alice['id'],capture=True)
check(cached.strip()=='1','profile cache is unused')
print('PASS: real Redis profile key exists')
try:
compose('stop','cache')
start=time.monotonic()
c.call('GET','/api/v1/users/me',actor=alice,schema='User')
check(time.monotonic()-start<5,'cache fallback too slow')
c.call('GET','/api/v1/users/me',401,headers={'Authorization':'Bearer '+'a'*43})
c.call('GET','/health/ready',schema='Health')
print('PASS: Redis down -> SQL fallback; unknown token rejected')
finally:
compose('start','cache')
try:
compose('stop','db')
start=time.monotonic()
c.call('GET','/api/v1/users/me',503,actor=alice)
check(time.monotonic()-start<8,'DB failure too slow')
c.call('GET','/health/ready',503)
c.call('GET','/health/live',schema='Health')
print('PASS: DB down -> bounded 503; live remains 200')
finally:
compose('start','db')
wait(c)
expiry_id=None
try:
expiry_id=compose('run','-d','--no-deps','-p','127.0.0.1:18082:8080','-e','SESSION_TTL_SECONDS=2','api',capture=True).strip().splitlines()[-1]
short=Client('http://localhost:18082')
wait(short)
env=dict(os.environ,BASE_URL='http://localhost:18082')
subprocess.run([sys.executable,'student-tests/expiry.py'],env=env,check=True)
finally:
if expiry_id:
subprocess.run(['docker','rm','-f',expiry_id],check=True)
c.call('DELETE','/api/v1/auth/sessions/current',204,actor=alice)
c.call('GET','/api/v1/users/me',401,actor=alice)
print('PASS: complete Compose verification; volumes retained')
if __name__=='__main__':
main()
+54
View File
@@ -0,0 +1,54 @@
"""Direct SQL evidence: rollback, idempotent migrations, real EXPLAIN on 12000 rows.
Run inside API container: docker compose exec -T api python student-tests/database.py
Synthetic SQL data is rolled back after the experiment.
"""
import asyncio
import sys
import uuid
from pathlib import Path
sys.path.insert(0,str(Path(__file__).resolve().parents[1]))
import psycopg
from db import make_pool,migrate
async def main():
pool=make_pool()
await pool.open()
try:
await pool.wait()
await migrate(pool)
await migrate(pool)
print('PASS: migrations applied twice')
async with pool.connection() as conn:
before=(await (await conn.execute('SELECT count(*) n FROM chats')).fetchone())['n']
try:
async with conn.transaction():
chat=uuid.uuid4()
await conn.execute('INSERT INTO chats(id,title) VALUES (%s,%s)',(chat,'rollback-check'))
await conn.execute('INSERT INTO members VALUES (%s,%s)',(chat,uuid.uuid4()))
except psycopg.errors.ForeignKeyViolation:
pass
else:
raise AssertionError('expected foreign key failure')
after=(await (await conn.execute('SELECT count(*) n FROM chats')).fetchone())['n']
assert before==after
print('PASS: rollback removes partial chat')
# Roll back synthetic rows while retaining actual planner output.
async with conn.transaction(force_rollback=True):
user,chat=uuid.uuid4(),uuid.uuid4()
await conn.execute('INSERT INTO users(id,username,display_name,password_hash) VALUES (%s,%s,%s,%s)',(user,'plan_'+uuid.uuid4().hex[:16],'plan','not-a-login-hash'))
await conn.execute('INSERT INTO chats(id,title) VALUES (%s,%s)',(chat,'plan'))
await conn.execute('INSERT INTO members VALUES (%s,%s)',(chat,user))
await 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,user))
await conn.execute('ANALYZE messages')
row=await (await conn.execute('SELECT created_at,id FROM messages WHERE chat_id=%s ORDER BY created_at,id OFFSET 9000 LIMIT 1',(chat,))).fetchone()
plan=await (await conn.execute('EXPLAIN (ANALYZE, BUFFERS) SELECT * FROM messages WHERE chat_id=%s AND (created_at,id)>(%s,%s) ORDER BY created_at,id LIMIT 51',(chat,row['created_at'],row['id']))).fetchall()
rendered='\n'.join(r['QUERY PLAN'] for r in plan)
print('EXPLAIN: 12000 messages; cursor after row 9001; page 51')
print(rendered)
assert 'messages_history' in rendered and 'Index' in rendered
print('PASS: history uses messages_history index')
finally:
await pool.close()
if __name__=='__main__':
asyncio.run(main())
+16
View File
@@ -0,0 +1,16 @@
"""Run on a dedicated API with SESSION_TTL_SECONDS=2."""
import sys
import time
from pathlib import Path
sys.path.insert(0,str(Path(__file__).resolve().parents[1]/'tests'))
from client import Client,run
def main():
c=Client()
user=c.user('expiry')
c.call('GET','/api/v1/users/me',actor=user,schema='User')
time.sleep(2.5)
c.call('GET','/api/v1/users/me',401,actor=user)
print('PASS: short session expires (expected configured TTL=2)')
if __name__=='__main__':
run(main)
+45
View File
@@ -0,0 +1,45 @@
"""Extra black-box cases. Uses public Client without modifying public tests."""
import base64
from concurrent.futures import ThreadPoolExecutor
import sys
import time
import uuid
from pathlib import Path
sys.path.insert(0,str(Path(__file__).resolve().parents[1]/'tests'))
from client import Client,check,run
def main():
c = Client()
alice,bob,eve,chat = c.bootstrap()
body = {'username':'race_'+uuid.uuid4().hex[:16],'display_name':'Гонка','password':'Пароль:🙂'*3}
def register(_):
return Client().call('POST','/api/v1/users',[201,409],body=body)['status']
with ThreadPoolExecutor(max_workers=4) as pool:
statuses = list(pool.map(register,range(4)))
check(statuses.count(201)==1 and statuses.count(409)==3,'registration race failed')
print('PASS: concurrent registration: 1 x 201, 3 x 409')
credential = base64.b64encode((body['username']+':'+body['password']).encode()).decode()
c.call('POST','/api/v1/auth/sessions',201,headers={'Authorization':'Basic '+credential},schema='Session')
print('PASS: Unicode password with colon')
c.call('POST','/api/v1/chats',400,actor=alice,body={'title':'rollback-'+uuid.uuid4().hex,'member_ids':[alice['id'],str(uuid.uuid4())]})
c.call('GET','/api/v1/chats/not-a-uuid',401)
c.call('GET','/api/v1/chats/not-a-uuid',400,actor=alice)
c.call('POST','/api/v1/users',400,body={**body,'extra':True})
for text in ('', ' ', 'x'*4001):
c.call('POST','/api/v1/chats/'+chat['id']+'/messages',400,actor=alice,body={'text':text})
for i in range(6):
c.message(alice,chat,'page '+str(i))
path='/api/v1/chats/'+chat['id']+'/messages'
page=c.call('GET',path+'?limit=2',actor=alice,schema='MessagePage')['json']
other=c.call('POST','/api/v1/chats',201,actor=alice,body={'title':'other','member_ids':[alice['id']]},schema='Chat')['json']
from urllib.parse import quote
cursor=quote(page['next_cursor'],safe='')
c.call('GET','/api/v1/chats/'+other['id']+'/messages?cursor='+cursor,400,actor=alice)
c.call('GET',path+'?cursor=bad',400,actor=alice)
c.call('DELETE','/api/v1/auth/sessions/current',204,actor=alice)
c.call('GET','/api/v1/users/me',401,actor=alice)
c.call('DELETE','/api/v1/auth/sessions/current',401,actor=alice)
print('PASS: validation, cursor isolation, logout')
if __name__=='__main__':
run(main)
+72
View File
@@ -0,0 +1,72 @@
"""Optional Linux-only native verification, requires installed PostgreSQL/Redis binaries.
NATIVE_DATA must be a separate test directory. Ports: 8080, 55432, 56379.
Uses local trust authentication on synthetic data; never deploy this test cluster.
Primary supported user workflow is scripts/verify.py with Docker Compose.
"""
import os,subprocess,sys,time,json,signal
from pathlib import Path
LAB=Path(__file__).resolve().parents[1]
ROOT=Path(os.environ['NATIVE_DATA']).resolve()
ROOT.mkdir(parents=True,exist_ok=True)
PY=sys.executable
PG=Path(os.environ['PG_BIN']).resolve()
REDIS=Path(os.environ['REDIS_SERVER']).absolute()
os.environ.update(DATABASE_URL='postgresql://agent@127.0.0.1:55432/postgres',CACHE_URL='redis://127.0.0.1:56379/0',CURSOR_SECRET='native-test-only-cursor-secret-01234567890123456789',APP_HOST='127.0.0.1',APP_PORT='8080',SESSION_TTL_SECONDS='3600')
sys.path.insert(0,str(LAB/'tests'))
from client import Client,check,Failure
from resilience import history
processes={}
logs=[]
def start(name):
commands={'db':[str(PG/'postgres'),'-D',str(ROOT/'postgres'),'-p','55432','-h','127.0.0.1','-c',"unix_socket_directories="],
'cache':[str(REDIS),'--port','56379','--bind','127.0.0.1','--dir',str(ROOT/'redis'),'--appendonly','yes'],
'api':[PY,'run.py']}
log=open(ROOT/(name+'-native.log'),'a'); logs.append(log)
processes[name]=subprocess.Popen(commands[name],cwd=LAB,stdout=log,stderr=log)
def stop(name):
p=processes.pop(name)
p.send_signal(signal.SIGINT if name=='db' else signal.SIGTERM); p.wait(timeout=15)
def wait(c):
for _ in range(60):
try:
c.call('GET','/health/ready',schema='Health');return
except Failure:time.sleep(.3)
raise RuntimeError('not ready; see logs')
def test(script,out=None,env=None):
p=subprocess.run([PY,script],cwd=LAB,text=True,capture_output=True,env=env)
print(p.stdout,flush=True)
if out:(LAB/'evidence'/out).write_text(p.stdout)
if p.returncode:print(p.stderr);raise RuntimeError(script+' failed')
try:
(ROOT/'redis').mkdir(exist_ok=True)
if not (ROOT/'postgres/PG_VERSION').exists():
subprocess.run([str(PG/'initdb'),'-D',str(ROOT/'postgres'),'-U','agent','-A','trust','--no-locale','-E','UTF8'],check=True,stdout=subprocess.DEVNULL)
start('db');start('cache');time.sleep(1);start('api')
c=Client();wait(c)
test('tests/smoke.py');test('student-tests/extra.py')
test('student-tests/database.py','local-explain-and-rollback.txt')
a,b,e,chat=c.bootstrap();m=c.message(a,chat,'persistence')['json']
for name in ('api','db','cache'):stop(name)
for name in ('db','cache'):start(name)
time.sleep(1);start('api');wait(c)
check(m in history(c,b,chat),'message lost')
c.call('GET','/api/v1/users/me',actor=a,schema='User')
print('PASS: actual API/PostgreSQL/Redis process restart preserves data and existing tokens',flush=True)
import redis
r=redis.Redis.from_url(os.environ['CACHE_URL']);check(r.exists('profile:v1:'+a['id']),'no cache key')
print('PASS: actual Redis cache key exists',flush=True)
stop('cache')
t=time.monotonic();c.call('GET','/api/v1/users/me',actor=a,schema='User');elapsed=time.monotonic()-t
check(elapsed<5,'cache timeout');c.call('GET','/api/v1/users/me',401,headers={'Authorization':'Bearer '+'a'*43})
print('PASS: Redis outage fallback %.3fs; invalid token rejected'%elapsed,flush=True)
start('cache');stop('db')
t=time.monotonic();c.call('GET','/api/v1/users/me',503,actor=a);elapsed=time.monotonic()-t
check(elapsed<8,'DB timeout');c.call('GET','/health/ready',503);c.call('GET','/health/live',schema='Health')
print('PASS: PostgreSQL outage 503 %.3fs; live 200, ready 503'%elapsed,flush=True)
start('db');wait(c)
stop('api');os.environ['SESSION_TTL_SECONDS']='2';start('api');wait(c)
test('student-tests/expiry.py')
print('PASS: native integration suite (Docker not available)',flush=True)
finally:
for name in list(processes):stop(name)
for log in logs:log.close()