sse

README

tinysse

Client and Event Server, SSE (Server-Sent Events) protocol compatible with Go (Server) and TinyGo (WASM Client).

Get Started

Installation

go get github.com/tinywasm/sse

Quick Links

• Usage Guide: How to set up Server and Client.
• Configuration: Detailed configuration options.
• Architecture: Diagrams and system overview.
• Design Principles: Why we built it this way.

Documentation

Index

• func New(c *Config) *tinySSE
• type ChannelProvider
• type Config
• type SSEMessage
• type SSEPublisher
• type SSEServer
  • func (s *SSEServer) Publish(data []byte, channels ...string)
  • func (s *SSEServer) PublishEvent(event string, data []byte, channels ...string)
  • func (s *SSEServer) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type ServerConfig

Functions

func New

func New(c *Config) *tinySSE

New creates a new tinySSE instance with shared configuration.

Types

type ChannelProvider

type ChannelProvider interface {
	// ResolveChannels extracts channels for an SSE connection.
	// Called once when client connects.
	//
	// Parameters:
	//   - r: The HTTP request (contains cookies, headers, query params)
	//
	// Returns:
	//   - channels: List of channels to subscribe (e.g., ["all", "user:123", "role:admin"])
	//   - err: If non-nil, connection is rejected with 401/403
	ResolveChannels(r *http.Request) (channels []string, err error)
}

ChannelProvider resolves SSE channels for a connection. Implemented by external packages (e.g., crudp session handler).

type Config

type Config struct {
	// Log is the centralized logger function.
	// If nil, logging is disabled.
	Log func(args ...any)
}

Config holds the shared configuration for both Server and Client.

type SSEMessage

type SSEMessage struct {
	ID    string // SSE "id:" field - Required. Used for Last-Event-ID reconnection.
	Event string // SSE "event:" field - Optional. Allows routing to different handlers.
	Data  []byte // SSE "data:" field - RAW bytes, library does NOT parse.
}

SSEMessage represents a message sent over SSE. Shared by both Server (for broadcasting) and Client (for consumption).

type SSEPublisher

type SSEPublisher interface {
	// Publish sends data to clients subscribed to the specified channels.
	// Data can contain newlines - tinysse handles them internally.
	Publish(data []byte, channels ...string)

	// PublishEvent sends data with an event type for client-side routing.
	PublishEvent(event string, data []byte, channels ...string)
}

SSEPublisher allows publishing messages to SSE clients. Implemented by sse.SSEServer.

type SSEServer

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

SSEServer handles Server-Sent Events HTTP connections.

func (*SSEServer) Publish

func (s *SSEServer) Publish(data []byte, channels ...string)

Publish implements SSEPublisher.Publish

func (*SSEServer) PublishEvent

func (s *SSEServer) PublishEvent(event string, data []byte, channels ...string)

PublishEvent implements SSEPublisher.PublishEvent

func (*SSEServer) ServeHTTP

func (s *SSEServer) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements the http.Handler interface.

type ServerConfig

type ServerConfig struct {
	// ClientChannelBuffer prevents blocking on slow clients.
	// Recommended: 10-100.
	ClientChannelBuffer int

	// HistoryReplayBuffer manages the "Last-Event-ID" replay history.
	// Recommended: Depends on message frequency.
	HistoryReplayBuffer int

	// ChannelProvider resolves channels for each SSE connection.
	// If nil, a default provider is used that rejects all connections
	// with error "channel provider not configured".
	ChannelProvider ChannelProvider
}

ServerConfig holds configuration strictly for the Server HTTP Handler.