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

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?

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

Longer answer:

The HTML spec requires browsers to first set the redirect mode to manual when the browser starts navigating to a resource. That’s the only use in any spec for the manual redirect mode.

But because the Fetch API essentially exposes the same primitives that browsers use internally for fetches, it exposes a manual redirect mode. However, just because the API exposes a particular primitive doesn’t mean there’s a good use for that primitive in frontend code.

The spec used to require that even though you could call the API with redirect: 'manual', browsers would throw if you did — because back then nobody had yet offered any valid reason for setting it for any case other than browsers doing navigations.

But that behavior got changed due to https://github.com/whatwg/fetch/issues/66, which gives 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).