realtime

package
v0.2.2 Latest Latest
Warning

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

Go to latest
Published: Nov 3, 2026 License: MIT Imports: 26 Imported by: 0

Documentation

Overview

Package realtime is chok's battery for pushing events to browsers as they happen: a Hub of topics that clients subscribe to over a WebSocket or a server-sent event stream, opened with one-time tickets, resumed after a reconnect from a short replay buffer, and shared by the replicas of a deployment through Redis.

hub := realtime.MustNew(cfg.Realtime,
	realtime.Authn(auth.Authn()), // a ticket carries the signed-in user
	realtime.Authorize(func(ctx context.Context, topic string) error {
		p, _ := chok.PrincipalFrom(ctx)
		if canWatch(ctx, p.UserID, topic) {
			return nil
		}
		return chok.ErrForbidden.Msgf("not your order")
	}),
)
app.Use(d, auth, hub) // POST /realtime/ticket, GET /realtime/ws and /realtime/sse

// After the write commits, from any code that has the hub:
err := hub.Publish(ctx, "order:"+o.RID, "order.updated", o)

Tickets

A browser cannot put an Authorization header on a WebSocket or an EventSource, and a long-lived token in a URL ends up in proxy logs. So the page first POSTs to {Path}/ticket with its token (Authn guards the endpoint) and gets a ticket: 32 random bytes, redeemable once, within Config.TicketTTL, by the ws or sse endpoint, which binds the connection to the ticket's principal. Without Authn the endpoint is public and tickets are anonymous.

Topics

A topic is 1 to 128 of A-Z a-z 0-9 _ . : -, such as order:ord_123 or jobs. Authorize decides who may subscribe to what; without it, a connection may subscribe to nothing but its own user's topic, user:<UserID>, which is reserved: only that user's connections subscribe to it, and Send publishes to it. A refused subscription is a refused event to the client, not a closed connection. The event types refused, reset and error are the hub's: Publish refuses them.

In the browser

Server-sent events are the simpler transport when the page only listens. EventSource reconnects by itself, but a ticket is good once: on error, close it and open a new one with a fresh ticket and the last event's ID.

let last = "";
async function listen() {
  const {ticket} = await (await fetch("/realtime/ticket", {method: "POST", headers: {Authorization: "Bearer " + token}})).json();
  const es = new EventSource(`/realtime/sse?ticket=${ticket}&topics=jobs&last_event_id=${last}`);
  es.addEventListener("run.finished", e => { last = e.lastEventId; show(JSON.parse(e.data)); });
  es.addEventListener("reset", reload); // too far behind: fetch the state anew
  es.addEventListener("refused", e => console.warn(JSON.parse(e.data).data.message));
  es.onerror = () => { es.close(); setTimeout(listen, 3000); }; // the connection broke
}

A WebSocket also takes the client's frames: {"subscribe":["room:7"], "after":"<last event id>"} and {"unsubscribe":["room:7"]}; each event arrives as one JSON text frame, an Event.

Delivery

Each event gets an ID, "<origin>-<seq>", and goes to the subscribers' send queues; the hub never waits for a slow connection — one that has Config.SendBuffer events waiting is dropped (WebSocket close code 4408). The last Config.Replay events, across topics, stay in memory: a client that resumes after an event ID gets the events of its topics since then, or a reset event per topic when that event is gone, which tells it to fetch the state anew. Events are not stored anywhere else: a client that must not miss one reads the state from the API after a reset.

Several replicas

With Redis, tickets live in Redis — any replica redeems a ticket, once — and every Publish also goes to the channel Config.Channel, where the other replicas pick it up for their subscribers and their replay buffers. Start runs that subscription, reconnecting after a loss; Health fails while it is down. Without Redis, run one replica or pin clients to one. Resuming on a replica that just started finds an empty buffer: the client gets a reset, as designed.

Example

A hub whose topic news anyone may follow, a stream reading it the way a browser's EventSource does, and an event published to it.

package main

import (
	"bufio"
	"context"
	"encoding/json/v2"
	"fmt"
	"log/slog"
	"net/http"
	"net/http/httptest"
	"strings"

	"github.com/zynthara/chok"
	"github.com/zynthara/chok/realtime"
)

func main() {
	hub := realtime.MustNew(realtime.Config{Path: "/realtime", Replay: 256},
		realtime.Authorize(func(ctx context.Context, topic string) error {
			if topic == "news" {
				return nil
			}
			return chok.ErrForbidden.Msgf("no topic %s", topic)
		}))
	app := chok.New(chok.Base{}, chok.Logger(slog.New(slog.DiscardHandler)))
	app.Use(hub) // POST /realtime/ticket, GET /realtime/ws and /realtime/sse
	srv := httptest.NewServer(app.Handler())
	defer srv.Close()
	defer func() { _ = hub.Close(context.Background()) }()

	// The page: a ticket, then the stream (no Authn: tickets are anonymous).
	resp, err := http.Post(srv.URL+"/realtime/ticket", "", nil)
	if err != nil {
		panic(err)
	}
	var t struct {
		Ticket string `json:"ticket"`
	}
	if err := json.UnmarshalRead(resp.Body, &t); err != nil {
		panic(err)
	}
	_ = resp.Body.Close()
	stream, err := http.Get(srv.URL + "/realtime/sse?topics=news&ticket=" + t.Ticket)
	if err != nil {
		panic(err)
	}
	defer func() { _ = stream.Body.Close() }()
	lines := bufio.NewScanner(stream.Body)
	lines.Scan() // retry: 3000 — the stream is subscribed

	// The server, after a commit:
	_ = hub.Publish(context.Background(), "news", "headline", map[string]string{"title": "chok ships realtime"})

	for lines.Scan() {
		if data, ok := strings.CutPrefix(lines.Text(), "data: "); ok {
			var ev realtime.Event
			if err := json.Unmarshal([]byte(data), &ev); err != nil {
				panic(err)
			}
			fmt.Println(ev.Topic, ev.Type, string(ev.Data))
			break
		}
	}
}
Output:
news headline {"title":"chok ships realtime"}

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Config

type Config struct {
	// Path prefixes the three endpoints: {Path}/ticket, {Path}/ws and
	// {Path}/sse. It starts with a slash and does not end with one.
	Path string `yaml:"path" default:"/realtime"`
	// AllowedOrigins admits browser WebSockets from these origins besides
	// the server's own host: host patterns in path.Match syntax, such as
	// app.example.com or *.example.com, matched against the Origin's host
	// (against scheme://host when a pattern has a scheme); "*" admits any
	// origin. Empty admits the same host only. Server-sent event streams
	// are ordinary requests that CORS governs.
	AllowedOrigins []string `yaml:"allowed_origins"`
	// SendBuffer is how many published events may wait for one
	// connection. A connection that falls further behind is a slow
	// consumer: the hub drops it (a WebSocket with close code 4408) and
	// counts it in Stats.Dropped. What a subscription adds — the events it
	// replays, its refused or reset events — does not count, but nothing
	// waits beyond SendBuffer + Replay + 2 × MaxSubscriptions events.
	SendBuffer int `yaml:"send_buffer" default:"64"`
	// PingInterval paces the heartbeats: a WebSocket ping, which the
	// client must answer within two intervals or be disconnected, and an
	// SSE comment line.
	PingInterval time.Duration `yaml:"ping_interval" default:"25s"`
	// TicketTTL is how long a ticket from {Path}/ticket can be redeemed.
	TicketTTL time.Duration `yaml:"ticket_ttl" default:"60s"`
	// ConnectionTTL bounds the lifetime of the ticket's principal snapshot.
	// Reconnect obtains a fresh ticket through Authn.
	ConnectionTTL time.Duration `yaml:"connection_ttl" default:"5m"`
	// Replay is how many recent events the hub keeps, across all topics,
	// for clients that resume after an event they saw; 0 turns resuming
	// off, so every resume gets a reset event.
	Replay int `yaml:"replay" default:"256"`
	// MaxSubscriptions caps the topics of one connection: beyond it a
	// WebSocket is closed with 1008 and a stream request answers 400.
	MaxSubscriptions int `yaml:"max_subscriptions" default:"64"`
	// Channel is the Redis channel of the backplane and the prefix of the
	// tickets' keys; deployments sharing one Redis each need their own.
	Channel string `yaml:"channel" default:"chok:realtime"`
}

