gRPC API¶

Требования применяются к разработке, тестированию и сборке gRPC provider и consumer. Уровни обязательности определены в корневом README.md.

INT-GRPC-001. Версионируемый Protocol Buffers контракт¶

Уровень: MUST

Применяется к: каждому gRPC service

Файлы Protocol Buffers должны храниться в GitLab, объявлять package и service и компилироваться зафиксированной версией toolchain. Сгенерированный provider и consumer код должен создаваться из одного идентифицированного contract release.

Обоснование¶

Сгенерированный код наследует совместимость и смысл исходной схемы.

Проверка¶

компиляция .proto;
воспроизводимая генерация кода;
сопоставление contract release с package.

Исключения¶

Не допускаются для межпроцессного API.

INT-GRPC-002. Wire-совместимость¶

Уровень: MUST

Применяется к: изменению опубликованного .proto

Номер поля не должен повторно использоваться или менять тип несовместимым образом. Удалённые номера и имена должны объявляться reserved. Удаление RPC, изменение streaming kind и изменение семантики поля требуют новой версии контракта и миграции consumers.

Обоснование¶

Совпадение имён не защищает от несовместимости бинарного wire-формата.

Проверка¶

automated breaking-change check;
тест старого consumer с новым provider;
проверка reserved для удалённых полей.

Исключения¶

Изменение до первой публикации не считается изменением опубликованного контракта.

INT-GRPC-003. Deadline и отмена¶

Уровень: MUST

Применяется к: каждому gRPC-вызову

Consumer должен задавать конечный deadline. Provider должен распространять оставшийся deadline и отмену во вложенные операции и прекращать работу, когда результат больше нельзя доставить. Повтор допустим только для объявленной идемпотентной операции и ограниченного набора status codes.

Обоснование¶

Без deadline один отменённый вызов продолжает удерживать ресурсы всей цепочки.

Проверка¶

integration-тест истечения deadline;
тест распространения отмены;
тест запрета повтора неидемпотентного RPC.

Исключения¶

Длительный streaming RPC должен использовать конечные heartbeat/read deadlines и явное завершение вместо единого короткого deadline.

INT-GRPC-004. Статусы и детали ошибки¶

Уровень: MUST

Применяется к: неуспешному завершению RPC

Provider должен использовать стабильный gRPC status code и версионируемые типизированные error details. Сообщение не должно быть единственным машинно-читаемым признаком и не должно раскрывать внутреннее исключение, адрес зависимости или секрет.

Обоснование¶

Разбор текста ошибки связывает consumer с реализацией и локалью.

Проверка¶

contract-тест каждого класса статуса;
schema test error details;
security-тест необработанного исключения.

Исключения¶

Не допускаются для программно обрабатываемой ошибки.

INT-GRPC-005. Ограничение сообщений и потоков¶

Уровень: MUST

Применяется к: unary и streaming RPC

Provider и consumer должны задавать максимальный размер сообщения и конечные границы локальной очереди потока. Запись должна учитывать backpressure и не накапливать неограниченное число сообщений. Превышение границы должно завершаться определённым статусом.

Обоснование¶

HTTP/2 flow control не ограничивает автоматически очередь прикладного кода.

Проверка¶

тест превышения размера;
нагрузочный тест медленного reader;
проверка ограниченности buffer.

Исключения¶

Передача крупного объекта может использовать отдельный потоковый контракт с явной границей chunk и общего размера.