Chiebot-Mirror
/
data-plane-api
8
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

docs: gRPC transcoder filter (#286)

Browse Source 
Signed-off-by: Matt Klein <mklein@lyft.com>
pull/288/head
Matt Klein 8 years ago committed by htuch
parent 2ad4af574d
commit 3a63fc5035
5 changed files with 129 additions and 103 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 1
      api/BUILD
  2. 72
      api/filter/http/transcoder.proto
  3. 1
      docs/build.sh
  4. 82
      docs/root/api-v1/http_filters/grpc_json_transcoder_filter.rst
  5. 76
      docs/root/configuration/http_filters/grpc_json_transcoder_filter.rst

1
api/BUILD
Unescape View File

@ -150,6 +150,7 @@ proto_library(
"//api/filter/http:buffer",
"//api/filter/http:lua",
"//api/filter/http:router",
"//api/filter/http:transcoder",
"//api/filter/network:tcp_proxy",
"//api/filter/network:http_connection_manager",
"//api/filter/network:mongo_proxy",

72
api/filter/http/transcoder.proto
Unescape View File

@ -2,51 +2,65 @@ syntax = "proto3";
package envoy.api.v2.filter.http;
// This is a filter which allows a RESTful JSON API client to send requests
// to Envoy over HTTP and get proxied to a gRPC service. The HTTP mapping
// for the gRPC service has to be defined by custom options, defined in
// https://cloud.google.com/service-management/reference/rpc/google.api#http
import "validate/validate.proto";
// [#protodoc-title: gRPC-JSON transcoder]
// gRPC-JSON transcoder :ref:`configuration overview <config_http_filters_grpc_json_transcoder>`.
message GrpcJsonTranscoder {
// The filter config for the filter requires the descriptor file as well
// as a list of the gRPC services to be transcoded.
// Supplies the binary protobuf descriptor set for the gRPC services. The
// descriptor set has to include all of the types that are used in the
// services. Make sure to use the --include_import option for protoc.
string proto_descriptor = 1;
// A list of strings that supplies the service names 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.
repeated string services = 2;
// Control options for response json. These options are passed directly
// to JsonPrintOptions.
// Supplies the binary protobuf descriptor set for the gRPC services.
// The descriptor set has to include all of the types that are used in the services. Make sure
// to use the ``--include_import`` option for ``protoc``.
//
// To generate a protobuf descriptor set for the gRPC service, you'll also need to clone the
// googleapis repository from Github before running protoc, as you'll need annotations.proto
// in your include path.
//
// .. code-block:: bash
//
// git clone https://github.com/googleapis/googleapis
// GOOGLEAPIS_DIR=<your-local-googleapis-folder>
//
// Then run protoc to generate the descriptor set from bookstore.proto:
//
// .. code-block:: bash
//
// protoc -I$(GOOGLEAPIS_DIR) -I. --include_imports --include_source_info \
// --descriptor_set_out=proto.pb test/proto/bookstore.proto
//
// If you have more than one proto source files, you can pass all of them in one command.
string proto_descriptor = 1 [(validate.rules).string.min_len = 1];
// A list of strings that supplies the service names 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.
repeated string services = 2 [(validate.rules).repeated.min_items = 1];
message PrintOptions {
// Whether to add spaces, line breaks and indentation to make the JSON
// output easy to read. Default to false.
// output easy to read. Defaults to false.
bool add_whitespace = 1;
// 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. Set this flag to
// 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. Default to false.
// regardless of their values. Defaults to false.
bool always_print_primitive_fields = 2;
// Whether to always print enums as ints. By default they are rendered
// as strings. Default to false.
// as strings. Defaults to false.
bool always_print_enums_as_ints = 3;
// Whether to preserve proto field names. By default protobuf will
// generate JSON field names use json_name option, or lower camel case,
// in that order. Set this flag will preserve original field
// names. Default to false.
// 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.
bool preserve_proto_field_names = 4;
};
// Control options for response json. These options are passed directly
// to JsonPrintOptions.
// 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>`_.
PrintOptions print_options = 3;
}

1
docs/build.sh
Unescape View File

@ -41,6 +41,7 @@ PROTO_RST="
/api/filter/http/buffer/api/filter/http/buffer.proto.rst
/api/filter/http/lua/api/filter/http/lua.proto.rst
/api/filter/http/router/api/filter/http/router.proto.rst
/api/filter/http/transcoder/api/filter/http/transcoder.proto.rst
/api/filter/network/http_connection_manager/api/filter/network/http_connection_manager.proto.rst
/api/filter/network/mongo_proxy/api/filter/network/mongo_proxy.proto.rst
/api/filter/network/tcp_proxy/api/filter/network/tcp_proxy.proto.rst

82
docs/root/api-v1/http_filters/grpc_json_transcoder_filter.rst
Unescape View File

@ -0,0 +1,82 @@
.. _config_http_filters_grpc_json_transcoder_v1:
gRPC-JSON transcoder filter
===========================
gRPC-JSON transcoder :ref:`configuration overview <config_http_filters_grpc_json_transcoder>`.
Configure gRPC-JSON transcoder
------------------------------
The filter config for the filter requires the descriptor file as well as a list of the gRPC
services to be transcoded.
.. code-block:: json
{
"name": "grpc_json_transcoder",
"config": {
"proto_descriptor": "proto.pb",
"services": ["grpc.service.Service"],
"print_options": {
"add_whitespace": false,
"always_print_primitive_fields": false,
"always_print_enums_as_ints": false,
"preserve_proto_field_names": false
}
}
}
proto_descriptor
*(required, string)* Supplies the binary protobuf descriptor set for the gRPC services.
The descriptor set has to include all of the types that are used in the services. Make sure
to use the ``--include_import`` option for ``protoc``.
To generate a protobuf descriptor set for the gRPC service, you'll also need to clone the
googleapis repository from Github before running protoc, as you'll need annotations.proto
in your include path.
.. code-block:: bash
git clone https://github.com/googleapis/googleapis
GOOGLEAPIS_DIR=<your-local-googleapis-folder>
Then run protoc to generate the descriptor set from bookstore.proto:
.. code-block:: bash
protoc -I$(GOOGLEAPIS_DIR) -I. --include_imports --include_source_info \
--descriptor_set_out=proto.pb test/proto/bookstore.proto
If you have more than one proto source files, you can pass all of them in one command.
services
*(required, array)* A list of strings that supplies the service names 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
*(optional, object)* 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>`_. Valid options are:
add_whitespace
*(optional, boolean)* Whether to add spaces, line breaks and indentation to make the JSON
output easy to read. Defaults to false.
always_print_primitive_fields
*(optional, boolean)* 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
*(optional, boolean)* Whether to always print enums as ints. By default they are rendered
as strings. Defaults to false.
preserve_proto_field_names
*(optional, boolean)* 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.

76
docs/root/configuration/http_filters/grpc_json_transcoder_filter.rst
Unescape View File

@ -9,77 +9,5 @@ This is a filter which allows a RESTful JSON API client to send requests to Envo
and get proxied to a gRPC service. The HTTP mapping for the gRPC service has to be defined by
`custom options <https://cloud.google.com/service-management/reference/rpc/google.api#http>`_.
Configure gRPC-JSON transcoder
------------------------------
The filter config for the filter requires the descriptor file as well as a list of the gRPC
services to be transcoded.
.. code-block:: json
{
"name": "grpc_json_transcoder",
"config": {
"proto_descriptor": "proto.pb",
"services": ["grpc.service.Service"],
"print_options": {
"add_whitespace": false,
"always_print_primitive_fields": false,
"always_print_enums_as_ints": false,
"preserve_proto_field_names": false
}
}
}
proto_descriptor
*(required, string)* Supplies the binary protobuf descriptor set for the gRPC services.
The descriptor set has to include all of the types that are used in the services. Make sure
to use the ``--include_import`` option for ``protoc``.
To generate a protobuf descriptor set for the gRPC service, you'll also need to clone the
googleapis repository from Github before running protoc, as you'll need annotations.proto
in your include path.
.. code-block:: bash
git clone https://github.com/googleapis/googleapis
GOOGLEAPIS_DIR=<your-local-googleapis-folder>
Then run protoc to generate the descriptor set from bookstore.proto:
.. code-block:: bash
protoc -I$(GOOGLEAPIS_DIR) -I. --include_imports --include_source_info \
--descriptor_set_out=proto.pb test/proto/bookstore.proto
If you have more than one proto source files, you can pass all of them in one command.
services
*(required, array)* A list of strings that supplies the service names 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
*(optional, object)* 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>`_. Valid options are:
add_whitespace
*(optional, boolean)* Whether to add spaces, line breaks and indentation to make the JSON
output easy to read. Default to false.
always_print_primitive_fields
*(optional, boolean)* 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. Set this flag to true will override the default behavior and print primitive
fields regardless of their values. Default to false.
always_print_enums_as_ints
*(optional, boolean)* Whether to always print enums as ints. By default they are rendered as
strings. Default to false.
preserve_proto_field_names
*(optional, boolean)* Whether to preserve proto field names. By default protobuf will generate
JSON field names use ``json_name`` option, or lower camel case, in that order. Set this flag
will preserve original field names. Default to false.
* :ref:`v1 configuration <config_http_filters_grpc_json_transcoder_v1>`
* :ref:`v2 configuration <envoy_api_msg_filter.http.GrpcJsonTranscoder>`

Write Preview
Loading…
Cancel
Save