blob: a98e7affdb607a2b3df1b1d170f679cfc5802529 [file] [log] [blame]
// Copyright 2015 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#ifndef URL_SCHEME_HOST_PORT_H_
#define URL_SCHEME_HOST_PORT_H_
#include <stdint.h>
#include <string>
#include "base/component_export.h"
#include "base/strings/string_piece.h"
class GURL;
namespace url {
struct Parsed;
// This class represents a (scheme, host, port) tuple extracted from a URL.
//
// The primary purpose of this class is to represent relevant network-authority
// information for a URL. It is _not_ an Origin, as described in RFC 6454. In
// particular, it is generally NOT the right thing to use for security
// decisions.
//
// Instead, this class is a mechanism for simplifying URLs with standard schemes
// (that is, those which follow the generic syntax of RFC 3986) down to the
// uniquely identifying information necessary for network fetches. This makes it
// suitable as a cache key for a collection of active connections, for instance.
// It may, however, be inappropriate to use as a cache key for persistent
// storage associated with a host.
//
// In particular, note that:
//
// * SchemeHostPort can only represent schemes which follow the RFC 3986 syntax
// (e.g. those registered with GURL as "standard schemes"). Non-standard
// schemes such as "blob", "filesystem", "data", and "javascript" can only be
// represented as invalid SchemeHostPort objects.
//
// * For example, the "file" scheme follows the standard syntax, but it is
// important to note that the authority portion (host, port) is optional.
// URLs without an authority portion will be represented with an empty string
// for the host, and a port of 0 (e.g. "file:///etc/hosts" =>
// ("file", "", 0)), and URLs with a host-only authority portion will be
// represented with a port of 0 (e.g. "file://example.com/etc/hosts" =>
// ("file", "example.com", 0)). See Section 3 of RFC 3986 to better understand
// these constructs.
//
// * SchemeHostPort has no notion of the Origin concept (RFC 6454), and in
// particular, it has no notion of an opaque Origin. If you need to take
// opaque origins into account (and, if you're making security-relevant
// decisions then you absolutely do), please use 'url::Origin' instead.
//
// Usage:
//
// * SchemeHostPort objects are commonly created from GURL objects:
//
// GURL url("https://example.com/");
// url::SchemeHostPort tuple(url);
// tuple.scheme(); // "https"
// tuple.host(); // "example.com"
// tuple.port(); // 443
//
// * Objects may also be explicitly created and compared:
//
// url::SchemeHostPort tuple(url::kHttpsScheme, "example.com", 443);
// tuple.scheme(); // "https"
// tuple.host(); // "example.com"
// tuple.port(); // 443
//
// GURL url("https://example.com/");
// tuple == url::SchemeHostPort(url); // true
class COMPONENT_EXPORT(URL) SchemeHostPort {
public:
// Creates an invalid (scheme, host, port) tuple, which represents an invalid
// or non-standard URL.
SchemeHostPort();
// Creates a (scheme, host, port) tuple. |host| must be a canonicalized
// A-label (that is, '☃.net' must be provided as 'xn--n3h.net'). |scheme|
// must be a standard scheme. |port| must be 0 if |scheme| does not support
// ports (e.g. 'file').
//
// Copies the data in |scheme| and |host|.
SchemeHostPort(base::StringPiece scheme,
base::StringPiece host,
uint16_t port);
// Metadata influencing whether or not the constructor should sanity check
// host canonicalization.
enum ConstructPolicy { CHECK_CANONICALIZATION, ALREADY_CANONICALIZED };
// Creates a (scheme, host, port) tuple without performing sanity checking
// that the host and port are canonicalized. This should only be used when
// converting between already normalized types, and should NOT be used for
// IPC.
SchemeHostPort(std::string scheme,
std::string host,
uint16_t port,
ConstructPolicy policy);
// Creates a (scheme, host, port) tuple from |url|, as described at
// https://tools.ietf.org/html/rfc6454#section-4
//
// If |url| is invalid or non-standard, the result will be an invalid
// SchemeHostPort object.
explicit SchemeHostPort(const GURL& url);
// Copyable and movable.
SchemeHostPort(const SchemeHostPort&) = default;
SchemeHostPort& operator=(const SchemeHostPort&) = default;
SchemeHostPort(SchemeHostPort&&) noexcept = default;
SchemeHostPort& operator=(SchemeHostPort&&) noexcept = default;
~SchemeHostPort();
// Returns the host component, in URL form. That is all IDN domain names will
// be expressed as A-Labels ('☃.net' will be returned as 'xn--n3h.net'), and
// and all IPv6 addresses will be enclosed in brackets ("[2001:db8::1]").
const std::string& host() const { return host_; }
const std::string& scheme() const { return scheme_; }
uint16_t port() const { return port_; }
bool IsValid() const;
// Serializes the SchemeHostPort tuple to a canonical form.
//
// While this string form resembles the Origin serialization specified in
// Section 6.2 of RFC 6454, it is important to note that invalid
// SchemeHostPort tuples serialize to the empty string, rather than being
// serialized as would an opaque Origin.
std::string Serialize() const;
// Efficiently returns what GURL(Serialize()) would return, without needing to
// re-parse the URL. Note: this still performs allocations to copy data into
// GURL, so please avoid using this method if you only need to work on
// schemes, hosts, or ports individually.
// For example, see crrev.com/c/3637099/comments/782360d0_e14757be.
GURL GetURL() const;
// Two SchemeHostPort objects are "equal" iff their schemes, hosts, and ports
// are exact matches.
//
// Note that this comparison is _not_ the same as an origin-based comparison.
// In particular, invalid SchemeHostPort objects match each other (and
// themselves). Opaque origins, on the other hand, would not.
bool operator==(const SchemeHostPort& other) const {
return port_ == other.port() && scheme_ == other.scheme() &&
host_ == other.host();
}
bool operator!=(const SchemeHostPort& other) const {
return !(*this == other);
}
// Allows SchemeHostPort to be used as a key in STL (for example, a std::set
// or std::map).
bool operator<(const SchemeHostPort& other) const;
private:
std::string SerializeInternal(url::Parsed* parsed) const;
std::string scheme_;
std::string host_;
uint16_t port_ = 0;
};
COMPONENT_EXPORT(URL)
std::ostream& operator<<(std::ostream& out,
const SchemeHostPort& scheme_host_port);
} // namespace url
#endif // URL_SCHEME_HOST_PORT_H_