internal/http3: add Transport and ClientConn

Add the first rudiments of an HTTP/3 client.

The client currently opens a QUIC connection and creates a control
stream on it, and nothing else.

Add surrounding test infrastructure for examining the client's
behavior. Tests use the experimental testing/synctest package
and will only run when the Go version is at least Go 1.24 and
GOEXPERIMENT=synctest is set.

For golang/go#70914

Change-Id: I19803187a8e62c461f60d7a1d44c2a408377e342
Reviewed-on: https://go-review.googlesource.com/c/net/+/642516
Reviewed-by: Jonathan Amsterdam <[email protected]>
Auto-Submit: Damien Neil <[email protected]>
Reviewed-by: Brad Fitzpatrick <[email protected]>
LUCI-TryBot-Result: Go LUCI <[email protected]>

Author: neild

Diff for: internal/http3/http3_test.go

@@ -0,0 +1,59 @@
+// Copyright 2024 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+//go:build go1.24 && goexperiment.synctest
+
+package http3
+
+import (
+	"os"
+	"slices"
+	"testing"
+	"testing/synctest"
+)
+
+func init() {
+	// testing/synctest requires asynctimerchan=0 (the default as of Go 1.23),
+	// but the x/net go.mod is currently selecting go1.18.
+	//
+	// Set asynctimerchan=0 explicitly.
+	//
+	// TODO: Remove this when the x/net go.mod Go version is >= go1.23.
+	os.Setenv("GODEBUG", os.Getenv("GODEBUG")+",asynctimerchan=0")
+}
+
+// runSynctest runs f in a synctest.Run bubble.
+// It arranges for t.Cleanup functions to run within the bubble.
+func runSynctest(t *testing.T, f func(t testing.TB)) {
+	synctest.Run(func() {
+		ct := &cleanupT{T: t}
+		defer ct.done()
+		f(ct)
+	})
+}
+
+// runSynctestSubtest runs f in a subtest in a synctest.Run bubble.
+func runSynctestSubtest(t *testing.T, name string, f func(t testing.TB)) {
+	t.Run(name, func(t *testing.T) {
+		runSynctest(t, f)
+	})
+}
+
+// cleanupT wraps a testing.T and adds its own Cleanup method.
+// Used to execute cleanup functions within a synctest bubble.
+type cleanupT struct {
+	*testing.T
+	cleanups []func()
+}
+
+// Cleanup replaces T.Cleanup.
+func (t *cleanupT) Cleanup(f func()) {
+	t.cleanups = append(t.cleanups, f)
+}
+
+func (t *cleanupT) done() {
+	for _, f := range slices.Backward(t.cleanups) {
+		f()
+	}
+}

Diff for: internal/http3/settings.go

@@ -0,0 +1,73 @@
+// Copyright 2025 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+//go:build go1.24
+
+package http3
+
+import (
+	"golang.org/x/net/internal/quic/quicwire"
+	"golang.org/x/net/quic"
+)
+
+const (
+	// https://www.rfc-editor.org/rfc/rfc9114.html#section-7.2.4.1
+	settingsMaxFieldSectionSize = 0x06
+
+	// https://www.rfc-editor.org/rfc/rfc9204.html#section-5
+	settingsQPACKMaxTableCapacity = 0x01
+	settingsQPACKBlockedStreams   = 0x07
+)
+
+// writeSettings writes a complete SETTINGS frame.
+// Its parameter is a list of alternating setting types and values.
+func (st *stream) writeSettings(settings ...int64) {
+	var size int64
+	for _, s := range settings {
+		// Settings values that don't fit in a QUIC varint ([0,2^62)) will panic here.
+		size += int64(quicwire.SizeVarint(uint64(s)))
+	}
+	st.writeVarint(int64(frameTypeSettings))
+	st.writeVarint(size)
+	for _, s := range settings {
+		st.writeVarint(s)
+	}
+}
+
+// readSettings reads a complete SETTINGS frame, including the frame header.
+func (st *stream) readSettings(f func(settingType, value int64) error) error {
+	frameType, err := st.readFrameHeader()
+	if err != nil || frameType != frameTypeSettings {
+		return &quic.ApplicationError{
+			Code:   uint64(errH3MissingSettings),
+			Reason: "settings not sent on control stream",
+		}
+	}
+	for st.lim > 0 {
+		settingsType, err := st.readVarint()
+		if err != nil {
+			return err
+		}
+		settingsValue, err := st.readVarint()
+		if err != nil {
+			return err
+		}
+
+		// Use of HTTP/2 settings where there is no corresponding HTTP/3 setting
+		// is an error.
+		// https://www.rfc-editor.org/rfc/rfc9114.html#section-7.2.4.1-5
+		switch settingsType {
+		case 0x02, 0x03, 0x04, 0x05:
+			return &quic.ApplicationError{
+				Code:   uint64(errH3SettingsError),
+				Reason: "use of reserved setting",
+			}
+		}
+
+		if err := f(settingsType, settingsValue); err != nil {
+			return err
+		}
+	}
+	return st.endFrame()
+}

