webtransport

package module
v0.11.0-okdaichi.2 Latest Latest
Warning

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

 Go to latest Published: Aug 2, 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-15 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
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
signalr SignalR server and client 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 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

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

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

type RequirementsNotMetError 

type RequirementsNotMetError struct {
	Message string
}

RequirementsNotMetError is returned when the peer doesn't advertise the required 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) 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) 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
	// 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) 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) 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 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 and the per-connection stream router 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.