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