grpc 1.30.2

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

@@ -0,0 +1,34 @@
+/*
+ *
+ * Copyright 2016 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_HTTP_CONNECT_HANDSHAKER_H
+#define GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_HTTP_CONNECT_HANDSHAKER_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"
+
+/// Channel arg indicating HTTP CONNECT headers (string).
+/// Multiple headers are separated by newlines.  Key/value pairs are
+/// separated by colons.
+#define GRPC_ARG_HTTP_CONNECT_HEADERS "grpc.http_connect_headers"
+
+/// Registers handshaker factory.
+void grpc_http_connect_register_handshaker_factory();
+
+#endif /* GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_HTTP_CONNECT_HANDSHAKER_H */

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

@@ -0,0 +1,216 @@
+/*
+ *
+ * Copyright 2016 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/http_proxy.h"
+
+#include <stdbool.h>
+#include <string.h>
+
+#include <grpc/support/alloc.h>
+#include <grpc/support/log.h>
+#include <grpc/support/string_util.h>
+
+#include "src/core/ext/filters/client_channel/http_connect_handshaker.h"
+#include "src/core/ext/filters/client_channel/proxy_mapper_registry.h"
+#include "src/core/lib/channel/channel_args.h"
+#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/slice/b64.h"
+#include "src/core/lib/uri/uri_parser.h"
+
+namespace grpc_core {
+namespace {
+
+/**
+ * Parses the 'https_proxy' env var (fallback on 'http_proxy') and returns the
+ * proxy hostname to resolve or nullptr on error. Also sets 'user_cred' to user
+ * 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(const grpc_channel_args* args, char** user_cred) {
+  GPR_ASSERT(user_cred != nullptr);
+  grpc_uri* uri = nullptr;
+  char* proxy_name = nullptr;
+  char** authority_strs = nullptr;
+  size_t authority_nstrs;
+  /* 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_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");
+    goto done;
+  }
+  if (strcmp(uri->scheme, "http") != 0) {
+    gpr_log(GPR_ERROR, "'%s' scheme not supported in proxy URI", uri->scheme);
+    goto done;
+  }
+  /* Split on '@' to separate user credentials from host */
+  gpr_string_split(uri->authority, "@", &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 */
+    proxy_name = authority_strs[0];
+  } else if (authority_nstrs == 2) {
+    /* User cred found */
+    *user_cred = authority_strs[0];
+    proxy_name = authority_strs[1];
+    gpr_log(GPR_DEBUG, "userinfo found in proxy URI");
+  } else {
+    /* Bad authority */
+    for (size_t i = 0; i < authority_nstrs; i++) {
+      gpr_free(authority_strs[i]);
+    }
+    proxy_name = nullptr;
+  }
+  gpr_free(authority_strs);
+done:
+  gpr_free(uri_str);
+  grpc_uri_destroy(uri);
+  return proxy_name;
+}
+
+class HttpProxyMapper : public ProxyMapperInterface {
+ public:
+  bool MapName(const char* server_uri, const grpc_channel_args* args,
+               char** name_to_resolve, grpc_channel_args** new_args) override {
+    if (!grpc_channel_args_find_bool(args, GRPC_ARG_ENABLE_HTTP_PROXY, true)) {
+      return false;
+    }
+    char* user_cred = nullptr;
+    *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') {
+      gpr_log(GPR_ERROR,
+              "'http_proxy' environment variable set, but cannot "
+              "parse server URI '%s' -- not using proxy",
+              server_uri);
+      goto no_use_proxy;
+    }
+    if (strcmp(uri->scheme, "unix") == 0) {
+      gpr_log(GPR_INFO, "not using proxy for Unix domain socket '%s'",
+              server_uri);
+      goto no_use_proxy;
+    }
+    /* Prefer using 'no_grpc_proxy'. Fallback on 'no_proxy' if it is not set. */
+    no_proxy_str = gpr_getenv("no_grpc_proxy");
+    if (no_proxy_str == nullptr) no_proxy_str = gpr_getenv("no_proxy");
+    if (no_proxy_str != nullptr) {
+      static const char* NO_PROXY_SEPARATOR = ",";
+      bool use_proxy = true;
+      std::string server_host;
+      std::string server_port;
+      if (!grpc_core::SplitHostPort(
+              uri->path[0] == '/' ? uri->path + 1 : 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 = 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,
+                         &num_no_proxy_hosts);
+        for (size_t i = 0; i < num_no_proxy_hosts; i++) {
+          char* no_proxy_entry = no_proxy_hosts[i];
+          size_t no_proxy_len = strlen(no_proxy_entry);
+          if (no_proxy_len <= uri_len &&
+              gpr_stricmp(no_proxy_entry,
+                          &(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;
+            break;
+          }
+        }
+        for (size_t i = 0; i < num_no_proxy_hosts; i++) {
+          gpr_free(no_proxy_hosts[i]);
+        }
+        gpr_free(no_proxy_hosts);
+        gpr_free(no_proxy_str);
+        if (!use_proxy) goto no_use_proxy;
+      }
+    }
+    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);
+    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);
+      gpr_free(encoded_user_cred);
+      args_to_add[1] = grpc_channel_arg_string_create(
+          (char*)GRPC_ARG_HTTP_CONNECT_HEADERS, header);
+      *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);
+    return false;
+  }
+
+  bool MapAddress(const grpc_resolved_address& /*address*/,
+                  const grpc_channel_args* /*args*/,
+                  grpc_resolved_address** /*new_address*/,
+                  grpc_channel_args** /*new_args*/) override {
+    return false;
+  }
+};
+
+}  // namespace
+
+void RegisterHttpProxyMapper() {
+  ProxyMapperRegistry::Register(
+      true /* at_start */,
+      std::unique_ptr<ProxyMapperInterface>(new HttpProxyMapper()));
+}
+
+}  // namespace grpc_core

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

