h2quic

Documentation

Index

• Variables
• func ListenAndServe(addr, certFile, keyFile string, handler http.Handler, quicConfig *quic.Config) error
• func ListenAndServeQUIC(addr, certFile, keyFile string, handler http.Handler, quicConfig *quic.Config) error
• func RoundTripPriority(r *RoundTripper, req *http.Request, priority *http2.PriorityParam) (*http.Response, error)
• type Client
  • func (c *Client) Do(req *http.Request, priority *http2.PriorityParam) (*http.Response, error)
  • func (c *Client) Get(url string, priority *http2.PriorityParam) (resp *http.Response, err error)
• type RoundTripOpt
• type RoundTripper
  • func (r *RoundTripper) Close() error
  • func (r *RoundTripper) OpenStream(hostname string, priority *http2.PriorityParam) (uint32, error)
  • func (r *RoundTripper) RoundTrip(req *http.Request) (*http.Response, error)
  • func (r *RoundTripper) RoundTripOpt(req *http.Request, opt RoundTripOpt, priority *http2.PriorityParam) (*http.Response, error)
  • func (r *RoundTripper) WritePriority(hostname string, dataStream protocol.StreamID, priority *http2.PriorityParam) 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) SetQuicHeaders(hdr http.Header) error

Variables

var DefaultClient = &Client{}

DefaultClient is the default Client and is used by Get, Head, and Post.

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

ErrNoCachedConn is returned when RoundTripper.OnlyCachedConn is set

var NoBody = noBod{}

NoBody is an io.ReadCloser with no bytes. Read always returns EOF and Close always returns nil. It can be used in an outgoing client request to explicitly signal that a request has zero bytes. An alternative, however, is to simply set Request.Body to nil.

Functions

func ListenAndServe

func ListenAndServe(addr, certFile, keyFile string, handler http.Handler, quicConfig *quic.Config) error

ListenAndServe listens on the given network address for both, TLS and QUIC connetions 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, quicConfig *quic.Config) error

ListenAndServeQUIC listens on the UDP network address addr and calls the handler for HTTP/2 requests on incoming connections. http.DefaultServeMux is used when handler is nil.

func RoundTripPriority

func RoundTripPriority(r *RoundTripper, req *http.Request, priority *http2.PriorityParam) (*http.Response, error)

RoundTripPriority is like RoundTrip, but uses http2 priority.

Types

type Client

type Client struct {
	// Transport specifies the mechanism by which individual
	// HTTP requests are made.
	// If nil, DefaultTransport is used.
	Transport RoundTripper

	// CheckRedirect specifies the policy for handling redirects.
	// If CheckRedirect is not nil, the client calls it before
	// following an HTTP redirect. The arguments req and via are
	// the upcoming request and the requests made already, oldest
	// first. If CheckRedirect returns an error, the Client's Get
	// method returns both the previous Response (with its Body
	// closed) and CheckRedirect's error (wrapped in a url.Error)
	// instead of issuing the Request req.
	// As a special case, if CheckRedirect returns ErrUseLastResponse,
	// then the most recent response is returned with its body
	// unclosed, along with a nil error.
	//
	// If CheckRedirect is nil, the Client uses its default policy,
	// which is to stop after 10 consecutive requests.
	CheckRedirect func(req *http.Request, via []*http.Request) error

	// Jar specifies the cookie jar.
	//
	// The Jar is used to insert relevant cookies into every
	// outbound Request and is updated with the cookie values
	// of every inbound Response. The Jar is consulted for every
	// redirect that the Client follows.
	//
	// If Jar is nil, cookies are only sent if they are explicitly
	// set on the Request.
	Jar http.CookieJar

	// Timeout specifies a time limit for requests made by this
	// Client. The timeout includes connection time, any
	// redirects, and reading the response body. The timer remains
	// running after Get, Head, Post, or Do return and will
	// interrupt reading of the Response.Body.
	//
	// A Timeout of zero means no timeout.
	//
	// The Client cancels requests to the underlying Transport
	// using the Request.Cancel mechanism. Requests passed
	// to Client.Do may still set Request.Cancel; both will
	// cancel the request.
	//
	// For compatibility, the Client will also use the deprecated
	// CancelRequest method on Transport if found. New
	// RoundTripper implementations should use Request.Cancel
	// instead of implementing CancelRequest.
	Timeout time.Duration
}

