Skip to content

feat: add --http-version to select HTTP/1.1, HTTP/2 or HTTP/3 - #154

Open
AlphaJack wants to merge 4 commits into
librespeed:masterfrom
AlphaJack:http3
Open

AlphaJack wants to merge 4 commits into
librespeed:masterfrom
AlphaJack:http3

Conversation

@AlphaJack

@AlphaJack AlphaJack commented Oct 8, 2026 •

Copy link
Copy Markdown

Adds --http-version auto|1.1|2|3 to choose the protocol used with test servers (1 works as an alias of 1.1). HTTP/3 comes from quic-go, as Go's own x/net/http3 is still a proposal (golang/go#70914).
The protocol used is printed and added to the JSON report:

{"protocol":"HTTP/3.0","tls":{"version":"TLS 1.3","cipher":"TLS_AES_128_GCM_SHA256"}, ...}

Modes

auto keeps today's behaviour (HTTP/2 or HTTP/1.1 over TCP) until a server advertises h3 on the same host and port in Alt-Svc. Then it switches that server to HTTP/3. If QUIC fails it falls back to TCP with a warning.

  • Alt-Svc is parsed per RFC 7838. ma=0 and clear withdraw the offer, and quoted parameters cannot split an entry.
  • The QUIC handshake gets at most a third of --timeout (3s cap). A network that silently drops UDP still leaves time for the TCP retry.
  • The request that discovered HTTP/3 is repeated over it. The JSON report then names the protocol and TLS the download and upload actually ran over. A run that fell back midway shows as HTTP/3.0+HTTP/2.0.
  • An upload request cannot be replayed once its body is sent. When one fails, a new request starts, over TCP once auto has fallen back. The bytes it sent stay counted: with --no-pre-allocate the body never ends, every request ends at --timeout, and the server got all of them. If no request gets an answer and the last error is not the client timeout, the upload fails instead of reporting 0 Mbps.

Known limit: the handshake time limit covers only the handshake. If UDP stops working after HTTP/3 is up, the request in flight waits for --timeout and gets no TCP retry, because its time is used up. The next request goes over TCP.

A forced version never falls back. Failures go to stderr even with --json, since a result silently measured over another protocol would be misleading. --http-version 3 on an http:// server says to use --secure.

What stays on TCP

  • Server list and telemetry: librespeed.org advertises h3 but doesn't answer on UDP 443. Telemetry has its own TCP-only client, even when it shares a host with a test server.
  • Anything behind HTTP(S)_PROXY: QUIC cannot go through an HTTP proxy. auto stays on TCP through the proxy. A forced 3 fails with a clear error instead of going around it.

Sockets

QUIC sockets reuse the TCP dialer's Control and source address. So --source, --interface, --fwmark and -4/-6 apply to HTTP/3 too. With --source, addresses of the other IP family are skipped, so a dual-stack host still works.

Initial packets are 1200 bytes. quic-go's 1280-byte default does not fit the 1280-byte MTU of WireGuard/Tailscale tunnels, and the handshake times out (quic-go/quic-go#5573).

Each UDP socket is closed with its connection: quic-go closes only the sockets it opened itself.

Network errors can carry text from the server, such as an HTTP/3 close reason or a certificate name. The transport strips their control characters before returning them, and the places that print errors sanitize them again.

Testing

Tested against a self-hosted server serving all three versions, over Tailscale and its public address. Also tested against server 105, which advertises h3 without serving it: auto falls back to HTTP/2 and forced 3 errors.

On quic-go v0.63.0, HTTP/3 download matched TCP but upload was about a third of it (~17 vs ~55 Mbps). curl over HTTP/3 reached TCP speed against the same server, so the gap was quic-go's sender (quic-go/quic-go#5325). quic-go/quic-go#5925 fixed that in v0.64.0, and this PR now uses v0.65.0.

Re-measured in Docker: the official LibreSpeed image behind Caddy (which serves and advertises h3), with the client's uplink shaped by tc netem to 100 Mbit/s and 20 ms delay. Same code built on both quic-go versions. 10 s upload tests, two rounds each, in Mbps:

