Explainer needed for creating requests

[tabatkins]

In the section on requests, there are, at current count, 39 separate fields "associated with" a request. Some of those appear to be things the spec firing off a request would set; some of them appear to be things the fetch machinery would set; some of them are unclear. Several of them have notes giving some guidance on what they're for; several of these notes aren't sufficient for me to actually understand what the field is for or how to use it; about half of the fields don't have notes at all, leaving me to guess at the purpose and intended use of the field from the name.

All in all, this means that I have no real clue what I'm supposed to do to, say, make CSS's @import use the Fetch machinery. Instead I have to ask Anne or Domenic to tell me how to do it, or try to hunt down a spec that's hopefully using best practices and cargo-cult their usage, hoping that they're not doing something odd that doesn't apply to my case.

Since the stated point of Fetch is to allow specs to use a consistent, unambiguous machinery for processing requests and responses, it would be very useful to have explicit guidance given in the spec about how to actually use Fetch.

[domenic]

+1, this would be good. Besides fields to set, some interesting points to cover:

• Should your request be sync (and in parallel) or async?
• How do you process results of the request? Does fetch return a response? Do you use the various tasks in https://fetch.spec.whatwg.org/#process-request-body ?
• Basic stuff after you get a response: check that it's not a network error; usually check that it's an ok status (don't check 200 specifically).
• How do you read the body of the request? Actually, this is not really clear: Getting all bytes in a body #661.
• What common things should you do with "modern" fetches? For example, use "cors" mode, check MIME types (using the specific verbiage "the result of extracting a MIME type from response's header list is...", with some advice about essence matches vs. exact matches), be careful with credentials mode, always use UTF-8 regardless of any headers telling you otherwise...
• How to deal with opaque responses? I think there's an "inner response" or "unsafe inner response" or something involved here.

Regarding fields specifically, a good heuristic is: if you would set them using the fetch() API, then set them when calling from other specs. Otherwise, you can leave them as the default. So this just reduces to the problem of understanding the fetch() API, which is relatively well-documented.

Except, specs really should be setting a destination, I think, which fetch() does not need configured...

[annevk]

I think this is a duplicate of #186. I agree that this would be good, but I don't really have the bandwidth to work on this. And I feel like if I did work on it, I would want to first tackle issues such as #536 which I also haven't gotten to. If there's someone out there who could help with this I'd really appreciate it.

Until that happens my advice would be to look at how HTML, fetch(), and XMLHttpRequest handle this integration. Features such as @import will be aligned with the defaults of features from that era, such as the img element. Newer features should require CORS, similar to module scripts.

[tabatkins]

Please don't let perfect be the enemy of good here; there's many layers of improvement possible. It would be a huge help just to have notes explaining the usage of the field for all the fields, rather than for half the fields like now. And note in there whether it's something set by the request creator, or something reflecting request progress that's manipulated by the algorithms.

Like, the third field listed is the "local-urls-only flag", and I have absolutely no clue what it does or who it's for. Any explanation would help here; I don't need an involved tutorial.

[annevk]

That specifically is for "SVG as image". So it could reference certain resources, but not leak data to the outside world. I'm not sure if that ever made it into implementations however or if they simply block all resources. Pretty sure that was added before we had a proper Working Mode.

What I think I should do is create a "create a request" algorithm that does the right thing unless there are some esoteric needs and migrate callers to that.

[tabatkins]

That specifically is for...

Cool, now put that into the spec. ^_^

What I think I should do is create a "create a request" algorithm that does the right thing unless there are some esoteric needs and migrate callers to that.

Also good, but I'll still need guidance on the individual flags so I can figure out if I have esoteric needs.

[annevk]

What other members are unclear?

[tabatkins]

Just scanning down the list:

• the second un-noted one is "headers list" which is reasonably straightforward on its own
• the third is "client", which I again have no idea what it does or why I would set it
• "initiator" and "destination" aren't particularly clear, tho I can probably puzzle out when I need to set just by scanning down the table following them and seeing what my situation is most similar to. But I don't actually know what they do, except for the vague statement that it's involved in CSP somehow, so I'd be unsure I'm doing things correctly.
• in general it's not clear to me what exactly I'm meant to do regarding CORS, but that's probably best addressed in a separate explainer or helper algo.

[tabatkins]

I'm currently writing the "@import on Fetch" commit, and I still just have a ???? on specifying the client for the request. What is the client, and how should I figure out what to set it to?

[jyasskin]

For client in particular, I believe it'll be the relevant settings object of the Document passed into https://drafts.csswg.org/cssom/#fetch-a-css-style-sheet. Once you set the client, I believe you won't need to set the origin anymore, since the client provides a default for the origin. (This comment isn't intended to replace the need for the spec to explain how to set the client.)