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 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 GRPC_MUST_USE_RESULT; 109 110 // Asynchronously perform a HTTP POST. 111 // 'uri' is the target to make the request to. The scheme field is used to 112 // determine the port number. The authority field is the target host. The 113 // path field determines the path of the request. No other fields are used. 114 // 'args' are optional channel args for the request. 115 // 'pollent' indicates a grpc_polling_entity that is interested in the result 116 // of the post - work on this entity may be used to progress the post 117 // operation 118 // 'request' contains request parameters - these are caller owned and can be 119 // destroyed once the call returns 120 // 'deadline' contains a deadline for the request (or gpr_inf_future) 121 // 'on_done' is a callback to report results to 122 // 'channel_creds' are used to configurably secure the connection. 123 // For insecure requests, use grpc_insecure_credentials_create. 124 // For secure requests, use CreateHttpRequestSSLCredentials(). 125 // nullptr is treated as insecure credentials. 126 // TODO(apolcyn): disallow nullptr as a value after unsecure builds 127 // are removed. 128 // Does not support ?var1=val1&var2=val2 in the path. 129 static OrphanablePtr<HttpRequest> Post( 130 URI uri, const grpc_channel_args* args, grpc_polling_entity* pollent, 131 const grpc_http_request* request, Timestamp deadline, 132 grpc_closure* on_done, grpc_http_response* response, 133 RefCountedPtr<grpc_channel_credentials> channel_creds) 134 GRPC_MUST_USE_RESULT; 135 136 // Asynchronously perform a HTTP PUT. 137 // 'uri' is the target to make the request to. The scheme field is used to 138 // determine the port number. The authority field is the target host. The 139 // path field determines the path of the request. No other fields are used. 140 // 'args' are optional channel args for the request. 141 // 'pollent' indicates a grpc_polling_entity that is interested in the result 142 // of the post - work on this entity may be used to progress the post 143 // operation 144 // 'request' contains request parameters - these are caller owned and can be 145 // destroyed once the call returns 146 // 'deadline' contains a deadline for the request (or gpr_inf_future) 147 // 'on_done' is a callback to report results to 148 // 'channel_creds' are used to configurably secure the connection. 149 // For insecure requests, use grpc_insecure_credentials_create. 150 // For secure requests, use CreateHttpRequestSSLCredentials(). 151 // nullptr is treated as insecure credentials. 152 // TODO(apolcyn): disallow nullptr as a value after unsecure builds 153 // are removed. 154 // Does not support ?var1=val1&var2=val2 in the path. 155 static OrphanablePtr<HttpRequest> Put( 156 URI uri, const grpc_channel_args* args, grpc_polling_entity* pollent, 157 const grpc_http_request* request, Timestamp deadline, 158 grpc_closure* on_done, grpc_http_response* response, 159 RefCountedPtr<grpc_channel_credentials> channel_creds) 160 GRPC_MUST_USE_RESULT; 161 162 HttpRequest(URI uri, const grpc_slice& request_text, 163 grpc_http_response* response, Timestamp deadline, 164 const grpc_channel_args* channel_args, grpc_closure* on_done, 165 grpc_polling_entity* pollent, const char* name, 166 absl::optional<std::function<void()>> test_only_generate_response, 167 RefCountedPtr<grpc_channel_credentials> channel_creds); 168 169 ~HttpRequest() override; 170 171 void Start(); 172 173 void Orphan() override; 174 175 static void SetOverride(grpc_httpcli_get_override get, 176 grpc_httpcli_post_override post, 177 grpc_httpcli_put_override put); 178 179 static void TestOnlySetOnHandshakeDoneIntercept( 180 void (*intercept)(HttpRequest* req)); 181 182 private: Finish(grpc_error_handle error)183 void Finish(grpc_error_handle error) ABSL_EXCLUSIVE_LOCKS_REQUIRED(mu_) { 184 grpc_polling_entity_del_from_pollset_set(pollent_, pollset_set_); 185 ExecCtx::Run(DEBUG_LOCATION, on_done_, error); 186 } 187 188 void AppendError(grpc_error_handle error) ABSL_EXCLUSIVE_LOCKS_REQUIRED(mu_); 189 DoRead()190 void DoRead() ABSL_EXCLUSIVE_LOCKS_REQUIRED(mu_) { 191 Ref().release(); // ref held by pending read 192 grpc_endpoint_read(ep_, &incoming_, &on_read_, /*urgent=*/true, 193 /*min_progress_size=*/1); 194 } 195 OnRead(void * user_data,grpc_error_handle error)196 static void OnRead(void* user_data, grpc_error_handle error) { 197 HttpRequest* req = static_cast<HttpRequest*>(user_data); 198 ExecCtx::Run(DEBUG_LOCATION, 199 &req->continue_on_read_after_schedule_on_exec_ctx_, error); 200 } 201 202 // Needed since OnRead may be called inline from grpc_endpoint_read ContinueOnReadAfterScheduleOnExecCtx(void * user_data,grpc_error_handle error)203 static void ContinueOnReadAfterScheduleOnExecCtx(void* user_data, 204 grpc_error_handle error) { 205 RefCountedPtr<HttpRequest> req(static_cast<HttpRequest*>(user_data)); 206 MutexLock lock(&req->mu_); 207 req->OnReadInternal(error); 208 } 209 210 void OnReadInternal(grpc_error_handle error) 211 ABSL_EXCLUSIVE_LOCKS_REQUIRED(mu_); 212 OnWritten()213 void OnWritten() ABSL_EXCLUSIVE_LOCKS_REQUIRED(mu_) { DoRead(); } 214 DoneWrite(void * arg,grpc_error_handle error)215 static void DoneWrite(void* arg, grpc_error_handle error) { 216 HttpRequest* req = static_cast<HttpRequest*>(arg); 217 ExecCtx::Run(DEBUG_LOCATION, 218 &req->continue_done_write_after_schedule_on_exec_ctx_, error); 219 } 220 221 // Needed since DoneWrite may be called inline from grpc_endpoint_write 222 static void ContinueDoneWriteAfterScheduleOnExecCtx(void* arg, 223 grpc_error_handle error); 224 225 void StartWrite() ABSL_EXCLUSIVE_LOCKS_REQUIRED(mu_); 226 227 static void OnHandshakeDone(void* arg, grpc_error_handle error); 228 229 void DoHandshake(const grpc_resolved_address* addr) 230 ABSL_EXCLUSIVE_LOCKS_REQUIRED(mu_); 231 232 void NextAddress(grpc_error_handle error) ABSL_EXCLUSIVE_LOCKS_REQUIRED(mu_); 233 234 void OnResolved( 235 absl::StatusOr<std::vector<grpc_resolved_address>> addresses_or); 236 237 const URI uri_; 238 const grpc_slice request_text_; 239 const Timestamp deadline_; 240 const grpc_channel_args* channel_args_; 241 RefCountedPtr<grpc_channel_credentials> channel_creds_; 242 grpc_closure on_read_; 243 grpc_closure continue_on_read_after_schedule_on_exec_ctx_; 244 grpc_closure done_write_; 245 grpc_closure continue_done_write_after_schedule_on_exec_ctx_; 246 grpc_endpoint* ep_ = nullptr; 247 grpc_closure* on_done_; 248 ResourceQuotaRefPtr resource_quota_; 249 grpc_polling_entity* pollent_; 250 grpc_pollset_set* pollset_set_; 251 const absl::optional<std::function<void()>> test_only_generate_response_; 252 Mutex mu_; 253 RefCountedPtr<HandshakeManager> handshake_mgr_ ABSL_GUARDED_BY(mu_); 254 bool own_endpoint_ ABSL_GUARDED_BY(mu_) = true; 255 bool cancelled_ ABSL_GUARDED_BY(mu_) = false; 256 grpc_http_parser parser_ ABSL_GUARDED_BY(mu_); 257 std::vector<grpc_resolved_address> addresses_ ABSL_GUARDED_BY(mu_); 258 size_t next_address_ ABSL_GUARDED_BY(mu_) = 0; 259 int have_read_byte_ ABSL_GUARDED_BY(mu_) = 0; 260 grpc_iomgr_object iomgr_obj_ ABSL_GUARDED_BY(mu_); 261 grpc_slice_buffer incoming_ ABSL_GUARDED_BY(mu_); 262 grpc_slice_buffer outgoing_ ABSL_GUARDED_BY(mu_); 263 grpc_error_handle overall_error_ ABSL_GUARDED_BY(mu_) = absl::OkStatus(); 264 std::shared_ptr<DNSResolver> resolver_; 265 absl::optional<DNSResolver::TaskHandle> dns_request_handle_ 266 ABSL_GUARDED_BY(mu_) = DNSResolver::kNullHandle; 267 }; 268 269 } // namespace grpc_core 270 271 #endif // GRPC_SRC_CORE_LIB_HTTP_HTTPCLI_H 272