#20276

Committed 11 May 2026 08:24AM UTC coverage: 88.821% (-0.02%) from 88.838%

Build # #20276

Build Type

push

github

Committed by

web-flow

Commit Message

Allow injecting bootstrap info into xDS Filter API for config parsing (#12724)

Extend the xDS Filter API to support injecting bootstrap information
into filters during configuration parsing. This allows filters to access
context information (e.g., allowed gRPC services) from the resource loading
layer during configuration validation and parsing.

- Update `Filter.Provider.parseFilterConfig` and
`parseFilterConfigOverride`
  to accept a `FilterContext` parameter.
- Introduce `BootstrapInfoGrpcServiceContextProvider` to encapsulate
  bootstrap info for context resolution.
- Update `XdsListenerResource` and `XdsRouteConfigureResource` to
  construct and pass `FilterContext` during configuration parsing.
- Update sub-filters (`FaultFilter`, `RbacFilter`,
`GcpAuthenticationFilter`,
  `RouterFilter`) to match the updated `FilterContext` signature.

Known Gaps & Limitations:
1. **MetricHolder**: Propagation of `MetricHolder` is not supported with
   this approach currently and is planned for support in a later phase.
2. **NameResolverRegistry**: Propagation is deferred for consistency.
While it could be passed from `XdsNameResolver` on the client side, there is
no equivalent mechanism on the server side. To ensure consistent
behavior, `DefaultRegistry` is used when validating schemes and creating channels.

Coverage Stats

36254 of 40817 relevant lines covered (88.82%)

0.89 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

92.0

/../xds/src/main/java/io/grpc/xds/Filter.java

/*
 * Copyright 2021 The 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.
 */

package io.grpc.xds;


import com.google.auto.value.AutoValue;
import com.google.common.base.MoreObjects;
import com.google.protobuf.Message;
import io.grpc.ClientInterceptor;
import io.grpc.ServerInterceptor;
import io.grpc.xds.client.Bootstrapper.BootstrapInfo;
import io.grpc.xds.client.Bootstrapper.ServerInfo;
import java.io.Closeable;
import java.util.Objects;
import java.util.concurrent.ScheduledExecutorService;
import javax.annotation.Nullable;

/**
 * Defines the parsing functionality of an HTTP filter.
 *
 * <p>A Filter may optionally implement either {@link Filter#buildClientInterceptor} or
 * {@link Filter#buildServerInterceptor} or both, and return true from corresponding
 * {@link Provider#isClientFilter()}, {@link Provider#isServerFilter()} to indicate that the filter
 * is capable of working on the client side or server side or both, respectively.
 */
interface Filter extends Closeable {

  /** Represents an opaque data structure holding configuration for a filter. */
  interface FilterConfig {
    String typeUrl();
  }

  /**
   * Common interface for filter providers.
   */
  interface Provider {
    /**
     * The proto message types supported by this filter. A filter will be registered by each of its
     * supported message types.
     */
    String[] typeUrls();

    /**
     * Whether the filter can be installed on the client side.
     *
     * <p>Returns true if the filter implements {@link Filter#buildClientInterceptor}.
     */
    default boolean isClientFilter() {
      return false;
    }

    /**
     * Whether the filter can be installed into xDS-enabled servers.
     *
     * <p>Returns true if the filter implements {@link Filter#buildServerInterceptor}.
     */
    default boolean isServerFilter() {
      return false;
    }

    /**
     * Creates a new instance of the filter.
     *
     * <p>Returns a filter instance registered with the same typeUrls as the provider,
     * capable of working with the same FilterConfig type returned by provider's parse functions.
     *
     * <p>For xDS gRPC clients, new filter instances are created per combination of:
     * <ol>
     *   <li><code>XdsNameResolver</code> instance,</li>
     *   <li>Filter name+typeUrl in HttpConnectionManager (HCM) http_filters.</li>
     * </ol>
     *
     * <p>For xDS-enabled gRPC servers, new filter instances are created per combination of:
     * <ol>
     *   <li>Server instance,</li>
     *   <li>FilterChain name,</li>
     *   <li>Filter name+typeUrl in FilterChain's HCM.http_filters.</li>
     * </ol>
     */
    Filter newInstance(String name);

    /**
     * Parses the top-level filter config from raw proto message. The message may be either a {@link
     * com.google.protobuf.Any} or a {@link com.google.protobuf.Struct}.
     */
    ConfigOrError<? extends FilterConfig> parseFilterConfig(
        Message rawProtoMessage, FilterConfigParseContext context);

    /**
     * Parses the per-filter override filter config from raw proto message. The message may be
     * either a {@link com.google.protobuf.Any} or a {@link com.google.protobuf.Struct}.
     */
    ConfigOrError<? extends FilterConfig> parseFilterConfigOverride(
        Message rawProtoMessage, FilterConfigParseContext context);
  }

  /** Uses the FilterConfigs produced above to produce an HTTP filter interceptor for clients. */
  @Nullable
  default ClientInterceptor buildClientInterceptor(
      FilterConfig config, @Nullable FilterConfig overrideConfig,
      ScheduledExecutorService scheduler) {
    return null;
  }

  /** Uses the FilterConfigs produced above to produce an HTTP filter interceptor for the server. */
  @Nullable
  default ServerInterceptor buildServerInterceptor(
      FilterConfig config, @Nullable FilterConfig overrideConfig) {
    return null;
  }

  /**
   * Releases filter resources like shared resources and remote connections.
   *
   * <p>See {@link Provider#newInstance()} for details on filter instance creation.
   */
  @Override
  default void close() {}

  /** Context carrying dynamic metadata for a filter. */
  @AutoValue
  abstract static class FilterConfigParseContext {
    abstract BootstrapInfo bootstrapInfo();

    abstract ServerInfo serverInfo();

    static Builder builder() {
      return new AutoValue_Filter_FilterConfigParseContext.Builder();
    }

    @AutoValue.Builder
    abstract static class Builder {
      abstract Builder bootstrapInfo(BootstrapInfo info);

      abstract Builder serverInfo(ServerInfo info);

      abstract FilterConfigParseContext build();
    }
  }

  /** Filter config with instance name. */
  final class NamedFilterConfig {
    // filter instance name
    final String name;
    final FilterConfig filterConfig;

    NamedFilterConfig(String name, FilterConfig filterConfig) {
      this.name = name;
      this.filterConfig = filterConfig;
    }

    String filterStateKey() {
      return name + "_" + filterConfig.typeUrl();
    }

    @Override
    public boolean equals(Object o) {
      if (this == o) {
        return true;
      }
      if (o == null || getClass() != o.getClass()) {
        return false;
      }
      NamedFilterConfig that = (NamedFilterConfig) o;
      return Objects.equals(name, that.name)
          && Objects.equals(filterConfig, that.filterConfig);
    }

    @Override
    public int hashCode() {
      return Objects.hash(name, filterConfig);
    }

    @Override
    public String toString() {
      return MoreObjects.toStringHelper(this)
          .add("name", name)
          .add("filterConfig", filterConfig)
          .toString();
    }
  }
}

1	/*
2	* Copyright 2021 The gRPC Authors
3	*
4	* Licensed under the Apache License, Version 2.0 (the "License");
5	* you may not use this file except in compliance with the License.
6	* You may obtain a copy of the License at
7	*
8	* http://www.apache.org/licenses/LICENSE-2.0
9	*
10	* Unless required by applicable law or agreed to in writing, software
11	* distributed under the License is distributed on an "AS IS" BASIS,
12	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13	* See the License for the specific language governing permissions and
14	* limitations under the License.
15	*/
16
17	package io.grpc.xds;
18
19
20	import com.google.auto.value.AutoValue;
21	import com.google.common.base.MoreObjects;
22	import com.google.protobuf.Message;
23	import io.grpc.ClientInterceptor;
24	import io.grpc.ServerInterceptor;
25	import io.grpc.xds.client.Bootstrapper.BootstrapInfo;
26	import io.grpc.xds.client.Bootstrapper.ServerInfo;
27	import java.io.Closeable;
28	import java.util.Objects;
29	import java.util.concurrent.ScheduledExecutorService;
30	import javax.annotation.Nullable;
31
32	/**
33	* Defines the parsing functionality of an HTTP filter.
34	*
35	* <p>A Filter may optionally implement either {@link Filter#buildClientInterceptor} or
36	* {@link Filter#buildServerInterceptor} or both, and return true from corresponding
37	* {@link Provider#isClientFilter()}, {@link Provider#isServerFilter()} to indicate that the filter
38	* is capable of working on the client side or server side or both, respectively.
39	*/
40	interface Filter extends Closeable {
41
42	/** Represents an opaque data structure holding configuration for a filter. */
43	interface FilterConfig {
44	String typeUrl();
45	}
46
47	/**
48	* Common interface for filter providers.
49	*/
50	interface Provider {
51	/**
52	* The proto message types supported by this filter. A filter will be registered by each of its
53	* supported message types.
54	*/
55	String[] typeUrls();
56
57	/**
58	* Whether the filter can be installed on the client side.
59	*
60	* <p>Returns true if the filter implements {@link Filter#buildClientInterceptor}.
61	*/
62	default boolean isClientFilter() {
63	return false;	1✔
64	}
65
66	/**
67	* Whether the filter can be installed into xDS-enabled servers.
68	*
69	* <p>Returns true if the filter implements {@link Filter#buildServerInterceptor}.
70	*/
71	default boolean isServerFilter() {
72	return false;	1✔
73	}
74
75	/**
76	* Creates a new instance of the filter.
77	*
78	* <p>Returns a filter instance registered with the same typeUrls as the provider,
79	* capable of working with the same FilterConfig type returned by provider's parse functions.
80	*
81	* <p>For xDS gRPC clients, new filter instances are created per combination of:
82	* <ol>
83	* <li><code>XdsNameResolver</code> instance,</li>
84	* <li>Filter name+typeUrl in HttpConnectionManager (HCM) http_filters.</li>
85	* </ol>
86	*
87	* <p>For xDS-enabled gRPC servers, new filter instances are created per combination of:
88	* <ol>
89	* <li>Server instance,</li>
90	* <li>FilterChain name,</li>
91	* <li>Filter name+typeUrl in FilterChain's HCM.http_filters.</li>
92	* </ol>
93	*/
94	Filter newInstance(String name);
95
96	/**
97	* Parses the top-level filter config from raw proto message. The message may be either a {@link
98	* com.google.protobuf.Any} or a {@link com.google.protobuf.Struct}.
99	*/
100	ConfigOrError<? extends FilterConfig> parseFilterConfig(
101	Message rawProtoMessage, FilterConfigParseContext context);
102
103	/**
104	* Parses the per-filter override filter config from raw proto message. The message may be
105	* either a {@link com.google.protobuf.Any} or a {@link com.google.protobuf.Struct}.
106	*/
107	ConfigOrError<? extends FilterConfig> parseFilterConfigOverride(
108	Message rawProtoMessage, FilterConfigParseContext context);
109	}
110
111	/** Uses the FilterConfigs produced above to produce an HTTP filter interceptor for clients. */
112	@Nullable
113	default ClientInterceptor buildClientInterceptor(
114	FilterConfig config, @Nullable FilterConfig overrideConfig,
115	ScheduledExecutorService scheduler) {
116	return null;	1✔
117	}
118
119	/** Uses the FilterConfigs produced above to produce an HTTP filter interceptor for the server. */
120	@Nullable
121	default ServerInterceptor buildServerInterceptor(
122	FilterConfig config, @Nullable FilterConfig overrideConfig) {
123	return null;	1✔
124	}
125
126	/**
127	* Releases filter resources like shared resources and remote connections.
128	*
129	* <p>See {@link Provider#newInstance()} for details on filter instance creation.
130	*/
131	@Override
132	default void close() {}	1✔
133
134	/** Context carrying dynamic metadata for a filter. */
135	@AutoValue
136	abstract static class FilterConfigParseContext {	1✔
137	abstract BootstrapInfo bootstrapInfo();
138
139	abstract ServerInfo serverInfo();
140
141	static Builder builder() {
142	return new AutoValue_Filter_FilterConfigParseContext.Builder();	1✔
143	}
144
145	@AutoValue.Builder
146	abstract static class Builder {	1✔
147	abstract Builder bootstrapInfo(BootstrapInfo info);
148
149	abstract Builder serverInfo(ServerInfo info);
150
151	abstract FilterConfigParseContext build();
152	}
153	}
154
155	/** Filter config with instance name. */
156	final class NamedFilterConfig {
157	// filter instance name
158	final String name;
159	final FilterConfig filterConfig;
160
161	NamedFilterConfig(String name, FilterConfig filterConfig) {	1✔
162	this.name = name;	1✔
163	this.filterConfig = filterConfig;	1✔
164	}	1✔
165
166	String filterStateKey() {
167	return name + "_" + filterConfig.typeUrl();	1✔
168	}
169
170	@Override
171	public boolean equals(Object o) {
172	if (this == o) {	1✔
173	return true;	×
174	}
175	if (o == null \|\| getClass() != o.getClass()) {	1✔
176	return false;	×
177	}
178	NamedFilterConfig that = (NamedFilterConfig) o;	1✔
179	return Objects.equals(name, that.name)	1✔
180	&& Objects.equals(filterConfig, that.filterConfig);	1✔
181	}
182
183	@Override
184	public int hashCode() {
185	return Objects.hash(name, filterConfig);	1✔
186	}
187
188	@Override
189	public String toString() {
190	return MoreObjects.toStringHelper(this)	1✔
191	.add("name", name)	1✔
192	.add("filterConfig", filterConfig)	1✔
193	.toString();	1✔
194	}
195	}
196	}

grpc / grpc-java / #20276

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous