Introduce 'url::Origin'.

url/origin.h

Index: url/origin.h
diff --git a/url/origin.h b/url/origin.h
new file mode 100644
index 0000000000000000000000000000000000000000..0587415e3c20402235c4693436091b95c307adcf
--- /dev/null
+++ b/url/origin.h
@@ -0,0 +1,115 @@
+// Copyright 2015 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_ORIGIN_H_
+#define URL_ORIGIN_H_
+
+#include <string>
+
+#include "base/strings/string16.h"
+#include "url/scheme_host_port.h"
+#include "url/third_party/mozilla/url_parse.h"
+#include "url/url_canon.h"
+#include "url/url_constants.h"
+#include "url/url_export.h"
+
+class GURL;
+
+namespace url {
+
+// An Origin is a tuple of (scheme, host, port), as described in RFC 6454.

[Ryan Sleevi, 2015/07/10 11:59:54]

I would hope that immediately after stating this, in the first paragraph (e.g.
before line 23), explain explicitly how these differ from url::SchemeHostPort.
Otherwise, I think the confusion will still exist.

Since Origin is composed on SchemeHostPort, that sort of 'downreference' in
comments is certainly allowed.

My stab, which is probably bad and I should feel bad, is

// While both SchemeHostPort and Origin are composed of tuples of (scheme, host,
port), it's important to
// understand they reflect different conceptual models. A SchemeHostPort
reflects the underlying storage of
// a standard-schemed URL (that is, the generic URL syntax of RFC 3986, using
scheme://authority ), where
// authority is a host and optional port (ignoring the user@ portion). However,
an Origin is the fundamental
// concept of the web's security model, and represents the boundaries in which
user agents generally
// compartmentalize information, and between which user agents enforce access
controls.
//
// An Origin may be created from a variety of URLs, not just those using the
generic syntax, and an
// Origin may not necessarily represent a reachable network endpoint. For
example, an empty Origin
// is a valid concept, indicating that it is unique and different from all other
Origins, including itself,
// while an empty SchemeHostPort is an invalid object.
//
// The choice between whether to use Origin or SchemeHostPort depends on the
context. For
// example, if recording a list of active network connections, a SchemeHostPort
may be wholly
// appropriate - it's just a storage of the tuple of information used to
establish that network connection.
// However, if performing access checks for some resource, for persisting things
in to long term
// storage, or for determining access controls between two arbitrary URLs, it's
generally more
// appropriate to use an Origin, to ensure that the security separation between
Origins is preserved.
//
// There are a few subtleties to note:


That's way wordier, and I'm sure you can further distill it to core points. But
I think as we land this, we want to provide clear and canonical documentation
for people about when they should prefer things. Likewise, in SchemeHostPort, we
want to be clear to indicate that it shouldn't be used for security-relevant
access checks, and instead should be seen moreso as a cache key of sorts for
network-related information.

[Mike West, 2015/07/17 09:58:09]

Poked at the text a bit.

+//
+// Origins are the fundamental component of the web's security model, and
+// represent the boundries within which user agents generally compartmentalize
+// information, and between which user agents enforce access controls.
+//
+// This class ought to be used when code needs to determine if two resources
+// are "same-origin", and when a canonical serialization of an origin is
+// required.
+//
+// Some origins are "unique", meaning that they are not same-origin with any
+// other origin (including themselves).
+//
+// There are a few subtleties to note:
+//
+// * Invalid and non-standard GURLs are parsed as unique origins. This includes
+//   non-hierarchical URLs like 'data:text/html,...' and 'javascript:alert(1)'.
+//
+// * GURLs with a 'file' scheme are tricky. They are parsed as ('file', '', 0),
+//   and are difficult to reason about in the abstract.

[Ryan Sleevi, 2015/07/10 11:59:54]

I feel like something more may be warranted to here.

+//
+// * Unique origins all serialize to the string "null"; this means that the
+//   serializations of two unique origins are '==' to each other, though the

[Ryan Sleevi, 2015/07/10 11:59:54]

s/are '==' to each other/are identical/

[Mike West, 2015/07/17 09:58:09]

Done.

+//   origins themselves are not "the same". This means that origins'
+//   serializations must not be relied upon for security checks.
+//
+// * GURLs with schemes of 'filesystem' or 'blob' parse the origin out of the
+//   internals of the URL. That is, 'filesystem:https://example.com/temporary/f'
+//   is parsed as ('https', 'example.com', 443).
+//
+// * The host component of an IPv6 address includes brackets, just like the URL
+//   representation.

