webtransport

package module
v0.12.0-okdaichi.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 11, 2026 License: MIT Imports: 20 Imported by: 0

README

webtransport-go

Documentation PkgGoDev Code Coverage

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

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

Example

A runnable client and server example is available in example.

Projects using webtransport-go

Project Description Stars
any-sync Local-first, peer-to-peer synchronization protocol for encrypted collaborative apps GitHub Repo stars
Centrifugo Scalable real-time messaging server in a language-agnostic way. Self-hosted alternative to Pubnub, Pusher, Ably, socket.io, Phoenix.PubSub, SignalR. GitHub Repo stars
go-libp2p libp2p implementation in Go, powering Kubo (IPFS) and Lotus (Filecoin), among others GitHub Repo stars
MediaMTX Ready-to-use live media server and media proxy supporting Media-over-QUIC, SRT, WebRTC, RTSP, RTMP, HLS, and more GitHub Repo stars
signalr SignalR server and client in Go GitHub Repo stars
socket.io Socket.IO server and client implementation in Go GitHub Repo stars

If you'd like to see your project added to this list, please send us a PR.

Release Policy

webtransport-go always aims to support the latest two Go releases.

Documentation

Index

Constants

View Source 
const (
	// WTBufferedStreamRejectedErrorCode is the error code of the
	// WT_BUFFERED_STREAM_REJECTED error.
	WTBufferedStreamRejectedErrorCode quic.StreamErrorCode = 0x3994bd84

	// WTSessionGoneErrorCode is the error code of the WT_SESSION_GONE error.
	WTSessionGoneErrorCode quic.StreamErrorCode = 0x170d7b68

	// WTFlowControlErrorCode is the error code of the WT_FLOW_CONTROL_ERROR error.
	WTFlowControlErrorCode quic.StreamErrorCode = 0x045d4487

	// WTRequirementsNotMetErrorCode is the error code of the
	// WT_REQUIREMENTS_NOT_MET error.
	WTRequirementsNotMetErrorCode quic.ApplicationErrorCode = 0x212c0d48

	// WTALPNErrorCode is the error code of the WT_ALPN_ERROR error.
	WTALPNErrorCode SessionErrorCode = 0x0817b3dd
)

Variables

This section is empty.

Functions

This section is empty.

Types

type ClientConn 

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

A ClientConn is a WebTransport client connection. Multiple sessions can be established concurrently on a ClientConn.

func (*ClientConn) Dial 

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

Dial establishes a new WebTransport session on the client connection. Closing the session doesn't close the underlying QUIC connection or other sessions.

func (*ClientConn) RoundTrip 

func (c *ClientConn) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip executes an HTTP request on the underlying HTTP/3 connection.

type Config 

type Config struct {
	// MaxIncomingStreams is the maximum number of concurrent bidirectional streams
	// that the peer is allowed to open in a WebTransport session.
	// If zero, SETTINGS_WT_INITIAL_MAX_STREAMS_BIDI is not sent.
	// If negative, the setting is sent with a value of zero.
	// Values larger than 2^60 are clipped to 2^60.
	MaxIncomingStreams int64

	// MaxIncomingUniStreams is the maximum number of concurrent unidirectional streams
	// that the peer is allowed to open in a WebTransport session.
	// If zero, SETTINGS_WT_INITIAL_MAX_STREAMS_UNI is not sent.
	// If negative, the setting is sent with a value of zero.
	// Values larger than 2^60 are clipped to 2^60.
	MaxIncomingUniStreams int64

	// MaxIncomingData is the initial maximum number of bytes that the peer is allowed
	// to send in WebTransport streams. Stream headers don't count towards this limit.
	// If zero, SETTINGS_WT_INITIAL_MAX_DATA is not sent.
	// If negative, the setting is sent with a value of zero.
	// Values larger than 2^62-1 are clipped to 2^62-1.
	MaxIncomingData int64
}

