From c17ee4acbb38fc1c4a31093f9a5b85c642306aae Mon Sep 17 00:00:00 2001 From: Jeremy Roman Date: Wed, 28 Aug 2024 12:26:18 -0400 Subject: [PATCH 1/3] Explain how HTTP header fields integrate with URL patterns. Per discussion on #182 some text explaining this would be useful. --- spec.bs | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/spec.bs b/spec.bs index a567e5a..8e2ea6f 100644 --- a/spec.bs +++ b/spec.bs @@ -21,6 +21,11 @@ spec: ECMASCRIPT; urlPrefix: https://tc39.es/ecma262/ spec: URL; urlPrefix: https://url.spec.whatwg.org/ type: dfn text: serialize an integer; url: #serialize-an-integer +spec: RFC8941; urlPrefix: https://httpwg.org/specs/rfc8941.html + type: dfn + text: structured header; url: top + for: structured header + text: string; url: string

URL patterns

@@ -2021,7 +2026,7 @@ If a specification has an Infra value (e.g., after using [=parse a JSON string t To build a [=URL pattern=] from an Infra value |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=].
It may become necessary in the future to plumb non-empty options here.
@@ -2029,7 +2034,7 @@ If a specification has an Infra value (e.g., after using [=parse a JSON string t 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 identifier of a dictionary member of {{URLPatternInit}} or one of its inherited dictionaries, |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 identifier of a dictionary member of {{URLPatternInit}} or one of its inherited dictionaries, |value| is not a [=/string=], or the member's type is not declared to be {{USVString}}, then return null.
This will need to be updated if {{URLPatternInit}} gains members of other types.
A future version of this specification might also have a less strict mode, if that proves useful to other specifications.
@@ -2044,6 +2049,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, Speculation Rules 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]] +

Integrating with HTTP header fields

+ +HTTP headers which include URL patterns should accept a string in the constructor string syntax, likely as part of a structured field [[RFC8941]]. + +
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.
+ +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=]). + +
+ To build a [=URL pattern=] from an HTTP structured field value |rawPattern| given [=/URL=] |baseURL|, perform the following steps. + + 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=]. +
+ +
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.
+

Acknowledgments

The editors would like to thank From d75e99aef69d31cd8ed743c653217e367b7e8097 Mon Sep 17 00:00:00 2001 From: Jeremy Roman Date: Wed, 28 Aug 2024 16:37:53 -0400 Subject: [PATCH 2/3] Reduce boilerplate wording Co-authored-by: Domenic Denicola --- spec.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec.bs b/spec.bs index dae7755..8b42667 100644 --- a/spec.bs +++ b/spec.bs @@ -2063,7 +2063,7 @@ HTTP headers which include URL patterns should accept a string in the constructo 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=]).
- To build a [=URL pattern=] from an HTTP structured field value |rawPattern| given [=/URL=] |baseURL|, perform the following steps. + To build a [=URL pattern=] from an HTTP structured field value |rawPattern| given [=/URL=] |baseURL|: 1. Let |serializedBaseURL| be the [=URL serializer|serialization=] of |baseURL|. 1. [=Assert=]: |rawPattern| is a [=structured header/string=]. From 3f4ebef85825d93b6b152eb00a994be84fb45e9d Mon Sep 17 00:00:00 2001 From: Jeremy Roman Date: Tue, 3 Sep 2024 13:49:05 -0400 Subject: [PATCH 3/3] link to the section on constructor string (shorthand) parsing --- spec.bs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/spec.bs b/spec.bs index dae7755..de2bd44 100644 --- a/spec.bs +++ b/spec.bs @@ -36,7 +36,7 @@ spec: RFC8941; urlPrefix: https://httpwg.org/specs/rfc8941.html 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.

The shorthand "`https://example.com/:category/*`" corresponds to the following components: @@ -1988,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. @@ -2023,7 +2023,7 @@ This allows authors to concisely specify most patterns, and use the JavaScript APIs 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]] @@ -2056,7 +2056,7 @@ Specifications may wish to leave room in their formats to accept options for {{U

Integrating with HTTP header fields

-HTTP headers which include URL patterns should accept a string in the constructor string syntax, likely as part of a structured field [[RFC8941]]. +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]].
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.