Skip to content

feat: Added @perseveranza-pets/milo as alternative experimental HTTP parser - #5492

Merged
ronag merged 2 commits into
nodejs:mainfrom
ShogunPanda:milo
Sep 30, 2026
Merged

ronag merged 2 commits into
nodejs:mainfrom
ShogunPanda:milo

Conversation

@ShogunPanda

Copy link
Copy Markdown
Contributor

Summary

  • Added an opt-in Milo-backed HTTP/1 parser, enabled with UNDICI_USE_MILO=1 or UNDICI_USE_MILO=true.
  • Vendored Milo CJS artifacts, including SIMD and non-SIMD WebAssembly builds, plus a build:milo script to refresh them.
  • Integrated Milo into the HTTP/1 client parser selection while preserving the existing llhttp parser as the default.
  • Updated benchmarks and tests for the new parser callback flow and Milo’s stricter RFC 9112 parsing behavior.

Assisted-By: OpenAI:GPT-5.5 <openai/gpt-5.5>

Status

@ShogunPanda
ShogunPanda requested a review from mcollina July 2, 2026 15:15
@ronag

ronag commented Jul 2, 2026

Copy link
Copy Markdown
Member

Perf comparison?

@codecov-commenter

codecov-commenter commented Jul 2, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 20.85521% with 4220 lines in your changes missing coverage. Please review.
✅ Project coverage is 84.63%. Comparing base (f59b0f2) to head (fc0bac2).

Files with missing lines Patch % Lines
lib/milo/src/no-simd/index.js 0.00% 1087 Missing ⚠ïļ
lib/milo/src/no-simd/unbundled.js 0.00% 1085 Missing ⚠ïļ
lib/milo/src/simd/unbundled.js 0.00% 1085 Missing ⚠ïļ
lib/dispatcher/parser-h1.js 23.95% 711 Missing ⚠ïļ
lib/milo/src/simd/index.js 76.90% 251 Missing ⚠ïļ
lib/dispatcher/client-h1.js 97.91% 1 Missing ⚠ïļ
Additional details and impacted files
@@            Coverage Diff             @@
##             main    #5492      +/-   ##
==========================================
- Coverage   93.50%   84.63%   -8.88%     
==========================================
  Files         110      115       +5     
  Lines       38436    43701    +5265     
==========================================
+ Hits        35940    36985    +1045     
- Misses       2496     6716    +4220     

☔ View full report in Codecov by Harness.
ðŸ“Ē Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄ïļ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • ðŸ“Ķ JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@ShogunPanda

Copy link
Copy Markdown
Contributor Author

Perf comparison?

I haven't posted them here but even thought Milo is twice as fast as llhttp in terms of pure WASM perf, undici benchmark varies from +3% to -1% on different runs. I've tried countless times.
The interesting thing is that Milo has an optimization which can suspend the parser after the headers and I have this in the H1Parser so body parsing can be skipped when the Content-Length is present. This would help performance in big payloads.

@metcoder95 metcoder95 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I like this, a env var seems a good option as well to switch between experiences; but maybe adding it within a Client constructor can be helpful.

@ShogunPanda

ShogunPanda commented Jul 3, 2026 •

Copy link
Copy Markdown
Contributor Author

I like this, a env var seems a good option as well to switch between experiences; but maybe adding it within a Client constructor can be helpful.

@metcoder95 Do you mind to expand. I'm not sure I get what you're asking for.

@metcoder95

Copy link
Copy Markdown
Member

Sure thing, was just referring that it could be nice to, when instantiating a Client, we could turn on a flag that uses milo instead of llhttp.

Just guarding it as experimental should be enough to warn its usage.

@ShogunPanda

Copy link
Copy Markdown
Contributor Author

@metcoder95 How about now?

@metcoder95 metcoder95 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

lgtm, thanks @ShogunPanda 🚀

Just conflicts arised

â€Ķparser.

Signed-off-by: Paolo Insogna <paolo@cowtech.it>
Signed-off-by: Paolo Insogna <paolo@cowtech.it>
@mcollina

Copy link
Copy Markdown
Member

Benchmark results (llhttp vs Milo)

