Google Cloud Storage C++ Client  1.32.1
A C++ Client Library for Google Cloud Storage
client_options.h
Go to the documentation of this file.
1 // Copyright 2018 Google LLC
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 #ifndef GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_STORAGE_CLIENT_OPTIONS_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_STORAGE_CLIENT_OPTIONS_H
17 
18 #include "google/cloud/storage/oauth2/credentials.h"
19 #include "google/cloud/storage/options.h"
20 #include "google/cloud/storage/version.h"
21 #include "google/cloud/common_options.h"
22 #include "google/cloud/options.h"
23 #include <chrono>
24 #include <memory>
25 #include <string>
26 
27 namespace google {
28 namespace cloud {
29 namespace storage {
30 inline namespace STORAGE_CLIENT_NS {
31 class ClientOptions;
32 namespace internal {
33 std::string JsonEndpoint(Options const&);
34 std::string JsonUploadEndpoint(Options const&);
35 std::string XmlEndpoint(Options const&);
36 std::string IamEndpoint(Options const&);
37 
38 Options MakeOptions(ClientOptions);
39 
40 ClientOptions MakeBackwardsCompatibleClientOptions(Options);
41 
42 Options ApplyPolicy(Options opts, RetryPolicy const& p);
43 Options ApplyPolicy(Options opts, BackoffPolicy const& p);
44 Options ApplyPolicy(Options opts, IdempotencyPolicy const& p);
45 
46 inline Options ApplyPolicies(Options opts) { return opts; }
47 
48 template <typename P, typename... Policies>
49 Options ApplyPolicies(Options opts, P&& head, Policies&&... tail) {
50  opts = ApplyPolicy(std::move(opts), std::forward<P>(head));
51  return ApplyPolicies(std::move(opts), std::forward<Policies>(tail)...);
52 }
53 
54 Options DefaultOptions(std::shared_ptr<oauth2::Credentials> credentials,
55  Options opts);
56 Options DefaultOptionsWithCredentials(Options opts);
57 
58 } // namespace internal
59 
60 /**
61  * Describes the configuration for low-level connection features.
62  *
63  * Some applications may want to use a different SSL root of trust for their
64  * connections, for example, containerized applications might store the
65  * certificate authority certificates in a hard-coded location.
66  *
67  * This is a separate class, as it is used to configure both the normal
68  * connections to GCS and the connections used to obtain OAuth2 access
69  * tokens.
70  */
72  public:
73  std::string ssl_root_path() const { return ssl_root_path_; }
74 
75  ChannelOptions& set_ssl_root_path(std::string ssl_root_path) {
76  ssl_root_path_ = std::move(ssl_root_path);
77  return *this;
78  }
79 
80  private:
81  std::string ssl_root_path_;
82 };
83 
84 /**
85  * Describes the configuration for a `storage::Client` object.
86  *
87  * By default, several environment variables are read to configure the client:
88  *
89  * - `CLOUD_STORAGE_EMULATOR_ENDPOINT`: if set, use this http endpoint to
90  * make all http requests instead of the production GCS service. Also,
91  * if set, the `CreateDefaultClientOptions()` function will use an
92  * `AnonymousCredentials` object instead of loading Application Default
93  * %Credentials.
94  * - `CLOUD_STORAGE_ENABLE_CLOG`: if set, enable std::clog as a backend for
95  * `google::cloud::LogSink`.
96  * - `CLOUD_STORAGE_ENABLE_TRACING`: if set, this is the list of components that
97  * will have logging enabled, the component this is:
98  * - `http`: trace all http request / responses.
99  */
101  public:
102  explicit ClientOptions(std::shared_ptr<oauth2::Credentials> credentials)
103  : ClientOptions(std::move(credentials), {}) {}
104  ClientOptions(std::shared_ptr<oauth2::Credentials> credentials,
105  ChannelOptions channel_options);
106 
107  /**
108  * Creates a `ClientOptions` with Google Application Default %Credentials.
109  *
110  * If Application Default %Credentials could not be loaded, this returns a
111  * `Status` with failure details. If the `CLOUD_STORAGE_EMULATOR_ENDPOINT`
112  * environment variable is set, this function instead uses an
113  * `AnonymousCredentials` to configure the client.
114  */
115  static StatusOr<ClientOptions> CreateDefaultClientOptions();
116  static StatusOr<ClientOptions> CreateDefaultClientOptions(
117  ChannelOptions const& channel_options);
118 
119  std::shared_ptr<oauth2::Credentials> credentials() const {
121  }
123  opts_.set<Oauth2CredentialsOption>(std::move(c));
124  return *this;
125  }
126 
127  std::string const& endpoint() const {
128  return opts_.get<RestEndpointOption>();
129  }
130  ClientOptions& set_endpoint(std::string endpoint) {
131  opts_.set<RestEndpointOption>(std::move(endpoint));
132  return *this;
133  }
134 
135  std::string const& iam_endpoint() const {
136  return opts_.get<IamEndpointOption>();
137  }
138  ClientOptions& set_iam_endpoint(std::string endpoint) {
139  opts_.set<IamEndpointOption>(std::move(endpoint));
140  return *this;
141  }
142 
143  std::string const& version() const {
144  return opts_.get<internal::TargetApiVersionOption>();
145  }
146  ClientOptions& set_version(std::string version) {
147  opts_.set<internal::TargetApiVersionOption>(std::move(version));
148  return *this;
149  }
150 
151  bool enable_http_tracing() const;
153 
154  bool enable_raw_client_tracing() const;
156 
157  std::string const& project_id() const { return opts_.get<ProjectIdOption>(); }
158  ClientOptions& set_project_id(std::string v) {
159  opts_.set<ProjectIdOption>(std::move(v));
160  return *this;
161  }
162 
163  std::size_t connection_pool_size() const {
165  }
168  return *this;
169  }
170 
171  std::size_t download_buffer_size() const {
173  }
174  ClientOptions& SetDownloadBufferSize(std::size_t size);
175 
176  std::size_t upload_buffer_size() const {
177  return opts_.get<UploadBufferSizeOption>();
178  }
179  ClientOptions& SetUploadBufferSize(std::size_t size);
180 
181  std::string const& user_agent_prefix() const { return user_agent_prefix_; }
182  ClientOptions& add_user_agent_prefix(std::string prefix) {
183  opts_.lookup<UserAgentProductsOption>().push_back(prefix);
184  if (!user_agent_prefix_.empty()) {
185  prefix += ' ';
186  prefix += user_agent_prefix_;
187  }
188  user_agent_prefix_ = std::move(prefix);
189  return *this;
190  }
191  /// @deprecated use `add_user_agent_prefix()` instead.
192  ClientOptions& add_user_agent_prefx(std::string const& v) {
193  return add_user_agent_prefix(v);
194  }
195 
196  std::size_t maximum_simple_upload_size() const {
198  }
201  return *this;
202  }
203 
204  /**
205  * If true and using OpenSSL 1.0.2 the library configures the OpenSSL
206  * callbacks for locking.
207  */
210  }
213  return *this;
214  }
215 
216  bool enable_sigpipe_handler() const {
218  }
221  return *this;
222  }
223 
224  std::size_t maximum_socket_recv_size() const {
226  }
229  return *this;
230  }
231 
232  std::size_t maximum_socket_send_size() const {
234  }
237  return *this;
238  }
239 
240  ChannelOptions& channel_options() { return channel_options_; }
241  ChannelOptions const& channel_options() const { return channel_options_; }
242 
243  //@{
244  /**
245  * Control the maximum amount of time allowed for "stalls" during a download.
246  *
247  * A download that receives no data is considered "stalled". If the download
248  * remains stalled for more than the time set in this option then the download
249  * is aborted.
250  *
251  * The default value is 2 minutes. Can be disabled by setting the value to 0.
252  */
253  std::chrono::seconds download_stall_timeout() const {
255  }
256  ClientOptions& set_download_stall_timeout(std::chrono::seconds v) {
257  opts_.set<TransferStallTimeoutOption>(std::move(v));
258  return *this;
259  }
260  //@}
261 
262  private:
263  friend Options internal::MakeOptions(ClientOptions);
264  friend ClientOptions internal::MakeBackwardsCompatibleClientOptions(Options);
265 
266  explicit ClientOptions(Options o);
267 
268  Options opts_;
269 
270  // Used for backwards compatibility. The value here is merged with the values
271  // in `opts_` by internal::MakeOptions(ClientOptions const&);
272  ChannelOptions channel_options_;
273 
274  // Only used for backwards compatibility, the value in `opts_.
275  std::string user_agent_prefix_;
276 };
277 
278 } // namespace STORAGE_CLIENT_NS
279 } // namespace storage
280 } // namespace cloud
281 } // namespace google
282 
283 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_STORAGE_CLIENT_OPTIONS_H