http3

Documentation

Index

• Constants
• Variables
• func ConfigureTLSConfig(tlsConf *tls.Config) *tls.Config
• func ListenAndServe(addr, certFile, keyFile string, handler http.Handler) error
• func ListenAndServeQUIC(addr, certFile, keyFile string, handler http.Handler) error
• type DataStreamer
• type RoundTripOpt
• type RoundTripper
  • func (r *RoundTripper) Close() error
  • func (r *RoundTripper) RoundTrip(req *http.Request) (*http.Response, error)
  • func (r *RoundTripper) RoundTripOpt(req *http.Request, opt RoundTripOpt) (*http.Response, error)
• type Server
  • func (s *Server) Close() error
  • func (s *Server) CloseGracefully(timeout time.Duration) error
  • func (s *Server) ListenAndServe() error
  • func (s *Server) ListenAndServeTLS(certFile, keyFile string) error
  • func (s *Server) Serve(conn net.PacketConn) error
  • func (s *Server) ServeListener(listener quic.EarlyListener) error
  • func (s *Server) SetQuicHeaders(hdr http.Header) error

Constants

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 ErrNoAltSvcPort = errors.New("no port can be announced, specify it explicitly using Server.Port or Server.Addr")

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.

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

ErrNoCachedConn is returned when RoundTripper.OnlyCachedConn is set

var ServerContextKey = &contextKey{"http3-server"}

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.

Functions

func ConfigureTLSConfig

func ConfigureTLSConfig(tlsConf *tls.Config) *tls.Config

ConfigureTLSConfig creates a new tls.Config which can be used to create a quic.Listener meant for serving http3. The created tls.Config adds the functionality of detecting the used QUIC version in order to set the correct ALPN value for the http3 connection.

func ListenAndServe

func ListenAndServe(addr, certFile, keyFile string, handler http.Handler) error

ListenAndServe listens on the given network address for both, TLS 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.

func ListenAndServeQUIC

func ListenAndServeQUIC(addr, certFile, keyFile string, handler http.Handler) error

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.

Types

type DataStreamer

type DataStreamer interface {
	DataStream() quic.Stream
}

DataStreamer lets the caller take over the stream. After a call to DataStream the HTTP server library will not do anything else with the connection.

It becomes the caller's responsibility to manage and close the stream.

After a call to DataStream, the original Request.Body must not be used.

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, RoundTrip will return ErrNoCachedConn.
	OnlyCachedConn bool
}

RoundTripOpt are options for the Transport.RoundTripOpt method.

type RoundTripper

type RoundTripper struct {

	// 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

	// 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

	// Enable support for HTTP/3 datagrams.
	// If set to true, QuicConfig.EnableDatagram will be set.
	// See https://www.ietf.org/archive/id/draft-schinazi-masque-h3-datagram-02.html.
	EnableDatagrams bool

	// Dial specifies an optional dial function for creating QUIC
	// connections for requests.
	// If Dial is nil, quic.DialAddrEarlyContext will be used.
	Dial func(ctx context.Context, network, addr string, tlsCfg *tls.Config, cfg *quic.Config) (quic.EarlyConnection, error)

	// 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
	// contains filtered or unexported fields
}

RoundTripper implements the http.RoundTripper interface

func (*RoundTripper) Close

func (r *RoundTripper) Close() error

Close closes the QUIC connections that this RoundTripper has used

func (*RoundTripper) RoundTrip

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

RoundTrip does a round trip.

func (*RoundTripper) RoundTripOpt

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

RoundTripOpt is like RoundTrip, but takes options.

type Server

type Server struct {
	*http.Server

	// By providing a quic.Config, it is possible to set parameters of the QUIC connection.
	// If nil, it uses reasonable default values.
	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/draft-ietf-masque-h3-datagram-07.
	EnableDatagrams bool

	// The port to use in Alt-Svc response headers.
	// 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.
	Port int
	// contains filtered or unexported fields
}

Server is a HTTP/3 server.

func (*Server) Close

func (s *Server) Close() error

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.

func (*Server) CloseGracefully

func (s *Server) CloseGracefully(timeout time.Duration) error

CloseGracefully shuts down the server gracefully. The server sends a GOAWAY frame first, then waits for either timeout to trigger, or for all running requests to complete. CloseGracefully in combination with ListenAndServe() (instead of Serve()) may race if it is called before a UDP socket is established.

func (*Server) ListenAndServe

func (s *Server) ListenAndServe() error

ListenAndServe listens on the UDP address s.Addr and calls s.Handler to handle HTTP/3 requests on incoming connections.

func (*Server) ListenAndServeTLS

func (s *Server) ListenAndServeTLS(certFile, keyFile string) error

ListenAndServeTLS listens on the UDP address s.Addr and calls s.Handler to handle HTTP/3 requests on incoming connections.

func (*Server) Serve

func (s *Server) Serve(conn net.PacketConn) error

Serve an existing UDP connection. It is possible to reuse the same connection for outgoing connections. Closing the server does not close the packet conn.

func (*Server) ServeListener

func (s *Server) ServeListener(listener quic.EarlyListener) error

Serve 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 close the listener.

func (*Server) SetQuicHeaders

func (s *Server) SetQuicHeaders(hdr http.Header) error

SetQuicHeaders can be used to set the proper headers that announce that this server supports HTTP/3. The values set by default advertise all of the ports the server is listening on, but can be changed to a specific port by setting Server.Port before launching the serverr. 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,h3-29=":443"; ma=2592000