[whatwg/url] Clarify: "host" definition doesn't include port, but URL host attribute getter can (Issue #870)

ukusormus created an issue (whatwg/url#870)

### What is the issue with the URL Standard?

URL API "host" getter can return a port, but the definition for "host" itself doesn't include port. This may cause confusion and could be clarified, e.g. as a note under the host getter section.

Somewhat similar in nature to #869.

### "host" definition

[#concept-host](https://url.spec.whatwg.org/#concept-host):
```
A host is a domain, an IP address, an opaque host, or an empty host.
```

### "host" getter (URL class)

[#dom-url-host](https://url.spec.whatwg.org/#dom-url-host):
```
The host getter steps are:
...
3. If url’s port is null, return url’s host, serialized.
4. Return url’s host, serialized, followed by U+003A (:) and url’s port, serialized. 
```

As in practice:
```js
new URL("http://site.example").host  // "site.example"
new URL("http://site.example:80").host  // "site.example"
new URL("http://site.example:81").host  // "site.example:81" (!)
```

### Possible solution

As with #869, an explicit note, e.g., "it's just the historical reasons the URL API acts this way", could avoid confusion *why* the URL API host getter may include a port number, but the definition for "host" does not include port.

---

This behavior is somewhat hinted at (but not explained why) in a note under ["host setter steps"](https://url.spec.whatwg.org/#dom-url-host):
```
[...] This can be unexpected as host getter does return a URL-port string [...]
```
Which may be confusing as a separate issue (coming from a non-native English speaker, be aware)  - maybe "does return" should be "can return" or "could return", and since [#url-port-string](https://url.spec.whatwg.org/#url-port-string) is defined like:
```
A URL-port string must be one of the following:
- the empty string
- one or more ASCII digits representing a decimal number [...]
```
the note currently seems to indicate to me that the return value of host getter is (only) the port, not including "host" itself (e.g., `new URL("http://site.example:1234").host  // -> "1234" `, which is obviously not true).
Something along the lines of "[...] as the return value of host getter can include a URL-port string [...]" could be better understood in my opinion.




-- 
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/url/issues/870
You are receiving this because you are subscribed to this thread.

Message ID: <whatwg/url/issues/870@github.com>