Ran benchmarks/ on fc0bac20 comparing the default llhttp path against UNDICI_USE_MILO=1.

TL;DR: Milo is meaningfully faster on the GET benchmark (+14% to +44% on the core dispatcher APIs) and roughly neutral on the POST benchmark, where the 128 KiB upload dominates and parsing is a small share of the work.

Environment

  • Intel i7-7700 (4C/8T @ 3.60 GHz), 62 GB RAM, Linux 6.8, Node.js v24.18.0
  • SIMD Milo build was selected (lib/milo/src/simd/index.js)

Methodology

The stock npm run bench layout (server with os.cpus().length = 8 workers, client on the same 8 cores) turned out to be too noisy to interpret on this box — between two back-to-back runs the control clients (got, node-fetch, superagent, plain node:http) moved by up to 2×, which swamps the effect being measured. My first unpinned pair of runs actually showed Milo slower; that was noise, not signal.

So I pinned the two sides apart:

  • server: WORKERS=4, taskset -c 0-3
  • client: taskset -c 4-7, SAMPLES=100 CONNECTIONS=50 (otherwise identical to npm run bench)
  • rounds alternated llhttp → Milo → llhttp → Milo â€Ķ so drift hits both configs equally
  • first round discarded as warm-up; numbers below are the mean of the remaining rounds (3 rounds for GET, 2 for POST)

The non-undici clients in the table act as a built-in control: they don't touch the H1 parser, so their spread between configs is the noise floor. With pinning that floor is Âą6%.

GET benchmark (benchmark.js, 64 KiB response)

Test llhttp (req/sec) Milo (req/sec) Δ
undici - stream 12,953 18,605 +43.6%
undici - dispatch 14,471 19,960 +37.9%
undici - request 12,352 16,868 +36.6%
undici - pipeline 11,707 13,392 +14.4%
undici - fetch 5,424 5,718 +5.4%

Control clients (should be unaffected — this is the noise floor):

Test llhttp Milo Δ
http - keepalive 9,214 8,700 -5.6%
superagent 7,289 7,097 -2.6%
got 6,045 5,714 -5.5%
http - no keepalive 5,869 5,851 -0.3%
node-fetch 4,703 4,561 -3.0%

The undici deltas are 6–8× the control spread, so the GET win looks real.

undici - fetch barely moves, which is expected — it's bottlenecked in the Fetch/streams layer rather than in the parser.

POST benchmark (post-benchmark.js, 128 KiB request body)

Test llhttp (req/sec) Milo (req/sec) Δ
undici - pipeline 3,593 4,125 +14.8%
undici - fetch 1,700 1,854 +9.0%
undici - dispatch 5,577 5,690 +2.0%
undici - stream 5,414 5,509 +1.8%
undici - request 5,527 5,255 -4.9%

Apart from pipeline, everything here is inside the noise band — unsurprising, since the upload dominates and the response body is small.

Correctness spot-check

Before trusting the GET numbers I checked that Milo isn't simply delivering less: 500 concurrent requests against the bench server under both parsers returned identical results — 32,768,000 bytes total, correct content-length, correct status, and byte-for-byte identical payloads, 0 mismatches under both.

Caveats

  • Single machine, 4 physical cores; the pinning that makes the comparison stable also means server and client each get half the box, so absolute numbers are lower than an unpinned npm run bench.
  • Results on an unpinned, fully-contended setup were not reproducible in either direction on this hardware — worth a second opinion from a bigger/quieter machine before treating the exact percentages as final.
  • Only bench and bench-post were run; bench:h2 is unaffected (H2 doesn't use this parser) and bench:https wasn't run.

Benchmarks run with Claude Code.

@ShogunPanda

Copy link
Copy Markdown
Contributor Author

@metcoder95 @mcollina Are we good to land this?

@metcoder95

Copy link
Copy Markdown
Member

Nothing to add in my side, lgtm 👍

@ronag
ronag merged commit 2764d99 into nodejs:main Sep 30, 2026
38 checks passed
@ShogunPanda
ShogunPanda deleted the milo branch October 1, 2026 07:35
@github-actions github-actions Bot mentioned this pull request Oct 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants