dynamic_modules: scaffolds config API & HTTP Filter

CODEOWNERS

@@ -356,6 +356,7 @@ extensions/filters/http/oauth2 @derekargueta @mattklein123
 /*/extensions/filters/network/generic_proxy/ @wbpcode @soulxu
 # Dynamic Modules
 /*/extensions/dynamic_modules @mattklein123 @mathetake @marc-barry
+/*/extensions/filters/http/dynamic_modules @mattklein123 @mathetake @marc-barry
 
 # HTTP credential injector
 /*/extensions/filters/http/credential_injector @zhaohuabing @kyessenov

api/BUILD

@@ -151,6 +151,7 @@ proto_library(
         "//envoy/extensions/compression/zstd/compressor/v3:pkg",
         "//envoy/extensions/compression/zstd/decompressor/v3:pkg",
         "//envoy/extensions/config/validators/minimum_clusters/v3:pkg",
+        "//envoy/extensions/dynamic_modules/v3:pkg",
         "//envoy/extensions/early_data/v3:pkg",
         "//envoy/extensions/filters/common/dependency/v3:pkg",
         "//envoy/extensions/filters/common/fault/v3:pkg",
@@ -175,6 +176,7 @@ proto_library(
         "//envoy/extensions/filters/http/custom_response/v3:pkg",
         "//envoy/extensions/filters/http/decompressor/v3:pkg",
         "//envoy/extensions/filters/http/dynamic_forward_proxy/v3:pkg",
+        "//envoy/extensions/filters/http/dynamic_modules/v3:pkg",
         "//envoy/extensions/filters/http/ext_authz/v3:pkg",
         "//envoy/extensions/filters/http/ext_proc/v3:pkg",
         "//envoy/extensions/filters/http/fault/v3:pkg",

api/envoy/extensions/dynamic_modules/v3/BUILD

@@ -0,0 +1,13 @@
+# DO NOT EDIT. This file is generated by tools/proto_format/proto_sync.py.
+
+load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package")
+
+licenses(["notice"])  # Apache 2
+
+api_proto_package(
+    deps = [
+        "//envoy/config/core/v3:pkg",
+        "@com_github_cncf_xds//udpa/annotations:pkg",
+        "@com_github_cncf_xds//xds/annotations/v3:pkg",
+    ],
+)

api/envoy/extensions/dynamic_modules/v3/dynamic_modules.proto

@@ -0,0 +1,45 @@
+syntax = "proto3";
+
+package envoy.extensions.dynamic_modules.v3;
+
+import "envoy/config/core/v3/base.proto";
+
+import "xds/annotations/v3/status.proto";
+
+import "udpa/annotations/status.proto";
+
+option java_package = "io.envoyproxy.envoy.extensions.dynamic_modules.v3";
+option java_outer_classname = "DynamicModulesProto";
+option java_multiple_files = true;
+option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/dynamic_modules/v3;dynamic_modulesv3";
+option (udpa.annotations.file_status).package_version_status = ACTIVE;
+option (xds.annotations.v3.file_status).work_in_progress = true;
+
+// [#protodoc-title: Dynamic Modules common configuration]
+
+// Configuration of a dynamic module. A dynamic module is a shared object file that can be loaded via dlopen
+// by a various Envoy extension points. Currently, only HTTP filter (envoy.filters.http.dynamic_modules) is supported.
+//
+// How the module is loaded is determined by the extension point that uses it. For example, the HTTP filter
+// loads the module with dlopen on the first creation of the filter chain for the same shared object file.
+//
+// Whether or not the shared object is the same is determined by the file path as well as the file's inode depending
+// on the platform. Notably, if the file path and the content of the file are the same, the shared object will be reused.
+//
+// A module must be compatible with the ABI specified in :repo:`abi.h <source/extensions/dynamic_modules/abi.h>`.
+// Currently, compatibility is only guaranteed by an exact version match between the Envoy
+// codebase and the dynamic module SDKs. In the future, after the ABI is stabilized, we will revisit
+// this restriction and hopefully provide a wider compatibility guarantee. Until then, Envoy
+// checks the hash of the ABI header files to ensure that the dynamic modules are built against the
+// same version of the ABI.
+//
+// Currently, the implementation is work in progress and not usable.
+// [#next-free-field: 8]
+message DynamicModuleConfig {
+  // The location of the object file. Currently, only the local path is supported.
+  config.core.v3.DataSource object_file = 7;
+
+  // Set true to prevent the module from being unloaded with dlclose.
+  // This is useful for modules that have global state that should not be unloaded.
+  bool do_not_close = 3;
+}

api/envoy/extensions/filters/http/dynamic_modules/v3/BUILD

@@ -0,0 +1,13 @@
+# DO NOT EDIT. This file is generated by tools/proto_format/proto_sync.py.
+
+load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package")
+
+licenses(["notice"])  # Apache 2
+
+api_proto_package(
+    deps = [
+        "//envoy/extensions/dynamic_modules/v3:pkg",
+        "@com_github_cncf_xds//udpa/annotations:pkg",
+        "@com_github_cncf_xds//xds/annotations/v3:pkg",
+    ],
+)

api/envoy/extensions/filters/http/dynamic_modules/v3/dynamic_modules.proto

@@ -0,0 +1,45 @@
+syntax = "proto3";
+
+package envoy.extensions.filters.http.dynamic_modules.v3;
+
+import "envoy/extensions/dynamic_modules/v3/dynamic_modules.proto";
+
+import "xds/annotations/v3/status.proto";
+
+import "udpa/annotations/status.proto";
+
+option java_package = "io.envoyproxy.envoy.extensions.filters.http.dynamic_modules.v3";
+option java_outer_classname = "DynamicModulesProto";
+option java_multiple_files = true;
+option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/http/dynamic_modules/v3;dynamic_modulesv3";
+option (udpa.annotations.file_status).package_version_status = ACTIVE;
+option (xds.annotations.v3.file_status).work_in_progress = true;
+
+// [#protodoc-title: HTTP filter for dynamic modules]
+
+// Configuration of the HTTP filter for dynamic modules. This filter allows loading shared object files
+// that can be loaded via dlopen by the HTTP filter.
+//
+// A module can be loaded by multiple HTTP filters, hence the program can be structured in a way that
+// the module is loaded only once and shared across multiple filters providing multiple functionalities.
+//
+// Currently, the implementation is work in progress and not usable.
+message DynamicModuleFilter {
+  // Specifies the shared-object level configuration.
+  envoy.extensions.dynamic_modules.v3.DynamicModuleConfig dynamic_module_config = 1;
+
+  // The name for this filter configuration. This can be used to distinguish between different filter implementations
+  // inside a dynamic module. For example, a module can have completely different filter implementations.
+  // At the start up of a filter chain, this name is passed to the module's HTTP filter initialization function.
+  // That way the module can decide which in-module filter implementation to use based on the name.
+  string filter_name = 2;
+
+  // The configuration for the filter chosen by filter_name. This is passed to the module's HTTP filter initialization function.
+  // Together with the filter_name, the module can decide which in-module filter implementation to use and
+  // fine-tune the behavior of the filter.
+  //
+  // For example, if a module has two filter implementations, one for logging and one for header manipulation,
+  // filter_name is used to choose either logging or header manipulation. The filter_config can be used to
+  // configure the logging level or the header manipulation behavior.
+  string filter_config = 3;
+}

api/versioning/BUILD

@@ -89,6 +89,7 @@ proto_library(
         "//envoy/extensions/compression/zstd/compressor/v3:pkg",
         "//envoy/extensions/compression/zstd/decompressor/v3:pkg",
         "//envoy/extensions/config/validators/minimum_clusters/v3:pkg",
+        "//envoy/extensions/dynamic_modules/v3:pkg",
         "//envoy/extensions/early_data/v3:pkg",
         "//envoy/extensions/filters/common/dependency/v3:pkg",
         "//envoy/extensions/filters/common/fault/v3:pkg",
@@ -113,6 +114,7 @@ proto_library(
         "//envoy/extensions/filters/http/custom_response/v3:pkg",
         "//envoy/extensions/filters/http/decompressor/v3:pkg",
         "//envoy/extensions/filters/http/dynamic_forward_proxy/v3:pkg",
+        "//envoy/extensions/filters/http/dynamic_modules/v3:pkg",
         "//envoy/extensions/filters/http/ext_authz/v3:pkg",
         "//envoy/extensions/filters/http/ext_proc/v3:pkg",
         "//envoy/extensions/filters/http/fault/v3:pkg",

docs/root/api-v3/common_messages/common_messages.rst

@@ -42,3 +42,4 @@ Common messages
   ../config/core/v3/udp_socket_config.proto
   ../extensions/filters/common/set_filter_state/v3/value.proto
   ../config/core/v3/socket_cmsg_headers.proto
+  ../extensions/dynamic_modules/v3/dynamic_modules.proto

source/extensions/filters/http/dynamic_modules/BUILD

@@ -0,0 +1,48 @@
+load(
+    "//bazel:envoy_build_system.bzl",
+    "envoy_cc_library",
+    "envoy_extension_package",
+)
+
+licenses(["notice"])  # Apache 2
+
+envoy_extension_package()
+
+envoy_cc_library(
+    name = "filter_config_lib",
+    srcs = ["filter_config.cc"],
+    hdrs = ["filter_config.h"],
+    deps = [
+        "//source/extensions/dynamic_modules:dynamic_modules_lib",
+        "//source/extensions/filters/http/common:pass_through_filter_lib",
+    ],
+)
+
+envoy_cc_library(
+    name = "filter_lib",
+    srcs = ["filter.cc"],
+    hdrs = ["filter.h"],
+    deps = [
+        ":filter_config_lib",
+        "//source/extensions/filters/http/common:pass_through_filter_lib",
+    ],
+)
+
+envoy_cc_library(
+    name = "factory_lib",
+    srcs = ["factory.cc"],
+    hdrs = ["factory.h"],
+    deps = [
+        ":filter_config_lib",
+        ":filter_lib",
+        "@envoy_api//envoy/extensions/filters/http/dynamic_modules/v3:pkg_cc_proto",
+    ],
+)
+
+envoy_cc_library(
+    name = "factory_registration",
+    srcs = ["factory_registration.cc"],
+    deps = [
+        ":factory_lib",
+    ],
+)

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

@@ -0,0 +1,43 @@
+#include "source/extensions/filters/http/dynamic_modules/factory.h"
+
+#include "source/extensions/filters/http/dynamic_modules/filter.h"
+#include "source/extensions/filters/http/dynamic_modules/filter_config.h"
+
+namespace Envoy {
+namespace Server {
+namespace Configuration {
+
+absl::StatusOr<Http::FilterFactoryCb> DynamicModuleConfigFactory::createFilterFactoryFromProto(
+    const Protobuf::Message& raw_config, const std::string&, FactoryContext& context) {
+
+  const auto proto_config = Envoy::MessageUtil::downcastAndValidate<const FilterConfig&>(
+      raw_config, context.messageValidationVisitor());
+
+  const auto& module_config = proto_config.dynamic_module_config();
+  // TODO(mathetake): add support for other data source.
+  if (!module_config.object_file().has_filename()) {
+    return absl::InvalidArgumentError(
+        "Only filename is supported as a data source of dynamic module object file");
+  }
+  const auto dynamic_module = Extensions::DynamicModules::newDynamicModule(
+      module_config.object_file().filename(), module_config.do_not_close());
+  if (!dynamic_module.ok()) {
+    return absl::InvalidArgumentError("Failed to load dynamic module: " +
+                                      std::string(dynamic_module.status().message()));
+  }
+  auto filter_config = std::make_shared<
+      Envoy::Extensions::DynamicModules::HttpFilters::DynamicModuleHttpFilterConfig>(
+      proto_config.filter_name(), proto_config.filter_config(), dynamic_module.value());
+
+  return [filter_config](Http::FilterChainFactoryCallbacks& callbacks) -> void {
+    auto filter =
+        std::make_shared<Envoy::Extensions::DynamicModules::HttpFilters::DynamicModuleHttpFilter>(
+            filter_config);
+    callbacks.addStreamDecoderFilter(filter);
+    callbacks.addStreamEncoderFilter(filter);
+  };
+}
+
+} // namespace Configuration
+} // namespace Server
+} // namespace Envoy

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

@@ -0,0 +1,30 @@
+#pragma once
+
+#include "envoy/extensions/filters/http/dynamic_modules/v3/dynamic_modules.pb.h"
+#include "envoy/extensions/filters/http/dynamic_modules/v3/dynamic_modules.pb.validate.h"
+#include "envoy/server/filter_config.h"
+
+#include "source/extensions/dynamic_modules/dynamic_modules.h"
+
+namespace Envoy {
+namespace Server {
+namespace Configuration {
+
+using FilterConfig = envoy::extensions::filters::http::dynamic_modules::v3::DynamicModuleFilter;
+
+class DynamicModuleConfigFactory : public NamedHttpFilterConfigFactory {
+public:
+  absl::StatusOr<Http::FilterFactoryCb>
+  createFilterFactoryFromProto(const Protobuf::Message& raw_config, const std::string&,
+                               FactoryContext& context) override;
+
+  ProtobufTypes::MessagePtr createEmptyConfigProto() override {
+    return ProtobufTypes::MessagePtr{new FilterConfig()};
+  }
+
+  std::string name() const override { return "envoy.extensions.filters.http.dynamic_modules"; }
+};
+
+} // namespace Configuration
+} // namespace Server
+} // namespace Envoy

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

@@ -0,0 +1,16 @@
+#pragma once
+
+#include "envoy/registry/registry.h"
+#include "envoy/server/filter_config.h"
+
+#include "source/extensions/filters/http/dynamic_modules/factory.h"
+
+namespace Envoy {
+namespace Server {
+namespace Configuration {
+
+REGISTER_FACTORY(DynamicModuleConfigFactory, NamedHttpFilterConfigFactory);
+
+} // namespace Configuration
+} // namespace Server
+} // namespace Envoy

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

@@ -0,0 +1,57 @@
+#include "source/extensions/filters/http/dynamic_modules/filter.h"
+
+#include "envoy/server/filter_config.h"
+
+namespace Envoy {
+namespace Extensions {
+namespace DynamicModules {
+namespace HttpFilters {
+
+void DynamicModuleHttpFilter::onStreamComplete() {}
+
+void DynamicModuleHttpFilter::onDestroy(){};
+
+FilterHeadersStatus DynamicModuleHttpFilter::decodeHeaders(RequestHeaderMap&, bool) {
+  return FilterHeadersStatus::Continue;
+};
+
+FilterDataStatus DynamicModuleHttpFilter::decodeData(Buffer::Instance&, bool) {
+  return FilterDataStatus::Continue;
+};
+
+FilterTrailersStatus DynamicModuleHttpFilter::decodeTrailers(RequestTrailerMap&) {
+  return FilterTrailersStatus::Continue;
+}
+
+FilterMetadataStatus DynamicModuleHttpFilter::decodeMetadata(MetadataMap&) {
+  return FilterMetadataStatus::Continue;
+}
+
+void DynamicModuleHttpFilter::decodeComplete() {}
+
+Filter1xxHeadersStatus DynamicModuleHttpFilter::encode1xxHeaders(ResponseHeaderMap&) {
+  return Filter1xxHeadersStatus::Continue;
+}
+
+FilterHeadersStatus DynamicModuleHttpFilter::encodeHeaders(ResponseHeaderMap&, bool) {
+  return FilterHeadersStatus::Continue;
+};
+
+FilterDataStatus DynamicModuleHttpFilter::encodeData(Buffer::Instance&, bool) {
+  return FilterDataStatus::Continue;
+};
+
+FilterTrailersStatus DynamicModuleHttpFilter::encodeTrailers(ResponseTrailerMap&) {
+  return FilterTrailersStatus::Continue;
+};
+
+FilterMetadataStatus DynamicModuleHttpFilter::encodeMetadata(MetadataMap&) {
+  return FilterMetadataStatus::Continue;
+}
+
+void DynamicModuleHttpFilter::encodeComplete(){};
+
+} // namespace HttpFilters
+} // namespace DynamicModules
+} // namespace Extensions
+} // namespace Envoy