diff options
author | James M Snell <jasnell@gmail.com> | 2018-08-11 07:37:53 +0300 |
---|---|---|
committer | James M Snell <jasnell@gmail.com> | 2018-08-12 02:56:10 +0300 |
commit | 58cf40987f6e08038c74c053da85b62956fe4469 (patch) | |
tree | 38286e1724978c4c722d0bf6c763f047c04650c8 /doc/api/url.md | |
parent | bdef1b1eb45e2953e1ff68f0cc9a68ec83573e57 (diff) |
doc: discuss special protocol handling
Fixes: https://github.com/nodejs/node/issues/13523
PR-URL: https://github.com/nodejs/node/pull/22261
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Jon Moss <me@jonathanmoss.me>
Diffstat (limited to 'doc/api/url.md')
-rw-r--r-- | doc/api/url.md | 40 |
1 files changed, 40 insertions, 0 deletions
diff --git a/doc/api/url.md b/doc/api/url.md index 64b7b444c54..7a101f6706f 100644 --- a/doc/api/url.md +++ b/doc/api/url.md @@ -389,6 +389,46 @@ console.log(myURL.href); Invalid URL protocol values assigned to the `protocol` property are ignored. +##### Special Schemes + +The [WHATWG URL Standard][] considers a handful of URL protocol schemes to be +_special_ in terms of how they are parsed and serialized. When a URL is +parsed using one of these special protocols, the `url.protocol` property +may be changed to another special protocol but cannot be changed to a +non-special protocol, and vice versa. + +For instance, changing from `http` to `https` works: + +```js +const u = new URL('http://example.org'); +u.protocol = 'https'; +console.log(u.href); +// https://example.org +``` + +However, changing from `http` to a hypothetical `fish` protocol does not +because the new protocol is not special. + +```js +const u = new URL('http://example.org'); +u.protocol = 'fish'; +console.log(u.href); +// http://example.org +``` + +Likewise, changing from a non-special protocol to a special protocol is also +not permitted: + +```js +const u = new URL('fish://example.org'); +u.protocol = 'http'; +console.log(u.href); +// fish://example.org +``` + +The protocol schemes considered to be special by the WHATWG URL Standard +include: `ftp`, `file`, `gopher`, `http`, `https`, `ws`, and `wss`. + #### url.search * {string} |