Diff for: internal/http3/stream.go

@@ -7,6 +7,7 @@
 package http3
 
 import (
+	"context"
 	"io"
 
 	"golang.org/x/net/quic"
@@ -24,6 +25,36 @@ type stream struct {
 	lim int64
 }
 
+// newConnStream creates a new stream on a connection.
+// It writes the stream header for unidirectional streams.
+//
+// The stream returned by newStream is not flushed,
+// and will not be sent to the peer until the caller calls
+// Flush or writes enough data to the stream.
+func newConnStream(ctx context.Context, qconn *quic.Conn, stype streamType) (*stream, error) {
+	var qs *quic.Stream
+	var err error
+	if stype == streamTypeRequest {
+		// Request streams are bidirectional.
+		qs, err = qconn.NewStream(ctx)
+	} else {
+		// All other streams are unidirectional.
+		qs, err = qconn.NewSendOnlyStream(ctx)
+	}
+	if err != nil {
+		return nil, err
+	}
+	st := &stream{
+		stream: qs,
+		lim:    -1, // no limit
+	}
+	if stype != streamTypeRequest {
+		// Unidirectional stream header.
+		st.writeVarint(int64(stype))
+	}
+	return st, err
+}
+
 func newStream(qs *quic.Stream) *stream {
 	return &stream{
 		stream: qs,
@@ -106,6 +137,41 @@ func (st *stream) Read(b []byte) (int, error) {
 	return n, nil
 }
 
+// discardUnknownFrame discards an unknown frame.
+//
+// HTTP/3 requires that unknown frames be ignored on all streams.
+// However, a known frame appearing in an unexpected place is a fatal error,
+// so this returns an error if the frame is one we know.
+func (st *stream) discardUnknownFrame(ftype frameType) error {
+	switch ftype {
+	case frameTypeData,
+		frameTypeHeaders,
+		frameTypeCancelPush,
+		frameTypeSettings,
+		frameTypePushPromise,
+		frameTypeGoaway,
+		frameTypeMaxPushID:
+		return &quic.ApplicationError{
+			Code:   uint64(errH3FrameUnexpected),
+			Reason: "unexpected " + ftype.String() + " frame",
+		}
+	}
+	return st.discardFrame()
+}
+
+// discardFrame discards any remaining data in the current frame and resets the read limit.
+func (st *stream) discardFrame() error {
+	// TODO: Consider adding a *quic.Stream method to discard some amount of data.
+	for range st.lim {
+		_, err := st.stream.ReadByte()
+		if err != nil {
+			return errH3FrameError
+		}
+	}
+	st.lim = -1
+	return nil
+}
+
 // Write writes to the stream.
 func (st *stream) Write(b []byte) (int, error) { return st.stream.Write(b) }
 

Diff for: internal/http3/stream_test.go

@@ -243,6 +243,26 @@ func TestStreamReadByte(t *testing.T) {
 	}
 }
 
+func TestStreamDiscardFrame(t *testing.T) {
+	const typ = 10
+	data := []byte("hello")
+	st1, st2 := newStreamPair(t)
+	st1.writeVarint(typ)              // type
+	st1.writeVarint(int64(len(data))) // size
+	st1.Write(data)                   // data
+	st1.stream.CloseWrite()
+
+	if got, err := st2.readFrameHeader(); err != nil || got != typ {
+		t.Fatalf("st.readFrameHeader() = %v, %v; want %v, nil", got, err, typ)
+	}
+	if err := st2.discardFrame(); err != nil {
+		t.Fatalf("st.discardFrame() = %v", err)
+	}
+	if b, err := io.ReadAll(st2); err != nil || len(b) > 0 {
+		t.Fatalf("after discarding frame, read %x, %v; want EOF", b, err)
+	}
+}
+
 func newStreamPair(t *testing.T) (s1, s2 *stream) {
 	t.Helper()
 	q1, q2 := newQUICStreamPair(t)