realtime

package
v0.32.0 Latest Latest
Warning

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

Go to latest
Published: Oct 31, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package realtime implements the nexus.io.realtime plugin: a WebSocket transport that streams LLM token deltas, tool previews, voice audio, and cancellation envelopes to connected clients, and accepts text input, audio chunks, cancel, and HITL responses going the other way.

This is Phase 3 of Idea 18 (multimodal & voice IO). Phase 4 will land nexus.io.voice (VAD + ASR + TTS); Phase 5 may eventually fold the envelope shape into io/browser. Until then the realtime transport stands alongside the TUI and browser plugins as a lower-latency option for clients that want raw stream.delta deltas without the browser UI's hub state machine.

Security: there is **no auth in v1**. Origin checks and bearer-token validation are tracked as follow-ups; operators running this on a public network must front it with a reverse proxy that does its own authentication. See docs/src/configuration/reference.md for the nexus.io.realtime entry.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func New

func New() engine.Plugin

New creates a new realtime IO plugin. Used by the plugin registry.

Types

type Plugin

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

Plugin is the realtime IO plugin. It hosts a WebSocket server and bridges a small set of bus events into JSON envelopes for clients.

func (*Plugin) Capabilities

func (p *Plugin) Capabilities() []engine.Capability

func (*Plugin) Dependencies

func (p *Plugin) Dependencies() []string

func (*Plugin) Emissions

func (p *Plugin) Emissions() []string

func (*Plugin) ID

func (p *Plugin) ID() string

func (*Plugin) Init

func (p *Plugin) Init(ctx engine.PluginContext) error

Init reads config and constructs (but does not start) the server.

func (*Plugin) Name

func (p *Plugin) Name() string

func (*Plugin) Ready

func (p *Plugin) Ready() error

Ready starts the HTTP server.

func (*Plugin) Requires

func (p *Plugin) Requires() []engine.Requirement

func (*Plugin) Shutdown

func (p *Plugin) Shutdown(ctx context.Context) error

Shutdown unsubscribes and closes all client connections.

func (*Plugin) Subscriptions

func (p *Plugin) Subscriptions() []engine.EventSubscription

Subscriptions declares the events forwarded to clients. We attach a vetoable subscription for before:tool.invoke for read-only observation — the handler never sets Veto. The remainder are post-event observers.

func (*Plugin) Version

func (p *Plugin) Version() string

type Server

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

Server is the HTTP/WebSocket front-end for the realtime IO plugin. It owns a connection set, a single mux registered at the configured path, and a handler that the plugin calls into for each inbound envelope.

func NewServer

func NewServer(logger *slog.Logger, addr, path string, maxClients int, onInbound func(env envelope, headers map[string]string)) *Server

NewServer constructs a server but does not listen yet — call Start. Mostly broken out from the plugin so tests can construct a server against an ephemeral port without touching plugin lifecycle. onInbound is called once per inbound frame with the frame and the X-Nexus-* headers of the upgrade the connection was opened with. The headers are passed alongside rather than folded into the envelope on purpose: the envelope is the client-authored wire type, so a field on it would be something a client could set, and these must come from the transport.

func (*Server) Addr

func (s *Server) Addr() string

Addr returns the listener's bound address (useful for tests where addr=":0" picks an ephemeral port).

func (*Server) Broadcast

func (s *Server) Broadcast(env envelope)

Broadcast queues an envelope for every connected client. A client whose send buffer is full is logged and dropped on this frame — we do not block on slow consumers.

func (*Server) ClientCount

func (s *Server) ClientCount() int

ClientCount returns the number of currently-connected clients.

func (*Server) Handler

func (s *Server) Handler() http.Handler

Handler returns the http.Handler the server uses to upgrade incoming WebSocket connections. Exposed so tests can mount it on httptest.Server without going through Start().

func (*Server) Shutdown

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

Shutdown closes all client connections and stops the HTTP server.

func (*Server) Start

func (s *Server) Start() error

Start binds to the configured address and serves WebSocket upgrades. Returns once the listener is bound; the actual Serve runs in a background goroutine.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL