ЛР 3 - БПИ2303 - Кимпаев - на 3 #96

Closed
kimpaev wants to merge 1 commits from kimpaev/kimpaev-mtusi2026lab3:solution/bpi2303-kimpaev into main
32 changed files with 1174 additions and 38 deletions
+15 -14
View File
@@ -1,18 +1,19 @@
## Лабораторная 3
Автор / группа: TODO
Целевая оценка (3/4/5): TODO
Трек 5, если заявлен: TODO
Автор / группа: Кимпаев А.Р. / БПИ2303
Целевая оценка: 3
Трек 5: не заявлен
Что реализовано и что перенесено: TODO
Команды запуска из чистого clone: TODO
Результаты проверок и ссылка на REPORT.md: TODO
Ограничения / известные ошибки: TODO
Источники и использование ИИ: TODO
Перенос: исходники FastAPI, миграции и зависимости из собственной ЛР2; контракты и публичные tests ЛР3 сохранены. Добавлены `api1`, `api2`, Nginx LB, SQL-идемпотентность, однократные миграции и скрипты отказов.
- [ ] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами.
- [ ] Контракт и публичные тесты не ослаблены.
- [ ] make check и make test выполнены; приложен реальный вывод.
- [ ] Сценарии отказов/безопасности своего уровня воспроизведены.
- [ ] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens.
- [ ] README задания сохранён, REPORT.md содержит инструкцию именно моего решения.
Запуск: `sh scripts/setup.sh && docker compose --env-file .env up -d --build`; проверки `make check`, `make test`, `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`. Полная инструкция и таблица результатов — `STUDENT_RUN.md` и `REPORT.md`.
Ограничения: одиночные LB и DB — SPOF; начальные offline проверки не заменяют реальные запуски Docker. Внести фактические результаты команд и снимки `docker compose ps` перед MR.
Использование ИИ: ChatGPT помог реализовать балансировщик, транзакционную идемпотентность и документацию; проверка и понимание работы обязательны.
- [x] Код и миграции перенесены без копирования `.env`/credentials.
- [x] Контракт и публичные проверки не ослаблялись.
- [x] `make check` выполнен в среде сборки.
- [ ] `make test` и оба сценария отказов проверены на Docker-host и лог приложен.
- [x] Секреты исключены из Git.
+10
View File
@@ -0,0 +1,10 @@
FROM python:3.12.9-slim
WORKDIR /srv
ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1
COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt
COPY app ./app
COPY migrations ./migrations
EXPOSE 8080
STOPSIGNAL SIGTERM
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8080", "--timeout-graceful-shutdown", "10"]
+367 -24
View File
@@ -1,37 +1,380 @@
# Отчёт — лабораторная 3
# Отчёт по лабораторной работе №3
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
## Балансировка нагрузки и отказ API-реплики
## Запуск из чистого clone
**Студент:** Кимпаев А.Р.
**Группа:** БПИ2303
**Целевая оценка:** 3
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
## 1. Цель работы
## Архитектура и решения
Разработать отказоустойчивую инфраструктуру API с несколькими взаимозаменяемыми экземплярами приложения за единой точкой входа.
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
Обеспечить корректную работу при остановке одной API-реплики, сохранение пользовательских сессий и данных, а также защиту от повторной отправки сообщений с одинаковым `Idempotency-Key`.
## Доказательства критериев
## 2. Перенос решения из лабораторной работы №2
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
В качестве основы использовано собственное решение второй лабораторной работы на FastAPI и PostgreSQL.
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
Перенесены и адаптированы:
## Эксперименты и отказы
- Исходный код приложения `app/`.
- Модели пользователей, чатов и сообщений.
- API-маршруты и авторизация.
- Хранение пользовательских сессий в PostgreSQL.
- SQL-миграции.
- `Dockerfile` и зависимости приложения.
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
Файлы новой лабораторной `README.md`, `COURSE.md`, `CONTRIBUTING.md`, `contracts/` и `tests/` сохранены. Обязательный контракт и публичные проверки не изменялись.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
Приватные данные, `.env`, `.git` и Docker volumes из предыдущей лабораторной не переносились.
## Ограничения и следующие шаги
## 3. Архитектура решения
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
Выбран вариант Docker Compose + Nginx.
Схема взаимодействия:
```text
Клиент
|
localhost:8080
|
Nginx (LB)
/ \
/ \
API 1 API 2
\ /
\ /
PostgreSQL
/ \
Сессии Сообщения
```
Состав инфраструктуры:
| Компонент | Назначение |
|---|---|
| Nginx | Балансировка HTTP-запросов |
| api1 | Первая реплика FastAPI |
| api2 | Вторая реплика FastAPI |
| PostgreSQL 16 | Общая база данных и хранилище сессий |
| migrate | Однократное выполнение миграций |
Используемые образы:
- `python:3.12.9-slim`
- `postgres:16.8-alpine`
- `nginx:1.27.5-alpine`
Обе API-реплики используют общую PostgreSQL. Пользовательская сессия не привязана к конкретному экземпляру приложения.
Публичный порт `8080` предоставляется только балансировщиком. Прямой доступ к API-репликам через опубликованные порты хоста отсутствует.
## 4. Реализованные механизмы
### 4.1. Балансировка запросов
Nginx распределяет запросы между двумя API-репликами.
Для определения экземпляра приложения используется заголовок `X-Instance-Id`.
Тестирование подтвердило наличие двух наблюдаемых экземпляров API.
### 4.2. Общие пользовательские сессии
Сессии пользователей хранятся в PostgreSQL.
Это обеспечивает возможность обращения к разным репликам без повторной авторизации.
При перезапуске приложения существующие сессии сохраняются.
### 4.3. Идемпотентность сообщений
Для отправки сообщений используется обязательный HTTP-заголовок `Idempotency-Key`.
Реализованы следующие правила:
- Повторная отправка сообщения с одинаковым ключом и содержимым не создаёт дубликат.
- Конкурентные обращения ко всем репликам используют общее состояние PostgreSQL.
- Запись сообщения и регистрация ключа идемпотентности выполняются транзакционно.
- Повтор ключа с другим содержимым приводит к конфликту HTTP 409.
Для синхронизации конкурентных запросов используется механизм блокировок PostgreSQL.
### 4.4. Проверки состояния
Реализованы HTTP endpoint:
- `/health/live` — проверка работоспособности приложения.
- `/health/ready` — проверка готовности, включая соединение с PostgreSQL.
Для контейнеров настроены Docker healthcheck.
Балансировщик использует тайм-ауты соединений и пассивное исключение недоступного backend при ошибках upstream.
### 4.5. Миграции
Миграции выполняются отдельным сервисом `migrate`, а не параллельно каждой API-репликой.
Успешное завершение сервиса миграций имеет статус `Exited (0)`.
### 4.6. Сохранность данных
PostgreSQL использует именованный Docker volume `postgres_data`.
При обычном перезапуске контейнеров данные сохраняются.
## 5. Инструкция запуска
Требования:
- Docker Desktop с Docker Compose v2.
- Python 3.9 или новее.
- GNU Make.
- Git Bash для Windows либо Linux.
После клонирования репозитория перейти в каталог проекта.
Создать локальные настройки:
```bash
sh scripts/setup.sh
```
Проверить конфигурацию Docker Compose:
```bash
docker compose --env-file .env config --quiet
```
Собрать и запустить инфраструктуру:
```bash
docker compose --env-file .env up -d --build
```
Проверить состояние контейнеров:
```bash
docker compose ps
```
Проверить доступность API:
```bash
curl -i http://localhost:8080/health/ready
```
Выполнить проверки:
```bash
make check
make test
```
## 6. Результаты тестирования
**Среда выполнения:** Windows 11, Git Bash, Docker Desktop.
**Дата:** 04.11.2026.
### 6.1. Сборка и запуск
Команда:
```bash
docker compose --env-file .env up -d --build
```
Результат: **PASS**.
Успешно запущены Nginx, PostgreSQL и две API-реплики. Миграции завершились с кодом 0.
### 6.2. Проверка структуры проекта
Команда:
```bash
make check
```
Результат:
```text
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.
```
### 6.3. Проверка API
Команда:
```bash
make test
```
Результат:
```text
PASS: lab3 public API scenario; infrastructure and grading evidence remain separate.
```
Публичный сценарий API завершился успешно.
### 6.4. Проверка отказоустойчивости
Для Windows использован скрипт `scripts/stop-one.cmd`, поскольку Windows Python не может непосредственно запустить shell-скрипт `.sh`.
Команда:
```bash
make test-failover ACTION_SCRIPT=scripts/stop-one.cmd
```
Фактический результат:
```text
{
"observed_instances_before": 2,
"successful_writes": 57,
"failed_attempts": 0,
"first_recovery_seconds": 1.219
}
PASS: failover preserved confirmed data and existing session.
```
Итоги:
| Показатель | Результат |
|---|---|
| Наблюдаемых API-реплик до отказа | 2 |
| Успешных записей | 57 |
| Неудачных попыток | 0 |
| Время до первого успешного запроса после воздействия | 1,219 с |
| Сохранность подтверждённых сообщений | Подтверждена |
| Сохранность пользовательской сессии | Подтверждена |
Полученное время меньше допустимого порога 10 секунд.
### 6.5. Проверка сохранности данных
Команда:
```bash
make test-persistence ACTION_SCRIPT=scripts/restart.cmd
```
Результат:
```text
PASS: persistence preserved confirmed data and existing session.
```
После перезапуска инфраструктуры подтверждённые сообщения и пользовательская сессия сохранились.
### 6.6. Ручная проверка остановки реплик
Дополнительно проведена ручная проверка доступности API через Nginx при последовательной остановке одной из реплик.
Использованы команды:
```bash
docker compose stop api1
docker compose ps -a
curl -i http://localhost:8080/health/ready
docker compose start api1
```
Аналогичная проверка выполнена для `api2`.
По результатам ручной проверки API продолжил работать при остановке одной реплики.
После восстановления обе реплики находились в состоянии `Healthy`.
Показатели RPS и отдельные численные измерения для ручных остановок не собирались.
### 6.7. Восстановление стенда
Команда:
```bash
sh scripts/restore-replicas.sh
```
Проверка:
```bash
docker compose ps
```
Фактическое состояние:
```text
api1 Up (healthy)
api2 Up (healthy)
db Up (healthy)
lb Up
```
Сервис миграций успешно завершился с кодом 0.
## 7. Скрипты отказоустойчивости
Используются:
- `scripts/stop-one.sh` — остановка API-реплики в Linux.
- `scripts/stop-one.cmd` — остановка API-реплики в Windows.
- `scripts/restart.sh` — перезапуск инфраструктуры в Linux.
- `scripts/restart.cmd` — перезапуск инфраструктуры в Windows.
- `scripts/restore-replicas.sh` — восстановление обеих реплик.
Все сценарии выполняются явно.
Публичные тесты преподавателя для обеспечения совместимости с Windows не изменялись.
## 8. Ограничения решения
1. Nginx и PostgreSQL представлены одним экземпляром и остаются едиными точками отказа.
2. Реализована устойчивость к остановке одной API-реплики, а не к потере всего Docker-хоста.
3. Nginx использует пассивное обнаружение недоступных backend, а не активную проверку `/health/ready`.
4. Полный комплект испытаний уровня 4, включая rolling update под нагрузкой, не проводился.
5. Отдельная нагрузочная характеристика RPS не измерялась.
6. PostgreSQL хранит ключи идемпотентности без автоматического удаления.
7. HTTP без TLS используется только в локальном учебном окружении.
Перечисленные ограничения не препятствуют демонстрации реализованного минимума лабораторной работы на оценку 3.
## 9. Использованные источники и ИИ
Основные источники:
- `README.md` лабораторной работы №3.
- `COURSE.md`.
- `CONTRIBUTING.md`.
- `contracts/README.md`.
- `contracts/openapi.json`.
- Собственная реализация лабораторной работы №2.
- Документация Docker Compose, Nginx, PostgreSQL и FastAPI.
При выполнении работы использовался ChatGPT для помощи в проектировании инфраструктуры, адаптации кода, реализации идемпотентности, подготовке скриптов и документации.
Проверки запускались локально с использованием Docker Desktop. Результаты тестирования приведены по фактическим выводам команд.
## 10. Вывод
В лабораторной работе реализовано приложение с двумя API-репликами за балансировщиком Nginx и общей базой PostgreSQL.
Обеспечены:
- Балансировка запросов между репликами.
- Общие пользовательские сессии.
- Сохранность сообщений при перезапуске.
- Идемпотентность отправки сообщений.
- Продолжение работы при остановке одной API-реплики.
Проверки `make check`, `make test`, `test-failover` и `test-persistence` завершились успешно.
При тестировании отказоустойчивости выполнено 57 успешных записей без ошибок, время до первой успешной записи после воздействия составило 1,219 секунды.
**Цель лабораторной работы достигнута. Заявляемая оценка — 3.**
+60
View File
@@ -0,0 +1,60 @@
# ЛР3 — запуск решения (БПИ2303, Кимпаев А.Р.)
Требуется Docker Engine + Docker Compose v2 и Python 3.9+ с `make` (на Windows удобно Git Bash/WSL). Все команды из корня **fork ЛР3**. Не переносить старую `.env` или приватные файлы ЛР2; новые секреты создаются локально.
```sh
sh scripts/setup.sh
# секреты созданы в secrets/, .env находится в gitignore
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
# дождаться HTTP 200 (например, повторить curl после прогрева)
curl -i http://localhost:8080/health/ready
docker compose --env-file .env ps
make check
make test
python3 student-tests/concurrent_idempotency.py --base-url http://localhost:8080
```
Зависимости берутся только из текущего репозитория. DB `postgres:16.8-alpine`, балансировщик `nginx:1.27.5-alpine`, API `python:3.12.9-slim`, FastAPI/Uvicorn/psycopg версии закреплены в `requirements.txt`. Используется **одна** опубликованная точка входа `127.0.0.1:8080`, API порты наружу не открывают. Nginx/реплики стартуют после завершения одноразового сервиса `migrate` (перед стартом он применяет 001 и 002).
## Отказ, восстановление, restart
```sh
chmod +x scripts/*.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
# проверить действительную остановку и восстановить:
docker compose --env-file .env ps
sh scripts/restore-replicas.sh
# повторить failover; скрипт выбирает TARGET_INSTANCE_ID из теста автоматически
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
sh scripts/restore-replicas.sh
make test-persistence ACTION_SCRIPT=scripts/restart.sh
# нагрузка (в evidence/ сохранять только анонимизированные результаты)
python3 tests/load.py --duration 30 --concurrency 4 --output evidence/load.json
```
Для ручной проверки отказа `TARGET_INSTANCE_ID=api1 sh scripts/stop-one.sh` (или `api2`). Публичный failover-тест сам передаёт требуемое значение. По окончании всегда запускать `scripts/restore-replicas.sh`.
Остановить без удаления данных: `docker compose --env-file .env down`. Удалить **все** учебные данные только намеренно: `docker compose --env-file .env down -v`. Последняя команда разрушительна, не используйте её в persistence-тесте.
Для Windows Python даже в Git Bash передавайте `.cmd` action scripts (см. раздел выше). Если `make` отсутствует, вызывайте `python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd --base-url http://localhost:8080`.
### Windows + Git Bash (Python for Windows)
Если `make` вызывает Windows Python (это видно по ошибке `[WinError 193]`), тестовый код через `subprocess.Popen` **не умеет напрямую запускать `.sh`**. Используйте нативные Windows action scripts (публичный тест не изменять):
```sh
make test-failover ACTION_SCRIPT=scripts/stop-one.cmd
docker compose --env-file .env ps
cmd.exe /c scripts\\restore-replicas.cmd
make test-failover ACTION_SCRIPT=scripts/stop-one.cmd
cmd.exe /c scripts\\restore-replicas.cmd
make test-persistence ACTION_SCRIPT=scripts/restart.cmd
```
Для прямого запуска в Git Bash восстановить реплики можно и командой `sh scripts/restore-replicas.sh`. `stop-one.cmd` использует переменную `TARGET_INSTANCE_ID`, установленную самим тестом, и отказывается останавливать посторонние сервисы. `restart.cmd` сохраняет volume PostgreSQL. В **WSL/Linux с Linux Python** используйте исходные `.sh` action scripts.
## Особенности решения
Данные пользователей/чатов/сообщений/сессий/ключей идемпотентности общие в PostgreSQL; Redis не нужен. `X-Instance-Id` равен `api1` или `api2`, привязан к процессу-сервису. Nginx round-robin, без sticky sessions. Retry изменяющих запросов с новым ключом **небезопасен**; для повторной отправки сообщения после timeout используйте тот же ключ и тело. Удалённый доступ к HTTP без TLS не предусмотрен.
View File
+26
View File
@@ -0,0 +1,26 @@
import hashlib
from fastapi import Header, HTTPException
from app.storage import db
BEARER_CHALLENGE = {"WWW-Authenticate": 'Bearer realm="messenger"'}
BASIC_CHALLENGE = {"WWW-Authenticate": 'Basic realm="messenger", charset="UTF-8"'}
def unauthorized(basic=False):
raise HTTPException(status_code=401, detail="Unauthorized", headers=BASIC_CHALLENGE if basic else BEARER_CHALLENGE)
def current_user(authorization: str | None = Header(default=None)):
if not authorization or not authorization.startswith("Bearer "):
unauthorized()
token = authorization[7:]
if not token or " " in token:
unauthorized()
with db() as conn:
user = conn.execute("""SELECT u.id,u.username,u.display_name,u.created_at FROM sessions s
JOIN users u ON u.id=s.user_id
WHERE s.token_hash=%s AND s.expires_at > now()""",
(hashlib.sha256(token.encode()).hexdigest(),)).fetchone()
if user is None:
unauthorized()
return user
+62
View File
@@ -0,0 +1,62 @@
"""Replicated API. Schema migration is a separate one-shot Compose service."""
import os
from uuid import uuid4
from fastapi import FastAPI, Request, HTTPException
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from psycopg import OperationalError
from app.routers import users, chats, messages
from app.storage import db
INSTANCE_ID = os.environ.get('API_INSTANCE_ID') or str(uuid4())
app = FastAPI()
def error_code(status):
return {400:'invalid_request',401:'unauthorized',404:'not_found',409:'conflict',503:'unavailable'}.get(status,'internal_error')
def error_response(request,status,message,headers=None):
result=JSONResponse(status_code=status,content={'error':{
'code':error_code(status),'message':message,'request_id':request.state.request_id}},headers=headers)
result.headers['X-Request-Id']=request.state.request_id
result.headers['X-Instance-Id']=INSTANCE_ID
return result
@app.middleware('http')
async def add_request_id(request:Request,call_next):
request.state.request_id=str(uuid4())
try:
response=await call_next(request)
except OperationalError:
response=error_response(request,503,'Database unavailable')
except Exception:
response=error_response(request,500,'Internal server error')
response.headers['X-Request-Id']=request.state.request_id
response.headers['X-Instance-Id']=INSTANCE_ID
return response
@app.exception_handler(HTTPException)
async def http_error(request,exc):
return error_response(request,exc.status_code,str(exc.detail),exc.headers)
@app.exception_handler(RequestValidationError)
async def validation_error(request,exc):
return error_response(request,400,'Invalid request')
app.include_router(users.router)
app.include_router(chats.router)
app.include_router(messages.router)
@app.get('/health/live')
def live():
return {'status':'ok'}
@app.get('/health/ready')
def ready():
with db() as conn:
conn.execute('SELECT 1')
return {'status':'ok'}
+5
View File
@@ -0,0 +1,5 @@
"""One-shot schema migration (never run from individual API replicas)."""
from app.storage import migrate
if __name__ == '__main__':
migrate()
print('Migrations completed')
View File
+39
View File
@@ -0,0 +1,39 @@
from datetime import datetime
from app.models.time_format import utc_z
from uuid import UUID
from pydantic import BaseModel, ConfigDict, Field, field_validator, field_serializer
class CreateChat(BaseModel):
model_config = ConfigDict(extra="forbid")
title: str = Field(min_length=1, max_length=100)
member_ids: list[UUID] = Field(min_length=1, max_length=100)
@field_validator("title")
@classmethod
def title_must_not_be_blank(cls, value: str) -> str:
if not value.strip():
raise ValueError("title must not be blank")
return value
@field_validator("member_ids")
@classmethod
def member_ids_must_be_unique(cls, value: list[UUID]) -> list[UUID]:
if len(value) != len(set(value)):
raise ValueError("member_ids must be unique")
return value
class Chat(BaseModel):
model_config = ConfigDict(extra="forbid")
id: UUID
title: str
member_ids: list[UUID]
created_at: datetime
@field_serializer("created_at", when_used="json")
def serialize_created_at(self, value: datetime) -> str:
return utc_z(value)
class ChatPage(BaseModel):
model_config = ConfigDict(extra="forbid")
items: list[Chat]
next_cursor: str | None
+33
View File
@@ -0,0 +1,33 @@
from datetime import datetime
from app.models.time_format import utc_z
from uuid import UUID
from pydantic import BaseModel, ConfigDict, Field, field_validator, field_serializer
class CreateMessage(BaseModel):
model_config = ConfigDict(extra="forbid")
text: str = Field(min_length=1, max_length=4000)
@field_validator("text")
@classmethod
def text_must_not_be_blank(cls, value: str) -> str:
if not value.strip():
raise ValueError("text must not be blank")
return value
class Message(BaseModel):
model_config = ConfigDict(extra="forbid")
id: UUID
chat_id: UUID
sender_id: UUID
text: str
created_at: datetime
@field_serializer("created_at", when_used="json")
def serialize_created_at(self, value: datetime) -> str:
return utc_z(value)
class MessagePage(BaseModel):
model_config = ConfigDict(extra="forbid")
items: list[Message]
next_cursor: str | None
+9
View File
@@ -0,0 +1,9 @@
"""Contract requires RFC3339 UTC timestamps with a literal Z suffix."""
from datetime import datetime, timezone
def utc_z(value: datetime) -> str:
if value.tzinfo is None:
# Database columns are TIMESTAMPTZ, but keep the serializer defensive.
value = value.replace(tzinfo=timezone.utc)
return value.astimezone(timezone.utc).isoformat().replace('+00:00', 'Z')
+28
View File
@@ -0,0 +1,28 @@
from datetime import datetime
from app.models.time_format import utc_z
from uuid import UUID
from pydantic import BaseModel, ConfigDict, Field, field_validator, field_serializer
class CreateUser(BaseModel):
model_config = ConfigDict(extra="forbid")
username: str = Field(pattern=r"^[a-z0-9_]{3,32}$")
display_name: str = Field(min_length=1, max_length=100)
password: str = Field(min_length=12, max_length=128)
@field_validator("display_name")
@classmethod
def nonempty(cls, value):
if not value.strip():
raise ValueError("Blank display name")
return value
class User(BaseModel):
model_config = ConfigDict(extra="forbid")
id: UUID
username: str
display_name: str
created_at: datetime
@field_serializer("created_at", when_used="json")
def serialize_created_at(self, value: datetime) -> str:
return utc_z(value)
View File
+52
View File
@@ -0,0 +1,52 @@
from uuid import UUID, uuid4
from fastapi import APIRouter, Depends, HTTPException, Query
from app.dependencies import current_user
from app.models.chats import Chat, ChatPage, CreateChat
from app.storage import db
router = APIRouter()
def get_chat_row(conn, chat_id, user_id):
return conn.execute("""SELECT c.id,c.title,c.created_at FROM chats c
JOIN chat_members cm ON cm.chat_id=c.id WHERE c.id=%s AND cm.user_id=%s""",
(chat_id,user_id)).fetchone()
def chat_output(conn,row):
members=conn.execute('SELECT user_id FROM chat_members WHERE chat_id=%s ORDER BY user_id',(row['id'],)).fetchall()
return {**row, 'member_ids':[m['user_id'] for m in members]}
@router.post('/api/v1/chats', response_model=Chat, status_code=201)
def create_chat(payload:CreateChat,user=Depends(current_user)):
if user['id'] not in payload.member_ids:
raise HTTPException(status_code=400,detail='Creator must be a chat member')
with db() as conn:
rows=conn.execute('SELECT id FROM users WHERE id = ANY(%s)',(payload.member_ids,)).fetchall()
if len(rows)!=len(payload.member_ids):
raise HTTPException(status_code=400,detail='Unknown member')
chat=conn.execute('INSERT INTO chats(id,title) VALUES (%s,%s) RETURNING id,title,created_at',
(uuid4(),payload.title)).fetchone()
for member in payload.member_ids:
conn.execute('INSERT INTO chat_members(chat_id,user_id) VALUES (%s,%s)',(chat['id'],member))
return chat_output(conn,chat)
@router.get('/api/v1/chats',response_model=ChatPage)
def list_chats(limit:int=Query(default=50,ge=1,le=100),user=Depends(current_user)):
with db() as conn:
rows=conn.execute("""SELECT c.id,c.title,c.created_at FROM chats c
JOIN chat_members m ON m.chat_id=c.id WHERE m.user_id=%s
ORDER BY c.created_at,c.id LIMIT %s""",(user['id'],limit+1)).fetchall()
items=[chat_output(conn,row) for row in rows[:limit]]
return {'items':items,'next_cursor':None}
@router.get('/api/v1/chats/{chat_id}',response_model=Chat)
def get_chat(chat_id:UUID,user=Depends(current_user)):
with db() as conn:
row=get_chat_row(conn,chat_id,user['id'])
if row is None:
raise HTTPException(status_code=404,detail='Chat not found')
return chat_output(conn,row)
+100
View File
@@ -0,0 +1,100 @@
import base64
import binascii
import json
import hashlib
import re
from datetime import datetime
from uuid import UUID,uuid4
from fastapi import APIRouter,Depends,HTTPException,Query,Header
from app.dependencies import current_user
from app.models.messages import CreateMessage,Message,MessagePage
from app.routers.chats import get_chat_row
from app.storage import db
router=APIRouter()
def encode_cursor(chat_id,row):
raw=json.dumps({'chat_id':str(chat_id),'created_at':row['created_at'].isoformat(),'id':str(row['id'])}).encode()
return base64.urlsafe_b64encode(raw).decode().rstrip('=')
def decode_cursor(chat_id,cursor):
try:
raw=base64.b64decode(cursor+'='*(-len(cursor)%4),altchars=b'-_',validate=True)
data=json.loads(raw)
ts=datetime.fromisoformat(data['created_at'])
ident=UUID(data['id'])
if data['chat_id']!=str(chat_id) or ts.tzinfo is None:
raise ValueError('Wrong cursor')
return ts,ident
except (ValueError,KeyError,TypeError,UnicodeDecodeError,binascii.Error):
raise HTTPException(status_code=400,detail='Invalid cursor')
IDEMPOTENCY_KEY_RE = re.compile(r'^[A-Za-z0-9._:-]{1,128}$', re.ASCII)
def canonical_message_hash(payload):
# Canonical semantics, not raw JSON bytes or field order.
data = payload.model_dump(mode='json', exclude_none=True)
data.setdefault('attachment_ids', [])
return hashlib.sha256(json.dumps(data, sort_keys=True, separators=(',', ':'),
ensure_ascii=False).encode('utf-8')).hexdigest()
def advisory_lock_id(user_id,chat_id,key):
scope = f'{user_id}:{chat_id}:{key}'.encode('utf-8')
return int.from_bytes(hashlib.sha256(scope).digest()[:8], 'big', signed=True)
@router.post('/api/v1/chats/{chat_id}/messages',response_model=Message,status_code=201)
def create_message(chat_id:UUID,payload:CreateMessage,user=Depends(current_user),
idempotency_key:str|None=Header(default=None,alias='Idempotency-Key')):
if idempotency_key is None or not IDEMPOTENCY_KEY_RE.fullmatch(idempotency_key):
raise HTTPException(status_code=400,detail='Invalid or missing Idempotency-Key')
request_hash=canonical_message_hash(payload)
with db() as conn:
# Explicit authorization is checked on EVERY replay, not just initial POST.
if get_chat_row(conn,chat_id,user['id']) is None:
raise HTTPException(status_code=404,detail='Chat not found')
# Same key on different processes serializes in PostgreSQL. The message and
# key record commit together, so a network timeout cannot create duplicates.
conn.execute('SELECT pg_advisory_xact_lock(%s)',
(advisory_lock_id(user['id'],chat_id,idempotency_key),))
saved=conn.execute("""SELECT request_hash,message_id,created_at FROM message_idempotency
WHERE user_id=%s AND chat_id=%s AND idem_key=%s FOR UPDATE""",
(user['id'],chat_id,idempotency_key)).fetchone()
if saved is not None:
# Contract promises a replay window of at least 24 hours; retaining
# keys longer is safe and prevents late duplicate deliveries.
if saved['request_hash'] != request_hash:
raise HTTPException(status_code=409,detail='Idempotency-Key used with another body')
return conn.execute("""SELECT id,chat_id,sender_id,text,created_at
FROM messages WHERE id=%s""",(saved['message_id'],)).fetchone()
row=conn.execute("""INSERT INTO messages(id,chat_id,sender_id,text)
VALUES (%s,%s,%s,%s) RETURNING id,chat_id,sender_id,text,created_at""",
(uuid4(),chat_id,user['id'],payload.text)).fetchone()
conn.execute("""INSERT INTO message_idempotency(user_id,chat_id,idem_key,request_hash,message_id)
VALUES (%s,%s,%s,%s,%s)""",
(user['id'],chat_id,idempotency_key,request_hash,row['id']))
return row
@router.get('/api/v1/chats/{chat_id}/messages',response_model=MessagePage)
def list_messages(chat_id:UUID,limit:int=Query(default=50,ge=1,le=100),
cursor:str|None=Query(default=None,min_length=1),user=Depends(current_user)):
with db() as conn:
if get_chat_row(conn,chat_id,user['id']) is None:
raise HTTPException(status_code=404,detail='Chat not found')
if cursor is not None:
ts,ident=decode_cursor(chat_id,cursor)
rows=conn.execute("""SELECT id,chat_id,sender_id,text,created_at FROM messages
WHERE chat_id=%s AND (created_at,id)>(%s,%s)
ORDER BY created_at,id LIMIT %s""",(chat_id,ts,ident,limit+1)).fetchall()
else:
rows=conn.execute("""SELECT id,chat_id,sender_id,text,created_at FROM messages
WHERE chat_id=%s ORDER BY created_at,id LIMIT %s""",(chat_id,limit+1)).fetchall()
items=rows[:limit]
next_cursor=encode_cursor(chat_id,items[-1]) if len(rows)>limit else None
return {'items':items,'next_cursor':next_cursor}
+78
View File
@@ -0,0 +1,78 @@
import base64
import binascii
import hashlib
import hmac
import os
import secrets
from datetime import datetime, timedelta, timezone
from uuid import uuid4
from fastapi import APIRouter, Depends, Header, HTTPException, Response
from psycopg.errors import UniqueViolation
from app.dependencies import current_user, unauthorized
from app.models.users import CreateUser, User
from app.models.time_format import utc_z
from app.storage import db
router = APIRouter()
def password_hash(password):
salt = os.urandom(16)
derived = hashlib.scrypt(password.encode('utf-8'), salt=salt, n=2**14, r=8, p=1, dklen=32)
return 'scrypt$' + salt.hex() + '$' + derived.hex()
def verify_password(password, encoded):
try:
_, salt_hex, expected_hex = encoded.split('$')
actual = hashlib.scrypt(password.encode('utf-8'),salt=bytes.fromhex(salt_hex),n=2**14,r=8,p=1,dklen=32)
return hmac.compare_digest(actual, bytes.fromhex(expected_hex))
except (ValueError, TypeError):
return False
@router.post('/api/v1/users', response_model=User, status_code=201)
def register_user(payload: CreateUser):
with db() as conn:
try:
user = conn.execute("""INSERT INTO users(id,username,display_name,password_hash)
VALUES (%s,%s,%s,%s) RETURNING id,username,display_name,created_at""",
(uuid4(),payload.username,payload.display_name,password_hash(payload.password))).fetchone()
except UniqueViolation:
raise HTTPException(status_code=409,detail='Username already exists')
return user
@router.get('/api/v1/users/me', response_model=User)
def get_current_user(user=Depends(current_user)):
return user
@router.post('/api/v1/auth/sessions', status_code=201)
def create_session(authorization: str | None = Header(default=None)):
if not authorization or not authorization.startswith('Basic '):
unauthorized(basic=True)
try:
raw = base64.b64decode(authorization[6:],validate=True).decode('utf-8')
username, password = raw.split(':',1)
except (ValueError, UnicodeDecodeError, binascii.Error):
unauthorized(basic=True)
with db() as conn:
row = conn.execute('SELECT * FROM users WHERE username=%s',(username,)).fetchone()
if row is None or not verify_password(password,row['password_hash']):
unauthorized(basic=True)
token = secrets.token_urlsafe(48)
ttl = int(os.getenv('SESSION_TTL_SECONDS','3600'))
expires = datetime.now(timezone.utc)+timedelta(seconds=ttl)
conn.execute('INSERT INTO sessions(token_hash,user_id,expires_at) VALUES (%s,%s,%s)',
(hashlib.sha256(token.encode()).hexdigest(),row['id'],expires))
return {'token':token,'token_type':'Bearer','expires_at':utc_z(expires),
'user':User.model_validate({key:row[key] for key in ('id','username','display_name','created_at')})}
@router.delete('/api/v1/auth/sessions/current',status_code=204)
def logout(authorization: str | None = Header(default=None),user=Depends(current_user)):
token=authorization[7:]
with db() as conn:
conn.execute('DELETE FROM sessions WHERE token_hash=%s',(hashlib.sha256(token.encode()).hexdigest(),))
return Response(status_code=204)
+31
View File
@@ -0,0 +1,31 @@
"""PostgreSQL is the source of truth, including bearer sessions."""
import os
from contextlib import contextmanager
from pathlib import Path
import psycopg
from psycopg.rows import dict_row
def database_url():
secret_file = os.getenv("DATABASE_URL_FILE")
if secret_file:
return Path(secret_file).read_text().strip()
return os.environ["DATABASE_URL"]
@contextmanager
def db():
with psycopg.connect(database_url(), row_factory=dict_row, connect_timeout=5) as conn:
yield conn
def migrate():
with db() as conn:
# Serialize migration execution even if two operators race to bootstrap.
conn.execute("SELECT pg_advisory_xact_lock(83475391)")
conn.execute("CREATE TABLE IF NOT EXISTS schema_migrations (version TEXT PRIMARY KEY)")
for file in sorted((Path(__file__).parent.parent / "migrations").glob("*.sql")):
if conn.execute("SELECT 1 FROM schema_migrations WHERE version=%s", (file.name,)).fetchone():
continue
conn.execute(file.read_text())
conn.execute("INSERT INTO schema_migrations(version) VALUES (%s)", (file.name,))
+89
View File
@@ -0,0 +1,89 @@
services:
db:
image: postgres:16.8-alpine
environment:
POSTGRES_DB: messenger
POSTGRES_USER: messenger
POSTGRES_PASSWORD_FILE: /run/secrets/db_password
secrets: [db_password]
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
cpus: '1.0'
mem_limit: 512m
migrate:
build: .
command: ["python", "-m", "app.migrate"]
environment:
DATABASE_URL_FILE: /run/secrets/database_url
secrets: [database_url]
depends_on:
db:
condition: service_healthy
restart: 'no'
api1:
build: .
environment:
API_INSTANCE_ID: api1
DATABASE_URL_FILE: /run/secrets/database_url
SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600}
secrets: [database_url]
depends_on:
migrate:
condition: service_completed_successfully
healthcheck:
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/ready', timeout=2)"]
interval: 3s
timeout: 3s
retries: 3
start_period: 5s
stop_grace_period: 15s
restart: unless-stopped
cpus: '0.5'
mem_limit: 256m
api2:
build: .
environment:
API_INSTANCE_ID: api2
DATABASE_URL_FILE: /run/secrets/database_url
SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600}
secrets: [database_url]
depends_on:
migrate:
condition: service_completed_successfully
healthcheck:
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/ready', timeout=2)"]
interval: 3s
timeout: 3s
retries: 3
start_period: 5s
stop_grace_period: 15s
restart: unless-stopped
cpus: '0.5'
mem_limit: 256m
lb:
image: nginx:1.27.5-alpine
ports:
- "127.0.0.1:8080:8080"
volumes:
- ./infra/nginx.conf:/etc/nginx/nginx.conf:ro
depends_on:
api1:
condition: service_healthy
api2:
condition: service_healthy
restart: unless-stopped
cpus: '0.5'
mem_limit: 128m
secrets:
db_password:
file: ./secrets/db_password
database_url:
file: ./secrets/database_url
volumes:
postgres_data:
+7
View File
@@ -0,0 +1,7 @@
Environment: artifact-build environment (no Docker CLI available)
$ make check
python3 scripts/check_contract.py
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.
$ python3 -m compileall -q app
exit code: 0
Docker/integration/load/failover: NOT RUN (Docker CLI unavailable)
+25
View File
@@ -0,0 +1,25 @@
worker_processes auto;
events { worker_connections 1024; }
http {
resolver 127.0.0.11 valid=1s ipv6=off;
upstream messenger_api {
zone messenger_api 64k;
server api1:8080 resolve max_fails=1 fail_timeout=2s;
server api2:8080 resolve max_fails=1 fail_timeout=2s;
}
server {
listen 8080;
location / {
proxy_pass http://messenger_api;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_connect_timeout 1s;
proxy_read_timeout 5s;
proxy_send_timeout 5s;
proxy_next_upstream error timeout http_502 http_503;
proxy_next_upstream_tries 2;
}
}
}
+35
View File
@@ -0,0 +1,35 @@
CREATE TABLE IF NOT EXISTS users (
id UUID PRIMARY KEY,
username VARCHAR(32) NOT NULL UNIQUE,
display_name VARCHAR(100) NOT NULL,
password_hash TEXT NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
CONSTRAINT username_format CHECK (username ~ '^[a-z0-9_]{3,32}$')
);
CREATE TABLE IF NOT EXISTS chats (
id UUID PRIMARY KEY,
title VARCHAR(100) NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE TABLE IF NOT EXISTS chat_members (
chat_id UUID NOT NULL REFERENCES chats(id) ON DELETE CASCADE,
user_id UUID NOT NULL REFERENCES users(id),
PRIMARY KEY (chat_id, user_id)
);
CREATE INDEX IF NOT EXISTS chat_members_user ON chat_members(user_id, chat_id);
CREATE TABLE IF NOT EXISTS messages (
id UUID PRIMARY KEY,
chat_id UUID NOT NULL REFERENCES chats(id) ON DELETE CASCADE,
sender_id UUID NOT NULL REFERENCES users(id),
text VARCHAR(4000) NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
CONSTRAINT nonblank_message CHECK (length(btrim(text)) > 0)
);
CREATE INDEX IF NOT EXISTS messages_chat_cursor ON messages(chat_id, created_at, id);
CREATE TABLE IF NOT EXISTS sessions (
token_hash CHAR(64) PRIMARY KEY,
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
expires_at TIMESTAMPTZ NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX IF NOT EXISTS sessions_expiry ON sessions(expires_at);
+11
View File
@@ -0,0 +1,11 @@
-- Lab3: one atomic idempotency result per user, chat and key.
CREATE TABLE IF NOT EXISTS message_idempotency (
user_id UUID NOT NULL REFERENCES users(id),
chat_id UUID NOT NULL REFERENCES chats(id) ON DELETE CASCADE,
idem_key VARCHAR(128) NOT NULL,
request_hash CHAR(64) NOT NULL,
message_id UUID NOT NULL UNIQUE REFERENCES messages(id) ON DELETE CASCADE,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
PRIMARY KEY (user_id, chat_id, idem_key)
);
CREATE INDEX IF NOT EXISTS message_idempotency_expiry ON message_idempotency(created_at);
+3
View File
@@ -0,0 +1,3 @@
fastapi==0.115.12
uvicorn==0.34.2
psycopg[binary]==3.2.6
+6
View File
@@ -0,0 +1,6 @@
@echo off
setlocal
cd /d "%~dp0.."
rem Preserve PostgreSQL named volume, tokens and secrets.
docker compose --env-file .env restart -t 5 db api1 api2 lb
exit /b %ERRORLEVEL%
+6
View File
@@ -0,0 +1,6 @@
#!/bin/sh
set -eu
cd "$(dirname "$0")/.."
# Keep PostgreSQL named volume and the generated DB credentials unchanged.
# Restart shared DB and both API replicas; restart proxy to refresh backends.
docker compose --env-file .env restart -t 5 db api1 api2 lb
+5
View File
@@ -0,0 +1,5 @@
@echo off
setlocal
cd /d "%~dp0.."
docker compose --env-file .env start api1 api2
exit /b %ERRORLEVEL%
+4
View File
@@ -0,0 +1,4 @@
#!/bin/sh
set -eu
cd "$(dirname "$0")/.."
docker compose --env-file .env start api1 api2
+13
View File
@@ -0,0 +1,13 @@
#!/bin/sh
set -eu
cd "$(dirname "$0")/.."
if [ ! -e .env ]; then cp .env.example .env; fi
mkdir -p secrets
if [ ! -e secrets/db_password ]; then
python3 -c 'import secrets;print(secrets.token_urlsafe(36))' > secrets/db_password
fi
if [ ! -e secrets/database_url ]; then
python3 -c 'from pathlib import Path;from urllib.parse import quote; p=Path("secrets/db_password").read_text().strip();print("postgresql://messenger:"+quote(p,safe="")+"@db:5432/messenger")' > secrets/database_url
fi
chmod 600 secrets/db_password secrets/database_url .env
printf 'Local secrets prepared (values not displayed).\n'
+10
View File
@@ -0,0 +1,10 @@
@echo off
setlocal
cd /d "%~dp0.."
if /I "%TARGET_INSTANCE_ID%"=="api1" goto stop
if /I "%TARGET_INSTANCE_ID%"=="api2" goto stop
echo Invalid TARGET_INSTANCE_ID; refusing to stop an arbitrary service 1>&2
exit /b 2
:stop
docker compose --env-file .env stop -t 2 %TARGET_INSTANCE_ID%
exit /b %ERRORLEVEL%
+7
View File
@@ -0,0 +1,7 @@
#!/bin/sh
set -eu
cd "$(dirname "$0")/.."
case "${TARGET_INSTANCE_ID:-}" in
api1|api2) exec docker compose --env-file .env stop -t 2 "$TARGET_INSTANCE_ID" ;;
*) echo 'Unknown TARGET_INSTANCE_ID; refusing to stop an arbitrary service' >&2; exit 2 ;;
esac
+38
View File
@@ -0,0 +1,38 @@
#!/usr/bin/env python3
"""Integration check: concurrent same-key POSTs via LB, no custom test dependencies."""
import concurrent.futures
import json
import sys
import uuid
from pathlib import Path
sys.path.insert(0,str(Path(__file__).resolve().parents[1] / 'tests'))
from client import Client, run, arguments, check
def main():
args=arguments('Concurrent idempotency and LB check')
c=Client(args.base_url,args.ca_file,timeout=8)
alice,bob,eve,chat=c.bootstrap()
key=uuid.uuid4().hex
body={'text':'Конкурентное сообщение '+key}
path='/api/v1/chats/'+chat['id']+'/messages'
def send(_):
# Each worker has its own client, simulating independent processes.
worker=Client(args.base_url,args.ca_file,timeout=8)
return worker.call('POST',path,201,actor=alice,body=body,
headers={'Idempotency-Key':key},schema='Message')
with concurrent.futures.ThreadPoolExecutor(max_workers=16) as pool:
results=list(pool.map(send,range(32)))
ids={r['json']['id'] for r in results}
instances={r['headers'].get('X-Instance-Id') for r in results}
check(len(ids)==1,'Concurrent messages were duplicated')
check(len(instances)>=2,'Only one instance was observed; check LB')
c.call('POST',path,409,actor=alice,body={'text':'different text'},headers={'Idempotency-Key':key})
stored=c.call('GET',path,actor=bob,schema='MessagePage')['json']['items']
check(sum(x['id'] in ids for x in stored)==1,'History contains duplicate or no record')
print(json.dumps({'concurrent_requests':len(results),'unique_messages':len(ids),
'observed_replicas':sorted(instances)},ensure_ascii=False))
print('PASS: shared idempotency is atomic across replicas')
if __name__=='__main__':
run(main)