1 // Copyright 2012 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_LIST_H_ 6 #define NET_PROXY_RESOLUTION_PROXY_LIST_H_ 7 8 #include <stddef.h> 9 10 #include <memory> 11 #include <string> 12 #include <vector> 13 14 #include "net/base/net_export.h" 15 #include "net/base/proxy_server.h" 16 #include "net/proxy_resolution/proxy_retry_info.h" 17 #include "third_party/abseil-cpp/absl/types/optional.h" 18 19 namespace base { 20 class TimeDelta; 21 class Value; 22 } 23 24 namespace net { 25 26 class ProxyChain; 27 class NetLogWithSource; 28 29 // This class is used to hold a prioritized list of proxy chains. It handles 30 // fallback to lower-priority chains if multiple chains are specified. 31 // 32 // TODO(crbug.com/1491092): For compatibility until proxy chains are used 33 // everywhere, this class can also provide a list of ProxyServers only when 34 // there are no multi-proxy chains in the list. This support will be removed. 35 class NET_EXPORT_PRIVATE ProxyList { 36 public: 37 ProxyList(); 38 ProxyList(const ProxyList& other); 39 ProxyList(ProxyList&& other); 40 ProxyList& operator=(const ProxyList& other); 41 ProxyList& operator=(ProxyList&& other); 42 ~ProxyList(); 43 44 // Initializes the ProxyList to contain one or more ProxyChains. 45 // `proxy_uri_list` is a semicolon-delimited list of proxy URIs. Note that 46 // multi-proxy chains cannot be represented in this format. 47 void Set(const std::string& proxy_uri_list); 48 49 // Set the proxy list to a single entry, |proxy_chain|. 50 void SetSingleProxyChain(const ProxyChain& proxy_chain); 51 52 // Set the proxy list to a single entry, a chain containing |proxy_server|. 53 void SetSingleProxyServer(const ProxyServer& proxy_server); 54 55 // Append a single proxy chain to the end of the proxy list. 56 void AddProxyChain(const ProxyChain& proxy_chain); 57 58 // Append a single proxy chain containing the given server to the end of the 59 // proxy list. 60 void AddProxyServer(const ProxyServer& proxy_server); 61 62 // De-prioritizes the proxy chains that are cached as not working but are 63 // allowed to be reconsidered, by moving them to the end of the fallback list. 64 void DeprioritizeBadProxyChains(const ProxyRetryInfoMap& proxy_retry_info); 65 66 // Deletes all chains which don't exclusively consist of proxy servers with 67 // the specified schemes. `scheme_bit_field` is a bunch of 68 // `ProxyServer::Scheme` bitwise ORed together. This is used to remove proxies 69 // that do not support specific functionality such as websockets. 70 void RemoveProxiesWithoutScheme(int scheme_bit_field); 71 72 // Clear the proxy list. 73 void Clear(); 74 75 // Returns true if there is nothing left in the ProxyList. 76 bool IsEmpty() const; 77 78 // Returns the number of proxy servers in this list. 79 size_t size() const; 80 81 // Returns true if |*this| lists the same proxies as |other|. 82 bool Equals(const ProxyList& other) const; 83 84 // Returns the first proxy chain in the list. 85 const ProxyChain& First() const; 86 87 // Returns all proxy servers in the list. It is only valid to call this 88 // if no chain in the list is multi-proxy. 89 // TODO(crbug.com/1491092): Remove this method in favor of `AllChains()`. 90 std::vector<ProxyServer> GetAll() const; 91 92 // Returns all proxy chains in the list. 93 const std::vector<ProxyChain>& AllChains() const; 94 95 // Sets the list by parsing the PAC result |pac_string|. 96 // Some examples for |pac_string|: 97 // "DIRECT" 98 // "PROXY foopy1" 99 // "PROXY foopy1; SOCKS4 foopy2:1188" 100 // Does a best-effort parse, and silently discards any errors. 101 void SetFromPacString(const std::string& pac_string); 102 103 // Returns a PAC-style semicolon-separated list of valid proxy servers. 104 // For example: "PROXY xxx.xxx.xxx.xxx:xx; SOCKS yyy.yyy.yyy:yy". This is 105 // only valid if the list contains no multi-proxy chains, as those cannot 106 // be represented in PAC syntax. 107 std::string ToPacString() const; 108 109 // Returns a semicolon-separated list of proxy chain debug representations. 110 // For single-proxy chains, this is just the PAC representation of the proxy; 111 // otherwise the chain is displayed in `[..]`. 112 std::string ToDebugString() const; 113 114 // Returns a serialized value for the list. 115 base::Value ToValue() const; 116 117 // Marks the current proxy chain as bad and deletes it from the list. The 118 // list of known bad proxies is given by |proxy_retry_info|. |net_error| 119 // should contain the network error encountered when this proxy chain was 120 // tried, if any. If this fallback is not because of a network error, then 121 // |OK| should be passed in (eg. for reasons such as local policy). Returns 122 // true if there is another chain available in the list. 123 bool Fallback(ProxyRetryInfoMap* proxy_retry_info, 124 int net_error, 125 const NetLogWithSource& net_log); 126 127 // Updates |proxy_retry_info| to indicate that the first proxy chain in the 128 // list is bad. This is distinct from Fallback(), above, to allow updating 129 // proxy retry information without modifying a given transction's proxy list. 130 // Will retry after |retry_delay| if positive, and will use the default proxy 131 // retry duration otherwise. It may reconsider the proxy beforehand if 132 // |reconsider| is true. Additionally updates |proxy_retry_info| with 133 // |additional_proxies_to_bypass|. |net_error| should contain the network 134 // error countered when this proxy chain was tried, or OK if the proxy retry 135 // info is being updated for a non-network related reason (e.g. local policy). 136 void UpdateRetryInfoOnFallback( 137 ProxyRetryInfoMap* proxy_retry_info, 138 base::TimeDelta retry_delay, 139 bool reconsider, 140 const std::vector<ProxyChain>& additional_proxies_to_bypass, 141 int net_error, 142 const NetLogWithSource& net_log) const; 143 144 private: 145 // Updates |proxy_retry_info| to indicate that the |proxy_to_retry| in 146 // |proxies_| is bad for |retry_delay|, but may be reconsidered earlier if 147 // |try_while_bad| is true. |net_error| should contain the network error 148 // countered when this proxy was tried, or OK if the proxy retry info is 149 // being updated for a non-network related reason (e.g. local policy). 150 void AddProxyChainToRetryList(ProxyRetryInfoMap* proxy_retry_info, 151 base::TimeDelta retry_delay, 152 bool try_while_bad, 153 const ProxyChain& proxy_chain_to_retry, 154 int net_error, 155 const NetLogWithSource& net_log) const; 156 157 // List of proxy chains. 158 std::vector<ProxyChain> proxy_chains_; 159 }; 160 161 } // namespace net 162 163 #endif // NET_PROXY_RESOLUTION_PROXY_LIST_H_ 164