<commit_before>.. _config_http_filters_grpc_json_transcoder:

gRPC-JSON transcoder
====================

* gRPC :ref:`architecture overview <arch_overview_grpc>`
* :ref:`v3 API reference <envoy_v3_api_msg_extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder>`
* This filter should be configured with the name *envoy.filters.http.grpc_json_transcoder*.

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 <https://cloud.google.com/service-management/reference/rpc/google.api#http>`_.

JSON mapping
------------

The protobuf to JSON mapping is defined `here <https://developers.google.com/protocol-buffers/docs/proto3#json>`_. For
gRPC stream request parameters, Envoy expects an array of messages, and it returns an array of messages for stream
response parameters.

.. _config_grpc_json_generate_proto_descriptor_set:

How to generate proto descriptor set
------------------------------------

Envoy has to know the proto descriptor of your gRPC service in order to do the transcoding.

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, to define the HTTP mapping.

.. code-block:: console

  $ git clone https://github.com/googleapis/googleapis
  $ GOOGLEAPIS_DIR=<your-local-googleapis-folder>

Then run protoc to generate the descriptor set. For example using the test
:repo:`bookstore.proto <test/proto/bookstore.proto>` provided in the Envoy repository:

.. code-block:: console

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

Route configs for transcoded requests
-------------------------------------
<commit_msg>Update incorrect docs for gRPC-JSON transcoder. (#19661)<commit_after>.. _config_http_filters_grpc_json_transcoder:

gRPC-JSON transcoder
====================

* gRPC :ref:`architecture overview <arch_overview_grpc>`
* :ref:`v3 API reference <envoy_v3_api_msg_extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder>`
* This filter should be configured with the name *envoy.filters.http.grpc_json_transcoder*.

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 <https://cloud.google.com/service-management/reference/rpc/google.api#http>`_.

JSON mapping
------------

The protobuf to JSON mapping is defined `here <https://developers.google.com/protocol-buffers/docs/proto3#json>`_. For
gRPC stream request parameters, Envoy expects an array of messages, and it returns an array of messages for stream
response parameters.

.. _config_grpc_json_generate_proto_descriptor_set:

How to generate proto descriptor set
------------------------------------

Envoy has to know the proto descriptor of your gRPC service in order to do the transcoding.

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, to define the HTTP mapping.

.. code-block:: console

  $ git clone https://github.com/googleapis/googleapis
  $ GOOGLEAPIS_DIR=<your-local-googleapis-folder>

Then run protoc to generate the descriptor set. For example using the test
:repo:`bookstore.proto <test/proto/bookstore.proto>` provided in the Envoy repository:

.. code-block:: console

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

Route configs for transcoded requests
-------------------------------------

{'fraction_non_alphanumeric': 0.11976487876561352, 'fraction_numerical': 0.0031839333823169237, 'mean_word_length': 3.902761104441777, 'pattern_counts': {'":': 0, '<': 15, '<?xml version=': 0, '>': 15, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7591778', 'n_tokens_mistral': 1150, 'n_tokens_neox': 1107, 'n_words': 430}