puma-plus-core 0.1.0

data/go/internal/control/sim/sim_test.go

@@ -0,0 +1,300 @@
+package sim
+
+import (
+	"testing"
+	"time"
+
+	"github.com/evanphx/puma-plus/internal/control"
+)
+
+func ioBound() Workload {
+	return Workload{
+		ServiceMean: 25 * time.Millisecond,
+		ServiceCV:   0.8,
+		CPUFraction: 0.15, // database-bound: threads genuinely help
+	}
+}
+
+func cpuBound() Workload {
+	return Workload{
+		ServiceMean: 25 * time.Millisecond,
+		ServiceCV:   0.4,
+		CPUFraction: 0.95, // compute-bound: the GVL caps what threads can do
+	}
+}
+
+// TestSteadyLoadDoesNotChurn is the negative result that matters commercially.
+// An autoscaler that fidgets under steady load is a liability: every fork costs
+// memory and a cold cache, and the operator gets paged for a graph that wiggles.
+func TestSteadyLoadDoesNotChurn(t *testing.T) {
+	p := DefaultParams()
+	p.Workload = ioBound()
+	p.Workload.Phases = []Phase{{Duration: 5 * time.Minute, Rate: 100}}
+	p.Config.MinWorkers = 2
+	p.Config.ThreadsPerWorker = 5
+
+	r := Run(p)
+	t.Logf("steady 100rps/5min: %d spawns, %d retires, workers %d..%d, queue p95 %s",
+		r.Spawns, r.Retires, r.MinWorkers, r.MaxWorkers, r.QueueP95.Round(time.Millisecond))
+
+	if r.Spawns+r.Retires > 3 {
+		t.Errorf("churned under steady load: %d spawns, %d retires", r.Spawns, r.Retires)
+	}
+}
+
+// TestStepLoadRecovers is the headline scenario: a 10x step that a statically
+// sized server cannot absorb.
+func TestStepLoadRecovers(t *testing.T) {
+	p := DefaultParams()
+	p.Workload = ioBound()
+	p.Workload.Phases = []Phase{
+		{Duration: 60 * time.Second, Rate: 40},
+		{Duration: 120 * time.Second, Rate: 400},
+		{Duration: 60 * time.Second, Rate: 40},
+	}
+	p.Config.MinWorkers = 1
+	p.Config.MaxWorkers = 12
+	p.Config.ThreadsPerWorker = 5
+
+	r := Run(p)
+	t.Logf("step 40->400->40 rps: %d spawns, %d retires, peaked at %d workers",
+		r.Spawns, r.Retires, r.MaxWorkers)
+	t.Logf("  queue p50=%s p95=%s p99=%s max=%s  completed=%d shed=%d",
+		r.QueueP50.Round(time.Millisecond), r.QueueP95.Round(time.Millisecond),
+		r.QueueP99.Round(time.Millisecond), r.QueueMax.Round(time.Millisecond),
+		r.Completed, r.Shed)
+
+	if r.Spawns == 0 {
+		t.Fatal("never scaled up during a 10x step")
+	}
+	if r.MaxWorkers < 4 {
+		t.Errorf("only reached %d workers; 400rps at 25ms needs ~10 threads-worth of capacity",
+			r.MaxWorkers)
+	}
+
+	// Find how long the queue stayed over target after the step.
+	var overTarget int
+	for _, s := range r.Samples {
+		if s.T >= 60*time.Second && s.T < 180*time.Second && s.QueueP95 > p.Config.TargetQueueP95 {
+			overTarget++
+		}
+	}
+	t.Logf("  ticks over target during the loaded phase: %d of 120", overTarget)
+	if overTarget > 60 {
+		t.Errorf("queue stayed over target for %d of 120 loaded ticks; too slow to recover", overTarget)
+	}
+}
+
+// TestAutoscaleVsStatic is the honesty test the plan demands. Against a
+// statically peak-provisioned server the claim is NOT better latency -- it is
+// comparable latency at materially lower average cost.
+func TestAutoscaleVsStatic(t *testing.T) {
+	phases := []Phase{
+		{Duration: 60 * time.Second, Rate: 40},
+		{Duration: 120 * time.Second, Rate: 400},
+		{Duration: 120 * time.Second, Rate: 40},
+	}
+
+	run := func(min, max int) Result {
+		p := DefaultParams()
+		p.Workload = ioBound()
+		p.Workload.Phases = phases
+		p.Config.MinWorkers = min
+		p.Config.MaxWorkers = max
+		p.Config.ThreadsPerWorker = 5
+		return Run(p)
+	}
+
+	underProvisioned := run(2, 2) // sized for the average
+	peakProvisioned := run(12, 12)
+	autoscaled := run(1, 12)
+
+	for name, r := range map[string]Result{
+		"static-2  (sized for average)": underProvisioned,
+		"static-12 (sized for peak)":    peakProvisioned,
+		"autoscale 1..12":               autoscaled,
+	} {
+		t.Logf("%-30s queue p95=%-8s p99=%-8s completed=%-6d shed=%-5d worker-seconds=%.0f",
+			name, r.QueueP95.Round(time.Millisecond), r.QueueP99.Round(time.Millisecond),
+			r.Completed, r.Shed, r.WorkerSeconds)
+	}
+
+	// Claim 1: we beat the under-provisioned server on latency. This is the real
+	// win, because sizing for the average is what people actually do.
+	if autoscaled.QueueP95 >= underProvisioned.QueueP95 {
+		t.Errorf("autoscaling (p95 %s) did not beat the under-provisioned static server (p95 %s)",
+			autoscaled.QueueP95, underProvisioned.QueueP95)
+	}
+
+	// Claim 2: we cost materially less than peak provisioning. We do NOT claim
+	// to beat it on latency -- it has the capacity the whole time.
+	if autoscaled.WorkerSeconds >= peakProvisioned.WorkerSeconds*0.85 {
+		t.Errorf("autoscaling used %.0f worker-seconds vs %.0f for peak provisioning; "+
+			"the cost saving is the whole claim against that baseline",
+			autoscaled.WorkerSeconds, peakProvisioned.WorkerSeconds)
+	}
+}
+
+// TestCPUBoundStopsScaling is the negative result stated in the plan: past
+// hardware saturation, capacity cannot fix queue time, and a controller that
+// keeps forking is actively harmful -- it burns memory and worsens contention.
+//
+// Here the controller may reach its ceiling, but it must not thrash, and the
+// memory guard must be able to hold it.
+func TestCPUBoundRespectsMemoryLimit(t *testing.T) {
+	p := DefaultParams()
+	p.Workload = cpuBound()
+	p.Workload.Phases = []Phase{{Duration: 3 * time.Minute, Rate: 600}} // hopeless overload
+	p.Config.MinWorkers = 1
+	p.Config.MaxWorkers = 64
+	p.WorkerRSS = 200 << 20
+	p.Config.MemLimitBytes = 1 << 30 // 1GB => at most 5 workers
+
+	r := Run(p)
+	t.Logf("cpu-bound overload with a 1GB cap: peaked at %d workers, %d spawns, shed %d of %d",
+		r.MaxWorkers, r.Spawns, r.Shed, r.Shed+r.Completed)
+
+	if int64(r.MaxWorkers)*p.WorkerRSS > p.Config.MemLimitBytes+p.WorkerRSS {
+		t.Errorf("grew to %d workers (%dMB) past the %dMB limit",
+			r.MaxWorkers, int64(r.MaxWorkers)*p.WorkerRSS>>20, p.Config.MemLimitBytes>>20)
+	}
+	// Under hopeless overload, shedding must be doing the work that scaling
+	// cannot. A server that neither scales nor sheds just grows an unbounded
+	// queue.
+	if r.Shed == 0 {
+		t.Error("hopeless overload produced no shedding; latency would be unbounded")
+	}
+}
+
+// TestSpikesDoNotThrash: repeated short flash crowds must not produce a
+// spawn/retire cycle per spike.
+func TestSpikesDoNotThrash(t *testing.T) {
+	p := DefaultParams()
+	p.Workload = ioBound()
+	for i := 0; i < 8; i++ {
+		p.Workload.Phases = append(p.Workload.Phases,
+			Phase{Duration: 20 * time.Second, Rate: 50},
+			Phase{Duration: 10 * time.Second, Rate: 300},
+		)
+	}
+	p.Config.MinWorkers = 2
+	p.Config.MaxWorkers = 12
+
+	r := Run(p)
+	t.Logf("8 flash crowds over 4min: %d spawns, %d retires, workers %d..%d",
+		r.Spawns, r.Retires, r.MinWorkers, r.MaxWorkers)
+
+	if r.Spawns > 10 {
+		t.Errorf("thrashing across spikes: %d spawns for 8 spikes", r.Spawns)
+	}
+}
+
+// TestForkLatencyOvershoot checks behavior when dead time is large. A slow fork
+// is the classic way a naive controller overshoots: it keeps issuing spawns
+// while earlier ones are still booting. The settled gate should prevent that.
+func TestSlowForkDoesNotOvershoot(t *testing.T) {
+	p := DefaultParams()
+	p.Workload = ioBound()
+	p.Workload.Phases = []Phase{
+		{Duration: 30 * time.Second, Rate: 40},
+		{Duration: 90 * time.Second, Rate: 400},
+	}
+	p.ForkLatency = 8 * time.Second // a slow-booting Rails app
+	p.Config.MinWorkers = 1
+	p.Config.MaxWorkers = 20
+
+	r := Run(p)
+	t.Logf("8s fork latency: %d spawns, peaked at %d workers", r.Spawns, r.MaxWorkers)
+
+	// 400rps at 25ms needs ~10 threads = 2 workers of 5. Reaching far past that
+	// means the controller kept firing during dead time.
+	if r.MaxWorkers > 12 {
+		t.Errorf("overshot to %d workers with an 8s fork latency", r.MaxWorkers)
+	}
+}
+
+// TestDeterminism: the simulator must reproduce exactly, or a failure found
+// here cannot be debugged.
+func TestDeterminism(t *testing.T) {
+	p := DefaultParams()
+	p.Workload = ioBound()
+	p.Workload.Phases = []Phase{
+		{Duration: 30 * time.Second, Rate: 50},
+		{Duration: 30 * time.Second, Rate: 300},
+	}
+	p.Seed = 42
+
+	a, b := Run(p), Run(p)
+	if a.Completed != b.Completed || a.Spawns != b.Spawns || a.QueueP95 != b.QueueP95 {
+		t.Errorf("simulation is not deterministic:\n  %+v\n  %+v",
+			[]any{a.Completed, a.Spawns, a.QueueP95},
+			[]any{b.Completed, b.Spawns, b.QueueP95})
+	}
+}
+
+// TestTuningSweep runs a grid of plants and reports how the current tuning
+// behaves across it. Not a pass/fail gate on every cell -- it is the artifact
+// you read when changing a cooldown or a threshold, so the trade-off is visible
+// rather than guessed at.
+func TestTuningSweep(t *testing.T) {
+	t.Log("service  CV   fork    | spawns retires maxW  p95      shed")
+	t.Log("---------------------------------------------------------")
+	for _, service := range []time.Duration{5 * time.Millisecond, 25 * time.Millisecond, 100 * time.Millisecond} {
+		for _, cv := range []float64{0.3, 1.5} {
+			for _, fork := range []time.Duration{time.Second, 5 * time.Second} {
+				p := DefaultParams()
+				p.Workload = ioBound()
+				p.Workload.ServiceMean = service
+				p.Workload.ServiceCV = cv
+				p.ForkLatency = fork
+				p.Workload.Phases = []Phase{
+					{Duration: 30 * time.Second, Rate: 40},
+					{Duration: 90 * time.Second, Rate: 400},
+					{Duration: 60 * time.Second, Rate: 40},
+				}
+				p.Config.MinWorkers = 1
+				p.Config.MaxWorkers = 16
+
+				r := Run(p)
+				t.Logf("%-8s %-4.1f %-7s | %-6d %-7d %-5d %-8s %d",
+					service, cv, fork, r.Spawns, r.Retires, r.MaxWorkers,
+					r.QueueP95.Round(time.Millisecond), r.Shed)
+
+				if r.Spawns > 20 {
+					t.Errorf("service=%s cv=%.1f fork=%s: %d spawns is thrash",
+						service, cv, fork, r.Spawns)
+				}
+			}
+		}
+	}
+}
+
+// TestShedKeepsLatencyBounded: under hopeless overload the served requests must
+// still see bounded queue time. Converting a 30-second wait into an immediate
+// 503 is the point -- a request nobody will wait for is worse than no request.
+func TestShedKeepsServedLatencyBounded(t *testing.T) {
+	p := DefaultParams()
+	p.Workload = ioBound()
+	p.Workload.Phases = []Phase{{Duration: 2 * time.Minute, Rate: 2000}}
+	p.Config.MinWorkers = 1
+	p.Config.MaxWorkers = 4 // hard ceiling: cannot scale out of this
+
+	r := Run(p)
+	t.Logf("2000rps against at most 4 workers: completed=%d shed=%d queue p99=%s",
+		r.Completed, r.Shed, r.QueueP99.Round(time.Millisecond))
+
+	if r.Shed == 0 {
+		t.Fatal("no shedding under 2000rps with a 4-worker ceiling")
+	}
+	if r.QueueP99 > 5*time.Second {
+		t.Errorf("served requests saw p99 queue time of %s; shedding is not bounding latency",
+			r.QueueP99)
+	}
+}
+
+func TestShedLimitDerivation(t *testing.T) {
+	cfg := control.DefaultConfig()
+	if got, want := cfg.ShedLimit(), time.Second; got != want {
+		t.Errorf("ShedLimit() = %s, want %s for a 25ms target", got, want)
+	}
+}

