gRPC-JSON transcoder¶

This extension may be referenced by the qualified name envoy.filters.http.grpc_json_transcoder

Note

This extension is intended to be robust against untrusted downstream traffic. It assumes that the upstream is trusted.

Tip

This extension extends and can be used with the following extension category:

envoy.filters.http

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

(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 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.