Marking `http` client APIs as `Legacy`

[jasnell]

Now that fetch(...) has had a while to mature in the runtime and now that most development effort for client-side http is happening in undici, I'd like to propose that we mark all of the http and https module client-side operations as Legacy.

As a reminder what Legacy means... it is NOT the same as deprecating. It means that we have no intention of removing the APIs but that a better option is available and we prefer developers to use that better option. It means that the APIs likely will not receive new features but they are still maintained for the purposes of bug and security fixes.

• http.get(...)
• http.request(...)
• http.globalAgent
• https.get(...)
• https.request(...)
• https.globalAgent

@nodejs/http @nodejs/undici

[mcollina]

I'm ok with it. I don't see how can we reasonably fix some of the problems there are there without massive ecosystem breakage, at least we can start closing some issues/feature requests.

[panva]

Wouldn't having a maintained, performant, and built-in http client be a prerequisite? i.e. exposing some of undici directly in core for developers to use?

It gets repeated over and over that fetch() performance is not even on par with these legacy APIs which is why I'm wondering if we can point developers to it with clean conscience.

[KhafraDev]

exposing some of undici directly in core for developers to use?

undici as a whole could replace those http/s apis but not fetch. Fetch is too opinionated and the spec is maintained and controlled by browsers. For example, we doc-deprecated .formData() in undici due to the poor design choices in the spec that could lead to DOSing on the server (see this PR by a Deno member that has been in limbo for over 2 years now).

[marco-ippolito]

+1 but I think we should expose undici request as modern alternative

[metcoder95]

+1

Tho, exposing at least undici's Agent, request or the equivalents of node:http and node:https from undici should be a must to provide a good alternative.

[Delapouite]

Previous issue about exposing more of undici #43187

[pimterry]

+1 to the general conclusion above: I agree with this general direction of travel, fetch is absolutely not a full substitute for http, but undici could be if it were fully exposed as an official Node API.

Working out the next steps required to start exposing undici and what http features are missing (if any) for it to become the official http replacement would be a great topic for the Paris summit next month.

Do some of the Undici team want to facilitate a summit session to get together and start planning this out? I've worked more on http than undici till now but I'll be there and I'd definitely be interested to get more involved on the undici side and help make this happen.

[mcollina]

@nodejs/undici who will be there in Paris?

[ronag]

Sorry. I'm super busy with my normal work until end of summer.

[metcoder95]

I'll be there 👍

[jasnell]

I don't think it is necessarily required that we have a full replacement for the legacy apis before we mark them as Legacy as long as we're clear that is the direction we are moving.

[joyeecheung]

I don't think it is necessarily required that we have a full replacement for the legacy apis before we mark them as Legacy as long as we're clear that is the direction we are moving.

Isn't that contradictory to

As a reminder what Legacy means... it is NOT the same as deprecating. It means that we have no intention of removing the APIs but that a better option is available and we prefer developers to use that better option.

Telling users that they should use a better option without telling them specifically what is the better option adds confusion to beginners IMO (and they tend to need very detailed instructions on what is the better option, let alone just a vague description).

[jasnell]

No, it's not contradictory. Saying "... a better option is available" does not necessarily mean that the better option is built-in to the runtime.

...Telling users that they should use a better option without telling them specifically what is the better option

I wasn't suggesting that.

[jasnell]

Based on the conversation I'll close this. There's obviously more work to be done before we're ready to do this.