.. _envoy_v3_api_file_envoy/extensions/filters/http/grpc_json_transcoder/v3/transcoder.proto: gRPC-JSON transcoder ==================== This documentation is for the Envoy v3 API. As of Envoy v1.18 the v2 API has been removed and is no longer supported. If you are upgrading from v2 API config you may wish to view the v2 API documentation: :ref:`config/filter/http/transcoder/v2/transcoder.proto ` .. _extension_envoy.filters.http.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: - :ref:`envoy.filters.http ` gRPC-JSON transcoder :ref:`configuration overview `. .. _envoy_v3_api_msg_extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder: extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder ------------------------------------------------------------------ :repo:`[extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder proto] ` GrpcJsonTranscoder filter configuration. The filter itself can be used per route / per virtual host or on the general level. The most specific one is being used for a given route. If the list of services is empty - filter is considered to be disabled. Note that if specifying the filter per route, first the route is matched, and then transcoding filter is applied. It matters when specifying the route configuration and paths to match the request - for per-route grpc transcoder configs, the original path should be matched, while in other cases, the grpc-like path is expected (the one AFTER the filter is applied). .. code-block:: json { "proto_descriptor": "...", "proto_descriptor_bin": "...", "services": [], "print_options": "{...}", "match_incoming_request_route": "...", "ignored_query_parameters": [], "auto_mapping": "...", "ignore_unknown_query_parameters": "...", "convert_grpc_status": "...", "url_unescape_spec": "...", "request_validation_options": "{...}" } .. _envoy_v3_api_field_extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.proto_descriptor: proto_descriptor (`string `_) Supplies the filename of :ref:`the proto descriptor set ` for the gRPC services. Precisely one of :ref:`proto_descriptor `, :ref:`proto_descriptor_bin ` must be set. .. _envoy_v3_api_field_extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.proto_descriptor_bin: proto_descriptor_bin (`bytes `_) Supplies the binary content of :ref:`the proto descriptor set ` for the gRPC services. Precisely one of :ref:`proto_descriptor `, :ref:`proto_descriptor_bin ` must be set. .. _envoy_v3_api_field_extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.services: services (**repeated** `string `_) 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. By default, the filter will pass through requests that do not map to any specified services. If the list of services is empty, filter is considered disabled. However, this behavior changes if :ref:`reject_unknown_method ` is enabled. .. _envoy_v3_api_field_extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.print_options: print_options (:ref:`extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.PrintOptions `) Control options for response JSON. These options are passed directly to `JsonPrintOptions `_. .. _envoy_v3_api_field_extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.match_incoming_request_route: 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*. .. _envoy_v3_api_field_extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.ignored_query_parameters: 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 : .. code-block:: proto 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``. .. _envoy_v3_api_field_extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.auto_mapping: auto_mapping (`bool `_) Whether to route methods without the ``google.api.http`` option. Example : .. code-block:: proto 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``. .. _envoy_v3_api_field_extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.ignore_unknown_query_parameters: 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. .. _envoy_v3_api_field_extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.convert_grpc_status: 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: .. code-block:: none 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: .. code-block:: none 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 `. .. _envoy_v3_api_field_extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.url_unescape_spec: url_unescape_spec (:ref:`extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.UrlUnescapeSpec `) URL unescaping policy. This spec is only applied when extracting variable with multiple segments. For example, in case of `/foo/{x=*}/bar/{y=prefix/*}/{z=**}` `x` variable is single segment and `y` and `z` are multiple segments. For a path with `/foo/first/bar/prefix/second/third/fourth`, `x=first`, `y=prefix/second`, `z=third/fourth`. If this setting is not specified, the value defaults to :ref:`ALL_CHARACTERS_EXCEPT_RESERVED`. .. _envoy_v3_api_field_extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.request_validation_options: request_validation_options (:ref:`extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.RequestValidationOptions `) Configure the behavior when handling requests that cannot be transcoded. By default, the transcoder will silently pass through HTTP requests that are malformed. This includes requests with unknown query parameters, unregister paths, etc. Set these options to enable strict HTTP request validation, resulting in the transcoder rejecting such requests with a ``HTTP 4xx``. See each individual option for more details on the validation. gRPC requests will still silently pass through without transcoding. The benefit is a proper error message to the downstream. If the upstream is a gRPC server, it cannot handle the passed-through HTTP requests and will reset the TCP connection. The downstream will then receive a ``HTTP 503 Service Unavailable`` due to the upstream connection reset. This incorrect error message may conflict with other Envoy components, such as retry policies. .. _envoy_v3_api_msg_extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.PrintOptions: extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.PrintOptions ------------------------------------------------------------------------------- :repo:`[extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.PrintOptions proto] ` .. code-block:: json { "add_whitespace": "...", "always_print_primitive_fields": "...", "always_print_enums_as_ints": "...", "preserve_proto_field_names": "..." } .. _envoy_v3_api_field_extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.PrintOptions.add_whitespace: add_whitespace (`bool `_) Whether to add spaces, line breaks and indentation to make the JSON output easy to read. Defaults to false. .. _envoy_v3_api_field_extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.PrintOptions.always_print_primitive_fields: 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. .. _envoy_v3_api_field_extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.PrintOptions.always_print_enums_as_ints: always_print_enums_as_ints (`bool `_) Whether to always print enums as ints. By default they are rendered as strings. Defaults to false. .. _envoy_v3_api_field_extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.PrintOptions.preserve_proto_field_names: 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. .. _envoy_v3_api_msg_extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.RequestValidationOptions: extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.RequestValidationOptions ------------------------------------------------------------------------------------------- :repo:`[extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.RequestValidationOptions proto] ` .. code-block:: json { "reject_unknown_method": "...", "reject_unknown_query_parameters": "..." } .. _envoy_v3_api_field_extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.RequestValidationOptions.reject_unknown_method: reject_unknown_method (`bool `_) By default, a request that cannot be mapped to any specified gRPC :ref:`services ` will pass-through this filter. When set to true, the request will be rejected with a ``HTTP 404 Not Found``. .. _envoy_v3_api_field_extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.RequestValidationOptions.reject_unknown_query_parameters: reject_unknown_query_parameters (`bool `_) By default, a request with query parameters that cannot be mapped to the gRPC request message will pass-through this filter. When set to true, the request will be rejected with a ``HTTP 400 Bad Request``. The fields :ref:`ignore_unknown_query_parameters ` and :ref:`ignored_query_parameters ` have priority over this strict validation behavior. .. _envoy_v3_api_enum_extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.UrlUnescapeSpec: Enum extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.UrlUnescapeSpec --------------------------------------------------------------------------------------- :repo:`[extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.UrlUnescapeSpec proto] ` .. _envoy_v3_api_enum_value_extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.UrlUnescapeSpec.ALL_CHARACTERS_EXCEPT_RESERVED: ALL_CHARACTERS_EXCEPT_RESERVED *(DEFAULT)* ⁣URL path parameters will not decode RFC 6570 reserved characters. For example, segment `%2f%23/%20%2523` is unescaped to `%2f%23/ %23`. .. _envoy_v3_api_enum_value_extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.UrlUnescapeSpec.ALL_CHARACTERS_EXCEPT_SLASH: ALL_CHARACTERS_EXCEPT_SLASH ⁣URL path parameters will be fully URI-decoded except in cases of single segment matches in reserved expansion, where "%2F" will be left encoded. For example, segment `%2f%23/%20%2523` is unescaped to `%2f#/ %23`. .. _envoy_v3_api_enum_value_extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.UrlUnescapeSpec.ALL_CHARACTERS: ALL_CHARACTERS ⁣URL path parameters will be fully URI-decoded. For example, segment `%2f%23/%20%2523` is unescaped to `/#/ %23`.