gRPC-JSON reverse transcoder (proto)

This extension has the qualified name envoy.filters.http.grpc_json_reverse_transcoder

Note

This extension is functional but has not had substantial production burn time, use only with this caveat.

This extension has an unknown security posture and should only be used in deployments where both the downstream and upstream are trusted.

Tip

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

envoy.filters.http

This extension must be configured with one of the following type URLs:

type.googleapis.com/envoy.extensions.filters.http.grpc_json_reverse_transcoder.v3.GrpcJsonReverseTranscoder

gRPC-JSON reverse transcoder configuration overview.

extensions.filters.http.grpc_json_reverse_transcoder.v3.GrpcJsonReverseTranscoder

[extensions.filters.http.grpc_json_reverse_transcoder.v3.GrpcJsonReverseTranscoder proto]

GrpcJsonReverseTranscoder is the filter configuration for the gRPC JSON reverse transcoder. The reverse transcoder acts as a bridge between a gRPC client and an HTTP/JSON server, converting the gRPC request into HTTP/JSON for the HTTP backend and the HTTP/JSON response back to gRPC for the gRPC client. This effectively reverses the behavior of the grpc_json_transcoder filter, allowing a gRPC client to communicate with an HTTP/JSON server.

{
  "descriptor_path": ...,
  "descriptor_binary": ...,
  "max_request_body_size": {...},
  "max_response_body_size": {...},
  "api_version_header": ...,
  "request_json_print_options": {...}
}

descriptor_path: (string) Supplies the filename of the proto descriptor set for the gRPC services. If set, takes precedence over the descriptor_binary field.

descriptor_binary: (bytes) Supplies the binary content of the proto descriptor set for the gRPC services. If descriptor_path is set, this field is not used.

max_request_body_size

(UInt32Value) The maximum size of a request body to be transcoded, in bytes. A body exceeding this size will provoke a gRPC status: ResourceExhausted response.

Large values may cause envoy to use a lot of memory if there are many concurrent requests.

If unset, the current stream buffer size is used.

max_response_body_size

(UInt32Value) The maximum size of a response body to be transcoded, in bytes. A body exceeding this size will provoke a gRPC status: Internal response.

Large values may cause envoy to use a lot of memory if there are many concurrent requests.

If unset, the current stream buffer size is used.

api_version_header: (string) The name of the header field that has the API version of the request.

request_json_print_options: (extensions.filters.http.grpc_json_reverse_transcoder.v3.GrpcJsonReverseTranscoder.PrintOptions) Control options for upstream request JSON. These options are passed directly to JsonPrintOptions.

extensions.filters.http.grpc_json_reverse_transcoder.v3.GrpcJsonReverseTranscoder.PrintOptions

[extensions.filters.http.grpc_json_reverse_transcoder.v3.GrpcJsonReverseTranscoder.PrintOptions proto]

{
  "always_print_primitive_fields": ...,
  "always_print_enums_as_ints": ...,
  "use_canonical_field_names": ...
}

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.

use_canonical_field_names

(bool) Whether to convert the proto field names to json_name annotation value, or lower camel case, in absence of json_name. By default the field names will be preserved after conversion. Setting this flag will convert the field names to their canonical form. Defaults to false.

Example:

message Author {
  int64 id = 1;
  enum Gender {
    UNKNOWN = 0;
    MALE = 1;
    FEMALE = 2;
  };
  Gender gender = 2;
  string first_name = 3;
  string last_name = 4 [json_name = "lname"];
}

The above proto message after being transcoded to JSON with use_canonical_field_names set to false will have the field names same as in the proto message, as follows:

{
  "id": "12345",
  "gender": "MALE",
  "first_name": "John",
  "last_name": "Doe"
}

and with the use_canonical_field_names set to true, the transcoded JSON will have first_name converted to camelCase and last_name converted to its json_name annotation value, as follows:

{
  "id": "12345",
  "gender": "MALE",
  "firstName": "John",
  "lname": "Doe"
}