1 // 2 // 3 // Copyright 2015 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_SRC_CORE_LIB_HTTP_HTTPCLI_H 20 #define GRPC_SRC_CORE_LIB_HTTP_HTTPCLI_H 21 22 #include <grpc/support/port_platform.h> 23 24 #include <stddef.h> 25 26 #include <functional> 27 #include <memory> 28 #include <vector> 29 30 #include "absl/base/thread_annotations.h" 31 #include "absl/status/status.h" 32 #include "absl/status/statusor.h" 33 #include "absl/types/optional.h" 34 35 #include <grpc/grpc.h> 36 #include <grpc/slice.h> 37 38 #include "src/core/lib/gprpp/debug_location.h" 39 #include "src/core/lib/gprpp/orphanable.h" 40 #include "src/core/lib/gprpp/ref_counted_ptr.h" 41 #include "src/core/lib/gprpp/sync.h" 42 #include "src/core/lib/gprpp/time.h" 43 #include "src/core/lib/http/parser.h" 44 #include "src/core/lib/iomgr/closure.h" 45 #include "src/core/lib/iomgr/endpoint.h" 46 #include "src/core/lib/iomgr/error.h" 47 #include "src/core/lib/iomgr/exec_ctx.h" 48 #include "src/core/lib/iomgr/iomgr_fwd.h" 49 #include "src/core/lib/iomgr/iomgr_internal.h" 50 #include "src/core/lib/iomgr/polling_entity.h" 51 #include "src/core/lib/iomgr/resolve_address.h" 52 #include "src/core/lib/iomgr/resolved_address.h" 53 #include "src/core/lib/resource_quota/resource_quota.h" 54 #include "src/core/lib/transport/handshaker.h" 55 #include "src/core/lib/uri/uri_parser.h" 56 57 // User agent this library reports 58 #define GRPC_HTTPCLI_USER_AGENT "grpc-httpcli/0.0" 59 60 // override functions return 1 if they handled the request, 0 otherwise 61 typedef int (*grpc_httpcli_get_override)(const grpc_http_request* request, 62 const char* host, const char* path, 63 grpc_core::Timestamp deadline, 64 grpc_closure* on_complete, 65 grpc_http_response* response); 66 typedef int (*grpc_httpcli_post_override)( 67 const grpc_http_request* request, const char* host, const char* path, 68 const char* body_bytes, size_t body_size, grpc_core::Timestamp deadline, 69 grpc_closure* on_complete, grpc_http_response* response); 70 typedef int (*grpc_httpcli_put_override)( 71 const grpc_http_request* request, const char* host, const char* path, 72 const char* body_bytes, size_t body_size, grpc_core::Timestamp deadline, 73 grpc_closure* on_complete, grpc_http_response* response); 74 75 namespace grpc_core { 76 77 // Tracks an in-progress GET or POST request. Calling \a Start() 78 // begins async work and calling \a Orphan() arranges for async work 79 // to be completed as sooon as possible (possibly aborting the request 80 // if it's in flight). 81 // TODO(ctiller): allow caching and capturing multiple requests for the 82 // same content and combining them 83 class HttpRequest : public InternallyRefCounted<HttpRequest> { 84 public: 85 // Asynchronously perform a HTTP GET. 86 // 'uri' is the target to make the request to. The scheme field is used to 87 // determine the port number. The authority field is the target host. The 88 // path field determines the path of the request. No other fields are used. 89 // 'args' are optional channel args for the request. 90 // 'pollent' indicates a grpc_polling_entity that is interested in the result 91 // of the get - work on this entity may be used to progress the get 92 // operation 93 // 'request' contains request parameters - these are caller owned and 94 // can be destroyed once the call returns 95 // 'deadline' contains a deadline for the request (or gpr_inf_future) 96 // 'on_done' is a callback to report results to 97 // 'channel_creds' are used to configurably secure the connection. 98 // For insecure requests, use grpc_insecure_credentials_create. 99 // For secure requests, use CreateHttpRequestSSLCredentials(). 100 // nullptr is treated as insecure credentials. 101 // TODO(yihuaz): disallow nullptr as a value after unsecure builds 102 // are removed. 103 GRPC_MUST_USE_RESULT static OrphanablePtr<HttpRequest> Get( 104 URI uri, const grpc_channel_args* args, grpc_polling_entity* pollent, 105 const grpc_http_request* request, Timestamp deadline, 106 grpc_closure* on_done, grpc_http_response* response, 107 RefCountedPtr<grpc_channel_credentials> channel_creds); 108 109 // Asynchronously perform a HTTP POST. 110 // 'uri' is the target to make the request to. The scheme field is used to 111 // determine the port number. The authority field is the target host. The 112 // path field determines the path of the request. No other fields are used. 113 // 'args' are optional channel args for the request. 114 // 'pollent' indicates a grpc_polling_entity that is interested in the result 115 // of the post - work on this entity may be used to progress the post 116 // operation 117 // 'request' contains request parameters - these are caller owned and can be 118 // destroyed once the call returns 119 // 'deadline' contains a deadline for the request (or gpr_inf_future) 120 // 'on_done' is a callback to report results to 121 // 'channel_creds' are used to configurably secure the connection. 122 // For insecure requests, use grpc_insecure_credentials_create. 123 // For secure requests, use CreateHttpRequestSSLCredentials(). 124 // nullptr is treated as insecure credentials. 125 // TODO(apolcyn): disallow nullptr as a value after unsecure builds 126 // are removed. 127 // Does not support ?var1=val1&var2=val2 in the path. 128 GRPC_MUST_USE_RESULT static OrphanablePtr<HttpRequest> Post( 129 URI uri, const grpc_channel_args* args, grpc_polling_entity* pollent, 130 const grpc_http_request* request, Timestamp deadline, 131 grpc_closure* on_done, grpc_http_response* response, 132 RefCountedPtr<grpc_channel_credentials> channel_creds); 133 134 // Asynchronously perform a HTTP PUT. 135 // 'uri' is the target to make the request to. The scheme field is used to 136 // determine the port number. The authority field is the target host. The 137 // path field determines the path of the request. No other fields are used. 138 // 'args' are optional channel args for the request. 139 // 'pollent' indicates a grpc_polling_entity that is interested in the result 140 // of the post - work on this entity may be used to progress the post 141 // operation 142 // 'request' contains request parameters - these are caller owned and can be 143 // destroyed once the call returns 144 // 'deadline' contains a deadline for the request (or gpr_inf_future) 145 // 'on_done' is a callback to report results to 146 // 'channel_creds' are used to configurably secure the connection. 147 // For insecure requests, use grpc_insecure_credentials_create. 148 // For secure requests, use CreateHttpRequestSSLCredentials(). 149 // nullptr is treated as insecure credentials. 150 // TODO(apolcyn): disallow nullptr as a value after unsecure builds 151 // are removed. 152 // Does not support ?var1=val1&var2=val2 in the path. 153 GRPC_MUST_USE_RESULT static OrphanablePtr<HttpRequest> Put( 154 URI uri, const grpc_channel_args* args, grpc_polling_entity* pollent, 155 const grpc_http_request* request, Timestamp deadline, 156 grpc_closure* on_done, grpc_http_response* response, 157 RefCountedPtr<grpc_channel_credentials> channel_creds); 158 159 HttpRequest(URI uri, const grpc_slice& request_text, 160 grpc_http_response* response, Timestamp deadline, 161 const grpc_channel_args* channel_args, grpc_closure* on_done, 162 grpc_polling_entity* pollent, const char* name, 163 absl::optional<std::function<void()>> test_only_generate_response, 164 RefCountedPtr<grpc_channel_credentials> channel_creds); 165 166 ~HttpRequest() override; 167 168 void Start(); 169 170 void Orphan() override; 171 172 static void SetOverride(grpc_httpcli_get_override get, 173 grpc_httpcli_post_override post, 174 grpc_httpcli_put_override put); 175 176 static void TestOnlySetOnHandshakeDoneIntercept( 177 void (*intercept)(HttpRequest* req)); 178 179 private: Finish(grpc_error_handle error)180 void Finish(grpc_error_handle error) ABSL_EXCLUSIVE_LOCKS_REQUIRED(mu_) { 181 grpc_polling_entity_del_from_pollset_set(pollent_, pollset_set_); 182 ExecCtx::Run(DEBUG_LOCATION, on_done_, error); 183 } 184 185 void AppendError(grpc_error_handle error) ABSL_EXCLUSIVE_LOCKS_REQUIRED(mu_); 186 DoRead()187 void DoRead() ABSL_EXCLUSIVE_LOCKS_REQUIRED(mu_) { 188 Ref().release(); // ref held by pending read 189 grpc_endpoint_read(ep_, &incoming_, &on_read_, /*urgent=*/true, 190 /*min_progress_size=*/1); 191 } 192 OnRead(void * user_data,grpc_error_handle error)193 static void OnRead(void* user_data, grpc_error_handle error) { 194 HttpRequest* req = static_cast<HttpRequest*>(user_data); 195 ExecCtx::Run(DEBUG_LOCATION, 196 &req->continue_on_read_after_schedule_on_exec_ctx_, error); 197 } 198 199 // Needed since OnRead may be called inline from grpc_endpoint_read ContinueOnReadAfterScheduleOnExecCtx(void * user_data,grpc_error_handle error)200 static void ContinueOnReadAfterScheduleOnExecCtx(void* user_data, 201 grpc_error_handle error) { 202 RefCountedPtr<HttpRequest> req(static_cast<HttpRequest*>(user_data)); 203 MutexLock lock(&req->mu_); 204 req->OnReadInternal(error); 205 } 206 207 void OnReadInternal(grpc_error_handle error) 208 ABSL_EXCLUSIVE_LOCKS_REQUIRED(mu_); 209 OnWritten()210 void OnWritten() ABSL_EXCLUSIVE_LOCKS_REQUIRED(mu_) { DoRead(); } 211 DoneWrite(void * arg,grpc_error_handle error)212 static void DoneWrite(void* arg, grpc_error_handle error) { 213 HttpRequest* req = static_cast<HttpRequest*>(arg); 214 ExecCtx::Run(DEBUG_LOCATION, 215 &req->continue_done_write_after_schedule_on_exec_ctx_, error); 216 } 217 218 // Needed since DoneWrite may be called inline from grpc_endpoint_write 219 static void ContinueDoneWriteAfterScheduleOnExecCtx(void* arg, 220 grpc_error_handle error); 221 222 void StartWrite() ABSL_EXCLUSIVE_LOCKS_REQUIRED(mu_); 223 224 static void OnHandshakeDone(void* arg, grpc_error_handle error); 225 226 void DoHandshake(const grpc_resolved_address* addr) 227 ABSL_EXCLUSIVE_LOCKS_REQUIRED(mu_); 228 229 void NextAddress(grpc_error_handle error) ABSL_EXCLUSIVE_LOCKS_REQUIRED(mu_); 230 231 void OnResolved( 232 absl::StatusOr<std::vector<grpc_resolved_address>> addresses_or); 233 234 const URI uri_; 235 const grpc_slice request_text_; 236 const Timestamp deadline_; 237 const grpc_channel_args* channel_args_; 238 RefCountedPtr<grpc_channel_credentials> channel_creds_; 239 grpc_closure on_read_; 240 grpc_closure continue_on_read_after_schedule_on_exec_ctx_; 241 grpc_closure done_write_; 242 grpc_closure continue_done_write_after_schedule_on_exec_ctx_; 243 grpc_endpoint* ep_ = nullptr; 244 grpc_closure* on_done_; 245 ResourceQuotaRefPtr resource_quota_; 246 grpc_polling_entity* pollent_; 247 grpc_pollset_set* pollset_set_; 248 const absl::optional<std::function<void()>> test_only_generate_response_; 249 Mutex mu_; 250 RefCountedPtr<HandshakeManager> handshake_mgr_ ABSL_GUARDED_BY(mu_); 251 bool own_endpoint_ ABSL_GUARDED_BY(mu_) = true; 252 bool cancelled_ ABSL_GUARDED_BY(mu_) = false; 253 grpc_http_parser parser_ ABSL_GUARDED_BY(mu_); 254 std::vector<grpc_resolved_address> addresses_ ABSL_GUARDED_BY(mu_); 255 size_t next_address_ ABSL_GUARDED_BY(mu_) = 0; 256 int have_read_byte_ ABSL_GUARDED_BY(mu_) = 0; 257 grpc_iomgr_object iomgr_obj_ ABSL_GUARDED_BY(mu_); 258 grpc_slice_buffer incoming_ ABSL_GUARDED_BY(mu_); 259 grpc_slice_buffer outgoing_ ABSL_GUARDED_BY(mu_); 260 grpc_error_handle overall_error_ ABSL_GUARDED_BY(mu_) = absl::OkStatus(); 261 std::shared_ptr<DNSResolver> resolver_; 262 absl::optional<DNSResolver::TaskHandle> dns_request_handle_ 263 ABSL_GUARDED_BY(mu_) = DNSResolver::kNullHandle; 264 }; 265 266 } // namespace grpc_core 267 268 #endif // GRPC_SRC_CORE_LIB_HTTP_HTTPCLI_H 269