feat(undici-http-handler): add HttpHandler backed by Node.js undici by trivikr · Pull Request #2029 · smithy-lang/smithy-typescript

trivikr · 2026-05-14T19:00:00Z

Issue #, if available:

Migrating code from test package in https://github.com/trivikr/trivikr-test-undici-http-handler

Description of changes:

Adds a new @smithy/undici-http-handler package that provides a Smithy-compatible HTTP handler backed by undici instead of Node.js native http/https modules.

undici offers improved HTTP performance over Node.js built-in modules. Benchmarks show 20%-30% less time spent in request handling compared to NodeHttpHandler from @smithy/node-http-handler, particularly under concurrent load.

Benchmarks (in several runs, it's close to 1.20x and 1.30x)

$ undici-http-handler> yarn test:bench
...
 ✓ src/undici-http-handler.bench.ts > 10 sequential GETs 1213ms
     name                   hz     min     max    mean     p75     p99    p995    p999     rme  samples
   · NodeHttpHandler    413.26  2.0419  5.2733  2.4198  2.3764  3.9081  5.0611  5.2733  ±2.49%      207
   · UndiciHttpHandler  476.21  1.8400  4.0838  2.0999  2.1102  2.9196  3.0122  4.0838  ±1.55%      239

 ✓ src/undici-http-handler.bench.ts > 50 concurrent GETs 1267ms
     name                   hz     min     max    mean     p75     p99    p995    p999     rme  samples
   · NodeHttpHandler    208.81  4.2706  7.0158  4.7890  4.8566  6.7310  7.0158  7.0158  ±2.30%      105
   · UndiciHttpHandler  274.86  3.3944  4.3799  3.6383  3.6770  4.2547  4.3799  4.3799  ±0.87%      138

 BENCH  Summary

  UndiciHttpHandler - src/undici-http-handler.bench.ts > 10 sequential GETs
    1.15x faster than NodeHttpHandler

  UndiciHttpHandler - src/undici-http-handler.bench.ts > 50 concurrent GETs
    1.32x faster than NodeHttpHandler

The E2E tests were run on test handler in aws/aws-sdk-js-v3#8014
New E2E tests will be added when @smithy/undici-http-handler is published.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

This reverts commit 3d71928. It's a one-way door to strictly depend on undici version. We can specify it in peerDependencies for example.

trivikr · 2026-05-14T22:01:57Z

There are a lot of issues with monorepo setup which blocks us from using private fields in UndiciHttpHandler.
I'll switch to using TypeScript private member. We can switch to private fields in a major version bump when dropping support for Node.js version in future.

This reverts commit ba0f0a4.

…jor version

kuhe · 2026-05-15T13:37:51Z

+    "typedoc": "0.23.23"
+  },
+  "peerDependencies": {
+    "undici": "^6.0.0"


This should only appear in one of deps and peerDeps, right?

A module, when it appears in both dependencies and peerDependencies within a package.json file, it usually means a default fallback for the dependency.

When we specify undici@^6.0.0 in dependencies, that mean it's the default. When we specify undici@^6.0.0 in peerDepedencies, it means customers can use those versions when passing their custom dispatcher.

The handler as it's currently designed will accept 7.x and 8.x versions of undici too, if customers on newer versions of Node.js and want to avail performance benefits.

I considered removing undici from dependencies and asking customers to provide a dispatcher.
But customers will have to import both the handler and undici, which won't be a good minimal experience.

Existing minimal code

import { S3 } from "@aws-sdk/client-s3"; import { UndiciHttpHandler } from "@smithy/undici-http-handler"; const client = new S3({ requestHandler: new UndiciHttpHandler(), });

Minimal code if we require customer to pass dispatcher

import { S3 } from "@aws-sdk/client-s3"; import { UndiciHttpHandler } from "@smithy/undici-http-handler"; import { Agent } from "undici"; const client = new S3({ requestHandler: new UndiciHttpHandler({ dispatcher: new Agent() }), });

I think the former is better.

I see, so should the one in peerDep be stated as >=6.0.0 then?

kuhe · 2026-05-15T13:45:33Z

+  public destroy(): void {
+    if (this.config.dispatcher && !this.externalDispatcher) {
+      this.config.dispatcher.destroy();
+      this.config.dispatcher = undefined;


what if the user intent/expectation is that the destroy method destroys their dispatcher too?

By default, we should not destroy the dispatcher as it's external.
But I can also see that most of the customers would likely create dispatcher specifically for the client.

I would like to keep this behavior, and make a change in major version bump is customers request it.
Their existing code, which destroys the custom dispatcher would be backward compatible.

update: I realized that we destroy the user provided agent in node-http-handler, so it would make sense to also do so here

ref:

smithy-typescript/packages/node-http-handler/src/node-http-handler.ts

Lines 131 to 134 in 396de9c

public destroy(): void {

this.config?.httpAgent?.destroy();

this.config?.httpsAgent?.destroy();

}

kuhe · 2026-05-15T14:32:16Z

+  }
+
+  public httpHandlerConfigs(): UndiciHttpHandlerOptions {
+    return { ...this.config };


why copy here? in node http2 I see return this.config ?? {}

If we don't copy, the callee can mutate dispatcher/logger directly and can bypass the intended runtime encapsulation. We should update node http2 handler implementation.

should the return type be marked Readonly<UndiciHttpHandlerOptions>?

kuhe · 2026-05-15T14:41:58Z

      const contents = fs.readFileSync(file);

-      if (file.endsWith(".spec.ts")) {
+      if (file.endsWith(".spec.ts") || file.endsWith(".bench.ts")) {


if we move the bench to /tests it wouldn't need this exception, as only src is walked.

This should be okay, since .bench.ts is a recommended standard for naming benchmark files in vitest.
And we're likely going to use the recommendation for future benchmarks.

Historically, we've use test folder only for clients as we overwrite the src folder which is code generated. For non-clients modules, we tend to keep tests as close to the source as possible.

I'm open to naming benchmark files as *.bench.spec.ts, but that would be against the recommendation from vitest. Do you have a preference?

leaving .bench.ts here is fine, is there some way to globally exclude the pattern from compilation into dist-cjs/es/types?

…eDispatcher

…no-op

…spatcher

siddsriv · 2026-05-15T19:48:23Z

+    // Uses the same duck-typing check as undici's isStream (pipe + on).
+    const body = request.body as Readable | undefined;
+    if (body && typeof body.pipe === "function" && typeof body.on === "function") {
+      if (headers["transfer-encoding"] === "chunked") delete headers["transfer-encoding"];


http headers are case insensitive entirely, things like EXPECT and Transfer-encoding will slip through here, is it ok?

siddsriv · 2026-05-15T19:58:40Z

+      }
+    }
+    if (request.fragment) {
+      path += `#${request.fragment}`;


does this need to be appended and sent over the wire? reading some RFCs around this here (9110, 3986, 9112) it seems like the server could reject it or ignore it.

Some protocol elements that refer to a URI allow inclusion of a fragment, while others do not.

Note: The fragment identifier component is not part of the scheme definition for a URI scheme....

and it does not seem to be a part of the request-targets either (RFC 9112)

siddsriv · 2026-05-15T20:04:51Z

+      for (const key in responseHeaders) {
+        const value = responseHeaders[key];
+        if (value !== undefined) {
+          transformedHeaders[key] = Array.isArray(value) ? value.join(", ") : value;


does this transformation need to be unconditional? we might have some perf gains here: most headers might not require this transformation, they should be strings. We might not need to make a new allocation and x iterations

we could check if the value is indeed an array otherwise skip this copying. i'm hoping the multi-value-header case is indeed rare in which case this could be optimized further

trivikr requested a review from a team as a code owner May 14, 2026 19:00

github-advanced-security AI found potential problems May 14, 2026

View reviewed changes

Comment thread packages/undici-http-handler/src/undici-http-handler.spec.ts Dismissed

trivikr force-pushed the undici-http-handler branch from 1e62635 to 3c321e1 Compare May 14, 2026 19:01

trivikr and others added 5 commits May 14, 2026 20:15

feat: add HttpHandler backed by Node.js undici

7ba5622

test: add validation for value provided for ms

f6b592c

Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

test: add benchmarks using vitest

3f15360

chore: yarn changeset

86ed893

test: use '127.0.0.1' instead of localhost

450e88b

trivikr force-pushed the undici-http-handler branch from e87cecf to 450e88b Compare May 14, 2026 20:17

trivikr added 5 commits May 14, 2026 20:33

chore: skip '.bench.ts' from check-dependencies

2b98884

test(undici-http-handler): compare with undici major version

3d71928

test(undici-http-handler): revert compare with undici major version

6d0dfd4

This reverts commit 3d71928. It's a one-way door to strictly depend on undici version. We can specify it in peerDependencies for example.

chore(undici-http-handler): define 'undici' version in peerDependencies

9e6ef9e

fix: temporarily exclude undici-http-handler from types check

ba0f0a4

trivikr added 5 commits May 14, 2026 22:06

chore: switch to using private keyword

4ae1d6d

test: use import in '.version.spec.ts'

abdb661

fix: revert temporarily exclude undici-http-handler from types check

1347a8b

This reverts commit ba0f0a4.

test: import HttpRequest from @smithy/core/protocols

b9ab281

test: suggest update undici version when dropping support for node ma…

5234a2c

…jor version

kuhe reviewed May 15, 2026

View reviewed changes

kuhe changed the title ~~feat: add HttpHandler backed by Node.js undici~~ feat(undici-http-handler): add HttpHandler backed by Node.js undici May 15, 2026

trivikr added 8 commits May 15, 2026 16:38

chore: move private getOrCreateDispatcher to the bottom

1730a56

chore: use destructuring with assignment as expressions in getOrCreat…

ef5fd38

…eDispatcher

docs: add @public annotation for UndiciHttpHandler

7d28db6

chore: store timeout in a variable before assigning

aacd105

chore: delete expect header only if the value is '100-continue'

0035a7c

chore: delete 'transfer-encoding' header only if the value is 'chunked'

d77b94b

fix: 'requestTimeout' is possibly 'undefined'

8bf7691

feat: accept Agent.Options in dispatcher config

ebf2fab

docs: add low overhead Client option in README

8c3a032

trivikr force-pushed the undici-http-handler branch from 2ac220f to 8c3a032 Compare May 15, 2026 19:09

trivikr added 2 commits May 15, 2026 19:18

chore: allow undefined in updateHttpClientConfig but keep dispatcher …

d355253

…no-op

chore: close previous internal dispatcher when updating with a new Di…

f909f89

…spatcher

siddsriv reviewed May 15, 2026

View reviewed changes

	public destroy(): void {
	this.config?.httpAgent?.destroy();
	this.config?.httpsAgent?.destroy();
	}

Conversation

trivikr commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

trivikr commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

siddsriv May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

trivikr commented May 14, 2026 •

edited

Loading

trivikr commented May 14, 2026 •

edited

Loading

siddsriv May 15, 2026 •

edited

Loading