url/scheme_host_port.h

   1 // Copyright 2015 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 URL_SCHEME_HOST_PORT_H_
   6 #define URL_SCHEME_HOST_PORT_H_
   7
   8 #include <string>
   9
  10 #include "base/basictypes.h"
  11 #include "base/strings/string_piece.h"
  12 #include "url/url_export.h"
  13
  14 class GURL;
  15
  16 namespace url {
  17
  18 // This class represents a (scheme, host, port) tuple extracted from a URL.
  19 //
  20 // The primary purpose of this class is to represent relevant network-authority
  21 // information for a URL. It is _not_ an Origin, as described in RFC 6454. In
  22 // particular, it is generally NOT the right thing to use for security
  23 // decisions.
  24 //
  25 // Instead, this class is a mechanism for simplifying URLs with standard schemes
  26 // (that is, those which follow the generic syntax of RFC 3986) down to the
  27 // uniquely identifying information necessary for network fetches. This makes it
  28 // suitable as a cache key for a collection of active connections, for instance.
  29 // It may, however, be inappropriate to use as a cache key for persistent
  30 // storage associated with a host.
  31 //
  32 // In particular, note that:
  33 //
  34 // * SchemeHostPort can only represent schemes which follow the RFC 3986 syntax
  35 //   (e.g. those registered with GURL as "standard schemes"). Non-standard
  36 //   schemes such as "blob", "filesystem", "data", and "javascript" can only be
  37 //   represented as invalid SchemeHostPort objects.
  38 //
  39 // * The "file" scheme follows the standard syntax, but it is important to note
  40 //   that the authority portion (host, port) is optional. URLs without an
  41 //   authority portion will be represented with an empty string for the host,
  42 //   and a port of 0 (e.g. "file:///etc/hosts" => ("file", "", 0)), and URLs
  43 //   with a host-only authority portion will be represented with a port of 0
  44 //   (e.g. "file://example.com/etc/hosts" => ("file", "example.com", 0)). See
  45 //   Section 3 of RFC 3986 to better understand these constructs.
  46 //
  47 // * SchemeHostPort has no notion of the Origin concept (RFC 6454), and in
  48 //   particular, it has no notion of a "unique" Origin. If you need to take
  49 //   uniqueness into account (and, if you're making security-relevant decisions
  50 //   then you absolutely do), please use 'url::Origin' instead[1].
  51 //
  52 // [1]: // TODO(mkwst): Land 'url::Origin'. :)
  53 //
  54 // Usage:
  55 //
  56 // * SchemeHostPort objects are commonly created from GURL objects:
  57 //
  58 //     GURL url("https://example.com/");
  59 //     url::SchemeHostPort tuple(url);
  60 //     tuple.scheme(); // "https"
  61 //     tuple.host(); // "example.com"
  62 //     tuple.port(); // 443
  63 //
  64 // * Objects may also be explicitly created and compared:
  65 //
  66 //     url::SchemeHostPort tuple(url::kHttpsScheme, "example.com", 443);
  67 //     tuple.scheme(); // "https"
  68 //     tuple.host(); // "example.com"
  69 //     tuple.port(); // 443
  70 //
  71 //     GURL url("https://example.com/");
  72 //     tuple.Equals(url::SchemeHostPort(url)); // true
  73 class URL_EXPORT SchemeHostPort {
  74  public:
  75   // Creates an invalid (scheme, host, port) tuple, which represents an invalid
  76   // or non-standard URL.
  77   SchemeHostPort();
  78
  79   // Creates a (scheme, host, port) tuple. |host| must be a canonicalized
  80   // A-label (that is, '☃.net' must be provided as 'xn--n3h.net'). |scheme|
  81   // must be a standard scheme. |port| must not be 0, unless |scheme| does not
  82   // support ports (e.g. 'file'). In that case, |port| must be 0.
  83   //
  84   // Copies the data in |scheme| and |host|.
  85   SchemeHostPort(base::StringPiece scheme, base::StringPiece host, uint16 port);
  86
  87   // Creates a (scheme, host, port) tuple from |url|, as described at
  88   // https://tools.ietf.org/html/rfc6454#section-4
  89   //
  90   // If |url| is invalid or non-standard, the result will be an invalid
  91   // SchemeHostPort object.
  92   explicit SchemeHostPort(const GURL& url);
  93
  94   ~SchemeHostPort();
  95
  96   // Returns the host component, in URL form. That is all IDN domain names will
  97   // be expressed as A-Labels ('☃.net' will be returned as 'xn--n3h.net'), and
  98   // and all IPv6 addresses will be enclosed in brackets ("[2001:db8::1]").
  99   const std::string& host() const { return host_; }
 100   const std::string& scheme() const { return scheme_; }
 101   uint16 port() const { return port_; }
 102   bool IsInvalid() const;
 103
 104   // Serializes the SchemeHostPort tuple to a canonical form.
 105   //
 106   // While this string form resembles the Origin serialization specified in
 107   // Section 6.2 of RFC 6454, it is important to note that invalid
 108   // SchemeHostPort tuples serialize to the empty string, rather than being
 109   // serialized as a unique Origin.
 110   std::string Serialize() const;
 111
 112   // Two SchemeHostPort objects are "equal" iff their schemes, hosts, and ports
 113   // are exact matches.
 114   //
 115   // Note that this comparison is _not_ the same as an origin-based comparison.
 116   // In particular, invalid SchemeHostPort objects match each other (and
 117   // themselves). Unique origins, on the other hand, would not.
 118   bool Equals(const SchemeHostPort& other) const;
 119
 120   // Allows SchemeHostPort to used as a key in STL (for example, a std::set or
 121   // std::map).
 122   bool operator<(const SchemeHostPort& other) const;
 123
 124  private:
 125   std::string scheme_;
 126   std::string host_;
 127   uint16 port_;
 128 };
 129
 130 }  // namespace url
 131
 132 #endif  // URL_SCHEME_HOST_PORT_H_