grpc-transcode

Translates HTTP and JSON requests into gRPC calls and back.

Category TransformationAdd it to Route, Service, Consumer, Consumer group, Global rule, Plugin configEngine plugin grpc-transcodePriority 506

What it does

grpc-transcode lets HTTP clients call a gRPC backend. The fields of the request's JSON body become the message of one call, to the method under Method of the service under Service. Both are defined in a proto, which the plugin names by its ID under Proto ID.

The route needs an upstream whose scheme is grpc. The ID under Proto ID is the one the proto was given when it was saved, shown on its page, and not its name.

When to use it

• The orders service speaks gRPC only, and the web shop and the partners call it with JSON over HTTP.
• A mobile app that carries no gRPC library asks for an order with GetOrder, sending the order's id in a JSON body.
• A team moves its orders backend from REST to gRPC, and the HTTP paths the clients already call stay as they are.

Not for browsers that speak gRPC-Web themselves — see grpc-web (Lets gRPC-Web browser clients reach a gRPC upstream), reshaping a JSON body for a backend that reads JSON — see body-transformer (Rewrites request and response bodies with templates) or changing the path, Host or headers the backend receives — see proxy-rewrite (Rewrites the request URI, method, host and headers before proxying).

Set it up

Translate JSON requests into calls to a gRPC service method

proto_id is the ID the engine gave the Proto object when it was saved, shown on the Proto's page, and not the Proto's name; that Proto defines orders.Orders, and the route's upstream scheme is grpc.

Under Basics pick your proto in Proto ID, set Service to orders.Orders and set Method to GetOrder. Under Behavior set Deadline to 3000 milliseconds.

grpc-transcode · as the console saves it

{
  "proto_id": "00000000000000799563",
  "service": "orders.Orders",
  "method": "GetOrder",
  "deadline": 3000
}

Things to know

• Service — The call reaches the backend under the service's full name. A backend that does not serve orders.Orders answers it, and the client gets 501 with unknown service orders.Orders.
• Proto ID — An ID the gateway does not hold is saved without complaint. Every request then reaches the backend untranscoded, and a gRPC backend answers 502.
• Proto ID — The ID is text: a number, 7000007 for example, is refused when you save.
• Service — A name the proto does not define is saved without complaint, and every request is answered 503.
• Method — An empty Method is refused when you save.
• Protobuf options — When two words of one family are stored, the one that sorts last wins. Left empty, the four default words apply.
• Response body limit — A longer answer is cut before it is decoded, and the client can receive 200 with empty or partial fields.
• A GET whose query string carries the fields, id=42 for example, is transcoded too: it reaches the backend under the service's name, as a POST with a JSON body does.
• AdviceKeep the proto beside the backend's own source and update both together, so the gateway and the backend read one contract.

Settings

The fields as the console shows them, section by section.

Basics

Proto IDproto_idstringRequired

The id of the Proto that defines the service and method below. The engine assigns that id when the Proto is created, so it is not the Proto's name. An id the gateway does not hold is saved without complaint, and every request then reaches the upstream untranscoded, which a gRPC upstream answers with 502.

1 to 64 characters · letters, digits, dots, hyphens and underscores

pattern

^[a-zA-Z0-9-_.]+$

ServiceservicestringRequired

The full name of a service defined in that proto, package included, such as hello.HelloService. A name the proto does not define is saved without complaint and every request is answered 503.

at least 1 character

MethodmethodstringRequired

The name of the method inside that service.

at least 1 character

Behavior

Protobuf optionspb_optionarray of stringsdefault ["enum_as_name","int64_as_number","auto_default_values","disable_hooks"]

Decoding options, at most one word per family: enums, 64-bit integers, absent fields and hooks. When two words of one family are stored, the one that sorts last wins. Left empty, the four default words apply.

at least 1 item · one of enum_as_name, enum_as_value, int64_as_hexstring, int64_as_number, int64_as_string, auto_default_values, no_default_values, use_default_metatable, use_default_values, disable_hooks, enable_hooks

Deadlinedeadlinenumberdefault 0

The call's deadline sent to the upstream, where zero or less sends none.

in milliseconds

Show status in bodyshow_status_in_bodybooleandefault false

On a failed call the decoded status details are written into the response body as well.

Status detail typestatus_detail_typestring

The message type the status details are decoded as, where empty leaves them as they arrived.

Advanced

Response body limitmax_resp_body_sizeintegerdefault 67108864

The largest response in bytes held for transcoding. A longer response is cut before decoding, and the client can receive 200 with empty or partial fields.

at least 1

Every plugin also has Enabled, Priority, Filter, Error response and Pre-function: see Plugin execution settings.