Link v0.63 HTTP/2 v0.63 HTTP/3 v0.65 HTTP/2 v0.65 HTTP/3
25% reordered 9.5 / 11.5 5.2 / 5.7 10.3 / 9.1 22.0 / 22.9
2% reordered 92.5 / 92.9 91.5 / 90.8 93.3 / 93.3 91.7 / 91.3
±5 ms jitter, in order 92.5 / 92.9 88.7 / 88.8 92.9 / 93.0 79.0 / 76.5

Heavy reordering reproduces the old gap, and v0.65.0 fixes it. With jitter but no reordering, v0.65.0 HTTP/3 is about 12% below v0.63.0. Two rounds are too few to tell whether that is noise. auto switched to HTTP/3 against this server with no flags.

Unit tests cover the forced versions, the Alt-Svc upgrade, fallback on a refused and a blackholed UDP port, Alt-Svc parsing, proxies, dual-stack --source, error sanitizing, socket cleanup and upload retries. go build/go vet/go test/go test -race all green. CSV is unchanged.

@maddie maddie left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Thanks for this. The feature is well-scoped and the tests pass (go test ./..., go vet ./..., and go test -race ./... in the worktree). I found several correctness and security problems in the new HTTP/3 path that should be fixed before merge.

❌ speedtest/transport.go:52-59,147-187 — HTTP/3 bypasses the configured HTTP proxy

speedtest/speedtest.go:186 clones http.DefaultTransport, so the TCP paths honor ProxyFromEnvironment. The custom h3 Dial opens UDP directly to the resolved origin, and http3.Transport has no proxy support. With HTTP_PROXY/HTTPS_PROXY set, --http-version 3 fails when the proxy is mandatory, and auto can switch the test traffic outside a privacy/policy proxy after seeing an Alt-Svc header. This is a real bypass, not just a compatibility gap.

Please evaluate the proxy for each request (tcp.Proxy or http.ProxyFromEnvironment(req)) before using h3: in auto, do not upgrade; for forced 3, return a clear sanitized error. Add a test with HTTPS_PROXY set.

❌ speedtest/transport.go:157-172 — --source can fail before trying the matching address family

laddr is built from the source IP's family, but the loop tries resolved destinations in resolver order and returns immediately if ListenPacket fails. A dual-stack host with an AAAA record first plus an IPv4 --source gives udp6 + IPv4 local address, which fails, and the IPv4 destination is never tried. This contradicts the PR's claim that --source and -4/-6 apply to HTTP/3.

Skip mismatched families (or bind a wildcard port when no source is set), append bind errors and continue until all candidates fail, then return the joined errors. Preserve the IPv6 zone in the local address. Add a dual-stack source test.

❌ speedtest/transport.go:93-103 — auto does not fall back when the h3 attempt hits the client timeout

The fallback is skipped whenever req.Context().Err() != nil (line 95). On networks that silently drop UDP, the QUIC handshake consumes http.DefaultClient.Timeout (speedtest/speedtest.go:171), so the error is context.DeadlineExceeded and the request returns instead of retrying TCP. This is the common filtered-network case, and it is exactly when the promised fallback is needed.

Distinguish user cancellation from deadline expiry; give the h3 attempt a shorter budget than the overall test timeout; and retry TCP for a replayable GET while the request can still proceed. Add a blackholed-UDP test with a short timeout.

❌ speedtest/transport.go:128-136 — Alt-Svc is a substring check and ignores ma=0 / clear

Alt-Svc: h3=":443"; ma=0 withdraws the alternative, but this code still upgrades. It also matches unrelated/malformed values. Parse the header list, require the same host/port and protocol h3, and reject ma=0 and clear. Add table tests for ma=0, clear, a different port, a different host, and a normal ma=60.

❌ speedtest/transport.go:86,98 — remote-influenced errors are printed without sanitization

