ЛР3: балансировка, отказоустойчивость и идемпотентность

This commit is contained in:
2026-10-23 18:54:18 +03:00
parent 3f7c306f4f
commit 57b4e8b5ec
20 changed files with 659 additions and 39 deletions
+4 -1
View File
@@ -4,7 +4,7 @@ CA_FILE ?=
ACTION_SCRIPT ?=
TLS_ARGS = $(if $(CA_FILE),--ca-file "$(CA_FILE)",)
.PHONY: help check validate test load test-persistence test-failover
.PHONY: help check validate test test-idempotency load test-persistence test-failover
help:
@echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes"
@@ -18,6 +18,9 @@ validate:
test:
$(PYTHON) tests/smoke.py --base-url "$(BASE_URL)" $(TLS_ARGS)
test-idempotency:
BASE_URL="$(BASE_URL)" CA_FILE="$(CA_FILE)" $(PYTHON) -m pytest -q tests/test_idempotency.py
load:
$(PYTHON) tests/load.py --base-url "$(BASE_URL)" $(TLS_ARGS)
+126 -15
View File
@@ -1,37 +1,148 @@
# Отчёт — лабораторная 3
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
- Автор, группа: Сергей Возжин, БПИ2301.
- Целевая оценка: 4; трек 5 не выбран.
- Commit/PR: коммит не создавался по условию выполнения; указать после публикации.
- Использованные источники: материалы и контракт репозитория, документация Docker Compose и HAProxy.
- Библиотеки: FastAPI, Uvicorn, SQLAlchemy, asyncpg, Alembic, redis-py, Argon2, pytest.
- Помощь ИИ: OpenAI Codex использовался для плана, реализации lab3, тестов, сценариев отказа и оформления отчёта; результат проверен исполняемыми тестами.
## Запуск из чистого clone
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
Требуются Docker Engine с Compose v2, Python 3.9+ для публичных тестов и свободный host-порт 8080. Проверенный стенд: Docker 28.0.4, Compose 2.34.0, API на Python 3.13.15. Образы: `python:3.13.15-slim`, `haproxy:3.2.26-alpine`, `postgres:17.4-alpine`, `redis:7.4.2-alpine`.
Создать локальную конфигурацию, не добавляя её в Git:
```sh
cp .env.example .env
```
Перед запуском заменить учебный пароль PostgreSQL в `.env` и ту же часть пароля в `DATABASE_URL`. Сам `.env` игнорируется Git. Все данные тестов должны быть синтетическими.
Проверить конфигурацию, собрать образы, однократно применить миграции и дождаться готовности:
```sh
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait
docker compose --env-file .env ps
```
`migrate` выполняет `alembic upgrade head` один раз. Две реплики `api` стартуют только после успешной миграции и готовности Redis; HAProxy стартует после готовности API. Единственная публичная точка входа — `http://localhost:8080`.
Полный набор проверок:
```sh
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
make check
make validate PYTHON=.venv/bin/python
make test
make test-idempotency PYTHON=.venv/bin/python
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
```
После failover восстановить вторую реплику и дождаться готовности:
```sh
docker compose --env-file .env up -d --wait --wait-timeout 60 api lb
```
Для проверки другой реплики повторить `make test-failover` после восстановления первой. Для поочерёдной замены под нагрузкой запустить `tests/load.py`, параллельно выполнить `scripts/rolling-update.sh` и сохранить агрегаты.
Безопасная остановка с сохранением named volumes:
```sh
docker compose --env-file .env down
```
Намеренное необратимое удаление всех учебных данных выполняется только оператором:
```sh
docker compose --env-file .env down -v
```
## Архитектура и решения
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
```text
HTTP client
|
v
HAProxy :8080
|
+-- round-robin --> API replica 1 --+
| +--> PostgreSQL
+-- round-robin --> API replica 2 --+--> Redis sessions
```
PostgreSQL — источник истины для пользователей, чатов, участников и сообщений. Redis — общее хранилище действующих сессий с AOF. Локального значимого состояния у API нет; sticky sessions не используются.
Из lab2 перенесены REST API, PostgreSQL, Redis-сессии, password KDF и миграции. В lab3 добавлены HAProxy, две API-реплики, `X-Instance-Id`, обязательный `Idempotency-Key`, конкурентная проверка и сценарии отказа/замены.
Каждый API-процесс один раз берёт `X-Instance-Id` из hostname контейнера. Middleware добавляет его во все созданные API ответы. Значение меняется при замене контейнера.
Идемпотентность сообщения хранится в PostgreSQL. Уникальность `(sender_id, chat_id, idempotency_key)` соответствует области пользователь + метод отправки сообщения + путь чата + ключ. `INSERT ... ON CONFLICT DO NOTHING` и чтение существующей строки выполняются в одной транзакции. Одинаковое тело возвращает исходный `201 Message`, другое тело — `409`. Ограничение хранится дольше обязательных 24 часов.
Миграция выполняется отдельно. Поле `idempotency_key` nullable: старая версия может продолжать писать `NULL`, новая читает старые записи. Создание unique constraint может блокировать большую production-таблицу; это ограничение учебной миграции описано и не маскируется.
HAProxy использует round-robin и Docker DNS `127.0.0.11`. `/health/ready` проверяется каждую секунду с `fall 2`, `rise 2`, `timeout check 2s`. При быстром отказе типичное исключение занимает 2–3 секунды; консервативная верхняя оценка с двумя полными timeout — около 6 секунд. Наблюдавшееся восстановление записи — 2,560–3,248 секунды, что меньше требуемых 10 секунд.
Таймауты HAProxy: connect/check 2 секунды, client/server 30 секунд. Uvicorn прекращает принимать новые соединения по SIGTERM, имеет graceful shutdown 5 секунд, Compose даёт API `stop_grace_period` 10 секунд.
Лимиты контейнеров:
| Сервис | CPU | RAM |
| --- | ---: | ---: |
| API, каждая реплика | 0,5 | 256 MiB |
| HAProxy | 0,25 | 128 MiB |
| PostgreSQL | 1,0 | 512 MiB |
| Redis | 0,25 | 128 MiB |
| migrate | 0,5 | 256 MiB |
Наружу опубликован только порт HAProxy. PostgreSQL, Redis и API доступны только в Compose-сети. `DATABASE_URL` получают только API и migrate; настройки PostgreSQL — только сам PostgreSQL. `container_name` отсутствует.
Переменные `.env.example`: `APP_PORT` задаёт host-порт HAProxy; `POSTGRES_*` настраивают PostgreSQL; `DATABASE_URL` используют API/migrate; `REDIS_URL` используют API/migrate; `SESSION_TTL_SECONDS` задаёт TTL серверной сессии; `LOG_LEVEL` задаёт логирование API. `APP_HOST` и `APP_ENV` оставлены как описательные учебные настройки и приложением не читаются.
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| Критерий README | Команда/сценарий | Наблюдаемый результат | Доказательство |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
| Публичный smoke | `make test` | `PASS: lab3 public API scenario` | `evidence/results.md` |
| Две реплики и одна точка входа | 20 запросов через `localhost:8080`, `docker compose ps` | два `X-Instance-Id`; host-порт есть только у HAProxy | `evidence/results.md` |
| Общая сессия | smoke/idempotency через HAProxy | одна Bearer-сессия работает на обеих репликах | `evidence/results.md` |
| Общая идемпотентность | `make test-idempotency PYTHON=.venv/bin/python` | 20 конкурентных запросов, две реплики, одно сообщение; `5 passed` | `evidence/results.md` |
| Persistence | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | данные и прежний token доступны после рестарта API/PostgreSQL/Redis | `evidence/results.md` |
| Отказ первой реплики | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | восстановление 3,248 с; 111 успешных записей за 15 с (≈7,40 RPS), 1 переходная ошибка | `evidence/results.md` |
| Отказ второй реплики | восстановление первой и повтор failover | восстановление 2,560 с; 110 успешных записей за 15 с (≈7,33 RPS), 1 переходная ошибка | `evidence/results.md` |
| Health/timeouts/SIGTERM | HAProxy checks и остановка выбранного контейнера | backend исключён, другая реплика продолжила чтение/запись | `evidence/results.md` |
| CPU/RAM и закрытые порты | `docker compose ps`, `docker stats --no-stream` | лимиты применены; наружу опубликован только 8080 HAProxy | `evidence/results.md` |
| Поочерёдная замена | `scripts/rolling-update.sh` во время `tests/load.py` | обе реплики получили новые container ID, 10 512 успешных запросов, 0 ошибок | `evidence/rolling-update.md`, `evidence/rolling-update-load.json` |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
Трек оценки 5 не заявлен.
## Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
Проверяемое ожидание: остановка любой одной API-реплики не приводит к потере подтверждённых сообщений или сессии, а новые чтения/записи возобновляются не позднее 10 секунд.
Аппаратная конфигурация локального стенда: Apple M4 Pro, 12 CPU cores, 24 GB RAM; Docker Desktop. Основной профиль — closed-loop POST сообщений, 30 секунд, concurrency 4, без автоматических retry и отдельного временного прогрева. Bootstrap выполняется до измеряемого интервала. После профиля: 39 пользователей, 13 чатов, 18 448 сообщений, PostgreSQL 14 MB.
Основной прогон: 9807 успешных запросов, 0 ошибок, 326,771 successful RPS, p50/p95/p99 6,436/52,344/63,559 мс. CPU/RAM по двум срезам приведены в `evidence/results.md`; обе API-реплики использовали около 50–52% CPU и 66–76 MiB RAM каждая.
Числа двух failover-запусков взяты из JSON summary, который печатает `tests/resilience.py`: `successful_writes`, `failed_attempts` и `first_recovery_seconds`. Приблизительный RPS рассчитан как число успешных записей, делённое на 15 секунд нагрузки. Результат persistence взят из успешного завершения того же теста в режиме `persistence`. Числа поочерёдной замены взяты из `evidence/rolling-update-load.json`, записанного `tests/load.py` во время работы `scripts/rolling-update.sh`.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
| Restart API + PostgreSQL + Redis | данные и token сохраняются | persistence PASS | время отдельно не замерялось; потерь нет |
| Остановка первой API-реплики | HAProxy оставляет вторую | 111 записей за 15 с (≈7,40 RPS), 1 краткая ошибка | 3,248 с; потерь и дублей нет |
| Остановка второй после восстановления первой | симметричный failover | 110 записей за 15 с (≈7,33 RPS), 1 краткая ошибка | 2,560 с; потерь и дублей нет |
| Поочерёдная замена двух API | трафик продолжается | 10 512 успешных запросов, 0 ошибок | явного перерыва не наблюдалось |
`tests/load.py` — простой closed-loop генератор, ограниченный клиентом и подверженный coordinated omission. Перцентили учитывают только успешные запросы. Эти цифры описывают конкретный учебный стенд и не объявляются максимальной производительностью.
## Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
Стенд выдерживает остановку одного API-процесса при работающих HAProxy, второй API-реплике, PostgreSQL, Redis и Docker-host. Он не выдерживает потерю единственного HAProxy, PostgreSQL, Redis или всего host: это осознанные SPOF лабораторной работы.
HAProxy и хранилища не реплицированы. Redis AOF снижает риск потери сессий при штатном перезапуске, но не является HA. Docker Compose обеспечивает локальную воспроизводимость, а не перенос контейнеров между узлами. HTTP используется только локально с синтетическими данными; TLS здесь не заявлен. Универсальная идемпотентность остальных POST, WebSocket, UI, мониторинг и требования оценки 5 намеренно не реализованы.
Следующие возможные улучшения, не входящие в оценку 4: несколько Docker-узлов, HA для LB/БД/Redis, online-создание индекса на большой таблице и более строгий open-loop нагрузочный генератор.
@@ -0,0 +1,35 @@
"""Add shared message idempotency for lab 3.
Revision ID: 20261023_0002
Revises: 20261019_0001
Create Date: 2026-10-23
"""
from alembic import op
import sqlalchemy as sa
revision = '20261023_0002'
down_revision = '20261019_0001'
branch_labels = None
depends_on = None
def upgrade() -> None:
op.add_column(
'messages',
sa.Column('idempotency_key', sa.String(length=128), nullable=True),
)
op.create_unique_constraint(
'messages_sender_chat_idempotency_key',
'messages',
['sender_id', 'chat_id', 'idempotency_key'],
)
def downgrade() -> None:
op.drop_constraint(
'messages_sender_chat_idempotency_key',
'messages',
type_='unique',
)
op.drop_column('messages', 'idempotency_key')
+6 -1
View File
@@ -1,4 +1,6 @@
import logging
import os
import socket
from uuid import uuid4
from starlette.datastructures import MutableHeaders
@@ -11,6 +13,7 @@ logger = logging.getLogger('app')
class RequestContext:
def __init__(self, app) -> None:
self.app = app
self.instance_id = os.getenv('INSTANCE_ID') or socket.gethostname()
async def __call__(self, scope, receive, send) -> None:
if scope['type'] != 'http':
@@ -25,7 +28,9 @@ class RequestContext:
nonlocal started
if message['type'] == 'http.response.start':
started = True
MutableHeaders(scope=message)['X-Request-Id'] = request_id
headers = MutableHeaders(scope=message)
headers['X-Request-Id'] = request_id
headers['X-Instance-Id'] = self.instance_id
await send(message)
try:
+12 -3
View File
@@ -1,7 +1,7 @@
from typing import Optional
from typing import Annotated, Optional
from uuid import UUID
from fastapi import APIRouter, Depends, Query
from fastapi import APIRouter, Depends, Header, Query
from ...domain.models import User
from ...services.messages import MessageService
@@ -23,10 +23,19 @@ router = APIRouter(prefix='/api/v1/chats/{chat_id}/messages', tags=['messages'])
async def send(
chat_id: UUID,
body: CreateMessage,
idempotency_key: Annotated[
str,
Header(
alias='Idempotency-Key',
min_length=1,
max_length=128,
pattern=r'^[A-Za-z0-9._:-]+$',
),
],
actor: User = Depends(current_user),
messages: MessageService = Depends(message_service),
) -> MessageOut:
return MessageOut.from_domain(await messages.send(actor, chat_id, body.text))
return MessageOut.from_domain(await messages.send(actor, chat_id, body.text, idempotency_key))
@router.get('', response_model=MessagePageOut)
+2 -2
View File
@@ -70,8 +70,8 @@ def create_app() -> FastAPI:
logger.info('shutdown complete')
api = FastAPI(
title='MTUSI Messenger. LR 2',
version='1.2.0',
title='MTUSI Messenger. LR 3',
version='1.3.0',
description=DESCRIPTION,
lifespan=lifespan,
)
+11 -2
View File
@@ -3,7 +3,7 @@ from __future__ import annotations
from datetime import datetime
from uuid import UUID
from sqlalchemy import DateTime, ForeignKey, Index, String
from sqlalchemy import DateTime, ForeignKey, Index, String, UniqueConstraint
from sqlalchemy.orm import Mapped, mapped_column
from sqlalchemy.types import Uuid
@@ -12,10 +12,19 @@ from ..db.postgres import Base
class MessageRow(Base):
__tablename__ = 'messages'
__table_args__ = (Index('messages_history_idx', 'chat_id', 'created_at', 'id'),)
__table_args__ = (
Index('messages_history_idx', 'chat_id', 'created_at', 'id'),
UniqueConstraint(
'sender_id',
'chat_id',
'idempotency_key',
name='messages_sender_chat_idempotency_key',
),
)
id: Mapped[UUID] = mapped_column(Uuid, primary_key=True)
chat_id: Mapped[UUID] = mapped_column(ForeignKey('chats.id', ondelete='CASCADE'), nullable=False)
sender_id: Mapped[UUID] = mapped_column(ForeignKey('users.id'), nullable=False)
text: Mapped[str] = mapped_column(String(4000), nullable=False)
created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
idempotency_key: Mapped[str | None] = mapped_column(String(128), nullable=True)
+43 -9
View File
@@ -4,8 +4,10 @@ from datetime import datetime
from uuid import UUID
from sqlalchemy import select, tuple_
from sqlalchemy.dialects.postgresql import insert
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from ..domain.errors import Conflict
from ..domain.models import Keyset, Message
from ..models.chat import ChatMemberRow, ChatRow
from ..models.message import MessageRow
@@ -34,22 +36,54 @@ class MessageRepository:
)
async def create_for_member(
self, message_id: UUID, chat_id: UUID, sender_id: UUID, text: str, created_at: datetime
self,
message_id: UUID,
chat_id: UUID,
sender_id: UUID,
text: str,
created_at: datetime,
idempotency_key: str,
) -> Message | None:
async with self._sessions() as session:
async with session.begin():
accessible_chat_id = await self._accessible_chat_id(session, chat_id, sender_id)
if accessible_chat_id is None:
return None
row = MessageRow(
id=message_id,
chat_id=accessible_chat_id,
sender_id=sender_id,
text=text,
created_at=created_at,
statement = (
insert(MessageRow)
.values(
id=message_id,
chat_id=accessible_chat_id,
sender_id=sender_id,
text=text,
created_at=created_at,
idempotency_key=idempotency_key,
)
.on_conflict_do_nothing(
index_elements=[
MessageRow.sender_id,
MessageRow.chat_id,
MessageRow.idempotency_key,
]
)
.returning(MessageRow.id)
)
session.add(row)
await session.flush()
created_id = await session.scalar(statement)
if created_id is not None:
row = await session.get(MessageRow, created_id)
else:
row = await session.scalar(
select(MessageRow).where(
MessageRow.sender_id == sender_id,
MessageRow.chat_id == accessible_chat_id,
MessageRow.idempotency_key == idempotency_key,
)
)
if row is None:
raise RuntimeError('результат идемпотентной операции не найден')
if row.text != text:
raise Conflict('Idempotency-Key уже использован с другим сообщением')
return self._to_domain(row)
async def page_for_member(
+2 -1
View File
@@ -13,13 +13,14 @@ class MessageService:
def __init__(self, repository: MessageRepository) -> None:
self._repository = repository
async def send(self, actor: User, chat_id: UUID, text: str) -> Message:
async def send(self, actor: User, chat_id: UUID, text: str, idempotency_key: str) -> Message:
message = await self._repository.create_for_member(
message_id=uuid4(),
chat_id=chat_id,
sender_id=actor.id,
text=text,
created_at=datetime.now(timezone.utc),
idempotency_key=idempotency_key,
)
if message is None:
raise NotFound('чат не найден')
+34 -5
View File
@@ -1,6 +1,8 @@
services:
postgres:
image: postgres:17.4-alpine
cpus: "1.0"
mem_limit: 512m
environment:
POSTGRES_USER: ${POSTGRES_USER}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
@@ -15,6 +17,8 @@ services:
redis:
image: redis:7.4.2-alpine
cpus: "0.25"
mem_limit: 128m
command: ["redis-server", "--appendonly", "yes", "--appendfsync", "always"]
volumes:
- redis_data:/data
@@ -26,6 +30,8 @@ services:
migrate:
build: .
cpus: "0.5"
mem_limit: 256m
command: ["alembic", "upgrade", "head"]
environment:
DATABASE_URL: ${DATABASE_URL}
@@ -38,13 +44,17 @@ services:
api:
build: .
cpus: "0.5"
mem_limit: 256m
environment:
DATABASE_URL: ${DATABASE_URL}
REDIS_URL: ${REDIS_URL}
SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS}
LOG_LEVEL: ${LOG_LEVEL:-info}
ports:
- "${APP_PORT:-8080}:8080"
expose:
- "8080"
deploy:
replicas: 2
depends_on:
migrate:
condition: service_completed_successfully
@@ -52,9 +62,28 @@ services:
condition: service_healthy
healthcheck:
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/ready', timeout=3).read()"]
interval: 10s
timeout: 3s
retries: 10
interval: 2s
timeout: 2s
retries: 5
stop_grace_period: 10s
lb:
image: haproxy:3.2.26-alpine
cpus: "0.25"
mem_limit: 128m
ports:
- "${APP_PORT:-8080}:8080"
volumes:
- ./infra/haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro
depends_on:
api:
condition: service_healthy
healthcheck:
test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://127.0.0.1:8080/health/live"]
interval: 2s
timeout: 2s
retries: 5
stop_grace_period: 5s
volumes:
postgres_data:
+7
View File
@@ -3,3 +3,10 @@
Храните небольшие обезличенные результаты: команды и stdout проверок, JSON/CSV агрегатов нагрузки, EXPLAIN, dashboard JSON, текст разбора отказа. Укажите дату, commit, аппаратные лимиты и профиль нагрузки.
Не добавляйте .env, session tokens, cookies, приватные ключи, credentials, реальные сообщения, raw dumps и signed URLs. Для скриншотов скрывайте секреты. Большие логи/бинарные traces сохраняйте отдельно по правилам преподавателя; одного скриншота без методики недостаточно.
Собранные результаты lab3:
- `results.md` — контракт, идемпотентность, persistence, failover, нагрузка и ресурсы;
- `load.json` — агрегаты отдельного 30-секундного нагрузочного прогона;
- `rolling-update.md` — методика и результат поочерёдной замены;
- `rolling-update-load.json` — агрегаты нагрузки во время замены.
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 30.0,
"elapsed_seconds": 30.012,
"concurrency": 4,
"successful_requests": 9807,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 326.771,
"successful_latency_ms": {
"p50": 6.436,
"p95": 52.344,
"p99": 63.559
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+87
View File
@@ -0,0 +1,87 @@
# Результаты обязательных проверок lab3
Дата: 2026-10-23.
## Стенд
- Host: MacBook Pro, Apple M4 Pro, 12 CPU cores, 24 GB RAM.
- Docker Engine: 28.0.4.
- Docker Compose: 2.34.0.
- API runtime: Python 3.13.15.
- HAProxy: 3.2.26, образ `haproxy:3.2.26-alpine`.
- PostgreSQL: 17.4, образ `postgres:17.4-alpine`.
- Redis: 7.4.2, образ `redis:7.4.2-alpine`.
Лимиты: API — 0,5 CPU и 256 MiB на реплику; HAProxy — 0,25 CPU и 128 MiB; PostgreSQL — 1 CPU и 512 MiB; Redis — 0,25 CPU и 128 MiB; migrate — 0,5 CPU и 256 MiB.
## Контракт и идемпотентность
До изменений lab3 базовый стенд lab2 собирался, а `make check` и OpenAPI validation проходили. Первый lab3 smoke завершался на `FAIL: missing X-Instance-Id`; в коде также отсутствовали обязательный `Idempotency-Key`, общая идемпотентность, HAProxy и вторая API-реплика.
```sh
make test
make test-idempotency PYTHON=.venv/bin/python
```
Наблюдение:
```text
PASS: lab3 public API scenario
5 passed
```
Конкурентный тест отправляет 20 запросов с одним `Idempotency-Key` через HAProxy. Ответы получены минимум от двух `X-Instance-Id`; все содержали один ID, и в истории осталось одно сообщение.
Отдельная проверка воспроизводимости выполнена новым Compose-проектом `mtusi2026lab3-clean` с пустыми PostgreSQL/Redis volumes и host-портом 18080. Сборка, миграции, readiness двух реплик, публичный smoke и пять pytest-тестов прошли; после проверки временные контейнеры и volumes удалены.
## Persistence
```sh
make test-persistence ACTION_SCRIPT=scripts/restart.sh
```
Наблюдение: после перезапуска API, PostgreSQL и Redis с сохранением volumes подтверждённые данные и прежний session token остались доступны.
## Последовательный failover реплик
```sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
```
| Реплика | Успешные записи за 15 с | Successful write RPS (≈) | Ошибки перехода | Первая успешная запись после воздействия |
| --- | ---: | ---: | ---: | ---: |
| Первая | 111 | 7,40 | 1 | 3,248 с |
| Вторая, после восстановления первой | 110 | 7,33 | 1 | 2,560 с |
Оба запуска наблюдали две реплики до воздействия. RPS рассчитан как число успешных записей, делённое на 15 секунд нагрузки. Остановленная реплика не обслуживала последние ответы; подтверждённые сообщения сохранились, неопределённый POST не создал дубль.
## Нагрузка
```sh
python3 tests/load.py \
--base-url http://localhost:8080 \
--duration 30 \
--concurrency 4 \
--output evidence/load.json
```
- Длительность: 30,012 с.
- Concurrency: 4, closed-loop.
- Успешные запросы: 9807.
- Ошибки: 0; error ratio 0,0.
- Successful RPS: 326,771.
- p50/p95/p99 успешных запросов: 6,436 / 52,344 / 63,559 мс.
- Прогрев: отдельного временного прогрева нет; bootstrap выполнен до измеряемого интервала, стенд уже работал.
- Набор данных после теста: 39 пользователей, 13 чатов, 18 448 сообщений, PostgreSQL 14 MB.
Два среза `docker stats` во время этого прогона:
| Контейнер | CPU 1 / CPU 2 | RAM 1 / RAM 2 | Лимит RAM |
| --- | --- | --- | ---: |
| HAProxy | 12,98% / 14,26% | 82,59 / 82,62 MiB | 128 MiB |
| API replica 1 | 50,42% / 50,85% | 66,34 / 66,23 MiB | 256 MiB |
| API replica 2 | 52,31% / 51,00% | 66,40 / 76,12 MiB | 256 MiB |
| PostgreSQL | 20,22% / 19,96% | 44,47 / 45,44 MiB | 512 MiB |
| Redis | 1,31% / 1,33% | 3,71 / 3,70 MiB | 128 MiB |
Генератор closed-loop ограничен клиентом и подвержен coordinated omission. Перцентили относятся только к успешным запросам, поэтому результат не является пределом производительности системы.
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 30.0,
"elapsed_seconds": 30.017,
"concurrency": 4,
"successful_requests": 10512,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 350.206,
"successful_latency_ms": {
"p50": 5.169,
"p95": 50.037,
"p99": 61.382
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+55
View File
@@ -0,0 +1,55 @@
# Поочерёдная замена API под нагрузкой
Дата: 2026-10-23.
## Сценарий
Нагрузка выполнялась через HAProxy на `http://localhost:8080`:
```sh
python3 tests/load.py \
--base-url http://localhost:8080 \
--duration 30 \
--concurrency 4 \
--output evidence/rolling-update-load.json
```
Во время нагрузки выполнен `scripts/rolling-update.sh`. Скрипт по очереди удаляет одну API-реплику, создаёт замену и перед переходом ко второй ждёт две реплики в состоянии `healthy`.
## Наблюдение реплик
До замены:
```text
486287bf812aecec7bba303bd502e06fe6758602ef248e5933ecfd02964a388a healthy
03f5832b4b2a570d245a01a308e7756db170b54caeeb7ec9e6c2a0e4cf2241a6 healthy
```
После замены:
```text
c1fa8669e26796af661b85f947369a9be8245c18c5f560c74a24f772d1015bbd healthy
3d931568da47ff5723fd7089e876ea5d5825abe1ec73506b3625180686425cd4 healthy
```
Обе исходные реплики заменены новыми контейнерами. Одновременно останавливалась только одна реплика.
## Результат нагрузки
- Длительность: 30,017 с.
- Concurrency: 4.
- Успешные запросы: 10 512.
- Ошибки: 0.
- Error ratio: 0,0.
- Successful RPS: 350,206.
- p50: 5,169 мс.
- p95: 50,037 мс.
- p99: 61,382 мс.
Машиночитаемый результат сохранён в `evidence/rolling-update-load.json`.
## Совместимость миграции
Миграция lab3 добавляет nullable-поле `idempotency_key` и уникальность `(sender_id, chat_id, idempotency_key)`. Старая версия API может продолжать записывать `NULL`, а новая версия читает старые сообщения без ключа. Поэтому схема совместима с поочерёдной заменой приложения.
Ограничение: создание уникального ограничения может блокировать запись на большой таблице. В учебном стенде миграция выполняется отдельно до запуска API и проверена на малом наборе данных; online-миграция большой production-таблицы не заявляется.
+31
View File
@@ -0,0 +1,31 @@
global
log stdout format raw local0
defaults
log global
mode http
option httplog
timeout connect 2s
timeout client 30s
timeout server 30s
timeout check 2s
resolvers docker
nameserver docker_dns 127.0.0.11:53
resolve_retries 3
timeout resolve 1s
timeout retry 1s
hold valid 1s
hold obsolete 1s
frontend public
bind :8080
default_backend api_backend
backend api_backend
balance roundrobin
option httpchk
http-check send meth GET uri /health/ready ver HTTP/1.1 hdr Host api
http-check expect status 200
default-server check inter 1s fastinter 500ms downinter 1s fall 2 rise 2 resolvers docker init-addr libc,none
server-template api 2 api:8080
+12
View File
@@ -0,0 +1,12 @@
#!/bin/sh
set -eu
script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
project_dir=$(dirname -- "$script_dir")
cd "$project_dir"
# Останавливаем публичный маршрут до перезапуска общих хранилищ.
docker compose --env-file .env stop lb api >/dev/null
docker compose --env-file .env restart postgres redis >/dev/null
docker compose --env-file .env up -d --wait --wait-timeout 60 postgres redis >/dev/null
docker compose --env-file .env up -d --wait --wait-timeout 60 api lb >/dev/null
+42
View File
@@ -0,0 +1,42 @@
#!/bin/sh
set -eu
script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
project_dir=$(dirname -- "$script_dir")
cd "$project_dir"
wait_for_two_healthy() {
deadline=$(( $(date +%s) + 60 ))
while [ "$(date +%s)" -lt "$deadline" ]; do
ids=$(docker compose --env-file .env ps -q api)
set -- $ids
if [ "$#" -eq 2 ]; then
all_healthy=true
for container_id in "$@"; do
status=$(docker inspect --format '{{.State.Health.Status}}' "$container_id")
if [ "$status" != 'healthy' ]; then
all_healthy=false
break
fi
done
if [ "$all_healthy" = true ]; then
return 0
fi
fi
sleep 1
done
printf '%s\n' 'two healthy API replicas did not appear within 60 seconds' >&2
return 1
}
wait_for_two_healthy
original_ids=$(docker compose --env-file .env ps -q api)
for old_id in $original_ids; do
old_instance=$(docker inspect --format '{{.Config.Hostname}}' "$old_id")
docker stop --time 5 "$old_id" >/dev/null
docker rm "$old_id" >/dev/null
docker compose --env-file .env up -d --no-deps --no-recreate --scale api=2 api >/dev/null
wait_for_two_healthy
printf 'replaced API instance %s\n' "$old_instance"
done
+24
View File
@@ -0,0 +1,24 @@
#!/bin/sh
set -eu
: "${TARGET_INSTANCE_ID:?test provides target API instance alias}"
script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
project_dir=$(dirname -- "$script_dir")
cd "$project_dir"
target_container=''
for container_id in $(docker compose --env-file .env ps -q api); do
instance_id=$(docker inspect --format '{{.Config.Hostname}}' "$container_id")
if [ "$instance_id" = "$TARGET_INSTANCE_ID" ]; then
target_container=$container_id
break
fi
done
if [ -z "$target_container" ]; then
printf '%s\n' 'API instance from TARGET_INSTANCE_ID was not found' >&2
exit 1
fi
docker stop --time 5 "$target_container" >/dev/null
+92
View File
@@ -0,0 +1,92 @@
"""Pytest-проверки общей идемпотентности сообщений."""
from concurrent.futures import ThreadPoolExecutor
import uuid
import pytest
from tests.client import Client
@pytest.fixture
def scenario():
"""Создаёт отдельного пользователя и чат для теста."""
client = Client()
alice, _bob, _eve, chat = client.bootstrap()
return client, alice, chat
def test_replay_returns_original_message(scenario):
"""Повтор ключа возвращает исходное сообщение."""
client, alice, chat = scenario
key = uuid.uuid4().hex
first = client.message(alice, chat, 'same-body', key=key)['json']
replay = client.message(alice, chat, 'same-body', key=key)['json']
assert replay == first
def test_reused_key_with_different_body_returns_conflict(scenario):
"""Повтор ключа с другим телом возвращает 409."""
client, alice, chat = scenario
key = uuid.uuid4().hex
client.message(alice, chat, 'first-body', key=key)
client.call(
'POST',
'/api/v1/chats/' + chat['id'] + '/messages',
409,
actor=alice,
body={'text': 'different-body'},
headers={'Idempotency-Key': key},
)
@pytest.mark.parametrize(
'headers',
[
pytest.param({}, id='missing'),
pytest.param({'Idempotency-Key': 'invalid key'}, id='invalid'),
],
)
def test_invalid_idempotency_key_returns_bad_request(scenario, headers):
"""Отсутствующий или неверный ключ возвращает 400."""
client, alice, chat = scenario
client.call(
'POST',
'/api/v1/chats/' + chat['id'] + '/messages',
400,
actor=alice,
body={'text': 'validation'},
headers=headers,
)
def test_concurrent_retries_create_one_message(scenario):
"""Конкурентные повторы через две реплики создают одно сообщение."""
client, alice, chat = scenario
key = uuid.uuid4().hex
text = 'concurrent-idempotency-' + key
def send(_index):
return Client(timeout=5).message(alice, chat, text, key=key)
with ThreadPoolExecutor(max_workers=20) as pool:
responses = list(pool.map(send, range(20)))
message_ids = {response['json']['id'] for response in responses}
instance_ids = {response['headers']['X-Instance-Id'] for response in responses}
assert len(message_ids) == 1
assert len(instance_ids) >= 2
history = client.call(
'GET',
'/api/v1/chats/' + chat['id'] + '/messages?limit=100',
actor=alice,
schema='MessagePage',
)['json']['items']
matching = [message for message in history if message['text'] == text]
assert len(matching) == 1
assert matching[0]['id'] in message_ids