http3

package
v3.55.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 8, 2025 License: MIT Imports: 29 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// MethodGet0RTT allows a GET request to be sent using 0-RTT.
	// Note that 0-RTT doesn't provide replay protection and should only be used for idempotent requests.
	MethodGet0RTT = "GET_0RTT"
	// MethodHead0RTT allows a HEAD request to be sent using 0-RTT.
	// Note that 0-RTT doesn't provide replay protection and should only be used for idempotent requests.
	MethodHead0RTT = "HEAD_0RTT"
)
View Source 
const (
	VersionUnknown quic.Version = math.MaxUint32

	Version1 quic.Version = 0x1
	Version2 quic.Version = 0x6b3343cf
)

The version numbers, making grepping easier

View Source 
const InvalidStreamID quic.StreamID = -1

InvalidPacketNumber is a stream ID that is invalid. The first valid stream ID in QUIC is 0.

View Source 
const NextProtoH3 = "h3"

NextProtoH3 is the ALPN protocol negotiated during the TLS handshake, for QUIC v1 and v2.

Variables

View Source 
var ErrNoCachedConn = errors.New("http3: no cached connection was available")

ErrNoCachedConn is returned when Transport.OnlyCachedConn is set

View Source 
var SupportedVersions = []quic.Version{Version1, Version2}

SupportedVersions lists the versions that the server supports must be in sorted descending order

Functions

This section is empty.

Types

type ClientConn added in v3.51.0 

type ClientConn struct {
	*transport.Options
	// contains filtered or unexported fields
}

ClientConn is an HTTP/3 client doing requests to a single remote server.

func (*ClientConn) CloseWithError added in v3.51.0 

func (c *ClientConn) CloseWithError(code ErrCode, msg string) error

CloseWithError closes the connection with the given error code and message. It is invalid to call this function after the connection was closed.

func (*ClientConn) Conn added in v3.54.0 

func (c *ClientConn) Conn() *Conn

Conn returns the underlying HTTP/3 connection. This method is only useful for advanced use cases, such as when the application needs to open streams on the HTTP/3 connection (e.g. WebTransport).

func (*ClientConn) Context added in v3.51.0 

func (c *ClientConn) Context() context.Context

Context returns a context that is cancelled when the connection is closed.

func (*ClientConn) OpenRequestStream added in v3.51.0 

func (c *ClientConn) OpenRequestStream(ctx context.Context) (*RequestStream, error)

OpenRequestStream opens a new request stream on the HTTP/3 connection.

func (*ClientConn) ReceivedSettings added in v3.51.0 

func (c *ClientConn) ReceivedSettings() <-chan struct{}

ReceivedSettings returns a channel that is closed once the server's HTTP/3 settings were received. Settings can be obtained from the Settings method after the channel was closed.

func (*ClientConn) RoundTrip added in v3.51.0 

func (c *ClientConn) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip executes a request and returns a response

func (*ClientConn) Settings added in v3.51.0 

func (c *ClientConn) Settings() *Settings

Settings returns the HTTP/3 settings for this connection. It is only valid to call this function after the channel returned by ReceivedSettings was closed.

type Conn added in v3.54.0 

type Conn struct {
	*transport.Options
	// contains filtered or unexported fields
}

Conn is an HTTP/3 connection. It has all methods from the quic.Conn expect for AcceptStream, AcceptUniStream, SendDatagram and ReceiveDatagram.

func (*Conn) CloseWithError added in v3.54.0 

func (c *Conn) CloseWithError(code quic.ApplicationErrorCode, msg string) error

func (*Conn) ConnectionState added in v3.54.0 

func (c *Conn) ConnectionState() quic.ConnectionState

func (*Conn) Context added in v3.54.0 

func (c *Conn) Context() context.Context

Context returns the context of the underlying QUIC connection.

func (*Conn) HandshakeComplete added in v3.54.0 

func (c *Conn) HandshakeComplete() <-chan struct{}

func (*Conn) LocalAddr added in v3.54.0 

func (c *Conn) LocalAddr() net.Addr

func (*Conn) OpenStream added in v3.54.0 

func (c *Conn) OpenStream() (*quic.Stream, error)

func (*Conn) OpenStreamSync added in v3.54.0 

func (c *Conn) OpenStreamSync(ctx context.Context) (*quic.Stream, error)

func (*Conn) OpenUniStream added in v3.54.0 

func (c *Conn) OpenUniStream() (*quic.SendStream, error)

