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