Config is the realtime section of an application's configuration:

realtime:
  allowed_origins: ["app.example.com"]
  ping_interval: 25s
  replay: 256

New gives a zero SendBuffer, PingInterval, TicketTTL or MaxSubscriptions the defaults below, whether the Config comes from a file or from code. Path, Replay and Channel have no zero-value default: a Config built in code sets Path, sets Replay to resume at all, and sets Channel when it uses Redis.

func (*Config) Validate

func (c *Config) Validate() error

Validate checks the section. It runs when chok.Load reads the configuration and again in New, after New's defaults.

type Event

type Event struct {
	// ID is "<origin>-<seq>": origin is a random id the publishing Hub
	// draws in New, seq counts that Hub's events. A client resumes after
	// the ID it saw last; IDs from different replicas are not ordered.
	// The refused and reset events the hub sends itself have no ID.
	ID string `json:"id"`
	// Topic is the topic the event was published to.
	Topic string `json:"topic"`
	// Type is the application's name for the event, such as
	// order.updated or run.finished. The hub sends two of its own:
	// refused, for a subscription refused, and reset, for a resume that
	// went too far back. Neither is error, which Publish refuses too: a
	// browser's EventSource fires its own connection errors under that
	// name.
	Type string `json:"type"`
	// Data is the published value as JSON; empty when nil was published.
	Data json.RawMessage `json:"data,omitzero"`
	// At is when the event was published, in UTC.
	At time.Time `json:"at"`
}

Event is one event as a client receives it: a WebSocket text frame carries one, and so does the data line of a server-sent event.

type Hub

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

Hub is the realtime battery: the topics, the connections subscribed to them over WebSocket or server-sent events, the tickets that open them, and, with Redis, the backplane to the other replicas. Register it with app.Use: it mounts its endpoints, Start runs the backplane, Close ends the connections.

func MustNew

func MustNew(cfg Config, opts ...Option) *Hub

MustNew is New that panics on error.

func New

func New(cfg Config, opts ...Option) (*Hub, error)

New builds a hub from cfg after checking cfg and every option; nothing runs until Start, and nothing is served until Mount.

func (*Hub) Close

func (h *Hub) Close(ctx context.Context) error

Close ends every connection — a WebSocket with 1001, a stream by finishing it — and stops the backplane, then waits within ctx for the connections' handlers to return. The App calls it on stop, bounded by app.shutdown_timeout. Streams already ended when the HTTP server began its shutdown, which waits for open requests.

func (*Hub) Disconnect

func (h *Hub) Disconnect(userID string)

Disconnect ends the current connections of userID on this replica. Call after revoking sessions or changing authorization. With several replicas, deliver the revocation to every replica; ConnectionTTL is the fallback bound. Outstanding tickets still live until TicketTTL.

func (*Hub) Health

func (h *Hub) Health(context.Context) error

Health reports the backplane: an error while it has not subscribed yet or has lost its connection, nil once subscribed, and nil without Redis. The App waits for it at start, so with Redis an instance takes traffic once it hears the other replicas.

func (*Hub) Mount

func (h *Hub) Mount(r chok.Router)

Mount registers the three endpoints under Config.Path:

POST {Path}/ticket   a one-time ticket; behind Authn when given, else public
GET  {Path}/ws       a WebSocket, opened with ?ticket=…[&topics=a,b]
GET  {Path}/sse      a server-sent event stream: ?ticket=…&topics=a,b

