listener: first implementation of an Api Listener (#9516)

Description: this PR introduces the initial implementation of an Api Listener based on the proto configuration merged in envoyproxy/envoy#8170. Notably, this PR introduces the ability to add only _one_ api listener via _bootstrap config only_. This decision was made in order to iterate into more complex setups (multiple listeners, LDS supplied listeners) in subsequent PRs. Moreover, the API listener is created in the context of Envoy's main thread not worker threads.

A first use of this Api Listener can be seen in envoyproxy/envoy-mobile#616.
Risk Level: low, only used in Envoy Mobile. The risk here is about building something generally useful and flexible. Note however that a couple of things were rejiggered in the HCM.
Testing: unit and integration tests. Additional testing in https://github.com/lyft/envoy-mobile.
Docs Changes: Added inline comments and TODOs. Proto documentation is up-to-date.
Release Notes: similar to doc changes.

Signed-off-by: Jose Nino <jnino@lyft.com>

Mirrored from https://github.com/envoyproxy/envoy @ 9b6260fcf6ee1299744b8e5c76c1e6d9d36f7c89

envoy/api/v2/listener.proto

@@ -202,11 +202,16 @@ message Listener {
   // creating a packet-oriented UDP listener. If not present, treat it as "raw_udp_listener".
   listener.UdpListenerConfig udp_listener_config = 18;
 
-  // [#not-implemented-hide:]
   // Used to represent an API listener, which is used in non-proxy clients. The type of API
   // exposed to the non-proxy application depends on the type of API listener.
   // When this field is set, no other field except for :ref:`name<envoy_api_field_Listener.name>`
   // should be set.
+  //
+  // .. note::
+  //
+  //  Currently only one ApiListener can be installed; and it can only be done via bootstrap config,
+  //  not LDS.
+  //
   // [#next-major-version: In the v3 API, instead of this messy approach where the socket
   // listener fields are directly in the top-level Listener message and the API listener types
   // are in the ApiListener message, the socket listener messages should be in their own message,

envoy/config/listener/v2/api_listener.proto

@@ -11,13 +11,12 @@ option java_outer_classname = "ApiListenerProto";
 option java_multiple_files = true;
 option (udpa.annotations.file_migrate).move_to_package = "envoy.config.listener.v3";
 
-// [#not-implemented-hide:]
 // Describes a type of API listener, which is used in non-proxy clients. The type of API
 // exposed to the non-proxy application depends on the type of API listener.
 message ApiListener {
   // The type in this field determines the type of API listener. At present, the following
   // types are supported:
-  //   envoy.config.filter.network.http_connection_manager.v2.HttpConnectionManager (HTTP)
+  // envoy.config.filter.network.http_connection_manager.v2.HttpConnectionManager (HTTP)
   // [#next-major-version: In the v3 API, replace this Any field with a oneof containing the
   // specific config message for each type of API listener. We could not do this in v2 because
   // it would have caused circular dependencies for go protos: lds.proto depends on this file,

envoy/config/listener/v3/api_listener.proto

@@ -10,7 +10,6 @@ option java_package = "io.envoyproxy.envoy.config.listener.v3";
 option java_outer_classname = "ApiListenerProto";
 option java_multiple_files = true;
 
-// [#not-implemented-hide:]
 // Describes a type of API listener, which is used in non-proxy clients. The type of API
 // exposed to the non-proxy application depends on the type of API listener.
 message ApiListener {
@@ -19,7 +18,7 @@ message ApiListener {
 
   // The type in this field determines the type of API listener. At present, the following
   // types are supported:
-  //   envoy.config.filter.network.http_connection_manager.v2.HttpConnectionManager (HTTP)
+  // envoy.config.filter.network.http_connection_manager.v2.HttpConnectionManager (HTTP)
   // [#next-major-version: In the v3 API, replace this Any field with a oneof containing the
   // specific config message for each type of API listener. We could not do this in v2 because
   // it would have caused circular dependencies for go protos: lds.proto depends on this file,

envoy/config/listener/v3/listener.proto

@@ -196,11 +196,16 @@ message Listener {
   // for creating a packet-oriented UDP listener. If not present, treat it as "raw_udp_listener".
   UdpListenerConfig udp_listener_config = 18;
 
-  // [#not-implemented-hide:]
   // Used to represent an API listener, which is used in non-proxy clients. The type of API
   // exposed to the non-proxy application depends on the type of API listener.
   // When this field is set, no other field except for
   // :ref:`name<envoy_api_field_config.listener.v3.Listener.name>` should be set.
+  //
+  // .. note::
+  //
+  //  Currently only one ApiListener can be installed; and it can only be done via bootstrap config,
+  //  not LDS.
+  //
   // [#next-major-version: In the v3 API, instead of this messy approach where the socket
   // listener fields are directly in the top-level Listener message and the API listener types
   // are in the ApiListener message, the socket listener messages should be in their own message,