dynamic_modules: support for http callouts (envoyproxy#39151)

Commit Message: dynamic_modules: support for http callouts 
Additional Description:

This adds support for http callouts initiated from HTTP filter context.
More precisely, this adds a new ABI function:
* envoy_dynamic_module_callback_http_filter_http_callout
* envoy_dynamic_module_on_http_filter_http_callout_done 

Risk Level: low 
Testing: unit+integration
Docs Changes: n/a
Release Notes: n/a
Platform Specific Features: n/a

---------

Signed-off-by: Takeshi Yoneda <[email protected]>

Author: mathetake

source/extensions/dynamic_modules/abi.h

@@ -371,6 +371,34 @@ typedef enum {
   envoy_dynamic_module_type_attribute_id_XdsFilterChainName,
 } envoy_dynamic_module_type_attribute_id;
 
+/**
+ * envoy_dynamic_module_type_http_callout_init_result represents the result of the HTTP callout
+ * initialization after envoy_dynamic_module_callback_http_filter_http_callout is called.
+ * Success means the callout is successfully initialized and ready to be used.
+ * MissingRequiredHeaders means the callout is missing one of the required headers, :path, :method,
+ * or host header. DuplicateCalloutId means the callout id is already used by another callout.
+ * ClusterNotFound means the cluster is not found in the configuration. CannotCreateRequest means
+ * the request cannot be created. That happens when, for example, there's no healthy upstream host
+ * in the cluster.
+ */
+typedef enum {
+  envoy_dynamic_module_type_http_callout_init_result_Success,
+  envoy_dynamic_module_type_http_callout_init_result_MissingRequiredHeaders,
+  envoy_dynamic_module_type_http_callout_init_result_ClusterNotFound,
+  envoy_dynamic_module_type_http_callout_init_result_DuplicateCalloutId,
+  envoy_dynamic_module_type_http_callout_init_result_CannotCreateRequest,
+} envoy_dynamic_module_type_http_callout_init_result;
+
+/**
+ * envoy_dynamic_module_type_http_callout_result represents the result of the HTTP callout.
+ * This corresponds to `AsyncClient::FailureReason::*` in envoy/http/async_client.h plus Success.
+ */
+typedef enum {
+  envoy_dynamic_module_type_http_callout_result_Success,
+  envoy_dynamic_module_type_http_callout_result_Reset,
+  envoy_dynamic_module_type_http_callout_result_ExceedResponseBufferLimit,
+} envoy_dynamic_module_type_http_callout_result;
+
 // -----------------------------------------------------------------------------
 // ------------------------------- Event Hooks ---------------------------------
 // -----------------------------------------------------------------------------
@@ -566,6 +594,32 @@ void envoy_dynamic_module_on_http_filter_stream_complete(
 void envoy_dynamic_module_on_http_filter_destroy(
     envoy_dynamic_module_type_http_filter_module_ptr filter_module_ptr);
 
+/**
+ * envoy_dynamic_module_on_http_filter_http_callout_done is called when the HTTP callout
+ * response is received initiated by a HTTP filter.
+ *
+ * @param filter_envoy_ptr is the pointer to the DynamicModuleHttpFilter object of the
+ * corresponding HTTP filter.
+ * @param filter_module_ptr is the pointer to the in-module HTTP filter created by
+ * envoy_dynamic_module_on_http_filter_new.
+ * @param callout_id is the ID of the callout. This is used to differentiate between multiple
+ * calls.
+ * @param result is the result of the callout.
+ * @param headers is the headers of the response.
+ * @param headers_size is the size of the headers.
+ * @param body_vector is the body of the response.
+ * @param body_vector_size is the size of the body.
+ *
+ * headers and body_vector are owned by Envoy, and they are guaranteed to be valid until the end of
+ * this event hook. They may be null if the callout fails or the response is empty.
+ */
+void envoy_dynamic_module_on_http_filter_http_callout_done(
+    envoy_dynamic_module_type_http_filter_envoy_ptr filter_envoy_ptr,
+    envoy_dynamic_module_type_http_filter_module_ptr filter_module_ptr, uint32_t callout_id,
+    envoy_dynamic_module_type_http_callout_result result,
+    envoy_dynamic_module_type_http_header* headers, size_t headers_size,
+    envoy_dynamic_module_type_envoy_buffer* body_vector, size_t body_vector_size);
+
 // -----------------------------------------------------------------------------
 // -------------------------------- Callbacks ----------------------------------
 // -----------------------------------------------------------------------------
@@ -1083,6 +1137,32 @@ bool envoy_dynamic_module_callback_http_filter_get_attribute_int(
     envoy_dynamic_module_type_http_filter_envoy_ptr filter_envoy_ptr,
     envoy_dynamic_module_type_attribute_id attribute_id, uint64_t* result);
 
+/**
+ * envoy_dynamic_module_callback_http_filter_http_callout is called by the module to initiate
+ * an HTTP callout. The callout is initiated by the HTTP filter and the response is received in
+ * envoy_dynamic_module_on_http_filter_http_callout_done.
+ *
+ * @param filter_envoy_ptr is the pointer to the DynamicModuleHttpFilter object of the
+ * corresponding HTTP filter.
+ * @param callout_id is the ID of the callout. This can be arbitrary and is used to
+ * differentiate between multiple calls from the same filter.
+ * @param cluster_name is the name of the cluster to which the callout is sent.
+ * @param cluster_name_length is the length of the cluster name.
+ * @param headers is the headers of the request. It must contain :method, :path and host headers.
+ * @param headers_size is the size of the headers.
+ * @param body is the pointer to the buffer of the body of the request.
+ * @param body_size is the length of the body.
+ * @param timeout_milliseconds is the timeout for the callout in milliseconds.
+ * @return envoy_dynamic_module_type_http_callout_init_result is the result of the callout.
+ */
+envoy_dynamic_module_type_http_callout_init_result
+envoy_dynamic_module_callback_http_filter_http_callout(
+    envoy_dynamic_module_type_http_filter_envoy_ptr filter_envoy_ptr, uint32_t callout_id,
+    envoy_dynamic_module_type_buffer_module_ptr cluster_name, size_t cluster_name_length,
+    envoy_dynamic_module_type_http_header* headers, size_t headers_size,
+    envoy_dynamic_module_type_buffer_module_ptr body, size_t body_size,
+    uint64_t timeout_milliseconds);
+
 #ifdef __cplusplus
 }
 #endif

source/extensions/dynamic_modules/abi_version.h

@@ -6,7 +6,7 @@ namespace DynamicModules {
 #endif
 // This is the ABI version calculated as a sha256 hash of the ABI header files. When the ABI
 // changes, this value must change, and the correctness of this value is checked by the test.
-const char* kAbiVersion = "0874b1e9587ef1dbd355ffde32f3caf424cb819df552de4833b2ed5b8996c18b";
+const char* kAbiVersion = "915695bafb13d22d4f0bdb3b9a249193532779eb8a7dc7d72b48ecc1c9fe943e";
 
 #ifdef __cplusplus
 } // namespace DynamicModules

source/extensions/dynamic_modules/sdk/rust/src/lib.rs

@@ -207,6 +207,23 @@ pub trait HttpFilter<EHF: EnvoyHttpFilter> {
   ///
   /// This is called before this [`HttpFilter`] object is dropped and access logs are flushed.
   fn on_stream_complete(&mut self, _envoy_filter: &mut EHF) {}
+
+  /// This is called when the HTTP callout is done.
+  ///
+  /// * `envoy_filter` can be used to interact with the underlying Envoy filter object.
+  /// * `callout_id` is the ID of the callout that was done.
+  /// * `result` indicates the result of the callout.
+  /// * `response_headers` is a list of key-value pairs of the response headers. This is optional.
+  /// * `response_body` is the response body. This is optional.
+  fn on_http_callout_done(
+    &mut self,
+    _envoy_filter: &mut EHF,
+    _callout_id: u32,
+    _result: abi::envoy_dynamic_module_type_http_callout_result,
+    _response_headers: Option<&[(EnvoyBuffer, EnvoyBuffer)]>,
+    _response_body: Option<&[EnvoyBuffer]>,
+  ) {
+  }
 }
 
 /// An opaque object that represents the underlying Envoy Http filter config. This has one to one
@@ -533,6 +550,32 @@ pub trait EnvoyHttpFilter {
     &self,
     attribute_id: abi::envoy_dynamic_module_type_attribute_id,
   ) -> Option<i64>;
+
+  /// Send an HTTP callout to the given cluster with the given headers and body.
+  /// Multiple callouts can be made from the same filter. Different callouts can be
+  /// distinguished by the `callout_id` parameter.
+  ///
+  /// Headers must contain the `:method`, ":path", and `host` headers.
+  ///
+  /// This returns the status of the callout. The meaning of the status is
+  ///
+  ///   * Success: The callout was sent successfully.
+  ///   * MissingRequiredHeaders: One of the required headers is missing: `:method`, `:path`, or
+  ///     `host`.
+  ///   * ClusterNotFound: The cluster with the given name was not found.
+  ///   * DuplicateCalloutId: The callout ID is already in use.
+  ///   * CouldNotCreateRequest: The request could not be created. This happens when, for example,
+  ///     there's no healthy upstream host in the cluster.
+  ///
+  /// The callout result will be delivered to the [`HttpFilter::on_http_callout_done`] method.
+  fn send_http_callout<'a>(
+    &mut self,
+    _callout_id: u32,
+    _cluster_name: &'a str,
+    _headers: Vec<(&'a str, &'a [u8])>,
+    _body: Option<&'a [u8]>,
+    _timeout_milliseconds: u64,
+  ) -> abi::envoy_dynamic_module_type_http_callout_init_result;
 }
 
 /// This implements the [`EnvoyHttpFilter`] trait with the given raw pointer to the Envoy HTTP
