Исходящие HTTP-вызовы backend-компонентов¶
Требования применяются к backend-, worker- и data-pipeline-компонентам,
вызывающим HTTP API как consumer. Тайм-ауты, повторы, отмена и ограничение
распространения отказа регулируются BE-RES-001–BE-RES-004. Уровни
обязательности определены в корневом README.md.
INT-HTTP-001. Версионируемый контракт consumer¶
Уровень: MUST
Применяется к: каждому исходящему HTTP-вызову backend-, worker- или data-pipeline-компонента
Проект должен фиксировать источник и версию потребляемого контракта. Контракт должен определять методы, адресуемые ресурсы, media types, структуры запросов и ответов, а также успешные и ошибочные статусы, которые использует consumer. Сборка должна проверять совместимость consumer с зафиксированной версией контракта.
Consumer должен игнорировать неизвестные поля ответа, если они не меняют смысл известных полей. Отсутствующее обязательное поле, неизвестное значение закрытого enum или несовместимый тип не должны интерпретироваться как полноценный успешный результат.
Обоснование¶
Неявный контракт обнаруживает несовместимость только после независимой поставки provider или consumer.
Проверка¶
- contract-тест consumer с зафиксированной схемой;
- тест неизвестного поля, отсутствующего обязательного поля и закрытого enum;
- проверка gate на изменение версии контракта.
Исключения¶
Provider без машинно-проверяемой схемы требует ADR и эквивалентного автоматического contract-теста запросов, ответов и используемых статусов.
INT-HTTP-002. Ограниченный и проверенный ответ¶
Уровень: MUST
Применяется к: HTTP-ответу, получаемому backend-, worker- или data-pipeline-компонентом
Consumer должен задавать конечные пределы размера headers и декодированного тела ответа. Предел тела должен применяться во время чтения, а не только после полной буферизации. Ответ с превышением предела, необъявленным media type или структурой, не соответствующей используемому контракту, должен завершать вызов отдельным техническим исходом до использования данных в обязательном эффекте.
Пустое тело, отсутствие тела и JSON null должны различаться, если контракт
задаёт для них разные результаты.
Обоснование¶
Даже доверенный provider при ошибке или компрометации может вернуть неограниченный либо несовместимый ответ и исчерпать ресурсы consumer.
Проверка¶
- граничный тест допустимого и превышающего размер ответа;
- тест предела после content decoding;
- негативный тест media type, структуры, пустого тела и JSON
null.
Исключения¶
Потоковый ответ MAY не иметь предела общего размера, если контракт определяет конечный предел одного элемента, допустимый период отсутствия прогресса и условие завершения потока.
INT-HTTP-003. Неопределённый результат изменяющего вызова¶
Уровень: MUST
Применяется к: исходящему HTTP-вызову, который может создать необратимый или повторно наблюдаемый эффект у provider
Если запрос мог достичь provider, но consumer не получил подтверждённый результат, consumer не должен считать операцию подтверждённо неуспешной или повторять неидемпотентный эффект как новую операцию. Контракт должен предоставлять хотя бы один способ определить итог:
- повтор с тем же стабильным ключом идемпотентности;
- получение статуса по стабильному идентификатору операции;
- сверку подтверждённого состояния provider с локальной операцией.
Автоматический повтор должен дополнительно соблюдать BE-RES-002. Если вызов
является частью операции с несколькими независимыми фиксациями, восстановление
должно также соблюдать BE-STATE-007.
Обоснование¶
Разрыв после фиксации provider оставляет consumer без ответа, но повтор с новым идентификатором способен дублировать необратимый эффект.
Проверка¶
- fault-injection до и после фиксации provider;
- повтор с тем же идентификатором операции;
- тест status lookup либо reconciliation после timeout;
- проверка отсутствия ложного окончательного отказа.
Исключения¶
Требование не применяется к операции, которая по опубликованному контракту идемпотентна и не создаёт повторно наблюдаемого эффекта.