func (*Conn) OpenUniStreamSync added in v3.54.0 

func (c *Conn) OpenUniStreamSync(ctx context.Context) (*quic.SendStream, error)

func (*Conn) ReceivedSettings added in v3.54.0 

func (c *Conn) ReceivedSettings() <-chan struct{}

ReceivedSettings returns a channel that is closed once the peer's SETTINGS frame was received. Settings can be optained from the Settings method after the channel was closed.

func (*Conn) RemoteAddr added in v3.54.0 

func (c *Conn) RemoteAddr() net.Addr

func (*Conn) Settings added in v3.54.0 

func (c *Conn) Settings() *Settings

Settings returns the settings received on this connection. It is only valid to call this function after the channel returned by ReceivedSettings was closed.

type ErrCode added in v3.42.3 

type ErrCode quic.ApplicationErrorCode
const (
	ErrCodeNoError              ErrCode = 0x100
	ErrCodeGeneralProtocolError ErrCode = 0x101
	ErrCodeInternalError        ErrCode = 0x102
	ErrCodeStreamCreationError  ErrCode = 0x103
	ErrCodeClosedCriticalStream ErrCode = 0x104
	ErrCodeFrameUnexpected      ErrCode = 0x105
	ErrCodeFrameError           ErrCode = 0x106
	ErrCodeExcessiveLoad        ErrCode = 0x107
	ErrCodeIDError              ErrCode = 0x108
	ErrCodeSettingsError        ErrCode = 0x109
	ErrCodeMissingSettings      ErrCode = 0x10a
	ErrCodeRequestRejected      ErrCode = 0x10b
	ErrCodeRequestCanceled      ErrCode = 0x10c
	ErrCodeRequestIncomplete    ErrCode = 0x10d
	ErrCodeMessageError         ErrCode = 0x10e
	ErrCodeConnectError         ErrCode = 0x10f
	ErrCodeVersionFallback      ErrCode = 0x110
	ErrCodeDatagramError        ErrCode = 0x33
)

func (ErrCode) String added in v3.42.3 

func (e ErrCode) String() string

type Error added in v3.42.3 

type Error struct {
	Remote       bool
	ErrorCode    ErrCode
	ErrorMessage string
}

Error is returned from the round tripper (for HTTP clients) and inside the HTTP handler (for HTTP servers) if an HTTP/3 error occurs. See section 8 of RFC 9114.

func (*Error) Error added in v3.42.3 

func (e *Error) Error() string

func (*Error) Is added in v3.51.0 

func (e *Error) Is(target error) bool

type FrameType 

type FrameType uint64

FrameType is the frame type of a HTTP/3 frame

type Hijacker 

type Hijacker interface {
	Connection() *Conn
}

A Hijacker allows hijacking of the stream creating part of a quic.Conn from a http.ResponseWriter. It is used by WebTransport to create WebTransport streams after a session has been established.

type Perspective added in v3.46.0 

type Perspective int

Perspective determines if we're acting as a server or a client 

const (
	PerspectiveServer Perspective = 1
	PerspectiveClient Perspective = 2
)

the perspectives

func (Perspective) Opposite added in v3.46.0 

func (p Perspective) Opposite() Perspective

Opposite returns the perspective of the peer

func (Perspective) String added in v3.46.0 

func (p Perspective) String() string

type RequestStream added in v3.46.0 

type RequestStream struct {
	*transport.Options
	// contains filtered or unexported fields
}

A RequestStream is a low-level abstraction representing an HTTP/3 request stream. It decouples sending of the HTTP request from reading the HTTP response, allowing the application to optimistically use the stream (and, for example, send datagrams) before receiving the response.

This is only needed for advanced use case, e.g. WebTransport and the various MASQUE proxying protocols.

func (*RequestStream) CancelRead added in v3.54.0 

func (s *RequestStream) CancelRead(errorCode quic.StreamErrorCode)

CancelRead aborts receiving on this stream. See quic.Stream.CancelRead for more details.

func (*RequestStream) CancelWrite added in v3.54.0 

func (s *RequestStream) CancelWrite(errorCode quic.StreamErrorCode)

CancelWrite aborts sending on this stream. See quic.Stream.CancelWrite for more details.

func (*RequestStream) Close added in v3.54.0 

func (s *RequestStream) Close() error

Close closes the send-direction of the stream. It does not close the receive-direction of the stream.

func (*RequestStream) Context added in v3.54.0 

func (s *RequestStream) Context() context.Context

