quic

README

A QUIC implementation in pure Go

quic-go is an implementation of the QUIC protocol in Go.

Roadmap

quic-go is compatible with the current version(s) of Google Chrome and QUIC as deployed on Google's servers. We're actively tracking the development of the Chrome code to ensure compatibility as the protocol evolves. In that process, we're dropping support for old QUIC versions. As Google's QUIC versions are expected to converge towards the IETF QUIC draft, quic-go will eventually implement that draft.

Guides

We currently support Go 1.7+.

Installing deps:

go get -t

Running tests:

go test ./...

Running the example server

go run example/main.go -www /var/www/

Using the quic_client from chromium:

quic_client --host=127.0.0.1 --port=6121 --v=1 https://quic.clemente.io

Using Chrome:

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --user-data-dir=/tmp/chrome --no-proxy-server --enable-quic --origin-to-force-quic-on=quic.clemente.io:443 --host-resolver-rules='MAP quic.clemente.io:443 127.0.0.1:6121' https://quic.clemente.io

Using the example client

go run example/client/main.go https://clemente.io

Usage

As a server

See the example server or try out Caddy (from version 0.9, instructions here). Starting a QUIC server is very similar to the standard lib http in go:

http.Handle("/", http.FileServer(http.Dir(wwwDir)))
h2quic.ListenAndServeQUIC("localhost:4242", "/path/to/cert/chain.pem", "/path/to/privkey.pem", nil)

As a client

See the example client. Use a QuicRoundTripper as a Transport in a http.Client.

http.Client{
  Transport: &h2quic.QuicRoundTripper{},
}

Contributing

We are always happy to welcome new contributors! We have a number of self-contained issues that are suitable for first-time contributors, they are tagged with want-help. If you have any questions, please feel free to reach out by opening an issue or leaving a comment.

Documentation

Index

• type Config
• type ConnState
• type ConnStateCallback
• type Listener
  • func Listen(conn net.PacketConn, config *Config) (Listener, error)
  • func ListenAddr(addr string, config *Config) (Listener, error)
• type PublicHeader
  • func ParsePublicHeader(b *bytes.Reader, packetSentBy protocol.Perspective) (*PublicHeader, error)
  • func (h *PublicHeader) GetLength(pers protocol.Perspective) (protocol.ByteCount, error)
  • func (h *PublicHeader) Write(b *bytes.Buffer, version protocol.VersionNumber, pers protocol.Perspective) error
• type Session
  • func Dial(pconn net.PacketConn, remoteAddr net.Addr, host string, config *Config) (Session, error)
  • func DialAddr(addr string, config *Config) (Session, error)
• type Stream

Types

type Config

type Config struct {
	TLSConfig *tls.Config
	// ConnStateCallback will be called when the QUIC version is successfully negotiated or when the encryption level changes.
	// If this field is not set, the Dial functions will return only when the connection is forward secure.
	// Callbacks have to be thread-safe, since they might be called in separate goroutines.
	ConnState ConnStateCallback
}

Config contains all configuration data needed for a QUIC server or client. More config parameters (such as timeouts) will be added soon, see e.g. https://github.com/lucas-clemente/quic-go/issues/441.

type ConnState

type ConnState int

ConnState is the status of the connection

const (
	// ConnStateInitial is the initial state
	ConnStateInitial ConnState = iota
	// ConnStateVersionNegotiated means that version negotiation is complete
	ConnStateVersionNegotiated
	// ConnStateSecure means that the connection is encrypted
	ConnStateSecure
	// ConnStateForwardSecure means that the connection is forward secure
	ConnStateForwardSecure
)

type ConnStateCallback

type ConnStateCallback func(Session, ConnState)

ConnStateCallback is called every time the connection moves to another connection state.

type Listener

type Listener interface {
	// Close the server, sending CONNECTION_CLOSE frames to each peer.
	Close() error
	// Addr returns the local network addr that the server is listening on.
	Addr() net.Addr
	// Serve starts the main server loop, and blocks until a network error occurs or the server is closed.
	Serve() error
}

A Listener for incoming QUIC connections

func Listen

func Listen(conn net.PacketConn, config *Config) (Listener, error)

Listen listens for QUIC connections on a given net.PacketConn. The listener is not active until Serve() is called.

func ListenAddr

func ListenAddr(addr string, config *Config) (Listener, error)

ListenAddr creates a QUIC server listening on a given address. The listener is not active until Serve() is called.

type PublicHeader

type PublicHeader struct {
	Raw                  []byte
	ConnectionID         protocol.ConnectionID
	VersionFlag          bool
	ResetFlag            bool
	TruncateConnectionID bool
	PacketNumberLen      protocol.PacketNumberLen
	PacketNumber         protocol.PacketNumber
	VersionNumber        protocol.VersionNumber   // VersionNumber sent by the client
	SupportedVersions    []protocol.VersionNumber // VersionNumbers sent by the server
	DiversificationNonce []byte
}

The PublicHeader of a QUIC packet. Warning: This struct should not be considered stable and will change soon.

func ParsePublicHeader

func ParsePublicHeader(b *bytes.Reader, packetSentBy protocol.Perspective) (*PublicHeader, error)

ParsePublicHeader parses a QUIC packet's public header. The packetSentBy is the perspective of the peer that sent this PublicHeader, i.e. if we're the server, packetSentBy should be PerspectiveClient. Warning: This API should not be considered stable and will change soon.

func (*PublicHeader) GetLength

func (h *PublicHeader) GetLength(pers protocol.Perspective) (protocol.ByteCount, error)

GetLength gets the length of the publicHeader in bytes. It can only be called for regular packets.

func (*PublicHeader) Write

func (h *PublicHeader) Write(b *bytes.Buffer, version protocol.VersionNumber, pers protocol.Perspective) error

Write writes a public header. Warning: This API should not be considered stable and will change soon.

type Session

type Session interface {
	// AcceptStream returns the next stream opened by the peer, blocking until one is available.
	// Since stream 1 is reserved for the crypto stream, the first stream is either 2 (for a client) or 3 (for a server).
	AcceptStream() (Stream, error)
	// OpenStream opens a new QUIC stream, returning a special error when the peeer's concurrent stream limit is reached.
	// New streams always have the smallest possible stream ID.
	// TODO: Enable testing for the special error
	OpenStream() (Stream, error)
	// OpenStreamSync opens a new QUIC stream, blocking until the peer's concurrent stream limit allows a new stream to be opened.
	// It always picks the smallest possible stream ID.
	OpenStreamSync() (Stream, error)
	// LocalAddr returns the local address.
	LocalAddr() net.Addr
	// RemoteAddr returns the address of the peer.
	RemoteAddr() net.Addr
	// Close closes the connection. The error will be sent to the remote peer in a CONNECTION_CLOSE frame. An error value of nil is allowed and will cause a normal PeerGoingAway to be sent.
	Close(error) error
}

A Session is a QUIC connection between two peers.

func Dial

func Dial(pconn net.PacketConn, remoteAddr net.Addr, host string, config *Config) (Session, error)

Dial establishes a new QUIC connection to a server using a net.PacketConn. The host parameter is used for SNI.

func DialAddr

func DialAddr(addr string, config *Config) (Session, error)

DialAddr establishes a new QUIC connection to a server. The hostname for SNI is taken from the given address.

type Stream

type Stream interface {
	io.Reader
	io.Writer
	io.Closer
	StreamID() protocol.StreamID
	// Reset closes the stream with an error.
	Reset(error)
}

Stream is the interface implemented by QUIC streams