fallback

Documentation

Overview

SSE provides a Server-Sent Events fallback for environments where both WebTransport (UDP) and WebSocket (TCP upgrade) are blocked.

SSE is unidirectional (server → client only). For client → server, pair with regular HTTP POST requests.

This is the most degraded fallback mode — use only when nothing else works.

Package fallback provides a transparent WebSocket fallback for the wt framework.

When a client can't use WebTransport (Safari, corporate firewalls blocking UDP, old browsers), the fallback layer serves the same handlers over WebSocket. Stream multiplexing is simulated over the single WebSocket connection using a simple framing protocol.

Index

• func Handler(onConnect func(*WSConn)) http.Handler
• type SSEClient
• type SSEHub
  • func NewSSEHub() *SSEHub
  • func (h *SSEHub) Broadcast(event string, data any)
  • func (h *SSEHub) Close(clientID string)
  • func (h *SSEHub) Count() int
  • func (h *SSEHub) Handler() http.Handler
  • func (h *SSEHub) Send(clientID, event string, data any) error
• type Transport
  • func (t Transport) String() string
• type WSConn
  • func NewWSConn(ws *websocket.Conn) *WSConn
  • func (c *WSConn) AcceptStream() (*WSStream, error)
  • func (c *WSConn) Close() error
  • func (c *WSConn) OpenStream() (*WSStream, error)
  • func (c *WSConn) ReceiveDatagram() ([]byte, error)
  • func (c *WSConn) SendDatagram(data []byte) error
• type WSStream
  • func (s *WSStream) Close() error
  • func (s *WSStream) ID() uint32
  • func (s *WSStream) Read(b []byte) (int, error)
  • func (s *WSStream) Write(b []byte) (int, error)

Functions

func Handler

func Handler(onConnect func(*WSConn)) http.Handler

Handler returns an http.Handler that accepts WebSocket connections and provides the same multiplexed stream/datagram API. Use this alongside the WebTransport server to serve fallback clients.

Types

type SSEClient

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

SSEClient represents a connected SSE client.

type SSEHub

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

SSEHub manages SSE client connections.

func NewSSEHub

func NewSSEHub() *SSEHub

NewSSEHub creates a new SSE hub.

func (*SSEHub) Broadcast

func (h *SSEHub) Broadcast(event string, data any)

Broadcast sends an event to all connected clients.

func (*SSEHub) Close

func (h *SSEHub) Close(clientID string)

Close disconnects a specific client.

func (*SSEHub) Count

func (h *SSEHub) Count() int

Count returns the number of connected SSE clients.

func (*SSEHub) Handler

func (h *SSEHub) Handler() http.Handler

Handler returns an http.Handler that accepts SSE connections. Use alongside the WebTransport server for maximum compatibility.

Usage:

hub := fallback.NewSSEHub()
http.Handle("/events", hub.Handler())

func (*SSEHub) Send

func (h *SSEHub) Send(clientID, event string, data any) error

Send sends an event to a specific client.

type Transport

type Transport int

Transport identifies the connection type.

const (
	TransportWebTransport Transport = iota
	TransportWebSocket
)

func (Transport) String

func (t Transport) String() string

type WSConn

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

WSConn wraps a WebSocket connection and provides stream multiplexing.

func NewWSConn

func NewWSConn(ws *websocket.Conn) *WSConn

NewWSConn wraps a websocket.Conn with multiplexing support.

func (*WSConn) AcceptStream

func (c *WSConn) AcceptStream() (*WSStream, error)

AcceptStream waits for the next incoming stream from the client.

func (*WSConn) Close

func (c *WSConn) Close() error

Close closes the WebSocket connection and all streams.

func (*WSConn) OpenStream

func (c *WSConn) OpenStream() (*WSStream, error)

OpenStream creates a new outbound stream.

func (*WSConn) ReceiveDatagram

func (c *WSConn) ReceiveDatagram() ([]byte, error)

ReceiveDatagram receives a datagram-like message.

func (*WSConn) SendDatagram

func (c *WSConn) SendDatagram(data []byte) error

SendDatagram sends a datagram-like message (simulated over WebSocket).

type WSStream

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

WSStream is a multiplexed stream over a WebSocket connection.

func (*WSStream) Close

func (s *WSStream) Close() error

Close closes the stream.

func (*WSStream) ID

func (s *WSStream) ID() uint32

ID returns the stream ID.

func (*WSStream) Read

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

Read reads data from the stream.

func (*WSStream) Write

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

Write writes data to the stream.