Documentation
¶
Index ¶
- Constants
- Variables
- type Connection
- type ErrCode
- type Error
- type FrameType
- type Hijacker
- type Perspective
- type RequestStream
- type RoundTripOpt
- type RoundTripper
- func (r *RoundTripper) AddConn(ctx context.Context, 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 ServerStreamType
- type Settings
- type SingleDestinationRoundTripper
- type Stream
- type StreamID
- type StreamNum
- type StreamType
Constants ¶
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" )
const ( VersionUnknown quic.Version = math.MaxUint32 Version1 quic.Version = 0x1 Version2 quic.Version = 0x6b3343cf )
The version numbers, making grepping easier
const NextProtoH3 = "h3"
NextProtoH3 is the ALPN protocol negotiated during the TLS handshake, for QUIC v1 and v2.
Variables ¶
var ErrNoCachedConn = errors.New("http3: no cached connection was available")
ErrNoCachedConn is returned when RoundTripper.OnlyCachedConn is set
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 Connection ¶ added in v3.50.0
type Connection interface {
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
CloseWithError(quic.ApplicationErrorCode, string) error
Context() context.Context
ConnectionState() quic.ConnectionState
// ReceivedSettings returns a channel that is closed once the client's SETTINGS frame was received.
ReceivedSettings() <-chan struct{}
// Settings returns the settings received on this connection.
Settings() *Settings
}
Connection is an HTTP/3 connection. It has all methods from the quic.Connection expect for AcceptStream, AcceptUniStream, SendDatagram and ReceiveDatagram.
type ErrCode ¶ added in v3.50.0
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 )
type Error ¶ added in v3.50.0
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.
type Hijacker ¶
type Hijacker interface {
Connection() Connection
}
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 Perspective ¶ added in v3.50.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.50.0
func (p Perspective) Opposite() Perspective
Opposite returns the perspective of the peer
func (Perspective) String ¶ added in v3.50.0
func (p Perspective) String() string
type RequestStream ¶ added in v3.50.0
type RequestStream interface {
Stream
// SendRequestHeader sends the HTTP request.
// It is invalid to call it more than once.
// It is invalid to call it after Write has been called.
SendRequestHeader(req *http.Request) error
// ReadResponse reads the HTTP response from the stream.
// 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.
ReadResponse() (*http.Response, error)
}
A RequestStream is an HTTP/3 request stream. When writing to and reading from the stream, data is framed in HTTP/3 DATA frames.
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
}
RoundTripOpt are options for the Transport.RoundTripOpt method.
type RoundTripper ¶
type RoundTripper 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.EarlyConnection, 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
// contains filtered or unexported fields
}
RoundTripper implements the http.RoundTripper interface
func (*RoundTripper) AddConn ¶
func (r *RoundTripper) AddConn(ctx context.Context, 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 ¶ added in v3.50.0
func (r *RoundTripper) CloseIdleConnections()
func (*RoundTripper) RoundTripOnlyCachedConn ¶
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 ServerStreamType ¶ added in v3.50.0
type ServerStreamType uint64
StreamType is the stream type of a unidirectional stream.
type Settings ¶ added in v3.50.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 SingleDestinationRoundTripper ¶ added in v3.50.0
type SingleDestinationRoundTripper struct {
*transport.Options
Connection quic.Connection
// 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
StreamHijacker func(FrameType, quic.ConnectionTracingID, quic.Stream, error) (hijacked bool, err error)
UniStreamHijacker func(ServerStreamType, quic.ConnectionTracingID, quic.ReceiveStream, error) (hijacked bool)
// contains filtered or unexported fields
}
SingleDestinationRoundTripper is an HTTP/3 client doing requests to a single remote server.
func (*SingleDestinationRoundTripper) OpenRequestStream ¶ added in v3.50.0
func (c *SingleDestinationRoundTripper) OpenRequestStream(ctx context.Context) (RequestStream, error)
func (*SingleDestinationRoundTripper) RoundTrip ¶ added in v3.50.0
RoundTrip executes a request and returns a response
func (*SingleDestinationRoundTripper) Start ¶ added in v3.50.0
func (c *SingleDestinationRoundTripper) Start() Connection
type Stream ¶
type Stream interface {
quic.Stream
SendDatagram([]byte) error
ReceiveDatagram(context.Context) ([]byte, error)
}
A Stream is an HTTP/3 request stream. When writing to and reading from the stream, data is framed in HTTP/3 DATA frames.
type StreamID ¶ added in v3.50.0
type StreamID int64
A StreamID in QUIC
const InvalidStreamID StreamID = -1
InvalidPacketNumber is a stream ID that is invalid. The first valid stream ID in QUIC is 0.
func (StreamID) InitiatedBy ¶ added in v3.50.0
func (s StreamID) InitiatedBy() Perspective
InitiatedBy says if the stream was initiated by the client or by the server
func (StreamID) StreamNum ¶ added in v3.50.0
StreamNum returns how many streams in total are below this Example: for stream 9 it returns 3 (i.e. streams 1, 5 and 9)
func (StreamID) Type ¶ added in v3.50.0
func (s StreamID) Type() StreamType
Type says if this is a unidirectional or bidirectional stream
type StreamNum ¶ added in v3.50.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.50.0
func (s StreamNum) StreamID(stype StreamType, pers Perspective) 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 )