@@ -1016,6 +1059,32 @@ impl EnvoyHttpFilter for EnvoyHttpFilterImpl {
       None
     }
   }
+
+  fn send_http_callout<'a>(
+    &mut self,
+    callout_id: u32,
+    cluster_name: &'a str,
+    headers: Vec<(&'a str, &'a [u8])>,
+    body: Option<&'a [u8]>,
+    timeout_milliseconds: u64,
+  ) -> abi::envoy_dynamic_module_type_http_callout_init_result {
+    let body_ptr = body.map(|s| s.as_ptr()).unwrap_or(std::ptr::null());
+    let body_length = body.map(|s| s.len()).unwrap_or(0);
+    let headers_ptr = headers.as_ptr() as *const abi::envoy_dynamic_module_type_module_http_header;
+    unsafe {
+      abi::envoy_dynamic_module_callback_http_filter_http_callout(
+        self.raw_ptr,
+        callout_id,
+        cluster_name.as_ptr() as *const _ as *mut _,
+        cluster_name.len(),
+        headers_ptr as *const _ as *mut _,
+        headers.len(),
+        body_ptr as *const _ as *mut _,
+        body_length,
+        timeout_milliseconds,
+      )
+    }
+  }
 }
 
 impl EnvoyHttpFilterImpl {
@@ -1341,3 +1410,37 @@ unsafe extern "C" fn envoy_dynamic_module_on_http_filter_response_trailers(
   let filter = &mut **filter;
   filter.on_response_trailers(&mut EnvoyHttpFilterImpl::new(envoy_ptr))
 }
+
+#[no_mangle]
+unsafe extern "C" fn envoy_dynamic_module_on_http_filter_http_callout_done(
+  envoy_ptr: abi::envoy_dynamic_module_type_http_filter_envoy_ptr,
+  filter_ptr: abi::envoy_dynamic_module_type_http_filter_module_ptr,
+  callout_id: u32,
+  result: abi::envoy_dynamic_module_type_http_callout_result,
+  headers: *const abi::envoy_dynamic_module_type_http_header,
+  headers_size: usize,
+  body_vector: *const abi::envoy_dynamic_module_type_envoy_buffer,
+  body_vector_size: usize,
+) {
+  let filter = filter_ptr as *mut *mut dyn HttpFilter<EnvoyHttpFilterImpl>;
+  let filter = &mut **filter;
+  let headers = if headers_size > 0 {
+    Some(unsafe {
+      std::slice::from_raw_parts(headers as *const (EnvoyBuffer, EnvoyBuffer), headers_size)
+    })
+  } else {
+    None
+  };
+  let body = if body_vector_size > 0 {
+    Some(unsafe { std::slice::from_raw_parts(body_vector as *const EnvoyBuffer, body_vector_size) })
+  } else {
+    None
+  };
+  filter.on_http_callout_done(
+    &mut EnvoyHttpFilterImpl::new(envoy_ptr),
+    callout_id,
+    result,
+    headers,
+    body,
+  )
+}

source/extensions/filters/http/dynamic_modules/abi_impl.cc

@@ -1,3 +1,5 @@
+#include "source/common/http/header_map_impl.h"
+#include "source/common/http/message_impl.h"
 #include "source/common/http/utility.h"
 #include "source/common/router/string_accessor_impl.h"
 #include "source/extensions/dynamic_modules/abi.h"
@@ -713,6 +715,41 @@ bool envoy_dynamic_module_callback_http_filter_get_attribute_int(
   }
   return ok;
 }
