minor

5-network/06-fetch-api/article.md

@@ -3,7 +3,7 @@
 
 So far, we know quite a bit about `fetch`.
 
-Now let's see the rest of API, to cover all its abilities.
+Let's see the rest of API, to cover all its abilities.
 
 Here's the full list of all possible `fetch` options with their default values (alternatives in comments):
 
@@ -11,11 +11,13 @@ Here's the full list of all possible `fetch` options with their default values (
 let promise = fetch(url, {
   method: "GET", // POST, PUT, DELETE, etc.
   headers: {
-    // the content type header value is usually auto-set depending on the request body
+    // the content type header value is usually auto-set
+    // depending on the request body
     "Content-Type": "text/plain;charset=UTF-8"
   },
   body: undefined // string, FormData, Blob, BufferSource, or URLSearchParams
-  referrer: "about:client", // or "" to send no Referer header, or an url from the current origin
+  referrer: "about:client", // or "" to send no Referer header,
+  // or an url from the current origin
   referrerPolicy: "no-referrer-when-downgrade", // no-referrer, origin, same-origin...
   mode: "cors", // same-origin, no-cors
   credentials: "same-origin", // omit, include
@@ -34,15 +36,15 @@ We fully covered `method`, `headers` and `body` in the chapter <info:fetch>.
 
 The `signal` option is covered in <info:fetch-abort>.
 
-Now let's explore the rest of options.
+Now let's explore the rest of capabilities.
 
 ## referrer, referrerPolicy
 
 These options govern how `fetch` sets HTTP `Referer` header.
 
-That header contains the url of the page that made the request. In most scenarios, it plays a very minor informational role, but sometimes, for security purposes, it makes sense to remove or shorten it.
+Usually that header is set automatically and contains the url of the page that made the request. In most scenarios, it's not important at all, sometimes, for security purposes, it makes sense to remove or shorten it.
 
-**The `referrer` option allows to set any `Referer` within the current origin) or disable it.**
+**The `referrer` option allows to set any `Referer` within the current origin) or remove it.**
 
 To send no referer, set an empty string:
 ```js
@@ -67,48 +69,71 @@ fetch('/page', {
 
 **The `referrerPolicy` option sets general rules for `Referer`.**
 
+Requests are split into 3 types:
+
+1. Request to the same origin.
+2. Request to another origin.
+3. Request from HTTPS to HTTP (from safe to unsafe protocol).
+
+Unlike `referrer` option that allows to set the exact `Referer` value, `referrerPolicy` tells the browser general rules for each request type.
+
 Possible values are described in the [Referrer Policy specification](https://w3c.github.io/webappsec-referrer-policy/):
 
-- **`"no-referrer-when-downgrade"`** -- default value: `Referer` is sent always, unless we send a request from HTTPS to HTTP (to less secure protocol).
+- **`"no-referrer-when-downgrade"`** -- the default value: full `Referer` is sent always, unless we send a request from HTTPS to HTTP (to less secure protocol).
 - **`"no-referrer"`** -- never send `Referer`.
-- **`"origin"`** -- only send the origin in `Referer`, not the full page URL, e.g. `http://site.com` instead of `http://site.com/path`.
-- **`"origin-when-cross-origin"`** -- send full `Referer` to the same origin, but only the origin part for cross-origin requests.
+- **`"origin"`** -- only send the origin in `Referer`, not the full page URL, e.g. only `http://site.com` instead of `http://site.com/path`.
+- **`"origin-when-cross-origin"`** -- send full `Referer` to the same origin, but only the origin part for cross-origin requests (as above).
 - **`"same-origin"`** -- send full `Referer` to the same origin, but no referer for for cross-origin requests.
 - **`"strict-origin"`** -- send only origin, don't send `Referer` for HTTPS→HTTP requests.
 - **`"strict-origin-when-cross-origin"`** -- for same-origin send full `Referer`, for cross-origin send only origin, unless it's HTTPS→HTTP request, then send nothing.
-- **`"unsafe-url"`** -- always send full url in `Referer`.
+- **`"unsafe-url"`** -- always send full url in `Referer`, even for HTTPS→HTTP requests.
+
+Here's a table with all combinations:
+
+| Value | To same origin | To another origin | HTTPS→HTTP |
+|-------|----------------|-------------------|------------|
+| `"no-referrer"` | - | - | - |
+| `"no-referrer-when-downgrade"` or `""` (default) | full | full | - |
+| `"origin"` | origin | origin | origin |
+| `"origin-when-cross-origin"` | full | origin | origin |
+| `"same-origin"` | full | - | - |
+| `"strict-origin"` | origin | origin | - |
+| `"strict-origin-when-cross-origin"` | full | origin | - |
+| `"unsafe-url"` | full | full | full |
 
 Let's say we have an admin zone with URL structure that shouldn't be known from outside of the site.
 
