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#pragma once
8
9#include <string>
10#include <vector>
11
12#include "googleurl/src/gurl.h"
13
14namespace 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.
19class ProxyBypassRules {
20 public:
21  // Interface for an individual proxy bypass rule.
22  class 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