+
+envoy_dynamic_module_type_http_callout_init_result
+envoy_dynamic_module_callback_http_filter_http_callout(
+    envoy_dynamic_module_type_http_filter_envoy_ptr filter_envoy_ptr, uint32_t callout_id,
+    envoy_dynamic_module_type_buffer_module_ptr cluster_name, size_t cluster_name_length,
+    envoy_dynamic_module_type_http_header* headers, size_t headers_size,
+    envoy_dynamic_module_type_buffer_module_ptr body, size_t body_size,
+    uint64_t timeout_milliseconds) {
+  auto filter = static_cast<DynamicModuleHttpFilter*>(filter_envoy_ptr);
+
+  // Try to get the cluster from the cluster manager for the given cluster name.
+  absl::string_view cluster_name_view(cluster_name, cluster_name_length);
+
+  // Construct the request message, starting with the headers, checking for required headers, and
+  // adding the body if present.
+  std::unique_ptr<RequestHeaderMapImpl> hdrs = Http::RequestHeaderMapImpl::create();
+  for (size_t i = 0; i < headers_size; i++) {
+    const auto& header = &headers[i];
+    const absl::string_view key(static_cast<const char*>(header->key_ptr), header->key_length);
+    const absl::string_view value(static_cast<const char*>(header->value_ptr),
+                                  header->value_length);
+    hdrs->addCopy(Http::LowerCaseString(key), value);
+  }
+  Http::RequestMessagePtr message(new Http::RequestMessageImpl(std::move(hdrs)));
+  if (message->headers().Path() == nullptr || message->headers().Method() == nullptr ||
+      message->headers().Host() == nullptr) {
+    return envoy_dynamic_module_type_http_callout_init_result_MissingRequiredHeaders;
+  }
+  if (body_size > 0) {
+    message->body().add(absl::string_view(static_cast<const char*>(body), body_size));
+    message->headers().setContentLength(body_size);
+  }
+  return filter->sendHttpCallout(callout_id, cluster_name_view, std::move(message),
+                                 timeout_milliseconds);
+}
 }
 } // namespace HttpFilters
 } // namespace DynamicModules

source/extensions/filters/http/dynamic_modules/factory.cc

@@ -32,7 +32,7 @@ absl::StatusOr<Http::FilterFactoryCb> DynamicModuleConfigFactory::createFilterFa
       Envoy::Extensions::DynamicModules::HttpFilters::DynamicModuleHttpFilterConfigSharedPtr>
       filter_config =
           Envoy::Extensions::DynamicModules::HttpFilters::newDynamicModuleHttpFilterConfig(
-              proto_config.filter_name(), config, std::move(dynamic_module.value()));
+              proto_config.filter_name(), config, std::move(dynamic_module.value()), context);
 
   if (!filter_config.ok()) {
     return absl::InvalidArgumentError("Failed to create filter config: " +