webtransport

package module
v0.0.5 Latest Latest
Warning

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

 Go to latest Published: Sep 9, 2025 License: BSD-3-Clause Imports: 13 Imported by: 2

README

webtransport-go

This package provides a WebTransport-over-HTTP/3 server implementation in Go.

This package depend of the quic-go package.

This package uses in Teonet project but has not any relation with Teonet and may be used in any other golang projects.

GoDoc Go Report Card

What is WebTransport?

Basic example

License

BSD

Documentation

Overview

Package webtransport provides a WebTransport-over-HTTP/3 server implementation in Go.

This package depend of the [quic-go](https://github.com/quic-go/quic-go) package.

This package uses in Teonet project but has not any relation with Teonet and may be used in any other golang projects.

Index

Constants

This section is empty.

Variables

View Source 
var ErrSTreamClosed = fmt.Errorf("webtransport stream closed")
View Source 
var ErrWrongStreamType = fmt.Errorf("unidirectional stream received with the wrong stream type")

Functions

This section is empty.

Types

type CertFile 

type CertFile struct {
	Path string
	Data []byte
}

A CertFile represents a TLS certificate or key, expressed either as a file path or file contents as a []byte.

type QuicConfig 

type QuicConfig quic.Config

QuicConfig is a wrapper for quic.Config.

type ReceiveStream 

type ReceiveStream struct {
	*quic.ReceiveStream
	// contains filtered or unexported fields
}

ReceiveStream wraps a quic.ReceiveStream providing a unidirectional WebTransport client server stream, including a Read function.

func (*ReceiveStream) Read 

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

Read reads up to len(p) bytes from a WebTransport unidirectional stream, and return the actual number of bytes read or an error.

Before first read it reads stream header and checks that the stream type is correct (it should be h3.STREAM_WEBTRANSPORT_UNI_STREAM). If the stream type is wrong, it returns ErrWrongStreamType. After reading the stream header it stores the requestSessionID field and marks the header as read.

type SendStream 

type SendStream struct {
	*quic.SendStream
	// contains filtered or unexported fields
}

SendStream wraps a quic.SendStream providing a unidirectional WebTransport client server stream, including a Write function.

func (*SendStream) Write 

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

Write writes up to len(p) bytes to a WebTransport unidirectional stream, and return the actual number of bytes written or an error.

Before first write it writes stream header, which is:

  • one byte with the stream type (should be h3.STREAM_WEBTRANSPORT_UNI_STREAM)
  • requestSessionID, which is the ID of the stream, as it is sent in the WebTransport stream header.

type Server 

type Server struct {
	http.Handler
	// ListenAddr sets an address to bind server to, e.g. ":4433"
	ListenAddr string
	// TLSCert defines a path to, or byte array containing, a certificate
	// (CRT file)
	TLSCert CertFile
	// TLSKey defines a path to, or byte array containing, the certificate's
	// private key (KEY file)
	TLSKey CertFile
	// AllowedOrigins represents list of allowed origins to connect from
	AllowedOrigins []string
	// Additional configuration parameters to pass onto QUIC listener
	QuicConfig *QuicConfig
}

A Server defines parameters for running a WebTransport server. Use http.HandleFunc to register HTTP/3 endpoints for handling WebTransport requests.

func (*Server) Run 

func (s *Server) Run(ctx context.Context) error

Starts a WebTransport server and blocks while it's running. Cancel the supplied Context to stop the server.

type Session 

type Session struct {
	*quic.Stream
	Session             *quic.Conn
	ClientControlStream *quic.ReceiveStream
	ServerControlStream *quic.SendStream
	// contains filtered or unexported fields
}

Session is a WebTransport session (and the Body of a WebTransport http.Request) wrapping the request stream (a quic.Stream), the two control streams and a quic.Connection.

func (*Session) AcceptSession 

func (s *Session) AcceptSession()

AcceptSession accepts an incoming WebTransport session. Call it in your http.HandleFunc.

func (*Session) AcceptStream 

func (s *Session) AcceptStream() (*quic.Stream, error)

AcceptStream accepts an incoming (that is, client-initated) bidirectional stream, blocking if necessary until one is available. Supply your own context, or use the WebTransport session's Context() so that ending the WebTransport session automatically cancels this call.

func (*Session) AcceptUniStream 

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

AcceptUniStream accepts an incoming (that is, client-initated) unidirectional stream, blocking if necessary until one is available. Supply your own context, or use the WebTransport session's Context() so that ending the WebTransport session automatically cancels this call.

func (*Session) CloseSession 

func (s *Session) CloseSession()

CloseSession cleanly closes a WebTransport session. All active streams are cancelled before terminating the session.

func (*Session) CloseWithError 

func (s *Session) CloseWithError(code quic.ApplicationErrorCode, str string)

CloseWithError closes a WebTransport session with a supplied error code and string.

func (*Session) Context 

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

Context returns the context for the WebTransport session.

func (*Session) OpenStream 

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

OpenStream creates an outgoing (that is, server-initiated) bidirectional stream. It returns immediately.

func (*Session) OpenStreamSync 

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

OpenStream creates an outgoing (that is, server-initiated) bidirectional stream. It generally returns immediately, but if the session's maximum number of streams has been exceeded, it will block until a slot is available. Supply your own context, or use the WebTransport session's Context() so that ending the WebTransport session automatically cancels this call.

func (*Session) OpenUniStream 

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

OpenUniStream creates an outgoing (that is, server-initiated) bidirectional stream. It returns immediately.

func (*Session) OpenUniStreamSync 

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

OpenUniStreamSync creates an outgoing (that is, server-initiated) unidirectional stream. It generally returns immediately, but if the session's maximum number of streams has been exceeded, it will block until a slot is available. Supply your own context, or use the WebTransport session's Context() so that ending the WebTransport session automatically cancels this call.

func (*Session) ReceiveDatagram 

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

ReceiveDatagram returns a datagram received from a WebTransport session, blocking if necessary until one is available. Supply your own context, or use the WebTransport session's Context() so that ending the WebTransport session automatically cancels this call.

Note that datagrams are unreliable - depending on network conditions, datagrams sent by the client may never be received by the server.

The datagram returned is a sequence of bytes that is sent in a single UDP packet.

WebTransport datagrams are associated with a particular HTTP/3 request, and are sent on the same connection as that request. The WebTransport datagram is sent with the "quarter stream ID" of the associated request stream, as per: https://datatracker.ietf.org/doc/html/draft-ietf-masque-h3-datagram

func (*Session) RejectSession 

func (s *Session) RejectSession(errorCode int)

AcceptSession rejects an incoming WebTransport session, returning the supplied HTML error code to the client. Call it in your http.HandleFunc.

func (*Session) SendDatagram 

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

SendDatagram sends a datagram over a WebTransport session. It use the WebTransport session's Context() so that ending the WebTransport session automatically cancels this call.

Note that datagrams are unreliable - depending on network conditions, datagrams sent by the server may never be received by the client.

A datagram is a sequence of bytes that is sent in a single UDP packet. WebTransport datagrams are associated with a particular HTTP/3 request, and are sent on the same connection as that request. The WebTransport datagram is sent with the "quarter stream ID" of the associated request stream, as per: https://datatracker.ietf.org/doc/html/draft-ietf-masque-h3-datagram

type Stream 

type Stream *quic.Stream

Stream wraps a quic.Stream providing a bidirectional client server stream, including Read and Write functions.

Source Files

View all Source files

Directories

Path Synopsis

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.