The ws and sse routes run no authentication middleware, so the OpenAPI document lists them without security: the ticket in their query is what admits a client, so a browser's WebSocket and EventSource never carry the long-lived token, nor does any URL. The ticket route lists the schemes of the Authn given, if any.

func (*Hub) Name

func (h *Hub) Name() string

Name is "realtime", its name in the health report.

func (*Hub) Publish

func (h *Hub) Publish(ctx context.Context, topic, typ string, data any) error

Publish sends an event of type typ, with data encoded as JSON (nil sends none), to the subscribers of topic — this replica's at once and, with Redis, the other replicas' through the backplane. A topic is 1 to 128 of A-Z a-z 0-9 _ . : -, and so is typ, which must not be refused or reset, the hub's own, nor error, the name of an EventSource's connection errors. Publish fails only on a bad topic or type, or data that does not encode; no subscriber is not an error, and a backplane that does not take the event is logged, not returned: the local subscribers have it. It does not block on slow connections: one that has Config.SendBuffer events waiting is dropped.

func (*Hub) Send

func (h *Hub) Send(ctx context.Context, userID, typ string, data any) error

Send publishes to userID's own topic: Publish(ctx, "user:"+userID, typ, data). Only that user's connections may subscribe to it.

func (*Hub) Start

func (h *Hub) Start(ctx context.Context) error

Start runs the Redis backplane until ctx ends: it subscribes to Config.Channel, delivers what the other replicas publish, and reconnects after a disconnect, logging it at Warn. Without Redis there is nothing to run and Start returns nil at once.

func (*Hub) Stats

func (h *Hub) Stats() Stats

Stats returns the hub's connections and counters.

type Option

type Option func(*options)

Option configures New.

func Authn

func Authn(mw chok.Middleware) Option

Authn guards {Path}/ticket with mw — identity's Authn(), typically — so that a ticket carries the principal mw puts in the request, and the connection it opens acts for that user. Without Authn the ticket endpoint is public and its tickets are anonymous, for pages that serve guests.

func Authorize

func Authorize(fn func(ctx context.Context, topic string) error) Option

Authorize decides which topics a connection may subscribe to: fn runs once per subscription, with a context that carries the ticket's principal (none for an anonymous ticket), and refuses the subscription by returning an error. The client then gets a refused event, with the reason and message of the error when it is a *chok.Error or a chok.Coder, and Forbidden otherwise (that error is logged at Warn); its other subscriptions stand. Without Authorize every topic is refused except the connection's own user:<UserID>. Topics starting with user: always follow that rule: fn never sees them.

func Logger

func Logger(l *slog.Logger) Option

Logger is where the hub logs; the default is slog.Default().

func Redis

func Redis(client *goredis.Client) Option

Redis makes the hub one of several replicas sharing client: tickets live in Redis, so any replica redeems a ticket and only once, and every Publish also reaches the other replicas' subscribers, through PUBLISH on Config.Channel. A nil client is the same as no Redis option; the client of cache.Redis() can be passed as it is. The hub does not close the client.

type Stats

type Stats struct {
	// Connections counts the open WebSocket and SSE connections.
	Connections int `json:"connections"`
	// Users counts the distinct users among the connections that carry a
	// principal.
	Users int `json:"users"`
	// Topics counts the topics with at least one subscriber.
	Topics int `json:"topics"`
	// Published counts this process's Publish calls, Send's included.
	Published uint64 `json:"published"`
	// Delivered counts the events put on connections' send queues, live
	// or replayed; refused and reset events are not counted.
	Delivered uint64 `json:"delivered"`
	// Dropped counts the connections dropped as slow consumers.
	Dropped uint64 `json:"dropped"`
	// Backplane is "" without Redis, else connected or disconnected.
	Backplane string `json:"backplane"`
}

Stats is a snapshot of a Hub: its connections and its counters since New.

Jump to

Keyboard shortcuts

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