WiP: Local reply mapper

api/envoy/config/filter/network/http_connection_manager/v2/http_connection_manager.proto

@@ -23,7 +23,7 @@ import "validate/validate.proto";
 // [#protodoc-title: HTTP connection manager]
 // HTTP connection manager :ref:`configuration overview <config_http_conn_man>`.
 
-// [#comment:next free field: 35]
+// [#comment:next free field: 36]
 message HttpConnectionManager {
   enum CodecType {
 
@@ -453,6 +453,40 @@ message HttpConnectionManager {
   // with `prefix` match set to `/dir`. Defaults to `false`. Note that slash merging is not part of
   // `HTTP spec <https://tools.ietf.org/html/rfc3986>` and is provided for convenience.
   bool merge_slashes = 33;
+
+  message LocalReplyConfig {
+    // Configuration of list of mappers which allows to filter and change local response. 
+    // Code iterate through mappers until first match of filter.
+    repeated ResponseMapper mapper = 1;
+
+    // Allows to define custom format of local reply.
+    oneof reply_format {
+      // Response body plain text format.
+      string format = 2;
+
+      // Response body json format as dictionary.
+      google.protobuf.Struct json_format = 3;
+    }
+  };
+
+  // Configuration of local reply returned by Envoy. Allows to specify mapping and format of response.
+  LocalReplyConfig local_reply_config = 35;
+}
+
+message ResponseMapper {
+  // Filter is used to determine if the response should be changed.
+  envoy.config.filter.accesslog.v2.AccessLogFilter filter = 1 [(validate.rules).message.required = true];
+
+  // Rewriter defines which values in local reply should be changed.
+  ResponseRewriter rewriter = 2 [(validate.rules).message.required = true];
+}
+
+// Configuration of new value for matched local response.
+message ResponseRewriter {
+  // Status code for matched response.
+  google.protobuf.UInt32Value status_code = 1;
+
+  // TODO: add support for GRPC rewrite.
 }
 
 message Rds {

docs/root/configuration/http/http_conn_man/http_conn_man.rst

@@ -14,3 +14,4 @@ HTTP connection manager
   stats
   runtime
   rds
+  local_reply

docs/root/configuration/http/http_conn_man/local_reply.rst

@@ -0,0 +1,103 @@
+.. _config_http_conn_man_local_reply:
+
+Local reply modification
+========================
+
+The :ref:`HTTP connection manager <arch_overview_http_conn_man>` supports modification of local reply which is response returned by Envoy itself
+rather than response from cluster. 
+
+Features:
+
+* :ref:`Local reply content modification<config_http_conn_man_local_reply_modification>`.
+* :ref:`Local reply format modification<config_http_conn_man_local_reply_format>`.
+
+.. _config_http_conn_man_local_reply_modification:
+
+Local reply content modification
+--------------------------------
+
+There is support for modification of local replies. You can specify list of :ref:`mappers <envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.LocalReplyConfig.mapper>` which contains 
+pairs of :ref:`filter <envoy_api_msg_config.filter.accesslog.v2.AccessLogFilter>` and :ref:`rewriter <envoy_api_msg_config.filter.network.http_connection_manager.v2.ResponseRewriter>`. Both elements in pair has to be
+specified. If more than one pair is defined then first matching is used.
+
+Example how to change status code when local reply contains any of these response flags:
+
+.. code-block:: yaml
+
+  mapper:
+    filter:
+      response_flag_filter:
+        flags:
+        - LH
+        - UH
+    rewriter:
+      status_code: 504
+
+.. _config_http_conn_man_local_reply_format:
+
+Local reply format modification
+-------------------------------
+
+Local reply format contains command operators that extract the relevant data and insert it.
+They support two formats: :ref:`format strings <config_http_conn_man_local_reply_format_string>` and 
+:ref:`"format dictionaries" <config_http_conn_man_local_reply_dictionaries>`. In both cases, the :ref:`command operators <config_http_conn_man_local_reply_command_operators>`
+are used to extract the relevant data, which is then inserted into the specified reply format.
+Only one reply format may be specified at the time. 
+
+.. _config_http_conn_man_local_reply_format_string:
+
+Format Strings
+--------------
+
+Format strings are plain strings, specified using the ``format`` key. They may contain
+either :ref:`command operators <config_http_conn_man_local_reply_command_operators>` or other characters interpreted as a plain string.
+The access log formatter does not make any assumptions about a new line separator, so one
+has to specified as part of the format string.
+
+.. code-block:: none
+
+  %RESP_BODY% %RESPONSE_CODE% %RESPONSE_FLAGS% "My custom response"
+
+Example of custom Envoy local reply format:
+
+.. code-block:: none
+
+  upstream connect error or disconnect/reset before headers. reset reason: connection failure 204 UH My custom response
+
+
+If format isn't specified then :ref:`default format <config_http_conn_man_local_reply_default_format>` is used.
+
+.. _config_http_conn_man_local_reply_default_format:
+
+Default Format String
+---------------------
+
+If custom format string is not specified, Envoy uses the following default format:
+
+.. code-block:: none
+
+  %RESP_BODY%
+
+Example of the default local reply format:
+
+.. code-block:: none
+
+  upstream connect error or disconnect/reset before headers. reset reason: connection failure
+
+.. _config_http_conn_man_local_reply_dictionaries:
+
+Format Dictionaries
+-------------------
+
+Format dictionaries are dictionaries that specify a structured local reply output format,
+specified using the ``json_format`` key. This allows response to be returned in a structured format
+such as JSON.
+
+More can be found in :ref:`configuration <config_access_log_format_dictionaries>`.
+
+.. _config_http_conn_man_local_reply_command_operators:
+
+Command Operators
+-----------------
+
+Local reply format reuse :ref:`access log operators <config_access_log_command_operators>`, so more information can be found there.

docs/root/configuration/observability/access_log.rst

@@ -91,6 +91,8 @@ Format dictionaries have the following restrictions:
 
 * The dictionary must map strings to strings (specifically, strings to command operators). Nesting is not currently supported.
 
+.. _config_access_log_command_operators:
+
 Command Operators
 -----------------