What's the difference/intended usage of the response* algorithms in fetch?

[tabatkins]

The fetch algo takes five algorithms as input, of which three deal with the response: processResponse, processResponseEndOfBody, and processResponseDone. No explanation is given as to when each of these run or what each is for.

The two examples I've found of correct usage of the fetch algo (fetch() itself and XHR.send()) each use processResponse, and fetch also uses processResponseDone.

From reading the fetch algorithm in detail, I can infer that processResponse is called early, as soon as the request finishes, so you can do things like handle progress events or immediately handle errors. It's not clear to me if this is an idiom to be followed, or if it's okay to do all the processing in one of the later-occurring algos.

I don't know what the difference is between processResponseEndOfBody and processResponseDone, other than that, again from reading the fetch algo in detail, they're called in that order, with some degree of processing happening between them that I'm not sure of the details of. So I'm not sure what sort of tasks are appropriate to do in one vs the other.

Could we get some explanation of these inputs in https://fetch.spec.whatwg.org/#fetch-params-process-request-body maybe?

[annevk]

Yeah, I need to write a guide. And per usual my problem is that I also still want to improve things.

What you want to do depends on your use case. If you want to read the body stream yourself you can use processResponse and you probably need to use processResponseDone for resource timing purposes. The latter we might be able to make optional once we have more experience with how that ends up being used by all the various callers of fetch. cc @noamr

If your API doesn't expose intermediate signals and you just want a byte sequence to pass to a parser of sorts, you can use processResponseEndOfBody (XHR does this in a slightly weird way for its synchronous bits, but it's perfectly fine to use it in a non-weird way elsewhere). You will get a response and null, a byte sequence, or failure out of that. processResponseDone is the same as above.

Notably processResponseDone does not consume the body stream. The idea is also that it's called after trailers are received, if we ever add trailers back, but perhaps at that point we change things around a bit if we also got more experience with exposing timing information. (E.g., have a dedicated callback for trailers as there's talk about also being able to send them in the middle of responses and such.)

[noamr]

I am about to start working on whatwg/html#6542, which would add a lot of substance to the usage of those response callbacks. Hopefully once we have that substance we can also clarify the interface.

[tabatkins]

Everything you just wrote, @annevk, would be wonderful in an informative note in the spec; even just marked as an issue for "needs improvement, but for now here's a rough explanation" works. Right now I have nothing to go on in the spec, and locating and reverse-engineering the few existing usages is painful.