wasm: add config setting to control StopIteration behavior (#40213)

Add PluginConfig.allow_on_headers_stop_iteration config field to control
the behavior of WasmFilter when plugin onRequestHeaders and
onResponseHeaders callbacks return a value of
FilterHeadersStatus::StopIteration.

If allow_on_headers_stop_iteration is false (the default), then in cases
where a Wasm plugin onRequestHeaders or onResponseHeaders callback
returns FilterHeadersStatus::StopIteration, WasmFilter will maintain its
current behavior of translating that response code to
FilterHeadersStatus::StopAllIterationAndWatermark.

If allow_on_headers_stop_iteration is true, then WasmFilter will avoid
any translation of FilterHeadersStatus::StopIteration, and will pass it
through to HCM unmodified, which allows Wasm plugins to inspect request
or response body data before deciding how to handle/transform request or
response headers.

For details, see [Envoy Wasm / Proxy-Wasm support for
FilterHeadersStatus::StopIteration](https://docs.google.com/document/d/1Whd1C0k-H2NHrPOmlAqqauFz6ObSTP017juJIYyciB0/edit?usp=sharing).
This PR implements [Option B: WasmFilter config
knob](https://docs.google.com/document/d/1Whd1C0k-H2NHrPOmlAqqauFz6ObSTP017juJIYyciB0/edit?tab=t.0#bookmark=id.5wxldlapsp54),
building on proxy-wasm/proxy-wasm-cpp-host#434.

Note that this config knob is a stopgap until upcoming v0.3.0 of the
Proxy-Wasm ABI adds more comprehensive support for StopIteration and
body buffering, per proxy-wasm/spec#63.

Additional Description:

This change updates the proxy-wasm-cpp-host dependency since it depends
on proxy-wasm/proxy-wasm-cpp-host#434, which was
recently merged there.



Signed-off-by: Michael Warres <mpw@google.com>

Author: mpwarres

api/envoy/extensions/wasm/v3/wasm.proto

@@ -6,6 +6,7 @@ import "envoy/config/core/v3/backoff.proto";
 import "envoy/config/core/v3/base.proto";
 
 import "google/protobuf/any.proto";
+import "google/protobuf/wrappers.proto";
 
 import "envoy/annotations/deprecation.proto";
 import "udpa/annotations/status.proto";
@@ -148,7 +149,7 @@ message EnvironmentVariables {
 }
 
 // Base Configuration for Wasm Plugins e.g. filters and services.
-// [#next-free-field: 9]
+// [#next-free-field: 10]
 message PluginConfig {
   // A unique name for a filters/services in a VM for use in identifying the filter/service if
   // multiple filters/services are handled by the same ``vm_id`` and ``root_id`` and for
@@ -192,6 +193,10 @@ message PluginConfig {
 
   // Configuration for restricting Proxy-Wasm capabilities available to modules.
   CapabilityRestrictionConfig capability_restriction_config = 6;
+
+  // Whether or not to allow plugin onRequestHeaders and onResponseHeaders callbacks to return
+  // FilterHeadersStatus::StopIteration.
+  google.protobuf.BoolValue allow_on_headers_stop_iteration = 9;
 }
 
 // WasmService is configured as a built-in ``envoy.wasm_service`` :ref:`WasmService

bazel/repository_locations.bzl

@@ -1404,8 +1404,8 @@ REPOSITORY_LOCATIONS_SPEC = dict(
         project_name = "WebAssembly for Proxies (C++ host implementation)",
         project_desc = "WebAssembly for Proxies (C++ host implementation)",
         project_url = "https://github.com/proxy-wasm/proxy-wasm-cpp-host",
-        version = "c4d7bb0fda912e24c64daf2aa749ec54cec99412",
-        sha256 = "3ea005e85d2b37685149c794c6876fd6de7f632f0ad49dc2b3cd580e7e7a5525",
+        version = "65bb78fbf8beb6d3670701d35711e691c0c4c4ce",
+        sha256 = "a73bb64561d631097d4c1fb1c3c64f41f107b6186544565db70e74358b5f3ec3",
         strip_prefix = "proxy-wasm-cpp-host-{version}",
         urls = ["https://github.com/proxy-wasm/proxy-wasm-cpp-host/archive/{version}.tar.gz"],
         use_category = ["dataplane_ext"],
@@ -1420,7 +1420,7 @@ REPOSITORY_LOCATIONS_SPEC = dict(
             "envoy.wasm.runtime.wamr",
             "envoy.wasm.runtime.wasmtime",
         ],
-        release_date = "2024-12-19",
+        release_date = "2025-07-13",
         cpe = "N/A",
         license = "Apache-2.0",
         license_url = "https://github.com/proxy-wasm/proxy-wasm-cpp-host/blob/{version}/LICENSE",

changelogs/current.yaml

@@ -375,5 +375,10 @@ new_features:
 - area: alts
   change: |
     Added environment variable-protected gRPC keepalive params to the ALTS handshaker client.
+- area: wasm
+  change: |
+    Added support for returning ``StopIteration`` from plugin ``onRequestHeader`` and ``onResponseHeader`` callbacks. See
+    :ref:`allow_on_headers_stop_iteration <envoy_v3_api_field_extensions.wasm.v3.PluginConfig.allow_on_headers_stop_iteration>`
+    for more details. By default, current behavior is maintained.
 
 deprecated:

source/extensions/common/wasm/context.cc

@@ -26,6 +26,7 @@
 #include "source/common/http/header_map_impl.h"
 #include "source/common/http/message_impl.h"
 #include "source/common/http/utility.h"
+#include "source/common/protobuf/utility.h"
 #include "source/common/tracing/http_tracer_impl.h"
 #include "source/extensions/common/wasm/plugin.h"
 #include "source/extensions/common/wasm/wasm.h"
@@ -70,6 +71,11 @@ namespace {
 // FilterState prefix for CelState values.
 constexpr absl::string_view CelStateKeyPrefix = "wasm.";
 
+// Default behavior for Proxy-Wasm 0.2.* ABI is to not support StopIteration as
+// a return value from onRequestHeaders() or onResponseHeaders() plugin
+// callbacks.
+constexpr bool DefaultAllowOnHeadersStopIteration = false;
+
 using HashPolicy = envoy::config::route::v3::RouteAction::HashPolicy;
 using CelState = Filters::Common::Expr::CelState;
 using CelStatePrototype = Filters::Common::Expr::CelStatePrototype;
@@ -162,13 +168,19 @@ Context::Context(Wasm* wasm, const PluginSharedPtr& plugin) : ContextBase(wasm,
   if (wasm != nullptr) {
     abi_version_ = wasm->abi_version_;
   }
-  root_local_info_ = &std::static_pointer_cast<Plugin>(plugin)->localInfo();
+  root_local_info_ = &this->plugin()->localInfo();
+  allow_on_headers_stop_iteration_ = PROTOBUF_GET_WRAPPED_OR_DEFAULT(
+      this->plugin()->wasmConfig().config(), allow_on_headers_stop_iteration,
+      DefaultAllowOnHeadersStopIteration);
 }
 Context::Context(Wasm* wasm, uint32_t root_context_id, PluginHandleSharedPtr plugin_handle)
     : ContextBase(wasm, root_context_id, plugin_handle), plugin_handle_(plugin_handle) {
   if (wasm != nullptr) {
     abi_version_ = wasm->abi_version_;
   }
+  allow_on_headers_stop_iteration_ = PROTOBUF_GET_WRAPPED_OR_DEFAULT(
+      plugin()->wasmConfig().config(), allow_on_headers_stop_iteration,
+      DefaultAllowOnHeadersStopIteration);
 }
 
 Wasm* Context::wasm() const { return static_cast<Wasm*>(wasm_); }

test/extensions/filters/http/wasm/wasm_filter_test.cc

@@ -291,6 +291,29 @@ TEST_P(WasmHttpFilterTest, HeadersStopAndContinue) {
   filter().onDestroy();
 }
 
+TEST_P(WasmHttpFilterTest, HeadersStopAndContinueAllowStopIteration) {
+  if (std::get<1>(GetParam()) == "rust") {
+    // TODO(PiotrSikora): This hand off is not currently possible in the Rust SDK.
+    return;
+  }
+  setAllowOnHeadersStopIteration(true);
+  setupTest("", "headers");
+  setupFilter();
+  EXPECT_CALL(encoder_callbacks_, streamInfo()).WillRepeatedly(ReturnRef(request_stream_info_));
+  EXPECT_CALL(filter(),
+              log_(spdlog::level::debug, Eq(absl::string_view("onRequestHeaders 2 headers"))));
+  EXPECT_CALL(filter(), log_(spdlog::level::info, Eq(absl::string_view("header path /"))));
+  EXPECT_CALL(filter(), log_(spdlog::level::warn, Eq(absl::string_view("onDone 2"))));
+  Http::TestRequestHeaderMapImpl request_headers{{":path", "/"}, {"server", "envoy-wasm-pause"}};
+  EXPECT_EQ(Http::FilterHeadersStatus::StopIteration,
+            filter().decodeHeaders(request_headers, true));
+  root_context_->onTick(0);
+  filter().clearRouteCache();
+  EXPECT_THAT(request_headers.get_("newheader"), Eq("newheadervalue"));
+  EXPECT_THAT(request_headers.get_("server"), Eq("envoy-wasm-continue"));
+  filter().onDestroy();
+}
+
 #if 0
 TEST_P(WasmHttpFilterTest, HeadersStopAndEndStream) {
   if (std::get<1>(GetParam()) == "rust") {

test/test_common/wasm_base.h

@@ -23,6 +23,7 @@
 #include "test/test_common/printers.h"
 #include "test/test_common/utility.h"
 
+#include "absl/types/optional.h"
 #include "gmock/gmock.h"
 #include "gtest/gtest.h"
 
@@ -65,6 +66,10 @@ template <typename Base = testing::Test> class WasmTestBase : public Base {
     *plugin_config.mutable_root_id() = root_id_;
     *plugin_config.mutable_name() = "plugin_name";
     plugin_config.set_fail_open(fail_open_);
+    if (allow_on_headers_stop_iteration_.has_value()) {
+      plugin_config.mutable_allow_on_headers_stop_iteration()->set_value(
+          *allow_on_headers_stop_iteration_);
+    }
     plugin_config.mutable_configuration()->set_value(plugin_configuration_);
     *plugin_config.mutable_vm_config()->mutable_environment_variables() = envs_;
 
@@ -122,6 +127,7 @@ template <typename Base = testing::Test> class WasmTestBase : public Base {
     plugin_configuration_ = plugin_configuration;
   }
   void setFailOpen(bool fail_open) { fail_open_ = fail_open; }
+  void setAllowOnHeadersStopIteration(bool allow) { allow_on_headers_stop_iteration_ = allow; }
   void setAllowedCapabilities(proxy_wasm::AllowedCapabilitiesMap allowed_capabilities) {
     allowed_capabilities_ = allowed_capabilities;
   }
@@ -131,6 +137,7 @@ template <typename Base = testing::Test> class WasmTestBase : public Base {
   std::string root_id_ = "";
   std::string vm_configuration_ = "";
   bool fail_open_ = false;
+  absl::optional<bool> allow_on_headers_stop_iteration_ = absl::nullopt;
   std::string plugin_configuration_ = "";
   proxy_wasm::AllowedCapabilitiesMap allowed_capabilities_ = {};
   envoy::extensions::wasm::v3::EnvironmentVariables envs_ = {};