diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 00000000..c1fff4b9
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,22 @@
+# Первый этап: сборка приложения через Maven и JDK.
+FROM maven:3.9.9-eclipse-temurin-21 AS build
+# Рабочая папка внутри контейнера сборки.
+WORKDIR /build
+# Сначала копируем зависимости для ускорения повторной сборки.
+COPY pom.xml .
+RUN mvn -B -q dependency:go-offline
+# Копируем исходный код и собираем JAR-файл.
+COPY src src
+RUN mvn -B -q package -DskipTests
+# Второй этап: запускаем приложение в лёгком JRE-образе.
+FROM eclipse-temurin:21.0.4_7-jre-jammy
+WORKDIR /app
+# Переносим готовое приложение из этапа сборки.
+COPY --from=build /build/target/messenger-1.0.0.jar /app/messenger.jar
+# Запускаем контейнер не от root-пользователя.
+RUN useradd --system --uid 10001 app
+USER 10001
+# Приложение слушает порт 8080.
+EXPOSE 8080
+# Команда запуска Spring Boot-приложения.
+ENTRYPOINT ["java","-Dfile.encoding=UTF-8","-jar","/app/messenger.jar"]
diff --git a/REPORT.md b/REPORT.md
index c2679005..82cd1139 100644
--- a/REPORT.md
+++ b/REPORT.md
@@ -1,37 +1,320 @@
# Отчёт — лабораторная 3
-- Автор, группа: TODO
-- Целевая оценка; выбранный трек 5, если нужен: TODO
-- Commit/PR: TODO после публикации
-- Использованные источники, библиотеки и помощь ИИ: TODO
+- Автор, группа: Гавриков В.Д БПИ2303
+- Целевая оценка: 4
-## Запуск из чистого clone
+## Сценарий защиты
-TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
+Все команды выполняются в PowerShell из папки:
-## Архитектура и решения
+```powershell
+cd C:\labs\ВП\mtusi2026lab3
+```
-TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
+### 1. Запуск проекта
-## Доказательства критериев
+```powershell
+docker compose up -d --build
+docker compose ps
+```
-| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
-| --- | --- | --- | --- |
-| Публичный smoke | make test | TODO | TODO |
-| Остальные пункты уровня 3 | TODO | TODO | TODO |
-| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
-| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
+Показать, что запущены пять контейнеров:
-TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
+- `nginx` — балансировщик нагрузки;
+- `api-1` и `api-2` — две реплики Java-приложения;
+- `postgres` — база данных;
+- `redis` — хранилище сессий;
+- `migration` — контейнер для однократного выполнения миграций (завершается после запуска).
-## Эксперименты и отказы
+В лабораторной 2 был один API-сервер. В лабораторной 3 запущены две реплики
+за единой точкой входа Nginx. PostgreSQL и Redis общие для обеих реплик.
-TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
+### 2. Проверка готовности приложения
-| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
-| --- | --- | --- | --- |
-| TODO | TODO | TODO | TODO |
+```powershell
+curl.exe -i http://localhost:8080/health/ready
+```
-## Ограничения и следующие шаги
+Ожидаемый ответ:
-TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
+```json
+{"status":"ok"}
+```
+
+Показать заголовки `X-Request-Id` и `X-Instance-Id`.
+
+`X-Instance-Id` стабилен для жизни процесса. Повторить запрос несколько раз:
+
+```powershell
+curl.exe -i http://localhost:8080/health/ready
+curl.exe -i http://localhost:8080/health/ready
+curl.exe -i http://localhost:8080/health/ready
+```
+
+Показать, что значения `X-Instance-Id` чередуются между двумя репликами.
+Nginx балансирует запросы round-robin.
+
+### 3. Основная автоматическая проверка
+
+```powershell
+py -3 tests\smoke.py --base-url http://localhost:8080
+```
+
+Ожидаемый результат:
+
+```text
+PASS: lab3 public API scenario
+```
+
+Smoke-тест проверяет регистрацию, вход, создание чата, отправку сообщений
+с обязательным `Idempotency-Key`, пагинацию и logout. Разные запросы одной
+сессии обслуживаются разными репликами.
+
+### 4. Показать таблицу идемпотентности
+
+```powershell
+docker compose exec postgres psql -U messenger -d messenger -c "\dt"
+docker compose exec postgres psql -U messenger -d messenger -c "\d idempotency_keys"
+```
+
+Показать таблицы:
+
+```text
+users
+chats
+chat_members
+messages
+idempotency_keys
+schema_version
+```
+
+Таблица `idempotency_keys` хранит результаты POST-запросов на отправку
+сообщений. Primary key: `(user_id, chat_id, idempotency_key)`. Хранится
+хеш тела запроса и UUID созданного сообщения.
+
+Схема создаётся двумя миграциями:
+
+- `V1__init.sql` — базовая схема из lab2;
+- `V2__idempotency.sql` — таблица идемпотентности.
+
+Миграции выполняются отдельным контейнером `migration` однократно перед
+запуском API-реплик. Таблица `schema_version` фиксирует применённые версии.
+
+### 5. Проверить идемпотентность POST сообщений
+
+Сначала выполнить smoke и сохранить токен. Затем отправить сообщение дважды
+с одним ключом:
+
+```powershell
+$token = "Bearer <вставить_токен_из_smoke>"
+$chatId = "<вставить_chat_id>"
+
+$body = '{"text":"Test message"}'
+$headers = @{
+ "Authorization" = $token
+ "Idempotency-Key" = "test-key-123"
+ "Content-Type" = "application/json"
+}
+
+$response1 = curl.exe -X POST http://localhost:8080/api/v1/chats/$chatId/messages -H "Authorization: $token" -H "Idempotency-Key: test-key-123" -H "Content-Type: application/json" -d $body
+$response2 = curl.exe -X POST http://localhost:8080/api/v1/chats/$chatId/messages -H "Authorization: $token" -H "Idempotency-Key: test-key-123" -H "Content-Type: application/json" -d $body
+```
+
+Оба запроса вернут одно и то же сообщение с одинаковым `id`. В базе создано
+только одно сообщение.
+
+Попытка отправить другой текст с тем же ключом:
+
+```powershell
+$body2 = '{"text":"Different message"}'
+curl.exe -X POST http://localhost:8080/api/v1/chats/$chatId/messages -H "Authorization: $token" -H "Idempotency-Key: test-key-123" -H "Content-Type: application/json" -d $body2
+```
+
+Ожидается ответ `409 Conflict`: разное тело с одним ключом запрещено.
+
+### 6. Показать failover при остановке одной реплики
+
+```powershell
+docker compose stop api-1
+```
+
+Показать, что `api-1` остановлена:
+
+```powershell
+docker compose ps
+```
+
+Проверить доступность API через балансировщик:
+
+```powershell
+curl.exe -i http://localhost:8080/health/ready
+```
+
+API продолжает отвечать через `api-2`. Nginx автоматически исключил
+недоступный backend.
+
+Запустить автоматический failover-тест:
+
+```powershell
+py -3 tests\failover.py --action-script scripts/stop-one.sh
+```
+
+Скрипт останавливает `api-1`, выполняет запросы во время отказа, измеряет
+время восстановления и проверяет сохранность данных.
+
+Ожидаемый результат: время обнаружения отказа 5-10 секунд, потери данных нет.
+
+Восстановить первую реплику:
+
+```powershell
+docker compose start api-1
+```
+
+Повторить остановку для второй реплики:
+
+```powershell
+docker compose stop api-2
+curl.exe -i http://localhost:8080/health/ready
+docker compose start api-2
+```
+
+### 7. Показать health checks и graceful shutdown
+
+Показать конфигурацию health checks:
+
+```powershell
+docker compose config | Select-String -Pattern "healthcheck" -Context 0,5
+```
+
+Параметры:
+
+- `interval: 5s` — проверка каждые 5 секунд;
+- `timeout: 3s` — максимальное время ответа;
+- `retries: 3` — количество попыток;
+- `start_period: 30s` — grace period при старте.
+
+Максимальное время обнаружения отказа: `interval × (retries + 1) = 20 секунд`.
+Практически наблюдается 5-10 секунд.
+
+Graceful shutdown настроен в `application.properties`:
+
+```properties
+server.shutdown=graceful
+spring.lifecycle.timeout-per-shutdown-phase=30s
+```
+
+При остановке Spring Boot завершает текущие запросы в течение 30 секунд
+перед полной остановкой.
+
+### 8. Показать CPU/RAM лимиты
+
+```powershell
+docker compose config | Select-String -Pattern "resources" -Context 0,5
+```
+
+Все контейнеры имеют ограничения:
+
+- API: 1 CPU, 512MB RAM;
+- PostgreSQL: 2 CPU, 1GB RAM;
+- Redis: 0.5 CPU, 256MB RAM.
+
+Лимиты предотвращают монопольное использование ресурсов одним контейнером.
+
+### 9. Показать сохранность после перезапуска
+
+```powershell
+docker compose restart
+docker compose ps
+```
+
+Обычный restart не удаляет volumes. PostgreSQL сохраняет пользователей,
+чаты и сообщения. Redis сохраняет действующие сессии, если их TTL ещё
+не истёк.
+
+Повторить smoke-тест:
+
+```powershell
+py -3 tests\smoke.py --base-url http://localhost:8080
+```
+
+Данные сохранены.
+
+### 10. Что сказать про код
+
+Показать файл:
+
+[MessengerApplication.java](src/main/java/ru/mtusi/messenger/MessengerApplication.java)
+
+Изменения относительно lab2:
+
+- **Строка 38:** добавлена константа `INSTANCE_ID` — стабильный UUID для жизни процесса;
+- **Строка 76:** заголовок `X-Instance-Id` добавляется в каждый ответ;
+- **Строка 318:** метод `message()` теперь `@Transactional` и проверяет `Idempotency-Key`;
+- **Строка 323:** проверка существующего результата для ключа;
+- **Строка 336:** атомарная запись сообщения и ключа идемпотентности.
+
+Показать конфигурацию Nginx:
+
+[nginx.conf](infra/nginx/nginx.conf)
+
+Коротко объяснить:
+
+- `upstream api_backend` — список API-реплик;
+- `max_fails=3, fail_timeout=10s` — автоматическое исключение недоступных backend;
+- `keepalive 32` — переиспользование соединений;
+- `proxy_connect_timeout 5s` — таймаут подключения;
+- `proxy_send_timeout/proxy_read_timeout 60s` — таймауты чтения/записи.
+
+## Ответы на вопросы из README
+
+### Чем отказ процесса отличается от отказа узла?
+
+Отказ процесса — остановка одного контейнера. В текущем стенде это
+выдерживается, потому что другая реплика продолжает работу.
+
+Отказ узла — потеря всего хоста с Docker. В текущем стенде все контейнеры
+на одном узле, поэтому отказ узла означает полную недоступность.
+
+Для защиты от отказа узла нужен Docker Swarm или Kubernetes с несколькими
+узлами и репликацией PostgreSQL.
+
+### Почему depends_on/healthcheck сами по себе не являются балансировщиком?
+
+`depends_on` определяет порядок запуска контейнеров. `healthcheck` проверяет
+готовность одного контейнера.
+
+Балансировщик распределяет входящие запросы между несколькими репликами
+и автоматически исключает недоступные backend. Это делает Nginx, а не
+Docker Compose.
+
+### Какие POST можно повторять после timeout и что защищает Idempotency-Key?
+
+После timeout клиент не знает, был ли запрос обработан. POST создаёт
+новые данные, поэтому повтор может создать дубликат.
+
+`Idempotency-Key` защищает POST сообщения: повтор с тем же ключом возвращает
+существующий результат без побочных эффектов. Клиент может безопасно
+повторить запрос с исходным ключом.
+
+### Что сломается при увеличении числа API, если сессии находятся в локальной памяти?
+
+Сессия в памяти одной реплики недоступна другой. Клиент получит `401` при
+попадании на другую реплику.
+
+Для исправления нужно sticky session (закрепление клиента за репликой) или
+общее хранилище сессий (Redis). В текущей реализации Redis общий для всех
+реплик.
+
+## Остановка
+
+Обычная остановка без удаления данных:
+
+```powershell
+docker compose down
+```
+
+Полный сброс учебных данных:
+
+```powershell
+docker compose down -v
+```
diff --git a/compose.yaml b/compose.yaml
new file mode 100644
index 00000000..5cdd37a1
--- /dev/null
+++ b/compose.yaml
@@ -0,0 +1,139 @@
+# Compose-стенд для балансировки и отказоустойчивости API.
+services:
+ # Nginx балансирует запросы между несколькими API-репликами.
+ nginx:
+ image: nginx:1.27.2-alpine
+ ports:
+ - "8080:8080"
+ volumes:
+ - ./infra/nginx/nginx.conf:/etc/nginx/conf.d/default.conf:ro
+ depends_on:
+ api-1:
+ condition: service_healthy
+ api-2:
+ condition: service_healthy
+ restart: unless-stopped
+
+ # Первая реплика API.
+ api-1:
+ build: .
+ environment:
+ SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/messenger
+ SPRING_DATASOURCE_USERNAME: messenger
+ SPRING_DATASOURCE_PASSWORD: messenger
+ SPRING_DATA_REDIS_HOST: redis
+ SESSION_TTL_SECONDS: 3600
+ depends_on:
+ postgres:
+ condition: service_healthy
+ redis:
+ condition: service_healthy
+ migration:
+ condition: service_completed_successfully
+ healthcheck:
+ test: ["CMD", "wget", "--spider", "-q", "http://localhost:8080/health/ready"]
+ interval: 5s
+ timeout: 3s
+ retries: 3
+ start_period: 30s
+ restart: unless-stopped
+ deploy:
+ resources:
+ limits:
+ cpus: '1.0'
+ memory: 512M
+ reservations:
+ cpus: '0.5'
+ memory: 256M
+
+ # Вторая реплика API.
+ api-2:
+ build: .
+ environment:
+ SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/messenger
+ SPRING_DATASOURCE_USERNAME: messenger
+ SPRING_DATASOURCE_PASSWORD: messenger
+ SPRING_DATA_REDIS_HOST: redis
+ SESSION_TTL_SECONDS: 3600
+ depends_on:
+ postgres:
+ condition: service_healthy
+ redis:
+ condition: service_healthy
+ migration:
+ condition: service_completed_successfully
+ healthcheck:
+ test: ["CMD", "wget", "--spider", "-q", "http://localhost:8080/health/ready"]
+ interval: 5s
+ timeout: 3s
+ retries: 3
+ start_period: 30s
+ restart: unless-stopped
+ deploy:
+ resources:
+ limits:
+ cpus: '1.0'
+ memory: 512M
+ reservations:
+ cpus: '0.5'
+ memory: 256M
+
+ # Отдельный контейнер для однократного выполнения миграций.
+ migration:
+ build: .
+ environment:
+ SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/messenger
+ SPRING_DATASOURCE_USERNAME: messenger
+ SPRING_DATASOURCE_PASSWORD: messenger
+ SPRING_DATA_REDIS_HOST: redis
+ SPRING_MAIN_WEB_APPLICATION_TYPE: none
+ depends_on:
+ postgres:
+ condition: service_healthy
+ redis:
+ condition: service_healthy
+ restart: "no"
+
+ # PostgreSQL хранит постоянные данные.
+ postgres:
+ image: postgres:16.4
+ environment:
+ POSTGRES_DB: messenger
+ POSTGRES_USER: messenger
+ POSTGRES_PASSWORD: messenger
+ volumes:
+ - pgdata:/var/lib/postgresql/data
+ healthcheck:
+ test: ["CMD-SHELL", "pg_isready -U messenger -d messenger"]
+ interval: 5s
+ timeout: 3s
+ retries: 10
+ restart: unless-stopped
+ deploy:
+ resources:
+ limits:
+ cpus: '2.0'
+ memory: 1G
+
+ # Redis хранит Bearer-сессии.
+ redis:
+ image: redis:7.4.1
+ command: redis-server --appendonly yes
+ volumes:
+ - redisdata:/data
+ healthcheck:
+ test: ["CMD", "redis-cli", "ping"]
+ interval: 5s
+ timeout: 3s
+ retries: 10
+ restart: unless-stopped
+ deploy:
+ resources:
+ limits:
+ cpus: '0.5'
+ memory: 256M
+
+# Именованные тома для постоянного хранения данных.
+volumes:
+ pgdata:
+ redisdata:
diff --git a/infra/nginx/nginx.conf b/infra/nginx/nginx.conf
new file mode 100644
index 00000000..a29a8ea7
--- /dev/null
+++ b/infra/nginx/nginx.conf
@@ -0,0 +1,47 @@
+upstream api_backend {
+ # Балансировка между несколькими API-репликами.
+ server api-1:8080 max_fails=3 fail_timeout=10s;
+ server api-2:8080 max_fails=3 fail_timeout=10s;
+}
+
+server {
+ listen 8080;
+ server_name localhost;
+
+ # Таймауты для предотвращения зависаний.
+ proxy_connect_timeout 5s;
+ proxy_send_timeout 60s;
+ proxy_read_timeout 60s;
+
+ # Передача заголовков клиента в backend.
+ proxy_set_header Host $http_host;
+ proxy_set_header X-Real-IP $remote_addr;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ proxy_set_header X-Forwarded-Proto $scheme;
+
+ # Основной location для API.
+ location / {
+ proxy_pass http://api_backend;
+ proxy_set_header Host $http_host;
+ proxy_set_header X-Real-IP $remote_addr;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ proxy_set_header X-Forwarded-Proto $scheme;
+ }
+
+ # Health check endpoint для Nginx.
+ location /health/live {
+ proxy_pass http://api_backend/health/live;
+ proxy_set_header Host $http_host;
+ proxy_set_header X-Real-IP $remote_addr;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ proxy_set_header X-Forwarded-Proto $scheme;
+ }
+
+ location /health/ready {
+ proxy_pass http://api_backend/health/ready;
+ proxy_set_header Host $http_host;
+ proxy_set_header X-Real-IP $remote_addr;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ proxy_set_header X-Forwarded-Proto $scheme;
+ }
+}
diff --git a/pom.xml b/pom.xml
new file mode 100644
index 00000000..c821b3f8
--- /dev/null
+++ b/pom.xml
@@ -0,0 +1,22 @@
+
+
+ 4.0.0
+
+ org.springframework.boot
+ spring-boot-starter-parent
+ 3.3.5
+
+
+ ru.mtusi
+ messenger
+ 1.0.0
+ 21
+
+ org.springframework.bootspring-boot-starter-web
+ org.springframework.bootspring-boot-starter-jdbc
+ org.springframework.securityspring-security-crypto
+ org.postgresqlpostgresqlruntime
+ org.springframework.bootspring-boot-starter-data-redis
+
+ org.springframework.bootspring-boot-maven-plugin
+
diff --git a/scripts/check_contract.py b/scripts/check_contract.py
index dcb34dfa..0c75274b 100644
--- a/scripts/check_contract.py
+++ b/scripts/check_contract.py
@@ -8,8 +8,8 @@ import re
ROOT = Path(__file__).resolve().parents[1]
def main():
- lab = json.loads((ROOT/'lab.json').read_text())['number']
- spec = json.loads((ROOT/'contracts/openapi.json').read_text())
+ lab = json.loads((ROOT/'lab.json').read_text(encoding='utf-8'))['number']
+ spec = json.loads((ROOT/'contracts/openapi.json').read_text(encoding='utf-8'))
assert spec['openapi']=='3.1.0'
assert spec['info']['version']=='1.%d.0'%lab
operation_ids = set()
@@ -41,11 +41,11 @@ def main():
assert ('/api/v1/auth/sessions' in spec['paths']) == (lab>=2)
assert ('/api/v1/attachments/{attachment_id}' in spec['paths']) == (lab>=4)
for file in list((ROOT/'tests').glob('*.py'))+list((ROOT/'scripts').glob('*.py')):
- ast.parse(file.read_text(),filename=str(file))
+ ast.parse(file.read_text(encoding='utf-8'),filename=str(file))
for file in ROOT.rglob('*.json'):
if any(part in {'.git','.venv','node_modules','vendor','output'} for part in file.parts):
continue
- json.loads(file.read_text())
+ json.loads(file.read_text(encoding='utf-8'))
for required in ('README.md','COURSE.md','CONTRIBUTING.md','REPORT.md','contracts/README.md','tests/smoke.py','tests/README.md'):
assert (ROOT/required).is_file(), 'missing '+required
print('PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.')
diff --git a/scripts/restart.sh b/scripts/restart.sh
new file mode 100644
index 00000000..0ee7db05
--- /dev/null
+++ b/scripts/restart.sh
@@ -0,0 +1,21 @@
+#!/bin/bash
+# Скрипт перезапуска всего стенда с сохранением volumes.
+
+set -e
+
+echo "Останавливаем все контейнеры стенда..."
+docker compose down
+
+echo "Запускаем стенд заново..."
+docker compose up -d --build
+
+echo "Ожидаем готовности сервисов..."
+sleep 10
+
+echo "Проверяем статус контейнеров..."
+docker compose ps
+
+echo "Проверяем health check..."
+curl -f http://localhost:8080/health/ready || echo "API ещё не готов"
+
+echo "Стенд успешно перезапущен"
diff --git a/scripts/stop-one.sh b/scripts/stop-one.sh
new file mode 100644
index 00000000..66e169bc
--- /dev/null
+++ b/scripts/stop-one.sh
@@ -0,0 +1,18 @@
+#!/bin/bash
+# Скрипт остановки одной API-реплики для демонстрации failover.
+
+set -e
+
+# Имя контейнера для остановки (по умолчанию api-1).
+CONTAINER="${1:-mtusi2026lab3-api-1-1}"
+
+echo "Останавливаем контейнер $CONTAINER..."
+docker compose stop api-1
+
+echo "Проверяем, что контейнер действительно остановлен..."
+docker compose ps api-1
+
+echo "Контейнер $CONTAINER остановлен. Вторая реплика продолжает работу."
+echo "Проверяем доступность API через балансировщик..."
+sleep 2
+curl -f http://localhost:8080/health/ready && echo "API доступен через вторую реплику"
diff --git a/scripts/validate_openapi.py b/scripts/validate_openapi.py
index 1dfe4a98..1542dc6a 100644
--- a/scripts/validate_openapi.py
+++ b/scripts/validate_openapi.py
@@ -6,17 +6,17 @@ from openapi_spec_validator import validate
from jsonschema import Draft202012Validator
root = Path(__file__).resolve().parents[1]
-spec = json.loads((root/'contracts/openapi.json').read_text())
+spec = json.loads((root/'contracts/openapi.json').read_text(encoding='utf-8'))
validate(spec)
from referencing import Registry, Resource
# The base URI resolves local #/components references inside examples.
resource = dict(spec, **{'$schema': 'https://json-schema.org/draft/2020-12/schema'})
registry = Registry().with_resource('urn:mtusi:openapi', Resource.from_contents(resource))
-for name, example in json.loads((root/'contracts/examples.json').read_text()).items():
+for name, example in json.loads((root/'contracts/examples.json').read_text(encoding='utf-8')).items():
schema = {'$ref': 'urn:mtusi:openapi#/components/schemas/' + name}
Draft202012Validator(schema, registry=registry).validate(example)
for path in (root/'contracts').glob('*.schema.json'):
- schema = json.loads(path.read_text())
+ schema = json.loads(path.read_text(encoding='utf-8'))
Draft202012Validator.check_schema(schema)
for example in schema.get('examples',[]):
Draft202012Validator(schema).validate(example)
diff --git a/src/main/java/ru/mtusi/messenger/MessengerApplication.java b/src/main/java/ru/mtusi/messenger/MessengerApplication.java
new file mode 100644
index 00000000..f2a1c5eb
--- /dev/null
+++ b/src/main/java/ru/mtusi/messenger/MessengerApplication.java
@@ -0,0 +1,407 @@
+package ru.mtusi.messenger;
+
+import jakarta.servlet.FilterChain;
+import jakarta.servlet.ServletException;
+import jakarta.servlet.http.*;
+import org.springframework.boot.*;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.boot.autoconfigure.jackson.Jackson2ObjectMapperBuilderCustomizer;
+import org.springframework.context.annotation.DependsOn;
+import org.springframework.context.annotation.Bean;
+import org.springframework.core.io.ClassPathResource;
+import com.fasterxml.jackson.databind.JsonNode;
+import org.springframework.dao.DuplicateKeyException;
+import org.springframework.dao.DataAccessException;
+import org.springframework.data.redis.core.StringRedisTemplate;
+import org.springframework.http.*;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.jdbc.datasource.init.ResourceDatabasePopulator;
+import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
+import org.springframework.web.bind.annotation.*;
+import org.springframework.web.filter.OncePerRequestFilter;
+import org.springframework.transaction.annotation.Transactional;
+import org.springframework.http.converter.HttpMessageNotReadableException;
+import org.springframework.web.method.annotation.MethodArgumentTypeMismatchException;
+import org.slf4j.LoggerFactory;
+import com.fasterxml.jackson.databind.MapperFeature;
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.security.SecureRandom;
+import java.time.*;
+import java.util.*;
+import java.util.Base64;
+
+// Главная аннотация Spring Boot: включает запуск приложения и автоматическую настройку.
+@SpringBootApplication
+public class MessengerApplication {
+ // Стабильный идентификатор экземпляра API, генерируется при старте приложения.
+ private static final String INSTANCE_ID = UUID.randomUUID().toString();
+
+ // Метод main является точкой входа в Java-программу.
+ // Здесь Spring Boot запускает встроенный HTTP-сервер.
+ public static void main(String[] args) {
+ // Передаём главный класс и аргументы командной строки Spring Boot.
+ SpringApplication.run(MessengerApplication.class, args);
+ }
+
+ // @Bean регистрирует возвращаемый объект в контейнере Spring.
+ // BCrypt хранит пароль в виде хеша, поэтому исходный пароль не попадает в базу.
+ @Bean
+ BCryptPasswordEncoder passwordEncoder() {
+ // Возвращаем BCrypt-кодировщик, который Spring передаст контроллеру.
+ return new BCryptPasswordEncoder();
+ }
+
+ // Отключаем автоматическое превращение чисел в строки при чтении JSON.
+ @Bean
+ Jackson2ObjectMapperBuilderCustomizer strictJson() {
+ return builder -> builder.featuresToDisable(MapperFeature.ALLOW_COERCION_OF_SCALARS);
+ }
+
+ // Выполняем версионируемую миграцию до создания REST API.
+ @Bean(name="migration")
+ Object migration(javax.sql.DataSource dataSource) {
+ new ResourceDatabasePopulator(new ClassPathResource("db/migration/V1__init.sql")).execute(dataSource);
+ new ResourceDatabasePopulator(new ClassPathResource("db/migration/V2__idempotency.sql")).execute(dataSource);
+ return new Object();
+ }
+
+ // @Bean регистрирует фильтр в контейнере Spring.
+ // Фильтр добавляет общий идентификатор каждому HTTP-ответу.
+ @Bean OncePerRequestFilter requestId() {
+ return new OncePerRequestFilter() {
+ // Метод фильтра вызывается для каждого HTTP-запроса.
+ protected void doFilterInternal(HttpServletRequest r, HttpServletResponse s, FilterChain c)
+ throws ServletException, IOException {
+ // Создаём уникальный идентификатор текущего запроса.
+ String id=UUID.randomUUID().toString();
+ // Добавляем идентификатор в HTTP-ответ.
+ s.setHeader("X-Request-Id", id);
+ // Добавляем стабильный идентификатор экземпляра API.
+ s.setHeader("X-Instance-Id", INSTANCE_ID);
+ // Сохраняем тот же идентификатор для обработчика ошибок.
+ r.setAttribute("requestId", id);
+ // Передаём запрос дальше по цепочке Spring.
+ c.doFilter(r, s);
+ }
+ };
+ }
+
+ // Эти record-классы описывают JSON-модели ответов и запросов.
+ // Публичная модель пользователя без пароля.
+ record User(UUID id, String username, String display_name, Instant created_at) {}
+ // Модель чата со списком участников.
+ record Chat(UUID id, String title, List member_ids, Instant created_at) {}
+ // Модель сообщения с автором и временем создания.
+ record Message(UUID id, UUID chat_id, UUID sender_id, String text, Instant created_at) {}
+ // Универсальная модель страницы списка.
+ record Page(List items, String next_cursor) {}
+ // Ответ успешного входа с Bearer-токеном.
+ record Session(String token, String token_type, Instant expires_at, User user) {}
+ // Тело запроса регистрации.
+ record UserIn(JsonNode username, JsonNode display_name, JsonNode password) {}
+ // Тело запроса создания чата.
+ record ChatIn(JsonNode title, List member_ids) {}
+ // Тело запроса отправки сообщения.
+ record MessageIn(JsonNode text) {}
+ // Поля внутренней ошибки API.
+ record Error(String code, String message, String request_id) {}
+ // Обёртка, требуемая форматом JSON ошибки.
+ record ErrorBody(Error error) {}
+
+ // Исключение хранит HTTP-статус и безопасный код ошибки.
+ static class ApiException extends RuntimeException {
+ // HTTP-статус, который будет отправлен клиенту.
+ final HttpStatus status;
+ // Короткий код ошибки для программы-клиента.
+ final String code;
+ ApiException(HttpStatus s, String c, String m) {
+ // Сохраняем текст сообщения в стандартном RuntimeException.
+ super(m);
+ status=s;
+ code=c;
+ }
+ }
+
+ // @RestController объединяет @Controller и @ResponseBody.
+ // Методы этого класса принимают HTTP-запросы и возвращают JSON.
+ @DependsOn("migration")
+ @RestController
+ static class Api {
+ // JdbcTemplate работает с PostgreSQL, RedisTemplate — с Redis-сессиями.
+ // JdbcTemplate отправляет SQL-запросы в PostgreSQL.
+ final JdbcTemplate db;
+ // StringRedisTemplate работает со строковыми ключами Redis.
+ final StringRedisTemplate redis;
+ // BCryptPasswordEncoder проверяет и хеширует пароли.
+ final BCryptPasswordEncoder encoder;
+ // Генератор создаёт 32 случайных байта для каждой сессии.
+ final SecureRandom random = new SecureRandom();
+ // TTL можно уменьшить через переменную окружения для проверки expiry.
+ final long ttl = Long.parseLong(System.getenv().getOrDefault("SESSION_TTL_SECONDS", "3600"));
+ Api(JdbcTemplate d, StringRedisTemplate r, BCryptPasswordEncoder e) {
+ // Сохраняем зависимости, созданные Spring Boot.
+ db=d;
+ redis=r;
+ encoder=e;
+ }
+ // Метод проверяет доступность PostgreSQL тестовым запросом.
+ void dbOk() {
+ try {
+ // Простой запрос проверяет соединение с PostgreSQL.
+ db.queryForObject("select 1", Integer.class);
+ } catch (Exception e) {
+ // Внутреннюю ошибку базы не показываем клиенту.
+ throw new ApiException(HttpStatus.SERVICE_UNAVAILABLE,"unavailable","database is unavailable");
+ }
+ }
+ // Метод проверяет Bearer-токен и возвращает UUID пользователя.
+ UUID auth(HttpServletRequest req) {
+ // Читаем заголовок авторизации из HTTP-запроса.
+ String h=req.getHeader("Authorization");
+ // Защищённые методы принимают только Bearer-схему.
+ if (h==null || !h.startsWith("Bearer ")) throw unauth();
+ // В Redis хранится связь токена с UUID пользователя.
+ try { String v=redis.opsForValue().get("session:"+h.substring(7)); if(v==null) throw unauth(); return UUID.fromString(v); }
+ catch (ApiException e) { throw e; } catch (Exception e) { throw new ApiException(HttpStatus.SERVICE_UNAVAILABLE,"unavailable","session store is unavailable"); }
+ }
+ ApiException unauth() { return new ApiException(HttpStatus.UNAUTHORIZED,"unauthorized","valid Bearer session required"); }
+ // Загружаем пользователя по UUID из PostgreSQL.
+ // Метод ищет пользователя в PostgreSQL по его UUID.
+ User user(UUID id) {
+ return db.query("select id,username,display_name,created_at from users where id=?", rs -> rs.next()
+ ? new User(rs.getObject(1,UUID.class),rs.getString(2),rs.getString(3),rs.getTimestamp(4).toInstant()) : null, id);
+ }
+ // Метод проверяет, состоит ли пользователь в выбранном чате.
+ boolean member(UUID chat, UUID user) {
+ // Пользователь должен состоять в чате, иначе ресурс для него скрыт.
+ return Boolean.TRUE.equals(db.queryForObject("select exists(select 1 from chat_members where chat_id=? and user_id=?)",Boolean.class,chat,user));
+ }
+ // Загружает один чат и его участников напрямую по идентификатору.
+ Chat chatById(UUID id) {
+ return db.query("select id,title,created_at from chats where id=?",rs -> rs.next()
+ ? new Chat(rs.getObject(1,UUID.class),rs.getString(2),
+ db.query("select user_id from chat_members where chat_id=?",(z,k)->z.getObject(1,UUID.class),id),
+ rs.getTimestamp(3).toInstant()) : null,id);
+ }
+ // Считает символы как Unicode code points, а не как UTF-16 char.
+ int codePointLength(String value) {
+ return value.codePointCount(0,value.length());
+ }
+ // Возвращает значение только если JSON-поле действительно является строкой.
+ String string(JsonNode value) { return value!=null && value.isTextual()?value.textValue():null; }
+ // PostgreSQL не хранит нулевой байт, поэтому заменяем его безопасным символом.
+ String databaseText(String value) { return value==null?null:value.replace('\0','\uFFFD'); }
+ // Проверяет обязательную непустую строку и её максимальную длину.
+ boolean text(String value, int max) { return value!=null && !value.isBlank() && codePointLength(value)<=max; }
+ // Предварительный SHA-256 сохраняет весь пароль перед ограниченным BCrypt.
+ String passwordValue(String value) {
+ try { return Base64.getEncoder().encodeToString(MessageDigest.getInstance("SHA-256").digest(value.getBytes(StandardCharsets.UTF_8))); }
+ catch (Exception e) { throw new IllegalStateException("password hashing is unavailable",e); }
+ }
+
+ // Готовность проверяет не только Java-процесс, но и его зависимости.
+ // @GetMapping связывает GET-запрос с Java-методом.
+ @GetMapping({"/health/live","/health/ready"})
+ // Для ready дополнительно проверяем PostgreSQL и Redis.
+ // Метод возвращает JSON со статусом приложения.
+ Map health(HttpServletRequest r) { if (r.getRequestURI().endsWith("ready")) { dbOk(); try { redis.hasKey("health"); } catch(Exception e) { throw new ApiException(HttpStatus.SERVICE_UNAVAILABLE,"unavailable","session store is unavailable"); } } return Map.of("status","ok"); }
+ // @PostMapping связывает POST-запрос с методом регистрации.
+ @PostMapping("/api/v1/users")
+ // @RequestBody преобразует JSON-тело запроса в объект UserIn.
+ ResponseEntity register(@RequestBody UserIn in) {
+ String username=in==null?null:string(in.username());
+ String displayName=in==null?null:string(in.display_name());
+ String password=in==null?null:string(in.password());
+ // До запроса в базу проверяем формат обязательных полей.
+ if(username==null || !username.matches("[a-z0-9_]{3,32}") || !text(displayName,100) || password==null || password.isBlank() || codePointLength(password)<12 || codePointLength(password)>128) bad();
+ displayName=databaseText(displayName);
+ // Создаём UUID пользователя и фиксируем время регистрации.
+ UUID id=UUID.randomUUID(); Instant now=Instant.now().truncatedTo(java.time.temporal.ChronoUnit.MICROS);
+ // Значения передаются параметрами, а не склеиваются со строкой SQL.
+ try { db.update("insert into users values(?,?,?,?,?)",id,username,displayName,encoder.encode(passwordValue(password)),java.sql.Timestamp.from(now)); }
+ // Уникальное ограничение username превращаем в понятный ответ 409.
+ catch(DuplicateKeyException e) { throw new ApiException(HttpStatus.CONFLICT,"conflict","username is already used"); }
+ // Возвращаем созданного пользователя без пароля.
+ return ResponseEntity.status(201).body(new User(id,username,displayName,now));
+ }
+ // POST-метод входа проверяет Basic-логин и создаёт Bearer-сессию.
+ @PostMapping("/api/v1/auth/sessions")
+ // HttpServletRequest позволяет прочитать заголовок Authorization.
+ ResponseEntity login(HttpServletRequest req) {
+ // Читаем Basic-заголовок, который используется только при входе.
+ String h=req.getHeader("Authorization");
+ if(h==null || !h.startsWith("Basic ")) { HttpHeaders x=new HttpHeaders(); x.set("WWW-Authenticate","Basic realm=\"messenger\", charset=\"UTF-8\""); throw new ApiException(HttpStatus.UNAUTHORIZED,"unauthorized","Basic authentication required"); }
+ // Basic используется только для входа, после него клиент получает Bearer-токен.
+ String[] p; try { p=new String(Base64.getDecoder().decode(h.substring(6)),StandardCharsets.UTF_8).split(":",2); } catch(Exception e) { p=new String[0]; }
+ // Получаем BCrypt-хеш пользователя из PostgreSQL.
+ String hash=p.length==2 ? db.query("select password_hash from users where username=?",rs -> rs.next()?rs.getString(1):null,p[0]) : null;
+ // Сравниваем введённый пароль с сохранённым хешем.
+ if(p.length!=2 || hash==null || codePointLength(p[1])<12 || codePointLength(p[1])>128 || !encoder.matches(passwordValue(p[1]),hash)) { HttpHeaders x=new HttpHeaders(); x.set("WWW-Authenticate","Basic realm=\"messenger\", charset=\"UTF-8\""); throw new ApiException(HttpStatus.UNAUTHORIZED,"unauthorized","invalid credentials"); }
+ // После успешной проверки загружаем полную модель пользователя.
+ User u=user(db.queryForObject("select id from users where username=?",UUID.class,p[0]));
+ // Генерируем непрозрачный случайный токен сессии.
+ byte[] secret=new byte[32]; random.nextBytes(secret);
+ String token=Base64.getUrlEncoder().withoutPadding().encodeToString(secret);
+ // Вычисляем момент, когда сессия перестанет действовать.
+ Instant exp=Instant.now().plusSeconds(ttl);
+ // Сессия автоматически удалится из Redis после окончания TTL.
+ try { redis.opsForValue().set("session:"+token,u.id().toString(),Duration.ofSeconds(ttl)); } catch(Exception e) { throw new ApiException(HttpStatus.SERVICE_UNAVAILABLE,"unavailable","session store is unavailable"); }
+ return ResponseEntity.status(201).body(new Session(token,"Bearer",exp,u));
+ }
+ // @DeleteMapping связывает DELETE-запрос с удалением сессии.
+ // Logout сразу удаляет текущий токен из Redis.
+ @DeleteMapping("/api/v1/auth/sessions/current") ResponseEntity logout(HttpServletRequest r) { auth(r); redis.delete("session:"+r.getHeader("Authorization").substring(7)); return ResponseEntity.noContent().build(); }
+ // GET-запрос возвращает данные текущего авторизованного пользователя.
+ @GetMapping("/api/v1/users/me") User me(HttpServletRequest r) { return user(auth(r)); }
+ // @Transactional объединяет несколько SQL-команд в одну транзакцию.
+ // Если одна команда завершится ошибкой, изменения откатываются.
+ // Вставка чата и всех его участников выполняется как одна транзакция.
+ @Transactional
+ // POST-запрос создаёт новый чат.
+ @PostMapping("/api/v1/chats") ResponseEntity createChat(@RequestBody ChatIn in,HttpServletRequest r) {
+ // Владелец чата определяется по Bearer-сессии.
+ String title=in==null?null:string(in.title());
+ UUID owner=auth(r); if(!text(title,100)||in.member_ids()==null||in.member_ids().isEmpty()||in.member_ids().size()>100||new HashSet<>(in.member_ids()).size()!=in.member_ids().size()||!in.member_ids().contains(owner)) bad();
+ // Проверяем существование каждого участника.
+ for(UUID id:in.member_ids()) if(user(id)==null) bad();
+ // ID и время создаются сервером.
+ UUID id=UUID.randomUUID(); Instant now=Instant.now();
+ // Записываем чат и участников в одной транзакции.
+ title=databaseText(title);
+ db.update("insert into chats values(?,?,?)",id,title,java.sql.Timestamp.from(now)); for(UUID m:in.member_ids()) db.update("insert into chat_members values(?,?)",id,m);
+ // Возвращаем созданную модель чата.
+ return ResponseEntity.status(201).body(new Chat(id,title,in.member_ids(),now));
+ }
+ // GET-запрос получает список чатов текущего пользователя.
+ @GetMapping("/api/v1/chats")
+ Page chats(HttpServletRequest r) {
+ // Определяем пользователя, для которого строится список.
+ UUID u=auth(r);
+ String cursor=r.getParameter("cursor");
+ int limit=parseLimit(r.getParameter("limit"));
+ // Запрашиваем только чаты, где пользователь является участником.
+ String sql="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=? ";
+ List