Context returns a context derived from the underlying QUIC stream's context. See quic.Stream.Context for more details.

func (*RequestStream) Read added in v3.54.0 

func (s *RequestStream) Read(b []byte) (int, error)

Read reads data from the underlying stream.

It can only be used after the request has been sent (using SendRequestHeader) and the response has been consumed (using ReadResponse).

func (*RequestStream) ReadResponse added in v3.46.0 

func (s *RequestStream) ReadResponse() (*http.Response, error)

ReadResponse reads the HTTP response from the stream.

It must be called after sending the request (using SendRequestHeader). It is invalid to call it more than once. It doesn't set Response.Request and Response.TLS. It is invalid to call it after Read has been called.

func (*RequestStream) ReceiveDatagram added in v3.54.0 

func (s *RequestStream) ReceiveDatagram(ctx context.Context) ([]byte, error)

ReceiveDatagram receives HTTP Datagrams (RFC 9297).

It is only possible if support for HTTP Datagrams was enabled, using the EnableDatagram option on the Transport.

func (*RequestStream) SendDatagram added in v3.54.0 

func (s *RequestStream) SendDatagram(b []byte) error

SendDatagrams send a new HTTP Datagram (RFC 9297).

It is only possible to send datagrams if the server enabled support for this extension. It is recommended (though not required) to send the request before calling this method, as the server might drop datagrams which it can't associate with an existing request.

func (*RequestStream) SendRequestHeader added in v3.46.0 

func (s *RequestStream) SendRequestHeader(req *http.Request) error

SendRequestHeader sends the HTTP request.

It can only used for requests that don't have a request body. It is invalid to call it more than once. It is invalid to call it after Write has been called.

func (*RequestStream) SetDeadline added in v3.54.0 

func (s *RequestStream) SetDeadline(t time.Time) error

SetDeadline sets the read and write deadlines associated with the stream. It is equivalent to calling both SetReadDeadline and SetWriteDeadline.

func (*RequestStream) SetReadDeadline added in v3.54.0 

func (s *RequestStream) SetReadDeadline(t time.Time) error

SetReadDeadline sets the deadline for Read calls.

func (*RequestStream) SetWriteDeadline added in v3.54.0 

func (s *RequestStream) SetWriteDeadline(t time.Time) error

SetWriteDeadline sets the deadline for Write calls.

func (*RequestStream) StreamID added in v3.54.0 

func (s *RequestStream) StreamID() quic.StreamID

StreamID returns the QUIC stream ID of the underlying QUIC stream.

func (*RequestStream) Write added in v3.54.0 

func (s *RequestStream) Write(b []byte) (int, error)

Write writes data to the stream.

It can only be used after the request has been sent (using SendRequestHeader).

type RoundTripOpt 

type RoundTripOpt struct {
	// OnlyCachedConn controls whether the Transport may create a new QUIC connection.
	// If set true and no cached connection is available, RoundTripOpt will return ErrNoCachedConn.
	OnlyCachedConn bool
}

RoundTripOpt are options for the Transport.RoundTripOpt method.

type ServerStreamType added in v3.46.0 

type ServerStreamType uint64

StreamType is the stream type of a unidirectional stream.

type Settings added in v3.46.0 

type Settings struct {
	// Support for HTTP/3 datagrams (RFC 9297)
	EnableDatagrams bool
	// Extended CONNECT, RFC 9220
	EnableExtendedConnect bool
	// Other settings, defined by the application
	Other map[uint64]uint64
}

Settings are HTTP/3 settings that apply to the underlying connection.

type Stream 

type Stream struct {
	// contains filtered or unexported fields
}

A Stream is an HTTP/3 stream.

When writing to and reading from the stream, data is framed in HTTP/3 DATA frames.

func (*Stream) Read added in v3.54.0 

func (s *Stream) Read(b []byte) (int, error)

func (*Stream) ReceiveDatagram added in v3.46.0 

func (s *Stream) ReceiveDatagram(ctx context.Context) ([]byte, error)

func (*Stream) SendDatagram added in v3.46.0 

func (s *Stream) SendDatagram(b []byte) error

func (*Stream) StreamID added in v3.54.0 

func (s *Stream) StreamID() quic.StreamID

func (*Stream) Write added in v3.54.0 

func (s *Stream) Write(b []byte) (int, error)

type StreamNum added in v3.46.0 

type StreamNum int64

StreamNum is the stream number 

