http3

Documentation

Index

• Constants
• Variables
• type ErrCode
  • func (e ErrCode) String() string
• type Error
  • func (e *Error) Error() string
• type FrameType
• type GzipReader
  • func (gz *GzipReader) Close() error
  • func (gz *GzipReader) Read(p []byte) (n int, err error)
• type HTTPStreamer
• type Header
• type Hijacker
• type RoundTripOpt
• type RoundTripper
  • func (r *RoundTripper) AddConn(addr string) error
  • func (r *RoundTripper) Close() error
  • func (r *RoundTripper) CloseIdleConnections()
  • func (r *RoundTripper) RoundTrip(req *http.Request) (*http.Response, error)
  • func (r *RoundTripper) RoundTripOnlyCachedConn(req *http.Request) (*http.Response, error)
  • func (r *RoundTripper) RoundTripOpt(req *http.Request, opt RoundTripOpt) (*http.Response, error)
• type Stream
• type StreamCreator
• type StreamType

Constants

const (
	VersionDraft29 quic.VersionNumber = 0xff00001d
	Version1       quic.VersionNumber = 0x1
	Version2       quic.VersionNumber = 0x6b3343cf
)

const MethodGet0RTT = "GET_0RTT"

MethodGet0RTT allows a GET request to be sent using 0-RTT. Note that 0-RTT data doesn't provide replay protection.

Variables

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

ErrNoCachedConn is returned when RoundTripper.OnlyCachedConn is set

Types

type ErrCode

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

func (e ErrCode) String() string

type Error

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

func (e *Error) Error() string

type FrameType

type FrameType uint64

FrameType is the frame type of a HTTP/3 frame

type GzipReader

type GzipReader struct {
	Body io.ReadCloser // underlying Response.Body
	// contains filtered or unexported fields
}

call gzip.NewReader on the first call to Read

func (*GzipReader) Close

func (gz *GzipReader) Close() error

func (*GzipReader) Read

func (gz *GzipReader) Read(p []byte) (n int, err error)

type HTTPStreamer

type HTTPStreamer interface {
	HTTPStream() Stream
}

The HTTPStreamer allows taking over a HTTP/3 stream. The interface is implemented by: * for the server: the http.Request.Body * for the client: the http.Response.Body On the client side, the stream will be closed for writing, unless the DontCloseRequestStream RoundTripOpt was set. When a stream is taken over, it's the caller's responsibility to close the stream.

type Header

type Header struct {
	// Pseudo header fields defined in RFC 9114
	Path      string
	Method    string
	Authority string
	Scheme    string
	Status    string
	// for Extended connect
	Protocol string
	// parsed and deduplicated
	ContentLength int64
	// all non-pseudo headers
	Headers http.Header
}

type Hijacker

type Hijacker interface {
	StreamCreator() StreamCreator
}

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

type RoundTripOpt

type RoundTripOpt struct {
	// OnlyCachedConn controls whether the RoundTripper may create a new QUIC connection.
	// If set true and no cached connection is available, RoundTripOpt will return ErrNoCachedConn.
	OnlyCachedConn bool
	// DontCloseRequestStream controls whether the request stream is closed after sending the request.
	// If set, context cancellations have no effect after the response headers are received.
	DontCloseRequestStream bool
}

RoundTripOpt are options for the Transport.RoundTripOpt method.

type RoundTripper

type RoundTripper struct {
	*transport.Options

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

	// Enable support for HTTP/3 datagrams.
	// If set to true, QuicConfig.EnableDatagram will be set.
	//
	// See https://datatracker.ietf.org/doc/html/rfc9297.
	EnableDatagrams bool

	// Additional HTTP/3 settings.
	// It is invalid to specify any settings defined by the HTTP/3 draft and the datagram draft.
	AdditionalSettings map[uint64]uint64

	// When set, this callback is called for the first unknown frame parsed on a bidirectional stream.
	// It is called right after parsing the frame type.
	// If parsing the frame type fails, the error is passed to the callback.
	// In that case, the frame type will not be set.
	// Callers can either ignore the frame and return control of the stream back to HTTP/3
	// (by returning hijacked false).
	// Alternatively, callers can take over the QUIC stream (by returning hijacked true).
	StreamHijacker func(FrameType, quic.Connection, quic.Stream, error) (hijacked bool, err error)

	// When set, this callback is called for unknown unidirectional stream of unknown stream type.
	// If parsing the stream type fails, the error is passed to the callback.
	// In that case, the stream type will not be set.
	UniStreamHijacker func(StreamType, quic.Connection, quic.ReceiveStream, error) (hijacked bool)

	// 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.EarlyConnection, error)
	// contains filtered or unexported fields
}

RoundTripper implements the http.RoundTripper interface

func (*RoundTripper) AddConn

func (r *RoundTripper) AddConn(addr string) error

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

func (*RoundTripper) Close

func (r *RoundTripper) Close() error

Close closes the QUIC connections that this RoundTripper has used. It also closes the underlying UDPConn if it is not nil.

func (*RoundTripper) CloseIdleConnections

func (r *RoundTripper) CloseIdleConnections()

func (*RoundTripper) RoundTrip

func (r *RoundTripper) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip does a round trip.

func (*RoundTripper) RoundTripOnlyCachedConn

func (r *RoundTripper) RoundTripOnlyCachedConn(req *http.Request) (*http.Response, error)

RoundTripOnlyCachedConn round trip only cached conn.

func (*RoundTripper) RoundTripOpt

func (r *RoundTripper) RoundTripOpt(req *http.Request, opt RoundTripOpt) (*http.Response, error)

RoundTripOpt is like RoundTrip, but takes options.

type Stream

type Stream quic.Stream

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

type StreamCreator

type StreamCreator interface {
	// Context returns a context that is cancelled when the underlying connection is closed.
	Context() context.Context
	OpenStream() (quic.Stream, error)
	OpenStreamSync(context.Context) (quic.Stream, error)
	OpenUniStream() (quic.SendStream, error)
	OpenUniStreamSync(context.Context) (quic.SendStream, error)
	LocalAddr() net.Addr
	RemoteAddr() net.Addr
	ConnectionState() quic.ConnectionState
}

type StreamType

type StreamType uint64

StreamType is the stream type of a unidirectional stream.