Make Alt and a digit set the send target as /window does (closes #221)

In neoirc-cli, Alt and a digit switched the window but kept the send
target, so typed text went to the window the user had left. The key
now runs /window with that digit through the input handler.

/window 0 now clears the send target. The status window has no target,
but the command used to keep the previous one.

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

@@ -2611,7 +2611,7 @@ listener.
 | Variable               | Type   | Default                                                                                | Description                                                                                                                                                                                                                                                                             |
 | ---------------------- | ------ | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `PORT`                 | int    | `8080`                                                                                 | HTTP listen port                                                                                                                                                                                                                                                                        |
-| `DBURL`                | string | `file:///var/lib/neoirc/state.db?_pragma=journal_mode(WAL)&_pragma=busy_timeout(5000)` | SQLite connection string. For file-based: `file:///path/to/db.db?_pragma=journal_mode(WAL)&_pragma=busy_timeout(5000)`. For in-memory (testing): `file::memory:?cache=shared`. See [SQLite Considerations](#sqlite-considerations).                                                     |
+| `DBURL`                | string | `file:///var/lib/neoirc/state.db?_pragma=journal_mode(WAL)&_pragma=busy_timeout(5000)` | SQLite connection string. For file-based: `file:///path/to/db.db?_pragma=journal_mode(WAL)&_pragma=busy_timeout(5000)`. For in-memory (testing): `file::memory:?cache=shared`. It must not set `foreign_keys`. See [SQLite Considerations](#sqlite-considerations).                     |
 | `DEBUG`                | bool   | `false`                                                                                | Switch logging to debug level                                                                                                                                                                                                                                                           |
 | `MESSAGE_MAX_AGE`      | string | `720h`                                                                                 | Maximum age of messages as a Go duration string (e.g. `720h`, `24h`). Messages older than this are pruned. Default is 30 days.                                                                                                                                                          |
 | `SESSION_IDLE_TIMEOUT` | string | `720h`                                                                                 | Idle timeout as a Go duration string (e.g. `720h`, `24h`). Clients with no authenticated HTTP API request or IRC listener command for this long are removed, and a session left with none is expired and its nick released (see [Data Lifecycle](#data-lifecycle)). Default is 30 days. |
@@ -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

@@ -627,6 +627,10 @@ func (a *App) cmdWindow(args string) {
 				nick, buf.Name, "connected",
 			)
 		} else {
+			a.mu.Lock()
+			a.target = ""
+			a.mu.Unlock()
+
 			a.ui.SetStatus(nick, "", "connected")
 		}
 	}

internal/cli/app_internal_test.go

@@ -219,6 +219,63 @@ 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}
+			app.ui.OnInput(app.handleInput)
+			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.GetInputCapture()(key)
+
+			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)
+			}
+		})
+	}
+}
+
 // 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.

internal/cli/ui.go

@@ -240,10 +240,13 @@ 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)
+				if ui.onInput != nil {
+					ui.onInput("/window " + string(r))
+				}
 
 				return nil
 			}

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.go

@@ -5,9 +5,11 @@ import (
 	"context"
 	"database/sql"
 	"embed"
+	"errors"
 	"fmt"
 	"io/fs"
 	"log/slog"
+	"net/url"
 	"sort"
 	"strconv"
 	"strings"
@@ -22,6 +24,10 @@ import (
 
 const minMigrationParts = 2
 
+var errForeignKeysInDBURL = errors.New(
+	"DBURL must not set foreign_keys, which the server always turns on",
+)
+
 // SchemaFiles contains embedded SQL migration files.
 //
 //go:embed schema/*.sql
@@ -90,6 +96,33 @@ func (database *Database) connect(ctx context.Context) error {
 		dbURL = config.DefaultDBURL
 	}
 
+	// SQLite keeps the foreign keys setting per connection. The driver
+	// runs each _pragma parameter on every connection it opens. So the
+	// one added below also covers the connection the pool opens after
+	// a cancelled query breaks the old one. A foreign_keys pragma in
+	// DBURL could undo it, because the driver sorts the pragmas.
+	_, query, hasQuery := strings.Cut(dbURL, "?")
+
+	urlParams, err := url.ParseQuery(query)
+	if err != nil {
+		return fmt.Errorf("parse DBURL: %w", err)
+	}
+
+	for _, pragma := range urlParams["_pragma"] {
+		if strings.Contains(strings.ToLower(pragma), "foreign_keys") {
+			return fmt.Errorf(
+				"%w: _pragma=%s", errForeignKeysInDBURL, pragma,
+			)
+		}
+	}
+
+	separator := "?"
+	if hasQuery {
+		separator = "&"
+	}
+
+	dbURL += separator + "_pragma=foreign_keys(1)"
+
 	database.log.Info(
 		"connecting to database", "url", dbURL,
 	)
@@ -109,13 +142,6 @@ func (database *Database) connect(ctx context.Context) error {
 	database.conn = conn
 	database.log.Info("database connected")
 
-	_, err = database.conn.ExecContext(
-		ctx, "PRAGMA foreign_keys = ON",
-	)
-	if err != nil {
-		return fmt.Errorf("enable foreign keys: %w", err)
-	}
-
 	return database.runMigrations(ctx)
 }
 

internal/db/db_test.go

@@ -1,19 +1,34 @@
 package db_test
 
 import (
+	"context"
+	"errors"
+	"net/url"
 	"path/filepath"
 	"strings"
 	"testing"
+	"time"
 
 	"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"
 )
 
 const wantBusyTimeoutMS = 5000
 
+const (
+	// endlessQuery counts the rows of a recursive query that never
+	// stops, so it runs until its context ends.
+	endlessQuery = `WITH RECURSIVE n(x) AS
+		(SELECT 1 UNION ALL SELECT x + 1 FROM n)
+		SELECT COUNT(*) FROM n`
+
+	endlessQueryTimeout = 100 * time.Millisecond
+)
+
 // TestDefaultDBURLSetsWALAndBusyTimeout opens a file database
 // with the default URL's parameters the way the server does,
 // and checks the journal mode and busy timeout it ends up with.
@@ -73,3 +88,191 @@ func TestDefaultDBURLSetsWALAndBusyTimeout(t *testing.T) {
 		)
 	}
 }
