Show the connection state in the neoirc-cli status bar (closes #229)

The status bar had colour tags turned on, so tview read "[connected]"
and "[disconnected]" as tags and dropped them. It dropped all or part
of a nick, a target or a window name holding square brackets the same
way.

The status bar now has colour tags turned off. It wrote none of its
own, so every bracket shows as it is. TestStartUp checks that the
status bar shows [disconnected] at start-up. TestStatusBar checks
[connected], and checks nicks and a /query target that hold brackets.

Model: opus-5-5

.golangci.yml

@@ -61,6 +61,10 @@ linters:
               desc: >-
                 Test-support code belongs in test files and in packages whose
                 directory name ends in test, not in the shipped binary.
+            - pkg: sneak.berlin/go/neoirc/internal/dbtest
+              desc: >-
+                Test-support code belongs in test files and in packages whose
+                directory name ends in test, not in the shipped binary.
     # Only decisions already recorded in the Go package defaults are
     # listed here. Every entry matches the module path exactly.
     gomodguard_v2:

README.md

@@ -3342,6 +3342,7 @@ neoirc/
 │   │   └── schema/
 │   │       ├── 000.sql     # schema_migrations bootstrap
 │   │       └── 001_initial.sql
+│   ├── dbtest/             # Gives each test its own database; only tests import it
 │   ├── globals/            # Application-wide metadata
 │   │   └── globals.go
 │   ├── handlers/           # HTTP request handlers

internal/cli/app.go

@@ -34,30 +34,44 @@ type App struct {
 
 // Run creates and runs the CLI application.
 func Run() {
-	app := &App{ //nolint:exhaustruct
-		ui:   NewUI(),
-		nick: "guest",
-	}
-
-	app.ui.OnInput(app.handleInput)
-	app.ui.SetStatus(app.nick, "", "disconnected")
-
-	app.ui.AddStatus(
-		"Welcome to neoirc-cli — an IRC-style client",
-	)
-	app.ui.AddStatus(
-		"Type [yellow]/connect <server-url>" +
-			"[white] to begin, " +
-			"or [yellow]/help[white] for commands",
-	)
-
-	err := app.ui.Run()
+	err := run(NewUI())
 	if err != nil {
 		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
 		os.Exit(1)
 	}
 }
 
+// run starts the client on ui and returns when ui stops. Tests
+// call it with ui on a simulation screen.
+func run(ui *UI) error {
+	app := &App{ //nolint:exhaustruct
+		ui:   ui,
+		nick: "guest",
+	}
+
+	app.ui.OnInput(app.handleInput)
+
+	// SetStatus and AddStatus wait for the event loop, which
+	// app.ui.Run starts below, so they run on a goroutine. The
+	// nick is read first, as a typed /nick may change app.nick.
+	nick := app.nick
+
+	go func() {
+		app.ui.SetStatus(nick, "", "disconnected")
+
+		app.ui.AddStatus(
+			"Welcome to neoirc-cli — an IRC-style client",
+		)
+		app.ui.AddStatus(
+			"Type [yellow]/connect <server-url>" +
+				"[white] to begin, " +
+				"or [yellow]/help[white] for commands",
+		)
+	}()
+
+	return app.ui.Run()
+}
+
 func (a *App) handleInput(text string) {
 	if strings.HasPrefix(text, "/") {
 		a.handleCommand(text)
@@ -610,23 +624,30 @@ func (a *App) cmdWindow(args string) {
 
 	_, _ = fmt.Sscanf(args, "%d", &bufIndex)
 
-	a.ui.SwitchBuffer(bufIndex)
-
 	a.mu.Lock()
 	nick := a.nick
 	a.mu.Unlock()
 
-	if bufIndex >= 0 && bufIndex < a.ui.BufferCount() {
-		buf := a.ui.buffers[bufIndex]
-		if buf.Name != "(status)" {
+	// Read the name before switching. A message from the server can
+	// add a buffer at any time, but only at the end, so bufIndex
+	// still names this buffer when SwitchBuffer runs.
+	name, found := a.ui.BufferName(bufIndex)
+	if found {
+		a.ui.SwitchBuffer(bufIndex)
+
+		if name != "(status)" {
 			a.mu.Lock()
-			a.target = buf.Name
+			a.target = name
 			a.mu.Unlock()
 
 			a.ui.SetStatus(
-				nick, buf.Name, "connected",
+				nick, name, "connected",
 			)
 		} else {
+			a.mu.Lock()
+			a.target = ""
+			a.mu.Unlock()
+
 			a.ui.SetStatus(nick, "", "connected")
 		}
 	}

internal/cli/app_internal_test.go

@@ -4,7 +4,10 @@ import (
 	"io"
 	"net/http"
 	"net/http/httptest"
+	"slices"
+	"strings"
 	"testing"
+	"time"
 
 	"github.com/gdamore/tcell/v2"
 	api "sneak.berlin/go/neoirc/internal/cli/api"
@@ -20,6 +23,23 @@ const (
 	testText      = "hello"
 )
 
+// eventLoopTimeout is how long a test waits for a typed line to
+// be handled, for the welcome lines, or for the UI to stop, before
+// it fails.
+const eventLoopTimeout = 5 * time.Second
+
+// holdTime is how long TestLinesKeepOrder holds the first line,
+// which gives the second line time to start too early.
+const holdTime = 200 * time.Millisecond
+
+// welcomeLines is the number of lines run adds to the status
+// window when the client starts.
+const welcomeLines = 2
+
+// checkInterval is how often TestStartUp reads the status window
+// while it waits for the welcome lines.
+const checkInterval = 10 * time.Millisecond
+
 func TestMemberPrefix(t *testing.T) {
 	t.Parallel()
 
@@ -219,6 +239,270 @@ func TestJoinResponse(t *testing.T) {
 	}
 }
 
+// TestAltDigit checks that Alt and a digit shows that window and
+// makes its channel or user the target, as /window does. Window
+// 0, the status window, leaves no target.
+func TestAltDigit(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name  string
+		digit rune
+		// The buffer shown and the target after the key.
+		wantBuffer string
+		wantTarget string
+	}{
+		{
+			name:       "channel window",
+			digit:      '1',
+			wantBuffer: testChannel,
+			wantTarget: testChannel,
+		},
+		{
+			name:       "status window",
+			digit:      '0',
+			wantBuffer: "(status)",
+			wantTarget: "",
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			t.Parallel()
+
+			app := &App{ui: NewUI(), nick: testNick, target: testOtherNick}
+			handled := handledLines(app)
+			runUI(t, app.ui)
+
+			// Window 1 is the channel. Window 2, the one shown, is
+			// the other user's.
+			app.ui.SwitchToBuffer(testChannel)
+			app.ui.SwitchToBuffer(testOtherNick)
+
+			key := tcell.NewEventKey(tcell.KeyRune, test.digit, tcell.ModAlt)
+			app.ui.app.QueueEvent(key)
+			waitHandled(t, handled, "/window "+string(test.digit))
+
+			var shown string
+
+			app.ui.app.QueueUpdate(func() {
+				shown = app.ui.buffers[app.ui.currentBuffer].Name
+			})
+
+			if shown != test.wantBuffer || app.target != test.wantTarget {
+				t.Fatalf("got buffer %s and target %q, want %s and %q",
+					shown, app.target, test.wantBuffer, test.wantTarget)
+			}
+		})
+	}
+}
+
+// TestEventLoopKeepsRunning sends Alt and 1, then a typed line and
+// Enter, to a running UI. It checks that both are handled, so the
+// event loop did not stop on either.
+func TestEventLoopKeepsRunning(t *testing.T) {
+	t.Parallel()
+
+	app := &App{ui: NewUI(), nick: testNick}
+	handled := handledLines(app)
+	runUI(t, app.ui)
+
+	// Window 1 is the channel, and window 0, the status window, is
+	// shown. The typed line adds a line to the status window, as
+	// the client is not connected.
+	app.ui.SwitchToBuffer(testChannel)
+	app.ui.SwitchBuffer(0)
+
+	app.ui.app.QueueEvent(tcell.NewEventKey(tcell.KeyRune, '1', tcell.ModAlt))
+
+	for _, r := range testText {
+		app.ui.app.QueueEvent(tcell.NewEventKey(tcell.KeyRune, r, tcell.ModNone))
+	}
+
+	app.ui.app.QueueEvent(tcell.NewEventKey(tcell.KeyEnter, 0, tcell.ModNone))
+
+	waitHandled(t, handled, "/window 1")
+	waitHandled(t, handled, testText)
+}
+
+// TestLinesKeepOrder holds the handling of a first line until a
+// second line has been passed in. It fails if the second line is
+// handled while the first is still held.
+func TestLinesKeepOrder(t *testing.T) {
+	t.Parallel()
+
+	const firstLine, secondLine = "one", "two"
+
+	ui := NewUI()
+	handled := make(chan string)
+	release := make(chan struct{})
+
+	ui.OnInput(func(text string) {
+		if text == firstLine {
+			<-release
+		}
+
+		handled <- text
+	})
+
+	ui.callOnInput(firstLine)
+	ui.callOnInput(secondLine)
+
+	select {
+	case got := <-handled:
+		t.Fatalf("handled %q while the first line was held", got)
+	case <-time.After(holdTime):
+	}
+
+	close(release)
+	waitHandled(t, handled, firstLine)
+	waitHandled(t, handled, secondLine)
+}
+
+// TestStartUp runs the client's start-up path on a simulation
+// screen. It fails unless the event loop starts and the status
+// window gets two lines: first the one that holds "Welcome to
+// neoirc-cli", then the /connect hint. The status bar must show
+// [disconnected].
+func TestStartUp(t *testing.T) {
+	t.Parallel()
+
+	ui := NewUI()
+	ui.app.SetScreen(tcell.NewSimulationScreen(""))
+
+	// One slot, so that run's goroutine can end even after the
+	// cleanup below has stopped waiting for it.
+	done := make(chan error, 1)
+
+	go func() { done <- run(ui) }()
+
+	t.Cleanup(func() {
+		ui.Stop()
+
+		select {
+		case err := <-done:
+			if err != nil {
+				t.Errorf("run: %v", err)
+			}
+		case <-time.After(eventLoopTimeout):
+			t.Error("run did not return after the UI was stopped")
+		}
+	})
+
+	// run adds the welcome lines on a goroutine, so the status
+	// window is read until it holds two lines. Each read waits for
+	// the event loop, so the reads run on a goroutine too, which
+	// this test stops waiting for after eventLoopTimeout. The
+	// channel has one slot, so that goroutine can still end.
+	shown := make(chan []string, 1)
+
+	go func() {
+		for {
+			var lines []string
+
+			ui.app.QueueUpdate(func() {
+				lines = slices.Clone(ui.getOrCreateBuffer("(status)").Lines)
+			})
+
+			if len(lines) == welcomeLines {
+				shown <- lines
+
+				return
+			}
+
+			time.Sleep(checkInterval)
+		}
+	}()
+
+	var lines []string
+
+	select {
+	case lines = <-shown:
+	case <-time.After(eventLoopTimeout):
+		t.Fatalf("the status window did not get the welcome lines within %v",
+			eventLoopTimeout)
+	}
+
+	if !strings.Contains(lines[0], "Welcome to neoirc-cli") {
+		t.Errorf("first status line is %q, want the welcome line", lines[0])
+	}
+
+	if !strings.Contains(lines[1], "/connect <server-url>") {
+		t.Errorf("second status line is %q, want the /connect hint", lines[1])
+	}
+
+	// run sets the status bar before it adds the welcome lines.
+	status := statusBarText(ui)
+	if !strings.Contains(status, "[disconnected]") {
+		t.Errorf("status bar is %q, want it to show [disconnected]", status)
+	}
+}
+
+// TestStatusBar checks that the status bar shows [connected], and
+// shows a nick, target or window name with square brackets as it
+// is.
+func TestStatusBar(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name   string
+		nick   string
+		target string
+		unread string
+		want   string
+	}{
+		{
+			name:   "plain names",
+			nick:   testNick,
+			target: testChannel,
+			unread: testOtherNick,
+			want:   " [connected] erin [1:#chan] #chan [Act: 2:bob(1)]",
+		},
+		{
+			name:   "nicks with brackets",
+			nick:   "erin[away]",
+			target: "bob[m]",
+			unread: "dave[afk]",
+			want:   " [connected] erin[away] [1:bob[m]] bob[m] [Act: 2:dave[afk](1)]",
+		},
+		{
+			name:   "nicks with brackets and symbols",
+			nick:   "bob[|[]",
+			target: "x[^[]",
+			unread: testOtherNick,
+			want:   " [connected] bob[|[] [1:x[^[]] x[^[] [Act: 2:bob(1)]",
+		},
+		{
+			// /query takes any text as the target.
+			name:   "query target with brackets",
+			nick:   testNick,
+			target: "[:::y|z]",
+			unread: testOtherNick,
+			want:   " [connected] erin [1:[:::y|z]] [:::y|z] [Act: 2:bob(1)]",
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			t.Parallel()
+
+			ui := NewUI()
+			runUI(t, ui)
+
+			// Window 1, the one shown, is the target's. Window 2
+			// gets one unread line.
+			ui.SwitchToBuffer(test.target)
+			ui.AddLine(test.unread, testText)
+			ui.SetStatus(test.nick, test.target, "connected")
+
+			got := statusBarText(ui)
+			if got != test.want {
+				t.Fatalf("status bar is %q, want %q", got, test.want)
+			}
+		})
+	}
+}
+
 // TestOwnEventFromOtherClient checks that a message, notice,
 // join or part that the user's session makes from another
 // client shows as one line in the buffer it belongs to.
@@ -301,6 +585,49 @@ func bufferState(ui *UI, name string) (int, int) {
 	return lines, unread
 }
 
+// statusBarText returns the text the status bar shows.
+// GetText(true) leaves out whatever tview reads as a tag, as
+// drawing does.
+func statusBarText(ui *UI) string {
+	var text string
+
+	ui.app.QueueUpdate(func() {
+		text = ui.statusBar.GetText(true)
+	})
+
+	return text
+}
+
+// handledLines makes app.ui pass each typed line to
+// app.handleInput, as Run does, and returns a channel that
+// receives each line once it has been handled.
+func handledLines(app *App) <-chan string {
+	handled := make(chan string)
+
+	app.ui.OnInput(func(text string) {
+		app.handleInput(text)
+
+		handled <- text
+	})
+
+	return handled
+}
+
+// waitHandled fails the test unless want is the next line handled,
+// within eventLoopTimeout.
+func waitHandled(t *testing.T, handled <-chan string, want string) {
+	t.Helper()
+
+	select {
+	case got := <-handled:
+		if got != want {
+			t.Fatalf("handled %q, want %q", got, want)
+		}
+	case <-time.After(eventLoopTimeout):
+		t.Fatalf("%q was not handled within %v", want, eventLoopTimeout)
+	}
+}
+
 // newServer starts a server that answers every request with
 // body until the test ends.
 func newServer(t *testing.T, body string) *httptest.Server {
@@ -322,16 +649,22 @@ func runUI(t *testing.T, ui *UI) {
 
 	ui.app.SetScreen(tcell.NewSimulationScreen(""))
 
-	done := make(chan error)
+	// One slot, so that Run's goroutine can end even after the
+	// cleanup below has stopped waiting for it.
+	done := make(chan error, 1)
 
 	go func() { done <- ui.Run() }()
 
 	t.Cleanup(func() {
 		ui.Stop()
 
-		err := <-done
-		if err != nil {
-			t.Errorf("run ui: %v", err)
+		select {
+		case err := <-done:
+			if err != nil {
+				t.Errorf("run ui: %v", err)
+			}
+		case <-time.After(eventLoopTimeout):
+			t.Error("the UI did not stop: its event loop stopped responding")
 		}
 	})
 }

internal/cli/ui.go

@@ -16,7 +16,10 @@ type Buffer struct {
 	Unread int
 }
 
-// UI manages the terminal interface.
+// UI manages the terminal interface. Most of its methods wait for
+// the tview event loop to run their update. Code that runs on that
+// loop, such as a key handler, must not call them: it would wait
+// for itself.
 type UI struct {
 	app       *tview.Application
 	messages  *tview.TextView
@@ -28,6 +31,10 @@ type UI struct {
 	currentBuffer int
 
 	onInput func(string)
+	// inputDone is closed once the line last passed to onInput
+	// has been handled. Only callOnInput, on the event loop, uses
+	// it.
+	inputDone chan struct{}
 }
 
 // NewUI creates the tview-based IRC-like UI.
@@ -176,9 +183,24 @@ func (ui *UI) SetStatus(
 	})
 }
 
-// BufferCount returns the number of buffers.
-func (ui *UI) BufferCount() int {
-	return len(ui.buffers)
+// BufferName returns the name of the buffer at index bufIndex,
+// and whether there is such a buffer.
+func (ui *UI) BufferName(bufIndex int) (string, bool) {
+	var (
+		name  string
+		found bool
+	)
+
+	ui.app.QueueUpdate(func() {
+		if bufIndex < 0 || bufIndex >= len(ui.buffers) {
+			return
+		}
+
+		name = ui.buffers[bufIndex].Name
+		found = true
+	})
+
+	return name, found
 }
 
 // BufferIndex returns the index of a named buffer.
@@ -204,8 +226,10 @@ func (ui *UI) initMessages() {
 }
 
 func (ui *UI) initStatusBar() {
-	ui.statusBar = tview.NewTextView().
-		SetDynamicColors(true)
+	// Colour tags stay off. With them on, tview reads text in
+	// square brackets, such as "[connected]" or part of a nick,
+	// as a tag and drops it.
+	ui.statusBar = tview.NewTextView()
 	ui.statusBar.SetBackgroundColor(tcell.ColorNavy)
 	ui.statusBar.SetTextColor(tcell.ColorWhite)
 }
@@ -226,10 +250,7 @@ func (ui *UI) initInput() {
 		}
 
 		ui.input.SetText("")
-
-		if ui.onInput != nil {
-			ui.onInput(text)
-		}
+		ui.callOnInput(text)
 	})
 }
 
@@ -240,10 +261,11 @@ func (ui *UI) initKeyCapture() {
 				return event
 			}
 
+			// Alt and a digit runs /window with that digit.
+			// SwitchBuffer alone would leave the target as it was.
 			r := event.Rune()
 			if r >= '0' && r <= '9' {
-				idx := int(r - '0')
-				ui.SwitchBuffer(idx)
+				ui.callOnInput("/window " + string(r))
 
 				return nil
 			}
@@ -253,6 +275,31 @@ func (ui *UI) initKeyCapture() {
 	)
 }
 
+// callOnInput passes text to the input callback on a new
+// goroutine. The key handlers call it on the event loop, and the
+// callback waits for that loop to update the screen, so they must
+// not wait for the callback. The goroutine first waits for the
+// line before it to be handled, which keeps lines in the order
+// they were typed.
+func (ui *UI) callOnInput(text string) {
+	if ui.onInput == nil {
+		return
+	}
+
+	previous := ui.inputDone
+	done := make(chan struct{})
+	ui.inputDone = done
+
+	go func() {
+		if previous != nil {
+			<-previous
+		}
+
+		ui.onInput(text)
+		close(done)
+	}()
+}
+
 func (ui *UI) refreshStatusBar() {
 	// Placeholder; full refresh needs nick/target context.
 }

internal/config/config.go

@@ -3,8 +3,12 @@ package config
 
 import (
 	"errors"
+	"fmt"
 	"log/slog"
+	"math"
 	"os"
+	"strconv"
+	"time"
 
 	"github.com/spf13/viper"
 	"go.uber.org/fx"
@@ -28,6 +32,8 @@ Type /help for available commands.`
 const DefaultDBURL = "file:///var/lib/neoirc/state.db" +
 	"?_pragma=journal_mode(WAL)&_pragma=busy_timeout(5000)"
 
+var errOutOfRange = errors.New("setting out of range")
+
 // Params defines the dependencies for creating a Config.
 type Params struct {
 	fx.In
@@ -63,6 +69,8 @@ type Config struct {
 }
 
 // New creates a new Config by reading from files and environment variables.
+// It returns an error when a number, true/false or duration setting does
+// not parse or is out of range.
 func New(
 	_ fx.Lifecycle, params Params,
 ) (*Config, error) {
@@ -107,29 +115,27 @@ func New(
 
 	cfg := &Config{
 		DBURL:              viper.GetString("DBURL"),
-		Debug:              viper.GetBool("DEBUG"),
-		Port:               viper.GetInt("PORT"),
 		SentryDSN:          viper.GetString("SENTRY_DSN"),
-		MaintenanceMode:    viper.GetBool("MAINTENANCE_MODE"),
 		MetricsUsername:    viper.GetString("METRICS_USERNAME"),
 		MetricsPassword:    viper.GetString("METRICS_PASSWORD"),
 		MessageMaxAge:      viper.GetString("MESSAGE_MAX_AGE"),
-		MaxMessageSize:     viper.GetInt("MAX_MESSAGE_SIZE"),
 		QueueMaxAge:        viper.GetString("QUEUE_MAX_AGE"),
 		MOTD:               viper.GetString("MOTD"),
 		ServerName:         viper.GetString("SERVER_NAME"),
 		FederationKey:      viper.GetString("FEDERATION_KEY"),
 		SessionIdleTimeout: viper.GetString("SESSION_IDLE_TIMEOUT"),
-		HashcashBits:       viper.GetInt("NEOIRC_HASHCASH_BITS"),
 		OperName:           viper.GetString("NEOIRC_OPER_NAME"),
 		OperPassword:       viper.GetString("NEOIRC_OPER_PASSWORD"),
-		LoginRateLimit:     viper.GetFloat64("LOGIN_RATE_LIMIT"),
-		LoginRateBurst:     viper.GetInt("LOGIN_RATE_BURST"),
 		IRCListenAddr:      viper.GetString("IRC_LISTEN_ADDR"),
 		log:                log,
 		params:             &params,
 	}
 
+	err = parseSettings(cfg)
+	if err != nil {
+		return nil, err
+	}
+
 	// Viper counts an empty environment variable as unset, but an
 	// empty IRC_LISTEN_ADDR must turn the IRC listener off.
 	ircListenAddr, set := os.LookupEnv("IRC_LISTEN_ADDR")
@@ -144,3 +150,93 @@ func New(
 
 	return cfg, nil
 }
+
+// parseSettings reads the number and true/false settings into cfg and
+// checks the duration settings. Each number and duration must be above
+// zero. PORT and NEOIRC_HASHCASH_BITS may also be zero: port 0 lets the
+// system pick a port, and 0 bits turns proof of work off. The error
+// names each setting that does not parse or is out of range.
+func parseSettings(cfg *Config) error {
+	return errors.Join(
+		parseInt("PORT", 0, &cfg.Port),
+		parseInt("MAX_MESSAGE_SIZE", 1, &cfg.MaxMessageSize),
+		parseInt("NEOIRC_HASHCASH_BITS", 0, &cfg.HashcashBits),
+		parseInt("LOGIN_RATE_BURST", 1, &cfg.LoginRateBurst),
+		parseFloat("LOGIN_RATE_LIMIT", &cfg.LoginRateLimit),
+		parseBool("DEBUG", &cfg.Debug),
+		parseBool("MAINTENANCE_MODE", &cfg.MaintenanceMode),
+		checkDuration("MESSAGE_MAX_AGE", cfg.MessageMaxAge),
+		checkDuration("QUEUE_MAX_AGE", cfg.QueueMaxAge),
+		checkDuration("SESSION_IDLE_TIMEOUT", cfg.SessionIdleTimeout),
+	)
+}
+
+// parseInt sets *value to the setting key read as a whole number. It
+// returns an error when the value does not parse or is below minimum.
+func parseInt(key string, minimum int, value *int) error {
+	raw := viper.GetString(key)
+
+	parsed, err := strconv.Atoi(raw)
+	if err != nil {
+		return fmt.Errorf("cannot parse %s: %w", key, err)
+	}
+
+	if parsed < minimum {
+		return fmt.Errorf("%w: %s is %s, but must be at least %d",
+			errOutOfRange, key, raw, minimum)
+	}
+
+	*value = parsed
+
+	return nil
+}
+
+// parseFloat sets *value to the setting key read as a floating-point
+// number. It returns an error when the value does not parse or is not a
+// finite number above zero.
+func parseFloat(key string, value *float64) error {
+	raw := viper.GetString(key)
+
+	parsed, err := strconv.ParseFloat(raw, 64)
+	if err != nil {
+		return fmt.Errorf("cannot parse %s: %w", key, err)
+	}
+
+	if math.IsNaN(parsed) || math.IsInf(parsed, 0) || parsed <= 0 {
+		return fmt.Errorf(
+			"%w: %s is %s, but must be a finite number above zero",
+			errOutOfRange, key, raw)
+	}
+
+	*value = parsed
+
+	return nil
+}
+
+// parseBool sets *value to the setting key read as true or false.
+func parseBool(key string, value *bool) error {
+	parsed, err := strconv.ParseBool(viper.GetString(key))
+	if err != nil {
+		return fmt.Errorf("cannot parse %s: %w", key, err)
+	}
+
+	*value = parsed
+
+	return nil
+}
+
+// checkDuration returns an error naming the setting key when value is
+// not a Go duration above zero.
+func checkDuration(key, value string) error {
+	duration, err := time.ParseDuration(value)
+	if err != nil {
+		return fmt.Errorf("cannot parse %s: %w", key, err)
+	}
+
+	if duration <= 0 {
+		return fmt.Errorf("%w: %s is %s, but must be above zero",
+			errOutOfRange, key, value)
+	}
+
+	return nil
+}

internal/config/config_test.go

@@ -2,6 +2,7 @@ package config_test
 
 import (
 	"os"
+	"strings"
 	"testing"
 	"time"
 
@@ -10,7 +11,8 @@ import (
 	"sneak.berlin/go/neoirc/internal/logger"
 )
 
-func newConfig(t *testing.T) *config.Config {
+// loadConfig runs config.New and returns its result.
+func loadConfig(t *testing.T) (*config.Config, error) {
 	t.Helper()
 
 	globs := &globals.Globals{
@@ -24,9 +26,15 @@ func newConfig(t *testing.T) *config.Config {
 		t.Fatal(err)
 	}
 
-	cfg, err := config.New(
+	return config.New(
 		nil, config.Params{Globals: globs, Logger: log},
 	)
+}
+
+func newConfig(t *testing.T) *config.Config {
+	t.Helper()
+
+	cfg, err := loadConfig(t)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -34,6 +42,145 @@ func newConfig(t *testing.T) *config.Config {
 	return cfg
 }
 
+func TestUnsetSettingsKeepDefaults(t *testing.T) {
+	// Viper counts an empty environment variable as unset.
+	t.Setenv("PORT", "")
+	t.Setenv("MAX_MESSAGE_SIZE", "")
+	t.Setenv("NEOIRC_HASHCASH_BITS", "")
+	t.Setenv("LOGIN_RATE_BURST", "")
+	t.Setenv("LOGIN_RATE_LIMIT", "")
+	t.Setenv("DEBUG", "")
+	t.Setenv("MAINTENANCE_MODE", "")
+	t.Setenv("MESSAGE_MAX_AGE", "")
+	t.Setenv("QUEUE_MAX_AGE", "")
+	t.Setenv("SESSION_IDLE_TIMEOUT", "")
+
+	// Each duration setting defaults to 30 days.
+	const thirtyDays = "720h"
+
+	want := settings{
+		Port:               8080,
+		MaxMessageSize:     4096,
+		HashcashBits:       20,
+		LoginRateBurst:     5,
+		LoginRateLimit:     1,
+		Debug:              false,
+		MaintenanceMode:    false,
+		MessageMaxAge:      thirtyDays,
+		QueueMaxAge:        thirtyDays,
+		SessionIdleTimeout: thirtyDays,
+	}
+
+	got := settingsOf(newConfig(t))
+	if got != want {
+		t.Errorf("settings = %+v, want %+v", got, want)
+	}
+}
+
+func TestValidSettingsAreUsed(t *testing.T) {
+	// Each whole number is the lowest value its setting allows, and 1ns
+	// is the shortest duration allowed.
+	t.Setenv("PORT", "0")
+	t.Setenv("MAX_MESSAGE_SIZE", "1")
+	t.Setenv("NEOIRC_HASHCASH_BITS", "0")
+	t.Setenv("LOGIN_RATE_BURST", "1")
+	t.Setenv("LOGIN_RATE_LIMIT", "0.5")
+	t.Setenv("DEBUG", "true")
+	t.Setenv("MAINTENANCE_MODE", "true")
+	t.Setenv("MESSAGE_MAX_AGE", "1ns")
+	t.Setenv("QUEUE_MAX_AGE", "1h30m")
+	t.Setenv("SESSION_IDLE_TIMEOUT", "45m")
+
+	want := settings{
+		Port:               0,
+		MaxMessageSize:     1,
+		HashcashBits:       0,
+		LoginRateBurst:     1,
+		LoginRateLimit:     0.5,
+		Debug:              true,
+		MaintenanceMode:    true,
+		MessageMaxAge:      "1ns",
+		QueueMaxAge:        "1h30m",
+		SessionIdleTimeout: "45m",
+	}
+
+	got := settingsOf(newConfig(t))
+	if got != want {
+		t.Errorf("settings = %+v, want %+v", got, want)
+	}
+}
+
+// settings holds the Config fields whose settings config.New parses.
+type settings struct {
+	Port               int
+	MaxMessageSize     int
+	HashcashBits       int
+	LoginRateBurst     int
+	LoginRateLimit     float64
+	Debug              bool
+	MaintenanceMode    bool
+	MessageMaxAge      string
+	QueueMaxAge        string
+	SessionIdleTimeout string
+}
+
+func settingsOf(cfg *config.Config) settings {
+	return settings{
+		Port:               cfg.Port,
+		MaxMessageSize:     cfg.MaxMessageSize,
+		HashcashBits:       cfg.HashcashBits,
+		LoginRateBurst:     cfg.LoginRateBurst,
+		LoginRateLimit:     cfg.LoginRateLimit,
+		Debug:              cfg.Debug,
+		MaintenanceMode:    cfg.MaintenanceMode,
+		MessageMaxAge:      cfg.MessageMaxAge,
+		QueueMaxAge:        cfg.QueueMaxAge,
+		SessionIdleTimeout: cfg.SessionIdleTimeout,
+	}
+}
+
+func TestBadSettingStopsStartup(t *testing.T) {
+	// For each setting, the first value does not parse and the others
+	// parse but are out of range.
+	tests := []struct {
+		key    string
+		values []string
+	}{
+		{key: "PORT", values: []string{"80a", "-1"}},
+		{key: "MAX_MESSAGE_SIZE", values: []string{"4k", "0", "-4096"}},
+		{key: "NEOIRC_HASHCASH_BITS", values: []string{"twenty", "-1"}},
+		{key: "LOGIN_RATE_BURST", values: []string{"five", "0", "-5"}},
+		{key: "LOGIN_RATE_LIMIT", values: []string{
+			"fast", "0", "-1", "NaN", "Inf", "-Inf",
+		}},
+		{key: "DEBUG", values: []string{"yes"}},
+		{key: "MAINTENANCE_MODE", values: []string{"on"}},
+		{key: "MESSAGE_MAX_AGE", values: []string{"30d", "0", "-1h"}},
+		{key: "QUEUE_MAX_AGE", values: []string{"720", "0s", "-24h"}},
+		{key: "SESSION_IDLE_TIMEOUT", values: []string{"a month", "0", "-1m"}},
+	}
+
+	for _, test := range tests {
+		for _, value := range test.values {
+			t.Run(test.key+"="+value, func(t *testing.T) {
+				t.Setenv(test.key, value)
+
+				_, err := loadConfig(t)
+				if err == nil {
+					t.Fatalf("%s=%q: got no error", test.key, value)
+				}
+
+				msg := err.Error()
+				if !strings.Contains(msg, test.key) ||
+					!strings.Contains(msg, value) {
+					t.Errorf("error %q does not name %s and %q",
+						msg, test.key, value)
+				}
+			})
+		}
+	}
+}
+
 func TestIRCListenAddrUnsetKeepsDefault(t *testing.T) {
 	// t.Setenv puts back whatever value was there after the test.
 	t.Setenv("IRC_LISTEN_ADDR", "")

internal/db/db_test.go

@@ -12,6 +12,7 @@ import (
 	"go.uber.org/fx/fxtest"
 	"sneak.berlin/go/neoirc/internal/config"
 	"sneak.berlin/go/neoirc/internal/db"
+	"sneak.berlin/go/neoirc/internal/dbtest"
 	"sneak.berlin/go/neoirc/internal/globals"
 	"sneak.berlin/go/neoirc/internal/logger"
 )
@@ -155,6 +156,52 @@ func TestForeignKeysOnAfterCancelledQuery(t *testing.T) {
 	}
 }
 
+// TestNewURLKeepsDataAfterCancelledQuery cancels a query on a test
+// database while it runs, which makes the pool close its only
+// connection and open a new one. A TEMP table lasts only as long as
+// its connection, so its absence shows the connection was replaced.
+// The database must still have its tables and rows.
+func TestNewURLKeepsDataAfterCancelledQuery(t *testing.T) {
+	t.Parallel()
+
+	database, err := startDatabase(t, dbtest.NewURL(t))
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_, err = database.GetOrCreateChannel(t.Context(), "#test")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_, err = database.GetDB().ExecContext(
+		t.Context(), "CREATE TEMP TABLE first_connection (x)",
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	ctx, cancel := context.WithTimeout(t.Context(), endlessQueryTimeout)
+	defer cancel()
+
+	_, err = database.GetDB().ExecContext(ctx, endlessQuery)
+	if !errors.Is(err, context.DeadlineExceeded) {
+		t.Fatalf("endless query: err = %v", err)
+	}
+
+	tempTables := queryInt(
+		t, database, "SELECT COUNT(*) FROM sqlite_temp_schema",
+	)
+	if tempTables != 0 {
+		t.Fatal("the pool kept its first connection")
+	}
+
+	channels := queryInt(t, database, "SELECT COUNT(*) FROM channels")
+	if channels != 1 {
+		t.Errorf("channels = %d, want 1", channels)
+	}
+}
+
 // TestDBURLSettingForeignKeysFailsStartup checks that the database
 // refuses to start when DBURL sets foreign_keys itself, however it
 // is spelled.

internal/db/export_test.go

@@ -5,21 +5,16 @@ import (
 	"database/sql"
 	"fmt"
 	"log/slog"
-	"sync/atomic"
+	"testing"
+
+	"sneak.berlin/go/neoirc/internal/dbtest"
 )
 
-//nolint:gochecknoglobals // test counter
-var testDBCounter atomic.Int64
-
 // NewTestDatabase creates an in-memory database for testing.
-func NewTestDatabase() (*Database, error) {
-	counter := testDBCounter.Add(1)
+func NewTestDatabase(tb testing.TB) (*Database, error) {
+	tb.Helper()
 
-	dsn := fmt.Sprintf(
-		"file:testdb%d?mode=memory"+
-			"&cache=shared&_pragma=foreign_keys(1)",
-		counter,
-	)
+	dsn := dbtest.NewURL(tb) + "&_pragma=foreign_keys(1)"
 
 	conn, err := sql.Open("sqlite", dsn)
 	if err != nil {

internal/db/queries_test.go

@@ -13,7 +13,7 @@ import (
 func setupTestDB(t *testing.T) *db.Database {
 	t.Helper()
 
-	database, err := db.NewTestDatabase()
+	database, err := db.NewTestDatabase(t)
 	if err != nil {
 		t.Fatal(err)
 	}

internal/dbtest/dbtest.go

@@ -0,0 +1,39 @@
+// Package dbtest gives each test a database of its own. Only tests
+// may import it.
+package dbtest
+
+import (
+	"crypto/rand"
+	"database/sql"
+	"testing"
+
+	_ "modernc.org/sqlite" // registers the sqlite driver
+)
+
+// NewURL returns the URL of a new, empty in-memory database for one
+// test. SQLite deletes an in-memory database when its last connection
+// closes. A pool closes a connection when a query on it is cancelled
+// while it runs. So this function holds a connection of its own open
+// until the test ends.
+func NewURL(tb testing.TB) string {
+	tb.Helper()
+
+	// A random name, so that no other test can share the database.
+	dbURL := "file:" + rand.Text() + "?mode=memory&cache=shared"
+
+	pool, err := sql.Open("sqlite", dbURL)
+	if err != nil {
+		tb.Fatalf("open test database: %v", err)
+	}
+
+	tb.Cleanup(func() { _ = pool.Close() })
+
+	conn, err := pool.Conn(tb.Context())
+	if err != nil {
+		tb.Fatalf("connect to test database: %v", err)
+	}
+
+	tb.Cleanup(func() { _ = conn.Close() })
+
+	return dbURL
+}

internal/handlers/api_test.go

@@ -3,7 +3,6 @@ package handlers_test
 import (
 	"bytes"
 	"context"
-	"crypto/rand"
 	"database/sql"
 	"encoding/json"
 	"errors"
@@ -28,6 +27,7 @@ import (
 	api "sneak.berlin/go/neoirc/internal/cli/api"
 	"sneak.berlin/go/neoirc/internal/config"
 	"sneak.berlin/go/neoirc/internal/db"
+	"sneak.berlin/go/neoirc/internal/dbtest"
 	"sneak.berlin/go/neoirc/internal/globals"
 	"sneak.berlin/go/neoirc/internal/handlers"
 	"sneak.berlin/go/neoirc/internal/hashcash"
@@ -164,13 +164,7 @@ func newTestServerWith(
 	viperMu.Lock()
 	defer viperMu.Unlock()
 
-	// A random name, so that no other test can share it, not
-	// even one that has finished but still holds its database
-	// open.
-	dbURL := fmt.Sprintf(
-		"file:%s?mode=memory&cache=shared",
-		rand.Text(),
-	)
+	dbURL := dbtest.NewURL(t)
 	copyTemplateDB(t, dbURL)
 
 	var (

internal/ircserver/server_test.go

@@ -3,7 +3,6 @@ package ircserver_test
 import (
 	"bufio"
 	"context"
-	"crypto/rand"
 	"database/sql"
 	"errors"
 	"fmt"
@@ -20,6 +19,7 @@ import (
 	"sneak.berlin/go/neoirc/internal/broker"
 	"sneak.berlin/go/neoirc/internal/config"
 	"sneak.berlin/go/neoirc/internal/db"
+	"sneak.berlin/go/neoirc/internal/dbtest"
 	"sneak.berlin/go/neoirc/internal/globals"
 	"sneak.berlin/go/neoirc/internal/ircserver"
 	"sneak.berlin/go/neoirc/internal/logger"
@@ -107,14 +107,7 @@ func newTestEnvWithResolver(
 ) *testEnv {
 	t.Helper()
 
-	// A random name, so that no other test environment, not
-	// even an earlier run of the same test, can share it.
-	dsn := fmt.Sprintf(
-		"file:%s?mode=memory&cache=shared",
-		rand.Text(),
-	)
-
-	conn, err := sql.Open("sqlite", dsn)
+	conn, err := sql.Open("sqlite", dbtest.NewURL(t))
 	if err != nil {
 		t.Fatalf("open db: %v", err)
 	}
@@ -144,20 +137,6 @@ func newTestEnvWithResolver(
 
 	brk := broker.New()
 
-	var listenConfig net.ListenConfig
-
-	listener, err := listenConfig.Listen(t.Context(), "tcp", "127.0.0.1:0")
-	if err != nil {
-		t.Fatalf("listen: %v", err)
-	}
-
-	addr := listener.Addr().String()
-
-	err = listener.Close()
-	if err != nil {
-		t.Fatalf("close listener: %v", err)
-	}
-
 	log := slog.New(slog.NewTextHandler(
 		os.Stderr,
 		&slog.HandlerOptions{Level: slog.LevelError}, //nolint:exhaustruct
@@ -167,7 +146,9 @@ func newTestEnvWithResolver(
 		log, cfg, database, brk, interval, deadline, resolve,
 	)
 
-	err = srv.Start(addr)
+	// Port 0 makes the system pick a free port. dial reads it
+	// back from the server's listener.
+	err = srv.Start("127.0.0.1:0")
 	if err != nil {
 		t.Fatalf("start irc server: %v", err)
 	}

internal/server/export_test.go

@@ -15,6 +15,12 @@ func NewTestSPAServer() *Server {
 	return srv
 }
 
+// Listener returns the listener the start hook bound for the
+// HTTP server.
+func (srv *Server) Listener() net.Listener {
+	return srv.listener
+}
+
 // ServeUntilShutdown runs serveUntilShutdown, which serves the
 // HTTP server on listener, and returns when it does.
 func (srv *Server) ServeUntilShutdown(listener net.Listener) {

internal/server/server.go

@@ -50,6 +50,7 @@ type Server struct {
 	sentryEnabled bool
 	log           *slog.Logger
 	httpServer    *http.Server
+	listener      net.Listener
 	router        *chi.Mux
 	params        Params
 	mw            *middleware.Middleware
@@ -179,6 +180,8 @@ func (srv *Server) startHTTP(ctx context.Context) error {
 		return fmt.Errorf("http listen: %w", err)
 	}
 
+	srv.listener = listener
+
 	srv.httpServer = &http.Server{ //nolint:exhaustruct // optional fields
 		Addr:           listenAddr,
 		ReadTimeout:    httpReadTimeout,

internal/server/server_test.go

@@ -5,7 +5,6 @@
 package server_test
 
 import (
-	"crypto/rand"
 	"fmt"
 	"net"
 	"net/http"
@@ -19,6 +18,7 @@ import (
 	"sneak.berlin/go/neoirc/internal/broker"
 	"sneak.berlin/go/neoirc/internal/config"
 	"sneak.berlin/go/neoirc/internal/db"
+	"sneak.berlin/go/neoirc/internal/dbtest"
 	"sneak.berlin/go/neoirc/internal/globals"
 	"sneak.berlin/go/neoirc/internal/handlers"
 	"sneak.berlin/go/neoirc/internal/healthcheck"
@@ -45,10 +45,9 @@ const (
 // for a long poll the HTTP server is serving to finish, and
 // that the poll gets its response.
 func TestStopWaitsForRequestInProgress(t *testing.T) {
-	port := freePort(t)
-	addr := net.JoinHostPort("127.0.0.1", strconv.Itoa(port))
+	var srv *server.Server
 
-	app, brk, database := startApp(t, port)
+	app, brk, database := startApp(t, fx.Populate(&srv))
 
 	sessionID, _, token, err := database.CreateSession(
 		t.Context(), "poller", "poller", "", "",
@@ -57,9 +56,12 @@ func TestStopWaitsForRequestInProgress(t *testing.T) {
 		t.Fatalf("create session: %v", err)
 	}
 
-	waitUntil(t, "the HTTP server to listen", func() bool {
-		return canConnect(t, addr)
-	})
+	tcpAddr, ok := srv.Listener().Addr().(*net.TCPAddr)
+	if !ok {
+		t.Fatalf("listener address %v is not TCP", srv.Listener().Addr())
+	}
+
+	addr := net.JoinHostPort("127.0.0.1", strconv.Itoa(tcpAddr.Port))
 
 	statuses := make(chan int, 1)
 
@@ -145,7 +147,7 @@ func TestStartFailsWhenHTTPPortIsTaken(t *testing.T) {
 func TestServeFailureStopsApp(t *testing.T) {
 	var srv *server.Server
 
-	app, _, _ := startApp(t, freePort(t), fx.Populate(&srv))
+	app, _, _ := startApp(t, fx.Populate(&srv))
 
 	shutdowns := app.Wait()
 
@@ -168,7 +170,7 @@ func TestServeFailureStopsApp(t *testing.T) {
 func TestServeAfterStopDoesNotStopApp(t *testing.T) {
 	var srv *server.Server
 
-	app, _, _ := startApp(t, freePort(t), fx.Populate(&srv))
+	app, _, _ := startApp(t, fx.Populate(&srv))
 
 	shutdowns := app.Wait()
 
@@ -186,16 +188,15 @@ func TestServeAfterStopDoesNotStopApp(t *testing.T) {
 	}
 }
 
-// startApp starts the app newApp builds, with the HTTP server
-// listening on port.
+// startApp starts the app newApp builds, with the HTTP port
+// set to 0, so the system gives the server a free port.
 func startApp(
 	t *testing.T,
-	port int,
 	options ...fx.Option,
 ) (*fxtest.App, *broker.Broker, *db.Database) {
 	t.Helper()
 
-	app, brk, database := newApp(t, port, options...)
+	app, brk, database := newApp(t, 0, options...)
 
 	app.RequireStart()
 
@@ -241,10 +242,7 @@ func newApp(
 			stats.New,
 		),
 		fx.Decorate(func(cfg *config.Config) *config.Config {
-			// A random name, so that no other test can share it.
-			cfg.DBURL = fmt.Sprintf(
-				"file:%s?mode=memory&cache=shared", rand.Text(),
-			)
+			cfg.DBURL = dbtest.NewURL(t)
 			cfg.Port = port
 
 			return cfg
@@ -257,21 +255,6 @@ func newApp(
 	return app, brk, database
 }
 
-// freePort returns a TCP port that nothing was listening on a
-// moment ago.
-func freePort(t *testing.T) int {
-	t.Helper()
-
-	listener := closedListener(t)
-
-	tcpAddr, ok := listener.Addr().(*net.TCPAddr)
-	if !ok {
-		t.Fatalf("listener address %v is not TCP", listener.Addr())
-	}
-
-	return tcpAddr.Port
-}
-
 // closedListener returns a TCP listener that has already been
 // closed, so that accepting a connection on it fails.
 func closedListener(t *testing.T) net.Listener {
@@ -294,22 +277,6 @@ func closedListener(t *testing.T) net.Listener {
 	return listener
 }
 
-// canConnect reports whether addr accepts a TCP connection.
-func canConnect(t *testing.T, addr string) bool {
-	t.Helper()
-
-	var dialer net.Dialer
-
-	conn, err := dialer.DialContext(t.Context(), "tcp", addr)
-	if err != nil {
-		return false
-	}
-
-	_ = conn.Close()
-
-	return true
-}
-
 // waitUntil calls done every checkStep until it returns true,
 // and fails the test if it does not within testTimeout.
 func waitUntil(t *testing.T, what string, done func() bool) {

internal/service/service_test.go

@@ -6,7 +6,6 @@ package service_test
 
 import (
 	"context"
-	"crypto/rand"
 	"encoding/json"
 	"errors"
 	"fmt"
@@ -23,6 +22,7 @@ import (
 	"sneak.berlin/go/neoirc/internal/broker"
 	"sneak.berlin/go/neoirc/internal/config"
 	"sneak.berlin/go/neoirc/internal/db"
+	"sneak.berlin/go/neoirc/internal/dbtest"
 	"sneak.berlin/go/neoirc/internal/globals"
 	"sneak.berlin/go/neoirc/internal/hashcash"
 	"sneak.berlin/go/neoirc/internal/logger"
@@ -46,13 +46,7 @@ type testEnv struct {
 func newTestEnv(t *testing.T) *testEnv {
 	t.Helper()
 
-	// A random name, so that no other test can share it, not
-	// even one that has finished but still holds its database
-	// open.
-	dbURL := fmt.Sprintf(
-		"file:%s?mode=memory&cache=shared",
-		rand.Text(),
-	)
+	dbURL := dbtest.NewURL(t)
 
 	var (
 		database *db.Database

schema/README.md

@@ -1,98 +1,166 @@
-# Message Schemas
+# Message schemas
 
-JSON Schema definitions (draft 2020-12) for the neoirc protocol. Messages use
-**IRC command names and numeric reply codes** (RFC 1459/2812) encoded as JSON
-over HTTP.
+This directory holds JSON Schema files (draft 2020-12) for the messages that the
+neoirc HTTP API carries. `message.json` describes the fields that every message
+can have. `commands/` has files for some commands. `numerics/` has files for
+some of the numeric replies. A numeric reply is a server reply named by a
+three-digit number, such as `001`. `README.md` at the repository root documents
+the protocol.
 
-## Envelope
+The server can also run an IRC listener for ordinary IRC clients. The IRC
+listener sends plain IRC lines, which these files do not describe.
 
-Every message is a JSON object with a `command` field. The format maps directly
-to IRC wire format:
+## Message fields
+
+Every message is one JSON object, which `message.json` calls the envelope. These
+are the fields it can have:
+
+- `command`: the IRC command name, such as `PRIVMSG`, or the name of a numeric
+  reply, such as `RPL_WELCOME`. Always present.
+- `code`: the number of a numeric reply, such as `1` for `RPL_WELCOME`. Absent
+  on other messages.
+- `id`: the message's UUID, a unique ID that the server assigns.
+- `from`: the sender's nick, or the server name on a server message.
+- `to`: the target, such as a channel name starting with `#` or a nick.
+- `params`: an array of strings with the message's other parameters, in order.
+  `KICK` events and many numeric replies have it. The HTTP API ignores `params`
+  sent by a client.
+- `body`: an array of strings. It is never a bare string. In a `PRIVMSG` or
+  `NOTICE`, each string is one line of text.
+- `ts`: the time the server stored the message. It is an RFC 3339 time in UTC,
+  such as `2026-10-27T12:00:00.123Z`.
+- `meta`: an object of extra data, such as a hashcash stamp in `meta.hashcash`.
+  A hashcash stamp is a short string that takes a computer some work to make. A
+  `PRIVMSG` to a channel with mode `+H` needs one. The HTTP API relays the
+  `meta` of a `PRIVMSG` or `NOTICE` unchanged. It drops the `meta` of every
+  other command.
+
+Here is one `PRIVMSG` as the IRC listener sends it and as the HTTP API sends it.
+The JSON leaves out `id`, `ts` and `meta`:
 
 ```
-IRC:  :nick PRIVMSG #channel :hello world
-JSON: {"command": "PRIVMSG", "from": "nick", "to": "#channel", "body": ["hello world"]}
-
-IRC:  :server 353 nick = #channel :user1 @op1 +voice1
-JSON: {"command": "353", "to": "nick", "params": ["=", "#channel"], "body": ["user1 @op1 +voice1"]}
-
-Multiline:  {"command": "PRIVMSG", "to": "#ch", "body": ["line 1", "line 2"]}
-Structured: {"command": "PUBKEY", "body": {"alg": "ed25519", "key": "base64..."}}
+IRC:  :alice!alice@* PRIVMSG #general :hello world
+JSON: {"command": "PRIVMSG", "from": "alice", "to": "#general", "body": ["hello world"]}
 ```
 
-Common fields (see `message.json` for full schema):
+In the JSON, a numeric reply has its name in `command` and its number in `code`.
+This `353` reply lists the members of `#general`. The JSON again leaves out
+`id`, `ts` and `meta`:
 
-| Field     | Type            | Description                                          |
-| --------- | --------------- | ---------------------------------------------------- |
-| `id`      | string (uuid)   | Server-assigned message UUID                         |
-| `command` | string          | IRC command or 3-digit numeric code                  |
-| `from`    | string          | Source nick or server name (IRC prefix)              |
-| `to`      | string          | Target: #channel or nick                             |
-| `params`  | string[]        | Middle parameters (mainly for numerics)              |
-| `body`    | array \| object | Structured body — never a raw string (see below)     |
-| `ts`      | string          | ISO 8601 timestamp (server-assigned, not in raw IRC) |
-| `meta`    | object          | Extensible metadata (signatures, hashes, etc.)       |
+```
+{"command": "RPL_NAMREPLY", "code": 353, "from": "neoirc", "to": "alice",
+ "params": ["=", "#general"], "body": ["@op1!op1@host1 alice!alice@host2"]}
+```
 
-**Structured bodies:** `body` is always an array of strings (for text) or an
-object (for structured data like PUBKEY). Never a raw string. This enables:
+A `PRIVMSG` whose `body` has two strings is a two-line message:
 
-- Multiline messages without escape sequences
-- Deterministic canonicalization via RFC 8785 JCS for signing
-- Structured data where needed
+```
+{"command": "PRIVMSG", "to": "#general", "body": ["line one", "line two"]}
+```
 
-## Commands
+## Files
 
-IRC commands used for client↔server and server↔server communication.
+Commands, in `commands/`:
 
-| Command   | File                    | RFC         | Description                |
-| --------- | ----------------------- | ----------- | -------------------------- |
-| `PRIVMSG` | `commands/PRIVMSG.json` | 1459 §4.4.1 | Message to channel or user |
-| `NOTICE`  | `commands/NOTICE.json`  | 1459 §4.4.2 | Notice (no auto-reply)     |
-| `JOIN`    | `commands/JOIN.json`    | 1459 §4.2.1 | Join a channel             |
-| `PART`    | `commands/PART.json`    | 1459 §4.2.2 | Leave a channel            |
-| `QUIT`    | `commands/QUIT.json`    | 1459 §4.1.6 | User disconnected          |
-| `NICK`    | `commands/NICK.json`    | 1459 §4.1.2 | Change nickname            |
-| `TOPIC`   | `commands/TOPIC.json`   | 1459 §4.2.4 | Get/set channel topic      |
-| `MODE`    | `commands/MODE.json`    | 1459 §4.2.3 | Set channel/user modes     |
-| `KICK`    | `commands/KICK.json`    | 1459 §4.2.8 | Kick user from channel     |
-| `PING`    | `commands/PING.json`    | 1459 §4.6.2 | Keepalive                  |
-| `PONG`    | `commands/PONG.json`    | 1459 §4.6.3 | Keepalive response         |
-| `PUBKEY`  | `commands/PUBKEY.json`  | (extension) | Announce/relay signing key |
+- `PRIVMSG.json`: a message to a channel or a user.
+- `NOTICE.json`: a notice, which is a message that a client must not answer
+  automatically.
+- `JOIN.json`: a user joined a channel.
+- `PART.json`: a user left a channel.
+- `QUIT.json`: a user left the server.
+- `NICK.json`: a user changed nick.
+- `TOPIC.json`: a channel topic was set.
+- `MODE.json`: a channel mode was changed.
+- `KICK.json`: a channel operator removed a user from a channel.
+- `PING.json`: a check that the server still answers.
+- `PONG.json`: the answer to a `PING`.
+- `PUBKEY.json`: an announcement of a user's public signing key. The server has
+  no such command. It answers a `PUBKEY` with `ERR_UNKNOWNCOMMAND` (`421`).
 
-## Numeric Replies
+Numeric replies, in `numerics/`:
 
-Three-digit codes for server responses, per IRC convention.
+- `001.json`: `RPL_WELCOME`, which welcomes a new user.
+- `002.json`: `RPL_YOURHOST`, the server's name and version.
+- `003.json`: `RPL_CREATED`, which says when the server was created.
+- `004.json`: `RPL_MYINFO`, the server's version and its lists of modes.
+- `322.json`: `RPL_LIST`, one channel in the answer to `LIST`.
+- `323.json`: `RPL_LISTEND`, the end of the answer to `LIST`.
+- `332.json`: `RPL_TOPIC`, a channel's topic.
+- `353.json`: `RPL_NAMREPLY`, a channel's members.
+- `366.json`: `RPL_ENDOFNAMES`, the end of the member list.
+- `372.json`: `RPL_MOTD`, one line of the message of the day.
+- `375.json`: `RPL_MOTDSTART`, the start of the message of the day.
+- `376.json`: `RPL_ENDOFMOTD`, the end of the message of the day.
+- `401.json`: `ERR_NOSUCHNICK`, the nick does not exist.
+- `403.json`: `ERR_NOSUCHCHANNEL`, the channel does not exist.
+- `433.json`: `ERR_NICKNAMEINUSE`, the nick is taken.
+- `442.json`: `ERR_NOTONCHANNEL`, the user is not on that channel.
+- `482.json`: `ERR_CHANOPRIVSNEEDED`, the user is not a channel operator.
 
-### Success / Informational (0xx–3xx)
+## Where the files differ from the HTTP API
 
-| Code  | Name           | File                | Description                    |
-| ----- | -------------- | ------------------- | ------------------------------ |
-| `001` | RPL_WELCOME    | `numerics/001.json` | Welcome after session creation |
-| `002` | RPL_YOURHOST   | `numerics/002.json` | Server host info               |
-| `003` | RPL_CREATED    | `numerics/003.json` | Server creation date           |
-| `004` | RPL_MYINFO     | `numerics/004.json` | Server info and modes          |
-| `322` | RPL_LIST       | `numerics/322.json` | Channel list entry             |
-| `323` | RPL_LISTEND    | `numerics/323.json` | End of channel list            |
-| `332` | RPL_TOPIC      | `numerics/332.json` | Channel topic                  |
-| `353` | RPL_NAMREPLY   | `numerics/353.json` | Channel member list            |
-| `366` | RPL_ENDOFNAMES | `numerics/366.json` | End of NAMES list              |
-| `372` | RPL_MOTD       | `numerics/372.json` | MOTD line                      |
-| `375` | RPL_MOTDSTART  | `numerics/375.json` | Start of MOTD                  |
-| `376` | RPL_ENDOFMOTD  | `numerics/376.json` | End of MOTD                    |
+Where a schema file and the HTTP API disagree, the HTTP API is right:
 
-### Errors (4xx)
+- `message.json` and the files in `numerics/` put the three-digit code in
+  `command`. They have no `code` field. The HTTP API puts the reply's name in
+  `command` and its number in `code`.
+- `message.json` allows an object as `body`. The HTTP API reads only arrays of
+  strings. A `PRIVMSG` with an object as `body` gets `ERR_NOTEXTTOSEND` (`412`).
+- `message.json` says `to` is a channel or a nick. A `WALLOPS` message has `*`
+  there.
+- `message.json` allows `meta` on every message. The HTTP API keeps a client's
+  `meta` only on a `PRIVMSG` or `NOTICE`.
+- `message.json` describes signature fields in `meta`. The server never checks a
+  signature.
+- `message.json` does not describe `meta.hashcash`. The HTTP API reads it in a
+  `PRIVMSG` to a channel with mode `+H`.
+- `JOIN.json` has no `body`. A client's `JOIN` can carry the channel key in
+  `body`. When a user joins, the `JOIN` event repeats the channel name in
+  `body`.
+- `JOIN.json` allows a channel name of any length. The server allows at most 63
+  characters after the `#`. It answers a longer name with `ERR_NOSUCHCHANNEL`
+  (`403`).
+- `KICK.json` puts the kicked nick in `params`. The HTTP API reads a client's
+  `KICK` from `body`: the nick, then an optional reason.
+- `MODE.json` puts the mode change in `params`. The HTTP API uses `body`
+  instead. A client sends the change and any value as separate strings, such as
+  `"+o"` and `"bob"`. In a `MODE` event, `body` holds the change as one string,
+  such as `"+o bob"`, or as two strings, such as `"+k"` and `"secret"`.
+- `NOTICE.json` allows `*` as `to`. The server answers a `NOTICE` to `*` with
+  `ERR_NOSUCHNICK` (`401`).
+- `NOTICE.json` has an example notice from the server to `*`. The server sends
+  no such notice.
+- `PING.json` and `PONG.json` describe a token that the `PONG` repeats. The HTTP
+  API ignores the `body` of a `PING`. Its answer is the HTTP response
+  `{"command": "PONG", "from": "<server name>"}`.
+- `PING.json` and `PONG.json` also describe messages between servers. The server
+  does not connect to other IRC servers.
+- `PUBKEY.json` describes a command the server does not have.
+- `QUIT.json` says that `QUIT` comes only from the server. A client can send it
+  too, to end its session. A client's `QUIT` can carry a reason in `body`.
+- `TOPIC.json` says a `TOPIC` without a `body` queries the topic. The HTTP API
+  answers such a `TOPIC` with `ERR_NEEDMOREPARAMS` (`461`).
+- `TOPIC.json` says an empty array clears the topic. The HTTP API answers `[]`
+  with `ERR_NEEDMOREPARAMS` (`461`). A `body` of `[""]` clears the topic.
+- `003.json` describes the server's creation date. The HTTP API sends the date
+  the server last started.
+- `004.json` has example mode lists. The HTTP API sends an empty string as the
+  user modes and `ikmnostl` as the channel modes.
+- `322.json` says `LIST` gets one reply per channel. The server leaves out a
+  secret channel, one with mode `+s`, unless the user is on it.
+- `332.json` says `RPL_TOPIC` answers a `TOPIC` query. The HTTP API has no such
+  query. It sends `RPL_TOPIC` after a client sets the topic, and after a `JOIN`
+  to a channel that has one.
+- `353.json` says `body` lists nicks. The HTTP API lists `nick!user@host` in
+  place of each nick, such as `@op1!op1@host1`.
+- `353.json` says the first parameter marks a channel as public, private or
+  secret. The server always sends `=`, the mark for a public channel.
+- `376.json` gives the text as `End of /MOTD command`. The HTTP API adds a full
+  stop.
+- `401.json` gives the text as `No such nick/channel`. The server sends
+  `No such nick` in answer to a `PRIVMSG` or `NOTICE` to an unknown nick.
+- `433.json` has an example with `*` as `to`. The HTTP API sends `433` only in
+  answer to a `NICK`, with the user's nick as `to`.
 
-| Code  | Name                 | File                | Description             |
-| ----- | -------------------- | ------------------- | ----------------------- |
-| `401` | ERR_NOSUCHNICK       | `numerics/401.json` | No such nick/channel    |
-| `403` | ERR_NOSUCHCHANNEL    | `numerics/403.json` | No such channel         |
-| `433` | ERR_NICKNAMEINUSE    | `numerics/433.json` | Nickname already in use |
-| `442` | ERR_NOTONCHANNEL     | `numerics/442.json` | Not on that channel     |
-| `482` | ERR_CHANOPRIVSNEEDED | `numerics/482.json` | Not channel operator    |
-
-## Federation (S2S)
-
-Server-to-server messages use the same command format. Federated servers relay
-messages with an additional `origin` field in `meta` to track the source server.
-The PING/PONG commands serve as inter-server keepalives. State sync after link
-establishment uses a burst of JOIN, NICK, TOPIC, and MODE commands.
+The HTTP API also accepts some messages that the files do not allow, such as a
+`JOIN` whose `to` has no `#`.