docs/comments: to distinguish between upstream HTTP filters and upstr…

…eam network filters

Signed-off-by: wbpcode <wbphub@live.com>

api/envoy/config/cluster/v3/filter.proto

@@ -16,8 +16,8 @@ option java_multiple_files = true;
 option go_package = "github.com/envoyproxy/go-control-plane/envoy/config/cluster/v3;clusterv3";
 option (udpa.annotations.file_status).package_version_status = ACTIVE;
 
-// [#protodoc-title: Upstream filters]
-// Upstream filters apply to the connections to the upstream cluster hosts.
+// [#protodoc-title: Upstream network filters]
+// Upstream network filters apply to the connections to the upstream cluster hosts.
 
 message Filter {
   option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.cluster.Filter";
@@ -28,7 +28,7 @@ message Filter {
   // Filter specific configuration which depends on the filter being
   // instantiated. See the supported filters for further documentation.
   // Note that Envoy's :ref:`downstream network
-  // filters <config_network_filters>` are not valid upstream filters.
+  // filters <config_network_filters>` are not valid upstream network filters.
   // Only one of typed_config or config_discovery can be used.
   google.protobuf.Any typed_config = 2;
 

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

@@ -122,16 +122,16 @@ message Router {
   // .. note::
   //   Upstream HTTP filters are currently in alpha.
   //
-  // Optional HTTP filters for the upstream filter chain.
+  // Optional HTTP filters for the upstream HTTP filter chain.
   //
   // These filters will be applied for all requests that pass through the router.
   // They will also be applied to shadowed requests.
-  // Upstream filters cannot change route or cluster.
-  // Upstream filters specified on the cluster will override these filters.
+  // Upstream HTTP filters cannot change route or cluster.
+  // Upstream HTTP filters specified on the cluster will override these filters.
   //
-  // If using upstream filters, please be aware that local errors sent by
-  // upstream filters will not trigger retries, and local errors sent by
-  // upstream filters will count as a final response if hedging is configured.
+  // If using upstream HTTP filters, please be aware that local errors sent by
+  // upstream HTTP filters will not trigger retries, and local errors sent by
+  // upstream HTTP filters will count as a final response if hedging is configured.
   // [#extension-category: envoy.filters.http.upstream]
   repeated network.http_connection_manager.v3.HttpFilter upstream_http_filters = 8;
 }

api/envoy/extensions/upstreams/http/v3/http_protocol_options.proto

@@ -154,14 +154,14 @@ message HttpProtocolOptions {
   // .. note::
   //   Upstream HTTP filters are currently in alpha.
   //
-  // Optional HTTP filters for the upstream filter chain.
+  // Optional HTTP filters for the upstream HTTP filter chain.
   //
   // These filters will be applied for all HTTP streams which flow through this
-  // cluster. Unlike downstream filters, they will *not* be applied to terminated CONNECT requests.
+  // cluster. Unlike downstream HTTP filters, they will *not* be applied to terminated CONNECT requests.
   //
-  // If using upstream filters, please be aware that local errors sent by
-  // upstream filters will not trigger retries, and local errors sent by
-  // upstream filters will count as a final response if hedging is configured.
+  // If using upstream HTTP filters, please be aware that local errors sent by
+  // upstream HTTP filters will not trigger retries, and local errors sent by
+  // upstream HTTP filters will count as a final response if hedging is configured.
   // [#extension-category: envoy.filters.http.upstream]
   repeated filters.network.http_connection_manager.v3.HttpFilter http_filters = 6;
 

changelogs/1.24.0.yaml

@@ -99,7 +99,7 @@ minor_behavior_changes:
     changed the filter callback interfaces to make sure that downstream-only functionality is explicit.
 - area: http
   change: |
-    the upstream remote address is now available to downstream filters via the ``upstreamRemoteAddress`` function.
+    the upstream remote address is now available to downstream HTTP filters via the ``upstreamRemoteAddress`` function.
 - area: stats
   change: |
     Default tag extraction rules were changed for ``worker_id`` extraction. Previously, ``worker_`` was removed from the
@@ -193,13 +193,13 @@ new_features:
 - area: http
   change: |
     made the :ref:`admission control <envoy_v3_api_msg_extensions.filters.http.admission_control.v3.AdmissionControl>` work
-    as an upstream filter.
+    as an upstream HTTP filter.
 - area: http
   change: |
     added default-false ``envoy.reloadable_features.http1_use_balsa_parser`` for experimental BalsaParser.
 - area: http
   change: |
-    added ``envoy.reloadable_features.allow_upstream_filters`` for experimental upstream filters.
+    added ``envoy.reloadable_features.allow_upstream_filters`` for experimental upstream HTTP filters.
 - area: dns_resolver
   change: |
     added DNS stats for c-ares DNS resolver. Detailed documentation is available :ref:`here <arch_overview_dns_resolution>`.

changelogs/1.28.0.yaml

@@ -60,8 +60,8 @@ minor_behavior_changes:
 - area: alternate_protocols_cache_filter
   change: |
     Changed the alternate protocols cache filter to get the cache from cluster config rather than filter config.
-    This allows one downstream filter to be used with multiple clusters with different caches. This change can be reverted by
-    setting runtime guard ``envoy.reloadable_features.use_cluster_cache_for_alt_protocols_filter`` to ``false``.
+    This allows one downstream HTTP filter to be used with multiple clusters with different caches. This change can be
+    reverted by setting runtime guard ``envoy.reloadable_features.use_cluster_cache_for_alt_protocols_filter`` to ``false``.
 - area: ext_authz
   change: |
     Don't append the local address to ``x-forwarded-for`` header when sending an http (not gRPC) auth request.
@@ -130,8 +130,8 @@ minor_behavior_changes:
     Enable environment_variable in router direct response.
 - area: access_log
   change: |
-    When emitting grpc logs, only downstream filter state was used. Now, both downstream and upstream filter states will be tried
-    to find the keys configured in filter_state_objects_to_log.
+    When emitting grpc logs, only downstream HTTP filter state was used. Now, both downstream and upstream HTTP filter states
+    will be tried to find the keys configured in filter_state_objects_to_log.
 
 bug_fixes:
 - area: connection limit

docs/root/configuration/http/http_filters/cdn_loop_filter.rst

@@ -7,7 +7,7 @@ The CDN-Loop header filter participates in the cross-CDN loop detection protocol
 8586 <https://tools.ietf.org/html/rfc8586>`_. The CDN-Loop header filter performs two actions.
 First, the filter checks to see how many times a particular CDN identifier has appeared in the
 CDN-Loop header. Next, if the check passes, the filter then appends the CDN identifier to the
-CDN-Loop header and passes the request to the next upstream filter. If the check fails, the filter
+CDN-Loop header and passes the request to the next upstream HTTP filter. If the check fails, the filter
 stops processing on the request and returns an error response.
 
 RFC 8586 is particular in how the CDN-Loop header should be modified. As such:

docs/root/configuration/http/http_filters/header_mutation_filter.rst

@@ -18,7 +18,7 @@ The filter provides complete control over the position and order of the header m
 the route cache is cleared by a filter executing after the header mutation filter.
 
 
-In addition, this filter can be used as upstream filter and mutate the request headers after load balancing and host selection.
+In addition, this filter can be used as upstream HTTP filter and mutate the request headers after load balancing and host selection.
 
 
 Please note that as an encoder filter, this filter follows the standard rules of when it will execute in situations such as local replies - response

docs/root/configuration/http/http_filters/upstream_codec_filter.rst

@@ -3,7 +3,7 @@
 Upstream Codec
 ==============
 
-The upstream codec filter is the only supported terminal filter for upstream filters.
+The upstream codec filter is the only supported terminal filter for upstream HTTP filters.
 It is responsible for encoding headers/body/data to the upstream codec, and decoding
 headers/body/data from the upstream codec, as well as updating stats and timing metrics.
 

docs/root/intro/arch_overview/http/http_filters.rst

@@ -9,8 +9,8 @@ HTTP level filter stack within the connection manager.
 Filters can be written that operate on HTTP level messages without knowledge of the underlying physical
 protocol (HTTP/1.1, HTTP/2, etc.) or multiplexing capabilities.
 
-HTTP filters can be downstream filters, associated with a given listener and doing stream processing on each
-downstream request before routing, or upstream filters, associated with a given cluster and doing stream processing once per upstream request, after the router filter.
+HTTP filters can be downstream HTTP filters, associated with a given listener and doing stream processing on each
+downstream request before routing, or upstream HTTP filters, associated with a given cluster and doing stream processing once per upstream request, after the router filter.
 
 There are three types of HTTP level filters:
 
@@ -83,7 +83,7 @@ During downstream HTTP filter chain processing, when ``decodeHeaders()`` is invo
 connection manager performs route resolution and sets a *cached route* pointing to an upstream
 cluster.
 
-Downstream filters have the capability to directly mutate this *cached route* after route resolution, via the
+Downstream HTTP filters have the capability to directly mutate this *cached route* after route resolution, via the
 ``setRoute`` callback and :repo:`DelegatingRoute <source/common/router/delegating_route_impl.h>`
 mechanism.
 

docs/root/intro/arch_overview/upstream/upstream_filters.rst

@@ -5,8 +5,8 @@ Upstream network filters
 
 Upstream clusters provide an ability to inject network level (L3/L4)
 filters. It should be noted that a network filter needs to
-be registered in code as an upstream filter before usage. Currently,
-there are no upstream filters available in Envoy out of the box.
+be registered in code as an upstream network filter before usage. Currently,
+there are no upstream network filters available in Envoy out of the box.
 The filters apply to the connection to the upstream hosts, using the same API presented by listeners for
 the downstream connections. The write-callbacks are invoked for any chunk of
 data sent to the upstream host, and the read-callbacks are invoked for data

docs/root/intro/life_of_a_request.rst

@@ -200,7 +200,7 @@ A brief outline of the life cycle of a request and response using the example co
    capacity.
 8. For each stream an :ref:`Upstream HTTP filter <arch_overview_http_filters>` chain is created and
    runs. By default this only includes the CodecFilter, sending data to the appropriate codec, but if
-   the cluster is configured with an upstream filter chain, that filter chain will be created and run
+   the cluster is configured with an upstream HTTP filter chain, that filter chain will be created and run
    on each stream, which includes creating and running separate filter chains for retries and shadowed
    requests.
 9. The upstream endpoint connection's HTTP/2 codec multiplexes and frames the request’s stream with
@@ -210,7 +210,7 @@ A brief outline of the life cycle of a request and response using the example co
 11. The request, consisting of headers, and optional body and trailers, is proxied upstream, and the
     response is proxied downstream. The response passes through the HTTP filters in the
     :ref:`opposite order <arch_overview_http_filters_ordering>` from the request, starting at the
-    codec filter, traversing any upstream filters, then going through the router filter and passing
+    codec filter, traversing any upstream HTTP filters, then going through the router filter and passing
     through CustomFilter, before being sent downstream.
 12. When the response is complete, the stream is destroyed. Post-request processing will update
     stats, write to the access log and finalize trace spans.
@@ -461,13 +461,13 @@ stream allocated from the HTTP connection pool. It also is responsible for reque
 and affinity.
 
 The router filter is also responsible for the creation and running of the `Upstream HTTP filter <arch_overview_http_filters>`
-chain. By default, upstream filters will start running immediately after headers arrive at the router
+chain. By default, upstream HTTP filters will start running immediately after headers arrive at the router
 filter, however C++ filters can pause until the upstream connection is established if they need to
-inspect the upstream stream or connection. Upstream filter chains are by default configured via cluster
-configuration, so for example a shadowed request can have a separate upstream filter chain for the primary
-and shadowed clusters. Also as the upstream filter chain is upstream of the router filter, it is run per each
+inspect the upstream stream or connection. Upstream HTTP filter chains are by default configured via cluster
+configuration, so for example a shadowed request can have a separate upstream HTTP filter chain for the primary
+and shadowed clusters. Also as the upstream HTTP filter chain is upstream of the router filter, it is run per each
 retry attempt allowing header manipulation per retry and including information about the upstream stream and
-connection. Unlike downstream filters, upstream filters can not alter the route.
+connection. Unlike downstream HTTP filters, upstream HTTP filters can not alter the route.
 
 7. Load balancing
 ^^^^^^^^^^^^^^^^^

envoy/http/filter.h

@@ -202,7 +202,8 @@ enum class LocalErrorStatus {
   ContinueAndResetStream,
 };
 
-// These are events that upstream filters can register for, via the addUpstreamCallbacks function.
+// These are events that upstream HTTP filters can register for, via the addUpstreamCallbacks
+// function.
 class UpstreamCallbacks {
 public:
   virtual ~UpstreamCallbacks() = default;
@@ -214,7 +215,7 @@ class UpstreamCallbacks {
   virtual void onUpstreamConnectionEstablished() PURE;
 };
 
-// These are filter callbacks specific to upstream filters, accessible via
+// These are filter callbacks specific to upstream HTTP filters, accessible via
 // StreamFilterCallbacks::upstreamCallbacks()
 class UpstreamStreamFilterCallbacks {
 public:
@@ -426,14 +427,14 @@ class StreamFilterCallbacks {
   virtual Http1StreamEncoderOptionsOptRef http1StreamEncoderOptions() PURE;
 
   /**
-   * Return a handle to the upstream callbacks. This is valid for upstream filters, and nullopt for
-   * downstream filters.
+   * Return a handle to the upstream callbacks. This is valid for upstream HTTP filters, and nullopt
+   * for downstream HTTP filters.
    */
   virtual OptRef<UpstreamStreamFilterCallbacks> upstreamCallbacks() PURE;
 
   /**
-   * Return a handle to the downstream callbacks. This is valid for downstream filters, and nullopt
-   * for upstream filters.
+   * Return a handle to the downstream callbacks. This is valid for downstream HTTP filters, and
+   * nullopt for upstream HTTP filters.
    */
   virtual OptRef<DownstreamStreamFilterCallbacks> downstreamCallbacks() PURE;
 

envoy/network/connection.h

@@ -287,7 +287,7 @@ class Connection : public Event::DeferredDeletable,
   virtual bool connecting() const PURE;
 
   /**
-   * Write data to the connection. Will iterate through downstream filters with the buffer if any
+   * Write data to the connection. Will iterate through network filters with the buffer if any
    * are installed.
    * @param data Supplies the data to write to the connection.
    * @param end_stream If true, this indicates that this is the last write to the connection. If

envoy/server/factory_context.h

@@ -321,7 +321,7 @@ class ListenerFactoryContext : public virtual FactoryContext {
 using ProtocolOptionsFactoryContext = Server::Configuration::TransportSocketFactoryContext;
 
 /**
- * FactoryContext for upstream filters.
+ * FactoryContext for upstream HTTP filters.
  */
 class UpstreamFactoryContext {
 public:

source/common/http/filter_manager.cc

@@ -843,7 +843,8 @@ void FilterManager::decodeMetadata(ActiveStreamDecoderFilter* filter, MetadataMa
     if (state_.decoder_filter_chain_aborted_) {
       // If the decoder filter chain has been aborted, then either:
       // 1. This filter has sent a local reply from decode metadata.
-      // 2. This filter is the terminal http filter, and an upstream filter has sent a local reply.
+      // 2. This filter is the terminal http filter, and an upstream HTTP filter has sent a local
+      // reply.
       ASSERT((status == FilterMetadataStatus::StopIterationForLocalReply) ||
              (std::next(entry) == decoder_filters_.end()));
       executeLocalReplyIfPrepared();
@@ -1535,8 +1536,8 @@ bool FilterManager::createFilterChain() {
     }
   }
 
-  // This filter chain options is only used for the downstream filter chains for now. So, try to
-  // set valid initial route only when the downstream callbacks is available.
+  // This filter chain options is only used for the downstream HTTP filter chains for now. So, try
+  // to set valid initial route only when the downstream callbacks is available.
   FilterChainOptionsImpl options(
       filter_manager_callbacks_.downstreamCallbacks().has_value() ? streamInfo().route() : nullptr);
   filter_chain_factory_.createFilterChain(*this, false, options);

source/common/http/filter_manager.h

@@ -497,7 +497,7 @@ class FilterManagerCallbacks {
   virtual Http1StreamEncoderOptionsOptRef http1StreamEncoderOptions() PURE;
 
   /**
-   * Returns the UpstreamStreamFilterCallbacks for upstream filters.
+   * Returns the UpstreamStreamFilterCallbacks for upstream HTTP filters.
    */
   virtual OptRef<UpstreamStreamFilterCallbacks> upstreamCallbacks() { return {}; }
 
@@ -518,7 +518,7 @@ class FilterManagerCallbacks {
   virtual const ScopeTrackedObject& scope() PURE;
 
   /**
-   * Returns a handle to the downstream callbacks, if available.
+   * Returns the DownstreamStreamFilterCallbacks for downstream HTTP filters.
    */
   virtual OptRef<DownstreamStreamFilterCallbacks> downstreamCallbacks() { return {}; }
 };

source/common/router/router.h

@@ -245,7 +245,7 @@ class FilterConfig : Http::FilterChainFactory {
 
   bool createUpgradeFilterChain(absl::string_view, const UpgradeMap*,
                                 Http::FilterChainManager&) const override {
-    // Upgrade filter chains not yet supported for upstream filters.
+    // Upgrade filter chains not yet supported for upstream HTTP filters.
     return false;
   }
 

source/common/router/upstream_codec_filter.h

@@ -18,7 +18,7 @@
 namespace Envoy {
 namespace Router {
 
-// This is the last filter in the upstream filter chain.
+// This is the last filter in the upstream HTTP filter chain.
 // It takes request headers/body/data from the filter manager and encodes them to the upstream
 // codec. It also registers the CodecBridge with the upstream stream, and takes response
 // headers/body/data from the upstream stream and sends them to the filter manager.