gRPC-JSON transcoder¶
This extension may be referenced by the qualified name envoy.filters.http.grpc_json_transcoder
Note
This extension has an unknown security posture and should only be used in deployments where both the downstream and upstream are trusted.
gRPC-JSON transcoder configuration overview.
config.filter.http.transcoder.v2.GrpcJsonTranscoder¶
[config.filter.http.transcoder.v2.GrpcJsonTranscoder proto]
{
"proto_descriptor": "...",
"proto_descriptor_bin": "...",
"services": [],
"print_options": "{...}",
"match_incoming_request_route": "...",
"ignored_query_parameters": [],
"auto_mapping": "...",
"ignore_unknown_query_parameters": "...",
"convert_grpc_status": "..."
}
- proto_descriptor
(string) Supplies the filename of the proto descriptor set for the gRPC services.
Precisely one of proto_descriptor, proto_descriptor_bin must be set.
- proto_descriptor_bin
(bytes) Supplies the binary content of the proto descriptor set for the gRPC services.
Precisely one of proto_descriptor, proto_descriptor_bin must be set.
- services
(repeated string, REQUIRED) A list of strings that supplies the fully qualified service names (i.e. “package_name.service_name”) that the transcoder will translate. If the service name doesn’t exist in
proto_descriptor
, Envoy will fail at startup. Theproto_descriptor
may contain more services than the service names specified here, but they won’t be translated.
- print_options
(config.filter.http.transcoder.v2.GrpcJsonTranscoder.PrintOptions) Control options for response JSON. These options are passed directly to JsonPrintOptions.
- match_incoming_request_route
(bool) Whether to keep the incoming request route after the outgoing headers have been transformed to the match the upstream gRPC service. Note: This means that routes for gRPC services that are not transcoded cannot be used in combination with match_incoming_request_route.
- ignored_query_parameters
(repeated string) A list of query parameters to be ignored for transcoding method mapping. By default, the transcoder filter will not transcode a request if there are any unknown/invalid query parameters.
Example :
service Bookstore { rpc GetShelf(GetShelfRequest) returns (Shelf) { option (google.api.http) = { get: "/shelves/{shelf}" }; } } message GetShelfRequest { int64 shelf = 1; } message Shelf {}
The request
/shelves/100?foo=bar
will not be mapped toGetShelf`
because variable binding forfoo
is not defined. Addingfoo
toignored_query_parameters
will allow the same request to be mapped toGetShelf
.
- auto_mapping
(bool) Whether to route methods without the
google.api.http
option.Example :
package bookstore; service Bookstore { rpc GetShelf(GetShelfRequest) returns (Shelf) {} } message GetShelfRequest { int64 shelf = 1; } message Shelf {}
The client could
post
a json body{"shelf": 1234}
with the path of/bookstore.Bookstore/GetShelfRequest
to callGetShelfRequest
.
- ignore_unknown_query_parameters
(bool) Whether to ignore query parameters that cannot be mapped to a corresponding protobuf field. Use this if you cannot control the query parameters and do not know them beforehand. Otherwise use
ignored_query_parameters
. Defaults to false.
- convert_grpc_status
(bool) Whether to convert gRPC status headers to JSON. When trailer indicates a gRPC error and there was no HTTP body, take
google.rpc.Status
from thegrpc-status-details-bin
header and use it as JSON body. If there was no such header, makegoogle.rpc.Status
out of thegrpc-status
andgrpc-message
headers. The error details types must be present in theproto_descriptor
.For example, if an upstream server replies with headers:
grpc-status: 5 grpc-status-details-bin: CAUaMwoqdHlwZS5nb29nbGVhcGlzLmNvbS9nb29nbGUucnBjLlJlcXVlc3RJbmZvEgUKA3ItMQ
The
grpc-status-details-bin
header contains a base64-encoded protobuf messagegoogle.rpc.Status
. It will be transcoded into:HTTP/1.1 404 Not Found content-type: application/json {"code":5,"details":[{"@type":"type.googleapis.com/google.rpc.RequestInfo","requestId":"r-1"}]} In order to transcode the message, the ``google.rpc.RequestInfo`` type from the ``google/rpc/error_details.proto`` should be included in the configured :ref:`proto descriptor set <config_grpc_json_generate_proto_descriptor_set>`.
config.filter.http.transcoder.v2.GrpcJsonTranscoder.PrintOptions¶
[config.filter.http.transcoder.v2.GrpcJsonTranscoder.PrintOptions proto]
{
"add_whitespace": "...",
"always_print_primitive_fields": "...",
"always_print_enums_as_ints": "...",
"preserve_proto_field_names": "..."
}
- add_whitespace
(bool) Whether to add spaces, line breaks and indentation to make the JSON output easy to read. Defaults to false.
- always_print_primitive_fields
(bool) Whether to always print primitive fields. By default primitive fields with default values will be omitted in JSON output. For example, an int32 field set to 0 will be omitted. Setting this flag to true will override the default behavior and print primitive fields regardless of their values. Defaults to false.
- always_print_enums_as_ints
(bool) Whether to always print enums as ints. By default they are rendered as strings. Defaults to false.
- preserve_proto_field_names
(bool) Whether to preserve proto field names. By default protobuf will generate JSON field names using the
json_name
option, or lower camel case, in that order. Setting this flag will preserve the original field names. Defaults to false.