+
+// TestForeignKeysOnAfterCancelledQuery cancels a query 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 test then
+// checks that the file database keeps its tables and that the new
+// connection has foreign keys on.
+func TestForeignKeysOnAfterCancelledQuery(t *testing.T) {
+	t.Parallel()
+
+	_, defaultParams, _ := strings.Cut(config.DefaultDBURL, "?")
+
+	urlParams := map[string]string{
+		"default parameters": "?" + defaultParams,
+		"no parameters":      "",
+	}
+
+	for name, params := range urlParams {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			dbURL := "file://" +
+				filepath.Join(t.TempDir(), "state.db") + params
+
+			database, err := startDatabase(t, dbURL)
+			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")
+			}
+
+			migrations := queryInt(
+				t, database, "SELECT COUNT(*) FROM schema_migrations",
+			)
+			if migrations == 0 {
+				t.Error("schema_migrations is empty")
+			}
+
+			foreignKeys := queryInt(t, database, "PRAGMA foreign_keys")
+			if foreignKeys != 1 {
+				t.Errorf("foreign_keys = %d, want 1", foreignKeys)
+			}
+		})
+	}
+}
+
+// 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.
+func TestDBURLSettingForeignKeysFailsStartup(t *testing.T) {
+	t.Parallel()
+
+	pragmas := []string{
+		"foreign_keys(0)",
+		"foreign_keys(off)",
+		"foreign_keys=0",
+		"FOREIGN_KEYS(FALSE)",
+		" Foreign_Keys = 1",
+	}
+
+	for _, pragma := range pragmas {
+		t.Run(pragma, func(t *testing.T) {
+			t.Parallel()
+
+			dbURL := "file://" +
+				filepath.Join(t.TempDir(), "state.db") +
+				"?_pragma=" + url.QueryEscape(pragma)
+
+			_, err := startDatabase(t, dbURL)
+			if err == nil {
+				t.Fatal("the database started")
+			}
+
+			if !strings.Contains(err.Error(), "DBURL") {
+				t.Errorf("error %q does not name DBURL", err)
+			}
+		})
+	}
+}
+
+// startDatabase starts a Database for dbURL the way the server does.
+// It returns the error that stopped it from starting, if any.
+func startDatabase(t *testing.T, dbURL string) (*db.Database, error) {
+	t.Helper()
+
+	lifecycle := fxtest.NewLifecycle(t)
+
+	log, err := logger.New(lifecycle, logger.Params{
+		Globals: &globals.Globals{},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	database, err := db.New(lifecycle, db.Params{
+		Logger: log,
+		Config: &config.Config{DBURL: dbURL},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	t.Cleanup(lifecycle.RequireStop)
+
+	return database, lifecycle.Start(t.Context())
+}
+
+// queryInt runs a query that returns a single number.
+func queryInt(t *testing.T, database *db.Database, query string) int {
+	t.Helper()
+
+	var result int
+
+	err := database.GetDB().QueryRowContext(t.Context(), query).Scan(&result)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	return result
+}

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 `#`.