Author SHA1 Message Date
allerg1q 23f4fd6d41 Implement lab3 load balancing and failover 2026-11-16 22:34:30 +03:00
25 changed files with 1327 additions and 18 deletions
+7
View File
@@ -18,3 +18,10 @@ __pycache__
node_modules
evidence
.DS_Store
.git
.env
.venv
__pycache__
.pytest_cache
*.pyc
evidence
+5
View File
@@ -30,3 +30,8 @@ coverage/
.vscode/
# Keep small, sanitized evidence summaries in evidence/ under version control.
# Inspect git diff --cached: ignore rules are not a secret scanner.
.env
.venv/
__pycache__/
*.pyc
evidence/*.tmp
+17
View File
@@ -0,0 +1,17 @@
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY src/ ./src/
COPY migrations/ ./migrations/
ENV HOST=0.0.0.0
ENV PORT=8080
EXPOSE 8080
CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8080", "--workers", "1"]
+116 -18
View File
@@ -1,37 +1,135 @@
# Отчёт — лабораторная 3
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
- **Автор, группа:** Матвиенко, БПИ2304
- **Целевая оценка:** 3
- **Commit/PR:** добавить после публикации
- **Использованные источники, библиотеки:** материалы и контракт лабораторной, Python 3.12, FastAPI, Uvicorn, PostgreSQL 16, Nginx 1.29, Docker Compose.
## Запуск из чистого clone
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
Для запуска необходимы Docker Desktop с Docker Compose, Git и WSL Ubuntu с установленным Make.
Создать файл `.env` в корне проекта, указав локальный пароль:
```env
POSTGRES_PASSWORD=<локальный_пароль>
SESSION_TTL_SECONDS=3600
```
Сборка и запуск:
```bash
docker compose up -d --build
docker compose ps -a
curl http://127.0.0.1:8080/health/ready
```
Миграции выполняются отдельным сервисом `migrate` перед запуском API. Проверить повторный запуск миграций:
```bash
docker compose run --rm --no-deps migrate
```
Проверки:
```bash
make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
```
После тестирования восстановить две реплики:
```bash
docker compose up -d --wait api1 api2
```
Безопасная остановка с сохранением данных:
```bash
docker compose down
```
Намеренное удаление учебной базы и контейнеров:
```bash
docker compose down -v
```
Последняя команда удаляет также именованные тома с данными PostgreSQL. Секреты из `.env` в репозиторий не добавляются.
## Архитектура и решения
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
Архитектура приложения:
**Клиент → Nginx → API1 / API2 → PostgreSQL**
Единая публичная точка входа — `http://localhost:8080`. Nginx распределяет запросы между двумя независимыми процессами FastAPI.
В общей PostgreSQL хранятся пользователи, чаты, сообщения, сессии и ключи идемпотентности. PostgreSQL является источником истины, а именованный Docker volume обеспечивает сохранность данных при перезапуске контейнеров.
Из второй лабораторной перенесены REST API, аутентификация, работа с PostgreSQL и SQL-миграции. В третьей лабораторной добавлены:
- Две API-реплики и балансировка через Nginx.
- Заголовок `X-Instance-Id`, уникальный для каждого процесса.
- Общая идемпотентность отправки сообщений с `Idempotency-Key`.
- Транзакционная защита от одновременного создания дубликатов сообщений.
- Отдельный сервис миграций и healthcheck контейнеров.
- Скрипты перезапуска инфраструктуры и остановки выбранной реплики.
Для повторного запроса с тем же ключом и содержимым возвращается ранее созданное сообщение. При изменении содержимого с тем же ключом возвращается HTTP 409. Запись сообщения и ключа выполняется в одной транзакции PostgreSQL.
Переменные `.env`: `POSTGRES_PASSWORD` задаёт пароль базы данных, `SESSION_TTL_SECONDS` — время жизни пользовательской сессии. Адрес `DATABASE_URL` формируется в Docker Compose.
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
| Критерий | Команда или сценарий | Наблюдаемый результат | Доказательство |
|---|---|---|---|
| Публичный smoke | `make test` | PASS | `evidence/smoke.txt` |
| Две API-реплики | Получение `X-Instance-Id` от `api1` и `api2` | Два различных UUID | `evidence/instances.txt` |
| Проверка сохранности | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | PASS, данные и сессия сохранены | `evidence/persistence.txt` |
| Отказ одной реплики | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | PASS, 122 успешные записи, 0 ошибок | `evidence/failover.txt` |
| Восстановление записи | Сценарий failover | 0,909 секунды | `evidence/failover.txt` |
| Повторные миграции | `docker compose run --rm --no-deps migrate` | Обе миграции уже применены | `evidence/migrations.txt` |
| Состояние контейнеров | `docker compose ps -a` | Обе API-реплики и PostgreSQL healthy | `evidence/containers.txt` |
| Реальный перезапуск | `bash scripts/restart.sh` и `docker inspect` | Изменилось время запуска PostgreSQL и двух API | `evidence/restart-before.txt`, `evidence/restart-action.txt`, `evidence/restart-after.txt` |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
Уровень 4 и трек 5 не заявлены.
## Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
**Гипотеза:** после остановки одной API-реплики запросы продолжат обрабатываться оставшимся экземпляром, подтверждённые сообщения не потеряются, пользовательская сессия сохранится.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
**Испытательная среда:** Windows, WSL Ubuntu, Docker Desktop, два процесса FastAPI, PostgreSQL 16 и Nginx 1.29. Проверки проведены 16 ноября 2026 года на локальном стенде.
Результаты теста отказа:
```text
observed_instances_before: 2
successful_writes: 122
failed_attempts: 0
first_recovery_seconds: 0.909
PASS: failover preserved confirmed data and existing session.
```
| Воздействие | Ожидание | Наблюдаемый результат | Восстановление / данные |
|---|---|---|---|
| Остановка одной API-реплики | Работа через оставшуюся реплику | PASS, 122 записи, 0 ошибок | 0,909 с, потерь подтверждённых данных не выявлено |
| Перезапуск API и PostgreSQL | Сохранение записей и сессий | Persistence PASS | Данные и сессия сохранены |
| Повторное применение миграций | Отсутствие повторных изменений схемы | `Already applied` для двух миграций | Успешное завершение |
Дополнительно подтверждён фактический перезапуск инфраструктуры. Время запуска PostgreSQL изменилось с `19:31:02 UTC` на `19:31:47 UTC`, а API-реплик — примерно с `19:31:09 UTC` на `19:31:53 UTC`.
После перезапуска оба API-контейнера перешли в состояние `healthy`. Проверка readiness возвращала HTTP 200, а заголовки `X-Instance-Id` двух реплик различались.
Результаты 122 успешных записей и 0 ошибок относятся к автоматическому failover-сценарию, а не к отдельному нагрузочному тесту. Отдельные измерения RPS, p50/p95/p99, CPU/RAM, длительности прогрева и серии повторов не проводились.
## Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
Реализация выдерживает остановку одной API-реплики. Однако PostgreSQL и Nginx остаются едиными точками отказа. Резервирование базы данных и балансировщика не реализовано.
Идемпотентность использует транзакции и блокировки PostgreSQL, поэтому дополнительный Redis не требуется, но производительность такого решения под высокой нагрузкой отдельно не измерялась.
В дальнейшем возможны резервирование PostgreSQL, мониторинг, автоматизированные нагрузочные испытания и независимое масштабирование API.
**Вывод:** реализована работа двух API-реплик через единый балансировщик. Публичный smoke, persistence и failover завершились успешно. При отказе одной реплики тест выполнил 122 записи без ошибок, восстановление записи заняло 0,909 секунды. Подтверждены сохранность данных, сессий и реальный перезапуск инфраструктуры.
+74
View File
@@ -0,0 +1,74 @@
services:
db:
image: postgres:16-alpine
environment:
POSTGRES_DB: messenger
POSTGRES_USER: messenger
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set password in .env}
volumes:
- postgres_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U messenger -d messenger"]
interval: 5s
timeout: 3s
retries: 20
restart: unless-stopped
migrate:
build: .
command: ["python", "-m", "src.migrate"]
environment:
DATABASE_URL: postgresql://messenger:${POSTGRES_PASSWORD}@db:5432/messenger
depends_on:
db:
condition: service_healthy
restart: "no"
api1:
build: .
environment:
DATABASE_URL: postgresql://messenger:${POSTGRES_PASSWORD}@db:5432/messenger
SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600}
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=3)"]
interval: 5s
timeout: 3s
retries: 20
stop_grace_period: 15s
restart: unless-stopped
api2:
build: .
environment:
DATABASE_URL: postgresql://messenger:${POSTGRES_PASSWORD}@db:5432/messenger
SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600}
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=3)"]
interval: 5s
timeout: 3s
retries: 20
stop_grace_period: 15s
restart: unless-stopped
nginx:
image: nginx:1.29-alpine
ports:
- "127.0.0.1:8080:80"
volumes:
- ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
depends_on:
api1:
condition: service_healthy
api2:
condition: service_healthy
restart: unless-stopped
volumes:
postgres_data:
+1
View File
@@ -0,0 +1 @@
29cf28a5-c15d-4cd8-afe2-66f66dce42ea
+1
View File
@@ -0,0 +1 @@
700d8531-6668-4348-b607-548988b19a42
+6
View File
@@ -0,0 +1,6 @@
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
mtusi2026lab3-api1-1 mtusi2026lab3-api1 "uvicorn src.main:ap…" api1 9 minutes ago Up 20 seconds (healthy) 8080/tcp
mtusi2026lab3-api2-1 mtusi2026lab3-api2 "uvicorn src.main:ap…" api2 9 minutes ago Up 20 seconds (healthy) 8080/tcp
mtusi2026lab3-db-1 postgres:16-alpine "docker-entrypoint.s…" db 9 minutes ago Up 26 seconds (healthy) 5432/tcp
mtusi2026lab3-migrate-1 mtusi2026lab3-migrate "python -m src.migra…" migrate 9 minutes ago Exited (0) 5 seconds ago
mtusi2026lab3-nginx-1 nginx:1.29-alpine "/docker-entrypoint.…" nginx 9 minutes ago Up 9 minutes 127.0.0.1:8080->80/tcp
+4
View File
@@ -0,0 +1,4 @@
python3 tests/resilience.py --mode failover --action-script "scripts/stop-one.sh" --base-url "http://localhost:8080"
Executing explicit failover hook; hook output suppressed to avoid leaking secrets.
{"observed_instances_before": 2, "successful_writes": 122, "failed_attempts": 0, "first_recovery_seconds": 0.909}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
+4
View File
@@ -0,0 +1,4 @@
api1:
c4cba6f5-7569-4569-b8fa-5fa6ee05ba47
api2:
483700e7-418e-4967-a1fe-ef8047157299
+3
View File
@@ -0,0 +1,3 @@
Already applied: 001_initial.sql
Already applied: 002_idempotency.sql
Migrations completed
+3
View File
@@ -0,0 +1,3 @@
python3 tests/resilience.py --mode persistence --action-script "scripts/restart.sh" --base-url "http://localhost:8080"
Executing explicit persistence hook; hook output suppressed to avoid leaking secrets.
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.
+37
View File
@@ -0,0 +1,37 @@
Stopping API replicas...
Container mtusi2026lab3-api2-1 Stopping
Container mtusi2026lab3-api1-1 Stopping
Container mtusi2026lab3-api1-1 Stopped
Container mtusi2026lab3-api2-1 Stopped
Restarting PostgreSQL...
Container mtusi2026lab3-db-1 Restarting
Container mtusi2026lab3-db-1 Started
Container mtusi2026lab3-db-1 Running
Container mtusi2026lab3-db-1 Waiting
Container mtusi2026lab3-db-1 Healthy
Starting API replicas...
Container mtusi2026lab3-db-1 Running
Container mtusi2026lab3-migrate-1 Created
Container mtusi2026lab3-api2-1 Created
Container mtusi2026lab3-api1-1 Created
Container mtusi2026lab3-db-1 Waiting
Container mtusi2026lab3-db-1 Healthy
Container mtusi2026lab3-migrate-1 Starting
Container mtusi2026lab3-migrate-1 Started
Container mtusi2026lab3-migrate-1 Waiting
Container mtusi2026lab3-migrate-1 Waiting
Container mtusi2026lab3-migrate-1 Exited
Container mtusi2026lab3-api2-1 Starting
Container mtusi2026lab3-migrate-1 Exited
Container mtusi2026lab3-api1-1 Starting
Container mtusi2026lab3-api1-1 Started
Container mtusi2026lab3-api2-1 Started
Container mtusi2026lab3-api1-1 Waiting
Container mtusi2026lab3-api2-1 Waiting
Container mtusi2026lab3-db-1 Waiting
Container mtusi2026lab3-migrate-1 Waiting
Container mtusi2026lab3-db-1 Healthy
Container mtusi2026lab3-migrate-1 Exited
Container mtusi2026lab3-api1-1 Healthy
Container mtusi2026lab3-api2-1 Healthy
Restart complete. Volumes preserved.
+3
View File
@@ -0,0 +1,3 @@
/mtusi2026lab3-api1-1 2026-11-16T19:31:53.527997798Z
/mtusi2026lab3-api2-1 2026-11-16T19:31:53.529776269Z
/mtusi2026lab3-db-1 2026-11-16T19:31:47.080811938Z
+3
View File
@@ -0,0 +1,3 @@
/mtusi2026lab3-api1-1 2026-11-16T19:31:09.094359828Z
/mtusi2026lab3-api2-1 2026-11-16T19:31:09.096234406Z
/mtusi2026lab3-db-1 2026-11-16T19:31:02.648013137Z
+2
View File
@@ -0,0 +1,2 @@
python3 tests/smoke.py --base-url "http://localhost:8080"
PASS: lab3 public API scenario; infrastructure and grading evidence remain separate.
+74
View File
@@ -0,0 +1,74 @@
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 clock_timestamp(),
CONSTRAINT username_format
CHECK (username ~ '^[a-z0-9_]{3,32}$'),
CONSTRAINT display_name_length
CHECK (char_length(display_name) BETWEEN 1 AND 100),
CONSTRAINT display_name_not_blank
CHECK (length(btrim(display_name)) > 0)
);
CREATE TABLE IF NOT EXISTS chats (
id UUID PRIMARY KEY,
title VARCHAR(100) NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp(),
CONSTRAINT title_not_blank
CHECK (length(btrim(title)) > 0)
);
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),
position INTEGER NOT NULL,
PRIMARY KEY (chat_id, user_id),
UNIQUE (chat_id, position)
);
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 TEXT NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp(),
CONSTRAINT message_length
CHECK (char_length(text) BETWEEN 1 AND 4000),
CONSTRAINT message_not_blank
CHECK (length(btrim(text)) > 0)
);
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,
revoked BOOLEAN NOT NULL DEFAULT FALSE,
created_at TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp()
);
CREATE INDEX IF NOT EXISTS idx_chat_members_user
ON chat_members(user_id, chat_id);
CREATE INDEX IF NOT EXISTS idx_chats_order
ON chats(created_at, id);
CREATE INDEX IF NOT EXISTS idx_messages_history
ON messages(chat_id, created_at, id);
CREATE INDEX IF NOT EXISTS idx_sessions_user
ON sessions(user_id);
CREATE INDEX IF NOT EXISTS idx_sessions_expiry
ON sessions(expires_at);
+14
View File
@@ -0,0 +1,14 @@
CREATE TABLE IF NOT EXISTS message_idempotency (
user_id UUID NOT NULL REFERENCES users(id),
chat_id UUID NOT NULL REFERENCES chats(id),
idempotency_key VARCHAR(128) NOT NULL,
request_hash CHAR(64) NOT NULL,
message_id UUID NOT NULL REFERENCES messages(id),
created_at TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp(),
PRIMARY KEY (user_id, chat_id, idempotency_key)
);
CREATE INDEX IF NOT EXISTS idx_idempotency_created
ON message_idempotency(created_at);
+36
View File
@@ -0,0 +1,36 @@
events {
worker_connections 1024;
}
http {
resolver 127.0.0.11 valid=2s ipv6=off;
resolver_timeout 2s;
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 80;
location / {
proxy_pass http://messenger_api;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_connect_timeout 2s;
proxy_read_timeout 30s;
proxy_send_timeout 30s;
proxy_next_upstream error timeout http_502 http_503 http_504;
proxy_next_upstream_tries 2;
}
}
}
+4
View File
@@ -0,0 +1,4 @@
fastapi==0.115.12
uvicorn==0.34.2
psycopg[binary]==3.2.6
argon2-cffi==23.1.0
+16
View File
@@ -0,0 +1,16 @@
#!/usr/bin/env bash
set -euo pipefail
cd "$(dirname "$0")/.."
echo "Stopping API replicas..."
docker compose stop api1 api2
echo "Restarting PostgreSQL..."
docker compose restart db
docker compose up -d --wait db
echo "Starting API replicas..."
docker compose up -d --wait api1 api2
echo "Restart complete. Volumes preserved."
+33
View File
@@ -0,0 +1,33 @@
#!/usr/bin/env bash
set -euo pipefail
cd "$(dirname "$0")/.."
if [[ -z "${TARGET_INSTANCE_ID:-}" ]]; then
echo "TARGET_INSTANCE_ID is not set" >&2
exit 1
fi
for service in api1 api2; do
instance_id=$(
docker compose exec -T "$service" python -c '
import urllib.request
response = urllib.request.urlopen(
"http://127.0.0.1:8080/health/live",
timeout=2
)
print(response.headers.get("X-Instance-Id", ""))
' 2>/dev/null
) || continue
if [[ "$instance_id" == "$TARGET_INSTANCE_ID" ]]; then
echo "Stopping $service"
docker compose stop -t 2 "$service"
exit 0
fi
done
echo "Target API instance not found" >&2
exit 1
View File
+811
View File
@@ -0,0 +1,811 @@
import base64
import hashlib
import json
import os
import re
import secrets
import uuid
from datetime import datetime, timedelta, timezone
import psycopg
from psycopg.rows import dict_row
from psycopg.errors import UniqueViolation
from argon2 import PasswordHasher
from argon2.exceptions import (
VerifyMismatchError,
VerificationError,
InvalidHashError,
)
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse, Response
from fastapi.exceptions import RequestValidationError
from starlette.exceptions import HTTPException as StarletteHTTPException
app = FastAPI(title="MTUSI Messenger Lab3")
INSTANCE_ID = str(uuid.uuid4())
DATABASE_URL = os.environ["DATABASE_URL"]
SESSION_TTL_SECONDS = int(os.getenv("SESSION_TTL_SECONDS", "3600"))
password_hasher = PasswordHasher()
# ---------- Helpers ----------
class ApiError(Exception):
def __init__(self, status, code, message, headers=None):
self.status = status
self.code = code
self.message = message
self.headers = headers or {}
def fail(status, code, message, headers=None):
raise ApiError(status, code, message, headers)
def db():
return psycopg.connect(DATABASE_URL, row_factory=dict_row)
def utc_string(value):
return value.astimezone(timezone.utc).isoformat(
timespec="microseconds"
).replace("+00:00", "Z")
def user_json(row):
return {
"id": str(row["id"]),
"username": row["username"],
"display_name": row["display_name"],
"created_at": utc_string(row["created_at"]),
}
def message_json(row):
return {
"id": str(row["id"]),
"chat_id": str(row["chat_id"]),
"sender_id": str(row["sender_id"]),
"text": row["text"],
"created_at": utc_string(row["created_at"]),
}
def chat_json(conn, row):
members = conn.execute(
"""
SELECT user_id FROM chat_members
WHERE chat_id = %s
ORDER BY position
""",
(row["id"],)
).fetchall()
return {
"id": str(row["id"]),
"title": row["title"],
"member_ids": [str(m["user_id"]) for m in members],
"created_at": utc_string(row["created_at"]),
}
def valid_uuid(value):
if not isinstance(value, str):
return False
try:
return str(uuid.UUID(value)) == value
except ValueError:
return False
def valid_text(value, maximum):
return (
isinstance(value, str)
and 1 <= len(value) <= maximum
and bool(value.strip())
)
def validate_limit(request):
value = request.query_params.get("limit", "50")
if not re.fullmatch(r"[0-9]+", value):
fail(400, "invalid_request", "Invalid limit")
number = int(value)
if not 1 <= number <= 100:
fail(400, "invalid_request", "Invalid limit")
return number
def make_cursor(resource, row):
payload = {
"resource": resource,
"created_at": utc_string(row["created_at"]),
"id": str(row["id"]),
}
raw = json.dumps(payload).encode("utf-8")
return base64.urlsafe_b64encode(raw).decode().rstrip("=")
def read_cursor(cursor, resource):
if not isinstance(cursor, str) or not cursor:
fail(400, "invalid_request", "Invalid cursor")
try:
raw = base64.urlsafe_b64decode(
cursor + "=" * (-len(cursor) % 4)
)
value = json.loads(raw)
if value["resource"] != resource:
raise ValueError()
if not valid_uuid(value["id"]):
raise ValueError()
timestamp = datetime.fromisoformat(
value["created_at"].replace("Z", "+00:00")
)
if timestamp.tzinfo is None:
raise ValueError()
return timestamp, value["id"]
except (ValueError, KeyError, TypeError, UnicodeDecodeError):
fail(400, "invalid_request", "Invalid cursor")
async def json_body(request, required, allowed):
content_type = request.headers.get("content-type", "")
media_type = content_type.split(";")[0].strip().lower()
if media_type != "application/json":
fail(415, "unsupported_media_type", "Expected JSON")
try:
data = await request.json()
except Exception:
fail(400, "invalid_request", "Invalid JSON")
if not isinstance(data, dict):
fail(400, "invalid_request", "Expected JSON object")
if not set(required).issubset(data):
fail(400, "invalid_request", "Missing fields")
if not set(data).issubset(allowed):
fail(400, "invalid_request", "Unexpected fields")
return data
def unauthorized(kind="Bearer"):
if kind == "Basic":
header = 'Basic realm="messenger", charset="UTF-8"'
else:
header = 'Bearer realm="messenger"'
fail(
401,
"unauthorized",
"Authentication required",
{"WWW-Authenticate": header},
)
def current_user(request):
authorization = request.headers.get("Authorization", "")
if not authorization.startswith("Bearer "):
unauthorized()
token = authorization[7:]
if not token:
unauthorized()
token_hash = hashlib.sha256(token.encode()).hexdigest()
with db() as conn:
row = 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.revoked = FALSE
AND s.expires_at > clock_timestamp()
""",
(token_hash,)
).fetchone()
if row is None:
unauthorized()
return row
def accessible_chat(conn, chat_id, user_id):
if not valid_uuid(chat_id):
fail(400, "invalid_request", "Invalid chat ID")
row = conn.execute(
"""
SELECT c.id, c.title, c.created_at
FROM chats c
JOIN chat_members m ON m.chat_id = c.id
WHERE c.id = %s AND m.user_id = %s
""",
(chat_id, user_id)
).fetchone()
if row is None:
fail(404, "not_found", "Chat not found")
return row
# ---------- Request IDs and errors ----------
def error_response(request, status, code, message, headers=None):
request_id = request.state.request_id
response_headers = {
"X-Request-Id": request_id,
**(headers or {}),
}
return JSONResponse(
status_code=status,
content={
"error": {
"code": code,
"message": message,
"request_id": request_id,
}
},
headers=response_headers,
)
@app.middleware("http")
async def add_request_id(request, call_next):
request.state.request_id = str(uuid.uuid4())
try:
response = await call_next(request)
except psycopg.OperationalError:
response = error_response(
request, 503, "unavailable", "Database unavailable"
)
except Exception:
response = error_response(
request, 500, "internal_error", "Internal server error"
)
response.headers["X-Request-Id"] = request.state.request_id
response.headers["X-Instance-Id"] = INSTANCE_ID
return response
@app.exception_handler(ApiError)
async def api_error_handler(request, exc):
return error_response(
request, exc.status, exc.code, exc.message, exc.headers
)
@app.exception_handler(StarletteHTTPException)
async def http_error_handler(request, exc):
return error_response(
request, exc.status_code,
"not_found" if exc.status_code == 404 else "invalid_request",
"Resource not found" if exc.status_code == 404 else "Invalid request",
)
@app.exception_handler(RequestValidationError)
async def validation_error_handler(request, exc):
return error_response(
request, 400, "invalid_request", "Invalid request"
)
# ---------- Health ----------
@app.get("/health/live")
def health_live():
return {"status": "ok"}
@app.get("/health/ready")
def health_ready():
try:
with db() as conn:
conn.execute("SELECT 1")
return {"status": "ok"}
except psycopg.Error:
fail(503, "unavailable", "Database unavailable")
# ---------- Users ----------
@app.post("/api/v1/users", status_code=201)
async def create_user(request: Request):
data = await json_body(
request,
required=["username", "display_name", "password"],
allowed=["username", "display_name", "password"],
)
username = data["username"]
display_name = data["display_name"]
password = data["password"]
if (
not isinstance(username, str)
or not re.fullmatch(r"[a-z0-9_]{3,32}", username)
or not valid_text(display_name, 100)
or not isinstance(password, str)
or not 12 <= len(password) <= 128
):
fail(400, "invalid_request", "Invalid user fields")
password_hash = password_hasher.hash(password)
user_id = str(uuid.uuid4())
try:
with db() as conn:
row = conn.execute(
"""
INSERT INTO users
(id, username, display_name, password_hash)
VALUES (%s, %s, %s, %s)
RETURNING id, username, display_name, created_at
""",
(user_id, username, display_name, password_hash)
).fetchone()
return user_json(row)
except UniqueViolation:
fail(409, "conflict", "Username already exists")
@app.get("/api/v1/users/me")
def get_me(request: Request):
return user_json(current_user(request))
# ---------- Sessions ----------
@app.post("/api/v1/auth/sessions", status_code=201)
async def create_session(request: Request):
authorization = request.headers.get("Authorization", "")
if not authorization.startswith("Basic "):
unauthorized("Basic")
try:
encoded = authorization[6:]
decoded = base64.b64decode(encoded, validate=True).decode("utf-8")
if ":" not in decoded:
raise ValueError()
username, password = decoded.split(":", 1)
except (ValueError, UnicodeDecodeError):
unauthorized("Basic")
if not re.fullmatch(r"[a-z0-9_]{3,32}", username):
unauthorized("Basic")
with db() as conn:
row = conn.execute(
"SELECT * FROM users WHERE username = %s",
(username,)
).fetchone()
if row is None:
unauthorized("Basic")
try:
password_hasher.verify(row["password_hash"], password)
except (VerifyMismatchError, VerificationError, InvalidHashError):
unauthorized("Basic")
token = secrets.token_urlsafe(32)
token_hash = hashlib.sha256(token.encode()).hexdigest()
expires_at = datetime.now(timezone.utc) + timedelta(
seconds=SESSION_TTL_SECONDS
)
with db() as conn:
conn.execute(
"""
INSERT INTO sessions (token_hash, user_id, expires_at)
VALUES (%s, %s, %s)
""",
(token_hash, row["id"], expires_at)
)
return {
"token": token,
"token_type": "Bearer",
"expires_at": utc_string(expires_at),
"user": user_json(row),
}
@app.delete("/api/v1/auth/sessions/current", status_code=204)
def logout(request: Request):
current_user(request)
token = request.headers["Authorization"][7:]
token_hash = hashlib.sha256(token.encode()).hexdigest()
with db() as conn:
conn.execute(
"UPDATE sessions SET revoked = TRUE WHERE token_hash = %s",
(token_hash,)
)
return Response(status_code=204)
# ---------- Chats ----------
@app.post("/api/v1/chats", status_code=201)
async def create_chat(request: Request):
actor = current_user(request)
data = await json_body(
request,
required=["title", "member_ids"],
allowed=["title", "member_ids"],
)
title = data["title"]
member_ids = data["member_ids"]
if not valid_text(title, 100):
fail(400, "invalid_request", "Invalid title")
if (
not isinstance(member_ids, list)
or not 1 <= len(member_ids) <= 100
or not all(valid_uuid(x) for x in member_ids)
or len(member_ids) != len(set(member_ids))
or str(actor["id"]) not in member_ids
):
fail(400, "invalid_request", "Invalid members")
chat_id = str(uuid.uuid4())
with db() as conn:
# All operations use one transaction.
existing = conn.execute(
"""
SELECT id FROM users
WHERE id = ANY(%s::uuid[])
FOR KEY SHARE
""",
(member_ids,)
).fetchall()
if len(existing) != len(member_ids):
fail(400, "invalid_request", "Unknown member")
row = conn.execute(
"""
INSERT INTO chats (id, title)
VALUES (%s, %s)
RETURNING id, title, created_at
""",
(chat_id, title)
).fetchone()
for position, member_id in enumerate(member_ids):
conn.execute(
"""
INSERT INTO chat_members (chat_id, user_id, position)
VALUES (%s, %s, %s)
""",
(chat_id, member_id, position)
)
result = chat_json(conn, row)
return result
@app.get("/api/v1/chats")
def list_chats(request: Request):
actor = current_user(request)
limit = validate_limit(request)
cursor = request.query_params.get("cursor")
resource = "chats:" + str(actor["id"])
with db() as conn:
if cursor is None:
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
""",
(actor["id"], limit + 1)
).fetchall()
else:
timestamp, last_id = read_cursor(cursor, resource)
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
AND (c.created_at, c.id) > (%s, %s)
ORDER BY c.created_at, c.id
LIMIT %s
""",
(actor["id"], timestamp, last_id, limit + 1)
).fetchall()
has_more = len(rows) > limit
page = rows[:limit]
items = [chat_json(conn, row) for row in page]
next_cursor = (
make_cursor(resource, page[-1])
if has_more else None
)
return {"items": items, "next_cursor": next_cursor}
@app.get("/api/v1/chats/{chat_id}")
def get_chat(chat_id: str, request: Request):
actor = current_user(request)
with db() as conn:
row = accessible_chat(conn, chat_id, actor["id"])
result = chat_json(conn, row)
return result
def get_idempotency_key(request):
key = request.headers.get("Idempotency-Key")
if (
key is None
or not re.fullmatch(r"[A-Za-z0-9._:-]{1,128}", key)
):
fail(
400,
"invalid_request",
"Invalid or missing Idempotency-Key"
)
return key
def request_fingerprint(data):
normalized = {
"text": data["text"],
"attachment_ids": [],
}
encoded = json.dumps(
normalized,
ensure_ascii=False,
sort_keys=True,
separators=(",", ":")
).encode("utf-8")
return hashlib.sha256(encoded).hexdigest()
def idempotency_lock_id(user_id, chat_id, key):
scope = f"{user_id}:{chat_id}:{key}"
digest = hashlib.sha256(
scope.encode("utf-8")
).digest()
return int.from_bytes(
digest[:8],
byteorder="big",
signed=True
)
# ---------- Messages ----------
@app.post("/api/v1/chats/{chat_id}/messages", status_code=201)
async def send_message(chat_id: str, request: Request):
actor = current_user(request)
data = await json_body(
request,
required=["text"],
allowed=["text"],
)
if not valid_text(data["text"], 4000):
fail(
400,
"invalid_request",
"Invalid message text"
)
key = get_idempotency_key(request)
fingerprint = request_fingerprint(data)
user_id = actor["id"]
with db() as conn:
# First check access to the chat.
accessible_chat(conn, chat_id, user_id)
# Lock the idempotency scope across API replicas.
lock_id = idempotency_lock_id(
user_id, chat_id, key
)
conn.execute(
"SELECT pg_advisory_xact_lock(%s)",
(lock_id,)
)
# Allow reuse after the 24-hour window.
conn.execute(
"""
DELETE FROM message_idempotency
WHERE user_id = %s
AND chat_id = %s
AND idempotency_key = %s
AND created_at < clock_timestamp()
- INTERVAL '24 hours'
""",
(user_id, chat_id, key)
)
previous = conn.execute(
"""
SELECT i.request_hash, m.*
FROM message_idempotency i
JOIN messages m ON m.id = i.message_id
WHERE i.user_id = %s
AND i.chat_id = %s
AND i.idempotency_key = %s
""",
(user_id, chat_id, key)
).fetchone()
if previous is not None:
if previous["request_hash"] != fingerprint:
fail(
409,
"conflict",
"Idempotency-Key already used "
"with different content"
)
return message_json(previous)
# Create exactly one message.
message_id = str(uuid.uuid4())
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
""",
(
message_id,
chat_id,
user_id,
data["text"],
)
).fetchone()
# Store the key in the same transaction.
conn.execute(
"""
INSERT INTO message_idempotency
(
user_id,
chat_id,
idempotency_key,
request_hash,
message_id
)
VALUES (%s, %s, %s, %s, %s)
""",
(
user_id,
chat_id,
key,
fingerprint,
message_id,
)
)
return message_json(row)
@app.get("/api/v1/chats/{chat_id}/messages")
def list_messages(chat_id: str, request: Request):
actor = current_user(request)
limit = validate_limit(request)
cursor = request.query_params.get("cursor")
resource = "messages:" + chat_id
with db() as conn:
accessible_chat(conn, chat_id, actor["id"])
if cursor is None:
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()
else:
timestamp, last_id = read_cursor(cursor, resource)
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, timestamp, last_id, limit + 1)
).fetchall()
has_more = len(rows) > limit
page = rows[:limit]
next_cursor = (
make_cursor(resource, page[-1])
if has_more else None
)
items = [message_json(row) for row in page]
return {"items": items, "next_cursor": next_cursor}
+53
View File
@@ -0,0 +1,53 @@
import os
from pathlib import Path
import psycopg
DATABASE_URL = os.environ["DATABASE_URL"]
MIGRATIONS_DIR = Path(__file__).resolve().parent.parent / "migrations"
def run_migrations():
with psycopg.connect(DATABASE_URL) as conn:
with conn.cursor() as cur:
# Prevent simultaneous migration runs.
cur.execute("SELECT pg_advisory_xact_lock(2026002)")
cur.execute("""
CREATE TABLE IF NOT EXISTS schema_migrations (
version TEXT PRIMARY KEY,
applied_at TIMESTAMPTZ NOT NULL
DEFAULT clock_timestamp()
)
""")
for file in sorted(MIGRATIONS_DIR.glob("*.sql")):
cur.execute(
"SELECT 1 FROM schema_migrations WHERE version = %s",
(file.name,)
)
if cur.fetchone():
print(f"Already applied: {file.name}")
continue
sql = file.read_text(encoding="utf-8")
for statement in sql.split(";"):
if statement.strip():
cur.execute(statement)
cur.execute(
"INSERT INTO schema_migrations (version) VALUES (%s)",
(file.name,)
)
print(f"Applied migration: {file.name}")
print("Migrations completed")
if __name__ == "__main__":
run_migrations()