From 57b4e8b5ec1f499dbf5fcad73deccbae76f4eee8 Mon Sep 17 00:00:00 2001 From: thefankor Date: Fri, 23 Oct 2026 18:54:18 +0300 Subject: [PATCH] =?UTF-8?q?=D0=9B=D0=A03:=20=D0=B1=D0=B0=D0=BB=D0=B0=D0=BD?= =?UTF-8?q?=D1=81=D0=B8=D1=80=D0=BE=D0=B2=D0=BA=D0=B0,=20=D0=BE=D1=82?= =?UTF-8?q?=D0=BA=D0=B0=D0=B7=D0=BE=D1=83=D1=81=D1=82=D0=BE=D0=B9=D1=87?= =?UTF-8?q?=D0=B8=D0=B2=D0=BE=D1=81=D1=82=D1=8C=20=D0=B8=20=D0=B8=D0=B4?= =?UTF-8?q?=D0=B5=D0=BC=D0=BF=D0=BE=D1=82=D0=B5=D0=BD=D1=82=D0=BD=D0=BE?= =?UTF-8?q?=D1=81=D1=82=D1=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Makefile | 5 +- REPORT.md | 141 ++++++++++++++++-- .../20261023_0002_message_idempotency.py | 35 +++++ app/api/middleware.py | 7 +- app/api/routers/messages.py | 15 +- app/main.py | 4 +- app/models/message.py | 13 +- app/repositories/messages.py | 52 +++++-- app/services/messages.py | 3 +- compose.yaml | 39 ++++- evidence/README.md | 7 + evidence/load.json | 17 +++ evidence/results.md | 87 +++++++++++ evidence/rolling-update-load.json | 17 +++ evidence/rolling-update.md | 55 +++++++ infra/haproxy.cfg | 31 ++++ scripts/restart.sh | 12 ++ scripts/rolling-update.sh | 42 ++++++ scripts/stop-one.sh | 24 +++ tests/test_idempotency.py | 92 ++++++++++++ 20 files changed, 659 insertions(+), 39 deletions(-) create mode 100644 alembic/versions/20261023_0002_message_idempotency.py create mode 100644 evidence/load.json create mode 100644 evidence/results.md create mode 100644 evidence/rolling-update-load.json create mode 100644 evidence/rolling-update.md create mode 100644 infra/haproxy.cfg create mode 100755 scripts/restart.sh create mode 100755 scripts/rolling-update.sh create mode 100755 scripts/stop-one.sh create mode 100644 tests/test_idempotency.py diff --git a/Makefile b/Makefile index 5d86d17..b32dc6d 100644 --- a/Makefile +++ b/Makefile @@ -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) diff --git a/REPORT.md b/REPORT.md index c267900..a485efc 100644 --- a/REPORT.md +++ b/REPORT.md @@ -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 нагрузочный генератор. diff --git a/alembic/versions/20261023_0002_message_idempotency.py b/alembic/versions/20261023_0002_message_idempotency.py new file mode 100644 index 0000000..60d5eeb --- /dev/null +++ b/alembic/versions/20261023_0002_message_idempotency.py @@ -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') diff --git a/app/api/middleware.py b/app/api/middleware.py index ef00576..fb4e64f 100644 --- a/app/api/middleware.py +++ b/app/api/middleware.py @@ -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: diff --git a/app/api/routers/messages.py b/app/api/routers/messages.py index 369610f..b97f10f 100644 --- a/app/api/routers/messages.py +++ b/app/api/routers/messages.py @@ -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) diff --git a/app/main.py b/app/main.py index bfe0c55..9426a9d 100644 --- a/app/main.py +++ b/app/main.py @@ -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, ) diff --git a/app/models/message.py b/app/models/message.py index c2615cf..96a716f 100644 --- a/app/models/message.py +++ b/app/models/message.py @@ -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) diff --git a/app/repositories/messages.py b/app/repositories/messages.py index 95ac41a..f387e9a 100644 --- a/app/repositories/messages.py +++ b/app/repositories/messages.py @@ -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( diff --git a/app/services/messages.py b/app/services/messages.py index 9ed342a..ec3de20 100644 --- a/app/services/messages.py +++ b/app/services/messages.py @@ -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('чат не найден') diff --git a/compose.yaml b/compose.yaml index fe13d8e..0511f04 100644 --- a/compose.yaml +++ b/compose.yaml @@ -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: diff --git a/evidence/README.md b/evidence/README.md index 8df7001..cc69db4 100644 --- a/evidence/README.md +++ b/evidence/README.md @@ -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` — агрегаты нагрузки во время замены. diff --git a/evidence/load.json b/evidence/load.json new file mode 100644 index 0000000..9b574ad --- /dev/null +++ b/evidence/load.json @@ -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." +} diff --git a/evidence/results.md b/evidence/results.md new file mode 100644 index 0000000..c2f9bf9 --- /dev/null +++ b/evidence/results.md @@ -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. Перцентили относятся только к успешным запросам, поэтому результат не является пределом производительности системы. diff --git a/evidence/rolling-update-load.json b/evidence/rolling-update-load.json new file mode 100644 index 0000000..20db2eb --- /dev/null +++ b/evidence/rolling-update-load.json @@ -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." +} diff --git a/evidence/rolling-update.md b/evidence/rolling-update.md new file mode 100644 index 0000000..03ca75b --- /dev/null +++ b/evidence/rolling-update.md @@ -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-таблицы не заявляется. diff --git a/infra/haproxy.cfg b/infra/haproxy.cfg new file mode 100644 index 0000000..5bd0c14 --- /dev/null +++ b/infra/haproxy.cfg @@ -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 diff --git a/scripts/restart.sh b/scripts/restart.sh new file mode 100755 index 0000000..691598a --- /dev/null +++ b/scripts/restart.sh @@ -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 diff --git a/scripts/rolling-update.sh b/scripts/rolling-update.sh new file mode 100755 index 0000000..a822c18 --- /dev/null +++ b/scripts/rolling-update.sh @@ -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 diff --git a/scripts/stop-one.sh b/scripts/stop-one.sh new file mode 100755 index 0000000..3f77079 --- /dev/null +++ b/scripts/stop-one.sh @@ -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 diff --git a/tests/test_idempotency.py b/tests/test_idempotency.py new file mode 100644 index 0000000..96e0758 --- /dev/null +++ b/tests/test_idempotency.py @@ -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