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 // Clears the list of bad proxy servers that has been cached. 76 virtual void ClearBadProxiesCache() = 0; 77 78 // Returns the map of proxies which have been marked as "bad". 79 virtual const ProxyRetryInfoMap& proxy_retry_info() const = 0; 80 81 // Returns proxy related debug information to be included in the NetLog. The 82 // data should be appropriate for any capture mode (sensitivity level). 83 virtual base::Value::Dict GetProxyNetLogValues() = 0; 84 85 // Returns true if |this| is an instance of ConfiguredProxyResolutionService 86 // and assigns |this| to the out parameter. Otherwise returns false and sets 87 // |*configured_proxy_resolution_service| to nullptr. 88 // 89 // In general, consumers of the ProxyResolutionService should exclusively 90 // interact with the general ProxyResolutionService. In some isolated 91 // instances, a consumer may specifically need to interact with an underlying 92 // implementation. For example, one might need to fetch the set of proxy 93 // configurations determined by the proxy, something which not all 94 // implementations of the ProxyResolutionService would have an answer for. 95 [[nodiscard]] virtual bool CastToConfiguredProxyResolutionService( 96 ConfiguredProxyResolutionService** 97 configured_proxy_resolution_service) = 0; 98 }; 99 100 } // namespace net 101 102 #endif // NET_PROXY_RESOLUTION_PROXY_RESOLUTION_SERVICE_H_ 103