grpc 1.83.1 → 1.84.0

data/src/core/filter/ext_proc/ext_proc_filter.cc

@@ -0,0 +1,224 @@
+//
+// Copyright 2026 gRPC authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+#include "src/core/filter/ext_proc/ext_proc_filter.h"
+
+#include <memory>
+#include <string>
+#include <utility>
+
+#include "src/core/call/call_spine.h"
+#include "src/core/call/metadata.h"
+#include "src/core/lib/channel/channel_args.h"
+#include "src/core/lib/channel/channel_fwd.h"
+#include "src/core/lib/channel/promise_based_filter.h"
+#include "src/core/lib/debug/trace_impl.h"
+#include "src/core/lib/promise/try_seq.h"
+#include "src/core/util/down_cast.h"
+#include "src/core/util/grpc_check.h"
+#include "src/core/util/match.h"
+#include "src/core/util/ref_counted_ptr.h"
+#include "src/core/util/string.h"
+#include "src/core/util/time.h"
+#include "src/core/xds/grpc/xds_server_grpc.h"
+#include "src/core/xds/xds_client/xds_bootstrap.h"
+#include "src/core/xds/xds_client/xds_transport.h"
+#include "absl/log/log.h"
+#include "absl/status/status.h"
+#include "absl/status/statusor.h"
+#include "absl/strings/str_join.h"
+
+namespace grpc_core {
+
+//
+// ExtProcFilter::Config
+//
+
+std::string ExtProcFilter::Config::ToString() const {
+  std::string result = "{";
+  bool is_first = true;
+  Match(
+      channel_info,
+      [&](const GrpcXdsServerTarget& target) {
+        StrAppend(result, "grpc_service=");
+        StrAppend(result, target.Key());
+        is_first = false;
+      },
+      [&](const RefCountedPtr<ExtProcChannel>& channel) {
+        if (channel != nullptr) {
+          StrAppend(result, "ext_proc_channel=");
+          StrAppend(result, channel->server()->Key());
+          is_first = false;
+        }
+      });
+  if (failure_mode_allow.value_or(false)) {
+    if (!is_first) StrAppend(result, ", ");
+    StrAppend(result, "failure_mode_allow=true");
+    is_first = false;
+  }
+  if (processing_mode.has_value()) {
+    if (!is_first) StrAppend(result, ", ");
+    StrAppend(result, "processing_mode=");
+    StrAppend(result, processing_mode->ToString());
+    is_first = false;
+  }
+  if (!request_attributes.empty()) {
+    if (!is_first) StrAppend(result, ", ");
+    StrAppend(result, "request_attributes=[");
+    StrAppend(result, absl::StrJoin(request_attributes, ", "));
+    StrAppend(result, "]");
+    is_first = false;
+  }
+  if (!response_attributes.empty()) {
+    if (!is_first) StrAppend(result, ", ");
+    StrAppend(result, "response_attributes=[");
+    StrAppend(result, absl::StrJoin(response_attributes, ", "));
+    StrAppend(result, "]");
+    is_first = false;
+  }
+  if (mutation_rules.has_value()) {
+    if (!is_first) StrAppend(result, ", ");
+    StrAppend(result, "mutation_rules=");
+    StrAppend(result, mutation_rules->ToString());
+    is_first = false;
+  }
+  if (!forwarding_allowed_headers.empty()) {
+    if (!is_first) StrAppend(result, ", ");
+    StrAppend(result, "forwarding_allowed_headers=[");
+    bool first_matcher = true;
+    for (const auto& matcher : forwarding_allowed_headers) {
+      if (!first_matcher) StrAppend(result, ", ");
+      StrAppend(result, matcher.ToString());
+      first_matcher = false;
+    }
+    StrAppend(result, "]");
+    is_first = false;
+  }
+  if (!forwarding_disallowed_headers.empty()) {
+    if (!is_first) StrAppend(result, ", ");
+    StrAppend(result, "forwarding_disallowed_headers=[");
+    bool first_matcher = true;
+    for (const auto& matcher : forwarding_disallowed_headers) {
+      if (!first_matcher) StrAppend(result, ", ");
+      StrAppend(result, matcher.ToString());
+      first_matcher = false;
+    }
+    StrAppend(result, "]");
+    is_first = false;
+  }
+  if (disable_immediate_response) {
+    if (!is_first) StrAppend(result, ", ");
+    StrAppend(result, "disable_immediate_response=true");
+    is_first = false;
+  }
+  if (observability_mode) {
+    if (!is_first) StrAppend(result, ", ");
+    StrAppend(result, "observability_mode=true");
+    is_first = false;
+  }
+  if (deferred_close_timeout != Duration::Zero()) {
+    if (!is_first) StrAppend(result, ", ");
+    StrAppend(result, "deferred_close_timeout=");
+    StrAppend(result, deferred_close_timeout.ToString());
+  }
+  StrAppend(result, "}");
+  return result;
+}
+
+bool ExtProcFilter::Config::Equals(const FilterConfig& other) const {
+  const auto& o = DownCast<const Config&>(other);
+  return channel_info == o.channel_info &&
+         failure_mode_allow == o.failure_mode_allow &&
+         processing_mode == o.processing_mode &&
+         request_attributes == o.request_attributes &&
+         response_attributes == o.response_attributes &&
+         mutation_rules == o.mutation_rules &&
+         forwarding_allowed_headers == o.forwarding_allowed_headers &&
+         forwarding_disallowed_headers == o.forwarding_disallowed_headers &&
+         disable_immediate_response == o.disable_immediate_response &&
+         observability_mode == o.observability_mode &&
+         deferred_close_timeout == o.deferred_close_timeout;
+}
+
+//
+// ExtProcFilter
+//
+
+const grpc_channel_filter ExtProcFilter::kFilterVtable = MakePromiseBasedFilter<
+    ExtProcFilter, FilterEndpoint::kClient,
+    kFilterExaminesServerInitialMetadata | kFilterExaminesOutboundMessages |
+        kFilterExaminesInboundMessages | kFilterExaminesCallContext>();
+
+absl::StatusOr<RefCountedPtr<ExtProcFilter>> ExtProcFilter::Create(
+    const ChannelArgs& args, ChannelFilter::Args filter_args) {
+  if (filter_args.config()->type() != Config::Type()) {
+    return absl::InternalError("ext_proc filter config has wrong type");
+  }
+  auto config = filter_args.config().TakeAsSubclass<const Config>();
+  return MakeRefCounted<ExtProcFilter>(args, std::move(config));
+}
+
+ExtProcFilter::ExtProcFilter(const ChannelArgs& args,
+                             RefCountedPtr<const Config> config)
+    : V3InterceptorToV2Bridge<ExtProcFilter>(args),
+      config_(std::move(config)) {}
+
+void ExtProcFilter::InterceptCall(UnstartedCallHandler unstarted_call_handler) {
+  CallHandler handler = Consume(std::move(unstarted_call_handler));
+  handler.SpawnGuarded(
+      "ext_proc_bypass",
+      [self = RefAsSubclass<ExtProcFilter>(), handler]() mutable {
+        GRPC_TRACE_LOG(ext_proc_filter, INFO)
+            << "ExtProc: Bypassing filter (stub implementation)";
+        return TrySeq(handler.PullClientInitialMetadata(),
+                      [self, handler](ClientMetadataHandle metadata) mutable {
+                        CallInitiator initiator = self->MakeChildCall(
+                            std::move(metadata), handler.arena()->Ref());
+                        handler.AddChildCall(initiator);
+                        ForwardCall(handler, initiator);
+                        return absl::OkStatus();
+                      });
+      });
+}
+
+//
+// ExtProcFilter::ExtProcChannel
+//
+
+ExtProcFilter::ExtProcChannel::ExtProcChannel(
+    std::shared_ptr<const XdsBootstrap::XdsServerTarget> server,
+    RefCountedPtr<XdsTransportFactory> transport_factory)
+    : server_(std::move(server)) {
+  GRPC_TRACE_LOG(ext_proc_filter, INFO)
+      << "creating channel " << this << " for server " << server_->server_uri();
+  absl::Status status;
+  transport_ = transport_factory->GetTransport(*server_, &status);
+  GRPC_CHECK(transport_ != nullptr);
+  // TODO(rishesh): Return an error if channel construction fails instead of
+  // just logging a message.
+  if (!status.ok()) {
+    LOG(ERROR) << "Error creating ext_proc channel to " << server_->server_uri()
+               << ": " << status;
+  }
+}
+
+ExtProcFilter::ExtProcChannel::~ExtProcChannel() {
+  GRPC_TRACE_LOG(ext_proc_filter, INFO)
+      << "destroying ext_proc channel " << this << " for server "
+      << server_->server_uri();
+}
+
+}  // namespace grpc_core

