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 // * For example, the "file" scheme follows the standard syntax, but it is
  40 //   important to note that the authority portion (host, port) is optional.
  41 //   URLs without an authority portion will be represented with an empty string
  42 //   for the host, and a port of 0 (e.g. "file:///etc/hosts" =>
  43 //   ("file", "", 0)), and URLs with a host-only authority portion will be
  44 //   represented with a port of 0 (e.g. "file://example.com/etc/hosts" =>
  45 //   ("file", "example.com", 0)). See Section 3 of RFC 3986 to better understand
  46 //   these constructs.
  47 //
  48 // * SchemeHostPort has no notion of the Origin concept (RFC 6454), and in
  49 //   particular, it has no notion of a "unique" Origin. If you need to take
  50 //   uniqueness into account (and, if you're making security-relevant decisions
  51 //   then you absolutely do), please use 'url::Origin' instead.
  52 //
  53 // Usage:
  54 //
  55 // * SchemeHostPort objects are commonly created from GURL objects:
  56 //
  57 //     GURL url("https://example.com/");
  58 //     url::SchemeHostPort tuple(url);
  59 //     tuple.scheme(); // "https"
  60 //     tuple.host(); // "example.com"
  61 //     tuple.port(); // 443
  62 //
  63 // * Objects may also be explicitly created and compared:
  64 //
  65 //     url::SchemeHostPort tuple(url::kHttpsScheme, "example.com", 443);
  66 //     tuple.scheme(); // "https"
  67 //     tuple.host(); // "example.com"
  68 //     tuple.port(); // 443
  69 //
  70 //     GURL url("https://example.com/");
  71 //     tuple.Equals(url::SchemeHostPort(url)); // true
  72 class URL_EXPORT SchemeHostPort {
  73  public:
  74   // Creates an invalid (scheme, host, port) tuple, which represents an invalid
  75   // or non-standard URL.
  76   SchemeHostPort();
  77
  78   // Creates a (scheme, host, port) tuple. |host| must be a canonicalized
  79   // A-label (that is, '☃.net' must be provided as 'xn--n3h.net'). |scheme|
  80   // must be a standard scheme. |port| must not be 0, unless |scheme| does not
  81   // support ports (e.g. 'file'). In that case, |port| must be 0.
  82   //
  83   // Copies the data in |scheme| and |host|.
  84   SchemeHostPort(base::StringPiece scheme, base::StringPiece host, uint16 port);
  85
  86   // Creates a (scheme, host, port) tuple from |url|, as described at
  87   // https://tools.ietf.org/html/rfc6454#section-4
  88   //
  89   // If |url| is invalid or non-standard, the result will be an invalid
  90   // SchemeHostPort object.
  91   explicit SchemeHostPort(const GURL& url);
  92
  93   ~SchemeHostPort();
  94
  95   // Returns the host component, in URL form. That is all IDN domain names will
  96   // be expressed as A-Labels ('☃.net' will be returned as 'xn--n3h.net'), and
  97   // and all IPv6 addresses will be enclosed in brackets ("[2001:db8::1]").
  98   const std::string& host() const { return host_; }
  99   const std::string& scheme() const { return scheme_; }
 100   uint16 port() const { return port_; }
 101   bool IsInvalid() const;
 102
 103   // Serializes the SchemeHostPort tuple to a canonical form.
 104   //
 105   // While this string form resembles the Origin serialization specified in
 106   // Section 6.2 of RFC 6454, it is important to note that invalid
 107   // SchemeHostPort tuples serialize to the empty string, rather than being
 108   // serialized as a unique Origin.
 109   std::string Serialize() const;
 110
 111   // Two SchemeHostPort objects are "equal" iff their schemes, hosts, and ports
 112   // are exact matches.
 113   //
 114   // Note that this comparison is _not_ the same as an origin-based comparison.
 115   // In particular, invalid SchemeHostPort objects match each other (and
 116   // themselves). Unique origins, on the other hand, would not.
 117   bool Equals(const SchemeHostPort& other) const;
 118
 119   // Allows SchemeHostPort to used as a key in STL (for example, a std::set or
 120   // std::map).
 121   bool operator<(const SchemeHostPort& other) const;
 122
 123  private:
 124   std::string scheme_;
 125   std::string host_;
 126   uint16 port_;
 127 };
 128
 129 }  // namespace url
 130
 131 #endif  // URL_SCHEME_HOST_PORT_H_