proxy_resolution_service.h 5.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115
  1. // Copyright 2020 The Chromium Authors. All rights reserved.
  2. // Use of this source code is governed by a BSD-style license that can be
  3. // found in the LICENSE file.
  4. #ifndef NET_PROXY_RESOLUTION_PROXY_RESOLUTION_SERVICE_H_
  5. #define NET_PROXY_RESOLUTION_PROXY_RESOLUTION_SERVICE_H_
  6. #include <memory>
  7. #include <string>
  8. #include "base/time/time.h"
  9. #include "net/base/completion_once_callback.h"
  10. #include "net/base/net_export.h"
  11. #include "net/base/network_isolation_key.h"
  12. #include "net/base/proxy_server.h"
  13. #include "net/log/net_log_with_source.h"
  14. #include "net/proxy_resolution/proxy_info.h"
  15. #include "url/gurl.h"
  16. namespace net {
  17. class ConfiguredProxyResolutionService;
  18. class ProxyDelegate;
  19. class ProxyResolutionRequest;
  20. // This is a generic interface that is used to decide which proxy server(s) to
  21. // use for a particular URL request. The typical consumer of the
  22. // ProxyResolutionService does not need to know how we decide on the right proxy
  23. // for that network request.
  24. class NET_EXPORT ProxyResolutionService {
  25. public:
  26. virtual ~ProxyResolutionService() = default;
  27. // Determines the appropriate proxy for |url| for a |method| request and
  28. // stores the result in |results|. If |method| is empty, the caller can expect
  29. // method independent resolution.
  30. //
  31. // Returns ERR_IO_PENDING if the proxy information could not be provided
  32. // synchronously, to indicate that the result will be available when the
  33. // callback is run. The callback is run on the thread that calls
  34. // ResolveProxy.
  35. //
  36. // The caller is responsible for ensuring that |results| and |callback|
  37. // remain valid until the callback is run or until |request| is cancelled,
  38. // which occurs when the unique pointer to it is deleted (by leaving scope or
  39. // otherwise). |request| must not be nullptr.
  40. //
  41. // Profiling information for the request is saved to |net_log| if non-nullptr.
  42. virtual int ResolveProxy(const GURL& url,
  43. const std::string& method,
  44. const NetworkIsolationKey& network_isolation_key,
  45. ProxyInfo* results,
  46. CompletionOnceCallback callback,
  47. std::unique_ptr<ProxyResolutionRequest>* request,
  48. const NetLogWithSource& net_log) = 0;
  49. // Called to report that the last proxy connection succeeded. If |proxy_info|
  50. // has a non empty proxy_retry_info map, the proxies that have been tried (and
  51. // failed) for this request will be marked as bad.
  52. virtual void ReportSuccess(const ProxyInfo& proxy_info) = 0;
  53. // Associates a delegate with this ProxyResolutionService. |delegate|
  54. // must outlive |this|.
  55. // TODO(eroman): Specify this as a dependency at construction time rather
  56. // than making it a mutable property.
  57. virtual void SetProxyDelegate(ProxyDelegate* delegate) = 0;
  58. // Cancels all network requests, and prevents the service from creating new
  59. // ones. Must be called before the URLRequestContext the
  60. // ProxyResolutionService was created with is torn down, if it's torn down
  61. // before the ProxyResolutionService itself.
  62. virtual void OnShutdown() = 0;
  63. // Explicitly trigger proxy fallback for the given |results| by updating our
  64. // list of bad proxies to include the first entry of |results|, and,
  65. // additional bad proxies (can be none). Will retry after |retry_delay| if
  66. // positive, and will use the default proxy retry duration otherwise. Proxies
  67. // marked as bad will not be retried until |retry_delay| has passed. Returns
  68. // true if there will be at least one proxy remaining in the list after
  69. // fallback and false otherwise. This method should be used to add proxies to
  70. // the bad proxy list only for reasons other than a network error.
  71. virtual bool MarkProxiesAsBadUntil(
  72. const ProxyInfo& results,
  73. base::TimeDelta retry_delay,
  74. const std::vector<ProxyServer>& additional_bad_proxies,
  75. const NetLogWithSource& net_log) = 0;
  76. // Clears the list of bad proxy servers that has been cached.
  77. virtual void ClearBadProxiesCache() = 0;
  78. // Returns the map of proxies which have been marked as "bad".
  79. virtual const ProxyRetryInfoMap& proxy_retry_info() const = 0;
  80. // Returns proxy related debug information to be included in the NetLog. The
  81. // data should be appropriate for any capture mode (sensitivity level).
  82. virtual base::Value::Dict GetProxyNetLogValues() = 0;
  83. // Returns true if |this| is an instance of ConfiguredProxyResolutionService
  84. // and assigns |this| to the out parameter. Otherwise returns false and sets
  85. // |*configured_proxy_resolution_service| to nullptr.
  86. //
  87. // In general, consumers of the ProxyResolutionService should exclusively
  88. // interact with the general ProxyResolutionService. In some isolated
  89. // instances, a consumer may specifically need to interact with an underlying
  90. // implementation. For example, one might need to fetch the set of proxy
  91. // configurations determined by the proxy, something which not all
  92. // implementations of the ProxyResolutionService would have an answer for.
  93. [[nodiscard]] virtual bool CastToConfiguredProxyResolutionService(
  94. ConfiguredProxyResolutionService**
  95. configured_proxy_resolution_service) = 0;
  96. };
  97. } // namespace net
  98. #endif // NET_PROXY_RESOLUTION_PROXY_RESOLUTION_SERVICE_H_