scheme_host_port.h 6.7 KB

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