From 242c0c4af43a1e539ca1a2a64acc7003da855138 Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Sat, 14 Dec 2024 22:24:16 +0100 Subject: [PATCH 1/6] docs(http): service-worker-allowed header --- .../using_service_workers/index.md | 2 +- .../serviceworkercontainer/register/index.md | 30 +++---- files/en-us/web/http/headers/index.md | 5 +- .../headers/service-worker-allowed/index.md | 85 +++++++++++++++++++ .../web/http/headers/service-worker/index.md | 50 +++++++++++ 5 files changed, 155 insertions(+), 17 deletions(-) create mode 100644 files/en-us/web/http/headers/service-worker-allowed/index.md create mode 100644 files/en-us/web/http/headers/service-worker/index.md diff --git a/files/en-us/web/api/service_worker_api/using_service_workers/index.md b/files/en-us/web/api/service_worker_api/using_service_workers/index.md index f0b415186f89ede..ab95b7f49bb8f35 100644 --- a/files/en-us/web/api/service_worker_api/using_service_workers/index.md +++ b/files/en-us/web/api/service_worker_api/using_service_workers/index.md @@ -99,7 +99,7 @@ This could be for the following reasons: - The path to your service worker file is not written correctly — it needs to be written relative to the origin, not your app's root directory. In our example, the worker is at `https://bncb2v.csb.app/sw.js`, and the app's root is `https://bncb2v.csb.app/`. But the path needs to be written as `/sw.js`. - It is also not allowed to point to a service worker of a different origin than that of your app. - The service worker will only catch requests from clients under the service worker's scope. -- The max scope for a service worker is the location of the worker (in other words if the script `sw.js` is located in `/js/sw.js`, it can only control URLs under `/js/` by default). A list of max scopes for that worker can be specified with the `Service-Worker-Allowed` header. +- The max scope for a service worker is the location of the worker (in other words if the script `sw.js` is located in `/js/sw.js`, it can only control URLs under `/js/` by default). A list of max scopes for that worker can be specified with the {{HTTPHeader("Service-Worker-Allowed")}} header. - In Firefox, Service Worker APIs are hidden and cannot be used when the user is in [private browsing mode](https://bugzil.la/1320796), or when history is disabled, or if cookies are cleared when Firefox is closed. - In Chrome, registration fails when the "Block all cookies (not recommended)" option is enabled. diff --git a/files/en-us/web/api/serviceworkercontainer/register/index.md b/files/en-us/web/api/serviceworkercontainer/register/index.md index 49c455f33c52024..51d7be0470e6d11 100644 --- a/files/en-us/web/api/serviceworkercontainer/register/index.md +++ b/files/en-us/web/api/serviceworkercontainer/register/index.md @@ -45,11 +45,11 @@ register(scriptURL, options) - : A string representing a URL that defines a service worker's registration scope; that is, what range of URLs a service worker can control. This is usually specified as a URL that is relative to the base URL of the site (e.g. `/some/path/`), so that the resolved scope is the same irrespective of what page the registration code is called from. - By default, the `scope` value for a service worker registration is set to the directory where the service worker script is located (by resolving `./` against `scriptURL`). + The default `scope` for a service worker registration is the directory where the service worker script is located (resolving `./` against `scriptURL`). - The scope must specify documents that are in the same directory or more deeply nested than the service worker (if you need a broader scope, this can be permitted via the HTTP `Service-Worker-Allowed` header). - - See the [Examples](#examples) section for more information on how it works. + The scope should be used to specify documents that are in the same directory or more deeply nested than the service worker. + If you need a broader scope, this can be permitted via the HTTP {{HTTPHeader("Service-Worker-Allowed")}} header. + See the [Examples](#examples) section for information on broadening the default scope of a service worker. - `type` @@ -95,11 +95,11 @@ A {{jsxref("Promise")}} that resolves with a {{domxref("ServiceWorkerRegistratio ## Examples -The examples described here should be taken together to get a better understanding of how service workers scope applies to a page. +The examples below should be read together to understand how service worker scope applies to a page. ### Register a service worker with default scope -The following example uses the default value of `scope` (by omitting it), which sets it to be the same location as the script URL. +The following example uses the default value of `scope` by omitting it, which sets it to be the same location as the script URL. Suppose the service worker code is at `example.com/sw.js`, and the registration code at `example.com/index.html`. The service worker code will control `example.com/index.html`, as well as pages underneath it, like `example.com/product/description.html`. @@ -121,13 +121,13 @@ if ("serviceWorker" in navigator) { } ``` -Note that we have registered the scriptURL relative to the site root rather than the current page. +Note that we have registered the `scriptURL` relative to the site root rather than the current page. This allows the same registration code to be used from any page. ### Register a service worker with an explicit default scope The code below is almost identical, except we have specified the scope explicitly using `{ scope: "/" }`. -Again, we've specified the scope as site-relative so the same registration code can be used from anywhere in the site. +We've specified the scope as site-relative so the same registration code can be used from anywhere in the site. ```js if ("serviceWorker" in navigator) { @@ -145,7 +145,7 @@ if ("serviceWorker" in navigator) { } ``` -This scope happens to be the same as the default scope, so the registration applies to exactly the same pages as the example above. +This scope is the same as the default scope, so the registration applies to exactly the same pages as the previous example. Note that if we were to run this code after the previous example, browsers should recognize that we're updating an existing registration rather than a new one. ### Register a service worker using page-relative URLs @@ -153,7 +153,7 @@ Note that if we were to run this code after the previous example, browsers shoul There is nothing to stop you from using page-relative URLs except that this makes it harder to move your pages around, and it is easy to accidentally create unwanted registrations if you do so. In this example the service worker code is at `example.com/product/sw.js`, and the registration code at `example.com/product/description.html`. -We're using URLs that are relative to the current directory for the scriptURL and the scope, where the current directory is the base URL of the page that is calling `register()` (`example.com/product/`). +We're using URLs that are relative to the current directory for the `scriptURL` and the `scope`, where the current directory is the base URL of the page that is calling `register()` (`example.com/product/`). The service worker applies to resources under `example.com/product/`. ```js @@ -174,9 +174,8 @@ if ("serviceWorker" in navigator) { ### Using Service-Worker-Allowed to increase service worker scope -There is frequent confusion surrounding the meaning and use of _scope_. -A service worker can't have a scope broader than its own location, unless the server specifies a broader maximum scope in a [Service-Worker-Allowed](https://w3c.github.io/ServiceWorker/#service-worker-allowed) header on the service worker script. -Therefore you should use the `scope` option when you need a _narrower_ scope than the default. +A service worker can't have a scope broader than its own location, unless the server specifies a broader maximum scope in a {{HTTPHeader("Service-Worker-Allowed")}} header on the service worker script. +It's appropriate to use the `scope` option when you need a _narrower_ scope than the default. The following code, if included in `example.com/index.html`, at the root of a site, would only apply to resources under `example.com/product`. @@ -196,8 +195,8 @@ if ("serviceWorker" in navigator) { } ``` -As noted above, servers can change the default maximum scope by setting the `Service-Worker-Allowed` header on the service worker script. -In this case, the `scope` option should specify a scope narrower than the header value, but potentially larger than the service worker's location. +Servers can change the default maximum scope by setting the `Service-Worker-Allowed` header on the service worker script. +In this case, the `scope` option can be narrower than the header value, but potentially larger than the service worker's location. The following code, if included in `example.com/product/index.html`, would apply to all resources under `example.com` if the server set the `Service-Worker-Allowed` header to `/` or `https://example.com/` when serving `sw.js`. If the server doesn't set the header, the service worker registration will fail, as the requested `scope` is too broad. @@ -233,3 +232,4 @@ if ("serviceWorker" in navigator) { - [ServiceWorkerRegistration: `unregister()` method](/en-US/docs/Web/API/ServiceWorkerRegistration/unregister) - [Service worker API](/en-US/docs/Web/API/Service_Worker_API) - [Using service workers](/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers) +- {{HTTPHeader("Service-Worker-Allowed")}} HTTP header diff --git a/files/en-us/web/http/headers/index.md b/files/en-us/web/http/headers/index.md index 11836286c14011c..b69f5ce5ab3c9ae 100644 --- a/files/en-us/web/http/headers/index.md +++ b/files/en-us/web/http/headers/index.md @@ -316,7 +316,10 @@ Headers used by the [WebSockets API](/en-US/docs/Web/API/WebSockets_API) in the - : Indicates how long the user agent should wait before making a follow-up request. - {{HTTPHeader("Server-Timing")}} - : Communicates one or more metrics and descriptions for the given request-response cycle. -- `Service-Worker-Allowed` +- {{HTTPHeader("Service-Worker")}} + - : Included in fetches for a service worker's script resource. + This header helps administrators log service worker script requests for monitoring purposes. +- {{HTTPHeader("Service-Worker-Allowed")}} - : Used to remove the [path restriction](/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers#why_is_my_service_worker_failing_to_register) by including this header [in the response of the Service Worker script](https://w3c.github.io/ServiceWorker/#service-worker-script-response). - {{HTTPHeader("SourceMap")}} - : Links to a {{Glossary("source map")}} so that debuggers can step through original source code instead of generated or transformed code. diff --git a/files/en-us/web/http/headers/service-worker-allowed/index.md b/files/en-us/web/http/headers/service-worker-allowed/index.md new file mode 100644 index 000000000000000..7cab74c09bef563 --- /dev/null +++ b/files/en-us/web/http/headers/service-worker-allowed/index.md @@ -0,0 +1,85 @@ +--- +title: Service-Worker-Allowed +slug: Web/HTTP/Headers/Service-Worker-Allowed +page-type: http-header +browser-compat: http.headers.Service-Worker-Allowed +spec-urls: https://w3c.github.io/ServiceWorker/#service-worker-allowed +--- + +{{HTTPSidebar}} + +The HTTP **`Service-Worker-Allowed`** {{Glossary("response header")}} is used to broaden the path restriction for a service worker's default `scope`. + +By default, the [`scope`](/en-US/docs/Web/API/ServiceWorkerContainer/register#scope) for a service worker registration is the directory where the service worker script is located. +For example, if the script `sw.js` is located in `/js/sw.js`, it can only control URLs under `/js/` by default. +Servers can change the default maximum scope by setting the `Service-Worker-Allowed` header if a service worker needs to control a broader range of URLs beyond its own directory. + +/en-US/docs/Web/API/ServiceWorkerContainer + +A service worker intercepts all network requests within its scope so you should avoid using overly broad scopes unless necessary. + + + + + + + + + + + + +
Header type{{Glossary("Response header")}}
{{Glossary("Forbidden header name")}}No
+ +## Syntax + +```http +Service-Worker-Allowed: +``` + +## Directives + +- `` + - : A string representing a URL that defines a service worker's registration scope; that is, what range of URLs a service worker can control. + +## Examples + +### Using Service-Worker-Allowed to increase service worker scope + +In the following example, an HTTP response to a service worker's script resource request includes the `Service-Worker-Allowed` header set to `/`: + +```http +200 OK +Service-Worker-Allowed: / +``` + +If included in `example.com/product/index.html`, the following code would apply to all resources under `example.com/` when serving `sw.js`. +If the server doesn't set the header, the service worker registration will fail, as the `scope` option (`{ scope: "/" }`) is too broad: + +```js +navigator.serviceWorker.register("./sw.js", { scope: "/" }).then( + (registration) => { + console.log( + "Install succeeded, max allowed scope was overriden to '/'", + registration, + ); + }, + (error) => { + console.error(`Service worker registration failed: ${error}`); + }, +); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Service worker API](/en-US/docs/Web/API/Service_Worker_API) +- [Using service workers](/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers) +- {{domxref("ServiceWorkerRegistration")}} diff --git a/files/en-us/web/http/headers/service-worker/index.md b/files/en-us/web/http/headers/service-worker/index.md new file mode 100644 index 000000000000000..e25ecce1d4513d0 --- /dev/null +++ b/files/en-us/web/http/headers/service-worker/index.md @@ -0,0 +1,50 @@ +--- +title: Service-Worker +slug: Web/HTTP/Headers/Service-Worker +page-type: http-header +browser-compat: http.headers.Service-Worker +spec-urls: https://www.w3.org/TR/service-workers/#service-worker +--- + +{{HTTPSidebar}} + +The HTTP **`Service-Worker`** {{Glossary("request header")}} is included in fetches for a service worker's script resource. +This header helps administrators log service worker script requests for monitoring purposes. + + + + + + + + + + + + +
Header type{{Glossary("Request header")}}
{{Glossary("Forbidden header name")}}No
+ +## Syntax + +```http +Service-Worker: script +``` + +## Directives + +- `script` + - : The only specified value this header may have. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Service worker API](/en-US/docs/Web/API/Service_Worker_API) +- [Using service workers](/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers) +- {{domxref("ServiceWorkerRegistration")}} From afbe053fd3c7657668d11c7242c30d671106cb1f Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Mon, 16 Dec 2024 15:54:03 +0100 Subject: [PATCH 2/6] feat(http): Add pages for Service Workers --- .../using_service_workers/index.md | 1 + .../headers/service-worker-allowed/index.md | 38 +++++++++---------- .../web/http/headers/service-worker/index.md | 4 +- 3 files changed, 20 insertions(+), 23 deletions(-) diff --git a/files/en-us/web/api/service_worker_api/using_service_workers/index.md b/files/en-us/web/api/service_worker_api/using_service_workers/index.md index ab95b7f49bb8f35..987faa8e641aa3b 100644 --- a/files/en-us/web/api/service_worker_api/using_service_workers/index.md +++ b/files/en-us/web/api/service_worker_api/using_service_workers/index.md @@ -452,3 +452,4 @@ self.addEventListener("activate", (event) => { - [Promises](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) - [Using web workers](/en-US/docs/Web/API/Web_Workers_API/Using_web_workers) +- {{HTTPHeader("Service-Worker-Allowed")}} HTTP header diff --git a/files/en-us/web/http/headers/service-worker-allowed/index.md b/files/en-us/web/http/headers/service-worker-allowed/index.md index 7cab74c09bef563..11f5cccf16b1d84 100644 --- a/files/en-us/web/http/headers/service-worker-allowed/index.md +++ b/files/en-us/web/http/headers/service-worker-allowed/index.md @@ -3,7 +3,6 @@ title: Service-Worker-Allowed slug: Web/HTTP/Headers/Service-Worker-Allowed page-type: http-header browser-compat: http.headers.Service-Worker-Allowed -spec-urls: https://w3c.github.io/ServiceWorker/#service-worker-allowed --- {{HTTPSidebar}} @@ -12,11 +11,9 @@ The HTTP **`Service-Worker-Allowed`** {{Glossary("response header")}} is used to By default, the [`scope`](/en-US/docs/Web/API/ServiceWorkerContainer/register#scope) for a service worker registration is the directory where the service worker script is located. For example, if the script `sw.js` is located in `/js/sw.js`, it can only control URLs under `/js/` by default. -Servers can change the default maximum scope by setting the `Service-Worker-Allowed` header if a service worker needs to control a broader range of URLs beyond its own directory. +Servers can change the default maximum allowed scope by setting the `Service-Worker-Allowed` header if a service worker needs to control a broader range of URLs beyond its own directory. -/en-US/docs/Web/API/ServiceWorkerContainer - -A service worker intercepts all network requests within its scope so you should avoid using overly broad scopes unless necessary. +A service worker intercepts all network requests within its scope so you should avoid using overly-broad scopes unless necessary. @@ -44,25 +41,14 @@ Service-Worker-Allowed: ## Examples -### Using Service-Worker-Allowed to increase service worker scope +### Using Service-Worker-Allowed to broaden service worker scope -In the following example, an HTTP response to a service worker's script resource request includes the `Service-Worker-Allowed` header set to `/`: - -```http -200 OK -Service-Worker-Allowed: / -``` - -If included in `example.com/product/index.html`, the following code would apply to all resources under `example.com/` when serving `sw.js`. -If the server doesn't set the header, the service worker registration will fail, as the `scope` option (`{ scope: "/" }`) is too broad: +The JavaScript example below is included in `example.com/product/index.html`, and attempts to register a service worker with a scope that applies to all resources under `example.com/`. ```js navigator.serviceWorker.register("./sw.js", { scope: "/" }).then( (registration) => { - console.log( - "Install succeeded, max allowed scope was overriden to '/'", - registration, - ); + console.log("Install succeeded, scoped to '/'", registration); }, (error) => { console.error(`Service worker registration failed: ${error}`); @@ -70,6 +56,18 @@ navigator.serviceWorker.register("./sw.js", { scope: "/" }).then( ); ``` +The HTTP response to the service worker's script resource request (`./sw.js`) includes the `Service-Worker-Allowed` header set to `/`: + +```http +HTTP/1.1 200 OK +Date: Mon, 16 Dec 2024 14:37:20 GMT +Service-Worker-Allowed: / + +// sw.js contents… +``` + +If the server doesn't set the header, the service worker registration will fail, as the `scope` option (`{ scope: "/" }`) requests a scope broader than the directory where the service worker script is located (`/product/sw.js`). + ## Specifications {{Specifications}} @@ -80,6 +78,6 @@ navigator.serviceWorker.register("./sw.js", { scope: "/" }).then( ## See also +- {{HTTPHeader("Service-Worker")}} header - [Service worker API](/en-US/docs/Web/API/Service_Worker_API) -- [Using service workers](/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers) - {{domxref("ServiceWorkerRegistration")}} diff --git a/files/en-us/web/http/headers/service-worker/index.md b/files/en-us/web/http/headers/service-worker/index.md index e25ecce1d4513d0..d2a70f286d29696 100644 --- a/files/en-us/web/http/headers/service-worker/index.md +++ b/files/en-us/web/http/headers/service-worker/index.md @@ -3,7 +3,6 @@ title: Service-Worker slug: Web/HTTP/Headers/Service-Worker page-type: http-header browser-compat: http.headers.Service-Worker -spec-urls: https://www.w3.org/TR/service-workers/#service-worker --- {{HTTPSidebar}} @@ -45,6 +44,5 @@ Service-Worker: script ## See also +- {{HTTPHeader("Service-Worker-Allowed")}} header - [Service worker API](/en-US/docs/Web/API/Service_Worker_API) -- [Using service workers](/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers) -- {{domxref("ServiceWorkerRegistration")}} From a670baf3997514287ab7db4cd48e89234c33532e Mon Sep 17 00:00:00 2001 From: Brian Smith Date: Tue, 17 Dec 2024 13:33:11 +0100 Subject: [PATCH 3/6] Apply suggestions from code review Co-authored-by: Hamish Willee --- .../en-us/web/api/serviceworkercontainer/register/index.md | 6 +++--- .../en-us/web/http/headers/service-worker-allowed/index.md | 7 ++++--- files/en-us/web/http/headers/service-worker/index.md | 3 ++- 3 files changed, 9 insertions(+), 7 deletions(-) diff --git a/files/en-us/web/api/serviceworkercontainer/register/index.md b/files/en-us/web/api/serviceworkercontainer/register/index.md index 51d7be0470e6d11..0ef949a2c14d9b7 100644 --- a/files/en-us/web/api/serviceworkercontainer/register/index.md +++ b/files/en-us/web/api/serviceworkercontainer/register/index.md @@ -175,7 +175,7 @@ if ("serviceWorker" in navigator) { ### Using Service-Worker-Allowed to increase service worker scope A service worker can't have a scope broader than its own location, unless the server specifies a broader maximum scope in a {{HTTPHeader("Service-Worker-Allowed")}} header on the service worker script. -It's appropriate to use the `scope` option when you need a _narrower_ scope than the default. +Use the `scope` option when you need a _narrower_ scope than the default. The following code, if included in `example.com/index.html`, at the root of a site, would only apply to resources under `example.com/product`. @@ -195,8 +195,8 @@ if ("serviceWorker" in navigator) { } ``` -Servers can change the default maximum scope by setting the `Service-Worker-Allowed` header on the service worker script. -In this case, the `scope` option can be narrower than the header value, but potentially larger than the service worker's location. +As noted above, servers can change the default scope by setting the `Service-Worker-Allowed` header on the service worker script. +This allows the `scope` option to be set outside the path defined by the service worker's location. The following code, if included in `example.com/product/index.html`, would apply to all resources under `example.com` if the server set the `Service-Worker-Allowed` header to `/` or `https://example.com/` when serving `sw.js`. If the server doesn't set the header, the service worker registration will fail, as the requested `scope` is too broad. diff --git a/files/en-us/web/http/headers/service-worker-allowed/index.md b/files/en-us/web/http/headers/service-worker-allowed/index.md index 11f5cccf16b1d84..322917800a37ce2 100644 --- a/files/en-us/web/http/headers/service-worker-allowed/index.md +++ b/files/en-us/web/http/headers/service-worker-allowed/index.md @@ -11,9 +11,9 @@ The HTTP **`Service-Worker-Allowed`** {{Glossary("response header")}} is used to By default, the [`scope`](/en-US/docs/Web/API/ServiceWorkerContainer/register#scope) for a service worker registration is the directory where the service worker script is located. For example, if the script `sw.js` is located in `/js/sw.js`, it can only control URLs under `/js/` by default. -Servers can change the default maximum allowed scope by setting the `Service-Worker-Allowed` header if a service worker needs to control a broader range of URLs beyond its own directory. +Servers can use the `Service-Worker-Allowed` header to allow a service worker to control URLs outside of its own directory. -A service worker intercepts all network requests within its scope so you should avoid using overly-broad scopes unless necessary. +A service worker intercepts all network requests within its scope, so you should avoid using overly-broad scopes unless necessary.
@@ -43,7 +43,7 @@ Service-Worker-Allowed: ### Using Service-Worker-Allowed to broaden service worker scope -The JavaScript example below is included in `example.com/product/index.html`, and attempts to register a service worker with a scope that applies to all resources under `example.com/`. +The JavaScript example below is included in `example.com/product/index.html`, and attempts to [register](/en-US/docs/Web/API/ServiceWorkerContainer/register) a service worker with a scope that applies to all resources under `example.com/`. ```js navigator.serviceWorker.register("./sw.js", { scope: "/" }).then( @@ -81,3 +81,4 @@ If the server doesn't set the header, the service worker registration will fail, - {{HTTPHeader("Service-Worker")}} header - [Service worker API](/en-US/docs/Web/API/Service_Worker_API) - {{domxref("ServiceWorkerRegistration")}} +- [Why is my service worker failing to register](/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers#why_is_my_service_worker_failing_to_register) in _Using Service Workers_. diff --git a/files/en-us/web/http/headers/service-worker/index.md b/files/en-us/web/http/headers/service-worker/index.md index d2a70f286d29696..fd255adb0812604 100644 --- a/files/en-us/web/http/headers/service-worker/index.md +++ b/files/en-us/web/http/headers/service-worker/index.md @@ -32,7 +32,8 @@ Service-Worker: script ## Directives - `script` - - : The only specified value this header may have. + - : A value indicating that this is a script. + This is the only allowed directive for this header. ## Specifications From dcf7f8c0a368b63002cc995d661bc6c8d58a70a8 Mon Sep 17 00:00:00 2001 From: Brian Smith Date: Tue, 17 Dec 2024 13:38:11 +0100 Subject: [PATCH 4/6] Update files/en-us/web/http/headers/service-worker/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- files/en-us/web/http/headers/service-worker/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/http/headers/service-worker/index.md b/files/en-us/web/http/headers/service-worker/index.md index fd255adb0812604..b003a7bc97ed4d3 100644 --- a/files/en-us/web/http/headers/service-worker/index.md +++ b/files/en-us/web/http/headers/service-worker/index.md @@ -32,7 +32,7 @@ Service-Worker: script ## Directives - `script` - - : A value indicating that this is a script. + - : A value indicating that this is a script. This is the only allowed directive for this header. ## Specifications From f6de952ce2de0fcb657e5f0124274b79de12c157 Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Thu, 19 Dec 2024 18:50:15 +0100 Subject: [PATCH 5/6] chore(http): reword common pitfalls for service worker registration failures --- .../using_service_workers/index.md | 22 +++++++++++-------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/files/en-us/web/api/service_worker_api/using_service_workers/index.md b/files/en-us/web/api/service_worker_api/using_service_workers/index.md index 987faa8e641aa3b..08c7ae30c56b3c0 100644 --- a/files/en-us/web/api/service_worker_api/using_service_workers/index.md +++ b/files/en-us/web/api/service_worker_api/using_service_workers/index.md @@ -93,15 +93,19 @@ A single service worker can control many pages. Each time a page within your sco #### Why is my service worker failing to register? -This could be for the following reasons: - -- You are not running your application through HTTPS. -- The path to your service worker file is not written correctly — it needs to be written relative to the origin, not your app's root directory. In our example, the worker is at `https://bncb2v.csb.app/sw.js`, and the app's root is `https://bncb2v.csb.app/`. But the path needs to be written as `/sw.js`. -- It is also not allowed to point to a service worker of a different origin than that of your app. -- The service worker will only catch requests from clients under the service worker's scope. -- The max scope for a service worker is the location of the worker (in other words if the script `sw.js` is located in `/js/sw.js`, it can only control URLs under `/js/` by default). A list of max scopes for that worker can be specified with the {{HTTPHeader("Service-Worker-Allowed")}} header. -- In Firefox, Service Worker APIs are hidden and cannot be used when the user is in [private browsing mode](https://bugzil.la/1320796), or when history is disabled, or if cookies are cleared when Firefox is closed. -- In Chrome, registration fails when the "Block all cookies (not recommended)" option is enabled. +A service worker fails to register for one of the following reasons: + +- You are not running your application in a [secure context](/en-US/docs/Web/Security/Secure_Contexts) (over HTTPS). +- The path of the service worker file is incorrect. + The path must be relative to the origin, not an app's root directory. + In our example, the worker is at `https://bncb2v.csb.app/sw.js`, and the app's root is `https://bncb2v.csb.app/`, so the service worker must be `/sw.js`. +- The path to your service worker points to a service worker of a different origin to your app. +- The service worker registration contained a `scope` option broader than permitted. + The maximum scope for a service worker is the directory where the worker is located. + In other words, if the script `sw.js` is located in `/js/sw.js`, it can only control URLs under `/js/` by default. + The maximum scope for a service worker can be broadened with the {{HTTPHeader("Service-Worker-Allowed")}} header. +- Browser-specific settings are enabled, such as blocking all cookies, private browsing mode, automatic cookie deletion on close, etc. + See [serviceWorker.register() browser compatibility](/en-US/docs/Web/API/ServiceWorkerContainer/register#browser_compatibility) for more information. ### Install and activate: populating your cache From 43f8498294ac2b3589572c473e8232b696fe65c7 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Fri, 20 Dec 2024 10:04:47 +1100 Subject: [PATCH 6/6] Apply suggestions from code review --- .../using_service_workers/index.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/files/en-us/web/api/service_worker_api/using_service_workers/index.md b/files/en-us/web/api/service_worker_api/using_service_workers/index.md index 08c7ae30c56b3c0..8ab2b736c3eb208 100644 --- a/files/en-us/web/api/service_worker_api/using_service_workers/index.md +++ b/files/en-us/web/api/service_worker_api/using_service_workers/index.md @@ -98,14 +98,14 @@ A service worker fails to register for one of the following reasons: - You are not running your application in a [secure context](/en-US/docs/Web/Security/Secure_Contexts) (over HTTPS). - The path of the service worker file is incorrect. The path must be relative to the origin, not an app's root directory. - In our example, the worker is at `https://bncb2v.csb.app/sw.js`, and the app's root is `https://bncb2v.csb.app/`, so the service worker must be `/sw.js`. + In our example, the worker is at `https://bncb2v.csb.app/sw.js`, and the app's root is `https://bncb2v.csb.app/`, so the service worker must be specified as `/sw.js`. - The path to your service worker points to a service worker of a different origin to your app. -- The service worker registration contained a `scope` option broader than permitted. - The maximum scope for a service worker is the directory where the worker is located. - In other words, if the script `sw.js` is located in `/js/sw.js`, it can only control URLs under `/js/` by default. - The maximum scope for a service worker can be broadened with the {{HTTPHeader("Service-Worker-Allowed")}} header. +- The service worker registration contains a `scope` option broader than permitted by the worker path. + The default scope for a service worker is the directory where the worker is located. + In other words, if the script `sw.js` is located in `/js/sw.js`, it can only control URLs in (or nested within) the `/js/` path by default. + The scope for a service worker can be broadened (or narrowed) with the {{HTTPHeader("Service-Worker-Allowed")}} header. - Browser-specific settings are enabled, such as blocking all cookies, private browsing mode, automatic cookie deletion on close, etc. - See [serviceWorker.register() browser compatibility](/en-US/docs/Web/API/ServiceWorkerContainer/register#browser_compatibility) for more information. + See [`serviceWorker.register()` browser compatibility](/en-US/docs/Web/API/ServiceWorkerContainer/register#browser_compatibility) for more information. ### Install and activate: populating your cache