lds: Add listener_filter_chain.

api/lds.proto

@@ -66,7 +66,17 @@ message Listener {
   // true, the listener hands off redirected connections to the listener associated with the
   // original destination address. If there is no listener associated with the original destination
   // address, the connection is handled by the listener that receives it. Defaults to false.
-  google.protobuf.BoolValue use_original_dst = 4;
+  //
+  // .. attention::
+  //
+  //   This field is deprecated. Use :ref:`an original_dst <config_listener_filters_original_dst>`
+  //   :ref:`listener filter <envoy_api_field_Listener.listener_filters>` instead.
+  //
+  //   Note that hand off to another listener is *NOT* performed without this flag. Once
+  //   :ref:`FilterChainMatch <envoy_api_msg_FilterChainMatch>` is implemented this flag will be
+  //   removed, as filter chain matching can be used to select a filter chain based on the restored
+  //   destination address.
+  google.protobuf.BoolValue use_original_dst = 4 [deprecated = true];
 
   // Soft limit on size of the listener’s new connection read and write buffers.
   // If unspecified, an implementation defined default is applied (1MiB).
@@ -103,6 +113,13 @@ message Listener {
 
   // The type of draining to perform at a listener-wide level.
   DrainType drain_type = 8;
+
+  // Listener filters have the opportunity to manipulate and augment the connection metadata that
+  // is used in connection filter chain matching, for example. These filters are run before any in
+  // :ref:`filter_chains <envoy_api_field_Listener.filter_chains>`. Order matters as the filters
+  // are processed sequentially right after a socket has been accepted by the listener, and before
+  // a connection is created.
+  repeated ListenerFilter listener_filters = 9;
 }
 
 message Filter {
@@ -205,3 +222,16 @@ message FilterChain {
   // [#not-implemented-hide:] See base.TransportSocket description.
   TransportSocket transport_socket = 6;
 }
+
+message ListenerFilter {
+  // The name of the filter to instantiate. The name must match a supported
+  // filter. The built-in filters are:
+  //
+  // [#comment:TODO(mattklein123): Auto generate the following list]
+  // * :ref:`envoy.listener.original_dst <config_listener_filters_original_dst>`
+  string name = 1 [(validate.rules).string.min_bytes = 1];
+
+  // Filter specific configuration which depends on the filter being
+  // instantiated. See the supported filters for further documentation.
+  google.protobuf.Struct config = 2;
+}

docs/root/api-v1/listeners/listeners.rst

@@ -36,7 +36,7 @@ address
   listeners are supported, e.g., "tcp://127.0.0.1:80". Note, "tcp://0.0.0.0:80" is the wild card
   match for any IPv4 address with port 80.
 
-:ref:`filters <config_listener_filters>`
+:ref:`filters <config_listener_network_filters>`
   *(required, array)* A list of individual :ref:`network filters <arch_overview_network_filters>`
   that make up the filter chain for connections established with the listener. Order matters as the
   filters are processed sequentially as connection events happen.
@@ -80,7 +80,7 @@ drain_type
   and *modify_only*. See the :ref:`draining <arch_overview_draining>` architecture overview for
   more information.
 
-.. _config_listener_filters:
+.. _config_listener_network_filters:
 
 Filters
 -------

docs/root/configuration/configuration.rst

@@ -10,6 +10,7 @@ Configuration reference
   overview/v1_overview
   overview/v2_overview
   listeners/listeners
+  listener_filters/listener_filters
   network_filters/network_filters
   http_conn_man/http_conn_man
   http_filters/http_filters

docs/root/configuration/listener_filters/listener_filters.rst

@@ -0,0 +1,11 @@
+.. _config_listener_filters:
+
+Listener filters
+================
+
+Envoy has the follow builtin listener filters.
+
+.. toctree::
+  :maxdepth: 2
+
+  original_dst_filter

docs/root/configuration/listener_filters/original_dst_filter.rst

@@ -0,0 +1,13 @@
+.. _config_listener_filters_original_dst:
+
+Original Destination
+====================
+
+Original destination listener filter reads the SO_ORIGINAL_DST socket option set when a connection
+has been redirected by iptables REDIRECT. Later processing in Envoy sees the restored destination
+address as the connection's local address, rather than the address at which the listener is
+listening at. Furthermore, :ref:`an original destination cluster
+<arch_overview_service_discovery_types_original_destination>` may be used to forward HTTP requests
+or TCP connections to the restored destination address.
+
+* :ref:`v2 API reference <envoy_api_field_Filter.name>`

docs/root/intro/arch_overview/arch_overview.rst

@@ -7,6 +7,7 @@ Architecture overview
   terminology
   threading_model
   listeners
+  listener_filters
   network_filters
   http_connection_management
   http_filters

docs/root/intro/arch_overview/dynamic_configuration.rst

@@ -18,7 +18,7 @@ Fully static
 ------------
 
 In a fully static configuration, the implementor provides a set of :ref:`listeners
-<config_listeners>` (and :ref:`filter chains <config_listener_filters>`), :ref:`clusters
+<config_listeners>` (and :ref:`filter chains <config_listener_network_filters>`), :ref:`clusters
 <config_cluster_manager>`, and optionally :ref:`HTTP route configurations
 <config_http_conn_man_route_table>`. Dynamic host discovery is only possible via DNS based
 :ref:`service discovery <arch_overview_service_discovery>`. Configuration reloads must take place

docs/root/intro/arch_overview/listener_filters.rst

@@ -0,0 +1,16 @@
+.. _arch_overview_listener_filters:
+
+Listener filters
+================
+
+As discussed in the :ref:`listener <arch_overview_listeners>` section, listener filters may be
+used to manipulate connection metadata. The main purpose of listener filters is to make adding
+further system integration functions easier by not requiring changes to Envoy core functionality,
+and also make interaction between multiple such features more explicit.
+
+The API for listener filters is relatively simple since ultimately these filters operate on newly
+accepted sockets. Filters in the chain can stop and subsequently continue iteration to
+further filters. This allows for more complex scenarios such as calling a :ref:`rate limiting
+service <arch_overview_rate_limit>`, etc. Envoy already includes several listener filters that
+are documented in this architecture overview as well as the :ref:`configuration reference
+<config_listener_filters>`.

docs/root/intro/arch_overview/listeners.rst

@@ -17,6 +17,11 @@ used for (e.g., :ref:`rate limiting <arch_overview_rate_limit>`, :ref:`TLS clien
 MongoDB :ref:`sniffing <arch_overview_mongo>`, raw :ref:`TCP proxy <arch_overview_tcp_proxy>`,
 etc.).
 
+Listeners are optionally also configured with some number of :ref:`listener filters
+<arch_overview_listener_filters>`. These filters are processed before the network level filters,
+and have the opportunity to manipulate the connection metadata, usually to influence how the
+connection is processed later filters or clusters.
+
 Listeners can also be fetched dynamically via the :ref:`listener discovery service (LDS)
 <config_listeners_lds>`.