Skip to content

Commit c17ee4a

Browse files
committed
Explain how HTTP header fields integrate with URL patterns.
Per discussion on whatwg#182 some text explaining this would be useful.
1 parent 69ccf3a commit c17ee4a

1 file changed

Lines changed: 25 additions & 2 deletions

File tree

spec.bs

Lines changed: 25 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,11 @@ spec: ECMASCRIPT; urlPrefix: https://tc39.es/ecma262/
2121
spec: URL; urlPrefix: https://url.spec.whatwg.org/
2222
type: dfn
2323
text: serialize an integer; url: #serialize-an-integer
24+
spec: RFC8941; urlPrefix: https://httpwg.org/specs/rfc8941.html
25+
type: dfn
26+
text: structured header; url: top
27+
for: structured header
28+
text: string; url: string
2429
</pre>
2530

2631
<h2 id=urlpatterns>URL patterns</h2>
@@ -2021,15 +2026,15 @@ If a specification has an Infra value (e.g., after using [=parse a JSON string t
20212026
To <dfn export>build a [=URL pattern=] from an Infra value</dfn> |rawPattern| given [=/URL=] |baseURL|, perform the following steps.
20222027

20232028
1. Let |serializedBaseURL| be the [=URL serializer|serialization=] of |baseURL|.
2024-
1. If |rawPattern| is a [=string=], then:
2029+
1. If |rawPattern| is a [=/string=], then:
20252030
1. Return the result of [=creating=] a URL pattern given |rawPattern|, |serializedBaseURL|, and an empty [=map=].
20262031

20272032
<div class="note">It may become necessary in the future to plumb non-empty options here.</div>
20282033

20292034
1. Otherwise, if |rawPattern| is a [=map=], then:
20302035
1. Let |init| be «[ "{{URLPatternInit/baseURL}}" → |serializedBaseURL| ]», representing a dictionary of type {{URLPatternInit}}.
20312036
1. [=map/For each=] |key| → |value| of |rawPattern|:
2032-
1. If |key| is not the <a spec=webidl>identifier</a> of a <a spec=webidl>dictionary member</a> of {{URLPatternInit}} or one of its <a spec=webidl>inherited dictionaries</a>, |value| is not a [=string=], or the member's type is not declared to be {{USVString}}, then return null.
2037+
1. If |key| is not the <a spec=webidl>identifier</a> of a <a spec=webidl>dictionary member</a> of {{URLPatternInit}} or one of its <a spec=webidl>inherited dictionaries</a>, |value| is not a [=/string=], or the member's type is not declared to be {{USVString}}, then return null.
20332038

20342039
<div class="note">This will need to be updated if {{URLPatternInit}} gains members of other types.</div>
20352040
<div class="note">A future version of this specification might also have a less strict mode, if that proves useful to other specifications.</div>
@@ -2044,6 +2049,24 @@ If a specification has an Infra value (e.g., after using [=parse a JSON string t
20442049

20452050
Specifications may wish to leave room in their formats to accept options for {{URLPatternOptions}}, override the base URL, or similar, since it is not possible to construct a {{URLPattern}} object directly in this case, unlike in a JavaScript API. For example, <cite>Speculation Rules</cite> accepts a "`relative_to`" key which can be used to switch to using the [=document base URL=] instead of the JSON resource's URL. [[SPECULATION-RULES]]
20462051

2052+
<h3 id=other-specs-http>Integrating with HTTP header fields</h3>
2053+
2054+
HTTP headers which include URL patterns should accept a string in the constructor string syntax, likely as part of a structured field [[RFC8941]].
2055+
2056+
<div class="note">No known header accepts the dictionary syntax for URL patterns. If that changes, this specification will be updated to define it, likely by processing [[RFC8941]] inner lists.</div>
2057+
2058+
Specifications for HTTP headers should operate on [=URL patterns=] (e.g., using the [=URL pattern/match=] algorithm) rather than {{URLPattern}} objects (which imply the existence of a JavaScript [=ECMAScript/realm=]).
2059+
2060+
<div algorithm>
2061+
To <dfn export>build a [=URL pattern=] from an HTTP structured field value</dfn> |rawPattern| given [=/URL=] |baseURL|, perform the following steps.
2062+
2063+
1. Let |serializedBaseURL| be the [=URL serializer|serialization=] of |baseURL|.
2064+
1. [=Assert=]: |rawPattern| is a [=structured header/string=].
2065+
1. Return the result of [=creating=] a URL pattern given |rawPattern|, |serializedBaseURL|, and an empty [=map=].
2066+
</div>
2067+
2068+
<div class="note">Specifications might consider accepting only patterns which do not [=URL pattern/has regexp groups|have regexp groups=] if evaluating the pattern, since the performance of such patterns might be more reliable, and may not require a [[ECMA-262]] regular expression implementation, which may have security, code size, or other implications for implementations. On the other hand, JavaScript APIs run in environments where such an implementation is readily available.</div>
2069+
20472070
<h2 id=acknowledgments class=no-num>Acknowledgments</h2>
20482071

20492072
The editors would like to thank

0 commit comments

Comments
 (0)