База lab4: контракт 1.4.0 и реализация lab1–lab3
This commit is contained in:
@@ -1,4 +1,4 @@
|
||||
## Лабораторная 3
|
||||
## Лабораторная 4
|
||||
|
||||
Автор / группа: TODO
|
||||
Целевая оценка (3/4/5): TODO
|
||||
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
# Памятка преподавателю — лабораторная 3
|
||||
# Памятка преподавателю — лабораторная 4
|
||||
|
||||
## Что подготовлено
|
||||
|
||||
|
||||
@@ -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/)
|
||||
|
||||
@@ -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: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
|
||||
|
||||
@@ -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: {}
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
File diff suppressed because it is too large
Load Diff
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
Vendored
+9
@@ -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.
|
||||
Vendored
BIN
Binary file not shown.
|
After Width: | Height: | Size: 109 KiB |
@@ -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')
|
||||
Reference in New Issue
Block a user