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.

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

Explain how HTTP header fields integrate with URL patterns #230

Merged
merged 5 commits into from
Sep 27, 2024
Merged
Changes from 3 commits
Commits
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
27 changes: 25 additions & 2 deletions spec.bs
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 Down Expand Up @@ -2026,15 +2031,15 @@ If a specification has an Infra value (e.g., after using [=parse a JSON string t
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 syntax, likely as part of a structured field [[RFC8941]].
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is "constructor string syntax"? Is this talking about the URLPattern constructor which it below says should not be relied upon?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It refers to the syntax that is accepted when a single string is passed to the constructor (i.e., is accepted by the constructor string parser), as opposed to the pattern syntax for a single component.

It could be renamed something else, but this is how the spec currently refers to that syntax.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think if the syntax is defined somewhere and you can xref it that seems reasonable. Otherwise it seems rather opaque to me.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added links to the constructor string parsing section.


<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