#19717

/*
 * 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.common.base.MoreObjects;
import com.google.protobuf.Message;
import io.grpc.ClientInterceptor;
import io.grpc.ServerInterceptor;
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();

    /**
     * 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);

    /**
     * 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);
  }

  /** 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() {}

  /** 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	import com.google.common.base.MoreObjects;
20	import com.google.protobuf.Message;
21	import io.grpc.ClientInterceptor;
22	import io.grpc.ServerInterceptor;
23	import java.io.Closeable;
24	import java.util.Objects;
25	import java.util.concurrent.ScheduledExecutorService;
26	import javax.annotation.Nullable;
27
28	/**
29	* Defines the parsing functionality of an HTTP filter.
30	*
31	* <p>A Filter may optionally implement either {@link Filter#buildClientInterceptor} or
32	* {@link Filter#buildServerInterceptor} or both, and return true from corresponding
33	* {@link Provider#isClientFilter()}, {@link Provider#isServerFilter()} to indicate that the filter
34	* is capable of working on the client side or server side or both, respectively.
35	*/
36	interface Filter extends Closeable {
37
38	/** Represents an opaque data structure holding configuration for a filter. */
39	interface FilterConfig {
40	String typeUrl();
41	}
42
43	/**
44	* Common interface for filter providers.
45	*/
46	interface Provider {
47	/**
48	* The proto message types supported by this filter. A filter will be registered by each of its
49	* supported message types.
50	*/
51	String[] typeUrls();
52
53	/**
54	* Whether the filter can be installed on the client side.
55	*
56	* <p>Returns true if the filter implements {@link Filter#buildClientInterceptor}.
57	*/
58	default boolean isClientFilter() {
59	return false;	1✔
60	}
61
62	/**
63	* Whether the filter can be installed into xDS-enabled servers.
64	*
65	* <p>Returns true if the filter implements {@link Filter#buildServerInterceptor}.
66	*/
67	default boolean isServerFilter() {
68	return false;	1✔
69	}
70
71	/**
72	* Creates a new instance of the filter.
73	*
74	* <p>Returns a filter instance registered with the same typeUrls as the provider,
75	* capable of working with the same FilterConfig type returned by provider's parse functions.
76	*
77	* <p>For xDS gRPC clients, new filter instances are created per combination of:
78	* <ol>
79	* <li><code>XdsNameResolver</code> instance,</li>
80	* <li>Filter name+typeUrl in HttpConnectionManager (HCM) http_filters.</li>
81	* </ol>
82	*
83	* <p>For xDS-enabled gRPC servers, new filter instances are created per combination of:
84	* <ol>
85	* <li>Server instance,</li>
86	* <li>FilterChain name,</li>
87	* <li>Filter name+typeUrl in FilterChain's HCM.http_filters.</li>
88	* </ol>
89	*/
90	Filter newInstance();
91
92	/**
93	* Parses the top-level filter config from raw proto message. The message may be either a {@link
94	* com.google.protobuf.Any} or a {@link com.google.protobuf.Struct}.
95	*/
96	ConfigOrError<? extends FilterConfig> parseFilterConfig(Message rawProtoMessage);
97
98	/**
99	* Parses the per-filter override filter config from raw proto message. The message may be
100	* either a {@link com.google.protobuf.Any} or a {@link com.google.protobuf.Struct}.
101	*/
102	ConfigOrError<? extends FilterConfig> parseFilterConfigOverride(Message rawProtoMessage);
103	}
104
105	/** Uses the FilterConfigs produced above to produce an HTTP filter interceptor for clients. */
106	@Nullable
107	default ClientInterceptor buildClientInterceptor(
108	FilterConfig config, @Nullable FilterConfig overrideConfig,
109	ScheduledExecutorService scheduler) {
110	return null;	1✔
111	}
112
113	/** Uses the FilterConfigs produced above to produce an HTTP filter interceptor for the server. */
114	@Nullable
115	default ServerInterceptor buildServerInterceptor(
116	FilterConfig config, @Nullable FilterConfig overrideConfig) {
117	return null;	1✔
118	}
119
120	/**
121	* Releases filter resources like shared resources and remote connections.
122	*
123	* <p>See {@link Provider#newInstance()} for details on filter instance creation.
124	*/
125	@Override
126	default void close() {}	1✔
127
128	/** Filter config with instance name. */
129	final class NamedFilterConfig {
130	// filter instance name
131	final String name;
132	final FilterConfig filterConfig;
133
134	NamedFilterConfig(String name, FilterConfig filterConfig) {	1✔
135	this.name = name;	1✔
136	this.filterConfig = filterConfig;	1✔
137	}	1✔
138
139	String filterStateKey() {
140	return name + "_" + filterConfig.typeUrl();	1✔
141	}
142
143	@Override
144	public boolean equals(Object o) {
145	if (this == o) {	1✔
146	return true;	×
147	}
148	if (o == null \|\| getClass() != o.getClass()) {	1✔
149	return false;	×
150	}
151	NamedFilterConfig that = (NamedFilterConfig) o;	1✔
152	return Objects.equals(name, that.name)	1✔
153	&& Objects.equals(filterConfig, that.filterConfig);	1✔
154	}
155
156	@Override
157	public int hashCode() {
158	return Objects.hash(name, filterConfig);	1✔
159	}
160
161	@Override
162	public String toString() {
163	return MoreObjects.toStringHelper(this)	1✔
164	.add("name", name)	1✔
165	.add("filterConfig", filterConfig)	1✔
166	.toString();	1✔
167	}
168	}
169	}

grpc / grpc-java / #19717

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