The host is sanitized, but err is passed raw to WriteError/WriteUI. TLS and transport errors can contain remote-controlled certificate names or text, and an embedded ESC sequence can rewrite the terminal. Pass output.Sanitize(err.Error()) at both sites and add a test with an error containing \x1b[2J.

💡 Protocol/TLS reporting can be stale

defs/server.go:80 records Protocol and TLS during IsUp; speedtest/helper.go:57,211-216 later prints that snapshot. If auto upgrades during the first download, or falls back from h3 during a measurement, the UI/JSON can describe a connection that was not used. Prefer the protocol/TLS observed on the actual measurement requests (with synchronization), or update the server after download/upload completes.

💡 Telemetry can use HTTP/3 when it shares a host with a test server

speedtest/helper.go:340 posts telemetry through http.DefaultClient, and every test-server host is in protoTransport.hosts. If --share uses the same host as a test server, telemetry is upgraded or forced to h3, contrary to the PR's “telemetry stays on TCP” design. Use a separate TCP-only client for telemetry.

💡 Forced HTTP/3 on an http:// server hides the useful hint

transport.go:81-82 returns “HTTP/3 requires https, try --secure”, but IsUp logs it only under --debug; the user sees “not responding”. Surface this sanitized error without --debug, and document the HTTPS/proxy constraints in the flag help.

💡 The default auto mode changes upload performance

The PR notes HTTP/3 upload is about 17 Mbps vs 55 Mbps over TCP because of quic-go’s sender. Since auto is the default, users of h3-capable servers will silently get the slower path. Consider defaulting to 2 until that issue is resolved, or document the tradeoff prominently.

The TLS verification path looks correct: h3 clones tcp.TLSClientConfig, so --ca-cert and the explicit --skip-cert-verify setting are honored. The forced 1.1/2/3 happy paths also work; the gaps above are the failure and proxy paths.

@maddie

maddie commented Nov 16, 2026

Copy link
Copy Markdown
Collaborator

Status check: master has advanced to 8aefd77 (#153, #158), and this branch is now CONFLICTING. The only conflict is speedtest/helper.go:66-71: #153 replaced if currentServer.IsUp() with if upErr := currentServer.CheckUp(); upErr == nil {. Keep the new CheckUp condition and your output.WriteUI("Protocol: ...") line; I verified this resolution locally, and go test ./... and go vet ./... pass on the rebased head.

The five ❌ findings in the review above still need fixes before re-review: proxy bypass for HTTP/3, dual-stack --source, timeout fallback in auto, Alt-Svc parsing, and unsanitized remote errors. Please rebase and push when ready.

Test servers can now be reached over HTTP/3 (QUIC, via quic-go). The
default, auto, keeps negotiating HTTP/2 or HTTP/1.1 over TCP and moves a
server to HTTP/3 once it advertises it through Alt-Svc, falling back to
TCP if QUIC then fails. 1.1, 2 and 3 force that version and never fall
back. The server list and telemetry stay on TCP.

QUIC sockets are bound like the TCP ones, so --source, --interface,
--fwmark and -4/-6 apply to HTTP/3 too. Initial packets are 1200 bytes,
as quic-go's 1280-byte default does not fit the 1280-byte MTU of
WireGuard/Tailscale tunnels (quic-go/quic-go#5573).

The protocol used is printed and reported in --json as "protocol".
- Keep HTTP/3 off behind an HTTP(S) proxy: auto stays on TCP, forced 3 errors
- Skip addresses of the other IP family when --source is set
- Cap the QUIC handshake in auto at a third of --timeout so the TCP retry fits
- Parse Alt-Svc per RFC 7838, honouring ma=0 and clear
- Sanitize error text from the server before printing it
- Report the protocol and TLS the measurements ran over
- Send telemetry over a TCP-only client
- Show the "HTTP/3 requires https" hint without --debug
- Bump quic-go to v0.65.0, which fixes slow uploads on reordering links
@AlphaJack

Copy link
Copy Markdown
Author

@maddie added changes after bumping quic-go, also updated the PR body with my speedtest results

@maddie maddie left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Re-review at 9821b42

The five findings from the previous review are addressed: the HTTP/3 proxy bypass, the --source dual-stack early exit, the auto-mode handshake timeout, the Alt-Svc substring check, and the unsanitized transport errors. The new observation plumbing also fixes the stale protocol/TLS snapshot and keeps telemetry on TCP.

I ran go test ./..., go vet ./..., and go test -race ./... at this head with Go 1.26.8; all pass.

❌ error

speedtest/transport.go:311-315 and speedtest/transport.go:358 — a DNS response with no addresses can crash the process.

LookupIP can return an empty slice with a nil error for a NOERROR/NODATA answer. dialQUICAddrs then never enters its loop, and errors.Join() of an empty slice is nil, so dialQUIC returns (nil, nil). quic-go v0.65 passes that nil connection to newClientConn (http3/transport.go:390), which calls conn.QlogTrace() at http3/client.go:93 and panics. This is reachable in both forced --http-version 3 and auto mode, so a resolver that answers NODATA can take down the CLI.

Please return an explicit error when len(ips) == 0 in dialQUIC, and make dialQUICAddrs return an error when it made no connection and errs is empty. A unit test that calls dialQUICAddrs with an empty slice would cover the second guard.

💡 nit

speedtest/transport.go:152-155 — for a non-replayable POST/upload, the code flips the host to TCP but returns the original error, so the current upload fails rather than falling back. Refusing to replay a partially sent body is correct, but the PR description says auto mode “falls back to TCP” without that caveat. Please document the limitation, or have the upload path retry the chunk over TCP after the state flip.

speedtest/transport.go:147-149 — the handshake budget only covers the QUIC handshake. If UDP works for the handshake and then blackholes, auto mode waits for the client timeout and returns without a TCP retry because the context is already done. This is not a regression, but it is worth documenting as a known limit of the auto fallback.

speedtest/transport.go:266 and speedtest/transport.go:288 — ma=00 is not treated as a withdrawal, and Clear is not recognized because the comparison is case-sensitive. Minor RFC 7838 edge cases; not a blocker.

@maddie maddie left a comment •

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Re-review at 9821b42 (turn 4)

This round found three defects, all in error and teardown paths, and I corrected one claim from my previous review. I reproduced every finding at this head instead of relying on the code reading. go test ./..., go vet ./..., and go test -race ./... pass with Go 1.26.8, and the happy path works over 1.1, 2, 3, and auto, so the PR is close.

❌ error — speedtest/transport.go:341-352: the UDP socket is never closed, so every QUIC attempt leaks a file descriptor

pc comes from ListenPacket and is handed to a quic.Transport built as a struct literal. quic-go closes Transport.Conn only when it created that conn itself (createdConn, set by quic.Listen/quic.Dial — see quic-go@v0.65.0/transport.go:462-474). Neither tr.Close() at line 352 nor the goroutine at line 349 closes pc.

Reproduced: 20 failed dials to a closed local UDP port grew /proc/self/fd from 7 to 27, and adding pc.Close() after tr.Close() on both paths kept it at 7. The runtime finalizer reclaims them eventually, so this is fd pressure rather than unbounded exhaustion, but each attempt holds a socket for a whole GC window.

Please call pc.Close() on both paths, or use quic.Dial so quic-go owns the socket.

❌ error — speedtest/transport.go:152-153, defs/server.go:560-566, defs/server.go:640: a failed upload is dropped instead of retried, and the run then reports zero bytes as a success

Upload bodies are io.TeeReader values with no GetBody (defs/server.go:534-538), so replayable is false. When the h3 attempt fails mid-test, roundTrip flips the host to TCP and returns the error; doUpload logs it through WriteDebug (hidden without --debug), returns without signalling uploadDone, and Upload returns counter.AvgMbps(), counter.Total(), nil.

Reproduced end to end: a server that advertises h3, QUIC dropped before the upload, auto mode. CheckUp negotiated HTTP/3, the first POST failed, and Upload returned rate=0.000 total=0 err=<nil> after the full duration. With --json that is an upload of 0.00 Mbps presented as a valid measurement.

Signalling uploadDone after a non-cancellation failure restarts the request over TCP; I tried that locally and the test then ran normally (total=672137216). Either retry the chunk this way or return the error. Reset the per-request counter as well, so bytes from a partially sent body are not counted twice.

❌ error — speedtest/helper.go:80, defs/server.go:669-672: HTTP/3 error text reaches stderr unsanitized

GetIPInfo returns the raw http.DefaultClient.Do error, and the caller prints it with output.WriteError("Failed to get IP info: %s\n", err). Over HTTP/3 that error carries peer-controlled text: quic-go formats ApplicationError as ...: <ErrorMessage> (qerr/errors.go:72-80), and the HTTP/3 connection error embeds it.

Confirmed the ESC byte survives into the returned error. A server closing with reason boom \x1b[2J forged produced:

Get "https://127.0.0.1:37175": http3: parsing frame failed: H3_NO_ERROR: boom \x1b[2J forged

h3Failure sanitizes only the copy the transport prints itself, not the error it returns. Sanitize at the sink (output.Sanitize(err.Error())), and audit the other sinks that can now receive transport errors: speedtest/helper.go:107,140,162,203,419.

💡 nit — speedtest/transport.go:311-315 and speedtest/transport.go:358: dialQUICAddrs can return (nil, nil)

I am downgrading this from ❌ to 💡 after re-checking reachability. errors.Join of an empty slice is nil, so an empty ips slice returns a nil connection and a nil error, and http3.newClientConn (http3/client.go:93) panics on it. I confirmed both halves: dialQUICAddrs(ctx, nil, "443", ...) returns conn=<nil> err=<nil>, and feeding that to http3.Transport.RoundTrip panics with a nil pointer dereference.

Correction to my 2026-11-17 review: this is not reachable through LookupIP. Both resolver paths error on an empty answer — the pure-Go path returns no such host (net/dnsclient_unix.go:255-267), and the cgo path adds nothing after which filterAddrList (net/ipsock.go:133-146) returns no suitable address found before LookupIP returns. I could only reach the nil result by calling the helper directly. So this is a latent trap for a future caller, not a live crash. Still worth guarding: return an explicit error when len(ips) == 0, and make dialQUICAddrs error when it made no connection and errs is empty.

💡 nit — speedtest/transport.go:269,288

ma is compared to the literal string "0", so ma=00 and ma="00" (both valid delta-seconds) are not treated as a withdrawal. The split on ; also happens before quoted strings are honored, so a quoted parameter such as note="x;ma=0" can falsely withdraw an alternative. Parse ma as a number and tokenize quoted-string parameters. Not a blocker.

What I verified

  • go test -count=1 ./..., go vet ./..., gofmt -l ., go test -race ./... at 9821b42: all pass with Go 1.26.8.
  • fd accounting, the direct empty-slice dial, upload-after-QUIC-drop, and the ESC-bearing error text were each reproduced with temporary tests that are not part of this branch. The worktree is clean.
  • Happy path over 1.1, 2, 3, and auto; the --json protocol field; CSV unchanged; the proxy guard; and TLS --ca-cert/--skip-cert-verify/SNI handling all behave as described.

@maddie

maddie commented Nov 20, 2026

Copy link
Copy Markdown
Collaborator

Status: this is the fourth review round, and three ❌ findings are still open. Four review turns on the same area is the point where I hand this to the maintainers rather than keep iterating.

Still open at 9821b42:

  1. speedtest/transport.go:341-352 — the UDP socket is never closed, one fd per QUIC attempt.
  2. defs/server.go:560-566,640 — a failed upload is dropped, and the run then reports zero bytes as a valid result. In auto mode this hides a broken HTTP/3 path.
  3. speedtest/helper.go:80 — HTTP/3 error text reaches stderr unsanitized; the ESC sequence survives.

@AlphaJack, if you want to keep going, the three fixes are small and local. If your time is limited, say so and I will take the branch over: the smallest mergeable version is forced --http-version 1.1|2|3 with auto's upgrade and fallback dropped to a follow-up PR, because all three errors live in the auto/h3-failure paths.

@adolfintel, this needs your call: keep waiting, ask for the reduced scope above, or have me finish it. Nothing here blocks a release — --http-version is new and opt-in, and auto is only the default for this branch, not for master.

- Close the UDP socket of every QUIC dial: quic-go closes only the ones it opened
- Retry an upload request that fails mid-test, without counting its bytes twice
- Fail the upload instead of reporting 0 Mbps when nothing was sent
- Sanitize network errors where the transport returns them and where they are printed
- Return an error, never a nil connection, from a dial with no address
- Treat ma=00 as a withdrawal, accept Clear and honour quoted Alt-Svc parameters
- Accept --http-version 1 as an alias of 1.1
@AlphaJack

Copy link
Copy Markdown
Author

Thanks for reproducing each finding. All of them are fixed in ee2ce32:

Finding Fix Test
❌ UDP socket never closed pc.Close() after tr.Close() on both paths TestDialQUICClosesItsSocket counts fds with GC off: 9 → 29 at 9821b42, flat now
❌ Failed upload dropped, 0 Mbps reported A failed request's bytes are taken back and a new request starts after 200 ms. If nothing was uploaded, Upload returns the error TestUploadRetriesAFailedRequest, TestUploadFailsWhenNothingIsUploaded
❌ Unsanitized error text The transport wraps every error and body read error in a sanitizing type, for test servers, the server list and telemetry. Unwrap keeps errors.Is. The sinks you listed and main.go's Terminated due to error sanitize too TestTransportSanitizesErrors
💡 (nil, nil) dial Errors on an empty address list in both functions TestDialQUICWithoutAddresses
💡 ma=00, quoted params, Clear ma parsed as a number, entries and params split outside quotes New cases in TestAdvertisesH3

Every new behaviour test fails at 9821b42 and passes at ee2ce32. go vet, go test and go test -race pass.

RFC 7838 spells clear case-sensitively. It is matched in any case here, since the only effect is staying on TCP.

The mid-connection UDP blackhole is now documented in the PR description as a known limit. The branch also accepts --http-version 1 as an alias of 1.1.

@AlphaJack
AlphaJack requested a review from maddie November 20, 2026 11:45

@BKPepe BKPepe 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 ran ee2ce32 against a local Go server (plain HTTP that decodes chunked
bodies, and a TLS variant with HTTP/2) and compared it with master 096d72a
on the same server. go vet ./... and go test ./... pass at ee2ce32 with
Go 1.27.4. I did not run -race.

--no-pre-allocate now under-reports the upload. With --no-download --no-pre-allocate and otherwise default flags, master reports 15397 Mbps and
bytes_sent 30.0 GB, and the server received 29.8 GB. ee2ce32 reports
368 Mbps and 0.72 GB while the server received 32.7 GB (a second run:
391 Mbps, 32.0 GB received). With --no-pre-allocate the body never ends, so
each request ends in the client's --timeout, 15 s by default. That is not
the end of the test, so the new code in Upload treats it as a failed request
and counter.Discount takes back everything it sent. What is left are the
replacement requests started just before the end. With --timeout 5 --duration 15 it reports 1929 Mbps for 32.0 GB received. One way out,
untested: do not take the bytes back when the error is the client timeout.

The retry itself works. In that last run master sends 3 requests and then
idles, this branch sends 12.

A question on the default. With --http-version auto and 2,
--concurrent 3 runs over one TCP connection, and with 1.1 over 7 (counted
by the server). On loopback, where the CPU is the limit, the same server gave
11.3 Gbps down and 14.5 Gbps up with 2, and 33.1 and 28.6 with 1.1.
Master behaves like auto here, so this is not new. But this PR makes the
version a choice, so it may be the place to decide what auto should prefer,
or at least to say in the help that under HTTP/2 the concurrent streams share
one connection. 5 of the 22 servers in the public list negotiated HTTP/2 when
I asked each ping URL once with curl.

With --no-pre-allocate the body never ends, so every request ends at
--timeout. Taking back the bytes of failed requests then dropped nearly
everything the server received: 0.49 GB reported for 22.7 GB received.
A retry sends new bytes, so nothing is counted twice.

The upload now fails only when no request got an answer and the last
error was not the client timeout, which means the body was still
streaming.

This branch has not been deployed

No deployments
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.

3 participants