Local reply mapper - implementation

api/envoy/config/filter/accesslog/v2/accesslog.proto

@@ -45,6 +45,7 @@ message AccessLog {
   }
 }
 
+// [#next-major-version: In the v3 API, we should consider renaming it to more generic filter]
 // [#next-free-field: 12]
 message AccessLogFilter {
   oneof filter_specifier {

api/envoy/config/filter/accesslog/v3alpha/accesslog.proto

@@ -47,6 +47,7 @@ message AccessLog {
   }
 }
 
+// [#next-major-version: In the v3 API, we should consider renaming it to more generic filter]
 // [#next-free-field: 12]
 message AccessLogFilter {
   oneof filter_specifier {

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

@@ -11,6 +11,7 @@ import "envoy/api/v2/core/protocol.proto";
 import "envoy/api/v2/rds.proto";
 import "envoy/api/v2/srds.proto";
 import "envoy/config/filter/accesslog/v2/accesslog.proto";
+import "envoy/type/format.proto";
 import "envoy/type/percent.proto";
 
 import "google/protobuf/any.proto";
@@ -24,7 +25,7 @@ import "validate/validate.proto";
 // HTTP connection manager :ref:`configuration overview <config_http_conn_man>`.
 // [#extension: envoy.filters.network.http_connection_manager]
 
-// [#next-free-field: 36]
+// [#next-free-field: 37]
 message HttpConnectionManager {
   enum CodecType {
     // For every new connection, the connection manager will determine which
@@ -468,6 +469,35 @@ 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;
+
+  // Configuration of local reply returned by Envoy. Allows to specify mappings and format of
+  // response.
+  LocalReplyConfig local_reply_config = 36;
+}
+
+message LocalReplyConfig {
+  // Configuration of list of mappers which allows to filter and change local response.
+  // The client will iterate through mappers until first match.
+  repeated ResponseMapper mapper = 1;
+
+  // Allows to define custom format of local reply.
+  // It is allowed to use :ref:`command operators <config_access_log_command_operators>`
+  // which will be resolved to actual data.
+  type.StringOrJson format = 2;
+}
+
+message ResponseMapper {
+  // Filter is used to determine if the response should be rewritten.
+  accesslog.v2.AccessLogFilter filter = 1 [(validate.rules).message = {required: true}];
+
+  // Rewriter defines how to rewrite determined response.
+  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;
 }
 
 message Rds {

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

@@ -11,6 +11,7 @@ import "envoy/api/v3alpha/core/protocol.proto";
 import "envoy/api/v3alpha/rds.proto";
 import "envoy/api/v3alpha/srds.proto";
 import "envoy/config/filter/accesslog/v3alpha/accesslog.proto";
+import "envoy/type/v3alpha/format.proto";
 import "envoy/type/v3alpha/percent.proto";
 
 import "google/protobuf/any.proto";
@@ -24,7 +25,7 @@ import "validate/validate.proto";
 // HTTP connection manager :ref:`configuration overview <config_http_conn_man>`.
 // [#extension: envoy.filters.network.http_connection_manager]
 
-// [#next-free-field: 36]
+// [#next-free-field: 37]
 message HttpConnectionManager {
   enum CodecType {
     // For every new connection, the connection manager will determine which
@@ -455,6 +456,35 @@ 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;
+
+  // Configuration of local reply returned by Envoy. Allows to specify mappings and format of
+  // response.
+  LocalReplyConfig local_reply_config = 36;
+}
+
+message LocalReplyConfig {
+  // Configuration of list of mappers which allows to filter and change local response.
+  // The client will iterate through mappers until first match.
+  repeated ResponseMapper mapper = 1;
+
+  // Allows to define custom format of local reply.
+  // It is allowed to use :ref:`command operators <config_access_log_command_operators>`
+  // which will be resolved to actual data.
+  type.v3alpha.StringOrJson format = 2;
+}
+
+message ResponseMapper {
+  // Filter is used to determine if the response should be rewritten.
+  accesslog.v3alpha.AccessLogFilter filter = 1 [(validate.rules).message = {required: true}];
+
+  // Rewriter defines how to rewrite determined response.
+  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;
 }
 
 message Rds {

api/envoy/type/format.proto

@@ -0,0 +1,43 @@
+syntax = "proto3";
+
+package envoy.type;
+
+option java_outer_classname = "FormatProto";
+option java_multiple_files = true;
+option java_package = "io.envoyproxy.envoy.type";
+
+import "google/protobuf/struct.proto";
+
+// [#protodoc-title: Format]
+
+// Allows to define one of format: flat plain text or structured json.
+message StringOrJson {
+  oneof format {
+    // Allows to specify flat plain text format.
+    //
+    // .. code-block:: yaml
+    //
+    //   string_format: "My custom message"
+    //
+    string string_format = 1;
+
+    // Allows to specify structured data as json.
+    //
+    // .. code-block:: yaml
+    //
+    //  json_format:
+    //    protocol: "HTTP/1.1"
+    //    message: "My message"
+    //
+    // The following JSON object would be created:
+    //
+    // .. code-block:: json
+    //
+    //  {
+    //    "protocol": "HTTP/1.1",
+    //    "message": "My message"
+    //  }
+    //
+    google.protobuf.Struct json_format = 2;
+  }
+}

api/envoy/type/v3alpha/format.proto

@@ -0,0 +1,43 @@
+syntax = "proto3";
+
+package envoy.type.v3alpha;
+
+option java_outer_classname = "FormatProto";
+option java_multiple_files = true;
+option java_package = "io.envoyproxy.envoy.type.v3alpha";
+
+import "google/protobuf/struct.proto";
+
+// [#protodoc-title: Format]
+
+// Allows to define one of format: flat plain text or structured json.
+message StringOrJson {
+  oneof format {
+    // Allows to specify flat plain text format.
+    //
+    // .. code-block:: yaml
+    //
+    //   string_format: "My custom message"
+    //
+    string string_format = 1;
+
+    // Allows to specify structured data as json.
+    //
+    // .. code-block:: yaml
+    //
+    //  json_format:
+    //    protocol: "HTTP/1.1"
+    //    message: "My message"
+    //
+    // The following JSON object would be created:
+    //
+    // .. code-block:: json
+    //
+    //  {
+    //    "protocol": "HTTP/1.1",
+    //    "message": "My message"
+    //  }
+    //
+    google.protobuf.Struct json_format = 2;
+  }
+}

docs/root/api-v2/types/types.rst

@@ -5,6 +5,7 @@ Types
   :glob:
   :maxdepth: 2
 
+  ../type/format.proto
   ../type/hash_policy.proto
   ../type/http.proto
   ../type/http_status.proto

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

@@ -12,6 +12,7 @@ HTTP connection manager
   header_casing
   headers
   header_sanitizing
+  local_reply
   stats
   runtime
   rds

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

@@ -0,0 +1,107 @@
+.. _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.
+
+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.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. 
+It is also possible to use new command operator provided only for local reply modification purpose.
+
+%RESP_BODY%
+    HTTP response body generated by Envoy.
+

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

include/envoy/access_log/access_log.h

@@ -114,7 +114,8 @@ class Formatter {
   virtual std::string format(const Http::HeaderMap& request_headers,
                              const Http::HeaderMap& response_headers,
                              const Http::HeaderMap& response_trailers,
-                             const StreamInfo::StreamInfo& stream_info) const PURE;
+                             const StreamInfo::StreamInfo& stream_info,
+                             const absl::string_view& response_body) const PURE;
 };
 
 using FormatterPtr = std::unique_ptr<Formatter>;
@@ -133,12 +134,14 @@ class FormatterProvider {
    * @param response_headers supplies the response headers.
    * @param response_trailers supplies the response trailers.
    * @param stream_info supplies the stream info.
+   * @param response_body supplies the response body.
    * @return std::string containing a single value extracted from the given headers/trailers/stream.
    */
   virtual std::string format(const Http::HeaderMap& request_headers,
                              const Http::HeaderMap& response_headers,
                              const Http::HeaderMap& response_trailers,
-                             const StreamInfo::StreamInfo& stream_info) const PURE;
+                             const StreamInfo::StreamInfo& stream_info,
+                             const absl::string_view& response_body) const PURE;
 };
 
 using FormatterProviderPtr = std::unique_ptr<FormatterProvider>;