A Client is an HTTP client. Its zero value (DefaultClient) is a usable client that uses DefaultTransport.

The Client's Transport typically has internal state (cached TCP connections), so Clients should be reused instead of created as needed. Clients are safe for concurrent use by multiple goroutines.

A Client is higher-level than a RoundTripper (such as Transport) and additionally handles HTTP details such as cookies and redirects.

When following redirects, the Client will forward all headers set on the initial Request except:

• when forwarding sensitive headers like "Authorization", "WWW-Authenticate", and "Cookie" to untrusted targets. These headers will be ignored when following a redirect to a domain that is not a subdomain match or exact match of the initial domain. For example, a redirect from "foo.com" to either "foo.com" or "sub.foo.com" will forward the sensitive headers, but a redirect to "bar.com" will not.

• when forwarding the "Cookie" header with a non-nil cookie Jar. Since each redirect may mutate the state of the cookie jar, a redirect may possibly alter a cookie set in the initial request. When forwarding the "Cookie" header, any mutated cookies will be omitted, with the expectation that the Jar will insert those mutated cookies with the updated values (assuming the origin matches). If Jar is nil, the initial cookies are forwarded without change.

func (*Client) Do

func (c *Client) Do(req *http.Request, priority *http2.PriorityParam) (*http.Response, error)

Do sends an HTTP request and returns an HTTP response, following policy (such as redirects, cookies, auth) as configured on the client.

An error is returned if caused by client policy (such as CheckRedirect), or failure to speak HTTP (such as a network connectivity problem). A non-2xx status code doesn't cause an error.

If the returned error is nil, the Response will contain a non-nil Body which the user is expected to close. If the Body is not closed, the Client's underlying RoundTripper (typically Transport) may not be able to re-use a persistent TCP connection to the server for a subsequent "keep-alive" request.

The request Body, if non-nil, will be closed by the underlying Transport, even on errors.

On error, any Response can be ignored. A non-nil Response with a non-nil error only occurs when CheckRedirect fails, and even then the returned Response.Body is already closed.

Generally Get, Post, or PostForm will be used instead of Do.

If the server replies with a redirect, the Client first uses the CheckRedirect function to determine whether the redirect should be followed. If permitted, a 301, 302, or 303 redirect causes subsequent requests to use HTTP method GET (or HEAD if the original request was HEAD), with no body. A 307 or 308 redirect preserves the original HTTP method and body, provided that the Request.GetBody function is defined. The NewRequest function automatically sets GetBody for common standard library body types.

func (*Client) Get

func (c *Client) Get(url string, priority *http2.PriorityParam) (resp *http.Response, err error)

Get issues a GET to the specified URL. If the response is one of the following redirect codes, Get follows the redirect after calling the Client's CheckRedirect function:

301 (Moved Permanently)
302 (Found)
303 (See Other)
307 (Temporary Redirect)
308 (Permanent Redirect)

An error is returned if the Client's CheckRedirect function fails or if there was an HTTP protocol error. A non-2xx response doesn't cause an error.

When err is nil, resp always contains a non-nil resp.Body. Caller should close resp.Body when done reading from it.

To make a request with custom headers, use NewRequest and Client.Do.

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

func (r *RoundTripper) OpenStream(hostname string, priority *http2.PriorityParam) (uint32, error)

OpenStream opens an idle stream

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, priority *http2.PriorityParam) (*http.Response, error)

RoundTripOpt is like RoundTrip, but takes options.

func (*RoundTripper) WritePriority

func (r *RoundTripper) WritePriority(hostname string, dataStream protocol.StreamID, priority *http2.PriorityParam) error

WritePriority writes a priority frame

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

	// Private flag for demo, do not use
	CloseAfterFirstRequest bool
	// contains filtered or unexported fields
}

Server is a HTTP2 server listening for QUIC connections.

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/2 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/2 requests on incoming connections.

func (*Server) Serve

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

Serve an existing UDP connection.

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 QUIC. The values that are set depend on the port information from s.Server.Addr, and currently look like this (if Addr has port 443):

Alt-Svc: quic=":443"; ma=2592000; v="33,32,31,30"