1 // Copyright 2013 The Chromium Authors
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
13 #include <string_view>
15 #include "base/component_export.h"
16 #include "base/debug/alias.h"
17 #include "base/debug/crash_logging.h"
18 #include "base/trace_event/base_tracing_forward.h"
19 #include "url/third_party/mozilla/url_parse.h"
20 #include "url/url_canon.h"
21 #include "url/url_canon_stdstring.h"
22 #include "url/url_constants.h"
24 // Represents a URL. GURL is Google's URL parsing library.
26 // A parsed canonicalized URL is guaranteed to be UTF-8. Any non-ASCII input
27 // characters are UTF-8 encoded and % escaped to ASCII.
29 // The string representation of a URL is called the spec(). Getting the
30 // spec will assert if the URL is invalid to help protect against malicious
31 // URLs. If you want the "best effort" canonicalization of an invalid URL, you
32 // can use possibly_invalid_spec(). Test validity with is_valid(). Data and
33 // javascript URLs use GetContent() to extract the data.
35 // This class has existence checkers and getters for the various components of
36 // a URL. Existence is different than being nonempty. "http://www.google.com/?"
37 // has a query that just happens to be empty, and has_query() will return true
38 // while the query getters will return the empty string.
40 // Prefer not to modify a URL using string operations (though sometimes this is
41 // unavoidable). Instead, use ReplaceComponents which can replace or delete
42 // multiple parts of a URL in one step, doesn't re-canonicalize unchanged
43 // sections, and avoids some screw-ups. An example is creating a URL with a
44 // path that contains a literal '#'. Using string concatenation will generate a
45 // URL with a truncated path and a reference fragment, while ReplaceComponents
46 // will know to escape this and produce the desired result.
47 class COMPONENT_EXPORT(URL) GURL {
49 using Replacements = url::StringViewReplacements<char>;
50 using ReplacementsW = url::StringViewReplacements<char16_t>;
52 // Creates an empty, invalid URL.
55 // Copy construction is relatively inexpensive, with most of the time going
56 // to reallocating the string. It does not re-parse.
57 GURL(const GURL& other);
58 GURL(GURL&& other) noexcept;
60 // The strings to this constructor should be UTF-8 / UTF-16.
61 explicit GURL(std::string_view url_string);
62 explicit GURL(std::u16string_view url_string);
64 // Constructor for URLs that have already been parsed and canonicalized. This
65 // is used for conversions from KURL, for example. The caller must supply all
66 // information associated with the URL, which must be correct and consistent.
67 GURL(const char* canonical_spec,
68 size_t canonical_spec_len,
69 const url::Parsed& parsed,
71 // Notice that we take the canonical_spec by value so that we can convert
72 // from WebURL without copying the string. When we call this constructor
73 // we pass in a temporary std::string, which lets the compiler skip the
74 // copy and just move the std::string into the function argument. In the
75 // implementation, we use std::move to move the data into the GURL itself,
76 // which means we end up with zero copies.
77 GURL(std::string canonical_spec, const url::Parsed& parsed, bool is_valid);
81 GURL& operator=(const GURL& other);
82 GURL& operator=(GURL&& other) noexcept;
84 // Returns true when this object represents a valid parsed URL. When not
85 // valid, other functions will still succeed, but you will not get canonical
86 // data out in the format you may be expecting. Instead, we keep something
87 // "reasonable looking" so that the user can see how it's busted if
89 bool is_valid() const {
93 // Returns true if the URL is zero-length. Note that empty URLs are also
94 // invalid, and is_valid() will return false for them. This is provided
95 // because some users may want to treat the empty case differently.
96 bool is_empty() const {
100 // Returns the raw spec, i.e., the full text of the URL, in canonical UTF-8,
101 // if the URL is valid. If the URL is not valid, this will assert and return
102 // the empty string (for safety in release builds, to keep them from being
103 // misused which might be a security problem).
105 // The URL will be ASCII (non-ASCII characters will be %-escaped UTF-8).
107 // The exception is for empty() URLs (which are !is_valid()) but this will
108 // return the empty string without asserting.
110 // Use invalid_spec() below to get the unusable spec of an invalid URL. This
111 // separation is designed to prevent errors that may cause security problems
112 // that could result from the mistaken use of an invalid URL.
113 const std::string& spec() const;
115 // Returns the potentially invalid spec for a the URL. This spec MUST NOT be
116 // modified or sent over the network. It is designed to be displayed in error
117 // messages to the user, as the appearance of the spec may explain the error.
118 // If the spec is valid, the valid spec will be returned.
120 // The returned string is guaranteed to be valid UTF-8.
121 const std::string& possibly_invalid_spec() const {
125 // Getter for the raw parsed structure. This allows callers to locate parts
126 // of the URL within the spec themselves. Most callers should consider using
127 // the individual component getters below.
129 // The returned parsed structure will reference into the raw spec, which may
130 // or may not be valid. If you are using this to index into the spec, BE
131 // SURE YOU ARE USING possibly_invalid_spec() to get the spec, and that you
132 // don't do anything "important" with invalid specs.
133 const url::Parsed& parsed_for_possibly_invalid_spec() const {
137 // Allows GURL to used as a key in STL (for example, a std::set or std::map).
138 bool operator<(const GURL& other) const;
139 bool operator>(const GURL& other) const;
141 // Resolves a URL that's possibly relative to this object's URL, and returns
142 // it. Absolute URLs are also handled according to the rules of URLs on web
145 // It may be impossible to resolve the URLs properly. If the input is not
146 // "standard" (IsStandard() == false) and the input looks relative, we can't
147 // resolve it. In these cases, the result will be an empty, invalid GURL.
149 // The result may also be a nonempty, invalid URL if the input has some kind
150 // of encoding error. In these cases, we will try to construct a "good" URL
151 // that may have meaning to the user, but it will be marked invalid.
153 // It is an error to resolve a URL relative to an invalid URL. The result
154 // will be the empty URL.
155 GURL Resolve(std::string_view relative) const;
156 GURL Resolve(std::u16string_view relative) const;
158 // Creates a new GURL by replacing the current URL's components with the
159 // supplied versions. See the Replacements class in url_canon.h for more.
161 // These are not particularly quick, so avoid doing mutations when possible.
162 // Prefer the 8-bit version when possible.
164 // It is an error to replace components of an invalid URL. The result will
167 // Note that this intentionally disallows direct use of url::Replacements,
168 // which is harder to use correctly.
169 GURL ReplaceComponents(const Replacements& replacements) const;
170 GURL ReplaceComponents(const ReplacementsW& replacements) const;
172 // A helper function that is equivalent to replacing the path with a slash
173 // and clearing out everything after that. We sometimes need to know just the
174 // scheme and the authority. If this URL is not a standard URL (it doesn't
175 // have the regular authority and path sections), then the result will be
176 // an empty, invalid GURL. Note that this *does* work for file: URLs, which
177 // some callers may want to filter out before calling this.
179 // It is an error to get an empty path on an invalid URL. The result
180 // will be the empty URL.
181 GURL GetWithEmptyPath() const;
183 // A helper function to return a GURL without the filename, query values, and
184 // fragment. For example,
185 // GURL("https://www.foo.com/index.html?q=test").GetWithoutFilename().spec()
186 // will return "https://www.foo.com/".
187 // GURL("https://www.foo.com/bar/").GetWithoutFilename().spec()
188 // will return "https://www.foo.com/bar/". If the GURL is invalid or missing a
189 // scheme, authority or path, it will return an empty, invalid GURL.
190 GURL GetWithoutFilename() const;
192 // A helper function to return a GURL without the Ref (also named Fragment
193 // Identifier). For example,
194 // GURL("https://www.foo.com/index.html#test").GetWithoutRef().spec()
195 // will return "https://www.foo.com/index.html".
196 // If the GURL is invalid or missing a
197 // scheme, authority or path, it will return an empty, invalid GURL.
198 GURL GetWithoutRef() const;
200 // A helper function to return a GURL containing just the scheme, host,
201 // and port from a URL. Equivalent to clearing any username and password,
202 // replacing the path with a slash, and clearing everything after that. If
203 // this URL is not a standard URL, then the result will be an empty,
204 // invalid GURL. If the URL has neither username nor password, this
205 // degenerates to GetWithEmptyPath().
207 // It is an error to get the origin of an invalid URL. The result
208 // will be the empty URL.
210 // WARNING: Please avoid converting urls into origins if at all possible!
211 // //docs/security/origin-vs-url.md is a list of gotchas that can result. Such
212 // conversions will likely return a wrong result for about:blank and/or
213 // in the presence of iframe.sandbox attribute. Prefer to get origins directly
214 // from the source (e.g. RenderFrameHost::GetLastCommittedOrigin).
215 GURL DeprecatedGetOriginAsURL() const;
217 // A helper function to return a GURL stripped from the elements that are not
218 // supposed to be sent as HTTP referrer: username, password and ref fragment.
219 // For invalid URLs or URLs that no valid referrers, an empty URL will be
221 GURL GetAsReferrer() const;
223 // Returns true if the scheme for the current URL is a known "standard-format"
224 // scheme. A standard-format scheme adheres to what RFC 3986 calls "generic
225 // URI syntax" (https://tools.ietf.org/html/rfc3986#section-3). This includes
226 // file: and filesystem:, which some callers may want to filter out explicitly
227 // by calling SchemeIsFile[System].
228 bool IsStandard() const;
230 // Returns true when the url is of the form about:blank, about:blank?foo or
232 bool IsAboutBlank() const;
234 // Returns true when the url is of the form about:srcdoc, about:srcdoc?foo or
235 // about:srcdoc/#foo.
236 bool IsAboutSrcdoc() const;
238 // Returns true if the given parameter (should be lower-case ASCII to match
239 // the canonicalized scheme) is the scheme for this URL. Do not include a
241 bool SchemeIs(std::string_view lower_ascii_scheme) const;
243 // Returns true if the scheme is "http" or "https".
244 bool SchemeIsHTTPOrHTTPS() const;
246 // Returns true is the scheme is "ws" or "wss".
247 bool SchemeIsWSOrWSS() const;
249 // We often need to know if this is a file URL. File URLs are "standard", but
250 // are often treated separately by some programs.
251 bool SchemeIsFile() const {
252 return SchemeIs(url::kFileScheme);
255 // FileSystem URLs need to be treated differently in some cases.
256 bool SchemeIsFileSystem() const {
257 return SchemeIs(url::kFileSystemScheme);
260 // Returns true if the scheme indicates a network connection that uses TLS or
261 // some other cryptographic protocol (e.g. QUIC) for security.
263 // This function is a not a complete test of whether or not an origin's code
264 // is minimally trustworthy. For that, see Chromium's |IsOriginSecure| for a
265 // higher-level and more complete semantics. See that function's documentation
267 bool SchemeIsCryptographic() const;
269 // As above, but static. Parameter should be lower-case ASCII.
270 static bool SchemeIsCryptographic(std::string_view lower_ascii_scheme);
272 // Returns true if the scheme is "blob".
273 bool SchemeIsBlob() const {
274 return SchemeIs(url::kBlobScheme);
277 // Returns true if the scheme is a local scheme, as defined in Fetch:
278 // https://fetch.spec.whatwg.org/#local-scheme
279 bool SchemeIsLocal() const;
281 // For most URLs, the "content" is everything after the scheme (skipping the
282 // scheme delimiting colon) and before the fragment (skipping the fragment
283 // delimiting octothorpe). For javascript URLs the "content" also includes the
284 // fragment delimiter and fragment.
286 // It is an error to get the content of an invalid URL: the result will be an
288 std::string GetContent() const;
289 std::string_view GetContentPiece() const;
291 // Returns true if the hostname is an IP address. Note: this function isn't
292 // as cheap as a simple getter because it re-parses the hostname to verify.
293 bool HostIsIPAddress() const;
295 // Not including the colon. If you are comparing schemes, prefer SchemeIs.
296 bool has_scheme() const { return parsed_.scheme.is_valid(); }
297 std::string scheme() const {
298 return ComponentString(parsed_.scheme);
300 std::string_view scheme_piece() const {
301 return ComponentStringPiece(parsed_.scheme);
304 bool has_username() const { return parsed_.username.is_valid(); }
305 std::string username() const {
306 return ComponentString(parsed_.username);
308 std::string_view username_piece() const {
309 return ComponentStringPiece(parsed_.username);
312 bool has_password() const { return parsed_.password.is_valid(); }
313 std::string password() const {
314 return ComponentString(parsed_.password);
316 std::string_view password_piece() const {
317 return ComponentStringPiece(parsed_.password);
320 // The host may be a hostname, an IPv4 address, or an IPv6 literal surrounded
321 // by square brackets, like "[2001:db8::1]". To exclude these brackets, use
322 // HostNoBrackets() below.
323 bool has_host() const {
324 // Note that hosts are special, absence of host means length 0.
325 return parsed_.host.is_nonempty();
327 std::string host() const {
328 return ComponentString(parsed_.host);
330 std::string_view host_piece() const {
331 return ComponentStringPiece(parsed_.host);
334 // The port if one is explicitly specified. Most callers will want IntPort()
335 // or EffectiveIntPort() instead of these. The getters will not include the
337 bool has_port() const { return parsed_.port.is_valid(); }
338 std::string port() const {
339 return ComponentString(parsed_.port);
341 std::string_view port_piece() const {
342 return ComponentStringPiece(parsed_.port);
345 // Including first slash following host, up to the query. The URL
346 // "http://www.google.com/" has a path of "/".
347 bool has_path() const { return parsed_.path.is_valid(); }
348 std::string path() const {
349 return ComponentString(parsed_.path);
351 std::string_view path_piece() const {
352 return ComponentStringPiece(parsed_.path);
355 // Stuff following '?' up to the ref. The getters will not include the '?'.
356 bool has_query() const { return parsed_.query.is_valid(); }
357 std::string query() const {
358 return ComponentString(parsed_.query);
360 std::string_view query_piece() const {
361 return ComponentStringPiece(parsed_.query);
364 // Stuff following '#' to the end of the string. This will be %-escaped UTF-8.
365 // The getters will not include the '#'.
366 bool has_ref() const { return parsed_.ref.is_valid(); }
367 std::string ref() const {
368 return ComponentString(parsed_.ref);
370 std::string_view ref_piece() const {
371 return ComponentStringPiece(parsed_.ref);
374 // Returns a parsed version of the port. Can also be any of the special
375 // values defined in Parsed for ExtractPort.
378 // Returns the port number of the URL, or the default port number.
379 // If the scheme has no concept of port (or unknown default) returns
381 int EffectiveIntPort() const;
383 // Extracts the filename portion of the path and returns it. The filename
384 // is everything after the last slash in the path. This may be empty.
385 std::string ExtractFileName() const;
387 // Returns the path that should be sent to the server. This is the path,
388 // parameter, and query portions of the URL. It is guaranteed to be ASCII.
389 std::string PathForRequest() const;
391 // Returns the same characters as PathForRequest(), avoiding a copy.
392 std::string_view PathForRequestPiece() const;
394 // Returns the host, excluding the square brackets surrounding IPv6 address
395 // literals. This can be useful for passing to getaddrinfo().
396 std::string HostNoBrackets() const;
398 // Returns the same characters as HostNoBrackets(), avoiding a copy.
399 std::string_view HostNoBracketsPiece() const;
401 // Returns true if this URL's host matches or is in the same domain as
402 // the given input string. For example, if the hostname of the URL is
403 // "www.google.com", this will return true for "com", "google.com", and
406 // The input domain should match host canonicalization rules. i.e. the input
407 // should be lowercase except for escape chars.
409 // This call is more efficient than getting the host and checking whether the
410 // host has the specific domain or not because no copies or object
411 // constructions are done.
412 bool DomainIs(std::string_view canonical_domain) const;
414 // Checks whether or not two URLs differ only in the ref (the part after
416 bool EqualsIgnoringRef(const GURL& other) const;
418 // Swaps the contents of this GURL object with |other|, without doing
419 // any memory allocations.
420 void Swap(GURL* other);
422 // Returns a reference to a singleton empty GURL. This object is for callers
423 // who return references but don't have anything to return in some cases.
424 // If you just want an empty URL for normal use, prefer GURL(). This function
425 // may be called from any thread.
426 static const GURL& EmptyGURL();
428 // Returns the inner URL of a nested URL (currently only non-null for
431 // TODO(mmenke): inner_url().spec() currently returns the same value as
432 // caling spec() on the GURL itself. This should be fixed.
433 // See https://crbug.com/619596
434 const GURL* inner_url() const {
435 return inner_url_.get();
438 // Estimates dynamic memory usage.
439 // See base/trace_event/memory_usage_estimator.h for more info.
440 size_t EstimateMemoryUsage() const;
442 // Helper used by GURL::IsAboutUrl and KURL::IsAboutURL.
443 static bool IsAboutPath(std::string_view actual_path,
444 std::string_view allowed_path);
446 void WriteIntoTrace(perfetto::TracedValue context) const;
449 // Variant of the string parsing constructor that allows the caller to elect
450 // retain trailing whitespace, if any, on the passed URL spec, but only if
451 // the scheme is one that allows trailing whitespace. The primary use-case is
452 // for data: URLs. In most cases, you want to use the single parameter
453 // constructor above.
454 enum RetainWhiteSpaceSelector { RETAIN_TRAILING_PATH_WHITEPACE };
455 GURL(const std::string& url_string, RetainWhiteSpaceSelector);
457 template <typename T, typename CharT = typename T::value_type>
458 void InitCanonical(T input_spec, bool trim_path_end);
460 void InitializeFromCanonicalSpec();
462 // Helper used by IsAboutBlank and IsAboutSrcdoc.
463 bool IsAboutUrl(std::string_view allowed_path) const;
465 // Returns the substring of the input identified by the given component.
466 std::string ComponentString(const url::Component& comp) const {
467 return std::string(ComponentStringPiece(comp));
469 std::string_view ComponentStringPiece(const url::Component& comp) const {
471 return std::string_view();
472 return std::string_view(spec_).substr(static_cast<size_t>(comp.begin),
473 static_cast<size_t>(comp.len));
476 void ProcessFileSystemURLAfterReplaceComponents();
478 // The actual text of the URL, in canonical ASCII form.
481 // Set when the given URL is valid. Otherwise, we may still have a spec and
482 // components, but they may not identify valid resources (for example, an
483 // invalid port number, invalid characters in the scheme, etc.).
486 // Identified components of the canonical spec.
489 // Used for nested schemes [currently only filesystem:].
490 std::unique_ptr<GURL> inner_url_;
493 // Stream operator so GURL can be used in assertion statements.
494 COMPONENT_EXPORT(URL)
495 std::ostream& operator<<(std::ostream& out, const GURL& url);
497 COMPONENT_EXPORT(URL) bool operator==(const GURL& x, const GURL& y);
498 COMPONENT_EXPORT(URL) bool operator!=(const GURL& x, const GURL& y);
500 // Equality operator for comparing raw spec_. This should be used in place of
501 // url == GURL(spec) where |spec| is known (i.e. constants). This is to prevent
502 // needlessly re-parsing |spec| into a temporary GURL.
503 COMPONENT_EXPORT(URL)
504 bool operator==(const GURL& x, std::string_view spec);
505 COMPONENT_EXPORT(URL)
506 bool operator==(std::string_view spec, const GURL& x);
507 COMPONENT_EXPORT(URL)
508 bool operator!=(const GURL& x, std::string_view spec);
509 COMPONENT_EXPORT(URL)
510 bool operator!=(std::string_view spec, const GURL& x);
512 // DEBUG_ALIAS_FOR_GURL(var_name, url) copies |url| into a new stack-allocated
513 // variable named |<var_name>|. This helps ensure that the value of |url| gets
514 // preserved in crash dumps.
515 #define DEBUG_ALIAS_FOR_GURL(var_name, url) \
516 DEBUG_ALIAS_FOR_CSTR(var_name, (url).possibly_invalid_spec().c_str(), 128)
518 namespace url::debug {
520 class COMPONENT_EXPORT(URL) ScopedUrlCrashKey {
522 ScopedUrlCrashKey(base::debug::CrashKeyString* crash_key, const GURL& value);
523 ~ScopedUrlCrashKey();
525 ScopedUrlCrashKey(const ScopedUrlCrashKey&) = delete;
526 ScopedUrlCrashKey& operator=(const ScopedUrlCrashKey&) = delete;
529 base::debug::ScopedCrashKeyString scoped_string_value_;
532 } // namespace url::debug
534 #endif // URL_GURL_H_