Source: mtusi2026lab5-safronov, solution/bvt2301-safronov, 046ec9e. Contracts, public tests and evidence of lab 5 are not carried over. The compose project, image and CI prefix are renamed to lab6; the first broker start defect is recorded in KNOWN_ISSUES.md; PLAN.md outlines the OpenSpec changes of lab 6. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
639 lines
45 KiB
Markdown
639 lines
45 KiB
Markdown
# student-tests Specification
|
||
|
||
## Purpose
|
||
|
||
Собственный набор black-box тестов API мессенджера: одной командой
|
||
проверяет по HTTP любой запущенный стенд. Покрывает обязательные
|
||
сценарии рубрики, гонки и сценарии основных спеков, а результат прогона
|
||
сохраняется как доказательство.
|
||
|
||
## Requirements
|
||
|
||
### Requirement: Запуск одной командой
|
||
|
||
Набор, кроме проверок отказов (требование «Проверки отказов на
|
||
отдельном стенде»), SHALL запускаться одной командой `make student_test`
|
||
против сервера по адресу `BASE_URL`, по умолчанию
|
||
`http://localhost:8080`. Команда SHALL завершаться с кодом 0, только
|
||
если прошли все тесты. Если сервер по `BASE_URL` не отвечает, набор
|
||
MUST завершаться с ненулевым кодом и сообщением о недоступности адреса,
|
||
а не множеством ошибок отдельных тестов.
|
||
|
||
#### Scenario: Все тесты прошли
|
||
|
||
- **WHEN** сервер запущен и `make student_test` выполняется без
|
||
аргументов
|
||
- **THEN** все тесты, кроме проверок отказов, проходят, команда
|
||
завершается с кодом 0, а проверки отказов в прогоне не выполняются
|
||
|
||
#### Scenario: Другой адрес
|
||
|
||
- **WHEN** выполняется `make student_test BASE_URL=http://localhost:8090`
|
||
- **THEN** тесты обращаются к `http://localhost:8090`
|
||
|
||
#### Scenario: Сервер не запущен
|
||
|
||
- **WHEN** по `BASE_URL` никто не слушает
|
||
- **THEN** команда завершается с ненулевым кодом, а вывод называет
|
||
недоступный адрес
|
||
|
||
### Requirement: Только по HTTP
|
||
|
||
Тесты SHALL обращаться к сервису только по HTTP и MUST NOT импортировать
|
||
код приложения, запускать или останавливать сервер. Проверки отказов
|
||
SHALL действовать на хранилища стенда, брокер, relay и worker и узнавать их
|
||
состояние только через hook, который им передаёт `make failure_checks`. Без hook они
|
||
MUST завершаться ошибкой с указанием этой команды, а не обращаться к
|
||
хранилищам сами. Один и тот же набор SHALL проходить против сервера,
|
||
запущенного на хосте, и против контейнера.
|
||
|
||
#### Scenario: Консоль и контейнер
|
||
|
||
- **WHEN** набор запускается сначала против `make run_dev` с `make run_relay` и `make
|
||
run_worker`, затем против `make run_docker`
|
||
- **THEN** оба прогона проходят одинаково
|
||
|
||
#### Scenario: Проверка отказа без hook
|
||
|
||
- **WHEN** проверки отказов запущены pytest напрямую, без
|
||
`make failure_checks`
|
||
- **THEN** они завершаются ошибкой, которая называет `make
|
||
failure_checks`, и ни одно хранилище не останавливается
|
||
|
||
### Requirement: Независимость прогонов
|
||
|
||
Каждый тест SHALL создавать собственных пользователей с уникальным
|
||
`username` и собственные чаты. Результат MUST NOT зависеть от порядка
|
||
тестов, от данных, уже лежащих на сервере, и от предыдущих прогонов.
|
||
|
||
#### Scenario: Два прогона подряд
|
||
|
||
- **WHEN** набор запускается дважды подряд против одного сервера без
|
||
рестарта
|
||
- **THEN** оба прогона проходят
|
||
|
||
### Requirement: Обязательные сценарии рубрики
|
||
|
||
Набор SHALL содержать отдельные тесты для сценариев уровня «4»:
|
||
неверный JSON, чужой чат, пустое сообщение, дубликат `username`, обход
|
||
нескольких страниц истории, а с лабы 2 — неверный пароль и logout. С
|
||
лабы 4 к ним SHALL добавиться слишком большой файл, повреждённое
|
||
изображение, подмена MIME, чужое `attachment_id` и вложение другого
|
||
чата. Каждый такой тест SHALL проверять, что ошибка клиента дала
|
||
статус 4xx в формате контракта, а не 500.
|
||
|
||
#### Scenario: Неверный JSON
|
||
|
||
- **WHEN** тест отправляет тело `{bad` в эндпоинт, ожидающий JSON
|
||
- **THEN** проверяется ответ 400 с `code` `invalid_request`
|
||
|
||
#### Scenario: Чужой чат
|
||
|
||
- **WHEN** пользователь, не состоящий в чате, читает чат, читает
|
||
историю и пишет в чат
|
||
- **THEN** проверяется, что все три запроса получают 404 `not_found`
|
||
|
||
#### Scenario: Пустое сообщение
|
||
|
||
- **WHEN** участник отправляет сообщение с `text` пустым и из пробелов
|
||
- **THEN** проверяется ответ 400 `invalid_request`, и сообщение не
|
||
появляется в истории
|
||
|
||
#### Scenario: Дубликат username
|
||
|
||
- **WHEN** регистрируется `username`, который уже занят
|
||
- **THEN** проверяется ответ 409 `conflict`
|
||
|
||
#### Scenario: Обход нескольких страниц
|
||
|
||
- **WHEN** история содержит больше сообщений, чем помещается на одну
|
||
страницу, и тест обходит её по `next_cursor`, в том числе меняя
|
||
`limit` между страницами
|
||
- **THEN** проверяется, что каждое сообщение встречается ровно один раз
|
||
в порядке `(created_at, id)`, а последняя страница имеет
|
||
`next_cursor` null
|
||
|
||
#### Scenario: Неверный пароль в рубрике
|
||
|
||
- **WHEN** зарегистрированный пользователь входит с неверным паролем
|
||
- **THEN** проверяется ответ 401 с `WWW-Authenticate` схемы `Basic`, и
|
||
выданного токена в ответе нет
|
||
|
||
#### Scenario: Logout в рубрике
|
||
|
||
- **WHEN** пользователь выходит, а затем повторяет запрос прежним
|
||
токеном
|
||
- **THEN** проверяется ответ 204 на выход и 401 с `WWW-Authenticate`
|
||
схемы `Bearer` на повтор
|
||
|
||
#### Scenario: Слишком большой файл в рубрике
|
||
|
||
- **WHEN** участник загружает файл больше 10 MiB с `Content-Length` и
|
||
частями без него
|
||
- **THEN** проверяется ответ 413 `payload_too_large` в обоих случаях
|
||
|
||
#### Scenario: Повреждённое изображение в рубрике
|
||
|
||
- **WHEN** участник загружает обрезанные PNG и JPEG и PNG с изменённым
|
||
байтом данных
|
||
- **THEN** проверяется ответ 415 `unsupported_media_type` на каждый
|
||
|
||
#### Scenario: Подмена MIME в рубрике
|
||
|
||
- **WHEN** участник загружает JPEG с `Content-Type: image/png` и текст с
|
||
`Content-Type: image/jpeg`
|
||
- **THEN** проверяется ответ 415 `unsupported_media_type` на оба
|
||
|
||
#### Scenario: Чужое attachment_id в рубрике
|
||
|
||
- **WHEN** участник отправляет сообщение с вложением чата, где он не
|
||
состоит, и с неизвестным id вложения, а посторонний читает метаданные
|
||
и байты вложения
|
||
- **THEN** проверяется ответ 404 `not_found` на каждый запрос
|
||
|
||
#### Scenario: Вложение другого чата в рубрике
|
||
|
||
- **WHEN** участник двух чатов отправляет в один из них сообщение с
|
||
вложением другого
|
||
- **THEN** проверяется ответ 404 `not_found`, и сообщение не появляется
|
||
в истории
|
||
|
||
### Requirement: Тест гонок
|
||
|
||
Набор SHALL содержать тест гонок с реальной параллельностью: запросы
|
||
находятся в обработке одновременно, по отдельным соединениям. 10
|
||
клиентов SHALL одновременно отправлять по 10 сообщений в один чат, после
|
||
чего полный обход истории SHALL давать ровно 100 сообщений с
|
||
уникальными `id`. Отдельный тест SHALL одновременно регистрировать
|
||
одинаковый `username` несколькими клиентами. Ещё один тест SHALL
|
||
одновременно отправлять одно тело с одним `Idempotency-Key` несколькими
|
||
клиентами.
|
||
|
||
#### Scenario: 100 сообщений от 10 клиентов
|
||
|
||
- **WHEN** 10 клиентов одновременно отправляют по 10 сообщений
|
||
- **THEN** получено 100 ответов 201, полный обход истории возвращает
|
||
100 сообщений с уникальными `id`, и каждое отправленное сообщение
|
||
найдено ровно один раз
|
||
|
||
#### Scenario: Гонка за username
|
||
|
||
- **WHEN** 10 клиентов одновременно регистрируют одинаковый `username`
|
||
- **THEN** ровно один ответ 201, остальные 409 `conflict`
|
||
|
||
#### Scenario: Гонка одного ключа
|
||
|
||
- **WHEN** 10 клиентов одновременно отправляют одно тело с одним
|
||
`Idempotency-Key`, и не меньше двух запросов были в обработке
|
||
одновременно
|
||
- **THEN** все ответы 201 с одним `id`, а в истории ровно одно такое
|
||
сообщение
|
||
|
||
### Requirement: Тесты реплик через балансировщик
|
||
|
||
Набор SHALL содержать тесты, которым нужны две и больше реплики за
|
||
`BASE_URL`:
|
||
- распределение одной сессии по репликам и чтение записи через другую
|
||
реплику (capability `load-balancing`);
|
||
- повтор с тем же ключом через другую реплику и гонка одного ключа с
|
||
ответами разных реплик, пересекающимися по времени (capability
|
||
`idempotency`).
|
||
|
||
Сколько реплик ожидается за `BASE_URL`, набор SHALL узнавать из
|
||
переменной `EXPECT_REPLICAS`, а не угадывать по ответам. `make
|
||
student_test` SHALL брать её из `API_REPLICAS` (по умолчанию 2), `make
|
||
test_isolated` и прогон драйвера против своего процесса в консоли SHALL
|
||
передавать 1. При `EXPECT_REPLICAS` = 1 тесты реплик SHALL
|
||
пропускаться с причиной, которая называет режим одного процесса. Они
|
||
MUST NOT считаться пройденными. При `EXPECT_REPLICAS` ≥ 2 тест SHALL
|
||
падать, если ответы дали меньше двух разных `X-Instance-Id`, и
|
||
сообщение SHALL называть число увиденных значений.
|
||
|
||
#### Scenario: Против стенда с балансировщиком
|
||
|
||
- **WHEN** стенд запущен `make run_docker`, и выполнен `make
|
||
student_test`
|
||
- **THEN** тесты реплик выполняются и проходят, а их вывод показывает
|
||
увиденные `X-Instance-Id`
|
||
|
||
#### Scenario: Против одного процесса
|
||
|
||
- **WHEN** выполнен `make test_isolated` или `make student_test
|
||
EXPECT_REPLICAS=1` против одного процесса API
|
||
- **THEN** тесты реплик помечены пропущенными с причиной «один
|
||
процесс», остальные тесты проходят, и код выхода 0
|
||
|
||
#### Scenario: Реплик меньше ожидаемого
|
||
|
||
- **WHEN** `make student_test` с `EXPECT_REPLICAS=2` запущен против
|
||
одного процесса API
|
||
- **THEN** тесты реплик падают с сообщением, что увидено одно значение
|
||
`X-Instance-Id`, а не пропускаются
|
||
|
||
### Requirement: Покрытие сценариев основных спеков
|
||
|
||
Для каждого сценария основных спеков `api-conventions`,
|
||
`identification`, `sessions`, `users`, `chats`, `messages`,
|
||
`pagination`, `data-storage`, `chat-cache`, `health`, `idempotency`, с
|
||
лабы 4 `attachments` и `storage-consistency` и с лабы 5
|
||
`attachment-processing`, `message-broker`, `job-outbox` и `queue-overload`, который воспроизводится
|
||
по HTTP против работающего сервера, в том числе на стенде отказов,
|
||
SHALL быть тест. Из имени или описания теста SHALL быть понятно, какой
|
||
capability и сценарий он проверяет. Сценарий, который проверяет тест
|
||
отказа, SHALL считаться покрытым, хотя `make student_test` этот тест
|
||
не выполняет; итог сверки SHALL называть, сколько сценариев покрыто
|
||
проверками отказов. Сценарии, которые по HTTP не воспроизвести, SHALL
|
||
быть перечислены с причиной и способом проверки.
|
||
|
||
#### Scenario: Сверка покрытия
|
||
|
||
- **WHEN** проверяющий берёт любой сценарий перечисленных спеков
|
||
- **THEN** находится проверяющий его тест либо запись в списке
|
||
исключений с причиной
|
||
|
||
#### Scenario: Сценарий отказа в сверке
|
||
|
||
- **WHEN** выполняется `make student_test`
|
||
- **THEN** сверка считает сценарии проверок отказов покрытыми, не
|
||
требует для них исключений и печатает их число
|
||
|
||
### Requirement: Проверка формы ответов
|
||
|
||
Тесты SHALL проверять не только статус.
|
||
- У ошибок: тело — ровно `{"error": {"code", "message",
|
||
"request_id"}}`, `code` соответствует статусу, `request_id` равен
|
||
заголовку `X-Request-Id`.
|
||
- У успешных ответов: поля совпадают со схемой контракта, лишних нет,
|
||
`id` — UUID в нижнем регистре, `created_at` — RFC 3339 UTC с `Z`.
|
||
|
||
#### Scenario: Ошибка не в формате контракта
|
||
|
||
- **WHEN** сервер отвечает на ошибку телом `{"detail": ...}`
|
||
- **THEN** тест падает, даже если статус верный
|
||
|
||
### Requirement: Результат прогона сохраняется
|
||
|
||
Вывод прогона против контейнера (`make test_isolated`), вывод `make
|
||
student_test` против стенда с балансировщиком и вывод `make
|
||
failure_checks` SHALL сохраняться в `evidence/` с командой, датой,
|
||
commit, адресом стенда и итогом. `REPORT.md` SHALL ссылаться на них в
|
||
строках уровня «4»: собственные тесты, 100 сообщений от 10 клиентов,
|
||
гонка одного ключа через реплики, автоматические проверки истечения
|
||
сессии и недоступности БД и Valkey, а с лабы 4 — негативные тесты
|
||
вложений и проверки отказов S3.
|
||
|
||
#### Scenario: Доказательство в отчёте
|
||
|
||
- **WHEN** проверяющий открывает строку уровня «4» в `REPORT.md`
|
||
- **THEN** в ней есть команда, наблюдаемый результат и путь к файлу
|
||
вывода в `evidence/`
|
||
|
||
### Requirement: Прогон на временной базе
|
||
|
||
`make test_isolated` SHALL проверять образ, собранный из рабочего
|
||
дерева, в связке compose на временной базе `test_<имя рабочей базы>` в
|
||
PostgreSQL стенда, с Valkey, S3 и брокером стенда. Команда SHALL по порядку:
|
||
1. поднять PostgreSQL, Valkey, S3 с bootstrap и брокер;
|
||
2. собрать образ и создать базу заново;
|
||
3. применить к ней миграции сервисом миграций compose;
|
||
4. запустить отдельный контейнер API, отдельный контейнер relay и отдельный контейнер
|
||
worker из определений сервисов compose, в которых подменено только имя базы, и
|
||
опубликовать API на `127.0.0.1:TEST_APP_PORT` из `.env`;
|
||
5. дождаться готовности и выполнить публичный smoke (`make test`) и
|
||
весь набор (`make student_test`) против этого контейнера;
|
||
6. остановить и удалить все три контейнера, удалить базу, объекты S3 под
|
||
префиксом `test_<db>/` и очередь временной базы.
|
||
|
||
Это один процесс API без балансировщика: набор SHALL запускаться с
|
||
`EXPECT_REPLICAS=1`, и тесты реплик пропускаются с причиной. Код
|
||
выхода SHALL быть ненулевым, если не прошёл smoke, набор или уборка.
|
||
|
||
Рабочая база и рабочие контейнеры стенда MUST NOT затрагиваться.
|
||
Тестовый прогон отделён от рабочего именем базы:
|
||
- карточки чатов в Valkey — именем базы в ключе (capability
|
||
`chat-cache`);
|
||
- объекты в S3 — префиксом имени базы в ключе объекта (capability
|
||
`object-storage`);
|
||
- задания — именем базы в имени очереди (capability `message-broker`).
|
||
|
||
Объекты и очередь рабочей базы при уборке MUST NOT удаляться. Параллельный
|
||
запуск двух прогонов не поддерживается.
|
||
|
||
#### Scenario: Успешный прогон
|
||
|
||
- **WHEN** в рабочей базе есть данные, рабочий стенд запущен, и
|
||
выполнен `make test_isolated`
|
||
- **THEN** smoke и набор прошли, тесты реплик пропущены с причиной,
|
||
код выхода 0, ни базы `test_<db>`, ни тестовых контейнеров, ни
|
||
объектов под префиксом `test_<db>/`, ни очереди временной базы после команды
|
||
нет, число строк в таблицах рабочей базы и объекты рабочей базы не изменились,
|
||
а рабочий стенд продолжает отвечать через балансировщик
|
||
|
||
#### Scenario: Упавшие тесты
|
||
|
||
- **WHEN** во время `make test_isolated` падает хотя бы один тест
|
||
- **THEN** код выхода ненулевой, журналы тестовых контейнеров выведены,
|
||
контейнеры удалены, база `test_<db>`, объекты под префиксом `test_<db>/` и
|
||
очередь временной базы удалены
|
||
|
||
#### Scenario: Прерывание
|
||
|
||
- **WHEN** `make test_isolated` прерван Ctrl+C
|
||
- **THEN** тестовые контейнеры остановлены и удалены, база `test_<db>`, объекты
|
||
под префиксом `test_<db>/` и очередь временной базы удалены
|
||
|
||
#### Scenario: Хвост прошлого прогона
|
||
|
||
- **WHEN** тестовые контейнеры, база `test_<db>`, объекты под префиксом
|
||
`test_<db>/` или очередь временной базы остались от прогона, убитого без уборки
|
||
- **THEN** следующий `make test_isolated` удаляет их и начинает заново
|
||
|
||
#### Scenario: Сохранить базу для разбора
|
||
|
||
- **WHEN** выполнен `make test_isolated KEEP_TEST_DB=1`
|
||
- **THEN** после прогона тестовые контейнеры удалены, база `test_<db>`, объекты под
|
||
префиксом `test_<db>/` и очередь временной базы остаются, а команда печатает имя
|
||
базы, префикс и очередь
|
||
|
||
### Requirement: Проверки отказов на отдельном стенде
|
||
|
||
Сценарии отказов SHALL проверяться автоматически одной командой
|
||
`make failure_checks`:
|
||
- `sessions`: «Истёкший токен», «Срок не продлевается», «БД остановлена при
|
||
запросе с токеном»;
|
||
- `data-storage`: «Сбой при добавлении участников», «БД остановлена»,
|
||
«БД вернулась», «Соединения исчерпаны»;
|
||
- `health`: «Хранилище не готово», «Кэш недоступен», «Хранилище
|
||
объектов недоступно», «Брокер и worker недоступны»;
|
||
- `chat-cache`: «Valkey остановлен», «Valkey завис», «Valkey вернулся»,
|
||
«Очистка кэша»;
|
||
- `idempotency`: «Сбой при записи сообщения», «Отказ БД при отправке»,
|
||
«Ключ после срока», «Повтор после failed вложения»;
|
||
- `api-conventions`: «Лимит одновременных загрузок»;
|
||
- `messages`: «Вложение в обработке», «Вложение стало failed после отправки»;
|
||
- `attachments`: «Запись в S3 не удалась», «Отклонённая загрузка ничего
|
||
не оставляет», «S3 остановлен», «S3 завис», «Незавершённая загрузка не
|
||
видна», «Сбой записи метаданных», «Фиксация задания не удалась», «Фиксация ready не
|
||
удалась», «Исход фиксации неизвестен», «Брокер не подтвердил задание», «Обрыв
|
||
передачи тела», «Отказ раньше
|
||
очереди», «Все места заняты», «Очередь ожидания полна», «Ожидание места», «Место
|
||
освобождается», «Медленный клиент», «Медленная передача в срок», «Потерянный
|
||
оригинал», «Загрузка после простоя S3», «Скачивание до готовности», «Отсутствующий
|
||
вариант»;
|
||
- `attachment-processing`: все сценарии, которым нужны остановка worker, relay, брокера или
|
||
S3, сбой внутри обработки, запуск worker с другими параметрами или команда replay;
|
||
- `message-broker`: все сценарии, которые не названы исключениями сверки покрытия;
|
||
- `job-outbox`: все сценарии;
|
||
- `storage-consistency`: все сценарии;
|
||
- `queue-overload`: все сценарии требования «Предел незавершённых заданий».
|
||
|
||
Команда SHALL:
|
||
- собрать образ из рабочего дерева;
|
||
- поднять отдельный стенд со своими PostgreSQL, Valkey, S3 и брокером, применить
|
||
миграции и bootstrap S3;
|
||
- запустить пять API. У первых четырёх предел незавершённых заданий выключен: проверки копят
|
||
задания при остановленном worker и под нагрузкой, и предел отклонял бы загрузки чужих проверок:
|
||
- с настройками по умолчанию;
|
||
- «тесный» — с коротким сроком сессии и ключа идемпотентности и пулом
|
||
из одного соединения;
|
||
- «узкий по загрузкам» — с одним местом загрузки, одной загрузкой в
|
||
очереди, коротким сроком ожидания места и коротким сроком тела;
|
||
- «с коротким сроком S3» — со сроком вызова S3 в одну секунду: простой
|
||
дольше срока вызова в проверке длится полторы секунды, а не шесть;
|
||
- «узкий по заданиям» — с малым пределом незавершённых заданий.
|
||
|
||
Значения «узких» API и API с коротким сроком S3 SHALL передаваться
|
||
проверкам, и проверки SHALL сверять с ними стенд;
|
||
- запустить уборщика с коротким grace, интервалом и сроком хранения staging, сравнимыми со
|
||
временем теста, без плановой сверки, и передать их значения
|
||
проверкам. Grace при этом SHALL проходить проверку границы живой
|
||
загрузки (`service-configuration`, «Параметры уборщика»). Сверку
|
||
проверки запускают сами, и плановая сверка не меняет стенд у них за
|
||
спиной;
|
||
- запустить relay с короткими паузой и порогом потерянного сообщения и передать их значения
|
||
проверкам;
|
||
- запустить worker с короткими сроками и малым числом попыток, сравнимыми со
|
||
временем теста, и передать их значения проверкам;
|
||
- выполнить проверки отказов;
|
||
- удалить стенд вместе с его данными при любом исходе.
|
||
|
||
Hook стенда отказов SHALL уметь:
|
||
- сообщить вложения стенда в PostgreSQL с их статусами, `id` последнего
|
||
вложения в статусе «загружается» и `id` вложений с потерянным
|
||
оригиналом;
|
||
- сообщить задание вложения: идентификатор, состояние, число начатых попыток, число
|
||
попыток до последнего replay, причину последней ошибки, время следующей попытки, срок
|
||
аренды и время подтверждения брокером, а также записи аудита replay;
|
||
- сообщить число незавершённых заданий стенда;
|
||
- сообщить, у каких вложений есть объект в конечном префиксе и в staging bucket
|
||
стенда, и сколько у вложения объектов вариантов, — по самим объектам, а не по
|
||
каталогам хранилища, и SHA-256 объекта по ключу;
|
||
- внедрить отказ PostgreSQL:
|
||
- при записи метаданных загрузки с заданным `filename`;
|
||
- при фиксации её `queued`, и задержать такую фиксацию;
|
||
- при фиксации `ready` с заданным `filename`, и задержать такую фиксацию: оператор
|
||
перевода и сам COMMIT;
|
||
- при пометке потерянного оригинала такого вложения;
|
||
- задержать запись времени подтверждения брокером у задания вложения с заданным
|
||
`filename`;
|
||
- дождаться, пока COMMIT задержан в PostgreSQL;
|
||
- убить и снова запустить обычный API стенда;
|
||
- остановить, убить, заморозить и запустить брокер, relay и worker стенда, заморозить процесс 1
|
||
контейнера worker сигналом и убить контейнер, запустить отдельный worker или relay с заданными
|
||
значениями `WORKER__*` и `RELAY__*` и убрать его;
|
||
- сообщить состояние очереди: сообщений, готовых, неподтверждённых, потребителей,
|
||
устойчива ли она;
|
||
- прочитать сообщение из очереди без подтверждения, добавить в очередь сообщение
|
||
и удалить очередь; включить и снять предел памяти брокера;
|
||
- убить процесс обработки в контейнере worker и сообщить имена переменных его окружения;
|
||
- внести расхождения хранилищ:
|
||
- записать объект в bucket стенда мимо API и удалить объект мимо API —
|
||
только под префиксами вложений и staging базы стенда;
|
||
- удалить метаданные вложения, изменить в них размер, SHA-256, ключ staging и время
|
||
следующей попытки, сдвинуть их время в прошлое и вернуть вложение в статус «загружается» без
|
||
задания;
|
||
- удалить метаданные варианта;
|
||
- выполнить разовую сверку — без изменений или с `--apply`, с заданным
|
||
пределом изменений, стратегией обхода, глубиной, пределом скорости и сроком хранения
|
||
staging — и вернуть её записи и код выхода;
|
||
- выполнить команду replay с заданным выбором и вернуть её записи и код выхода;
|
||
- остановить и запустить уборщика стенда, а также запустить отдельного
|
||
уборщика с коротким интервалом плановой сверки на заданное время и
|
||
вернуть его журнал.
|
||
|
||
Других сведений о хранилищах проверки вложений не получают. Объекты без
|
||
метаданных проверка находит сравнением двух списков: вложений и
|
||
объектов. Ключи доступа S3 и пароль брокера hook не получает и не печатает: объект
|
||
мимо API и сообщение в очередь записывает процесс в контейнере стенда своими ключами.
|
||
|
||
Порты PostgreSQL, Valkey, S3 и брокера этого стенда MUST NOT публиковаться на
|
||
хосте, API — только на `127.0.0.1`. Рабочий стенд, его база, кэш,
|
||
хранилище объектов, брокер и контейнеры MUST NOT затрагиваться. Код выхода
|
||
SHALL быть ненулевым, если не прошла хотя бы одна проверка или уборка.
|
||
Параллельный запуск двух прогонов не поддерживается: уборка хвоста в
|
||
начале второго удаляет стенд первого.
|
||
|
||
Точек внедрения сбоя в коде приложения MUST NOT быть: сбои внедряются снаружи, средствами стенда.
|
||
|
||
#### Scenario: Успешный прогон
|
||
|
||
- **WHEN** рабочий стенд запущен, и выполнен `make failure_checks`
|
||
- **THEN** все проверки отказов прошли, код выхода 0, контейнеров и
|
||
volumes стенда отказов после команды нет, а у контейнеров рабочего
|
||
стенда прежнее время старта, и рабочий API отвечает
|
||
|
||
#### Scenario: Упавшая проверка
|
||
|
||
- **WHEN** во время `make failure_checks` падает хотя бы одна проверка
|
||
- **THEN** код выхода ненулевой, журналы API, уборщика, relay и worker стенда отказов
|
||
выведены, стенд отказов удалён
|
||
|
||
#### Scenario: Прерывание
|
||
|
||
- **WHEN** `make failure_checks` прерван Ctrl+C
|
||
- **THEN** стенд отказов остановлен и удалён вместе с volumes
|
||
|
||
#### Scenario: Хвост прошлого прогона
|
||
|
||
- **WHEN** контейнеры или volumes стенда отказов остались от прогона,
|
||
убитого без уборки
|
||
- **THEN** следующий `make failure_checks` удаляет их и начинает заново
|
||
|
||
### Requirement: Доказательства исключений сверки в репозитории
|
||
|
||
Если способ проверки сценария из списка исключений сверки покрытия
|
||
ссылается на файл в `evidence/`, этот файл SHALL лежать в репозитории
|
||
текущей лабы. В нём SHALL быть результат, снятый на стенде этой лабы,
|
||
команда, дата и commit. Если способ проверки — команда, которая сама
|
||
снимает доказательство на стенде, исключение SHALL её называть.
|
||
|
||
Сверка покрытия SHALL падать, если файла по ссылке исключения нет, и
|
||
называть сценарий и путь.
|
||
|
||
Такое доказательство MUST NOT содержать токенов, паролей и их хэшей
|
||
целиком, ключей доступа и секретов S3, пароля брокера — только факты, счётчики и
|
||
префиксы.
|
||
|
||
#### Scenario: Ссылка на отсутствующий файл
|
||
|
||
- **WHEN** исключение ссылается на файл `evidence/…`, которого нет в
|
||
репозитории
|
||
- **THEN** `make student_test` завершается с ненулевым кодом, а
|
||
сообщение называет сценарий и путь
|
||
|
||
#### Scenario: Кэш и хранение секретов на стенде лабы
|
||
|
||
- **WHEN** проверяющий открывает файлы, на которые ссылаются исключения
|
||
`chat-cache` «Чтение из кэша», «Срок записи», «Временная база»,
|
||
`sessions` «Токена нет в хранилище» и `users` «Хэш в БД»
|
||
- **THEN** в них вывод названной в исключении команды на стенде с
|
||
балансировщиком и двумя репликами, дата и commit, а токенов, паролей
|
||
и полных хэшей нет
|
||
|
||
#### Scenario: Вложения на стенде лабы
|
||
|
||
- **WHEN** проверяющий открывает файлы, на которые ссылаются исключения
|
||
`attachments` «Принявшая реплика остановлена», «Байты не в БД и не на
|
||
диске API» и «Рестарт стенда»
|
||
- **THEN** в них вывод названной в исключении команды на стенде с
|
||
балансировщиком, двумя репликами, S3, брокером и worker, дата и commit, SHA-256
|
||
загруженного и скачанного файла, а токенов и секретов S3 нет
|
||
|
||
#### Scenario: Обработка на стенде лабы
|
||
|
||
- **WHEN** проверяющий открывает файлы, на которые ссылаются исключения
|
||
`attachment-processing` и `message-broker`
|
||
- **THEN** в них вывод названной в исключении команды на стенде с балансировщиком,
|
||
двумя репликами, брокером и worker, дата и commit, а токенов, секретов S3 и пароля
|
||
брокера нет
|
||
|
||
### Requirement: PostgreSQL стенда отказов без аварийных перезапусков
|
||
|
||
Проверки отказов MUST NOT приводить к аварийному перезапуску PostgreSQL
|
||
своего стенда. Процессы, которые проверки запускают в его контейнере
|
||
(сессии `psql`, занимающие слоты соединений), после завершения MUST NOT
|
||
восприниматься сервером PostgreSQL как его собственные процессы.
|
||
|
||
`make failure_checks` SHALL после проверок и до уборки читать журнал
|
||
PostgreSQL стенда отказов и искать признаки аварийного перезапуска:
|
||
- неизвестный дочерний процесс сервера;
|
||
- завершение всех процессов сервера и повторная инициализация;
|
||
- восстановление после сбоя.
|
||
|
||
Сводку журнала команда SHALL печатать после каждого прогона проверок,
|
||
с признаками и без. Если признаки есть, команда SHALL выводить
|
||
найденные строки и завершаться с ненулевым кодом.
|
||
|
||
#### Scenario: Заполнение и освобождение слотов
|
||
|
||
- **WHEN** проверка «Соединения исчерпаны» заняла все слоты соединений
|
||
PostgreSQL стенда отказов, а затем освободила их
|
||
- **THEN** в журнале PostgreSQL стенда нет «untracked child process» и
|
||
«reinitializing», а сводка журнала в выводе команды называет ноль
|
||
признаков аварии
|
||
|
||
#### Scenario: PostgreSQL перезапустился аварийно
|
||
|
||
- **WHEN** во время `make failure_checks` PostgreSQL стенда отказов
|
||
перезапустился аварийно
|
||
- **THEN** код выхода команды ненулевой, найденные строки журнала
|
||
выведены, а стенд отказов удалён
|
||
|
||
### Requirement: Готовность вложения в тестах
|
||
|
||
Тест, которому нужны байты вложения, SHALL ждать `ready` опросом метаданных со сроком,
|
||
а не считать вложение готовым после ответа 202. Срок ожидания — не больше 60 с, как у
|
||
публичного smoke. Истёк срок или вложение стало `failed` — тест SHALL падать и называть
|
||
последнее состояние. Проверки формы ответа 202 SHALL идти до ожидания: `status` `queued`,
|
||
`variants` `[]`, `error_code` null. Ослаблять проверки и пропускать сценарии вложений
|
||
ради этого перехода MUST NOT.
|
||
|
||
#### Scenario: Ожидание готовности
|
||
|
||
- **WHEN** тест загружает файл, ждёт `ready` и скачивает оригинал
|
||
- **THEN** загрузка проверена по схеме контракта как 202 со `status` `queued`, а
|
||
скачивание — 200 с теми же байтами
|
||
|
||
#### Scenario: Worker не работает
|
||
|
||
- **WHEN** worker стенда не запущен, и выполняется `make student_test`
|
||
- **THEN** тесты, которым нужна готовность, падают с сообщением, что вложение не стало
|
||
`ready` за срок, и называют его состояние `queued`
|
||
|
||
### Requirement: Сценарий защиты автоматизирован
|
||
|
||
Сценарий защиты из `README.md` SHALL быть автоматизирован на стенде отказов и командой
|
||
драйвера на рабочем стенде. Шаги 1–3: worker остановлен → загрузка 202 → сообщение с вложением 201 →
|
||
скачивание 409 → текстовое сообщение 201 → перезапуск API и брокера с сохранёнными volumes →
|
||
worker запущен → то же вложение `ready`, оригинал равен загруженному, thumbnail — настоящий
|
||
JPEG.
|
||
|
||
Шаг 4 — отдельная команда драйвера и проверка отказа, по порядку:
|
||
- crash после записи объектов до фиксации и crash после фиксации до подтверждения
|
||
(`attachment-processing`, «Доставка at least once»): повтор завершает тот же результат;
|
||
- разрыв COMMIT и publish: relay убит, загрузка 202, сообщения нет, relay запущен, вложение `ready`;
|
||
и crash relay после подтверждения до отметки (`job-outbox`, «Relay публикует намерения»);
|
||
- replay `failed`: показ реестра, replay с `--apply`, вложение `ready`, отказ replay готового
|
||
(`attachment-processing`, «Реестр failed и replay»).
|
||
|
||
Команды драйвера SHALL печатать порядок действий и `id` без токенов и завершаться
|
||
ненулевым кодом при расхождении, а их вывод SHALL сохраняться в `evidence/`. Worker и relay SHALL
|
||
быть запущены снова, а внедрённые сбои сняты при любом исходе.
|
||
|
||
#### Scenario: Команда на рабочем стенде
|
||
|
||
- **WHEN** на запущенном рабочем стенде выполняется команда защиты драйвера
|
||
- **THEN** код выхода 0, вывод называет шаги, коды ответов, `id` вложения и сообщения и время
|
||
старта контейнеров API и брокера до и после, а токенов и секретов в выводе нет
|
||
|
||
#### Scenario: Сбой посреди сценария
|
||
|
||
- **WHEN** сценарий команды прерван расхождением или сигналом
|
||
- **THEN** worker и relay снова запущены, внедрённых триггеров нет, а код выхода ненулевой
|
||
|
||
#### Scenario: Шаг 4 на рабочем стенде
|
||
|
||
- **WHEN** на запущенном рабочем стенде выполняется команда шага 4
|
||
- **THEN** код выхода 0, вывод по каждому сбою называет окно, действие, `id` задания, число начатых
|
||
попыток и итог, а токенов и секретов в выводе нет
|