Config contains configuration for a WebTransport client or server.

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

	// ApplicationProtocols is a list of application protocols that can be negotiated,
	// see section 3.3 of https://www.ietf.org/archive/id/draft-ietf-webtrans-http3-15 for details.
	ApplicationProtocols []string

	// StreamReorderingTimeout is the time an incoming WebTransport stream that cannot
	// be associated with a session is buffered. Defaults to 5 seconds.
	StreamReorderingTimeout time.Duration
	// contains filtered or unexported fields
}

Dialer is a convenience client that dials a fresh QUIC connection for each WebTransport session. It is a thin wrapper around Transport, preserved for callers that upgrade from the pre-v0.12 Dialer API.

Each Dial call opens (and, on session close, closes) its own QUIC connection. To pool multiple sessions on a single QUIC connection, use Transport.NewClientConn + ClientConn.Dial instead.

func (*Dialer) Close 

func (d *Dialer) Close() error

Close stops the Dialer from establishing new sessions. It does not close already-established sessions or externally-supplied QUIC connections.

func (*Dialer) Dial 

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

Dial dials a new WebTransport session to the given URL on a fresh QUIC connection. The QUIC connection is closed when the returned session is closed.

type HandshakeError 

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

HandshakeError describes an error with the WebTransport handshake from the peer. Upgrade returns a HandshakeError for client-caused handshake failures — wrong request method or :protocol, a rejected origin, the client's SETTINGS not arriving in time, or missing datagram support. Server-side misconfiguration (the request was not routed through a webtransport.Server, or the ResponseWriter lacks required http3 interfaces) is returned as a plain error instead.

Callers can distinguish the two with errors.As: 

var he webtransport.HandshakeError
if errors.As(err, &he) { /* client-side handshake failure */ }

func (HandshakeError) Error 

func (e HandshakeError) Error() string

type ReceiveStream 

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

A ReceiveStream is a unidirectional WebTransport receive stream.

func (*ReceiveStream) CancelRead 

func (s *ReceiveStream) CancelRead(e StreamErrorCode)

CancelRead aborts receiving on this stream. It instructs the peer to stop transmitting stream data. Read will unblock immediately, and future Read calls will fail. When called multiple times it is a no-op.

func (*ReceiveStream) Read 

func (s *ReceiveStream) Read(b []byte) (int, error)

Read reads data from the stream. Read can be made to time out using ReceiveStream.SetReadDeadline. If the stream was canceled, the error is a StreamError.

func (*ReceiveStream) SetReadDeadline 

func (s *ReceiveStream) SetReadDeadline(t time.Time) error

SetReadDeadline sets the deadline for future Read calls and any currently-blocked Read call. A zero value for t means Read will not time out.

func (*ReceiveStream) StreamID 

func (s *ReceiveStream) StreamID() quic.StreamID

StreamID returns the ID of the underlying QUIC stream.

type RequirementsNotMetError 

type RequirementsNotMetError struct {
	Message string
}

RequirementsNotMetError is returned when the peer doesn't advertise the required QUIC, HTTP/3 or WebTransport capabilities.

func (*RequirementsNotMetError) Error 

func (e *RequirementsNotMetError) Error() string

type SendStream 

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

A SendStream is a unidirectional WebTransport send stream.

func (*SendStream) CancelWrite 

func (s *SendStream) CancelWrite(e StreamErrorCode)

CancelWrite aborts sending on this stream. Data already written, but not yet delivered to the peer is not guaranteed to be delivered reliably. Write will unblock immediately, and future calls to Write will fail. When called multiple times it is a no-op.

func (*SendStream) Close 

func (s *SendStream) Close() error

Close closes the write-direction of the stream. Future calls to Write are not permitted after calling Close.

func (*SendStream) Context 

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

The Context is canceled as soon as the write-side of the stream is closed. This happens when Close() or CancelWrite() is called, or when the peer cancels the read-side of their stream. The cancellation cause is set to the error that caused the stream to close, or `context.Canceled` in case the stream is closed without error.

func (*SendStream) SetPriority 

