Carry over the agent context and openspec history from lab 4
Bring the Claude Code settings, the lint hook, the opsx commands and
skills, the architecture notes, the lab 1 to lab 4 specs and the
archived lab 1 to lab 4 changes into the lab 5 skeleton, so lab 5
continues the same spec history instead of starting from scratch. The
files come from the lab 4 solution commit d2744bc.
Rewrite AGENTS.md and the openspec context and rules for lab 5: upload
answers 202 queued after the original is in a private staging prefix
and the attachment, the job and the outbox row are committed in one
transaction, a separate relay publishes the outbox to RabbitMQ with
publisher confirms, a separate worker built from the same image
consumes the queue through FastStream with a manual ack after the
result commit, PostgreSQL stays the source of truth for job states,
Out of scope moves to labs 6-7, track 1 and broker HA, and the rules
add the failure windows between PostgreSQL and the broker, the effect
key and the lease to specs and designs.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
276dbdad8a
commit
1210dd899c
@@ -0,0 +1,4 @@
|
||||
schema: spec-driven
|
||||
created: 2026-09-29
|
||||
archived: 2026-09-29
|
||||
lab: 1
|
||||
@@ -0,0 +1,177 @@
|
||||
## Context
|
||||
|
||||
См. `proposal.md` — Why. Ограничения, формирующие подход:
|
||||
|
||||
- Состояние живёт только в памяти одного процесса. Это не временное упрощение, а условие лабы: репозиторий не прячет БД, он прячет её отсутствие.
|
||||
- Публичный `tests/smoke.py` сверяет порядок истории с `sorted(key=(created_at, UUID(id).int))`. Любая неоднозначность порядка при равных отметках времени ломает проверку пагинации.
|
||||
- Проверки идут в порядке «идентификация → доступ → содержимое»: посторонний с некорректным телом обязан получить `404`, а не `400`.
|
||||
- Домен лабы 1 беден: три сущности, пять правил. По книге (с. 71) это ровно тот случай, когда весь аппарат не окупается. Он вводится сознательно как учебная цель курса и как задел на лабы 2–7, где за теми же портами встанут PostgreSQL, Redis, S3 и брокер. Цена названа в разделе «Risks».
|
||||
- Это монолит, а не набор служб: один процесс, одна точка входа, один образ. Разделение на доменные зоны — способ удержать границы внутри монолита, а не подготовка к немедленному разъезду по репозиториям.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
|
||||
- Правило зависимостей соблюдается механически: `domain/` не импортирует ничего инфраструктурного, `application/` знает только порты, адаптеры подключаются в единственной точке сборки.
|
||||
- Границы доменных зон проверяются тестом по графу импортов, а не держатся на дисциплине.
|
||||
- Порядок истории строго определён при конкурентной записи, без сортировки на чтении.
|
||||
- Замена in-memory адаптеров на адаптеры лаб 2–5 не требует правок в `domain/` и `application/`.
|
||||
- Режим блокировки хранилища и вариант конвейера запроса переключаются конфигурацией — это измерительные инструменты трека «5», а не мёртвый код.
|
||||
|
||||
**Non-Goals:**
|
||||
|
||||
- Не вводится ORM, миграции и слой представлений поверх SQL — их нечем наполнить.
|
||||
- Не вводится оптимистическая блокировка по номеру версии: конкурентная запись идёт только в append-only историю, конфликт обновления невозможен.
|
||||
- Не строится обобщённый механизм повторов и dead-letter: события лабы 1 не переживают процесс по условию.
|
||||
- Зоны не разносятся по процессам и образам: это остаётся монолитом, а разделение существует внутри него.
|
||||
|
||||
## Decisions
|
||||
|
||||
### Две доменные зоны и общий минимум
|
||||
|
||||
```
|
||||
src/messenger/
|
||||
main.py сборка приложения: вклады зон в один процесс
|
||||
gunicorn_conf.py конфигурация сервера
|
||||
identity/ domain (ошибки, события, значения, User) / application / infrastructure /
|
||||
entrypoints (роутер, провайдер DI, отображение ошибок, журнал, идентификация)
|
||||
messaging/ domain (ошибки, события, значения, ключ истории, агрегат Chat) /
|
||||
application / infrastructure (память, курсор) / config /
|
||||
entrypoints (роутеры, провайдер DI, отображение ошибок, журнал)
|
||||
shared/ domain / application / infrastructure — платформа без транспорта
|
||||
entrypoints/ — транспортная платформа: конвейер, health, актор запроса,
|
||||
механизм ответа об ошибке, транспортные настройки, платформенный провайдер
|
||||
```
|
||||
|
||||
Отдельного каталога точек входа на верхнем уровне нет: правило «общее — в `shared/`, доменное — в зону» не допускает второго места для общего кода. Транспортная платформа — общее, поэтому живёт в `shared/entrypoints/`. Сборка — ни то ни другое, поэтому лежит в `main.py` в корне пакета.
|
||||
|
||||
Правило простое: **ошибки, события и команды принадлежат зоне**. Общих доменных понятий не существует — в `shared/` лежат только их базовые типы, нужные шине, чтобы уметь их переносить.
|
||||
|
||||
Границы зон взяты по ресурсным корням API: `/api/v1/users` — одна зона, `/api/v1/chats` вместе с историей — другая. Сообщения отдельной зоной не выделены: у них нет жизненного цикла вне чата, это сущность внутри агрегата `Chat`.
|
||||
|
||||
Внутри зоны каталоги повторяют словарь книги («Порты и адаптеры», гл. 13). Порт объявляется в `application/ports.py` своей зоны, адаптеры лежат в её `infrastructure/`. Точка сборки одна — `entrypoints/api/ioc.py`, где каждая зона представлена своим провайдером.
|
||||
|
||||
`shared/` — крайняя мера: туда попадает только платформа (часы, идентификаторы, журнал, брокер) и механизм связи (шина, базовые типы сообщений). Проверка простая: ни один файл в `shared/` не упоминает ни одну зону, и это закреплено тестом.
|
||||
|
||||
Отдельно вынесены из домена коды контракта. Раньше `DomainError` нёс поля `code` и `http_status` — словарь протокола, протёкший в доменный слой. Теперь домен кидает свою ошибку (`UsernameAlreadyTaken`, `ChatNotFound`, `InvalidPageRequest`), а таблица перевода в коды контракта живёт в точке входа. Домен ничего не знает про HTTP, и это тоже проверяется тестом.
|
||||
|
||||
**Альтернатива:** плоский пакет с `routers/`, `services/`, `models/`. Отвергнута: в ней нет места, куда положить порт, и правило зависимостей нечем проверить. **Альтернатива:** отдельная зона для сообщений. Отвергнута: инвариант порядка истории держит агрегат `Chat`, и разрыв границы потребовал бы распределённой согласованности там, где её можно не заводить.
|
||||
|
||||
### Зона владеет всем своим HTTP-слоем
|
||||
|
||||
В `<зона>/entrypoints/` лежит не только роутер, но и провайдер DI, отображение доменных ошибок на коды контракта и журнал событий зоны. У `identity` там же живёт идентификация: разбор заголовка, проверка по справочнику и слоёный middleware.
|
||||
|
||||
В `entrypoints/api/` остаётся только транспортная платформа: конвейер запроса, health, механизм формирования ответа об ошибке, примитив «актор запроса» и сборка приложения. Единственный модуль платформы, знающий обе зоны, — `app.py`, и это его работа: он собирает вклады (роутеры, провайдеры, реестры ошибок, поля журнала) в одно приложение, запускаемое одним процессом.
|
||||
|
||||
Конвейер запроса не знает, кто такой пользователь: он принимает функцию-страж снаружи, а её даёт `identity`. Примитив `Actor` платформенный и опирается на транспортную ошибку `Unauthenticated`, а не на доменную, — «заголовок не предъявлен» это факт транспорта, а не предметной области.
|
||||
|
||||
Проверяется тестом: ни один модуль платформы, кроме `app.py`, не импортирует ни одну зону.
|
||||
|
||||
Изоляция транспорта держится не каталогом верхнего уровня, а слоями внутри `shared/`: ядро (`domain`, `application`, `infrastructure`) не импортирует ни FastAPI, ни Starlette, и это проверяется тестом. В лабе 5 появится второй вход — worker: он подключит ядро `shared/` и не тронет `shared/entrypoints/`, поэтому веб-фреймворк за собой не потащит.
|
||||
|
||||
По той же логике разделены настройки: платформенные (`host`, `port`, `log_level`, предел очереди событий) живут в `shared/config.py`, транспортные (`pipeline`, предел тела, таймаут) — в `shared/entrypoints/config.py`, а `storage_locking` и секрет курсора принадлежат `messaging` и лежат в её `config.py`.
|
||||
|
||||
### Связь зон: событие и проекция, а не вызов
|
||||
|
||||
`messaging` не спрашивает у `identity`, существует ли пользователь. У него есть собственный реестр участников (`MemberRegistry`), который наполняет проекция на событие `UserRegistered`. Единственное, что `messaging` заимствует у соседней зоны, — объявление этого события.
|
||||
|
||||
Проекции выполняются синхронно, до того как клиент получит ответ: иначе «зарегистрировался и сразу создал чат» превратилось бы в гонку, а контракт требует, чтобы подтверждённая запись была видна следующему чтению. Остальные подписчики — журнал активности, внешний брокер — работают через очередь и на ответ не влияют.
|
||||
|
||||
Правило проверяется тестом по графу импортов, а не только договорённостью: `identity` не смеет знать о `messaging` вовсе, `messaging` — только об объявлении события.
|
||||
|
||||
**Альтернатива:** порт `MemberDirectory`, за которым стоит адаптер поверх `identity`. Отвергнута: это скрытый синхронный вызов между зонами, который при разделении на службы превратится в сетевую зависимость. Цена выбранного варианта — дублирование идентификаторов в двух местах; в обмен зоны можно разнести, не переписывая ни строчки домена.
|
||||
|
||||
### Агрегат: чат вместе с историей
|
||||
|
||||
Граница согласованности — `Chat`: состав участников и append-only история. `Message` — сущность внутри агрегата, доступная только через него. `User` — отдельный агрегат.
|
||||
|
||||
Инварианты, которые держит `Chat`: отправитель входит в состав; пара `(created_at, id)` строго возрастает по всей истории; состав неизменен после создания.
|
||||
|
||||
**Альтернатива:** сделать `Message` самостоятельным агрегатом, а членство проверять в обработчике. Отвергнута: инвариант порядка тогда некому держать, и проверка членства расползается по обработчикам. Цена выбранного варианта — агрегат неограниченно растёт; в памяти это дёшево (взятие ссылки, не загрузка), но при переходе на PostgreSQL в лабе 2 репозиторий обязан отдавать агрегат без материализации истории. Это отмечено как точка пересмотра границы.
|
||||
|
||||
### Строго возрастающие часы вместо сортировки на чтении
|
||||
|
||||
Порт `Clock` реализуется адаптером, который выдаёт метки в UTC с микросекундной точностью и гарантирует строгое возрастание: если системные часы вернули значение, не большее предыдущего, выдаётся предыдущее плюс одна микросекунда.
|
||||
|
||||
Следствия: история хранится как append-only список, уже упорядоченный по `(created_at, id)`; keyset-чтение — срез по позиции, найденной двоичным поиском; сортировка на чтении не нужна вовсе.
|
||||
|
||||
**Альтернатива:** брать системное время как есть и вставлять с `bisect.insort` по ключу `(created_at, id)`. Отвергнута: вставка в середину — O(n) на сообщение, а при совпадении меток порядок вставки перестаёт совпадать с порядком чтения, и страница может потерять запись. Цена выбранного варианта — отметка времени может обогнать системные часы на микросекунды при всплеске записи; это фиксируется в отчёте как объявленная семантика (`contracts/README.md` прямо требует её описать).
|
||||
|
||||
### Keyset-курсор: подписанный и привязанный к запросу
|
||||
|
||||
Курсор — base64url от `<версия>.<область>.<время в микросекундах>.<id>` с усечённой подписью HMAC-SHA256. Область — `messages:<chat_id>` либо `chats:<user_id>`. Ключ подписи читается из `CURSOR_SECRET`, а при его отсутствии генерируется случайно на старте процесса.
|
||||
|
||||
Это даёт непрозрачность, обнаружение подделки и привязку к ресурсу одним механизмом: курсор от другого чата не пройдёт проверку области и даст `400`. Случайный ключ по умолчанию означает, что курсоры не переживают перезапуск — ровно как и данные.
|
||||
|
||||
**Альтернатива:** отдавать `created_at` и `id` открытым составным значением. Отвергнута: клиент начнёт на них полагаться, а подделанный курсор придётся отличать от испорченного вручную.
|
||||
|
||||
### Команды, события и две шины
|
||||
|
||||
`CommandBus` направляет команду ровно одному обработчику, ошибка всплывает к вызывающему. `EventBus` рассылает событие всем подписчикам через `asyncio.Queue` с явным пределом; исключение обработчика логируется и не мешает ни ответу клиента, ни остальным подписчикам. События собираются из агрегатов в UoW после фиксации (`.seen` → `collect_new_events`), обработчик команды их не публикует.
|
||||
|
||||
**Альтернатива:** синхронный вызов обработчиков событий прямо в обработчике команды. Отвергнута: скрытая работа удлиняет HTTP-ответ, а отказ уведомления опрокидывает подтверждённую запись.
|
||||
|
||||
### Порт EventPublisher
|
||||
|
||||
`EventPublisher` — порт с единственным адаптером `InMemoryEventPublisher`, который кладёт события в `EventBus`. Внешних сервисов в лабе 1 нет: состояние живёт только в памяти процесса, и брокер был бы таким же нарушением условия, как и база данных.
|
||||
|
||||
Порт при этом сохранён: в лабе 5 за ним встанет брокер, и ни домен, ни обработчики команд об этом не узнают. Это ровно та развязка, ради которой порт и вводится.
|
||||
|
||||
### Сторона чтения в обход агрегата
|
||||
|
||||
Запросы (`GetCurrentUser`, `ListChats`, `ReadHistory`) читают хранилище напрямую через отдельный порт и возвращают плоские структуры. Они не поднимают агрегат и не проходят через репозиторий.
|
||||
|
||||
Это лёгкая форма CQRS (гл. 12): выделен модуль «только для чтения», отдельного хранилища нет. Мотив: чтение истории — срез упорядоченного списка, и тащить ради него агрегат с инвариантами незачем. Цена — две дороги к одним данным; она оправдана тем, что сторона чтения не меняет состояние и её нечем нарушить.
|
||||
|
||||
### Конкурентность: блокировка на агрегат, переключаемая режимом
|
||||
|
||||
Приложение работает одним процессом и одним event loop; несколько воркеров Uvicorn несовместимы с общим состоянием в памяти и запрещены конфигурацией. Атомарность операции обеспечивает UoW, удерживая `asyncio.Lock` на время команды.
|
||||
|
||||
Режим задаётся `STORAGE_LOCKING`:
|
||||
|
||||
- `global` — одна блокировка на всё хранилище; операции разных чатов сериализуются;
|
||||
- `per-chat` — блокировка на агрегат (значение по умолчанию); операции в разных чатах идут параллельно.
|
||||
|
||||
Оба режима — реальные реализации одного порта, и их сравнение образует эксперимент трека «5»: гипотеза в том, что глобальная блокировка становится узким местом при росте конкуренции, а не при росте истории.
|
||||
|
||||
**Альтернатива:** положиться на то, что корутина не прерывается между `await`. Отвергнута: инвариант перестанет держаться при первом же `await` внутри критической секции, а проверка «участник → добавить сообщение» станет гонкой.
|
||||
|
||||
### Порядок проверок в точке входа
|
||||
|
||||
`401` даёт зависимость идентификации, выполняемая до валидации тела; `404` даёт проверка доступа внутри обработчика команды; `400` даёт валидация DTO и доменные ошибки. `RequestValidationError` и ошибка разбора JSON переводятся в `400 invalid_request`; неперехваченное исключение — в `500 internal_error`. Все ответы проходят через middleware, проставляющее `X-Request-Id` и пишущее строку лога без тел запросов.
|
||||
|
||||
### Конвейер запроса: один слой вместо трёх
|
||||
|
||||
Порядок действий над запросом фиксирован: `X-Request-Id` → предел размера тела → идентификация → таймаут обработки → запись в журнал. Идентификация обязана опережать разбор тела, иначе запрос без заголовка и с испорченным JSON получил бы `400` вместо `401`.
|
||||
|
||||
Реализаций две, обе живые и переключаются настройкой `PIPELINE`: `layered` — три `BaseHTTPMiddleware`, `single` — один чистый ASGI-слой. Наблюдаемое поведение API у них совпадает, что закреплено тестом, прогоняющим контрактный сценарий в обоих режимах. Выбор по умолчанию — `single`, и он обоснован измерением, а не вкусом: см. `REPORT.md`.
|
||||
|
||||
### Сервер приложений и единый журнал
|
||||
|
||||
gunicorn с ровно одним `UvicornWorker`. Несколько воркеров означали бы несколько процессов с независимой памятью: два клиента получали бы разные множества данных. Число воркеров поэтому не настройка, а константа конфигурации.
|
||||
|
||||
Логгер в приложении один — structlog за портом `Logger`. Сообщения gunicorn, uvicorn и библиотек перенаправлены в тот же поток и получают тот же формат; access-лог uvicorn заглушён, потому что запись `request.handled` уже содержит те же поля и `request_id`. Поля пишутся по белому списку — это делает утечку текста сообщений невозможной по построению, а не по внимательности автора.
|
||||
|
||||
На каждый запрос действует предел времени: при превышении клиент получает `503`, факт записывается в журнал, остальные запросы не затронуты. Предел gunicorn по времени воркера выставлен выше прикладного, чтобы сначала срабатывал аккуратный ответ, а не убийство процесса.
|
||||
|
||||
### Конфигурация и контейнер
|
||||
|
||||
Настройки читаются из окружения через `pydantic-settings`; значения по умолчанию рассчитаны на запуск без единой переменной. Образ — multi-stage на закреплённом по digest `python:3.14-slim-trixie`, зависимости ставятся из `uv.lock`, рабочий пользователь непривилегированный, `HEALTHCHECK` опрашивает `/health/live`, gunicorn запускается exec-формой и потому получает `SIGTERM` как PID 1; срок корректной остановки — 10 секунд.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- **Аппарат паттернов тяжелее домена лабы 1** → цена принята сознательно: ровно те же порты обслуживают лабы 2–7, где адаптеры меняются на PostgreSQL, Redis, S3 и брокер. В отчёте это названо прямо, а не выдано за необходимость.
|
||||
- **Реестр участников дублирует идентификаторы пользователей** → это осознанная цена разделения зон: расхождение возможно только если событие потеряно, а проекции выполняются синхронно и потому теряться не могут, пока процесс один. При переходе к нескольким процессам сюда понадобится надёжная доставка.
|
||||
- **Две реализации конвейера запроса в кодовой базе** → вторая существует как контрольная серия эксперимента и покрыта тем же контрактным тестом; если эксперимент больше не нужен, слоёная реализация удаляется одним файлом.
|
||||
- **Агрегат `Chat` растёт неограниченно** → в памяти это ссылка, а не загрузка; при переходе на БД граница агрегата пересматривается, и это зафиксировано как точка пересмотра, а не скрытый долг.
|
||||
- **Строго возрастающие часы могут обогнать системное время при всплеске записи** → расхождение ограничено микросекундами на сообщение и описано в отчёте как объявленная семантика.
|
||||
- **Один процесс и одно состояние** → горизонтального масштабирования нет и не может быть; несколько воркеров Uvicorn дали бы разные множества данных, поэтому запрещены конфигурацией и проверяются тестом.
|
||||
- **Событие, потерянное при переполнении очереди, не восстанавливается** → предел очереди явный, отбрасывание логируется; долговечность доставки появится вместе с брокером в лабе 5.
|
||||
- **Курсоры и данные не переживают перезапуск** → это требование лабы, а не дефект; демонстрируется в сценарии защиты.
|
||||
- **Измерения снимаются на одной машине, клиент и сервер делят ресурсы** → закрытый контур даёт согласованные пропуски; в отчёте указано, что измерение сравнивает две реализации между собой, а не устанавливает абсолютную пропускную способность.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
Миграции данных нет: приложение создаётся впервые, состояние пустое по определению. Откат — возврат к предыдущему образу; потеря данных при откате ожидаема и не требует отдельной процедуры.
|
||||
|
||||
Порядок выката: собрать образ из чистого clone → запустить контейнер с публикацией порта → дождаться `healthy` → прогнать `make test` → снять измерения трека «5» → заполнить `REPORT.md`.
|
||||
@@ -0,0 +1,38 @@
|
||||
## Why
|
||||
|
||||
В репозитории есть контракт и публичные проверки, но нет приложения: `make test` падает на отказе соединения. Лабораторная 1 закрывается только работающим сервисом, поэтому нужно превратить `contracts/openapi.json` в процесс и воспроизводимый контейнер. Целевая оценка — «5»: весь уровень 4 плюс завершённый трек 1 «Предел in-memory архитектуры».
|
||||
|
||||
## What Changes
|
||||
|
||||
- Появляется приложение в `src/messenger/`: обязательный API лабы 1, состояние только в памяти одного процесса, идентификация по `X-User-Id`.
|
||||
- Две доменные зоны монолита: `identity/` (пользователи) и `messaging/` (чаты и история). У каждой свои ошибки, события, команды, объекты-значения, хранилище и HTTP-фасад. В `shared/` остаются только платформа и механизм связи: базовые типы ошибки, события и команды, технические порты и шина. Коды контракта и HTTP-статусы живут в точке входа. Точка входа одна — `entrypoints/api/`.
|
||||
- Зоны не вызывают друг друга: `messaging` ведёт собственный реестр участников, наполняемый проекцией на событие `UserRegistered` зоны `identity`. Команда имеет ровно одного обработчика, событие — сколько угодно; проекции выполняются до подтверждения записи, прочие обработчики — через `asyncio.Queue`.
|
||||
- Порт `EventPublisher` с единственным адаптером — внутренней очередью в памяти. Внешних сервисов в лабе 1 нет; порт остаётся точкой расширения для лабы 5.
|
||||
- Сервер — gunicorn с одним `UvicornWorker` (несколько воркеров несовместимы с состоянием в памяти); его логи идут через тот же структурный логгер, что и логи приложения. На каждый запрос действует таймаут с предсказуемым `503`.
|
||||
- Уровень «4»: собственные тесты одной командой, конкурентный тест 100 сообщений от 10 клиентов, non-root контейнер с закреплёнными версиями, SIGTERM ≤10 с, healthcheck, логи без текста сообщений.
|
||||
- Трек «5»: повторяемый эксперимент 3 размера истории × 3 уровня конкуренции, замеры throughput / p95 / p99 / RSS; проверены две гипотезы об узком месте, сравнение «до/после» приложено для каждой.
|
||||
- Заполняются `REPORT.md` и `evidence/`; в `Makefile` добавляются цели запуска, тестов и измерений, существующие цели не меняются.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `lab1-messenger-identity`: регистрация пользователя, уникальность `username`, идентификация запроса по `X-User-Id` и её отказы.
|
||||
- `lab1-messenger-chats`: создание чата с явным списком участников, членство как граница доступа, список чатов с keyset-пагинацией.
|
||||
- `lab1-messenger-history`: отправка сообщения с выводом отправителя из идентификации, порядок `(created_at, id)`, keyset-курсор, привязанный к чату.
|
||||
- `lab1-service-operability`: health-пробы, `X-Request-Id`, единый формат ошибки, таймаут запроса, поведение при SIGTERM, единый журнал всех сообщений процесса, контейнерная поставка.
|
||||
- `lab1-event-publication`: регистрация доменных событий, доставка проекциям и подписчикам внутренней шиной, изоляция доменных зон друг от друга.
|
||||
- `lab1-inmemory-capacity`: наблюдаемый предел in-memory хранения — что измеряется, при каких условиях и что считается подтверждённым улучшением.
|
||||
|
||||
### Modified Capabilities
|
||||
<!-- нет: спеки создаются впервые -->
|
||||
|
||||
## Impact
|
||||
|
||||
- Новое: `src/messenger/{shared,identity,messaging,entrypoints}/**`, `student-tests/**`, `pyproject.toml`, `uv.lock`, `Dockerfile`, `scripts/bench.py`.
|
||||
- Правится: `REPORT.md`, `evidence/**`, `Makefile` (только новые цели), `.gitignore`.
|
||||
- Зависимости: `fastapi`, `uvicorn`, `gunicorn`, `pydantic`, `pydantic-settings`, `dishka`, `structlog`, `pytest`, `pytest-asyncio`, `ruff`, `ty`.
|
||||
- Не затрагиваются: `contracts/**`, `tests/**`, `README.md`, `COURSE.md`, `CONTRIBUTING.md` — контракт и публичные проверки остаются как есть.
|
||||
|
||||
## Non-goals
|
||||
|
||||
Из Out of scope не появляется ничего: PostgreSQL, Redis и файлы состояния на пути данных, Bearer-сессии и пароли (лаба 2), несколько реплик, балансировщик и `Idempotency-Key` (лаба 3), вложения и S3 (лаба 4), worker и обработка изображений (лаба 5), OTel и Grafana (лаба 6), TLS и Argon2id (лаба 7). Web UI, WebSocket, редактирование и удаление сообщений, изменение состава участников и поиск пользователей не реализуются.
|
||||
+102
@@ -0,0 +1,102 @@
|
||||
## Purpose
|
||||
|
||||
Определяет, как зоны предметной области узнают о произошедшем, не вызывая друг друга напрямую: модель регистрирует факт, шина разводит его по обработчикам. Транспорт доставки заменяем, и его отказ не влияет на обязательный путь данных.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Побочные эффекты выполняются через события
|
||||
|
||||
Побочная работа, не входящая в границу согласованности операции, SHALL выполняться обработчиками событий, а не внутри обработчика команды. Событие SHALL регистрироваться моделью как факт о произошедшем и SHALL публиковаться только после успешного завершения операции, породившей его.
|
||||
|
||||
#### Scenario: Успешная операция порождает событие
|
||||
|
||||
- **WHEN** сообщение успешно сохранено и клиент получил `201`
|
||||
- **THEN** зарегистрировано событие об отправке сообщения, доступное обработчикам
|
||||
|
||||
#### Scenario: Отклонённая операция событий не порождает
|
||||
|
||||
- **WHEN** отправка сообщения отклонена с `400` или `404`
|
||||
- **THEN** ни одно событие об отправке не публикуется
|
||||
|
||||
#### Scenario: Событие получают все подписчики
|
||||
|
||||
- **WHEN** на один тип события подписано несколько обработчиков
|
||||
- **THEN** событие доставляется каждому из них
|
||||
|
||||
### Requirement: Отказ обработчика события не влияет на ответ клиента
|
||||
|
||||
Исключение в обработчике события SHALL быть залогировано и SHALL NOT менять код ответа уже подтверждённой операции. Отказ одного обработчика SHALL NOT мешать остальным обработчикам того же события.
|
||||
|
||||
#### Scenario: Обработчик падает после подтверждения
|
||||
|
||||
- **WHEN** обработчик события завершается исключением после того, как клиент получил `201`
|
||||
- **THEN** ответ клиента остаётся `201`
|
||||
- **AND** факт отказа виден в логах с идентификатором запроса
|
||||
|
||||
#### Scenario: Один обработчик не блокирует остальные
|
||||
|
||||
- **WHEN** первый из двух обработчиков события завершается исключением
|
||||
- **THEN** второй обработчик всё равно вызывается
|
||||
|
||||
### Requirement: Публикация событий не удлиняет обязательный путь
|
||||
|
||||
Доставка событий обработчикам SHALL быть развязана с обработкой HTTP-запроса: публикация SHALL завершаться, не дожидаясь работы обработчиков. Очередь публикации SHALL иметь явный предел; при его достижении событие SHALL отбрасываться с записью в лог, а обязательный путь данных SHALL продолжать работать.
|
||||
|
||||
#### Scenario: Ответ не ждёт обработчиков
|
||||
|
||||
- **WHEN** обработчик события выполняется заметно дольше, чем обработка запроса
|
||||
- **THEN** клиент получает ответ, не дожидаясь завершения обработчика
|
||||
|
||||
#### Scenario: Очередь переполнена
|
||||
|
||||
- **WHEN** события публикуются быстрее, чем разбираются, и очередь достигла предела
|
||||
- **THEN** новые события отбрасываются с записью в лог
|
||||
- **AND** запись сообщений продолжает подтверждаться кодом `201`
|
||||
|
||||
### Requirement: Доставка событий не требует внешних сервисов
|
||||
|
||||
Публикация событий SHALL выполняться через порт, реализованный внутренней очередью в памяти процесса. Сервис SHALL NOT зависеть от внешнего брокера, базы данных или иного сетевого сервиса для работы обязательного API.
|
||||
|
||||
#### Scenario: Сервис работает без единого внешнего сервиса
|
||||
|
||||
- **WHEN** сервис запущен и ни один внешний сервис не поднят
|
||||
- **THEN** весь обязательный API работает, а события доставляются внутренней очередью
|
||||
|
||||
#### Scenario: Публикация скрыта за портом
|
||||
|
||||
- **WHEN** проверяется слой приложения
|
||||
- **THEN** он обращается к публикации только через порт и не знает её реализации
|
||||
|
||||
### Requirement: Опубликованное событие не раскрывает содержимого сообщений
|
||||
|
||||
Полезная нагрузка события SHALL содержать только идентификаторы и метаданные. Текст сообщений, `display_name` и любые пользовательские данные SHALL NOT попадать ни в тело события, ни в журнал.
|
||||
|
||||
#### Scenario: Событие об отправке сообщения без текста
|
||||
|
||||
- **WHEN** опубликовано событие об отправке сообщения
|
||||
- **THEN** его тело содержит идентификаторы сообщения, чата и отправителя и отметку времени
|
||||
- **AND** не содержит текста сообщения
|
||||
|
||||
### Requirement: Доменные зоны связаны только событиями
|
||||
|
||||
Зона «чаты и сообщения» SHALL NOT вызывать зону «пользователи» напрямую. Сведения о существующих участниках SHALL поддерживаться собственной проекцией зоны, наполняемой событием о регистрации пользователя. Проекция SHALL обновляться до того, как клиент получит подтверждение операции, породившей событие.
|
||||
|
||||
#### Scenario: Регистрация видна чатам сразу
|
||||
|
||||
- **WHEN** пользователь зарегистрирован и немедленно создаёт чат со своим участием
|
||||
- **THEN** чат создаётся успешно, потому что проекция участников уже знает этот идентификатор
|
||||
|
||||
#### Scenario: Неизвестный зоне участник отклоняется
|
||||
|
||||
- **WHEN** в состав чата передан идентификатор, о регистрации которого зона не получала события
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Зона пользователей не знает о чатах
|
||||
|
||||
- **WHEN** проверяется список зависимостей модулей зоны «пользователи»
|
||||
- **THEN** среди них нет ни одного модуля зоны «чаты и сообщения»
|
||||
|
||||
#### Scenario: Обратная связь идёт только через контракт события
|
||||
|
||||
- **WHEN** проверяется список зависимостей модулей зоны «чаты и сообщения»
|
||||
- **THEN** единственная заимствованная у зоны «пользователи» единица — объявление события о регистрации
|
||||
+60
@@ -0,0 +1,60 @@
|
||||
## Purpose
|
||||
|
||||
Определяет трек «5» — предел in-memory архитектуры: что измеряется, при каких условиях измерение считается повторяемым и что считается подтверждённым улучшением, а что остаётся гипотезой.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Повторяемая методика измерения
|
||||
|
||||
Эксперимент SHALL выполняться одной командой и SHALL покрывать не менее трёх размеров истории и не менее трёх уровней конкуренции. Каждый прогон SHALL фиксировать длительность, прогрев, уровень конкуренции, размер набора данных, успешные RPS, долю ошибок, p50/p95/p99 задержки и RSS процесса. Результаты SHALL сохраняться машиночитаемым файлом без учётных данных и пользовательских данных.
|
||||
|
||||
#### Scenario: Матрица прогонов выполнена
|
||||
|
||||
- **WHEN** запущен сценарий измерения предела in-memory
|
||||
- **THEN** выполняются прогоны для всех сочетаний трёх размеров истории и трёх уровней конкуренции
|
||||
- **AND** результат каждого прогона содержит успешные RPS, p50/p95/p99, долю ошибок и RSS
|
||||
|
||||
#### Scenario: Прогон воспроизводим
|
||||
|
||||
- **WHEN** сценарий запущен повторно с теми же параметрами и теми же ресурсными лимитами
|
||||
- **THEN** сохранённый отчёт содержит версии runtime и образа, лимиты CPU и памяти, длительность и прогрев, позволяющие повторить измерение
|
||||
|
||||
#### Scenario: Отчёт не содержит чувствительных данных
|
||||
|
||||
- **WHEN** сохранён файл результатов
|
||||
- **THEN** он не содержит текстов сообщений, учётных данных и идентификаторов реальных людей
|
||||
|
||||
### Requirement: Наблюдаемый предел хранения в памяти
|
||||
|
||||
Сервис SHALL позволять измерить стоимость хранения одного сообщения в памяти. Эксперимент SHALL показать зависимость RSS от размера истории и SHALL давать оценку числа сообщений, при котором процесс исчерпает заданный лимит памяти.
|
||||
|
||||
#### Scenario: Рост RSS измерен
|
||||
|
||||
- **WHEN** история чата последовательно доводится до трёх заданных размеров
|
||||
- **THEN** для каждого размера зафиксирован RSS процесса
|
||||
- **AND** из измерений выводится средняя стоимость одного сообщения в байтах
|
||||
|
||||
#### Scenario: Предел объяснён
|
||||
|
||||
- **WHEN** известны стоимость сообщения и лимит памяти контейнера
|
||||
- **THEN** отчёт приводит оценку предельного числа сообщений и называет допущения этой оценки
|
||||
|
||||
### Requirement: Узкое место названо и подтверждено изменением
|
||||
|
||||
Отчёт SHALL называть узкое место, выявленное измерениями, и SHALL описывать ровно одно внесённое изменение, направленное на него. Сравнение «до» и «после» SHALL выполняться при одинаковых ресурсных лимитах, одинаковом профиле нагрузки и одинаковом размере набора данных. Улучшение SHALL считаться подтверждённым только при наблюдаемом изменении метрик; необоснованные измерениями выводы SHALL быть помечены как гипотезы.
|
||||
|
||||
#### Scenario: Сравнение до и после
|
||||
|
||||
- **WHEN** режим работы переключён на изменённую реализацию и прогон повторён с теми же параметрами
|
||||
- **THEN** отчёт содержит обе серии измерений и разницу по throughput и p95/p99
|
||||
|
||||
#### Scenario: Улучшение не подтвердилось
|
||||
|
||||
- **WHEN** после изменения метрики не улучшились или ухудшились
|
||||
- **THEN** отчёт фиксирует это как наблюдение, а не как успех
|
||||
- **AND** объясняет, какое допущение гипотезы не подтвердилось
|
||||
|
||||
#### Scenario: Границы эксперимента названы
|
||||
|
||||
- **WHEN** сформулирован вывод об узком месте
|
||||
- **THEN** отчёт называет, что измерение не доказывает: закрытый контур создаёт согласованные пропуски, клиент и сервер делят одну машину, единственный процесс не даёт отказоустойчивости
|
||||
+85
@@ -0,0 +1,85 @@
|
||||
## Purpose
|
||||
|
||||
Определяет чат как границу доступа: кто попадает в состав участников, кто видит чат в списке и что происходит с посторонним. Состав участников задаётся при создании и в обязательном API лабы 1 не меняется.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Создание чата
|
||||
|
||||
Сервис SHALL принимать `POST /api/v1/chats` от идентифицированного пользователя с телом `{"title":..., "member_ids":[...]}` и возвращать `201` с объектом `Chat`. `title` SHALL содержать от 1 до 100 code points и не состоять только из пробельных символов. `member_ids` SHALL содержать от 1 до 100 уникальных идентификаторов существующих пользователей и SHALL включать вызывающего. Чат SHALL создаваться атомарно: при любой ошибке валидации он не создаётся вовсе.
|
||||
|
||||
#### Scenario: Чат создан
|
||||
|
||||
- **WHEN** участник отправляет `POST /api/v1/chats` с корректным `title` и списком из своего и чужого идентификаторов
|
||||
- **THEN** ответ `201`, тело соответствует схеме `Chat`, `member_ids` совпадает с запрошенным составом
|
||||
- **AND** `id` и `created_at` назначены сервером
|
||||
|
||||
#### Scenario: Вызывающий не входит в состав
|
||||
|
||||
- **WHEN** `member_ids` не содержит идентификатора вызывающего
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Состав содержит дубликаты
|
||||
|
||||
- **WHEN** `member_ids` содержит один и тот же идентификатор дважды
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Состав содержит неизвестного пользователя
|
||||
|
||||
- **WHEN** `member_ids` содержит идентификатор, которому не соответствует ни один пользователь
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
- **AND** чат не создаётся
|
||||
|
||||
#### Scenario: Запрос без идентификации
|
||||
|
||||
- **WHEN** `POST /api/v1/chats` приходит без действительного `X-User-Id`
|
||||
- **THEN** ответ `401` с кодом `unauthorized`
|
||||
|
||||
### Requirement: Членство как граница доступа
|
||||
|
||||
Чат SHALL быть доступен только своим участникам. Посторонний пользователь SHALL получать `404` с кодом `not_found` — тот же ответ, что и для несуществующего чата. Сервис SHALL NOT использовать `403` и SHALL NOT раскрывать факт существования чужого чата ни кодом ответа, ни текстом сообщения.
|
||||
|
||||
#### Scenario: Участник читает чат
|
||||
|
||||
- **WHEN** участник запрашивает `GET /api/v1/chats/{chat_id}` своего чата
|
||||
- **THEN** ответ `200` с объектом `Chat`
|
||||
|
||||
#### Scenario: Посторонний читает чужой чат
|
||||
|
||||
- **WHEN** пользователь, не входящий в состав, запрашивает `GET /api/v1/chats/{chat_id}`
|
||||
- **THEN** ответ `404` с кодом `not_found`
|
||||
|
||||
#### Scenario: Запрос несуществующего чата
|
||||
|
||||
- **WHEN** запрашивается `GET /api/v1/chats/{chat_id}` с UUID, которому не соответствует ни один чат
|
||||
- **THEN** ответ `404` с кодом `not_found`, неотличимый от ответа на чужой чат
|
||||
|
||||
#### Scenario: Идентификатор чата не является UUID
|
||||
|
||||
- **WHEN** `chat_id` в пути не является UUID
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
### Requirement: Список чатов пользователя
|
||||
|
||||
Сервис SHALL отдавать по `GET /api/v1/chats` страницу `{"items":[...],"next_cursor":...}` с чатами, в которых состоит вызывающий, упорядоченными по `(created_at, id)` по возрастанию. Параметр `limit` SHALL быть целым в диапазоне 1–100 со значением по умолчанию 50. Список SHALL NOT содержать чатов, недоступных вызывающему.
|
||||
|
||||
#### Scenario: Участник видит свой чат
|
||||
|
||||
- **WHEN** участник запрашивает `GET /api/v1/chats?limit=100`
|
||||
- **THEN** ответ `200`, и его чат присутствует в `items`
|
||||
|
||||
#### Scenario: Посторонний не видит чужой чат
|
||||
|
||||
- **WHEN** пользователь, не входящий в состав, запрашивает `GET /api/v1/chats?limit=100`
|
||||
- **THEN** ответ `200`, и этого чата в `items` нет
|
||||
|
||||
#### Scenario: Limit вне допустимого диапазона
|
||||
|
||||
- **WHEN** запрос содержит `limit=0`, `limit=101` или нечисловое значение
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Обход списка курсором
|
||||
|
||||
- **WHEN** пользователь состоит в нескольких чатах и запрашивает страницы по одному элементу, передавая `next_cursor` предыдущей страницы
|
||||
- **THEN** страницы идут в порядке `(created_at, id)` по возрастанию, ни один чат не повторяется и не пропускается
|
||||
- **AND** `next_cursor` последней страницы равен `null`
|
||||
+106
@@ -0,0 +1,106 @@
|
||||
## Purpose
|
||||
|
||||
Определяет отправку сообщений и чтение истории чата: кто считается отправителем, в каком порядке лежат сообщения и какие гарантии даёт keyset-курсор при обходе истории.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Отправка сообщения
|
||||
|
||||
Сервис SHALL принимать `POST /api/v1/chats/{chat_id}/messages` от участника чата с телом `{"text":...}` и возвращать `201` с объектом `Message`. Отправитель SHALL выводиться из предъявленной идентификации; поле `sender_id` в теле запроса SHALL NOT приниматься. `text` SHALL содержать от 1 до 4000 Unicode code points и SHALL NOT состоять только из пробельных символов. `id` и `created_at` SHALL назначаться сервером.
|
||||
|
||||
#### Scenario: Сообщение отправлено
|
||||
|
||||
- **WHEN** участник отправляет `{"text":"Привет, мир 👋"}` в свой чат
|
||||
- **THEN** ответ `201`, тело соответствует схеме `Message`
|
||||
- **AND** `sender_id` равен идентификатору вызывающего, `chat_id` равен чату из пути, `text` побайтово совпадает с отправленным
|
||||
|
||||
#### Scenario: Отправитель не берётся из тела запроса
|
||||
|
||||
- **WHEN** тело запроса содержит поле `sender_id`
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Пустой или пробельный текст
|
||||
|
||||
- **WHEN** тело содержит `{"text":""}` или `{"text":" "}`
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Текст длиннее предела
|
||||
|
||||
- **WHEN** `text` содержит более 4000 Unicode code points
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
- **AND** длина считается в code points, а не в байтах UTF-8
|
||||
|
||||
#### Scenario: Посторонний пишет в чужой чат
|
||||
|
||||
- **WHEN** пользователь, не входящий в состав чата, отправляет корректное сообщение
|
||||
- **THEN** ответ `404` с кодом `not_found`
|
||||
- **AND** сообщение не сохраняется
|
||||
|
||||
#### Scenario: Доступ проверяется раньше содержимого
|
||||
|
||||
- **WHEN** посторонний отправляет в чужой чат тело, нарушающее схему
|
||||
- **THEN** ответ `404`, а не `400`
|
||||
|
||||
### Requirement: Порядок истории
|
||||
|
||||
История чата SHALL быть упорядочена по паре `(created_at, id)` по возрастанию. Время SHALL назначаться сервером в формате RFC 3339 UTC с суффиксом `Z`. Сервис SHALL гарантировать, что пара `(created_at, id)` строго возрастает для последовательно принятых сообщений, в том числе при конкурентных вставках, — иначе обход истории теряет или дублирует записи.
|
||||
|
||||
#### Scenario: Сообщения возвращаются в порядке приёма
|
||||
|
||||
- **WHEN** в чат последовательно отправлены два сообщения от разных участников
|
||||
- **THEN** `GET /api/v1/chats/{chat_id}/messages` возвращает их в порядке отправки
|
||||
|
||||
#### Scenario: Конкурентная запись не ломает порядок
|
||||
|
||||
- **WHEN** 10 клиентов параллельно отправляют по 10 сообщений в один чат
|
||||
- **THEN** история содержит ровно 100 сообщений с попарно различными `id`
|
||||
- **AND** порядок `(created_at, id)` строго возрастает по всей истории
|
||||
|
||||
### Requirement: Чтение истории keyset-курсором
|
||||
|
||||
Сервис SHALL отдавать по `GET /api/v1/chats/{chat_id}/messages` страницу `{"items":[...],"next_cursor":...}`. Параметр `limit` SHALL быть целым в диапазоне 1–100 со значением по умолчанию 50. `next_cursor` SHALL быть непрозрачной для клиента строкой либо `null`, если на момент чтения следующей записи нет. Курсор SHALL быть привязан к чату: курсор, выданный для другого чата, SHALL приводить к `400`. Обход неизменной истории SHALL NOT повторять и SHALL NOT пропускать записи; `limit` разрешается менять между страницами.
|
||||
|
||||
#### Scenario: Первая страница отдаёт курсор
|
||||
|
||||
- **WHEN** в чате два сообщения и запрошено `?limit=1`
|
||||
- **THEN** ответ содержит один элемент и непустой `next_cursor`
|
||||
|
||||
#### Scenario: Последняя страница закрывает историю
|
||||
|
||||
- **WHEN** запрошена вторая страница с курсором предыдущей и `limit=1`
|
||||
- **THEN** ответ содержит оставшийся элемент и `next_cursor` равный `null`
|
||||
- **AND** элемент первой страницы не повторяется
|
||||
|
||||
#### Scenario: Курсор не привязан к читателю
|
||||
|
||||
- **WHEN** курсор, выданный одному участнику чата, предъявляет другой участник того же чата
|
||||
- **THEN** страница отдаётся на общих основаниях
|
||||
|
||||
#### Scenario: Курсор от другого чата
|
||||
|
||||
- **WHEN** курсор, выданный для одного чата, предъявлен при чтении другого чата
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Испорченный или подделанный курсор
|
||||
|
||||
- **WHEN** значение `cursor` не является ранее выданным сервером курсором
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Limit вне допустимого диапазона
|
||||
|
||||
- **WHEN** запрос содержит `limit=0` или `limit=101`
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Посторонний читает чужую историю
|
||||
|
||||
- **WHEN** пользователь, не входящий в состав чата, запрашивает его историю
|
||||
- **THEN** ответ `404` с кодом `not_found`
|
||||
|
||||
### Requirement: Подтверждённое сообщение видно следующему чтению
|
||||
|
||||
Сообщение, на которое выдан ответ `201`, SHALL быть видно любому последующему чтению истории этого чата. Кэширование допускается, но SHALL NOT возвращать историю, устаревшую относительно успешной записи.
|
||||
|
||||
#### Scenario: Запись видна сразу после подтверждения
|
||||
|
||||
- **WHEN** участник получил `201` на отправку сообщения и немедленно читает историю
|
||||
- **THEN** отправленное сообщение присутствует в ответе
|
||||
+84
@@ -0,0 +1,84 @@
|
||||
## Purpose
|
||||
|
||||
Определяет, как пользователь появляется в системе и как сервер узнаёт, от чьего имени пришёл запрос. В лабе 1 идентификация учебная и никого не аутентифицирует: любой клиент может выдать себя за другого, предъявив чужой идентификатор.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Регистрация пользователя
|
||||
|
||||
Сервис SHALL принимать `POST /api/v1/users` без идентификации и возвращать `201` с объектом `User`, содержащим назначенные сервером `id` и `created_at`. Тело запроса SHALL содержать ровно поля `username` и `display_name`. `username` SHALL соответствовать `^[a-z0-9_]{3,32}$` и быть уникальным, `display_name` SHALL содержать от 1 до 100 Unicode code points и не состоять только из пробельных символов. Ответ SHALL NOT содержать полей, отсутствующих в схеме `User`.
|
||||
|
||||
#### Scenario: Пользователь создан
|
||||
|
||||
- **WHEN** приходит `POST /api/v1/users` с телом `{"username":"alice_01","display_name":"Алиса"}`
|
||||
- **THEN** ответ `201`, тело соответствует схеме `User`, `username` и `display_name` совпадают с запросом
|
||||
- **AND** `id` — UUID, назначенный сервером, `created_at` — RFC 3339 UTC с суффиксом `Z`
|
||||
|
||||
#### Scenario: Username занят
|
||||
|
||||
- **WHEN** приходит `POST /api/v1/users` с `username`, уже принадлежащим другому пользователю
|
||||
- **THEN** ответ `409` с телом ошибки и кодом `conflict`
|
||||
|
||||
#### Scenario: Username нарушает формат
|
||||
|
||||
- **WHEN** `username` содержит заглавные буквы, дефис, пробел или имеет длину вне 3–32 символов
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Display_name пуст или состоит из пробелов
|
||||
|
||||
- **WHEN** `display_name` равен `""`, `" "` или длиннее 100 code points
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Тело запроса нарушает схему
|
||||
|
||||
- **WHEN** тело содержит лишнее поле, неверный тип поля, не содержит обязательного поля или не является корректным JSON
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
- **AND** сообщение ошибки не содержит stack trace и внутренних деталей реализации
|
||||
|
||||
#### Scenario: Регистрация не требует идентификации
|
||||
|
||||
- **WHEN** `POST /api/v1/users` приходит без заголовка `X-User-Id`
|
||||
- **THEN** запрос обрабатывается на общих основаниях, ответ не равен `401`
|
||||
|
||||
### Requirement: Идентификация запроса заголовком X-User-Id
|
||||
|
||||
Защищённые endpoint SHALL требовать заголовок `X-User-Id` со значением идентификатора существующего пользователя. Отсутствующий, синтаксически неверный и неизвестный идентификатор SHALL приводить к `401` с кодом `unauthorized`. Проверка идентификации SHALL выполняться до проверки доступа к конкретному ресурсу и до содержательной проверки тела запроса.
|
||||
|
||||
#### Scenario: Заголовок отсутствует
|
||||
|
||||
- **WHEN** приходит `GET /api/v1/users/me` без `X-User-Id`
|
||||
- **THEN** ответ `401` с кодом `unauthorized`
|
||||
|
||||
#### Scenario: Идентификатор неизвестен системе
|
||||
|
||||
- **WHEN** `X-User-Id` содержит синтаксически корректный UUID, которому не соответствует ни один пользователь
|
||||
- **THEN** ответ `401` с кодом `unauthorized`
|
||||
- **AND** ответ не сообщает, существовал ли такой пользователь когда-либо
|
||||
|
||||
#### Scenario: Идентификатор не является UUID
|
||||
|
||||
- **WHEN** `X-User-Id` содержит произвольную строку, пустое значение или несколько значений
|
||||
- **THEN** ответ `401` с кодом `unauthorized`
|
||||
|
||||
#### Scenario: Идентификация проверяется раньше тела запроса
|
||||
|
||||
- **WHEN** приходит запрос без `X-User-Id` и с телом, нарушающим схему
|
||||
- **THEN** ответ `401`, а не `400`
|
||||
|
||||
### Requirement: Чтение текущего пользователя
|
||||
|
||||
Сервис SHALL отдавать по `GET /api/v1/users/me` объект `User`, соответствующий предъявленной идентификации, в том же виде, в каком он был возвращён при регистрации.
|
||||
|
||||
#### Scenario: Текущий пользователь возвращён
|
||||
|
||||
- **WHEN** приходит `GET /api/v1/users/me` с `X-User-Id` существующего пользователя
|
||||
- **THEN** ответ `200`, тело соответствует схеме `User` и совпадает с телом ответа его регистрации
|
||||
|
||||
### Requirement: Состояние пользователей не переживает перезапуск
|
||||
|
||||
Список пользователей SHALL храниться только в памяти процесса. После перезапуска процесса ранее выданные идентификаторы SHALL перестать быть действительными.
|
||||
|
||||
#### Scenario: Идентификатор после перезапуска недействителен
|
||||
|
||||
- **WHEN** процесс перезапущен и приходит запрос с `X-User-Id`, выданным до перезапуска
|
||||
- **THEN** ответ `401` с кодом `unauthorized`
|
||||
+164
@@ -0,0 +1,164 @@
|
||||
## Purpose
|
||||
|
||||
Определяет наблюдаемое поведение сервиса как эксплуатируемого процесса: пробы жизни и готовности, сквозной идентификатор запроса, единый формат ошибок, реакция на сигнал остановки и требования к контейнерной поставке.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Пробы жизни и готовности
|
||||
|
||||
Сервис SHALL отвечать на `GET /health/live` кодом `200` с телом `{"status":"ok"}`, проверяя только жизнь процесса. Сервис SHALL отвечать на `GET /health/ready` кодом `200` с тем же телом, если он способен обслуживать обязательный синхронный путь, и кодом `503` с телом ошибки в общем формате в противном случае. Пробы SHALL NOT требовать идентификации. Недоступность опциональных зависимостей SHALL NOT переводить готовность в `503`.
|
||||
|
||||
#### Scenario: Проба жизни отвечает без идентификации
|
||||
|
||||
- **WHEN** приходит `GET /health/live` без заголовков идентификации
|
||||
- **THEN** ответ `200` с телом `{"status":"ok"}`
|
||||
|
||||
#### Scenario: Готовность подтверждена
|
||||
|
||||
- **WHEN** приходит `GET /health/ready` на полностью запущенном процессе
|
||||
- **THEN** ответ `200` с телом `{"status":"ok"}`
|
||||
|
||||
#### Scenario: Готовность не зависит от внешних сервисов
|
||||
|
||||
- **WHEN** проверяется готовность сервиса
|
||||
- **THEN** она определяется только состоянием самого процесса, поскольку внешних зависимостей нет
|
||||
|
||||
#### Scenario: Сервис остановлен
|
||||
|
||||
- **WHEN** процесс получил сигнал остановки и перестал принимать новую работу
|
||||
- **THEN** `GET /health/ready` отвечает `503` с кодом `unavailable` либо соединение не устанавливается
|
||||
|
||||
### Requirement: Сквозной идентификатор запроса
|
||||
|
||||
Каждый ответ сервиса, включая ответы проб и ответы об ошибках, SHALL содержать непустой заголовок `X-Request-Id`. Если запрос принёс собственный `X-Request-Id`, сервис SHALL использовать его значение, иначе SHALL сгенерировать новое.
|
||||
|
||||
#### Scenario: Идентификатор присутствует в любом ответе
|
||||
|
||||
- **WHEN** выполняется любой запрос к сервису, успешный или ошибочный
|
||||
- **THEN** ответ содержит непустой `X-Request-Id`
|
||||
|
||||
#### Scenario: Клиентский идентификатор сохраняется
|
||||
|
||||
- **WHEN** запрос содержит `X-Request-Id` с непустым значением
|
||||
- **THEN** ответ содержит то же значение
|
||||
|
||||
### Requirement: Единый формат ошибки
|
||||
|
||||
Ответ с кодом `4xx` или `5xx` SHALL иметь `Content-Type: application/json` и тело `{"error":{"code":...,"message":...,"request_id":...}}` без каких-либо дополнительных полей. `code` SHALL принимать значение из перечисления контракта, `request_id` SHALL совпадать со значением заголовка `X-Request-Id`. `message` SHALL быть непустым и SHALL NOT содержать stack trace, SQL, учётных данных, внутренних путей и сведений о существовании чужих объектов.
|
||||
|
||||
#### Scenario: Тело ошибки соответствует схеме
|
||||
|
||||
- **WHEN** запрос завершается ошибкой любого класса
|
||||
- **THEN** тело ответа соответствует схеме `Error` контракта
|
||||
- **AND** `request_id` в теле совпадает с заголовком `X-Request-Id`
|
||||
|
||||
#### Scenario: Необработанное исключение
|
||||
|
||||
- **WHEN** обработка запроса завершается непредвиденным исключением
|
||||
- **THEN** ответ `500` с кодом `internal_error` и телом в общем формате
|
||||
- **AND** тело не раскрывает внутренних деталей
|
||||
|
||||
#### Scenario: Неподдерживаемый метод или несуществующий путь
|
||||
|
||||
- **WHEN** запрашивается несуществующий путь или неподдерживаемый метод существующего пути
|
||||
- **THEN** ответ имеет тело в общем формате ошибки с непустым `X-Request-Id`
|
||||
|
||||
### Requirement: Корректное завершение по сигналу
|
||||
|
||||
По получении `SIGTERM` сервис SHALL перестать принимать новые соединения, дождаться завершения принятых запросов и завершить процесс не более чем за 10 секунд. Процесс сервера SHALL быть основным процессом контейнера и SHALL получать сигналы напрямую.
|
||||
|
||||
#### Scenario: Остановка укладывается в срок
|
||||
|
||||
- **WHEN** запущенному контейнеру послан `SIGTERM`
|
||||
- **THEN** процесс завершается не позднее чем через 10 секунд
|
||||
- **AND** код завершения соответствует штатной остановке, а не убийству по таймауту
|
||||
|
||||
#### Scenario: Принятый запрос дорабатывается
|
||||
|
||||
- **WHEN** `SIGTERM` приходит во время обработки принятого запроса
|
||||
- **THEN** этот запрос получает ответ до завершения процесса
|
||||
|
||||
### Requirement: Логи без содержимого сообщений
|
||||
|
||||
Сервис SHALL писать в stdout/stderr структурированную запись на каждый запрос с методом, шаблоном маршрута, кодом ответа, длительностью и `X-Request-Id`. Логи SHALL NOT содержать текста сообщений, `display_name`, значений заголовков идентификации и тел запросов.
|
||||
|
||||
#### Scenario: Запись о запросе присутствует
|
||||
|
||||
- **WHEN** обработан любой запрос к API
|
||||
- **THEN** в stdout появляется запись с методом, шаблоном маршрута, кодом ответа и идентификатором запроса
|
||||
|
||||
#### Scenario: Текст сообщения не попадает в логи
|
||||
|
||||
- **WHEN** отправлено сообщение с известным текстом-маркером
|
||||
- **THEN** этот текст отсутствует в stdout и stderr процесса
|
||||
|
||||
### Requirement: Контейнерная поставка
|
||||
|
||||
Сервис SHALL собираться из исходников в образ, слушать `0.0.0.0:8080` и читать конфигурацию из переменных окружения. Контейнер SHALL выполняться от непривилегированного пользователя, SHALL фиксировать версию базового образа и версии зависимостей и SHALL объявлять healthcheck, опирающийся на пробу жизни.
|
||||
|
||||
#### Scenario: Образ собирается из чистого clone
|
||||
|
||||
- **WHEN** выполняется сборка образа в свежей копии репозитория
|
||||
- **THEN** сборка завершается успешно без обращения к артефактам вне репозитория
|
||||
|
||||
#### Scenario: API доступен на опубликованном порту
|
||||
|
||||
- **WHEN** контейнер запущен с публикацией порта 8080
|
||||
- **THEN** `GET /health/ready` с хоста отвечает `200`
|
||||
|
||||
#### Scenario: Процесс работает не от root
|
||||
|
||||
- **WHEN** в работающем контейнере проверяется эффективный пользователь процесса сервера
|
||||
- **THEN** это не `root`, и идентификатор пользователя не равен 0
|
||||
|
||||
#### Scenario: Healthcheck отражает состояние сервиса
|
||||
|
||||
- **WHEN** контейнер запущен и сервис готов
|
||||
- **THEN** статус healthcheck контейнера становится `healthy`
|
||||
|
||||
### Requirement: Состояние живёт только в памяти процесса
|
||||
|
||||
Сервис SHALL хранить пользователей, чаты и сообщения только в памяти своего процесса. Сервис SHALL NOT использовать внешние СУБД, кэши и файлы состояния на обязательном пути данных. После перезапуска процесса всё состояние SHALL быть пустым.
|
||||
|
||||
#### Scenario: Данные исчезают после перезапуска
|
||||
|
||||
- **WHEN** созданы пользователь, чат и сообщение, после чего контейнер перезапущен тем же образом
|
||||
- **THEN** прежний идентификатор пользователя получает `401`, а созданные чат и сообщение недоступны
|
||||
|
||||
#### Scenario: Нет записи состояния на диск
|
||||
|
||||
- **WHEN** сервис обработал запись пользователей, чатов и сообщений
|
||||
- **THEN** в файловой системе контейнера не появляется файлов с этим состоянием
|
||||
|
||||
### Requirement: Предел времени обработки запроса
|
||||
|
||||
Обработка запроса SHALL ограничиваться настраиваемым пределом времени. При его превышении сервис SHALL отвечать `503` с кодом `unavailable`, если ответ ещё не начал отправляться, и SHALL записывать факт превышения в журнал. Превышение предела одним запросом SHALL NOT влиять на последующие запросы и на готовность сервиса.
|
||||
|
||||
#### Scenario: Запрос превысил предел
|
||||
|
||||
- **WHEN** обработка запроса длится дольше установленного предела
|
||||
- **THEN** ответ `503` с кодом `unavailable` и телом в общем формате ошибки
|
||||
|
||||
#### Scenario: Сервис продолжает работать после превышения
|
||||
|
||||
- **WHEN** после превышения предела приходит обычный запрос
|
||||
- **THEN** он обрабатывается штатно, а `GET /health/ready` отвечает `200`
|
||||
|
||||
#### Scenario: Запись о превышении не раскрывает содержимого
|
||||
|
||||
- **WHEN** запрос с известным текстом-маркером превысил предел
|
||||
- **THEN** в журнале появляется запись о превышении, и этот текст в ней отсутствует
|
||||
|
||||
### Requirement: Единый журнал всех сообщений процесса
|
||||
|
||||
Сервис SHALL выводить в stdout единый поток структурированных записей. Сообщения сервера приложений и используемых библиотек SHALL проходить через тот же журнал и иметь тот же формат, что и сообщения приложения. Записи SHALL содержать только поля из объявленного перечня; поля вне перечня SHALL отбрасываться.
|
||||
|
||||
#### Scenario: Сообщения сервера приложений в общем формате
|
||||
|
||||
- **WHEN** процесс запускается и печатает сообщения о старте сервера
|
||||
- **THEN** каждая строка stdout разбирается как структурированная запись того же формата, что и записи приложения
|
||||
|
||||
#### Scenario: Незаявленное поле не попадает в журнал
|
||||
|
||||
- **WHEN** запись журнала формируется с полем, отсутствующим в перечне разрешённых
|
||||
- **THEN** это поле в выводе отсутствует
|
||||
@@ -0,0 +1,94 @@
|
||||
## 1. Тулчейн и каркас проекта
|
||||
|
||||
- [x] 1.1 Завести `pyproject.toml`: метаданные, `requires-python`, зависимости рантайма (`fastapi`, `uvicorn[standard]`, `gunicorn`, `pydantic`, `pydantic-settings`, `dishka`, `structlog`) и dev-группу (`pytest`, `pytest-asyncio`, `httpx`, `ruff`, `ty`)
|
||||
- [x] 1.2 Настроить `ruff` в `pyproject.toml`: целевая версия Python, набор правил, `line-length`, стиль отступов, изоляция `student-tests/` от правил приложения
|
||||
- [x] 1.3 Настроить `ty` в `pyproject.toml`: корень исходников `src/`, строгость проверок, исключения для тестов
|
||||
- [x] 1.4 Закрепить версии: `uv lock`, зафиксировать `uv.lock` в репозитории, дополнить `.gitignore` и `.dockerignore` артефактами сборки
|
||||
- [x] 1.5 Добавить в `Makefile` цели `lint`, `format`, `typecheck`, `student-test`, `app-run`, `app-stop`, `bench`, не трогая существующие цели
|
||||
- [x] 1.6 Настроить PostToolUse-хук Claude Code в `.claude/settings.json`: после каждой правки файла под `src/` выполняются `ruff check --fix`, `ruff format` и `ty check` по этому файлу; правки вне `src/` хук пропускает
|
||||
- [x] 1.7 Проверка группы: `uv sync`, затем `make lint` и `make check` на пустом каркасе проходят
|
||||
|
||||
## 2. Доменные зоны
|
||||
|
||||
- [x] 2.1 Разделить приложение на зоны `identity/` и `messaging/`; в `shared/` оставить только базовый тип события, коды ошибок, общие проверки строк и ключ истории
|
||||
- [x] 2.2 Зона `identity`: объекты-значения `Username` и `DisplayName`, сущность `User`, событие `UserRegistered`
|
||||
- [x] 2.3 Зона `messaging`: объекты-значения `ChatTitle` и `MessageText`, агрегат `Chat` с составом участников и append-only историей, сущность `Message`, события `ChatCreated` и `MessagePosted`
|
||||
- [x] 2.4 Инварианты агрегата `Chat`: отправитель входит в состав, пара `(created_at, id)` строго возрастает, состав неизменен после создания
|
||||
- [x] 2.5 Коды ошибок контракта в `shared/domain/errors.py`: `invalid_request`, `not_found`, `conflict`, `unauthorized`, `unavailable`
|
||||
- [x] 2.6 Проверка группы: юнит-тесты обеих зон на правила `username`, длину текста в code points, членство и монотонность истории
|
||||
|
||||
## 3. Слой приложения
|
||||
|
||||
- [x] 3.1 Общие порты в `shared/application/ports.py`: `Clock`, `IdGenerator`, `Logger`, `UnitOfWork`, `EventPublisher`, `CursorCodec`
|
||||
- [x] 3.2 Порты зоны `identity`: `UserRepository`, `IdentityUnitOfWork`, `UserDirectory`; команда `RegisterUser` и её обработчик
|
||||
- [x] 3.3 Порты зоны `messaging`: `ChatRepository`, `MemberRegistry`, `MessagingUnitOfWork`, `ChatDirectory`; команды `CreateChat` и `PostMessage` и их обработчики
|
||||
- [x] 3.4 Сторона чтения: `GetCurrentUser` в `identity`, `GetChat`, `ListChats` и `ReadHistory` в `messaging` — плоские результаты в обход агрегата
|
||||
- [x] 3.5 Шины в `shared/application/messagebus.py`: `CommandBus` (ровно один обработчик, ошибка всплывает) и `EventBus` с двумя видами подписки — проекции до подтверждения и отложенные обработчики через `asyncio.Queue` с пределом
|
||||
- [x] 3.6 Проекция `MemberProjection` в `messaging`: реестр участников наполняется событием `UserRegistered` зоны `identity`, прямых вызовов между зонами нет
|
||||
- [x] 3.7 Сбор событий: UoW обходит `.seen` после фиксации и передаёт события публикатору
|
||||
- [x] 3.8 Проверка группы: тесты границ зон по графу импортов и тесты консистентности данных между зонами
|
||||
|
||||
## 4. Инфраструктура
|
||||
|
||||
- [x] 4.1 Хранилище зоны `identity`: индексы по идентификатору и по `username`, своя блокировка
|
||||
- [x] 4.2 Хранилище зоны `messaging`: чаты, индекс по участнику, реестр известных участников; история как append-only список внутри агрегата
|
||||
- [x] 4.3 Репозитории и UoW обеих зон с ведением `.seen`; фиксация явная, откат по умолчанию
|
||||
- [x] 4.4 Режимы блокировки `global` и `per-chat` за одним портом, выбор через настройку `STORAGE_LOCKING`
|
||||
- [x] 4.5 Часы `shared/infrastructure/clock.py`: UTC, микросекунды, строго возрастающие метки; генератор идентификаторов
|
||||
- [x] 4.6 Кодек курсора: base64url, подпись HMAC-SHA256, привязка к области `messages:<chat_id>` и `chats:<user_id>`
|
||||
- [x] 4.7 Адаптер публикации `InMemoryEventPublisher` поверх `EventBus`; порт `EventPublisher` остаётся точкой расширения на лабу 5
|
||||
- [x] 4.8 Структурный логгер на structlog за портом `Logger`: единый JSON-поток, белый список полей, сообщения сервера приложений и библиотек идут через него же
|
||||
- [x] 4.9 Проверка группы: тесты кодека курсора (подделка, чужая область, испорченное значение) и монотонности часов под конкурентной нагрузкой
|
||||
|
||||
## 5. Точка входа HTTP
|
||||
|
||||
- [x] 5.1 Настройки `config.py` через `pydantic-settings`: хост, порт, лимиты, режим блокировки, параметры брокера, срок остановки; рабочие значения по умолчанию
|
||||
- [x] 5.2 DTO запросов и ответов в `entrypoints/api/schemas.py` с запретом лишних полей; тела ответов ровно по схемам контракта
|
||||
- [x] 5.3 Middleware `X-Request-Id`: использовать клиентское значение либо сгенерировать, проставить в каждый ответ, связать с логом
|
||||
- [x] 5.4 Обработчики ошибок: доменные ошибки, `RequestValidationError`, ошибка разбора JSON, `404`/`405` и неперехваченное исключение — все в единый формат `Error`
|
||||
- [x] 5.5 Зависимость идентификации `X-User-Id`, выполняемая до валидации тела; отсутствие, неверный формат и неизвестный идентификатор дают `401`
|
||||
- [x] 5.6 Маршруты health, users, chats, messages; путь запроса переводится в команду или запрос и передаётся шине
|
||||
- [x] 5.7 Сборка зависимостей `ioc.py` на dishka: отдельные провайдеры `SharedProvider`, `IdentityProvider`, `MessagingProvider` и `BusProvider`; `Scope.APP` для хранилищ, часов, публикатора и шины событий, `Scope.REQUEST` для UoW и шин команд
|
||||
- [x] 5.8 Жизненный цикл приложения: старт и остановка фоновой задачи разбора событий, закрытие контейнера DI, перевод `/health/ready` в `503` при остановке
|
||||
- [x] 5.9 Единый конвейер запроса как чистый ASGI-middleware: `X-Request-Id`, предел тела, идентификация, таймаут обработки и запись в журнал; слоёный вариант сохраняется для сравнения
|
||||
- [x] 5.10 Проверка группы: `make app-run`, затем `make test` — публичный smoke проходит целиком
|
||||
|
||||
## 6. Контейнер
|
||||
|
||||
- [x] 6.1 `Dockerfile`: multi-stage, базовый образ закреплён по digest, зависимости из `uv.lock`, слой зависимостей отделён от слоя исходников
|
||||
- [x] 6.2 Непривилегированный пользователь, минимальный набор файлов в финальном образе, `.dockerignore` исключает `.venv`, `.git`, `evidence` и кэши
|
||||
- [x] 6.3 Сервер — gunicorn с одним `UvicornWorker`, конфигурация в `gunicorn_conf.py`, его журнал перенастроен на общий логгер; `HEALTHCHECK` на `/health/live` без дополнительных пакетов; `CMD` в exec-форме, gunicorn — PID 1
|
||||
- [x] 6.4 Корректная остановка: `SIGTERM` завершает процесс не дольше 10 секунд, принятые запросы дорабатываются
|
||||
- [x] 6.6 Проверка группы: сборка из чистого clone, запуск, `healthy`, `make test`, замер времени остановки, проверка пользователя процесса
|
||||
|
||||
## 7. Собственные тесты (уровень «4»)
|
||||
|
||||
- [x] 7.1 Негативные тесты API: malformed JSON, лишнее поле, неверный тип, пустой и пробельный текст, текст свыше 4000 code points
|
||||
- [x] 7.2 Тесты доступа: чужой чат даёт `404` на чтение и на запись, чужой чат не виден в списке, `403` не используется
|
||||
- [x] 7.3 Тесты идентификации: отсутствующий, неверный и неизвестный `X-User-Id` дают `401`; дубликат `username` даёт `409`
|
||||
- [x] 7.4 Тесты пагинации: обход нескольких страниц без повторов и пропусков, смена `limit` между страницами, курсор от другого чата, подделанный курсор, `limit` вне диапазона
|
||||
- [x] 7.5 Конкурентный тест: 100 сообщений от 10 клиентов дают ровно 100 уникальных сообщений и строго возрастающий порядок
|
||||
- [x] 7.6 Тест логов: текст-маркер сообщения не появляется в stdout и stderr
|
||||
- [x] 7.8 Тесты границ зон: граф импортов подтверждает, что `identity` не знает о `messaging`, а `messaging` заимствует только объявление события
|
||||
- [x] 7.9 Тесты консистентности между зонами: регистрация сразу видна чатам, отклонённые операции не оставляют следа ни в одной зоне, параллельная работа обеих зон не расходится по счётчикам
|
||||
- [x] 7.10 Тесты таймаута запроса: предсказуемый `503`, отсутствие влияния на следующие запросы, запись в журнал без текста сообщения
|
||||
- [x] 7.11 Проверка группы: `make student-test` запускает всё одной командой и проходит
|
||||
|
||||
## 8. Трек «5»: предел in-memory архитектуры
|
||||
|
||||
- [x] 8.1 `scripts/bench.py`: матрица из трёх размеров истории и трёх уровней конкуренции, прогрев, сбор успешных RPS, доли ошибок, p50/p95/p99 и RSS
|
||||
- [x] 8.2 Снятие RSS процесса контейнера и вывод средней стоимости одного сообщения в байтах
|
||||
- [x] 8.3 Гипотеза 1: блокировка хранилища. Прогон матрицы в режимах `global` и `per-chat` при тех же лимитах, сохранение обеих серий
|
||||
- [x] 8.4 Профилирование пути записи для поиска настоящего узкого места, когда гипотеза 1 не подтвердилась
|
||||
- [x] 8.5 Гипотеза 2: накладные расходы конвейера запроса. Прогон матрицы в режимах `layered` и `single`, сохранение обеих серий
|
||||
- [x] 8.6 Сведение серий в сравнительные таблицы: throughput, p95, p99, RSS, разница по каждому сочетанию
|
||||
- [x] 8.7 Оценка предела: число сообщений до исчерпания лимита памяти, допущения и границы экстраполяции
|
||||
- [x] 8.8 Проверка группы: `make bench` воспроизводит серии, результаты машиночитаемы и не содержат пользовательских данных
|
||||
|
||||
## 9. Отчёт и приёмка
|
||||
|
||||
- [x] 9.1 Заполнить `REPORT.md`: запуск из чистого clone, версии, архитектура, границы транзакций, объявленная семантика времени и курсоров
|
||||
- [x] 9.2 Таблица «критерий → команда → наблюдение → файл доказательства» для каждого заявленного пункта уровней «3», «4» и трека «5»
|
||||
- [x] 9.3 Таблица воздействий: перезапуск контейнера, `SIGTERM` под нагрузкой, недоступный брокер при включённой публикации
|
||||
- [x] 9.4 Раздел ограничений: какие отказы не выдерживаются, где учебное упрощение, что подтверждено измерением, а что осталось гипотезой
|
||||
- [x] 9.5 Проверка группы: `make check`, `make lint`, `make student-test` и `make test` против собранного образа проходят подряд
|
||||
@@ -0,0 +1,5 @@
|
||||
schema: spec-driven
|
||||
created: 2026-10-12
|
||||
skip_specs: true
|
||||
archived: 2026-10-12
|
||||
lab: 1
|
||||
@@ -0,0 +1,66 @@
|
||||
## Context
|
||||
|
||||
Мотивация — в `proposal.md` (Why). Сейчас FastAPI 0.141 уже сериализует успешные ответы через pydantic-core: аннотация `-> dict[str, Any]` превращается в TypeAdapter, и JSON-байты собираются на стороне Rust. Значит, модели ответов не добавляют новый сериализатор: меняется только то, что собирается в Python, — dict или модель. Тело ошибки отправляется в обход FastAPI, из сырого ASGI-конвейера (`shared/entrypoints/pipeline.py`) и из `identification.py`, сейчас через `orjson.dumps(error_body(...))`.
|
||||
|
||||
Изменение затрагивает обе зоны и `shared/entrypoints/`, но новой связи между зонами не вводит: каждая зона правит только свой HTTP-слой, обмен событиями не меняется.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Каждое значение, пересекающее HTTP-границу, имеет объявленный pydantic-тип; внутри — только dataclass и доменные объекты.
|
||||
- Ядро зон (`domain/`, `application/`) не импортирует pydantic: схемы живут в `entrypoints/`, настройки — в `config.py`.
|
||||
- Байт-в-байт тот же JSON на всех endpoint и в теле ошибки.
|
||||
|
||||
**Non-Goals:**
|
||||
- Перенос доменных инвариантов в схемы.
|
||||
- Замена `tuple` (`HistoryKey`, `tuple[list[T], bool]` из портов, `tuple[str, int]` в реестре ошибок) — это не dict.
|
||||
- Изменение индексов хранилища, ASGI-сообщений, реестров обработчиков, `CONFIG_KWARGS` uvicorn.
|
||||
- Изменения контейнера: пользователь, закрепление версий, healthcheck, обработка `SIGTERM` и переменные окружения остаются прежними.
|
||||
|
||||
## Decisions
|
||||
|
||||
### D1. Схемы транспорта лежат в `entrypoints/schemas.py` своей зоны
|
||||
|
||||
`identity/entrypoints/schemas.py`: `CreateUserRequest`, `UserOut`. `messaging/entrypoints/schemas.py`: `CreateChatRequest`, `CreateMessageRequest`, `PageQuery`, `ChatOut`, `MessageOut`, `PageOut[T]`. `shared/entrypoints/schemas.py`: `ErrorEnvelope` и `ErrorDetail`, `HealthOut`.
|
||||
|
||||
В `shared/` попадают только конверт ошибки и health: это механизм платформы, общий для всех ответов, а не доменное понятие. Коды ошибок по-прежнему объявляет зона в своём `errors.py`. `PageOut` остаётся в `messaging`, потому что страницы есть только там.
|
||||
|
||||
Что получаем: форма ответа объявлена типом и проверяется `ty` и FastAPI, а валидация входа заканчивается до application. Чего стоит: форма дублирует `contracts/openapi.json`, при этом источником истины остаётся `contracts/`.
|
||||
|
||||
### D2. Маппинг явным `of(domain)`, а не `from_attributes`
|
||||
|
||||
`UserOut.of(user)`, `ChatOut.of(chat)`, `MessageOut.of(message)`, `PageOut[MessageOut].of(page, MessageOut.of)`. В доменных объектах лежат value objects (`username.value`, `text.value`), и `from_attributes` пришлось бы подстраивать алиасами или свойствами в домене, а домен не должен знать транспорт. Чего стоит: один конструктор модели на элемент ответа.
|
||||
|
||||
### D3. Типы полей ответа — `UUID` и `datetime`
|
||||
|
||||
Поля `id`, `chat_id`, `sender_id`, `member_ids`, `created_at` типизированы по смыслу; pydantic сериализует `UUID` строкой, а UTC-`datetime` — с `Z`. Функция `moment()`, которая дублируется в двух зонах, удаляется. Альтернатива — поля `str`, заполняемые маппером, — отвергнута, потому что дублирует форматирование. Если формат разойдётся с текущим `isoformat().replace("+00:00", "Z")`, поле получит `Annotated[datetime, PlainSerializer(...)]` с прежним форматом.
|
||||
|
||||
### D4. Параметры запроса типизируются на границе
|
||||
|
||||
- `GET /chats` и `GET .../messages` принимают `Annotated[PageQuery, Query()]`: `limit: int = Field(50, ge=1, le=100)`, `cursor: str | None = None`. `extra="forbid"` у этой модели не ставится, потому что неизвестные query-параметры сегодня игнорируются. Строгий режим тоже не ставится: значения query — строки.
|
||||
- `chat_id: UUID` в path; функция `chat_uuid()` удаляется.
|
||||
- `CreateChatRequest.member_ids: list[Annotated[UUID, Field(strict=False)]]`. Модель остаётся `strict=True`, но FastAPI проверяет уже распарсенный dict в python-режиме, а там строгий `UUID` не принимает строку.
|
||||
- `parse_limit` и `LIMIT_*` уходят из `messaging/application/queries.py`. `ListChats` и `ReadHistory` получают `limit: int`. `CreateChat.member_ids` становится `Sequence[UUID]`, а `parse_uuids` в обработчике удаляется. Проверки дубликатов, неизвестных участников и отсутствия вызывающего остаются в домене и обработчике.
|
||||
|
||||
Ошибка разбора даёт `RequestValidationError` → `400 invalid_request`, то есть тот же код, что сейчас дают `InvalidPageRequest` и `InvalidChatData`. Курсор остаётся непрозрачной строкой, и разбирает его по-прежнему `SignedCursorCodec`.
|
||||
|
||||
### D5. Конверт ошибки сериализует pydantic-core
|
||||
|
||||
`ErrorEnvelope.of(code, message, request_id)` заменяет `error_body()` во всех четырёх местах вызова (`errors.py`, `pipeline.py`, `middleware.py`, `identification.py`). Байты получаются через `model_dump_json().encode()`, и на этом заканчивается использование orjson для HTTP-ответов. `orjson` остаётся зависимостью ради строк журнала.
|
||||
|
||||
### D6. Внутренние dict-методы удаляются
|
||||
|
||||
`DomainEvent.payload()` и его реализации в `UserRegistered`, `ChatCreated`, `MessagePosted` удаляются: событие уже frozen dataclass и само служит внутренним DTO. Журналы читают поля события напрямую. Порт `ChatDirectory.totals()`, его адаптер и метод хранилища тоже удаляются, потому что вызовов нет. Альтернатива — dataclass `Totals` и `EventPayload` — отвергнута как код ради кода. Когда в лабе 5 появится брокер, сериализацию события для него определит схема на той границе.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- [Формат `created_at` от pydantic расходится с текущим, например в долях секунды] → тест сравнивает ответ с форматом `isoformat().replace("+00:00", "Z")` на моменте с микросекундами и без них; при расхождении применяется резерв из D3.
|
||||
- [Строгий `UUID` в python-режиме отвергает корректный `member_ids`] → тест на успешный `POST /chats` закрывает это до остальных правок.
|
||||
- [Lax-разбор `limit` принимает нестандартную запись вроде `+5`, `05`, `1.0` или `1_0`, которую сейчас отвергает `parse_limit`] → контракт задаёт только целое 1–100; `0`, `101`, `abc` и отсутствие параметра ведут себя как прежде, это подтверждают собственные негативные тесты.
|
||||
- [Текст `message` в ответе 400 для плохого `limit` или `chat_id` станет общим `MESSAGES["invalid_request"]`] → контракт фиксирует `code`, а не текст; тесты проверяют код.
|
||||
- [Регрессия горячего пути: на страницу из 50 сообщений строится 50 моделей вместо 50 dict] → контрольный прогон `scripts/bench.py` по сценариям read и write в режиме `pipeline=single+locking=per-chat`; регрессия больше разброса повторов (3.2%) считается блокирующей и разбирается до архивации.
|
||||
- [Абзац REPORT про `orjson` устаревает] → уточняется отдельной задачей.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
Миграции нет: состояние живёт в памяти, данных между перезапусками нет. Откат — `git revert` коммитов изменения.
|
||||
@@ -0,0 +1,37 @@
|
||||
## Why
|
||||
|
||||
На краях сервиса данные описаны нетипизированными `dict[str, Any]`: ответы собираются вручную функциями `*_view`, тело ошибки — `error_body()`, health — литералом, а `limit`, `cursor` и `chat_id` приходят сырыми строками и разбираются внутри слоя application. Форма ответа нигде не объявлена как тип, поэтому ни `ty`, ни FastAPI её не проверяют, а транспортная валидация протекла внутрь (`parse_limit` в `messaging/application/queries.py`, `parse_uuids` в обработчике команды).
|
||||
|
||||
Правило изменения: на границе с внешним миром — pydantic-схемы, внутри — dataclass.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Ответы всех endpoint объявляются pydantic-моделями: `UserOut`, `ChatOut`, `MessageOut`, `PageOut[T]`, `HealthOut`, `ErrorEnvelope`; функции `*_view`, `moment()` и `error_body()` удаляются.
|
||||
- Query-параметры пагинации описываются моделью `PageQuery`, `chat_id` в path типизируется как `UUID`, `member_ids` в `CreateChatRequest` — как `list[UUID]`. Проверка `limit` и UUID переезжает из application на границу; application и команды получают уже типизированные значения.
|
||||
- Внутренние dict-«DTO» удаляются как неиспользуемые: `DomainEvent.payload()` (вызывается только тестами) и порт `totals()` (вызовов нет). Событие уже является dataclass и само служит внутренним DTO.
|
||||
- Инварианты (`username`, длины, пустой текст) остаются в доменных value objects и не дублируются в схемах.
|
||||
- `HistoryKey` остаётся `tuple`; индексы хранилища, ASGI-сообщения и реестры обработчиков — структуры данных, а не DTO, и не меняются.
|
||||
|
||||
Наблюдаемое поведение API не меняется: те же коды, тела, заголовки и `X-Request-Id`.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
Нет.
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
Нет: изменение — чистый рефакторинг без изменения требований, поэтому в `.openspec.yaml` выставлен `skip_specs: true`.
|
||||
|
||||
## Non-goals
|
||||
|
||||
Всё из Out of scope лабы 1 остаётся вне изменения. Схемы для брокера событий не вводятся: внешний брокер появится в лабе 5, тогда у него будет своя граница и своя схема. Публикация FastAPI `/openapi.json` не становится заменой `contracts/openapi.json`. Контракт, публичные тесты и рубрика не меняются.
|
||||
|
||||
## Impact
|
||||
|
||||
- Уровень рубрики: «3» (контракт сохраняется, `make test` проходит) и «4» (собственные негативные тесты подтверждают, что поведение не изменилось). Для трека «5» нужен контрольный прогон, показывающий отсутствие регрессии на горячем пути.
|
||||
- Строки `REPORT.md`: «**«3»** Все endpoint, форматы ошибок…» (`make test`), «Собственные негативные тесты одной командой» (`make student-test`), «Измерения предела in-memory» (`make bench`); абзац про `orjson` уточняется: успешные ответы сериализует pydantic-core.
|
||||
- Код: `identity/entrypoints/http.py`, `messaging/entrypoints/http.py`, новые `*/entrypoints/schemas.py`, `shared/entrypoints/{errors,health,pipeline,middleware}.py`, `identity/entrypoints/identification.py`, `messaging/application/{queries,handlers,commands,ports}.py`, `messaging/infrastructure/memory/{store,directory}.py`, `*/domain/events.py`, `shared/domain/events.py`.
|
||||
- Тесты: `student-tests/api/test_events.py`, `student-tests/unit/test_domain.py` проверяют поля события через `dataclasses.fields` вместо `payload()`.
|
||||
- Зависимости не меняются.
|
||||
@@ -0,0 +1,47 @@
|
||||
## 1. Подготовка и страховочные тесты
|
||||
|
||||
- [x] 1.1 Закоммитить текущие незафиксированные правки (`scripts/bench.py`, `main.py`, `shared/entrypoints/config.py`, `REPORT.md`, `evidence/bench/repeats/`) отдельным коммитом, чтобы рефакторинг начинался с чистого дерева
|
||||
- [x] 1.2 Добавить в `student-tests/api/` тест формата `created_at` у пользователя, чата и сообщения: RFC 3339 UTC с `Z`, совпадение с `isoformat().replace("+00:00", "Z")` на моменте с микросекундами и без них
|
||||
- [x] 1.3 Добавить тест на `?limit=abc`, отсутствие `limit` (по умолчанию 50) и неизвестный query-параметр (игнорируется), если таких сценариев ещё нет
|
||||
- [x] 1.4 Проверка: `make student-test` зелёный на текущем коде
|
||||
|
||||
## 2. Платформа `shared/entrypoints`
|
||||
|
||||
- [x] 2.1 Создать `shared/entrypoints/schemas.py`: `ErrorDetail`, `ErrorEnvelope` с `of(code, message, request_id)` и `HealthOut`
|
||||
- [x] 2.2 Заменить `error_body()` на `ErrorEnvelope` в `errors.py`, `pipeline.py`, `middleware.py` и удалить `error_body()`
|
||||
- [x] 2.3 Перевести `/health/live` и `/health/ready` на `-> HealthOut`
|
||||
- [x] 2.4 Проверка: `make student-test -k "operability or pipeline_modes or timeout"` зелёный
|
||||
|
||||
## 3. Зона `identity`
|
||||
|
||||
- [x] 3.1 Создать `identity/entrypoints/schemas.py`: перенести `CreateUserRequest`, добавить `UserOut.of(user)` с полями `UUID` и `datetime`
|
||||
- [x] 3.2 Перевести `create_user` и `current_user` на `-> UserOut`, удалить `user_view()` и `moment()` из `identity/entrypoints/http.py`
|
||||
- [x] 3.3 Заменить `error_body()` на `ErrorEnvelope` в `identity/entrypoints/identification.py`
|
||||
- [x] 3.4 Удалить `UserRegistered.payload()`, перевести `student-tests/unit/test_domain.py` на проверку `dataclasses.fields`
|
||||
- [x] 3.5 Проверка: `make student-test -k "access or negative or domain"` зелёный
|
||||
|
||||
## 4. Зона `messaging`: граница
|
||||
|
||||
- [x] 4.1 Создать `messaging/entrypoints/schemas.py`: перенести `CreateChatRequest` с `member_ids: list[Annotated[UUID, Field(strict=False)]]` и `CreateMessageRequest`, добавить `PageQuery` с `limit` 1–100 (по умолчанию 50) и `cursor`, добавить `ChatOut`, `MessageOut`, `PageOut[T]` с `of(...)`
|
||||
- [x] 4.2 Перевести обработчики `messaging/entrypoints/http.py` на `chat_id: UUID`, `Annotated[PageQuery, Query()]` и типизированные ответы; удалить `chat_uuid()`, `moment()` и все `*_view()`
|
||||
- [x] 4.3 Проверка: успешный `POST /api/v1/chats` с корректными `member_ids` проходит, `make student-test -k "negative or pagination"` зелёный
|
||||
|
||||
## 5. Зона `messaging`: application, domain, infrastructure
|
||||
|
||||
- [x] 5.1 В `messaging/application/queries.py` принять `limit: int` в `ListChats` и `ReadHistory`, удалить `parse_limit` и `LIMIT_*`
|
||||
- [x] 5.2 В `messaging/application/commands.py` сменить `CreateChat.member_ids` на `Sequence[UUID]`, в `handlers.py` удалить `parse_uuids`
|
||||
- [x] 5.3 Удалить `ChatDirectory.totals()` из `ports.py`, адаптера `memory/directory.py` и `memory/store.py`
|
||||
- [x] 5.4 Удалить `payload()` у `ChatCreated`, `MessagePosted` и базового `DomainEvent`; перевести `student-tests/api/test_events.py` на `dataclasses.fields`
|
||||
- [x] 5.5 Проверка: `rg "dict\[str, Any\]|payload\(|totals\(" src` не находит DTO-словарей, `make lint` (ruff + ty) и `make student-test` зелёные, `test_bounded_contexts` подтверждает, что `domain/` и `application/` не импортируют pydantic
|
||||
|
||||
## 6. Контракт и измерения
|
||||
|
||||
- [x] 6.1 Собрать образ, поднять контейнер, прогнать `make test` и `make check`: `PASS: lab1 public API scenario`
|
||||
- [x] 6.2 Контрольный прогон `scripts/bench.py --scenario read` и `--scenario write` в режиме `pipeline=single+locking=per-chat`, сравнить RPS и p95/p99 с текущими `evidence/bench/repeats/`; регрессия больше 3.2% блокирует архивацию
|
||||
- [x] 6.3 Проверка: результаты контрольного прогона сохранены в `evidence/bench/`, расхождение с прежними цифрами в пределах разброса
|
||||
|
||||
## 7. Отчёт
|
||||
|
||||
- [x] 7.1 Уточнить в `REPORT.md` абзац про `orjson`: успешные ответы и тело ошибки сериализует pydantic-core, `orjson` остаётся для журнала
|
||||
- [x] 7.2 Обновить в таблице доказательств число тестов в строке «Собственные негативные тесты одной командой» и сослаться на файл контрольного прогона
|
||||
- [x] 7.3 Проверка: `make lint`, `make student-test`, `make check` зелёные, `evidence/student-tests.txt` перезаписан свежим выводом
|
||||
@@ -0,0 +1,5 @@
|
||||
schema: spec-driven
|
||||
created: 2026-10-28
|
||||
retire_capabilities: true
|
||||
archived: 2026-10-28
|
||||
lab: 2
|
||||
@@ -0,0 +1,104 @@
|
||||
## Context
|
||||
|
||||
Мотивация — в `proposal.md`. Исходная точка — решение лабы 1 (ветка `solution/bpi2303-kostylev` в `mtusi2026lab1`): две зоны `identity` и `messaging`, порты и адаптеры в память, единый ASGI-конвейер с идентификацией раньше разбора тела, шина событий, курсор с HMAC. Ограничения лабы 2, формирующие решение:
|
||||
|
||||
- Smoke и persistence-тест сравнивают dict'ы целиком: `Session.user` с ответом регистрации, страницы истории с ответами `POST`, историю после рестарта с исходным сообщением. Формат `created_at` и порядок полей обязаны совпадать до символа.
|
||||
- Persistence-тест ждёт ответ не дольше 2 с и до 90 с опрашивает готовность после hook.
|
||||
- Несколько воркеров gunicorn — несколько процессов: ничто, что должно быть общим (секрет курсора, порядок истории), не может жить в памяти одного процесса.
|
||||
- Изменение касается обеих зон и `shared/`. Новой связи между зонами в коде не появляется: общая точка — схема БД.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- PostgreSQL — единственный источник истины для пользователей, сессий, чатов, участников и сообщений; адаптеры встают за существующие порты, `domain/` и `application/` не импортируют asyncpg.
|
||||
- Аутентификация целиком в ASGI-конвейере: `401` раньше доступа и валидации, точные challenge-заголовки, `X-User-Id` не читается вовсе.
|
||||
- Порядок истории строго определён при нескольких процессах API.
|
||||
- Стенд поднимается из чистого clone двумя командами, рестартуется hook-ом без потери данных и сессий.
|
||||
|
||||
**Non-Goals:**
|
||||
- Valkey, тесты гонок и отказов, EXPLAIN — изменение уровня «4».
|
||||
- ORM и генераторы миграций: SQL пишется руками, его план виден напрямую.
|
||||
- Очистка истёкших сессий фоновым процессом: строки удаляются при следующем входе того же пользователя.
|
||||
|
||||
## Decisions
|
||||
|
||||
### D1. Что переносится и что удаляется
|
||||
|
||||
Переносятся зоны, шина, конвейер, курсор, журнал, схемы pydantic, тесты и тулчейн. Удаляются адаптеры в память, `MemberRegistry` с проекцией `MemberProjection`, ошибка `HistoryOrderViolated`, слоёный конвейер на трёх `BaseHTTPMiddleware` (`PIPELINE=layered`), режимы блокировки `STORAGE_LOCKING` и `scripts/bench.py`. Последние три были измерительными инструментами трека лабы 1: с переездом в PostgreSQL сравнивать их больше не с чем. Что получаем: меньше кода и одно поведение. Чего стоит: эксперимент лабы 1 нельзя повторить на этой ветке — он остаётся в репозитории лабы 1.
|
||||
|
||||
### D2. Схема и границы транзакций
|
||||
|
||||
```
|
||||
users(id uuid PK, username text UNIQUE CHECK ~ '^[a-z0-9_]{3,32}$', display_name text CHECK 1..100,
|
||||
password_hash text, created_at timestamptz)
|
||||
sessions(token_hash bytea PK CHECK 32 байта, user_id → users ON DELETE CASCADE,
|
||||
created_at, expires_at CHECK > created_at) индекс (user_id)
|
||||
chats(id uuid PK, title text CHECK 1..100, created_at, last_message_at timestamptz NULL)
|
||||
chat_members(chat_id → chats ON DELETE CASCADE, user_id → users, position smallint,
|
||||
chat_created_at timestamptz, PK (chat_id, user_id)) индекс (user_id, chat_created_at, chat_id)
|
||||
messages(id uuid PK, chat_id, sender_id, text CHECK 1..4000, created_at,
|
||||
FK (chat_id, sender_id) → chat_members) индекс (chat_id, created_at, id)
|
||||
```
|
||||
|
||||
Длины в `CHECK` считаются `char_length` — в code points, как в контракте. Составной внешний ключ `messages → chat_members` гарантирует на уровне БД, что отправитель — участник своего чата. `position` хранит порядок `member_ids` из запроса, `chat_created_at` денормализован ради keyset-списка чатов по одному индексу. Индекс истории `(chat_id, created_at, id)` обслуживает keyset-запрос без сортировки; его обоснование планом — в изменении уровня «4».
|
||||
|
||||
Транзакции: регистрация — один `INSERT … ON CONFLICT (username) DO NOTHING RETURNING`; вход — удаление истёкших сессий пользователя и вставка новой одним оператором; создание чата — `INSERT chats` и `INSERT chat_members` из `unnest(…) WITH ORDINALITY` в одной транзакции UoW; сообщение — `SELECT … FOR UPDATE` строки чата, `INSERT messages`, `UPDATE chats.last_message_at` в одной транзакции. Чтения идут без явной транзакции, по одному оператору.
|
||||
|
||||
### D3. Миграции
|
||||
|
||||
`src/messenger/migrations/NNNN_*.sql` поставляются внутри пакета, применяет их `python -m messenger.migrate`: `pg_advisory_lock`, таблица `schema_migrations(version, checksum, applied_at)`, каждая миграция и запись о ней — в одной транзакции, SHA-256 текста сверяется с записанным. Запуск — одноразовый compose-сервис `migrate` на образе приложения; `api` зависит от него `service_completed_successfully`. Альтернатива — миграции при старте каждого воркера — отвергнута: четыре процесса гоняли бы DDL одновременно, а сбой миграции превращался бы в crash-loop API. Чего стоит: ещё один сервис в compose и ~50 строк runner-а вместо готового инструмента.
|
||||
|
||||
### D4. Доступ к PostgreSQL: пул, UoW и ошибки зависимости
|
||||
|
||||
`shared/infrastructure/postgres.py` — платформа: `Database` над `asyncpg.Pool` (ленивый, `min_size=0`, `max_size` на воркер, таймауты подключения, `acquire`, команды и `statement_timeout` на сервере) и база `PostgresUnitOfWork` (соединение на транзакцию, фиксация явная, откат по умолчанию, сбор событий). SQL только параметризованный (`$1…`). Ошибки сети, таймауты и отказ сервера (`OSError`, `asyncpg.InterfaceError`, `PostgresConnectionError`, классы `57*` и `53*`) превращаются в платформенное `Unavailable` (`shared/application/errors.py`), которое точка входа отдаёт как `503 unavailable`. Нарушения ограничений адаптер зоны переводит в доменные ошибки (`UsernameAlreadyTaken`, `InvalidChatData`). В `shared/` попадает только механизм — пул, транзакция, классификация отказа; ни одной таблицы зоны.
|
||||
|
||||
Пул ленивый, поэтому процесс стартует и при недоступной БД: `/health/live` отвечает, `/health/ready` даёт `503` до первого успешного `SELECT 1`. Готовность пингует БД через тот же пул с таймаутом 1 с.
|
||||
|
||||
### D5. Пароли и сессии (зона `identity`)
|
||||
|
||||
- `Password` — объект-значение (12–128 code points, не только пробелы). Хеш — порт `PasswordHasher`, адаптер `argon2-cffi`: Argon2id, `m=19 MiB, t=2, p=1` (минимум OWASP). Хеширование и проверка идут в пуле потоков под семафором (`PASSWORD_HASH_CONCURRENCY`, по умолчанию 2 на воркер), чтобы не блокировать event loop и ограничить память при всплеске регистраций. Для неизвестного `username` выполняется проверка против заранее вычисленного фиктивного хеша — время ответа не выдаёт существование пользователя.
|
||||
- Токен — `secrets.token_urlsafe(32)` (43 символа, 256 бит). В БД хранится только `sha256(token)`: у токена полная энтропия, медленный KDF ему не нужен, а утечка таблицы не даёт действующих токенов. В этом и разница с паролем, у которого энтропия мала и перебор надо удорожать.
|
||||
- `Session(token_hash, user_id, expires_at)`; `expires_at = now + SESSION_TTL_SECONDS`, абсолютный, не продлевается. Проверка — `expires_at > now` по часам приложения: один источник времени для назначения и проверки. Выход — `DELETE` строки.
|
||||
- Команды `RegisterUser`, `OpenSession`, `CloseSession` идут через `CommandBus` и UoW зоны; запросы `VerifyCredentials` и `Authenticate` — через справочники `UserDirectory` и `SessionDirectory`. События `SessionOpened` и `SessionClosed` пишутся в журнал аудита без токена.
|
||||
|
||||
### D6. Аутентификация в конвейере
|
||||
|
||||
Страж зоны `identity` (`entrypoints/authentication.py`) вызывается `RequestPipeline` до приложения и возвращает `None` или отказ `Rejection(status, code, headers)`; `Unavailable` из стража конвейер превращает в `503`. Публичны `/health/*` и `POST /api/v1/users`. На `POST /api/v1/auth/sessions` страж разбирает `Basic` своим парсером (строгий base64, первое `:`, UTF-8, ASCII-username) и проверяет пароль; на остальных `/api/v1/*` — `Bearer` (схема без учёта регистра). Challenge выбирает функция `challenge_for(path)` зоны, её же применяет обработчик ошибок `401` внутри приложения. Встроенный `fastapi.security.HTTPBasic` отвергнут: он декодирует ASCII и отвечает своим `401` без `realm`/`charset`. `X-User-Id` не читается нигде. Что получаем: порядок `401 → 404 → 400` держится одним местом. Чего стоит: проверка Argon2 на входе выполняется в конвейере, а не в обработчике.
|
||||
|
||||
### D7. Агрегат `Chat` без истории и порядок сообщений
|
||||
|
||||
Агрегат больше не держит историю: в памяти это была ссылка, в БД — материализация всей переписки. `Chat` хранит состав и `last_message_at`. `PostMessage` загружает чат `SELECT … FOR UPDATE`, агрегат проверяет членство и назначает `created_at = max(now, last_message_at + 1 мкс)`, адаптер вставляет сообщение и обновляет `last_message_at` в той же транзакции. Блокировка строки сериализует запись в один чат между процессами, поэтому порядок фиксации совпадает с порядком `(created_at, id)`, и keyset-читатель не пропускает сообщение, зафиксированное позже с меньшей отметкой. Это заменяет монотонные часы процесса лабы 1, которые при нескольких воркерах ничего не гарантируют. Чего стоит: запись в один горячий чат идёт последовательно (как блокировка `per-chat` в лабе 1); разные чаты не мешают друг другу. Альтернатива — время БД `clock_timestamp()` без блокировки — отвергнута: отметка назначается до фиксации, и параллельная транзакция может зафиксироваться позже с меньшей отметкой.
|
||||
|
||||
Идентификаторы — UUIDv7 (`uuid.uuid7()` в Python 3.14): вставки в B-tree первичных ключей идут в правый край, а порядок при равных отметках по-прежнему задаёт `uuid` как 128-битное число (сравнение `uuid` в PostgreSQL побайтовое и совпадает с `UUID.int`).
|
||||
|
||||
### D8. Зоны и общая БД
|
||||
|
||||
Проекция `MemberProjection` заменена внешним ключом `chat_members.user_id → users`: проверка «участник существует» выполняется СУБД в транзакции создания чата, и отказ откатывает её целиком. С реестром участников это была бы проекция в отдельной транзакции после фиксации пользователя — окно рассогласования без outbox. SQL зоны `messaging` не читает `users` и `sessions`, зона `identity` не читает таблиц чатов; тест границ проверяет и импорты, и тексты SQL. Событие `UserRegistered` остаётся (журнал аудита).
|
||||
|
||||
### D9. Курсор и секреты
|
||||
|
||||
`SignedCursorCodec` не меняется, но секрет обязателен и приходит из `CURSOR_SECRET_FILE`: случайный секрет на процесс ломал бы вторую страницу на другом воркере и после рестарта. Платформенный источник настроек читает `<ИМЯ>_FILE` для любого поля (`DATABASE_URL_FILE`, `CURSOR_SECRET_FILE`, позже `CACHE_URL_FILE`). `.env` приложение больше не читает: его использует только compose для подстановки.
|
||||
|
||||
### D10. Процесс и контейнер
|
||||
|
||||
gunicorn с `WEB_CONCURRENCY` (по умолчанию 4) воркерами `uvicorn_worker.UvicornWorker` (модуль `uvicorn.workers` объявлен устаревшим). Пул на воркер `DB_POOL_MAX_SIZE=8`: 4×8 плюс экземпляры тестов остаются ниже `max_connections=100`. Образ — как в лабе 1: python по digest, non-root `10001`, `SIGTERM` ≤10 с; healthcheck compose проверяет `/health/ready`.
|
||||
|
||||
Стенд `compose.yaml`: `postgres` (`postgres:17.11-alpine@sha256:…`, volume `pgdata`, `pg_isready`), `migrate`, `api` (`127.0.0.1:8080`). Учётные данные — compose secrets из `secrets/` (`postgres_password`, `database_url`, `cursor_secret`), их создаёт идемпотентный `scripts/secrets.sh` (`make secrets`) и не перезаписывает существующие. `scripts/restart.sh`: `stop api` → `restart postgres` → `up -d api` (повторно прогоняет `migrate`, что заодно проверяет идемпотентность).
|
||||
|
||||
Соответствие `.env.example`: `APP_HOST`/`APP_PORT` → `HOST`/`PORT` (задаёт образ), `APP_ENV` не используется, `SESSION_TTL_SECONDS` → `SESSION_TTL_SECONDS`, `DATABASE_URL_FILE` → `DATABASE_URL_FILE`, `SESSION_STORE=postgres` — фиксированный выбор (PostgreSQL — источник истины), `CACHE_URL_FILE` — изменение уровня «4».
|
||||
|
||||
### D11. Собственные тесты
|
||||
|
||||
Тесты API по-прежнему поднимают приложение в процессе (httpx + ASGI), но против настоящего PostgreSQL: фикстура сессии запускает одноразовый контейнер того же образа по digest, что и стенд, на случайном порту `127.0.0.1`, применяет миграции runner-ом и удаляет контейнер в конце. SQLite не используется. Публичный `make test` и persistence-тест идут против compose-стенда.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- [Argon2 на входе в конвейере под нагрузкой упирается в CPU] → семафор на воркер, параметры документированы; вход — не горячий путь.
|
||||
- [Первый запрос после рестарта PostgreSQL получает мёртвое соединение из пула] → asyncpg закрывает соединение по разрыву TCP, ошибка классифицируется как `503`, клиент persistence-теста повторяет запрос.
|
||||
- [`FOR UPDATE` сериализует запись в горячий чат] → это та же цена, что `per-chat` блокировка лабы 1; измерение стоимости записи — в треке «5».
|
||||
- [Истёкшие сессии копятся у пользователей, которые больше не входят] → индекс по `user_id` и удаление при входе; фоновой очистки нет, это записано в ограничениях.
|
||||
- [Секреты в `secrets/` на хосте читаемы контейнерами] → каталог в `.gitignore` и `.dockerignore`, файлы создаются скриптом, значения не печатаются.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
Перехода данных нет: лаба 1 не хранила состояния. Схема создаётся миграцией `0001_init.sql` на пустом volume. Откат — `git revert` и `make reset-data` (намеренное удаление volumes).
|
||||
@@ -0,0 +1,39 @@
|
||||
## Why
|
||||
|
||||
Решение лабы 1 держит всё состояние в памяти одного процесса и узнаёт пользователя по `X-User-Id`, которым любой клиент выдаёт себя за другого. Контракт 1.2.0 лабы 2 требует, чтобы пользователи, чаты, сообщения и действующие сессии переживали рестарт API и хранилищ, а запросы связывались с пользователем, доказавшим знание пароля. Изменение закрывает уровень «3» рубрики `README.md` и строки «Публичный smoke», «Persistence» и строки уровня 3 таблицы доказательств `REPORT.md`.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Решение лабы 1 переносится в skeleton лабы 2: `src/`, `student-tests/`, `Dockerfile`, тулчейн, цели `Makefile`, CI-job.
|
||||
- **BREAKING** Состояние переезжает в PostgreSQL: таблицы `users`, `sessions`, `chats`, `chat_members`, `messages` с первичными и внешними ключами, `UNIQUE(username)` и `CHECK`. Схема задаётся версионируемыми SQL-миграциями, которые применяет одноразовый сервис `migrate`; повторный запуск ничего не меняет.
|
||||
- Адаптеры PostgreSQL встают за существующие порты репозиториев, справочников и `UnitOfWork`; адаптеры в память, реестр участников с проекцией и экспериментальные режимы лабы 1 (`PIPELINE=layered`, `STORAGE_LOCKING`, `scripts/bench.py`) удаляются.
|
||||
- **BREAKING** `POST /api/v1/users` требует `password` (12–128 code points), пароль хранится только как Argon2id. `POST /api/v1/auth/sessions` принимает только `Basic` и выдаёт непрозрачный токен с абсолютным сроком `SESSION_TTL_SECONDS`; в БД лежит лишь его SHA-256. `DELETE /api/v1/auth/sessions/current` отзывает сессию.
|
||||
- **BREAKING** Все остальные `/api/v1/*` принимают только `Authorization: Bearer`; `X-User-Id` игнорируется. Аутентификация остаётся в ASGI-конвейере раньше доступа и валидации; `401` несёт точный `WWW-Authenticate` контракта.
|
||||
- Порядок истории при нескольких воркерах держит агрегат `Chat`: запись сообщения блокирует строку чата, и `created_at` строго возрастает в порядке фиксации.
|
||||
- Курсор подписывается постоянным секретом из `secrets/`, поэтому переживает рестарт и работает при нескольких воркерах.
|
||||
- Стенд — Docker Compose: `postgres` по digest с именованным volume, `migrate`, `api` (gunicorn с несколькими `UvicornWorker`, готовность пингует БД). Секреты — compose secrets из gitignored `secrets/`, генерируемых `make secrets`; `scripts/restart.sh` перезапускает API и PostgreSQL без удаления volumes.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `lab2-auth-sessions`: пароль и KDF, вход `Basic`, `Bearer`-сессии с абсолютным TTL, отзыв, игнорирование `X-User-Id`, challenge-заголовки `401`.
|
||||
- `lab2-persistent-storage`: схема PostgreSQL с ограничениями, версионируемые миграции, атомарное создание чата, сохранность данных и сессий при рестарте, воспроизводимый стенд, секреты вне Git.
|
||||
|
||||
### Modified Capabilities
|
||||
- `lab1-messenger-identity`: регистрация с паролем; идентификация по `X-User-Id` и требование «пользователи не переживают перезапуск» снимаются.
|
||||
- `lab1-messenger-chats`: запрос без действительной сессии вместо запроса без `X-User-Id`.
|
||||
- `lab1-messenger-history`: порядок истории гарантируется при нескольких процессах API.
|
||||
- `lab1-service-operability`: готовность зависит от PostgreSQL; логи без токенов и паролей; требование «состояние только в памяти» снимается.
|
||||
- `lab1-event-publication`: зоны связаны событием и внешним ключом схемы вместо проекции; событиям по-прежнему не нужен брокер.
|
||||
- `lab1-inmemory-capacity`: трек «5» лабы 1 о пределе памяти снимается вместе с in-memory хранением.
|
||||
|
||||
## Impact
|
||||
|
||||
- Код: все зоны `src/messenger/**`, новые `migrate.py`, `migrations/0001_init.sql`, `shared/infrastructure/postgres.py`; удаляются `*/infrastructure/memory/`, `messaging/application/projections.py`, `shared/entrypoints/middleware.py`.
|
||||
- Стенд: `compose.yaml`, `scripts/secrets.sh`, `scripts/restart.sh`, `.env.example`, `.dockerignore`, `Makefile`, `.github/workflows/application.yml`.
|
||||
- Зависимости: `asyncpg`, `argon2-cffi`, `uvicorn-worker`; образ `postgres:17.11-alpine` по digest.
|
||||
- Отчёт: `REPORT.md` (запуск, архитектура, строки уровня 3), `evidence/`.
|
||||
|
||||
## Non-goals
|
||||
|
||||
Valkey, гонки, rollback-тест, индекс истории с EXPLAIN и автотесты отказов — следующее изменение уровня «4»; трек «5» — третье. Из Out of scope лабы 2 не появляется ничего: реплики за балансировщиком и `Idempotency-Key` (лаба 3), S3 (лаба 4), брокер и worker (лаба 5), OTel (лаба 6), TLS (лаба 7). Контракт, публичные тесты, `README.md` и `COURSE.md` не меняются.
|
||||
+48
@@ -0,0 +1,48 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Публикация событий не требует брокера
|
||||
|
||||
Публикация событий SHALL выполняться через порт, реализованный внутренней очередью в памяти процесса. Доставка событий SHALL NOT зависеть от внешнего брокера; из сетевых сервисов обязательный API зависит только от PostgreSQL.
|
||||
|
||||
#### Scenario: События доставляются без брокера
|
||||
|
||||
- **WHEN** стенд поднят без брокера сообщений
|
||||
- **THEN** весь обязательный API работает, а события доставляются внутренней очередью
|
||||
|
||||
#### Scenario: Публикация скрыта за портом
|
||||
|
||||
- **WHEN** проверяется слой приложения
|
||||
- **THEN** он обращается к публикации только через порт и не знает её реализации
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Доменные зоны связаны только событиями
|
||||
|
||||
Зона «чаты и сообщения» SHALL NOT вызывать зону «пользователи» и импортировать её модули, кроме объявления события о регистрации. Существование участника SHALL проверяться внешним ключом схемы БД в той же транзакции, что и запись чата; SQL каждой зоны SHALL читать только таблицы своей зоны.
|
||||
|
||||
#### Scenario: Регистрация видна чатам сразу
|
||||
|
||||
- **WHEN** пользователь зарегистрирован и немедленно создаёт чат со своим участием
|
||||
- **THEN** чат создаётся успешно: ответ регистрации отправлен после фиксации пользователя в БД
|
||||
|
||||
#### Scenario: Неизвестный зоне участник отклоняется
|
||||
|
||||
- **WHEN** в состав чата передан идентификатор, которому не соответствует ни один пользователь
|
||||
- **THEN** ответ `400` с кодом `invalid_request`, чат не создаётся
|
||||
|
||||
#### Scenario: Зона пользователей не знает о чатах
|
||||
|
||||
- **WHEN** проверяется список зависимостей модулей зоны «пользователи»
|
||||
- **THEN** среди них нет ни одного модуля зоны «чаты и сообщения»
|
||||
|
||||
#### Scenario: Обратная связь идёт только через контракт события
|
||||
|
||||
- **WHEN** проверяется список зависимостей модулей зоны «чаты и сообщения»
|
||||
- **THEN** единственная заимствованная у зоны «пользователи» единица — объявление события о регистрации, а SQL зоны не упоминает таблиц `users` и `sessions`
|
||||
|
||||
## REMOVED Requirements
|
||||
|
||||
### Requirement: Доставка событий не требует внешних сервисов
|
||||
|
||||
**Reason**: С лабы 2 обязательный API зависит от PostgreSQL, поэтому формулировка «ни одного внешнего сервиса» больше неверна.
|
||||
**Migration**: Требование «Публикация событий не требует брокера» этой же capability.
|
||||
+16
@@ -0,0 +1,16 @@
|
||||
## REMOVED Requirements
|
||||
|
||||
### Requirement: Повторяемая методика измерения
|
||||
|
||||
**Reason**: Трек «5» лабы 1 измерял предел хранения в памяти одного процесса; с лабы 2 этого хранения нет.
|
||||
**Migration**: Повторяемая методика трека «5» лабы 2 — `lab2-query-plan-recovery` (вводится третьим изменением).
|
||||
|
||||
### Requirement: Наблюдаемый предел хранения в памяти
|
||||
|
||||
**Reason**: Сообщения больше не хранятся в памяти процесса API, RSS не растёт с историей.
|
||||
**Migration**: Стоимость хранения измеряется размером таблиц и индексов PostgreSQL в треке «5» лабы 2.
|
||||
|
||||
### Requirement: Узкое место названо и подтверждено изменением
|
||||
|
||||
**Reason**: Требование относилось к эксперименту in-memory архитектуры лабы 1.
|
||||
**Migration**: Сравнение вариантов индексов и запросов «до/после» — в треке «5» лабы 2.
|
||||
+32
@@ -0,0 +1,32 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Создание чата
|
||||
|
||||
Сервис SHALL принимать `POST /api/v1/chats` от аутентифицированного пользователя с телом `{"title":..., "member_ids":[...]}` и возвращать `201` с объектом `Chat`. `title` SHALL содержать от 1 до 100 code points и не состоять только из пробельных символов. `member_ids` SHALL содержать от 1 до 100 уникальных идентификаторов существующих пользователей и SHALL включать вызывающего. Чат SHALL создаваться атомарно: при любой ошибке валидации он не создаётся вовсе.
|
||||
|
||||
#### Scenario: Чат создан
|
||||
|
||||
- **WHEN** участник отправляет `POST /api/v1/chats` с корректным `title` и списком из своего и чужого идентификаторов
|
||||
- **THEN** ответ `201`, тело соответствует схеме `Chat`, `member_ids` совпадает с запрошенным составом
|
||||
- **AND** `id` и `created_at` назначены сервером
|
||||
|
||||
#### Scenario: Вызывающий не входит в состав
|
||||
|
||||
- **WHEN** `member_ids` не содержит идентификатора вызывающего
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Состав содержит дубликаты
|
||||
|
||||
- **WHEN** `member_ids` содержит один и тот же идентификатор дважды
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Состав содержит неизвестного пользователя
|
||||
|
||||
- **WHEN** `member_ids` содержит идентификатор, которому не соответствует ни один пользователь
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
- **AND** чат не создаётся
|
||||
|
||||
#### Scenario: Запрос без идентификации
|
||||
|
||||
- **WHEN** `POST /api/v1/chats` приходит без `Authorization: Bearer` или с недействительным токеном
|
||||
- **THEN** ответ `401` с кодом `unauthorized` и `WWW-Authenticate: Bearer realm="messenger"`
|
||||
+21
@@ -0,0 +1,21 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Порядок истории
|
||||
|
||||
История чата SHALL быть упорядочена по паре `(created_at, id)` по возрастанию. Время SHALL назначаться сервером в формате RFC 3339 UTC с суффиксом `Z`. Сервис SHALL гарантировать, что `created_at` внутри одного чата строго возрастает в порядке фиксации сообщений, в том числе при конкурентных вставках через разные процессы API, — иначе обход истории keyset-курсором теряет запись, зафиксированную позже с меньшей отметкой.
|
||||
|
||||
#### Scenario: Сообщения возвращаются в порядке приёма
|
||||
|
||||
- **WHEN** в чат последовательно отправлены два сообщения от разных участников
|
||||
- **THEN** `GET /api/v1/chats/{chat_id}/messages` возвращает их в порядке отправки
|
||||
|
||||
#### Scenario: Конкурентная запись не ломает порядок
|
||||
|
||||
- **WHEN** 10 клиентов параллельно отправляют по 10 сообщений в один чат
|
||||
- **THEN** история содержит ровно 100 сообщений с попарно различными `id`
|
||||
- **AND** `created_at` строго возрастает по всей истории
|
||||
|
||||
#### Scenario: Отметка не уходит назад при отставших часах процесса
|
||||
|
||||
- **WHEN** процесс API назначает сообщению отметку меньше, чем у последнего зафиксированного сообщения чата
|
||||
- **THEN** сообщение получает отметку на одну микросекунду больше последней, и порядок истории сохраняется
|
||||
+58
@@ -0,0 +1,58 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Регистрация пользователя
|
||||
|
||||
Сервис SHALL принимать `POST /api/v1/users` без аутентификации и возвращать `201` с объектом `User`, содержащим назначенные сервером `id` и `created_at`. Тело запроса SHALL содержать ровно поля `username`, `display_name` и `password`. `username` SHALL соответствовать `^[a-z0-9_]{3,32}$` и быть уникальным, `display_name` SHALL содержать от 1 до 100 Unicode code points и не состоять только из пробельных символов, требования к `password` задаёт `lab2-auth-sessions`. Ответ SHALL NOT содержать полей, отсутствующих в схеме `User`. Уникальность SHALL соблюдаться и при конкурентной регистрации одного `username`: успешной будет ровно одна, остальные получат `409`.
|
||||
|
||||
#### Scenario: Пользователь создан
|
||||
|
||||
- **WHEN** приходит `POST /api/v1/users` с телом `{"username":"alice_01","display_name":"Алиса","password":"<12+ символов>"}`
|
||||
- **THEN** ответ `201`, тело соответствует схеме `User`, `username` и `display_name` совпадают с запросом
|
||||
- **AND** `id` — UUID, назначенный сервером, `created_at` — RFC 3339 UTC с суффиксом `Z`
|
||||
|
||||
#### Scenario: Username занят
|
||||
|
||||
- **WHEN** приходит `POST /api/v1/users` с `username`, уже принадлежащим другому пользователю
|
||||
- **THEN** ответ `409` с телом ошибки и кодом `conflict`
|
||||
|
||||
#### Scenario: Username нарушает формат
|
||||
|
||||
- **WHEN** `username` содержит заглавные буквы, дефис, пробел, перевод строки или имеет длину вне 3–32 символов
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Display_name пуст или состоит из пробелов
|
||||
|
||||
- **WHEN** `display_name` равен `""`, `" "` или длиннее 100 code points
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Тело запроса нарушает схему
|
||||
|
||||
- **WHEN** тело содержит лишнее поле, неверный тип поля, не содержит обязательного поля (в том числе `password`) или не является корректным JSON
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
- **AND** сообщение ошибки не содержит stack trace и внутренних деталей реализации
|
||||
|
||||
#### Scenario: Регистрация не требует идентификации
|
||||
|
||||
- **WHEN** `POST /api/v1/users` приходит без заголовка `Authorization`
|
||||
- **THEN** запрос обрабатывается на общих основаниях, ответ не равен `401`
|
||||
|
||||
### Requirement: Чтение текущего пользователя
|
||||
|
||||
Сервис SHALL отдавать по `GET /api/v1/users/me` объект `User` владельца предъявленной `Bearer`-сессии в том же виде, в каком он был возвращён при регистрации.
|
||||
|
||||
#### Scenario: Текущий пользователь возвращён
|
||||
|
||||
- **WHEN** приходит `GET /api/v1/users/me` с действительным `Bearer`-токеном пользователя
|
||||
- **THEN** ответ `200`, тело соответствует схеме `User` и совпадает с телом ответа его регистрации
|
||||
|
||||
## REMOVED Requirements
|
||||
|
||||
### Requirement: Идентификация запроса заголовком X-User-Id
|
||||
|
||||
**Reason**: Контракт 1.2.0 заменяет учебную идентификацию аутентификацией: `X-User-Id` с лабы 2 игнорируется.
|
||||
**Migration**: Получить токен `POST /api/v1/auth/sessions` с `Basic` и передавать `Authorization: Bearer <token>`; правила описаны в `lab2-auth-sessions`.
|
||||
|
||||
### Requirement: Состояние пользователей не переживает перезапуск
|
||||
|
||||
**Reason**: С лабы 2 пользователи хранятся в PostgreSQL и обязаны переживать рестарт.
|
||||
**Migration**: Требование «Данные и сессии переживают рестарт» в `lab2-persistent-storage`.
|
||||
+56
@@ -0,0 +1,56 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Пробы жизни и готовности
|
||||
|
||||
Сервис SHALL отвечать на `GET /health/live` кодом `200` с телом `{"status":"ok"}`, проверяя только жизнь процесса. Сервис SHALL отвечать на `GET /health/ready` кодом `200` с тем же телом, только если в момент запроса выполнен запрос к PostgreSQL за ограниченное время, и кодом `503` с телом ошибки в общем формате в противном случае. Пробы SHALL NOT требовать аутентификации. Недоступность необязательных зависимостей SHALL NOT переводить готовность в `503`.
|
||||
|
||||
#### Scenario: Проба жизни отвечает без идентификации
|
||||
|
||||
- **WHEN** приходит `GET /health/live` без заголовка `Authorization`
|
||||
- **THEN** ответ `200` с телом `{"status":"ok"}`
|
||||
|
||||
#### Scenario: Готовность подтверждена
|
||||
|
||||
- **WHEN** приходит `GET /health/ready`, а PostgreSQL доступен
|
||||
- **THEN** ответ `200` с телом `{"status":"ok"}`
|
||||
|
||||
#### Scenario: Готовность не зависит от внешних сервисов
|
||||
|
||||
- **WHEN** проверяется готовность, а недоступна только необязательная зависимость
|
||||
- **THEN** ответ `200`: из внешних сервисов готовность зависит лишь от PostgreSQL
|
||||
|
||||
#### Scenario: Готовность отражает PostgreSQL
|
||||
|
||||
- **WHEN** PostgreSQL остановлен
|
||||
- **THEN** `GET /health/ready` отвечает `503` с кодом `unavailable`, а `GET /health/live` — `200`
|
||||
|
||||
#### Scenario: Сервис остановлен
|
||||
|
||||
- **WHEN** процесс получил сигнал остановки и перестал принимать новую работу
|
||||
- **THEN** `GET /health/ready` отвечает `503` с кодом `unavailable` либо соединение не устанавливается
|
||||
|
||||
### Requirement: Логи без содержимого сообщений
|
||||
|
||||
Сервис SHALL писать в stdout/stderr структурированную запись на каждый запрос с методом, шаблоном маршрута, кодом ответа, длительностью и `X-Request-Id`. Логи SHALL NOT содержать текста сообщений, `display_name`, паролей, токенов сессий, значений заголовка `Authorization`, строк подключения к хранилищам и тел запросов.
|
||||
|
||||
#### Scenario: Запись о запросе присутствует
|
||||
|
||||
- **WHEN** обработан любой запрос к API
|
||||
- **THEN** в stdout появляется запись с методом, шаблоном маршрута, кодом ответа и идентификатором запроса
|
||||
|
||||
#### Scenario: Текст сообщения не попадает в логи
|
||||
|
||||
- **WHEN** отправлено сообщение с известным текстом-маркером
|
||||
- **THEN** этот текст отсутствует в stdout и stderr процесса
|
||||
|
||||
#### Scenario: Учётные данные не попадают в логи
|
||||
|
||||
- **WHEN** пользователь зарегистрировался, вошёл и выполнил запрос с токеном
|
||||
- **THEN** ни пароль, ни токен, ни значение `Authorization` не встречаются в stdout и stderr процесса
|
||||
|
||||
## REMOVED Requirements
|
||||
|
||||
### Requirement: Состояние живёт только в памяти процесса
|
||||
|
||||
**Reason**: С лабы 2 обязательное состояние хранится в PostgreSQL и переживает рестарт процесса.
|
||||
**Migration**: Требования `lab2-persistent-storage`.
|
||||
+123
@@ -0,0 +1,123 @@
|
||||
## Purpose
|
||||
|
||||
Определяет, как пользователь доказывает знание пароля, получает непрозрачную сессию с абсолютным сроком жизни, предъявляет её на защищённых endpoint и отзывает её. Заменяет учебную идентификацию `X-User-Id` лабы 1.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Пароль хранится только как password KDF
|
||||
|
||||
Сервис SHALL хранить пароль пользователя только в виде хеша библиотечного password KDF Argon2id с солью. Пароль, его хеш и сессионные данные SHALL NOT входить в объект `User` и SHALL NOT попадать в журнал. Пароль SHALL содержать от 12 до 128 Unicode code points и SHALL NOT состоять только из пробельных символов.
|
||||
|
||||
#### Scenario: В хранилище нет открытого пароля
|
||||
|
||||
- **WHEN** пользователь зарегистрирован с паролем
|
||||
- **THEN** запись пользователя в БД содержит строку, начинающуюся с `$argon2id$`, и не содержит пароля
|
||||
|
||||
#### Scenario: Пароль вне допустимой длины
|
||||
|
||||
- **WHEN** `POST /api/v1/users` содержит `password` короче 12 или длиннее 128 code points
|
||||
- **THEN** ответ `400` с кодом `invalid_request`, пользователь не создаётся
|
||||
|
||||
#### Scenario: Пароль из одних пробелов
|
||||
|
||||
- **WHEN** `password` состоит только из пробельных символов
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Ответ регистрации без пароля
|
||||
|
||||
- **WHEN** пользователь успешно зарегистрирован
|
||||
- **THEN** тело `201` содержит ровно `id`, `username`, `display_name`, `created_at`
|
||||
|
||||
### Requirement: Вход по Basic выдаёт сессию
|
||||
|
||||
Сервис SHALL принимать `POST /api/v1/auth/sessions` только с заголовком `Authorization: Basic <base64(username:password)>` и без тела. Декодирование base64 SHALL быть строгим, разделителем SHALL служить первое двоеточие, пароль SHALL декодироваться как UTF-8. При верных учётных данных ответ SHALL быть `201` с телом `{"token","token_type":"Bearer","expires_at","user"}`, где `token` — непрозрачная случайная строка не короче 32 символов с энтропией не менее 256 бит, `expires_at` — RFC 3339 UTC с `Z`, а `user` совпадает с ответом регистрации. Неверный пароль, неизвестный `username`, отсутствующий и испорченный заголовок SHALL давать одинаковый `401` с кодом `unauthorized` и заголовком `WWW-Authenticate: Basic realm="messenger", charset="UTF-8"`.
|
||||
|
||||
#### Scenario: Успешный вход
|
||||
|
||||
- **WHEN** зарегистрированный пользователь отправляет верные `username:password` в `Basic`
|
||||
- **THEN** ответ `201`, тело соответствует схеме `Session`, `token_type` равен `Bearer`
|
||||
- **AND** `user` побайтно равен телу ответа его регистрации, `expires_at` в будущем
|
||||
|
||||
#### Scenario: Неверный пароль и неизвестный пользователь неразличимы
|
||||
|
||||
- **WHEN** приходит `Basic` с неверным паролем существующего пользователя или с несуществующим `username`
|
||||
- **THEN** оба ответа — `401` с кодом `unauthorized` и `WWW-Authenticate: Basic realm="messenger", charset="UTF-8"`
|
||||
- **AND** тела ответов различаются только `request_id`
|
||||
|
||||
#### Scenario: Испорченный заголовок Basic
|
||||
|
||||
- **WHEN** заголовок отсутствует, содержит другую схему, невалидный base64 или строку без двоеточия
|
||||
- **THEN** ответ `401` с тем же заголовком `WWW-Authenticate: Basic ...`
|
||||
|
||||
#### Scenario: Двоеточие в пароле
|
||||
|
||||
- **WHEN** пароль пользователя содержит двоеточие и он входит по `Basic`
|
||||
- **THEN** ответ `201`: разделителем служит первое двоеточие
|
||||
|
||||
#### Scenario: Тело запроса при входе
|
||||
|
||||
- **WHEN** запрос с верным `Basic` содержит тело
|
||||
- **THEN** ответ `400` с кодом `invalid_request`, сессия не создаётся
|
||||
|
||||
### Requirement: Защищённые endpoint принимают только Bearer
|
||||
|
||||
Все `/api/v1/*`, кроме `POST /api/v1/users` и `POST /api/v1/auth/sessions`, SHALL требовать `Authorization: Bearer <token>`; схема сравнивается без учёта регистра. Отсутствующий, неизвестный, истёкший и отозванный токен, а также `Basic` на этих endpoint SHALL давать `401` с кодом `unauthorized` и `WWW-Authenticate: Bearer realm="messenger"`. Заголовок `X-User-Id` SHALL игнорироваться: он не даёт доступа и не меняет владельца сессии. Аутентификация SHALL выполняться раньше проверки доступа к ресурсу и раньше валидации пути, параметров и тела.
|
||||
|
||||
#### Scenario: Только X-User-Id
|
||||
|
||||
- **WHEN** `GET /api/v1/users/me` приходит с `X-User-Id` существующего пользователя и без `Authorization`
|
||||
- **THEN** ответ `401` с `WWW-Authenticate: Bearer realm="messenger"`
|
||||
|
||||
#### Scenario: X-User-Id не подменяет владельца
|
||||
|
||||
- **WHEN** `GET /api/v1/users/me` приходит с `Bearer` пользователя alice и `X-User-Id` пользователя eve
|
||||
- **THEN** ответ `200` с пользователем alice
|
||||
|
||||
#### Scenario: Basic на бизнес-endpoint
|
||||
|
||||
- **WHEN** `GET /api/v1/users/me` приходит с верным `Basic`
|
||||
- **THEN** ответ `401` с `WWW-Authenticate: Bearer realm="messenger"`
|
||||
|
||||
#### Scenario: Неизвестный токен
|
||||
|
||||
- **WHEN** запрос несёт `Bearer` со случайной строкой
|
||||
- **THEN** ответ `401` с кодом `unauthorized`
|
||||
|
||||
#### Scenario: Аутентификация раньше валидации
|
||||
|
||||
- **WHEN** `POST /api/v1/chats/not-a-uuid/messages` приходит без `Authorization` и с испорченным JSON
|
||||
- **THEN** ответ `401`, а не `400`
|
||||
|
||||
### Requirement: Абсолютный срок жизни сессии
|
||||
|
||||
Срок жизни сессии SHALL задаваться `SESSION_TTL_SECONDS` (по умолчанию 3600) от момента входа и SHALL NOT продлеваться ни использованием, ни рестартом сервиса. После `expires_at` токен SHALL давать `401`.
|
||||
|
||||
#### Scenario: Срок назначен при входе
|
||||
|
||||
- **WHEN** пользователь вошёл
|
||||
- **THEN** `expires_at` равен моменту входа плюс `SESSION_TTL_SECONDS` секунд
|
||||
|
||||
#### Scenario: Истёкший токен
|
||||
|
||||
- **WHEN** сервис запущен с `SESSION_TTL_SECONDS=2` и токен предъявлен через 3 секунды после входа
|
||||
- **THEN** ответ `401` с `WWW-Authenticate: Bearer realm="messenger"`
|
||||
|
||||
### Requirement: Отзыв текущей сессии
|
||||
|
||||
`DELETE /api/v1/auth/sessions/current` SHALL отзывать предъявленный токен и отвечать `204` без тела. После отзыва этот токен SHALL давать `401`, в том числе на повторный `DELETE`. Остальные сессии того же пользователя SHALL оставаться действительными.
|
||||
|
||||
#### Scenario: Выход
|
||||
|
||||
- **WHEN** пользователь отправляет `DELETE /api/v1/auth/sessions/current` со своим токеном
|
||||
- **THEN** ответ `204` с пустым телом и непустым `X-Request-Id`
|
||||
- **AND** следующий `GET /api/v1/users/me` с этим токеном получает `401`
|
||||
|
||||
#### Scenario: Повторный выход
|
||||
|
||||
- **WHEN** `DELETE /api/v1/auth/sessions/current` повторяется с уже отозванным токеном
|
||||
- **THEN** ответ `401` с `WWW-Authenticate: Bearer realm="messenger"`
|
||||
|
||||
#### Scenario: Другая сессия не затронута
|
||||
|
||||
- **WHEN** пользователь вошёл дважды и отозвал первую сессию
|
||||
- **THEN** второй токен продолжает получать `200`
|
||||
+76
@@ -0,0 +1,76 @@
|
||||
## Purpose
|
||||
|
||||
Определяет постоянное хранение лабы 2: схему PostgreSQL с ограничениями, версионируемые миграции, атомарность составных операций, сохранность данных и сессий при рестарте и воспроизводимый стенд из репозитория без секретов в Git.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Схема с ограничениями целостности
|
||||
|
||||
PostgreSQL SHALL хранить пользователей, сессии, чаты, участников и сообщения в отдельных таблицах с первичными ключами. Уникальность `username` SHALL обеспечиваться ограничением БД. Участник чата SHALL ссылаться на существующего пользователя и существующий чат, сообщение SHALL ссылаться на участника своего чата, сессия — на пользователя. Схема SHALL дублировать правила контракта проверками `CHECK` (формат `username`, длины строк).
|
||||
|
||||
#### Scenario: Ограничения видны в схеме
|
||||
|
||||
- **WHEN** оператор выполняет `\d+` по таблицам `users`, `chat_members`, `messages`
|
||||
- **THEN** видны `PRIMARY KEY`, `UNIQUE (username)` и внешние ключи `chat_members → users, chats`, `messages → chat_members`
|
||||
|
||||
#### Scenario: Сообщение от постороннего не записывается даже в обход API
|
||||
|
||||
- **WHEN** в `messages` вставляется строка, отправитель которой не состоит в чате
|
||||
- **THEN** вставка отклоняется нарушением внешнего ключа
|
||||
|
||||
### Requirement: Версионируемые миграции
|
||||
|
||||
Схема SHALL создаваться только миграциями: упорядоченными SQL-файлами, каждый из которых применяется в своей транзакции и записывается в журнал применённых версий. Миграции SHALL применяться одноразовым процессом до старта API, одновременный запуск двух процессов SHALL сериализоваться. Повторный запуск SHALL NOT менять схему и данные. Изменение текста уже применённой миграции SHALL останавливать запуск с ошибкой.
|
||||
|
||||
#### Scenario: Миграции с пустого volume
|
||||
|
||||
- **WHEN** стенд поднимается на пустом volume PostgreSQL
|
||||
- **THEN** процесс миграций применяет все версии по порядку и завершается кодом 0, после чего стартует API
|
||||
|
||||
#### Scenario: Повторный запуск
|
||||
|
||||
- **WHEN** процесс миграций запускается повторно на той же БД
|
||||
- **THEN** он завершается кодом 0, журнал версий и число строк во всех таблицах не меняются
|
||||
|
||||
#### Scenario: Изменённая миграция
|
||||
|
||||
- **WHEN** текст применённой миграции изменён и процесс миграций запущен
|
||||
- **THEN** процесс завершается ненулевым кодом и схему не трогает
|
||||
|
||||
### Requirement: Атомарное создание чата
|
||||
|
||||
Создание чата SHALL записывать чат и всех его участников в одной транзакции. Если хотя бы одна запись нарушает ограничение, транзакция SHALL откатываться целиком: ни строки чата, ни строк участников не остаётся.
|
||||
|
||||
#### Scenario: Неизвестный участник откатывает чат
|
||||
|
||||
- **WHEN** `POST /api/v1/chats` содержит в `member_ids` UUID несуществующего пользователя
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
- **AND** в БД нет ни чата с этим `title`, ни его участников
|
||||
|
||||
### Requirement: Данные и сессии переживают рестарт
|
||||
|
||||
Пользователи, чаты, участники, сообщения и ещё действующие сессии SHALL сохраняться при перезапуске API и всех хранилищ с сохранёнными volumes. После рестарта прежний токен SHALL работать до своего прежнего `expires_at`, а подтверждённое сообщение SHALL читаться побайтно тем же.
|
||||
|
||||
#### Scenario: Полный рестарт стенда
|
||||
|
||||
- **WHEN** выполняется `make test-persistence ACTION_SCRIPT=scripts/restart.sh`
|
||||
- **THEN** hook перезапускает API и хранилища за ≤90 с с кодом 0, а тест печатает `PASS: persistence preserved confirmed data and existing session`
|
||||
|
||||
#### Scenario: Логаут после рестарта
|
||||
|
||||
- **WHEN** после рестарта пользователь отзывает прежний токен
|
||||
- **THEN** ответ `204`, а следующий запрос с этим токеном получает `401`
|
||||
|
||||
### Requirement: Воспроизводимый стенд из репозитория
|
||||
|
||||
Стенд SHALL подниматься из чистого clone командами репозитория: образы сторонних сервисов закреплены версией и digest, API собирается из исходников. Процессы сервисов SHALL работать не от root, у каждого долгоживущего сервиса SHALL быть healthcheck. Наружу SHALL публиковаться только API на `127.0.0.1:8080`. Учётные данные SHALL передаваться файлами compose secrets из каталога, исключённого из Git, и SHALL NOT появляться в Git, образе и журнале.
|
||||
|
||||
#### Scenario: Подъём из чистого clone
|
||||
|
||||
- **WHEN** в чистом clone выполняются `make secrets` и `make up`
|
||||
- **THEN** все сервисы становятся `healthy` или завершаются кодом 0, а `GET /health/ready` отвечает `200`
|
||||
|
||||
#### Scenario: Секреты и volumes вне Git
|
||||
|
||||
- **WHEN** выполняются `git ls-files secrets .env` и `git check-ignore secrets/database_url .env`
|
||||
- **THEN** первая команда ничего не выводит, вторая подтверждает, что пути игнорируются
|
||||
@@ -0,0 +1,52 @@
|
||||
## 1. Перенос решения лабы 1
|
||||
|
||||
- [x] 1.1 Перенести из `mtusi2026lab1` (ветка `solution/bpi2303-kostylev`) `src/`, `student-tests/`, `Dockerfile`, `pyproject.toml`, `uv.lock`, цели `Makefile`, `.github/workflows/application.yml`, дополнения `.dockerignore`; версия пакета — `1.2.0`
|
||||
- [x] 1.2 Проверка группы: `uv sync --group dev`, `make lint`, `make check` проходят на перенесённом коде
|
||||
|
||||
## 2. Схема и миграции
|
||||
|
||||
- [x] 2.1 Написать `src/messenger/migrations/0001_init.sql`: таблицы `users`, `sessions`, `chats`, `chat_members`, `messages` с PK, FK, `UNIQUE(username)`, `CHECK` и индексами из design D2
|
||||
- [x] 2.2 Платформа `shared/infrastructure/postgres.py`: `Database` (ленивый пул, таймауты, `ping`, классификация отказа в `Unavailable`) и база `PostgresUnitOfWork`; `Unavailable` в `shared/application/errors.py`
|
||||
- [x] 2.3 Runner `src/messenger/migrate.py`: advisory lock, `schema_migrations` с checksum, транзакция на файл, отказ на изменённой миграции
|
||||
- [x] 2.4 Источник настроек `<ИМЯ>_FILE` в `shared/config.py`; `database_url` и параметры пула в `PlatformSettings`; приложение не читает `.env`
|
||||
- [x] 2.5 Проверка группы: тест runner-а — с нуля применяет все версии, повтор ничего не меняет, изменённая миграция отклоняется
|
||||
|
||||
## 3. Зона `identity`
|
||||
|
||||
- [x] 3.1 Домен: объект-значение `Password`, поле `password_hash` у `User`, сущность `Session` с выпуском токена и `sha256`, события `SessionOpened` и `SessionClosed`
|
||||
- [x] 3.2 Приложение: порты `PasswordHasher`, `SessionRepository`, `SessionDirectory`, расширенные `UserDirectory`/`IdentityUnitOfWork`; команды и обработчики `RegisterUser` (с паролем), `OpenSession`, `CloseSession`; запросы `VerifyCredentials` (с фиктивной проверкой) и `Authenticate`
|
||||
- [x] 3.3 Инфраструктура: адаптер Argon2id в пуле потоков под семафором; адаптеры PostgreSQL пользователей и сессий; `UsernameAlreadyTaken` из `ON CONFLICT DO NOTHING`
|
||||
- [x] 3.4 Точка входа: `IdentitySettings` (`SESSION_TTL_SECONDS`, `PASSWORD_HASH_CONCURRENCY`), схемы `CreateUserRequest` с `password` и `SessionOut`, роутеры `/api/v1/users` и `/api/v1/auth/sessions`, провайдер DI, журнал
|
||||
- [x] 3.5 Страж `entrypoints/authentication.py`: строгий парсер `Basic`, разбор `Bearer`, `challenge_for(path)`, публичные маршруты, `X-User-Id` не читается
|
||||
- [x] 3.6 Проверка группы: юнит-тесты `Password`, парсеров `Basic`/`Bearer` и выпуска токена; API-тесты входа, неверного пароля, неизвестного пользователя, Basic на бизнес-endpoint, только `X-User-Id`, выхода и повторного выхода
|
||||
|
||||
## 4. Зона `messaging`
|
||||
|
||||
- [x] 4.1 Домен: `Chat` без истории, с `last_message_at` и правилом `created_at = max(now, last + 1 мкс)`; удалить `HistoryOrderViolated`, проверку известных участников и реестр
|
||||
- [x] 4.2 Приложение: порты `ChatRepository` (`add`, `get` с блокировкой, `append`), `MessagingUnitOfWork`, `ChatDirectory`; удалить `MemberRegistry` и `MemberProjection`
|
||||
- [x] 4.3 Инфраструктура: адаптеры PostgreSQL — создание чата двумя операторами в транзакции с переводом FK-нарушения в `InvalidChatData`, запись сообщения под `FOR UPDATE`, keyset-запросы списка чатов и истории (`limit + 1`), отдельный текст запроса для первой страницы
|
||||
- [x] 4.4 Обязательный `CURSOR_SECRET` (`CURSOR_SECRET_FILE`), удалить случайный секрет и `STORAGE_LOCKING`
|
||||
- [x] 4.5 Проверка группы: API-тесты создания чата с неизвестным участником (`400`, строк нет), пагинации списка и истории, курсора чужого чата, конкурентной записи 100 сообщений от 10 клиентов со строго возрастающим `created_at`
|
||||
|
||||
## 5. Платформа и сборка
|
||||
|
||||
- [x] 5.1 Конвейер: страж возвращает `Rejection` с заголовками, `Unavailable` из стража → `503`; удалить `PIPELINE=layered` и `shared/entrypoints/middleware.py`
|
||||
- [x] 5.2 Обработчики ошибок: `Unavailable` → `503`, `401` из приложения получает challenge зоны; `/health/ready` пингует БД
|
||||
- [x] 5.3 `main.py`: провайдер `Database` с закрытием пула, связывание журналов без проекций; генератор UUIDv7
|
||||
- [x] 5.4 `gunicorn_conf.py`: `uvicorn_worker.UvicornWorker`, `WEB_CONCURRENCY` воркеров
|
||||
- [x] 5.5 Проверка группы: `make lint`, тест границ зон (импорты и SQL зон), `make student-test` зелёные
|
||||
|
||||
## 6. Стенд
|
||||
|
||||
- [x] 6.1 `compose.yaml`: `postgres` по digest с volume `pgdata` и `pg_isready`, `migrate` на образе приложения, `api` на `127.0.0.1:8080` с healthcheck готовности; compose secrets; процессы не от root
|
||||
- [x] 6.2 `scripts/secrets.sh` (`make secrets`): идемпотентная генерация `secrets/*` и `.env` из `.env.example`; дополнить `.env.example` (`CURSOR_SECRET_FILE`, `WEB_CONCURRENCY`)
|
||||
- [x] 6.3 `scripts/restart.sh`: остановить API, перезапустить PostgreSQL, поднять API (с повторным `migrate`), без удаления volumes
|
||||
- [x] 6.4 Цели `Makefile`: `secrets`, `up`, `down`, `reset-data`, `migrate`, `ps`, `logs`, `restart-evidence`; существующие цели skeleton не меняются
|
||||
- [x] 6.5 CI-job приложения: lint и собственные тесты, затем сборка стенда, `make test` и persistence-тест
|
||||
- [x] 6.6 Проверка группы: из чистого состояния `make secrets up`, `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`, повторный `make migrate` без изменений
|
||||
|
||||
## 7. Отчёт и доказательства
|
||||
|
||||
- [x] 7.1 Сохранить в `evidence/` обезличенные выводы: smoke, persistence с `StartedAt` до и после, `\d+` схемы, повторные миграции, `$argon2id$`-префикс, `git check-ignore`, собственные тесты
|
||||
- [x] 7.2 Заполнить `REPORT.md`: шапка, запуск из чистого clone, архитектура и решения, соответствие переменных, строки уровня «3»
|
||||
- [x] 7.3 Проверка группы: `make check`, `make lint`, `make student-test`, `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh` зелёные
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
schema: spec-driven
|
||||
created: 2026-10-28
|
||||
archived: 2026-10-28
|
||||
lab: 2
|
||||
@@ -0,0 +1,62 @@
|
||||
## Context
|
||||
|
||||
Мотивация — в `proposal.md`. После уровня «3» каждая проверка `Bearer` — запрос `SELECT … FROM sessions WHERE token_hash = $1` к PostgreSQL. Пул, таймауты и перевод сетевых ошибок в `503` уже есть, но не проверены на живом стенде. Изменение касается только зоны `identity` (кэш сессий), стенда и тестов; новой связи между зонами нет.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Valkey с одной ролью — кэш сессий, — которую можно назвать, измерить и сломать без потери данных и без открытия доступа.
|
||||
- Каждый отказ зависимости из рубрики проверяется автотестом против стенда с кодом ответа и временем.
|
||||
- Индекс истории обоснован реальным планом на ≥10 000 сообщений.
|
||||
|
||||
**Non-Goals:**
|
||||
- Кэш истории и списков: read-after-write из контракта дороже, чем экономия.
|
||||
- Valkey как единственное хранилище сессий.
|
||||
- Сравнение вариантов индексов, стоимость записи, backup — трек «5».
|
||||
|
||||
## Decisions
|
||||
|
||||
### D1. Роль Valkey: read-through кэш сессий, PostgreSQL — источник истины
|
||||
|
||||
Порт `SessionDirectory` уже отделяет проверку сессии от хранения. Новый адаптер `CachedSessionDirectory` (`identity/infrastructure/valkey.py`) оборачивает `PostgresSessionDirectory` — паттерн «декоратор» за тем же портом, домен и обработчики не меняются. Ключ — `session:<hex sha256(token)>`, значение — `user_id`, `created_at`, `expires_at`; токен в открытом виде в кэш не попадает.
|
||||
|
||||
- Чтение: `GET`; отметка отзыва → `None` (401); значение → сессия, если `expires_at > now`; промах → PostgreSQL, затем `SET … NX PXAT min(expires_at, now + SESSION_CACHE_TTL_SECONDS)`.
|
||||
- Expiry: `PXAT` от сохранённого `expires_at` (абсолютный срок), а не `EXPIRE ttl` при каждой записи, поэтому повторное заполнение не продлевает сессию. Ограничение `SESSION_CACHE_TTL_SECONDS` (300 с) — страховка: даже при ошибке инвалидации устаревшая запись живёт не дольше пяти минут.
|
||||
- Инвалидация: `CloseSession` сначала пишет отметку отзыва `SET key "-" PXAT expires_at` (перетирая значение), затем удаляет строку в БД. Заполнение идёт только с `NX`, поэтому гонка «читатель достал сессию из БД до удаления и положил её в кэш после» не оживляет токен: его `SET NX` не перетрёт отметку. Если отметку записать нельзя, выход отвечает `503` и строку в БД не трогает — иначе после возвращения Valkey из AOF могла бы ожить закэшированная запись.
|
||||
|
||||
Что получаем: проверка сессии без обращения к БД на горячем пути, `FLUSHALL` безвреден (источник истины цел). Чего стоит: выход зависит от Valkey; ещё один сервис в стенде.
|
||||
|
||||
### D2. Обход недоступного Valkey
|
||||
|
||||
Клиент `redis.asyncio` с таймаутами подключения и чтения 0.2 с и одним немедленным повтором: после рестарта Valkey первая команда на старом соединении падает, повтор идёт уже по новому. Любая ошибка кэша (`RedisError`, `OSError`) на чтении и заполнении глотается: проверка идёт в PostgreSQL. Чтобы не платить таймаут на каждом запросе, простой размыкатель после ошибки пропускает кэш `CACHE_COOLDOWN_SECONDS` (1 с). Запрос при этом не становится анонимным: результат даёт только PostgreSQL, а его отказ — `503`. Готовность от Valkey не зависит: кэш не критичен для обязательного пути.
|
||||
|
||||
### D3. Persistence Valkey
|
||||
|
||||
AOF с `appendfsync always` на volume `valkeydata`: подтверждённая запись отметки отзыва уже на диске, поэтому рестарт или падение Valkey не возвращает закэшированную запись без её отметки. Частота записей низкая (вход, первое чтение сессии, выход), так что fsync на запись не заметен. `everysec` отвергнут: потеря последней секунды могла бы потерять отметку отзыва при живой записи сессии. Пароль `requirepass` лежит в `secrets/valkey.conf`, URL с паролем — в `secrets/cache_url`; процесс Valkey работает от uid 999.
|
||||
|
||||
### D4. Отказ PostgreSQL и пул
|
||||
|
||||
Поведение уже есть с уровня «3»: ленивый пул, `acquire` 1 с, команда 2 с, перевод ошибок в `503`. Здесь оно закрепляется тестами: in-process тест с пулом из одного соединения, занятым тестом, ждёт `503` за время `acquire`; тест стенда останавливает `postgres` и меряет время ответов `/health/ready`, `/users/me` и запроса с неизвестным токеном, затем запускает БД и ждёт восстановления без рестарта API. После остановки PostgreSQL контейнер не имеет DNS-имени, поэтому подключение падает сразу; зависшая БД ограничена таймаутами пула и команды.
|
||||
|
||||
### D5. Экземпляр с коротким TTL
|
||||
|
||||
`api-shortttl` — тот же образ с `SESSION_TTL_SECONDS=2`, один воркер, профиль compose `faults`, порт `127.0.0.1:${SHORTTTL_PORT:-8082}`. Отдельный экземпляр нужен, потому что smoke и persistence требуют TTL ≥300; БД и Valkey общие, что заодно проверяет, что истечение задаёт сессия, а не процесс.
|
||||
|
||||
### D6. Индекс истории и EXPLAIN
|
||||
|
||||
`scripts/sql/seed-history.sql` детерминированно создаёт синтетического пользователя и чат с 20 000 сообщений (`generate_series`, фиксированные UUID, `ON CONFLICT DO NOTHING` — повтор безопасен), `ANALYZE`. `scripts/sql/explain-history.sql` готовит тексты запросов приложения через `PREPARE` и снимает `EXPLAIN (ANALYZE, BUFFERS)` для первой страницы, глубокой keyset-страницы после 10 000-го сообщения и той же страницы через `OFFSET 10000`. Ожидание: keyset — `Index Scan` по `messages_history_idx`, 51 строка; `OFFSET` — тот же индекс, но 10 051 прочитанная строка.
|
||||
|
||||
### D7. Тесты стенда
|
||||
|
||||
`student-tests/stack/` — black-box тесты против поднятого стенда (`BASE_URL`, `SHORTTTL_URL`) с маркером `stack`, по умолчанию исключены из `make student-test`. `make test-faults` поднимает `api-shortttl` и запускает их. Отказы — `docker compose stop/start/restart/exec` подпроцессом; каждый тест возвращает стенд в рабочее состояние в `finally`.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- [Выход недоступен, пока недоступен Valkey] → осознанный выбор строгой инвалидации; ответ `503` честно говорит клиенту, что сессия ещё жива.
|
||||
- [`appendfsync always` замедляет запись при высокой частоте входов] → входы редки, а каждый вход и так стоит Argon2 (~30 мс) — fsync на этом фоне не виден.
|
||||
- [Тесты отказов меняют общий стенд] → каждый тест восстанавливает сервис в `finally` и ждёт готовности.
|
||||
- [Один повтор удваивает время отказа кэша до 0.4 с] → размыкатель платит его не чаще раза в секунду на воркер; потеря заполнения безвредна, потеря отметки отзыва — `503` клиенту.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
Схема БД не меняется. Новый сервис и secrets появляются после `make secrets` (дописывает недостающие файлы) и `make up`. Без `CACHE_URL` приложение работает как на уровне «3».
|
||||
@@ -0,0 +1,34 @@
|
||||
## Why
|
||||
|
||||
Уровень «3» закрыт: состояние и сессии в PostgreSQL. Рубрика «4» `README.md` требует Valkey с конкретной ролью, политикой expiry и инвалидации; ограниченный пул и таймауты; проверенные гонку регистрации и rollback; индекс истории, обоснованный `EXPLAIN (ANALYZE, BUFFERS)` на ≥10 000 сообщений; автоматические проверки expiry, logout, неверного пароля и недоступности Valkey и БД. Изменение закрывает строки уровня 4 таблицы доказательств `REPORT.md` и таблицу отказов.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Появляется сервис `valkey` (8.1.11-alpine по digest, AOF `appendfsync always` на volume `valkeydata`, `requirepass` из secret). Роль — read-through кэш сессий поверх PostgreSQL: запись `session:<sha256>` живёт до `expires_at` сессии (`PXAT`, но не дольше `SESSION_CACHE_TTL_SECONDS`), выход пишет tombstone до удаления строки в БД, заполнение идёт `SET NX` и не перетирает tombstone.
|
||||
- Недоступный Valkey обходится за короткий таймаут с размыкателем: проверка сессии уходит в PostgreSQL, неверный токен по-прежнему `401`. Выход при недоступном кэше отвечает `503`: отзыв подтверждается только тогда, когда он виден и в кэше.
|
||||
- Недоступный PostgreSQL даёт `503 unavailable` за ограниченное время на защищённых endpoint и в `/health/ready`; `/health/live` остаётся `200`; после старта БД пул переподключается без рестарта API. Исчерпание пула — `503` по таймауту ожидания соединения.
|
||||
- Отдельный экземпляр `api-shortttl` (профиль `faults`, `SESSION_TTL_SECONDS=2`, порт `SHORTTTL_PORT`) для автотеста истечения.
|
||||
- Собственные тесты стенда (`make test-faults`): гонка 50 регистраций одного `username`, rollback создания чата, expiry, logout, неверный пароль, остановка и рестарт Valkey, `FLUSHALL`, остановка PostgreSQL — с кодами и временем ответа.
|
||||
- `make seed` (≥10 000 сообщений синтетического чата) и `make explain`: планы `EXPLAIN (ANALYZE, BUFFERS)` первой и глубокой keyset-страницы против `OFFSET`.
|
||||
- `scripts/restart.sh` перезапускает и Valkey.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `lab2-session-cache`: роль Valkey, источник истины, политика expiry и инвалидации, поведение при недоступности, `FLUSHALL` и рестарте кэша.
|
||||
- `lab2-dependency-failures`: ограниченный по времени `503` при отказе PostgreSQL и исчерпании пула, готовность, восстановление без рестарта, запрет анонимного доступа.
|
||||
- `lab2-history-index`: индекс истории, обоснованный планом на ≥10 000 сообщений; страница истории не сканирует всю историю.
|
||||
|
||||
### Modified Capabilities
|
||||
Нет: гонка регистрации и откат создания чата уже записаны требованиями `lab1-messenger-identity` и `lab2-persistent-storage`, здесь добавляются их проверки.
|
||||
|
||||
## Impact
|
||||
|
||||
- Код: `identity/infrastructure/valkey.py`, `identity/config.py`, `identity/entrypoints/ioc.py`; тесты `student-tests/api/test_cache.py`, `student-tests/api/test_pool.py`, `student-tests/stack/`.
|
||||
- Стенд: `compose.yaml` (`valkey`, `api-shortttl`), `scripts/secrets.sh`, `scripts/restart.sh`, `scripts/sql/seed-history.sql`, `scripts/sql/explain-history.sql`, `Makefile`, `.env.example`, CI.
|
||||
- Зависимость: `redis` (клиент `redis.asyncio`, протокол совместим с Valkey).
|
||||
- Отчёт: строки уровня «4», таблица отказов, `evidence/`.
|
||||
|
||||
## Non-goals
|
||||
|
||||
Кэш истории сообщений и списков чатов не вводится: он рисковал бы нарушить read-after-write из контракта, а нагрузка его не требует. Valkey не становится единственным хранилищем сессий. Сравнение нескольких индексов, стоимость записи, backup и restore — трек «5», следующее изменение. Из Out of scope лабы 2 не появляется ничего.
|
||||
+37
@@ -0,0 +1,37 @@
|
||||
## Purpose
|
||||
|
||||
Определяет поведение API при отказе PostgreSQL и при исчерпании пула соединений: ограниченная по времени ошибка `503` вместо зависания, `500` или анонимного доступа, и восстановление без рестарта процесса.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Отказ PostgreSQL даёт ограниченную ошибку
|
||||
|
||||
При недоступном PostgreSQL защищённые endpoint и `/health/ready` SHALL отвечать `503` с кодом `unavailable` в общем формате ошибки быстрее 2 секунд. Проверка сессии, которая не смогла обратиться к БД, SHALL давать `503`, а не `401`, и SHALL NOT пропускать запрос. `/health/live` SHALL отвечать `200`.
|
||||
|
||||
#### Scenario: PostgreSQL остановлен
|
||||
|
||||
- **WHEN** сервис `postgres` остановлен
|
||||
- **THEN** `GET /health/ready` и `GET /api/v1/users/me` отвечают `503 unavailable` быстрее 2 с, `GET /health/live` — `200`, ни один ответ не `500`
|
||||
|
||||
#### Scenario: Неизвестный токен при остановленной БД
|
||||
|
||||
- **WHEN** PostgreSQL остановлен и приходит запрос с неизвестным токеном
|
||||
- **THEN** ответ `503`, а не `200`
|
||||
|
||||
### Requirement: Восстановление без рестарта API
|
||||
|
||||
После возвращения PostgreSQL API SHALL восстанавливать обслуживание без перезапуска своего процесса за счёт переподключения пула.
|
||||
|
||||
#### Scenario: PostgreSQL снова запущен
|
||||
|
||||
- **WHEN** сервис `postgres` запущен после остановки
|
||||
- **THEN** в течение 30 с `/health/ready` отвечает `200`, а прежний токен читает свои данные
|
||||
|
||||
### Requirement: Ограниченный пул соединений
|
||||
|
||||
Каждый процесс API SHALL держать не больше заданного числа соединений с PostgreSQL. Запрос, не получивший соединение за заданное время, SHALL получать `503` и SHALL NOT ждать бесконечно. Все SQL-запросы SHALL быть параметризованными.
|
||||
|
||||
#### Scenario: Пул исчерпан
|
||||
|
||||
- **WHEN** все соединения пула заняты и приходит запрос, требующий БД
|
||||
- **THEN** ответ `503 unavailable` за время ожидания соединения
|
||||
+24
@@ -0,0 +1,24 @@
|
||||
## Purpose
|
||||
|
||||
Определяет, чем обоснован индекс истории сообщений: планом запроса страницы на наборе не меньше 10 000 сообщений и отсутствием полного прохода по истории на каждой странице.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Индекс истории обоснован планом
|
||||
|
||||
Чтение страницы истории SHALL обслуживаться индексом по `(chat_id, created_at, id)` так, что число прочитанных строк и буферов пропорционально `limit`, а не размеру истории чата. Обоснование SHALL быть получено `EXPLAIN (ANALYZE, BUFFERS)` на чате не меньше чем из 10 000 сообщений для первой и для глубокой страницы и сохранено в доказательствах.
|
||||
|
||||
#### Scenario: Первая страница
|
||||
|
||||
- **WHEN** выполняется запрос первой страницы истории с `limit=50` на чате из ≥10 000 сообщений
|
||||
- **THEN** план — `Index Scan` по индексу истории без узла `Sort`, прочитана 51 строка
|
||||
|
||||
#### Scenario: Глубокая страница keyset-курсором
|
||||
|
||||
- **WHEN** выполняется запрос страницы после курсора, указывающего на 10 000-е сообщение
|
||||
- **THEN** план — `Index Scan` с условием по `(created_at, id)`, прочитана 51 строка, без прохода по предыдущим 10 000
|
||||
|
||||
#### Scenario: Сравнение с OFFSET
|
||||
|
||||
- **WHEN** та же глубокая страница запрашивается через `OFFSET 10000`
|
||||
- **THEN** план читает и отбрасывает ≥10 000 строк, что фиксируется рядом с keyset-планом как обоснование выбора курсора
|
||||
+56
@@ -0,0 +1,56 @@
|
||||
## Purpose
|
||||
|
||||
Определяет роль Valkey в лабе 2: read-through кэш сессий поверх PostgreSQL — что в нём лежит, сколько живёт, как инвалидируется при выходе и что происходит при его недоступности, очистке и рестарте.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Кэш сессий поверх источника истины
|
||||
|
||||
Проверка `Bearer`-токена SHALL сначала обращаться к кэшу Valkey по ключу от SHA-256 токена и только при промахе — к PostgreSQL, после чего заполнять кэш. PostgreSQL SHALL оставаться единственным источником истины: в кэш SHALL NOT попадать ничего, чего нет в БД, а запись кэша SHALL NOT жить дольше `expires_at` сессии. Токен в открытом виде SHALL NOT храниться в кэше.
|
||||
|
||||
#### Scenario: Повторная проверка обслуживается кэшем
|
||||
|
||||
- **WHEN** пользователь дважды подряд выполняет `GET /api/v1/users/me` с одним токеном
|
||||
- **THEN** второй запрос находит сессию в Valkey: счётчик попаданий `keyspace_hits` растёт, в кэше есть ключ `session:<sha256>`
|
||||
|
||||
#### Scenario: Срок записи кэша не превышает срок сессии
|
||||
|
||||
- **WHEN** сессия закэширована
|
||||
- **THEN** абсолютный срок жизни ключа (`PEXPIRETIME`) не позже `expires_at` сессии
|
||||
|
||||
### Requirement: Выход инвалидирует кэш
|
||||
|
||||
Отзыв сессии SHALL записывать в кэш отметку отзыва на оставшийся срок сессии до удаления строки в БД, а заполнение кэша после промаха SHALL выполняться только при отсутствии ключа. Отозванный токен SHALL получать `401` и при гонке «чтение заполнило кэш после выхода». Если отметку отзыва записать нельзя, выход SHALL отвечать `503` и SHALL NOT удалять сессию.
|
||||
|
||||
#### Scenario: Отозванный токен не оживает из кэша
|
||||
|
||||
- **WHEN** токен закэширован, после чего пользователь выполняет `DELETE /api/v1/auth/sessions/current`
|
||||
- **THEN** ответ `204`, а следующий запрос с этим токеном получает `401`
|
||||
|
||||
#### Scenario: Выход при недоступном кэше
|
||||
|
||||
- **WHEN** Valkey остановлен и пользователь выполняет `DELETE /api/v1/auth/sessions/current`
|
||||
- **THEN** ответ `503` с кодом `unavailable`, а после запуска Valkey повторный выход отвечает `204`
|
||||
|
||||
### Requirement: Недоступный кэш обходится, но не открывает доступ
|
||||
|
||||
При ошибке или таймауте Valkey проверка сессии SHALL выполняться по PostgreSQL за ограниченное время, а повторные попытки обращения к кэшу SHALL приостанавливаться на короткий интервал. Недействительный токен SHALL получать `401`; запрос SHALL NOT приниматься как анонимный. Недоступность Valkey SHALL NOT переводить `/health/ready` в `503`.
|
||||
|
||||
#### Scenario: Valkey остановлен
|
||||
|
||||
- **WHEN** сервис `valkey` остановлен
|
||||
- **THEN** `GET /api/v1/users/me` с действительным токеном отвечает `200` быстрее 1 с, с неизвестным токеном — `401`, `/health/ready` — `200`, вход по `Basic` — `201`
|
||||
|
||||
### Requirement: Очистка и рестарт кэша безопасны
|
||||
|
||||
Потеря содержимого Valkey (`FLUSHALL`, рестарт без данных) SHALL NOT терять сессии и SHALL NOT оживлять отозванные. Valkey SHALL хранить данные с AOF на именованном volume, чтобы рестарт сохранял тёплый кэш и отметки отзыва.
|
||||
|
||||
#### Scenario: FLUSHALL
|
||||
|
||||
- **WHEN** в Valkey выполнен `FLUSHALL`
|
||||
- **THEN** действующий токен получает `200`, отозванный — `401`
|
||||
|
||||
#### Scenario: Рестарт Valkey
|
||||
|
||||
- **WHEN** сервис `valkey` перезапущен
|
||||
- **THEN** ключи сессий на месте, действующий токен получает `200`, отозванный — `401`
|
||||
@@ -0,0 +1,38 @@
|
||||
## 1. Кэш сессий (зона `identity`)
|
||||
|
||||
- [x] 1.1 Добавить зависимость `redis`; настройки `CACHE_URL`, `SESSION_CACHE_TTL_SECONDS`, `CACHE_TIMEOUT_SECONDS`, `CACHE_COOLDOWN_SECONDS` в `IdentitySettings`
|
||||
- [x] 1.2 Адаптер `CachedSessionDirectory`: чтение с отметкой отзыва, заполнение `SET NX PXAT`, инвалидация отметкой с `503` при отказе, размыкатель
|
||||
- [x] 1.3 Провайдер DI: кэш подключается при заданном `CACHE_URL`, клиент закрывается вместе с контейнером
|
||||
- [x] 1.4 Проверка группы: in-process тесты против одноразового Valkey — попадание в кэш, срок ключа не позже `expires_at`, выход оставляет отметку, гонка заполнения после выхода, обход недоступного кэша, `503` выхода без кэша
|
||||
|
||||
## 2. Отказы PostgreSQL и пул
|
||||
|
||||
- [x] 2.1 In-process тест исчерпания пула: пул из одного занятого соединения → `503` за время ожидания
|
||||
- [x] 2.2 Проверка группы: `make student-test` зелёный
|
||||
|
||||
## 3. Стенд
|
||||
|
||||
- [x] 3.1 `compose.yaml`: `valkey` по digest (uid 999, AOF `always`, volume `valkeydata`, healthcheck с паролем), `CACHE_URL_FILE` в API, `api-shortttl` в профиле `faults`
|
||||
- [x] 3.2 `scripts/secrets.sh` дописывает `valkey.conf` и `cache_url`; `scripts/restart.sh` перезапускает и Valkey; `.env.example` — `SHORTTTL_PORT`
|
||||
- [x] 3.3 Проверка группы: `make up`, `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`
|
||||
|
||||
## 4. Тесты стенда
|
||||
|
||||
- [x] 4.1 `student-tests/stack/`: фикстуры `BASE_URL`/`SHORTTTL_URL`, вызовы `docker compose`, маркер `stack` вне набора по умолчанию
|
||||
- [x] 4.2 Гонка 50 регистраций одного `username` (1×201 + 49×409, одна строка в БД) и rollback чата с неизвестным участником (строк нет)
|
||||
- [x] 4.3 Expiry на `api-shortttl`, logout и повторный logout, неверный пароль и неизвестный пользователь
|
||||
- [x] 4.4 Остановка и рестарт Valkey, `FLUSHALL`, кэш реально используется (`keyspace_hits`)
|
||||
- [x] 4.5 Остановка PostgreSQL: `503` быстрее 2 с, `live` 200, восстановление без рестарта API
|
||||
- [x] 4.6 Цель `make test-faults`; проверка группы: прогон зелёный, вывод сохранён в `evidence/faults.txt`
|
||||
|
||||
## 5. Индекс истории
|
||||
|
||||
- [x] 5.1 `scripts/sql/seed-history.sql` и `make seed`: 20 000 сообщений синтетического чата, повтор безопасен
|
||||
- [x] 5.2 `scripts/sql/explain-history.sql` и `make explain`: первая и глубокая keyset-страница против `OFFSET` → `evidence/explain-history.txt`
|
||||
- [x] 5.3 Проверка группы: в планах `Index Scan using messages_history_idx`, 51 строка у keyset, ≥10 000 у `OFFSET`
|
||||
|
||||
## 6. Отчёт
|
||||
|
||||
- [x] 6.1 Нагрузка `tests/load.py --concurrency 64`: без `500`, ошибки и задержки в `evidence/load.json`
|
||||
- [x] 6.2 `REPORT.md`: роль Valkey, источник истины, expiry и инвалидация, persistence, пул и таймауты, строки уровня «4», таблица отказов
|
||||
- [x] 6.3 Проверка группы: `make check`, `make lint`, `make student-test`, `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`, `make test-faults` зелёные
|
||||
@@ -0,0 +1,4 @@
|
||||
schema: spec-driven
|
||||
created: 2026-10-28
|
||||
archived: 2026-10-28
|
||||
lab: 3
|
||||
@@ -0,0 +1,83 @@
|
||||
## Context
|
||||
|
||||
Мотивация — в `proposal.md`. После уровня «3» стенд — HAProxy 3.2 и сервис `api` с двумя репликами, проверка `GET /health/ready` (`inter 1s fastinter 500ms fall 2 rise 2`, `timeout check 1s`), Docker DNS, повтор на соседнюю реплику только для безопасных запросов. Обвязка уровня «4» (k6, режимы зонда `load`/`detect`, поочерёдный отказ, rolling update) проверена в `.prep` на заглушке и встраивается, а не пишется заново. Чего заготовка доказать не могла — поведение настоящего gunicorn при `SIGTERM`: по сигналу он сразу закрывает listener, и запрос, уже попавший в очередь `accept` закрывающегося сокета, балансировщик видит как обрыв после отправки. Для `GET` и сообщений с ключом это повтор на соседа, для `POST /users`, `/chats` и входа — `502`.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Плановая остановка реплики не порождает ни ошибок, ни повторов балансировщика: реплика уходит из ротации раньше, чем перестаёт принимать соединения.
|
||||
- Период проверок и максимум обнаружения заявлены формулой и подтверждены замером по каждому виду отказа.
|
||||
- Каждый пункт рубрики «4» проверяется одной командой `make`, которая пишет файл в `evidence/` и завершается ненулевым кодом при нарушении.
|
||||
|
||||
**Non-Goals:**
|
||||
- Серии 1/2/4 реплик и поиск насыщения — трек «5».
|
||||
- Изменение схемы БД, доменных зон и контракта.
|
||||
|
||||
## Decisions
|
||||
|
||||
### D1. Вывод из ротации по `SIGTERM` (платформа)
|
||||
|
||||
`gunicorn_conf.MessengerWorker` запускает `DrainingServer` — наследника `uvicorn.Server`, у которого `main_loop` после сигнала остановки ставит флаг `DRAINING` и ждёт `DRAIN_SECONDS`, а уже потом штатный `shutdown` закрывает listener и ждёт принятые запросы. Флаг — `threading.Event` в `shared/entrypoints/health.py`; `/health/ready` при поднятом флаге отвечает `503 unavailable` через обычный реестр ошибок (с `X-Request-Id` и `X-Instance-Id`), `/health/live` — `200`. Каждый воркер получает `SIGTERM` от мастера и поднимает свой флаг; проверка LB попадает в любой воркер и видит `503`.
|
||||
|
||||
Сроки: `DRAIN_SECONDS=2` > максимум обнаружения `503` (`inter + (fall−1)·fastinter` = 1,5 с); uvicorn `timeout_graceful_shutdown = SHUTDOWN_TIMEOUT_SECONDS − DRAIN_SECONDS` = 3 с ≥ ожидание соединения 1 с + `statement_timeout` 2 с; gunicorn `graceful_timeout = SHUTDOWN_TIMEOUT_SECONDS` = 5 с < `docker stop -t 6` в хуке < `stop_grace_period: 8s` < 10 с.
|
||||
|
||||
Что получаем: LB исключает реплику, пока она полностью исправна, и к моменту закрытия listener новых соединений нет — нет ни обрывов, ни повторов (`wretr`/`wredis` в статистике LB). Чего стоит: каждая остановка реплики дольше на 2 с (хук ≈2,5 с вместо 0,7 с), и переопределён приватный `UvicornWorker._serve` — четыре строки, которые придётся сверять при обновлении `uvicorn-worker`. Отвергнуто: shell-обёртка с `trap` в роли PID 1 (ломает прямую доставку сигнала процессу сервера, требование лабы 1); `preStop`-аналога в Compose нет; пауза в хуке до `docker stop` (не защищает `docker compose stop`, `restart.sh` и rolling update).
|
||||
|
||||
### D2. Readiness быстрее проверки LB
|
||||
|
||||
`Database.ping` берёт соединение с таймаутом 0,4 с и выполняет `SELECT 1` с таймаутом 0,4 с: худший ответ 0,8 с < `timeout check 1s`. Раньше пинг мог ждать пул 1 с и запрос ещё 1 с, и при занятом пуле LB видел таймаут проверки вместо явного `503`. Остальные запросы сохраняют свои таймауты.
|
||||
|
||||
### D2a. Возврат в ротацию только после проверок
|
||||
|
||||
Найдено первым прогоном `failover-each`: ошибок не было, но `wredis` в статистике LB был 19 и 49. Журнал HAProxy показал, что слот `server-template`, вышедший из `MAINT (resolution)`, когда остановленный контейнер снова появился в DNS, сразу становится `UP/READY (resolves again)` — до проверок. Запросы шли в ещё не слушающий gunicorn и перенаправлялись на соседа. `default-server … init-state fully-down` (HAProxy ≥ 3.1) делает начальное состояние сервера при старте, появлении через DNS и выходе из обслуживания `DOWN` до `rise 2` успешных проверок. Что получаем: новая и возвращённая реплика не получает трафика раньше готовности, повторов 0. Чего стоит: возврат в ротацию дольше на ≈1 с (две проверки), и старт LB ждёт первых проверок.
|
||||
|
||||
### D3. Цепочка таймаутов — тест, а не только таблица
|
||||
|
||||
| Звено | Значение | Условие |
|
||||
| --- | --- | --- |
|
||||
| LB `timeout server` | 10 с | > `REQUEST_TIMEOUT_SECONDS` |
|
||||
| `REQUEST_TIMEOUT_SECONDS` | 8 с | > `DB_ACQUIRE_TIMEOUT_SECONDS` + `DB_COMMAND_TIMEOUT_SECONDS` |
|
||||
| БД: ожидание соединения + оператор/блокировка | 1 + 2 с | ≤ окна дообработки 3 с |
|
||||
| LB `timeout check` | 1 с | > пинга readiness 0,8 с |
|
||||
| `DRAIN_SECONDS` | 2 с | > `inter + (fall−1)·fastinter` |
|
||||
| `SHUTDOWN_TIMEOUT_SECONDS` | 5 с | > `DRAIN_SECONDS`; < `STOP_TIMEOUT` хука |
|
||||
| `STOP_TIMEOUT` хука | 6 с | < `stop_grace_period` 8 с и < 10 с |
|
||||
| LB `hard-stop-after` | 5 с | < `stop_grace_period` LB 8 с |
|
||||
|
||||
Таймауты API (`DRAIN_SECONDS`, `DB_*`) становятся явными переменными `compose.yaml` со значениями по умолчанию. Тест `student-tests/unit/test_timeouts.py` читает умолчания из `compose.yaml` (PyYAML уже есть в зависимостях uvicorn), параметры из `haproxy.cfg` и `scripts/stop-one.sh` и проверяет все неравенства. Второй тест запускает настоящий gunicorn с тестовой БД, шлёт `SIGTERM` и проверяет D1: `503` на ready и `200` на live в окне, затем закрытый порт и код 0.
|
||||
|
||||
### D4. Измерения: `probe.py load` и `detect`
|
||||
|
||||
`load` — из заготовки: k6 open model (`constant-arrival-rate`, 80 % `POST` сообщения с уникальным ключом, 20 % чтения истории) в сети `edge` бьёт в `lb:8080`, параллельно зонд шлёт сообщение каждые 0,1 с и повторяет тот же ключ после ошибки, а опрос статистики LB 10 раз в секунду пишет число `UP`. Действие стартует через `warmup + lead`. Дополнено: вывод действия в `action.txt` (а не `.log`: `*.log` в `.gitignore`); дельта счётчиков backend `api` (`wretr`, `wredis`, `econ`, `eresp`, `hrsp_5xx`); режим `--expect dip` (реплика выпадает и возвращается: обнаружение, возврат, реплики в окне отказа) и `--expect replace` (минимум `UP` не ниже исходного, после действия только новые реплики); поле `pass` и код выхода по проверкам.
|
||||
|
||||
`detect` переписан: действие запускается фоном, опрос LB идёт одновременно, поэтому для `SIGTERM` видно, что исключение случилось раньше конца хука. Параметры: `--max`, `--until` (сколько `UP` считать отказом, для PostgreSQL — 0), `--within-action`, `--lb-status` (код ответа LB после обнаружения), `--restore` (команда возврата и время до исходного числа `UP`).
|
||||
|
||||
`scripts/detection.sh` — четыре сценария подряд с возвратом между ними: `stop-one.sh` (≤1,5 с и внутри хука), `docker kill` (≤1,5 с), `docker pause` (≤3,5 с), `docker compose stop postgres` (0 `UP` ≤ 1,5 с после остановки, LB `503`). `scripts/failover-each.sh` — по каждой реплике `stop-one.sh`, 10 с без неё, `restore.sh`, всё внутри окна нагрузки.
|
||||
|
||||
### D5. Серия гонок одного ключа
|
||||
|
||||
`probe.py check --rounds 20`: на каждый раунд новый ключ и 8 потоков за барьером; сводка — статусы и реплики по всем раундам, число раундов с одинаковыми телами, с одной копией в истории и с `409` на другой body.
|
||||
|
||||
### D6. Лимиты и изоляция — проверка политики
|
||||
|
||||
`scripts/limits.py` сравнивает `docker compose --profile bench config --format json` и `docker inspect` запущенных контейнеров с политикой в самом скрипте: какие секреты, volumes и сети нужны каждому сервису, у кого есть порты (только `lb`, только `127.0.0.1`), есть ли лимиты CPU/RAM, `container_name`, `read_only` у API. Таблица и нарушения — в `evidence/limits.txt`, код 1 при нарушении.
|
||||
|
||||
### D7. Rolling update с запасом +1
|
||||
|
||||
`scripts/rolling-update.sh` из заготовки: `migrate` один раз, затем для каждой старой реплики `up --no-deps --no-recreate --scale api=N+1` → `healthy` → LB видит N+1 `UP` → `docker stop -t 6` (с окном D1) и `rm` старой. Журнал называет hostname и образ старой и новой реплики. `make rolling-update` собирает образ до начала нагрузки (сборка не искажает замер); `FROM_REV=<коммит>` сначала собирает тот же тег из `git archive <коммит>` и пересоздаёт реплики на нём — так демонстрируется обновление с уровня «3» (без D1) на уровень «4». Схема между ними не меняется; совместимость `0002` с кодом лабы 2 следует из того, что она только добавляет таблицу (D4 change уровня «3»).
|
||||
|
||||
### D8. Генератор нагрузки
|
||||
|
||||
Сервис `k6` (`grafana/k6:2.3.0` по digest) под профилем `bench`: не стартует с `make up`, сеть только `edge`, лимиты 2 CPU / 512m, без секретов; `scripts/k6.sh` запускает его `docker compose run` от uid хоста, чтобы `summary.json` записывался и на Linux. `handleSummary` удаляет `setup_data` с токенами синтетических пользователей.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- [Окно вывода из ротации удлиняет остановку] → +2 с на реплику в `stop-one.sh`, `restart.sh`, `docker compose down`; бюджеты хука (10 с) и persistence (90 с) не затронуты.
|
||||
- [Флаг вывода из ротации на воркер, а не на контейнер] → мастер шлёт `SIGTERM` всем воркерам одновременно; воркер, перезапущенный мастером во время остановки, не появляется — мастер в остановке новых не порождает.
|
||||
- [Числа нагрузки зависят от Docker Desktop на одном хосте] → цель уровня «4» — отсутствие ошибок и время обнаружения, а не потолок RPS; потолок — трек «5».
|
||||
- [Rolling update меняет только образ] → изменение схемы проверено отдельно (аддитивная `0002`); миграция, ломающая старую версию, потребовала бы двух выпусков (expand/contract), это записано в ограничениях.
|
||||
- [LB и PostgreSQL — по-прежнему единственные точки отказа] → вне рамок лабы, остаётся в ограничениях отчёта.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
Схема не меняется. Новый образ совместим со старым стендом: при rolling update со старой версии старые реплики останавливаются без окна (видно по `wredis` > 0), новые — с окном.
|
||||
@@ -0,0 +1,34 @@
|
||||
## Why
|
||||
|
||||
Уровень «3» показал, что отказ реплики переживается, но не за сколько LB его замечает и что происходит под нагрузкой и при плановой замене. Рубрика «4» `README.md` требует согласованных проверок, таймаутов и остановки по `SIGTERM` с заявленными периодом и максимумом обнаружения, поочерёдного отказа каждой реплики под нагрузкой с RPS, ошибками и временем восстановления, параллельной проверки одного ключа, лимитов и изоляции портов и секретов, rolling update под нагрузкой с однократными совместимыми миграциями. Закрывает строки 4.1–4.4 `REPORT.md`.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Остановка реплики по `SIGTERM` начинается с вывода из ротации: `/health/ready` отвечает `503`, пока балансировщик не исключит реплику (`DRAIN_SECONDS=2` больше максимума обнаружения 1,5 с), и только потом процесс перестаёт принимать соединения и дорабатывает принятые запросы. Общий срок остаётся `SHUTDOWN_TIMEOUT_SECONDS=5` < `docker stop -t 6` < `stop_grace_period: 8s`.
|
||||
- Readiness отвечает быстрее `timeout check` балансировщика: пинг PostgreSQL ограничен 0,4 с на соединение и 0,4 с на запрос.
|
||||
- Цепочку таймаутов проверяет тест по `compose.yaml`, `haproxy.cfg` и хуку.
|
||||
- `make detection`: время обнаружения для `SIGTERM`, `SIGKILL`, зависшего процесса и остановки PostgreSQL, с заявленным максимумом.
|
||||
- `make failover-each`: каждая реплика по очереди останавливается и возвращается под нагрузкой k6; RPS, ошибки, обнаружение, восстановление, счётчики повторов LB.
|
||||
- `make lb-check`: 20 раундов по 8 параллельных `POST` с одним ключом через LB.
|
||||
- `make limits`: лимиты всех сервисов, порты только у `lb`, секреты, volumes и сети по принципу необходимости, нет `container_name`.
|
||||
- `make rolling-update`: замена реплик по одной с запасом +1 под нагрузкой, `migrate` один раз до замены; `FROM_REV` поднимает прежнюю версию из Git для настоящего обновления.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `lab3-failover-operations`: период и максимум обнаружения, поочерёдный отказ под нагрузкой, параллельная идемпотентность через LB, лимиты и изоляция, rolling update и однократные миграции.
|
||||
|
||||
### Modified Capabilities
|
||||
- `lab1-service-operability`: «Корректное завершение по сигналу» — сначала вывод из ротации, затем закрытие приёма.
|
||||
- `lab2-dependency-failures`: «Отказ PostgreSQL даёт ограниченную ошибку» — балансировщик исключает все реплики и сам отвечает `503`.
|
||||
|
||||
## Impact
|
||||
|
||||
- Код: платформа (`gunicorn_conf.py`, `shared/entrypoints/health.py`, пинг в `shared/infrastructure/postgres.py`); доменные зоны не меняются.
|
||||
- Стенд: `compose.yaml` (`k6` под профилем `bench`, явные таймауты API), `infra/k6/messages.js`, `scripts/` (`probe.py load|detect`, `detection.sh`, `failover-each.sh`, `rolling-update.sh`, `k6.sh`, `limits.py`), `Makefile`, CI.
|
||||
- Тесты: остановка gunicorn, цепочка таймаутов, отказ PostgreSQL через LB.
|
||||
- Отчёт: строки 4.1–4.4, таблица обнаружения и отказов, `evidence/`.
|
||||
|
||||
## Non-goals
|
||||
|
||||
Серии 1/2/4 реплик и поиск насыщения — трек «5», следующее изменение. Схема БД не меняется. Из Out of scope ничего: Swarm, HA PostgreSQL и LB, alias реплики (лаба 7).
|
||||
+21
@@ -0,0 +1,21 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Корректное завершение по сигналу
|
||||
|
||||
По получении `SIGTERM` сервис SHALL сначала выйти из ротации: на время окна `DRAIN_SECONDS` (по умолчанию 2 с, больше максимального времени обнаружения балансировщиком) `/health/ready` SHALL отвечать `503 unavailable`, а принятые и новые запросы SHALL обслуживаться как обычно. После окна сервис SHALL перестать принимать новые соединения, дождаться завершения принятых запросов и завершить процесс; весь срок, включая окно, SHALL укладываться в `SHUTDOWN_TIMEOUT_SECONDS` (по умолчанию 5 с), который меньше таймаута хука остановки, `stop_grace_period` контейнера и 10 секунд, чтобы контейнер не убивался по таймауту. Процесс сервера SHALL быть основным процессом контейнера и SHALL получать сигналы напрямую.
|
||||
|
||||
#### Scenario: Остановка укладывается в срок
|
||||
|
||||
- **WHEN** запущенному контейнеру послан `SIGTERM`
|
||||
- **THEN** процесс завершается не позднее чем через 10 секунд и раньше `stop_grace_period`
|
||||
- **AND** код завершения соответствует штатной остановке, а не убийству по таймауту
|
||||
|
||||
#### Scenario: Сначала вывод из ротации
|
||||
|
||||
- **WHEN** процессу сервера послан `SIGTERM`
|
||||
- **THEN** в течение окна `DRAIN_SECONDS` `/health/ready` отвечает `503` в общем формате ошибки, `/health/live` — `200`, соединения ещё принимаются, а после окна порт закрыт и процесс завершается с кодом 0 не позднее `SHUTDOWN_TIMEOUT_SECONDS`
|
||||
|
||||
#### Scenario: Принятый запрос дорабатывается
|
||||
|
||||
- **WHEN** `SIGTERM` приходит во время обработки принятого запроса
|
||||
- **THEN** этот запрос получает ответ до завершения процесса
|
||||
+21
@@ -0,0 +1,21 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Отказ PostgreSQL даёт ограниченную ошибку
|
||||
|
||||
При недоступном PostgreSQL защищённые endpoint и `/health/ready` каждой реплики SHALL отвечать `503` с кодом `unavailable` в общем формате ошибки быстрее 2 секунд. Проверка сессии, которая не смогла обратиться к БД, SHALL давать `503`, а не `401`, и SHALL NOT пропускать запрос. `/health/live` реплики SHALL отвечать `200`. Балансировщик SHALL исключить все реплики из ротации не позднее чем через 1,5 с после отказа и SHALL сам отвечать на любой запрос `503` в общем формате ошибки с `request_id`, равным `X-Request-Id`; после возвращения PostgreSQL реплики SHALL вернуться в ротацию без перезапуска.
|
||||
|
||||
#### Scenario: PostgreSQL остановлен
|
||||
|
||||
- **WHEN** сервис `postgres` остановлен
|
||||
- **THEN** `GET /health/ready` и `GET /api/v1/users/me` через LB отвечают `503 unavailable` быстрее 2 с, `GET /health/live` внутри реплики — `200`, ни один ответ не `500`
|
||||
|
||||
#### Scenario: Неизвестный токен при остановленной БД
|
||||
|
||||
- **WHEN** PostgreSQL остановлен и приходит запрос с неизвестным токеном
|
||||
- **THEN** ответ `503`, а не `200`
|
||||
|
||||
#### Scenario: Балансировщик исключает все реплики
|
||||
|
||||
- **WHEN** PostgreSQL остановлен дольше времени обнаружения
|
||||
- **THEN** статистика LB показывает 0 готовых реплик, а запрос через LB, включая `GET /health/live`, получает `503 {"error":{"code":"unavailable",...}}` без `X-Instance-Id`
|
||||
- **AND** после запуска PostgreSQL все реплики снова готовы в LB без перезапуска своих процессов
|
||||
+85
@@ -0,0 +1,85 @@
|
||||
## Purpose
|
||||
|
||||
Определяет эксплуатационные гарантии реплицированного стенда: за какое время балансировщик исключает отказавшую реплику, как переживается поочерёдный отказ и плановая замена реплик под нагрузкой, как проверяется общая идемпотентность параллельными запросами и как ограничены ресурсы, порты, секреты и хранилища.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Согласованные проверки, таймауты и остановка
|
||||
|
||||
Балансировщик SHALL проверять каждую реплику `GET /health/ready` с периодом 1 с, после первого провала — каждые 0,5 с, исключать её после 2 провалов подряд и возвращать после 2 успехов. Реплика, которая появилась или вернулась через DNS (запуск, `restore.sh`, новая реплика rolling update), SHALL получать запросы только после 2 успешных проверок, а не сразу после появления адреса. Максимальное время обнаружения SHALL составлять 1,5 с для реплики, которая отвечает `503` или отказывает в соединении, и 3,5 с для зависшей реплики (с таймаутом проверки 1 с). Readiness реплики SHALL отвечать быстрее таймаута проверки. Цепочка таймаутов SHALL убывать от внешнего звена к внутреннему: ожидание ответа балансировщиком > таймаут запроса в приложении > таймаут оператора и ожидания соединения с БД. Срок остановки реплики SHALL укладываться в таймаут хука остановки, а тот — в `stop_grace_period` и в 10 с.
|
||||
|
||||
#### Scenario: Конфигурация согласована
|
||||
|
||||
- **WHEN** выполняется `make student-test`
|
||||
- **THEN** тест цепочки таймаутов по `compose.yaml`, `infra/haproxy/haproxy.cfg` и `scripts/stop-one.sh` проходит: окно вывода из ротации больше максимума обнаружения, срок остановки меньше таймаута хука, таймаут хука меньше `stop_grace_period` и 10 с, `timeout server` балансировщика больше `REQUEST_TIMEOUT_SECONDS`, а тот больше суммы таймаутов БД
|
||||
|
||||
#### Scenario: Обнаружение измерено по каждому виду отказа
|
||||
|
||||
- **WHEN** выполняется `make detection`
|
||||
- **THEN** для `SIGTERM` через `scripts/stop-one.sh`, `docker kill`, `docker pause` и остановки PostgreSQL в `evidence/detection/*.json` записаны время обнаружения, заявленный максимум и время возврата в ротацию, и каждое время обнаружения не больше заявленного максимума
|
||||
|
||||
#### Scenario: Остановка по сигналу не теряет запросы
|
||||
|
||||
- **WHEN** реплике посылается `SIGTERM` через `scripts/stop-one.sh`
|
||||
- **THEN** балансировщик исключает её раньше, чем хук завершился, а реплика закрывает приём соединений только после этого
|
||||
|
||||
#### Scenario: Возврат реплики без преждевременного трафика
|
||||
|
||||
- **WHEN** остановленная реплика запускается снова под нагрузкой
|
||||
- **THEN** балансировщик не направляет на неё запросы, пока она не прошла 2 проверки готовности: счётчики повторов и перенаправлений LB (`wretr`, `wredis`) за прогон равны 0
|
||||
|
||||
#### Scenario: Зависшая реплика
|
||||
|
||||
- **WHEN** процесс реплики приостановлен (`docker pause`) и не отвечает на проверки
|
||||
- **THEN** балансировщик исключает её не позднее чем через 3,5 с, а после `docker unpause` возвращает в ротацию
|
||||
|
||||
### Requirement: Поочерёдный отказ под нагрузкой
|
||||
|
||||
Оператор SHALL одной командой останавливать каждую реплику по очереди под открытой нагрузкой (постоянная интенсивность запросов, 80 % отправок сообщений и 20 % чтений истории) и возвращать её до остановки следующей. Для каждой реплики SHALL фиксироваться интенсивность и доля ошибок нагрузки, задержки p50/p95/p99, время обнаружения, время возврата в ротацию, ошибки и время восстановления записи зонда, повторяющего неудачную запись с тем же ключом, и счётчики повторов и перенаправлений балансировщика.
|
||||
|
||||
#### Scenario: Каждая реплика по очереди
|
||||
|
||||
- **WHEN** выполняется `make failover-each`
|
||||
- **THEN** `evidence/failover-each/summary.json` содержит запись на каждую реплику; в каждой хук завершился кодом 0, доля ошибок нагрузки не больше 1 %, запись восстановилась не позже 10 с, пока реплика была исключена, её `X-Instance-Id` не встречался, а после возврата она снова обслуживает запросы
|
||||
|
||||
### Requirement: Общая идемпотентность под параллельными запросами
|
||||
|
||||
Параллельные `POST /api/v1/chats/{chat_id}/messages` с одним `Idempotency-Key` и одним телом, распределённые балансировщиком по разным репликам, SHALL создавать ровно одно сообщение и SHALL получать одинаковые ответы `201`; тот же ключ с другим телом SHALL получать `409`.
|
||||
|
||||
#### Scenario: Серия гонок через LB
|
||||
|
||||
- **WHEN** выполняется `make lb-check` (20 раундов по 8 параллельных запросов с одним ключом на раунд)
|
||||
- **THEN** все 160 ответов `201`, их обслужили не менее двух реплик, в каждом раунде тела ответов совпадают, в истории ровно одна копия, а другой body получает `409`
|
||||
|
||||
### Requirement: Лимиты и изоляция
|
||||
|
||||
Каждый сервис стенда, включая генератор нагрузки, SHALL иметь лимиты CPU и памяти. Ни один сервис SHALL NOT задавать `container_name`. Опубликованные порты SHALL быть только у балансировщика и только на `127.0.0.1`. Секреты SHALL монтироваться только сервисам, которые ими пользуются; volumes данных SHALL принадлежать только своему хранилищу; реплики API SHALL работать с корневой файловой системой только для чтения; внутренняя сеть SHALL быть недоступна снаружи, а генератор нагрузки SHALL видеть только балансировщик.
|
||||
|
||||
#### Scenario: Проверка лимитов и изоляции
|
||||
|
||||
- **WHEN** выполняется `make limits`
|
||||
- **THEN** проверка по `docker compose config` и `docker inspect` запущенных контейнеров печатает таблицу сервисов с лимитами, портами, секретами, volumes и сетями в `evidence/limits.txt` и завершается `PASS`; ни у одного контейнера `api` нет опубликованных портов
|
||||
|
||||
#### Scenario: Нарушение политики
|
||||
|
||||
- **WHEN** сервису без необходимости добавлен секрет, порт или `container_name`, либо снят лимит
|
||||
- **THEN** `make limits` перечисляет нарушение и завершается ненулевым кодом
|
||||
|
||||
### Requirement: Поочерёдная замена под нагрузкой и однократные миграции
|
||||
|
||||
Оператор SHALL одной командой заменять реплики новой версией образа по одной: сначала миграции применяются один раз отдельным процессом, затем на каждую старую реплику запускается новая, и старая останавливается только после того, как балансировщик видит новую готовой. Число готовых реплик в балансировщике SHALL NOT опускаться ниже исходного. Миграции SHALL быть совместимы с работающей предыдущей версией (только добавление объектов схемы) либо ограничение SHALL быть описано в `REPORT.md`.
|
||||
|
||||
#### Scenario: Замена под нагрузкой
|
||||
|
||||
- **WHEN** выполняется `make rolling-update`
|
||||
- **THEN** `evidence/rolling/result.json` показывает, что балансировщик ни разу не видел меньше исходного числа готовых реплик, доля ошибок нагрузки не больше 1 %, зонд не потерял записей, а после замены запросы обслуживают только новые контейнеры
|
||||
|
||||
#### Scenario: Обновление с прежней версии
|
||||
|
||||
- **WHEN** выполняется `make rolling-update FROM_REV=<коммит>`
|
||||
- **THEN** стенд сначала поднимается на образе, собранном из этого коммита, а затем заменяется текущей версией с теми же гарантиями; журнал замены называет старый и новый образ каждой реплики
|
||||
|
||||
#### Scenario: Миграции один раз
|
||||
|
||||
- **WHEN** идёт поочерёдная замена
|
||||
- **THEN** `migrate` запускается один раз до замены первой реплики, реплики схему не меняют, а повторный запуск сообщает `up to date`
|
||||
@@ -0,0 +1,35 @@
|
||||
## 1. Остановка и готовность (платформа)
|
||||
|
||||
- [x] 1.1 `DRAINING` в `shared/entrypoints/health.py`: `/health/ready` отвечает `503 unavailable`, пока флаг поднят
|
||||
- [x] 1.2 `DrainingServer` и `MessengerWorker._serve` в `gunicorn_conf.py`: окно `DRAIN_SECONDS`, затем штатная остановка; uvicorn дообрабатывает `SHUTDOWN_TIMEOUT_SECONDS − DRAIN_SECONDS`
|
||||
- [x] 1.3 Пинг readiness: 0,4 с на соединение и 0,4 с на запрос
|
||||
- [x] 1.4 Проверка группы: тесты — ready `503` при флаге и live `200`; настоящий gunicorn по `SIGTERM` держит окно, закрывает порт и выходит с кодом 0 за срок
|
||||
|
||||
## 2. Стенд и таймауты
|
||||
|
||||
- [x] 2.1 `compose.yaml`: явные `DRAIN_SECONDS`, `DB_ACQUIRE_TIMEOUT_SECONDS`, `DB_COMMAND_TIMEOUT_SECONDS` у `api`; сервис `k6` под профилем `bench`; `.env.example`, Dockerfile
|
||||
- [x] 2.2 Тест цепочки таймаутов по `compose.yaml`, `haproxy.cfg` и `scripts/stop-one.sh`
|
||||
- [x] 2.3 HAProxy `init-state fully-down`: вернувшаяся через DNS реплика ждёт `rise 2` проверок
|
||||
- [x] 2.4 Проверка группы: `docker compose --profile bench config --quiet`, `make student-test -k "timeouts or drain"`
|
||||
|
||||
## 3. Нагрузка и зонд
|
||||
|
||||
- [x] 3.1 `infra/k6/messages.js`, `scripts/k6.sh` (запуск от uid хоста)
|
||||
- [x] 3.2 `scripts/probe.py`: `load` (k6 + зонд + опрос LB, `action.txt`, счётчики повторов LB, `--expect dip|replace`, `pass`), `detect` (действие фоном, `--max`, `--until`, `--within-action`, `--lb-status`, `--restore`), `check --rounds`
|
||||
- [x] 3.3 Проверка группы: `make lint`, `make check` (разбор `scripts/*.py` интерпретатором CI), `k6 inspect`
|
||||
|
||||
## 4. Сценарии уровня «4»
|
||||
|
||||
- [x] 4.1 `scripts/detection.sh` и `make detection`: `SIGTERM`, `docker kill`, `docker pause`, остановка PostgreSQL с заявленными максимумами
|
||||
- [x] 4.2 `scripts/failover-each.sh` и `make failover-each`: остановка, 10 с без реплики и возврат каждой реплики под нагрузкой
|
||||
- [x] 4.3 `scripts/limits.py` и `make limits`: политика лимитов, портов, секретов, volumes, сетей
|
||||
- [x] 4.4 `scripts/rolling-update.sh` и `make rolling-update [FROM_REV=…]`: `migrate` один раз, замена с запасом +1, журнал образов
|
||||
- [x] 4.5 Тест отказа PostgreSQL через LB: ответы `503`, live внутри реплики `200`, LB исключает все реплики и сам отвечает `503`
|
||||
- [x] 4.6 CI: `make limits`, `make detection` в acceptance
|
||||
- [x] 4.7 Проверка группы: `make up`, `make limits`, `make lb-check`, `make detection`, `make failover-each`, `make rolling-update FROM_REV=8d28d45`, `make test-faults`
|
||||
|
||||
## 5. Отчёт
|
||||
|
||||
- [x] 5.1 `evidence/`: detection, failover-each, rolling, limits, lb-check, повторные прогоны уровня «3» на новом коде
|
||||
- [x] 5.2 `REPORT.md`: таймауты и обнаружение, строки 4.1–4.4, таблица отказов уровня «4», ограничения
|
||||
- [x] 5.3 Проверка группы: `make check`, `make validate`, `make lint`, `make student-test`, `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`, `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` для обеих реплик
|
||||
@@ -0,0 +1,4 @@
|
||||
schema: spec-driven
|
||||
created: 2026-10-28
|
||||
archived: 2026-10-28
|
||||
lab: 3
|
||||
@@ -0,0 +1,102 @@
|
||||
## Context
|
||||
|
||||
Мотивация — в `proposal.md`. Решение лабы 2 уже не держит в процессе ничего, от чего зависит корректность: пользователи, сессии, чаты и сообщения лежат в PostgreSQL, кэш сессий — общий Valkey с отметками отзыва, курсор подписан общим секретом из `secrets/cursor_secret`, порядок истории держит блокировка строки чата, а не часы процесса. Шина событий в памяти обслуживает только журнал аудита. Поэтому несколько реплик — это в основном стенд и два новых правила контракта: `X-Instance-Id` и `Idempotency-Key`. Инфраструктурные заготовки (HAProxy, хуки, зонд) проверены отдельно на заглушке и встраиваются, а не пишутся заново.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Любая реплика взаимозаменяема: ответ не зависит от того, какая реплика обслужила предыдущий запрос клиента.
|
||||
- Остановка реплики видна оператору (`docker ps -a` ↔ `X-Instance-Id`) и не прерывает запись дольше 10 с.
|
||||
- Идемпотентность держит одна транзакция PostgreSQL, без второго хранилища и без маркеров «в обработке».
|
||||
|
||||
**Non-Goals:**
|
||||
- Замер времени обнаружения, поочерёдный отказ под нагрузкой, rolling update — уровень «4».
|
||||
- Очистка истёкших ключей фоновым заданием (см. Risks).
|
||||
|
||||
## Decisions
|
||||
|
||||
### D1. Compose + HAProxy, один сервис `api` с репликами
|
||||
|
||||
Один compose-service `api` с `deploy.replicas: ${API_REPLICAS:-2}`, без `container_name`, `hostname` и `ports`; перед ним `lb` — HAProxy 3.2.26 LTS по digest, единственный сервис с опубликованными портами `127.0.0.1:${LB_HTTP_PORT:-8080}` и `127.0.0.1:${LB_STATS_PORT:-8404}` (статистика только на чтение, `/healthz` для healthcheck LB). Сети: `edge` (LB) и `backend` с `internal: true` (LB, `api`, `migrate`, `postgres`, `valkey`). Каждому сервису — `deploy.resources.limits`; `api` — `read_only` с `tmpfs /tmp` для heartbeat gunicorn.
|
||||
|
||||
Что получаем: масштаб одним параметром (нужен треку «5»), активные проверки готовности с явными `inter/fall/rise`, статистика `qcur/qtime` и DNS-обнаружение без `docker.sock`. Чего стоит: ещё один процесс на пути запроса. Отвергнуто: Nginx OSS (только пассивные проверки, DNS резолвится на старте), Traefik (нужен `docker.sock`), Swarm (вне Out of scope лабы), отдельные сервисы `api-1/api-2` (ломают масштабирование одного сервиса).
|
||||
|
||||
### D2. Конфигурация балансировщика
|
||||
|
||||
- `server-template api 8 api:8080` + `resolvers docker` (`127.0.0.11`, `hold` 2 с), `init-addr none`: остановленный контейнер пропадает из DNS, слот уходит в `MAINT`, запущенный возвращается сам.
|
||||
- `balance roundrobin`, без `stick`: новое соединение — следующая реплика; тест требует ≥2 `X-Instance-Id` на одном токене.
|
||||
- `option httpchk GET /health/ready`, `inter 1s fastinter 500ms fall 2 rise 2`, `timeout check 1s`.
|
||||
- Повторы: `retries 2`, `option redispatch 1`, `retry-on conn-failure empty-response`; `http-request disable-l7-retry` для всего, кроме `GET` и `POST …/messages` с `Idempotency-Key`. Отказ соединения повторяется всегда (запрос не ушёл), обрыв после отправки — только для безопасных к повтору запросов; `POST /users`, `/chats` и вход не повторяются, как требует `contracts/README.md`.
|
||||
- `option http-server-close`: соединение LB→API не переиспользуется, поэтому при остановке реплики нет гонки за простаивающее keep-alive-соединение.
|
||||
- `X-Request-Id`: непустой входящий до 200 символов пробрасывается, иначе LB генерирует uuid4; приложение эхо-возвращает его. Ответы LB `502/503/504` — JSON формата контракта с тем же `request_id`.
|
||||
- Таймауты: `connect 500ms` < `server 10s` > `REQUEST_TIMEOUT_SECONDS=8` приложения > `statement_timeout` 2 с; `queue 3s`, `maxconn` на сервер `API_SERVER_MAXCONN` (64). Мягкая остановка LB — `SIGUSR1` с `hard-stop-after 5s`.
|
||||
|
||||
### D3. `X-Instance-Id` — hostname контейнера, платформа
|
||||
|
||||
`PlatformSettings.instance_id` по умолчанию берётся из `socket.gethostname()` один раз при сборке приложения; в контейнере это короткий ID, совпадающий с `docker ps` и `.Config.Hostname`. Конвейер `RequestPipeline` ставит заголовок рядом с `X-Request-Id` на каждый ответ, который проходит через него (включая `401`, `413`, `503` по таймауту и `404/405` фреймворка); обработчик необработанных исключений ставит его сам, потому что `500` формирует внешний `ServerErrorMiddleware`, минуя конвейер. Это платформа (`shared/entrypoints`), без доменных понятий.
|
||||
|
||||
Отвергнуто: pid или uuid процесса — при `WEB_CONCURRENCY=2` одна реплика выглядела бы двумя, а `stop-one.sh` не нашёл бы контейнер; `INSTANCE_ID` в compose — одинаков у всех реплик сервиса. Непрозрачный alias вместо hostname — лаба 7.
|
||||
|
||||
### D4. Идемпотентность в зоне `messaging`, одна транзакция
|
||||
|
||||
Миграция `0002_idempotency_keys.sql` (аддитивная, код лабы 2 её не замечает):
|
||||
|
||||
```sql
|
||||
CREATE TABLE idempotency_keys (
|
||||
chat_id uuid NOT NULL,
|
||||
user_id uuid NOT NULL,
|
||||
key text NOT NULL CHECK (key ~ '^[A-Za-z0-9._:-]{1,128}$'),
|
||||
fingerprint bytea NOT NULL CHECK (octet_length(fingerprint) = 32),
|
||||
message_id uuid NOT NULL REFERENCES messages (id) ON DELETE CASCADE,
|
||||
created_at timestamptz NOT NULL,
|
||||
PRIMARY KEY (chat_id, user_id, key),
|
||||
FOREIGN KEY (chat_id, user_id) REFERENCES chat_members (chat_id, user_id)
|
||||
);
|
||||
```
|
||||
|
||||
Область «пользователь + метод + путь + ключ» сводится к `(chat_id, user_id, key)`: ключ бывает только у `POST /api/v1/chats/{chat_id}/messages`. Внешний ключ на `chat_members` держит связь внутри таблиц зоны `messaging` — SQL зоны по-прежнему не читает `users`.
|
||||
|
||||
`PostMessageHandler` в одной транзакции UoW:
|
||||
|
||||
1. `SELECT … FROM chats WHERE id = $1 FOR UPDATE` (уже есть ради порядка истории) → `404`, если чата нет;
|
||||
2. `chat.post(...)` — членство (`404`), затем текст (`400`), в памяти, без записи;
|
||||
3. поиск квитанции `SELECT k.fingerprint, m.* FROM idempotency_keys k JOIN messages m ON m.id = k.message_id WHERE (k.chat_id, k.user_id, k.key) = ($1, $2, $3) AND k.created_at > $4` по первичному ключу; `$4 = now − IDEMPOTENCY_TTL_SECONDS`;
|
||||
4. квитанция есть: отпечаток совпал → вернуть сохранённое сообщение (транзакция откатывается, события не публикуются), иначе `409 conflict`;
|
||||
5. квитанции нет → один оператор: `INSERT messages` + `INSERT idempotency_keys … ON CONFLICT (chat_id, user_id, key) DO UPDATE` (перезапись истёкшего ключа) + `UPDATE chats.last_message_at`; затем `COMMIT`.
|
||||
|
||||
Конкурентные повторы с одним ключом всегда идут в один чат, поэтому ждут на блокировке строки чата; после `COMMIT` первого следующий оператор в `READ COMMITTED` видит квитанцию и отдаёт то же сообщение. Перезапись в шаге 5 безопасна: под той же блокировкой уже проверено, что живой квитанции нет. Если транзакция откатилась (обрыв, `SIGTERM`, таймаут), не остаётся ни сообщения, ни ключа — повтор создаёт сообщение один раз. Ответы `4xx` и `5xx` ничего не пишут.
|
||||
|
||||
Отпечаток — SHA-256 канонического JSON распарсенной модели `CreateMessageRequest` (`model_dump_json`: порядок полей задаёт модель, а не клиент); считается на границе HTTP и передаётся в команду `PostMessage` вместе с ключом. Повтор отдаёт сообщение тем же `MessageOut`, а `created_at` хранится с микросекундами, поэтому тело совпадает строкой. Доменный объект `Receipt` (ключ, отпечаток, сообщение) решает «повтор или конфликт» методом `replay`; ошибка `IdempotencyConflict` зоны отображается в `409 conflict`. Ключ валидируется заголовком FastAPI (`pattern`, 1–128) → `400` через существующий обработчик ошибок валидации.
|
||||
|
||||
Что получаем: атомарность без второго хранилища и без «залипших» ключей. Чего стоит: строка ключа на каждое сообщение и чтение по первичному ключу под уже взятой блокировкой. Отвергнуто: `SET NX` в Valkey (не атомарен с `COMMIT` PostgreSQL), отдельно закоммиченный маркер «processing» (после гибели реплики повтор получал бы `409`), `INSERT … ON CONFLICT DO NOTHING` без блокировки чата (её всё равно требует порядок истории).
|
||||
|
||||
`LockNotAvailableError` (`lock_timeout` при очереди на строку чата) добавляется к ошибкам, которые пул превращает в `503 unavailable`: это транзиентный отказ, а не `500`, и он не сохраняется под ключом.
|
||||
|
||||
### D5. Миграции и старт реплик
|
||||
|
||||
`migrate` — одноразовый сервис на образе приложения под `pg_advisory_lock`; реплики зависят от него `service_completed_successfully` и сами схему не трогают. Повторный запуск (`restart.sh`, rolling update) безопасен: журнал версий и контрольные суммы.
|
||||
|
||||
### D6. Остановка, готовность и процессы
|
||||
|
||||
`SHUTDOWN_TIMEOUT_SECONDS=5` (gunicorn `graceful_timeout` и uvicorn `timeout_graceful_shutdown`) < `stop_grace_period: 8s`; хук останавливает с `docker stop -t 6`, худший случай хука ≈7 с < 10 с. По `SIGTERM` gunicorn закрывает listener: LB получает отказ соединения и повторяет запрос на соседней реплике. `WEB_CONCURRENCY=2` на реплику с лимитом `cpus: 1`, `512m`; пул 8 соединений на воркер: 2 реплики × 2 × 8 = 32 < `max_connections=200`.
|
||||
|
||||
### D7. Хуки и зонд
|
||||
|
||||
- `scripts/stop-one.sh`: среди `docker compose ps -q api` ищет контейнер с `.Config.Hostname == TARGET_INSTANCE_ID`, `docker stop -t 6`; неизвестный ID → код 3. Запускается тестом без shell, поэтому shebang и `chmod +x`.
|
||||
- `scripts/restart.sh`: `stop lb api` → `restart postgres valkey` → `up -d --wait` (заодно повторно `migrate`), volumes не трогаются.
|
||||
- `scripts/restore.sh`: `up -d --no-deps --no-recreate --wait api`, затем `scripts/lb-wait.sh` ждёт, пока статистика LB покажет все реплики `UP`; без этого следующий тест увидит одну реплику.
|
||||
- `scripts/probe.py check`: 40 `GET /users/me` одним токеном и 8 параллельных `POST` с одним ключом; stdlib, синтаксис Python 3.9.
|
||||
|
||||
`api-shortttl` лабы 2 публиковал порт API в обход LB и удаляется; истечение сессии проверяется in-process тестом с коротким TTL.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- [Таблица ключей растёт вместе с историей] → строка на сообщение (~100 байт против сообщения до 16 КБ), истёкшие ключи перезаписываются при повторном использовании; фоновая очистка — следующий шаг, описан в `REPORT.md`.
|
||||
- [Повтор берёт блокировку строки чата] → повтор так же дёшев, как запись; горячий чат сериализуется и без идемпотентности.
|
||||
- [`X-Instance-Id` раскрывает короткий ID контейнера] → допустимо до лабы 7, где появится alias.
|
||||
- [Цель failover-теста выбирается round robin] → для второй реплики тест повторяется после `restore.sh`; лишний запрос через LB сдвигает очередь.
|
||||
- [LB — единственная точка отказа, как и PostgreSQL] → честно в ограничениях отчёта; HA LB и БД — Out of scope.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
`0002` аддитивна: сначала `migrate`, затем реплики с новым кодом; откат кода не требует отката схемы. Старый API лабы 2 работает на новой схеме, не создавая ключей.
|
||||
@@ -0,0 +1,33 @@
|
||||
## Why
|
||||
|
||||
Решение лабы 2 — один контейнер API с опубликованным портом. Рубрика «3» `README.md` требует ≥2 взаимозаменяемых реплик за одной точкой входа, разные реплики на одном токене, запись ≤10 с после остановки любой реплики и повтор сообщения без дубля; контракт 1.3.0 вводит `X-Instance-Id` и `Idempotency-Key`. Изменение закрывает уровень «3» и строки 3.1–3.5 `REPORT.md`.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Каждый ответ API несёт `X-Instance-Id` — hostname контейнера, один на все воркеры.
|
||||
- `POST /api/v1/chats/{chat_id}/messages` требует `Idempotency-Key` (`^[A-Za-z0-9._:-]{1,128}$`, иначе `400`). Повтор того же JSON тем же пользователем в том же чате в течение `IDEMPOTENCY_TTL_SECONDS` (≥24 ч) возвращает исходный `201` и тот же `Message`, другой JSON — `409`. Ключ и сообщение — одна транзакция PostgreSQL; `4xx` и `5xx` не сохраняются.
|
||||
- Новая аддитивная миграция `0002_idempotency_keys.sql`.
|
||||
- Стенд: HAProxy 3.2 LTS (`lb`) — единственный опубликованный порт; `api` с `deploy.replicas: ${API_REPLICAS:-2}` без портов; проверка `GET /health/ready`, Docker DNS, round robin без sticky; `api-shortttl` с портом в обход LB удаляется.
|
||||
- Хуки `scripts/stop-one.sh`, `scripts/restart.sh`, `scripts/restore.sh`, `scripts/lb-wait.sh` и зонд `scripts/probe.py check`.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `lab3-load-balancing`: единственная точка входа, ≥2 реплики без локального состояния, балансировка без sticky, проверка готовности и DNS-обновление backend, политика повторов LB, хуки остановки реплики и рестарта стенда.
|
||||
- `lab3-idempotent-messages`: обязательный ключ, область, replay/`409`/`400`, TTL, атомарность, конкурентный повтор, повтор после неопределённого исхода.
|
||||
|
||||
### Modified Capabilities
|
||||
- `lab1-messenger-history`: «Отправка сообщения» требует `Idempotency-Key`.
|
||||
- `lab1-service-operability`: «Сквозной идентификатор запроса» дополняется `X-Instance-Id`; «Корректное завершение по сигналу» — срок внутри `stop_grace_period`; «Контейнерная поставка» — API доступен через LB.
|
||||
- `lab2-persistent-storage`: «Воспроизводимый стенд» — наружу только LB, реплики без портов; «Версионируемые миграции» — аддитивные и совместимые с работающей версией; «Данные и сессии переживают рестарт» — рестарт включает LB.
|
||||
|
||||
## Impact
|
||||
|
||||
- Код: платформа (`X-Instance-Id`), зона `messaging` (идемпотентная отправка), миграция `0002`.
|
||||
- Стенд: `compose.yaml`, `infra/haproxy/haproxy.cfg`, `scripts/`, `Makefile`, `.env.example`, `pyproject.toml` (ruff для `scripts/*.py`), CI.
|
||||
- Тесты: заголовки, идемпотентность, гонка ключа в реальном PostgreSQL.
|
||||
- Отчёт: строки 3.1–3.5 и переноса lab2 в `REPORT.md`, `evidence/`.
|
||||
|
||||
## Non-goals
|
||||
|
||||
Время обнаружения, поочерёдный отказ под нагрузкой, rolling update и измерения лимитов — уровень «4»; серии 1/2/4 реплик — трек «5»; оба — следующие изменения. Из Out of scope не появляется ничего: Swarm, HA PostgreSQL и LB, непрозрачный alias реплики (лаба 7), вложения (лаба 4).
|
||||
+43
@@ -0,0 +1,43 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Отправка сообщения
|
||||
|
||||
Сервис SHALL принимать `POST /api/v1/chats/{chat_id}/messages` от участника чата с телом `{"text":...}` и обязательным заголовком `Idempotency-Key` и возвращать `201` с объектом `Message`. Отправитель SHALL выводиться из предъявленной идентификации; поле `sender_id` в теле запроса SHALL NOT приниматься. `text` SHALL содержать от 1 до 4000 Unicode code points и SHALL NOT состоять только из пробельных символов. `id` и `created_at` SHALL назначаться сервером. Правила ключа описаны в `lab3-idempotent-messages`.
|
||||
|
||||
#### Scenario: Сообщение отправлено
|
||||
|
||||
- **WHEN** участник отправляет `{"text":"Привет, мир 👋"}` в свой чат с новым `Idempotency-Key`
|
||||
- **THEN** ответ `201`, тело соответствует схеме `Message`
|
||||
- **AND** `sender_id` равен идентификатору вызывающего, `chat_id` равен чату из пути, `text` побайтово совпадает с отправленным
|
||||
|
||||
#### Scenario: Ключ не передан
|
||||
|
||||
- **WHEN** участник отправляет корректное тело без заголовка `Idempotency-Key`
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Отправитель не берётся из тела запроса
|
||||
|
||||
- **WHEN** тело запроса содержит поле `sender_id`
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Пустой или пробельный текст
|
||||
|
||||
- **WHEN** тело содержит `{"text":""}` или `{"text":" "}`
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Текст длиннее предела
|
||||
|
||||
- **WHEN** `text` содержит более 4000 Unicode code points
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
- **AND** длина считается в code points, а не в байтах UTF-8
|
||||
|
||||
#### Scenario: Посторонний пишет в чужой чат
|
||||
|
||||
- **WHEN** пользователь, не входящий в состав чата, отправляет корректное сообщение с ключом
|
||||
- **THEN** ответ `404` с кодом `not_found`
|
||||
- **AND** сообщение не сохраняется
|
||||
|
||||
#### Scenario: Доступ проверяется раньше содержимого
|
||||
|
||||
- **WHEN** посторонний отправляет в чужой чат с ключом тело с пустым `text`
|
||||
- **THEN** ответ `404`, а не `400`
|
||||
+64
@@ -0,0 +1,64 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Сквозной идентификатор запроса
|
||||
|
||||
Каждый ответ сервиса, включая ответы проб, `204` выхода и ответы об ошибках (`404`/`405` неизвестного маршрута, `413`, `500` необработанного исключения), SHALL содержать непустые заголовки `X-Request-Id` и `X-Instance-Id`. Если запрос принёс собственный `X-Request-Id`, сервис SHALL использовать его значение, иначе SHALL сгенерировать новое. `X-Instance-Id` SHALL идентифицировать реплику (контейнер), а не отдельный процесс-воркер: значение SHALL быть одинаковым у всех процессов реплики, стабильным на всё время её жизни и SHALL совпадать с hostname контейнера, чтобы оператор мог сопоставить ответ с `docker ps`.
|
||||
|
||||
#### Scenario: Идентификатор присутствует в любом ответе
|
||||
|
||||
- **WHEN** выполняется любой запрос к сервису, успешный или ошибочный
|
||||
- **THEN** ответ содержит непустые `X-Request-Id` и `X-Instance-Id`
|
||||
|
||||
#### Scenario: Клиентский идентификатор сохраняется
|
||||
|
||||
- **WHEN** запрос содержит `X-Request-Id` с непустым значением
|
||||
- **THEN** ответ содержит то же значение
|
||||
|
||||
#### Scenario: Один идентификатор на реплику
|
||||
|
||||
- **WHEN** реплика с несколькими процессами-воркерами обслуживает серию запросов
|
||||
- **THEN** все её ответы несут одно и то же значение `X-Instance-Id`, равное hostname контейнера
|
||||
|
||||
#### Scenario: Необработанное исключение несёт идентификаторы
|
||||
|
||||
- **WHEN** обработка запроса завершается непредвиденным исключением
|
||||
- **THEN** ответ `500` содержит `X-Request-Id` и `X-Instance-Id`
|
||||
|
||||
### Requirement: Корректное завершение по сигналу
|
||||
|
||||
По получении `SIGTERM` сервис SHALL перестать принимать новые соединения, дождаться завершения принятых запросов и завершить процесс не более чем за 10 секунд; срок мягкой остановки сервера SHALL быть меньше `stop_grace_period` контейнера, чтобы контейнер не убивался по таймауту. Процесс сервера SHALL быть основным процессом контейнера и SHALL получать сигналы напрямую.
|
||||
|
||||
#### Scenario: Остановка укладывается в срок
|
||||
|
||||
- **WHEN** запущенному контейнеру послан `SIGTERM`
|
||||
- **THEN** процесс завершается не позднее чем через 10 секунд и раньше `stop_grace_period`
|
||||
- **AND** код завершения соответствует штатной остановке, а не убийству по таймауту
|
||||
|
||||
#### Scenario: Принятый запрос дорабатывается
|
||||
|
||||
- **WHEN** `SIGTERM` приходит во время обработки принятого запроса
|
||||
- **THEN** этот запрос получает ответ до завершения процесса
|
||||
|
||||
### Requirement: Контейнерная поставка
|
||||
|
||||
Сервис SHALL собираться из исходников в образ, слушать `0.0.0.0:8080` и читать конфигурацию из переменных окружения. Контейнер SHALL выполняться от непривилегированного пользователя, SHALL фиксировать версию базового образа и версии зависимостей и SHALL объявлять healthcheck, опирающийся на пробу жизни.
|
||||
|
||||
#### Scenario: Образ собирается из чистого clone
|
||||
|
||||
- **WHEN** выполняется сборка образа в свежей копии репозитория
|
||||
- **THEN** сборка завершается успешно без обращения к артефактам вне репозитория
|
||||
|
||||
#### Scenario: API доступен на опубликованном порту
|
||||
|
||||
- **WHEN** стенд поднят командой `make up`
|
||||
- **THEN** `GET /health/ready` с хоста через опубликованный порт балансировщика отвечает `200`
|
||||
|
||||
#### Scenario: Процесс работает не от root
|
||||
|
||||
- **WHEN** в работающем контейнере проверяется эффективный пользователь процесса сервера
|
||||
- **THEN** это не `root`, и идентификатор пользователя не равен 0
|
||||
|
||||
#### Scenario: Healthcheck отражает состояние сервиса
|
||||
|
||||
- **WHEN** контейнер запущен и сервис готов
|
||||
- **THEN** статус healthcheck контейнера становится `healthy`
|
||||
+58
@@ -0,0 +1,58 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Версионируемые миграции
|
||||
|
||||
Схема SHALL создаваться только миграциями: упорядоченными SQL-файлами, каждый из которых применяется в своей транзакции и записывается в журнал применённых версий. Миграции SHALL применяться одним одноразовым процессом до старта реплик API, а не каждой репликой; одновременный запуск двух процессов SHALL сериализоваться. Повторный запуск SHALL NOT менять схему и данные. Изменение текста уже применённой миграции SHALL останавливать запуск с ошибкой. Новая миграция SHALL быть аддитивной: работающая предыдущая версия API SHALL продолжать работать на схеме после неё.
|
||||
|
||||
#### Scenario: Миграции с пустого volume
|
||||
|
||||
- **WHEN** стенд поднимается на пустом volume PostgreSQL
|
||||
- **THEN** процесс миграций применяет все версии по порядку и завершается кодом 0, после чего стартуют реплики API
|
||||
|
||||
#### Scenario: Повторный запуск
|
||||
|
||||
- **WHEN** процесс миграций запускается повторно на той же БД
|
||||
- **THEN** он завершается кодом 0, журнал версий и число строк во всех таблицах не меняются
|
||||
|
||||
#### Scenario: Изменённая миграция
|
||||
|
||||
- **WHEN** текст применённой миграции изменён и процесс миграций запущен
|
||||
- **THEN** процесс завершается ненулевым кодом и схему не трогает
|
||||
|
||||
#### Scenario: Реплики не мигрируют схему
|
||||
|
||||
- **WHEN** стартует или перезапускается реплика API
|
||||
- **THEN** она не применяет миграции; журнал версий меняет только процесс `migrate`
|
||||
|
||||
### Requirement: Данные и сессии переживают рестарт
|
||||
|
||||
Пользователи, чаты, участники, сообщения, ключи идемпотентности и ещё действующие сессии SHALL сохраняться при перезапуске балансировщика, всех реплик API и всех хранилищ с сохранёнными volumes. После рестарта прежний токен SHALL работать до своего прежнего `expires_at`, а подтверждённое сообщение SHALL читаться побайтно тем же.
|
||||
|
||||
#### Scenario: Полный рестарт стенда
|
||||
|
||||
- **WHEN** выполняется `make test-persistence ACTION_SCRIPT=scripts/restart.sh`
|
||||
- **THEN** hook перезапускает балансировщик, API и хранилища за ≤90 с с кодом 0, а тест печатает `PASS: persistence preserved confirmed data and existing session`
|
||||
|
||||
#### Scenario: Логаут после рестарта
|
||||
|
||||
- **WHEN** после рестарта пользователь отзывает прежний токен
|
||||
- **THEN** ответ `204`, а следующий запрос с этим токеном получает `401`
|
||||
|
||||
### Requirement: Воспроизводимый стенд из репозитория
|
||||
|
||||
Стенд SHALL подниматься из чистого clone командами репозитория: образы сторонних сервисов закреплены версией и digest, API собирается из исходников. Процессы сервисов SHALL работать не от root, у каждого долгоживущего сервиса SHALL быть healthcheck и лимиты CPU и памяти. Наружу SHALL публиковаться только балансировщик на `127.0.0.1` (порт HTTP и порт статистики); PostgreSQL, Valkey и реплики API SHALL NOT публиковать порты. Учётные данные SHALL передаваться файлами compose secrets из каталога, исключённого из Git, только тем сервисам, которым они нужны, и SHALL NOT появляться в Git, образе и журнале.
|
||||
|
||||
#### Scenario: Подъём из чистого clone
|
||||
|
||||
- **WHEN** в чистом clone выполняются `make secrets` и `make up`
|
||||
- **THEN** все сервисы становятся `healthy` или завершаются кодом 0, а `GET /health/ready` через балансировщик отвечает `200`
|
||||
|
||||
#### Scenario: Опубликован только балансировщик
|
||||
|
||||
- **WHEN** выполняется `docker compose ps --format '{{.Service}} {{.Ports}}'`
|
||||
- **THEN** опубликованные порты есть только у сервиса `lb` и все они привязаны к `127.0.0.1`
|
||||
|
||||
#### Scenario: Секреты и volumes вне Git
|
||||
|
||||
- **WHEN** выполняются `git ls-files secrets .env` и `git check-ignore secrets/database_url .env`
|
||||
- **THEN** первая команда ничего не выводит, вторая подтверждает, что пути игнорируются
|
||||
+81
@@ -0,0 +1,81 @@
|
||||
## Purpose
|
||||
|
||||
Определяет идемпотентную отправку сообщения через `Idempotency-Key`: формат и область ключа, повтор и конфликт, срок хранения результата, атомарность записи и поведение при конкурентном повторе через разные реплики и при неопределённом исходе.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Обязательный ключ идемпотентности
|
||||
|
||||
`POST /api/v1/chats/{chat_id}/messages` SHALL требовать заголовок `Idempotency-Key` длиной 1–128 символов из `[A-Za-z0-9._:-]`. Отсутствующий или не соответствующий формату ключ SHALL давать `400` с кодом `invalid_request` в общем формате ошибки; сообщение при этом SHALL NOT сохраняться. Остальные endpoint SHALL NOT требовать ключ.
|
||||
|
||||
#### Scenario: Ключ отсутствует
|
||||
|
||||
- **WHEN** участник отправляет корректное сообщение без `Idempotency-Key`
|
||||
- **THEN** ответ `400` с кодом `invalid_request`, история чата не меняется
|
||||
|
||||
#### Scenario: Ключ неверного формата
|
||||
|
||||
- **WHEN** `Idempotency-Key` пустой, длиннее 128 символов или содержит пробел, `/` или не-ASCII символ
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
### Requirement: Повтор возвращает исходный результат
|
||||
|
||||
Область ключа SHALL составлять пользователь сессии, метод и путь чата и сам ключ. Повтор с тем же ключом и семантически тем же JSON (порядок полей не важен) в течение `IDEMPOTENCY_TTL_SECONDS` (не меньше 86 400 с) SHALL возвращать `201` и тот же объект `Message` — те же `id`, `text` и строку `created_at` — без создания нового сообщения. Тот же ключ с другим JSON SHALL давать `409` с кодом `conflict`. Одинаковый ключ у разных пользователей или в разных чатах SHALL действовать независимо. После истечения срока ключ SHALL приниматься как новый.
|
||||
|
||||
#### Scenario: Повтор того же тела
|
||||
|
||||
- **WHEN** участник повторяет `POST` с тем же ключом и тем же `{"text":...}`
|
||||
- **THEN** ответ `201`, тело равно телу первого ответа целиком, в истории одно такое сообщение
|
||||
|
||||
#### Scenario: Тот же ключ, другое тело
|
||||
|
||||
- **WHEN** участник повторяет `POST` с тем же ключом, но другим `text`
|
||||
- **THEN** ответ `409` с кодом `conflict`, новое сообщение не создаётся
|
||||
|
||||
#### Scenario: Тот же ключ у другого пользователя
|
||||
|
||||
- **WHEN** другой участник того же чата отправляет сообщение с тем же значением ключа
|
||||
- **THEN** ответ `201` с новым сообщением этого участника
|
||||
|
||||
#### Scenario: Тот же ключ в другом чате
|
||||
|
||||
- **WHEN** участник отправляет в другой свой чат сообщение с уже использованным ключом
|
||||
- **THEN** ответ `201` с новым сообщением в этом чате
|
||||
|
||||
#### Scenario: Срок ключа истёк
|
||||
|
||||
- **WHEN** с момента первой отправки прошло больше `IDEMPOTENCY_TTL_SECONDS` и участник отправляет с тем же ключом другой текст
|
||||
- **THEN** ответ `201` с новым сообщением, а не `409`
|
||||
|
||||
### Requirement: Повтор заново проверяет доступ
|
||||
|
||||
Повтор с известным ключом SHALL снова проверять сессию и членство в чате до выдачи сохранённого результата: отозванный или истёкший токен SHALL получать `401`, посторонний — `404`. Ответы `4xx` и `5xx` SHALL NOT сохраняться как результат ключа: после такого ответа повтор с тем же ключом обрабатывается как первая попытка.
|
||||
|
||||
#### Scenario: Повтор после выхода
|
||||
|
||||
- **WHEN** пользователь отправил сообщение, вышел и повторил запрос с тем же ключом и прежним токеном
|
||||
- **THEN** ответ `401`
|
||||
|
||||
#### Scenario: Ошибка не занимает ключ
|
||||
|
||||
- **WHEN** участник отправил с ключом `K` пустой текст и получил `400`, затем отправил с ключом `K` корректный текст
|
||||
- **THEN** второй ответ `201` с новым сообщением
|
||||
|
||||
#### Scenario: Посторонний с чужим ключом
|
||||
|
||||
- **WHEN** посторонний отправляет в чат запрос с ключом, уже использованным участником
|
||||
- **THEN** ответ `404`, сохранённое сообщение не раскрывается
|
||||
|
||||
### Requirement: Атомарная и общая для реплик идемпотентность
|
||||
|
||||
Сообщение и запись ключа SHALL фиксироваться одной транзакцией PostgreSQL: либо сохраняются оба, либо ни одно. Одновременные запросы с одним ключом и одним телом, пришедшие на разные реплики, SHALL создавать ровно одно сообщение, и каждый из них SHALL получать `201` с одинаковым `Message`. Если исход первой попытки неизвестен клиенту (обрыв, таймаут, остановка реплики), повтор с тем же ключом SHALL возвращать уже сохранённое сообщение либо, если транзакция не была зафиксирована, создавать его ровно один раз.
|
||||
|
||||
#### Scenario: Конкурентный повтор через разные реплики
|
||||
|
||||
- **WHEN** 8 параллельных `POST` с одним ключом и одним телом отправлены через LB
|
||||
- **THEN** все ответы `201` с одинаковым телом, ответы пришли от ≥2 реплик, в истории чата ровно одно такое сообщение
|
||||
|
||||
#### Scenario: Повтор после отказа реплики
|
||||
|
||||
- **WHEN** во время `make test-failover` запрос не получил ответа и повторён с тем же ключом и текстом
|
||||
- **THEN** в истории нет дублей по `id` и `text`, а каждый подтверждённый ответ совпадает с записью истории байт-в-байт
|
||||
+84
@@ -0,0 +1,84 @@
|
||||
## Purpose
|
||||
|
||||
Определяет развёртывание API несколькими взаимозаменяемыми репликами за единственной публичной точкой входа: что видно клиенту, как балансировщик выбирает и исключает реплики, какие запросы он вправе повторить и как оператор останавливает одну реплику и перезапускает стенд.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Единственная точка входа и не менее двух реплик
|
||||
|
||||
Стенд SHALL описываться одним `compose.yaml` и запускаться документированной командой. API SHALL работать не менее чем двумя репликами одного compose-service без `container_name`; их число SHALL задаваться `API_REPLICAS` (по умолчанию 2). Наружу SHALL публиковаться только балансировщик на `127.0.0.1`; порты реплик API SHALL NOT публиковаться. Все реплики SHALL использовать одну общую PostgreSQL и одно общее хранилище сессий.
|
||||
|
||||
#### Scenario: Стенд поднят
|
||||
|
||||
- **WHEN** выполняется `make up`, затем `docker compose ps`
|
||||
- **THEN** работают ≥2 контейнера сервиса `api` в состоянии `healthy`, у них нет опубликованных портов, а единственные опубликованные порты принадлежат сервису `lb`
|
||||
|
||||
#### Scenario: Реплика недоступна в обход балансировщика
|
||||
|
||||
- **WHEN** с хоста выполняется запрос на порт 8080 контейнера реплики
|
||||
- **THEN** соединение не устанавливается: реплика слушает только внутреннюю сеть
|
||||
|
||||
### Requirement: Разные реплики на одной сессии
|
||||
|
||||
Балансировщик SHALL распределять новые соединения по готовым репликам без привязки клиента (sticky session). Реплика SHALL NOT хранить в памяти процесса сессии, ключи идемпотентности и другое состояние, от которого зависит ответ другой реплики: токен, выданный через одну реплику, SHALL приниматься любой другой, а отзыв сессии SHALL действовать на всех репликах сразу.
|
||||
|
||||
#### Scenario: Один токен, несколько реплик
|
||||
|
||||
- **WHEN** клиент с одним Bearer-токеном выполняет 40 запросов `GET /api/v1/users/me`, каждый новым соединением через LB
|
||||
- **THEN** все ответы `200`, а заголовок `X-Instance-Id` принимает не менее двух разных значений
|
||||
|
||||
#### Scenario: Выход действует на всех репликах
|
||||
|
||||
- **WHEN** пользователь выполнил `DELETE /api/v1/auth/sessions/current` через одну реплику
|
||||
- **THEN** следующий запрос с этим токеном получает `401` независимо от того, какая реплика его обслужила
|
||||
|
||||
### Requirement: Готовность backend и обновление адресов
|
||||
|
||||
Балансировщик SHALL активно проверять каждую реплику запросом `GET /health/ready` и SHALL исключать из ротации реплику, которая не отвечает `200`. Адреса реплик SHALL обновляться через DNS без перезапуска балансировщика: остановленная реплика исчезает из ротации, запущенная или пересозданная появляется сама. Ответы, сформированные самим балансировщиком (`502`, `503`, `504`), SHALL иметь тело в общем формате ошибки с `request_id`, равным заголовку `X-Request-Id`.
|
||||
|
||||
#### Scenario: Реплика возвращается в ротацию
|
||||
|
||||
- **WHEN** остановленная реплика снова запущена
|
||||
- **THEN** после успешных проверок готовности балансировщик снова направляет на неё запросы без перезапуска `lb`
|
||||
|
||||
#### Scenario: Нет ни одной готовой реплики
|
||||
|
||||
- **WHEN** все реплики API остановлены
|
||||
- **THEN** запрос через LB получает `503` с телом `{"error":{"code":"unavailable",...}}`
|
||||
|
||||
### Requirement: Повтор запросов балансировщиком
|
||||
|
||||
Балансировщик SHALL повторять на другой реплике запрос, который не удалось отправить из-за отказа соединения. Повтор после того, как запрос мог быть обработан, SHALL допускаться только для `GET` и для `POST /api/v1/chats/{chat_id}/messages` с `Idempotency-Key`. Балансировщик SHALL NOT прозрачно повторять `POST /api/v1/users`, `POST /api/v1/chats` и `POST /api/v1/auth/sessions`.
|
||||
|
||||
#### Scenario: Создание чата не повторяется
|
||||
|
||||
- **WHEN** реплика оборвала соединение во время `POST /api/v1/chats`
|
||||
- **THEN** клиент получает ошибку балансировщика, а не результат повторной отправки на другую реплику
|
||||
|
||||
### Requirement: Остановка одной реплики
|
||||
|
||||
Оператор SHALL иметь исполняемый хук `scripts/stop-one.sh`, который по переменной `TARGET_INSTANCE_ID` находит контейнер реплики с этим `X-Instance-Id`, останавливает только его с сохранением остальных сервисов и volumes, оставляет остановленным и завершается кодом 0 быстрее 10 секунд. Неизвестный идентификатор SHALL давать ненулевой код без остановки чего-либо. Не позднее 10 секунд от запуска хука SHALL продолжаться новые чтения и записи через LB, а подтверждённые сообщения SHALL оставаться доступными. Хук `scripts/restore.sh` SHALL возвращать остановленные реплики и ждать, пока балансировщик снова видит их готовыми.
|
||||
|
||||
#### Scenario: Отказ реплики под запросами
|
||||
|
||||
- **WHEN** выполняется `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`
|
||||
- **THEN** тест печатает `PASS: failover preserved confirmed data and existing session`, хук завершился быстрее 10 с, первая успешная запись после хука пришла не позже 10 с от его старта, остановленная реплика больше не отвечает, а `docker ps -a` показывает именно её контейнер в состоянии `exited`
|
||||
|
||||
#### Scenario: Вторая реплика
|
||||
|
||||
- **WHEN** после `scripts/restore.sh` тест повторяется и целью становится другая реплика
|
||||
- **THEN** тест снова проходит
|
||||
|
||||
#### Scenario: Неизвестная реплика
|
||||
|
||||
- **WHEN** хук запущен с `TARGET_INSTANCE_ID`, которому не соответствует ни один контейнер `api`
|
||||
- **THEN** хук завершается ненулевым кодом, и все контейнеры продолжают работать
|
||||
|
||||
### Requirement: Рестарт стенда
|
||||
|
||||
Хук `scripts/restart.sh` SHALL перезапускать балансировщик, все реплики API, PostgreSQL и Valkey с сохранением volumes, без удаления и повторного заполнения данных, и SHALL завершаться кодом 0 не позднее 90 секунд, когда стенд снова готов.
|
||||
|
||||
#### Scenario: Полный рестарт сохраняет сессию
|
||||
|
||||
- **WHEN** выполняется `make test-persistence ACTION_SCRIPT=scripts/restart.sh`
|
||||
- **THEN** тест печатает `PASS: persistence preserved confirmed data and existing session`, а `StartedAt` контейнеров `lb`, `api`, `postgres` и `valkey` после прогона позже, чем до него
|
||||
@@ -0,0 +1,43 @@
|
||||
## 1. Перенос лабы 2
|
||||
|
||||
- [x] 1.1 Перенести контекст агента и историю openspec, переписать `AGENTS.md` и `openspec/config.yaml` под лабу 3
|
||||
- [x] 1.2 Перенести код, собственные тесты, Dockerfile, тулчейн, compose, миграции, скрипты и CI из коммита `8cddb09` лабы 2; влить цели Makefile
|
||||
- [x] 1.3 Проверка группы: `make lint`, `make student-test`, `make check` зелёные до изменений лабы 3
|
||||
|
||||
## 2. Идентификатор реплики (платформа)
|
||||
|
||||
- [x] 2.1 `PlatformSettings.instance_id` по умолчанию из `socket.gethostname()`; заголовок `X-Instance-Id` в конвейере и в обработчике `500`
|
||||
- [x] 2.2 Версия приложения 1.3.0; проверка группы: тесты — `X-Instance-Id` на `200`, `204`, `401`, `404`, `405`, `413`, `500`, одно значение на процесс
|
||||
|
||||
## 3. Схема
|
||||
|
||||
- [x] 3.1 Миграция `0002_idempotency_keys.sql`: PK `(chat_id, user_id, key)`, FK на `chat_members` и `messages`, `CHECK` формата ключа и длины отпечатка
|
||||
- [x] 3.2 Проверка группы: тест миграций — версии `0001`, `0002`, повтор без изменений, ключ без участника отклоняется FK
|
||||
|
||||
## 4. Идемпотентная отправка (зона `messaging`)
|
||||
|
||||
- [x] 4.1 Домен: `Receipt` с `replay`, ошибка `IdempotencyConflict`; команда `PostMessage` с ключом и отпечатком
|
||||
- [x] 4.2 Порт и адаптер PostgreSQL: поиск квитанции с учётом TTL, запись сообщения и ключа одним оператором; `LockNotAvailableError` → `503`
|
||||
- [x] 4.3 Обработчик: блокировка чата → `chat.post` → квитанция → повтор, `409` или запись; `IDEMPOTENCY_TTL_SECONDS` в настройках зоны
|
||||
- [x] 4.4 HTTP: обязательный заголовок `Idempotency-Key` (`400`), отпечаток канонического JSON модели, `409 conflict` в реестре ошибок зоны
|
||||
- [x] 4.5 Проверка группы: тесты — повтор, другое тело `409`, нет и неверный ключ `400`, `4xx` не занимает ключ, другой пользователь и другой чат независимы, повтор после выхода `401`, посторонний `404`, истёкший ключ, 8 конкурентных повторов в реальном PostgreSQL дают одно сообщение; ключ во всех прежних отправках
|
||||
|
||||
## 5. Стенд
|
||||
|
||||
- [x] 5.1 `infra/haproxy/haproxy.cfg` из заготовки: round robin, `httpchk /health/ready`, Docker DNS, политика повторов, JSON-ошибки LB, статистика
|
||||
- [x] 5.2 `compose.yaml`: `lb`, `api` с `deploy.replicas` без портов, сети `edge`/`backend`, лимиты всех сервисов, параметры PostgreSQL, таймауты и `stop_grace_period`; удалить `api-shortttl`
|
||||
- [x] 5.3 `.env.example`, Dockerfile (умолчания таймаутов и воркеров), Makefile (`up`, `down`, `restore`, `lb-check`, `test-faults` без `api-shortttl`), CI-job под лабу 3
|
||||
- [x] 5.4 Проверка группы: `docker compose config --quiet`, `haproxy -c`, `make up`, опубликованы только порты `lb`
|
||||
|
||||
## 6. Хуки и зонд
|
||||
|
||||
- [x] 6.1 `scripts/stop-one.sh`, `scripts/restart.sh` (вместо версии лабы 2), `scripts/restore.sh`, `scripts/lb-wait.sh`
|
||||
- [x] 6.2 `scripts/probe.py` (`check`), ruff для `scripts/*.py`
|
||||
- [x] 6.3 Скрипт доказательства отказа: `docker ps -a` до и после, `make test-failover`, какой контейнер остановлен
|
||||
- [x] 6.4 Проверка группы: `make test`, `make lb-check`, `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` для обеих реплик с `scripts/restore.sh` между ними, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`
|
||||
|
||||
## 7. Отчёт
|
||||
|
||||
- [x] 7.1 `evidence/`: smoke, stack, lb-check, failover по каждой реплике, persistence со `StartedAt`, схема и повтор миграций, KDF, секреты, собственные тесты, окружение
|
||||
- [x] 7.2 `REPORT.md`: запуск из чистого clone, архитектура и решения, роли и сервисы, соответствие переменных, строки 3.1–3.5 и переноса lab2, таблица отказов уровня «3»
|
||||
- [x] 7.3 Проверка группы: `make check`, `make validate`, `make lint`, `make student-test`, `make test`, persistence и failover зелёные
|
||||
@@ -0,0 +1,4 @@
|
||||
schema: spec-driven
|
||||
created: 2026-10-28
|
||||
archived: 2026-10-28
|
||||
lab: 4
|
||||
@@ -0,0 +1,155 @@
|
||||
## Context
|
||||
|
||||
Мотивация — в `proposal.md`. Решение лабы 3 — две зоны (`identity`, `messaging`) за HAProxy с ≥2 репликами, PostgreSQL как источник истины, Valkey как кэш сессий, ASGI-конвейер с лимитом тела 1 MiB по `Content-Length`, UoW с событиями. Реплики уже не держат состояния; вложения добавляют второе хранилище, где транзакции PostgreSQL не действуют. Инфраструктура S3, хуки и сценарии заранее проверены на заглушке в `.prep/lab4` и встраиваются, а не пишутся заново: MinIO community на arm64 не скачивается (`minio/minio` удалён с Docker Hub, quay отвечает 401), поэтому выбран RustFS 1.0.4 + `rc` v0.1.36.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Байты — только в bucket, метаданные — только в PostgreSQL; ни одна реплика не держит файл, от которого зависит ответ другой.
|
||||
- Каждый лимит применяется раньше дорогого шага: заголовок → поток → заголовок изображения → проверка файла.
|
||||
- `201` ровно тогда, когда обе записи подтверждены; любой сбой оставляет только невидимое клиенту состояние.
|
||||
- Зоны по-прежнему не импортируют друг друга и не читают чужие таблицы.
|
||||
|
||||
**Non-Goals:**
|
||||
- Компенсирующий `DeleteObject`, очистка `pending` по grace period, лимит одновременных загрузок и замер памяти — уровень «4».
|
||||
- Reconciler, карантин и глубокая сверка — трек 2.
|
||||
|
||||
## Decisions
|
||||
|
||||
### D1. Зона `attachments` и связь с `messaging`
|
||||
|
||||
Новая зона `attachments/` со слоями `domain` (агрегат `Attachment`, значения `Filename`, `ImageKind`, `ImageInfo`, ошибки, событие `AttachmentStored`), `application` (команда `UploadAttachment`, запросы `GetAttachment` и `OpenAttachment`, порты), `infrastructure` (PostgreSQL, S3, Pillow) и `entrypoints` (роутер, схемы, DI, журнал, реестр ошибок).
|
||||
|
||||
Зоне нужен один ответ от `messaging`: «входит ли пользователь в чат». Порт `ChatMembership.is_member(chat_id, user_id)` объявлен в `attachments/application/ports.py`; адаптер `MessagingMembership` поверх `ChatDirectory.chat_for_member` зоны `messaging` и его провайдер dishka живут в `main.py` — единственном месте, которое знает обе зоны. Целостность в БД держат внешние ключи, а не чужие `SELECT`:
|
||||
|
||||
- `attachments (chat_id, owner_id) → chat_members (chat_id, user_id)`: загрузить можно только в свой чат, гонка с проверкой порта ловится `ForeignKeyViolationError` → `404`;
|
||||
- `message_attachments (attachment_id, chat_id) → attachments (id, chat_id) ON DELETE RESTRICT`: сообщение ссылается только на вложение своего чата, а удалить используемое вложение нельзя. Нарушение (`message_attachments_attachment_fkey`) → `UnknownAttachment` зоны `messaging` → `404`.
|
||||
|
||||
Что получаем: SQL каждой зоны читает только свои таблицы, тест графа импортов остаётся строгим, проверка «вложение этого чата» атомарна с `INSERT` сообщения без чтения таблицы `attachments` из `messaging`. Чего стоит: два запроса (строка вложения + членство) вместо одного `JOIN` на метаданных и скачивании, лишний уникальный индекс `(id, chat_id)`. Отвергнуто: `JOIN chat_members` в SQL зоны `attachments` (нарушает границу), проекция членства через события в памяти (не переживает рестарт, расходится между репликами), `SELECT count(*) FROM attachments` из `messaging` (чтение чужой таблицы; внешний ключ даёт то же атомарно).
|
||||
|
||||
### D2. Схема — миграция `0003_attachments.sql`
|
||||
|
||||
```sql
|
||||
ALTER TABLE messages DROP CONSTRAINT messages_text_check,
|
||||
ADD CONSTRAINT messages_text_check CHECK (char_length(text) <= 4000);
|
||||
|
||||
CREATE TABLE attachments (
|
||||
id uuid PRIMARY KEY,
|
||||
chat_id uuid NOT NULL,
|
||||
owner_id uuid NOT NULL,
|
||||
filename text NOT NULL CHECK (char_length(filename) BETWEEN 1 AND 255),
|
||||
content_type text NOT NULL CHECK (content_type IN ('image/png', 'image/jpeg')),
|
||||
size_bytes bigint NOT NULL CHECK (size_bytes BETWEEN 1 AND 10485760),
|
||||
sha256 text NOT NULL CHECK (sha256 ~ '^[0-9a-f]{64}$'),
|
||||
width integer NOT NULL CHECK (width > 0),
|
||||
height integer NOT NULL CHECK (height > 0),
|
||||
object_key text COLLATE "C" NOT NULL UNIQUE,
|
||||
status text NOT NULL CHECK (status IN ('pending', 'ready')),
|
||||
created_at timestamptz NOT NULL,
|
||||
updated_at timestamptz NOT NULL,
|
||||
CONSTRAINT attachments_chat_key UNIQUE (id, chat_id),
|
||||
CONSTRAINT attachments_owner_fkey FOREIGN KEY (chat_id, owner_id) REFERENCES chat_members (chat_id, user_id)
|
||||
);
|
||||
CREATE INDEX attachments_pending_idx ON attachments (created_at) WHERE status = 'pending';
|
||||
|
||||
CREATE TABLE message_attachments (
|
||||
message_id uuid NOT NULL REFERENCES messages (id) ON DELETE CASCADE,
|
||||
position smallint NOT NULL CHECK (position BETWEEN 0 AND 9),
|
||||
chat_id uuid NOT NULL,
|
||||
attachment_id uuid NOT NULL,
|
||||
PRIMARY KEY (message_id, position),
|
||||
UNIQUE (message_id, attachment_id),
|
||||
CONSTRAINT message_attachments_attachment_fkey FOREIGN KEY (attachment_id, chat_id)
|
||||
REFERENCES attachments (id, chat_id) ON DELETE RESTRICT
|
||||
);
|
||||
CREATE INDEX message_attachments_attachment_idx ON message_attachments (attachment_id);
|
||||
```
|
||||
|
||||
Ни одного `bytea`. `object_key` с `COLLATE "C"` — байтовый порядок, как у листинга S3 (пригодится reconciler). Частичный индекс по `pending` обслуживает будущую очистку и не растёт вместе с готовыми вложениями. `UNIQUE (message_id, attachment_id)` запрещает дубль внутри сообщения; одно вложение в нескольких сообщениях допустимо. Индекс по `attachment_id` обслуживает проверку `RESTRICT`. `CHECK` текста ослаблен до `≤ 4000`: пустой текст с вложением легален, а пустой без вложений по-прежнему отсекает домен (`400`). Миграция аддитивна для кода лабы 3: старая версия не пишет пустой текст и не знает новых таблиц.
|
||||
|
||||
Запросы и индексы: метаданные — `SELECT … FROM attachments WHERE id = $1 AND status = 'ready'` (PK); членство — `chat_members` по PK; история и повтор добавляют `ARRAY(SELECT attachment_id FROM message_attachments WHERE message_id = m.id ORDER BY position)` — коррелированный подзапрос по PK `(message_id, position)`, не больше 100 index scan на страницу, без N+1 запросов из приложения.
|
||||
|
||||
### D3. Загрузка: порядок проверок и память
|
||||
|
||||
Эндпоинт не объявляет тела: FastAPI его не читает, обработчик получает `request.stream()`. Команда `UploadAttachment` несёт поток, и все проверки идут в обработчике в порядке «дешёвое раньше»:
|
||||
|
||||
1. `401` — guard конвейера (как в лабе 3);
|
||||
2. объявленный `Content-Length` больше лимита маршрута → `413` в конвейере, тело не читается;
|
||||
3. членство через порт → `404`;
|
||||
4. `Filename` (1–255 code points, не пробельный, без `/`, `\`, категорий `Cc`) → `400`;
|
||||
5. `Content-Type` (тип без параметров, регистр не важен) ∈ {`image/png`, `image/jpeg`} → иначе `415`;
|
||||
6. чтение потока в `bytearray` со счётчиком и инкрементальным SHA-256: на байте `MAX_UPLOAD_BYTES + 1` → `413`, дальше не читаем;
|
||||
7. проверка изображения (D4) → `415`/`413`;
|
||||
8. запись (D5).
|
||||
|
||||
Лимит тела в конвейере становится зависимым от маршрута: платформа получает пары «шаблон пути → лимит», а `main.py` передаёт шаблон upload из `attachments/entrypoints` и `MAX_UPLOAD_BYTES`; остальным маршрутам остаётся 1 MiB. Память одной загрузки — до 10 MiB: куски тела копятся в списке и один раз склеиваются (на миг склейки — вдвое больше), затем те же байты отдаются и в проверку, и в `PutObject`. Диск не используется (`read_only`, `tmpfs` только для heartbeat). Сколько загрузок идёт одновременно, на уровне «3» не ограничено — лимит и замер на уровне «4».
|
||||
|
||||
### D4. Проверка изображения — Pillow за портом `ImageInspector`
|
||||
|
||||
Адаптер `PillowImageInspector` выполняет проверку в `asyncio.to_thread` под `asyncio.Semaphore(IMAGE_CHECK_CONCURRENCY)`, чтобы не блокировать event loop и не декодировать много файлов разом:
|
||||
|
||||
- `Image.open(..., formats=("PNG", "JPEG"))` читает только заголовок; GIF, WebP, текст, пустое тело → `415`;
|
||||
- формат по сигнатуре ≠ заявленный `Content-Type` → `415` (подмена MIME);
|
||||
- `width * height > MAX_IMAGE_PIXELS` → `413` до любого декодирования; `DecompressionBombError`/`Warning` Pillow (выше его собственного порога) тоже → `413`;
|
||||
- PNG: `verify()` — обход всех чанков с проверкой CRC и `IEND` без распаковки пикселей; JPEG: `draft("RGB", (w/8, h/8))` + `load()` — полное декодирование потока в масштабе 1/8 (≈1/64 памяти). Ошибка → `415`. `LOAD_TRUNCATED_IMAGES` остаётся `False`, обрезанный файл — ошибка.
|
||||
|
||||
Что получаем: тип и целостность по содержимому, память проверки — килобайты для PNG и ≤2 MB для JPEG 40 MP. Чего стоит: `verify()` не распаковывает IDAT, поэтому PNG с правильными CRC, но испорченным zlib-потоком будет принят — оригинал отдаётся побайтно, вреда серверу нет, ограничение записано в отчёт. Отвергнуто: полное декодирование PNG (до 160 MB на 40 MP), `python-magic` (только сигнатура, без структуры).
|
||||
|
||||
### D5. Порядок записи PostgreSQL ↔ S3
|
||||
|
||||
`UploadAttachmentHandler`:
|
||||
|
||||
1. транзакция: `INSERT attachments (…, status='pending', object_key='attachments/<uuid7>')`, `COMMIT`;
|
||||
2. `PutObject(Key=object_key, Body=буфер, ContentType)`;
|
||||
3. транзакция: `UPDATE attachments SET status='ready', updated_at=$2 WHERE id=$1 AND status='pending'`, `COMMIT`; событие `AttachmentStored`;
|
||||
4. `201 Attachment`.
|
||||
|
||||
| Сбой | Что остаётся | Ответ клиенту |
|
||||
| --- | --- | --- |
|
||||
| до шага 1 (обрыв, `413`, `415`) | ничего | ошибка или обрыв |
|
||||
| шаг 1 | ничего | `503` |
|
||||
| шаг 2 | строка `pending` без объекта | `503` |
|
||||
| шаг 3 | строка `pending` и объект | `503` |
|
||||
| после шага 3 | готовое вложение | `201` (или обрыв уже после фиксации) |
|
||||
|
||||
`pending` не видно ни в метаданных, ни в скачивании (`404`), а сообщение на него сослаться не может: id отдаётся клиенту только в `201`. Намерение до `PUT` гарантирует, что у любого объекта под `attachments/` есть строка с тем же ключом, — поэтому на уровне «4» правило «объект без строки старше grace — мусор» безопасно. Отвергнуто: `PUT` до `INSERT` (объект без строки неотличим от свежей загрузки), одна транзакция вокруг `PUT` (соединение PostgreSQL держится на время сети S3).
|
||||
|
||||
### D6. Адаптер S3 — aiobotocore за портом `ObjectStorage`
|
||||
|
||||
Порт: `put(key, data, content_type)`, `open(key) -> ObjectContent(size, chunks)`, `delete(key)`. Адаптер `S3ObjectStorage` держит один клиент aiobotocore на воркер (scope `APP` dishka, async-генератор закрывает клиент при остановке): `signature_version="s3v4"`, `addressing_style="path"` (RustFS без virtual host), регион из `S3_REGION`, `connect_timeout=1`, `read_timeout=2`, `retries={"mode": "standard", "max_attempts": 2}`, `request_checksum_calculation`/`response_checksum_validation="when_required"` (CRC и aws-chunked botocore ≥1.36 ломают часть S3-совместимых серверов). Худший случай операции — 2 × (1 + 2) = 6 с < `REQUEST_TIMEOUT_SECONDS=8` < `timeout server 10s` HAProxy. Обработчик botocore, добавляющий `Expect: 100-continue` к потоковому телу, снят: aiohttp ждёт `100 Continue`, RustFS за прокси портов его не присылает, и `PutObject` висел до read timeout (найдено тестом адаптера). `NoSuchKey`/`404` → `ObjectMissingError` порта; `BotoCoreError`, прочие `ClientError`, `OSError`, `TimeoutError` → `Unavailable` платформы → `503`. Ключи читаются из `*_FILE` настройками зоны и в журнал не попадают.
|
||||
|
||||
LB не повторяет upload: в лабе 3 `disable-l7-retry` снят только для `GET` и `POST …/messages` с ключом; повтор `PutObject` клиентом botocore безопасен, ключ тот же.
|
||||
|
||||
### D7. Метаданные и скачивание
|
||||
|
||||
`GetAttachment`: строка `ready` по PK → членство → `Attachment`, иначе `404`. `OpenAttachment`: то же + `storage.open(key)` **до** отправки заголовков, поэтому `404` (объект пропал, событие `attachment.object_missing` в журнал) и `503` (S3 недоступен) ещё возможны; затем `StreamingResponse` по кускам 64 KiB с `Content-Type` из метаданных, `Content-Length` из S3, `X-Content-Type-Options: nosniff`, `Cache-Control: private, no-store`. `Accept` не учитывается, redirect нет. `X-Request-Id` и `X-Instance-Id` ставит конвейер на `http.response.start`, значит и на поток. `variant` — `Literal["original"]`, иное → `400`.
|
||||
|
||||
### D8. `attachment_ids` в `messaging`
|
||||
|
||||
- `CreateMessageRequest.attachment_ids: list[UUID] = []` — без `max_length` на границе, чтобы членство (`404`) проверялось раньше содержимого; отпечаток `model_dump_json` включает `attachment_ids`, поэтому отсутствующий и `[]` дают один отпечаток, а порядок значим.
|
||||
- `Chat.post(..., attachment_ids)`: членство → `404`; больше 10 или повторы → `InvalidAttachmentList` (`400`); `MessageText` разрешает пустую строку, но не пробельную; пустой текст без вложений → `400`. `Message.attachment_ids: tuple[UUID, ...]`.
|
||||
- `APPEND_MESSAGE` добавляет в тот же оператор `INSERT INTO message_attachments SELECT … FROM unnest($8::uuid[]) WITH ORDINALITY`; внешний ключ проверяется в конце оператора, нарушение откатывает и сообщение, и ключ идемпотентности. `RECEIPT` и история читают `attachment_ids` подзапросом по PK.
|
||||
|
||||
### D9. Стенд
|
||||
|
||||
- `s3`: `rustfs/rustfs:1.0.4@sha256:ed9210d6…`, uid 10001, `read_only` + `tmpfs /tmp`, `cap_drop: ALL`, `RUSTFS_CONSOLE_ENABLE=false`, логи в stdout, root-ключи из `*_FILE`, volume `s3data:/data`, healthcheck `/health/ready`, 1 CPU / 512M, сеть `backend` (internal), портов нет.
|
||||
- `s3-init`: `rustfs/rc:v0.1.36@sha256:ab024bfe…`, `infra/s3/init.sh` — `bucket create --ignore-existing`, `anonymous set private`, политика `messenger-api` из `infra/s3/api-policy.json` (Get/Put/DeleteObject, multipart abort/list, ListBucket, GetBucketLocation на один bucket), пользователь API, lifecycle «abort incomplete multipart за 1 день», самопроверка. `s3-cli` — тот же образ под профилем `tools`, aliases `root`, `api`, `anon`.
|
||||
- `api`: якорь `x-s3-env` подмешивается в `environment` (ключ сервиса заменяет ключ якоря целиком, поэтому не через `x-app`), секреты `s3_access_key_id`, `s3_secret_access_key`, `depends_on: s3-init: service_completed_successfully`.
|
||||
- `scripts/secrets.sh` создаёт hex-секреты S3 (без `:`/`@`, они идут в URL `RC_HOST_*`); `scripts/restart.sh` перезапускает и `s3`, `up --wait` ждёт его `healthy`, поэтому однократное чтение вложения после хука проходит.
|
||||
- Готовность: `/health/ready` от S3 **не** зависит. Иначе при падении S3 LB вывел бы все реплики и отказали бы даже тексты, а ответы LB не несут `X-Instance-Id`. Upload и скачивание при этом получают `503` от приложения.
|
||||
|
||||
### D10. Сценарии и доказательства
|
||||
|
||||
`scripts/lab4_scenarios.py` (stdlib, Python 3.9, импортирует `tests/client.py` для проверки схем и заголовков): `failover-upload` — upload, `stop-one.sh` по `X-Instance-Id` ответа upload, скачивание через другую реплику и сравнение SHA-256, `--restore`; `s3-outage` — `docker compose stop s3`, коды и время upload/скачивания/метаданных/текста/готовности, возврат S3 и повторное скачивание. `scripts/s3-check.sh` — анонимный доступ, порты, консоль, двойной `s3-init`, права ключа API. `scripts/evidence-attachments.sh` — `\d attachments`, листинг bucket, `ReadonlyRootfs` и mounts реплик, сверка байтов вне API. Цели Makefile: `scenario`, `s3-check`, `attachments-evidence`.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- [Строки `pending` после сбоя S3 или `COMMIT` остаются до уровня «4»] → они невидимы клиенту и не мешают ссылкам; компенсация и очистка с grace — следующее изменение.
|
||||
- [Ранний `413`/`404` до конца тела: клиент, ещё отправляющий 10 MiB, может получить reset] → собственные тесты проверяют `413` через `Content-Length`; поведение описано в отчёте.
|
||||
- [`verify()` PNG не распаковывает пиксели] → принято осознанно (D4), записано в ограничениях.
|
||||
- [RustFS молод (GA 2026-09), одиночный узел без parity — SPOF] → версия и digest закреплены, данные на volume, ограничение в отчёте.
|
||||
- [Одновременные загрузки без лимита держат по 10 MiB каждая] → `API_MEMORY=512m`; лимит параллелизма и замер — уровень «4».
|
||||
|
||||
## Migration Plan
|
||||
|
||||
`make up` на существующем стенде лабы 3: `migrate` применяет `0003` под advisory lock, `s3-init` создаёт bucket, реплики стартуют после обоих. Откат: предыдущий образ работает с новой схемой (новые таблицы ему не нужны, ослабленный `CHECK` его не задевает); `make reset-data` удаляет и `s3data`.
|
||||
@@ -0,0 +1,36 @@
|
||||
## Why
|
||||
|
||||
Решение лабы 3 хранит только текст. Рубрика «3» `README.md` лабы 4 требует вложения-изображения: S3-сервер в общем стенде, метаданные в PostgreSQL, байты в приватном bucket, `201 ready` только после сохранения, побайтное скачивание участником, `404` постороннему, лимиты 10 MiB / 40 млн пикселей и тип по содержимому, переживание остановки обслужившей реплики, рестарта стенда и недоступности S3. Контракт 1.4.0 добавляет три операции и обязательное `Message.attachment_ids`. Изменение закрывает уровень «3» и строки 3.1–3.9 `REPORT.md`.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Новая доменная зона `attachments`: `POST /api/v1/chats/{chat_id}/attachments?filename=…` (сырые байты PNG/JPEG, `201 Attachment` со `status=ready`), `GET /api/v1/attachments/{id}`, `GET /api/v1/attachments/{id}/content?variant=original` (байты через API, без redirect). Доступ — только участникам чата, иначе `404`.
|
||||
- Лимиты до неограниченного чтения и декодирования: `Content-Length` и потоковый счётчик (`413`), размер по заголовку изображения (`413`), сигнатура и проверка файла (`415`), `filename` (`400`). Object key `attachments/<uuid>` назначает сервер.
|
||||
- Порядок записи: строка-намерение `pending` → `PutObject` → `ready` и `COMMIT` → `201`. Недоступный S3 — `503` за ограниченное время; тексты продолжают работать, `/health/ready` от S3 не зависит.
|
||||
- Зона `messaging`: `attachment_ids` (0–10 уникальных, только вложения этого чата, иначе `400`/`404`) в отправке, ответе, повторе и истории; `text=""` допустим только с вложением; отсутствующий `attachment_ids` и `[]` — одно тело для `Idempotency-Key`.
|
||||
- Миграция `0003_attachments.sql`: таблицы `attachments` и `message_attachments`, ослабление `messages_text_check` до `≤ 4000`.
|
||||
- Стенд: RustFS 1.0.4 (`s3`, volume `s3data`, без портов, консоль выключена), одноразовый `s3-init` (`rc`: bucket, anonymous `private`, пользователь API с политикой на один bucket), `s3-cli` под профилем `tools`; S3-переменные и ключи API у `api`; `restart.sh` перезапускает и S3.
|
||||
- Сценарии `scripts/lab4_scenarios.py` (`failover-upload`, `s3-outage`), `scripts/s3-check.sh`, цели Makefile, сбор доказательств.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `lab4-attachments`: upload, лимиты и проверка содержимого, метаданные, скачивание оригинала, доступ участников, порядок записи PostgreSQL ↔ S3, поведение при недоступном S3.
|
||||
- `lab4-object-storage`: S3-сервер в стенде, приватный bucket и его bootstrap, раздельные ключи root и API, байты не в БД и не на диске реплики, переживание остановки реплики и рестарта.
|
||||
|
||||
### Modified Capabilities
|
||||
- `lab1-messenger-history`: «Отправка сообщения» — `attachment_ids` и пустой текст с вложением; «Чтение истории keyset-курсором» — элементы несут `attachment_ids`.
|
||||
- `lab3-idempotent-messages`: «Повтор возвращает исходный результат» — `attachment_ids` входит в тело, отсутствующий равен `[]`.
|
||||
- `lab3-load-balancing`: «Рестарт стенда» — хук перезапускает и S3, ждёт его готовности.
|
||||
- `lab2-persistent-storage`: «Данные и сессии переживают рестарт» — вложения и их байты; «Воспроизводимый стенд» — S3 без портов, root-ключи только у S3-сервисов.
|
||||
|
||||
## Impact
|
||||
|
||||
- Код: новая зона `attachments`, зона `messaging`, платформа (лимит тела по маршруту), `main.py` (порт членства), миграция `0003`; зависимости aiobotocore и Pillow.
|
||||
- Стенд: `compose.yaml`, `infra/s3/`, `scripts/`, `Makefile`, `.env.example`, CI.
|
||||
- Тесты: upload и лимиты, подмена MIME, `filename`, доступ, `attachment_ids`, идемпотентность, адаптер S3 против RustFS.
|
||||
- Отчёт: строки 3.1–3.9 в `REPORT.md`, `evidence/`.
|
||||
|
||||
## Non-goals
|
||||
|
||||
Компенсация сбоя между S3 и БД, очистка `pending`, замер памяти под ≥10 загрузками, доказательство ограниченных ключей — уровень «4»; reconciler — трек 2; оба — следующие изменения. Из Out of scope не появляется ничего: `202 queued`, worker и варианты (лаба 5), presigned upload (трек 1), удаление вложений, TLS (лаба 7).
|
||||
+108
@@ -0,0 +1,108 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Отправка сообщения
|
||||
|
||||
Сервис SHALL принимать `POST /api/v1/chats/{chat_id}/messages` от участника чата с телом `{"text":..., "attachment_ids":[...]}` и обязательным заголовком `Idempotency-Key` и возвращать `201` с объектом `Message`. Отправитель SHALL выводиться из предъявленной идентификации; поле `sender_id` в теле запроса SHALL NOT приниматься. `text` SHALL быть обязательным, содержать не более 4000 Unicode code points и SHALL NOT состоять только из пробельных символов; пустая строка допустима только при хотя бы одном вложении. `attachment_ids` SHALL быть необязательным списком из 0–10 уникальных UUID (по умолчанию `[]`); каждое вложение SHALL принадлежать этому чату и быть готовым, иначе ответ `404`. Порядок `attachment_ids` SHALL сохраняться, а одно вложение SHALL допускаться в нескольких сообщениях. Каждый `Message` в ответе SHALL содержать `attachment_ids`, у текстового — `[]`. `id` и `created_at` SHALL назначаться сервером. Правила ключа описаны в `lab3-idempotent-messages`.
|
||||
|
||||
#### Scenario: Сообщение отправлено
|
||||
|
||||
- **WHEN** участник отправляет `{"text":"Привет, мир 👋"}` в свой чат с новым `Idempotency-Key`
|
||||
- **THEN** ответ `201`, тело соответствует схеме `Message`, `attachment_ids` равен `[]`
|
||||
- **AND** `sender_id` равен идентификатору вызывающего, `chat_id` равен чату из пути, `text` побайтово совпадает с отправленным
|
||||
|
||||
#### Scenario: Сообщение с вложением без текста
|
||||
|
||||
- **WHEN** участник отправляет `{"text":"","attachment_ids":[id]}`, где `id` — готовое вложение этого чата
|
||||
- **THEN** ответ `201`, `attachment_ids` равен `[id]`
|
||||
|
||||
#### Scenario: Порядок вложений сохраняется
|
||||
|
||||
- **WHEN** участник отправляет три вложения чата в порядке `[c, a, b]`
|
||||
- **THEN** ответ и история содержат `attachment_ids` в том же порядке `[c, a, b]`
|
||||
|
||||
#### Scenario: Вложение другого чата или неизвестное
|
||||
|
||||
- **WHEN** `attachment_ids` содержит вложение другого чата того же пользователя или несуществующий UUID
|
||||
- **THEN** ответ `404` с кодом `not_found`, сообщение не сохраняется
|
||||
|
||||
#### Scenario: Слишком много, повторы или не UUID
|
||||
|
||||
- **WHEN** `attachment_ids` содержит 11 элементов, повторяющийся UUID или строку не в формате UUID
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Ключ не передан
|
||||
|
||||
- **WHEN** участник отправляет корректное тело без заголовка `Idempotency-Key`
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Отправитель не берётся из тела запроса
|
||||
|
||||
- **WHEN** тело запроса содержит поле `sender_id`
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Пустой или пробельный текст
|
||||
|
||||
- **WHEN** тело содержит `{"text":""}`, `{"text":"","attachment_ids":[]}` или `{"text":" "}` с вложениями или без
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Текст длиннее предела
|
||||
|
||||
- **WHEN** `text` содержит более 4000 Unicode code points
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
- **AND** длина считается в code points, а не в байтах UTF-8
|
||||
|
||||
#### Scenario: Посторонний пишет в чужой чат
|
||||
|
||||
- **WHEN** пользователь, не входящий в состав чата, отправляет корректное сообщение с ключом
|
||||
- **THEN** ответ `404` с кодом `not_found`
|
||||
- **AND** сообщение не сохраняется
|
||||
|
||||
#### Scenario: Доступ проверяется раньше содержимого
|
||||
|
||||
- **WHEN** посторонний отправляет в чужой чат с ключом тело с пустым `text` или с 11 вложениями
|
||||
- **THEN** ответ `404`, а не `400`
|
||||
|
||||
### Requirement: Чтение истории keyset-курсором
|
||||
|
||||
Сервис SHALL отдавать по `GET /api/v1/chats/{chat_id}/messages` страницу `{"items":[...],"next_cursor":...}`. Каждый элемент SHALL содержать `attachment_ids` в порядке отправки. Параметр `limit` SHALL быть целым в диапазоне 1–100 со значением по умолчанию 50. `next_cursor` SHALL быть непрозрачной для клиента строкой либо `null`, если на момент чтения следующей записи нет. Курсор SHALL быть привязан к чату: курсор, выданный для другого чата, SHALL приводить к `400`. Обход неизменной истории SHALL NOT повторять и SHALL NOT пропускать записи; `limit` разрешается менять между страницами.
|
||||
|
||||
#### Scenario: Первая страница отдаёт курсор
|
||||
|
||||
- **WHEN** в чате два сообщения и запрошено `?limit=1`
|
||||
- **THEN** ответ содержит один элемент и непустой `next_cursor`
|
||||
|
||||
#### Scenario: Последняя страница закрывает историю
|
||||
|
||||
- **WHEN** запрошена вторая страница с курсором предыдущей и `limit=1`
|
||||
- **THEN** ответ содержит оставшийся элемент и `next_cursor` равный `null`
|
||||
- **AND** элемент первой страницы не повторяется
|
||||
|
||||
#### Scenario: Элементы истории несут вложения
|
||||
|
||||
- **WHEN** в чате есть текстовое сообщение и сообщение с вложением
|
||||
- **THEN** у текстового элемента `attachment_ids` равен `[]`, у второго — список его вложений, и оба элемента совпадают с ответами `201`
|
||||
|
||||
#### Scenario: Курсор не привязан к читателю
|
||||
|
||||
- **WHEN** курсор, выданный одному участнику чата, предъявляет другой участник того же чата
|
||||
- **THEN** страница отдаётся на общих основаниях
|
||||
|
||||
#### Scenario: Курсор от другого чата
|
||||
|
||||
- **WHEN** курсор, выданный для одного чата, предъявлен при чтении другого чата
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Испорченный или подделанный курсор
|
||||
|
||||
- **WHEN** значение `cursor` не является ранее выданным сервером курсором
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Limit вне допустимого диапазона
|
||||
|
||||
- **WHEN** запрос содержит `limit=0` или `limit=101`
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Посторонний читает чужую историю
|
||||
|
||||
- **WHEN** пользователь, не входящий в состав чата, запрашивает его историю
|
||||
- **THEN** ответ `404` с кодом `not_found`
|
||||
+34
@@ -0,0 +1,34 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Данные и сессии переживают рестарт
|
||||
|
||||
Пользователи, чаты, участники, сообщения со ссылками на вложения, ключи идемпотентности, метаданные вложений, их байты в bucket и ещё действующие сессии SHALL сохраняться при перезапуске балансировщика, всех реплик API и всех хранилищ, включая S3, с сохранёнными volumes. После рестарта прежний токен SHALL работать до своего прежнего `expires_at`, подтверждённое сообщение SHALL читаться побайтно тем же, а загруженное вложение SHALL отдавать те же метаданные и те же байты.
|
||||
|
||||
#### Scenario: Полный рестарт стенда
|
||||
|
||||
- **WHEN** выполняется `make test-persistence ACTION_SCRIPT=scripts/restart.sh`
|
||||
- **THEN** hook перезапускает балансировщик, API и хранилища за ≤90 с с кодом 0, а тест печатает `PASS: persistence preserved confirmed data and existing session`, в том числе после однократного чтения метаданных и байтов вложения
|
||||
|
||||
#### Scenario: Логаут после рестарта
|
||||
|
||||
- **WHEN** после рестарта пользователь отзывает прежний токен
|
||||
- **THEN** ответ `204`, а следующий запрос с этим токеном получает `401`
|
||||
|
||||
### Requirement: Воспроизводимый стенд из репозитория
|
||||
|
||||
Стенд SHALL подниматься из чистого clone командами репозитория: образы сторонних сервисов закреплены версией и digest, API собирается из исходников, bucket и доступ к нему создаёт одноразовый bootstrap. Процессы сервисов SHALL работать не от root, у каждого долгоживущего сервиса SHALL быть healthcheck и лимиты CPU и памяти. Наружу SHALL публиковаться только балансировщик на `127.0.0.1` (порт HTTP и порт статистики); PostgreSQL, Valkey, S3 и реплики API SHALL NOT публиковать порты. Учётные данные SHALL передаваться файлами compose secrets из каталога, исключённого из Git, только тем сервисам, которым они нужны (root-ключи S3 — только S3-сервисам), и SHALL NOT появляться в Git, образе и журнале.
|
||||
|
||||
#### Scenario: Подъём из чистого clone
|
||||
|
||||
- **WHEN** в чистом clone выполняются `make secrets` и `make up`
|
||||
- **THEN** все сервисы становятся `healthy` или завершаются кодом 0 (`migrate`, `s3-init`), а `GET /health/ready` через балансировщик отвечает `200`
|
||||
|
||||
#### Scenario: Опубликован только балансировщик
|
||||
|
||||
- **WHEN** выполняется `docker compose ps --format '{{.Service}} {{.Ports}}'`
|
||||
- **THEN** опубликованные порты есть только у сервиса `lb` и все они привязаны к `127.0.0.1`
|
||||
|
||||
#### Scenario: Секреты и volumes вне Git
|
||||
|
||||
- **WHEN** выполняются `git ls-files secrets .env` и `git check-ignore secrets/database_url secrets/s3_root_password .env`
|
||||
- **THEN** первая команда ничего не выводит, вторая подтверждает, что пути игнорируются
|
||||
+40
@@ -0,0 +1,40 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Повтор возвращает исходный результат
|
||||
|
||||
Область ключа SHALL составлять пользователь сессии, метод и путь чата и сам ключ. Тело запроса для сравнения SHALL включать `text` и `attachment_ids` с учётом порядка вложений; отсутствующий `attachment_ids` SHALL считаться равным `[]`, порядок полей JSON SHALL NOT иметь значения. Повтор с тем же ключом и семантически тем же JSON в течение `IDEMPOTENCY_TTL_SECONDS` (не меньше 86 400 с) SHALL возвращать `201` и тот же объект `Message` — те же `id`, `text`, `attachment_ids` и строку `created_at` — без создания нового сообщения. Тот же ключ с другим JSON SHALL давать `409` с кодом `conflict`. Одинаковый ключ у разных пользователей или в разных чатах SHALL действовать независимо. После истечения срока ключ SHALL приниматься как новый.
|
||||
|
||||
#### Scenario: Повтор того же тела
|
||||
|
||||
- **WHEN** участник повторяет `POST` с тем же ключом и тем же `{"text":...}`
|
||||
- **THEN** ответ `201`, тело равно телу первого ответа целиком, включая `attachment_ids: []`, в истории одно такое сообщение
|
||||
|
||||
#### Scenario: Отсутствующий attachment_ids равен пустому списку
|
||||
|
||||
- **WHEN** первый `POST` содержит `{"text":"x"}`, а повтор с тем же ключом — `{"attachment_ids":[],"text":"x"}`
|
||||
- **THEN** повтор получает `201` с телом первого ответа
|
||||
|
||||
#### Scenario: Повтор сообщения с вложением
|
||||
|
||||
- **WHEN** участник повторяет `POST` с тем же ключом и тем же `{"text":"","attachment_ids":[id]}`
|
||||
- **THEN** ответ `201` с тем же `Message` и `attachment_ids` равным `[id]`
|
||||
|
||||
#### Scenario: Тот же ключ, другое тело
|
||||
|
||||
- **WHEN** участник повторяет `POST` с тем же ключом, но другим `text` или другим списком либо порядком `attachment_ids`
|
||||
- **THEN** ответ `409` с кодом `conflict`, новое сообщение не создаётся
|
||||
|
||||
#### Scenario: Тот же ключ у другого пользователя
|
||||
|
||||
- **WHEN** другой участник того же чата отправляет сообщение с тем же значением ключа
|
||||
- **THEN** ответ `201` с новым сообщением этого участника
|
||||
|
||||
#### Scenario: Тот же ключ в другом чате
|
||||
|
||||
- **WHEN** участник отправляет в другой свой чат сообщение с уже использованным ключом
|
||||
- **THEN** ответ `201` с новым сообщением в этом чате
|
||||
|
||||
#### Scenario: Срок ключа истёк
|
||||
|
||||
- **WHEN** с момента первой отправки прошло больше `IDEMPOTENCY_TTL_SECONDS` и участник отправляет с тем же ключом другой текст
|
||||
- **THEN** ответ `201` с новым сообщением, а не `409`
|
||||
+10
@@ -0,0 +1,10 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Рестарт стенда
|
||||
|
||||
Хук `scripts/restart.sh` SHALL перезапускать балансировщик, все реплики API, PostgreSQL, Valkey и S3-сервер с сохранением volumes, без удаления и повторного заполнения данных, и SHALL завершаться кодом 0 не позднее 90 секунд, когда стенд, включая S3, снова готов: первое же чтение метаданных и байтов вложения после хука SHALL проходить без повторов.
|
||||
|
||||
#### Scenario: Полный рестарт сохраняет сессию
|
||||
|
||||
- **WHEN** выполняется `make test-persistence ACTION_SCRIPT=scripts/restart.sh`
|
||||
- **THEN** тест печатает `PASS: persistence preserved confirmed data and existing session`, а `StartedAt` контейнеров `lb`, `api`, `postgres`, `valkey` и `s3` после прогона позже, чем до него
|
||||
+153
@@ -0,0 +1,153 @@
|
||||
## Purpose
|
||||
|
||||
Определяет вложения-изображения чата: синхронную загрузку оригинала PNG/JPEG с лимитами и проверкой содержимого, метаданные, скачивание оригинала через API, доступ только участникам чата, порядок записи PostgreSQL ↔ S3 и поведение при недоступном S3.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Загрузка оригинала в чат
|
||||
|
||||
Сервис SHALL принимать `POST /api/v1/chats/{chat_id}/attachments?filename=<имя>` от участника чата с телом из сырых байтов одного изображения (не multipart, не JSON) и заголовком `Content-Type: image/png` или `image/jpeg` и возвращать `201` с объектом `Attachment`: `status` `ready`, `variants` `[]`, `error_code` `null`, `chat_id` из пути, `owner_id` вызывающего, `size_bytes` равен длине тела, `sha256` — lowercase hex SHA-256 тела, `content_type` — тип, определённый по содержимому, `filename` — переданное имя. Ответ `201` SHALL выдаваться только после того, как оригинал записан в приватный bucket и метаданные зафиксированы в PostgreSQL. Ключ объекта SHALL назначаться сервером и SHALL NOT зависеть от `filename` и попадать в ответ. Повтор того же запроса SHALL создавать новое вложение.
|
||||
|
||||
#### Scenario: Fixture загружена
|
||||
|
||||
- **WHEN** участник загружает `tests/fixtures/sample.png` с `Content-Type: image/png` и `?filename=sample.png`
|
||||
- **THEN** ответ `201`, тело соответствует схеме `Attachment`, `status` `ready`, `size_bytes` 111817, `sha256` равен SHA-256 файла, `chat_id` и `owner_id` — чат и загрузивший
|
||||
|
||||
#### Scenario: JPEG загружен
|
||||
|
||||
- **WHEN** участник загружает корректный JPEG с `Content-Type: image/jpeg`
|
||||
- **THEN** ответ `201`, `content_type` `image/jpeg`
|
||||
|
||||
#### Scenario: Посторонний загружает в чужой чат
|
||||
|
||||
- **WHEN** пользователь, не входящий в чат, или любой пользователь в несуществующий чат отправляет корректное изображение
|
||||
- **THEN** ответ `404` с кодом `not_found`, ничего не сохраняется
|
||||
|
||||
#### Scenario: Доступ проверяется раньше содержимого
|
||||
|
||||
- **WHEN** посторонний отправляет в чужой чат тело, не являющееся изображением, или опасный `filename`
|
||||
- **THEN** ответ `404`, а не `400` или `415`
|
||||
|
||||
#### Scenario: Без аутентификации
|
||||
|
||||
- **WHEN** upload приходит без `Authorization` или с `Basic`
|
||||
- **THEN** ответ `401` с `WWW-Authenticate: Bearer realm="messenger"`
|
||||
|
||||
### Requirement: Лимиты размера до неограниченного чтения и декодирования
|
||||
|
||||
Тело SHALL быть не больше `MAX_UPLOAD_BYTES` (10 485 760) байт, а изображение — не больше `MAX_IMAGE_PIXELS` (40 000 000) пикселей по заголовку. Превышение SHALL давать `413` с кодом `payload_too_large`. Объявленный `Content-Length` больше лимита SHALL отклоняться без чтения тела, тело без `Content-Length` SHALL читаться не дальше лимита плюс один байт, а число пикселей SHALL проверяться по заголовку изображения до декодирования. Реплика SHALL NOT записывать тело на свой диск.
|
||||
|
||||
#### Scenario: Ровно 10 MiB
|
||||
|
||||
- **WHEN** загружается корректный PNG размером ровно 10 485 760 байт
|
||||
- **THEN** ответ `201` и `size_bytes` 10485760
|
||||
|
||||
#### Scenario: На байт больше с Content-Length
|
||||
|
||||
- **WHEN** загружается тело размером 10 485 761 байт с заголовком `Content-Length`
|
||||
- **THEN** ответ `413` с кодом `payload_too_large`
|
||||
|
||||
#### Scenario: На байт больше без Content-Length
|
||||
|
||||
- **WHEN** тело размером 10 485 761 байт передаётся chunked, без `Content-Length`
|
||||
- **THEN** ответ `413` с кодом `payload_too_large`, вложение не создаётся
|
||||
|
||||
#### Scenario: Ровно 40 млн пикселей
|
||||
|
||||
- **WHEN** загружается корректный PNG 8000×5000
|
||||
- **THEN** ответ `201`
|
||||
|
||||
#### Scenario: Больше 40 млн пикселей
|
||||
|
||||
- **WHEN** загружается PNG 8001×5000 или сжатый PNG огромных размеров весом несколько килобайт
|
||||
- **THEN** ответ `413` с кодом `payload_too_large`, изображение не декодируется
|
||||
|
||||
### Requirement: Тип определяется по содержимому
|
||||
|
||||
Сервис SHALL принимать только `Content-Type` `image/png` и `image/jpeg` (параметры заголовка и регистр не важны) и SHALL проверять, что сигнатура и структура файла соответствуют заявленному типу, а файл читается без ошибок. Иной или отсутствующий `Content-Type`, несовпадение заявленного типа и содержимого, пустое тело, обрезанный или повреждённый файл, GIF, WebP и текст SHALL давать `415` с кодом `unsupported_media_type`.
|
||||
|
||||
#### Scenario: Подмена MIME
|
||||
|
||||
- **WHEN** JPEG, GIF или текст отправлены с `Content-Type: image/png`
|
||||
- **THEN** ответ `415` с кодом `unsupported_media_type`
|
||||
|
||||
#### Scenario: Обрезанное изображение
|
||||
|
||||
- **WHEN** отправлена первая половина корректного PNG или JPEG с верным `Content-Type`
|
||||
- **THEN** ответ `415`
|
||||
|
||||
#### Scenario: Неподдерживаемый Content-Type
|
||||
|
||||
- **WHEN** корректный PNG отправлен с `Content-Type: application/octet-stream` или без `Content-Type`
|
||||
- **THEN** ответ `415`
|
||||
|
||||
### Requirement: Безопасное отображаемое имя
|
||||
|
||||
`filename` SHALL быть обязательным параметром длиной 1–255 Unicode code points после percent-декодирования, SHALL NOT состоять только из пробельных символов и SHALL NOT содержать `/`, `\`, NUL и другие управляющие символы. Нарушение SHALL давать `400` с кодом `invalid_request`. Имя SHALL использоваться только для отображения и возвращаться без изменений.
|
||||
|
||||
#### Scenario: Опасное имя
|
||||
|
||||
- **WHEN** `filename` равен `../a.png`, `a/b.png`, `a\b.png`, содержит `%00`, `%01` или `%7F`
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Пустое, пробельное, длинное или отсутствующее имя
|
||||
|
||||
- **WHEN** `filename` пустой, из пробелов, длиной 256 code points или не передан
|
||||
- **THEN** ответ `400`
|
||||
|
||||
#### Scenario: Имя на кириллице
|
||||
|
||||
- **WHEN** `filename` равен `фото 1.png` длиной до 255 code points
|
||||
- **THEN** ответ `201` и `filename` в ответе совпадает с переданным
|
||||
|
||||
### Requirement: Метаданные и скачивание только участникам
|
||||
|
||||
`GET /api/v1/attachments/{attachment_id}` SHALL возвращать `200 Attachment` участнику чата вложения. `GET /api/v1/attachments/{attachment_id}/content` SHALL возвращать участнику `200` с исходными байтами, `Content-Type` вложения и `Content-Length`, через API, без redirect, вне зависимости от заголовка `Accept`. Параметр `variant` SHALL принимать только `original` (по умолчанию). Посторонний, неизвестный id и ещё не готовое вложение SHALL получать `404` с кодом `not_found`, не раскрывающим существование вложения; невалидный UUID и неизвестный `variant` — `400`. Все ответы, включая бинарный `200`, SHALL нести `X-Request-Id` и `X-Instance-Id`.
|
||||
|
||||
#### Scenario: Второй участник скачивает оригинал
|
||||
|
||||
- **WHEN** второй участник чата запрашивает `/content` загруженного вложения с `Accept: application/json`
|
||||
- **THEN** ответ `200`, `Content-Type: image/png`, байты совпадают с загруженными, SHA-256 равен `sha256` метаданных
|
||||
|
||||
#### Scenario: Посторонний
|
||||
|
||||
- **WHEN** пользователь вне чата запрашивает метаданные или `/content`
|
||||
- **THEN** оба ответа `404` с кодом `not_found`
|
||||
|
||||
#### Scenario: Неизвестный вариант
|
||||
|
||||
- **WHEN** запрошен `/content?variant=thumbnail`
|
||||
- **THEN** ответ `400` с кодом `invalid_request`
|
||||
|
||||
#### Scenario: Объект пропал из хранилища
|
||||
|
||||
- **WHEN** метаданные готового вложения есть, а объекта в bucket нет
|
||||
- **THEN** `/content` отвечает `404`, событие пишется в журнал без ключа объекта
|
||||
|
||||
### Requirement: Порядок записи PostgreSQL и S3
|
||||
|
||||
Сервис SHALL фиксировать намерение (метаданные со статусом, невидимым клиентам) до записи объекта и SHALL переводить вложение в готовое только после подтверждённой записи объекта. Сбой на любом шаге SHALL NOT давать `201` и SHALL NOT оставлять видимого клиентам вложения без объекта. Обрыв клиента до конца тела SHALL NOT оставлять ни объекта, ни строки.
|
||||
|
||||
#### Scenario: S3 отказал при записи
|
||||
|
||||
- **WHEN** запись объекта завершилась ошибкой
|
||||
- **THEN** ответ `503` с кодом `unavailable`, вложение не видно ни в метаданных, ни в сообщениях
|
||||
|
||||
#### Scenario: Клиент оборвал загрузку
|
||||
|
||||
- **WHEN** клиент закрыл соединение, отправив часть тела
|
||||
- **THEN** в bucket нет нового объекта и в PostgreSQL нет новой строки вложения
|
||||
|
||||
### Requirement: Недоступный S3
|
||||
|
||||
Недоступность S3 SHALL превращаться в `503 unavailable` в общем формате ошибки за ограниченное время (меньше `REQUEST_TIMEOUT_SECONDS`) для upload и скачивания. Метаданные, тексты сообщений и `GET /health/ready` SHALL продолжать работать: готовность реплики от S3 не зависит. После возврата S3 ранее загруженные файлы SHALL скачиваться без изменений.
|
||||
|
||||
#### Scenario: S3 остановлен
|
||||
|
||||
- **WHEN** выполняется `docker compose stop s3` и клиент загружает и скачивает файл, отправляет текст и проверяет готовность
|
||||
- **THEN** upload и `/content` отвечают `503` с `X-Request-Id` и `X-Instance-Id` быстрее `REQUEST_TIMEOUT_SECONDS`, текстовое сообщение — `201`, метаданные и `/health/ready` — `200`
|
||||
|
||||
#### Scenario: S3 вернулся
|
||||
|
||||
- **WHEN** S3 снова запущен
|
||||
- **THEN** ранее загруженный файл скачивается с тем же SHA-256
|
||||
+47
@@ -0,0 +1,47 @@
|
||||
## Purpose
|
||||
|
||||
Определяет объектное хранилище вложений как часть стенда: S3-совместимый сервер с закреплённой версией и persistent volume, приватный bucket и воспроизводимый bootstrap, раздельные ключи администратора и API, а также то, что байты не живут в БД и на диске реплики и переживают остановку реплики и рестарт стенда.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: S3-сервер и приватный bucket в стенде
|
||||
|
||||
Стенд SHALL включать S3-совместимый сервер с образом, закреплённым версией и digest, данными на именованном volume и healthcheck, без опубликованных на хост портов и без доступной административной консоли. Одноразовый bootstrap SHALL создавать bucket `S3_BUCKET` (по умолчанию `messenger-attachments`), делать его приватным для анонимного клиента, создавать пользователя API с политикой только на объекты и листинг этого bucket и завершаться кодом 0; повторный запуск SHALL проходить без ошибок и без изменения состояния. Реплики API SHALL стартовать после успешного bootstrap.
|
||||
|
||||
#### Scenario: Анонимный GET объекта
|
||||
|
||||
- **WHEN** из отдельного контейнера в сети стенда выполняется HTTP GET существующего объекта bucket без подписи
|
||||
- **THEN** ответ `403`, байты объекта не возвращаются
|
||||
|
||||
#### Scenario: Порты и консоль
|
||||
|
||||
- **WHEN** выполняется `docker compose ps` и запрос к порту консоли внутри контейнера S3
|
||||
- **THEN** у сервиса S3 нет опубликованных портов, а консоль не отвечает
|
||||
|
||||
#### Scenario: Повторный bootstrap
|
||||
|
||||
- **WHEN** bootstrap запускается ещё два раза на работающем стенде
|
||||
- **THEN** оба запуска завершаются кодом 0, а bucket, его анонимная политика, пользователь и политика API не меняются
|
||||
|
||||
### Requirement: Раздельные ключи и места хранения
|
||||
|
||||
Root-ключи S3 SHALL передаваться файлами compose secrets только S3-серверу, bootstrap и операторскому CLI; реплики API SHALL получать отдельный ключ из `S3_ACCESS_KEY_ID_FILE` и `S3_SECRET_ACCESS_KEY_FILE`. Байты вложений SHALL храниться только в bucket: в PostgreSQL SHALL NOT быть столбцов с содержимым файла, у реплик API SHALL NOT быть volume, а корневая файловая система реплики SHALL быть только для чтения. Ключи и адреса хранилища SHALL NOT попадать в ответы API, журнал и Git.
|
||||
|
||||
#### Scenario: Где лежат байты
|
||||
|
||||
- **WHEN** после загрузки выполняются `\d attachments`, листинг bucket и `docker inspect` реплики API
|
||||
- **THEN** в таблице нет `bytea`, объект лежит в bucket под ключом `attachments/<uuid>`, у реплики `ReadonlyRootfs=true` и нет volume
|
||||
|
||||
#### Scenario: Ключ API
|
||||
|
||||
- **WHEN** проверяются секреты сервиса `api` в `docker compose config`
|
||||
- **THEN** у `api` есть только ключ API S3, а root-ключей нет
|
||||
|
||||
### Requirement: Файл переживает остановку обслужившей реплики
|
||||
|
||||
Вложение, загруженное через одну реплику API, SHALL скачиваться через другую реплику после остановки первой с тем же SHA-256.
|
||||
|
||||
#### Scenario: Upload, остановка реплики, download
|
||||
|
||||
- **WHEN** выполняется `python3 scripts/lab4_scenarios.py failover-upload`: upload, остановка реплики из `X-Instance-Id` ответа хуком `scripts/stop-one.sh`, скачивание
|
||||
- **THEN** скачивание обслуживает другая реплика, SHA-256 совпадает, сценарий печатает `"ok": true`
|
||||
@@ -0,0 +1,56 @@
|
||||
## 1. Схема
|
||||
|
||||
- [x] 1.1 Миграция `0003_attachments.sql`: `attachments` (статус `pending`/`ready`, `object_key COLLATE "C"`, `UNIQUE (id, chat_id)`, FK на `chat_members`, частичный индекс `pending`), `message_attachments` (FK на `attachments (id, chat_id)` `ON DELETE RESTRICT`, индекс по `attachment_id`), ослабленный `messages_text_check`
|
||||
- [x] 1.2 Проверка группы: тест миграций — версия `0003`, повтор без изменений, вложение не участника и ссылка на вложение другого чата отклоняются внешними ключами, пустой текст принимается схемой
|
||||
|
||||
## 2. Зона `attachments`: домен и приложение
|
||||
|
||||
- [x] 2.1 Домен: `Filename`, `ImageKind`, `ImageInfo`, агрегат `Attachment` (`stage` → `pending`, `store` → `ready` с событием `AttachmentStored`), ошибки зоны
|
||||
- [x] 2.2 Порты: `ChatMembership`, `ObjectStorage` (`put`/`open`/`delete`, `ObjectContent`, `ObjectMissing`), `ImageInspector`, `AttachmentsUnitOfWork`, `AttachmentDirectory`
|
||||
- [x] 2.3 Команда `UploadAttachment` и обработчик: членство → имя → `Content-Type` → поток со счётчиком и SHA-256 → проверка изображения → `pending` → `put` → `ready`; запросы `GetAttachment`, `OpenAttachment`
|
||||
- [x] 2.4 Проверка группы: unit-тесты `Filename` (граничные и опасные имена), агрегата и порядка записи обработчика с фейковыми портами (сбой `put` даёт `503` и не делает вложение готовым)
|
||||
|
||||
## 3. Зона `attachments`: инфраструктура и HTTP
|
||||
|
||||
- [x] 3.1 Адаптер PostgreSQL: `add`, `save`, `get` готового; нарушение FK членства → `404`
|
||||
- [x] 3.2 Адаптер `PillowImageInspector`: открытие только PNG/JPEG, подмена MIME, пиксели по заголовку, PNG `verify`, JPEG `draft` + `load`, `to_thread` под семафором
|
||||
- [x] 3.3 Адаптер `S3ObjectStorage` на aiobotocore (path-style, SigV4, таймауты, checksum `when_required`), отображение ошибок в `ObjectMissing`/`Unavailable`; зависимости aiobotocore и Pillow в `uv.lock`
|
||||
- [x] 3.4 Настройки зоны (`S3_*`, `MAX_UPLOAD_BYTES`, `MAX_IMAGE_PIXELS`, таймауты, параллелизм проверки), провайдер dishka, схемы `AttachmentOut`, роутер upload/метаданных/скачивания, реестр ошибок, журнал
|
||||
- [x] 3.5 Проверка группы: тест адаптера S3 против одноразового RustFS (put/open/delete, пропавший объект, недоступный endpoint → `Unavailable` за ограниченное время)
|
||||
|
||||
## 4. Связь зон и платформа
|
||||
|
||||
- [x] 4.1 Платформа: лимит тела по шаблону маршрута в конвейере
|
||||
- [x] 4.2 `main.py`: зона `attachments`, адаптер `MessagingMembership` для порта `ChatMembership`, лимит upload, поля журнала, реестр ошибок; `create_app` принимает дополнительные провайдеры для тестов
|
||||
- [x] 4.3 Проверка группы: тест графа импортов — `attachments` не импортирует `identity`/`messaging`, `messaging` не импортирует `attachments`, `shared` не знает зон
|
||||
|
||||
## 5. Зона `messaging`: `attachment_ids`
|
||||
|
||||
- [x] 5.1 Домен: `Message.attachment_ids`, `Chat.post` с проверкой списка вложений, `MessageText` с пустой строкой, ошибки `InvalidAttachmentList` и `UnknownAttachment`
|
||||
- [x] 5.2 HTTP и команда: `CreateMessageRequest.attachment_ids` (по умолчанию `[]`, отпечаток), `MessageOut.attachment_ids`
|
||||
- [x] 5.3 PostgreSQL: запись `message_attachments` в операторе отправки, FK → `404`, `attachment_ids` в повторе и истории подзапросом
|
||||
- [x] 5.4 Проверка группы: тесты — пустой текст с вложением, порядок, другой чат и неизвестный id `404`, 11 и повторы `400`, посторонний `404` раньше `400`, повтор с вложением, отсутствующий ≡ `[]`, другой порядок `409`, история с `attachment_ids`
|
||||
|
||||
## 6. API-тесты вложений
|
||||
|
||||
- [x] 6.1 Генераторы тестовых PNG (произвольный размер в пикселях и байтах) и JPEG, фейковое `ObjectStorage` в `student-tests`
|
||||
- [x] 6.2 Тесты: fixture `201` и побайтное скачивание вторым участником, посторонний `404` на метаданных и `/content`, ровно 10 MiB `201`, +1 байт `413` с `Content-Length` и chunked, 40 MP `201` и 40 MP+ `413`, подмена MIME, обрезанные PNG/JPEG, иной и пустой `Content-Type` `415`, опасные и пустые `filename` `400`, `variant=thumbnail` `400`, сбой хранилища `503` без готового вложения, пропавший объект `404`, заголовки на бинарном ответе
|
||||
|
||||
## 7. Стенд
|
||||
|
||||
- [x] 7.1 `infra/s3/` (`init.sh`, `cli.sh`, `api-policy.json`, `lifecycle.json`) из заготовки
|
||||
- [x] 7.2 `compose.yaml`: `s3`, `s3-init`, `s3-cli`, volume `s3data`, секреты S3, якорь `x-s3-env` у `api`, зависимость от `s3-init`; `.env.example` (таймауты S3, параллелизм проверки)
|
||||
- [x] 7.3 `scripts/secrets.sh` (секреты S3), `scripts/restart.sh` (S3 в списке хранилищ), `scripts/evidence-stack.sh` (пакеты и образы лабы 4)
|
||||
- [x] 7.4 Проверка группы: `docker compose config --quiet`, у `api` только ключ API S3, `make up` из чистого состояния, все сервисы `healthy`, `s3-init` завершился кодом 0, опубликованы только порты `lb`
|
||||
|
||||
## 8. Сценарии отказов и обвязка
|
||||
|
||||
- [x] 8.1 `scripts/lab4_scenarios.py` (`failover-upload`, `s3-outage`), `scripts/s3-check.sh`, `scripts/evidence-attachments.sh`; цели Makefile `scenario`, `s3-check`, `attachments-evidence`; ruff для новых `scripts/*.py`
|
||||
- [x] 8.2 CI-job под лабу 4: сценарии вложений после smoke
|
||||
- [x] 8.3 Проверка группы: `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`, `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` по обеим репликам с `make restore`, `make scenario SCENARIO=failover-upload`, `make scenario SCENARIO=s3-outage`, `make s3-check`
|
||||
|
||||
## 9. Отчёт
|
||||
|
||||
- [x] 9.1 `evidence/`: smoke, contract-checks, student-tests, stack, storage-layout, failover-upload, failover по каждой реплике, persistence со `StartedAt` (включая `s3`), s3-outage, s3-security, схема и миграции, окружение
|
||||
- [x] 9.2 `REPORT.md`: запуск из чистого clone, архитектура и решения, таблица ролей и сервисов, соответствие переменных `.env.example`, строки уровня «3», таблица отказов уровня «3»
|
||||
- [x] 9.3 Проверка группы: `make check`, `make validate`, `make lint`, `make student-test`, `make test` и сценарии зелёные
|
||||
@@ -0,0 +1,4 @@
|
||||
schema: spec-driven
|
||||
created: 2026-10-28
|
||||
archived: 2026-10-29
|
||||
lab: 4
|
||||
@@ -0,0 +1,103 @@
|
||||
## Context
|
||||
|
||||
Уровень «3» (архив `2026-10-28-add-lab4-image-attachments`, D3 и D5) пишет так: `INSERT pending` + `COMMIT` → `PutObject` → `UPDATE … SET status='ready' WHERE status='pending'` + `COMMIT` → `201`. Сбой между шагами оставляет невидимую строку `pending` и, если `PUT` прошёл, объект; их никто не убирает. Тело копится списком кусков и склеивается (до 2 × 10 MiB на миг склейки), число одновременных загрузок не ограничено: при 2 воркерах на реплику и `API_MEMORY=512m` десяток загрузок по 10 MiB на воркер уже упирается в лимит. Обрыв клиента посреди тела поднимает `ClientDisconnect` Starlette, который уходит в общий обработчик как `500`. Таймаут запроса (`REQUEST_TIMEOUT_SECONDS=8`) уже обрывает зависшее тело ответом `503`. Проверка S3 (`make s3-check`, 22 проверки) уже есть.
|
||||
|
||||
Изменение затрагивает только зону `attachments` и сборку в `main.py`; схема БД не меняется, контракт не меняется.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Любая строка `pending` и любой объект, оставленные сбоем, исчезают сами: сразу (компенсация) или через grace period (уборка). Объекта без строки не бывает.
|
||||
- Пик памяти реплики ограничен конфигурацией, а не числом клиентов; это подтверждено замером.
|
||||
- Каждый отказ из рубрики «4» воспроизводится одной командой против стенда.
|
||||
|
||||
**Non-Goals:**
|
||||
- Сверка «объект без строки», «строка `ready` без объекта», несовпадение размера и SHA-256, отчёт `--dry-run` — трек 2: при правильной работе уровня «4» таких расхождений нет, их внедряют руками.
|
||||
- Отдельный сервис-уборщик и расписание вне API.
|
||||
|
||||
## Decisions
|
||||
|
||||
### D1. Компенсация — «удалить, если не готово» под блокировкой строки
|
||||
|
||||
`UploadAttachmentHandler` после `PUT` выполняет перевод в `ready` в `try`. При любой ошибке (`Exception`) — компенсация `discard`:
|
||||
|
||||
1. транзакция; `SELECT … FROM attachments WHERE id=$1 FOR UPDATE`;
|
||||
2. строка `ready` → ничего не делать (фиксация на самом деле прошла: ответ `503`, повтор клиента создаст дубль — это допустимо);
|
||||
3. иначе `DeleteObject(object_key)` (идемпотентен), агрегат `discard("compensation")` → событие `AttachmentDiscarded`, `DELETE … WHERE id=$1 AND status='pending'`, `COMMIT`;
|
||||
4. ошибка компенсации пишется в журнал (`attachment.compensation_failed`) и глотается; клиенту уходит исходная ошибка (`503`).
|
||||
|
||||
Порядок «сначала объект, потом строка» сохраняет инвариант: пока объект существует, существует и строка-намерение с его ключом. Блокировка строки на время одного `DeleteObject` (≤ 2 × (1 + 2) = 6 с < `idle_in_transaction_session_timeout` 10 с) нужна, чтобы задержавшийся `UPDATE ready` той же загрузки не проскочил между удалением объекта и строки. В D5 уровня «3» транзакция вокруг `PUT` отвергнута из-за длинной сетевой операции на горячем пути; здесь блокировка берётся только на пути сбоя и в фоне. За это получаем отсутствие окна «`ready` без объекта»; стоит это соединение пула на время одного запроса к S3 при сбое.
|
||||
|
||||
`CancelledError` (таймаут запроса посреди `PUT` или `UPDATE`) компенсацию не запускает: исход `PUT` неизвестен, отложенный объект может появиться позже. Это доделывает уборка после grace period. Сбой самого `PUT` тоже не компенсируется сразу: S3, скорее всего, недоступен, а лишняя попытка удвоила бы время ответа `503`.
|
||||
|
||||
Перевод в `ready` проверяет число обновлённых строк: `UPDATE 0` значит, что намерение уже убрано (уборка при слишком малом grace); адаптер поднимает `Unavailable`, компенсация не находит строку и удаляет объект — `201` без строки невозможен.
|
||||
|
||||
Отвергнуто: удалять строку `pending` сразу при сбое `PUT` (объект может появиться после ответа — останется без строки); статус `discarding` и миграция (лишнее состояние: блокировка строки даёт то же без изменения схемы).
|
||||
|
||||
### D2. Уборка — фоновый проход в каждом воркере с `SKIP LOCKED`
|
||||
|
||||
Команда `SweepAbandonedUploads(grace, limit)` и её обработчик в зоне `attachments`. Проход повторяет шаг по одной строке, пока не наберёт `limit` или строки не кончатся:
|
||||
|
||||
```sql
|
||||
SELECT … FROM attachments
|
||||
WHERE status = 'pending' AND created_at < $1
|
||||
ORDER BY created_at LIMIT 1
|
||||
FOR UPDATE SKIP LOCKED
|
||||
```
|
||||
|
||||
`$1 = clock.now() - grace`; план — `Index Scan` по частичному индексу `attachments_pending_idx (created_at) WHERE status = 'pending'` из миграции `0003`, без чтения готовых строк. Дальше тот же шаг, что в компенсации: `DeleteObject` → `discard("abandoned")` → `DELETE … AND status='pending'` → `COMMIT`. Ошибка S3 откатывает транзакцию и прерывает проход до следующего интервала. Готовые строки и вложения в сообщениях не выбираются по условию `status='pending'`; на `ready` к тому же ссылается `message_attachments` с `ON DELETE RESTRICT`.
|
||||
|
||||
Точка входа — `UploadSweeper` в `attachments/entrypoints/sweeper.py`: задача asyncio, раз в `UPLOAD_SWEEP_INTERVAL_SECONDS` (30 с) открывает scope `REQUEST` контейнера dishka, берёт `AttachmentsCommandBus` и выполняет команду; ошибки пишет в журнал (`attachments.sweep_failed`), число удалённых — `attachments.swept`. `main.py` запускает её в lifespan после шины событий и отменяет первой при остановке. 2 реплики × 2 воркера = 4 прохода за интервал; `SKIP LOCKED` делает их независимыми, лишняя цена — один индексный запрос на проход.
|
||||
|
||||
Grace period `UPLOAD_GRACE_SECONDS=900`, не меньше 60 (валидация настроек). Жизнь загрузки от `INSERT pending` до `UPDATE ready` ограничена `REQUEST_TIMEOUT_SECONDS=8`, отложенный `PUT` после обрыва — таймаутами S3 (6 с); 900 с перекрывают это с запасом более чем в 50 раз, включая расхождение часов реплик (один хост, время из `Clock`). Почему не в отдельном сервисе: ещё один контейнер Python (~60 MiB) ради одного индексного запроса в 30 с; почему не по cron оператором: рубрика требует механизма, который не оставляет вечных объектов без участия человека.
|
||||
|
||||
Отвергнуто: `pg_advisory_lock` на весь проход (одна реплика держит соединение, пока ходит в S3; `SKIP LOCKED` распределяет строки без этого); удаление строки до объекта (сбой между шагами оставил бы объект без строки).
|
||||
|
||||
### D3. Память — слоты загрузки на воркер
|
||||
|
||||
`UploadSlots` — `asyncio.Semaphore(UPLOAD_CONCURRENCY)` на воркер (scope `APP`). Обработчик сначала проверяет членство, `filename` и `Content-Type` (дёшево, без тела), затем под слотом читает тело, проверяет изображение, пишет `pending` и делает `PutObject`. Буфер живёт только внутри метода записи и освобождается до перевода в `ready`. Без слота тело не читается: uvicorn приостанавливает чтение сокета, когда в его буфере больше 64 KiB, поэтому ждущая загрузка занимает десятки KiB; очередь ограничена `maxconn 64` HAProxy на реплику и таймаутом запроса (дольше 8 с — `503`).
|
||||
|
||||
Оценка до замера: одна загрузка 10 MiB — тело (10 MiB) плюс склейка (+10 MiB на миг) плюс копия в клиенте S3 — до ~30 MiB; `UPLOAD_CONCURRENCY=3` → 2 воркера × 3 × 30 MiB ≈ 180 MiB поверх простоя реплики при лимите 512 MiB.
|
||||
|
||||
Замер D5 уточнил картину в двух местах, и решение дополнено:
|
||||
|
||||
- **Ожидающая загрузка живёт в буферах сокетов.** Слот держит тело вне памяти воркера, но клиент продолжает слать, и байты копятся в ядре по цепочке: автонастройка TCP растит буфер приёма до 6 MiB на соединение, а память сокетов учитывается в cgroup контейнера. Первый прогон с 3 слотами при 40 одновременных загрузках по 10 MiB убил HAProxy по OOM (лимит 128 MiB, `memory.stat sock` ≈ 110 MB), соединения оборвались. Поэтому HAProxy получает `tune.rcvbuf.client/server` и `tune.sndbuf.client/server` по 64 KiB, а у `api` — `net.ipv4.tcp_rmem`/`tcp_wmem` с максимумом 256 KiB (sysctl сетевого namespace в `compose.yaml`). Пик LB после этого — 30 MiB; на пропускную способность внутри одного хоста буферы не влияют. Ожидающая загрузка стоит ~0,3 MiB на LB и столько же на реплике; число таких соединений ограничивает `maxconn 64` на реплику.
|
||||
- **Аллокатор glibc не отдаёт освобождённые тела.** Тела больше 128 KiB берутся у `malloc`; после первого освобождения крупного блока glibc поднимает порог `mmap` до 32 MiB, и следующие буферы по 10 MiB остаются в куче процесса после освобождения. `MALLOC_MMAP_THRESHOLD_=131072` у `api` фиксирует порог: большие буферы выделяются `mmap` и возвращаются системе. При 3 слотах и 40 загрузках по 10 MiB пик реплики — 330 MiB против 368 MiB с порогом 32 MiB.
|
||||
|
||||
Итог замера: одна загрузка 10 MiB в полёте стоит ≈ 35 MiB, 6 слотов на реплику — ≈ 210 MiB поверх простоя ~120 MiB, пик 304–330 MiB (до 64 % лимита) при 10–40 одновременных загрузках. Без лимита (64 слота) те же 40 загрузок упираются в 512 MiB: успешны 43 из 80, остальные получают `503`, а в предварительном прогоне ядро ещё и убило воркер. Значение `UPLOAD_CONCURRENCY=3` оставлено.
|
||||
|
||||
### D4. Обрыв и зависание тела
|
||||
|
||||
`ClientDisconnect` — транспортное понятие, поэтому HTTP-слой зоны оборачивает `request.stream()` и превращает его в доменную ошибку `UploadAborted` (`400 invalid_request` в реестре зоны). Ответ клиенту не доходит, но журнал реплики пишет `400`, а не `500`. Строка не создаётся: она пишется только после чтения и проверки всего тела. Зависшее тело обрывает конвейер (`asyncio.timeout`, `503`), слот освобождается выходом из `async with` при отмене.
|
||||
|
||||
### D5. Проверки против стенда и замер
|
||||
|
||||
`student-tests/stack/test_attachment_faults.py` (маркер `stack`, `make upload-faults` пишет вывод в `evidence/upload-faults.txt`):
|
||||
|
||||
- негативный suite через LB с настоящими PostgreSQL и RustFS; после прогона — `docker compose logs api --since` без `"status":500`, строк вложений в чате ровно столько, сколько `201`;
|
||||
- внедрение сбоев триггером PostgreSQL на время теста (снимается в `finally`): `AFTER INSERT` записывает id и ключ намерения в служебную таблицу (переживает откат), `BEFORE UPDATE` для имён `fault-fail-*` поднимает `55P03` (отказ `COMMIT` → компенсация), для `fault-crash-*` спит 1,8 с — за это время тест находит реплику по `client_addr` спящего backend и убивает её `docker kill -s KILL` (падение процесса между `PUT` и `COMMIT`);
|
||||
- `created_at` брошенного намерения сдвигается на 2 × grace назад — так проверка не ждёт 15 минут; свежее намерение остаётся и переживает проход;
|
||||
- обрыв и зависание тела — сырым сокетом через LB с собственным `X-Request-Id`, статус ищется в журнале реплики.
|
||||
|
||||
Замер памяти: `scripts/lab4_seed.py` из заготовки (режим `http`, `--sample`: `docker stats` в фоне и `memory.peak` cgroup в конце; добавлены `memory.current` до нагрузки и счётчик `oom_kill` из `memory.events`, заголовок `X-Instance-Id` читается без учёта регистра) и `scripts/upload_memory.py` (Python вместо задуманного `upload-memory.sh`: сводка и вызов генератора проще без оболочки): для `UPLOAD_CONCURRENCY` ∈ {64 (фактически без лимита), 3} × размер ∈ {1, 10 MiB} × одновременность ∈ {10, 20, 40} пересоздаёт реплики и LB (`memory.peak` на ядре Docker Desktop не сбрасывается), ждёт LB и делает 2 × c загрузок; пик LB снимается отдельно; сводка — `evidence/upload-memory/summary.txt`, сравнение порога `mmap` — `evidence/upload-memory/mmap-32m/`.
|
||||
|
||||
### D6. Проверка S3
|
||||
|
||||
`scripts/s3-check.sh` получает проверку консоли из отдельного контейнера сети стенда (`wget http://s3:9001/` — отказ соединения); остальное уже покрывает строку 4.4: два повторных bootstrap без изменения снимка IAM, разрешённые и запрещённые операции ключа API, анонимный доступ, прямой HTTP GET.
|
||||
|
||||
### D7. Платформа: события команды из нескольких транзакций
|
||||
|
||||
Компенсация фиксирует удаление уже после неудачного `COMMIT`, а проход уборки — по транзакции на строку и завершается откатом пустого поиска. Базовая `PostgresUnitOfWork` при любом откате очищала все накопленные события команды, а `CommandBus` не публиковал события, если обработчик бросил исключение, — журнал терял зафиксированные удаления. Теперь откат убирает только события, записанные внутри этой транзакции, а шина публикует собранное и при исключении обработчика. Это механизм платформы (`shared/`), доменных понятий он не добавляет; события по-прежнему появляются только из зафиксированных транзакций. Проверяется тестами компенсации и параллельной уборки по событиям `AttachmentDiscarded`.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- [Grace меньше реального времени жизни загрузки] → минимум 60 с в настройках, по умолчанию 900 с; даже при ошибке D1 гарантирует `503` и удаление объекта вместо `ready` без строки.
|
||||
- [Отменённый таймаутом `PUT` допишет объект после ответа] → строка-намерение остаётся, уборка удалит объект после grace.
|
||||
- [Уборка в каждом воркере даёт 4 запроса за интервал] → индексный запрос по частичному индексу; при пустом результате — одна строка плана.
|
||||
- [Слоты держат клиентов в ожидании] → ожидание ограничено таймаутом запроса; при длительной перегрузке клиент получает `503` и повторяет, а не реплика уходит в OOM.
|
||||
- [Триггер внедрения сбоев остался бы в БД при падении теста] → снимается в `finally` фикстуры, имена с префиксом `lab4_fault`, срабатывает только на `filename LIKE 'fault-%'`.
|
||||
- [`docker kill` реплики в тесте] → реплика возвращается `docker compose up -d --wait --no-recreate`, тест ждёт двух `UP` в LB.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
Схема не меняется; новые переменные имеют значения по умолчанию. Откат — прежний образ API: строки `pending` он не трогает, они остаются невидимыми.
|
||||
@@ -0,0 +1,32 @@
|
||||
## Why
|
||||
|
||||
Уровень «3» оставил три долга: строка-намерение `pending` после сбоя S3, `COMMIT` или процесса остаётся навсегда (а вместе с ней — объект, записанный до сбоя); одновременные загрузки ничем не ограничены, и каждая держит до 20 MiB; права ключа API и закрытость консоли проверены, но не сведены в критерий. Рубрика «4» `README.md` требует: тесты на большой, битый и подменённый файл, чужое вложение и вложение другого чата без `500`; компенсацию и очистку с безопасным grace period; ограниченную память и замер ≥10 одновременных загрузок; идемпотентный bootstrap, ограниченные ключи, закрытую консоль и проверку приватности вне API. Изменение закрывает уровень «4» и строки 4.1–4.4 `REPORT.md`.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Компенсация: если после записи объекта не удалось перевести вложение в `ready`, обработчик сразу под блокировкой строки удаляет объект и строку `pending`; строку `ready` не трогает никогда. Пропавшая строка-намерение при переводе в `ready` даёт `503`, а не готовое вложение без строки.
|
||||
- Уборка: фоновый проход в каждой реплике раз в `UPLOAD_SWEEP_INTERVAL_SECONDS` удаляет объект и строку `pending` старше `UPLOAD_GRACE_SECONDS` (900 с ≫ `REQUEST_TIMEOUT_SECONDS`), по одной строке под `FOR UPDATE SKIP LOCKED`; свежие намерения, `ready` и вложения в сообщениях не трогает.
|
||||
- Обрыв клиента посреди тела — `400` в журнале вместо `500`, ничего не пишется; зависшее тело обрывается таймаутом запроса (`503`), слот освобождается.
|
||||
- Память: не больше `UPLOAD_CONCURRENCY` тел в памяти воркера одновременно, остальные загрузки ждут слота, не читая тело; замер пика памяти при 10, 20 и 40 одновременных загрузках 1 и 10 MiB с лимитом и без.
|
||||
- Стенд: негативный suite и сценарии сбоев через LB против настоящих RustFS и PostgreSQL (`make upload-faults`): ошибка `COMMIT` и падение процесса между `PUT` и `COMMIT` внедряются триггером PostgreSQL, обрыв и зависание тела — сырым сокетом; журнал реплик не содержит `500`.
|
||||
- `make s3-check` дополняется проверкой консоли из сети стенда; результаты сводятся в строку 4.4.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `lab4-upload-resilience`: компенсация сбоя между S3 и PostgreSQL, уборка брошенных загрузок с grace period, обрыв и зависание тела, ограничение памяти одновременных загрузок, пользовательские ошибки файлов без `500`.
|
||||
|
||||
### Modified Capabilities
|
||||
- `lab4-attachments`: «Порядок записи PostgreSQL и S3» — намерение и объект после сбоя убираются компенсацией или уборкой.
|
||||
- `lab4-object-storage`: «S3-сервер и приватный bucket в стенде» — консоль недоступна из сети стенда; «Раздельные ключи и места хранения» — проверяемые запреты ключа API.
|
||||
|
||||
## Impact
|
||||
|
||||
- Код: зона `attachments` (домен, обработчики, адаптер PostgreSQL, настройки, фоновая уборка, HTTP-слой), `main.py` (запуск уборки); схема БД не меняется.
|
||||
- Стенд: `compose.yaml` (буферы сокетов и порог `mmap` у `api`), `infra/haproxy/haproxy.cfg` (буферы сокетов LB), `.env.example`, `scripts/lab4_seed.py` из заготовки и `scripts/upload_memory.py`, `scripts/s3-check.sh`, `Makefile`, CI.
|
||||
- Тесты: `student-tests/api` (компенсация, уборка, слоты, обрыв, таймаут), `student-tests/stack` (стенд).
|
||||
- Отчёт: строки 4.1–4.4, таблица отказов, раздел эксперимента, `evidence/`.
|
||||
|
||||
## Non-goals
|
||||
|
||||
Reconciler для объектов без строки, пропавших объектов и несовпадения байтов, `--dry-run`/`--apply` и стоимость обхода — трек 2, следующее изменение. Удаление вложений пользователем, `202 queued` и варианты (лаба 5), presigned upload (трек 1) — Out of scope.
|
||||
+15
@@ -0,0 +1,15 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Порядок записи PostgreSQL и S3
|
||||
|
||||
Сервис SHALL фиксировать намерение (метаданные со статусом, невидимым клиентам) до записи объекта и SHALL переводить вложение в готовое только после подтверждённой записи объекта. Сбой на любом шаге SHALL NOT давать `201` и SHALL NOT оставлять видимого клиентам вложения без объекта. Обрыв клиента до конца тела SHALL NOT оставлять ни объекта, ни строки. Намерение и объект, оставшиеся после сбоя, SHALL удаляться компенсацией сразу или уборкой по истечении grace period (capability `lab4-upload-resilience`), поэтому объект без строки-намерения в bucket не остаётся.
|
||||
|
||||
#### Scenario: S3 отказал при записи
|
||||
|
||||
- **WHEN** запись объекта завершилась ошибкой
|
||||
- **THEN** ответ `503` с кодом `unavailable`, вложение не видно ни в метаданных, ни в сообщениях, а строка-намерение удаляется уборкой после grace period
|
||||
|
||||
#### Scenario: Клиент оборвал загрузку
|
||||
|
||||
- **WHEN** клиент закрыл соединение, отправив часть тела
|
||||
- **THEN** в bucket нет нового объекта и в PostgreSQL нет новой строки вложения
|
||||
+39
@@ -0,0 +1,39 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: S3-сервер и приватный bucket в стенде
|
||||
|
||||
Стенд SHALL включать S3-совместимый сервер с образом, закреплённым версией и digest, данными на именованном volume и healthcheck, без опубликованных на хост портов и без доступной административной консоли — ни внутри контейнера, ни из сети стенда. Одноразовый bootstrap SHALL создавать bucket `S3_BUCKET` (по умолчанию `messenger-attachments`), делать его приватным для анонимного клиента, создавать пользователя API с политикой только на объекты и листинг этого bucket и завершаться кодом 0; повторный запуск SHALL проходить без ошибок и без изменения состояния. Реплики API SHALL стартовать после успешного bootstrap.
|
||||
|
||||
#### Scenario: Анонимный GET объекта
|
||||
|
||||
- **WHEN** из отдельного контейнера в сети стенда выполняется HTTP GET существующего объекта bucket без подписи
|
||||
- **THEN** ответ `403`, байты объекта не возвращаются
|
||||
|
||||
#### Scenario: Порты и консоль
|
||||
|
||||
- **WHEN** выполняется `docker compose ps`, запрос к порту консоли внутри контейнера S3 и запрос к тому же порту из отдельного контейнера сети стенда
|
||||
- **THEN** у сервиса S3 нет опубликованных портов, а консоль не отвечает ни там, ни там
|
||||
|
||||
#### Scenario: Повторный bootstrap
|
||||
|
||||
- **WHEN** bootstrap запускается ещё два раза на работающем стенде
|
||||
- **THEN** оба запуска завершаются кодом 0, а bucket, его анонимная политика, пользователь и политика API не меняются
|
||||
|
||||
### Requirement: Раздельные ключи и места хранения
|
||||
|
||||
Root-ключи S3 SHALL передаваться файлами compose secrets только S3-серверу, bootstrap и операторскому CLI; реплики API SHALL получать отдельный ключ из `S3_ACCESS_KEY_ID_FILE` и `S3_SECRET_ACCESS_KEY_FILE`. Ключ API SHALL разрешать только чтение, запись, удаление объектов и листинг bucket `S3_BUCKET` и SHALL получать `AccessDenied` на создание и удаление bucket, изменение его политики и lifecycle, администрирование пользователей и любые операции с другим bucket. Байты вложений SHALL храниться только в bucket: в PostgreSQL SHALL NOT быть столбцов с содержимым файла, у реплик API SHALL NOT быть volume, а корневая файловая система реплики SHALL быть только для чтения. Ключи и адреса хранилища SHALL NOT попадать в ответы API, журнал и Git.
|
||||
|
||||
#### Scenario: Где лежат байты
|
||||
|
||||
- **WHEN** после загрузки выполняются `\d attachments`, листинг bucket и `docker inspect` реплики API
|
||||
- **THEN** в таблице нет `bytea`, объект лежит в bucket под ключом `attachments/<uuid>`, у реплики `ReadonlyRootfs=true` и нет volume
|
||||
|
||||
#### Scenario: Ключ API
|
||||
|
||||
- **WHEN** проверяются секреты сервиса `api` в `docker compose config`
|
||||
- **THEN** у `api` есть только ключ API S3, а root-ключей нет
|
||||
|
||||
#### Scenario: Права ключа API вне API
|
||||
|
||||
- **WHEN** из отдельного контейнера ключом API выполняются запись, чтение, листинг и удаление объекта, а затем создание и удаление bucket, публичная политика, импорт lifecycle, список пользователей, запись и листинг в другом bucket
|
||||
- **THEN** первые четыре операции разрешены, остальные получают `AccessDenied`
|
||||
+80
@@ -0,0 +1,80 @@
|
||||
## Purpose
|
||||
|
||||
Определяет устойчивость загрузки вложений: что остаётся после сбоя между записью объекта и фиксацией метаданных и кто это убирает, какой grace period защищает идущие загрузки, как обрываются прерванные и зависшие загрузки, сколько памяти занимают одновременные загрузки и что пользовательские ошибки файлов не превращаются в `500`.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Компенсация сбоя после записи объекта
|
||||
|
||||
Если объект записан в bucket, а перевод вложения в готовое не зафиксирован, сервис SHALL ответить `503` с кодом `unavailable` и до ответа SHALL попытаться удалить объект и строку-намерение. Строку, которая к этому моменту уже готова, сервис SHALL NOT удалять вместе с её объектом. Если строку-намерение к моменту перевода в готовое уже убрали, сервис SHALL ответить `503` и удалить записанный объект, а не возвращать `201`. Неудача компенсации SHALL оставлять строку-намерение для уборки по grace period.
|
||||
|
||||
#### Scenario: Отказ COMMIT после записи объекта
|
||||
|
||||
- **WHEN** запись объекта прошла, а фиксация статуса `ready` в PostgreSQL отклонена
|
||||
- **THEN** ответ `503` с кодом `unavailable`, сразу после ответа нет ни строки вложения, ни объекта с его ключом, в журнале есть событие удаления намерения с причиной `compensation`
|
||||
|
||||
#### Scenario: Намерение снято раньше, чем загрузка завершилась
|
||||
|
||||
- **WHEN** во время записи объекта строку-намерение удалили
|
||||
- **THEN** ответ `503`, объект с ключом этой загрузки удалён, готового вложения не появилось
|
||||
|
||||
### Requirement: Уборка брошенных загрузок по grace period
|
||||
|
||||
Сервис SHALL без участия оператора и не реже чем раз в `UPLOAD_SWEEP_INTERVAL_SECONDS` удалять сначала объект, затем строку каждого намерения `pending`, созданного раньше чем `UPLOAD_GRACE_SECONDS` назад. Grace period SHALL быть не меньше 60 с и много больше `REQUEST_TIMEOUT_SECONDS`, чтобы идущая загрузка не была убрана. Уборка SHALL NOT трогать намерения моложе grace period, готовые вложения и вложения, на которые ссылаются сообщения, SHALL быть безопасной при одновременной работе на нескольких репликах и повторяемой: следующий проход после полного SHALL ничего не удалять. Если S3 недоступен, намерение SHALL оставаться до следующего прохода.
|
||||
|
||||
#### Scenario: Процесс упал между записью объекта и фиксацией
|
||||
|
||||
- **WHEN** процесс реплики убит после записи объекта, но до фиксации `ready`, а затем намерение становится старше grace period
|
||||
- **THEN** до истечения grace period строка `pending` и объект остаются невидимыми клиентам; после — уборка удаляет и объект, и строку
|
||||
|
||||
#### Scenario: Свежее намерение переживает уборку
|
||||
|
||||
- **WHEN** проход уборки выполняется, пока одно брошенное намерение старше grace period, а другое моложе
|
||||
- **THEN** удалено только старое, свежее остаётся вместе со своим объектом
|
||||
|
||||
#### Scenario: Готовые и используемые вложения не трогаются
|
||||
|
||||
- **WHEN** проход уборки выполняется после того, как время создания готового вложения, на которое ссылается сообщение, сдвинуто далеко в прошлое
|
||||
- **THEN** вложение по-прежнему скачивается участником с тем же SHA-256
|
||||
|
||||
#### Scenario: Несколько уборок одновременно
|
||||
|
||||
- **WHEN** два прохода уборки одновременно обрабатывают пять брошенных намерений
|
||||
- **THEN** вместе они удаляют ровно пять, без ошибок, а следующий проход удаляет ноль
|
||||
|
||||
### Requirement: Обрыв и зависание тела
|
||||
|
||||
Обрыв клиента до конца тела SHALL NOT оставлять ни объекта, ни строки вложения и SHALL учитываться как ошибка клиента (`400`), а не `500`. Тело, которое перестало поступать, SHALL обрываться не позже `REQUEST_TIMEOUT_SECONDS` с ответом `503` и кодом `unavailable`, без объекта и строки, а занятый им слот загрузки SHALL освобождаться для следующих загрузок.
|
||||
|
||||
#### Scenario: Клиент закрыл соединение посреди тела
|
||||
|
||||
- **WHEN** клиент объявил `Content-Length` 5 MiB, отправил 256 KiB и закрыл соединение
|
||||
- **THEN** строка вложения не создавалась, объект не появился, реплика записала в журнал статус `400`
|
||||
|
||||
#### Scenario: Тело зависло
|
||||
|
||||
- **WHEN** клиент отправил заголовки и часть тела и перестал слать байты
|
||||
- **THEN** не позже `REQUEST_TIMEOUT_SECONDS` плюс 2 с приходит `503` с кодом `unavailable`, строки и объекта нет, следующая загрузка проходит
|
||||
|
||||
### Requirement: Ограниченная память одновременных загрузок
|
||||
|
||||
Воркер API SHALL держать в памяти тела не более `UPLOAD_CONCURRENCY` загрузок одновременно; остальные загрузки SHALL ждать свободного слота, не читая тело, в пределах `REQUEST_TIMEOUT_SECONDS`. Тело SHALL NOT записываться на диск реплики. Пик памяти реплики при ≥10 одновременных загрузках по 10 MiB SHALL оставаться ниже её лимита памяти без перезапуска процесса, а все корректные загрузки SHALL получать `201`.
|
||||
|
||||
#### Scenario: Ожидание слота
|
||||
|
||||
- **WHEN** при `UPLOAD_CONCURRENCY=1` одна загрузка держит слот, а вторая приходит следом
|
||||
- **THEN** тело второй не читается, пока первая не завершилась, затем обе получают `201`
|
||||
|
||||
#### Scenario: Замер одновременных загрузок
|
||||
|
||||
- **WHEN** через LB идут 10, 20 и 40 одновременных загрузок PNG по 1 MiB и по 10 MiB, а пик памяти каждой реплики снимается из cgroup
|
||||
- **THEN** при лимите слотов все загрузки получают `201`, пик памяти реплики ниже `API_MEMORY` и не растёт пропорционально числу одновременных загрузок
|
||||
|
||||
### Requirement: Пользовательские ошибки файлов не дают 500
|
||||
|
||||
Ни одна ошибка клиента при загрузке, чтении вложения или ссылке на него SHALL NOT давать ответ `5xx` или строку журнала реплики со статусом `500`. Через балансировщик против настоящих PostgreSQL и S3 SHALL проверяться: тело на байт больше лимита (с `Content-Length` и chunked) — `413`; декомпрессионная бомба — `413`; обрезанный PNG и JPEG — `415`; подмена MIME (JPEG, GIF, текст как `image/png`, PNG как `image/jpeg`) и отсутствующий или иной `Content-Type` — `415`; опасный и пустой `filename` — `400`; метаданные и `/content` чужого вложения — `404`; ссылка на чужое, неизвестное вложение и вложение другого чата — `404`; 11 и повторяющиеся `attachment_ids`, невалидный UUID и неизвестный `variant` — `400`.
|
||||
|
||||
#### Scenario: Негативный suite через балансировщик
|
||||
|
||||
- **WHEN** все перечисленные запросы отправлены на стенд через LB
|
||||
- **THEN** каждый ответ имеет ожидаемый код и тело ошибки по схеме `Error`, ни один не `5xx`, в журнале реплик за время прогона нет статуса `500`, а строк вложений в чате ровно столько, сколько было ответов `201`
|
||||
@@ -0,0 +1,40 @@
|
||||
## 1. Зона `attachments`: домен и приложение
|
||||
|
||||
- [x] 1.1 Домен: событие `AttachmentDiscarded(reason)`, `Attachment.discard(reason)`, ошибка `UploadAborted`
|
||||
- [x] 1.2 Порты: репозиторий `lock`, `next_abandoned`, `remove`; `UploadSlots`; команда `SweepAbandonedUploads`
|
||||
- [x] 1.3 Обработчики: запись под слотом, компенсация `discard` после `PUT`, уборка по одной строке
|
||||
- [x] 1.4 Проверка группы: unit-тест `discard`, `make lint`
|
||||
|
||||
## 2. Зона `attachments`: инфраструктура, настройки и точки входа
|
||||
|
||||
- [x] 2.1 Адаптер PostgreSQL: `FOR UPDATE`, `FOR UPDATE SKIP LOCKED` по частичному индексу, `DELETE … AND status='pending'`, `UPDATE 0` → `Unavailable`
|
||||
- [x] 2.2 Настройки `UPLOAD_CONCURRENCY`, `UPLOAD_GRACE_SECONDS` (≥ 60), `UPLOAD_SWEEP_INTERVAL_SECONDS`, `UPLOAD_SWEEP_BATCH`; провайдер dishka
|
||||
- [x] 2.3 HTTP: `ClientDisconnect` → `UploadAborted` (`400`); журнал `audit.attachment_discarded`
|
||||
- [x] 2.4 `UploadSweeper` и его запуск/остановка в lifespan `main.py`
|
||||
- [x] 2.5 Платформа: откат транзакции не стирает события прежних транзакций команды, шина публикует их и при ошибке обработчика
|
||||
- [x] 2.6 Проверка группы: API-тесты против одноразового PostgreSQL — отказ `COMMIT` после `PUT` (компенсация), снятое намерение (`503`, объект удалён), сбой `PUT` и уборка после grace, свежее и готовое переживают проход, два прохода одновременно, фоновая уборка, ожидание слота, обрыв (`400`), зависшее тело (`503`, слот свободен)
|
||||
|
||||
## 3. Стенд
|
||||
|
||||
- [x] 3.1 `compose.yaml` и `.env.example`: новые переменные зоны у `api`
|
||||
- [x] 3.2 `scripts/s3-check.sh`: консоль из сети стенда
|
||||
- [x] 3.3 Проверка группы: `docker compose config --quiet`, `make up`, `make test`
|
||||
|
||||
## 4. Проверки против стенда
|
||||
|
||||
- [x] 4.1 `student-tests/stack/test_attachment_faults.py`: негативный suite через LB и журнал без `500`
|
||||
- [x] 4.2 Там же: отказ `COMMIT` (триггер) → компенсация; падение реплики между `PUT` и `COMMIT` → остаток виден, свежий переживает проход, старый убран; готовое вложение в сообщении переживает проход; обрыв и зависание тела
|
||||
- [x] 4.3 Цель `make upload-faults`, шаг CI
|
||||
- [x] 4.4 Проверка группы: `make upload-faults`, `make s3-check`
|
||||
|
||||
## 5. Замер памяти
|
||||
|
||||
- [x] 5.1 `scripts/lab4_seed.py` из заготовки (`memory.current` до нагрузки, `oom_kill`), `scripts/upload_memory.py`, цель `make upload-memory`, ruff для скриптов
|
||||
- [x] 5.2 Буферы сокетов по цепочке (HAProxy `tune.*buf`, `tcp_rmem`/`tcp_wmem` у `api`) и фиксированный порог `mmap` glibc по результатам первого прогона
|
||||
- [x] 5.3 Проверка группы: прогон 64/3 слота × 1/10 MiB × 10/20/40 и сравнение порога `mmap`; `UPLOAD_CONCURRENCY=3` подтверждено
|
||||
|
||||
## 6. Отчёт
|
||||
|
||||
- [x] 6.1 `evidence/`: `upload-faults.txt`, `upload-memory/`, `s3-security.txt`, `student-tests.txt`, `contract-checks.txt`, `regression-level4.txt`
|
||||
- [x] 6.2 `REPORT.md`: строки 4.1–4.4, механизм компенсации и уборки, эксперимент памяти, таблица отказов, ограничения; `AGENTS.md`: команды и уровень «4»
|
||||
- [x] 6.3 Проверка группы: `make check`, `make lint`, `make student-test`, `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`, `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`, сценарии уровня «3» и `make upload-faults`
|
||||
Reference in New Issue
Block a user