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 gpr_mu 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 */ 180