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>
This commit is contained in:
James M Snell 2018-08-10 21:37:53 -07:00
parent bdef1b1eb4
commit 58cf40987f

View File

@ -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}