grpc 1.28.0 → 1.42.0

data/src/core/ext/filters/client_channel/http_connect_handshaker.cc

@@ -22,6 +22,8 @@
 
 #include <string.h>
 
+#include "absl/strings/str_cat.h"
+
 #include <grpc/slice_buffer.h>
 #include <grpc/support/alloc.h>
 #include <grpc/support/log.h>
@@ -30,7 +32,9 @@
 #include "src/core/ext/filters/client_channel/client_channel.h"
 #include "src/core/ext/filters/client_channel/resolver_registry.h"
 #include "src/core/lib/channel/channel_args.h"
+#include "src/core/lib/channel/handshaker.h"
 #include "src/core/lib/channel/handshaker_registry.h"
+#include "src/core/lib/config/core_configuration.h"
 #include "src/core/lib/gpr/string.h"
 #include "src/core/lib/gprpp/sync.h"
 #include "src/core/lib/http/format_request.h"
@@ -45,38 +49,39 @@ namespace {
 class HttpConnectHandshaker : public Handshaker {
  public:
   HttpConnectHandshaker();
-  void Shutdown(grpc_error* why) override;
+  void Shutdown(grpc_error_handle why) override;
   void DoHandshake(grpc_tcp_server_acceptor* acceptor,
                    grpc_closure* on_handshake_done,
                    HandshakerArgs* args) override;
   const char* name() const override { return "http_connect"; }
 
  private:
-  virtual ~HttpConnectHandshaker();
-  void CleanupArgsForFailureLocked();
-  void HandshakeFailedLocked(grpc_error* error);
-  static void OnWriteDone(void* arg, grpc_error* error);
-  static void OnReadDone(void* arg, grpc_error* error);
-  static void OnWriteDoneScheduler(void* arg, grpc_error* error);
-  static void OnReadDoneScheduler(void* arg, grpc_error* error);
+  ~HttpConnectHandshaker() override;
+  void CleanupArgsForFailureLocked() ABSL_EXCLUSIVE_LOCKS_REQUIRED(mu_);
+  void HandshakeFailedLocked(grpc_error_handle error)
+      ABSL_EXCLUSIVE_LOCKS_REQUIRED(mu_);
+  static void OnWriteDone(void* arg, grpc_error_handle error);
+  static void OnReadDone(void* arg, grpc_error_handle error);
+  static void OnWriteDoneScheduler(void* arg, grpc_error_handle error);
+  static void OnReadDoneScheduler(void* arg, grpc_error_handle error);
 
   Mutex mu_;
 
-  bool is_shutdown_ = false;
+  bool is_shutdown_ ABSL_GUARDED_BY(mu_) = false;
   // Endpoint and read buffer to destroy after a shutdown.
-  grpc_endpoint* endpoint_to_destroy_ = nullptr;
-  grpc_slice_buffer* read_buffer_to_destroy_ = nullptr;
+  grpc_endpoint* endpoint_to_destroy_ ABSL_GUARDED_BY(mu_) = nullptr;
+  grpc_slice_buffer* read_buffer_to_destroy_ ABSL_GUARDED_BY(mu_) = nullptr;
 
   // State saved while performing the handshake.
   HandshakerArgs* args_ = nullptr;
   grpc_closure* on_handshake_done_ = nullptr;
 
   // Objects for processing the HTTP CONNECT request and response.
-  grpc_slice_buffer write_buffer_;
-  grpc_closure request_done_closure_;
-  grpc_closure response_read_closure_;
-  grpc_http_parser http_parser_;
-  grpc_http_response http_response_;
+  grpc_slice_buffer write_buffer_ ABSL_GUARDED_BY(mu_);
+  grpc_closure request_done_closure_ ABSL_GUARDED_BY(mu_);
+  grpc_closure response_read_closure_ ABSL_GUARDED_BY(mu_);
+  grpc_http_parser http_parser_ ABSL_GUARDED_BY(mu_);
+  grpc_http_response http_response_ ABSL_GUARDED_BY(mu_);
 };
 
 HttpConnectHandshaker::~HttpConnectHandshaker() {
@@ -105,7 +110,7 @@ void HttpConnectHandshaker::CleanupArgsForFailureLocked() {
 
 // If the handshake failed or we're shutting down, clean up and invoke the
 // callback with the error.
-void HttpConnectHandshaker::HandshakeFailedLocked(grpc_error* error) {
+void HttpConnectHandshaker::HandshakeFailedLocked(grpc_error_handle error) {
   if (error == GRPC_ERROR_NONE) {
     // If we were shut down after an endpoint operation succeeded but
     // before the endpoint callback was invoked, we need to generate our
@@ -131,7 +136,8 @@ void HttpConnectHandshaker::HandshakeFailedLocked(grpc_error* error) {
 
 // This callback can be invoked inline while already holding onto the mutex. To
 // avoid deadlocks, schedule OnWriteDone on ExecCtx.
-void HttpConnectHandshaker::OnWriteDoneScheduler(void* arg, grpc_error* error) {
+void HttpConnectHandshaker::OnWriteDoneScheduler(void* arg,
+                                                 grpc_error_handle error) {
   auto* handshaker = static_cast<HttpConnectHandshaker*>(arg);
   grpc_core::ExecCtx::Run(
       DEBUG_LOCATION,
@@ -142,14 +148,14 @@ void HttpConnectHandshaker::OnWriteDoneScheduler(void* arg, grpc_error* error) {
 }
 
 // Callback invoked when finished writing HTTP CONNECT request.
-void HttpConnectHandshaker::OnWriteDone(void* arg, grpc_error* error) {
+void HttpConnectHandshaker::OnWriteDone(void* arg, grpc_error_handle error) {
   auto* handshaker = static_cast<HttpConnectHandshaker*>(arg);
   ReleasableMutexLock lock(&handshaker->mu_);
   if (error != GRPC_ERROR_NONE || handshaker->is_shutdown_) {
     // If the write failed or we're shutting down, clean up and invoke the
     // callback with the error.
     handshaker->HandshakeFailedLocked(GRPC_ERROR_REF(error));
-    lock.Unlock();
+    lock.Release();
     handshaker->Unref();
   } else {
     // Otherwise, read the response.
@@ -165,7 +171,8 @@ void HttpConnectHandshaker::OnWriteDone(void* arg, grpc_error* error) {
 
 // This callback can be invoked inline while already holding onto the mutex. To
 // avoid deadlocks, schedule OnReadDone on ExecCtx.
-void HttpConnectHandshaker::OnReadDoneScheduler(void* arg, grpc_error* error) {
+void HttpConnectHandshaker::OnReadDoneScheduler(void* arg,
+                                                grpc_error_handle error) {
   auto* handshaker = static_cast<HttpConnectHandshaker*>(arg);
   grpc_core::ExecCtx::Run(
       DEBUG_LOCATION,
@@ -176,7 +183,7 @@ void HttpConnectHandshaker::OnReadDoneScheduler(void* arg, grpc_error* error) {
 }
 
 // Callback invoked for reading HTTP CONNECT response.
-void HttpConnectHandshaker::OnReadDone(void* arg, grpc_error* error) {
+void HttpConnectHandshaker::OnReadDone(void* arg, grpc_error_handle error) {
   auto* handshaker = static_cast<HttpConnectHandshaker*>(arg);
   ReleasableMutexLock lock(&handshaker->mu_);
   if (error != GRPC_ERROR_NONE || handshaker->is_shutdown_) {
@@ -241,11 +248,9 @@ void HttpConnectHandshaker::OnReadDone(void* arg, grpc_error* error) {
   // Make sure we got a 2xx response.
   if (handshaker->http_response_.status < 200 ||
       handshaker->http_response_.status >= 300) {
-    char* msg;
-    gpr_asprintf(&msg, "HTTP proxy returned response code %d",
-                 handshaker->http_response_.status);
-    error = GRPC_ERROR_CREATE_FROM_COPIED_STRING(msg);
-    gpr_free(msg);
+    error = GRPC_ERROR_CREATE_FROM_CPP_STRING(
+        absl::StrCat("HTTP proxy returned response code ",
+                     handshaker->http_response_.status));
     handshaker->HandshakeFailedLocked(error);
     goto done;
   }
@@ -255,7 +260,7 @@ done:
   // Set shutdown to true so that subsequent calls to
   // http_connect_handshaker_shutdown() do nothing.
   handshaker->is_shutdown_ = true;
-  lock.Unlock();
+  lock.Release();
   handshaker->Unref();
 }
 
@@ -263,7 +268,7 @@ done:
 // Public handshaker methods
 //
 
-void HttpConnectHandshaker::Shutdown(grpc_error* why) {
+void HttpConnectHandshaker::Shutdown(grpc_error_handle why) {
   {
     MutexLock lock(&mu_);
     if (!is_shutdown_) {
@@ -324,15 +329,14 @@ void HttpConnectHandshaker::DoHandshake(grpc_tcp_server_acceptor* /*acceptor*/,
   args_ = args;
   on_handshake_done_ = on_handshake_done;
   // Log connection via proxy.
-  char* proxy_name = grpc_endpoint_get_peer(args->endpoint);
+  std::string proxy_name(grpc_endpoint_get_peer(args->endpoint));
   gpr_log(GPR_INFO, "Connecting to server %s via HTTP proxy %s", server_name,
-          proxy_name);
-  gpr_free(proxy_name);
+          proxy_name.c_str());
   // Construct HTTP CONNECT request.
   grpc_httpcli_request request;
   request.host = server_name;
   request.ssl_host_override = nullptr;
-  request.http.method = (char*)"CONNECT";
+  request.http.method = const_cast<char*>("CONNECT");
   request.http.path = server_name;
   request.http.version = GRPC_HTTP_HTTP10;  // Set by OnReadDone
   request.http.hdrs = headers;
@@ -379,11 +383,10 @@ class HttpConnectHandshakerFactory : public HandshakerFactory {
 
 }  // namespace
 
-}  // namespace grpc_core
-
-void grpc_http_connect_register_handshaker_factory() {
-  using namespace grpc_core;
-  HandshakerRegistry::RegisterHandshakerFactory(
-      true /* at_start */, HANDSHAKER_CLIENT,
-      absl::make_unique<HttpConnectHandshakerFactory>());
+void RegisterHttpConnectHandshaker(CoreConfiguration::Builder* builder) {
+  builder->handshaker_registry()->RegisterHandshakerFactory(
+      true /* at_start */, grpc_core::HANDSHAKER_CLIENT,
+      absl::make_unique<grpc_core::HttpConnectHandshakerFactory>());
 }
+
+}  // namespace grpc_core

data/src/core/ext/filters/client_channel/http_connect_handshaker.h

@@ -19,6 +19,10 @@
 #ifndef GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_HTTP_CONNECT_HANDSHAKER_H
 #define GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_HTTP_CONNECT_HANDSHAKER_H
 
+#include <grpc/support/port_platform.h>
+
+#include "src/core/lib/config/core_configuration.h"
+
 /// Channel arg indicating the server in HTTP CONNECT request (string).
 /// The presence of this arg triggers the use of HTTP CONNECT.
 #define GRPC_ARG_HTTP_CONNECT_SERVER "grpc.http_connect_server"
@@ -28,7 +32,11 @@
 /// separated by colons.
 #define GRPC_ARG_HTTP_CONNECT_HEADERS "grpc.http_connect_headers"
 
-/// Registers handshaker factory.
-void grpc_http_connect_register_handshaker_factory();
+namespace grpc_core {
+
+// Register the HTTP Connect handshaker into the configuration builder.
+void RegisterHttpConnectHandshaker(CoreConfiguration::Builder* builder);
+
+}  // namespace grpc_core
 
 #endif /* GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_HTTP_CONNECT_HANDSHAKER_H */

data/src/core/ext/filters/client_channel/http_proxy.cc

@@ -23,6 +23,9 @@
 #include <stdbool.h>
 #include <string.h>
 
+#include "absl/strings/str_cat.h"
+#include "absl/strings/strip.h"
+
 #include <grpc/support/alloc.h>
 #include <grpc/support/log.h>
 #include <grpc/support/string_util.h>
@@ -33,6 +36,7 @@
 #include "src/core/lib/gpr/env.h"
 #include "src/core/lib/gpr/string.h"
 #include "src/core/lib/gprpp/host_port.h"
+#include "src/core/lib/iomgr/resolve_address.h"
 #include "src/core/lib/slice/b64.h"
 #include "src/core/lib/uri/uri_parser.h"
 
@@ -45,33 +49,43 @@ namespace {
  * credentials if present in the 'http_proxy' env var, otherwise leaves it
  * unchanged. It is caller's responsibility to gpr_free user_cred.
  */
-char* GetHttpProxyServer(char** user_cred) {
+// TODO(hork): change this to return std::string
+char* GetHttpProxyServer(const grpc_channel_args* args, char** user_cred) {
   GPR_ASSERT(user_cred != nullptr);
-  grpc_uri* uri = nullptr;
+  absl::StatusOr<URI> uri;
   char* proxy_name = nullptr;
   char** authority_strs = nullptr;
   size_t authority_nstrs;
-  /* Prefer using 'grpc_proxy'. Fallback on 'http_proxy' if it is not set.
-   * Also prefer using 'https_proxy' with fallback on 'http_proxy'. The
-   * fallback behavior can be removed if there's a demand for it.
+  /* We check the following places to determine the HTTP proxy to use, stopping
+   * at the first one that is set:
+   * 1. GRPC_ARG_HTTP_PROXY channel arg
+   * 2. grpc_proxy environment variable
+   * 3. https_proxy environment variable
+   * 4. http_proxy environment variable
+   * If none of the above are set, then no HTTP proxy will be used.
    */
-  char* uri_str = gpr_getenv("grpc_proxy");
+  char* uri_str =
+      gpr_strdup(grpc_channel_args_find_string(args, GRPC_ARG_HTTP_PROXY));
+  if (uri_str == nullptr) uri_str = gpr_getenv("grpc_proxy");
   if (uri_str == nullptr) uri_str = gpr_getenv("https_proxy");
   if (uri_str == nullptr) uri_str = gpr_getenv("http_proxy");
   if (uri_str == nullptr) return nullptr;
   // an emtpy value means "don't use proxy"
   if (uri_str[0] == '\0') goto done;
-  uri = grpc_uri_parse(uri_str, false /* suppress_errors */);
-  if (uri == nullptr || uri->authority == nullptr) {
-    gpr_log(GPR_ERROR, "cannot parse value of 'http_proxy' env var");
+  uri = URI::Parse(uri_str);
+  if (!uri.ok() || uri->authority().empty()) {
+    gpr_log(GPR_ERROR, "cannot parse value of 'http_proxy' env var. Error: %s",
+            uri.status().ToString().c_str());
     goto done;
   }
-  if (strcmp(uri->scheme, "http") != 0) {
-    gpr_log(GPR_ERROR, "'%s' scheme not supported in proxy URI", uri->scheme);
+  if (uri->scheme() != "http") {
+    gpr_log(GPR_ERROR, "'%s' scheme not supported in proxy URI",
+            uri->scheme().c_str());
     goto done;
   }
   /* Split on '@' to separate user credentials from host */
-  gpr_string_split(uri->authority, "@", &authority_strs, &authority_nstrs);
+  gpr_string_split(uri->authority().c_str(), "@", &authority_strs,
+                   &authority_nstrs);
   GPR_ASSERT(authority_nstrs != 0); /* should have at least 1 string */
   if (authority_nstrs == 1) {
     /* User cred not present in authority */
@@ -91,10 +105,20 @@ char* GetHttpProxyServer(char** user_cred) {
   gpr_free(authority_strs);
 done:
   gpr_free(uri_str);
-  grpc_uri_destroy(uri);
   return proxy_name;
 }
 
+// Adds the default port if target does not contain a port.
+std::string MaybeAddDefaultPort(absl::string_view target) {
+  absl::string_view host;
+  absl::string_view port;
+  SplitHostPort(target, &host, &port);
+  if (port.empty()) {
+    return JoinHostPort(host, kDefaultSecurePortInt);
+  }
+  return std::string(target);
+}
+
 class HttpProxyMapper : public ProxyMapperInterface {
  public:
   bool MapName(const char* server_uri, const grpc_channel_args* args,
@@ -103,18 +127,19 @@ class HttpProxyMapper : public ProxyMapperInterface {
       return false;
     }
     char* user_cred = nullptr;
-    *name_to_resolve = GetHttpProxyServer(&user_cred);
+    *name_to_resolve = GetHttpProxyServer(args, &user_cred);
     if (*name_to_resolve == nullptr) return false;
     char* no_proxy_str = nullptr;
-    grpc_uri* uri = grpc_uri_parse(server_uri, false /* suppress_errors */);
-    if (uri == nullptr || uri->path[0] == '\0') {
+    std::string server_target;
+    absl::StatusOr<URI> uri = URI::Parse(server_uri);
+    if (!uri.ok() || uri->path().empty()) {
       gpr_log(GPR_ERROR,
               "'http_proxy' environment variable set, but cannot "
-              "parse server URI '%s' -- not using proxy",
-              server_uri);
+              "parse server URI '%s' -- not using proxy. Error: %s",
+              server_uri, uri.status().ToString().c_str());
       goto no_use_proxy;
     }
-    if (strcmp(uri->scheme, "unix") == 0) {
+    if (uri->scheme() == "unix") {
       gpr_log(GPR_INFO, "not using proxy for Unix domain socket '%s'",
               server_uri);
       goto no_use_proxy;
@@ -125,18 +150,17 @@ class HttpProxyMapper : public ProxyMapperInterface {
     if (no_proxy_str != nullptr) {
       static const char* NO_PROXY_SEPARATOR = ",";
       bool use_proxy = true;
-      grpc_core::UniquePtr<char> server_host;
-      grpc_core::UniquePtr<char> server_port;
-      if (!grpc_core::SplitHostPort(
-              uri->path[0] == '/' ? uri->path + 1 : uri->path, &server_host,
-              &server_port)) {
+      std::string server_host;
+      std::string server_port;
+      if (!SplitHostPort(absl::StripPrefix(uri->path(), "/"), &server_host,
+                         &server_port)) {
         gpr_log(GPR_INFO,
                 "unable to split host and port, not checking no_proxy list for "
                 "host '%s'",
                 server_uri);
         gpr_free(no_proxy_str);
       } else {
-        size_t uri_len = strlen(server_host.get());
+        size_t uri_len = server_host.size();
         char** no_proxy_hosts;
         size_t num_no_proxy_hosts;
         gpr_string_split(no_proxy_str, NO_PROXY_SEPARATOR, &no_proxy_hosts,
@@ -146,7 +170,8 @@ class HttpProxyMapper : public ProxyMapperInterface {
           size_t no_proxy_len = strlen(no_proxy_entry);
           if (no_proxy_len <= uri_len &&
               gpr_stricmp(no_proxy_entry,
-                          &(server_host.get()[uri_len - no_proxy_len])) == 0) {
+                          &(server_host.c_str()[uri_len - no_proxy_len])) ==
+                  0) {
             gpr_log(GPR_INFO, "not using proxy for host in no_proxy list '%s'",
                     server_uri);
             use_proxy = false;
@@ -161,29 +186,29 @@ class HttpProxyMapper : public ProxyMapperInterface {
         if (!use_proxy) goto no_use_proxy;
       }
     }
+    server_target =
+        MaybeAddDefaultPort(absl::StripPrefix(uri->path(), "/")).c_str();
     grpc_arg args_to_add[2];
     args_to_add[0] = grpc_channel_arg_string_create(
-        (char*)GRPC_ARG_HTTP_CONNECT_SERVER,
-        uri->path[0] == '/' ? uri->path + 1 : uri->path);
+        const_cast<char*>(GRPC_ARG_HTTP_CONNECT_SERVER),
+        const_cast<char*>(server_target.c_str()));
     if (user_cred != nullptr) {
       /* Use base64 encoding for user credentials as stated in RFC 7617 */
       char* encoded_user_cred =
           grpc_base64_encode(user_cred, strlen(user_cred), 0, 0);
-      char* header;
-      gpr_asprintf(&header, "Proxy-Authorization:Basic %s", encoded_user_cred);
+      std::string header =
+          absl::StrCat("Proxy-Authorization:Basic ", encoded_user_cred);
       gpr_free(encoded_user_cred);
       args_to_add[1] = grpc_channel_arg_string_create(
-          (char*)GRPC_ARG_HTTP_CONNECT_HEADERS, header);
+          const_cast<char*>(GRPC_ARG_HTTP_CONNECT_HEADERS),
+          const_cast<char*>(header.c_str()));
       *new_args = grpc_channel_args_copy_and_add(args, args_to_add, 2);
-      gpr_free(header);
     } else {
       *new_args = grpc_channel_args_copy_and_add(args, args_to_add, 1);
     }
-    grpc_uri_destroy(uri);
     gpr_free(user_cred);
     return true;
   no_use_proxy:
-    if (uri != nullptr) grpc_uri_destroy(uri);
     gpr_free(*name_to_resolve);
     *name_to_resolve = nullptr;
     gpr_free(user_cred);

data/src/core/ext/filters/client_channel/lb_policy/address_filtering.cc

@@ -0,0 +1,96 @@
+//
+// Copyright 2020 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 <grpc/support/port_platform.h>
+
+#include "src/core/ext/filters/client_channel/lb_policy/address_filtering.h"
+
+#include "absl/strings/str_cat.h"
+#include "absl/strings/str_join.h"
+
+#include "src/core/lib/channel/channel_args.h"
+
+#define GRPC_ARG_HIERARCHICAL_PATH "grpc.internal.address.hierarchical_path"
+
+namespace grpc_core {
+
+const char* kHierarchicalPathAttributeKey = "hierarchical_path";
+
+namespace {
+
+class HierarchicalPathAttribute : public ServerAddress::AttributeInterface {
+ public:
+  explicit HierarchicalPathAttribute(std::vector<std::string> path)
+      : path_(std::move(path)) {}
+
+  std::unique_ptr<AttributeInterface> Copy() const override {
+    return absl::make_unique<HierarchicalPathAttribute>(path_);
+  }
+
+  int Cmp(const AttributeInterface* other) const override {
+    const std::vector<std::string>& other_path =
+        static_cast<const HierarchicalPathAttribute*>(other)->path_;
+    for (size_t i = 0; i < path_.size(); ++i) {
+      if (other_path.size() == i) return 1;
+      int r = path_[i].compare(other_path[i]);
+      if (r != 0) return r;
+    }
+    if (other_path.size() > path_.size()) return -1;
+    return 0;
+  }
+
+  std::string ToString() const override {
+    return absl::StrCat("[", absl::StrJoin(path_, ", "), "]");
+  }
+
+  const std::vector<std::string>& path() const { return path_; }
+
+ private:
+  std::vector<std::string> path_;
+};
+
+}  // namespace
+
+std::unique_ptr<ServerAddress::AttributeInterface>
+MakeHierarchicalPathAttribute(std::vector<std::string> path) {
+  return absl::make_unique<HierarchicalPathAttribute>(std::move(path));
+}
+
+HierarchicalAddressMap MakeHierarchicalAddressMap(
+    const ServerAddressList& addresses) {
+  HierarchicalAddressMap result;
+  for (const ServerAddress& address : addresses) {
+    const HierarchicalPathAttribute* path_attribute =
+        static_cast<const HierarchicalPathAttribute*>(
+            address.GetAttribute(kHierarchicalPathAttributeKey));
+    if (path_attribute == nullptr) continue;
+    const std::vector<std::string>& path = path_attribute->path();
+    auto it = path.begin();
+    ServerAddressList& target_list = result[*it];
+    std::unique_ptr<HierarchicalPathAttribute> new_attribute;
+    ++it;
+    if (it != path.end()) {
+      std::vector<std::string> remaining_path(it, path.end());
+      new_attribute = absl::make_unique<HierarchicalPathAttribute>(
+          std::move(remaining_path));
+    }
+    target_list.emplace_back(address.WithAttribute(
+        kHierarchicalPathAttributeKey, std::move(new_attribute)));
+  }
+  return result;
+}
+
+}  // namespace grpc_core

data/src/core/ext/filters/client_channel/lb_policy/address_filtering.h

@@ -0,0 +1,101 @@
+//
+// Copyright 2020 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_CORE_EXT_FILTERS_CLIENT_CHANNEL_LB_POLICY_ADDRESS_FILTERING_H
+#define GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_LB_POLICY_ADDRESS_FILTERING_H
+
+#include <grpc/support/port_platform.h>
+
+#include <map>
+#include <string>
+#include <vector>
+
+#include "src/core/ext/filters/client_channel/server_address.h"
+
+// The resolver returns a flat list of addresses.  When a hierarchy of
+// LB policies is in use, each leaf of the hierarchy will need a
+// different subset of those addresses.  This library provides a
+// mechanism for determining which address is passed to which leaf
+// policy.
+//
+// Each address will have an associated path that indicates which child
+// it should be sent to at each level of the hierarchy to wind up at the
+// right leaf policy.  Each LB policy will look at the first element of
+// the path of each address to determine which child to send the address
+// to.  It will then remove that first element when passing the address
+// down to its child.
+//
+// For example, consider the following LB policy hierarchy:
+//
+// - priority
+//   - child0 (weighted_target)
+//     - localityA (round_robin)
+//     - localityB (round_robin)
+//   - child1 (weighted_target)
+//     - localityC (round_robin)
+//     - localityD (round_robin)
+//
+// Now consider the following addresses:
+// - 10.0.0.1:80 path=["child0", "localityA"]
+// - 10.0.0.2:80 path=["child0", "localityB"]
+// - 10.0.0.3:80 path=["child1", "localityC"]
+// - 10.0.0.4:80 path=["child1", "localityD"]
+//
+// The priority policy will split this up into two lists, one for each
+// of its children:
+// - child0:
+//   - 10.0.0.1:80 path=["localityA"]
+//   - 10.0.0.2:80 path=["localityB"]
+// - child1:
+//   - 10.0.0.3:80 path=["localityC"]
+//   - 10.0.0.4:80 path=["localityD"]
+//
+// The weighted_target policy for child0 will split its list up into two
+// lists, one for each of its children:
+// - localityA:
+//   - 10.0.0.1:80 path=[]
+// - localityB:
+//   - 10.0.0.2:80 path=[]
+//
+// Similarly, the weighted_target policy for child1 will split its list
+// up into two lists, one for each of its children:
+// - localityC:
+//   - 10.0.0.3:80 path=[]
+// - localityD:
+//   - 10.0.0.4:80 path=[]
+
+namespace grpc_core {
+
+// The attribute key to be used for hierarchical paths in ServerAddress.
+extern const char* kHierarchicalPathAttributeKey;
+
+// Constructs an address attribute containing the hierarchical path
+// to be associated with the address.
+std::unique_ptr<ServerAddress::AttributeInterface>
+MakeHierarchicalPathAttribute(std::vector<std::string> path);
+
+// A map from the next path element to the addresses that fall under
+// that path element.
+using HierarchicalAddressMap = std::map<std::string, ServerAddressList>;
+
+// Splits up the addresses into a separate list for each child.
+HierarchicalAddressMap MakeHierarchicalAddressMap(
+    const ServerAddressList& addresses);
+
+}  // namespace grpc_core
+
+#endif /* GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_LB_POLICY_ADDRESS_FILTERING_H \
+        */