func (s *SendStream) SetPriority(urgency int8, incremental bool)

SetPriority sets the scheduling priority for data sent on the stream. See quic.SendStream.SetPriority for the urgency/incremental semantics defined by RFC 9218.

func (*SendStream) SetWriteDeadline 

func (s *SendStream) SetWriteDeadline(t time.Time) error

SetWriteDeadline sets the deadline for future Write calls and any currently-blocked Write call. Even if write times out, it may return n > 0, indicating that some data was successfully written. A zero value for t means Write will not time out.

func (*SendStream) StreamID 

func (s *SendStream) StreamID() quic.StreamID

StreamID returns the ID of the underlying QUIC stream.

func (*SendStream) Write 

func (s *SendStream) Write(b []byte) (int, error)

Write writes data to the stream. Write can be made to time out using SendStream.SetWriteDeadline. If the stream was canceled, the error is a StreamError.

type Server 

type Server struct {
	H3 *http3.Server

	// Config is the WebTransport configuration used for new sessions.
	// If nil, the zero value is used.
	Config *Config
	// 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.Conn) error

ServeQUICConn serves a single QUIC connection.

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) ConnectionStats 

func (s *Session) ConnectionStats() quic.ConnectionStats

ConnectionStats returns the statistics of the underlying QUIC connection.

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

func (*Session) SessionState 

func (s *Session) SessionState() SessionState

SessionState returns the current state of the session

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

func (*SessionError) Is 

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

type SessionErrorCode 

type SessionErrorCode uint32

SessionErrorCode is an error code for session termination.

type SessionState 

type SessionState struct {
	// ConnectionState contains the QUIC connection state, including TLS handshake information
	ConnectionState quic.ConnectionState

	// ApplicationProtocol contains the application protocol negotiated for the session
	ApplicationProtocol string
}

SessionState contains the state of a WebTransport session

type Stream 

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

Stream is a bidirectional WebTransport stream.

func (*Stream) CancelRead 

func (s *Stream) CancelRead(e StreamErrorCode)

CancelRead aborts receiving on this stream. See ReceiveStream.CancelRead for more details.

func (*Stream) CancelWrite 

func (s *Stream) CancelWrite(e StreamErrorCode)

CancelWrite aborts sending on this stream. See SendStream.CancelWrite for more details.

func (*Stream) Close 

func (s *Stream) Close() error

Close closes the send-direction of the stream. It does not close the receive-direction of the stream.

func (*Stream) Context 

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

The Context is canceled as soon as the write-side of the stream is closed. See SendStream.Context for more details.

func (*Stream) Read 

func (s *Stream) Read(b []byte) (int, error)

Read reads data from the stream. Read can be made to time out using Stream.SetReadDeadline and Stream.SetDeadline. If the stream was canceled, the error is a StreamError.

func (*Stream) SetDeadline 

func (s *Stream) SetDeadline(t time.Time) error

SetDeadline sets the read and write deadlines associated with the stream. It is equivalent to calling both SetReadDeadline and SetWriteDeadline.

func (*Stream) SetPriority 

func (s *Stream) SetPriority(urgency int8, incremental bool)

SetPriority sets the scheduling priority for data sent on the stream. See SendStream.SetPriority for more details.

func (*Stream) SetReadDeadline 

func (s *Stream) SetReadDeadline(t time.Time) error

SetReadDeadline sets the deadline for future Read calls. See ReceiveStream.SetReadDeadline for more details.

func (*Stream) SetWriteDeadline 

func (s *Stream) SetWriteDeadline(t time.Time) error

SetWriteDeadline sets the deadline for future Write calls. See SendStream.SetWriteDeadline for more details.

func (*Stream) StreamID 

func (s *Stream) StreamID() quic.StreamID

StreamID returns the ID of the underlying QUIC stream.

func (*Stream) Write 

func (s *Stream) Write(b []byte) (int, error)

Write writes data to the stream. Write can be made to time out using Stream.SetWriteDeadline or Stream.SetDeadline. If the stream was canceled, the error is a StreamError.

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.

