Skip to content

Commit

Permalink
doc: discuss special protocol handling
Browse files Browse the repository at this point in the history
Fixes: #13523

PR-URL: #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>
  • Loading branch information
jasnell authored and rvagg committed Aug 15, 2018
1 parent cea8d4f commit 1b41cd4
Showing 1 changed file with 40 additions and 0 deletions.
40 changes: 40 additions & 0 deletions doc/api/url.md
Original file line number Diff line number Diff line change
Expand Up @@ -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}
Expand Down

0 comments on commit 1b41cd4

Please sign in to comment.