data/go/internal/frontend/acceptor.go

@@ -0,0 +1,164 @@
+package frontend
+
+import (
+	"fmt"
+	"log"
+	"net"
+	"strconv"
+	"sync"
+
+	"github.com/evanphx/puma-plus/internal/queue"
+	"github.com/evanphx/puma-plus/internal/realtime"
+	"github.com/evanphx/puma-plus/internal/wire"
+)
+
+// Acceptor listens on the worker unix socket and registers Ruby worker threads
+// as they dial in.
+//
+// The inversion -- Ruby connects to Go rather than Go connecting to Ruby -- is
+// what gives us a real readiness signal. A thread appears here only after its
+// Rack app is loaded and callable, so there is nothing to poll for. Compare
+// puma-dev/dev/app.go:336-361, which dials a socket every 250ms and says in a
+// comment that it is "a poor substitute for getting an actual readiness signal".
+type Acceptor struct {
+	ln     net.Listener
+	reg    *queue.Registry
+	logger *log.Logger
+
+	mu       sync.Mutex
+	shepherd *ShepherdConn
+	hub      *realtime.Hub
+}
+
+// AttachHub enables the "ws" role, so workers can open outbound WebSocket
+// command channels.
+func (a *Acceptor) AttachHub(h *realtime.Hub) {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	a.hub = h
+}
+
+// Shepherd returns the attached control connection, or nil.
+func (a *Acceptor) Shepherd() *ShepherdConn {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	return a.shepherd
+}
+
+// NewAcceptor binds the worker socket. Any stale socket file at path is removed
+// first, since a crashed predecessor leaves one behind and bind would fail.
+func NewAcceptor(path string, reg *queue.Registry, logger *log.Logger) (*Acceptor, error) {
+	if err := removeStaleSocket(path); err != nil {
+		return nil, err
+	}
+	ln, err := net.Listen("unix", path)
+	if err != nil {
+		return nil, fmt.Errorf("listen on worker socket %s: %w", path, err)
+	}
+	if logger == nil {
+		logger = log.Default()
+	}
+	return &Acceptor{ln: ln, reg: reg, logger: logger}, nil
+}
+
+// Addr reports the bound socket path.
+func (a *Acceptor) Addr() string { return a.ln.Addr().String() }
+
+// Close stops accepting.
+func (a *Acceptor) Close() error { return a.ln.Close() }
+
+// Serve accepts worker connections until the listener is closed.
+func (a *Acceptor) Serve() error {
+	for {
+		nc, err := a.ln.Accept()
+		if err != nil {
+			return err
+		}
+		go a.handshake(nc)
+	}
+}
+
+// handshake reads the mandatory HELLO frame and registers the connection.
+func (a *Acceptor) handshake(nc net.Conn) {
+	r := wire.NewReader(nc)
+	typ, payload, err := r.ReadFrame()
+	if err != nil {
+		a.logger.Printf("worker handshake: %v", err)
+		nc.Close()
+		return
+	}
+	if typ != wire.TypeHello {
+		a.logger.Printf("worker handshake: expected HELLO, got %s", wire.TypeName(typ))
+		nc.Close()
+		return
+	}
+
+	pairs, _, err := wire.DecodeKV(payload)
+	if err != nil {
+		a.logger.Printf("worker handshake: bad HELLO payload: %v", err)
+		nc.Close()
+		return
+	}
+
+	fields := map[string]string{}
+	for _, p := range pairs {
+		fields[string(p.Key)] = string(p.Value)
+	}
+
+	if v := fields["version"]; v != wire.Version {
+		a.logger.Printf("worker handshake: protocol version %q, want %q", v, wire.Version)
+		nc.Close()
+		return
+	}
+
+	pid := atoiOr(fields["pid"], 0)
+
+	switch fields["role"] {
+	case "control":
+		// The shepherd. Registered separately from data conns: it is never
+		// capacity, and treating it as such would wedge a request against a peer
+		// that answers commands rather than requests.
+		sc := NewShepherdConn(nc, a.logger)
+		a.mu.Lock()
+		old := a.shepherd
+		a.shepherd = sc
+		a.mu.Unlock()
+		if old != nil {
+			old.Close()
+		}
+		a.logger.Printf("shepherd connected pid=%d", pid)
+		return
+	case "ws":
+		// The outbound WebSocket command channel. Not capacity: it carries
+		// commands from Ruby to the hub, never requests in the other direction.
+		if a.hub == nil {
+			a.logger.Printf("worker handshake: ws role but WebSockets are not enabled")
+			nc.Close()
+			return
+		}
+		a.logger.Printf("ws control channel connected pid=%d", pid)
+		go ServeWSControl(a.hub, nc, pid, a.logger)
+		return
+	case "data":
+		// fall through
+	default:
+		a.logger.Printf("worker handshake: unknown role %q", fields["role"])
+		nc.Close()
+		return
+	}
+
+	wid := atoiOr(fields["worker_id"], 0)
+	tidx := atoiOr(fields["thread_index"], 0)
+
+	conn := queue.NewConn(nc, pid, wid, tidx)
+	a.reg.Add(conn)
+	a.logger.Printf("worker ready pid=%d worker=%d thread=%d (capacity now %d)",
+		pid, wid, tidx, a.reg.Capacity())
+}
+
+func atoiOr(s string, def int) int {
+	if n, err := strconv.Atoi(s); err == nil {
+		return n
+	}
+	return def
+}

