Fetch API - What's the use of redirect: manual

Question

I've recently been playing with the Javascript Fetch API. As far as I understand, by default all redirects are handled transparently and in the end I get a response from the last call in the redirect chain.

However, I could invoke fetch with {redirect: 'manual'}, in which case it would return an opaqueredirect response with no usable information. From https://fetch.spec.whatwg.org/#concept-filtered-response-opaque-redirect

An opaque-redirect filtered response is a filtered response whose type is "opaqueredirect", status is 0, status message is the empty byte sequence, header list is empty, body is null, and trailer is empty.

https://fetch.spec.whatwg.org/#http-fetch says that a response gets to be opaqueredirect if redirect is set to 'manual':

Switch on request’s redirect mode:
...
- manual
    Set response to an opaque-redirect filtered response whose internal response is actualResponse.

The specification also says:

In other words, an opaque filtered response and an opaque-redirect filtered response are nearly indistinguishable from a network error.

Given all this, why would one set redirect to manual when using the Fetch API? To me it seems pretty useless. Are there use cases where this would be useful?

Answer 1

I think the short answer is: unless you’re doing something with service-worker code like what https://github.com/whatwg/fetch/issues/66 describes, you don’t ever want redirect: 'manual'.

Longer answer:

The HTML spec seems to require browsers to initially set the redirect mode to manual when the browser starts navigating to a resource, before then… (re)doing it with redirect mode unset? (In which case it defaults back to follow.) I don’t understand why the algorithm in the spec does it that way, but guess it must have something to do with handling the case where the navigation fails. Regardless, I believe that’s the only use in any spec for the manual redirect mode.

Anyway, the Fetch API is designed to expose all the same primitives that browsers use in fetches, but that doesn’t mean there are always good uses for those primitives in web-app code (in contrast to the use that browsers themselves make of the primitives).

So I think the Fetch spec used to require that even though you could call the API with redirect: 'manual', browsers would throw if you did—I guess because back then nobody had yet put forward any valid reason for it to be set for any case other than browsers doing navigations.

But that behavior seems to have been changed due to https://github.com/whatwg/fetch/issues/66 which describes a (corner) case where redirect: 'manual' is needed in service-worker code.

A similar case of something you can set in the Fetch API but with very little utility in web-app code is mode: 'no-cors'. That was initially added just because browsers use it for certain requests, so the Fetch API exposes it. But that’s another case that has limited utility just for service workers—for caching responses to serve back as-is later without any need to examine the responses (which mode: 'no-cors' prevents web-app code from doing).