http3: split H3Client into h3_client/ + Alt-Svc upgrade flag

src/bun.js.zig

@@ -106,6 +106,7 @@ pub const Run = struct {
         jsc.VirtualMachine.is_main_thread_vm = true;
 
         bun.http.experimental_http2_client_from_cli = ctx.runtime_options.experimental_http2_fetch;
+        bun.http.experimental_http3_client_from_cli = ctx.runtime_options.experimental_http3_fetch;
         doPreconnect(ctx.runtime_options.preconnect);
 
         const callback = OpaqueWrap(Run, Run.start);
@@ -292,6 +293,7 @@ pub const Run = struct {
         vm.transpiler.env.loadTracy();
 
         bun.http.experimental_http2_client_from_cli = ctx.runtime_options.experimental_http2_fetch;
+        bun.http.experimental_http3_client_from_cli = ctx.runtime_options.experimental_http3_fetch;
         doPreconnect(ctx.runtime_options.preconnect);
 
         vm.main_is_html_entrypoint = (loader orelse vm.transpiler.options.loader(std.fs.path.extension(entry_path))) == .html;

src/cli.zig

@@ -409,6 +409,7 @@ pub const Command = struct {
         } = .{},
         preconnect: []const []const u8 = &[_][]const u8{},
         experimental_http2_fetch: bool = false,
+        experimental_http3_fetch: bool = false,
         dns_result_order: []const u8 = "verbatim",
         /// `--expose-gc` makes `globalThis.gc()` available. Added for Node
         /// compatibility.

src/cli/Arguments.zig

@@ -109,6 +109,7 @@ pub const runtime_params_ = [_]ParamType{
     clap.parseParam("--conditions <STR>...             Pass custom conditions to resolve") catch unreachable,
     clap.parseParam("--fetch-preconnect <STR>...       Preconnect to a URL while code is loading") catch unreachable,
     clap.parseParam("--experimental-http2-fetch        Offer h2 in fetch() TLS ALPN. Same as BUN_FEATURE_FLAG_EXPERIMENTAL_HTTP2_CLIENT=1") catch unreachable,
+    clap.parseParam("--experimental-http3-fetch        Honor Alt-Svc: h3 in fetch() and upgrade to HTTP/3. Same as BUN_FEATURE_FLAG_EXPERIMENTAL_HTTP3_CLIENT=1") catch unreachable,
     clap.parseParam("--max-http-header-size <INT>      Set the maximum size of HTTP headers in bytes. Default is 16KiB") catch unreachable,
     clap.parseParam("--dns-result-order <STR>          Set the default order of DNS lookup results. Valid orders: verbatim (default), ipv4first, ipv6first") catch unreachable,
     clap.parseParam("--expose-gc                       Expose gc() on the global object. Has no effect on Bun.gc().") catch unreachable,
@@ -880,6 +881,7 @@ pub fn parse(allocator: std.mem.Allocator, ctx: Command.Context, comptime cmd: C
         ctx.runtime_options.smol = args.flag("--smol");
         ctx.runtime_options.preconnect = args.options("--fetch-preconnect");
         ctx.runtime_options.experimental_http2_fetch = args.flag("--experimental-http2-fetch");
+        ctx.runtime_options.experimental_http3_fetch = args.flag("--experimental-http3-fetch");
         ctx.runtime_options.expose_gc = args.flag("--expose-gc");
 
         if (args.option("--console-depth")) |depth_str| {

src/cli/test/parallel/runner.zig

@@ -229,6 +229,8 @@ fn buildWorkerArgv(arena: std.mem.Allocator, ctx: Command.Context) ![:null]?[*:0
         try argv.append(arena, "--smol");
     if (ctx.runtime_options.experimental_http2_fetch)
         try argv.append(arena, "--experimental-http2-fetch");
+    if (ctx.runtime_options.experimental_http3_fetch)
+        try argv.append(arena, "--experimental-http3-fetch");
     if (ctx.args.allow_addons == false)
         try argv.append(arena, "--no-addons");
     if (ctx.debug.macros == .disable)

src/cli/test_command.zig

@@ -1496,6 +1496,7 @@ pub const TestCommand = struct {
         vm.preload = ctx.preloads;
         vm.transpiler.options.rewrite_jest_for_tests = true;
         bun.http.experimental_http2_client_from_cli = ctx.runtime_options.experimental_http2_fetch;
+        bun.http.experimental_http3_client_from_cli = ctx.runtime_options.experimental_http3_fetch;
         vm.transpiler.options.env.behavior = .load_all_without_inlining;
 
         const node_env_entry = try env_loader.map.getOrPutWithoutValue("NODE_ENV");

src/env_var.zig

@@ -193,6 +193,11 @@ pub const feature_flag = struct {
     /// server selects it. Off by default while the client implementation
     /// matures. `--experimental-http2-fetch` is the CLI equivalent.
     pub const BUN_FEATURE_FLAG_EXPERIMENTAL_HTTP2_CLIENT = newFeatureFlag("BUN_FEATURE_FLAG_EXPERIMENTAL_HTTP2_CLIENT", .{});
+    /// Honor `Alt-Svc: h3` from fetch() responses: subsequent requests to the
+    /// same origin go over QUIC/HTTP-3 instead of TCP. Off by default while
+    /// the client implementation matures. `--experimental-http3-fetch` is the
+    /// CLI equivalent.
+    pub const BUN_FEATURE_FLAG_EXPERIMENTAL_HTTP3_CLIENT = newFeatureFlag("BUN_FEATURE_FLAG_EXPERIMENTAL_HTTP3_CLIENT", .{});
     pub const BUN_FEATURE_FLAG_FORCE_IO_POOL = newFeatureFlag("BUN_FEATURE_FLAG_FORCE_IO_POOL", .{});
     pub const BUN_FEATURE_FLAG_FORCE_WINDOWS_JUNCTIONS = newFeatureFlag("BUN_FEATURE_FLAG_FORCE_WINDOWS_JUNCTIONS", .{});
     pub const BUN_INSTRUMENTS = newFeatureFlag("BUN_INSTRUMENTS", .{});

src/http.zig

@@ -12,6 +12,9 @@ pub var async_http_id_monotonic: std.atomic.Value(u32) = std.atomic.Value(u32).i
 /// Set once at startup from `--experimental-http2-fetch` (before the HTTP
 /// thread spawns) and then only read on that thread, so no atomics needed.
 pub var experimental_http2_client_from_cli: bool = false;
+/// Set once at startup from `--experimental-http3-fetch`. Same threading
+/// rules as the http2 flag.
+pub var experimental_http3_client_from_cli: bool = false;
 
 const MAX_REDIRECT_URL_LENGTH = 128 * 1024;
 
@@ -228,6 +231,28 @@ pub fn alpnOffer(client: *const HTTPClient) BoringSSL.SSL.AlpnOffer {
     return if (client.flags.force_http2) .h2_only else .h1_or_h2;
 }
 
+/// Whether the experimental Alt-Svc-driven HTTP/3 upgrade is enabled at all
+/// (CLI flag or env var). Used on its own to gate `H3.AltSvc.record` — a
+/// response that arrived over a request shape h3 can't serve (proxy, sendfile,
+/// `force_http1`) still carries an authoritative Alt-Svc for the origin.
+pub fn h3AltSvcEnabled() bool {
+    return experimental_http3_client_from_cli or
+        bun.feature_flag.BUN_FEATURE_FLAG_EXPERIMENTAL_HTTP3_CLIENT.get();
+}
+
+/// Whether this request shape is eligible to *use* a cached Alt-Svc h3
+/// alternative (HTTPS, no proxy/unix-socket, no sendfile, not pinned to a
+/// specific protocol). When true, `start_()` consults `H3.AltSvc.lookup`
+/// before opening TCP.
+pub fn canTryH3AltSvc(client: *const HTTPClient) bool {
+    if (client.flags.force_http1 or client.flags.force_http2) return false;
+    if (client.http_proxy != null) return false;
+    if (client.flags.is_preconnect_only) return false;
+    if (client.unix_socket_path.length() > 0) return false;
+    if (client.state.original_request_body == .sendfile) return false;
+    return h3AltSvcEnabled();
+}
+
 pub fn firstCall(
     client: *HTTPClient,
     comptime is_ssl: bool,
@@ -1180,6 +1205,28 @@ fn start_(this: *HTTPClient, comptime is_ssl: bool) void {
         }
     }
 
+    if (comptime is_ssl) {
+        // Opportunistic Alt-Svc upgrade: a previous response from this origin
+        // advertised `h3`, and the experimental flag is on. Don't touch
+        // `flags.force_http3` — that's the user's explicit `protocol:"http3"`
+        // choice and persists across redirects, whereas an Alt-Svc upgrade is
+        // per-origin and a cross-origin redirect must re-evaluate from h1.
+        // `doRedirectMultiplexed` resets `flags.protocol`, so the redirected
+        // request lands back here with `force_http3` still false and consults
+        // the cache for the new origin.
+        if (!this.flags.force_http3 and this.canTryH3AltSvc()) {
+            if (H3.AltSvc.lookup(this.url.hostname, this.url.getPortAuto())) |alt_port| {
+                if (H3.ClientContext.getOrCreate(http_thread.loop.loop)) |ctx| {
+                    if (!ctx.connect(this, this.url.hostname, alt_port)) {
+                        this.fail(error.ConnectionRefused);
+                    }
+                    return;
+                }
+                // engine init failed: fall through to TCP
+            }
+        }
+    }
+
     if (this.flags.force_http3) {
         if (comptime !is_ssl) {
             this.fail(error.HTTP3Unsupported);
@@ -2803,6 +2850,14 @@ pub fn handleResponseMetadata(
             hashHeaderConst("Last-Modified") => {
                 pretend_304 = this.flags.force_last_modified and response.status_code > 199 and response.status_code < 300 and this.if_modified_since.len > 0 and strings.eql(this.if_modified_since, header.value);
             },
+            hashHeaderConst("Alt-Svc") => {
+                // Record regardless of *this* request's shape — a future
+                // request to the same origin may be h3-eligible even if this
+                // one was pinned/proxied/sendfile.
+                if (this.isHTTPS() and this.unix_socket_path.length() == 0 and h3AltSvcEnabled()) {
+                    H3.AltSvc.record(this.url.hostname, this.url.getPortAuto(), header.value);
+                }
+            },
 
             else => {},
         }