1 /* Copyright 2016 The TensorFlow Authors. All Rights Reserved. 2 3 Licensed under the Apache License, Version 2.0 (the "License"); 4 you may not use this file except in compliance with the License. 5 You may obtain a copy of the License at 6 7 http://www.apache.org/licenses/LICENSE-2.0 8 9 Unless required by applicable law or agreed to in writing, software 10 distributed under the License is distributed on an "AS IS" BASIS, 11 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 See the License for the specific language governing permissions and 13 limitations under the License. 14 ==============================================================================*/ 15 16 #ifndef TENSORFLOW_CORE_PLATFORM_HTTP_REQUEST_H_ 17 #define TENSORFLOW_CORE_PLATFORM_HTTP_REQUEST_H_ 18 19 #include <string> 20 #include <unordered_map> 21 #include <vector> 22 #include "tensorflow/core/lib/core/errors.h" 23 #include "tensorflow/core/lib/core/status.h" 24 #include "tensorflow/core/lib/core/stringpiece.h" 25 #include "tensorflow/core/platform/env.h" 26 #include "tensorflow/core/platform/macros.h" 27 #include "tensorflow/core/platform/protobuf.h" 28 #include "tensorflow/core/platform/types.h" 29 30 namespace tensorflow { 31 32 /// \brief An abstract basic HTTP client. 33 /// 34 /// The usage pattern for the class is based on the libcurl library: 35 /// create a request object, set request parameters and call Send(). 36 /// 37 /// For example: 38 /// HttpRequest request; 39 /// request.SetUri("http://www.google.com"); 40 /// request.SetResultsBuffer(out_buffer); 41 /// request.Send(); 42 class HttpRequest { 43 public: 44 class Factory { 45 public: 46 virtual ~Factory() {} 47 virtual HttpRequest* Create() = 0; 48 }; 49 50 HttpRequest() {} 51 virtual ~HttpRequest() {} 52 53 /// Sets the request URI. 54 virtual void SetUri(const string& uri) = 0; 55 56 /// \brief Sets the Range header. 57 /// 58 /// Used for random seeks, for example "0-999" returns the first 1000 bytes 59 /// (note that the right border is included). 60 virtual void SetRange(uint64 start, uint64 end) = 0; 61 62 /// Sets a request header. 63 virtual void AddHeader(const string& name, const string& value) = 0; 64 65 /// Sets a DNS resolve mapping (to skip DNS resolution). 66 /// 67 /// Note: because GCS is available over HTTPS, we cannot replace the hostname 68 /// in the URI with an IP address, as that will cause the certificate check 69 /// to fail. 70 virtual void AddResolveOverride(const string& hostname, int64 port, 71 const string& ip_addr) = 0; 72 73 /// Sets the 'Authorization' header to the value of 'Bearer ' + auth_token. 74 virtual void AddAuthBearerHeader(const string& auth_token) = 0; 75 76 /// Makes the request a DELETE request. 77 virtual void SetDeleteRequest() = 0; 78 79 /// \brief Makes the request a PUT request. 80 /// 81 /// The request body will be taken from the specified file starting from 82 /// the given offset. 83 virtual Status SetPutFromFile(const string& body_filepath, size_t offset) = 0; 84 85 /// Makes the request a PUT request with an empty body. 86 virtual void SetPutEmptyBody() = 0; 87 88 /// \brief Makes the request a POST request. 89 /// 90 /// The request body will be taken from the specified buffer. 91 virtual void SetPostFromBuffer(const char* buffer, size_t size) = 0; 92 93 /// Makes the request a POST request with an empty body. 94 virtual void SetPostEmptyBody() = 0; 95 96 /// \brief Specifies the buffer for receiving the response body. 97 /// 98 /// Size of out_buffer after an access will be exactly the number of bytes 99 /// read. Existing content of the vector will be cleared. 100 virtual void SetResultBuffer(std::vector<char>* out_buffer) = 0; 101 102 /// \brief Specifies the buffer for receiving the response body. 103 /// 104 /// This method should be used when a caller knows the upper bound of the 105 /// size of the response data. The caller provides a pre-allocated buffer 106 /// and its size. After the Send() method is called, the 107 /// GetResultBufferDirectBytesTransferred() method may be used to learn to the 108 /// number of bytes that were transferred using this method. 109 virtual void SetResultBufferDirect(char* buffer, size_t size) = 0; 110 111 /// \brief Returns the number of bytes transferred, when using 112 /// SetResultBufferDirect(). This method may only be used when using 113 /// SetResultBufferDirect(). 114 virtual size_t GetResultBufferDirectBytesTransferred() = 0; 115 116 /// \brief Returns the response headers of a completed request. 117 /// 118 /// If the header is not found, returns an empty string. 119 virtual string GetResponseHeader(const string& name) const = 0; 120 121 /// Returns the response code of a completed request. 122 virtual uint64 GetResponseCode() const = 0; 123 124 /// \brief Sends the formed request. 125 /// 126 /// If the result buffer was defined, the response will be written there. 127 /// The object is not designed to be re-used after Send() is executed. 128 virtual Status Send() = 0; 129 130 // Url encodes str and returns a new string. 131 virtual string EscapeString(const string& str) = 0; 132 133 /// \brief Set timeouts for this request. 134 /// 135 /// The connection parameter controls how long we should wait for the 136 /// connection to be established. The inactivity parameter controls how long 137 /// we should wait between additional responses from the server. Finally the 138 /// total parameter controls the maximum total connection time to prevent 139 /// hanging indefinitely. 140 virtual void SetTimeouts(uint32 connection, uint32 inactivity, 141 uint32 total) = 0; 142 143 TF_DISALLOW_COPY_AND_ASSIGN(HttpRequest); 144 }; 145 146 } // namespace tensorflow 147 148 #endif // TENSORFLOW_CORE_PLATFORM_HTTP_REQUEST_H_ 149
