After a few years since the first release of Undici 3 years ago, we have gathered many contributors and many new features. This little HTTP client that Matteo built as an experiment has quickly grown to be extremely stable and performant, leading the way in a renovated effort of bringing Node.js forward.
This new release brings many breaking changes both internal and external. The new website (https://undici.nodejs.org/) shows all the documentation: take your time to familiarize yourself with the new APIs.
The full change is available at: https://github.com/nodejs/undici/releases/tag/v4.0.0, here we list the most important parts.
Why Undici
A lot of people still ask us why building a replacement for Node.js core HTTP stack — while it works so well for them. The reality is that the Node.js core HTTP stack suffers from fundamental design issues that are impossible to overcome without breaking the API. There are certain bugs or performance bottlenecks we cannot fix without breaking the majority of our users — both on the client and server implementations as they are deeply tied.
The team behind Undici is committed to developing a fast, reliable, and spec-compliant HTTP client for Node.js. Undici is production-ready. Try it out!
Notable Changes
WASM Parser
Undici v3 used the internal Node.js HTTP parser through dynamic binding which has been deprecated in Node 16. To resolve this, and also further improve maintainability and performance, Undici has moved to a WASM build of llhttp (https://github.com/nodejs/llhttp). Using a wasm build also increased Undici’s performance.
Thanks to this feature, we could leverage the new SIMD acceleration that is coming to V8 (and Node.js) later this year. You can evaluate the difference by starting node with the--experimental-wasm-simd option.
As part of this change, we are also removing support for the--insecure-http-parser option.
Redirect Support
Undici will now automatically follow redirects for requests dispatched through the Agent and global API. As a user, you have to specify the `maxRedirections` option to a value greater than zero. Then, Undici will follow 302 and location headers!
Native Mock
Undici supports a native mocking layer that you can use to intercept any outgoing calls either in a pass-through or blocking form.
import { request, MockAgent, setGlobalDispatcher } from './index.js'const agent = new MockAgent()agent.disableNetConnect()
agent.get('http://localhost:3000')
.intercept({
path: '/foo',
method: 'GET'
})
.reply(200, 'hello world')setGlobalDispatcher(agent)const {
statusCode,
headers,
trailers,
body
} = await request('http://localhost:3000/foo')console.log('response received', statusCode)
console.log('headers', headers)body.setEncoding('utf8')
for await (const data of body) {
console.log('data', data)
}console.log('trailers', trailers)
The mock system was greatly inspired by nock.
Website and Documentation
Undici has a new documentation website: https://undici.nodejs.org/. It is built on docsify.
Dispatcher instead of Agent
The API of Undici has been unified so that Client, Pool, and Agent all implement the same and simpler Dispatcher API. This allows these different classes to be used interchangeably and also makes it simpler to extend Undici with custom behaviors while re-using existing functionality.
Support Node v12.x
As Node.js v10 ended its Long Term Support in April 2021, we are migrating the minimum supported Node.js version to v12.x.
What’s next?
Ethan has been working on https://github.com/Ethan-Arrowood/undici-fetch which is a WHATWG fetch implementation built on top of Undici. It is significantly faster than any of the alternatives of Node.js. Stay tuned for some news in this space!
Resume work on the HTTP/2 support. Adding it to Undici is important as the new design could be adapted to handle all versions of HTTP: 1.1, 2 and 3 when it would be available.
Benchmarks
The benchmark is a simple hello world example using Unix sockets (connections) with a pipelining depth of 10 running on Node.js 16. The benchmarks have the simd feature enabled.
Thanks
Thanks to all the folks that contributed to this release. Undici brings a new life to the Node.js HTTP stack — innovating on some old but still actual technology. We welcome all contributions and there is plenty to do, check out our “good first issues” https://github.com/nodejs/undici/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22.
