Commit cb16fad
doc: add initial version of maintaining-http.md
- document strategy based on Next-10 mini-summit
- initial top level info on http API implementations
Refs: nodejs/next-10#114
Signed-off-by: Michael Dawson <mdawson@devrus.com>
PR-URL: #41798
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Darshan Sen <raisinten@gmail.com>1 parent e117c0f commit cb16fad
1 file changed
Lines changed: 97 additions & 0 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -0,0 +1,97 @@ | |||
| 1 | + # Maintaining HTTP | ||
| 2 | + | ||
| 3 | + Support for HTTP is a key priority in terms of ensuring the continued success of | ||
| 4 | + Node.js as captured in the project's | ||
| 5 | + [technical priorities](https://github.com/nodejs/node/blob/HEAD/doc/contributing/technical-priorities.md). | ||
| 6 | + | ||
| 7 | + The current high level strategy is based on the discussion in the | ||
| 8 | + [Next-10](https://github.com/nodejs/next-10) | ||
| 9 | + [mini-summit](https://github.com/nodejs/next-10/blob/main/meetings/summit-jan-2022.md) | ||
| 10 | + on modern HTTP which was held on Jan 27 2022. | ||
| 11 | + | ||
| 12 | + ## High level strategy | ||
| 13 | + | ||
| 14 | + The key elements of our strategy for future HTTP APIs are: | ||
| 15 | + | ||
| 16 | + * APIs should be HTTP protocol independent (support HTTP1, HTTP2, etc.). | ||
| 17 | + * APIs should be transport protocol independent (TCP, QUIC, etc.). | ||
| 18 | + * APIs should provide good defaults that perform well. | ||
| 19 | + * Client/server APIs should be consistent and allow easy integration. | ||
| 20 | + * Common requirements like piping out from client API to server APIs should be | ||
| 21 | + easy. | ||
| 22 | + * For both the Client and Server there is a need for multiple APIs, with each | ||
| 23 | + targeting a different level of abstraction. | ||
| 24 | + | ||
| 25 | + Unfortunately our existing HTTP APIs ( | ||
| 26 | + [HTTP](https://nodejs.org/docs/latest/api/http.html), | ||
| 27 | + [HTTPS](https://nodejs.org/docs/latest/api/https.html), and | ||
| 28 | + [HTTP2](https://nodejs.org/docs/latest/api/http2.html)) | ||
| 29 | + do not align with our high level strategy. While these APIs | ||
| 30 | + are widely used and we do not plan to deprecate or remove them, | ||
| 31 | + they are not the focus of active development or performance improvements. | ||
| 32 | + Bug fixes however are still important for all of these APIs. | ||
| 33 | + | ||
| 34 | + With respect to the HTTP protocols themselves, our current assessment in | ||
| 35 | + terms of priority within existing or new APIs is: | ||
| 36 | + | ||
| 37 | + * HTTP 2 is in “maintenance mode” for both protocol and APIs. | ||
| 38 | + * HTTP 1 is a stable protocol, but innovation is still possible with the APIs. | ||
| 39 | + * HTTP 3 is an important protocol and we need to add support for it. | ||
| 40 | + | ||
| 41 | + The current strategy is to build out 2 new client APIs and 2 new Server APIs | ||
| 42 | + in line with the high level strategy above. | ||
| 43 | + | ||
| 44 | + While transport-level APIs are important (e.g. socket level), the HTTP APIs | ||
| 45 | + should not be tied to a specific transport-level API. Therefore, | ||
| 46 | + transport-level APIs are out of the scope of our HTTP strategy/maintenance | ||
| 47 | + information. | ||
| 48 | + | ||
| 49 | + ### Client APIs | ||
| 50 | + | ||
| 51 | + For client APIs we want a high-level API and a low-level API when | ||
| 52 | + more control is required. The current plan is for the following APIs: | ||
| 53 | + | ||
| 54 | + * High-level API - | ||
| 55 | + [Fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) | ||
| 56 | + based API built on top of [undici](https://www.npmjs.com/package/undici). | ||
| 57 | + * Low-level API - a subset of the APIs exposed by | ||
| 58 | + [undici](https://www.npmjs.com/package/undici). The exact shape and | ||
| 59 | + set of these APIs is still to be worked out. The current plan is to | ||
| 60 | + pull undici into Node.js core without exposing its APIs in the Node.js | ||
| 61 | + API so that it can initially be used to support the higher level | ||
| 62 | + Fetch-based API. As this gets worked out we will discuss which | ||
| 63 | + APIs to expose in the Node.js API surface. | ||
| 64 | + | ||
| 65 | + ### Server APIs | ||
| 66 | + | ||
| 67 | + For the server APIs we do not yet have a clear path, other than wanting | ||
| 68 | + to align them with the APIs built for the client. | ||
| 69 | + | ||
| 70 | + ## Maintaining the HTTP APIs | ||
| 71 | + | ||
| 72 | + ### HTTP, HTTPS | ||
| 73 | + | ||
| 74 | + The low-level implementation of the | ||
| 75 | + [HTTP](https://nodejs.org/docs/latest/api/http.html) | ||
| 76 | + and [HTTPS](https://nodejs.org/docs/latest/api/https.html) APIs | ||
| 77 | + are maintained in the [llttp](https://github.com/nodejs/llhttp) | ||
| 78 | + repository. Updates are pulled into Node.js under | ||
| 79 | + [deps/llhttp](https://github.com/nodejs/node/tree/HEAD/deps/llhttp) | ||
| 80 | + | ||
| 81 | + The low-level implementation is made available in the Node.js API through | ||
| 82 | + JavaScript code in the [lib](https://github.com/nodejs/node/tree/HEAD/lib) | ||
| 83 | + directory and C++ code in the | ||
| 84 | + [src](https://github.com/nodejs/node/tree/HEAD/src) directory. | ||
| 85 | + | ||
| 86 | + ### HTTP2 | ||
| 87 | + | ||
| 88 | + The low-level implementation of | ||
| 89 | + [HTTP2](https://nodejs.org/docs/latest/api/http2.html) | ||
| 90 | + is based on [nghttp2](https://nghttp2.org/). Updates are pulled into Node.js | ||
| 91 | + under [deps/nghttp2](https://github.com/nodejs/node/tree/HEAD/deps/nghttp2) | ||
| 92 | + as needed. | ||
| 93 | + | ||
| 94 | + The low-level implementation is made available in the Node.js API through | ||
| 95 | + JavaScript code in the [lib](https://github.com/nodejs/node/tree/HEAD/lib) | ||
| 96 | + directory and C++ code in the | ||
| 97 | + [src](https://github.com/nodejs/node/tree/HEAD/src) directory. | ||
0 commit comments