Package io.envoyproxy.envoy.extensions.filters.http.grpc_json_transcoder.v3

Interface GrpcJsonTranscoderOrBuilder

All Superinterfaces:
com.google.protobuf.MessageLiteOrBuilder, com.google.protobuf.MessageOrBuilder
All Known Implementing Classes:
GrpcJsonTranscoder, GrpcJsonTranscoder.Builder
public interface GrpcJsonTranscoderOrBuilder extends com.google.protobuf.MessageOrBuilder

  • Method Details

    • hasProtoDescriptor

      boolean hasProtoDescriptor()
       Supplies the filename of
 :ref:`the proto descriptor set <config_grpc_json_generate_proto_descriptor_set>` for the gRPC
 services.
      string proto_descriptor = 1;
      Returns:
      Whether the protoDescriptor field is set.

    • getProtoDescriptor

      String getProtoDescriptor()
       Supplies the filename of
 :ref:`the proto descriptor set <config_grpc_json_generate_proto_descriptor_set>` for the gRPC
 services.
      string proto_descriptor = 1;
      Returns:
      The protoDescriptor.

    • getProtoDescriptorBytes

      com.google.protobuf.ByteString getProtoDescriptorBytes()
       Supplies the filename of
 :ref:`the proto descriptor set <config_grpc_json_generate_proto_descriptor_set>` for the gRPC
 services.
      string proto_descriptor = 1;
      Returns:
      The bytes for protoDescriptor.

    • hasProtoDescriptorBin

      boolean hasProtoDescriptorBin()
       Supplies the binary content of
 :ref:`the proto descriptor set <config_grpc_json_generate_proto_descriptor_set>` for the gRPC
 services.
      bytes proto_descriptor_bin = 4;
      Returns:
      Whether the protoDescriptorBin field is set.

    • getProtoDescriptorBin

      com.google.protobuf.ByteString getProtoDescriptorBin()
       Supplies the binary content of
 :ref:`the proto descriptor set <config_grpc_json_generate_proto_descriptor_set>` for the gRPC
 services.
      bytes proto_descriptor_bin = 4;
      Returns:
      The protoDescriptorBin.

    • getServicesList

      List<String> getServicesList()
       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 <envoy_v3_api_field_extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.RequestValidationOptions.reject_unknown_method>`
 is enabled.
      repeated string services = 2;
      Returns:
      A list containing the services.

    • getServicesCount

      int getServicesCount()
       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 <envoy_v3_api_field_extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.RequestValidationOptions.reject_unknown_method>`
 is enabled.
      repeated string services = 2;
      Returns:
      The count of services.

    • getServices

      String getServices(int index)
       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 <envoy_v3_api_field_extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.RequestValidationOptions.reject_unknown_method>`
 is enabled.
      repeated string services = 2;
      Parameters:
      index - The index of the element to return.
      Returns:
      The services at the given index.

    • getServicesBytes

      com.google.protobuf.ByteString getServicesBytes(int index)
       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 <envoy_v3_api_field_extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.RequestValidationOptions.reject_unknown_method>`
 is enabled.
      repeated string services = 2;
      Parameters:
      index - The index of the value to return.
      Returns:
      The bytes of the services at the given index.

    • hasPrintOptions

      boolean hasPrintOptions()
       Control options for response JSON. These options are passed directly to
 `JsonPrintOptions <https://developers.google.com/protocol-buffers/docs/reference/cpp/
 google.protobuf.util.json_util#JsonPrintOptions>`_.
      .envoy.extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.PrintOptions print_options = 3;
      Returns:
      Whether the printOptions field is set.

    • getPrintOptions

      GrpcJsonTranscoder.PrintOptions getPrintOptions()
       Control options for response JSON. These options are passed directly to
 `JsonPrintOptions <https://developers.google.com/protocol-buffers/docs/reference/cpp/
 google.protobuf.util.json_util#JsonPrintOptions>`_.
      .envoy.extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.PrintOptions print_options = 3;
      Returns:
      The printOptions.

    • getPrintOptionsOrBuilder

      GrpcJsonTranscoder.PrintOptionsOrBuilder getPrintOptionsOrBuilder()
       Control options for response JSON. These options are passed directly to
 `JsonPrintOptions <https://developers.google.com/protocol-buffers/docs/reference/cpp/
 google.protobuf.util.json_util#JsonPrintOptions>`_.
      .envoy.extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.PrintOptions print_options = 3;

    • getMatchIncomingRequestRoute

      boolean getMatchIncomingRequestRoute()
       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``.
      bool match_incoming_request_route = 5;
      Returns:
      The matchIncomingRequestRoute.

    • getIgnoredQueryParametersList

      List<String> getIgnoredQueryParametersList()
       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``.
      repeated string ignored_query_parameters = 6;
      Returns:
      A list containing the ignoredQueryParameters.

    • getIgnoredQueryParametersCount

      int getIgnoredQueryParametersCount()
       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``.
      repeated string ignored_query_parameters = 6;
      Returns:
      The count of ignoredQueryParameters.

    • getIgnoredQueryParameters

      String getIgnoredQueryParameters(int index)
       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``.
      repeated string ignored_query_parameters = 6;
      Parameters:
      index - The index of the element to return.
      Returns:
      The ignoredQueryParameters at the given index.

    • getIgnoredQueryParametersBytes

      com.google.protobuf.ByteString getIgnoredQueryParametersBytes(int index)
       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``.
      repeated string ignored_query_parameters = 6;
      Parameters:
      index - The index of the value to return.
      Returns:
      The bytes of the ignoredQueryParameters at the given index.

    • getAutoMapping

      boolean getAutoMapping()
       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``.
      bool auto_mapping = 7;
      Returns:
      The autoMapping.

    • getIgnoreUnknownQueryParameters

      boolean getIgnoreUnknownQueryParameters()
       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.
      bool ignore_unknown_query_parameters = 8;
      Returns:
      The ignoreUnknownQueryParameters.

    • getConvertGrpcStatus

      boolean getConvertGrpcStatus()
       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 <config_grpc_json_generate_proto_descriptor_set>`.
      bool convert_grpc_status = 9;
      Returns:
      The convertGrpcStatus.

    • getUrlUnescapeSpecValue

      int getUrlUnescapeSpecValue()
       URL unescaping policy.
 This spec is only applied when extracting variable with multiple segments in the URL path.
 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_enum_value_extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.UrlUnescapeSpec.ALL_CHARACTERS_EXCEPT_RESERVED>`.
      .envoy.extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.UrlUnescapeSpec url_unescape_spec = 10 [(.validate.rules) = { ... }
      Returns:
      The enum numeric value on the wire for urlUnescapeSpec.

    • getUrlUnescapeSpec

      GrpcJsonTranscoder.UrlUnescapeSpec getUrlUnescapeSpec()
       URL unescaping policy.
 This spec is only applied when extracting variable with multiple segments in the URL path.
 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_enum_value_extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.UrlUnescapeSpec.ALL_CHARACTERS_EXCEPT_RESERVED>`.
      .envoy.extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.UrlUnescapeSpec url_unescape_spec = 10 [(.validate.rules) = { ... }
      Returns:
      The urlUnescapeSpec.

    • getQueryParamUnescapePlus

      boolean getQueryParamUnescapePlus()
       If true, unescape '+' to space when extracting variables in query parameters.
 This is to support `HTML 2.0 <https://tools.ietf.org/html/rfc1866#section-8.2.1>`_
      bool query_param_unescape_plus = 12;
      Returns:
      The queryParamUnescapePlus.

    • getMatchUnregisteredCustomVerb

      boolean getMatchUnregisteredCustomVerb()
       If true, try to match the custom verb even if it is unregistered. By
 default, only match when it is registered.

 According to the http template `syntax <https://github.com/googleapis/googleapis/blob/master/google/api/http.proto#L226-L231>`_,
 the custom verb is **":" LITERAL** at the end of http template.

 For a request with ``/foo/bar:baz`` and ``:baz`` is not registered in any url_template, here is the behavior change
 - if the field is not set, ``:baz`` will not be treated as custom verb, so it will match ``/foo/{x=*}``.
 - if the field is set, ``:baz`` is treated as custom verb,  so it will NOT match ``/foo/{x=*}`` since the template doesn't use any custom verb.
      bool match_unregistered_custom_verb = 13;
      Returns:
      The matchUnregisteredCustomVerb.

    • hasRequestValidationOptions

      boolean hasRequestValidationOptions()
       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.extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.RequestValidationOptions request_validation_options = 11;
      Returns:
      Whether the requestValidationOptions field is set.

    • getRequestValidationOptions

      GrpcJsonTranscoder.RequestValidationOptions getRequestValidationOptions()
       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.extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.RequestValidationOptions request_validation_options = 11;
      Returns:
      The requestValidationOptions.

    • getRequestValidationOptionsOrBuilder

      GrpcJsonTranscoder.RequestValidationOptionsOrBuilder getRequestValidationOptionsOrBuilder()
       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.extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.RequestValidationOptions request_validation_options = 11;

    • getCaseInsensitiveEnumParsing

      boolean getCaseInsensitiveEnumParsing()
       Proto enum values are supposed to be in upper cases when used in JSON.
 Set this to true if your JSON request uses non uppercase enum values.
      bool case_insensitive_enum_parsing = 14;
      Returns:
      The caseInsensitiveEnumParsing.

    • hasMaxRequestBodySize

      boolean hasMaxRequestBodySize()
       The maximum size of a request body to be transcoded, in bytes. A body exceeding this size will
 provoke a ``HTTP 413 Request Entity Too Large`` 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.
      .google.protobuf.UInt32Value max_request_body_size = 15 [(.validate.rules) = { ... }
      Returns:
      Whether the maxRequestBodySize field is set.

    • getMaxRequestBodySize

      com.google.protobuf.UInt32Value getMaxRequestBodySize()
       The maximum size of a request body to be transcoded, in bytes. A body exceeding this size will
 provoke a ``HTTP 413 Request Entity Too Large`` 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.
      .google.protobuf.UInt32Value max_request_body_size = 15 [(.validate.rules) = { ... }
      Returns:
      The maxRequestBodySize.

    • getMaxRequestBodySizeOrBuilder

      com.google.protobuf.UInt32ValueOrBuilder getMaxRequestBodySizeOrBuilder()
       The maximum size of a request body to be transcoded, in bytes. A body exceeding this size will
 provoke a ``HTTP 413 Request Entity Too Large`` 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.
      .google.protobuf.UInt32Value max_request_body_size = 15 [(.validate.rules) = { ... }

    • hasMaxResponseBodySize

      boolean hasMaxResponseBodySize()
       The maximum size of a response body to be transcoded, in bytes. A body exceeding this size will
 provoke a ``HTTP 500 Internal Server Error`` 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.
      .google.protobuf.UInt32Value max_response_body_size = 16 [(.validate.rules) = { ... }
      Returns:
      Whether the maxResponseBodySize field is set.

    • getMaxResponseBodySize

      com.google.protobuf.UInt32Value getMaxResponseBodySize()
       The maximum size of a response body to be transcoded, in bytes. A body exceeding this size will
 provoke a ``HTTP 500 Internal Server Error`` 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.
      .google.protobuf.UInt32Value max_response_body_size = 16 [(.validate.rules) = { ... }
      Returns:
      The maxResponseBodySize.

    • getMaxResponseBodySizeOrBuilder

      com.google.protobuf.UInt32ValueOrBuilder getMaxResponseBodySizeOrBuilder()
       The maximum size of a response body to be transcoded, in bytes. A body exceeding this size will
 provoke a ``HTTP 500 Internal Server Error`` 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.
      .google.protobuf.UInt32Value max_response_body_size = 16 [(.validate.rules) = { ... }

    • getCaptureUnknownQueryParameters

      boolean getCaptureUnknownQueryParameters()
       If true, query parameters that cannot be mapped to a corresponding
 protobuf field are captured in an HttpBody extension of UnknownQueryParams.
      bool capture_unknown_query_parameters = 17;
      Returns:
      The captureUnknownQueryParameters.

    • getDescriptorSetCase

      GrpcJsonTranscoder.DescriptorSetCase getDescriptorSetCase()