API metody fetch

O metodÄ› fetch jsme se už leccos dozvÄ›dÄ›li.

Podívejme se nyní na zbytek API, abychom probrali všechny její možnosti.

Následující seznam obsahuje vÅ¡echny volby fetch spolu s jejich standardními hodnotami (alternativy jsou uvedeny v komentářích):

let příslib = fetch(url, {
  method: "GET", // POST, PUT, DELETE, atd.
  headers: {
    // hodnota hlavičky s typem obsahu se obvykle nastavuje automaticky
    // v závislosti na těle požadavku
    "Content-Type": "text/plain;charset=UTF-8"
  },
  body: undefined, // řetězec, FormData, Blob, BufferSource nebo URLSearchParams
  referrer: "about:client", // nebo "", aby nebyla poslána žádná hlavička Referer,
  // nebo URL z aktuálního původu
  referrerPolicy: "strict-origin-when-cross-origin", // no-referrer-when-downgrade, no-referrer, origin, same-origin...
  mode: "cors", // same-origin, no-cors
  credentials: "same-origin", // omit, include
  cache: "default", // no-store, reload, no-cache, force-cache nebo only-if-cached
  redirect: "follow", // manual, error
  integrity: "", // kontrolní součet, např. "sha256-abcdef1234567890"
  keepalive: false, // true
  signal: undefined, // AbortController pro zastavení požadavku
  window: window // null
});

Úctyhodný seznam, že?

V kapitole Fetch jsme podrobnÄ› probrali method, headers a body.

V kapitole Fetch: zruÅ¡ení stahování jsme probrali volbu signal.

Nyní prozkoumejme ostatní volby.

referrer, referrerPolicy

Tyto volby stanovují způsob, jak fetch nastavuje HTTP hlavičku Referer.

Tato hlavička je obvykle nastavována automaticky a obsahuje URL stránky, která vytvořila požadavek. Ve většině scénářů není vůbec důležitá, ale někdy z bezpečnostních důvodů má smysl ji odstranit nebo zkrátit.

Volba referrer umožňuje nastavit libovolný Referer (v rámci aktuálního původu) nebo jej odstranit.

Nechceme-li poslat žádný referer, nastavíme prázdný řetězec:

fetch('/page', {
  referrer: "" // bez hlavičky Referer
});

Chceme-li nastavit jinou URL uvnitř aktuálního původu:

fetch('/page', {
  // předpokládejme, že jsme na https://javascript.info
  // můžeme nastavit jakoukoli hlavičku Referer, ale jen uvnitř aktuálního původu
  referrer: "https://javascript.info/jinastranka"
});

Volba referrerPolicy nastavuje obecná pravidla pro Referer.

Požadavky se dělí na tři druhy:

1. Požadavky na stejný původ.
2. Požadavky na jiný původ.
3. Požadavky z HTTPS na HTTP (z bezpečného protokolu na méně bezpečný).

Na rozdíl od volby referrer, která umožňuje hodnotu Referer pÅ™esnÄ› nastavit, referrerPolicy sdÄ›luje prohlížeči obecná pravidla pro vÅ¡echny druhy požadavků.

Možné hodnoty jsou popsány ve specifikaci politiky refereru:

• "strict-origin-when-cross-origin" – standardní hodnota: na stejný původ se posílá úplný Referer, na jiný původ se posílá jen původ, pÅ™i požadavku HTTPS→HTTP se neposílá nic.
• "no-referrer-when-downgrade" – vždy se posílá úplný Referer s výjimkou požadavků z HTTPS na HTTP (na ménÄ› bezpečný protokol).
• "no-referrer" – Referer se nikdy neposílá.
• "origin" – v Referer se posílá jen původ a ne celé URL stránky, napÅ™. jen http://site.com místo http://site.com/path.
• "origin-when-cross-origin" – na stejný původ se posílá úplný Referer, ale u požadavků jiného původu jen původ (stejnÄ› jako výše).
• "same-origin" – na stejný původ se posílá úplný Referer, ale u požadavků jiného původu se Referer neposílá.
• "strict-origin" – posílá se jen původ, u požadavků HTTPS→HTTP se Referer neposílá.
• "unsafe-url" – v Referer se vždy posílá celá URL, i u požadavků HTTPS→HTTP.