data/src/core/filter/ext_proc/ext_proc_filter.h

@@ -0,0 +1,155 @@
+//
+// Copyright 2026 gRPC authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+#ifndef GRPC_SRC_CORE_FILTER_EXT_PROC_EXT_PROC_FILTER_H
+#define GRPC_SRC_CORE_FILTER_EXT_PROC_EXT_PROC_FILTER_H
+
+#include <memory>
+#include <optional>
+#include <string>
+#include <variant>
+#include <vector>
+
+#include "src/core/filter/ext_proc/ext_proc_messages.h"
+#include "src/core/filter/filter_args.h"
+#include "src/core/lib/channel/channel_args.h"
+#include "src/core/lib/channel/promise_based_filter.h"
+#include "src/core/util/matchers.h"
+#include "src/core/util/ref_counted_ptr.h"
+#include "src/core/util/unique_type_name.h"
+#include "src/core/xds/grpc/blackboard.h"
+#include "src/core/xds/grpc/xds_common_types.h"
+#include "src/core/xds/grpc/xds_server_grpc.h"
+#include "src/core/xds/xds_client/xds_transport.h"
+
+namespace grpc_core {
+
+class ExtProcFilter final : public V3InterceptorToV2Bridge<ExtProcFilter> {
+ public:
+  class ExtProcChannel;
+
+  using ProcessingMode = ExtProcProcessingMode;
+
+  struct Config final : public FilterConfig {
+    static UniqueTypeName Type() {
+      return GRPC_UNIQUE_TYPE_NAME_HERE("ext_proc_filter_config");
+    }
+    UniqueTypeName type() const override { return Type(); }
+
+    bool Equals(const FilterConfig& other) const override;
+
+    std::string ToString() const override;
+
+    // The gRPC service configuration (target URI, credentials, timeout)
+    // used to establish the side-channel connection to the external processor
+    // server as described in gRFC A102.
+    // Or, a ref-counted handle to the persistent gRPC side-channel
+    // (ExtProcChannel) used to communicate with the external processing server
+    // across multiple data plane RPCs.
+    // Holds a null RefCountedPtr when neither is set (e.g. in an empty
+    // override config).
+    std::variant<RefCountedPtr<ExtProcChannel>, GrpcXdsServerTarget>
+        channel_info;
+    // If true, when an ext_proc stream fails or terminates with a non-OK
+    // status, the data plane RPC is allowed to continue without error if the
+    // filter is in observability mode or has not yet sent message bodies (body
+    // send mode is NONE). Defaults to false (failing the RPC with INTERNAL).
+    std::optional<bool> failure_mode_allow;
+    // Specifies which data plane events (request/response headers, body chunks,
+    // and trailers) should be forwarded to the external processing server. In
+    // gRPC, body chunks are sent in GRPC mode.
+    std::optional<ProcessingMode> processing_mode;
+    // List of request attribute names (e.g., "request.path", "request.method",
+    // "request.host") to extract from metadata and include in client request
+    // header events.
+    std::vector<std::string> request_attributes;
+    // List of response attribute names to extract from metadata and include in
+    // server response header events.
+    std::vector<std::string> response_attributes;
+    // Configuration specifying rules and restrictions for header mutations
+    // performed by the external processor (such as disallowed headers or rules
+    // for adding/removing headers).
+    std::optional<HeaderMutationRules> mutation_rules;
+    // List of string matchers defining the set of request/response headers and
+    // trailers allowed to be forwarded to the external processing server.
+    std::vector<StringMatcher> forwarding_allowed_headers;
+    // List of string matchers defining the set of request/response headers and
+    // trailers that must be excluded when sending events to the external
+    // processing server.
+    std::vector<StringMatcher> forwarding_disallowed_headers;
+    // If true, prevents the external processing server from sending an
+    // ImmediateResponse message to reject or terminate the data plane RPC
+    // prematurely.
+    bool disable_immediate_response;
+    // If true (observability mode as defined in gRFC A93), events are sent
+    // asynchronously without blocking data plane RPC traffic or waiting for
+    // response mutations from the external processor.
+    bool observability_mode;
+    // The maximum duration to wait for the external processor to close or drain
+    // its stream before forcibly closing the side-channel stream.
+    Duration deferred_close_timeout;
+
+    RefCountedPtr<ExtProcChannel> channel() const {
+      auto* channel = std::get_if<RefCountedPtr<ExtProcChannel>>(&channel_info);
+      if (channel == nullptr) return nullptr;
+      return *channel;
+    }
+  };
+
+  static const grpc_channel_filter kFilterVtable;
+
+  static absl::string_view TypeName() { return "ext_proc"; }
+
+  static absl::StatusOr<RefCountedPtr<ExtProcFilter>> Create(
+      const ChannelArgs& args, ChannelFilter::Args filter_args);
+
+  ExtProcFilter(const ChannelArgs& args, RefCountedPtr<const Config> config);
+
+  RefCountedPtr<const Config> config() const { return config_; }
+  RefCountedPtr<ExtProcChannel> channel() const { return config_->channel(); }
+
+  class ExtProcChannel final : public Blackboard::Entry {
+   public:
+    static UniqueTypeName Type() {
+      return GRPC_UNIQUE_TYPE_NAME_HERE("ext_proc_channel");
+    }
+    ExtProcChannel(std::shared_ptr<const XdsBootstrap::XdsServerTarget> server,
+                   RefCountedPtr<XdsTransportFactory> transport_factory);
+    ~ExtProcChannel() override;
+    std::shared_ptr<const XdsBootstrap::XdsServerTarget> server() const {
+      return server_;
+    }
+
+    RefCountedPtr<XdsTransportFactory::XdsTransport> transport() const {
+      return transport_;
+    }
+
+   private:
+    std::shared_ptr<const XdsBootstrap::XdsServerTarget> server_;
+    RefCountedPtr<XdsTransportFactory::XdsTransport> transport_;
+  };
+
+ private:
+  void Orphaned() override {}
+
+  void InterceptCall(UnstartedCallHandler unstarted_call_handler) override;
+
+  RefCountedPtr<const Config> config_;
+};
+
+}  // namespace grpc_core
+
+#endif  // GRPC_SRC_CORE_FILTER_EXT_PROC_EXT_PROC_FILTER_H