Home | History | Annotate | Download | only in proxy
      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_
    183