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_handle 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 /// Adds a handshaker to the handshake manager. 98 /// Takes ownership of \a handshaker. 99 void Add(RefCountedPtr<Handshaker> handshaker); 100 101 /// Shuts down the handshake manager (e.g., to clean up when the operation is 102 /// aborted in the middle). 103 void Shutdown(grpc_error_handle why); 104 105 /// Invokes handshakers in the order they were added. 106 /// Takes ownership of \a endpoint, and then passes that ownership to 107 /// the \a on_handshake_done callback. 108 /// Does NOT take ownership of \a channel_args. Instead, makes a copy before 109 /// invoking the first handshaker. 110 /// \a acceptor will be nullptr for client-side handshakers. 111 /// 112 /// When done, invokes \a on_handshake_done with a HandshakerArgs 113 /// object as its argument. If the callback is invoked with error != 114 /// GRPC_ERROR_NONE, then handshaking failed and the handshaker has done 115 /// the necessary clean-up. Otherwise, the callback takes ownership of 116 /// the arguments. 117 void DoHandshake(grpc_endpoint* endpoint, 118 const grpc_channel_args* channel_args, grpc_millis deadline, 119 grpc_tcp_server_acceptor* acceptor, 120 grpc_iomgr_cb_func on_handshake_done, void* user_data); 121 122 private: 123 bool CallNextHandshakerLocked(grpc_error_handle error); 124 125 // A function used as the handshaker-done callback when chaining 126 // handshakers together. 127 static void CallNextHandshakerFn(void* arg, grpc_error_handle error); 128 129 // Callback invoked when deadline is exceeded. 130 static void OnTimeoutFn(void* arg, grpc_error_handle error); 131 132 static const size_t HANDSHAKERS_INIT_SIZE = 2; 133 134 Mutex mu_; 135 bool is_shutdown_ = false; 136 // An array of handshakers added via grpc_handshake_manager_add(). 137 absl::InlinedVector<RefCountedPtr<Handshaker>, HANDSHAKERS_INIT_SIZE> 138 handshakers_; 139 // The index of the handshaker to invoke next and closure to invoke it. 140 size_t index_ = 0; 141 grpc_closure call_next_handshaker_; 142 // The acceptor to call the handshakers with. 143 grpc_tcp_server_acceptor* acceptor_; 144 // Deadline timer across all handshakers. 145 grpc_timer deadline_timer_; 146 grpc_closure on_timeout_; 147 // The final callback and user_data to invoke after the last handshaker. 148 grpc_closure on_handshake_done_; 149 // Handshaker args. 150 HandshakerArgs args_; 151 }; 152 153 } // namespace grpc_core 154 155 // TODO(arjunroy): These are transitional to account for the new handshaker API 156 // and will eventually be removed entirely. 157 typedef grpc_core::HandshakeManager grpc_handshake_manager; 158 typedef grpc_core::Handshaker grpc_handshaker; 159 void grpc_handshake_manager_add(grpc_handshake_manager* mgr, 160 grpc_handshaker* handshaker); 161 162 #endif /* GRPC_CORE_LIB_CHANNEL_HANDSHAKER_H */ 163