Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Explain how HTTP header fields integrate with URL patterns #230

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Explain how HTTP header fields integrate with URL patterns #230

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
c17ee4a
Explain how HTTP header fields integrate with URL patterns.
jeremyroman Aug 28, 2024
67f0dcd
Merge remote-tracking branch 'whatwg/main' into http-integration
jeremyroman Aug 28, 2024
d75e99a
Reduce boilerplate wording
jeremyroman Aug 28, 2024
3f4ebef
link to the section on constructor string (shorthand) parsing
jeremyroman Sep 3, 2024
667051e
Merge remote-tracking branch 'origin/http-integration' into http-inte…
jeremyroman Sep 3, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 28 additions & 5 deletions spec.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,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 @@ -31,7 +36,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 @@ -1983,7 +1988,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 @@ -2018,23 +2023,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 @@ -2049,6 +2054,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
Loading