const (
	// InvalidStreamNum is an invalid stream number.
	InvalidStreamNum = -1
	// MaxStreamCount is the maximum stream count value that can be sent in MAX_STREAMS frames
	// and as the stream count in the transport parameters
	MaxStreamCount StreamNum = 1 << 60
)

func (StreamNum) StreamID added in v3.46.0 

func (s StreamNum) StreamID(stype StreamType, pers Perspective) quic.StreamID

StreamID calculates the stream ID.

type StreamType 

type StreamType uint8

StreamType encodes if this is a unidirectional or bidirectional stream 

const (
	// StreamTypeUni is a unidirectional stream
	StreamTypeUni StreamType = iota
	// StreamTypeBidi is a bidirectional stream
	StreamTypeBidi
)

type Transport added in v3.51.0 

type Transport struct {
	*transport.Options
	// TLSClientConfig specifies the TLS configuration to use with
	// tls.Client. If nil, the default configuration is used.
	TLSClientConfig *tls.Config

	// QUICConfig is the quic.Config used for dialing new connections.
	// If nil, reasonable default values will be used.
	QUICConfig *quic.Config

	// Dial specifies an optional dial function for creating QUIC
	// connections for requests.
	// If Dial is nil, a UDPConn will be created at the first request
	// and will be reused for subsequent connections to other servers.
	Dial func(ctx context.Context, addr string, tlsCfg *tls.Config, cfg *quic.Config) (*quic.Conn, error)

	// Enable support for HTTP/3 datagrams (RFC 9297).
	// If a QUICConfig is set, datagram support also needs to be enabled on the QUIC layer by setting EnableDatagrams.
	EnableDatagrams bool

	// Additional HTTP/3 settings.
	// It is invalid to specify any settings defined by RFC 9114 (HTTP/3) and RFC 9297 (HTTP Datagrams).
	AdditionalSettings map[uint64]uint64

	// MaxResponseHeaderBytes specifies a limit on how many response bytes are
	// allowed in the server's response header.
	// Zero means to use a default limit.
	MaxResponseHeaderBytes int64

	// DisableCompression, if true, prevents the Transport from requesting compression with an
	// "Accept-Encoding: gzip" request header when the Request contains no existing Accept-Encoding value.
	// If the Transport requests gzip on its own and gets a gzipped response, it's transparently
	// decoded in the Response.Body.
	// However, if the user explicitly requested gzip it is not automatically uncompressed.
	DisableCompression bool

	StreamHijacker    func(FrameType, quic.ConnectionTracingID, *quic.Stream, error) (hijacked bool, err error)
	UniStreamHijacker func(StreamType, quic.ConnectionTracingID, *quic.ReceiveStream, error) (hijacked bool)

	Logger *slog.Logger
	// contains filtered or unexported fields
}

Transport implements the http.RoundTripper interface

func (*Transport) AddConn added in v3.51.0 

func (t *Transport) AddConn(ctx context.Context, addr string) error

AddConn add a http3 connection, dial new conn if not exists.

func (*Transport) Close added in v3.51.0 

func (t *Transport) Close() error

Close closes the QUIC connections that this Transport has used.

func (*Transport) CloseIdleConnections added in v3.51.0 

func (t *Transport) CloseIdleConnections()

CloseIdleConnections closes any QUIC connections in the transport's pool that are currently idle. An idle connection is one that was previously used for requests but is now sitting unused. This method does not interrupt any connections currently in use. It also does not affect connections obtained via NewClientConn.

func (*Transport) NewClientConn added in v3.51.0 

func (t *Transport) NewClientConn(conn *quic.Conn) *ClientConn

NewClientConn creates a new HTTP/3 client connection on top of a QUIC connection. Most users should use RoundTrip instead of creating a connection directly. Specifically, it is not needed to perform GET, POST, HEAD and CONNECT requests.

Obtaining a ClientConn is only needed for more advanced use cases, such as using Extended CONNECT for WebTransport or the various MASQUE protocols.

func (*Transport) RoundTrip added in v3.51.0 

func (t *Transport) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip does a round trip.

func (*Transport) RoundTripOnlyCachedConn added in v3.51.0 

func (t *Transport) RoundTripOnlyCachedConn(req *http.Request) (*http.Response, error)

RoundTripOnlyCachedConn round trip only cached conn.

func (*Transport) RoundTripOpt added in v3.51.0 

func (t *Transport) RoundTripOpt(req *http.Request, opt RoundTripOpt) (*http.Response, error)

RoundTripOpt is like RoundTrip, but takes options.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.