listener: first implementation of an Api Listener

api/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,

api/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,

api/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,

api/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,

include/envoy/http/BUILD

@@ -8,6 +8,12 @@ load(
 
 envoy_package()
 
+envoy_cc_library(
+    name = "api_listener_interface",
+    hdrs = ["api_listener.h"],
+    deps = [":codec_interface"],
+)
+
 envoy_cc_library(
     name = "async_client_interface",
     hdrs = ["async_client.h"],

include/envoy/http/api_listener.h

@@ -0,0 +1,33 @@
+#pragma once
+
+#include "envoy/http/codec.h"
+
+namespace Envoy {
+namespace Http {
+
+/**
+ * ApiListener that allows consumers to interact with HTTP streams via API calls.
+ */
+// TODO(junr03): this is a replica of the functions in ServerConnectionCallbacks. It would be nice
+// to not duplicate this interface layout.
+class ApiListener {
+public:
+  virtual ~ApiListener() = default;
+
+  /**
+   * Invoked when a new request stream is initiated by the remote.
+   * @param response_encoder supplies the encoder to use for creating the response. The request and
+   *                         response are backed by the same Stream object.
+   * @param is_internally_created indicates if this stream was originated by a
+   *   client, or was created by Envoy, by example as part of an internal redirect.
+   * @return StreamDecoder& supplies the decoder callbacks to fire into for stream decoding events.
+   */
+  virtual StreamDecoder& newStream(StreamEncoder& response_encoder,
+                                   bool is_internally_created = false) PURE;
+};
+
+using ApiListenerPtr = std::unique_ptr<ApiListener>;
+using ApiListenerOptRef = absl::optional<std::reference_wrapper<ApiListener>>;
+
+} // namespace Http
+} // namespace Envoy

include/envoy/server/BUILD

@@ -31,6 +31,12 @@ envoy_cc_library(
     ],
 )
 
+envoy_cc_library(
+    name = "api_listener_interface",
+    hdrs = ["api_listener.h"],
+    deps = ["//include/envoy/http:api_listener_interface"],
+)
+
 envoy_cc_library(
     name = "configuration_interface",
     hdrs = ["configuration.h"],
@@ -189,6 +195,7 @@ envoy_cc_library(
     name = "listener_manager_interface",
     hdrs = ["listener_manager.h"],
     deps = [
+        ":api_listener_interface",
         ":drain_manager_interface",
         ":filter_config_interface",
         ":guarddog_interface",

include/envoy/server/api_listener.h

@@ -0,0 +1,39 @@
+#pragma once
+
+#include "envoy/http/api_listener.h"
+
+namespace Envoy {
+namespace Server {
+
+/**
+ * Listener that allows consumer to interact with Envoy via a designated API.
+ */
+class ApiListener {
+public:
+  enum class Type { HttpApiListener };
+
+  virtual ~ApiListener() = default;
+
+  /**
+   * An ApiListener is uniquely identified by its name.
+   *
+   * @return the name of the ApiListener.
+   */
+  virtual absl::string_view name() const PURE;
+
+  /**
+   * @return the Type of the ApiListener.
+   */
+  virtual Type type() const PURE;
+
+  /**
+   * @return valid ref IFF type() == Type::HttpApiListener, otherwise nullopt.
+   */
+  virtual Http::ApiListenerOptRef http() PURE;
+};
+
+using ApiListenerPtr = std::unique_ptr<ApiListener>;
+using ApiListenerOptRef = absl::optional<std::reference_wrapper<ApiListener>>;
+
+} // namespace Server
+} // namespace Envoy

include/envoy/server/listener_manager.h

@@ -9,6 +9,7 @@
 #include "envoy/network/filter.h"
 #include "envoy/network/listen_socket.h"
 #include "envoy/network/listener.h"
+#include "envoy/server/api_listener.h"
 #include "envoy/server/drain_manager.h"
 #include "envoy/server/filter_config.h"
 #include "envoy/server/guarddog.h"
@@ -212,6 +213,14 @@ class ListenerManager {
    */
   using FailureStates = std::vector<std::unique_ptr<envoy::admin::v3::UpdateFailureState>>;
   virtual void endListenerUpdate(FailureStates&& failure_states) PURE;
+
+  // TODO(junr03): once ApiListeners support warming and draining, this function should return a
+  // weak_ptr to its caller. This would allow the caller to verify if the
+  // ApiListener is available to receive API calls on it.
+  /**
+   * @return the server's API Listener if it exists, nullopt if it does not.
+   */
+  virtual ApiListenerOptRef apiListener() PURE;
 };
 
 } // namespace Server

source/common/http/BUILD

@@ -162,6 +162,7 @@ envoy_cc_library(
         "//include/envoy/common:time_interface",
         "//include/envoy/event:deferred_deletable",
         "//include/envoy/event:dispatcher_interface",
+        "//include/envoy/http:api_listener_interface",
         "//include/envoy/http:codec_interface",
         "//include/envoy/http:context_interface",
         "//include/envoy/http:filter_interface",

source/common/http/conn_manager_impl.cc

@@ -286,18 +286,31 @@ void ConnectionManagerImpl::handleCodecException(const char* error) {
   read_callbacks_->connection().close(Network::ConnectionCloseType::FlushWriteAndDelay);
 }
 
+void ConnectionManagerImpl::createCodec(Buffer::Instance& data) {
+  ASSERT(!codec_);
+  codec_ = config_.createCodec(read_callbacks_->connection(), data, *this);
+
+  switch (codec_->protocol()) {
+  case Protocol::Http3:
+    stats_.named_.downstream_cx_http3_total_.inc();
+    stats_.named_.downstream_cx_http3_active_.inc();
+    break;
+  case Protocol::Http2:
+    stats_.named_.downstream_cx_http2_total_.inc();
+    stats_.named_.downstream_cx_http2_active_.inc();
+    break;
+  case Protocol::Http11:
+  case Protocol::Http10:
+    stats_.named_.downstream_cx_http1_total_.inc();
+    stats_.named_.downstream_cx_http1_active_.inc();
+    break;
+  }
+}
+
 Network::FilterStatus ConnectionManagerImpl::onData(Buffer::Instance& data, bool) {
   if (!codec_) {
     // Http3 codec should have been instantiated by now.
-    codec_ = config_.createCodec(read_callbacks_->connection(), data, *this);
-    if (codec_->protocol() == Protocol::Http2) {
-      stats_.named_.downstream_cx_http2_total_.inc();
-      stats_.named_.downstream_cx_http2_active_.inc();
-    } else {
-      ASSERT(codec_->protocol() != Protocol::Http3);
-      stats_.named_.downstream_cx_http1_total_.inc();
-      stats_.named_.downstream_cx_http1_active_.inc();
-    }
+    createCodec(data);
   }
 
   bool redispatch;
@@ -357,10 +370,8 @@ Network::FilterStatus ConnectionManagerImpl::onNewConnection() {
   }
   // Only QUIC connection's stream_info_ specifies protocol.
   Buffer::OwnedImpl dummy;
-  codec_ = config_.createCodec(read_callbacks_->connection(), dummy, *this);
+  createCodec(dummy);
   ASSERT(codec_->protocol() == Protocol::Http3);
-  stats_.named_.downstream_cx_http3_total_.inc();
-  stats_.named_.downstream_cx_http3_active_.inc();
   // Stop iterating through each filters for QUIC. Currently a QUIC connection
   // only supports one filter, HCM, and bypasses the onData() interface. Because
   // QUICHE already handles de-multiplexing.

source/common/http/conn_manager_impl.h

@@ -11,6 +11,7 @@
 #include "envoy/access_log/access_log.h"
 #include "envoy/common/scope_tracker.h"
 #include "envoy/event/deferred_deletable.h"
+#include "envoy/http/api_listener.h"
 #include "envoy/http/codec.h"
 #include "envoy/http/codes.h"
 #include "envoy/http/context.h"
@@ -48,7 +49,8 @@ namespace Http {
 class ConnectionManagerImpl : Logger::Loggable<Logger::Id::http>,
                               public Network::ReadFilter,
                               public ServerConnectionCallbacks,
-                              public Network::ConnectionCallbacks {
+                              public Network::ConnectionCallbacks,
+                              public Http::ApiListener {
 public:
   ConnectionManagerImpl(ConnectionManagerConfig& config, const Network::DrainDecision& drain_close,
                         Runtime::RandomGenerator& random_generator, Http::Context& http_context,
@@ -66,6 +68,15 @@ class ConnectionManagerImpl : Logger::Loggable<Logger::Id::http>,
                                                               Stats::Scope& scope);
   static const HeaderMapImpl& continueHeader();
 
+  // Currently the ConnectionManager creates a codec lazily when either:
+  //   a) onConnection for H3.
+  //   b) onData for H1 and H2.
+  // With the introduction of ApiListeners, neither event occurs. This function allows consumer code
+  // to manually create a codec.
+  // TODO(junr03): consider passing a synthetic codec instead of creating once. The codec in the
+  // ApiListener case is solely used to determine the protocol version.
+  void createCodec(Buffer::Instance& data);
+
   // Network::ReadFilter
   Network::FilterStatus onData(Buffer::Instance& data, bool end_stream) override;
   Network::FilterStatus onNewConnection() override;

source/common/protobuf/utility.h

@@ -303,6 +303,22 @@ class MessageUtil {
     return typed_message;
   };
 
+  /**
+   * Convert and validate from google.protobuf.Any to a typed message.
+   * @param message source google.protobuf.Any message.
+   *
+   * @return MessageType the typed message inside the Any.
+   * @throw ProtoValidationException if the message does not satisfy its type constraints.
+   */
+  template <class MessageType>
+  static inline MessageType
+  anyConvertAndValidate(const ProtobufWkt::Any& message,
+                        ProtobufMessage::ValidationVisitor& validation_visitor) {
+    MessageType typed_message = anyConvert<MessageType>(message);
+    validate(typed_message, validation_visitor);
+    return typed_message;
+  };
+
   /**
    * Convert between two protobufs via a JSON round-trip. This is used to translate arbitrary
    * messages to/from google.protobuf.Struct.

source/extensions/filters/network/http_connection_manager/BUILD

@@ -20,6 +20,7 @@ envoy_cc_extension(
     deps = [
         "//include/envoy/config:config_provider_manager_interface",
         "//include/envoy/filesystem:filesystem_interface",
+        "//include/envoy/http:codec_interface",
         "//include/envoy/http:filter_interface",
         "//include/envoy/registry",
         "//include/envoy/router:route_config_provider_manager_interface",