@@ -0,0 +1,28 @@
+/*
+ *
+ * Copyright 2016 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_HTTP_PROXY_H
+#define GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_HTTP_PROXY_H
+
+namespace grpc_core {
+
+void RegisterHttpProxyMapper();
+
+}  // namespace grpc_core
+
+#endif /* GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_HTTP_PROXY_H */

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

@@ -0,0 +1,138 @@
+/*
+ *
+ * Copyright 2015 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.h"
+
+#include "src/core/ext/filters/client_channel/lb_policy_registry.h"
+#include "src/core/lib/iomgr/combiner.h"
+
+namespace grpc_core {
+
+DebugOnlyTraceFlag grpc_trace_lb_policy_refcount(false, "lb_policy_refcount");
+
+//
+// LoadBalancingPolicy
+//
+
+LoadBalancingPolicy::LoadBalancingPolicy(Args args, intptr_t initial_refcount)
+    : InternallyRefCounted(&grpc_trace_lb_policy_refcount, initial_refcount),
+      work_serializer_(std::move(args.work_serializer)),
+      interested_parties_(grpc_pollset_set_create()),
+      channel_control_helper_(std::move(args.channel_control_helper)) {}
+
+LoadBalancingPolicy::~LoadBalancingPolicy() {
+  grpc_pollset_set_destroy(interested_parties_);
+}
+
+void LoadBalancingPolicy::Orphan() {
+  ShutdownLocked();
+  Unref(DEBUG_LOCATION, "Orphan");
+}
+
+//
+// LoadBalancingPolicy::UpdateArgs
+//
+
+LoadBalancingPolicy::UpdateArgs::UpdateArgs(const UpdateArgs& other) {
+  addresses = other.addresses;
+  config = other.config;
+  args = grpc_channel_args_copy(other.args);
+}
+
+LoadBalancingPolicy::UpdateArgs::UpdateArgs(UpdateArgs&& other) noexcept {
+  addresses = std::move(other.addresses);
+  config = std::move(other.config);
+  // TODO(roth): Use std::move() once channel args is converted to C++.
+  args = other.args;
+  other.args = nullptr;
+}
+
+LoadBalancingPolicy::UpdateArgs& LoadBalancingPolicy::UpdateArgs::operator=(
+    const UpdateArgs& other) {
+  addresses = other.addresses;
+  config = other.config;
+  grpc_channel_args_destroy(args);
+  args = grpc_channel_args_copy(other.args);
+  return *this;
+}
+
+LoadBalancingPolicy::UpdateArgs& LoadBalancingPolicy::UpdateArgs::operator=(
+    UpdateArgs&& other) noexcept {
+  addresses = std::move(other.addresses);
+  config = std::move(other.config);
+  // TODO(roth): Use std::move() once channel args is converted to C++.
+  grpc_channel_args_destroy(args);
+  args = other.args;
+  other.args = nullptr;
+  return *this;
+}
+
+//
+// LoadBalancingPolicy::QueuePicker
+//
+
+LoadBalancingPolicy::PickResult LoadBalancingPolicy::QueuePicker::Pick(
+    PickArgs /*args*/) {
+  // We invoke the parent's ExitIdleLocked() via a closure instead
+  // of doing it directly here, for two reasons:
+  // 1. ExitIdleLocked() may cause the policy's state to change and
+  //    a new picker to be delivered to the channel.  If that new
+  //    picker is delivered before ExitIdleLocked() returns, then by
+  //    the time this function returns, the pick will already have
+  //    been processed, and we'll be trying to re-process the same
+  //    pick again, leading to a crash.
+  // 2. We are currently running in the data plane mutex, but we
+  //    need to bounce into the control plane work_serializer to call
+  //    ExitIdleLocked().
+  if (!exit_idle_called_) {
+    exit_idle_called_ = true;
+    auto* parent = parent_->Ref().release();  // ref held by lambda.
+    ExecCtx::Run(DEBUG_LOCATION,
+                 GRPC_CLOSURE_CREATE(
+                     [](void* arg, grpc_error* /*error*/) {
+                       auto* parent = static_cast<LoadBalancingPolicy*>(arg);
+                       parent->work_serializer()->Run(
+                           [parent]() {
+                             parent->ExitIdleLocked();
+                             parent->Unref();
+                           },
+                           DEBUG_LOCATION);
+                     },
+                     parent, nullptr),
+                 GRPC_ERROR_NONE);
+  }
+  PickResult result;
+  result.type = PickResult::PICK_QUEUE;
+  return result;
+}
+
+//
+// LoadBalancingPolicy::TransientFailurePicker
+//
+
+LoadBalancingPolicy::PickResult
+LoadBalancingPolicy::TransientFailurePicker::Pick(PickArgs /*args*/) {
+  PickResult result;
+  result.type = PickResult::PICK_FAILED;
+  result.error = GRPC_ERROR_REF(error_);
+  return result;
+}
+
+}  // namespace grpc_core

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

