Версия документа от 07 ноября 2021 года. Может измениться в будущем.
Входными данными для выборки является запрос (request).
С запросом связан метод (method). Если не указано иное, это `GET`.
Это может быть обновлено во время перенаправления на `GET`, как описано в HTTP-выборке.
Реализациям рекомендуется делать это указателем на первый URL в списке URL-адресов запроса. Он предоставляется как отдельное поле исключительно для удобства подключения других стандартов к Fetch.
С запросом связан флаг только локальных URL (local-URLs-only flag). Если не указано иное, он не установлен.
С запросом связан список заголовков (header list). Если не указано иное, он пуст.
С запросом связан флаг небезопасного запроса (unsafe-request flag). Если не указано иное, он не установлен.
Флаг небезопасного запроса устанавливается такими API, как fetch() и XMLHttpRequest, чтобы гарантировать, что предварительная выборка CORS выполняется на основе предоставленного метода и списка заголовков. Это не освобождает API от запрещения запрещенных методов и запрещенных имен заголовков.
У запроса есть связанное тело (body — null, последовательность байтов или тело). Если не указано иное, он является null.
Последовательность байтов будет безопасно извлечена в тело на ранней стадии выборки. Как часть HTTP-выборки, это поле может быть установлено на null из-за определенных перенаправлений.
С запросом связан Клиент (client — null или объект настроек среды).
С запросом связан Зарезервированный клиент (reserved client — null, среда или объект настроек среды). Если не указано иное, он является null.
Это используется только для запросов навигации и рабочих запросов, но не для запросов рабочих служб. Он ссылается на среду для запроса навигации и объект параметров среды для рабочего запроса.
С запросом связан идентификатор клиента замены (replaces client id — строка). Если не указано иное, это пустая строка.
Это используется только запросами навигации. Это идентификатор объекта настроек среды активного документа целевого контекста просмотра.
С запросом связано Окно (window) («no-window«, «client» или объект настроек среды, глобальный объект которого является объектом Window). Если не указано иное, это «client«.
Значение «client» изменяется на «no-window» или клиент запроса во время выборки. Это удобный способ избавить стандарты от необходимости явно указывать окно запроса.
С запросом связан флаг поддержки активности (keepalive flag). Если не указано иное, он является false.
Это можно использовать, чтобы разрешить запросу переживать объект настроек среды, например, navigator.sendBeacon и элемент HTML img устанавливают этот флаг. Запросы с этим установленным флагом подлежат дополнительной обработке.
Запрос имеет связанный с ним Режим Работников Службы (service-workers mode), то есть «all» или «none«. Если не указано иное, это «all«.
Это определяет, какие работники службы получат событие «fetch» для этой выборки.
«all«
Соответствующие работники службы получат событие «fetch» для этой выборки.
«none«
Никакие работники службы не получат событий для этой выборки.
С запросом связан Инициатор (initiator), который представляет собой пустую строку, «download«, «imageset«, «manifest«, «prefetch«, «prerender» или «xslt«. Если не указано иное, это пустая строка.
Инициатор запроса на данный момент не отличается особой детальностью, поскольку этого не требуют другие спецификации. Это в первую очередь устройство спецификации, помогающее определять CSP и смешанный контент. Он не доступен для JavaScript. [CSP] [MIX]
С запросом связано Назначение (destination), которое представляет собой пустую строку, «audio«, «audioworklet«, «document«, «embed«, «font«, «frame«, «iframe«, «image«, «manifest«, «object«, «paintworklet«, «report«, «script«, «serviceworker«, «sharedworker«, «style«, «track«, «video«, «worker» или «xslt«. Если не указано иное, это пустая строка.
Пункт назначения запроса Похож на сценарий (script-like), если это «audioworklet«, «paintworklet«, «script«, «serviceworker«, «sharedworker«, или «worker«.
Предупреждение!!! Алгоритмы, использующие подобные сценариям, также должны учитывать «xslt«, поскольку это тоже может вызвать выполнение сценария. Он не включен в список, поскольку не всегда актуален и может требовать другого поведения.
Примечание
В следующей таблице показана взаимосвязь между инициатором запроса, местом назначения, директивами CSP и функциями. Он не является исчерпывающим в отношении функций. Функции должны иметь соответствующие значения, определенные в соответствующих стандартах.
Инициатор (Initiator) | Место назначения (Destination) | CSP директива | Характеристики |
---|---|---|---|
«» | «report« | — | CSP, NEL отчёты |
«document« | — | Алгоритм навигации HTML (только на верхнем уровне) | |
«frame« | child-src | HTML элемент <frame> | |
«iframe« | child-src | HTML элемент <iframe> | |
«» | connect-src | navigator.sendBeacon(),
EventSource, HTML элемент <a ping=»»> и <area ping=»»>, fetch(), XMLHttpRequest, WebSocket, Cache API |
|
«object« | object-src | HTML элемент <object> | |
«embed« | object-src | HTML элемент <embed> | |
«audio« | media-src | HTML элемент <audio> | |
«font« | font-src | CSS медиа-запрос @font-face | |
«image« | img-src | HTML элемент <img src>,
/favicon.ico ресурс, SVG’s <image>, CSS свойство background-image, CSS свойство cursor, CSS свойство list-style-image, … |
|
«audioworklet« | script-src | audioWorklet.addModule() | |
«paintworklet« | script-src | CSS.paintWorklet.addModule() | |
«script« | script-src | HTML элемент <script>,
метод importScripts() |
|
«serviceworker« | child-src, script-src, worker-src | navigator.serviceWorker.register() | |
«sharedworker« | child-src, script-src, worker-src | SharedWorker | |
«worker« | child-src, script-src, worker-src | Worker | |
«style« | style-src | HTML элемент <link rel=stylesheet>,
CSS медиа-запрос @import |
|
«track« | media-src | HTML элемент <track> | |
«video« | media-src | HTML элемент <video> | |
«download» | «» | — | HTML’s download=»», «Сохранить ссылку как…» UI-пользовательский интерфейс |
«imageset» | «image« | img-src | HTML элемент <img srcset> и <picture> |
«manifest» | «manifest« | manifest-src | HTML элемент <link rel=manifest> |
«prefetch» | «» | prefetch-src | HTML элемент <link rel=prefetch> |
«prerender» | «» | prefetch-src | HTML элемент <link rel=prerender> |
«xslt» | «xslt« | script-src | <?xml-stylesheet> |
CSP «form-action» должно быть перехватчиком непосредственно в алгоритме навигации HTML или отправки формы.
CSP также потребуется проверить контексты просмотра предков контекста просмотра глобального объекта клиента запроса на наличие различных директив CSP.
Запрос имеет связанный Приоритет (priority — null или объект, определенный пользовательским агентом). Если не указано иное, он имеет значение null.
С запросом связан Источник (origin), которым является «client» или источник. Если не указано иное, это «client«.
«client» изменяется на источник во время выборки. Это позволяет стандартам не указывать источник запроса.
С запросом связан Контейнер Политики (policy container), который является «client» или контейнером политики. Если не указано иное, это «client«.
«client» заменяется контейнером политики во время выборки. Это удобный способ избавить стандарты от необходимости устанавливать контейнер политики запроса.
С запросом связан Рефёрер — Источник перехода (referrer), который является «no-referrer«, «client» или URL. Если не указано иное, это «client«.
«client» заменяется на «no-referrer» или URL-адрес во время выборки. Это позволяет стандартам не указывать источник перехода для запроса.
С запросом связана Политика рефёрера (referrer policy), которая является политикой источника перехода. Если не указано иное, это пустая строка. [Referrer]
Это можно использовать для переопределения политики рефёрера, которая будет использоваться для этого запроса.
ЭТО УДАЛЕНО!!! С запросом связан Синхронный Флаг (synchronous flag). Если не указано иное, он не установлен.
С запросом связан Режим (mode): «same-origin«, «cors«, «no-cors«, «navigate«, или «websocket«. Если не указано иное, это «no-cors«.
«same-origin«
Используется для обеспечения того, чтобы запросы делались на URL-адреса того же происхождения. Fetch вернет сетевую ошибку, если запрос не направлен на URL-адрес того же происхождения.
«cors«
Для запросов, чье повреждение ответа установлено на «cors«, делает запрос CORS-запрос — в этом случае fetch вернет сетевую ошибку, если запрошенный ресурс не понимает протокол CORS или если запрошенный ресурс преднамеренно не участвуют в протоколе CORS.
«no-cors«
Запрещает запросы к использованию методов из списка надежных CORS и заголовков запросов из списка надежных CORS. В случае успеха выборка вернет непрозрачный фильтрованный ответ.
«navigate«
Это специальный режим, используемый только при переходе между документами.
«websocket«
Это специальный режим, используемый только при установке соединения WebSocket.
Несмотря на то, что режим запроса по умолчанию — «no-cors«, стандарты настоятельно не рекомендуют использовать его для новых функций. Это довольно небезопасно.
С запросом связан Флаг использования предварительной проверки CORS (use-CORS-preflight). Если не указано иное, он не установлен.
Флаг использования предварительной проверки CORS является одним из нескольких условий, которые приводят к запросу CORS-preflight. Флаг использования предварительной проверки CORS устанавливается, если один или несколько прослушивателей событий зарегистрированы в объекте XMLHttpRequestUpload или если в запросе используется объект ReadableStream.
С запросом связан Режим Учётных Данных (credentials mode): «omit«, «same-origin» или «include» («пропустить», «тот же источник» или «включить»). Если не указано иное, он «того же происхождения» — «same-origin«.
«omit«
Исключает учётные данные из этого запроса и заставляет игнорировать все учётные данные, отправленные обратно в ответе.
«same-origin«
Включает учётные данные в запросы, отправленные на URL-адреса того же происхождения, и использует любые учётные данные, отправленные обратно в ответах с URL-адресов того же происхождения.
«include«
Всегда включает учётные данные с этим запросом и всегда использует любые учётные данные, отправленные обратно в ответ.
Режим учётных данных запроса контролирует поток учётных данных во время выборки. Когда режим запроса — «navigate» (навигация), предполагается, что его режим учётных данных — «include«, а выборка в настоящее время не учитывает другие значения. Если HTML изменится здесь, этот стандарт потребует соответствующих изменений.
С запросом связан Флаг использования-URL-учетных данных (use-URL-credentials flag). Если не указано иное, он не установлен.
С запросом связан Режим Кэширования (cache mode):
- «default«
- «no-store«
- «reload«
- «no-cache«
- «force-cache«
- «only-if-cached«
(«по умолчанию», «без сохранения», «перезагрузка», «без кеширования», «принудительное кеширование» или «только при кэшировании»). Если не указано иное, это «default» (по умолчанию).
«default«
Fetch будет проверять HTTP-кеш на пути к сети. Если HTTP-кеш содержит соответствующий свежий ответ, он будет возвращен. Если HTTP-кеш содержит соответствующий ответ устаревшего при повторной проверке, он будет возвращен, и будет произведена условная сетевая выборка для обновления записи в кеше HTTP. Если HTTP-кеш содержит соответствующий устаревший ответ, будет возвращена условная сетевая выборка для обновления записи в кеше HTTP. В противном случае будет возвращена безусловная сетевая выборка для обновления записи в кэше HTTP. [HTTP] [HTTP-SEMANTICS] [HTTP-COND] [HTTP-CACHING] [HTTP-AUTH] [STALE-WHILE-REVALIDATE]
«no-store«
Fetch ведет себя так, как будто HTTP-кеша вообще нет.
«reload«
Fetch ведет себя так, как будто на пути к сети нет HTTP-кеша. Следовательно, он создает обычный запрос и обновляет HTTP-кеш ответом.
«no-cache«
Fetch создает условный запрос, если есть ответ в кеше HTTP, и обычный запрос в противном случае. Затем он обновляет HTTP-кеш ответом.
«force-cache«
Fetch использует любой ответ в HTTP-кеше, соответствующий запросу, не обращая внимания на устаревание. Если ответа нет, он создает обычный запрос и обновляет HTTP-кеш ответом.
«only-if-cached«
Fetch использует любой ответ в HTTP-кеше, соответствующий запросу, не обращая внимания на устаревание. Если ответа нет, возвращается сетевая ошибка. (Может использоваться только в том случае, если режим запроса — «same-origin» (тот же источник). Любые кэшированные перенаправления будут выполняться при условии, что режим перенаправления запроса — «follow» (следовать) и перенаправления не нарушают режим запроса.)
Если список заголовков содержит `If-Modified-Since`, `If-None-Match`, `If-Unmodified-Since`, `If-Match` или`If-Range`, выборка установит режим кеширования на «no-store» если это «default«.
С запросом связан Режим Перенаправления (redirect mode): «follow«, «error«, или «manual» («следование», «ошибка» или «ручной»). Если не указано иное, это «follow«.
«follow«
Следует всем перенаправлениям, возникающим при получении ресурса.
«error«
Возвращает сетевую ошибку, когда запрос встречается с перенаправлением.
«manual«
Извлекает отфильтрованный ответ с непрозрачным перенаправлением, когда запрос встречается с перенаправлением, чтобы позволить работнику службы воспроизвести перенаправление в автономном режиме. В остальном ответ неотличим от сетевой ошибки, чтобы не нарушать атомарную обработку перенаправления HTTP.
С запросом связаны Метаданные Целостности (integrity metadata) (строка). Если не указано иное, это пустая строка.
С запросом связаны Криптографические Одноразовые Метаданные (cryptographic nonce metadata) (строка). Если не указано иное, это пустая строка.
С запросом связаны Метаданные Синтаксического Анализатора (parser metadata), которые представляют собой пустую строку, «parser-inserted» (вставлено синтаксическим анализатором) или «not-parser-inserted» (не вставлено анализатором). Если не указано иное, это пустая строка.
Криптографические Одноразовые Метаданные запроса и метаданные синтаксического анализатора обычно заполняются из атрибутов и флагов элемента HTML, ответственного за создание запроса. Они используются различными алгоритмами в Политике Безопасности Контента, чтобы определить, должны ли быть заблокированы запросы или ответы в данном контексте. [CSP]
С запросом связан Флаг перезагрузки-навигации (reload-navigation flag). Если не указано иное, он не установлен.
Этот флаг предназначен исключительно для использования алгоритмом навигации HTML. [HTML]
С запросом связан Флаг навигации по истории (history-navigation flag). Если не указано иное, он не установлен.
Этот флаг предназначен исключительно для использования алгоритмом навигации HTML. [HTML]
С запросом связана Логическая Активация Пользователя (user-activation). Если не указано иное, это false.
Это исключительно для использования алгоритмом навигации HTML. [HTML]
С запросом связан Флаг Испорченного Происхождения (tainted origin flag). Если не указано иное, он не установлен.
С запросом связан Список URL-адресов (URL list — список из одного или нескольких URL-адресов). Если не указано иное, это список, содержащий копию URL-адрес запроса.
С запросом связан Текущий URL (current URL). Это указатель на последний URL в списке URL-адресов запроса.
С запросом связан Счётчик перенаправления (redirect count). Если не указано иное, он равен нулю (zero).
С запросом связано Заражение Ответа (response tainting), которое является «basic«, «cors«, или «opaque«. Если не указано иное, это «basic«.
С запросом связан Флаг предотвращения модификации заголовка управления кэшем без кеширования (prevent no-cache cache-control header modification flag). Если не указано иное, он не установлен.
С запросом связан Флаг выполнения (done flag). Если не указано иное, он не установлен.
С запросом связан Флаг ошибки разрешения синхронизации (timing allow failed flag). Если не указано иное, он не установлен.
Флаг испорченного происхождения запроса, список URL-адресов, текущий URL-адрес, счётчик перенаправления, повреждение ответа, флаг завершения и флаг разрешения времени сбоя используются в качестве бухгалтерии алгоритмом выборки.
Запрос субресурса (subresource request) — это запрос, адресатом которого является «audio«, «audioworklet«, «font«, «image«, «manifest«, «paintworklet«, «script«, «style«, «track«, «video«, «xslt» или пустая строка.
Запрос, не относящийся к подресурсам (non-subresource request) — это запрос, адресатом которого является «document«, «embed«, «frame«, «iframe«, «object«, «report«, «serviceworker«, «sharedworker» или «worker«.
Запрос навигации (navigation request) — это запрос, адресатом которого является «document«, «embed«, «frame«, «iframe» или «object«.
Смотри ручную выборку в разделе «Получение дескрипторов». [SW]
Сериализация источника запроса (Serializing a request origin) с учетом запроса «request» заключается в выполнении следующих шагов:
1. Если установлен флаг испорченного происхождения запроса request, вернуть "null". 2. Вернуть сериализованный источник request.
Байт-сериализация источника запроса (Byte-serializing a request origin) при наличии запроса «request» должна вернуть результат сериализации источника запроса с изоморфным кодированием «request».
Чтобы Клонировать (clone) запрос «request», выполните следующие действия:
1. Пусть newRequest будет копией request, за исключением его тела. 2. Если тело request не равно null, установите тело newRequest равным результату клонирования тела request. 3. Верните newRequest.
ЭТО УДАЛЕНО!!! Чтобы Передать тело (transmit body), запроса «request» , выполните следующие действия:
1. Пусть body будет телом request. 2. Если body имеет значение null, то поставьте в очередь задачу выборки по запросу для обработки конца тела запроса для request и прервите эти шаги. 3. Пусть reader будет результатом получения читателя из потока body. (Эта операция не может вызвать исключение.) 4. Выполните цикл передачи тела с учетом request, body и reader.
ЭТО УДАЛЕНО!!! Чтобы Выполнить цикл передачи тела (transmit-body loop) с учетом request, body и reader:
1. Пусть readRequest будет следующим запросом на чтение:
шаги блока, заданный блок (chunk steps, given chunk)
1. Если текущая выборка прервана, прервите эти шаги.
2. Если chunk не является объектом Uint8Array, прекратите текущую выборку и прервите эти шаги.
3. Пусть bs будет последовательностью байтов, представленной объектом Uint8Array.
4. В параллели:
4.1 Передайте bs. Каждый раз, когда передается один или несколько байтов, увеличивайте переданные байты body на количество переданных байтов и ставьте в очередь задачу выборки по request для обработки тела запроса для request.
Этот шаг блокируется до полной передачи bs.
4.2 Если текущая выборка не завершена, то поставьте задачу выборки в очередь на «request», чтобы выполнить цикл тела передачи с учетом «request», «body» и «reader».
близкие шаги (close steps)
1. Если текущая выборка прервана, прервите эти шаги.
2. Поставить задачу выборки в очередь на «request» для обработки конца тела запроса для «request».
шаги ошибки, учитывая e (error steps, given e)
1. Если текущая выборка прервана, прервите эти шаги.
2. Если e — это исключение DOMException «AbortError», завершите текущую выборку с установленным флагом прерывания.
3. В противном случае прекратите текущую выборку.
2. Прочтите фрагмент из потока body с помощью reader, которому задан readRequest.
Чтобы Добавить заголовок диапазона (add a range header) в запрос request, с целым числом first, и необязательное целое число last, выполните следующие действия:
1. Утверждено: last не указан или first меньше или равен last. 2. Пусть rangeValue будет `bytes=`. 3. Выполните сериализацию и изоморфное кодирование first и добавьте результат в rangeValue. 4. Добавьте 0x2D (-) к rangeValue. 5. Если last задан, то сериализуйте и изоморфно закодируйте его и добавьте результат в rangeValue. 6. Добавьте (`Range`, rangeValue) к списку заголовков запроса request.
Заголовок диапазона обозначает включающий диапазон байтов. Заголовок диапазона, где first (первый) — 0 и last (последний) — 500, составляет 501 байт.
Функции, объединяющие несколько ответов в один логический ресурс, исторически являются источником ошибок безопасности. Поищите проверку безопасности для функций, которые имеют дело с частичными ответами.
Чтобы Сериализовать URL-адрес ответа для создания отчетов (serialize a response URL for reporting) с учетом ответа response, выполните следующие действия:
1. Утверждено: список URL-адресов response не пустой. 2. Пусть url будет копией первого элемента списка URL-адресов response.
Это не URL-адрес response, чтобы избежать утечки информации о целях перенаправления (см. Аналогичные соображения для отчетов CSP). [CSP]
3. Установите имя пользователя с указанным url и пустой строкой. 4. Установите пароль, с указанным url и пустой строкой. 5. Верните сериализацию url с установленным флагом исключения фрагмента.
Чтобы проверить, разрешены ли Учётные данные политики внедрения из разных источников (Cross-Origin-Embedder-Policy allows credentials), при запросе request выполните следующие действия:
1. Если режим request не "no-cors", верните true. 2. Если клиент request равен null, верните true. 3. Если значение политики встраивания политики контейнера клиента request не равно "credentialless", то верните true. 4. Если источник request совпадает с источником текущего URL-адреса запроса request, а флаг испорченного источника запроса request не установлен, тогда верните true. 5. Вернуть false.
Информационные ссылки
Стандарт Fetch — https://fetch.spec.whatwg.org/#requests
Перевод стандарта Fetch — https://efim360.ru/fetch/