type StreamLimitReachedError 

type StreamLimitReachedError struct{}

StreamLimitReachedError is returned from OpenStream and OpenUniStream when it is not possible to open a new stream because the peer's stream limit is reached.

func (StreamLimitReachedError) Error 

func (e StreamLimitReachedError) Error() string

type Transport 

type Transport struct {
	// Config is the WebTransport configuration used for new sessions.
	Config *Config

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

	// ApplicationProtocols is a list of application protocols that can be negotiated,
	// see section 3.3 of https://www.ietf.org/archive/id/draft-ietf-webtrans-http3-15 for details.
	ApplicationProtocols []string

	// 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.Conn, error)
	// contains filtered or unexported fields
}

A Transport configures WebTransport clients. Dial creates a new QUIC connection for each session. To establish multiple sessions on one QUIC connection, use NewClientConn.

func (*Transport) Close 

func (d *Transport) Close() error

Close cancels session establishment waiting for peer HTTP/3 settings. It doesn't close established sessions or QUIC connections passed to NewClientConn.

func (*Transport) Dial 

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

Dial establishes a WebTransport session on a new QUIC connection. The QUIC connection is closed when the returned session is closed.

func (*Transport) NewClientConn 

func (d *Transport) NewClientConn(qconn *quic.Conn) (*ClientConn, error)

NewClientConn creates a WebTransport client connection on an existing QUIC connection. The QUIC connection must have datagrams and stream reset partial delivery enabled on both endpoints. It must only be called once per QUIC connection. The caller owns the QUIC connection and closes it when done.

type Upgrader 

type Upgrader struct {
	// ApplicationProtocols is a list of application protocols that can be negotiated,
	// see section 3.3 of https://www.ietf.org/archive/id/draft-ietf-webtrans-http3-15 for details.
	ApplicationProtocols []string

	// ReorderingTimeout is the maximum time Upgrade blocks waiting for the client's
	// SETTINGS to be received after the CONNECT request. Defaults to 5 seconds.
	// (Buffering of streams that arrive before a session's CONNECT is a separate,
	// connection-level concern handled by the Server and is not governed by this value.)
	ReorderingTimeout time.Duration

	// CheckOrigin returns true if the request Origin header is acceptable. If
	// CheckOrigin is nil, then a safe default is used: return false if the Origin
	// request header is present and the origin host is not equal to the request Host
	// header.
	//
	// A CheckOrigin function should carefully validate the request origin to prevent
	// cross-site request forgery.
	CheckOrigin func(r *http.Request) bool
}

Upgrader upgrades a single HTTP/3 request to a WebTransport session.

Configure an Upgrader with the application's origin policy, negotiable application protocols, and SETTINGS wait, then call Upgrade from the http.Handler that the Server's H3.Server dispatches to. It is safe to call an Upgrader's methods concurrently.

Upgrade requires the request to have been routed through a webtransport.Server (Serve / ListenAndServe / ServeQUICConn): the Server provisions the underlying QUIC connection, the per-connection stream router, and the WebTransport flow-control configuration via the request context, and Upgrade reads them from there. Calling Upgrade on a request that did not come from a webtransport.Server returns an error. This mirrors the standard library pattern used by http.Hijacker / websocket.Upgrader, where the upgrade is only meaningful inside a serving context.

func (*Upgrader) Upgrade 

func (u *Upgrader) Upgrade(w http.ResponseWriter, r *http.Request) (*Session, error)

Upgrade upgrades the incoming HTTP/3 request to a WebTransport session. The request must have been routed through a webtransport.Server.

A client-caused handshake failure is returned as a HandshakeError; other failures (the request was not routed through a webtransport.Server, or the ResponseWriter is missing required http3 interfaces) are returned as a plain error. Upgrade does not write an HTTP error response on failure; the caller is responsible for replying.

Source Files

View all Source files

Directories

Path Synopsis
example
client command
server command
client command
server command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.