net/proxy/proxy_bypass_rules.h

   1 // Copyright (c) 2011 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_BYPASS_RULES_H_
   6 #define NET_PROXY_PROXY_BYPASS_RULES_H_
   7
   8 #include <string>
   9 #include <vector>
  10
  11 #include "net/base/net_export.h"
  12 #include "url/gurl.h"
  13
  14 namespace net {
  15
  16 // ProxyBypassRules describes the set of URLs that should bypass the proxy
  17 // settings, as a list of rules. A URL is said to match the bypass rules
  18 // if it matches any one of these rules.
  19 class NET_EXPORT ProxyBypassRules {
  20  public:
  21   // Interface for an individual proxy bypass rule.
  22   class NET_EXPORT Rule {
  23    public:
  24     Rule();
  25     virtual ~Rule();
  26
  27     // Returns true if |url| matches the rule.
  28     virtual bool Matches(const GURL& url) const = 0;
  29
  30     // Returns a string representation of this rule. This is used both for
  31     // visualizing the rules, and also to test equality of a rules list.
  32     virtual std::string ToString() const = 0;
  33
  34     // Creates a copy of this rule. (Caller is responsible for deleting it)
  35     virtual Rule* Clone() const = 0;
  36
  37     bool Equals(const Rule& rule) const;
  38
  39    private:
  40     DISALLOW_COPY_AND_ASSIGN(Rule);
  41   };
  42
  43   typedef std::vector<const Rule*> RuleList;
  44
  45   // Note: This class supports copy constructor and assignment.
  46   ProxyBypassRules();
  47   ProxyBypassRules(const ProxyBypassRules& rhs);
  48   ~ProxyBypassRules();
  49   ProxyBypassRules& operator=(const ProxyBypassRules& rhs);
  50
  51   // Returns the current list of rules. The rules list contains pointers
  52   // which are owned by this class, callers should NOT keep references
  53   // or delete them.
  54   const RuleList& rules() const { return rules_; }
  55
  56   // Returns true if |url| matches any of the proxy bypass rules.
  57   bool Matches(const GURL& url) const;
  58
  59   // Returns true if |*this| is equal to |other|; in other words, whether they
  60   // describe the same set of rules.
  61   bool Equals(const ProxyBypassRules& other) const;
  62
  63   // Initializes the list of rules by parsing the string |raw|. |raw| is a
  64   // comma separated list of rules. See AddRuleFromString() to see the list
  65   // of supported formats.
  66   void ParseFromString(const std::string& raw);
  67
  68   // This is a variant of ParseFromString, which interprets hostname patterns
  69   // as suffix tests rather than hostname tests (so "google.com" would actually
  70   // match "*google.com"). This is only currently used for the linux no_proxy
  71   // evironment variable. It is less flexible, since with the suffix matching
  72   // format you can't match an individual host.
  73   // NOTE: Use ParseFromString() unless you truly need this behavior.
  74   void ParseFromStringUsingSuffixMatching(const std::string& raw);
  75
  76   // Adds a rule that matches a URL when all of the following are true:
  77   //  (a) The URL's scheme matches |optional_scheme|, if
  78   //      |!optional_scheme.empty()|
  79   //  (b) The URL's hostname matches |hostname_pattern|.
  80   //  (c) The URL's (effective) port number matches |optional_port| if
  81   //      |optional_port != -1|
  82   // Returns true if the rule was successfully added.
  83   bool AddRuleForHostname(const std::string& optional_scheme,
  84                           const std::string& hostname_pattern,
  85                           int optional_port);
  86
  87   // Adds a rule that bypasses all "local" hostnames.
  88   // This matches IE's interpretation of the
  89   // "Bypass proxy server for local addresses" settings checkbox. Fully
  90   // qualified domain names or IP addresses are considered non-local,
  91   // regardless of what they map to (except for the loopback addresses).
  92   void AddRuleToBypassLocal();
  93
  94   // Adds a rule given by the string |raw|. The format of |raw| can be any of
  95   // the following:
  96   //
  97   // (1) [ URL_SCHEME "://" ] HOSTNAME_PATTERN [ ":" <port> ]
  98   //
  99   //   Match all hostnames that match the pattern HOSTNAME_PATTERN.
 100   //
 101   //   Examples:
 102   //     "foobar.com", "*foobar.com", "*.foobar.com", "*foobar.com:99",
 103   //     "https://x.*.y.com:99"
 104   //
 105   // (2) "." HOSTNAME_SUFFIX_PATTERN [ ":" PORT ]
 106   //
 107   //   Match a particular domain suffix.
 108   //
 109   //   Examples:
 110   //     ".google.com", ".com", "http://.google.com"
 111   //
 112   // (3) [ SCHEME "://" ] IP_LITERAL [ ":" PORT ]
 113   //
 114   //   Match URLs which are IP address literals.
 115   //
 116   //   Conceptually this is the similar to (1), but with special cases
 117   //   to handle IP literal canonicalization. For example matching
 118   //   on "[0:0:0::1]" would be the same as matching on "[::1]" since
 119   //   the IPv6 canonicalization is done internally.
 120   //
 121   //   Examples:
 122   //     "127.0.1", "[0:0::1]", "[::1]", "http://[::1]:99"
 123   //
 124   // (4)  IP_LITERAL "/" PREFIX_LENGHT_IN_BITS
 125   //
 126   //   Match any URL that is to an IP literal that falls between the
 127   //   given range. IP range is specified using CIDR notation.
 128   //
 129   //   Examples:
 130   //     "192.168.1.1/16", "fefe:13::abc/33".
 131   //
 132   // (5)  "<local>"
 133   //
 134   //   Match local addresses. The meaning of "<local>" is whether the
 135   //   host matches one of: "127.0.0.1", "::1", "localhost".
 136   //
 137   // See the unit-tests for more examples.
 138   //
 139   // Returns true if the rule was successfully added.
 140   //
 141   // TODO(eroman): support IPv6 literals without brackets.
 142   //
 143   bool AddRuleFromString(const std::string& raw);
 144
 145   // This is a variant of AddFromString, which interprets hostname patterns as
 146   // suffix tests rather than hostname tests (so "google.com" would actually
 147   // match "*google.com"). This is used for KDE which interprets every rule as
 148   // a suffix test. It is less flexible, since with the suffix matching format
 149   // you can't match an individual host.
 150   //
 151   // Returns true if the rule was successfully added.
 152   //
 153   // NOTE: Use AddRuleFromString() unless you truly need this behavior.
 154   bool AddRuleFromStringUsingSuffixMatching(const std::string& raw);
 155
 156   // Converts the rules to string representation. Inverse operation to
 157   // ParseFromString().
 158   std::string ToString() const;
 159
 160   // Removes all the rules.
 161   void Clear();
 162
 163   // Sets |*this| to |other|.
 164   void AssignFrom(const ProxyBypassRules& other);
 165
 166  private:
 167   // The following are variants of ParseFromString() and AddRuleFromString(),
 168   // which additionally prefix hostname patterns with a wildcard if
 169   // |use_hostname_suffix_matching| was true.
 170   void ParseFromStringInternal(const std::string& raw,
 171                                bool use_hostname_suffix_matching);
 172   bool AddRuleFromStringInternal(const std::string& raw,
 173                                  bool use_hostname_suffix_matching);
 174   bool AddRuleFromStringInternalWithLogging(const std::string& raw,
 175                                             bool use_hostname_suffix_matching);
 176
 177   RuleList rules_;
 178 };
 179
 180 }  // namespace net
 181
 182 #endif  // NET_PROXY_PROXY_BYPASS_RULES_H_