net/proxy/proxy_config.h

   1 // Copyright (c) 2012 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
   5 #ifndef NET_PROXY_PROXY_CONFIG_H_
   6 #define NET_PROXY_PROXY_CONFIG_H_
   7
   8 #include <string>
   9
  10 #include "net/base/net_export.h"
  11 #include "net/proxy/proxy_bypass_rules.h"
  12 #include "net/proxy/proxy_config_source.h"
  13 #include "net/proxy/proxy_list.h"
  14 #include "net/proxy/proxy_server.h"
  15 #include "url/gurl.h"
  16
  17 namespace base {
  18 class Value;
  19 }
  20
  21 namespace net {
  22
  23 class ProxyInfo;
  24
  25 // ProxyConfig describes a user's proxy settings.
  26 //
  27 // There are two categories of proxy settings:
  28 //   (1) Automatic (indicates the methods to obtain a PAC script)
  29 //   (2) Manual (simple set of proxy servers per scheme, and bypass patterns)
  30 //
  31 // When both automatic and manual settings are specified, the Automatic ones
  32 // take precedence over the manual ones.
  33 //
  34 // For more details see:
  35 // http://www.chromium.org/developers/design-documents/proxy-settings-fallback
  36 class NET_EXPORT ProxyConfig {
  37  public:
  38   // ProxyRules describes the "manual" proxy settings.
  39   // TODO(eroman): Turn this into a class.
  40   // TODO(marq): Update the enum names; "TYPE_SINGLE_PROXY" really means
  41   //             the same set of proxies are used for all requests.
  42   struct NET_EXPORT ProxyRules {
  43     enum Type {
  44       TYPE_NO_RULES,
  45       TYPE_SINGLE_PROXY,
  46       TYPE_PROXY_PER_SCHEME,
  47     };
  48
  49     // Note that the default of TYPE_NO_RULES results in direct connections
  50     // being made when using this ProxyConfig.
  51     ProxyRules();
  52     ~ProxyRules();
  53
  54     bool empty() const {
  55       return type == TYPE_NO_RULES;
  56     }
  57
  58     // Sets |result| with the proxies to use for |url| based on the current
  59     // rules.
  60     void Apply(const GURL& url, ProxyInfo* result) const;
  61
  62     // Parses the rules from a string, indicating which proxies to use.
  63     //
  64     //   proxy-uri = [<proxy-scheme>"://"]<proxy-host>[":"<proxy-port>]
  65     //
  66     //   proxy-uri-list = <proxy-uri>[","<proxy-uri-list>]
  67     //
  68     //   url-scheme = "http" | "https" | "ftp" | "socks"
  69     //
  70     //   scheme-proxies = [<url-scheme>"="]<proxy-uri-list>
  71     //
  72     //   proxy-rules = scheme-proxies[";"<scheme-proxies>]
  73     //
  74     // Thus, the proxy-rules string should be a semicolon-separated list of
  75     // ordered proxies that apply to a particular URL scheme. Unless specified,
  76     // the proxy scheme for proxy-uris is assumed to be http.
  77     //
  78     // Some special cases:
  79     //  * If the scheme is omitted from the first proxy list, that list applies
  80     //    to all URL schemes and subsequent lists are ignored.
  81     //  * If a scheme is omitted from any proxy list after a list where a scheme
  82     //    has been provided, the list without a scheme is ignored.
  83     //  * If the url-scheme is set to 'socks', that sets a fallback list that
  84     //    to all otherwise unspecified url-schemes, however the default proxy-
  85     //    scheme for proxy urls in the 'socks' list is understood to be
  86     //    socks4:// if unspecified.
  87     //
  88     // For example:
  89     //   "http=foopy:80;ftp=foopy2"  -- use HTTP proxy "foopy:80" for http://
  90     //                                  URLs, and HTTP proxy "foopy2:80" for
  91     //                                  ftp:// URLs.
  92     //   "foopy:80"                  -- use HTTP proxy "foopy:80" for all URLs.
  93     //   "foopy:80,bar,direct://"    -- use HTTP proxy "foopy:80" for all URLs,
  94     //                                  failing over to "bar" if "foopy:80" is
  95     //                                  unavailable, and after that using no
  96     //                                  proxy.
  97     //   "socks4://foopy"            -- use SOCKS v4 proxy "foopy:1080" for all
  98     //                                  URLs.
  99     //   "http=foop,socks5://bar.com -- use HTTP proxy "foopy" for http URLs,
 100     //                                  and fail over to the SOCKS5 proxy
 101     //                                  "bar.com" if "foop" is unavailable.
 102     //   "http=foopy,direct://       -- use HTTP proxy "foopy" for http URLs,
 103     //                                  and use no proxy if "foopy" is
 104     //                                  unavailable.
 105     //   "http=foopy;socks=foopy2   --  use HTTP proxy "foopy" for http URLs,
 106     //                                  and use socks4://foopy2 for all other
 107     //                                  URLs.
 108     void ParseFromString(const std::string& proxy_rules);
 109
 110     // Returns one of {&proxies_for_http, &proxies_for_https, &proxies_for_ftp,
 111     // &fallback_proxies}, or NULL if there is no proxy to use.
 112     // Should only call this if the type is TYPE_PROXY_PER_SCHEME.
 113     const ProxyList* MapUrlSchemeToProxyList(
 114         const std::string& url_scheme) const;
 115
 116     // Returns true if |*this| describes the same configuration as |other|.
 117     bool Equals(const ProxyRules& other) const;
 118
 119     // Exceptions for when not to use a proxy.
 120     ProxyBypassRules bypass_rules;
 121
 122     // Reverse the meaning of |bypass_rules|.
 123     bool reverse_bypass;
 124
 125     Type type;
 126
 127     // Set if |type| is TYPE_SINGLE_PROXY.
 128     ProxyList single_proxies;
 129
 130     // Set if |type| is TYPE_PROXY_PER_SCHEME.
 131     ProxyList proxies_for_http;
 132     ProxyList proxies_for_https;
 133     ProxyList proxies_for_ftp;
 134
 135     // Used when a fallback has been defined and the url to be proxied doesn't
 136     // match any of the standard schemes.
 137     ProxyList fallback_proxies;
 138
 139    private:
 140     // Returns one of {&proxies_for_http, &proxies_for_https, &proxies_for_ftp}
 141     // or NULL if it is a scheme that we don't have a mapping
 142     // for. Should only call this if the type is TYPE_PROXY_PER_SCHEME.
 143     ProxyList* MapUrlSchemeToProxyListNoFallback(const std::string& scheme);
 144   };
 145
 146   typedef int ID;
 147
 148   // Indicates an invalid proxy config.
 149   static const ID kInvalidConfigID = 0;
 150
 151   ProxyConfig();
 152   ProxyConfig(const ProxyConfig& config);
 153   ~ProxyConfig();
 154   ProxyConfig& operator=(const ProxyConfig& config);
 155
 156   // Used to numerically identify this configuration.
 157   ID id() const { return id_; }
 158   void set_id(ID id) { id_ = id; }
 159   bool is_valid() const { return id_ != kInvalidConfigID; }
 160
 161   // Returns true if the given config is equivalent to this config.  The
 162   // comparison ignores differences in |id()| and |source()|.
 163   bool Equals(const ProxyConfig& other) const;
 164
 165   // Returns true if this config contains any "automatic" settings. See the
 166   // class description for what that means.
 167   bool HasAutomaticSettings() const;
 168
 169   void ClearAutomaticSettings();
 170
 171   // Creates a Value dump of this configuration. The caller is responsible for
 172   // deleting the returned value.
 173   base::DictionaryValue* ToValue() const;
 174
 175   ProxyRules& proxy_rules() {
 176     return proxy_rules_;
 177   }
 178
 179   const ProxyRules& proxy_rules() const {
 180     return proxy_rules_;
 181   }
 182
 183   void set_pac_url(const GURL& url) {
 184     pac_url_ = url;
 185   }
 186
 187   const GURL& pac_url() const {
 188     return pac_url_;
 189   }
 190
 191   void set_pac_mandatory(bool enable_pac_mandatory) {
 192     pac_mandatory_ = enable_pac_mandatory;
 193   }
 194
 195   bool pac_mandatory() const {
 196     return pac_mandatory_;
 197   }
 198
 199   bool has_pac_url() const {
 200     return pac_url_.is_valid();
 201   }
 202
 203   void set_auto_detect(bool enable_auto_detect) {
 204     auto_detect_ = enable_auto_detect;
 205   }
 206
 207   bool auto_detect() const {
 208     return auto_detect_;
 209   }
 210
 211   void set_source(ProxyConfigSource source) {
 212     source_ = source;
 213   }
 214
 215   ProxyConfigSource source() const {
 216     return source_;
 217   }
 218
 219   // Helpers to construct some common proxy configurations.
 220
 221   static ProxyConfig CreateDirect() {
 222     return ProxyConfig();
 223   }
 224
 225   static ProxyConfig CreateAutoDetect() {
 226     ProxyConfig config;
 227     config.set_auto_detect(true);
 228     return config;
 229   }
 230
 231   static ProxyConfig CreateFromCustomPacURL(const GURL& pac_url) {
 232     ProxyConfig config;
 233     config.set_pac_url(pac_url);
 234     // By default fall back to direct connection in case PAC script fails.
 235     config.set_pac_mandatory(false);
 236     return config;
 237   }
 238
 239  private:
 240   // True if the proxy configuration should be auto-detected.
 241   bool auto_detect_;
 242
 243   // If non-empty, indicates the URL of the proxy auto-config file to use.
 244   GURL pac_url_;
 245
 246   // If true, blocks all traffic in case fetching the pac script from |pac_url_|
 247   // fails. Only valid if |pac_url_| is non-empty.
 248   bool pac_mandatory_;
 249
 250   // Manual proxy settings.
 251   ProxyRules proxy_rules_;
 252
 253   // Source of proxy settings.
 254   ProxyConfigSource source_;
 255
 256   ID id_;
 257 };
 258
 259 }  // namespace net
 260
 261
 262
 263 #endif  // NET_PROXY_PROXY_CONFIG_H_