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: (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. The proto_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

(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 to GetShelf` because variable binding for foo is not defined. Adding foo to ignored_query_parameters will allow the same request to be mapped to GetShelf.

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 call GetShelfRequest.

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 the grpc-status-details-bin header and use it as JSON body. If there was no such header, make google.rpc.Status out of the grpc-status and grpc-message headers. The error details types must be present in the proto_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 message google.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.