Následující tabulka obsahuje všechny kombinace:

Řekněme, že máme administrátorskou zónu se strukturou URL, která by neměla být vidět mimo toto sídlo.

Jestliže poÅ¡leme fetch, standardnÄ› poÅ¡le vždy hlavičku Referer s celou URL naší stránky (kromÄ› požadavků z HTTPS na HTTP, které hlavičku Referer nebudou obsahovat).

Například Referer: https://javascript.info/admin/secret/paths.

Pokud bychom chtěli, aby jiná webová sídla znala jen původ a ne celou URL cestu, můžeme nastavit:

fetch('https://another.com/page', {
  // ...
  referrerPolicy: "origin-when-cross-origin" // Referer: https://javascript.info
});

Můžeme to umístit do vÅ¡ech volání fetch nebo tÅ™eba integrovat do JavaScriptové knihovny naÅ¡eho projektu, která provádí vÅ¡echny požadavky, a použít fetch v ní.

Jediný rozdíl oproti standardnímu chování spočívá v tom, že na požadavky jiného původu fetch posílá jen částečnou URL obsahující jen původ (napÅ™. https://javascript.info bez cesty). Pro požadavky na náš původ budeme stále mít úplný Referer (což může být užitečné pro účely ladÄ›ní).

mode

Volba mode je zabezpečení, které brání nechtÄ›ným požadavkům jiného původu:

• "cors" – standardnÄ›, požadavky jiného původu jsou povoleny, jak je popsáno v kapitole Fetch: požadavky jiného původu,
• "same-origin" – požadavky jiného původu jsou zakázány,
• "no-cors" – jsou povoleny jen bezpečné požadavky jiného původu.

Tato volba může být užitečná, když URL pro fetch pochází od tÅ™etí strany a my bychom chtÄ›li „vypínač“, který omezí možnosti posílání požadavků jiného původu.

credentials

Volba credentials specifikuje, zda má fetch v požadavku posílat cookies a hlavičky pro HTTP autorizaci.

• "same-origin" – standardnÄ›, neposílají se v požadavcích jiného původu,
• "include" – vždy se posílají, od serveru jiného původu vyžaduje Access-Control-Allow-Credentials, aby JavaScript mohl pÅ™istupovat k odpovÄ›di, bylo to vysvÄ›tleno v kapitole Fetch: požadavky jiného původu,
• "omit" – nikdy se neposílají, ani v požadavcích stejného původu.

cache

StandardnÄ› požadavky fetch využívání standardní HTTP mezipaměť. To znamená, že respektují hlavičky Expires a Cache-Control, posílají If-Modified-Since a podobnÄ›, stejnÄ› jako běžné HTTP požadavky.

Volba cache umožňuje HTTP mezipaměť ignorovat nebo vyladit její používání:

• "default" – fetch používá standardní pravidla a hlavičky pro HTTP mezipaměť,
• "no-store" – HTTP mezipaměť se zcela ignoruje, tento režim se stane standardním, jestliže nastavíme hlavičku If-Modified-Since, If-None-Match, If-Unmodified-Since, If-Match nebo If-Range,
• "reload" – nepÅ™ebírá výsledek z HTTP mezipamÄ›ti (pokud tam je), ale umístí do mezipamÄ›ti odpověď (pokud hlavičky odpovÄ›di tuto akci povolí),
• "no-cache" – pokud je odpověď v mezipamÄ›ti, vytvoří podmínÄ›ný požadavek, jinak vytvoří běžný požadavek. Umístí odpověď do HTTP mezipamÄ›ti,
• "force-cache" – použije odpověď z HTTP mezipamÄ›ti, i když je stará. Pokud v HTTP mezipamÄ›ti není odpověď, vytvoří běžný HTTP požadavek a chová se jako obvykle,
• "only-if-cached" – použije odpověď z HTTP mezipamÄ›ti, i když je stará. Pokud v HTTP mezipamÄ›ti není odpověď, nastane chyba. Funguje jen tehdy, když je mode nastaven na "same-origin".

redirect

Za normálních okolností fetch průhlednÄ› následuje HTTP pÅ™esmÄ›rování, napÅ™. 301, 302 atd.

Volba redirect to umožňuje zmÄ›nit:

• "follow" – standardní, HTTP pÅ™esmÄ›rování je následováno,
• "error" – v případÄ› HTTP pÅ™esmÄ›rování nastane chyba,
• "manual" – umožňuje zpracovat HTTP pÅ™esmÄ›rování ručnÄ›. V případÄ› pÅ™esmÄ›rování obdržíme speciální objekt odpovÄ›di, který obsahuje odpověď.type="opaqueredirect" a nulový nebo prázdný status a vÄ›tÅ¡inu dalších vlastností.

integrity

Volba integrity umožňuje zkontrolovat, zda odpověď odpovídá pÅ™edem známému kontrolnímu součtu.

Jak je popsáno ve specifikaci, podporované hashovací funkce jsou SHA-256, SHA-384 a SHA-512. V závislosti na prohlížeči mohou být i další.

Například stahujeme soubor a víme, že jeho kontrolní součet SHA-256 je „abcdef“ (skutečný kontrolní součet by samozřejmě byl delší).

Můžeme jej umístit do volby integrity následovnÄ›:

fetch('http://site.com/file', {
  integrity: 'sha256-abcdef'
});

Pak fetch vypočítá SHA-256 sama o sobÄ› a porovná ji s naším Å™etÄ›zcem. V případÄ› neshody nastane chyba.

keepalive

Volba keepalive oznamuje, že požadavek může „pÅ™ežít“ webovou stránku, která jej vyvolala.

Například shromažďujeme statistiku o tom, jak aktuální návštěvník využívá naši stránku (jak kliká myší, které části stránky si zobrazuje), abychom uživatelské zkušenosti analyzovali a vylepšovali.

Když návštěvník naši stránku opustí, chtěli bychom uložit data na server.

Můžeme k tomu využít událost window.onunload:

window.onunload = function() {
  fetch('/analytics', {
    method: 'POST',
    body: "statistics",
    keepalive: true
  });
};

Za normálních okolností, když je dokument odstranÄ›n, vÅ¡echny síťové požadavky k nÄ›mu přísluÅ¡ející jsou zastaveny. AvÅ¡ak volba keepalive říká prohlížeči, aby provedl požadavek v pozadí, i když návÅ¡tÄ›vník opustil stránku. Tato volba je tedy pro úspÄ›ch naÅ¡eho požadavku klíčová.

Má několik omezení:

• Nemůžeme posílat megabyty dat: velikost tÄ›la u požadavků s keepalive je omezena na 64 KB.
  • Pokud potÅ™ebujeme shromažďovat velké množství statistických dat o návÅ¡tÄ›vÄ›, mÄ›li bychom je odesílat pravidelnÄ› v paketech, aby jich na poslední požadavek onunload nezbylo příliÅ¡ mnoho.
  • Tento limit platí pro vÅ¡echny požadavky s keepalive dohromady. Jinými slovy, můžeme provádÄ›t více požadavků s keepalive současnÄ›, ale součet délek jejich tÄ›l by nemÄ›l pÅ™ekročit 64 KB.
• Pokud je dokument odstranÄ›n, nemůžeme zpracovat odpověď serveru. V naÅ¡em příkladu tedy fetch díky keepalive uspÄ›je, ale další funkce již nebudou fungovat.
  • Ve vÄ›tÅ¡inÄ› případů, například pÅ™i odesílání statistik, to není problém, jelikož server jenom pÅ™ijme data a obvykle na takové požadavky odeÅ¡le prázdnou odpověď.