-
Notifications
You must be signed in to change notification settings - Fork 141
/
url.bs
4263 lines (3294 loc) · 155 KB
/
url.bs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<pre class=metadata>
Group: WHATWG
H1: URL
Shortname: url
Text Macro: TWITTER urlstandard
Text Macro: LATESTRD 2024-08
Abstract: The URL Standard defines URLs, domains, IP addresses, the <code>application/x-www-form-urlencoded</code> format, and their API.
Translation: ja https://triple-underscore.github.io/URL-ja.html
Translation: zh-Hans https://htmlspecs.com/url/
Required IDs: application/x-www-form-urlencoded,urlencoded-parsing
</pre>
<pre class=anchors>
spec: ECMA-262; url: https://tc39.es/ecma262/#sec-encodeuricomponent-uricomponent; text: "encodeURIComponent() [sic]"; type: method
spec: UTS46; urlPrefix: https://www.unicode.org/reports/tr46/
type: abstract-op; text: ToASCII; url: #ToASCII
type: abstract-op; text: ToUnicode; url: #ToUnicode
</pre>
<style>
.yesno .yes { background: papayawhip; }
.yesno .yes, .yesno .no { text-align: center; }
</style>
<h2 id=goals class=no-num>Goals</h2>
<p>The URL standard takes the following approach towards making URLs fully interoperable:
<ul>
<li><p>Align RFC 3986 and RFC 3987 with contemporary implementations and
obsolete the RFCs in the process. (E.g., spaces, other "illegal" code points,
query encoding, equality, canonicalization, are all concepts not entirely
shared, or defined.) URL parsing needs to become as solid as HTML parsing.
[[RFC3986]]
[[RFC3987]]
<li><p>Standardize on the term URL. URI and IRI are just confusing. In
practice a single algorithm is used for both so keeping them distinct is
not helping anyone. URL also easily wins the
<a href="https://trends.google.com/trends/explore?q=url,uri">search result popularity contest</a>.
<li><p>Supplanting <a href="https://tools.ietf.org/html/rfc6454#section-4">Origin of a URI [sic]</a>.
[[RFC6454]]
<li><p>Define URL's existing JavaScript API in full detail and add
enhancements to make it easier to work with. Add a new <code><a interface>URL</a></code>
object as well for URL manipulation without usage of HTML elements. (Useful
for JavaScript worker environments.)
<li><p>Ensure the combination of parser, serializer, and API guarantee idempotence. For example, a
non-failure result of a parse-then-serialize operation will not change with any further
parse-then-serialize operations applied to it. Similarly, manipulating a non-failure result through
the API will not change from applying any number of serialize-then-parse operations to it.
</ul>
<p class=note>As the editors learn more about the subject matter the goals
might increase in scope somewhat.
<h2 id=infrastructure>Infrastructure</h2>
<p>This specification depends on <cite>Infra</cite>. [[!INFRA]]
<p>Some terms used in this specification are defined in the following standards and specifications:
<ul class=brief>
<li><cite>Encoding</cite> [[!ENCODING]]
<li><cite>File API</cite> [[!FILEAPI]]
<li><cite>HTML</cite> [[!HTML]]
<li><cite>Unicode IDNA Compatibility Processing</cite> [[!UTS46]]
<li><cite>Web IDL</cite> [[!WEBIDL]]
</ul>
<hr>
<p>To <dfn>serialize an integer</dfn>, represent it as the shortest possible decimal
number.
<h3 id=writing>Writing</h3>
<p>A <dfn oldids=syntax-violation>validation error</dfn> indicates a mismatch between input and
valid input. User agents, especially conformance checkers, are encouraged to report them somewhere.
<div class=note>
<p>A <a>validation error</a> does not mean that the parser terminates. Termination of a parser is
always stated explicitly, e.g., through a return statement.
<p>It is useful to signal <a>validation errors</a> as error-handling can be non-intuitive, legacy
user agents might not implement correct error-handling, and the intent of what is written might be
unclear to other developers.
</div>
<table class=yesno>
<thead>
<tr>
<th>Error type
<th>Error description
<th>Failure
<!-- The rows inside the <tbody>s are generally sorted by first occurrence. However, where logical
groupings exist those override that sorting:
- domain- and host- stay together
- IPv6- stays together
- IPv4-in-IPv6- stays together -->
<tbody>
<tr>
<th colspan=3 scope=rowgroup><a href=#idna>IDNA</a>
<tr>
<td><dfn id=validation-error-domain-to-ascii>domain-to-ASCII</dfn>
<td>
<p><a abstract-op lt=ToASCII>Unicode ToASCII</a> records an error or returns the empty string.
[[UTS46]]
<p class=note>If details about <a abstract-op lt=ToASCII>Unicode ToASCII</a> errors are
recorded, user agents are encouraged to pass those along.
<td class=yes>Yes
<tr>
<td><dfn>domain-invalid-code-point</dfn>
<td>
<p>The input's <a for=/>host</a> contains a <a>forbidden domain code point</a>.
<div class=example id=example-domain-invalid-code-point>
<p>Hosts are <a for=string>percent-decoded</a> before being processed when the URL
<a>is special</a>, which would result in the following host portion becoming
"<code>exa#mple.org</code>" and thus triggering this error.
<p>"<code>https://exa%23mple.org</code>"
</div>
<td class=yes>Yes
<tr>
<td><dfn>domain-to-Unicode</dfn>
<td>
<p><a abstract-op lt=ToUnicode>Unicode ToUnicode</a> records an error. [[UTS46]]
<p class=note>The same considerations as with <a>domain-to-ASCII</a> apply.
<td class=no>·
<tbody>
<tr>
<th colspan=3 scope=rowgroup><a href=#host-parsing>Host parsing</a>
<!-- opaque-host parser -->
<tr>
<td><dfn>host-invalid-code-point</dfn>
<td>
<p>An <a>opaque host</a> (in a URL that <a>is not special</a>) contains a
<a>forbidden host code point</a>.
<p class=example id=example-host-invalid-code-point>"<code>foo://exa[mple.org</code>"
<td class=yes>Yes
<!-- IPv4 parser -->
<tr>
<td><dfn>IPv4-empty-part</dfn>
<td>
<p>An <a for=/>IPv4 address</a> ends with a U+002E (.).
<p class=example id=example-ipv4-empty-part>"<code>https://127.0.0.1./</code>"
<td class=no>·
<tr>
<td><dfn>IPv4-too-many-parts</dfn>
<td>
<p>An <a for=/>IPv4 address</a> does not consist of exactly 4 parts.
<p class=example id=example-ipv4-too-many-parts>"<code>https://1.2.3.4.5/</code>"
<td class=yes>Yes
<tr>
<td><dfn>IPv4-non-numeric-part</dfn>
<td>
<p>An <a for=/>IPv4 address</a> part is not numeric.
<p class=example id=example-ipv4-non-numeric-part>"<code>https://test.42</code>"
<td class=yes>Yes
<tr>
<td><dfn>IPv4-non-decimal-part</dfn>
<td>
<p>The <a for=/>IPv4 address</a> contains numbers expressed using hexadecimal or octal digits.
<p class=example id=example-ipv4-non-decimal-part>"<code>https://127.0.0x0.1</code>"
<td class=no>·
<tr>
<td><dfn>IPv4-out-of-range-part</dfn>
<td>
<p>An <a for=/>IPv4 address</a> part exceeds 255.
<p class=example id=example-ipv4-out-of-range-part>"<code>https://255.255.4000.1</code>"
<td class=yes>Yes<br>(only if applicable to the last part)
<!-- host parser, but grouped with IPv6- -->
<tr>
<td><dfn>IPv6-unclosed</dfn>
<td>
<p>An <a for=/>IPv6 address</a> is missing the closing U+005D (]).
<p class=example id=example-ipv6-unclosed>"<code>https://[::1</code>"
<td class=yes>Yes
<!-- IPv6 parser -->
<tr>
<td><dfn>IPv6-invalid-compression</dfn>
<td>
<p>An <a for=/>IPv6 address</a> begins with improper compression.
<p class=example id=example-ipv6-invalid-compression>"<code>https://[:1]</code>"
<td class=yes>Yes
<tr>
<td><dfn>IPv6-too-many-pieces</dfn>
<td>
<p>An <a for=/>IPv6 address</a> contains more than 8 pieces.
<p class=example id=example-ipv6-too-many-pieces>"<code>https://[1:2:3:4:5:6:7:8:9]</code>"
<td class=yes>Yes
<tr>
<td><dfn>IPv6-multiple-compression</dfn>
<td>
<p>An <a for=/>IPv6 address</a> is compressed in more than one spot.
<p class=example id=example-ipv6-multiple-compression>"<code>https://[1::1::1]</code>"
<td class=yes>Yes
<tr>
<td><dfn>IPv6-invalid-code-point</dfn>
<td>
<p>An <a for=/>IPv6 address</a> contains a code point that is neither an <a>ASCII hex digit</a>
nor a U+003A (:). Or it unexpectedly ends.
<div class=example id=example-ipv6-invalid-code-point>
<p>"<code>https://[1:2:3!:4]</code>"
<p>"<code>https://[1:2:3:]</code>"
</div>
<td class=yes>Yes
<tr>
<td><dfn>IPv6-too-few-pieces</dfn>
<td>
<p>An uncompressed <a for=/>IPv6 address</a> contains fewer than 8 pieces.
<p class=example id=example-ipv6-too-few-pieces>"<code>https://[1:2:3]</code>"
<td class=yes>Yes
<tr>
<td><dfn>IPv4-in-IPv6-too-many-pieces</dfn>
<td>
<p>An <a for=/>IPv6 address</a> with <a for=/>IPv4 address</a> syntax: the IPv6 address has more
than 6 pieces.
<p class=example id=example-ipv4-in-ipv6-too-many-pieces>"<code>https://[1:1:1:1:1:1:1:127.0.0.1]</code>"
<td class=yes>Yes
<tr>
<td><dfn>IPv4-in-IPv6-invalid-code-point</dfn>
<td>
<p>An <a for=/>IPv6 address</a> with <a for=/>IPv4 address</a> syntax:
<ul>
<li>An IPv4 part is empty or contains a non-<a>ASCII digit</a>.
<li>An IPv4 part contains a leading 0.
<li>There are too many IPv4 parts.
</ul>
<div class=example id=example-ipv4-in-ipv6-invalid-code-point>
<p>"<code>https://[ffff::.0.0.1]</code>"
<p>"<code>https://[ffff::127.0.xyz.1]</code>"
<p>"<code>https://[ffff::127.0xyz]</code>"
<p>"<code>https://[ffff::127.00.0.1]</code>"
<p>"<code>https://[ffff::127.0.0.1.2]</code>"
</div>
<td class=yes>Yes
<tr>
<td><dfn>IPv4-in-IPv6-out-of-range-part</dfn>
<td>
<p>An <a for=/>IPv6 address</a> with <a for=/>IPv4 address</a> syntax: an IPv4 part exceeds 255.
<p class=example id=example-ipv4-in-ipv6-out-of-range-part>"<code>https://[ffff::127.0.0.4000]</code>"
<td class=yes>Yes
<tr>
<td><dfn>IPv4-in-IPv6-too-few-parts</dfn>
<td>
<p>An <a for=/>IPv6 address</a> with <a for=/>IPv4 address</a> syntax: an IPv4 address contains
too few parts.
<p class=example id=example-ipv4-in-ipv6-too-few-parts>"<code>https://[ffff::127.0.0]</code>"
<td class=yes>Yes
<tbody>
<tr>
<th colspan=3 scope=rowgroup><a href=#url-parsing>URL parsing</a>
<!-- invalid-URL-unit is also present in the opaque-host parser, but this is a more logical place.
-->
<tr>
<td><dfn>invalid-URL-unit</dfn>
<td>
<p>A code point is found that is not a <a>URL unit</a>.
<div class=example id=example-invalid-url-unit>
<p>"<code>https://example.org/></code>"
<p>"<code> https://example.org </code>"
<p>"<code>ht<br>tps://example.org</code>"
<p>"<code>https://example.org/%s</code>"
</div>
<td class=no>·
<tr>
<td><dfn>special-scheme-missing-following-solidus</dfn>
<td>
<p>The input's scheme is not followed by "<code>//</code>".
<div class=example id=example-special-scheme-missing-following-solidus>
<p>"<code>file:c:/my-secret-folder</code>"
<p>"<code>https:example.org</code>"
<pre><code class="lang-javascript">
const url = new URL("https:foo.html", "https://example.org/");</code></pre>
</div>
<td class=no>·
<tr>
<td><dfn>missing-scheme-non-relative-URL</dfn>
<td>
<p>The input is missing a <a for=url>scheme</a>, because it does not begin with an
<a>ASCII alpha</a>, and either no <a>base URL</a> was provided or the <a>base URL</a> cannot be
used as a <a>base URL</a> because it has an <a for=url>opaque path</a>.
<div class=example id=example-missing-scheme-non-relative-url>
<p>Input's <a for=url>scheme</a> is missing and no <a>base URL</a> is given:
<pre><code class=lang-javascript>
const url = new URL("💩");</code></pre>
<p>Input's <a for=url>scheme</a> is missing, but the <a>base URL</a> has an
<a for=url>opaque path</a>.
<pre><code class=lang-javascript>
</div>
<td class=yes>Yes
<tr>
<td><dfn>invalid-reverse-solidus</dfn>
<td>
<p>The URL has a <a>special scheme</a> and it uses U+005C (\) instead of U+002F (/).
<p class=example id=example-invalid-reverse-solidus>"<code>https://example.org\path\to\file</code>"
<td class=no>·
<tr>
<td><dfn>invalid-credentials</dfn>
<td>
<p>The input <a>includes credentials</a>.
<div class=example id=example-invalid-credentials>
</div>
<td class=no>·
<tr>
<td><dfn>host-missing</dfn>
<td>
<p>The input has a <a>special scheme</a>, but does not contain a <a for=/>host</a>.
<div class=example id=example-host-missing>
<p>"<code>https://#fragment</code>"
<p>"<code>https://:443</code>"
<p>"<code>https://user:pass@</code>"
</div>
<td class=yes>Yes
<tr>
<td><dfn>port-out-of-range</dfn>
<td>
<p>The input's port is too big.
<p class=example id=example-port-out-of-range>"<code>https://example.org:70000</code>"
<td class=yes>Yes
<tr>
<td><dfn>port-invalid</dfn>
<td>
<p>The input's port is invalid.
<p class=example id=example-port-invalid>"<code>https://example.org:7z</code>"
<td class=yes>Yes
<tr>
<td><dfn>file-invalid-Windows-drive-letter</dfn>
<td>
<p>The input is a <a>relative-URL string</a> that <a>starts with a Windows drive letter</a> and
the <a>base URL</a>'s <a for=url>scheme</a> is "<code>file</code>".
<pre class=example id=example-file-invalid-windows-drive-letter><code class=lang-javascript>
const url = new URL("/c:/path/to/file", "file:///c:/");</code></pre>
<td class=no>·
<tr>
<td><dfn>file-invalid-Windows-drive-letter-host</dfn>
<td>
<p>A <code>file:</code> URL's host is a Windows drive letter.
<p class=example id=example-file-invalid-windows-drive-letter-host>"<code>file://c:</code>"
<td class=no>·
</table>
<h3 id=parsers>Parsers</h3>
<p>The <dfn>EOF code point</dfn> is a conceptual code point that signifies the end of a string or
code point stream.
<p>A <dfn>pointer</dfn> for a <a for=/>string</a> <var>input</var> is an integer that points to a
<a for=/>code point</a> within <var>input</var>. Initially it points to the start of
<var>input</var>. If it is −1 it points nowhere. If it is greater than or equal to
<var>input</var>'s <a for=string>code point length</a>, it points to the <a>EOF code point</a>.
<p>When a <a>pointer</a> is used, <dfn>c</dfn> references the <a for=/>code point</a> the
<a>pointer</a> points to as long as it does not point nowhere. When the <a>pointer</a> points to
nowhere <a>c</a> cannot be used.
<p>When a <a>pointer</a> is used, <dfn>remaining</dfn> references the
<a lt="code point substring to the end of the string">code point substring</a> from the
<a>pointer</a> + 1 to the end of the string, as long as <a>c</a> is not the <a>EOF code point</a>.
When <a>c</a> is the <a>EOF code point</a> <a>remaining</a> cannot be used.
<p class=example id=example-12672b6a>If "<code>mailto:username@example</code>" is a <a>string</a>
being processed and a <a>pointer</a> points to @, <a>c</a> is U+0040 (@) and <a>remaining</a> is
"<code>example</code>".
<p class=example id=example-empty-string>If the empty string is being processed and a <a>pointer</a>
points to the start and is then decreased by 1, using <a>c</a> or <a>remaining</a> would be an
error.
<h3 id=percent-encoded-bytes>Percent-encoded bytes</h3>
<p>A <dfn>percent-encoded byte</dfn> is U+0025 (%), followed by two <a>ASCII hex digits</a>.
<p class=note>It is generally a good idea for sequences of <a>percent-encoded bytes</a> to be such
that, when <a for=string>percent-decoded</a> and then passed to
<a>UTF-8 decode without BOM or fail</a>, they do not end up as failure. How important this is
depends on where the <a>percent-encoded bytes</a> are used. E.g., for the <a>host parser</a> not
following this advice is fatal, whereas for <a href="#url-rendering-i18n">URL rendering</a> the
<a>percent-encoded bytes</a> would not be rendered <a for=string>percent-decoded</a>.
<div algorithm>
<p>To <dfn for=byte id=percent-encode>percent-encode</dfn> a <a for=/>byte</a> <var>byte</var>,
return a <a for=/>string</a> consisting of U+0025 (%), followed by two <a>ASCII upper hex digits</a>
representing <var>byte</var>.
</div>
<div algorithm>
<p>To <dfn export for="byte sequence" id=percent-decode>percent-decode</dfn> a
<a for=/>byte sequence</a> <var>input</var>, run these steps:
<p class=warning>Using anything but <a>UTF-8 decode without BOM</a> when <var>input</var> contains
bytes that are not <a>ASCII bytes</a> might be insecure and is not recommended.
<ol>
<li><p>Let <var>output</var> be an empty <a>byte sequence</a>.
<li>
<p>For each byte <var>byte</var> in <var>input</var>:
<ol>
<li><p>If <var>byte</var> is not 0x25 (%), then append <var>byte</var> to <var>output</var>.
<li><p>Otherwise, if <var>byte</var> is 0x25 (%) and the next two bytes after
<var>byte</var> in <var>input</var> are not in the ranges 0x30 (0) to 0x39 (9),
0x41 (A) to 0x46 (F), and 0x61 (a) to 0x66 (f), all inclusive, append <var>byte</var> to
<var>output</var>.
<li>
<p>Otherwise:
<ol>
<li><p>Let <var>bytePoint</var> be the two bytes after <var>byte</var> in <var>input</var>,
<a lt="isomorphic decode">decoded</a>, and then interpreted as hexadecimal number.
<!-- We should have a better definition for this. -->
<li><p>Append a byte whose value is <var>bytePoint</var> to
<var>output</var>.
<li><p>Skip the next two bytes in <var>input</var>.
</ol>
</ol>
<li><p>Return <var>output</var>.
</ol>
</div>
<div algorithm>
<p>To <dfn export for=string>percent-decode</dfn> a <a for=/>scalar value string</a>
<var>input</var>:
<ol>
<li><p>Let <var>bytes</var> be the <a>UTF-8 encoding</a> of <var>input</var>.
<li><p>Return the <a for="byte sequence">percent-decoding</a> of <var>bytes</var>.
</ol>
<p class=note>In general, percent-encoding results in a string with more U+0025 (%) code points than
the input, and percent-decoding results in a byte sequence with less 0x25 (%) bytes than the input.
</div>
<hr>
<p>The <dfn oldids=simple-encode-set>C0 control percent-encode set</dfn> are the <a>C0 controls</a>
and all <a>code points</a> greater than U+007E (~).
<p>The <dfn>fragment percent-encode set</dfn> is the <a>C0 control percent-encode set</a> and
U+0020 SPACE, U+0022 ("), U+003C (<), U+003E (>), and U+0060 (`).
<p>The <dfn>query percent-encode set</dfn> is the <a>C0 control percent-encode set</a> and
U+0020 SPACE, U+0022 ("), U+0023 (#), U+003C (<), and U+003E (>).
<p class=note>The <a>query percent-encode set</a> cannot be defined in terms of the
<a>fragment percent-encode set</a> due to the omission of U+0060 (`).
<p>The <dfn>special-query percent-encode set</dfn> is the <a>query percent-encode set</a> and
U+0027 (').
<p>The <dfn oldids=default-encode-set>path percent-encode set</dfn> is the
<a>query percent-encode set</a> and U+003F (?), U+0060 (`), U+007B ({), and U+007D (}).
<p>The <dfn oldids=userinfo-encode-set>userinfo percent-encode set</dfn> is the
<a>path percent-encode set</a> and U+002F (/), U+003A (:), U+003B (;), U+003D (=), U+0040 (@),
U+005B ([) to U+005E (^), inclusive, and U+007C (|).
<p>The <dfn export>component percent-encode set</dfn> is the <a>userinfo percent-encode set</a> and
U+0024 ($) to U+0026 (&), inclusive, U+002B (+), and U+002C (,).
<p class=note>This is used by <cite>HTML</cite> for
{{NavigatorContentUtils/registerProtocolHandler()}}, and could also be used by other standards to
percent-encode data that can then be embedded in a <a for=/>URL</a>'s <a for=url>path</a>,
<a for=url>query</a>, or <a for=url>fragment</a>; or in an <a for=/>opaque host</a>. Using it with
<a for=string>UTF-8 percent-encode</a> gives identical results to JavaScript's
<a method><code>encodeURIComponent()</code> [sic]</a>. [[HTML]] [[ECMA-262]]
<p>The <dfn><code>application/x-www-form-urlencoded</code> percent-encode set</dfn> is the
<a>component percent-encode set</a> and U+0021 (!), U+0027 (') to U+0029 RIGHT PARENTHESIS,
inclusive, and U+007E (~).
<p class=note>The <a><code>application/x-www-form-urlencoded</code> percent-encode set</a> contains
all code points, except the <a>ASCII alphanumeric</a>, U+002A (*), U+002D (-), U+002E (.), and
U+005F (_).
<div algorithm>
<p>To <dfn for=string>percent-encode after encoding</dfn>, given an <a for=/>encoding</a>
<var>encoding</var>, <a for=/>scalar value string</a> <var>input</var>, a
<var>percentEncodeSet</var>, and an optional boolean <var>spaceAsPlus</var> (default false):
<ol>
<li><p>Let <var>encoder</var> be the result of <a>getting an encoder</a> from <var>encoding</var>.
<li><p>Let <var>inputQueue</var> be <var>input</var> converted to an <a for=/>I/O queue</a>.
<li><p>Let <var>output</var> be the empty string.
<li>
<p>Let <var>potentialError</var> be 0.
<p class=note>This needs to be a non-null value to initiate the subsequent while loop.
<li>
<p>While <var>potentialError</var> is non-null:
<ol>
<li><p>Let <var>encodeOutput</var> be an empty <a for=/>I/O queue</a>.
<li><p>Set <var>potentialError</var> to the result of running <a>encode or fail</a> with
<var>inputQueue</var>, <var>encoder</var>, and <var>encodeOutput</var>.
<li>
<p>For each <var>byte</var> of <var>encodeOutput</var> converted to a byte sequence:
<ol>
<li><p>If <var>spaceAsPlus</var> is true and <var>byte</var> is 0x20 (SP), then append
U+002B (+) to <var>output</var> and <a for=iteration>continue</a>.
<li><p>Let <var>isomorph</var> be a <a for=/>code point</a> whose <a for="code point">value</a>
is <var>byte</var>'s <a for=byte>value</a>.
<li><p>Assert: <var>percentEncodeSet</var> includes all non-<a>ASCII code points</a>.
<li><p>If <var>isomorph</var> is not in <var>percentEncodeSet</var>, then append
<var>isomorph</var> to <var>output</var>.
<li><p>Otherwise, <a for=byte>percent-encode</a> <var>byte</var> and append the result to
<var>output</var>.
</ol>
<li>
<p>If <var>potentialError</var> is non-null, then append "<code>%26%23</code>", followed by the
shortest sequence of <a for=/>ASCII digits</a> representing <var>potentialError</var> in base
ten, followed by "<code>%3B</code>", to <var>output</var>.
<p class=note>This can happen when <var>encoding</var> is not <a>UTF-8</a>.
</ol>
<li><p>Return <var>output</var>.
</ol>
<p class=note>Of the possible values for the <var>percentEncodeSet</var> argument only two end up
encoding U+0025 (%) and thus give “roundtripable data”: <a>component percent-encode set</a> and
<a><code>application/x-www-form-urlencoded</code> percent-encode set</a>. The other values for the
<var>percentEncodeSet</var> argument — which happen to be used by the <a>URL parser</a> — leave
U+0025 (%) untouched and as such it needs to be
<a for="code point" lt="UTF-8 percent-encode">percent-encoded</a> first in order to be properly
represented.
</div>
<div algorithm>
<p>To <dfn for="code point" id=utf-8-percent-encode>UTF-8 percent-encode</dfn> a
<a for=/>scalar value</a> <var>scalarValue</var> using a <var>percentEncodeSet</var>, return the
result of running <a for=string>percent-encode after encoding</a> with <a for=/>UTF-8</a>,
<var>scalarValue</var> as a <a for=/>string</a>, and <var>percentEncodeSet</var>.
</div>
<div algorithm>
<p>To <dfn export for=string>UTF-8 percent-encode</dfn> a <a for=/>scalar value string</a>
<var>input</var> using a <var>percentEncodeSet</var>, return the result of running
<a for=string>percent-encode after encoding</a> with <a for=/>UTF-8</a>, <var>input</var>, and
<var>percentEncodeSet</var>.
</div>
<hr>
<div class=example id=example-percent-encode-operations>
<p>Here is a summary, by way of example, of the operations defined above:
<table>
<tr>
<th>Operation
<th>Input
<th>Output
<tr>
<td rowspan=2><a for=byte>Percent-encode</a> <var>input</var>
<td>0x23
<td>"<code>%23</code>"
<tr>
<td>0x7F
<td>"<code>%7F</code>"
<tr>
<td><a for="byte sequence">Percent-decode</a> <var>input</var>
<td>`<code>%25%s%1G</code>`
<td>`<code>%%s%1G</code>`
<tr>
<td><a for=string>Percent-decode</a> <var>input</var>
<td>"<code>‽%25%2E</code>"
<td>0xE2 0x80 0xBD 0x25 0x2E
<tr>
<td rowspan=3><a for=string>Percent-encode after encoding</a> with <a>Shift_JIS</a>,
<var>input</var>, and the <a>userinfo percent-encode set</a>
<td>"<code> </code>"
<td>"<code>%20</code>"
<tr>
<td>"<code>≡</code>"
<td>"<code>%81%DF</code>"
<tr>
<td>"<code>‽</code>"
<td>"<code>%26%238253%3B</code>"
<tr>
<td><a for=string>Percent-encode after encoding</a> with <a>ISO-2022-JP</a>, <var>input</var>,
and the <a>userinfo percent-encode set</a>
<td>"<code>¥</code>"
<td>"<code>%1B(J\%1B(B</code>"
<tr>
<td><a for=string>Percent-encode after encoding</a> with <a>Shift_JIS</a>, <var>input</var>, the
<a>userinfo percent-encode set</a>, and true
<td>"<code>1+1 ≡ 2%20‽</code>"
<td>"<code>1+1+%81%DF+2%20%26%238253%3B</code>"
<tr>
<td rowspan=2><a for="code point">UTF-8 percent-encode</a> <var>input</var> using the
<a>userinfo percent-encode set</a>
<td>U+2261 (≡)
<td>"<code>%E2%89%A1</code>"
<tr>
<td>U+203D (‽)
<td>"<code>%E2%80%BD</code>"
<tr>
<td><a for=string>UTF-8 percent-encode</a> <var>input</var> using the
<a>userinfo percent-encode set</a>
<td>"<code>Say what‽</code>"
<td>"<code>Say%20what%E2%80%BD</code>"
</table>
</div>
<h2 id=security-considerations>Security considerations</h2>
<p>The security of a <a for=/>URL</a> is a function of its environment. Care is to be
taken when rendering, interpreting, and passing <a for=/>URLs</a> around.
<p>When rendering and allocating new <a for=/>URLs</a> "spoofing" needs to be considered. An attack
whereby one <a for=/>host</a> or <a for=/>URL</a> can be confused for another. For instance,
consider how 1/l/I, m/rn/rri, 0/O, and а/a can all appear eerily similar. Or worse, consider how
U+202A LEFT-TO-RIGHT EMBEDDING and similar <a>code points</a> are invisible. [[UTR36]]
<p>When passing a <a for=/>URL</a> from party <var>A</var> to <var>B</var>, both need to
carefully consider what is happening. <var>A</var> might end up leaking data it does not
want to leak. <var>B</var> might receive input it did not expect and take an action that
harms the user. In particular, <var>B</var> should never trust <var>A</var>, as at some
point <a for=/>URLs</a> from <var>A</var> can come from untrusted sources.
<h2 id="hosts-(domains-and-ip-addresses)">Hosts (domains and IP addresses)</h2>
<p>At a high level, a <a for=/>host</a>, <a>valid host string</a>, <a>host parser</a>, and
<a>host serializer</a> relate as follows:
<ul>
<li><p>The <a>host parser</a> takes an arbitrary <a>scalar value string</a> and returns either
failure or a <a for=/>host</a>.
<li><p>A <a for=/>host</a> can be seen as the in-memory representation.
<li><p>A <a>valid host string</a> defines what input would not trigger a <a>validation error</a>
or failure when given to the <a>host parser</a>. I.e., input that would be considered conforming or
valid.
<li><p>The <a>host serializer</a> takes a <a for=/>host</a> and returns an <a>ASCII string</a>. (If
that string is then <a lt="host parser">parsed</a>, the result will <a for=host>equal</a> the
<a for=/>host</a> that was <a lt="host serializer">serialized</a>.)
</ul>
<div class=example id=example-host-parsing>
<p>A <a lt="host parser">parse</a>-<a lt="host serializer">serialize</a> roundtrip gives the
following results, depending on the <var ignore>isOpaque</var> argument to the <a>host parser</a>:
<table>
<tr>
<th>Input
<th>Output (<var ignore>isOpaque</var> = false)
<th>Output (<var ignore>isOpaque</var> = true)
<tr>
<td><code>EXAMPLE.COM</code>
<td rowspan=2><code>example.com</code> (<a for=/>domain</a>)
<td><code>EXAMPLE.COM</code> (<a>opaque host</a>)
<tr>
<td><code>example%2Ecom</code>
<td><code>example%2Ecom</code> (<a>opaque host</a>)
<tr>
<td><code>faß.example</code>
<td><code>xn--fa-hia.example</code> (<a for=/>domain</a>)
<td><code>fa%C3%9F.example</code> (<a>opaque host</a>)
<tr>
<td><code>0</code>
<td rowspan=3><code>0.0.0.0</code> (<a for=/ lt="IPv4 address">IPv4</a>)
<td><code>0</code> (<a>opaque host</a>)
<tr>
<td><code>%30</code>
<td><code>%30</code> (<a>opaque host</a>)
<tr>
<td><code>0x</code>
<td><code>0x</code> (<a>opaque host</a>)
<tr>
<td><code>0xffffffff</code>
<td><code>255.255.255.255</code> (<a for=/ lt="IPv4 address">IPv4</a>)
<td><code>0xffffffff</code> (<a>opaque host</a>)
<tr>
<td><code>[0:0::1]</code>
<td colspan=2><code>[::1]</code> (<a for=/ lt="IPv6 address">IPv6</a>)
<tr>
<td><code>[0:0::1%5D</code>
<td colspan=2 rowspan=2>Failure
<tr>
<td><code>[0:0::%31]</code>
<tr>
<td><code>09</code>
<td rowspan=3>Failure
<td><code>09</code> (<a>opaque host</a>)
<tr>
<td><code>example.255</code>
<td><code>example.255</code> (<a>opaque host</a>)
<tr>
<td><code>example^example</code>
<td>Failure
</table>
</div>
<h3 id=host-representation>Host representation</h3>
<p>A <dfn export id=concept-host>host</dfn> is a <a>domain</a>, an <a>IP address</a>, an
<a>opaque host</a>, or an <a>empty host</a>. Typically a <a for=/>host</a> serves as a network
address, but it is sometimes used as opaque identifier in <a for=/>URLs</a> where a network address
is not necessary.
<p class=example id=example-opaque-host-url>A typical <a for=/>URL</a> whose <a for=url>host</a> is
an <a>opaque host</a> is <code>git://github.com/whatwg/url.git</code>.
<p class=note>The RFCs referenced in the paragraphs below are for informative purposes only. They
have no influence on <a for=/>host</a> writing, parsing, and serialization. Unless stated otherwise
in the sections that follow.
<p>A <dfn export id=concept-domain>domain</dfn> is a non-empty <a>ASCII string</a> that identifies a
realm within a network.
[[RFC1034]]
<p>The <dfn export lt="domain label">domain labels</dfn> of a <a>domain</a> <var>domain</var> are
the result of <a>strictly splitting</a> <var>domain</var> on U+002E (.).
<p class=note>The <code>example.com</code> and <code>example.com.</code> <a for=/>domains</a> are
not equivalent and typically treated as distinct.
<p>An <dfn export>IP address</dfn> is an <a>IPv4 address</a> or an <a>IPv6 address</a>.
<p>An <dfn export id=concept-ipv4>IPv4 address</dfn> is a <a for=/>32-bit unsigned integer</a> that
identifies a network address.
[[RFC791]]
<p>An <dfn export id=concept-ipv6>IPv6 address</dfn> is a <a for=/>128-bit unsigned integer</a> that
identifies a network address. This integer is composed of a <a for=/>list</a> of 8
<a for=/>16-bit unsigned integers</a>, also known as an <a for=/>IPv6 address</a>'s
<dfn export for="IPv6 address" id=concept-ipv6-piece>pieces</dfn>.
[[RFC4291]]
<p class="note">Support for <code><zone_id></code> is
<a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=27234#c2">intentionally omitted</a>.
<p>An <dfn export>opaque host</dfn> is a non-empty <a>ASCII string</a> that can be used for further
processing.
<p>An <dfn export>empty host</dfn> is the empty string.
<h3 id=host-miscellaneous>Host miscellaneous</h3>
<p>A <dfn export>forbidden host code point</dfn> is U+0000 NULL, U+0009 TAB, U+000A LF, U+000D CR,
U+0020 SPACE, U+0023 (#), U+002F (/), U+003A (:), U+003C (<), U+003E (>), U+003F (?), U+0040 (@),
U+005B ([), U+005C (\), U+005D (]), U+005E (^), or U+007C (|).
<p>A <dfn export>forbidden domain code point</dfn> is a <a>forbidden host code point</a>,
a <a>C0 control</a>, U+0025 (%), or U+007F DELETE.
<div algorithm>
<p>To obtain the <dfn export for=host>public suffix</dfn> of a <a for=/>host</a> <var>host</var>,
run these steps. They return null or a <a for=/>domain</a> representing a portion of <var>host</var>
that is included on the <cite>Public Suffix List</cite>. [[!PSL]]
<ol>
<li><p>If <var>host</var> is not a <a>domain</a>, then return null.
<li><p>Let <var>trailingDot</var> be "<code>.</code>" if <var>host</var>
<a for=string>ends with</a> "<code>.</code>"; otherwise the empty string.
<li><p>Let <var>publicSuffix</var> be the public suffix determined by running the
<a href="https://github.com/publicsuffix/list/wiki/Format#formal-algorithm">Public Suffix List algorithm</a>
with <var>host</var> as domain. [[!PSL]]
<li><p>Assert: <var>publicSuffix</var> is an <a>ASCII string</a> that does not
<a for=string>end with</a> "<code>.</code>".
<li><p>Return <var>publicSuffix</var> and <var>trailingDot</var> concatenated.
</ol>
</div>
<div algorithm>
<p>To obtain the <dfn export for=host>registrable domain</dfn> of a <a for=/>host</a>
<var>host</var>, run these steps. They return null or a <a for=/>domain</a> formed by
<var>host</var>'s <a for=host>public suffix</a> and the <a for=/>domain label</a> preceding it, if
any.
<ol>
<li><p>If <var>host</var>'s <a for=host>public suffix</a> is null or <var>host</var>'s
<a for=host>public suffix</a> <a for=host>equals</a> <var>host</var>, then return null.
<li><p>Let <var>trailingDot</var> be "<code>.</code>" if <var>host</var>
<a for=string>ends with</a> "<code>.</code>"; otherwise the empty string.
<li><p>Let <var>registrableDomain</var> be the registrable domain determined by running the
<a href="https://github.com/publicsuffix/list/wiki/Format#formal-algorithm">Public Suffix List algorithm</a>
with <var>host</var> as domain. [[!PSL]]
<li><p>Assert: <var>registrableDomain</var> is an <a>ASCII string</a> that does not
<a for=string>end with</a> "<code>.</code>".
<li><p>Return <var>registrableDomain</var> and <var>trailingDot</var> concatenated.
</ol>
</div>
<div class=example id=example-host-psl>
<table>
<tr>
<th>Host input
<th>Public suffix
<th>Registrable domain
<tr>
<td><code>com</code>
<td><code>com</code>
<td>null
<tr>
<td><code>example.com</code>
<td><code>com</code>
<td><code>example.com</code>
<tr>
<td><code>www.example.com</code>
<td><code>com</code>
<td><code>example.com</code>
<tr>
<td><code>sub.www.example.com</code>
<td><code>com</code>
<td><code>example.com</code>
<tr>
<td><code>EXAMPLE.COM</code>
<td><code>com</code>
<td><code>example.com</code>
<tr>
<td><code>example.com.</code>
<td><code>com.</code>
<td><code>example.com.</code>
<tr>
<td><code>github.io</code>
<td><code>github.io</code>
<td>null
<tr>
<td><code>whatwg.github.io</code>
<td><code>github.io</code>
<td><code>whatwg.github.io</code>
<tr>
<td><code>إختبار</code>
<td><code>xn--kgbechtv</code>
<td>null
<tr>
<td><code>example.إختبار</code>
<td><code>xn--kgbechtv</code>
<td><code>example.xn--kgbechtv</code>
<tr>
<td><code>sub.example.إختبار</code>
<td><code>xn--kgbechtv</code>
<td><code>example.xn--kgbechtv</code>
<tr>
<td><code>[2001:0db8:85a3:0000:0000:8a2e:0370:7334]</code>
<td>null
<td>null
</table>
</div>
<p class=warning id=warning-avoid-psl>Specifications should prefer the <a for=/>origin</a> concept
for security decisions. The notion of "<a for=host>public suffix</a>" and
"<a for=host>registrable domain</a>" cannot be relied-upon to provide a hard security boundary, as
the public suffix list will diverge from client to client. Specifications which ignore this advice
are encouraged to carefully consider whether URLs' schemes ought to be incorporated into any
decisions made, i.e. whether to use the <a for=/>same site</a> or <a>schemelessly same site</a>
concepts.
<h3 id=idna>IDNA</h3>
<div algorithm>
<p>The <dfn id=concept-domain-to-ascii>domain to ASCII</dfn> algorithm, given a <a for=/>string</a>
<var>domain</var> and a boolean <var>beStrict</var>, runs these steps:
<ol>
<li>
<p>Let <var>result</var> be the result of running <a abstract-op lt=ToASCII>Unicode ToASCII</a>
with <i>domain_name</i> set to <var>domain</var>, <i>CheckHyphens</i> set to <var>beStrict</var>,
<i>CheckBidi</i> set to true, <i>CheckJoiners</i> set to true, <i>UseSTD3ASCIIRules</i> set to
<var>beStrict</var>, <i>Transitional_Processing</i> set to false, <i>VerifyDnsLength</i> set to
<var>beStrict</var>, and <i>IgnoreInvalidPunycode</i> set to false. [[!UTS46]]
<p class=note>If <var>beStrict</var> is false, <var>domain</var> is an <a>ASCII string</a>, and
<a>strictly splitting</a> <var>domain</var> on U+002E (.) does not produce any
<a for=list>item</a> that <a for=string>starts with</a> an <a>ASCII case-insensitive</a> match for
"<code>xn--</code>", this step is equivalent to <a>ASCII lowercasing</a> <var>domain</var>.
<li><p>If <var>result</var> is a failure value, <a>domain-to-ASCII</a> <a>validation error</a>,
return failure.
<li>
<p>If <var>beStrict</var> is false:
<ol>
<li><p>If <var>result</var> is the empty string, <a>domain-to-ASCII</a> <a>validation error</a>,
return failure.
<li>
<p>If <var>result</var> contains a <a>forbidden domain code point</a>,
<a>domain-invalid-code-point</a> <a>validation error</a>, return failure.
<p class=note>Due to web compatibility and compatibility with non-DNS-based systems the
<a>forbidden domain code points</a> are a subset of those disallowed when
<i>UseSTD3ASCIIRules</i> is true. See also
<a href="https://github.com/whatwg/url/issues/397">issue #397</a>.
</ol>
<li>
<p><a for=/>Assert</a>: <var>result</var> is not the empty string and does not contain a
<a>forbidden domain code point</a>.
<p class=note><cite>Unicode IDNA Compatibility Processing</cite> guarantees this holds when
<var>beStrict</var> is true. [[UTS46]]
<li><p>Return <var>result</var>.
</ol>
<p class=note>This document and the web platform at large use
<cite>Unicode IDNA Compatibility Processing</cite> and not IDNA2008. For instance,
<code>☕.example</code> becomes <code>xn--53h.example</code> and not failure. [[UTS46]] [[RFC5890]]
</div>
<div algorithm>
<p>The <dfn id=concept-domain-to-unicode>domain to Unicode</dfn> algorithm, given a <a>domain</a>
<var>domain</var> and a boolean <var>beStrict</var>, runs these steps:
<ol>
<li><p>Let <var>result</var> be the result of running
<a abstract-op lt=ToUnicode>Unicode ToUnicode</a> with <i>domain_name</i> set to <var>domain</var>,
<i>CheckHyphens</i> set to <var>beStrict</var>, <i>CheckBidi</i> set to true, <i>CheckJoiners</i>
set to true, <i>UseSTD3ASCIIRules</i> set to <var>beStrict</var>, <i>Transitional_Processing</i>
set to false, and <i>IgnoreInvalidPunycode</i> set to false. [[!UTS46]]
<li><p>Signify <a>domain-to-Unicode</a> <a>validation errors</a> for any returned errors, and then,
return <var>result</var>.
</ol>
</div>
<h3 id=host-writing oldids=host-syntax>Host writing</h3>
<p>A <dfn export oldids=syntax-host>valid host string</dfn> must be a <a>valid domain string</a>, a
<a>valid IPv4-address string</a>, or: U+005B ([), followed by a
<a>valid IPv6-address string</a>, followed by U+005D (]).
<p>A <a for=/>string</a> <var>input</var> is a <dfn>valid domain</dfn> if these steps return true:
<ol>
<li><p>Let <var>domain</var> be the result of running <a>domain to ASCII</a> with <var>input</var>
and true.
<li><p>Return false if <var>domain</var> is failure; otherwise true.
</ol>
<p class=XXX>Ideally we define this in terms of a sequence of code points that make up a
<a>valid domain</a> rather than through a whack-a-mole:
<a href=https://github.com/whatwg/url/issues/245>issue 245</a>.
<p>A <dfn export oldids=syntax-host-domain>valid domain string</dfn> must be a string that is a
<a>valid domain</a>.
<p>A <dfn export oldids=syntax-host-ipv4>valid IPv4-address string</dfn> must be four shortest
possible strings of <a>ASCII digits</a>, representing a decimal number in the range 0 to 255,
inclusive, separated from each other by U+002E (.).
<p>A <dfn export oldids=syntax-host-ipv6>valid IPv6-address string</dfn> is defined in the
<a href="https://tools.ietf.org/html/rfc4291#section-2.2">"Text Representation of Addresses" chapter of IP Version 6 Addressing Architecture</a>.
[[!RFC4291]]
<!-- https://tools.ietf.org/html/rfc5952 updates that RFC, but it seems as
far as what developers can do we should be liberal