mirror of
https://github.com/klzgrad/naiveproxy.git
synced 2024-11-24 14:26:09 +03:00
491 lines
20 KiB
C
491 lines
20 KiB
C
|
// Copyright 2013 The Chromium Authors. All rights reserved.
|
||
|
// Use of this source code is governed by a BSD-style license that can be
|
||
|
// found in the LICENSE file.
|
||
|
|
||
|
#ifndef URL_GURL_H_
|
||
|
#define URL_GURL_H_
|
||
|
|
||
|
#include <stddef.h>
|
||
|
|
||
|
#include <iosfwd>
|
||
|
#include <memory>
|
||
|
#include <string>
|
||
|
|
||
|
#include "base/debug/alias.h"
|
||
|
#include "base/strings/string16.h"
|
||
|
#include "base/strings/string_piece.h"
|
||
|
#include "url/third_party/mozilla/url_parse.h"
|
||
|
#include "url/url_canon.h"
|
||
|
#include "url/url_canon_stdstring.h"
|
||
|
#include "url/url_constants.h"
|
||
|
#include "url/url_export.h"
|
||
|
|
||
|
// Represents a URL.
|
||
|
//
|
||
|
// A parsed canonicalized URL is guaranteed to be UTF-8. Any non-ASCII input
|
||
|
// characters are UTF-8 encoded and % escaped to ASCII.
|
||
|
//
|
||
|
// The string representation of a URL is called the spec(). Getting the
|
||
|
// spec will assert if the URL is invalid to help protect against malicious
|
||
|
// URLs. If you want the "best effort" canonicalization of an invalid URL, you
|
||
|
// can use possibly_invalid_spec(). Test validity with is_valid(). Data and
|
||
|
// javascript URLs use GetContent() to extract the data.
|
||
|
//
|
||
|
// This class has existence checkers and getters for the various components of
|
||
|
// a URL. Existence is different than being nonempty. "http://www.google.com/?"
|
||
|
// has a query that just happens to be empty, and has_query() will return true
|
||
|
// while the query getters will return the empty string.
|
||
|
//
|
||
|
// Prefer not to modify a URL using string operations (though sometimes this is
|
||
|
// unavoidable). Instead, use ReplaceComponents which can replace or delete
|
||
|
// multiple parts of a URL in one step, doesn't re-canonicalize unchanged
|
||
|
// sections, and avoids some screw-ups. An example is creating a URL with a
|
||
|
// path that contains a literal '#'. Using string concatenation will generate a
|
||
|
// URL with a truncated path and a reference fragment, while ReplaceComponents
|
||
|
// will know to escape this and produce the desired result.
|
||
|
class URL_EXPORT GURL {
|
||
|
public:
|
||
|
typedef url::StringPieceReplacements<std::string> Replacements;
|
||
|
typedef url::StringPieceReplacements<base::string16> ReplacementsW;
|
||
|
|
||
|
// Creates an empty, invalid URL.
|
||
|
GURL();
|
||
|
|
||
|
// Copy construction is relatively inexpensive, with most of the time going
|
||
|
// to reallocating the string. It does not re-parse.
|
||
|
GURL(const GURL& other);
|
||
|
GURL(GURL&& other) noexcept;
|
||
|
|
||
|
// The strings to this contructor should be UTF-8 / UTF-16.
|
||
|
explicit GURL(base::StringPiece url_string);
|
||
|
explicit GURL(base::StringPiece16 url_string);
|
||
|
|
||
|
// Constructor for URLs that have already been parsed and canonicalized. This
|
||
|
// is used for conversions from KURL, for example. The caller must supply all
|
||
|
// information associated with the URL, which must be correct and consistent.
|
||
|
GURL(const char* canonical_spec,
|
||
|
size_t canonical_spec_len,
|
||
|
const url::Parsed& parsed,
|
||
|
bool is_valid);
|
||
|
// Notice that we take the canonical_spec by value so that we can convert
|
||
|
// from WebURL without copying the string. When we call this constructor
|
||
|
// we pass in a temporary std::string, which lets the compiler skip the
|
||
|
// copy and just move the std::string into the function argument. In the
|
||
|
// implementation, we use std::move to move the data into the GURL itself,
|
||
|
// which means we end up with zero copies.
|
||
|
GURL(std::string canonical_spec, const url::Parsed& parsed, bool is_valid);
|
||
|
|
||
|
~GURL();
|
||
|
|
||
|
GURL& operator=(const GURL& other);
|
||
|
GURL& operator=(GURL&& other) noexcept;
|
||
|
|
||
|
// Returns true when this object represents a valid parsed URL. When not
|
||
|
// valid, other functions will still succeed, but you will not get canonical
|
||
|
// data out in the format you may be expecting. Instead, we keep something
|
||
|
// "reasonable looking" so that the user can see how it's busted if
|
||
|
// displayed to them.
|
||
|
bool is_valid() const {
|
||
|
return is_valid_;
|
||
|
}
|
||
|
|
||
|
// Returns true if the URL is zero-length. Note that empty URLs are also
|
||
|
// invalid, and is_valid() will return false for them. This is provided
|
||
|
// because some users may want to treat the empty case differently.
|
||
|
bool is_empty() const {
|
||
|
return spec_.empty();
|
||
|
}
|
||
|
|
||
|
// Returns the raw spec, i.e., the full text of the URL, in canonical UTF-8,
|
||
|
// if the URL is valid. If the URL is not valid, this will assert and return
|
||
|
// the empty string (for safety in release builds, to keep them from being
|
||
|
// misused which might be a security problem).
|
||
|
//
|
||
|
// The URL will be ASCII (non-ASCII characters will be %-escaped UTF-8).
|
||
|
//
|
||
|
// The exception is for empty() URLs (which are !is_valid()) but this will
|
||
|
// return the empty string without asserting.
|
||
|
//
|
||
|
// Use invalid_spec() below to get the unusable spec of an invalid URL. This
|
||
|
// separation is designed to prevent errors that may cause security problems
|
||
|
// that could result from the mistaken use of an invalid URL.
|
||
|
const std::string& spec() const;
|
||
|
|
||
|
// Returns the potentially invalid spec for a the URL. This spec MUST NOT be
|
||
|
// modified or sent over the network. It is designed to be displayed in error
|
||
|
// messages to the user, as the appearance of the spec may explain the error.
|
||
|
// If the spec is valid, the valid spec will be returned.
|
||
|
//
|
||
|
// The returned string is guaranteed to be valid UTF-8.
|
||
|
const std::string& possibly_invalid_spec() const {
|
||
|
return spec_;
|
||
|
}
|
||
|
|
||
|
// Getter for the raw parsed structure. This allows callers to locate parts
|
||
|
// of the URL within the spec themselves. Most callers should consider using
|
||
|
// the individual component getters below.
|
||
|
//
|
||
|
// The returned parsed structure will reference into the raw spec, which may
|
||
|
// or may not be valid. If you are using this to index into the spec, BE
|
||
|
// SURE YOU ARE USING possibly_invalid_spec() to get the spec, and that you
|
||
|
// don't do anything "important" with invalid specs.
|
||
|
const url::Parsed& parsed_for_possibly_invalid_spec() const {
|
||
|
return parsed_;
|
||
|
}
|
||
|
|
||
|
// Allows GURL to used as a key in STL (for example, a std::set or std::map).
|
||
|
bool operator<(const GURL& other) const;
|
||
|
bool operator>(const GURL& other) const;
|
||
|
|
||
|
// Resolves a URL that's possibly relative to this object's URL, and returns
|
||
|
// it. Absolute URLs are also handled according to the rules of URLs on web
|
||
|
// pages.
|
||
|
//
|
||
|
// It may be impossible to resolve the URLs properly. If the input is not
|
||
|
// "standard" (IsStandard() == false) and the input looks relative, we can't
|
||
|
// resolve it. In these cases, the result will be an empty, invalid GURL.
|
||
|
//
|
||
|
// The result may also be a nonempty, invalid URL if the input has some kind
|
||
|
// of encoding error. In these cases, we will try to construct a "good" URL
|
||
|
// that may have meaning to the user, but it will be marked invalid.
|
||
|
//
|
||
|
// It is an error to resolve a URL relative to an invalid URL. The result
|
||
|
// will be the empty URL.
|
||
|
GURL Resolve(base::StringPiece relative) const;
|
||
|
GURL Resolve(base::StringPiece16 relative) const;
|
||
|
|
||
|
// Creates a new GURL by replacing the current URL's components with the
|
||
|
// supplied versions. See the Replacements class in url_canon.h for more.
|
||
|
//
|
||
|
// These are not particularly quick, so avoid doing mutations when possible.
|
||
|
// Prefer the 8-bit version when possible.
|
||
|
//
|
||
|
// It is an error to replace components of an invalid URL. The result will
|
||
|
// be the empty URL.
|
||
|
//
|
||
|
// Note that we use the more general url::Replacements type to give
|
||
|
// callers extra flexibility rather than our override.
|
||
|
GURL ReplaceComponents(const url::Replacements<char>& replacements) const;
|
||
|
GURL ReplaceComponents(
|
||
|
const url::Replacements<base::char16>& replacements) const;
|
||
|
|
||
|
// A helper function that is equivalent to replacing the path with a slash
|
||
|
// and clearing out everything after that. We sometimes need to know just the
|
||
|
// scheme and the authority. If this URL is not a standard URL (it doesn't
|
||
|
// have the regular authority and path sections), then the result will be
|
||
|
// an empty, invalid GURL. Note that this *does* work for file: URLs, which
|
||
|
// some callers may want to filter out before calling this.
|
||
|
//
|
||
|
// It is an error to get an empty path on an invalid URL. The result
|
||
|
// will be the empty URL.
|
||
|
GURL GetWithEmptyPath() const;
|
||
|
|
||
|
// A helper function to return a GURL without the filename, query values, and
|
||
|
// fragment. For example,
|
||
|
// GURL("https://www.foo.com/index.html?q=test").GetWithoutFilename().spec()
|
||
|
// will return "https://www.foo.com/".
|
||
|
// GURL("https://www.foo.com/bar/").GetWithoutFilename().spec()
|
||
|
// will return "https://www.foo.com/bar/". If the GURL is invalid or missing a
|
||
|
// scheme, authority or path, it will return an empty, invalid GURL.
|
||
|
GURL GetWithoutFilename() const;
|
||
|
|
||
|
// A helper function to return a GURL containing just the scheme, host,
|
||
|
// and port from a URL. Equivalent to clearing any username and password,
|
||
|
// replacing the path with a slash, and clearing everything after that. If
|
||
|
// this URL is not a standard URL, then the result will be an empty,
|
||
|
// invalid GURL. If the URL has neither username nor password, this
|
||
|
// degenerates to GetWithEmptyPath().
|
||
|
//
|
||
|
// It is an error to get the origin of an invalid URL. The result
|
||
|
// will be the empty URL.
|
||
|
GURL GetOrigin() const;
|
||
|
|
||
|
// A helper function to return a GURL stripped from the elements that are not
|
||
|
// supposed to be sent as HTTP referrer: username, password and ref fragment.
|
||
|
// For invalid URLs or URLs that no valid referrers, an empty URL will be
|
||
|
// returned.
|
||
|
GURL GetAsReferrer() const;
|
||
|
|
||
|
// Returns true if the scheme for the current URL is a known "standard-format"
|
||
|
// scheme. A standard-format scheme adheres to what RFC 3986 calls "generic
|
||
|
// URI syntax" (https://tools.ietf.org/html/rfc3986#section-3). This includes
|
||
|
// file: and filesystem:, which some callers may want to filter out explicitly
|
||
|
// by calling SchemeIsFile[System].
|
||
|
bool IsStandard() const;
|
||
|
|
||
|
// Returns true when the url is of the form about:blank, about:blank?foo or
|
||
|
// about:blank/#foo.
|
||
|
bool IsAboutBlank() const;
|
||
|
|
||
|
// Returns true if the given parameter (should be lower-case ASCII to match
|
||
|
// the canonicalized scheme) is the scheme for this URL. Do not include a
|
||
|
// colon.
|
||
|
bool SchemeIs(base::StringPiece lower_ascii_scheme) const;
|
||
|
|
||
|
// Returns true if the scheme is "http" or "https".
|
||
|
bool SchemeIsHTTPOrHTTPS() const;
|
||
|
|
||
|
// Returns true if the scheme is valid for use as a referrer.
|
||
|
bool SchemeIsValidForReferrer() const;
|
||
|
|
||
|
// Returns true is the scheme is "ws" or "wss".
|
||
|
bool SchemeIsWSOrWSS() const;
|
||
|
|
||
|
// We often need to know if this is a file URL. File URLs are "standard", but
|
||
|
// are often treated separately by some programs.
|
||
|
bool SchemeIsFile() const {
|
||
|
return SchemeIs(url::kFileScheme);
|
||
|
}
|
||
|
|
||
|
// FileSystem URLs need to be treated differently in some cases.
|
||
|
bool SchemeIsFileSystem() const {
|
||
|
return SchemeIs(url::kFileSystemScheme);
|
||
|
}
|
||
|
|
||
|
// Returns true if the scheme indicates a network connection that uses TLS or
|
||
|
// some other cryptographic protocol (e.g. QUIC) for security.
|
||
|
//
|
||
|
// This function is a not a complete test of whether or not an origin's code
|
||
|
// is minimally trustworthy. For that, see Chromium's |IsOriginSecure| for a
|
||
|
// higher-level and more complete semantics. See that function's documentation
|
||
|
// for more detail.
|
||
|
bool SchemeIsCryptographic() const {
|
||
|
return SchemeIs(url::kHttpsScheme) || SchemeIs(url::kWssScheme);
|
||
|
}
|
||
|
|
||
|
// Returns true if the scheme is "blob".
|
||
|
bool SchemeIsBlob() const {
|
||
|
return SchemeIs(url::kBlobScheme);
|
||
|
}
|
||
|
|
||
|
// The "content" of the URL is everything after the scheme (skipping the
|
||
|
// scheme delimiting colon). It is an error to get the content of an invalid
|
||
|
// URL: the result will be an empty string.
|
||
|
std::string GetContent() const;
|
||
|
|
||
|
// Returns true if the hostname is an IP address. Note: this function isn't
|
||
|
// as cheap as a simple getter because it re-parses the hostname to verify.
|
||
|
bool HostIsIPAddress() const;
|
||
|
|
||
|
// Not including the colon. If you are comparing schemes, prefer SchemeIs.
|
||
|
bool has_scheme() const {
|
||
|
return parsed_.scheme.len >= 0;
|
||
|
}
|
||
|
std::string scheme() const {
|
||
|
return ComponentString(parsed_.scheme);
|
||
|
}
|
||
|
base::StringPiece scheme_piece() const {
|
||
|
return ComponentStringPiece(parsed_.scheme);
|
||
|
}
|
||
|
|
||
|
bool has_username() const {
|
||
|
return parsed_.username.len >= 0;
|
||
|
}
|
||
|
std::string username() const {
|
||
|
return ComponentString(parsed_.username);
|
||
|
}
|
||
|
base::StringPiece username_piece() const {
|
||
|
return ComponentStringPiece(parsed_.username);
|
||
|
}
|
||
|
|
||
|
bool has_password() const {
|
||
|
return parsed_.password.len >= 0;
|
||
|
}
|
||
|
std::string password() const {
|
||
|
return ComponentString(parsed_.password);
|
||
|
}
|
||
|
base::StringPiece password_piece() const {
|
||
|
return ComponentStringPiece(parsed_.password);
|
||
|
}
|
||
|
|
||
|
// The host may be a hostname, an IPv4 address, or an IPv6 literal surrounded
|
||
|
// by square brackets, like "[2001:db8::1]". To exclude these brackets, use
|
||
|
// HostNoBrackets() below.
|
||
|
bool has_host() const {
|
||
|
// Note that hosts are special, absence of host means length 0.
|
||
|
return parsed_.host.len > 0;
|
||
|
}
|
||
|
std::string host() const {
|
||
|
return ComponentString(parsed_.host);
|
||
|
}
|
||
|
base::StringPiece host_piece() const {
|
||
|
return ComponentStringPiece(parsed_.host);
|
||
|
}
|
||
|
|
||
|
// The port if one is explicitly specified. Most callers will want IntPort()
|
||
|
// or EffectiveIntPort() instead of these. The getters will not include the
|
||
|
// ':'.
|
||
|
bool has_port() const {
|
||
|
return parsed_.port.len >= 0;
|
||
|
}
|
||
|
std::string port() const {
|
||
|
return ComponentString(parsed_.port);
|
||
|
}
|
||
|
base::StringPiece port_piece() const {
|
||
|
return ComponentStringPiece(parsed_.port);
|
||
|
}
|
||
|
|
||
|
// Including first slash following host, up to the query. The URL
|
||
|
// "http://www.google.com/" has a path of "/".
|
||
|
bool has_path() const {
|
||
|
return parsed_.path.len >= 0;
|
||
|
}
|
||
|
std::string path() const {
|
||
|
return ComponentString(parsed_.path);
|
||
|
}
|
||
|
base::StringPiece path_piece() const {
|
||
|
return ComponentStringPiece(parsed_.path);
|
||
|
}
|
||
|
|
||
|
// Stuff following '?' up to the ref. The getters will not include the '?'.
|
||
|
bool has_query() const {
|
||
|
return parsed_.query.len >= 0;
|
||
|
}
|
||
|
std::string query() const {
|
||
|
return ComponentString(parsed_.query);
|
||
|
}
|
||
|
base::StringPiece query_piece() const {
|
||
|
return ComponentStringPiece(parsed_.query);
|
||
|
}
|
||
|
|
||
|
// Stuff following '#' to the end of the string. This will be %-escaped UTF-8.
|
||
|
// The getters will not include the '#'.
|
||
|
bool has_ref() const {
|
||
|
return parsed_.ref.len >= 0;
|
||
|
}
|
||
|
std::string ref() const {
|
||
|
return ComponentString(parsed_.ref);
|
||
|
}
|
||
|
base::StringPiece ref_piece() const {
|
||
|
return ComponentStringPiece(parsed_.ref);
|
||
|
}
|
||
|
|
||
|
// Returns a parsed version of the port. Can also be any of the special
|
||
|
// values defined in Parsed for ExtractPort.
|
||
|
int IntPort() const;
|
||
|
|
||
|
// Returns the port number of the URL, or the default port number.
|
||
|
// If the scheme has no concept of port (or unknown default) returns
|
||
|
// PORT_UNSPECIFIED.
|
||
|
int EffectiveIntPort() const;
|
||
|
|
||
|
// Extracts the filename portion of the path and returns it. The filename
|
||
|
// is everything after the last slash in the path. This may be empty.
|
||
|
std::string ExtractFileName() const;
|
||
|
|
||
|
// Returns the path that should be sent to the server. This is the path,
|
||
|
// parameter, and query portions of the URL. It is guaranteed to be ASCII.
|
||
|
std::string PathForRequest() const;
|
||
|
|
||
|
// Returns the host, excluding the square brackets surrounding IPv6 address
|
||
|
// literals. This can be useful for passing to getaddrinfo().
|
||
|
std::string HostNoBrackets() const;
|
||
|
|
||
|
// Returns the same characters as HostNoBrackets(), avoiding a copy.
|
||
|
base::StringPiece HostNoBracketsPiece() const;
|
||
|
|
||
|
// Returns true if this URL's host matches or is in the same domain as
|
||
|
// the given input string. For example, if the hostname of the URL is
|
||
|
// "www.google.com", this will return true for "com", "google.com", and
|
||
|
// "www.google.com".
|
||
|
//
|
||
|
// The input domain should match host canonicalization rules. i.e. the input
|
||
|
// should be lowercase except for escape chars.
|
||
|
//
|
||
|
// This call is more efficient than getting the host and checking whether the
|
||
|
// host has the specific domain or not because no copies or object
|
||
|
// constructions are done.
|
||
|
bool DomainIs(base::StringPiece canonical_domain) const;
|
||
|
|
||
|
// Checks whether or not two URLs differ only in the ref (the part after
|
||
|
// the # character).
|
||
|
bool EqualsIgnoringRef(const GURL& other) const;
|
||
|
|
||
|
// Swaps the contents of this GURL object with |other|, without doing
|
||
|
// any memory allocations.
|
||
|
void Swap(GURL* other);
|
||
|
|
||
|
// Returns a reference to a singleton empty GURL. This object is for callers
|
||
|
// who return references but don't have anything to return in some cases.
|
||
|
// If you just want an empty URL for normal use, prefer GURL(). This function
|
||
|
// may be called from any thread.
|
||
|
static const GURL& EmptyGURL();
|
||
|
|
||
|
// Returns the inner URL of a nested URL (currently only non-null for
|
||
|
// filesystem URLs).
|
||
|
//
|
||
|
// TODO(mmenke): inner_url().spec() currently returns the same value as
|
||
|
// caling spec() on the GURL itself. This should be fixed.
|
||
|
// See https://crbug.com/619596
|
||
|
const GURL* inner_url() const {
|
||
|
return inner_url_.get();
|
||
|
}
|
||
|
|
||
|
// Estimates dynamic memory usage.
|
||
|
// See base/trace_event/memory_usage_estimator.h for more info.
|
||
|
size_t EstimateMemoryUsage() const;
|
||
|
|
||
|
private:
|
||
|
// Variant of the string parsing constructor that allows the caller to elect
|
||
|
// retain trailing whitespace, if any, on the passed URL spec, but only if
|
||
|
// the scheme is one that allows trailing whitespace. The primary use-case is
|
||
|
// for data: URLs. In most cases, you want to use the single parameter
|
||
|
// constructor above.
|
||
|
enum RetainWhiteSpaceSelector { RETAIN_TRAILING_PATH_WHITEPACE };
|
||
|
GURL(const std::string& url_string, RetainWhiteSpaceSelector);
|
||
|
|
||
|
template<typename STR>
|
||
|
void InitCanonical(base::BasicStringPiece<STR> input_spec,
|
||
|
bool trim_path_end);
|
||
|
|
||
|
void InitializeFromCanonicalSpec();
|
||
|
|
||
|
// Returns the substring of the input identified by the given component.
|
||
|
std::string ComponentString(const url::Component& comp) const {
|
||
|
if (comp.len <= 0)
|
||
|
return std::string();
|
||
|
return std::string(spec_, comp.begin, comp.len);
|
||
|
}
|
||
|
base::StringPiece ComponentStringPiece(const url::Component& comp) const {
|
||
|
if (comp.len <= 0)
|
||
|
return base::StringPiece();
|
||
|
return base::StringPiece(&spec_[comp.begin], comp.len);
|
||
|
}
|
||
|
|
||
|
// The actual text of the URL, in canonical ASCII form.
|
||
|
std::string spec_;
|
||
|
|
||
|
// Set when the given URL is valid. Otherwise, we may still have a spec and
|
||
|
// components, but they may not identify valid resources (for example, an
|
||
|
// invalid port number, invalid characters in the scheme, etc.).
|
||
|
bool is_valid_;
|
||
|
|
||
|
// Identified components of the canonical spec.
|
||
|
url::Parsed parsed_;
|
||
|
|
||
|
// Used for nested schemes [currently only filesystem:].
|
||
|
std::unique_ptr<GURL> inner_url_;
|
||
|
};
|
||
|
|
||
|
// Stream operator so GURL can be used in assertion statements.
|
||
|
URL_EXPORT std::ostream& operator<<(std::ostream& out, const GURL& url);
|
||
|
|
||
|
URL_EXPORT bool operator==(const GURL& x, const GURL& y);
|
||
|
URL_EXPORT bool operator!=(const GURL& x, const GURL& y);
|
||
|
|
||
|
// Equality operator for comparing raw spec_. This should be used in place of
|
||
|
// url == GURL(spec) where |spec| is known (i.e. constants). This is to prevent
|
||
|
// needlessly re-parsing |spec| into a temporary GURL.
|
||
|
URL_EXPORT bool operator==(const GURL& x, const base::StringPiece& spec);
|
||
|
URL_EXPORT bool operator==(const base::StringPiece& spec, const GURL& x);
|
||
|
URL_EXPORT bool operator!=(const GURL& x, const base::StringPiece& spec);
|
||
|
URL_EXPORT bool operator!=(const base::StringPiece& spec, const GURL& x);
|
||
|
|
||
|
// DEBUG_ALIAS_FOR_GURL(var_name, url) copies |url| into a new stack-allocated
|
||
|
// variable named |<var_name>|. This helps ensure that the value of |url| gets
|
||
|
// preserved in crash dumps.
|
||
|
#define DEBUG_ALIAS_FOR_GURL(var_name, url) \
|
||
|
DEBUG_ALIAS_FOR_CSTR(var_name, (url).possibly_invalid_spec().c_str(), 128)
|
||
|
|
||
|
#endif // URL_GURL_H_
|