legacy-libs/grpc-cloned/deps/grpc/src/core/lib/channel/handshaker.h

   1 /*
   2  *
   3  * Copyright 2016 gRPC authors.
   4  *
   5  * Licensed under the Apache License, Version 2.0 (the "License");
   6  * you may not use this file except in compliance with the License.
   7  * You may obtain a copy of the License at
   8  *
   9  *     http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  * Unless required by applicable law or agreed to in writing, software
  12  * distributed under the License is distributed on an "AS IS" BASIS,
  13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  * See the License for the specific language governing permissions and
  15  * limitations under the License.
  16  *
  17  */
  18
  19 #ifndef GRPC_CORE_LIB_CHANNEL_HANDSHAKER_H
  20 #define GRPC_CORE_LIB_CHANNEL_HANDSHAKER_H
  21
  22 #include <grpc/support/port_platform.h>
  23
  24 #include <grpc/support/string_util.h>
  25
  26 #include <grpc/impl/codegen/grpc_types.h>
  27
  28 #include "src/core/lib/channel/channel_args.h"
  29 #include "src/core/lib/gprpp/inlined_vector.h"
  30 #include "src/core/lib/gprpp/ref_counted.h"
  31 #include "src/core/lib/gprpp/sync.h"
  32 #include "src/core/lib/iomgr/closure.h"
  33 #include "src/core/lib/iomgr/endpoint.h"
  34 #include "src/core/lib/iomgr/exec_ctx.h"
  35 #include "src/core/lib/iomgr/tcp_server.h"
  36 #include "src/core/lib/iomgr/timer.h"
  37
  38 namespace grpc_core {
  39
  40 /// Handshakers are used to perform initial handshakes on a connection
  41 /// before the client sends the initial request.  Some examples of what
  42 /// a handshaker can be used for includes support for HTTP CONNECT on
  43 /// the client side and various types of security initialization.
  44 ///
  45 /// In general, handshakers should be used via a handshake manager.
  46
  47 /// Arguments passed through handshakers and to the on_handshake_done callback.
  48 ///
  49 /// For handshakers, all members are input/output parameters; for
  50 /// example, a handshaker may read from or write to \a endpoint and
  51 /// then later replace it with a wrapped endpoint.  Similarly, a
  52 /// handshaker may modify \a args.
  53 ///
  54 /// A handshaker takes ownership of the members while a handshake is in
  55 /// progress.  Upon failure or shutdown of an in-progress handshaker,
  56 /// the handshaker is responsible for destroying the members and setting
  57 /// them to NULL before invoking the on_handshake_done callback.
  58 ///
  59 /// For the on_handshake_done callback, all members are input arguments,
  60 /// which the callback takes ownership of.
  61 struct HandshakerArgs {
  62   grpc_endpoint* endpoint = nullptr;
  63   grpc_channel_args* args = nullptr;
  64   grpc_slice_buffer* read_buffer = nullptr;
  65   // A handshaker may set this to true before invoking on_handshake_done
  66   // to indicate that subsequent handshakers should be skipped.
  67   bool exit_early = false;
  68   // User data passed through the handshake manager.  Not used by
  69   // individual handshakers.
  70   void* user_data = nullptr;
  71 };
  72
  73 ///
  74 /// Handshaker
  75 ///
  76
  77 class Handshaker : public RefCounted<Handshaker> {
  78  public:
  79   virtual ~Handshaker() = default;
  80   virtual void Shutdown(grpc_error* why) GRPC_ABSTRACT;
  81   virtual void DoHandshake(grpc_tcp_server_acceptor* acceptor,
  82                            grpc_closure* on_handshake_done,
  83                            HandshakerArgs* args) GRPC_ABSTRACT;
  84   virtual const char* name() const GRPC_ABSTRACT;
  85   GRPC_ABSTRACT_BASE_CLASS
  86 };
  87
  88 //
  89 // HandshakeManager
  90 //
  91
  92 class HandshakeManager : public RefCounted<HandshakeManager> {
  93  public:
  94   HandshakeManager();
  95   ~HandshakeManager();
  96
  97   /// Add \a mgr to the server side list of all pending handshake managers, the
  98   /// list starts with \a *head.
  99   // Not thread-safe. Caller needs to synchronize.
 100   void AddToPendingMgrList(HandshakeManager** head);
 101
 102   /// Remove \a mgr from the server side list of all pending handshake managers.
 103   // Not thread-safe. Caller needs to synchronize.
 104   void RemoveFromPendingMgrList(HandshakeManager** head);
 105
 106   /// Shutdown all pending handshake managers starting at head on the server
 107   /// side. Not thread-safe. Caller needs to synchronize.
 108   void ShutdownAllPending(grpc_error* why);
 109
 110   /// Adds a handshaker to the handshake manager.
 111   /// Takes ownership of \a handshaker.
 112   void Add(RefCountedPtr<Handshaker> handshaker);
 113
 114   /// Shuts down the handshake manager (e.g., to clean up when the operation is
 115   /// aborted in the middle).
 116   void Shutdown(grpc_error* why);
 117
 118   /// Invokes handshakers in the order they were added.
 119   /// Takes ownership of \a endpoint, and then passes that ownership to
 120   /// the \a on_handshake_done callback.
 121   /// Does NOT take ownership of \a channel_args.  Instead, makes a copy before
 122   /// invoking the first handshaker.
 123   /// \a acceptor will be nullptr for client-side handshakers.
 124   ///
 125   /// When done, invokes \a on_handshake_done with a HandshakerArgs
 126   /// object as its argument.  If the callback is invoked with error !=
 127   /// GRPC_ERROR_NONE, then handshaking failed and the handshaker has done
 128   /// the necessary clean-up.  Otherwise, the callback takes ownership of
 129   /// the arguments.
 130   void DoHandshake(grpc_endpoint* endpoint,
 131                    const grpc_channel_args* channel_args, grpc_millis deadline,
 132                    grpc_tcp_server_acceptor* acceptor,
 133                    grpc_iomgr_cb_func on_handshake_done, void* user_data);
 134
 135  private:
 136   bool CallNextHandshakerLocked(grpc_error* error);
 137
 138   // A function used as the handshaker-done callback when chaining
 139   // handshakers together.
 140   static void CallNextHandshakerFn(void* arg, grpc_error* error);
 141
 142   // Callback invoked when deadline is exceeded.
 143   static void OnTimeoutFn(void* arg, grpc_error* error);
 144
 145   static const size_t HANDSHAKERS_INIT_SIZE = 2;
 146
 147   gpr_mu mu_;
 148   bool is_shutdown_ = false;
 149   // An array of handshakers added via grpc_handshake_manager_add().
 150   InlinedVector<RefCountedPtr<Handshaker>, HANDSHAKERS_INIT_SIZE> handshakers_;
 151   // The index of the handshaker to invoke next and closure to invoke it.
 152   size_t index_ = 0;
 153   grpc_closure call_next_handshaker_;
 154   // The acceptor to call the handshakers with.
 155   grpc_tcp_server_acceptor* acceptor_;
 156   // Deadline timer across all handshakers.
 157   grpc_timer deadline_timer_;
 158   grpc_closure on_timeout_;
 159   // The final callback and user_data to invoke after the last handshaker.
 160   grpc_closure on_handshake_done_;
 161   // Handshaker args.
 162   HandshakerArgs args_;
 163   // Links to the previous and next managers in a list of all pending handshakes
 164   // Used at server side only.
 165   HandshakeManager* prev_ = nullptr;
 166   HandshakeManager* next_ = nullptr;
 167 };
 168
 169 }  // namespace grpc_core
 170
 171 // TODO(arjunroy): These are transitional to account for the new handshaker API
 172 // and will eventually be removed entirely.
 173 typedef grpc_core::HandshakeManager grpc_handshake_manager;
 174 typedef grpc_core::Handshaker grpc_handshaker;
 175 void grpc_handshake_manager_add(grpc_handshake_manager* mgr,
 176                                 grpc_handshaker* handshaker);
 177
 178 #endif /* GRPC_CORE_LIB_CHANNEL_HANDSHAKER_H */