ClientConn is an HTTP/3 client doing requests to a single remote server. CloseWithError closes the connection with the given error code and message.
It is invalid to call this function after the connection was closed. Context returns a context that is cancelled when the connection is closed. HandleBidirectionalStream handles an incoming bidirectional stream. OpenRequestStream opens a new request stream on the HTTP/3 connection. 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. RoundTrip executes a request and returns a response 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.
*ClientConn : Settingser
*ClientConn : net/http.RoundTripper
func (*Transport).NewClientConn(conn *quic.Conn) *ClientConn
The HTTPStreamer allows taking over a HTTP/3 stream. The interface is implemented by the http.ResponseWriter.
When a stream is taken over, it's the caller's responsibility to close the stream.( HTTPStreamer) HTTPStream() *Stream
RawClientConn is a low-level HTTP/3 client connection.
It allows the application to take control of the stream accept loops,
giving the application the ability to handle streams originating from the server.ClientConn*ClientConn CloseWithError closes the connection with the given error code and message.
It is invalid to call this function after the connection was closed. Context returns a context that is cancelled when the connection is closed. HandleBidirectionalStream handles an incoming bidirectional stream. HandleUnidirectionalStream handles an incoming unidirectional stream. OpenRequestStream opens a new request stream on the HTTP/3 connection. 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. RoundTrip executes a request and returns a response 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.
RawClientConn : Settingser
RawClientConn : net/http.RoundTripper
func (*Transport).NewRawClientConn(conn *quic.Conn) *RawClientConn
RawServerConn is an HTTP/3 server connection.
It can be used for advanced use cases where the application wants to manage the QUIC connection lifecycle. CloseWithError closes the connection with the given error code and message. HandleRequestStream handles an HTTP/3 request on a bidirectional request stream.
The stream can either be obtained by calling AcceptStream on the underlying QUIC connection,
or (internally) by using the server's stream accept loop. HandleUnidirectionalStream handles an incoming unidirectional stream.
func (*Server).NewRawServerConn(conn *quic.Conn) (*RawServerConn, error)
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. CancelRead aborts receiving on this stream.
See [quic.Stream.CancelRead] for more details. CancelWrite aborts sending on this stream.
See [quic.Stream.CancelWrite] for more details. Close closes the send-direction of the stream.
It does not close the receive-direction of the stream. Context returns a context derived from the underlying QUIC stream's context.
See [quic.Stream.Context] for more details. 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). 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. ReceiveDatagram receives HTTP Datagrams (RFC 9297).
It is only possible if support for HTTP Datagrams was enabled, using the EnableDatagram
option on the [Transport]. 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. 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. SetDeadline sets the read and write deadlines associated with the stream.
It is equivalent to calling both SetReadDeadline and SetWriteDeadline. SetReadDeadline sets the deadline for Read calls. SetWriteDeadline sets the deadline for Write calls. StreamID returns the QUIC stream ID of the underlying QUIC stream. Write writes data to the stream.
It can only be used after the request has been sent (using SendRequestHeader).
*RequestStream : github.com/miekg/dns.Writer
*RequestStream : github.com/pion/datachannel.ReadDeadliner
*RequestStream : github.com/pion/datachannel.WriteDeadliner
*RequestStream : github.com/pion/stun.Connection
*RequestStream : github.com/pion/stun/v3.Connection
*RequestStream : github.com/prometheus/common/expfmt.Closer
*RequestStream : internal/bisect.Writer
*RequestStream : io.Closer
*RequestStream : io.ReadCloser
*RequestStream : io.Reader
*RequestStream : io.ReadWriteCloser
*RequestStream : io.ReadWriter
*RequestStream : io.WriteCloser
*RequestStream : io.Writer
func (*ClientConn).OpenRequestStream(ctx context.Context) (*RequestStream, error)
RoundTripOpt are options for the Transport.RoundTripOpt method. OnlyCachedConn controls whether the Transport may create a new QUIC connection.
If set true and no cached connection is available, RoundTripOpt will return ErrNoCachedConn.
func (*Transport).RoundTripOpt(req *http.Request, opt RoundTripOpt) (*http.Response, error)
Server is a HTTP/3 server. AdditionalSettings specifies additional HTTP/3 settings.
It is invalid to specify any settings defined by RFC 9114 (HTTP/3) and RFC 9297 (HTTP Datagrams). Addr optionally specifies the UDP address for the server to listen on,
in the form "host:port".
When used by ListenAndServe and ListenAndServeTLS methods, if empty,
":https" (port 443) is used. See net.Dial for details of the address
format.
Otherwise, if Port is not set and underlying QUIC listeners do not
have valid port numbers, the port part is used in Alt-Svc headers set
with SetQUICHeaders. ConnContext optionally specifies a function that modifies the context used for a new connection c.
The provided ctx has a ServerContextKey value. EnableDatagrams enables support for HTTP/3 datagrams (RFC 9297).
If set to true, QUICConfig.EnableDatagrams will be set. Handler is the HTTP request handler to use. If not set, defaults to
http.NotFound. IdleTimeout specifies how long until idle clients connection should be
closed. Idle refers only to the HTTP/3 layer, activity at the QUIC layer
like PING frames are not considered.
If zero or negative, there is no timeout.Logger*slog.Logger MaxHeaderBytes controls the maximum number of bytes the server will
read parsing the request HEADERS frame. It does not limit the size of
the request body. If zero or negative, http.DefaultMaxHeaderBytes is
used. Port is used in Alt-Svc response headers set with SetQUICHeaders. If
needed Port can be manually set when the Server is created.
This is useful when a Layer 4 firewall is redirecting UDP traffic and
clients must use a port different from the port the Server is
listening on. QUICConfig provides the parameters for QUIC connection created with Serve.
If nil, it uses reasonable default values.
Configured versions are also used in Alt-Svc response header set with SetQUICHeaders. TLSConfig provides a TLS configuration for use by server. It must be
set for ListenAndServe and Serve methods. Close the server immediately, aborting requests and sending CONNECTION_CLOSE frames to connected clients.
Close in combination with ListenAndServe() (instead of Serve()) may race if it is called before a UDP socket is established.
It is the caller's responsibility to close any connection passed to ServeQUICConn. ListenAndServe listens on the UDP address s.Addr and calls s.Handler to handle HTTP/3 requests on incoming connections.
If s.Addr is blank, ":https" is used. ListenAndServeTLS listens on the UDP address s.Addr and calls s.Handler to handle HTTP/3 requests on incoming connections.
If s.Addr is blank, ":https" is used.(*Server) NewRawServerConn(conn *quic.Conn) (*RawServerConn, error) Serve an existing UDP connection.
It is possible to reuse the same connection for outgoing connections.
Closing the server does not close the connection. ServeListener serves an existing QUIC listener.
Make sure you use http3.ConfigureTLSConfig to configure a tls.Config
and use it to construct a http3-friendly QUIC listener.
Closing the server does not close the listener. It is the application's responsibility to close them.
ServeListener always returns a non-nil error. After Shutdown or Close, the returned error is http.ErrServerClosed. ServeQUICConn serves a single QUIC connection. SetQUICHeaders can be used to set the proper headers that announce that this server supports HTTP/3.
The values set by default advertise all the ports the server is listening on, but can be
changed to a specific port by setting Server.Port before launching the server.
If no listener's Addr().String() returns an address with a valid port, Server.Addr will be used
to extract the port, if specified.
For example, a server launched using ListenAndServe on an address with port 443 would set:
Alt-Svc: h3=":443"; ma=2592000 Shutdown gracefully shuts down the server without interrupting any active connections.
The server sends a GOAWAY frame first, then or for all running requests to complete.
Shutdown in combination with ListenAndServe may race if it is called before a UDP socket is established.
It is recommended to use Serve instead.
*Server : github.com/prometheus/common/expfmt.Closer
*Server : io.Closer
func github.com/quic-go/webtransport-go.ConfigureHTTP3Server(s *Server)
Settings are HTTP/3 settings that apply to the underlying connection. Support for HTTP/3 datagrams (RFC 9297) Extended CONNECT, RFC 9220 Other settings, defined by the application
func (*ClientConn).Settings() *Settings
func Settingser.Settings() *Settings
Settingser allows waiting for and retrieving the peer's HTTP/3 settings. ReceivedSettings returns a channel that is closed once the peer's SETTINGS frame was received.
Settings can be obtained from the Settings method after the channel was closed. Settings returns the settings received on this connection.
It is only valid to call this function after the channel returned by ReceivedSettings was closed.
*ClientConnRawClientConn
StreamType is the stream type of a unidirectional stream.
Transport implements the http.RoundTripper interface Additional HTTP/3 settings.
It is invalid to specify any settings defined by RFC 9114 (HTTP/3) and RFC 9297 (HTTP Datagrams). 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. 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. 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.Logger*slog.Logger MaxResponseHeaderBytes specifies a limit on how many response bytes are
allowed in the server's response header.
Zero means to use a default limit. QUICConfig is the quic.Config used for dialing new connections.
If nil, reasonable default values will be used. TLSClientConfig specifies the TLS configuration to use with
tls.Client. If nil, the default configuration is used. Close closes the QUIC connections that this Transport has used.
A Transport cannot be used after it has been closed. 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. 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. NewRawClientConn creates a new low-level HTTP/3 client connection on top of a QUIC connection.
Unlike NewClientConn, the returned RawClientConn allows the application to take control
of the stream accept loops, by calling HandleUnidirectionalStream for incoming unidirectional
streams and HandleBidirectionalStream for incoming bidirectional streams. RoundTrip does a round trip. RoundTripOpt is like RoundTrip, but takes options.
*Transport : github.com/prometheus/common/expfmt.Closer
*Transport : io.Closer
*Transport : net/http.RoundTripper
Package-Level Functions (total 5)
ConfigureTLSConfig creates a new tls.Config which can be used
to create a quic.Listener meant for serving HTTP/3.
ListenAndServeQUIC listens on the UDP network address addr and calls the
handler for HTTP/3 requests on incoming connections. http.DefaultServeMux is
used when handler is nil.
ListenAndServeTLS listens on the given network address for both TLS/TCP and QUIC
connections in parallel. It returns if one of the two returns an error.
http.DefaultServeMux is used when handler is nil.
The correct Alt-Svc headers for QUIC are set.
ParseCapsule parses the header of a Capsule.
It returns an io.Reader that can be used to read the Capsule value.
The Capsule value must be read entirely (i.e. until the io.EOF) before using r again.
WriteCapsule writes a capsule
Package-Level Variables (total 5)
ErrNoAltSvcPort is the error returned by SetQUICHeaders when no port was found
for Alt-Svc to announce. This can happen if listening on a PacketConn without a port
(UNIX socket, for example) and no port is specified in Server.Port or Server.Addr.
ErrNoCachedConn is returned when Transport.OnlyCachedConn is set
ErrTransportClosed is returned when attempting to use a closed Transport
RemoteAddrContextKey is a context key. It can be used in
HTTP handlers with Context.Value to access the remote
address of the connection. The associated value will be of
type net.Addr.
Use this value instead of [http.Request.RemoteAddr] if you
require access to the remote address of the connection rather
than its string representation.
ServerContextKey is a context key. It can be used in HTTP
handlers with Context.Value to access the server that
started the handler. The associated value will be of
type *http3.Server.
Package-Level Constants (total 23)
CapsuleProtocolHeader is the header value used to advertise support for the capsule protocol
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.
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.
NextProtoH3 is the ALPN protocol negotiated during the TLS handshake, for QUIC v1 and v2.
The pages are generated with Goldsv0.8.2. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds.