@@ -0,0 +1,421 @@
+/*
+ *
+ * Copyright 2015 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_H
+#define GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_LB_POLICY_H
+
+#include <grpc/support/port_platform.h>
+
+#include <functional>
+#include <iterator>
+
+#include "absl/strings/string_view.h"
+
+#include "src/core/ext/filters/client_channel/server_address.h"
+#include "src/core/ext/filters/client_channel/service_config.h"
+#include "src/core/ext/filters/client_channel/subchannel_interface.h"
+#include "src/core/lib/gprpp/map.h"
+#include "src/core/lib/gprpp/orphanable.h"
+#include "src/core/lib/gprpp/ref_counted_ptr.h"
+#include "src/core/lib/iomgr/polling_entity.h"
+#include "src/core/lib/iomgr/work_serializer.h"
+#include "src/core/lib/transport/connectivity_state.h"
+
+namespace grpc_core {
+
+extern DebugOnlyTraceFlag grpc_trace_lb_policy_refcount;
+
+/// Interface for load balancing policies.
+///
+/// The following concepts are used here:
+///
+/// Channel: An abstraction that manages connections to backend servers
+///   on behalf of a client application.  The application creates a channel
+///   for a given server name and then sends calls (RPCs) on it, and the
+///   channel figures out which backend server to send each call to.  A channel
+///   contains a resolver, a load balancing policy (or a tree of LB policies),
+///   and a set of one or more subchannels.
+///
+/// Subchannel: A subchannel represents a connection to one backend server.
+///   The LB policy decides which subchannels to create, manages the
+///   connectivity state of those subchannels, and decides which subchannel
+///   to send any given call to.
+///
+/// Resolver: A plugin that takes a gRPC server URI and resolves it to a
+///   list of one or more addresses and a service config, as described
+///   in https://github.com/grpc/grpc/blob/master/doc/naming.md.  See
+///   resolver.h for the resolver API.
+///
+/// Load Balancing (LB) Policy: A plugin that takes a list of addresses
+///   from the resolver, maintains and manages a subchannel for each
+///   backend address, and decides which subchannel to send each call on.
+///   An LB policy has two parts:
+///   - A LoadBalancingPolicy, which deals with the control plane work of
+///     managing subchannels.
+///   - A SubchannelPicker, which handles the data plane work of
+///     determining which subchannel a given call should be sent on.
+
+/// LoadBalacingPolicy API.
+///
+/// Note: All methods with a "Locked" suffix must be called from the
+/// work_serializer passed to the constructor.
+///
+/// Any I/O done by the LB policy should be done under the pollset_set
+/// returned by \a interested_parties().
+// TODO(roth): Once we move to EventManager-based polling, remove the
+// interested_parties() hooks from the API.
+class LoadBalancingPolicy : public InternallyRefCounted<LoadBalancingPolicy> {
+ public:
+  // Represents backend metrics reported by the backend to the client.
+  struct BackendMetricData {
+    /// CPU utilization expressed as a fraction of available CPU resources.
+    double cpu_utilization;
+    /// Memory utilization expressed as a fraction of available memory
+    /// resources.
+    double mem_utilization;
+    /// Total requests per second being served by the backend.  This
+    /// should include all services that a backend is responsible for.
+    uint64_t requests_per_second;
+    /// Application-specific requests cost metrics.  Metric names are
+    /// determined by the application.  Each value is an absolute cost
+    /// (e.g. 3487 bytes of storage) associated with the request.
+    std::map<absl::string_view, double, StringLess> request_cost;
+    /// Application-specific resource utilization metrics.  Metric names
+    /// are determined by the application.  Each value is expressed as a
+    /// fraction of total resources available.
+    std::map<absl::string_view, double, StringLess> utilization;
+  };
+
+  /// Interface for accessing per-call state.
+  /// Implemented by the client channel and used by the SubchannelPicker.
+  class CallState {
+   public:
+    CallState() = default;
+    virtual ~CallState() = default;
+
+    /// Allocates memory associated with the call, which will be
+    /// automatically freed when the call is complete.
+    /// It is more efficient to use this than to allocate memory directly
+    /// for allocations that need to be made on a per-call basis.
+    virtual void* Alloc(size_t size) = 0;
+
+    /// Returns the backend metric data returned by the server for the call,
+    /// or null if no backend metric data was returned.
+    // TODO(roth): Move this out of CallState, since it should not be
+    // accessible to the picker, only to the recv_trailing_metadata_ready
+    // callback.  It should instead be in its own interface.
+    virtual const BackendMetricData* GetBackendMetricData() = 0;
+
+    /// EXPERIMENTAL API.
+    /// Returns the value of the call attribute \a key.
+    /// Keys are static strings, so an attribute can be accessed by an LB
+    /// policy implementation only if it knows about the internal key.
+    /// Returns a null string_view if key not found.
+    virtual absl::string_view ExperimentalGetCallAttribute(const char* key) = 0;
+  };
+
+  /// Interface for accessing metadata.
+  /// Implemented by the client channel and used by the SubchannelPicker.
+  class MetadataInterface {
+   public:
+    class iterator
+        : public std::iterator<
+              std::input_iterator_tag,
+              std::pair<absl::string_view, absl::string_view>,  // value_type
+              std::ptrdiff_t,  // difference_type
+              std::pair<absl::string_view, absl::string_view>*,  // pointer
+              std::pair<absl::string_view, absl::string_view>&   // reference
+              > {
+     public:
+      iterator(const MetadataInterface* md, intptr_t handle)
+          : md_(md), handle_(handle) {}
+      iterator& operator++() {
+        handle_ = md_->IteratorHandleNext(handle_);
+        return *this;
+      }
+      bool operator==(iterator other) const {
+        return md_ == other.md_ && handle_ == other.handle_;
+      }
+      bool operator!=(iterator other) const { return !(*this == other); }
+      value_type operator*() const { return md_->IteratorHandleGet(handle_); }
+
+     private:
+      friend class MetadataInterface;
+      const MetadataInterface* md_;
+      intptr_t handle_;
+    };
+
+    virtual ~MetadataInterface() = default;
+
+    /// Adds a key/value pair.
+    /// Does NOT take ownership of \a key or \a value.
+    /// Implementations must ensure that the key and value remain alive
+    /// until the call ends.  If desired, they may be allocated via
+    /// CallState::Alloc().
+    virtual void Add(absl::string_view key, absl::string_view value) = 0;
+
+    /// Iteration interface.
+    virtual iterator begin() const = 0;
+    virtual iterator end() const = 0;
+
+    /// Removes the element pointed to by \a it.
+    /// Returns an iterator pointing to the next element.
+    virtual iterator erase(iterator it) = 0;
+
+   protected:
+    intptr_t GetIteratorHandle(const iterator& it) const { return it.handle_; }
+
+   private:
+    friend class iterator;
+
+    virtual intptr_t IteratorHandleNext(intptr_t handle) const = 0;
+    virtual std::pair<absl::string_view /*key*/, absl::string_view /*value */>
+    IteratorHandleGet(intptr_t handle) const = 0;
+  };
+
+  /// Arguments used when picking a subchannel for a call.
+  struct PickArgs {
+    /// Initial metadata associated with the picking call.
+    /// The LB policy may use the existing metadata to influence its routing
+    /// decision, and it may add new metadata elements to be sent with the
+    /// call to the chosen backend.
+    MetadataInterface* initial_metadata;
+    /// An interface for accessing call state.  Can be used to allocate
+    /// memory associated with the call in an efficient way.
+    CallState* call_state;
+  };
+
+  /// The result of picking a subchannel for a call.
+  struct PickResult {
+    enum ResultType {
+      /// Pick complete.  If \a subchannel is non-null, the client channel
+      /// will immediately proceed with the call on that subchannel;
+      /// otherwise, it will drop the call.
+      PICK_COMPLETE,
+      /// Pick cannot be completed until something changes on the control
+      /// plane.  The client channel will queue the pick and try again the
+      /// next time the picker is updated.
+      PICK_QUEUE,
+      /// Pick failed.  If the call is wait_for_ready, the client channel
+      /// will wait for the next picker and try again; otherwise, it
+      /// will immediately fail the call with the status indicated via
+      /// \a error (although the call may be retried if the client channel
+      /// is configured to do so).
+      PICK_FAILED,
+    };
+    ResultType type;
+
+    /// Used only if type is PICK_COMPLETE.  Will be set to the selected
+    /// subchannel, or nullptr if the LB policy decides to drop the call.
+    RefCountedPtr<SubchannelInterface> subchannel;
+
+    /// Used only if type is PICK_FAILED.
+    /// Error to be set when returning a failure.
+    // TODO(roth): Replace this with something similar to grpc::Status,
+    // so that we don't expose grpc_error to this API.
+    grpc_error* error = GRPC_ERROR_NONE;
+
+    /// Used only if type is PICK_COMPLETE.
+    /// Callback set by LB policy to be notified of trailing metadata.
+    /// If set by LB policy, the client channel will invoke the callback
+    /// when trailing metadata is returned.
+    /// The metadata may be modified by the callback.  However, the callback
+    /// does not take ownership, so any data that needs to be used after
+    /// returning must be copied.
+    /// The call state can be used to obtain backend metric data.
+    // TODO(roth): The arguments to this callback should be moved into a
+    // struct, so that we can later add new fields without breaking
+    // existing implementations.
+    std::function<void(grpc_error*, MetadataInterface*, CallState*)>
+        recv_trailing_metadata_ready;
+  };
+
+  /// A subchannel picker is the object used to pick the subchannel to
+  /// use for a given call.  This is implemented by the LB policy and
+  /// used by the client channel to perform picks.
+  ///
+  /// Pickers are intended to encapsulate all of the state and logic
+  /// needed on the data plane (i.e., to actually process picks for
+  /// individual calls sent on the channel) while excluding all of the
+  /// state and logic needed on the control plane (i.e., resolver
+  /// updates, connectivity state notifications, etc); the latter should
+  /// live in the LB policy object itself.
+  ///
+  /// Currently, pickers are always accessed from within the
+  /// client_channel data plane mutex, so they do not have to be
+  /// thread-safe.
+  class SubchannelPicker {
+   public:
+    SubchannelPicker() = default;
+    virtual ~SubchannelPicker() = default;
+
+    virtual PickResult Pick(PickArgs args) = 0;
+  };
+
+  /// A proxy object implemented by the client channel and used by the
+  /// LB policy to communicate with the channel.
+  class ChannelControlHelper {
+   public:
+    ChannelControlHelper() = default;
+    virtual ~ChannelControlHelper() = default;
+
+    /// Creates a new subchannel with the specified channel args.
+    virtual RefCountedPtr<SubchannelInterface> CreateSubchannel(
+        const grpc_channel_args& args) = 0;
+
+    /// Sets the connectivity state and returns a new picker to be used
+    /// by the client channel.
+    virtual void UpdateState(grpc_connectivity_state state,
+                             std::unique_ptr<SubchannelPicker>) = 0;
+
+    /// Requests that the resolver re-resolve.
+    virtual void RequestReresolution() = 0;
+
+    /// Adds a trace message associated with the channel.
+    enum TraceSeverity { TRACE_INFO, TRACE_WARNING, TRACE_ERROR };
+    virtual void AddTraceEvent(TraceSeverity severity,
+                               absl::string_view message) = 0;
+  };
+
+  /// Interface for configuration data used by an LB policy implementation.
+  /// Individual implementations will create a subclass that adds methods to
+  /// return the parameters they need.
+  class Config : public RefCounted<Config> {
+   public:
+    virtual ~Config() = default;
+
+    // Returns the load balancing policy name
+    virtual const char* name() const = 0;
+  };
+
+  /// Data passed to the UpdateLocked() method when new addresses and
+  /// config are available.
+  struct UpdateArgs {
+    ServerAddressList addresses;
+    RefCountedPtr<Config> config;
+    const grpc_channel_args* args = nullptr;
+
+    // TODO(roth): Remove everything below once channel args is
+    // converted to a copyable and movable C++ object.
+    UpdateArgs() = default;
+    ~UpdateArgs() { grpc_channel_args_destroy(args); }
+    UpdateArgs(const UpdateArgs& other);
+    UpdateArgs(UpdateArgs&& other) noexcept;
+    UpdateArgs& operator=(const UpdateArgs& other);
+    UpdateArgs& operator=(UpdateArgs&& other) noexcept;
+  };
+
+  /// Args used to instantiate an LB policy.
+  struct Args {
+    /// The work_serializer under which all LB policy calls will be run.
+    std::shared_ptr<WorkSerializer> work_serializer;
+    /// Channel control helper.
+    /// Note: LB policies MUST NOT call any method on the helper from
+    /// their constructor.
+    std::unique_ptr<ChannelControlHelper> channel_control_helper;
+    /// Channel args.
+    // TODO(roth): Find a better channel args representation for this API.
+    // TODO(roth): Clarify ownership semantics here -- currently, this
+    // does not take ownership of args, which is the opposite of how we
+    // handle them in UpdateArgs.
+    const grpc_channel_args* args = nullptr;
+  };
+
+  explicit LoadBalancingPolicy(Args args, intptr_t initial_refcount = 1);
+  virtual ~LoadBalancingPolicy();
+
+  // Not copyable nor movable.
+  LoadBalancingPolicy(const LoadBalancingPolicy&) = delete;
+  LoadBalancingPolicy& operator=(const LoadBalancingPolicy&) = delete;
+
+  /// Returns the name of the LB policy.
+  virtual const char* name() const = 0;
+
+  /// Updates the policy with new data from the resolver.  Will be invoked
+  /// immediately after LB policy is constructed, and then again whenever
+  /// the resolver returns a new result.
+  virtual void UpdateLocked(UpdateArgs) = 0;  // NOLINT
+
+  /// Tries to enter a READY connectivity state.
+  /// This is a no-op by default, since most LB policies never go into
+  /// IDLE state.
+  virtual void ExitIdleLocked() {}
+
+  /// Resets connection backoff.
+  virtual void ResetBackoffLocked() = 0;
+
+  grpc_pollset_set* interested_parties() const { return interested_parties_; }
+
+  // Note: This must be invoked while holding the work_serializer.
+  void Orphan() override;
+
+  // A picker that returns PICK_QUEUE for all picks.
+  // Also calls the parent LB policy's ExitIdleLocked() method when the
+  // first pick is seen.
+  class QueuePicker : public SubchannelPicker {
+   public:
+    explicit QueuePicker(RefCountedPtr<LoadBalancingPolicy> parent)
+        : parent_(std::move(parent)) {}
+
+    ~QueuePicker() { parent_.reset(DEBUG_LOCATION, "QueuePicker"); }
+
+    PickResult Pick(PickArgs args) override;
+
+   private:
+    RefCountedPtr<LoadBalancingPolicy> parent_;
+    bool exit_idle_called_ = false;
+  };
+
+  // A picker that returns PICK_TRANSIENT_FAILURE for all picks.
+  class TransientFailurePicker : public SubchannelPicker {
+   public:
+    explicit TransientFailurePicker(grpc_error* error) : error_(error) {}
+    ~TransientFailurePicker() override { GRPC_ERROR_UNREF(error_); }
+
+    PickResult Pick(PickArgs args) override;
+
+   private:
+    grpc_error* error_;
+  };
+
+ protected:
+  std::shared_ptr<WorkSerializer> work_serializer() const {
+    return work_serializer_;
+  }
+
+  // Note: LB policies MUST NOT call any method on the helper from their
+  // constructor.
+  ChannelControlHelper* channel_control_helper() const {
+    return channel_control_helper_.get();
+  }
+
+  /// Shuts down the policy.
+  virtual void ShutdownLocked() = 0;
+
+ private:
+  /// Work Serializer under which LB policy actions take place.
+  std::shared_ptr<WorkSerializer> work_serializer_;
+  /// Owned pointer to interested parties in load balancing decisions.
+  grpc_pollset_set* interested_parties_;
+  /// Channel control helper.
+  std::unique_ptr<ChannelControlHelper> channel_control_helper_;
+};
+
+}  // namespace grpc_core
+
+#endif /* GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_LB_POLICY_H */