База lab4: контракт 1.4.0 и реализация lab1–lab3

This commit is contained in:
Vladislav Kunetskiy
2026-10-21 21:29:10 +03:00
13 changed files with 1098 additions and 265 deletions
+1 -1
View File
@@ -1,4 +1,4 @@
## Лабораторная 3
## Лабораторная 4
Автор / группа: TODO
Целевая оценка (3/4/5): TODO
+1 -1
View File
@@ -1,4 +1,4 @@
# Памятка преподавателю — лабораторная 3
# Памятка преподавателю — лабораторная 4
## Что подготовлено
+33 -32
View File
@@ -1,6 +1,6 @@
# Лабораторная 3. Балансировка и отказ API-реплики
# Лабораторная 4. S3-хранилище и вложения
Запустить несколько взаимозаменяемых экземпляров API за единой точкой входа и сохранить корректность при остановке одного из них.
Разделить метаданные и бинарное содержимое, добавить изображения в сообщения и сохранить доступ к ним при переключении API-реплики.
Это **skeleton**, а не готовый сервер. Здесь есть задание, контракт и публичные проверки. Реализацию приложения, Dockerfile и требуемую инфраструктуру пишет студент. Язык и framework свободные; UI не обязателен.
@@ -8,42 +8,41 @@
## Откуда начинаем
Нужен минимум lab2: PostgreSQL, общие действующие сессии, миграции. Добавляются X-Instance-Id и обязательный Idempotency-Key при отправке сообщения.
Перенесите минимум lab3. Дополняются поля сообщения и endpoint вложений; прежние текстовые POST остаются валидными.
**Архитектура:** Клиент → LB → API × 2+ → общие PostgreSQL и хранилище сессий. Compose или Swarm — на выбор.
**Архитектура:** Клиент → LB → API × 2+ → PostgreSQL (метаданные) + приватное S3-хранилище (байты).
## Что сделать
1. Выберите Compose + Nginx/HAProxy/Traefik либо Docker Swarm. Для выбранного варианта дайте одну последовательность запуска.
2. Уберите локальные сессии/другие данные, от которых зависит корректность, из API. Миграции выполняйте отдельно и согласованно, а не гонкой всех реплик.
3. Настройте балансировщик, проверки готовности, DNS/обновление backend-адресов и graceful shutdown. Не закрепляйте клиента sticky session как способ исправить раздельное состояние.
4. Реализуйте общую идемпотентность отправки сообщения. Проверьте одинаковый ключ одновременно через разные реплики.
5. Подготовьте явный action script, останавливающий одну выбранную API-реплику, и продемонстрируйте чтение/запись во время отказа.
1. Выберите один S3-совместимый сервер: MinIO, SeaweedFS или RustFS. Закрепите проверенную версию образа и опишите создание приватного bucket.
2. Спроектируйте Attachment и связь с чатом/сообщением. S3 object key назначает сервер, filename используется только для отображения.
3. Реализуйте синхронный binary upload PNG/JPEG с ограничениями, сохранение метаданных и авторизованный download через API.
4. Включите S3 и persistent volumes в общий Compose/Swarm. Проверьте, что другая API-реплика скачивает файл после остановки загрузившей.
5. Проверьте недоступность S3, чужой чат и restart всего стенда.
## Оценка «3»: работающий минимум
- Весь стенд описан в compose.yaml или stack.yaml, запускается документированной командой. Не менее двух API-реплик, одна публичная точка входа, одна общая БД и общее хранилище сессий.
- Разные запросы одного пользователя обслуживаются разными репликами без повторного входа. Это видно по X-Instance-Id. Доступ через LB — основной проверяемый маршрут.
- Можно остановить любую одну API-реплику при работающей другой: не позднее 10 секунд продолжаются новые чтения/записи, подтверждённые сообщения доступны. Краткие ошибки/оборванные запросы во время обнаружения отказа измеряются и допустимы.
- Повтор POST сообщения с тем же Idempotency-Key не создаёт дубль, включая конкурентный повтор и переключение реплики. Неподтверждённую запись клиент может безопасно повторить с тем же ключом.
- make test, persistence и failover-сценарий проходят; для failover проверяется наличие ≥2 наблюдаемых реплик. Для Swarm сборка образа и его доступность узлам описаны отдельно.
- Все обязательные возможности lab3 сохранены. S3-сервер находится в общем стенде; метаданные вложений живут в PostgreSQL, байты — в приватном bucket, не в БД или локальном каталоге API.
- POST вложения возвращает 201 ready после сохранения; оригинал скачивается побайтно. Message с attachment_ids читается участниками чата. Публичный smoke проверяет checksum и отсутствие доступа у постороннего.
- Принимаются реальные PNG/JPEG ≤10 MiB и ≤40 млн пикселей; MIME проверяется по содержимому, опасные filename отклоняются, лимиты применяются до неограниченного чтения/декодирования.
- Upload → остановка обслужившей API-реплики → download через другую возвращает тот же файл. Restart с сохранением volumes сохраняет метаданные и оригинал.
## Оценка «4»: уровень стажёра/джуна
Весь уровень 3 **и все** пункты ниже:
- Health/readiness, timeouts и прекращение приёма при SIGTERM настроены согласованно; LB исключает недоступный backend. Укажите период проверок и максимальное время обнаружения отказа.
- Последовательно остановите каждую API-реплику (восстанавливая предыдущую); соберите RPS, ошибки и время восстановления. Общая идемпотентность проверяется параллельными запросами с одним ключом.
- Контейнеры имеют CPU/RAM-лимиты, API не публикуют порты наружу в обход LB; секреты и хранилища общие только там, где нужно. Нет container_name, мешающего масштабированию одного Compose-service.
- Rolling update или эквивалентная поочерёдная замена проверена под нагрузкой. Миграции запускаются однократно и совместимы с работающей версией либо ограничение честно описано.
- Тесты покрывают слишком большой файл, повреждённое изображение, подмену MIME, чужое attachment_id и привязку файла другого чата. Пользовательская ошибка не превращается в 500.
- Прерывание загрузки и отказ между записью S3/БД не оставляют вечных неучтённых объектов: есть документированный механизм компенсации/сверки/очистки с безопасным grace period.
- Лимиты/таймауты и потоковая обработка не позволяют одной загрузке занять неограниченную RAM. Проведён эксперимент ≥10 одновременных загрузок с измерением пика памяти.
- Bucket bootstrap идемпотентен; API использует отдельные S3 credentials с ограниченными правами. Административная консоль не открыта в общей сети. Есть проверка private bucket вне API.
## Оценка «5»: исследование и доказанный результат
Весь уровень 4 **и один законченный трек на выбор**. Приведите гипотезу, повторяемую методику, результаты и ограничения.
**Трек 1. Цена масштабирования.** При фиксированном суммарном CPU/RAM сравните 1/2/4 API-реплики на одном профиле нагрузки; затем проведите серию с ростом ресурсов. Найдите saturation point БД/LB/пула и покажите, почему рост реплик перестаёт помогать. Дайте исходные данные, графики и одно подтверждённое улучшение.
**Трек 1. Прямой upload.** Добавьте отдельный безопасный presigned-upload flow: короткая подпись, уникальный ключ, проверка принадлежности, размера/checksum при complete, обработка незавершённой загрузки. Сохраните обязательный proxy endpoint. Сравните трафик и RAM API при ≥2 размерах файлов, покажите негативные сценарии.
**Трек 2. Отказ узла.** Расширьте стенд до нескольких узлов, покажите перенос API при потере узла и разберите оставшиеся SPOF (LB, DB, storage). Для заявленной защищённой зависимости покажите реальный failover и сохранность данных. Если DB не реплицирована, не заявляйте выживание её узла.
**Трек 2. Согласованность двух хранилищ.** Разработайте повторяемый reconciler для orphan/missing объектов и метаданных. Внедрите ошибки на обеих сторонах, покажите обнаружение и безопасное исправление с dry-run/повторным запуском. Докажите, что свежие и используемые вложения не удаляются; измерьте стоимость обхода.
## Как начать и проверить
@@ -79,26 +78,28 @@ Smoke не выставляет оценку автоматически. Про
## Сценарий защиты
1. Запустить стенд и показать ≥2 разных X-Instance-Id через LB с одной сессией.
2. Запустить make test-failover ACTION_SCRIPT=scripts/stop-one.sh. Скрипт теста выполняет запросы во время action, учитывает ошибки и повторяет сообщения с исходным ключом.
3. Показать, какой контейнер действительно остановлен; заголовок сам по себе не доказательство разных процессов. Повторить для второй реплики после восстановления первой.
4. Проверить restart всего стенда с сохранением volumes и неизменным токеном. Для 4/5 — соответствующие эксперименты.
1. Загрузить fixture, отправить message с attachment_ids, скачать как второй участник и сравнить SHA-256.
2. С третьим пользователем получить 404 для метаданных и bytes; direct unauthenticated S3 GET не отдаёт объект.
3. Выполнить persistence и failover: общий тест начиная с lab4 сохраняет и повторно читает оригинал через API.
4. Показать, что на API нет обязательного локального файла оригинала. Для 4/5 — отказы и эксперименты.
## Что должно быть в PR
compose.yaml или stack.yaml, конфигурация LB, scripts/restart.sh, scripts/stop-one.sh, Dockerfile, миграции, результаты отказов.
Дополненный стенд, настройка bucket/политики, миграции Attachment, тесты файлов, описание согласованности БД/S3 и результаты.
Заполните `REPORT.md` и [шаблон PR](.github/pull_request_template.md), укажите целевую оценку/трек. Не меняйте обязательный контракт и публичные tests ради зелёного результата. Сохраняйте возможности предыдущих лабораторных в пределах [объявленных переходов](COURSE.md).
## Вопросы на защите
- Чем отказ процесса отличается от отказа узла?
- Почему depends_on/healthcheck сами по себе не являются балансировщиком?
- Какие POST можно повторять после timeout и что защищает Idempotency-Key?
- Что сломается при увеличении числа API, если сессии находятся в локальной памяти?
- Почему файл в Docker volume одной API-реплики не равен объектному хранилищу?
- Когда можно честно вернуть 201?
- Что произойдёт, если S3 PUT прошёл, а COMMIT в PostgreSQL — нет?
- Почему случайный object key и приватный bucket не заменяют ACL приложения?
## Первичные материалы
- [Compose services](https://docs.docker.com/reference/compose-file/services/)
- [Swarm routing mesh](https://docs.docker.com/engine/swarm/ingress/)
- [Swarm services](https://docs.docker.com/engine/swarm/services/)
- [S3 object uploads](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html)
- [Presigned URLs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html)
- [MinIO](https://github.com/minio/minio)
- [SeaweedFS](https://github.com/seaweedfs/seaweedfs)
- [RustFS](https://docs.rustfs.com/)
+16 -217
View File
@@ -1,238 +1,37 @@
# Отчёт — лабораторная 3
# Отчёт — лабораторная 4
- Автор, группа: Владислав Кунецкий, БВT2303
- Целевая оценка; выбранный трек 5, если нужен: 5; трек 1 «Цена масштабирования»
- Commit/PR: solution/bvt2303-kunetsky (fork репозитория лабораторной 3)
- Использованные источники, библиотеки и помощь ИИ: ogen (HTTP-транспорт из `contracts/openapi.json`), sqlc (SQL-слой), goose (миграции), pgx/v5, go-redis/v9, viper + validator (конфигурация), mockery/v3 + testify (тесты), zap через `log/slog`. Помощь ИИ использовалась для обсуждения архитектуры, ревью и подготовки кода; решение проверено и изменено автором. База перенесена из лабораторной 2.
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
## Запуск из чистого clone
Требования: Docker Engine с Compose v2 (`docker compose`), `make`; Python 3.9+ (только стандартная библиотека) для проверок; Go 1.27 — для локальной сборки и unit/integration-тестов.
Проверено на: macOS 25.5.0, Apple M5 Pro, 48 GiB RAM, Docker Engine 29.5.2 (Colima, macOS Virtualization.framework), Docker Compose 5.5.1, Go 1.27.1. Docker VM: **2 vCPU и ≈1.9 GiB RAM** — лимиты контейнеров в `compose.yaml` подобраны под этот бюджет (API 0.5 CPU / 256 MiB на реплику, PostgreSQL 0.5 CPU / 384 MiB, Redis 0.25 / 192 MiB, LB 0.25 / 64 MiB), суммарно меньше доступного. Образы зафиксированы по версии: `haproxy:3.2-alpine`, `redis:7.4-alpine`, `postgres:18-alpine@sha256:77f585114c32fbca283dc835b0596f4e52b51b4c6662d7810b2f4084f60a1873`; приложение собирается из `Dockerfile` (`golang:1.27.1-alpine` → `alpine:3.22`), сборка ограничена `GOFLAGS=-p=2`, чтобы компилятор Go не выбил память небольшой VM.
```sh
cp .env.example .env # синтетические креды локального стенда, реальных секретов нет
make up # docker compose --env-file .env up -d --build
make ps # контейнеры и health
curl -fsS http://localhost:8080/health/ready
make test # публичный smoke (профиль lab3) через LB
make test-idempotency # параллельные повторы одного Idempotency-Key
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
python3 student-tests/replica_failover.py --action-script scripts/stop-one.sh
make test-lb-readiness # LB и реплика, потерявшая БД (readiness 503)
scripts/rolling_update.sh # поочерёдная замена реплик под нагрузкой
make down # остановка стенда; named volumes остаются
```
Намеренное удаление учебных данных (удаляет volumes и сессии):
```sh
docker compose --env-file .env down -v
```
Оператору достаточно `cp .env.example .env` и `make up`: миграции выполняет отдельный сервис `migrate` (`goose up`), он завершается успешно до старта API-реплик (`depends_on: service_completed_successfully`), поэтому реплики не гоняют схему наперегонки. Приложение принимает SIGTERM и дренирует сервер в пределах `SERVER_SHUTDOWN_TIMEOUT=10s`; у контейнера API `stop_grace_period: 15s`, чтобы Docker не убил запрос в полёте.
### Соответствие переменных `.env.example` реальной конфигурации
| Логическое имя из задания | Реальная переменная | Смысл |
| --- | --- | --- |
| `APP_HOST` / `APP_PORT` | `SERVER_HOST` / `SERVER_PORT` | адрес и порт HTTP-сервера API |
| `APP_ENV` | `APP_ENV` | выбор `config/<env>/config.yaml`; реализован только `dev` |
| `SESSION_STORE=postgres` | — | сессии лежат в PostgreSQL (`sessions.token_hash`), параметр не нужен |
| `DATABASE_URL_FILE` | `POSTGRES_*` | параметры подключения к общей БД без файлов секретов |
| `CACHE_URL_FILE` | `REDIS_*`, `CACHE_*` | общий кэш списка чатов и его блокировки |
| `IDEMPOTENCY_TTL_SECONDS` | `IDEMPOTENCY_TTL_SECONDS` | срок хранения записи идемпотентности (по умолчанию 86400 с) |
| `API_REPLICAS` | `API_REPLICAS` | число API-реплик стенда (`deploy.replicas`) |
| — | `API_CPU_LIMIT` / `API_MEM_LIMIT` | лимиты CPU/RAM одной реплики (для профилей трека 1) |
| — | `POSTGRES_CPU_LIMIT` / `POSTGRES_MEM_LIMIT` / `POSTGRES_MAX_CONNS` | бюджет общего PostgreSQL и пул соединений одной реплики (трек 1) |
| — | `SERVER_MAX_BODY_BYTES` | предел размера тела запроса (413 при превышении) |
| — | `LB_STATS_PORT` | loopback-порт страницы оператора HAProxy |
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
## Архитектура и решения
Схема: клиент → LB (HAProxy с активными проверками `/health/ready`) → 2+ API-реплики → общие PostgreSQL и Redis. Единая точка входа — только LB: `127.0.0.1:8080`; порты API и хранилищ наружу не публикуются.
| Роль | Сервис в compose | Образ / версия | Проверка готовности | Сеть и порт | Данные |
| --- | --- | --- | --- | --- | --- |
| Единая точка входа | `lb` | `haproxy:3.2-alpine` | активный `httpchk GET /health/ready`, период 2 с, `fall 2 rise 2` | публикует `127.0.0.1:8080`; страница оператора `127.0.0.1:8404` | — |
| API-реплики | `api`, `deploy.replicas=${API_REPLICAS:-2}` | сборка из `Dockerfile` → `mtusi-messenger:lab3` | Docker healthcheck `/health/ready`, интервал 10 с | только внутренняя сеть, alias `api-replica` | — |
| Миграции схемы | `migrate` | тот же образ, one-shot `goose up` | завершение с кодом 0 до старта реплик | только внутренняя сеть | — |
| Источник истины | `postgres` | `postgres:18-alpine@sha256:77f5…1873` | `pg_isready`, 5 с | только внутренняя сеть | volume `postgres18-data` |
| Кэш и блокировки | `redis` | `redis:7.4-alpine` (AOF everysec) | `redis-cli ping`, 5 с | только внутренняя сеть | volume `redis7-data` |
| Credentials | — | — | — | `.env` (вне git, синтетические значения для локального стенда), в контейнеры передаются явными переменными | — |
- **Источник истины — PostgreSQL**: пользователи, чаты, участники, сообщения, серверные сессии (`sha256(token)`), записи идемпотентности. Транзакционные границы: создание чата вместе с участниками; отправка сообщения вместе с записью идемпотентности.
- **Redis/Valkey** — кэш списка чатов с распределённой блокировкой от stampede и версиями (`user_chat_versions`); не хранит ничего, что нужно для корректности ответа.
- **Общие сессии**: сессия создаётся одной репликой, любые другие её читают из БД, поэтому логин не привязан к реплике (sticky-сессии не используются).
- **`X-Instance-Id`**: значение стабильно в пределах процесса (`INSTANCE_ID` или hostname = короткий ID контейнера) и проставляется middleware на **каждый** ответ, включая ошибки 400/404/405, которые формирует транспорт, а не handler.
- **Идемпотентность отправки** (`Idempotency-Key` обязателен, `[A-Za-z0-9._:-]{1,128}`):
- таблица `message_idempotency (actor_id, chat_id, key, request_hash, message_id, expires_at)`, PK `(actor_id, chat_id, key)` — область уникальности «пользователь + чат + ключ»;
- claim — один `INSERT ... ON CONFLICT (actor_id, chat_id, key) DO UPDATE ... WHERE expires_at <= now() RETURNING`: живая запись не перезаписывается, истёкшая занимается заново;
- вставка сообщения и запись `message_id` идут в **одной транзакции с claim**, поэтому не бывает ключа без сообщения и наоборот; при откате (например, отправитель не участник) ключ не занимается;
- конкурентный повтор через разные реплики блокируется на строке и после коммита победителя возвращает его сообщение → ровно один INSERT в `messages`;
- повтор с тем же ключом и другим payload — `409`, для этого хранится `request_hash` (sha256 канонического payload `{"text":...}`; порядок ключей и пробелы в JSON не влияют).
- **LB**: HAProxy 3.2 (образ зафиксирован), `server-template api 4 api-replica:8080` + `resolvers docker` (Docker DNS 127.0.0.11, `hold valid 5s`) — адреса берутся из общего сетевого alias, выданного всем репликам, и переразрешаются каждые 5 с, поэтому масштабирование (1/2/4), замена контейнеров и смена IP не требуют правки конфига. Балансировка `leastconn`. Aктивные проверки готовности: `option httpchk GET /health/ready` + `http-check expect status 200`, `inter 2s fall 2 rise 2` — неготовая реплика исключается из ротации за ≤4 с и возвращается за ≤4 с. Это принципиально: пассивные проверки (nginx OSS, прежний вариант) не умели убирать реплику, которая остаётся доступной по сети, но теряет БД — она продолжала получать трафик и отвечать 503 (зафиксировано в ревью: 20 из 40 запросов `/health/live`). После перехода на активные проверки такая реплика получает **0 из 40** запросов, её статус `DOWN` (`evidence/lb-readiness.txt`), а запись через LB не прерывается (1 247 RPS, ноль ошибок в том же сценарии).
- **Повторы и идемпотентность**: HAProxy настроен на `retry-on conn-failure` + `retries 2` — повтор происходит только когда соединение не установилось и запрос не ушёл. Уже отправленный POST не повторяется, поэтому прозрачного дублирования создания чата нет (прежний вариант с `proxy_next_upstream ... non_idempotent` этим страдал). Неопределённый результат повтора остаётся за клиентом, а отправка сообщения защищена обязательным `Idempotency-Key`.
- **Страница оператора**: `127.0.0.1:8404/stats` (только loopback) показывает, какие реплики `UP`/`DOWN` и почему — именно по ней сняты доказательства выше.
- **Предел размера тела**: `SERVER_MAX_BODY_BYTES` (по умолчанию 256 КиБ). Тело больше лимита отклоняется с `413` до чтения и декодирования, поэтому публичный `POST /api/v1/users` не может выбить память реплики (раньше JSON-декодер читал тело целиком до любой валидации и до аутентификации). Для вложений ЛР4 (до 10 MiB) значение поднимается явно — это объявленный переход.
- **Логи**: заголовочные параметры (в том числе `Idempotency-Key`) попадают в лог как `redacted`, тела запросов — только своим размером; пароли, токены и содержимое сообщений не логируются.
- **Миграции**: одна последовательность для всего стенда (`migrate`), совместимость с работающей версией — новая таблица добавляется отдельной миграцией, старый код её не читает. Новая миграция пронумерована `00003`, а не `00002`: в базе, перенесённой из ЛР2, goose уже содержит применённую версию 2 (другая миграция того же репозитория), и совпадающий номер был бы молча пропущен при обновлении существующего стенда — это проверено на dev-базе (`goose: no migrations to run. current version: 2` при отсутствующей таблице).
### Что перенесено из lab2
Перенос: ветки `lab1` + `lab2` репозитория `mtusi-messenger`, перенесены только исходники, миграции, собственные тесты, Dockerfile и конфигурации (по правилам CONTRIBUTING.md; README/COURSE/contracts/публичные tests остались от skeleton ЛР3).
- Транспорт: HTTP-слой, сгенерированный ogen из `contracts/openapi.json`, REST-адаптер поверх него, middleware X-Request-Id и структурного логирования.
- Домен и сервисы: user / chat / message / session с валидацией и keyset-пагинацией.
- PostgreSQL — источник истины: pgx + sqlc, миграции goose, транзакции на создание чата.
- Сессии: Basic только при создании сессии, далее Bearer; в БД `sha256(token)`, TTL, переживают перезапуск процесса.
- Redis/Valkey: кэш списка чатов с распределённой блокировкой от stampede (`user_chat_versions`).
- Наблюдаемость: `/health/live`, `/health/ready`, структурированные логи (log/slog + zap).
- Инструменты: multi-stage `Dockerfile`, `docker-compose.local.yaml` для локального запуска, Makefile-таргеты, `.github/workflows/app.yml`.
### Изменения в этой работе (лаб. 3)
- Контракт 1.3.0: транспорт перегенерирован, `X-Instance-Id` во всех ответах, обязательный `Idempotency-Key` для отправки сообщения.
- Общая идемпотентность в PostgreSQL (миграция `00003_message_idempotency.sql`, sqlc-запросы, транзакция в `MessageRepository.Create`), 409 на конфликт payload.
- `IDEMPOTENCY_TTL_SECONDS` в конфиге (по умолчанию 24 ч), `.env.example` приведён к реальным переменным.
- Стенд ЛР3: `compose.yaml` (LB + `API_REPLICAS` реплик + PostgreSQL + Redis + одноразовый `migrate`), конфигурация LB `infra/lb/haproxy.cfg` (активные проверки готовности, ограниченные повторы, страница оператора), action-скрипты `scripts/stop-one.sh` и `scripts/restart.sh`, Makefile-таргеты `up/down/ps/logs`.
- Собственные проверки: `make test-idempotency` (параллельные повторы через LB), `student-tests/replica_failover.py` (поочерёдная остановка каждой реплики с метриками), `scripts/lb_readiness_check.sh` (неготовая реплика и LB), `scripts/rolling_update.sh`, эксперименты трека 1.
- Исправления по итогам аудита: отправка в несуществующий чат больше не даёт `500` из-за нарушения внешнего ключа от claim'а ключа идемпотентности (`23503` → `404`); добавлен предел размера тела (`413`, см. выше); заголовочные параметры не пишутся в лог; у проверок LB задан `timeout check 1s`, чтобы «залипшая» реплика исключалась за ограниченное время; у собственного сценария rolling update появился настоящий «наплыв» (новая реплика поднимается до снятия старой) и корректный счётчик 5xx (в HAProxy статус в логе печатается без кавычки, прежний шаблон молча давал нули).
- `Dockerfile`: убран жёстко заданный `TARGETARCH=amd64` — на Apple Silicon он давал x86-64 бинарник внутри arm64-образа, тот исполнялся через эмуляцию и падал по runtime-фаталам под нагрузкой (см. «Ограничения»); сборка ограничена `GOFLAGS=-p=2`, чтобы компилятор не выбил память небольшой Colima VM.
- Удалён осиротевший `scripts/track1_benchmark.py` (бенчмарк in-memory хранилища ЛР1: сам in-memory store удалён ещё в ЛР2, скрипт ссылался на несуществующий файл).
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab3, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
## Доказательства критериев
Артефакты ЛР1/ЛР2 перенесены в `evidence/lab1-2/` (там же пояснение, почему они не относятся к этой работе); в `evidence/` — только доказательства ЛР3.
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | `make test` | `PASS: lab3 public API scenario` через LB с двумя репликами | `evidence/smoke.txt` |
| Разные запросы одного пользователя обслуживают разные реплики | 40× `GET /users/me` через LB одной сессией (и 40× `/health/live`) | два разных `X-Instance-Id`, распределение видно по репликам | `evidence/failover/sequential.txt` (одна сессия), `evidence/lb-readiness.txt` (счётчики по репликам) |
| Идемпотентность: повтор, конкурентный повтор, смена реплики | `make test-idempotency` | 12 параллельных повторов одного ключа → одно сообщение; 12 разных payload → один 201 и одиннадцать 409; без ключа и с недопустимым ключом → 400 | `evidence/idempotency.txt` |
| Остановка одной реплики при работающей другой | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` (два прогона) | 127 и 100 подтверждённых записей, 0 ошибок, первое восстановление 0.21 с и 2.24 с | `evidence/failover/run1.txt`, `evidence/failover/run2.txt` |
| Последовательно остановлена каждая реплика, с измерениями (RPS, ошибки, время) | `python3 student-tests/replica_failover.py --action-script scripts/stop-one.sh` | реплика A: 91 запись (6.06 RPS), 0 ошибок, восстановление 1.66 с; реплика B: 100 записей (6.66 RPS), 0 ошибок, 1.66 с; после отказа обслуживает только вторая реплика; восстановление обеих 0.18–0.20 с; дублей нет (191 сообщение) | `evidence/failover/sequential.txt` |
| LB исключает неготовую реплику | `scripts/lb_readiness_check.sh` | реплика с потерянной БД (осталась доступной, readiness 503): **0 из 40** запросов, статус `DOWN` **через 2 с** (проверка `inter 2s fall 2 timeout check 1s`), при этом запись через LB не прервалась (1 163 RPS, 0 ошибок) | `evidence/lb-readiness.txt` |
| Предел размера тела | `python3`-проверка публичного `POST /api/v1/users` | тело 400 КиБ (сверх лимита 256 КиБ) → `413`, тело 100 КиБ → `400` (схема); реплика не выбита | `evidence/body-limit.txt` |
| Отказ БД не превращается в 500 | `python3`-проверка: `POST` сообщения напрямую в реплику (в обход LB) при остановленном PostgreSQL | напрямую к реплике — `503`, через LB — `503` с `X-Instance-Id` (ответ приложения), после возврата БД — `201` | `evidence/db-outage.txt` |
| Сохранность при перезапуске API и хранилищ | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | `PASS`: подтверждённые сообщения и прежний токен после перезапуска, volumes не удалялись | `evidence/persistence.txt` |
| Лимиты CPU/RAM, отсутствие публичных портов API, отсутствие `container_name` | `docker compose --env-file .env config`, `docker ps` | лимиты у каждого сервиса, публикуется только `127.0.0.1:8080` (LB) | `evidence/stand.txt` |
| Поочерёдная замена реплик под нагрузкой | `scripts/rolling_update.sh` (60 с, 8 клиентов; наплыв по одной реплике) | 97 359 подтверждённых записей, 3 переходные ошибки (0.003 %), **3 ответа 5xx от LB** за окно обновления, `restarts=0`; каждый шаг подтверждён сменой образа новых реплик и числом UP-слотов | `evidence/rolling-update/after/` |
| Контроль: тот же код вне Docker | `student-tests/rolling_update_load.py` против нативного процесса (90 с, 32 клиента) | 220 781 запрос, 0 ошибок, 2 452 RPS, p50 12.5 мс, p95 17.5 мс, p99 22.4 мс | `evidence/native-load.txt` |
| Проверки качества | `make check`, `make validate`, `make unit-test` (`-race`), `make integration-test` | все PASS, включая интеграционный тест «отправка в несуществующий чат → 404» | `evidence/quality.txt` |
| Трек 1: цена масштабирования | `scripts/track1_series.sh` + `scripts/track1_controls.sh` + `scripts/track1_report.py` | потолок ≈1 300–1 550 RPS: 1/2/4 реплики → −3 %/−5 %; бюджет API ×3, бюджет БД ×2 и бюджет LB ×4 не меняют RPS (перемежающий контроль: ±0.05 %), пул соединений не исчерпан; дрейф серии измерен | `evidence/track1/summary.md`, `evidence/track1/scaling-*.png` |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
`make check`, `make validate` (полная OpenAPI-валидация в venv) и `make unit-test` (`-race`) проходят; интеграционные тесты PostgreSQL (`-tags=integration`, включая конкурентный повтор одного ключа) — тоже.
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
## Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| `docker stop` одной API-реплики (прогон 1) | записи продолжаются, остановленная реплика исчезает из ответов | 127 успешных записей, 0 ошибок | 0.21 с |
| `docker stop` другой API-реплики (прогон 2) | то же | 100 записей, 0 ошибок | 2.24 с |
| Поочерёдно остановлены обе реплики (свой скрипт) | после каждой остановки пишет только вторая реплика, дублей нет | 91 и 100 записей (6.06 и 6.66 RPS), 0 ошибок, повторы с тем же ключом дубля не создали | 1.66 с и 1.66 с |
| Одной реплике закрыт доступ к БД (она остаётся доступной, readiness 503) | LB исключает её из ротации | 0 из 40 запросов ей, статус `DOWN` через 2 с, запись через LB не прервалась | — |
| Поочерёдная замена каждой реплики под нагрузкой (наплыв) | потери только на время остановки, дублей нет | 97 359 записей, 3 переходные ошибки, 3 ответа 5xx от LB, `restarts=0`, смена образа подтверждена по шагам | окно замены 5–6 с на реплику |
| Перезапуск API и всех хранилищ с сохранением volumes | сессия и данные живут | `PASS`, прежний токен работает | потери нет |
| Эмуляция x86-64 бинарника в arm64-образе (`--build-arg TARGETARCH=amd64`) | реплики замедляются и падают | в контроле (45 с, 8 клиентов) падений **не воспроизведено**: 89 560 запросов, 0 ошибок, 0 ответов 5xx; crash-loop наблюдались в других условиях | эффект не измерен (`evidence/rolling-update/emulated/`) |
| Удвоенный CPU БД, четырёхкратный CPU LB, пул 5 вместо 10, 32 клиента | пропускная способность вырастет, если узкое место — БД, LB или пул | бюджеты БД и LB не меняют RPS (перемежающий контроль: +0.04 % и −0.02 % при лимитах, проверенных по `docker inspect`); меньший пул хуже (−7 %); 32 клиента снижают RPS до 1 284 и растят p95 до 52.8 мс | `evidence/track1/summary.md`, `evidence/load-32clients.txt` |
## Трек 1. Цена масштабирования
Методика: один и тот же профиль `tests/load.py` (closed loop, `concurrency=8`, `duration=60` с, прогрев 15 с) против стенда на 1, 2 и 4 API-репликах при **фиксированном суммарном бюджете** 1.0 CPU / 768 MiB на API; затем серия с ростом бюджета — 2 реплики и суммарно 0.5, 1.0 и 1.5 CPU. Бюджеты общих хранилищ между профилями не меняются: PostgreSQL 0.50 CPU / 384 MiB, Redis 0.25 / 192, LB 0.25 / 64. В контрольных профилях меняется ровно одна ручка: пул соединений реплики 10 → 5, бюджет CPU PostgreSQL 0.50 → 1.00, бюджет CPU балансировщика 0.25 → 1.00.
Бюджеты хранилищ compose применяет при **создании** контейнера, поэтому скрипт пересоздаёт PostgreSQL и LB, когда бюджет профиля отличается от действующего, и проверяет применение по `docker inspect`: в `profile-*.json` и в строке `=== applied … ===` сводки попадают значения, снятые с работающих контейнеров, а не переменные запуска. Без этой проверки профиль описывал бы намерение, а измерение шло бы на прежнем лимите — на этом и провалился первый контроль удвоения CPU БД; тот прогон вместе с прогоном, где нагрузку подавал клиент хоста, лежит в `evidence/track1/superseded/`. Генератор работает **внутри VM** (`CLIENT=vm`, контейнер в сети стенда): клиент на хосте через проброс порта под шквалом новых соединений получает отказы самого проброса, не относящиеся к стенду (разбор — `evidence/path-overhead/`). Вся серия снимается одной командой `scripts/track1_series.sh` (~15 минут); профили с уже снятыми артефактами при повторном запуске пропускаются.
Бюджеты выбраны под Colima VM (2 vCPU, ≈1.9 GiB), чтобы измерения шли в её пределах, а не за счёт хоста. Ресурсы реплик считаются суммированием по одному timestamp: в первой версии сводки несколько реплик усреднялись как одна выборка, что занижало CPU и память вдвое — исправлено, сырые CSV не менялись. Сводка учитывает только контейнеры своего проекта (`--prefix`): параллельно поднятый стенд другой лаборатории иначе попадал в те же колонки (`…-lab2-postgres-1` → `postgres`). Сырые артефакты — `evidence/track1/` (`load-*.json`, `stats-*.csv`, `profile-*.json`), сводка — `evidence/track1/summary.md`, графики — `scaling-fixed-budget.png` и `scaling-growth.png`.
### Профили и результаты
Серия 1 — фиксированный суммарный бюджет 1.0 CPU / 768 MiB на API (PostgreSQL 0.50 CPU / 384 MiB, Redis 0.25, LB 0.25), нагрузка `tests/load.py` (closed loop, 8 клиентов, 60 с, прогрев 15 с, клиент внутри VM):
| реплик | CPU на реплику | успешный RPS | p50, мс | p95, мс | p99, мс | ошибки | API CPU (сумма) | PG CPU | LB CPU | строк в `messages` |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 1 | 1.00 | 1 542.9 | 5.05 | 8.01 | 10.24 | 0 | 0.24 | 0.39 | 0.10 | 3.60 млн |
| 2 | 0.50 | 1 491.3 | 5.25 | 8.23 | 10.30 | 0 | 0.28 | 0.36 | 0.10 | 3.71 млн |
| 4 | 0.25 | 1 415.7 | 5.54 | 8.61 | 10.75 | 0 | 0.31 | 0.35 | 0.10 | 3.82 млн |
Серия 2 — рост бюджета API при 2 репликах:
| суммарный CPU API | CPU на реплику | успешный RPS | p95, мс | ошибки | API CPU (сумма) | PG CPU |
| --- | --- | --- | --- | --- | --- | --- |
| 0.5 | 0.25 | 1 489.9 | 8.25 | 0 | 0.28 | 0.36 |
| 1.0 | 0.50 | 1 496.3 | 8.22 | 0 | 0.27 | 0.37 |
| 1.5 | 0.75 | 1 491.3 | 8.18 | 0 | 0.27 | 0.36 |
Трехкратный бюджет API не сдвигает пропускную способность (1 490 → 1 496 → 1 491), а лишние реплики при неизменном суммарном бюджете её снижают: каждая реплика — ещё один процесс, соединения и копия кэша, а суммарный CPU фиксирован.
Отказов в чистой серии почти нет: 13 профилей из 15 без единого отказа, в двух профилях `pool` — по 4 обрыва в момент пересоздания реплики. Прежние прогоны показывали до 26 % отказов, но это были отказы соединений **у клиента на хосте**, а не у стенда: в контроле `evidence/path-overhead/` балансировщик отдал все запросы без 5xx, логи API не содержат ошибок, а клиент внутри VM не отказал ни разу. Подтверждённых записей не потеряно: повтор с тем же ключом дубля не создаёт (см. проверку идемпотентности).
Контроль снят попарно с эталоном, чтобы дрейф серии не выдавался за эффект бюджета (`scripts/track1_controls.sh`; лимиты применены к контейнерам и проверены по `docker inspect`):
| профиль | что изменено | успешный RPS | отличие от соседнего эталона |
| --- | --- | --- | --- |
| `ctl1base` / `ctl3base` | эталон (2 реплики, PostgreSQL 0.50, LB 0.25) | 1 391.1 / 1 360.1 | −2.2 % за два профиля — масштаб дрейфа |
| `ctl2pg` | бюджет CPU PostgreSQL 0.50 → 1.00 | 1 391.6 | **+0.04 %** |
| `ctl4lb` | бюджет CPU балансировщика 0.25 → 1.00 | 1 359.8 | **−0.02 %** |
| `pool10` / `pool5` | пул соединений реплики 10 → 5 (4 реплики) | 1 399.0 / 1 299.6 | −7 % (меньший пул хуже) |
| 32 клиента вместо 8 | — | 1 284 | p95 52.8 мс вместо ≈8-9 мс (`evidence/load-32clients.txt`) |
Профили серии `db1cpu` (PostgreSQL 1.00) и `lb1cpu` (LB 1.00) показывают на 15 % и 8 % меньше, чем `r2`, но сняты позже, и разница объясняется дрейфом: тот же профиль `r2`, повторённый в конце серии (`d2`), даёт 1 389 RPS вместо 1 491 (−6.9 %). Поэтому вопрос «помогает ли бюджет БД» решают именно перемежающие профили, а не сравнение через полчаса.
Стенд дрейфует по ходу серии: таблица `messages` растёт (≈95 тыс. строк на профиль, 3.6 → 5.1 млн за серию), и эталон `r2`, снятый в начале и в конце, даёт 1 491 и 1 389 RPS (−6.9 %, ≈0.9 % на профиль); независимая оценка дрейфа по двум эталонам перемежающего контроля — 2.2 % за два профиля. Повторы одной конфигурации внутри сессии расходятся до ~2 %. Поэтому профили сравнимы только внутри одной серии и рядом по времени, а влияние каждой ручки проверяется попарно с эталоном. Качественный вывод устойчив: **три независимые серии** дали одно и то же — рост числа реплик при фиксированном бюджете не помогает (первая: +3 % на двух, −9 % на четырёх; вторая: −7 % и −8 %; третья, чистая: −3.3 % и −5.1 %).
### Где насыщение
Потолок закрытого цикла на этой машине — **≈1 300–1 550 RPS подтверждённых записей**, и ни одна ручка стенда его не двигает:
| что меняли | как проверено | результат |
| --- | --- | --- |
| число API-реплик 1 → 2 → 4 при неизменном суммарном бюджете | серия 1 | −3.3 % и −5.1 % |
| суммарный бюджет API 0.5 → 1.0 → 1.5 CPU | серия 2 | +0.1 % (плоско) |
| бюджет CPU PostgreSQL 0.50 → 1.00 | перемежающий контроль | +0.04 % |
| бюджет CPU балансировщика 0.25 → 1.00 | перемежающий контроль | −0.02 % |
| пул соединений реплики 10 → 5 | пара профилей при 4 репликах | −7 % (хуже) |
| клиент на хосте вместо клиента внутри VM | `evidence/path-overhead/` | тот же RPS (1 539 против 1 475) |
| 32 клиента вместо 8 | `evidence/load-32clients.txt` | 1 284 RPS, p95 растёт до 52.8 мс |
Измерениями исключены: **клиент** (тот же закрытый цикл по тривиальному серверу на хосте даёт 4 469 RPS без отказов), **путь «хост → проброс порта → VM»** (клиент внутри VM даёт ту же пропускную способность), **квоты CPU PostgreSQL и LB** (перемежающий контроль: ±0.05 % при лимитах, проверенных по `docker inspect`), **размер пула** (19–22 соединения из 100; меньший пул только вредит). Сами сервисы при этом недогружены: реплики вместе берут 0.24–0.31 ядра из бюджета 1.0, PostgreSQL — 0.35–0.39 из 0.50, LB — 0.10 из 0.25 (в `docker stats` 100 % = одно ядро, проверено отдельным экспериментом: `evidence/quota-semantics.txt`).
Значит упор не в бюджет и не в число процессов, а в стоимость одной записи: сообщение — это транзакция из трёх обращений к БД (claim ключа идемпотентности, вставка сообщения, запись `message_id`), плюс проверка участников чата и работа с кэшем списка чатов, и всё это на 2 vCPU. Гипотеза следующего шага: сократить путь записи до двух обращений (вставка сообщения и upsert ключа в одной транзакции, конфликт — откат и повторное чтение) и перемерить перемежающим контролем. Числа сняты на одной конфигурации одиночными прогонами закрытого цикла, поэтому это не «предельная ёмкость системы»: на другом Docker-host потолок будет иным (см. «Ограничения»).
### Подтверждённое улучшение и проверенные гипотезы
**Подтверждено (измерено до/после):** балансировщик перестал отправлять трафик неготовой реплике. `scripts/lb_readiness_check.sh` поднимает рядом с рабочими репликами третью с тем же сетевым alias, но её доступ к БД идёт через временный TCP-прокси; после остановки прокси реплика остаётся доступной по сети, её `/health/ready` отвечает 503.
| Вариант LB | запросов неготовой реплике из 40 | статус в LB | запись через LB |
| --- | --- | --- | --- |
| пассивные проверки (nginx OSS, до правки) | 20 из 40 `/health/live` и бизнес-запросы (зафиксировано в ревью) | продолжает обслуживать | 503 и 200 вперемешку |
| активные проверки (HAProxy, `httpchk /health/ready`, `inter 2s fall 2 rise 2`, `timeout check 1s`) | **0 из 40** | `DOWN` **через 2 с** (измерено) | 1 163 RPS, 0 ошибок (`evidence/lb-readiness.txt`) |
Вместе с этим убраны две связанные проблемы: прозрачный повтор POST (`proxy_next_upstream ... non_idempotent` мог повторить создание чата) заменён на `retry-on conn-failure`, а недоступная реплика убирается из ротации полностью, а не «на 3 секунды». Сценарий rolling update проходит под нагрузкой: 97 359 подтверждённых записей, 3 переходные ошибки (0.003 %), `restarts=0` (`evidence/rolling-update/after/`, где каждый шаг подтверждён сменой образа новой реплики и числом UP-слотов).
**Дефект доказан, эффект его устранения — нет.** Архитектурная ошибка унаследованного `Dockerfile` (`ARG TARGETARCH=amd64`, а классический builder платформу не подставляет → x86-64 бинарник в arm64-образе) подтверждена ELF-заголовками (`evidence/arch.txt`): `e_machine=0x3e` против `0xb7`. Но контролируемое сравнение **не подтвердило**, что именно она вызывала прежние runtime-фаталы: прогон rolling update на эмулируемом образе завершился без ошибок — 89 560 успешных запросов за 45 с, 0 ошибок, 0 ответов 5xx (`evidence/rolling-update/emulated/load.json`). Падения (`fatal error: found pointer to free object`, `sync: inconsistent mutex state`, crash-loop реплик) наблюдались в других условиях и в приложенный A/B не попали. Корректная формулировка: эмуляция x86-64 на arm64 — доказанный дефект сборки, который устранён, но его вклад в те падения не измерен.
**Проверено измерениями (перемежающий контроль, лимиты подтверждены по `docker inspect`):** ни бюджет CPU PostgreSQL (0.50 → 1.00), ни бюджет CPU балансировщика (0.25 → 1.00) не меняют пропускную способность (+0.04 % и −0.02 %), поэтому потолок закрытого цикла на этой машине задаёт не нехватка ресурсов у БД или LB. Пул соединений 10 → 5 при четырёх репликах оказался хуже на 7 % — меньший пул не улучшение, а потеря.
**Следующий шаг для измерения:** сократить число обращений к БД на одно сообщение — сейчас их три (claim ключа, вставка сообщения, запись `message_id`), нужно два (вставка сообщения + upsert ключа в той же транзакции, конфликт — через откат и повторное чтение). Гипотеза: меньше round-trip и меньше версий строк. Эффект измеряется тем же способом, что и бюджеты, — перемежающим контролем (`scripts/track1_controls.sh`: эталон → изменение → эталон), потому что собственный дрейф серии сопоставим с ожидаемым выигрышем.
| TODO | TODO | TODO | TODO |
## Ограничения и следующие шаги
- **Архитектура образа (главная находка этапа отладки).** Унаследованный `Dockerfile` содержал `ARG TARGETARCH=amd64`, а классический builder платформу не подставляет — в arm64-образ попадал x86-64 бинарник (`e_machine=0x3e` против `0xb7` у busybox базового образа; в стеке паники видно `runtime/asm_amd64.s`). Пока нагрузка была низкой, эмуляция справлялась; под нагрузкой Go runtime падал с `fatal error: found pointer to free object`, `sync: inconsistent mutex state`, `bad pointer in Go heap`, `runtime: name offset base pointer out of range` — и это выглядело как проблема приложения. Контрольный эксперимент снял подозрения с кода: тот же исходник, собранный нативно (вне Docker, против локальной БД), выдержал 90 с при 32 клиентах — 220 781 запрос, 0 ошибок, p50 12.5 мс, p95 17.5 мс, p99 22.4 мс, 2 452 успешных RPS (`evidence/native-load.txt`), тогда как контейнерный стенд через LB даёт ≈1 300–1 700 RPS. После исправления (`ARG TARGETARCH` без значения по умолчанию, кросс-сборка — явным `--build-arg`) стенд стабилен, однако строгий A/B связь с прежними падениями не подтвердил (см. «Подтверждённое улучшение»). Если вы собираете под другую платформу, задавайте `TARGETOS`/`TARGETARCH` явно.
- **Ресурсы VM.** Colima (macOS Virtualization.framework) даёт 2 vCPU и ≈1.9 GiB RAM: сборка образа была один раз убита OOM, поэтому компилятор ограничен `GOFLAGS=-p=2`, а бюджеты экспериментов трека 1 подобраны под VM (1.0 CPU суммарно на API), иначе измеряется не масштабирование, а нехватка ресурсов.
- **Измерения трека 1 не переносятся на другую машину.** Все числа получены на одной конфигурации (Docker VM: 2 vCPU, ≈1.9 GiB; хост: 18 ядер) одиночными прогонами закрытого цикла, поэтому это не «пропускная способность системы», а точки одного профиля на конкретном стенде: на другом Docker-host и потолок, и точка насыщения будут иными, а сравнивать между собой можно только профили одной серии.
- **Что означает CPU% в `docker stats`.** Проверено экспериментом: контейнер, упёртый в `--cpus 0.5` (`cpu.max = 50000 100000`), показывает 49.49 %, то есть процент считается от одного ядра и 50 % = полная квота 0.5 CPU (`evidence/quota-semantics.txt`). Прежняя оговорка отчёта о «заниженных» значениях снята: колонки читаются однозначно.
- **Проброс порта хоста не выдерживает нагрузку генератора.** `tests/load.py` ходит без keep-alive (новое TCP-соединение на запрос). Клиент на хосте получает отказы соединения от проброса порта: в контроле `evidence/path-overhead/` тот же профиль дал 26 % отказов при клиенте на хосте и 0 % при клиенте внутри VM и тот же RPS. Точечный пробник из 40 000 быстрых подключений подряд получил 38 706 `ECONNREFUSED`, а прогон на ~4 500 соединений/с оставил проброс порта (вместе с доступом к Docker-эндпоинту Colima) неработоспособным до `colima restart`. Стенд при этом не падал: в прогонах с клиентскими отказами балансировщик отдал все запросы без 5xx, а логи API не содержат ни одной ошибки (сценарии отказа, персистентности и rolling update снимались клиентом на хосте раньше и прошли с 0-3 отказами — там темп новых соединений был ниже, чем в серии трека 1). Поэтому серия трека 1 снимается клиентом внутри VM.
- **«Потолок задаёт проброс порта» — опровергнуто измерением.** Прежняя формулировка объясняла потолок ≈1 500 RPS виртуализацией и пробросом порта. Контроль с клиентом внутри VM даёт ту же пропускную способность (1 475 против 1 539 RPS, различия в пределах разброса) вообще без проброса, значит этот путь потолок не задаёт; клиент тоже не потолок — тот же закрытый цикл по тривиальному локальному серверу даёт 4 469 RPS. Нативная оценка 2 452 RPS снята другим генератором, на хосте с 18 ядрами и против локальной БД, поэтому она не изолирует причину: отличается и доступный CPU, и способ подачи нагрузки. Корректная формулировка: узкое место — внутри стенда (путь записи сообщения), а не в виртуализации.
- **Окно обнаружения отказа.** Готовность проверяется активно (`httpchk /health/ready`, период 2 с, `fall 2`, `timeout check 1s`) — измеренное время перехода реплики в `DOWN` после потери БД: **2 с** (`evidence/lb-readiness.txt`); теоретическая верхняя граница ~4 с. Между фактическим отказом и первой неудачной проверкой реплика ещё получает трафик, поэтому клиент может увидеть 503 от неё или ошибку соединения — в измеренных сценариях это единичные переходные ошибки (0–2 %), они учтены в таблицах отказа.
- **Строгая проверка «до/после» по архитектуре не удалась.** Исходный дефект сборки доказан (ELF-заголовки), но воспроизвести падения в контролируемом A/B не удалось: эмулируемый образ в коротком прогоне тоже прошёл без ошибок. Считать эффект устранения измеренным нельзя.
- **Переходные ошибки при смене состава реплик.** HAProxy не повторяет уже отправленный POST (осознанно: прозрачный повтор неидемпотентной операции запрещён контрактом), а переиспользуемые соединения к снятому контейнеру рвутся — поэтому в момент замены или масштабирования клиент может увидеть единичный 502: ≤0.25 % в сериях трека 1 и 0.003 % в rolling update. Неопределённый результат клиент повторяет сам, и для сообщений это безопасно благодаря `Idempotency-Key`.
- Один Docker-host: эксперименты показывают отказ **процесса** API, но не отказ узла. Потеря хоста, а также LB, PostgreSQL и Redis остаются единичными точками отказа; выживание узла БД не заявлено.
- PostgreSQL не реплицирована, Redis не кластеризован — при их отказе стенд недоступен, это честное учебное упрощение.
- Генератор нагрузки `tests/load.py` — closed-loop: он ограничен клиентом и страдает coordinated omission, поэтому измеренный RPS — это пропускная способность HTTP-подтверждений, а не предельная ёмкость системы. Для серьёзных выводов нужен k6/Locust или свой open-loop генератор.
- **Принятые риски (осознанно, вне объёма ЛР3).** Пароли хешируются Argon2id с 64 МиБ памяти на хеш, а ограничителя частоты нет: 4–5 одновременных регистраций на реплику с бюджетом 256 МиБ могут её выбить, а перебор паролей не throttled. Контракт делает `429` факультативным, защита вынесена в ЛР7 по карте курса; предел размера тела при этом закрыт (см. выше). Страница оператора HAProxy доступна без аутентификации, но только на loopback. `docker-compose.local.yaml` (локальная разработка из ЛР2) публикует PostgreSQL и Redis на 127.0.0.1 с синтетическим паролем — для стенда ЛР3 не используется. `X-Request-ID` принимается от клиента как есть: это нужно для сквозной корреляции, подделка значения искажает только аудит, инъекция в лог невозможна (Go запрещает переводы строк в заголовках, лог пишется JSON). `Makefile` экспортирует `-include .env` в окружение рецептов — при синтетических значениях это безопасно.
- Записи идемпотентности не удаляются фоновым процессом: истёкшие строки занимаются лениво при повторном использовании ключа, остальные ждут будущей уборки (индекс `expires_at` уже есть).
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
+2 -1
View File
@@ -1,11 +1,12 @@
# Topology worksheet, deliberately NOT a runnable stack (no application supplied).
# Implement compose.yaml or stack.yaml; do not submit this empty file as deployment.
# Service names below are logical roles, not imposed container names.
x-lab-number: 3
x-lab-number: 4
x-required-roles:
- api
- postgres
- load_balancer
- s3
# TODO: implement real images/builds, network wiring, volumes, healthchecks,
# credentials and bootstrap. Details: contracts/infrastructure.json and README.md.
services: {}
+4 -2
View File
@@ -34,7 +34,8 @@
"chat_id": "33333333-3333-4333-8333-333333333333",
"sender_id": "11111111-1111-4111-8111-111111111111",
"text": "Привет, Боб!",
"created_at": "2026-09-01T12:00:00Z"
"created_at": "2026-09-01T12:00:00Z",
"attachment_ids": []
},
"MessagePage": {
"items": [
@@ -43,7 +44,8 @@
"chat_id": "33333333-3333-4333-8333-333333333333",
"sender_id": "11111111-1111-4111-8111-111111111111",
"text": "Привет, Боб!",
"created_at": "2026-09-01T12:00:00Z"
"created_at": "2026-09-01T12:00:00Z",
"attachment_ids": []
}
],
"next_cursor": null
+11 -1
View File
@@ -1,5 +1,5 @@
{
"lab": 3,
"lab": 4,
"kind": "requirements, not runnable deployment",
"required_for_grade_3": [
{
@@ -17,6 +17,16 @@
"role": "load_balancer",
"public_entrypoint": true,
"backend_readiness": true
},
{
"role": "s3",
"choose_one": [
"MinIO",
"SeaweedFS",
"RustFS"
],
"private_bucket": true,
"persistent_volume": true
}
],
"optional_components": [
+985 -7
View File
File diff suppressed because it is too large Load Diff
+7
View File
@@ -44,3 +44,10 @@ Content-Type: application/json
### Read first page
GET {{baseUrl}}/api/v1/chats/{{chatId}}/messages?limit=50
Authorization: Bearer {{sessionToken}}
### Binary upload; HTTP file-client syntax for reading local fixture
POST {{baseUrl}}/api/v1/chats/{{chatId}}/attachments?filename=sample.png
Authorization: Bearer {{sessionToken}}
Content-Type: image/png
< ../tests/fixtures/sample.png
+3 -3
View File
@@ -1,7 +1,7 @@
{
"number": 3,
"title": "Балансировка и отказ API-реплики",
"contract_version": "1.3.0",
"number": 4,
"title": "S3-хранилище и вложения",
"contract_version": "1.4.0",
"default_base_url": "http://localhost:8080",
"grading": "3; 4 includes 3; 5 includes 4 plus one completed research track",
"scaffold_has_application": false
+9
View File
@@ -0,0 +1,9 @@
# Синтетический fixture
sample.png: RGB PNG 320×200, создан программно специально для курса, без персональных данных и EXIF. Можно свободно использовать и менять в собственных тестах; исходный публичный fixture сохраните.
- Размер: 111817 байт.
- SHA-256: `99ea7533c441f79cd630d15ce4d58d1ec4e06f6f0efb3b77a5c088305cd1bd75`.
- Обязательный thumbnail с lab5: JPEG 256×160.
Проверяющий читает SHA-256 оригинала, metadata вариантов и реальные размеры JPEG, а не только JSON-обещание сервера. Повреждённые, oversized и decompression-bomb fixtures для собственного negative suite создавайте отдельно; не храните огромные файлы в Git.
BIN
View File
Binary file not shown.

After

Width:  |  Height:  |  Size: 109 KiB

+26
View File
@@ -0,0 +1,26 @@
"""Read JPEG SOF dimensions without external libraries; not a full image decoder."""
from client import Failure, check
def jpeg_size(data):
check(data[:2]==b'\xff\xd8','thumbnail is not JPEG')
i = 2
sof = {0xc0,0xc1,0xc2,0xc3,0xc5,0xc6,0xc7,0xc9,0xca,0xcb,0xcd,0xce,0xcf}
while i < len(data):
check(data[i]==0xff,'invalid JPEG marker')
while i<len(data) and data[i]==0xff:
i += 1
check(i<len(data),'truncated JPEG marker')
marker = data[i]
i += 1
if marker in {0xd9,0xda}:
break
if marker in {0x01,0xd8} or 0xd0<=marker<=0xd7:
continue
check(i+2<=len(data),'truncated JPEG segment')
length = int.from_bytes(data[i:i+2],'big')
check(length>=2 and i+length<=len(data),'invalid JPEG segment length')
if marker in sof:
check(length>=8,'invalid JPEG SOF')
return (int.from_bytes(data[i+5:i+7],'big'),int.from_bytes(data[i+3:i+5],'big'))
i += length
raise Failure('JPEG dimensions not found')