-If we send a cross-origin `fetch`, then by default it sends the `Referer` header with the full url of our page (except when we request from HTTPS to HTTP, then no `Referer`).
+If we send a `fetch`, then by default it sends the `Referer` header with the full url of our page (except when we request from HTTPS to HTTP, then no `Referer`).
 
 E.g. `Referer: https://javascript.info/admin/secret/paths`.
 
-If we'd like to totally hide the referrer:
+If we'd like other websites know only the origin part, not URL-path, we can set the option:
 
 ```js
 fetch('https://another.com/page', {
-  referrerPolicy: "no-referrer" // no Referer, same effect as referrer: ""
+  referrerPolicy: "origin-when-cross-origin" // Referer: https://javascript.info
 });
 ```
 
-Otherwise, if we'd like the remote side to see only the domain where the request comes from, but not the full URL, we can send only the "origin" part of it:
+We can put it to all `fetch` calls, maybe integrate into JavaScript library of our project that does all requests and uses `fetch` inside.
 
-```js
-fetch('https://another.com/page', {
-  referrerPolicy: "strict-origin" // Referer: https://javascript.info
-});
+Its only difference compared to the default behavior is that for requests to another origin `fetch` only sends the origin part of the URL. For requests to our origin we still get the full `Referer` (maybe useful for debugging purposes).
+
+```smart header="Referrer policy is not only for `fetch`"
+Referrer policy, described in the [specification](https://w3c.github.io/webappsec-referrer-policy/), is not just for `fetch`, but more global.
+
+In particular, it's possible to set the default policy for the whole page using `Referrer-Policy` HTTP header, or per-link, with `<a rel="noreferrer">`.
 ```
 
 ## mode
 
-The `mode` option serves as a safe-guard that prevents cross-origin requests:
+The `mode` option is a safe-guard that prevents occasional cross-origin requests:
 
 - **`"cors"`** -- the default, cross-origin requests are allowed, as described in <info:fetch-crossorigin>,
 - **`"same-origin"`** -- cross-origin requests are forbidden,
 - **`"no-cors"`** -- only simple cross-origin requests are allowed.
 
-That may be useful in contexts when the fetch url comes from 3rd-party, and we want a "power off switch" to limit cross-origin capabilities.
+This option may be useful when the URL comes from 3rd-party, and we want a "power off switch" to limit cross-origin capabilities.
 
 ## credentials
 
@@ -124,11 +149,11 @@ By default, `fetch` requests make use of standard HTTP-caching. That is, it hono
 
 The `cache` options allows to ignore HTTP-cache or fine-tune its usage:
 
-- **`"default"`** -- `fetch` uses standard HTTP-cache rules and headers;
-- **`"no-store"`** -- totally ignore HTTP-cache, this mode becomes the default if we set a header `If-Modified-Since`, `If-None-Match`, `If-Unmodified-Since`, `If-Match`, or `If-Range`;
-- **`"reload"`** -- don't take the result from HTTP-cache (if any), but populate cache with the response (if response headers allow);
-- **`"no-cache"`** -- create a conditional request if there is a cached response, and a normal request otherwise. Populate HTTP-cache with the response;
-- **`"force-cache"`** -- use a response from HTTP-cache, even if it's stale. If there's no response in HTTP-cache, make a regular HTTP-request, behave normally;
+- **`"default"`** -- `fetch` uses standard HTTP-cache rules and headers,
+- **`"no-store"`** -- totally ignore HTTP-cache, this mode becomes the default if we set a header `If-Modified-Since`, `If-None-Match`, `If-Unmodified-Since`, `If-Match`, or `If-Range`,
+- **`"reload"`** -- don't take the result from HTTP-cache (if any), but populate cache with the response (if response headers allow),
+- **`"no-cache"`** -- create a conditional request if there is a cached response, and a normal request otherwise. Populate HTTP-cache with the response,
+- **`"force-cache"`** -- use a response from HTTP-cache, even if it's stale. If there's no response in HTTP-cache, make a regular HTTP-request, behave normally,
 - **`"only-if-cached"`** -- use a response from HTTP-cache, even if it's stale. If there's no response in HTTP-cache, then error. Only works when `mode` is `"same-origin"`.
 
 ## redirect
@@ -147,13 +172,13 @@ The `integrity` option allows to check if the response matches the known-ahead c
 
 As described in the [specification](https://w3c.github.io/webappsec-subresource-integrity/), supported hash-functions are SHA-256, SHA-384, and SHA-512, there might be others depending on a browser.
 
-For example, we're downloading a file, and we know that it's SHA-256 checksum is "abc" (a real checksum is longer, of course).
+For example, we're downloading a file, and we know that it's SHA-256 checksum is "abcdef" (a real checksum is longer, of course).
 
 We can put it in the `integrity` option, like this:
 
 ```js
 fetch('http://site.com/file', {
-  integrity: 'sha256-abd'
+  integrity: 'sha256-abcdef'
 });
 ```