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.

Detailed documentation can be found on quic-go.net.

webtransport-go is currently unfunded.

What does this mean?

webtransport-go has been unfunded since the beginning of 2024. For the first half of the year, I have been maintaining the project in my spare time. Maintaining high-quality open-source software requires significant time and effort. This situation is becoming unsustainable, and as of June 2024, I will be ceasing maintenance work on the project.

Specifically, this means:

• I will no longer respond to issues or review PRs.
• I will not keep the API in sync with quic-go.
• Since WebTransport is still an IETF draft, browser compatibility will break as soon as the interoperability target changes.

If your project relies on WebTransport support, what can you do?

I’m glad you asked. First, I would like to hear about your use case. Second, please consider sponsoring the maintenance and future development of the project. It’s best to reach out to me via email.

Documentation

Index

• Constants
• 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) ServeListener(ln http3.QUICEarlyListener) 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 (s *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) (Stream, error)
  • func (s *Session) OpenUniStream() (SendStream, error)
  • func (s *Session) OpenUniStreamSync(ctx context.Context) (str SendStream, err error)
  • func (s *Session) ReceiveDatagram(ctx context.Context) ([]byte, error)
  • func (s *Session) RemoteAddr() net.Addr
  • func (s *Session) SendDatagram(b []byte) error
• type SessionError
  • func (e *SessionError) Error() string
• 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 Dialer

type Dialer struct {
	// TLSClientConfig is the TLS client config used when dialing the QUIC connection.
	// It must set the h3 ALPN.
	TLSClientConfig *tls.Config

	// QUICConfig is the QUIC config used when dialing the QUIC connection.
	QUICConfig *quic.Config

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

	// DialAddr is the function used to dial the underlying QUIC connection.
	// If unset, quic.DialAddrEarly will be used.
	DialAddr func(ctx context.Context, addr string, tlsCfg *tls.Config, cfg *quic.Config) (quic.EarlyConnection, error)
	// 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

	// ReorderingTimeout is the maximum time an incoming WebTransport stream that cannot be associated
	// with a session is buffered. It is also the maximum time a WebTransport connection request is
	// blocked waiting for the client's SETTINGS are received.
	// 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.
	ReorderingTimeout 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) ServeListener

func (s *Server) ServeListener(ln http3.QUICEarlyListener) error

new

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 (s *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) (Stream, 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) ReceiveDatagram

func (s *Session) ReceiveDatagram(ctx context.Context) ([]byte, error)

func (*Session) RemoteAddr

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

func (*Session) SendDatagram

func (s *Session) SendDatagram(b []byte) error

type SessionError

type SessionError struct {
	Remote    bool
	ErrorCode SessionErrorCode
	Message   string
}

SessionError is a WebTransport connection error.

func (*SessionError) Error

func (e *SessionError) Error() string

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
	Remote    bool
}

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 uint32

StreamErrorCode is an error code used for stream termination.