Specification outline

[Ethan-Arrowood]

As promised a few calls ago, I have been working on drafting the initial specification for WinterCG Fetch. I've had many discussions with multiple folks and I have arrived at two options for us. I'd like us to decide on one of them as the organization structure for our specification. Once agreed; I will continue #11 and get our base line specification published.

Option 1

The first option is to create a fork of whatwg/fetch here in wintercg. We will utilize aspects of the Bikeshed language (which is what whatwg/fetch is written in) to omit sections and include notes/extensions for aspects that we want to modify.

We will be responsible for rebasing our modifications every time Fetch lands a change to the specification. This could be partially automated where we create a bot that watches the whatwg/fetch repo, and anytime new commit(s) are merged to main, it would open a branch and attempts to do the necessary git operations. Of course, if there are merge conflicts they would need to be settled by a contributor here in WinterCG.

This will ensure our specification is always up to date with the latest whatwg version.

This option has a long-term maintenance cost where members of WinterCG would be responsible for managing the rebasing overtime. As stated, it could be automated, but it wouldn't be a perfect solution as whenever conflicts arise someone would have to spend time fixing them.

Option 2

The second option is to start with essentially an empty specification that states something along the lines of: "Unless otherwise specified in this document, WinterCG Fetch is compatible with the latest edition of WHATWG Fetch specification". Then, overtime as we agree on modifications to whatwg/fetch, we will create new sections within our document that states the necessary changes. For example, lets pretend we agree to get rid of the entire concept of "Forbidden Headers". Our specification may include a section such as:

Please note this is purely for demonstration purposes. The WinterCG has made no decisions regarding modifications to the Whatwg Fetch API and the content in the following example is purely hypothetical. Do not use this issue thread to discuss the nuance of the example.

### Headers

#### Modification of Forbidden Headers List

Section [2.2.2 Headers #forbidden-header-name](https://fetch.spec.whatwg.org/#forbidden-header-name) of the whatwg/fetch specification states a list of header names that are considered "forbidden". During runtime execution of the Fetch API, usage of a forbidden header results in an early return such as in the [Concept Headers append](https://fetch.spec.whatwg.org/#concept-headers-append) section.

WinterCG Fetch deviates from this section by stating that there are **no** forbidden headers. A WinterCG Fetch API will not return early if it encounters one of these headers.

This option has less maintenance burden as it could essentially stagnate while remaining "up to date". With the catch all statement stating that essentially WinterCG Fetch is WHATWG Fetch unless otherwise noted. The WHATWG Fetch could land changes and unless we need to deviate from those changes, we don't have to modify our specification.

Unfortunately, this also means that if we are not on top of changes to WHATWG Fetch, we could incorrectly be supporting something they add that we want to deviate from. Arguably, implementations don't generally move as quickly as standards. And so even if there is a bit of a lag between us coming to decision on a hypothetical change to WHATWG Fetch, many implementers would already be apart of the conversation and it wouldn't have much impact.

---

With these two options, please react to this post with which one you prefer more to give us a sense of what folks are preferring. We will also be discussing this at upcoming wintercg calls. When we come to a majority decision I will create the initial proposal draft. In the mean time, we can being making API decisions for WinterCG Fetch - capture the result in issues, and when we eventually get our proposal created, I can add those decisions to the initial draft. Also please feel free to use this issue to discuss details of either option too.

Thank you!

Option 1 - react with: 😄

Option 2 - react with: 🚀

[frank-dspeed]

i have a question related to this: whatwg#1535 in that specific situation what would you vote for as that is at present a real case that we have the ECMAScript fetch is not whatwg compatible

• v16.18.0 breaks npm ci nodejs/node#44998 (comment)

[frank-dspeed]

As i improved Proposal

• Proposal: allow none network related urls  whatwg/url#715

i found out that it also can replace this voting as this would offer option 3 which i call from now on url compatible specifers.

this allows to define a runtime and header handling algo on the fetch interception layer which is existing in all runtimes see service worker and load hooks for nodejs and or deno

when whatwg accepts to handle dynamic assigned protocols we would solve more higher level problem and platform feature that would be replacing the concepts of custom url based network based protocols like extension://

see the browser layercake picture that i linked in the proposal it allows us to directly reference components and this for does

more none technical explained

This enables none network based urls

Update

as i have writen tests for this i found out that we get near good results

// works
protocol: "node:"

// fails
protocol: "git+ssh@github:"

so its about allowing custom protocol specifiers with some additional signs

Update 2

Whatwg does not like changes in the url parsing for interop so that would be maybe something for wintercg anyway i will change url parsing in chromium it self and this way bypass w3c

[Ethan-Arrowood]

I'm not sure I fully understand what you are proposing.

Please feel free to open a new issue in this repo with your idea and we can discuss it at an upcoming call and potentially deviate from whatwg/fetch