#20232

Committed 02 Apr 2026 11:39AM UTC coverage: 88.784% (+0.03%) from 88.755%

Build # #20232

Build Type

push

github

Committed by

web-flow

Commit Message

xds: Add configuration objects for ExtAuthz, GrpcService and Bootstrap changes for GrpcService (#12492)

This commit introduces configuration objects for the external
authorization (ExtAuthz) filter and the gRPC service and corresponding
translations from XDS proto and Bootstrap. These classes provide a
structured, immutable representation of the subset of the configuration
defined in the xDS protobuf messages.

This PR should mostly now (hopefully ) be compliant with
https://github.com/grpc/proposal/pull/510 but without
- CallCredentials (since I don't see A97) being implemented yet and
would prefer to do it in a followup , we return empty optional)
- TlsCredentials( since it's non trivial to construct a TLS credentials
object, we throw an exception)
- LocalCredentials(Java does't support these, we throw an exception)

The main new classes are:
- `ExtAuthzConfig`: Represents the configuration for the `ExtAuthz`
filter, including settings for the gRPC service, header mutation rules,
and other filter behaviors.
- `GrpcServiceConfig`: Represents the configuration for a gRPC service,
including the target URI, credentials, and other settings.
- `HeaderMutationRulesConfig`: Represents the configuration for header
mutation rules.
- `ChannelCredsConfig` and friends: To allow comparison between
credential configuration , to allow caching based on creds which'll be
needed in followup PRs for authz and proc.

The relevant sections of the spec are 
- GrpcService: https://github.com/grpc/proposal/pull/510
- ExtAuthz:
https://github.com/grpc/proposal/pull/481/files#diff-6bb76a24ad2fd8849f164244e68cd54eaR106-R190

This commit also includes parsers to create these configuration objects
from the corresponding protobuf messages, as well as unit tests for the
new classes.

Coverage Stats

35968 of 40512 relevant lines covered (88.78%)

0.89 hits per line

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

94.44

/../xds/src/main/java/io/grpc/xds/client/Bootstrapper.java

/*
 * Copyright 2019 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.client;

import static com.google.common.base.Preconditions.checkArgument;

import com.google.auto.value.AutoValue;
import com.google.common.annotations.VisibleForTesting;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;
import io.grpc.Internal;
import io.grpc.xds.client.EnvoyProtoData.Node;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import javax.annotation.Nullable;

/**
 * Loads configuration information to bootstrap gRPC's integration of xDS protocol.
 */
@Internal
public abstract class Bootstrapper {

  public static final String XDSTP_SCHEME = "xdstp:";

  /**
   * Returns system-loaded bootstrap configuration.
   */
  public abstract BootstrapInfo bootstrap() throws XdsInitializationException;

  /**
   * Returns bootstrap configuration given by the raw data in JSON format.
   */
  public BootstrapInfo bootstrap(Map<String, ?> rawData) throws XdsInitializationException {
    throw new UnsupportedOperationException();
  }

  /**
   * Data class containing xDS server information, such as server URI and channel credentials
   * to be used for communication.
   */
  @AutoValue
  @Internal
  public abstract static class ServerInfo {
    public abstract String target();

    public abstract Object implSpecificConfig();

    public abstract boolean ignoreResourceDeletion();

    public abstract boolean isTrustedXdsServer();

    public abstract boolean resourceTimerIsTransientError();

    public abstract boolean failOnDataErrors();

    @VisibleForTesting
    public static ServerInfo create(String target, @Nullable Object implSpecificConfig) {
      return new AutoValue_Bootstrapper_ServerInfo(target, implSpecificConfig,
          false, false, false, false);
    }

    @VisibleForTesting
    public static ServerInfo create(
        String target, Object implSpecificConfig,
        boolean ignoreResourceDeletion, boolean isTrustedXdsServer,
        boolean resourceTimerIsTransientError, boolean failOnDataErrors) {
      return new AutoValue_Bootstrapper_ServerInfo(target, implSpecificConfig,
          ignoreResourceDeletion, isTrustedXdsServer,
          resourceTimerIsTransientError, failOnDataErrors);
    }
  }

  /**
   * Data class containing Certificate provider information: the plugin-name and an opaque
   * Map that represents the config for that plugin.
   */
  @AutoValue
  @Internal
  public abstract static class CertificateProviderInfo {
    public abstract String pluginName();

    public abstract ImmutableMap<String, ?> config();

    @VisibleForTesting
    public static CertificateProviderInfo create(String pluginName, Map<String, ?> config) {
      return new AutoValue_Bootstrapper_CertificateProviderInfo(
          pluginName, ImmutableMap.copyOf(config));
    }
  }

  @AutoValue
  public abstract static class AuthorityInfo {

    /**
     * A template for the name of the Listener resource to subscribe to for a gRPC client
     * channel. Used only when the channel is created using an "xds:" URI with this authority
     * name.
     *
     * <p>The token "%s", if present in this string, will be replaced with %-encoded
     * service authority (i.e., the path part of the target URI used to create the gRPC channel).
     *
     * <p>Return value must start with {@code "xdstp://<authority_name>/"}.
     */
    public abstract String clientListenerResourceNameTemplate();

    /**
     * Ordered list of xDS servers to contact for this authority.
     *
     * <p>If the same server is listed in multiple authorities, the entries will be de-duped (i.e.,
     * resources for both authorities will be fetched on the same ADS stream).
     *
     * <p>Defaults to the top-level server list {@link BootstrapInfo#servers()}. Must not be empty.
     */
    public abstract ImmutableList<ServerInfo> xdsServers();

    public static AuthorityInfo create(
        String clientListenerResourceNameTemplate, List<ServerInfo> xdsServers) {
      checkArgument(!xdsServers.isEmpty(), "xdsServers must not be empty");
      return new AutoValue_Bootstrapper_AuthorityInfo(
          clientListenerResourceNameTemplate, ImmutableList.copyOf(xdsServers));
    }
  }

  /**
   * Data class containing the results of reading bootstrap.
   */
  @AutoValue
  @Internal
  public abstract static class BootstrapInfo {
    /** Returns the list of xDS servers to be connected to. Must not be empty. */
    public abstract ImmutableList<ServerInfo> servers();

    /** Returns the node identifier to be included in xDS requests. */
    public abstract Node node();

    /** Returns the cert-providers config map. */
    @Nullable
    public abstract ImmutableMap<String, CertificateProviderInfo> certProviders();

    /**
     * A template for the name of the Listener resource to subscribe to for a gRPC server.
     *
     * <p>If starts with "xdstp:", will be interpreted as a new-style name, in which case the
     * authority of the URI will be used to select the relevant configuration in the
     * "authorities" map. The token "%s", if present in this string, will be replaced with
     * the IP and port on which the server is listening. If the template starts with "xdstp:",
     * the replaced string will be %-encoded.
     *
     * <p>There is no default; if unset, xDS-based server creation fails.
     */
    @Nullable
    public abstract String serverListenerResourceNameTemplate();

    /**
     * A template for the name of the Listener resource to subscribe to for a gRPC client channel.
     * Used only when the channel is created with an "xds:" URI with no authority.
     *
     * <p>If starts with "xdstp:", will be interpreted as a new-style name, in which case the
     * authority of the URI will be used to select the relevant configuration in the "authorities"
     * map.
     *
     * <p>The token "%s", if present in this string, will be replaced with the service authority
     * (i.e., the path part of the target URI used to create the gRPC channel). If the template
     * starts with "xdstp:", the replaced string will be %-encoded.
     *
     * <p>Defaults to {@code "%s"}.
     */
    public abstract String clientDefaultListenerResourceNameTemplate();

    /**
     * A map of authority name to corresponding configuration.
     *
     * <p>This is used in the following cases:
     *
     * <ul>
     * <li>A gRPC client channel is created using an "xds:" URI that includes  an
     * authority.</li>
     *
     * <li>A gRPC client channel is created using an "xds:" URI with no authority,
     * but the "client_default_listener_resource_name_template" field above turns it into an
     * "xdstp:" URI.</li>
     *
     * <li>A gRPC server is created and the "server_listener_resource_name_template" field is an
     * "xdstp:" URI.</li>
     * </ul>
     *
     * <p>In any of those cases, it is an error if the specified authority is not present in this
     * map.
     *
     * <p>Defaults to an empty map.
     */
    public abstract ImmutableMap<String, AuthorityInfo> authorities();

    /**
     * Parsed configuration for implementation-specific extensions.
     * Returns an opaque object containing the parsed configuration.
     */
    public abstract Optional<Object> implSpecificObject();

    @VisibleForTesting
    public static Builder builder() {
      return new AutoValue_Bootstrapper_BootstrapInfo.Builder()
          .clientDefaultListenerResourceNameTemplate("%s")
          .authorities(ImmutableMap.<String, AuthorityInfo>of())
          .implSpecificObject(Optional.empty());
    }

    @AutoValue.Builder
    @VisibleForTesting
    public abstract static class Builder {

      public abstract Builder servers(List<ServerInfo> servers);

      public abstract Builder node(Node node);

      public abstract Builder certProviders(@Nullable Map<String,
          CertificateProviderInfo> certProviders);

      public abstract Builder serverListenerResourceNameTemplate(
          @Nullable String serverListenerResourceNameTemplate);

      public abstract Builder clientDefaultListenerResourceNameTemplate(
          String clientDefaultListenerResourceNameTemplate);

      public abstract Builder authorities(Map<String, AuthorityInfo> authorities);

      public abstract Builder implSpecificObject(Optional<Object> implSpecificObject);

      public abstract BootstrapInfo build();
    }
  }

}

1	/*
2	* Copyright 2019 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.client;
18
19	import static com.google.common.base.Preconditions.checkArgument;
20
21	import com.google.auto.value.AutoValue;
22	import com.google.common.annotations.VisibleForTesting;
23	import com.google.common.collect.ImmutableList;
24	import com.google.common.collect.ImmutableMap;
25	import io.grpc.Internal;
26	import io.grpc.xds.client.EnvoyProtoData.Node;
27	import java.util.List;
28	import java.util.Map;
29	import java.util.Optional;
30	import javax.annotation.Nullable;
31
32	/**
33	* Loads configuration information to bootstrap gRPC's integration of xDS protocol.
34	*/
35	@Internal
36	public abstract class Bootstrapper {	1✔
37
38	public static final String XDSTP_SCHEME = "xdstp:";
39
40	/**
41	* Returns system-loaded bootstrap configuration.
42	*/
43	public abstract BootstrapInfo bootstrap() throws XdsInitializationException;
44
45	/**
46	* Returns bootstrap configuration given by the raw data in JSON format.
47	*/
48	public BootstrapInfo bootstrap(Map<String, ?> rawData) throws XdsInitializationException {
49	throw new UnsupportedOperationException();	×
50	}
51
52	/**
53	* Data class containing xDS server information, such as server URI and channel credentials
54	* to be used for communication.
55	*/
56	@AutoValue
57	@Internal
58	public abstract static class ServerInfo {	1✔
59	public abstract String target();
60
61	public abstract Object implSpecificConfig();
62
63	public abstract boolean ignoreResourceDeletion();
64
65	public abstract boolean isTrustedXdsServer();
66
67	public abstract boolean resourceTimerIsTransientError();
68
69	public abstract boolean failOnDataErrors();
70
71	@VisibleForTesting
72	public static ServerInfo create(String target, @Nullable Object implSpecificConfig) {
73	return new AutoValue_Bootstrapper_ServerInfo(target, implSpecificConfig,	1✔
74	false, false, false, false);
75	}
76
77	@VisibleForTesting
78	public static ServerInfo create(
79	String target, Object implSpecificConfig,
80	boolean ignoreResourceDeletion, boolean isTrustedXdsServer,
81	boolean resourceTimerIsTransientError, boolean failOnDataErrors) {
82	return new AutoValue_Bootstrapper_ServerInfo(target, implSpecificConfig,	1✔
83	ignoreResourceDeletion, isTrustedXdsServer,
84	resourceTimerIsTransientError, failOnDataErrors);
85	}
86	}
87
88	/**
89	* Data class containing Certificate provider information: the plugin-name and an opaque
90	* Map that represents the config for that plugin.
91	*/
92	@AutoValue
93	@Internal
94	public abstract static class CertificateProviderInfo {	1✔
95	public abstract String pluginName();
96
97	public abstract ImmutableMap<String, ?> config();
98
99	@VisibleForTesting
100	public static CertificateProviderInfo create(String pluginName, Map<String, ?> config) {
101	return new AutoValue_Bootstrapper_CertificateProviderInfo(	1✔
102	pluginName, ImmutableMap.copyOf(config));	1✔
103	}
104	}
105
106	@AutoValue
107	public abstract static class AuthorityInfo {	1✔
108
109	/**
110	* A template for the name of the Listener resource to subscribe to for a gRPC client
111	* channel. Used only when the channel is created using an "xds:" URI with this authority
112	* name.
113	*
114	* <p>The token "%s", if present in this string, will be replaced with %-encoded
115	* service authority (i.e., the path part of the target URI used to create the gRPC channel).
116	*
117	* <p>Return value must start with {@code "xdstp://<authority_name>/"}.
118	*/
119	public abstract String clientListenerResourceNameTemplate();
120
121	/**
122	* Ordered list of xDS servers to contact for this authority.
123	*
124	* <p>If the same server is listed in multiple authorities, the entries will be de-duped (i.e.,
125	* resources for both authorities will be fetched on the same ADS stream).
126	*
127	* <p>Defaults to the top-level server list {@link BootstrapInfo#servers()}. Must not be empty.
128	*/
129	public abstract ImmutableList<ServerInfo> xdsServers();
130
131	public static AuthorityInfo create(
132	String clientListenerResourceNameTemplate, List<ServerInfo> xdsServers) {
133	checkArgument(!xdsServers.isEmpty(), "xdsServers must not be empty");	1✔
134	return new AutoValue_Bootstrapper_AuthorityInfo(	1✔
135	clientListenerResourceNameTemplate, ImmutableList.copyOf(xdsServers));	1✔
136	}
137	}
138
139	/**
140	* Data class containing the results of reading bootstrap.
141	*/
142	@AutoValue
143	@Internal
144	public abstract static class BootstrapInfo {	1✔
145	/** Returns the list of xDS servers to be connected to. Must not be empty. */
146	public abstract ImmutableList<ServerInfo> servers();
147
148	/** Returns the node identifier to be included in xDS requests. */
149	public abstract Node node();
150
151	/** Returns the cert-providers config map. */
152	@Nullable
153	public abstract ImmutableMap<String, CertificateProviderInfo> certProviders();
154
155	/**
156	* A template for the name of the Listener resource to subscribe to for a gRPC server.
157	*
158	* <p>If starts with "xdstp:", will be interpreted as a new-style name, in which case the
159	* authority of the URI will be used to select the relevant configuration in the
160	* "authorities" map. The token "%s", if present in this string, will be replaced with
161	* the IP and port on which the server is listening. If the template starts with "xdstp:",
162	* the replaced string will be %-encoded.
163	*
164	* <p>There is no default; if unset, xDS-based server creation fails.
165	*/
166	@Nullable
167	public abstract String serverListenerResourceNameTemplate();
168
169	/**
170	* A template for the name of the Listener resource to subscribe to for a gRPC client channel.
171	* Used only when the channel is created with an "xds:" URI with no authority.
172	*
173	* <p>If starts with "xdstp:", will be interpreted as a new-style name, in which case the
174	* authority of the URI will be used to select the relevant configuration in the "authorities"
175	* map.
176	*
177	* <p>The token "%s", if present in this string, will be replaced with the service authority
178	* (i.e., the path part of the target URI used to create the gRPC channel). If the template
179	* starts with "xdstp:", the replaced string will be %-encoded.
180	*
181	* <p>Defaults to {@code "%s"}.
182	*/
183	public abstract String clientDefaultListenerResourceNameTemplate();
184
185	/**
186	* A map of authority name to corresponding configuration.
187	*
188	* <p>This is used in the following cases:
189	*
190	* <ul>
191	* <li>A gRPC client channel is created using an "xds:" URI that includes an
192	* authority.</li>
193	*
194	* <li>A gRPC client channel is created using an "xds:" URI with no authority,
195	* but the "client_default_listener_resource_name_template" field above turns it into an
196	* "xdstp:" URI.</li>
197	*
198	* <li>A gRPC server is created and the "server_listener_resource_name_template" field is an
199	* "xdstp:" URI.</li>
200	* </ul>
201	*
202	* <p>In any of those cases, it is an error if the specified authority is not present in this
203	* map.
204	*
205	* <p>Defaults to an empty map.
206	*/
207	public abstract ImmutableMap<String, AuthorityInfo> authorities();
208
209	/**
210	* Parsed configuration for implementation-specific extensions.
211	* Returns an opaque object containing the parsed configuration.
212	*/
213	public abstract Optional<Object> implSpecificObject();
214
215	@VisibleForTesting
216	public static Builder builder() {
217	return new AutoValue_Bootstrapper_BootstrapInfo.Builder()	1✔
218	.clientDefaultListenerResourceNameTemplate("%s")	1✔
219	.authorities(ImmutableMap.<String, AuthorityInfo>of())	1✔
220	.implSpecificObject(Optional.empty());	1✔
221	}
222
223	@AutoValue.Builder
224	@VisibleForTesting
225	public abstract static class Builder {	1✔
226
227	public abstract Builder servers(List<ServerInfo> servers);
228
229	public abstract Builder node(Node node);
230
231	public abstract Builder certProviders(@Nullable Map<String,
232	CertificateProviderInfo> certProviders);
233
234	public abstract Builder serverListenerResourceNameTemplate(
235	@Nullable String serverListenerResourceNameTemplate);
236
237	public abstract Builder clientDefaultListenerResourceNameTemplate(
238	String clientDefaultListenerResourceNameTemplate);
239
240	public abstract Builder authorities(Map<String, AuthorityInfo> authorities);
241
242	public abstract Builder implSpecificObject(Optional<Object> implSpecificObject);
243
244	public abstract BootstrapInfo build();
245	}
246	}
247
248	}

grpc / grpc-java / #20232

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