Reduce buggy usage of the registry controlled domain service.

net/base/registry_controlled_domains/registry_controlled_domain.h

Index: net/base/registry_controlled_domains/registry_controlled_domain.h
diff --git a/net/base/registry_controlled_domains/registry_controlled_domain.h b/net/base/registry_controlled_domains/registry_controlled_domain.h
index 24ffb707a50ab5fd44e7b7f86427a9dfd0bff8b6..60e232befd124a7865c22a25456ebd53b441eafd 100644
--- a/net/base/registry_controlled_domains/registry_controlled_domain.h
+++ b/net/base/registry_controlled_domains/registry_controlled_domain.h
@@ -227,11 +227,48 @@ NET_EXPORT size_t GetRegistryLength(const GURL& gurl,
                                     UnknownRegistryFilter unknown_filter,
                                     PrivateRegistryFilter private_filter);
 
-// Like the GURL version, but takes a host (which is canonicalized internally)
-// instead of a full GURL.
-NET_EXPORT size_t GetRegistryLength(base::StringPiece host,
-                                    UnknownRegistryFilter unknown_filter,
-                                    PrivateRegistryFilter private_filter);
+// Returns true if the given host name has a registry-controlled domain. The
+// host name will be internally canonicalized. Invalid host names like
+// "*.google.com" can be passed and will return true as long as it has a valid
+// registry-controlled portion.

[Peter Kasting, 2016/10/22 05:04:19]

Nit: How about this last sentence: "Also returns true for an invalid host name
like "*.google.com", as long as it has a valid registry-controlled portion."

+NET_EXPORT bool HostHasRegistryControlledDomain(
+    base::StringPiece host,
+    UnknownRegistryFilter unknown_filter,
+    PrivateRegistryFilter private_filter);
+
+// Like GetRegistryLength, but takes a previously-canonicalized host instead of
+// a GURL. Prefer the GURL version or HasRegistryControlledSuffix to eliminate

[Peter Kasting, 2016/10/22 05:04:19]

Nit: HasRegistryControlledSuffix -> HostHasRegistryControlledDomain

[brettw, 2016/10/24 21:45:24]

Done.

+// the possibility of bugs with non-canonical hosts.
+//
+// If you have a non-canonical host name, use the "Permissive" version instead.
+NET_EXPORT size_t
+GetCanonicalHostRegistryLength(base::StringPiece canon_host,
+                               UnknownRegistryFilter unknown_filter,
+                               PrivateRegistryFilter private_filter);
+
+// Like GetRegistryLength for a potentially non-canonicalized hostname. This
+// function will perform a reverse-mapping of canonicalization transformations
+// so that the length of the registry controlled domain indicates the length
+// in the original string, even in the presence of things like escaped
+// characters or re-enconding from UTF-16.
+//
+// It will also handle hostnames that are otherwise invalid as long as they
+// contain a valid registry controlled domain at the end. The only thing it
+// won't handle is if you have a non-canonical dot (perhaps escaped) separating
+// an otherwise-valid registry-controlled domain and invalid host characters.
+// Invalid components are skipped only when they are dot-separated.

[Peter Kasting, 2016/10/22 05:04:19]

Nit: I'm confused.

Is this paragraph simply trying to say:

Like HostHasRegistryControlledDomain, this can accept hostnames that are
otherwise invalid, as long as they end with a dot followed by a valid
registry-controlled portion.

...Because if not, the bit about "non-canonical dot" has me completely lost.

[brettw, 2016/10/24 21:45:24]

It actually handles more cases than your sentence, I expanded on this.

+//
+// The string won't be trimmed, so things like trailing spaces will be
+// considered part of the host and therefore won't match any TLD. An empty
+// string will return std::string::npos like GetRegistryLength().

[Peter Kasting, 2016/10/22 05:04:19]

Nit: Is the last sentence necessary?  I mean, we already said this function was
like GetRegistryLength().

[brettw, 2016/10/24 21:45:24]

I expanded on this a bit.

+NET_EXPORT size_t
+PermissiveGetHostRegistryLength(base::StringPiece host,
+                                UnknownRegistryFilter unknown_filter,
+                                PrivateRegistryFilter private_filter);
+NET_EXPORT size_t
+PermissiveGetHostRegistryLength(base::StringPiece16 host,
+                                UnknownRegistryFilter unknown_filter,
+                                PrivateRegistryFilter private_filter);
 
 typedef const struct DomainRule* (*FindDomainPtr)(const char *, unsigned int);
 
@@ -241,6 +278,7 @@ NET_EXPORT_PRIVATE void SetFindDomainGraph();
 // Used for unit tests, so that a frozen list of domains is used.
 NET_EXPORT_PRIVATE void SetFindDomainGraph(const unsigned char* domains,
                                            size_t length);
+
 }  // namespace registry_controlled_domains
 }  // namespace net