core/go-ws

WebSocket hub with channel-based pub/sub

Find a file

Snider 3d6f14cd91 All checks were successful Security Scan / security (push) Successful in 9s Details Test / test (push) Successful in 3m49s Details feat: modernise to Go 1.26 iterators and stdlib helpers Add AllClients, AllChannels, AllSubscriptions iter.Seq iterators. Use slices.Collect(maps.Keys()) in SendToChannel/Subscriptions, range-over-int in calculateBackoff and benchmarks. Co-Authored-By: Gemini <noreply@google.com> Co-Authored-By: Virgil <virgil@lethean.io>		2026-02-23 05:32:08 +00:00
.forgejo/workflows	ci: add Forgejo Actions test and security scan workflows	2026-02-23 03:28:08 +00:00
docs	docs: graduate TODO/FINDINGS into production documentation	2026-02-20 15:01:55 +00:00
auth.go	feat(ws): add authentication on WebSocket upgrade	2026-02-20 14:34:57 +00:00
auth_test.go	feat(ws): add authentication on WebSocket upgrade	2026-02-20 14:34:57 +00:00
CLAUDE.md	docs: graduate TODO/FINDINGS into production documentation	2026-02-20 15:01:55 +00:00
errors.go	feat(auth): Phase 2 — token-based authentication on WebSocket upgrade	2026-02-20 08:12:45 +00:00
go.mod	chore: sync workspace dependency versions	2026-02-22 21:42:04 +00:00
go.sum	feat: modernise to Go 1.26 iterators and stdlib helpers	2026-02-23 05:32:08 +00:00
README.md	docs: add README with quick start and docs links	2026-02-20 15:11:20 +00:00
redis.go	feat(redis): add Redis pub/sub bridge for multi-instance Hub coordination	2026-02-20 11:23:37 +00:00
redis_test.go	refactor: apply go fix modernizers for Go 1.26	2026-02-22 21:00:17 +00:00
ws.go	feat: modernise to Go 1.26 iterators and stdlib helpers	2026-02-23 05:32:08 +00:00
ws_bench_test.go	refactor: apply go fix modernizers for Go 1.26	2026-02-22 21:00:17 +00:00
ws_test.go	feat: modernise to Go 1.26 iterators and stdlib helpers	2026-02-23 05:32:08 +00:00

README.md

go-ws

WebSocket hub for real-time streaming in Go. Implements the hub pattern with centralised connection management, named channel pub/sub, token-based authentication on upgrade, client-side reconnection with exponential backoff, and a Redis pub/sub bridge for coordinating broadcasts across multiple hub instances. The envelope pattern with a per-bridge source ID prevents loop amplification when the Redis bridge is in use.

Module: forge.lthn.ai/core/go-ws Licence: EUPL-1.2 Language: Go 1.25

Quick Start

import "forge.lthn.ai/core/go-ws"

hub := ws.NewHub()
go hub.Run(ctx)

// Mount on any HTTP mux
http.HandleFunc("/ws", hub.Handler())

// Send process output to subscribers of "process:abc"
hub.SendProcessOutput("abc", "output line")

// Redis bridge for multi-instance coordination
bridge, _ := ws.NewRedisBridge(hub, ws.RedisConfig{Addr: "localhost:6379"})
bridge.Start(ctx)

Documentation

Architecture — hub pattern, channel subscriptions, authentication, Redis bridge, envelope loop prevention
Development Guide — prerequisites, test patterns, coding standards
Project History — completed phases with commit hashes, known limitations

Build & Test

go test ./...
go test -race ./...
go test -bench=. -benchmem ./...
go build ./...

Licence

European Union Public Licence 1.2 — see LICENCE for details.