Skip to content

Commit

Permalink
Explain how HTTP header fields integrate with URL patterns
Browse files Browse the repository at this point in the history
Per discussion on #182 some text explaining this would be useful.

This mostly consists of advice since the useful algorithms are already exposed.
  • Loading branch information
jeremyroman authored Sep 27, 2024
1 parent e2c2ef8 commit b45203d
Showing 1 changed file with 28 additions and 5 deletions.
33 changes: 28 additions & 5 deletions spec.bs
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,11 @@ spec: URL; urlPrefix: https://url.spec.whatwg.org/
type: dfn
text: serialize an integer; url: #serialize-an-integer
text: host serializer; url: #concept-host-serializer
spec: RFC8941; urlPrefix: https://httpwg.org/specs/rfc8941.html
type: dfn
text: structured header; url: top
for: structured header
text: string; url: string
</pre>

<h2 id=urlpatterns>URL patterns</h2>
Expand All @@ -33,7 +38,7 @@ spec: URL; urlPrefix: https://url.spec.whatwg.org/

A [=URL pattern=] consists of several [=components=], each of which represents a [=/pattern string|pattern=] which could be matched against the corresponding component of a [=/URL=].

It can be constructed using a string for each component, or from a shorthand string. It can optionally be resolved relative to a base URL.
It can be constructed using a string for each component, or from a [[#constructor-string-parsing|shorthand string]]. It can optionally be resolved relative to a base URL.

<div class="example" id="example-intro">
<p>The shorthand "`https://example.com/:category/*`" corresponds to the following components:
Expand Down Expand Up @@ -1993,7 +1998,7 @@ typedef (USVString or URLPatternInit or URLPattern) URLPatternCompatible;
JavaScript APIs should accept all of:
* a {{URLPattern}} object
* a dictionary-like object which specifies the components required to construct a pattern
* a string (in the constructor string syntax)
* a string (in the [[#constructor-string-parsing|constructor string syntax]])

To accomplish this, specifications should accept {{URLPatternCompatible}} as an argument to an [=operation=] or [=dictionary member=], and process it using the following algorithm, using the appropriate [=environment settings object=]'s [=environment settings object/API base URL=] or equivalent.

Expand Down Expand Up @@ -2028,23 +2033,23 @@ This allows authors to concisely specify most patterns, and use the <a construct

JSON data formats which include URL patterns should mirror the behavior of <a href="#other-specs-javascript">JavaScript APIs</a> and accept both:
* an object which specifies the components required to construct a pattern
* a string (in the constructor string syntax)
* a string (in the [[#constructor-string-parsing|constructor string syntax]])

If a specification has an Infra value (e.g., after using [=parse a JSON string to an Infra value=]), use the following algorithm, using the appropriate base URL (by default, the URL of the JSON resource). [[INFRA]]

<div algorithm>
To <dfn export>build a [=URL pattern=] from an Infra value</dfn> |rawPattern| given [=/URL=] |baseURL|, perform the following steps.

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

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

1. Otherwise, if |rawPattern| is a [=map=], then:
1. Let |init| be «[ "{{URLPatternInit/baseURL}}" → |serializedBaseURL| ]», representing a dictionary of type {{URLPatternInit}}.
1. [=map/For each=] |key| → |value| of |rawPattern|:
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.
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.

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

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]]

<h3 id=other-specs-http>Integrating with HTTP header fields</h3>

HTTP headers which include URL patterns should accept a string in the [[#constructor-string-parsing|constructor string syntax]], likely as part of a structured field [[RFC8941]].

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

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=]).

<div algorithm>
To <dfn export>build a [=URL pattern=] from an HTTP structured field value</dfn> |rawPattern| given [=/URL=] |baseURL|:

1. Let |serializedBaseURL| be the [=URL serializer|serialization=] of |baseURL|.
1. [=Assert=]: |rawPattern| is a [=structured header/string=].
1. Return the result of [=creating=] a URL pattern given |rawPattern|, |serializedBaseURL|, and an empty [=map=].
</div>

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

<h2 id=acknowledgments class=no-num>Acknowledgments</h2>

The editors would like to thank
Expand Down

0 comments on commit b45203d

Please sign in to comment.