diff --git a/BUILD b/BUILD index 3d0fce98..23ba0b56 100644 --- a/BUILD +++ b/BUILD @@ -152,6 +152,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", @@ -176,6 +177,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", diff --git a/envoy/extensions/dynamic_modules/v3/BUILD b/envoy/extensions/dynamic_modules/v3/BUILD new file mode 100644 index 00000000..d49202b7 --- /dev/null +++ b/envoy/extensions/dynamic_modules/v3/BUILD @@ -0,0 +1,12 @@ +# 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 = [ + "@com_github_cncf_xds//udpa/annotations:pkg", + "@com_github_cncf_xds//xds/annotations/v3:pkg", + ], +) diff --git a/envoy/extensions/dynamic_modules/v3/dynamic_modules.proto b/envoy/extensions/dynamic_modules/v3/dynamic_modules.proto new file mode 100644 index 00000000..e74ee1ef --- /dev/null +++ b/envoy/extensions/dynamic_modules/v3/dynamic_modules.proto @@ -0,0 +1,49 @@ +syntax = "proto3"; + +package envoy.extensions.dynamic_modules.v3; + +import "xds/annotations/v3/status.proto"; + +import "udpa/annotations/status.proto"; +import "validate/validate.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 various Envoy extension points. Currently, only HTTP filter (envoy.filters.http.dynamic_modules) is supported. +// +// How a module is loaded is determined by the extension point that uses it. For example, the HTTP filter +// loads the module with dlopen when Envoy receives a configuration that references the module at load time. +// If loading the module fails, the configuration will be rejected. +// +// 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 `. +// 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. +message DynamicModuleConfig { + // The name of the dynamic module. The client is expected to have some configuration indicating where to search for the module. + // In Envoy, the search path can only be configured via the environment variable ``ENVOY_DYNAMIC_MODULES_SEARCH_PATH``. + // The actual search path is ``${ENVOY_DYNAMIC_MODULES_SEARCH_PATH}/lib${name}.so``. TODO: make the search path configurable via + // command line options. + string name = 1 [(validate.rules).string = {min_len: 1}]; + + // 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. + // A module is closed when no more references to it exist in the process. For example, + // no HTTP filters are using the module (e.g. after configuration update). + bool do_not_close = 3; +} diff --git a/envoy/extensions/filters/http/dynamic_modules/v3/BUILD b/envoy/extensions/filters/http/dynamic_modules/v3/BUILD new file mode 100644 index 00000000..dd0fbd76 --- /dev/null +++ b/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", + ], +) diff --git a/envoy/extensions/filters/http/dynamic_modules/v3/dynamic_modules.proto b/envoy/extensions/filters/http/dynamic_modules/v3/dynamic_modules.proto new file mode 100644 index 00000000..eb3b1e6a --- /dev/null +++ b/envoy/extensions/filters/http/dynamic_modules/v3/dynamic_modules.proto @@ -0,0 +1,46 @@ +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. + // When Envoy receives this configuration, it passes the filter_name to the dynamic module's HTTP filter config init function + // together with the filter_config. + // That way a module can decide which in-module filter implementation to use based on the name at load time. + 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; +} diff --git a/versioning/BUILD b/versioning/BUILD index 2b9add10..ea278d4e 100644 --- a/versioning/BUILD +++ b/versioning/BUILD @@ -90,6 +90,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", @@ -114,6 +115,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",