webtransport

README

webtransport-go

webtransport-go is an implementation of the WebTransport protocol, based on quic-go. It currently implements draft-02 of the specification.

Running a Server

// create a new webtransport.Server, listening on (UDP) port 443
s := webtransport.Server{
    H3: http3.Server{Addr: ":443"},
}

// Create a new HTTP endpoint /webtransport.
http.HandleFunc("/webtransport", func(w http.ResponseWriter, r *http.Request) {
    conn, err := s.Upgrade(w, r)
    if err != nil {
        log.Printf("upgrading failed: %s", err)
        w.WriteHeader(500)
        return
    }
    // Handle the connection. Here goes the application logic. 
})

s.ListenAndServeTLS(certFile, keyFile)

Now that the server is running, Chrome can be used to establish a new WebTransport session as described in this tutorial.

Running a Client

var d webtransport.Dialer
rsp, conn, err := d.Dial(ctx, "https://example.com/webtransport", nil)
// err is only nil if rsp.StatusCode is a 2xx
// Handle the connection. Here goes the application logic.

Documentation

Index

• Constants
• type ConnectionError
  • func (e *ConnectionError) Error() string
• type Dialer
  • func (d *Dialer) Close() error
  • func (d *Dialer) Dial(ctx context.Context, urlStr string, reqHdr http.Header) (*http.Response, *Session, error)
• type ReceiveStream
• type SendStream
• type Server
  • func (s *Server) Close() 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) ServeQUICConn(conn quic.Connection) error
  • func (s *Server) Upgrade(w http.ResponseWriter, r *http.Request) (*Session, error)
• type Session
  • func (s *Session) AcceptStream(ctx context.Context) (Stream, error)
  • func (s *Session) AcceptUniStream(ctx context.Context) (ReceiveStream, error)
  • func (s *Session) CloseWithError(code SessionErrorCode, msg string) error
  • func (c *Session) ConnectionState() quic.ConnectionState
  • func (s *Session) Context() context.Context
  • func (s *Session) LocalAddr() net.Addr
  • func (s *Session) OpenStream() (Stream, error)
  • func (s *Session) OpenStreamSync(ctx context.Context) (str Stream, err error)
  • func (s *Session) OpenUniStream() (SendStream, error)
  • func (s *Session) OpenUniStreamSync(ctx context.Context) (str SendStream, err error)
  • func (s *Session) RemoteAddr() net.Addr
• type SessionErrorCode
• type Stream
• type StreamError
  • func (e *StreamError) Error() string
  • func (e *StreamError) Is(target error) bool
• type StreamErrorCode

Constants

const WebTransportBufferedStreamRejectedErrorCode quic.StreamErrorCode = 0x3994bd84

WebTransportBufferedStreamRejectedErrorCode is the error code of the H3_WEBTRANSPORT_BUFFERED_STREAM_REJECTED error.

Types

type ConnectionError

type ConnectionError struct {
	Remote    bool
	ErrorCode SessionErrorCode
	Message   string
}

ConnectionError is a WebTransport connection error.

func (*ConnectionError) Error

func (e *ConnectionError) Error() string

type Dialer

type Dialer struct {
	// If not set, reasonable defaults will be used.
	// In order for WebTransport to function, this implementation will:
	// * overwrite the StreamHijacker and UniStreamHijacker
	// * enable datagram support
	// * set the MaxIncomingStreams to 100 on the quic.Config, if unset
	*http3.RoundTripper

	// StreamReorderingTime is the time an incoming WebTransport stream that cannot be associated
	// with a session is buffered.
	// This can happen if the response to a CONNECT request (that creates a new session) is reordered,
	// and arrives after the first WebTransport stream(s) for that session.
	// Defaults to 5 seconds.
	StreamReorderingTimeout time.Duration
	// contains filtered or unexported fields
}

func (*Dialer) Close

func (d *Dialer) Close() error

func (*Dialer) Dial

func (d *Dialer) Dial(ctx context.Context, urlStr string, reqHdr http.Header) (*http.Response, *Session, error)

type ReceiveStream

type ReceiveStream interface {
	io.Reader

	StreamID() quic.StreamID
	CancelRead(StreamErrorCode)

	SetReadDeadline(time.Time) error
}

type SendStream

type SendStream interface {
	io.Writer
	io.Closer

	StreamID() quic.StreamID
	CancelWrite(StreamErrorCode)

	SetWriteDeadline(time.Time) error
}

type Server

type Server struct {
	H3 http3.Server

	// StreamReorderingTime is the time an incoming WebTransport stream that cannot be associated
	// with a session is buffered.
	// This can happen if the CONNECT request (that creates a new session) is reordered, and arrives
	// after the first WebTransport stream(s) for that session.
	// Defaults to 5 seconds.
	StreamReorderingTimeout time.Duration

	// CheckOrigin is used to validate the request origin, thereby preventing cross-site request forgery.
	// CheckOrigin returns true if the request Origin header is acceptable.
	// If unset, a safe default is used: If the Origin header is set, it is checked that it
	// matches the request's Host header.
	CheckOrigin func(r *http.Request) bool
	// contains filtered or unexported fields
}

func (*Server) Close

func (s *Server) Close() error

func (*Server) ListenAndServe

func (s *Server) ListenAndServe() error

func (*Server) ListenAndServeTLS

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

func (*Server) Serve

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

func (*Server) ServeQUICConn

func (s *Server) ServeQUICConn(conn quic.Connection) error

ServeQUICConn serves a single QUIC connection.

func (*Server) Upgrade

func (s *Server) Upgrade(w http.ResponseWriter, r *http.Request) (*Session, error)

type Session

type Session struct {
	// contains filtered or unexported fields
}

func (*Session) AcceptStream

func (s *Session) AcceptStream(ctx context.Context) (Stream, error)

func (*Session) AcceptUniStream

func (s *Session) AcceptUniStream(ctx context.Context) (ReceiveStream, error)

func (*Session) CloseWithError

func (s *Session) CloseWithError(code SessionErrorCode, msg string) error

func (*Session) ConnectionState

func (c *Session) ConnectionState() quic.ConnectionState

func (*Session) Context

func (s *Session) Context() context.Context

Context returns a context that is closed when the session is closed.

func (*Session) LocalAddr

func (s *Session) LocalAddr() net.Addr

func (*Session) OpenStream

func (s *Session) OpenStream() (Stream, error)

func (*Session) OpenStreamSync

func (s *Session) OpenStreamSync(ctx context.Context) (str Stream, err error)

func (*Session) OpenUniStream

func (s *Session) OpenUniStream() (SendStream, error)

func (*Session) OpenUniStreamSync

func (s *Session) OpenUniStreamSync(ctx context.Context) (str SendStream, err error)

func (*Session) RemoteAddr

func (s *Session) RemoteAddr() net.Addr

type SessionErrorCode

type SessionErrorCode uint32

SessionErrorCode is an error code for session termination.

type Stream

type Stream interface {
	SendStream
	ReceiveStream
	SetDeadline(time.Time) error
}

type StreamError

type StreamError struct {
	ErrorCode StreamErrorCode
}

StreamError is the error that is returned from stream operations (Read, Write) when the stream is canceled.

func (*StreamError) Error

func (e *StreamError) Error() string

func (*StreamError) Is

func (e *StreamError) Is(target error) bool

type StreamErrorCode

type StreamErrorCode uint8

StreamErrorCode is an error code used for stream termination.