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 "absl/container/inlined_vector.h"
  25
  26 #include <grpc/support/string_util.h>
  27
  28 #include <grpc/impl/codegen/grpc_types.h>
  29
  30 #include "src/core/lib/channel/channel_args.h"
  31 #include "src/core/lib/gprpp/ref_counted.h"
  32 #include "src/core/lib/gprpp/sync.h"
  33 #include "src/core/lib/iomgr/closure.h"
  34 #include "src/core/lib/iomgr/endpoint.h"
  35 #include "src/core/lib/iomgr/exec_ctx.h"
  36 #include "src/core/lib/iomgr/tcp_server.h"
  37 #include "src/core/lib/iomgr/timer.h"
  38
  39 namespace grpc_core {
  40
  41 /// Handshakers are used to perform initial handshakes on a connection
  42 /// before the client sends the initial request.  Some examples of what
  43 /// a handshaker can be used for includes support for HTTP CONNECT on
  44 /// the client side and various types of security initialization.
  45 ///
  46 /// In general, handshakers should be used via a handshake manager.
  47
  48 /// Arguments passed through handshakers and to the on_handshake_done callback.
  49 ///
  50 /// For handshakers, all members are input/output parameters; for
  51 /// example, a handshaker may read from or write to \a endpoint and
  52 /// then later replace it with a wrapped endpoint.  Similarly, a
  53 /// handshaker may modify \a args.
  54 ///
  55 /// A handshaker takes ownership of the members while a handshake is in
  56 /// progress.  Upon failure or shutdown of an in-progress handshaker,
  57 /// the handshaker is responsible for destroying the members and setting
  58 /// them to NULL before invoking the on_handshake_done callback.
  59 ///
  60 /// For the on_handshake_done callback, all members are input arguments,
  61 /// which the callback takes ownership of.
  62 struct HandshakerArgs {
  63   grpc_endpoint* endpoint = nullptr;
  64   grpc_channel_args* args = nullptr;
  65   grpc_slice_buffer* read_buffer = nullptr;
  66   // A handshaker may set this to true before invoking on_handshake_done
  67   // to indicate that subsequent handshakers should be skipped.
  68   bool exit_early = false;
  69   // User data passed through the handshake manager.  Not used by
  70   // individual handshakers.
  71   void* user_data = nullptr;
  72 };
  73
  74 ///
  75 /// Handshaker
  76 ///
  77
  78 class Handshaker : public RefCounted<Handshaker> {
  79  public:
  80   ~Handshaker() override = default;
  81   virtual void Shutdown(grpc_error* why) = 0;
  82   virtual void DoHandshake(grpc_tcp_server_acceptor* acceptor,
  83                            grpc_closure* on_handshake_done,
  84                            HandshakerArgs* args) = 0;
  85   virtual const char* name() const = 0;
  86 };
  87
  88 //
  89 // HandshakeManager
  90 //
  91
  92 class HandshakeManager : public RefCounted<HandshakeManager> {
  93  public:
  94   HandshakeManager();
  95   ~HandshakeManager() override;
  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   Mutex mu_;
 148   bool is_shutdown_ = false;
 149   // An array of handshakers added via grpc_handshake_manager_add().
 150   absl::InlinedVector<RefCountedPtr<Handshaker>, HANDSHAKERS_INIT_SIZE>
 151       handshakers_;
 152   // The index of the handshaker to invoke next and closure to invoke it.
 153   size_t index_ = 0;
 154   grpc_closure call_next_handshaker_;
 155   // The acceptor to call the handshakers with.
 156   grpc_tcp_server_acceptor* acceptor_;
 157   // Deadline timer across all handshakers.
 158   grpc_timer deadline_timer_;
 159   grpc_closure on_timeout_;
 160   // The final callback and user_data to invoke after the last handshaker.
 161   grpc_closure on_handshake_done_;
 162   // Handshaker args.
 163   HandshakerArgs args_;
 164   // Links to the previous and next managers in a list of all pending handshakes
 165   // Used at server side only.
 166   HandshakeManager* prev_ = nullptr;
 167   HandshakeManager* next_ = nullptr;
 168 };
 169
 170 }  // namespace grpc_core
 171
 172 // TODO(arjunroy): These are transitional to account for the new handshaker API
 173 // and will eventually be removed entirely.
 174 typedef grpc_core::HandshakeManager grpc_handshake_manager;
 175 typedef grpc_core::Handshaker grpc_handshaker;
 176 void grpc_handshake_manager_add(grpc_handshake_manager* mgr,
 177                                 grpc_handshaker* handshaker);
 178
 179 #endif /* GRPC_CORE_LIB_CHANNEL_HANDSHAKER_H */