1 // Copyright 2013 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_GURL_H_
6 #define URL_GURL_H_
7
8 #include <stddef.h>
9
10 #include <iosfwd>
11 #include <memory>
12 #include <string>
13
14 #include "base/component_export.h"
15 #include "base/debug/alias.h"
16 #include "base/strings/string16.h"
17 #include "base/strings/string_piece.h"
18 #include "url/third_party/mozilla/url_parse.h"
19 #include "url/url_canon.h"
20 #include "url/url_canon_stdstring.h"
21 #include "url/url_constants.h"
22
23 // Represents a URL. GURL is Google's URL parsing library.
24 //
25 // A parsed canonicalized URL is guaranteed to be UTF-8. Any non-ASCII input
26 // characters are UTF-8 encoded and % escaped to ASCII.
27 //
28 // The string representation of a URL is called the spec(). Getting the
29 // spec will assert if the URL is invalid to help protect against malicious
30 // URLs. If you want the "best effort" canonicalization of an invalid URL, you
31 // can use possibly_invalid_spec(). Test validity with is_valid(). Data and
32 // javascript URLs use GetContent() to extract the data.
33 //
34 // This class has existence checkers and getters for the various components of
35 // a URL. Existence is different than being nonempty. "http://www.google.com/?"
36 // has a query that just happens to be empty, and has_query() will return true
37 // while the query getters will return the empty string.
38 //
39 // Prefer not to modify a URL using string operations (though sometimes this is
40 // unavoidable). Instead, use ReplaceComponents which can replace or delete
41 // multiple parts of a URL in one step, doesn't re-canonicalize unchanged
42 // sections, and avoids some screw-ups. An example is creating a URL with a
43 // path that contains a literal '#'. Using string concatenation will generate a
44 // URL with a truncated path and a reference fragment, while ReplaceComponents
45 // will know to escape this and produce the desired result.
COMPONENT_EXPORT(URL)46 class COMPONENT_EXPORT(URL) GURL {
47 public:
48 typedef url::StringPieceReplacements<std::string> Replacements;
49 typedef url::StringPieceReplacements<base::string16> ReplacementsW;
50
51 // Creates an empty, invalid URL.
52 GURL();
53
54 // Copy construction is relatively inexpensive, with most of the time going
55 // to reallocating the string. It does not re-parse.
56 GURL(const GURL& other);
57 GURL(GURL&& other) noexcept;
58
59 // The strings to this contructor should be UTF-8 / UTF-16.
60 explicit GURL(base::StringPiece url_string);
61 explicit GURL(base::StringPiece16 url_string);
62
63 // Constructor for URLs that have already been parsed and canonicalized. This
64 // is used for conversions from KURL, for example. The caller must supply all
65 // information associated with the URL, which must be correct and consistent.
66 GURL(const char* canonical_spec,
67 size_t canonical_spec_len,
68 const url::Parsed& parsed,
69 bool is_valid);
70 // Notice that we take the canonical_spec by value so that we can convert
71 // from WebURL without copying the string. When we call this constructor
72 // we pass in a temporary std::string, which lets the compiler skip the
73 // copy and just move the std::string into the function argument. In the
74 // implementation, we use std::move to move the data into the GURL itself,
75 // which means we end up with zero copies.
76 GURL(std::string canonical_spec, const url::Parsed& parsed, bool is_valid);
77
78 ~GURL();
79
80 GURL& operator=(const GURL& other);
81 GURL& operator=(GURL&& other) noexcept;
82
83 // Returns true when this object represents a valid parsed URL. When not
84 // valid, other functions will still succeed, but you will not get canonical
85 // data out in the format you may be expecting. Instead, we keep something
86 // "reasonable looking" so that the user can see how it's busted if
87 // displayed to them.
88 bool is_valid() const {
89 return is_valid_;
90 }
91
92 // Returns true if the URL is zero-length. Note that empty URLs are also
93 // invalid, and is_valid() will return false for them. This is provided
94 // because some users may want to treat the empty case differently.
95 bool is_empty() const {
96 return spec_.empty();
97 }
98
99 // Returns the raw spec, i.e., the full text of the URL, in canonical UTF-8,
100 // if the URL is valid. If the URL is not valid, this will assert and return
101 // the empty string (for safety in release builds, to keep them from being
102 // misused which might be a security problem).
103 //
104 // The URL will be ASCII (non-ASCII characters will be %-escaped UTF-8).
105 //
106 // The exception is for empty() URLs (which are !is_valid()) but this will
107 // return the empty string without asserting.
108 //
109 // Use invalid_spec() below to get the unusable spec of an invalid URL. This
110 // separation is designed to prevent errors that may cause security problems
111 // that could result from the mistaken use of an invalid URL.
112 const std::string& spec() const;
113
114 // Returns the potentially invalid spec for a the URL. This spec MUST NOT be
115 // modified or sent over the network. It is designed to be displayed in error
116 // messages to the user, as the appearance of the spec may explain the error.
117 // If the spec is valid, the valid spec will be returned.
118 //
119 // The returned string is guaranteed to be valid UTF-8.
120 const std::string& possibly_invalid_spec() const {
121 return spec_;
122 }
123
124 // Getter for the raw parsed structure. This allows callers to locate parts
125 // of the URL within the spec themselves. Most callers should consider using
126 // the individual component getters below.
127 //
128 // The returned parsed structure will reference into the raw spec, which may
129 // or may not be valid. If you are using this to index into the spec, BE
130 // SURE YOU ARE USING possibly_invalid_spec() to get the spec, and that you
131 // don't do anything "important" with invalid specs.
132 const url::Parsed& parsed_for_possibly_invalid_spec() const {
133 return parsed_;
134 }
135
136 // Allows GURL to used as a key in STL (for example, a std::set or std::map).
137 bool operator<(const GURL& other) const;
138 bool operator>(const GURL& other) const;
139
140 // Resolves a URL that's possibly relative to this object's URL, and returns
141 // it. Absolute URLs are also handled according to the rules of URLs on web
142 // pages.
143 //
144 // It may be impossible to resolve the URLs properly. If the input is not
145 // "standard" (IsStandard() == false) and the input looks relative, we can't
146 // resolve it. In these cases, the result will be an empty, invalid GURL.
147 //
148 // The result may also be a nonempty, invalid URL if the input has some kind
149 // of encoding error. In these cases, we will try to construct a "good" URL
150 // that may have meaning to the user, but it will be marked invalid.
151 //
152 // It is an error to resolve a URL relative to an invalid URL. The result
153 // will be the empty URL.
154 GURL Resolve(base::StringPiece relative) const;
155 GURL Resolve(base::StringPiece16 relative) const;
156
157 // Creates a new GURL by replacing the current URL's components with the
158 // supplied versions. See the Replacements class in url_canon.h for more.
159 //
160 // These are not particularly quick, so avoid doing mutations when possible.
161 // Prefer the 8-bit version when possible.
162 //
163 // It is an error to replace components of an invalid URL. The result will
164 // be the empty URL.
165 //
166 // Note that we use the more general url::Replacements type to give
167 // callers extra flexibility rather than our override.
168 GURL ReplaceComponents(const url::Replacements<char>& replacements) const;
169 GURL ReplaceComponents(
170 const url::Replacements<base::char16>& replacements) const;
171
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.
178 //
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;
182
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;
191
192 // A helper function to return a GURL containing just the scheme, host,
193 // and port from a URL. Equivalent to clearing any username and password,
194 // replacing the path with a slash, and clearing everything after that. If
195 // this URL is not a standard URL, then the result will be an empty,
196 // invalid GURL. If the URL has neither username nor password, this
197 // degenerates to GetWithEmptyPath().
198 //
199 // It is an error to get the origin of an invalid URL. The result
200 // will be the empty URL.
201 GURL GetOrigin() const;
202
203 // A helper function to return a GURL stripped from the elements that are not
204 // supposed to be sent as HTTP referrer: username, password and ref fragment.
205 // For invalid URLs or URLs that no valid referrers, an empty URL will be
206 // returned.
207 GURL GetAsReferrer() const;
208
209 // Returns true if the scheme for the current URL is a known "standard-format"
210 // scheme. A standard-format scheme adheres to what RFC 3986 calls "generic
211 // URI syntax" (https://tools.ietf.org/html/rfc3986#section-3). This includes
212 // file: and filesystem:, which some callers may want to filter out explicitly
213 // by calling SchemeIsFile[System].
214 bool IsStandard() const;
215
216 // Returns true when the url is of the form about:blank, about:blank?foo or
217 // about:blank/#foo.
218 bool IsAboutBlank() const;
219
220 // Returns true when the url is of the form about:srcdoc, about:srcdoc?foo or
221 // about:srcdoc/#foo.
222 bool IsAboutSrcdoc() const;
223
224 // Returns true if the given parameter (should be lower-case ASCII to match
225 // the canonicalized scheme) is the scheme for this URL. Do not include a
226 // colon.
227 bool SchemeIs(base::StringPiece lower_ascii_scheme) const;
228
229 // Returns true if the scheme is "http" or "https".
230 bool SchemeIsHTTPOrHTTPS() const;
231
232 // Returns true is the scheme is "ws" or "wss".
233 bool SchemeIsWSOrWSS() const;
234
235 // We often need to know if this is a file URL. File URLs are "standard", but
236 // are often treated separately by some programs.
237 bool SchemeIsFile() const {
238 return SchemeIs(url::kFileScheme);
239 }
240
241 // FileSystem URLs need to be treated differently in some cases.
242 bool SchemeIsFileSystem() const {
243 return SchemeIs(url::kFileSystemScheme);
244 }
245
246 // Returns true if the scheme indicates a network connection that uses TLS or
247 // some other cryptographic protocol (e.g. QUIC) for security.
248 //
249 // This function is a not a complete test of whether or not an origin's code
250 // is minimally trustworthy. For that, see Chromium's |IsOriginSecure| for a
251 // higher-level and more complete semantics. See that function's documentation
252 // for more detail.
253 bool SchemeIsCryptographic() const;
254
255 // As above, but static. Parameter should be lower-case ASCII.
256 static bool SchemeIsCryptographic(base::StringPiece lower_ascii_scheme);
257
258 // Returns true if the scheme is "blob".
259 bool SchemeIsBlob() const {
260 return SchemeIs(url::kBlobScheme);
261 }
262
263 // For most URLs, the "content" is everything after the scheme (skipping the
264 // scheme delimiting colon) and before the fragment (skipping the fragment
265 // delimiting octothorpe). For javascript URLs the "content" also includes the
266 // fragment delimiter and fragment.
267 //
268 // It is an error to get the content of an invalid URL: the result will be an
269 // empty string.
270 std::string GetContent() const;
271
272 // Returns true if the hostname is an IP address. Note: this function isn't
273 // as cheap as a simple getter because it re-parses the hostname to verify.
274 bool HostIsIPAddress() const;
275
276 // Not including the colon. If you are comparing schemes, prefer SchemeIs.
277 bool has_scheme() const {
278 return parsed_.scheme.len >= 0;
279 }
280 std::string scheme() const {
281 return ComponentString(parsed_.scheme);
282 }
283 base::StringPiece scheme_piece() const {
284 return ComponentStringPiece(parsed_.scheme);
285 }
286
287 bool has_username() const {
288 return parsed_.username.len >= 0;
289 }
290 std::string username() const {
291 return ComponentString(parsed_.username);
292 }
293 base::StringPiece username_piece() const {
294 return ComponentStringPiece(parsed_.username);
295 }
296
297 bool has_password() const {
298 return parsed_.password.len >= 0;
299 }
300 std::string password() const {
301 return ComponentString(parsed_.password);
302 }
303 base::StringPiece password_piece() const {
304 return ComponentStringPiece(parsed_.password);
305 }
306
307 // The host may be a hostname, an IPv4 address, or an IPv6 literal surrounded
308 // by square brackets, like "[2001:db8::1]". To exclude these brackets, use
309 // HostNoBrackets() below.
310 bool has_host() const {
311 // Note that hosts are special, absence of host means length 0.
312 return parsed_.host.len > 0;
313 }
314 std::string host() const {
315 return ComponentString(parsed_.host);
316 }
317 base::StringPiece host_piece() const {
318 return ComponentStringPiece(parsed_.host);
319 }
320
321 // The port if one is explicitly specified. Most callers will want IntPort()
322 // or EffectiveIntPort() instead of these. The getters will not include the
323 // ':'.
324 bool has_port() const {
325 return parsed_.port.len >= 0;
326 }
327 std::string port() const {
328 return ComponentString(parsed_.port);
329 }
330 base::StringPiece port_piece() const {
331 return ComponentStringPiece(parsed_.port);
332 }
333
334 // Including first slash following host, up to the query. The URL
335 // "http://www.google.com/" has a path of "/".
336 bool has_path() const {
337 return parsed_.path.len >= 0;
338 }
339 std::string path() const {
340 return ComponentString(parsed_.path);
341 }
342 base::StringPiece path_piece() const {
343 return ComponentStringPiece(parsed_.path);
344 }
345
346 // Stuff following '?' up to the ref. The getters will not include the '?'.
347 bool has_query() const {
348 return parsed_.query.len >= 0;
349 }
350 std::string query() const {
351 return ComponentString(parsed_.query);
352 }
353 base::StringPiece query_piece() const {
354 return ComponentStringPiece(parsed_.query);
355 }
356
357 // Stuff following '#' to the end of the string. This will be %-escaped UTF-8.
358 // The getters will not include the '#'.
359 bool has_ref() const {
360 return parsed_.ref.len >= 0;
361 }
362 std::string ref() const {
363 return ComponentString(parsed_.ref);
364 }
365 base::StringPiece ref_piece() const {
366 return ComponentStringPiece(parsed_.ref);
367 }
368
369 // Returns a parsed version of the port. Can also be any of the special
370 // values defined in Parsed for ExtractPort.
371 int IntPort() const;
372
373 // Returns the port number of the URL, or the default port number.
374 // If the scheme has no concept of port (or unknown default) returns
375 // PORT_UNSPECIFIED.
376 int EffectiveIntPort() const;
377
378 // Extracts the filename portion of the path and returns it. The filename
379 // is everything after the last slash in the path. This may be empty.
380 std::string ExtractFileName() const;
381
382 // Returns the path that should be sent to the server. This is the path,
383 // parameter, and query portions of the URL. It is guaranteed to be ASCII.
384 std::string PathForRequest() const;
385
386 // Returns the same characters as PathForRequest(), avoiding a copy.
387 base::StringPiece PathForRequestPiece() const;
388
389 // Returns the host, excluding the square brackets surrounding IPv6 address
390 // literals. This can be useful for passing to getaddrinfo().
391 std::string HostNoBrackets() const;
392
393 // Returns the same characters as HostNoBrackets(), avoiding a copy.
394 base::StringPiece HostNoBracketsPiece() const;
395
396 // Returns true if this URL's host matches or is in the same domain as
397 // the given input string. For example, if the hostname of the URL is
398 // "www.google.com", this will return true for "com", "google.com", and
399 // "www.google.com".
400 //
401 // The input domain should match host canonicalization rules. i.e. the input
402 // should be lowercase except for escape chars.
403 //
404 // This call is more efficient than getting the host and checking whether the
405 // host has the specific domain or not because no copies or object
406 // constructions are done.
407 bool DomainIs(base::StringPiece canonical_domain) const;
408
409 // Checks whether or not two URLs differ only in the ref (the part after
410 // the # character).
411 bool EqualsIgnoringRef(const GURL& other) const;
412
413 // Swaps the contents of this GURL object with |other|, without doing
414 // any memory allocations.
415 void Swap(GURL* other);
416
417 // Returns a reference to a singleton empty GURL. This object is for callers
418 // who return references but don't have anything to return in some cases.
419 // If you just want an empty URL for normal use, prefer GURL(). This function
420 // may be called from any thread.
421 static const GURL& EmptyGURL();
422
423 // Returns the inner URL of a nested URL (currently only non-null for
424 // filesystem URLs).
425 //
426 // TODO(mmenke): inner_url().spec() currently returns the same value as
427 // caling spec() on the GURL itself. This should be fixed.
428 // See https://crbug.com/619596
429 const GURL* inner_url() const {
430 return inner_url_.get();
431 }
432
433 // Estimates dynamic memory usage.
434 // See base/trace_event/memory_usage_estimator.h for more info.
435 size_t EstimateMemoryUsage() const;
436
437 private:
438 // Variant of the string parsing constructor that allows the caller to elect
439 // retain trailing whitespace, if any, on the passed URL spec, but only if
440 // the scheme is one that allows trailing whitespace. The primary use-case is
441 // for data: URLs. In most cases, you want to use the single parameter
442 // constructor above.
443 enum RetainWhiteSpaceSelector { RETAIN_TRAILING_PATH_WHITEPACE };
444 GURL(const std::string& url_string, RetainWhiteSpaceSelector);
445
446 template<typename STR>
447 void InitCanonical(base::BasicStringPiece<STR> input_spec,
448 bool trim_path_end);
449
450 void InitializeFromCanonicalSpec();
451
452 // Helper used by IsAboutBlank and IsAboutSrcdoc.
453 bool IsAboutUrl(base::StringPiece allowed_path) const;
454
455 // Returns the substring of the input identified by the given component.
456 std::string ComponentString(const url::Component& comp) const {
457 if (comp.len <= 0)
458 return std::string();
459 return std::string(spec_, comp.begin, comp.len);
460 }
461 base::StringPiece ComponentStringPiece(const url::Component& comp) const {
462 if (comp.len <= 0)
463 return base::StringPiece();
464 return base::StringPiece(&spec_[comp.begin], comp.len);
465 }
466
467 // The actual text of the URL, in canonical ASCII form.
468 std::string spec_;
469
470 // Set when the given URL is valid. Otherwise, we may still have a spec and
471 // components, but they may not identify valid resources (for example, an
472 // invalid port number, invalid characters in the scheme, etc.).
473 bool is_valid_;
474
475 // Identified components of the canonical spec.
476 url::Parsed parsed_;
477
478 // Used for nested schemes [currently only filesystem:].
479 std::unique_ptr<GURL> inner_url_;
480 };
481
482 // Stream operator so GURL can be used in assertion statements.
483 COMPONENT_EXPORT(URL)
484 std::ostream& operator<<(std::ostream& out, const GURL& url);
485
486 COMPONENT_EXPORT(URL) bool operator==(const GURL& x, const GURL& y);
487 COMPONENT_EXPORT(URL) bool operator!=(const GURL& x, const GURL& y);
488
489 // Equality operator for comparing raw spec_. This should be used in place of
490 // url == GURL(spec) where |spec| is known (i.e. constants). This is to prevent
491 // needlessly re-parsing |spec| into a temporary GURL.
492 COMPONENT_EXPORT(URL)
493 bool operator==(const GURL& x, const base::StringPiece& spec);
494 COMPONENT_EXPORT(URL)
495 bool operator==(const base::StringPiece& spec, const GURL& x);
496 COMPONENT_EXPORT(URL)
497 bool operator!=(const GURL& x, const base::StringPiece& spec);
498 COMPONENT_EXPORT(URL)
499 bool operator!=(const base::StringPiece& spec, const GURL& x);
500
501 // DEBUG_ALIAS_FOR_GURL(var_name, url) copies |url| into a new stack-allocated
502 // variable named |<var_name>|. This helps ensure that the value of |url| gets
503 // preserved in crash dumps.
504 #define DEBUG_ALIAS_FOR_GURL(var_name, url) \
505 DEBUG_ALIAS_FOR_CSTR(var_name, (url).possibly_invalid_spec().c_str(), 128)
506
507 #endif // URL_GURL_H_
508