syntax = "proto3";

package envoy.extensions.filters.http.dynamic_modules.v3;

import "envoy/extensions/dynamic_modules/v3/dynamic_modules.proto";

import "google/protobuf/any.proto";

import "envoy/annotations/deprecation.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;

// [#protodoc-title: Dynamic Modules HTTP Filter]
// [#extension: envoy.filters.http.dynamic_modules]

// Configuration for the Dynamic Modules HTTP filter. This filter allows loading shared object files
// that can be loaded via ``dlopen`` to extend the HTTP filter chain.
//
// A module can be loaded by multiple HTTP filters; the module is loaded only once and shared across
// multiple filters.
//
// A dynamic module HTTP filter can opt into being a terminal filter with no upstream by setting
// :ref:`terminal_filter
// <envoy_v3_api_field_extensions.filters.http.dynamic_modules.v3.DynamicModuleFilter.terminal_filter>`
// to ``true``. A terminal dynamic module can use ``send_`` ABI methods to send response headers,
// body, and trailers to the downstream.
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.
  //
  // ``google.protobuf.Struct`` is serialized as JSON before passing it to the plugin.
  // ``google.protobuf.BytesValue`` and ``google.protobuf.StringValue`` are passed directly without
  // the wrapper.
  //
  // .. code-block:: yaml
  //
  //  # Passing in a string
  //  filter_config:
  //    "@type": "type.googleapis.com/google.protobuf.StringValue"
  //    value: hello
  //
  //  # Passing in raw bytes
  //  filter_config:
  //    "@type": "type.googleapis.com/google.protobuf.BytesValue"
  //    value: aGVsbG8= # echo -n "hello" | base64
  //
  google.protobuf.Any filter_config = 3;

  // If ``true``, the dynamic module is a terminal filter to use without an upstream.
  //
  // The dynamic module is responsible for creating and sending the response to downstream.
  //
  // Defaults to ``false``.
  bool terminal_filter = 4;
}

// Configuration of the HTTP per-route filter for dynamic modules.
message DynamicModuleFilterPerRoute {
  // 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 ``per_route_config_name`` to the dynamic module's
  // HTTP per-route 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.
  //
  // .. note::
  //   This is deprecated in favor of ``filter_name``. Please use ``filter_name`` instead of
  //   ``per_route_config_name`` to specify the name for the filter implementation.
  //   If both ``per_route_config_name`` and ``filter_name`` are specified, Envoy uses
  //   ``filter_name`` and ignores ``per_route_config_name``.
  //
  string per_route_config_name = 2
      [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];

  // 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 per-route 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 = 4;

  // The configuration for the filter chosen by ``filter_name``.
  //
  // This is passed to the module's HTTP per-route 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 on a specific route.
  //
  // 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.
  //
  // ``google.protobuf.Struct`` is serialized as JSON before passing it to the plugin.
  // ``google.protobuf.BytesValue`` and ``google.protobuf.StringValue`` are passed directly without
  // the wrapper.
  //
  // .. code-block:: yaml
  //
  //  # Passing in a string
  //  filter_config:
  //    "@type": "type.googleapis.com/google.protobuf.StringValue"
  //    value: hello
  //
  //  # Passing in raw bytes
  //  filter_config:
  //    "@type": "type.googleapis.com/google.protobuf.BytesValue"
  //    value: aGVsbG8= # echo -n "hello" | base64
  //
  google.protobuf.Any filter_config = 3;
}