data/go/internal/frontend/altsvc.go

@@ -0,0 +1,57 @@
+package frontend
+
+import (
+	"fmt"
+	"net"
+	"net/http"
+	"strconv"
+)
+
+// AltSvcMaxAge is how long a client may cache the HTTP/3 advertisement.
+//
+// A day, matching what most deployments publish. The tradeoff is entirely about
+// how long a client keeps trying QUIC after h3 stops being offered: too long and
+// a server that dropped h3 keeps getting UDP attempts that fail and fall back;
+// too short and every client pays a TCP round trip to rediscover it.
+const AltSvcMaxAge = 86400
+
+// AltSvcHeader builds the Alt-Svc value advertising an HTTP/3 endpoint, given
+// the address the h3 listener is bound to.
+//
+// Only the port is advertised (`h3=":443"`), never the host. The address the
+// listener binds is frequently not the address a client should connect to --
+// 0.0.0.0 and 127.0.0.1 being the obvious cases -- and a port-only value means
+// "same host you already reached, this port", which is both correct and what
+// every deployment actually wants.
+func AltSvcHeader(h3Addr string) (string, error) {
+	_, port, err := net.SplitHostPort(h3Addr)
+	if err != nil {
+		return "", fmt.Errorf("parsing h3 address %q: %w", h3Addr, err)
+	}
+	if _, err := strconv.Atoi(port); err != nil {
+		return "", fmt.Errorf("h3 address %q has no numeric port", h3Addr)
+	}
+	return fmt.Sprintf(`h3=":%s"; ma=%d`, port, AltSvcMaxAge), nil
+}
+
+// withAltSvc advertises an HTTP/3 endpoint on every response.
+//
+// This is how a client finds h3 at all. ALPN cannot do it: ALPN negotiates
+// inside an established TLS handshake over TCP, and h3 lives on a different
+// transport entirely, so a client already connected over TCP has to be told to
+// come back on UDP. Without this header the h3 listener works perfectly and no
+// browser ever uses it.
+//
+// The header does not affect the response carrying it. The client caches it and
+// may use h3 on a *later* connection, so the first visit is always TCP. DNS
+// HTTPS/SVCB records (RFC 9460) are what remove that first round trip, and they
+// are published rather than served -- outside what a server can do for itself.
+//
+// Set before the handler runs so it survives whatever the handler writes, and
+// with Set rather than Add so a repeated pass cannot advertise twice.
+func withAltSvc(next http.Handler, value string) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Alt-Svc", value)
+		next.ServeHTTP(w, r)
+	})
+}