[Ryan Sleevi, 2015/07/10 11:59:53]

Why is this? I found it a bit surprising?

[Mike West, 2015/07/17 09:58:09]

Why wouldn't we do this? It matches the representation you'll get in JavaScript,
and the representation you get from GURL.

+//
+// Usage:
+//
+// * Origins are generally constructed from GURL objects:

[Ryan Sleevi, 2015/07/10 11:59:53]

When I first read this comment, I had to scroll down to see if you had an
explicit scheme/host/port constructor, since that what I was expecting with the
way this was worded.

Perhaps an alternative wording

// * Unless creating a unique Origin, Origins are constructed from an already
canonicalized GURL:

[Mike West, 2015/07/17 09:58:09]

Ran with something like that.

+//
+//       GURL url("https://example.com/");

[Ryan Sleevi, 2015/07/10 11:59:53]

wrong indent level (2 != 4)

[Mike West, 2015/07/17 09:58:09]

[Insert eye rolling here.]

+//       url::Origin origin(url);
+//       origin.scheme(); // "https"
+//       origin.host(); // "example.com"
+//       origin.port(); // 443
+//       origin.IsUnique(); // false
+//
+// * To answer the question "Are |this| and |that| "same-origin" with each
+//   other?", use |Origin::IsSameOriginWith|:
+//
+//       if (this.IsSameOriginWith(that)) {

[Ryan Sleevi, 2015/07/10 11:59:53]

wrong indent level (2 != 4)

[Mike West, 2015/07/17 09:58:09]

[And here]

+//           // Amazingness goes here.

[Ryan Sleevi, 2015/07/10 11:59:54]

wrong indent level (2 != 4)

[Mike West, 2015/07/17 09:58:09]

[Also here]

+//       }
+class URL_EXPORT Origin {
+ public:
+  // Creates a unique Origin.
+  Origin();
+
+  // Creates an Origin from |url|, as described at
+  // https://url.spec.whatwg.org/#origin, with the following additions:
+  //
+  // 1. If |url| is invalid or non-standard, a unique Origin is constructed.
+  // 2. 'filesystem' URLs behave as 'blob' URLs (that is, the origin is parsed
+  //    out of everything in the URL which follows the scheme).
+  // 3. 'file' URLs all parse as ("file", "", 0).
+  Origin(const GURL& url);
+
+  ~Origin();
+
+  std::string scheme() const { return tuple_.scheme(); }
+  std::string host() const { return tuple_.host(); }
+  uint16 port() const { return tuple_.port(); }
+
+  // Origins may be forcibly treated as unique; this operation is irreversable.
+  void ForceUnique() { unique_ = true; }

[Ryan Sleevi, 2015/07/10 11:59:53]

I find this quite surprising. Why allow mutable state at all? I'd much rather
say you need to update the Origin to a new, unique origin, rather than have this
method.

[Mike West, 2015/07/17 09:58:09]

I think we'll need this for `file:` URLs, as we either treat them as unique or
not depending on decisions the embedder makes. This, of course, is absurd, but
it's the world we live in. I can drop it for the moment, and add it back in when
we need it. *shrug*

+  bool unique() const { return unique_; }
+
+  // An ASCII serialization of the Origin as per Section 6.2 of RFC 6454, with
+  // the addition that Origins with a 'file' scheme serialize to "file://".
+  std::string Serialize() const;
+
+  // Two Origins are "same-origin" iff their schemes, hosts, and ports are exact
+  // matches; and neither is unique.
+  bool IsSameOriginWith(const Origin& other) const;
+
+  // Allows SchemeHostPort to used as a key in STL (for example, a std::set or
+  // std::map).
+  bool operator<(const Origin& other) const;
+  bool operator>(const Origin& other) const;

[Ryan Sleevi, 2015/07/10 11:59:54]

operator> is not needed. All that's needed for anything on the
StrictWeakOrdering is an operator< or an std::less<typename> override, with a
preference for the former.

With strict weak ordering requirements, operator < is presumed to have symmetric
qualities, such that (a < b) == !(b < a). Equality is then equivalent to !(a <
b) && !(b < a).

[Mike West, 2015/07/17 09:58:09]

Done.

+
+ private:
+  url::SchemeHostPort tuple_;
+  bool unique_;

[Ryan Sleevi, 2015/07/10 11:59:54]

DISALLOW_COPY_AND_ASSIGN ?

+};
+
+}  // namespace url
+
+#endif  // URL_SCHEME_HOST_PORT_H_