25 KiB
Spec Delta
MODIFIED Requirements
Requirement: Только по HTTP
Тесты SHALL обращаться к сервису только по HTTP и MUST NOT импортировать
код приложения, запускать или останавливать сервер. Проверки отказов
SHALL действовать на хранилища стенда, брокер и worker и узнавать их состояние
только через hook, который им передаёт make failure_checks. Без hook они
MUST завершаться ошибкой с указанием этой команды, а не обращаться к
хранилищам сами. Один и тот же набор SHALL проходить против сервера,
запущенного на хосте, и против контейнера.
Scenario: Консоль и контейнер
- WHEN набор запускается сначала против
make run_devсmake run_worker, затем противmake run_docker - THEN оба прогона проходят одинаково
Scenario: Проверка отказа без hook
- WHEN проверки отказов запущены pytest напрямую, без
make failure_checks - THEN они завершаются ошибкой, которая называет
make failure_checks, и ни одно хранилище не останавливается
Requirement: Покрытие сценариев основных спеков
Для каждого сценария основных спеков api-conventions,
identification, sessions, users, chats, messages,
pagination, data-storage, chat-cache, health, idempotency, с
лабы 4 attachments и storage-consistency и с лабы 5
attachment-processing и message-broker, который воспроизводится
по HTTP против работающего сервера, в том числе на стенде отказов,
SHALL быть тест. Из имени или описания теста SHALL быть понятно, какой
capability и сценарий он проверяет. Сценарий, который проверяет тест
отказа, SHALL считаться покрытым, хотя make student_test этот тест
не выполняет; итог сверки SHALL называть, сколько сценариев покрыто
проверками отказов. Сценарии, которые по HTTP не воспроизвести, SHALL
быть перечислены с причиной и способом проверки.
Scenario: Сверка покрытия
- WHEN проверяющий берёт любой сценарий перечисленных спеков
- THEN находится проверяющий его тест либо запись в списке исключений с причиной
Scenario: Сценарий отказа в сверке
- WHEN выполняется
make student_test - THEN сверка считает сценарии проверок отказов покрытыми, не требует для них исключений и печатает их число
Requirement: Прогон на временной базе
make test_isolated SHALL проверять образ, собранный из рабочего
дерева, в связке compose на временной базе test_<имя рабочей базы> в
PostgreSQL стенда, с Valkey, S3 и брокером стенда. Команда SHALL по порядку:
- поднять PostgreSQL, Valkey, S3 с bootstrap и брокер;
- собрать образ и создать базу заново;
- применить к ней миграции сервисом миграций compose;
- запустить отдельный контейнер API и отдельный контейнер worker из определений
сервисов compose, в которых подменено только имя базы, и опубликовать API на
127.0.0.1:TEST_APP_PORTиз.env; - дождаться готовности и выполнить публичный smoke (
make test) и весь набор (make student_test) против этого контейнера; - остановить и удалить оба контейнера, удалить базу, объекты 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, брокера или S3 и сбой внутри обработки;message-broker: все сценарии, которые не названы исключениями сверки покрытия;storage-consistency: все сценарии.
Команда SHALL:
-
собрать образ из рабочего дерева;
-
поднять отдельный стенд со своими PostgreSQL, Valkey, S3 и брокером, применить миграции и bootstrap S3;
-
запустить четыре API:
- с настройками по умолчанию;
- «тесный» — с коротким сроком сессии и ключа идемпотентности и пулом из одного соединения;
- «узкий по загрузкам» — с одним местом загрузки, одной загрузкой в очереди, коротким сроком ожидания места и коротким сроком тела;
- «с коротким сроком S3» — со сроком вызова S3 в одну секунду: простой дольше срока вызова в проверке длится полторы секунды, а не шесть.
Значения «узкого» API и API с коротким сроком S3 SHALL передаваться проверкам, и проверки SHALL сверять с ними стенд;
-
запустить уборщика с коротким grace и интервалом, сравнимыми со временем теста, без плановой сверки, и передать их значения проверкам. Grace при этом SHALL проходить проверку границы живой загрузки (
service-configuration, «Параметры уборщика»). Сверку проверки запускают сами, и плановая сверка не меняет стенд у них за спиной; -
запустить worker с короткими сроками и малым числом попыток, сравнимыми со временем теста, и передать их значения проверкам;
-
выполнить проверки отказов;
-
удалить стенд вместе с его данными при любом исходе.
Hook стенда отказов SHALL уметь:
- сообщить вложения стенда в PostgreSQL с их статусами,
idпоследнего вложения в статусе «загружается» иidвложений с потерянным оригиналом; - сообщить задание вложения: идентификатор, состояние, число начатых попыток, причину последней ошибки, время следующей попытки и время подтверждения брокером;
- сообщить, у каких вложений есть объект в конечном префиксе и в staging bucket стенда, и сколько у вложения объектов вариантов, — по самим объектам, а не по каталогам хранилища;
- внедрить отказ PostgreSQL:
- при записи метаданных загрузки с заданным
filename; - при фиксации её
queued, и задержать такую фиксацию; - при фиксации
readyс заданнымfilename, и задержать такую фиксацию; - при пометке потерянного оригинала такого вложения;
- при записи метаданных загрузки с заданным
- убить и снова запустить обычный API стенда;
- остановить, убить, заморозить и запустить брокер и worker стенда;
- сообщить состояние очереди: сообщений, готовых, неподтверждённых, потребителей, устойчива ли она;
- прочитать сообщение из очереди без подтверждения, добавить в очередь сообщение и удалить очередь;
- внести расхождения хранилищ:
- записать объект в bucket стенда мимо API и удалить объект мимо API — только под префиксами вложений и staging базы стенда;
- удалить метаданные вложения, изменить в них размер и сдвинуть их время в прошлое;
- выполнить разовую сверку — без изменений или с
--apply, с заданным пределом изменений, стратегией обхода, глубиной и пределом скорости — и вернуть её записи и код выхода; - остановить и запустить уборщика стенда, а также запустить отдельного уборщика с коротким интервалом плановой сверки на заданное время и вернуть его журнал.
Других сведений о хранилищах проверки вложений не получают. Объекты без метаданных проверка находит сравнением двух списков: вложений и объектов. Ключи доступа S3 и пароль брокера hook не получает и не печатает: объект мимо API и сообщение в очередь записывает процесс в контейнере стенда своими ключами.
Порты PostgreSQL, Valkey, S3 и брокера этого стенда MUST NOT публиковаться на
хосте, API — только на 127.0.0.1. Рабочий стенд, его база, кэш,
хранилище объектов, брокер и контейнеры MUST NOT затрагиваться. Код выхода
SHALL быть ненулевым, если не прошла хотя бы одна проверка или уборка.
Параллельный запуск двух прогонов не поддерживается: уборка хвоста в
начале второго удаляет стенд первого.
Scenario: Успешный прогон
- WHEN рабочий стенд запущен, и выполнен
make failure_checks - THEN все проверки отказов прошли, код выхода 0, контейнеров и volumes стенда отказов после команды нет, а у контейнеров рабочего стенда прежнее время старта, и рабочий API отвечает
Scenario: Упавшая проверка
- WHEN во время
make failure_checksпадает хотя бы одна проверка - THEN код выхода ненулевой, журналы API, уборщика и 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 и пароля брокера нет
ADDED Requirements
Requirement: Готовность вложения в тестах
Тест, которому нужны байты вложения, SHALL ждать ready опросом метаданных со сроком,
а не считать вложение готовым после ответа 202. Срок ожидания — не больше 60 с, как у
публичного smoke. Истёк срок или вложение стало failed — тест SHALL падать и называть
последнее состояние. Проверки формы ответа 202 SHALL идти до ожидания: status queued,
variants [], error_code null. Ослаблять проверки и пропускать сценарии вложений
ради этого перехода MUST NOT.
Scenario: Ожидание готовности
- WHEN тест загружает файл, ждёт
readyи скачивает оригинал - THEN загрузка проверена по схеме контракта как 202 со
statusqueued, а скачивание — 200 с теми же байтами
Scenario: Worker не работает
- WHEN worker стенда не запущен, и выполняется
make student_test - THEN тесты, которым нужна готовность, падают с сообщением, что вложение не стало
readyза срок, и называют его состояниеqueued
Requirement: Сценарий защиты автоматизирован
Сценарий защиты из README.md SHALL быть автоматизирован на стенде отказов и командой
драйвера на рабочем стенде: worker остановлен → загрузка 202 → сообщение с вложением 201 →
скачивание 409 → текстовое сообщение 201 → перезапуск API и брокера с сохранёнными volumes →
worker запущен → то же вложение ready, оригинал равен загруженному, thumbnail — настоящий
JPEG. Команда драйвера SHALL печатать порядок действий и id без токенов и завершаться
ненулевым кодом при расхождении, а её вывод SHALL сохраняться в evidence/. Worker SHALL
быть запущен снова при любом исходе.
Scenario: Команда на рабочем стенде
- WHEN на запущенном рабочем стенде выполняется команда защиты драйвера
- THEN код выхода 0, вывод называет шаги, коды ответов,
idвложения и сообщения и время старта контейнеров API и брокера до и после, а токенов и секретов в выводе нет
Scenario: Сбой посреди сценария
- WHEN сценарий команды прерван расхождением или сигналом
- THEN worker снова запущен, а код выхода ненулевой