github.com/TugasAkhir-QUIC/quic-go@v0.0.2-0.20240215011318-d20e25a9054c/http3/README.md (about)

     1  # HTTP/3
     2  
     3  [![PkgGoDev](https://pkg.go.dev/badge/github.com/quic-go/quic-go/http3)](https://pkg.go.dev/github.com/quic-go/quic-go/http3)
     4  
     5  This package implements HTTP/3 ([RFC 9114](https://datatracker.ietf.org/doc/html/rfc9114)), including QPACK ([RFC 9204](https://datatracker.ietf.org/doc/html/rfc9204)).
     6  It aims to provide feature parity with the standard library's HTTP/1.1 and HTTP/2 implementation.
     7  
     8  ## Serving HTTP/3
     9  
    10  The easiest way to start an HTTP/3 server is using
    11  ```go
    12  mux := http.NewServeMux()
    13  // ... add HTTP handlers to mux ...
    14  // If mux is nil, the http.DefaultServeMux is used.
    15  http3.ListenAndServeQUIC("0.0.0.0:443", "/path/to/cert", "/path/to/key", mux)
    16  ```
    17  
    18  `ListenAndServeQUIC` is a convenience function. For more configurability, set up an `http3.Server` explicitly:
    19  ```go
    20  server := http3.Server{
    21  	Handler:    mux,
    22  	Addr:       "0.0.0.0:443",
    23  	TLSConfig:  http3.ConfigureTLSConfig(&tls.Config{}), // use your tls.Config here
    24  	QuicConfig: &quic.Config{},
    25  }
    26  err := server.ListenAndServe()
    27  ```
    28  
    29  The `http3.Server` provides a number of configuration options, please refer to the [documentation](https://pkg.go.dev/github.com/quic-go/quic-go/http3#Server) for a complete list. The `QuicConfig` is used to configure the underlying QUIC connection. More details can be found in the documentation of the QUIC package.
    30  
    31  It is also possible to manually set up a `quic.Transport`, and then pass the listener to the server. This is useful when you want to set configuration options on the `quic.Transport`.
    32  ```go
    33  tr := quic.Transport{Conn: conn}
    34  tlsConf := http3.ConfigureTLSConfig(&tls.Config{})  // use your tls.Config here
    35  quicConf := &quic.Config{} // QUIC connection options
    36  server := http3.Server{}
    37  ln, _ := tr.ListenEarly(tlsConf, quicConf)
    38  server.ServeListener(ln)
    39  ```
    40  
    41  Alternatively, it is also possible to pass fully established QUIC connections to the HTTP/3 server. This is useful if the QUIC server offers multiple ALPNs (via `NextProtos` in the `tls.Config`).
    42  ```go
    43  tr := quic.Transport{Conn: conn}
    44  tlsConf := http3.ConfigureTLSConfig(&tls.Config{})  // use your tls.Config here
    45  quicConf := &quic.Config{} // QUIC connection options
    46  server := http3.Server{}
    47  // alternatively, use tr.ListenEarly to accept 0-RTT connections
    48  ln, _ := tr.Listen(tlsConf, quicConf)
    49  for {
    50  	c, _ := ln.Accept()
    51  	switch c.ConnectionState().TLS.NegotiatedProtocol {
    52  	case http3.NextProtoH3:
    53  		go server.ServeQUICConn(c) 
    54          // ... handle other protocols ...  
    55  	}
    56  }
    57  ```
    58  
    59  ## Dialing HTTP/3
    60  
    61  This package provides a `http.RoundTripper` implementation that can be used on the `http.Client`:
    62  
    63  ```go
    64  &http3.RoundTripper{
    65  	TLSClientConfig: &tls.Config{},  // set a TLS client config, if desired
    66  	QuicConfig:      &quic.Config{}, // QUIC connection options
    67  }
    68  defer roundTripper.Close()
    69  client := &http.Client{
    70  	Transport: roundTripper,
    71  }
    72  ```
    73  
    74  The `http3.RoundTripper` provides a number of configuration options, please refer to the [documentation](https://pkg.go.dev/github.com/quic-go/quic-go/http3#RoundTripper) for a complete list.
    75  
    76  To use a custom `quic.Transport`, the function used to dial new QUIC connections can be configured:
    77  ```go
    78  tr := quic.Transport{}
    79  roundTripper := &http3.RoundTripper{
    80  	TLSClientConfig: &tls.Config{},  // set a TLS client config, if desired 
    81  	QuicConfig:      &quic.Config{}, // QUIC connection options 
    82  	Dial: func(ctx context.Context, addr string, tlsConf *tls.Config, quicConf *quic.Config) (quic.EarlyConnection, error) {
    83  		a, err := net.ResolveUDPAddr("udp", addr)
    84  		if err != nil {
    85  			return nil, err
    86  		}
    87  		return tr.DialEarly(ctx, a, tlsConf, quicConf)
    88  	},
    89  }
    90  ```
    91  
    92  ## Using the same UDP Socket for Server and Roundtripper
    93  
    94  Since QUIC demultiplexes packets based on their connection IDs, it is possible allows running a QUIC server and client on the same UDP socket. This also works when using HTTP/3: HTTP requests can be sent from the same socket that a server is listening on.
    95  
    96  To achieve this using this package, first initialize a single `quic.Transport`, and pass a `quic.EarlyListner` obtained from that transport to `http3.Server.ServeListener`, and use the `DialEarly` function of the transport as the `Dial` function for the `http3.RoundTripper`.
    97  
    98  ## QPACK
    99  
   100  HTTP/3 utilizes QPACK ([RFC 9204](https://datatracker.ietf.org/doc/html/rfc9204)) for efficient HTTP header field compression. Our implementation, available at[quic-go/qpack](https://github.com/quic-go/qpack), provides a minimal implementation of the protocol.  
   101  
   102  While the current implementation is a fully interoperable implementation of the QPACK protocol, it only uses the static compression table. The dynamic table would allow for more effective compression of frequently transmitted header fields. This can be particularly beneficial in scenarios where headers have considerable redundancy or in high-throughput environments.
   103  
   104  If you think that your application would benefit from higher compression efficiency, or if you're interested in contributing improvements here, please let us know in [#2424](https://github.com/quic-go/quic-go/issues/2424).