data/go/internal/frontend/altsvc_test.go

@@ -0,0 +1,170 @@
+package frontend
+
+import (
+	"context"
+	"crypto/tls"
+	"io"
+	"log"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/evanphx/puma-plus/internal/queue"
+	"github.com/evanphx/puma-plus/internal/wire"
+	"github.com/quic-go/quic-go"
+	"github.com/quic-go/quic-go/http3"
+	"golang.org/x/net/http2"
+)
+
+func TestAltSvcHeaderValue(t *testing.T) {
+	cases := []struct{ addr, want string }{
+		{"127.0.0.1:9443", `h3=":9443"; ma=86400`},
+		{"0.0.0.0:443", `h3=":443"; ma=86400`},
+		{":8443", `h3=":8443"; ma=86400`},
+		{"[::]:9443", `h3=":9443"; ma=86400`},
+	}
+	for _, tc := range cases {
+		got, err := AltSvcHeader(tc.addr)
+		if err != nil {
+			t.Errorf("AltSvcHeader(%q): %v", tc.addr, err)
+			continue
+		}
+		if got != tc.want {
+			t.Errorf("AltSvcHeader(%q) = %q, want %q", tc.addr, got, tc.want)
+		}
+	}
+
+	// The bind address is not the connect address. Advertising 0.0.0.0 or a
+	// loopback host would send clients somewhere they cannot reach, so only the
+	// port is ever emitted.
+	for _, addr := range []string{"0.0.0.0:9443", "127.0.0.1:9443"} {
+		got, _ := AltSvcHeader(addr)
+		if strings.Contains(got, "0.0.0.0") || strings.Contains(got, "127.0.0.1") {
+			t.Errorf("AltSvcHeader(%q) leaked the bind host: %q", addr, got)
+		}
+	}
+
+	for _, bad := range []string{"", "9443", "localhost", "127.0.0.1:http"} {
+		if _, err := AltSvcHeader(bad); err == nil {
+			t.Errorf("AltSvcHeader(%q) should have failed", bad)
+		}
+	}
+}
+
+// TestAltSvcAdvertisedOnlyWhereItIsTrusted is the whole point of the header: a
+// browser reaching the TLS listener has no other way to learn h3 exists, since
+// ALPN cannot cross transports.
+//
+// And it must NOT come from the cleartext listener. That origin is http://, so
+// the advertisement is cross-origin and ignored, and a client is right to
+// distrust an unauthenticated connection telling it where to go next.
+func TestAltSvcAdvertisedOnlyWhereItIsTrusted(t *testing.T) {
+	reg := queue.NewRegistry(16)
+	newProtoWorker(t, reg, func(_ wire.RequestMeta, _ map[string]string) {})
+	time.Sleep(20 * time.Millisecond)
+
+	h := NewHandler(reg, Options{
+		Logger:         log.New(io.Discard, "", 0),
+		AcquireTimeout: 5 * time.Second,
+	})
+	cert, err := DevCertificate("localhost")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	h1Addr, tlsAddr, h3Addr := freeTCP(t), freeTCP(t), freeUDP(t)
+	ls, err := Start(ListenerOptions{
+		Handler: h, Logger: log.New(io.Discard, "", 0),
+		Addr: h1Addr, TLSAddr: tlsAddr, H3Addr: h3Addr, Cert: cert,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer ls.Shutdown(context.Background())
+	time.Sleep(300 * time.Millisecond)
+
+	wantPort := h3Addr[strings.LastIndex(h3Addr, ":")+1:]
+
+	t.Run("tls listener advertises h3", func(t *testing.T) {
+		c := &http.Client{Transport: &http2.Transport{
+			TLSClientConfig: &tls.Config{InsecureSkipVerify: true, NextProtos: []string{"h2"}},
+		}}
+		got := headerOf(t, c, "https://"+tlsAddr+"/hello", "Alt-Svc")
+		if !strings.Contains(got, `h3=":`+wantPort+`"`) {
+			t.Errorf("Alt-Svc = %q, want it to advertise h3 on port %s", got, wantPort)
+		}
+		if !strings.Contains(got, "ma=") {
+			t.Errorf("Alt-Svc = %q, missing the max-age a client caches by", got)
+		}
+	})
+
+	t.Run("h3 listener refreshes the advertisement", func(t *testing.T) {
+		c := &http.Client{Transport: &http3.Transport{
+			TLSClientConfig: &tls.Config{InsecureSkipVerify: true, NextProtos: []string{http3.NextProtoH3}},
+			QUICConfig:      &quic.Config{MaxIdleTimeout: 10 * time.Second},
+		}}
+		if got := headerOf(t, c, "https://"+h3Addr+"/hello", "Alt-Svc"); got == "" {
+			t.Error("h3 responses carry no Alt-Svc; a client's cached entry would " +
+				"expire and force it back to TCP to rediscover h3")
+		}
+	})
+
+	t.Run("cleartext listener does not", func(t *testing.T) {
+		c := &http.Client{Transport: &http.Transport{ForceAttemptHTTP2: false}}
+		if got := headerOf(t, c, "http://"+h1Addr+"/hello", "Alt-Svc"); got != "" {
+			t.Errorf("cleartext listener advertised Alt-Svc = %q; the origin is "+
+				"http:// so it is cross-origin and untrusted", got)
+		}
+	})
+}
+
+// TestNoAltSvcWithoutH3: advertising an endpoint that is not listening would
+// make every client waste a QUIC attempt and fall back.
+func TestNoAltSvcWithoutH3(t *testing.T) {
+	reg := queue.NewRegistry(16)
+	newProtoWorker(t, reg, func(_ wire.RequestMeta, _ map[string]string) {})
+	time.Sleep(20 * time.Millisecond)
+
+	h := NewHandler(reg, Options{
+		Logger:         log.New(io.Discard, "", 0),
+		AcquireTimeout: 5 * time.Second,
+	})
+	cert, err := DevCertificate("localhost")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	tlsAddr := freeTCP(t)
+	ls, err := Start(ListenerOptions{
+		Handler: h, Logger: log.New(io.Discard, "", 0),
+		TLSAddr: tlsAddr, Cert: cert, // no H3Addr
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer ls.Shutdown(context.Background())
+	time.Sleep(300 * time.Millisecond)
+
+	c := &http.Client{Transport: &http2.Transport{
+		TLSClientConfig: &tls.Config{InsecureSkipVerify: true, NextProtos: []string{"h2"}},
+	}}
+	if got := headerOf(t, c, "https://"+tlsAddr+"/hello", "Alt-Svc"); got != "" {
+		t.Errorf("advertised Alt-Svc = %q with no h3 listener running", got)
+	}
+}
+
+func headerOf(t *testing.T, c *http.Client, url, header string) string {
+	t.Helper()
+	req, err := http.NewRequest(http.MethodGet, url, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	resp, err := c.Do(req)
+	if err != nil {
+		t.Fatalf("GET %s: %v", url, err)
+	}
+	defer resp.Body.Close()
+	io.Copy(io.Discard, resp.Body)
+	return resp.Header.Get(header)
+}