azure-core
Loading...
Searching...
No Matches
policy.hpp
Go to the documentation of this file.
1// Copyright (c) Microsoft Corporation.
2// Licensed under the MIT License.
3
9#pragma once
10
14#include "azure/core/dll_import_export.hpp"
17#include "azure/core/internal/http/http_sanitizer.hpp"
18#include "azure/core/uuid.hpp"
19
20#include <atomic>
21#include <chrono>
22#include <cstddef>
23#include <map>
24#include <memory>
25#include <mutex>
26#include <set>
27#include <shared_mutex>
28#include <string>
29#include <utility>
30#include <vector>
31
39extern std::shared_ptr<Azure::Core::Http::HttpTransport> AzureSdkGetCustomHttpTransport();
40
41namespace Azure { namespace Core { namespace Http { namespace Policies {
42
43 struct TransportOptions;
44 namespace _detail {
45 std::shared_ptr<HttpTransport> GetTransportAdapter(TransportOptions const& transportOptions);
46
47 AZ_CORE_DLLEXPORT extern std::set<std::string> const g_defaultAllowedHttpQueryParameters;
48 AZ_CORE_DLLEXPORT extern CaseInsensitiveSet const g_defaultAllowedHttpHeaders;
49 } // namespace _detail
50
51 namespace _internal {
52 class TelemetryPolicy;
53 }
54
59 struct TelemetryOptions final
60 {
68 std::string ApplicationId;
69
74 std::shared_ptr<Azure::Core::Tracing::TracerProvider> TracingProvider;
75
76 private:
77 // The friend declaration is needed so that TelemetryPolicy could access CppStandardVersion,
78 // and it is not a struct's public field like the ones above to be set non-programmatically.
79 // When building the SDK, tests, or samples, the value of __cplusplus is ultimately controlled
80 // by the cmake files in this repo (i.e. C++14), therefore we set distinct values of 0, -1, etc
81 // when it is the case.
82 friend class _internal::TelemetryPolicy;
83 long CppStandardVersion =
84#if defined(_azure_BUILDING_SDK)
85 -2L
86#elif defined(_azure_BUILDING_TESTS)
87 -1L
88#elif defined(_azure_BUILDING_SAMPLES)
89 0L
90#else
91 // https://devblogs.microsoft.com/cppblog/msvc-now-correctly-reports-__cplusplus/
92#if defined(_MSVC_LANG) && __cplusplus == 199711L
93 _MSVC_LANG
94#else
95 __cplusplus
96#endif
97#endif
98 ;
99 };
100
107 struct RetryOptions final
108 {
113 int32_t MaxRetries = 3;
114
120 std::chrono::milliseconds RetryDelay = std::chrono::milliseconds(800);
121
127 std::chrono::milliseconds MaxRetryDelay = std::chrono::seconds(60);
128
133 std::set<HttpStatusCode> StatusCodes{
134 HttpStatusCode::RequestTimeout,
135 HttpStatusCode::InternalServerError,
136 HttpStatusCode::BadGateway,
137 HttpStatusCode::ServiceUnavailable,
138 HttpStatusCode::GatewayTimeout,
139 };
140 };
141
147 struct LogOptions final
148 {
153 std::set<std::string> AllowedHttpQueryParameters = _detail::g_defaultAllowedHttpQueryParameters;
154
159 CaseInsensitiveSet AllowedHttpHeaders = _detail::g_defaultAllowedHttpHeaders;
160 };
161
165 struct TransportOptions final
166 {
177
185
193
203
216
229
248 std::shared_ptr<HttpTransport> Transport;
249 };
250
251 class NextHttpPolicy;
252
260 public:
261 // If we get a response that goes up the stack
262 // Any errors in the pipeline throws an exception
263 // At the top of the pipeline we might want to turn certain responses into exceptions
264
275 virtual std::unique_ptr<RawResponse> Send(
276 Request& request,
277 NextHttpPolicy nextPolicy,
278 Context const& context) const = 0;
279
284 virtual ~HttpPolicy() {}
285
290 virtual std::unique_ptr<HttpPolicy> Clone() const = 0;
291
292 protected:
297 HttpPolicy() = default;
298
304 HttpPolicy(const HttpPolicy& other) = default;
305
312 HttpPolicy& operator=(const HttpPolicy& other) = default;
313
319 HttpPolicy(HttpPolicy&& other) = default;
320 };
321
331 class NextHttpPolicy final {
332 const size_t m_index;
333 const std::vector<std::unique_ptr<HttpPolicy>>& m_policies;
334
335 public:
344 explicit NextHttpPolicy(size_t index, const std::vector<std::unique_ptr<HttpPolicy>>& policies)
345 : m_index(index), m_policies(policies)
346 {
347 }
348
358 std::unique_ptr<RawResponse> Send(Request& request, Context const& context);
359 };
360
361 namespace _internal {
362
367 class TransportPolicy final : public HttpPolicy {
368 private:
369 TransportOptions m_options;
370
371 public:
377 explicit TransportPolicy(TransportOptions const& options = TransportOptions());
378
379 std::unique_ptr<HttpPolicy> Clone() const override
380 {
381 return std::make_unique<TransportPolicy>(*this);
382 }
383
384 std::unique_ptr<RawResponse> Send(
385 Request& request,
386 NextHttpPolicy nextPolicy,
387 Context const& context) const override;
388 };
389
393 class RetryPolicy
394#if !defined(_azure_TESTING_BUILD)
395 final
396#endif
397 : public HttpPolicy {
398 private:
399 RetryOptions m_retryOptions;
400
401 public:
407 explicit RetryPolicy(RetryOptions options) : m_retryOptions(std::move(options)) {}
408
409 std::unique_ptr<HttpPolicy> Clone() const override
410 {
411 return std::make_unique<RetryPolicy>(*this);
412 }
413
414 std::unique_ptr<RawResponse> Send(
415 Request& request,
416 NextHttpPolicy nextPolicy,
417 Context const& context) const final;
418
430 static int32_t GetRetryCount(Context const& context);
431
432 protected:
433 virtual bool ShouldRetryOnTransportFailure(
434 RetryOptions const& retryOptions,
435 int32_t attempt,
436 std::chrono::milliseconds& retryAfter,
437 double jitterFactor = -1) const;
438
439 virtual bool ShouldRetryOnResponse(
440 RawResponse const& response,
441 RetryOptions const& retryOptions,
442 int32_t attempt,
443 std::chrono::milliseconds& retryAfter,
444 double jitterFactor = -1) const;
445 };
446
453 class RequestIdPolicy final : public HttpPolicy {
454 private:
455 constexpr static const char* RequestIdHeader = "x-ms-client-request-id";
456
457 public:
462 explicit RequestIdPolicy() {}
463
464 std::unique_ptr<HttpPolicy> Clone() const override
465 {
466 return std::make_unique<RequestIdPolicy>(*this);
467 }
468
469 std::unique_ptr<RawResponse> Send(
470 Request& request,
471 NextHttpPolicy nextPolicy,
472 Context const& context) const override
473 {
474 if (!request.GetHeader(RequestIdHeader).HasValue())
475 {
476 auto const uuid = Uuid::CreateUuid().ToString();
477 request.SetHeader(RequestIdHeader, uuid);
478 }
479
480 return nextPolicy.Send(request, context);
481 }
482 };
483
492 class RequestActivityPolicy final : public HttpPolicy {
493 private:
494 Azure::Core::Http::_internal::HttpSanitizer m_httpSanitizer;
495
496 public:
500 // explicit RequestActivityPolicy() = default;
506 explicit RequestActivityPolicy(
507 Azure::Core::Http::_internal::HttpSanitizer const& httpSanitizer)
508 : m_httpSanitizer(httpSanitizer)
509 {
510 }
511
512 std::unique_ptr<HttpPolicy> Clone() const override
513 {
514 return std::make_unique<RequestActivityPolicy>(*this);
515 }
516
517 std::unique_ptr<RawResponse> Send(
518 Request& request,
519 NextHttpPolicy nextPolicy,
520 Context const& context) const override;
521 };
522
536 class TelemetryPolicy final : public HttpPolicy {
537 private:
538 std::string const m_telemetryId;
539
540 public:
548 explicit TelemetryPolicy(
549 std::string const& packageName,
550 std::string const& packageVersion,
551 TelemetryOptions options = TelemetryOptions())
552 : m_telemetryId(Azure::Core::Http::_internal::HttpShared::GenerateUserAgent(
553 packageName,
554 packageVersion,
555 options.ApplicationId,
556 options.CppStandardVersion))
557 {
558 }
559
560 std::unique_ptr<HttpPolicy> Clone() const override
561 {
562 return std::make_unique<TelemetryPolicy>(*this);
563 }
564
565 std::unique_ptr<RawResponse> Send(
566 Request& request,
567 NextHttpPolicy nextPolicy,
568 Context const& context) const override;
569 };
570
575 class BearerTokenAuthenticationPolicy : public HttpPolicy {
576 private:
577 std::shared_ptr<Credentials::TokenCredential const> const m_credential;
578 Credentials::TokenRequestContext m_tokenRequestContext;
579
580 mutable Credentials::AccessToken m_accessToken;
581 mutable std::shared_timed_mutex m_accessTokenMutex;
582 mutable Credentials::TokenRequestContext m_accessTokenContext;
583 mutable std::atomic<bool> m_invalidateToken = {false};
584
585 public:
592 explicit BearerTokenAuthenticationPolicy(
593 std::shared_ptr<Credentials::TokenCredential const> credential,
594 Credentials::TokenRequestContext tokenRequestContext)
595 : m_credential(std::move(credential)),
596 m_tokenRequestContext(std::move(tokenRequestContext))
597 {
598 }
599
600 std::unique_ptr<HttpPolicy> Clone() const override
601 {
602 // Can't use std::make_shared here because copy constructor is not public.
603 return std::unique_ptr<HttpPolicy>(new BearerTokenAuthenticationPolicy(*this));
604 }
605
606 std::unique_ptr<RawResponse> Send(
607 Request& request,
608 NextHttpPolicy nextPolicy,
609 Context const& context) const override;
610
611 protected:
612 BearerTokenAuthenticationPolicy(BearerTokenAuthenticationPolicy const& other)
613 : BearerTokenAuthenticationPolicy(other.m_credential, other.m_tokenRequestContext)
614 {
615 std::shared_lock<std::shared_timed_mutex> readLock(other.m_accessTokenMutex);
616 m_accessToken = other.m_accessToken;
617 m_accessTokenContext = other.m_accessTokenContext;
618 m_invalidateToken.store(other.m_invalidateToken.load());
619 }
620
621 void operator=(BearerTokenAuthenticationPolicy const&) = delete;
622
623 virtual std::unique_ptr<RawResponse> AuthorizeAndSendRequest(
624 Request& request,
625 NextHttpPolicy& nextPolicy,
626 Context const& context) const;
627
628 virtual bool AuthorizeRequestOnChallenge(
629 std::string const& challenge,
630 Request& request,
631 Context const& context) const;
632
633 void AuthenticateAndAuthorizeRequest(
634 Request& request,
635 Credentials::TokenRequestContext const& tokenRequestContext,
636 Context const& context) const;
637 };
638
645 class LogPolicy final : public HttpPolicy {
646 LogOptions m_options;
647 Azure::Core::Http::_internal::HttpSanitizer m_httpSanitizer;
648
649 public:
654 explicit LogPolicy(LogOptions options)
655 : m_options(std::move(options)),
656 m_httpSanitizer(m_options.AllowedHttpQueryParameters, m_options.AllowedHttpHeaders)
657 {
658 }
659
660 std::unique_ptr<HttpPolicy> Clone() const override
661 {
662 return std::make_unique<LogPolicy>(*this);
663 }
664
665 std::unique_ptr<RawResponse> Send(
666 Request& request,
667 NextHttpPolicy nextPolicy,
668 Context const& context) const override;
669 };
670 } // namespace _internal
671}}}} // namespace Azure::Core::Http::Policies
A map<string, string> with case-insensitive key comparison.
std::set< std::string, _internal::StringExtensions::CaseInsensitiveComparator > CaseInsensitiveSet
A type alias of std::set<std::string> with case-insensitive element comparison.
Definition case_insensitive_containers.hpp:31
A context is a node within a unidirectional tree that represents deadlines and key/value pairs.
Definition context.hpp:72
HTTP policy base class.
Definition policy.hpp:259
virtual ~HttpPolicy()
Destructs HttpPolicy.
Definition policy.hpp:284
HttpPolicy()=default
Constructs a default instance of HttpPolicy.
HttpPolicy & operator=(const HttpPolicy &other)=default
Assigns this HttpPolicy to copy the other.
virtual std::unique_ptr< HttpPolicy > Clone() const =0
Creates a clone of this HttpPolicy.
HttpPolicy(HttpPolicy &&other)=default
Constructs HttpPolicy by moving other HttpPolicy.
HttpPolicy(const HttpPolicy &other)=default
Constructs a copy of other HttpPolicy.
virtual std::unique_ptr< RawResponse > Send(Request &request, NextHttpPolicy nextPolicy, Context const &context) const =0
Applies this HTTP policy.
The next HTTP policy in the stack sequence of policies.
Definition policy.hpp:331
NextHttpPolicy(size_t index, const std::vector< std::unique_ptr< HttpPolicy > > &policies)
Constructs an abstraction representing a next line in the stack sequence of policies,...
Definition policy.hpp:344
std::unique_ptr< RawResponse > Send(Request &request, Context const &context)
Applies this HTTP policy.
Definition policy.cpp:14
A request message from a client to a server.
Definition http.hpp:182
std::string ToString() const
Gets Uuid as a string.
Definition uuid.cpp:66
static Uuid CreateUuid()
Creates a new random UUID.
Definition uuid.cpp:134
Manages an optional contained value, i.e. a value that may or may not be present.
Definition nullable.hpp:30
Context for canceling long running operations.
Credentials used for authentication with many (not all) Azure SDK client libraries.
HTTP request and response functionality.
Compute the hash value for the input binary data, using SHA256, SHA384 and SHA512.
Definition azure_assert.hpp:57
std::shared_ptr< Azure::Core::Http::HttpTransport > AzureSdkGetCustomHttpTransport()
Log options that parameterize the information being logged.
Definition policy.hpp:148
std::set< std::string > AllowedHttpQueryParameters
HTTP query parameter names that are allowed to be logged.
Definition policy.hpp:153
CaseInsensitiveSet AllowedHttpHeaders
HTTP header names that are allowed to be logged.
Definition policy.hpp:159
The set of options that can be specified to influence how retry attempts are made,...
Definition policy.hpp:108
std::chrono::milliseconds RetryDelay
The minimum permissible delay between retry attempts.
Definition policy.hpp:120
int32_t MaxRetries
The maximum number of retry attempts before giving up.
Definition policy.hpp:113
std::chrono::milliseconds MaxRetryDelay
The maximum permissible delay between retry attempts.
Definition policy.hpp:127
std::set< HttpStatusCode > StatusCodes
The HTTP status codes that indicate when an operation should be retried.
Definition policy.hpp:133
Telemetry options, used to configure telemetry parameters.
Definition policy.hpp:60
std::string ApplicationId
The Application ID is the last part of the user agent for telemetry.
Definition policy.hpp:68
std::shared_ptr< Azure::Core::Tracing::TracerProvider > TracingProvider
Specifies the default distributed tracing provider to use for this client. By default,...
Definition policy.hpp:74
HTTP transport options parameterize the HTTP transport adapter being used.
Definition policy.hpp:166
bool DisableTlsCertificateValidation
Disable SSL/TLS certificate verification. This option allows transport layer to perform insecure SSL/...
Definition policy.hpp:215
std::shared_ptr< HttpTransport > Transport
Azure::Core::Http::HttpTransport that the transport policy will use to send and receive requests and ...
Definition policy.hpp:248
Azure::Nullable< std::string > ProxyPassword
The password to use when authenticating with the proxy server.
Definition policy.hpp:192
bool EnableCertificateRevocationListCheck
Enable TLS Certificate validation against a certificate revocation list.
Definition policy.hpp:202
std::string ExpectedTlsRootCertificate
Base64 encoded DER representation of an X.509 certificate expected in the certificate chain used in T...
Definition policy.hpp:228
Azure::Nullable< std::string > HttpProxy
The URL for the proxy server to use for this connection.
Definition policy.hpp:176
Azure::Nullable< std::string > ProxyUserName
The username to use when authenticating with the proxy server.
Definition policy.hpp:184
Utilities to be used by HTTP transport implementations.
Universally unique identifier.