OxL Справочник OxL
РусскийEnglish

16.3 gRPC и protobuf

  • import proto "payments.proto" генерирует extern service и типы; вызовы — как к обычным сервисам через connect.
  • oxl export --proto выдаёт .proto для сервисов и типов пакета по §9.3; oxl export --openapi — описание HTTP/JSON-шлюза.
  • Шлюз HTTP/JSON: POST /api/<Сервис>/<rpc> с телом application/json вызывает унарный rpc сервиса pub(api) (не @internal); тело — объект параметров (канонический protobuf JSON, отсутствующий параметр без значения по умолчанию — ошибка 400), ответ — {"result": значение}, ошибка — {code, status, message, details}; код HTTP соответствует коду gRPC (OK 200, INVALID_ARGUMENT и FAILED_PRECONDITION 400, UNAUTHENTICATED 401, PERMISSION_DENIED 403, NOT_FOUND 404, ALREADY_EXISTS и ABORTED 409, RESOURCE_EXHAUSTED 429, UNAVAILABLE 503, DEADLINE_EXCEEDED 504, …). Аутентификация, политики, идемпотентность и дедлайны — как у gRPC-вызова (D-8065; D-8210..D-8213, D-8218).

Определяется реализацией. Границы шлюза (D-8065; DIV-026; D-8210, D-8241). Эта реализация: шлюз работает на порту gRPC-слушателя (HTTP/2, h2c или TLS; HTTP/1.1 на этом порту не обслуживается); стримовые rpc шлюзом не обслуживаются (501); GET для @readonly rpc и NDJSON для серверных стримов, а также oxl export --openapi (описание шлюза) — необязательные возможности, не реализованные в 1.0.

  • oxl gen --ts --py --go --kotlin --cpp генерирует клиентов с типизированными ошибками и проверкой уточнённых типов.

Определяется реализацией. Клиентские генераторы (D-8056; DIV-034; D-4756). Набор целевых языков oxl gen и полнота клиентов определяются реализацией (состав — в oxl gen --help). Эта реализация генерирует клиентов Python, TypeScript, Go и Kotlin (вывод Kotlin проверен по эталонным файлам и структуре, но не компилировался); клиенты C++ не генерируются (--cpp, после 1.0); значения параметров rpc по умолчанию в клиентах не генерируются; @resumable генератором игнорируется (возобновление стрима клиентом не выполняется).

При импорте proto: option idempotency_level = IDEMPOTENT отображается в @idempotent, NO_SIDE_EFFECTS — в @readonly; сообщения с опцией (oxl.error) = true становятся @error-типами. Клиент внешнего сервиса — Client<S>, обычно получаемый через provide и dep.

import-skip

См. также

Исходник: docs/spec/oxl-standard.md