wsapi

Documentation

Overview

Package wsapi provides an optional WebSocket transport adapter for agentwatch.

The WebSocket protocol wraps monitor.Event — it does not define separate message types. Clients receive events as JSON-encoded monitor.Event values.

Index

• type Authenticator
• type Identity
• type Option
  • func WithAllowedOrigins(origins []string) Option
  • func WithAuthenticator(a Authenticator) Option
  • func WithHeartbeat(d time.Duration) Option
  • func WithLogger(l *slog.Logger) Option
  • func WithMaxConnections(n int) Option
  • func WithRateLimit(limit, burst int, window time.Duration) Option
  • func WithSendBuffer(n int) Option
  • func WithWriteTimeout(d time.Duration) Option
• type Server
  • func NewServer(mon *monitor.Monitor, opts ...Option) (*Server, error)
  • func (s *Server) ClientCount() int
  • func (s *Server) HandleEvent(ctx context.Context, ev monitor.Event) error
  • func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (s *Server) Stop()

Types

type Authenticator

type Authenticator interface {
	Authenticate(r *http.Request) (Identity, bool)
}

Authenticator validates WebSocket upgrade requests. Implementations should return false to reject the connection.

type Identity

type Identity struct {
	ID string
}

Identity represents an authenticated WebSocket client.

type Option

type Option func(*serverConfig)

Option configures a Server.

func WithAllowedOrigins

func WithAllowedOrigins(origins []string) Option

WithAllowedOrigins sets the allowed Origin header values for WebSocket upgrades. When empty (the default), the server allows same-origin and localhost connections.

func WithAuthenticator

func WithAuthenticator(a Authenticator) Option

WithAuthenticator sets an authenticator for WebSocket upgrade requests. When set, connections that fail authentication are rejected.

func WithHeartbeat

func WithHeartbeat(d time.Duration) Option

WithHeartbeat sets the interval for WebSocket ping/pong heartbeats. Defaults to 30 seconds.

func WithLogger

func WithLogger(l *slog.Logger) Option

WithLogger sets the structured logger. Defaults to slog.Default().

func WithMaxConnections

func WithMaxConnections(n int) Option

WithMaxConnections sets the maximum number of concurrent WebSocket connections. Zero means unlimited.

func WithRateLimit

func WithRateLimit(limit, burst int, window time.Duration) Option

WithRateLimit configures connection rate limiting per client IP. limit is max connections per window, burst is the initial token count. Defaults to 12 per minute with burst of 4.

func WithSendBuffer

func WithSendBuffer(n int) Option

WithSendBuffer sets the per-client send channel buffer size. Defaults to 64. Clients that fall behind by this many messages are evicted.

func WithWriteTimeout

func WithWriteTimeout(d time.Duration) Option

WithWriteTimeout sets the maximum duration for a write to complete. Defaults to 10 seconds.

type Server

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

Server is a WebSocket transport adapter for agentwatch. It implements monitor.EventSink: events from the monitor are fanned out to all connected WebSocket clients.

On connect, clients receive an initial snapshot event. Subsequent events (deltas, lifecycle, health) are delivered as they arrive from the monitor.

func NewServer

func NewServer(mon *monitor.Monitor, opts ...Option) (*Server, error)

NewServer creates a WebSocket server that broadcasts monitor events to connected clients. The server implements monitor.EventSink.

func (*Server) ClientCount

func (s *Server) ClientCount() int

ClientCount returns the number of currently connected clients.

func (*Server) HandleEvent

func (s *Server) HandleEvent(ctx context.Context, ev monitor.Event) error

HandleEvent implements monitor.EventSink. It fans out the event to all connected WebSocket clients. Returns quickly via non-blocking sends.

func (*Server) ServeHTTP

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

ServeHTTP handles WebSocket upgrade requests. Attach this to your HTTP router at the desired path (e.g., "/ws").

func (*Server) Stop

func (s *Server) Stop()

Stop disconnects all clients and prevents new connections.