From 3f76dedd64e2035d6b655230b6c87b410e6d173e Mon Sep 17 00:00:00 2001 From: SirishaDuba Date: Tue, 28 Oct 2025 16:18:59 +0530 Subject: [PATCH] Removed outdated markdown files as per issue #195 --- 202012-update.md | 204 ------------- dev-trials-feedack.md | 63 ---- docs/urlpattern.md | 1 - howto.md | 19 -- mdn-drafts/QUICK-REFERENCE.md | 524 ---------------------------------- tag-security-privacy.md | 39 --- 6 files changed, 850 deletions(-) delete mode 100644 202012-update.md delete mode 100644 dev-trials-feedack.md delete mode 100644 docs/urlpattern.md delete mode 100644 howto.md delete mode 100644 mdn-drafts/QUICK-REFERENCE.md delete mode 100644 tag-security-privacy.md diff --git a/202012-update.md b/202012-update.md deleted file mode 100644 index 69b8da6..0000000 --- a/202012-update.md +++ /dev/null @@ -1,204 +0,0 @@ -# Incubation Update - December 2020 - -## Overview - -URLPattern is a new web API for matching URLs. Its intended to both provide a convenient API for web developers and to be usable in other web APIs that need to match URLs; e.g. service workers. The [explainer](explainer.md) discusses the motivating use cases. There is also a [design document](https://docs.google.com/document/d/17L6b3zlTHtyxQvOAvbK55gQOi5rrJLERwjt_sKXpzqc/edit?usp=sharing) that goes into more details. - -Currently URLPattern is in [development](https://www.chromestatus.com/feature/5731920199548928) in Chromium based browsers. A specification has not been written yet. Once the initial prototype is complete we will gather feedback and iterate. When we believe the API is stable, we will then codify it in a spec. - -URLPattern's integration with service workers is not being worked on yet, as we want to get URLPattern in a solid shippable state first. - -As discussed in the [explainer](explainer.md) and [design document](https://docs.google.com/document/d/17L6b3zlTHtyxQvOAvbK55gQOi5rrJLERwjt_sKXpzqc/edit?usp=sharing), URLPattern is heavily based on Blake Embrey's [path-to-regexp](https://github.com/pillarjs/path-to-regexp) library. Various versions of this library are used in such projects as [express.js](https://expressjs.com/), [koa.js](https://koajs.com/), and [react-router](https://reactrouter.com/). By using a popular matching library with existing traction we hope to follow a well lit path and deliver a useful API to web developers. - -To that end we have implemented a large portion of path-to-regexp in C++ in an MIT licensed library called liburlpattern. It is currently being developed in the Chromium source tree [here](https://source.chromium.org/chromium/chromium/src/+/master:third_party/liburlpattern/). This implementation is based on version 6.2.0 of path-to-regexp. In addition, we plan to add back support for the `*` wildcard character that was previously in path-to-regexp up to version 1.7.0. - -Currently there is a partial implementation of URLPattern available in [Chrome Canary](https://www.google.com/chrome/canary/). To access it you must enable "Experimental Web Platform features" by enabling a [flag](chrome://flags/#enable-experimental-web-platform-features). The following discusses the implementation as of version 89.0.4358.0. - -Kenneth Rohde Christiansen is also working on a URLPattern [polyfill](https://github.com/kenchris/urlpattern-polyfill). Note that this polyfill currently implements some features not yet implemented in Chromium yet. There may also be slight differences until the API stabilizes. - -If you have questions or feedback, please start a [discussion](https://github.com/WICG/urlpattern/discussions) on the WICG/urlpattern repo. - -## API - -The API currently consists of the `URLPattern()` constructor and two matching methods; `test()` and `exec()`. The related [Web IDL](https://heycam.github.io/webidl/) can be found [here](https://source.chromium.org/chromium/chromium/src/+/master:third_party/blink/renderer/modules/url_pattern/). - -### Constructor - -The `URLPattern()` constructor accepts a single object argument. This dictionary can contain separate patterns for each URL component. For example (see [path-to-regexp](https://github.com/pillarjs/path-to-regexp) for pattern syntax): - -```javascript -const p = new URLPattern({ - protocol: 'https', - username: '', - password: '', - hostname: 'example.com', - port: '', - pathname: '/foo/:image.jpg', - search: '(.*)', - hash: '(.*)', -}); -``` - -This is example is very verbose. Fortunately, it can be simplified. First, if a component is not specified it defaults to the `(.*)` wildcard pattern. So we can write: - -```javascript -const p = new URLPattern({ - protocol: 'https', - username: '', - password: '', - hostname: 'example.com', - port: '', - pathname: '/foo/:image.jpg', -}); -``` - -This is still pretty long, though. To further simplify we can provide the fixed origin patterns via a `baseURL` property. - -```javascript -const p = new URLPattern({ - pathname: '/foo/:image.jpg', - baseURL: 'https://example.com', -}); -``` - -So far all of the above code snippets have been equivalent. If it turns out we only really care about finding image file names and don't need strict origin checking we can even just leave the baseURL off completely. This will be a more lenient, different pattern, but its quite brief: - -```javascript -const p = new URLPattern({ pathname: '/foo/:image.jpg' }); -``` - -The constructor also supports relative pathnames. For example, the following is equivalent to the first snippet above. - -```javascript -const p = new URLPattern({ - pathname: ':image.jpg', - baseURL: 'https://example.com/foo/', -}); -``` - -Currently URLPattern does not perform any encoding or normalization of the patterns. So a developer would need to URL encode unicode characters before passing the pattern into the constructor. Similarly, the constructor does not do things like flattening pathnames such as `/foo/../bar` to `/bar`. Currently the pattern must be written to target canonical URL output manually. There is an [open question](#open-questions) below whether the constructor should try to help more here or not. - -### Matching - -Both the `test()` and `exec()` methods take the same input and perform the same matching algorithm. They only differ in their return value. So let's discuss the common parts first. - -The matching methods take a single argument consisting of either a string or a dictionary object like the one used in the constructor. - -In the case of the string it is parsed as a URL. Each component of the URL is then compared to the URLPattern's component pattern one by one. If they all match, then the entire matching operation succeeds. Otherwise the match fails. - -In the case of the dictionary object the provided then the initial URL parsing step is skipped. Instead the components are individually encoded and normalized per normal URL rules. In addition, baseURL resolution is supported. Any missing components are assumed to be the empty string. The components are then again compared against the URLPattern's component patterns one by one. Again, if they all match then the overall operation succeeds. - -To make that a bit more concrete, these two method calls are equivalent: - -```javascript -// string input -p.test('https://example.com/foo/bar'); - -// dictionary input -p.test({ - pathname: '/foo/bar', - baseURL: 'https://example.com', -}); -``` - -The dictionary input, though, is really intended as a convenience for when you only have part of a URL available. For example, maybe you only have a pathname and not a full URL available. For example: - -```javascript -// we only care about the pathname -const p = new URLPattern({ pathname: '/foo/:name' }); - -// we only provide the pathname -p.test({ pathname: '/foo/bar' }); -``` - -If the match input is invalid `test()` and `exec()` simply return `false` instead of throwing. So `p.test({ port: 'bad' })` will always return `false`. - -The main difference between `test()` and `exec()` is the return value. The `test()` method returns `true` or `false` to indicate if the input matched the pattern. - -The `exec()` method, however, returns a full result object. It contains a property with the input to `exec()` and then a separate sub-result for each component. Each component result then contains the canonicalized input value for that component and a dictionary of group results. For example: - -```javascript -const p = new URLPattern({ pathname: '(.*)/:image.jpg' }); -const r = p.exec('https://example.com/foo/bar/cat.jpg?q=v'); - -// outputs 'https://example.com/foo/bar/cat.jpg?q=v' -console.log(r.input); - -// outputs '/foo/bar/cat.jpg' -console.log(r.pathname.input); - -// outputs 'cat' -console.log(r.pathname.groups.image); -``` - -## What's Still Left To Do - -While the current URLPattern implementation is usable, there are a number of additional features planned. - -* Support for a `*` wildcard character in patterns. This character would be equivalent to the `(.*)` regular expression group. This was previously available in path-to-regexp 1.7.0, but was later removed. We would like to support it in URLPattern since many existing URL matching systems in the web platform use `*` wildcards and this would offer us some compatibility with them. Discussions with the path-to-regexp author suggest it might be possible to upstream this change back to path-to-regexp. -* Possible support for a "short form" argument to the constructor that supports patterns inline in a URL string. For example, `new URLPattern('https://:cdnserver.foo.com/(.*)/:image.jpg')`. Its not clear yet how easily we can support this since certain characters are both pattern syntax characters and used in URL parsing; e.g. the `:` character, etc. -* Getters to access per-component patterns. For example, `p.pathname` returning `'(.*)/:image.jpg'`. -* Getters to access per-component regular expressions equivalent to matching the component pattern; e.g. `p.pathnameRegExp`. -* A toString() method that generates useful output. -* Better error reporting. For example, if you pass a bad regular expression embedded within a pattern we do not identify which regexp group is the problem, etc. -* Support a relative URL string argument to `test()` and `exec()` with a second argument providing the base URL. -* A URLPatternList object that would aggregate multiple URLPattern objects. -* Serialization support so that URLPattern objects can be passed through postMessage() and stored in indexedDB. -* Additional features identified by answering the open questions below... - -## Open Questions - -There are also a number of open questions to be answered. - -* [[Discussion 37](https://github.com/WICG/urlpattern/discussions/37)] - Currently URLPattern does no automatic encoding or URL canonicalization for patterns. It does, however, perform these operations for `test()` and `exec()` input. This means developers must write patterns to target canonical URL output which may mean manually encoding characters, etc. This may be non-ergonomic, particularly for developers working with non-Latin character sets. We could provide some encoding and canonicalization, but it would be uneven. For example, we probably could not automatically encode characters within a custom regular expression grouping. How much, if any, canonicalization to do is an open question. -* [[Discussion 38](https://github.com/WICG/urlpattern/discussions/38)] - Currently URLPattern uses case-sensitive matching whereas path-to-regexp uses case-insensitive matching by default. Again, will this cause problems and do we need to provide an option to control the behavior? -* [[Discussion 39](https://github.com/WICG/urlpattern/discussions/39)] - Currently URLPattern sets the path-to-regexp "strict" mode flag to true. By default path-to-regexp sets strict mode to false. When strict mode is disabled the pattern will implicitly allow a trailing slash on a pathname. We have chosen to set strict to true since its possible to achieve the same effect by appending `{/}?` to the end of a pattern. Conversely, its not possible to avoid the automatic slash behavior if strict mode is disabled. Will this cause problems for developers used to path-to-regexp behavior? - -## Questions? Feedback? - -If you have questions or feedback, please start a [discussion](https://github.com/WICG/urlpattern/discussions) on the WICG/urlpattern repo. - -## Ackowledgements - -Special thanks to Blake Embrey and the other path-to-regexp [contributors](https://github.com/pillarjs/path-to-regexp/graphs/contributors) for building an excellent open source library that so many have found useful. - -Also, special thanks to Kenneth Rohde Christiansen for his work on the polyfill. He put in extensive work to adapt to the changing URLPattern API. - -URLPattern is the culmination of extensive input and review from many people. Thanks to: - -* Łukasz Anforowicz -* Jake Archibald -* Kenji Baheux -* L. David Baron -* Joshua Bell -* Ralph Chelala -* Kenneth Rohde Christiansen -* Victor Costan -* Devlin Cronin -* Domenic Denicola -* Blake Embrey -* Youenn Fablet -* Matt Falkenhagen -* Matt Giuca -* Joe Gregorio -* Darwin Huang -* Kenichi Ishibashi -* Rajesh Jagannathan -* Cyrus Kasaaian -* Anne van Kesteren -* R. Samuel Klatchko -* Marijn Kruisselbrink -* Asa Kusuma -* Michael Landry -* Sangwhan Moon -* Daniel Murphy -* Dominick Ng -* Kingsley Ngan -* Jeffrey Posnick -* Jeremy Roman -* Alex Russell -* Jimmy Shen -* Makoto Shimazu -* Kinuko Yasuda - -Finally, thank you to Dominic Denicola, Kenneth Rohde Christiansen, and Jeremy Roman for reviewing this post. diff --git a/dev-trials-feedack.md b/dev-trials-feedack.md deleted file mode 100644 index 9cb6740..0000000 --- a/dev-trials-feedack.md +++ /dev/null @@ -1,63 +0,0 @@ -# URLPattern Dev Trials Feedback - -Last updated: August 13, 2021 - - -## Overview - -The [Ready for Trial](https://groups.google.com/a/chromium.org/g/blink-dev/c/WitVII_BzyU/m/mI8lZY4NAgAJ) announcement was sent for URLPattern on July 22. To help spread awareness of the information and help developers try the API, we also did the following: - - - -* Published a [web.dev article](https://web.dev/urlpattern/). -* Published [draft MDN documentation](https://github.com/WICG/urlpattern/blob/main/mdn-drafts/QUICK-REFERENCE.md). -* Boosted with a [twitter thread](https://twitter.com/jeffposnick/status/1418245808563101701). -* Ran a survey against a panel of web developers. - -This post captures the feedback we have received to date regarding the URLPattern API. [Additional feedback](https://github.com/WICG/urlpattern/issues/new) is still welcome, of course. - -In general feedback has been positive. The following sections provide some more detail. - - -## Survey Results - -The survey gave us the opportunity to collect structured feedback from a panel of web developers. This was an English language survey. - -A summary of the results follows: - - - -* 77% of respondents (n=247) were familiar with URL matching, with 42% actively using it. -* 80% of respondents (n=247) had a positive initial impression of the URLPattern API. 5% had a negative initial impression. -* 87% of respondents (n=180) felt the URLPattern API met their needs either fairly or very well. Only 4% of respondents felt the API met their needs poorly. -* 75% of respondents (n=180) agreed they would use the URLPattern API if it shipped. -* 83% of respondents (n=180) agreed that integrating URLPattern API with other web APIs would make it easier for sites to use those other web APIs. -* 68% of respondents (n=180) indicated URLPattern support internationalization fairly or very well. 28% indicated they could not say. Only 4% thought the API supported i18n poorly. (Again, note that this was an English language survey which may skew the results on this question.) - - -## Specific Feedback - -We have tried to capture specific feedback in the URLPattern Github [issues](https://github.com/WICG/urlpattern/issues). We call out a selection of the significant issues here. - -First, there were a couple of feature requests: - - - -* The most common piece of feedback across social media, the survey, and github has been a feature request to [support the generation of URL strings from a URLPattern and set of parameter values](https://github.com/WICG/urlpattern/issues/73). This is similar to [path-to-regexp](https://github.com/pillarjs/path-to-regexp)'s `compile()` function. Web developers use this feature to generate requests back to the server. This technique has the benefit of encapsulating the URL structure in the pattern string so that the using code does not need to be aware of it. -* One of the [vue](https://vuejs.org/) framework's authors has indicated they would need an [ordering of patterns](https://github.com/WICG/urlpattern/issues/61) in order to use the API. This use case is bolstered by the fact that a popular server-side routing framework, [find-my-way](https://github.com/delvedor/find-my-way), also provides an ordering of routes. - -These seem like worthwhile features to add, but we would like to tackle them after initially launching the matching capability. Matching is useful on its own and is also a blocker for integration into some other web APIs like service worker scopes. - -Second, there was some generalized feedback about [performance](https://github.com/WICG/urlpattern/issues/42) of URLPattern compared to the server-side framework [find-my-way](https://github.com/delvedor/find-my-way). Initial investigations suggest URLPattern should be able to achieve most of the same optimizations. We plan to do some additional performance investigation before launching the API. - -Finally, at the end of 2020 an [issue](https://github.com/WICG/urlpattern/issues/43) was filed pointing out that `:foo` named parameters may not be friendly to right-to-left languages. As part of this discussion we realized named parameters did not support unicode at the time. That has been fixed and named parameters now support the same code points as javascript identifiers. - -In regards to the RTL issue, however, so far we have decided to proceed with `:foo` style names. We are doing this for a few reasons. First, `:foo` names are well established across many different URL pattern matching systems; e.g. ruby on rails, etc. This is a well lit path we are following from the industry and not something new we have introduced. - -In addition, URLPattern API integrates these names into the result returned to javascript. Javascript is a left-to-right language. For example, javascript identifiers allow different code points in the left-hand "first" position compared to the rest of the identifier. Since we want to integrate well with javascript it seems difficult to fully support an RTL name. - -Further, there has been no follow-up from the original reporter or anyone else indicating that this is a problem or what an acceptable solution might look like. We have also requested a w3c i18n review, but received no feedback. Therefore, barring additional feedback, we plan to proceed with `:foo` names. - -## Additional Articles - -* https://css-tricks.com/native-javascript-routing/ diff --git a/docs/urlpattern.md b/docs/urlpattern.md deleted file mode 100644 index c9682fc..0000000 --- a/docs/urlpattern.md +++ /dev/null @@ -1 +0,0 @@ -This document has [moved](../mdn-drafts/QUICK-REFERENCE.md). diff --git a/howto.md b/howto.md deleted file mode 100644 index 794e317..0000000 --- a/howto.md +++ /dev/null @@ -1,19 +0,0 @@ -# How to use the URLPattern API - -The URLPattern API is currently available in Chrome 93 and later behind a flag. - -1. Download Chrome ([Android](https://play.google.com/store/apps/details?id=com.android.chrome), [Desktop](https://www.google.com/chrome/)). -2. Navigate to `chrome://flags` and enable `Experimental Web Platform features`. -3. Visit a page that uses `URLPattern`, such as the [demo on glitch](https://urlpattern-sw-routing.glitch.me/). - -Here is an example of how to use the API: - -```javascript -const pattern = new URLPattern({ pathname: '/:product/index.html' }); -const result = pattern.exec(someURL); -if (result) { - handleProduct(result.pathname.groups.product); -} -``` - -More code examples can be found in the [URLPattern documentation](docs/urlpattern.md). diff --git a/mdn-drafts/QUICK-REFERENCE.md b/mdn-drafts/QUICK-REFERENCE.md deleted file mode 100644 index 5af83e8..0000000 --- a/mdn-drafts/QUICK-REFERENCE.md +++ /dev/null @@ -1,524 +0,0 @@ -## Description - -The `URLPattern` interface provides a web platform primitive for matching -URLs. The pattern syntax is adopted from the popular [path-to-regexp][] -javascript library and is more ergonomic than using regular expressions. - -### Normalization - -When a URL is parsed it is automatically normalized to a canonical form. For -example, unicode characters are percent encoded in the `pathname` property, punycode -encoding is used in the hostname, default port numbers are elided, paths like -`/foo/./bar/` are collapsed to just `/foo/bar`, etc. In addition, there are some -pattern representations that parse to the same underlying meaning, like `foo` and -`{foo}`. Such cases are normalized to the simplest form. In this case `{foo}` gets -changed to `foo`. - -## Constructor - -Creates a new `URLPattern` object. It has two forms. - -**`new URLPattern(obj)`** - -This form of the constructor takes a `URLPatternInit` dictionary object that -describes the URLs you want to match. Its members can be any of `protocol`, -`username`, `password`, `hostname`, `port`, `pathname`, `search`, `hash`, or -`baseURL`. If the `baseURL` property is provided it will be parsed as a URL -and used to populate any other properties that are missing. If the `baseURL` -property is missing, then any other missing properties default to the pattern -`*` wildcard, accepting any input. - -**`new URLPattern(pattern, baseURL)`** - -This form of the constructor takes a URL string that contains patterns embedded -in it. The URL string may be relative if a base URL is provided as the second -argument. Note, it may be necessary to escape some characters in the URL -string where its ambiguous whether the character is separating different URL -components or if it's instead part of a pattern. For example, you must write -`about\\:blank` to indicate that the `:` is the protocol suffix and not the -start of a `:blank` named group pattern. - -## Properties - -**`URLPattern.protocol`** - -Returns the URL scheme pattern passed to the constructor. This value may -be differ from the input to the constructor due to normalization. - -**`URLPattern.username`** - -Returns the URL username pattern set during construction. This value may -be differ from the input to the constructor due to normalization. - -**`URLPattern.password`** - -Returns the URL password pattern set during construction. This value may -be differ from the input to the constructor due to normalization. - -**`URLPattern.hostname`** - -Returns the URL hostname pattern set during construction. This value may -be differ from the input to the constructor due to normalization. - -**`URLPattern.port`** - -Returns the URL port pattern set during construction. This value may -be differ from the input to the constructor due to normalization. - -**`URLPattern.pathname`** - -Returns the URL path pattern set during construction. This value may -be differ from the input to the constructor due to normalization. - -**`URLPattern.search`** - -Returns the URL query pattern set during construction. This value may -be differ from the input to the constructor due to normalization. - -**`URLPattern.hash`** - -Returns the URL hash pattern set during construction. This value may -be differ from the input to the constructor due to normalization. - -## Events - -None - -## Methods - -**`URLPattern.test()`** - -Returns a boolean indicating whether the passed string matches the current pattern. - -**`URLPattern.exec()`** - -Returns a `URLPatternResult` object containing detailed information about the match along with capture groups, or null if there is no match. - -## Examples - -### Filter on a Specific URL Component - -The following example shows how a URLPattern filters a -specific URL component. When the `URLPattern()` constructor is called with a -structured object of component patterns any missing components default to -the `*` wildcard value. - -```js -// Construct a URLPattern that matches a specific domain and its subdomains. -// All other URL components default to the wildcard `*` pattern. -const pattern = new URLPattern({ - hostname: `{*.}?example.com` -}); - -// Prints `{*.}?example.com` -console.log(pattern.hostname); - -// All print `*` -console.log(pattern.protocol); -console.log(pattern.username); -console.log(pattern.password); -console.log(pattern.pathname); -console.log(pattern.search); -console.log(pattern.hash); - -// Prints `true` -console.log(pattern.test("https://example.com/foo/bar")); - -// Prints `true` -console.log(pattern.test({ hostname: "cdn.example.com" })); - -// Prints `true` -console.log(pattern.test("custom-protocol://example.com/other/path?q=1")); - -// Prints `false` because the hostname component does not match -console.log(pattern.test("https://cdn-example.com/foo/bar")); -``` - -### Construct a URLPattern from a Full URL String. - -The following example shows how a URLPattern can be constructed from a full -URL string with patterns embedded. For example, a `:` can be both the URL -protocol suffix, like `https:`, and the beginning of a named pattern group, -like `:foo`. If there is no ambiguity between whether a character is a part -of the URL syntax or part of the pattern syntax then it just works. - -```js -// Construct a URLPattern that matches URLs to CDN servers loading jpg images. -// URL components not explicitly specified, like search and hash here, result -// in the empty string similar to the URL() constructor. -const pattern = new URLPattern("https://cdn-*.example.com/*.jpg"); - -// Prints `https` -console.log(pattern.protocol); - -// Prints `cdn-*.example.com` -console.log(pattern.hostname); - -// Prints `/*.jpg` -console.log(pattern.pathname); - -// All print `""` -console.log(pattern.username); -console.log(pattern.password); -console.log(pattern.search); -console.log(pattern.hash); - -// Prints `true` -console.log( - pattern.test("https://cdn-1234.example.com/product/assets/hero.jpg"); - -// Prints `false` because the search component does not match -console.log( - pattern.test("https://cdn-1234.example.com/product/assets/hero.jpg?q=1"); -``` - -### Constructing a URLPattern with an Ambiguous URL String. - -The following example shows how a URLPattern constructed from an ambiguous -string will favor treating characters as part of the pattern syntax. In -this case the `:` character could be the protocol component suffix or it -could be the prefix for a pattern named group. The constructor chooses -to treat this as part of the pattern and therefore determines this is -a relative pathname pattern. Since there is no base URL the relative -pathname cannot be resolved and it throws an error. - -```js -// Throws because this is interpreted as a single relative pathname pattern -// with a ":foo" named group and there is no base URL. -const pattern = new URLPattern("data:foo*"); -``` - -### Escaping Characters to Disambiguate URLPattern Constructor Strings - -The following example shows how an ambiguous constructor string character -can be escaped to be treated as a URL separator instead of a pattern -character. Here `:` is escaped as `\\:`. - -```js -// Constructs a URLPattern treating the `:` as the protocol suffix. -const pattern = new URLPattern("data\\:foo*"); - -// Prints `data` -console.log(pattern.protocol); - -// Prints `foo*` -console.log(pattern.pathname); - -// All print `""` -console.log(pattern.username); -console.log(pattern.password); -console.log(pattern.hostname); -console.log(pattern.port); -console.log(pattern.search); -console.log(pattern.hash); - -// Prints `true` -console.log(pattern.test("data:foobar")); -``` - -### Using Base URLs for test() and exec() - -The following example shows how input values to `test()` and `exec()` can use -base URLs. - -```js -const pattern = new URLPattern({ hostname: "example.com", pathname: "/foo/*" }); - -// Prints `true` as the hostname based in the dictionary `baseURL` property -// matches. -console.log( - pattern.test({ pathname: "/foo/bar", baseURL: "https://example.com/baz" })); - -// Prints `true` as the hostname in the second argument base URL matches. -console.log(pattern.test("/foo/bar", "https://example.com/baz")); - -// Throws because the second argument cannot be passed with a dictionary input. -try { - pattern.test({ pathname: "/foo/bar" }, "https://example.com/baz"); -} catch (e) {} - -// The `exec()` method takes the same arguments as `test()`. -const result = pattern.exec("/foo/bar", "https://example.com/baz"); - -// Prints `/foo/bar` -console.log(result.pathname.input); - -// Prints `bar` -console.log(result.pathname.groups[0]); - -// Prints `example.com` -console.log(result.hostname.input); -``` - -### Using base URLs in the URLPattern Constructor. - -The follow example shows how base URLs can also be used to construct the -URLPattern. It's important to note that the base URL in these cases is -treated strictly as a URL and cannot contain any pattern syntax itself. - -Also, since the base URL provides a value for every component the resulting -URLPattern will also have a value for every component; even if it's the -empty string. This means you do not get the "default to wildcard" behavior. - -```js -const pattern1 = new URLPattern({ pathname: "/foo/*", - baseURL: "https://example.com" }); - -// Prints `https` -console.log(pattern1.protocol); - -// Prints `example.com` -console.log(pattern1.hostname); - -// Prints `/foo/*` -console.log(pattern1.pathname); - -// All print `""` -console.log(pattern1.username); -console.log(pattern1.password); -console.log(pattern1.port); -console.log(pattern1.search); -console.log(pattern1.hash); - -// Equivalent to pattern1 -const pattern2 = new URLPattern("/foo/*", "https://example.com" }); - -// Throws because a relative constructor string must have a base URL to resolve -// against. -try { - const pattern3 = new URLPattern("/foo/*"); -} catch (e) {} -``` - -### Accessing Matched Group Values - -The following example shows how input values that match pattern groups can later -be accessed from the `exec()` result object. Unnamed groups are assigned index -numbers sequentially. - -```js -const pattern = new URLPattern({ hostname: "*.example.com" }); -const result = pattern.exec({ hostname: "cdn.example.com" }); - -// Prints `cdn` -console.log(result.hostname.groups[0]); - -// Prints `cdn.example.com` -console.log(result.hostname.input); - -// Prints `[{ hostname: "cdn.example.com" }]` -console.log(result.inputs); -``` - -### Accessing Matched Group Values Using Custom Names - -The following example shows how groups can be given custom names which can -be used to accessed the matched value in the result object. - -```js -// Construct a URLPattern using matching groups with custom names. These -// names can then be later used to access the matched values in the result -// object. -const pattern = new URLPattern({ pathname: "/:product/:user/:action" }); -const result = pattern.exec({ pathname: "/store/wanderview/view" }); - -// Prints `store` -console.log(result.pathname.groups.product); - -// Prints `wanderview` -console.log(result.pathname.groups.user); - -// Prints `view` -console.log(result.pathname.groups.action); - -// Prints `/store/wanderview/view` -console.log(result.pathname.input); - -// Prints `[{ pathname: "/store/wanderview/view" }]` -console.log(result.inputs); -``` - -### Custom Regular Expression Groups - -The following example shows how a matching group can use a custom regular -expression. - -```js -const pattern = new URLPattern({ pathname: "/(foo|bar)" }); - -// Prints `true` -console.log(pattern.test({ pathname: "/foo" })); - -// Prints `true` -console.log(pattern.test({ pathname: "/bar" })); - -// Prints `false` -console.log(pattern.test({ pathname: "/baz" })); - -const result = pattern.exec({ pathname: "/foo" }); - -// Prints `foo` -console.log(result.pathname.groups[0]); -``` - -### Named Group with a Custom Regular Expression - -The following example shows how a custom regular expression can be used with a -named group. - -```js -const pattern = new URLPattern({ pathname: "/:type(foo|bar)" }); -const result = pattern.exec({ pathname: "/foo" }); - -// Prints `foo` -console.log(result.pathname.groups.type); -``` - -### Making Matching Groups Optional - -The following example shows how a matching group can be made optional by placing -a `?` modifier after it. For the pathname component this also causes any -preceding `/` character to also be treated as an optional prefix to the group. - -```js -const pattern = new URLPattern({ pathname: "/product/(index.html)?" }); - -// Prints `true` -console.log(pattern.test({ pathname: "/product/index.html" })); - -// Prints `true` -console.log(pattern.test({ pathname: "/product" })); - -const pattern2 = new URLPattern({ pathname: "/product/:action?" }); - -// Prints `true` -console.log(pattern2.test({ pathname: "/product/view" })); - -// Prints `true` -console.log(pattern2.test({ pathname: "/product" })); - -// Wildcards can be made optional as well. This may not seem to make sense -// since they already match the empty string, but it also makes the prefix -// `/` optional in a pathname pattern. -const pattern3 = new URLPattern({ pathname: "/product/*?" }); - -// Prints `true` -console.log(pattern3.test({ pathname: "/product/wanderview/view" })); - -// Prints `true` -console.log(pattern3.test({ pathname: "/product" })); - -// Prints `true` -console.log(pattern3.test({ pathname: "/product/" })); -``` - -### Making Matching Groups Repeated - -The following example shows how a matching group can be made repeated by placing -a `+` modifier after it. In the pathname component this also treats the -`/` prefix as special. It is repeated with the group. - -```js -const pattern = new URLPattern({ pathname: "/product/:action+" }); -const result = pattern.exec({ pathname: "/product/do/some/thing/cool" }); - -// `do/some/thing/cool` -result.pathname.groups.action; - -// Prints `false` -console.log(pattern.test({ pathname: "/product" })); -``` - -### Making Matching Groups Optional and Repeated - -The following example shows how a matching group can be made both optional and -repeated. This is done by placing a `*` modifier after the group. Again, the -pathname component treats the `/` prefix as special. It both becomes optional -and is also repeated with the group. - -```js -const pattern = new URLPattern({ pathname: "/product/:action*" }); -const result = pattern.exec({ pathname: "/product/do/some/thing/cool" }); - -// Prints `do/some/thing/cool` -console.log(result.pathname.groups.action); - -// Prints `true` -console.log(pattern.test({ pathname: "/product" })); -``` - -### Using a Custom Prefix or Suffix for an Optional or Repeated Modifier - -The following example shows how curly braces can be used to denote a custom -prefix and/or suffix to be operated on by a subsequent `?`, `*`, or `+` -modifier. - -```js -const pattern = new URLPattern({ hostname: "{:subdomain.}*example.com" }); - -// Prints `true` -console.log(pattern.test({ hostname: "example.com" })); - -// Prints `true` -console.log(pattern.test({ hostname: "foo.bar.example.com" })); - -// Prints `false` -console.log(pattern.test({ hostname: ".example.com" })); - -const result = pattern.exec({ hostname: "foo.bar.example.com" }); - -// Prints `foo.bar` -console.log(result.hostname.groups.subdomain); -``` - -### Example: Making text optional or repeated without a matching group. - -The following example shows how curly braces can be used to denote text -without a matching group can be made optional or repeated without a -matching group. - -```js -const pattern = new URLPattern({ pathname: "/product{/}?" }); - -// Prints `true` -console.log(pattern.test({ pathname: "/product" })); - -// Prints `true` -console.log(pattern.test({ pathname: "/product/" })); - -const result = pattern.exec({ pathname: "/product/" }); - -// Prints `{}` -console.log(result.pathname.groups); -``` - -### Using Multiple Components and Features at Once - -The following example shows how many features can be combined across multiple -URL components. - -```js -const pattern = new URLPattern({ - protocol: "http{s}?", - username: ":user?", - password: ":pass?", - hostname: "{:subdomain.}*example.com", - pathname: "/product/:action*", -}); - -const result = pattern.exec("http://foo:bar@sub.example.com/product/view?q=12345"); - -// Prints `foo` -console.log(result.username.groups.user); - -// Prints `bar` -console.log(result.password.groups.pass); - -// Prints `sub` -console.log(result.hostname.groups.subdomain); - -// Prints `view` -console.log(result.pathname.groups.action); -``` - -[path-to-regexp]: https://github.com/pillarjs/path-to-regexp diff --git a/tag-security-privacy.md b/tag-security-privacy.md deleted file mode 100644 index a730bb9..0000000 --- a/tag-security-privacy.md +++ /dev/null @@ -1,39 +0,0 @@ -# TAG Security & Privacy Questionnaire Answers # - -* **Author:** wanderview@google.com -* **Questionnaire Source:** https://www.w3.org/TR/security-privacy-questionnaire/#questions - -## Questions ## - -* **What information might this feature expose to Web sites or other parties, and for what purposes is that exposure necessary?** - * None. The proposal relates to matching client URLs that are already exposed to sites. -* **Is this specification exposing the minimum amount of information necessary to power the feature?** - * Yes. It does not expose any new information. -* **How does this specification deal with personal information or personally-identifiable information or information derived thereof?** - * This proposal does not deal with PII. -* **How does this specification deal with sensitive information?** - * No. -* **Does this specification introduce new state for an origin that persists across browsing sessions?** - * No. It allows a pattern to be stored in the existing service worker scope persistent state. Sites could previously store arbitrary data in this field using URL encoding. -* **What information from the underlying platform, e.g. configuration data, is exposed by this specification to an origin?** - * None. -* **Does this specification allow an origin access to sensors on a user’s device** - * No. -* **What data does this specification expose to an origin? Please also document what data is identical to data exposed by other features, in the same or different contexts.** - * None. -* **Does this specification enable new script execution/loading mechanisms?** - * It allows service worker scopes to match more restrictive URL patterns. It also supports matching URL search parameters regardless of order. This allows a service worker to be reliably spawned in cases where it could not before. -* **Does this specification allow an origin to access other devices?** - * No. -* **Does this specification allow an origin some measure of control over a user agent’s native UI?** - * No. -* **What temporary identifiers might this this specification create or expose to the web?** - * None. -* **How does this specification distinguish between behavior in first-party and third-party contexts?** - * Service workers operate differently in first-party and third-party contexts in some browsers; e.g. double-keying, etc. This proposal does not change that behavior or create new differences. -* **How does this specification work in the context of a user agent’s Private \ Browsing or "incognito" mode?** - * Service workers operate differently in private browser modes in some browsers; e.g. firefox does not support SW in private browsing. This proposal does not change that behavior or create new differences. -* **Does this specification have a "Security Considerations" and "Privacy Considerations" section?** - * Yes. -* **Does this specification allow downgrading default security characteristics?** - * No.