Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: add initial version of maintaining-http.md #41798

Closed
wants to merge 16 commits into from
Closed
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 98 additions & 0 deletions doc/contributing/maintaining-http.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
# Maintaining HTTP

Support for HTTP is a key priority in terms of ensuring the continued success of
Node.js as captured in the projects
targos marked this conversation as resolved.
Show resolved Hide resolved
[technical priorities](https://github.com/nodejs/node/blob/master/doc/contributing/technical-priorities.md).
mhdawson marked this conversation as resolved.
Show resolved Hide resolved

The current high level stragegy is based on the discussion in the
targos marked this conversation as resolved.
Show resolved Hide resolved
[Next-10](https://github.com/nodejs/next-10)
[mini-summit](https://github.com/nodejs/next-10/blob/main/meetings/summit-jan-2022.md)
on modern HTTP which was held on Jan 27 2022.

## High level strategy

The key elements of our strategy for future HTTP APIs are:

* APIs should HTTP protocol independant (support HTTP1, HTTP2, etc.)
targos marked this conversation as resolved.
Show resolved Hide resolved
* APIs should be transport protocol independant (tcp, quick, etc.)
targos marked this conversation as resolved.
Show resolved Hide resolved
targos marked this conversation as resolved.
Show resolved Hide resolved
* APIs should provide good defaults the perform well
targos marked this conversation as resolved.
Show resolved Hide resolved
* Client/server APIs should be consistent and allow easy integration
* Common requirements like piping out from client API to server APIs should be easy
* For both the Client and Sever there is a need for multiple APIs, with each targeting
targos marked this conversation as resolved.
Show resolved Hide resolved
a different level of abstraction.

Unfortunately our existing HTTP APIs:

* [HTTP](https://nodejs.org/docs/latest/api/http.html)
* [HTTPS](https://nodejs.org/docs/latest/api/https.html)
* [HTTP2](https://nodejs.org/docs/latest/api/http2.html)
targos marked this conversation as resolved.
Show resolved Hide resolved

do not align with the key elements. For this reason, while these APIs
targos marked this conversation as resolved.
Show resolved Hide resolved
are widely used and we do not plan to deprecate or remove them,
they are not the focus of active development or performance improvements.
Bug fixing is still important for all of these APIs.
targos marked this conversation as resolved.
Show resolved Hide resolved

With respect to the HTTP protocols themselves our current assessment in
targos marked this conversation as resolved.
Show resolved Hide resolved
terms of priority within existing or new APIs is:
* HTTP 2 in “maintenance mode” both protocol and APIs
targos marked this conversation as resolved.
Show resolved Hide resolved
* HTTP 1 stable protocol, but innovation in APIs
targos marked this conversation as resolved.
Show resolved Hide resolved
* HTTP 3 is the future need to plan in support
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure what this bullet point is trying to say


The current strategy is to build out 2 new client APIs and 2 new Server APIs
in line with the key elements above.
mhdawson marked this conversation as resolved.
Show resolved Hide resolved

While trasport level APIs are important (ex socket level), the HTTP APIs
targos marked this conversation as resolved.
Show resolved Hide resolved
should not be tied to a specific transport level API. Therefore,
targos marked this conversation as resolved.
Show resolved Hide resolved
transport level APIs are out of the scope of our HTTP strategy/maintaining
targos marked this conversation as resolved.
Show resolved Hide resolved
information.

### Client APIs

For client APIs we want a high level API and a lower level API when
targos marked this conversation as resolved.
Show resolved Hide resolved
more control is required. The current plan is for the following APIs:

* High level api -
targos marked this conversation as resolved.
Show resolved Hide resolved
[Fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)
based API buit on top of [undici](https://www.npmjs.com/package/undici).
targos marked this conversation as resolved.
Show resolved Hide resolved
* Lower Level API - a subset of the APIs exposed by
targos marked this conversation as resolved.
Show resolved Hide resolved
targos marked this conversation as resolved.
Show resolved Hide resolved
targos marked this conversation as resolved.
Show resolved Hide resolved
[undici](https://www.npmjs.com/package/undici). The exact shape and
set of these APIs is still to be worked out. The current plan is to
targos marked this conversation as resolved.
Show resolved Hide resolved
pull undici into Node.js core without exposing its APIs in the Node.js
API so that it can initially be used to support the higher level
Fetch based API. As this gets proved out we will discuss which
targos marked this conversation as resolved.
Show resolved Hide resolved
APIs to expose in the Node.js API surface.

### Server APIs

For the server APIs we do not yet have a clear path, other than wanting
to align them with the APIs built for the client.

## Maintaining the HTTP APIs

### HTTP, HTTPS

The lower implementation of the
targos marked this conversation as resolved.
Show resolved Hide resolved
[HTTPS](https://nodejs.org/docs/latest/api/https.html)
targos marked this conversation as resolved.
Show resolved Hide resolved
and [HTTP2](https://nodejs.org/docs/latest/api/http2.html) APIs
targos marked this conversation as resolved.
Show resolved Hide resolved
are maintained in the [llttp](https://github.com/nodejs/llhttp)
repository. Updates are pulled into Node.js under
targos marked this conversation as resolved.
Show resolved Hide resolved
[deps/llhttp](https://github.com/nodejs/node/tree/master/deps/llhttp)
mhdawson marked this conversation as resolved.
Show resolved Hide resolved

The lower level implemention is surfaced in the Node.js API through
targos marked this conversation as resolved.
Show resolved Hide resolved
JavaScript code in the [lib](https://github.com/nodejs/node/tree/master/lib)
mhdawson marked this conversation as resolved.
Show resolved Hide resolved
directory and C++ code in the
[src](https://github.com/nodejs/node/tree/master/src) directory.
mhdawson marked this conversation as resolved.
Show resolved Hide resolved

### HTTP2

The low level implementation of
targos marked this conversation as resolved.
Show resolved Hide resolved
[HTTP2](https://nodejs.org/docs/latest/api/http2.html)
targos marked this conversation as resolved.
Show resolved Hide resolved
is based on [nghttp2](https://nghttp2.org/). Updates are pulled into Node.js
under [deps/nghttp2](https://github.com/nodejs/node/tree/master/deps/nghttp2)
mhdawson marked this conversation as resolved.
Show resolved Hide resolved
as needed.

The lower level implemention is surfaced in the Node.js API through
targos marked this conversation as resolved.
Show resolved Hide resolved
JavaScript code in the [lib](https://github.com/nodejs/node/tree/master/lib)
mhdawson marked this conversation as resolved.
Show resolved Hide resolved
directory and C++ code in the
[src](https://github.com/nodejs/node/tree/master/src) directory.
mhdawson marked this conversation as resolved.
Show resolved Hide resolved

mhdawson marked this conversation as resolved.
Show resolved Hide resolved