webtransport

package module
v0.11.0 Latest Latest
Warning

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

 Go to latest Published: Jun 15, 2026 License: MIT Imports: 20 Imported by: 146

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

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

func ConfigureHTTP3Server added in v0.10.0 

func ConfigureHTTP3Server(s *http3.Server)

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 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 added in v0.9.0 

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 added in v0.11.0 

type RequirementsNotMetError struct {
	Message string
}

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

func (*RequirementsNotMetError) Error added in v0.11.0 

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 added in v0.9.0 

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 added in v0.10.0 

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 added in v0.9.0 

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

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

func (s *Server) ServeQUICConn(conn *quic.Conn) 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) 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 added in v0.8.0 

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

func (*Session) RemoteAddr 

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

func (*Session) SendDatagram added in v0.8.0 

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

func (*Session) SessionState added in v0.10.0 

func (s *Session) SessionState() SessionState

SessionState returns the current state of the session

type SessionError added in v0.8.0 

type SessionError struct {
	Remote    bool
	ErrorCode SessionErrorCode
	Message   string
}

SessionError is a WebTransport connection error.

func (*SessionError) Error added in v0.8.0 

func (e *SessionError) Error() string

func (*SessionError) Is added in v0.10.0 

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

type SessionErrorCode 

type SessionErrorCode uint32

SessionErrorCode is an error code for session termination.

type SessionState added in v0.10.0 

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 added in v0.9.0 

func (s *Stream) CancelRead(e StreamErrorCode)

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

func (*Stream) CancelWrite added in v0.9.0 

func (s *Stream) CancelWrite(e StreamErrorCode)

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

func (*Stream) Close added in v0.9.0 

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 added in v0.10.0 

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 added in v0.9.0 

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 added in v0.9.0 

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 added in v0.9.0 

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 added in v0.9.0 

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.

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.