Remove the unused GetSessionChannelIDs from the db package (closes #254)

Neither the server nor any test calls this method.

Model: opus-5-5

AGENTS.md

@@ -1,55 +1,73 @@
-# AGENTS.md — Rules for AI Agents
+# Rules for coding agents
 
-## Before Every Commit
+This file holds the rules for coding agents working in this repository.
+`CONVENTIONS.md` defines the architecture. `REPO_POLICIES.md` defines the
+repository standards. Both are copies of shared documents. Do not edit them
+here.
 
-1. **Format**: `make fmt`
-2. **Check**: `make check` — the tests and the linter, which run in Docker, and
-   the format check: all passing, zero issues
+## Before every commit
 
-Never run `go test`, `golangci-lint` or `gofmt` directly; use the `make`
-targets.
+1. Run `make fmt`.
+2. Run `make check`. It runs the tests and the linter in Docker, then the format
+   check. All three must pass with no findings.
 
-No commit lands on main with lint errors, test failures, or formatting issues.
+Never run `go test`, `golangci-lint` or `gofmt` directly. Use the `make` targets
+instead, such as `make test` and `make lint`.
 
-## Code Style
+## Branches and pull requests
 
-- Follow CONVENTIONS.md exactly — it defines the architecture
-- All exported types, functions, methods, and vars must have doc comments
-- All packages must have a package doc comment
-- JSON tags use camelCase (not snake_case)
-- No magic numbers — use named constants
-- No inline error handling (`if err := ...; err != nil`) — use plain assignment
-- Blank line before every `return` statement
-- Blank line separating embedded fields from regular fields in structs
-- Blank imports must have a justification comment
+- Never commit to `main` or `next` directly. Every change is a pull request from
+  a feature branch into `next`.
+- Only the owner merges `next` into `main`.
+- A pull request that closes an issue has the title `Description (closes #N)`.
+- One logical change per commit.
+- Commit messages are in the imperative mood and short.
 
-## Git Workflow
+## Code style
 
-- **Never commit directly to main** — all changes go on feature branches
-- Merge to main only when ready and passing all checks
-- PR titles: `Description (closes #N)` when closing an issue
-- One logical change per commit
-- Commit messages: imperative mood, concise
+- Follow `CONVENTIONS.md`.
+- Every package has a package doc comment. Test files need none.
+- Every exported type, function and variable has a doc comment. Test files need
+  none.
+- JSON tags are camelCase. The HTTP API's `last_id`, `pow_token` and
+  `hashcash_bits` stay as they are, each with a `//nolint:tagliatelle` comment.
+- Prefer named constants to magic numbers. The `mnd` linter checks for them
+  outside test files.
+- No inline error handling such as `if err := f(); err != nil`. Assign the error
+  on its own line, then test it.
+- A `return` that follows another statement in its block has a blank line before
+  it.
+- A blank line between the embedded fields of a struct and its other fields.
+- Every blank import has a comment saying why it is there. Test files need none.
 
 ## Architecture
 
-- Dependency injection via Uber fx — all components are fx providers
-- `internal/` for all application packages — one package per concern
-- Handlers return `http.HandlerFunc` using the closure pattern
-- Request/response structs defined inside handler closures
-- Models embed `models.Base` for database access to relation methods
-- Database migrations in `internal/db/schema/` — embedded via `go:embed`
-- SQLite by default (pure Go driver: modernc.org/sqlite)
+- The server uses `go.uber.org/fx` for dependency injection.
+  `cmd/neoircd/main.go` lists its `fx` providers, such as `db.New` and
+  `handlers.New`.
+- Application packages live under `internal/`, one package per concern.
+- `pkg/irc` holds the IRC command names and numeric reply codes.
+- The `web` package embeds the built web client.
+- Each exported `Handle…` method of `Handlers` returns an `http.HandlerFunc`.
+- A request struct is defined inside the method that decodes it.
+- The server uses the database only through the methods of `db.Database`.
+- The database migrations live in `internal/db/schema/` and are embedded with
+  `go:embed`.
+- The database is SQLite, through the pure Go driver `modernc.org/sqlite`.
 
 ## Testing
 
-- Table-driven tests preferred
-- Use `testing.T` helpers, not assertion libraries
-- Test files live next to the code they test
-- `_test.go` suffix, same package for white-box testing
+- Prefer table-driven tests.
+- Use `testing.T` helpers, not assertion libraries.
+- A test file lives next to the code it tests and ends in `_test.go`.
+- The linter requires each test file to be in the package's external test
+  package, such as `handlers_test`. It allows `export_test.go` and files ending
+  in `_internal_test.go` in the package itself.
+- An `export_test.go` file gives the external tests access to the package's
+  unexported code.
 
 ## Dependencies
 
-- Required libraries are listed in CONVENTIONS.md §1
-- No new dependencies without justification
-- Pure Go preferred (no CGO)
+- The required libraries are listed in `CONVENTIONS.md` §1.
+- No new dependency without a reason given in the pull request.
+- Prefer dependencies written in pure Go, which build without cgo.

Dockerfile

@@ -33,14 +33,18 @@ RUN golangci-lint run --config .golangci.yml ./...
 # golang:1.24.13-bookworm, 2026-10-06
 FROM golang@sha256:1a6d4452c65dea36aac2e2d606b01b4a029ec90cc1ae53890540ce6173ea77ac AS test
 WORKDIR /src
-COPY go.mod go.sum ./
-RUN go mod download
 COPY . .
 RUN mkdir -p web/dist && touch web/dist/index.html web/dist/style.css web/dist/app.js
 # -p 4 because test runs on a shared build host cap their parallelism.
-RUN go test -p 4 -timeout 90s -race -cover ./... || \
+# The modules download in this RUN rather than a layer of their own, because
+# exporting a layer that holds them is slow. Nothing reads them or the build
+# cache afterwards, so go clean removes both.
+RUN set -e; \
+    go mod download; \
+    go test -p 4 -timeout 90s -race -cover ./... || \
     { echo "--- Rerunning with -v for details ---"; \
-      go test -p 4 -timeout 90s -race -v ./...; exit 1; }
+      go test -p 4 -timeout 90s -race -v ./...; exit 1; }; \
+    go clean -cache -modcache
 
 # Build stage. Nothing is wanted from either phase above; the copies
 # are what make BuildKit build them first, so this stage cannot run

README.md

@@ -25,7 +25,7 @@ neoirc is IRC with a different transport. The commands are IRC's: `PRIVMSG`,
 replies, such as `353` and `433`. Channels start with `#`. The first user to
 join a channel creates it, and a channel disappears when its last member leaves.
 
-Four things differ from IRC:
+The main differences from IRC:
 
 - A client talks to the server over HTTP. It sends commands with one `POST`
   request and reads its messages with one `GET` request.
@@ -48,9 +48,8 @@ The repository ships three programs:
 
 IRC ties a session to one TCP connection. When a phone drops the connection, the
 user loses the nick, the channels and every message sent in between. neoirc
-keeps the session on the server, so a client can disconnect and come back
-without losing anything. Everything else stays IRC: the same commands, the same
-replies, the same channel modes.
+keeps the session on the server. A client can disconnect and come back to its
+nick, its channels and the messages it missed.
 
 ## Getting started
 
@@ -123,12 +122,14 @@ seen as `after`, so it reads each entry once.
 
 Three kinds of message reach a queue:
 
-- Chat messages: `PRIVMSG` and `NOTICE`. The server echoes a session's own to
-  every client of the session, except an IRC connection that sent one.
+- **Chat messages**: `PRIVMSG` and `NOTICE`. The server echoes a session's own
+  chat messages to every client of the session, except the IRC connection that
+  sent one.
 - **Events**: `JOIN`, `PART`, `NICK`, `QUIT`, `TOPIC`, `MODE`, `KICK`, `INVITE`
   and `WALLOPS`, telling the client what other users did. When a client's own
-  `JOIN`, `PART`, `NICK`, `TOPIC`, `MODE` or `KICK` causes an event, every
-  client of its session receives it too.
+  `JOIN`, `PART`, `NICK`, `TOPIC`, `MODE` or `KICK` causes an event, every HTTP
+  client of its session receives it too. The IRC connection that sent the
+  command gets it as an IRC line instead.
 - **Numeric replies**: the server's answers to commands, such as `RPL_TOPIC` or
   `ERR_NOSUCHNICK`. A numeric reply goes only to the client that sent the
   command.
@@ -185,8 +186,8 @@ of the response does not repeat it. A browser sends the cookie by itself. Any
 other client must save it and send it back, as `curl -c` and `curl -b` do.
 
 The cookie is `Secure`. Chrome, Firefox, `curl` and `neoirc-cli` send it to a
-server on `localhost` over plain HTTP too; Python's `requests` does not. For
-every other host the server needs HTTPS, which a reverse proxy provides.
+server on `localhost` over plain HTTP too; Python's `requests` does not. To a
+remote host they send it only over HTTPS, which a reverse proxy provides.
 
 `QUIT`, `POST /api/v1/logout`, `KILL` and the idle cleanup invalidate the
 cookie. After that, every request with it gets `401`.
@@ -201,7 +202,7 @@ No auth. Request body:
 {
     "nick": "alice",
     "username": "alice",
-    "pow_token": "1:20:260310:neoirc::3a2f1"
+    "pow_token": "1:20:261027:neoirc::5971e"
 }
 ```
 
@@ -221,8 +222,9 @@ Response `201`, with the cookie:
 
 `id` is the session's number. The new client's queue already holds the welcome
 replies `001` to `005` and the `LUSERS` replies (see
-[Numeric replies](#numeric-replies)). It also holds the message of the day when
-`MOTD` is set.
+[Numeric replies](#numeric-replies)). It also holds the message of the day,
+unless that is empty (see the `MOTD` setting under
+[Configuration](#configuration)).
 
 Errors:
 
@@ -233,9 +235,11 @@ Errors:
   requires one.
 - `402` `invalid hashcash stamp: <reason>`.
 - `409` `nick already taken`.
+- `500` `internal error`.
 
 The server checks the stamp before the nick, and spends it only when the session
-is created. A request refused with `400` or `409` leaves the stamp unspent.
+is created. A request refused with `400`, `409` or `500` leaves the stamp
+unspent.
 
 #### `POST /api/v1/login`: add a client to a session
 
@@ -253,7 +257,7 @@ Response `200`, with a new cookie for the new client:
 ```
 
 The new client's queue holds the welcome replies and the `LUSERS` replies, then
-the message of the day when `MOTD` is set. For each channel of the session it
+the message of the day unless that is empty. For each channel of the session it
 then holds:
 
 - a `JOIN` event from the session's own nick with an empty `body`;
@@ -280,16 +284,16 @@ Needs auth. Response `200`:
     "id": 1,
     "nick": "alice",
     "channels": [
-        { "id": 1, "name": "#general", "topic": "Welcome!" },
-        { "id": 2, "name": "#dev", "topic": "" }
+        { "id": 2, "name": "#dev", "topic": "" },
+        { "id": 1, "name": "#general", "topic": "Welcome!" }
     ]
 }
 ```
 
 `channels` lists the channels the session has joined, sorted by name. With
-`?initChannelState=1`, the server also fills the calling client's queue as
-`POST /api/v1/login` does. The web client uses this when it loads, to restore
-its channel tabs.
+`?initChannelState=1`, the server also queues, for each channel, the `JOIN`
+event, the topic replies and the member list, as `POST /api/v1/login` does. The
+web client uses this when it loads, to restore its channel tabs.
 
 `GET /api/v1/users/me` is the same endpoint under another path.
 
@@ -298,9 +302,11 @@ its channel tabs.
 Needs auth. Query parameters:
 
 - `after` (default `0`): return only queue entries with a number greater than
-  this. Pass the `last_id` of the previous response.
+  this. Pass the `last_id` of the previous response. A value that is not a whole
+  number counts as `0`.
 - `timeout` (default `0`): how many seconds to wait for a message when the queue
-  has none. `0` answers at once. The server caps it at `30`.
+  has none. `0` answers at once. The server caps it at `30`. A negative value,
+  or one that is not a whole number, counts as `0`.
 
 Response `200`:
 
@@ -327,9 +333,9 @@ the last entry returned, or the `after` value when there was none.
 When the queue has nothing after `after` and `timeout` is above `0`, the server
 holds the request. This wait is a long poll. It ends when a message arrives for
 any client of the session, or when the time is up. The answer then holds the
-messages queued for this client, or an empty `messages` array when there are
-none, as when the message was for another client of the session. A client that
-closes the connection first gets no answer.
+messages queued for this client. When there are none, `messages` is an empty
+array. That happens when the message was for another client of the session, or
+when the time ran out. A client that closes the connection first gets no answer.
 
 A client loop is: call with `after=0`, then call again with `after` set to each
 response's `last_id`. Passing an earlier `after` reads the entries again. Queue
@@ -350,7 +356,9 @@ gets `ERR_UNKNOWNCOMMAND` (`421`) in the queue and `{"status": "error"}`.
 
 Errors at the HTTP level:
 
-- `400` `invalid request body`: not JSON, or too large.
+- `400` `invalid request body`: not JSON, or too large. A `PRIVMSG` or `NOTICE`
+  also gets it when `body` is not an array of strings or `meta` is not an
+  object.
 - `400` `command required`.
 - `401` `not registered`.
 - `500` `internal error`.
@@ -365,14 +373,18 @@ Needs auth. Query parameters:
 - `limit` (default `50`): at most this many messages, from 1 to 500. Any other
   value means 50.
 
-Response `200`: an array of `PRIVMSG` messages, oldest first. Only `PRIVMSG` is
-kept in history; events and `NOTICE` are not.
+Response `200`: an array of `PRIVMSG` messages, oldest first. History holds only
+`PRIVMSG`; events and `NOTICE` are left out.
+
+Without `before`, the answer holds the newest `limit` messages. With `before`,
+it holds the newest `limit` messages older than that one.
 
 For a channel, the caller must be a member. For a nick, only the caller's own
 nick is allowed. The result is then the direct messages sent to the caller's
-session, under any nick it has held. A session that takes a released nick sees
-none of the messages sent to the nick's earlier holder. A channel created again
-after it was deleted starts with no history.
+session, under any nick it has held. It does not hold the direct messages the
+caller sent. A session that takes a released nick sees none of the messages sent
+to the nick's earlier holder. A channel created again after it was deleted
+starts with no history.
 
 To page back, pass the `id` of the oldest message of a page as `before`. An
 empty array means there is nothing older.
@@ -399,8 +411,8 @@ Needs auth. Response `200`: every channel on the server, sorted by name, secret
 
 ```json
 [
-    { "id": 1, "name": "#general", "topic": "Welcome!" },
-    { "id": 2, "name": "#dev", "topic": "" }
+    { "id": 2, "name": "#dev", "topic": "" },
+    { "id": 1, "name": "#general", "topic": "Welcome!" }
 ]
 ```
 
@@ -422,8 +434,9 @@ Needs auth. `{name}` is the channel name without the `#`. Response `200`:
 ]
 ```
 
-`id` is the member's session number. `lastSeen` is the time of the session's
-last request. An unknown channel gets `404` `channel not found`.
+The members are sorted by nick. `id` is the member's session number. `lastSeen`
+is the time of the session's last request. An unknown channel gets `404`
+`channel not found`.
 
 #### `POST /api/v1/logout`: remove this client
 
@@ -522,16 +535,18 @@ with these fields:
 - `params`: an array of strings with further parameters. `KICK` events and many
   numeric replies have it. The server ignores one sent by a client.
 - `body`: an array of strings. For chat it is the lines of text, one string per
-  line. A `body` is never a bare string. Every numeric reply has a `body`; a
-  few, such as `RPL_CHANNELMODEIS`, carry one empty string.
+  line. A `body` is never a bare string. On a command other than `PRIVMSG` and
+  `NOTICE`, a `body` that is not an array of strings counts as missing. Every
+  numeric reply has a `body`; a few, such as `RPL_CHANNELMODEIS`, carry one
+  empty string.
 - `ts`: when the server stored the message: UTC, RFC 3339 with fractional
   seconds, such as `2026-02-10T20:00:00.123456789Z`; trailing zeros are dropped.
   The server assigns it.
 - `meta`: an object. A client may put anything in it. On a `PRIVMSG` or `NOTICE`
-  the server stores and relays it unchanged, and `{}` when the client sent none.
-  On every other command the server drops it, and the event carries `{}`. The
-  server reads one key: `meta.hashcash` on a `PRIVMSG` to a channel with mode
-  `+H`.
+  the server stores and relays it unchanged. When the client sent none, the
+  message carries `{}`. On every other command the server drops it, and the
+  event carries `{}`. The server reads one key: `meta.hashcash` on a `PRIVMSG`
+  to a channel with mode `+H`.
 
 ### Commands
 
@@ -555,7 +570,8 @@ otherwise, an error numeric comes with the HTTP response `{"status": "error"}`.
 {"command": "PRIVMSG", "to": "bob", "body": ["hey"]}
 ```
 
-- `to` (required): a channel name, or a nick for a direct message.
+- `to` (required): a channel name, or a nick for a direct message. The server
+  does not add a missing `#` here: a `to` without one is a nick.
 - `body` (required): one or more lines.
 - `meta` (optional): relayed unchanged. A `PRIVMSG` to a `+H` channel carries
   its stamp in `meta.hashcash`.
@@ -584,25 +600,30 @@ Replies and errors:
 - `ERR_NORECIPIENT` (`411`): no `to`.
 - `ERR_NOTEXTTOSEND` (`412`): no `body`, or an empty one.
 - `ERR_NOSUCHCHANNEL` (`403`): the channel does not exist.
-- `ERR_CANNOTSENDTOCHAN` (`404`): the message is not allowed. The `body` says
-  why:
+- `ERR_CANNOTSENDTOCHAN` (`404`): the message is not allowed:
     - the sender is not a member;
     - the sender is banned (`+b`);
     - the channel is moderated (`+m`) and the sender has neither `+o` nor `+v`;
     - the channel is `+H` and the message has no valid hashcash stamp.
+
+    The `body` names the reason in the last three cases.
+
 - `ERR_NOSUCHNICK` (`401`): no session has the target nick.
 - `RPL_AWAY` (`301`): the target of a direct message is away. The message is
   still delivered. `params` holds the nick and `body` the away message.
 
 HTTP response: `{"id": "<message id>", "status": "sent"}`.
 
+A `body` or `meta` of the wrong type gets `400` `invalid request body`, and
+nothing is relayed.
+
 #### `NOTICE`: send a notice
 
 The same as `PRIVMSG`, with three differences:
 
 - The server sends no `RPL_AWAY` for a notice.
 - A notice to a `+H` channel needs no hashcash stamp.
-- A notice is not kept in history (see
+- A notice does not appear in history (see
   [`GET /api/v1/history`](#get-apiv1history-past-messages)).
 
 A client that receives a `NOTICE` must not answer it automatically. That is the
@@ -826,8 +847,8 @@ changes:
   positive whole number.
 - `+b <mask>` / `-b <mask>`: add or remove a ban. `+b` with no mask lists the
   bans; anyone may do that.
-- `+H <bits>` / `-H`: require a hashcash stamp of `bits` leading zero bits on
-  every `PRIVMSG`, from 1 to 40, or stop requiring one.
+- `+H <bits>` / `-H`: require a hashcash stamp on every `PRIVMSG`, or stop
+  requiring one. `bits`, from 1 to 40, is the number of leading zero bits.
 
 Every member, the operator included, receives a `MODE` event. For `o`, `v`, `i`,
 `m`, `s` and `t` its `body` is one string: `["+o bob"]`, `["+m"]`. For `k`, `l`
@@ -850,8 +871,8 @@ Errors of a channel `MODE`:
 - `ERR_NEEDMOREPARAMS` (`461`): no `to`, or `+o`, `-o`, `+v`, `-v`, `+k`, `+l`,
   `-b` or `+H` without its value.
 - `ERR_NOSUCHCHANNEL` (`403`): the channel does not exist.
-- `ERR_CHANOPRIVSNEEDED` (`482`): a change by a user who is not a channel
-  operator.
+- `ERR_CHANOPRIVSNEEDED` (`482`): a change from the list above by a user who is
+  not a channel operator.
 - `ERR_UNKNOWNMODE` (`472`), in three cases:
     - a change the list above does not have;
     - a `+H` value that is not a whole number from 1 to 40;
@@ -864,9 +885,9 @@ gets `ERR_USERSDONTMATCH` (`502`). With no `body`, the server sends
 `RPL_UMODEIS` (`221`) with the modes in `body`: `+`, `+o`, `+w` or `+ow`. With a
 `body`, `body[0]` is a mode string starting with `+` or `-`, such as `+w` or
 `-o`. `w` can be set and unset. `o` can only be unset; `OPER` sets it. A string
-with any other letter, or without a letter, gets `ERR_UMODEUNKNOWNFLAG` (`501`)
-and changes nothing. An accepted change is answered with `RPL_UMODEIS` (`221`)
-and the new modes, and nobody else is told.
+that sets `o`, has any other letter or has no letter gets `ERR_UMODEUNKNOWNFLAG`
+(`501`) and changes nothing. An accepted change is answered with `RPL_UMODEIS`
+(`221`) and the new modes, and nobody else is told.
 
 ```json
 { "command": "RPL_UMODEIS", "code": 221, "to": "alice", "body": ["+w"] }
@@ -949,9 +970,9 @@ HTTP response: `{"status": "ok"}`.
 ```
 
 A `body` sets the away message; several strings are joined with spaces. No
-`body` clears it. The reply is `RPL_NOWAWAY` (`306`) or `RPL_UNAWAY` (`305`). A
-user who sends a `PRIVMSG` to an away user receives `RPL_AWAY` (`301`).
-`USERHOST` marks an away user with `-`.
+`body`, or one empty string, clears it. The reply is `RPL_NOWAWAY` (`306`) or
+`RPL_UNAWAY` (`305`). A user who sends a `PRIVMSG` to an away user receives
+`RPL_AWAY` (`301`). `USERHOST` marks an away user with `-`.
 
 HTTP response: `{"status": "ok"}`.
 
@@ -963,9 +984,9 @@ HTTP response: `{"status": "ok"}`.
 
 The server adds a missing `#`. The reply is `RPL_NAMREPLY` (`353`), when the
 channel has members, then `RPL_ENDOFNAMES` (`366`). `RPL_NAMREPLY` has `params`
-`["=", channel]` and a `body` with one string: the members' hostmasks separated
-by spaces, each with `@` before a channel operator and `+` before a voiced
-member:
+`["=", channel]` and a `body` with one string. That string holds the members'
+hostmasks in nick order, separated by spaces. A `@` before a hostmask marks a
+channel operator, and a `+` marks a voiced member:
 
 ```json
 {
@@ -973,7 +994,7 @@ member:
     "code": 353,
     "to": "alice",
     "params": ["=", "#general"],
-    "body": ["@op1!op1@host1 alice!alice@host2 +bob!bob@host3"]
+    "body": ["alice!alice@host2 +bob!bob@host3 @op1!op1@host1"]
 }
 ```
 
@@ -990,7 +1011,7 @@ HTTP response: `{"status": "ok"}`.
 { "command": "LIST" }
 ```
 
-The reply is one `RPL_LIST` (`322`) per channel, with `params`
+The reply is one `RPL_LIST` (`322`) per channel, in name order, with `params`
 `[channel, member count]` and the topic in `body`, then `RPL_LISTEND` (`323`).
 Secret (`+s`) channels the user is not a member of are left out.
 
@@ -1058,8 +1079,8 @@ HTTP response: `{"status": "ok"}`.
 
 The server sends the welcome replies `001` to `005`, the `LUSERS` replies and
 the message of the day again: `RPL_MOTDSTART` (`375`), one `RPL_MOTD` (`372`)
-per line, `RPL_ENDOFMOTD` (`376`). With an empty `MOTD` setting, the welcome and
-`LUSERS` replies come alone.
+per line, `RPL_ENDOFMOTD` (`376`). When the message of the day is empty, the
+welcome and `LUSERS` replies come alone.
 
 HTTP response: `{"status": "ok"}`.
 
@@ -1168,13 +1189,16 @@ name and `to` the client's nick. `005` arrives as `RPL_BOUNCE`, its name in
 RFC 2812. Every reply has a `body` with one string, the reply's text; a few
 carry an empty string.
 
-Sent to every new client, on `POST /api/v1/session`, `POST /api/v1/login` and
-`MOTD`; `375` to `376` only when `MOTD` is set:
+The server sends these to every new client, on `POST /api/v1/session` and
+`POST /api/v1/login`, and again on the `MOTD` command. `375` to `376` are left
+out when the message of the day is empty (see the `MOTD` setting under
+[Configuration](#configuration)).
 
 - `001` `RPL_WELCOME`: `Welcome to the network, <nick>`.
 - `002` `RPL_YOURHOST`: `Your host is <server name>, running version <version>`.
+  `<version>` is `dev` in a binary built without one.
 - `003` `RPL_CREATED`: `This server was created <date the server started>`.
-- `004` `RPL_MYINFO`: `params` `[server name, version, "", "ikmnostl"]`.
+- `004` `RPL_MYINFO`: `params` `[server name, version, "ow", "Hbiklmnostv"]`.
 - `005` `RPL_BOUNCE`: `params`
   `["CHANTYPES=#", "NICKLEN=32", "PREFIX=(ov)@+", "CHANMODES=b,k,Hl,imnst", "NETWORK=neoirc", "CASEMAPPING=ascii"]`,
   `body` `["are supported by this server"]`.
@@ -1189,32 +1213,49 @@ Sent to every new client, on `POST /api/v1/session`, `POST /api/v1/login` and
 - `372` `RPL_MOTD`: one per line of the message of the day, each `- <line>`.
 - `376` `RPL_ENDOFMOTD`: `End of /MOTD command.`
 
-Answers to commands, as described under each command:
+Answers to commands. Each line names the command that gets the reply, then what
+`params` holds:
 
-- `221` `RPL_UMODEIS`: user `MODE`.
-- `256` `RPL_ADMINME`, `257` `RPL_ADMINLOC1`, `258` `RPL_ADMINLOC2`, `259`
-  `RPL_ADMINEMAIL`: `ADMIN`.
-- `301` `RPL_AWAY`: a `PRIVMSG` to an away user.
-- `302` `RPL_USERHOST`: `USERHOST`.
-- `305` `RPL_UNAWAY`, `306` `RPL_NOWAWAY`: `AWAY`.
-- `311` `RPL_WHOISUSER`, `312` `RPL_WHOISSERVER`, `313` `RPL_WHOISOPERATOR`,
-  `317` `RPL_WHOISIDLE`, `318` `RPL_ENDOFWHOIS`, `319` `RPL_WHOISCHANNELS`,
-  `338` `RPL_WHOISACTUALLY`: `WHOIS`.
-- `315` `RPL_ENDOFWHO`, `352` `RPL_WHOREPLY`: `WHO`.
-- `322` `RPL_LIST`, `323` `RPL_LISTEND`: `LIST`.
-- `324` `RPL_CHANNELMODEIS`, `329` `RPL_CREATIONTIME`: a channel `MODE` query;
-  `324` also after `+H` and `-H`.
-- `331` `RPL_NOTOPIC`, `332` `RPL_TOPIC`, `333` `RPL_TOPICWHOTIME`: `JOIN`,
-  `TOPIC` and the channel state after login or `?initChannelState=1`. `333` has
-  `params` `[channel, nick who set the topic, Unix time]`.
-- `341` `RPL_INVITING`: `INVITE`.
-- `351` `RPL_VERSION`: `VERSION`.
-- `353` `RPL_NAMREPLY`, `366` `RPL_ENDOFNAMES`: `JOIN`, `NAMES` and the channel
-  state after login or `?initChannelState=1`.
-- `367` `RPL_BANLIST`, `368` `RPL_ENDOFBANLIST`: `MODE #channel +b`.
-- `371` `RPL_INFO`, `374` `RPL_ENDOFINFO`: `INFO`.
-- `381` `RPL_YOUREOPER`: `OPER`.
-- `391` `RPL_TIME`: `TIME`.
+- `221` `RPL_UMODEIS`: user `MODE`. No `params`; the modes are in `body`.
+- `256` `RPL_ADMINME`: `ADMIN`. `[server name]`.
+- `257` `RPL_ADMINLOC1`, `258` `RPL_ADMINLOC2`, `259` `RPL_ADMINEMAIL`: `ADMIN`.
+  No `params`.
+- `301` `RPL_AWAY`: a `PRIVMSG` to an away user. `[nick]`; the away message is
+  in `body`.
+- `302` `RPL_USERHOST`: `USERHOST`. No `params`.
+- `305` `RPL_UNAWAY`, `306` `RPL_NOWAWAY`: `AWAY`. No `params`.
+- `311` `RPL_WHOISUSER`: `WHOIS`. `[nick, username, hostname, "*"]`.
+- `312` `RPL_WHOISSERVER`: `WHOIS`. `[nick, server name]`.
+- `313` `RPL_WHOISOPERATOR`: `WHOIS`. `[nick]`.
+- `317` `RPL_WHOISIDLE`: `WHOIS`. `[nick, idle seconds, signon Unix time]`.
+- `318` `RPL_ENDOFWHOIS`: `WHOIS`. `[nick]`.
+- `319` `RPL_WHOISCHANNELS`: `WHOIS`. `[nick]`; the channels are in `body`.
+- `338` `RPL_WHOISACTUALLY`: `WHOIS`. `[nick, IP address]`.
+- `315` `RPL_ENDOFWHO`: `WHO`. `[channel]`.
+- `352` `RPL_WHOREPLY`: `WHO`.
+  `[channel, username, hostname, server name, nick, "H"]`.
+- `322` `RPL_LIST`: `LIST`. `[channel, member count]`; the topic is in `body`.
+- `323` `RPL_LISTEND`: `LIST`. No `params`.
+- `324` `RPL_CHANNELMODEIS`: a channel `MODE` query, and a `+H` or `-H` change.
+  `[channel, mode string]`.
+- `329` `RPL_CREATIONTIME`: a channel `MODE` query. `[channel, Unix time]`.
+- `331` `RPL_NOTOPIC`: `JOIN` and the channel state after login or
+  `?initChannelState=1`. `[channel]`.
+- `332` `RPL_TOPIC`: `JOIN`, `TOPIC` and the channel state. `[channel]`; the
+  topic is in `body`.
+- `333` `RPL_TOPICWHOTIME`: `JOIN`, `TOPIC` and the channel state.
+  `[channel, nick who set the topic, Unix time]`.
+- `341` `RPL_INVITING`: `INVITE`. `[nick, channel]`.
+- `351` `RPL_VERSION`: `VERSION`. `["neoirc-<version>.", server name]`.
+- `353` `RPL_NAMREPLY`: `JOIN`, `NAMES` and the channel state. `["=", channel]`;
+  the members are in `body`.
+- `366` `RPL_ENDOFNAMES`: `JOIN`, `NAMES` and the channel state. `[channel]`.
+- `367` `RPL_BANLIST`: `MODE #channel +b`.
+  `[channel, mask, nick who set it, Unix time]`.
+- `368` `RPL_ENDOFBANLIST`: `MODE #channel +b`. `[channel]`.
+- `371` `RPL_INFO`, `374` `RPL_ENDOFINFO`: `INFO`. No `params`.
+- `381` `RPL_YOUREOPER`: `OPER`. No `params`.
+- `391` `RPL_TIME`: `TIME`. `[server name]`; the time is in `body`.
 
 Errors, each with what its `params` holds:
 
@@ -1305,9 +1346,9 @@ of the `X-Forwarded-For` header, then `X-Real-IP`, then the TCP connection (see
 Every user can see a hostmask: in `RPL_WHOISUSER` (`311`), `RPL_WHOREPLY`
 (`352`), `RPL_USERHOST` (`302`), `RPL_NAMREPLY` (`353`) and
 `GET /api/v1/channels/{name}/members`. Bans match against it. Only a server
-operator sees IP addresses, in `RPL_WHOISACTUALLY` (`338`), and only that of the
-user's newest client. When the lookup gave no name, the hostname everyone sees
-is the IP address.
+operator sees IP addresses, in `RPL_WHOISACTUALLY` (`338`) over the HTTP API,
+and only that of the user's newest client. When the lookup gave no name, the
+hostname everyone sees is the IP address.
 
 ### Hashcash
 
@@ -1336,7 +1377,8 @@ has six fields separated by colons:
 - `counter`: a hex number the client varies until the hash fits.
 
 The SHA-256 hash of the whole stamp string must start with at least
-`hashcash_bits` zero bits. Example: `1:20:260310:neoirc::3a2f1b`. In pseudocode:
+`hashcash_bits` zero bits. `1:20:261027:neoirc::5971e` is a real 20-bit stamp
+for 27 October 2026; its hash starts with `00000e`. In pseudocode:
 
 ```
 counter = 0
@@ -1358,9 +1400,9 @@ The server accepts a stamp when all of these hold:
 - the hash has the zero bits;
 - the stamp has not been spent.
 
-Spent stamps are kept in memory for 48 hours; a restart forgets them. The client
-sends the stamp as `pow_token` in `POST /api/v1/session`. The web client and
-`neoirc-cli` compute it on their own.
+The server keeps spent stamps in memory until their date is 48 hours old; a
+restart forgets them. The client sends the stamp as `pow_token` in
+`POST /api/v1/session`. The web client and `neoirc-cli` compute it on their own.
 
 #### Channel stamps
 
@@ -1378,22 +1420,26 @@ The stamp is bound to the channel and to the message:
 The version, `bits` and date rules of session stamps apply to channel stamps
 too, with the channel's `+H` value as the difficulty.
 
-Example:
+This message carries a real 20-bit stamp for 27 October 2026, for the `body`
+spelled exactly `["hello world"]`:
 
 ```json
 {
     "command": "PRIVMSG",
     "to": "#general",
     "body": ["hello world"],
-    "meta": { "hashcash": "1:20:260317:#general:a1b2c3...:1f4a" }
+    "meta": {
+        "hashcash": "1:20:261027:#general:d7f54e4fb4d97b407a45ce7ba369ec4cb70d15337fb33a1adfcb4f523aeb1b32:16ec2f"
+    }
 }
 ```
 
 The server checks the stamp after membership, bans and `+m`, so a message
 refused for one of those does not spend it. It then records the stamp's hash in
-the database and refuses the stamp for a year. A missing, invalid or spent stamp
-gets `ERR_CANNOTSENDTOCHAN` (`404`), with the reason in `body`. `NOTICE` needs
-no stamp. The web client and `neoirc-cli` do not compute channel stamps.
+the database and refuses the stamp for at least a year. A missing, invalid or
+spent stamp gets `ERR_CANNOTSENDTOCHAN` (`404`), with the reason in `body`.
+`NOTICE` needs no stamp. The web client and `neoirc-cli` do not compute channel
+stamps.
 
 ### Login rate limit
 
@@ -1404,9 +1450,10 @@ over the limit gets `429` `too many login attempts, try again later` with
 attempt is more than 15 minutes old. Session creation has no rate limit; the
 hashcash stamp is its cost.
 
-The IP address comes from `X-Forwarded-For` or `X-Real-IP` when present. Without
-a reverse proxy that sets those headers, a client can set them itself and so
-pick any address (see [Reverse proxy](#reverse-proxy)).
+The IP address comes from the first entry of `X-Forwarded-For`, else from
+`X-Real-IP`, else from the TCP connection. Without a reverse proxy that
+overwrites those headers, a client can set them itself and so pick any address
+(see [Reverse proxy](#reverse-proxy)).
 
 ### Writing a client
 
@@ -1440,16 +1487,22 @@ while True:
         resp = session.get(f"{BASE}/messages",
                            params={"after": last_id, "timeout": 15},
                            timeout=20)  # longer than the long-poll timeout
-        data = resp.json()
-        last_id = data.get("last_id", last_id)
-        for msg in data.get("messages", []):
-            print(f"[{msg['command']}] <{msg.get('from', '')}> "
-                  f"{' '.join(msg.get('body', []))}")
     except requests.exceptions.Timeout:
         continue
-    except Exception as exc:
+    except requests.exceptions.RequestException as exc:
         print(f"error: {exc}")
         time.sleep(2)
+        continue
+    if resp.status_code == 401:
+        break  # the session is gone
+    if resp.status_code != 200:
+        time.sleep(2)
+        continue
+    data = resp.json()
+    last_id = data["last_id"]
+    for msg in data["messages"]:
+        print(f"[{msg['command']}] <{msg.get('from', '')}> "
+              f"{' '.join(msg['body'])}")
 ```
 
 The same loop in a browser, where the cookie is sent automatically:
@@ -1464,6 +1517,10 @@ async function pollLoop() {
                 { credentials: "same-origin" },
             );
             if (resp.status === 401) break; // the session is gone
+            if (resp.status !== 200) {
+                await new Promise((r) => setTimeout(r, 2000));
+                continue;
+            }
             const data = await resp.json();
             lastId = data.last_id;
             for (const msg of data.messages) handleMessage(msg);
@@ -1474,6 +1531,9 @@ async function pollLoop() {
 }
 ```
 
+Both loops keep `after` where it was unless the answer is `200`, and stop on
+`401`.
+
 Advice for client authors:
 
 - Set the HTTP timeout above the long-poll timeout. With `timeout=15`, give the
@@ -1481,7 +1541,9 @@ Advice for client authors:
 - Keep `after` moving. Reset it to `0` only to read the queue again.
 - Expect your own messages. The server echoes a session's own `PRIVMSG` and
   `NOTICE` to all its clients. It does the same with the events of its `JOIN`,
-  `PART`, `NICK`, `TOPIC`, `MODE` and `KICK`. Show them, or drop them by `id`.
+  `PART`, `NICK`, `TOPIC`, `MODE` and `KICK`. Show them. A `PRIVMSG` or `NOTICE`
+  can instead be dropped by the `id` its `POST` response returned; the response
+  to an event carries no `id`.
 - Key a direct-message window by the other user's nick: `to` when `from` is you,
   `from` otherwise.
 - On `401`, the session is gone or the cookie is wrong. Create a new session, or
@@ -1519,9 +1581,10 @@ password of the wrong length is refused with a `NOTICE` once registration
 completes.
 
 After registration the client receives `001` to `005`, the `LUSERS` replies and
-the message of the day, or `ERR_NOMOTD` (`422`) when `MOTD` is empty. The `004`
-modes are `mnst` and the `005` tokens `CHANTYPES=#`, `NICKLEN=32`,
-`PREFIX=(ov)@+`, `CHANMODES=,,H,imnst` and `NETWORK=<server name>`.
+the message of the day, or `ERR_NOMOTD` (`422`) when that is empty. The `004`
+user modes are `ow` and its channel modes are `Himnostv`. The `005` tokens are
+`CHANTYPES=#`, `NICKLEN=32`, `PREFIX=(ov)@+`, `CHANMODES=,,H,imnst` and
+`NETWORK=<server name>`.
 
 `CAP LS` is answered with an empty capability list; other `CAP` subcommands are
 ignored.
@@ -1530,10 +1593,10 @@ When a connection has sent nothing for 90 seconds, the server sends `PING`. When
 nothing arrives in the 30 seconds after that, the server closes the connection.
 Any line, such as the client's `PONG`, starts both waits again.
 
-Closing the connection, with or without `QUIT`, ends the session, as `QUIT` does
-over the HTTP API. Its channel peers see a `QUIT` with the reason
-`Connection closed`; the reason given to `QUIT` is not relayed. Every command
-after registration counts as activity for the idle cleanup.
+Closing the connection ends the session, as `QUIT` does over the HTTP API. After
+a `QUIT`, channel peers see the reason the client gave, or `Client quit` when it
+gave none. Without a `QUIT`, they see `Connection closed`. Every command after
+registration counts as activity for the idle cleanup.
 
 ### Commands
 
@@ -1572,6 +1635,11 @@ They behave as over the HTTP API, with the IRC syntax and these differences:
   end reply.
 - `NICK` without a nick gets `ERR_NONICKNAMEGIVEN` (`431`).
 - `KICK` without a reason uses the kicked user's nick as the reason.
+- `MOTD` sends only `375` to `376`, or `ERR_NOMOTD` (`422`) when the message of
+  the day is empty, without the welcome and `LUSERS` replies.
+- `PASS` after registration answers with a `NOTICE` when it stores the password.
+  A password of the wrong length also gets a `NOTICE`, not `ERR_NEEDMOREPARAMS`
+  (`461`).
 
 ### What IRC clients see
 
@@ -1580,8 +1648,9 @@ Each line of a multi-line `body` reaches an IRC client as its own `PRIVMSG` or
 appear with the prefix `nick!nick@*`. A mode change made over the HTTP API
 arrives as an IRC `MODE` line with each value as its own parameter, such as
 `MODE #general +k secretkey`. An `INVITE` arrives as
-`:alice!alice@* INVITE bob #general`. Numeric replies, `KICK`, `TOPIC`, `NICK`,
-`QUIT` (as `Quit: <reason>`) and `WALLOPS` arrive in their IRC forms.
+`:alice!alice@* INVITE bob #general`. Numeric replies, `JOIN`, `PART`, `KICK`,
+`TOPIC`, `NICK`, `QUIT` (as `Quit: <reason>`) and `WALLOPS` arrive in their IRC
+forms.
 
 The listener does not queue a client's own commands back to it. It sends the
 echo itself, as IRC does, and for `PRIVMSG` and `NOTICE` sends none. Other
@@ -1628,14 +1697,14 @@ It starts disconnected. Commands start with `/`:
 - `/quit`: send `QUIT` and exit. `/help`: the command list.
 
 Text without a `/` goes as a `PRIVMSG` to the current target. `/join` and
-`/query` set the target to the channel or user they open. `/window` and `/w` set
-it to the channel or user of the window they switch to; a switch to window `0`
-leaves it as it was. Alt and a digit switches the window shown and leaves the
-target as it was. `/part` of the target's channel clears it.
+`/query` set the target to the channel or user they open. `/window`, `/w` and
+Alt with a digit set it to the channel or user of the window they switch to. A
+switch to window `0` clears it, and so does `/part` of the target's channel.
 
 The client reads its queue with `timeout=15` and retries after two seconds on an
 error. It sends no hashcash stamps for `+H` channels. It sends the auth cookie
-to a server on `localhost` over plain HTTP, and otherwise only over HTTPS.
+over plain HTTP to a server on `localhost` or a loopback address such as
+`127.0.0.1`, and otherwise only over HTTPS.
 
 ## Running the server
 
@@ -1643,12 +1712,15 @@ to a server on `localhost` over plain HTTP, and otherwise only over HTTPS.
 
 Every setting is an environment variable. The server also reads a `.env` file in
 its working directory, and a YAML file `neoirc.yaml` in `/etc/neoirc/` or
-`$HOME/.config/neoirc/` with the same names as keys. An environment variable
-wins over the file. An environment variable set to the empty string counts as
-unset, except `IRC_LISTEN_ADDR`, where the empty string turns the IRC listener
-off. A `neoirc.yaml` that is not valid YAML stops the server at startup.
+`$HOME/.config/neoirc/` with the same names as keys. A variable from the
+environment wins over one in `.env`, and both win over `neoirc.yaml`. An
+environment variable set to the empty string counts as unset, except
+`IRC_LISTEN_ADDR`, where the empty string turns the IRC listener off. A
+`neoirc.yaml` that is not valid YAML stops the server at startup. A setting that
+does not parse or is out of range also stops the server at startup, and the
+error names the setting.
 
-- `PORT` (default `8080`): the HTTP port.
+- `PORT` (default `8080`): the HTTP port. `0` lets the system pick a free port.
 - `IRC_LISTEN_ADDR` (default `:6667`): the address of the IRC listener. The
   empty string turns the listener off.
 - `DBURL` (default
@@ -1662,27 +1734,30 @@ off. A `neoirc.yaml` that is not valid YAML stops the server at startup.
   hashcash resource use `neoirc`, and `GET /api/v1/server` returns an empty
   string.
 - `MOTD` (default: a built-in banner): the message of the day. Lines are
-  separated by newlines.
+  separated by newlines. An empty environment variable counts as unset and gives
+  the banner. To send no message of the day, put `MOTD: ""` in `neoirc.yaml`.
 - `NEOIRC_HASHCASH_BITS` (default `20`): the difficulty of the stamp
   `POST /api/v1/session` needs. `0` turns the requirement off.
 - `NEOIRC_OPER_NAME` and `NEOIRC_OPER_PASSWORD` (default empty): the name and
   password `OPER` accepts. `OPER` fails while either is empty.
 - `MAX_MESSAGE_SIZE` (default `4096`): the largest request body, in bytes, for
-  `POST /api/v1/session`, `POST /api/v1/login` and `POST /api/v1/messages`.
-- `LOGIN_RATE_LIMIT` (default `1`) and `LOGIN_RATE_BURST` (default `5`): login
-  attempts allowed per second per IP address, and the burst above that rate. A
-  value of `0` or less means the default.
-- `SESSION_IDLE_TIMEOUT` (default `720h`, 30 days): a Go duration such as `720h`
-  or `24h`. A client with no request for this long is removed, and a session
-  left with no client ends. See [Data lifecycle](#data-lifecycle). A value that
-  is not a duration is logged, and the default applies.
-- `MESSAGE_MAX_AGE` (default `720h`): messages older than this are deleted. A
-  value that is not a duration is logged, and no message is deleted.
-- `QUEUE_MAX_AGE` (default `720h`): queue entries older than this are deleted. A
-  value that is not a duration is logged, and no entry is deleted.
+  `POST /api/v1/session`, `POST /api/v1/login` and `POST /api/v1/messages`. It
+  must be at least `1`.
+- `LOGIN_RATE_LIMIT` (default `1`): login attempts allowed per second per IP
+  address. A fraction such as `0.5` is allowed. It must be above `0`.
+- `LOGIN_RATE_BURST` (default `5`): how many attempts an address may make at
+  once before the rate applies. It must be at least `1`.
+- `SESSION_IDLE_TIMEOUT` (default `720h`, 30 days): a duration with a unit, `h`
+  for hours, `m` for minutes or `s` for seconds, such as `720h` or `36h30m`. A
+  client with no request for this long is removed, and a session left with no
+  client ends. See [Data lifecycle](#data-lifecycle). It must be above zero.
+- `MESSAGE_MAX_AGE` (default `720h`): messages older than this duration are
+  deleted. It must be above zero.
+- `QUEUE_MAX_AGE` (default `720h`): queue entries older than this duration are
+  deleted. It must be above zero.
 - `DEBUG` (default `false`): `true` turns on debug logging.
 - `SENTRY_DSN` (default empty): when set, panics in HTTP requests are reported
-  to Sentry.
+  to Sentry. A value that is not a valid DSN stops the server at startup.
 - `METRICS_USERNAME` and `METRICS_PASSWORD` (default empty): the HTTP basic auth
   credentials of `GET /metrics`. The endpoint exists only when
   `METRICS_USERNAME` is set.
@@ -1702,7 +1777,8 @@ NEOIRC_HASHCASH_BITS=20
 
 ### Docker
 
-`make docker` builds the image, tagged `neoirc`. The image:
+`make docker` builds the image, tagged `neoirc`. The build runs the tests and
+the linter first and stops when either fails. The image:
 
 - is Alpine with the `neoircd` binary and CA certificates;
 - runs as the user `neoirc`;
@@ -1728,10 +1804,11 @@ Run the server behind a reverse proxy that terminates TLS. The server itself
 speaks plain HTTP, and the auth cookie is `Secure`, so browsers send it only
 over HTTPS. The proxy must:
 
-- Set `X-Forwarded-For` or `X-Real-IP` to the client's address, replacing any
-  value the client sent. The server trusts these headers from anyone. Without a
-  proxy that overwrites them, a client can choose its own address, which sets
-  its hostname and lets it dodge the login rate limit.
+- Set `X-Forwarded-For` to the client's address, replacing any value the client
+  sent. The server reads that header first and trusts it from anyone; it reads
+  `X-Real-IP` only when `X-Forwarded-For` is absent. Without a proxy that
+  overwrites the header, a client can choose its own address, which sets its
+  hostname and lets it dodge the login rate limit.
 - Wait at least 60 seconds for a response. A long poll can take 30 seconds, and
   the server's own write timeout is 60 seconds.
 
@@ -1768,8 +1845,8 @@ The IRC listener has no TLS.
 ### Limits and headers
 
 - The server reads a request within 10 seconds and writes a response within 60
-  seconds. A request is cancelled after 60 seconds and gets `504` with no body.
-  Headers may be up to 1 MiB.
+  seconds. A request still running after 60 seconds is cancelled, and the
+  connection closes without a response. Headers may be up to 1 MiB.
 - A long poll waits at most 30 seconds.
 - Every response to a well-formed request, except to a cross-origin preflight,
   carries a `Content-Security-Policy` header:
@@ -1784,16 +1861,16 @@ The IRC listener has no TLS.
 
 The server logs with Go's `slog`, one line per event, to standard output. The
 lines are JSON, or plain text when standard output is a terminal. Every HTTP
-request is logged with its method, URL, status, latency, remote address, user
-agent and request ID. `DEBUG=true` adds debug-level lines.
+request is logged with its method, URL, protocol, status, latency, remote
+address, user agent, referrer and request ID. `DEBUG=true` adds debug-level
+lines.
 
 ### The database
 
 The server stores everything in one SQLite database, through the pure Go driver
 `modernc.org/sqlite`. It uses one database connection, so reads and writes take
-turns. On startup it creates the tables from
-`internal/db/schema/001_initial.sql` if they do not exist, and records the
-schema version in `schema_migrations`.
+turns. On its first start it runs `internal/db/schema/001_initial.sql`, which
+creates the tables, and records that in `schema_migrations`.
 
 The tables:
 
@@ -1893,15 +1970,16 @@ standard. Each script has a `make` target of the same name, except
 `script/install-precommit`, which is `make hooks`, and `script/cibuild`,
 `script/precommit` and `script/projectname`, which have none.
 
-- `script/bootstrap`: installs what development needs: `make`, `git`, Node and
-  `yarn` (for prettier) and Go.
+- `script/bootstrap`: installs `make`, `git`, Go, Node and `yarn`, and
+  `prettier` through `yarn`. Docker must already be installed.
 - `script/setup`: makes a fresh clone ready: runs `script/bootstrap`, then
   `script/install-precommit`.
 - `script/test`: builds the `Dockerfile`'s `test` stage, which runs the tests
   with `-race`.
 - `script/lint`: builds the `Dockerfile`'s `lint` stage, which runs
-  golangci-lint.
-- `script/fmt`: formats the Go code with `gofmt` and the Markdown with prettier.
+  `golangci-lint`.
+- `script/fmt`: formats the Go code with `gofmt` and the Markdown with
+  `prettier`.
 - `script/fmt-check`: the same, read-only; fails if anything would change.
 - `script/check`: runs `script/test`, `script/lint` and `script/fmt-check`.
 - `script/docker`: builds the image, tagged `neoirc`.
@@ -1919,7 +1997,9 @@ standard. Each script has a `make` target of the same name, except
   `/`. To include the web client, build it first: in `web/`, run
   `yarn install --frozen-lockfile` and `sh build.sh`.
 - `make run`: builds and starts the server. `make debug` does the same with
-  `DEBUG=1`.
+  `DEBUG=1`. With the default `DBURL`, both stop at startup when
+  `/var/lib/neoirc/` does not exist or is not writable. Set `DBURL` to a
+  writable path to avoid that.
 - `make clean`: removes `bin/`.
 - `make check`: runs `script/check`. `make test`, `make lint`, `make fmt` and
   `make fmt-check` run the script of the same name.
@@ -1931,8 +2011,8 @@ standard. Each script has a `make` target of the same name, except
 The tests and the linter run inside Docker, as stages of the `Dockerfile`, so
 every developer and the CI run the same toolchain. `make test` builds the `test`
 stage: `go test -race` over every package, with a 90-second limit. `make lint`
-builds the `lint` stage, which runs golangci-lint with the shared
-`.golangci.yml`. `make fmt-check` runs `gofmt` and prettier on the host. Tests
+builds the `lint` stage, which runs `golangci-lint` with the shared
+`.golangci.yml`. `make fmt-check` runs `gofmt` and `prettier` on the host. Tests
 live next to the code, most in `_test` packages. A test that needs a database
 gets an in-memory one of its own from `internal/dbtest`, which holds a second
 connection open to keep it.
@@ -1940,9 +2020,9 @@ connection open to keep it.
 The `Dockerfile` has five stages:
 
 1. `web-builder`: installs the web client's Node dependencies and bundles
-   `web/src/app.jsx` with esbuild into `web/dist/`.
-2. `lint`: runs golangci-lint, with placeholder files in `web/dist/` so that it
-   does not wait for the web build.
+   `web/src/app.jsx` with `esbuild` into `web/dist/`.
+2. `lint`: runs `golangci-lint`, with placeholder files in `web/dist/` so that
+   it does not wait for the web build.
 3. `test`: runs the tests, with the same placeholders.
 4. `builder`: runs only after `lint` and `test` have passed. It compiles
    `neoircd` with the real web client, and compiles `neoirc-cli` to check that

internal/cli/app.go

@@ -34,13 +34,30 @@ type App struct {
 
 // Run creates and runs the CLI application.
 func 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:   NewUI(),
+		ui:   ui,
 		nick: "guest",
 	}
 
 	app.ui.OnInput(app.handleInput)
-	app.ui.SetStatus(app.nick, "", "disconnected")
+
+	// 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",
@@ -50,12 +67,9 @@ func Run() {
 				"[white] to begin, " +
 				"or [yellow]/help[white] for commands",
 		)
+	}()
 
-	err := app.ui.Run()
-	if err != nil {
-		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
-		os.Exit(1)
-	}
+	return app.ui.Run()
 }
 
 func (a *App) handleInput(text string) {
@@ -94,7 +108,7 @@ func (a *App) handleInput(text string) {
 	})
 	if err != nil {
 		a.ui.AddStatus(
-			"[red]Send error: " + err.Error(),
+			"[red]Send error: " + escape(err.Error()),
 		)
 	}
 }
@@ -152,7 +166,7 @@ func (a *App) dispatchInfoCommand(cmd, args string) {
 		a.cmdWhois(args)
 	default:
 		a.ui.AddStatus(
-			"[red]Unknown command: " + cmd,
+			"[red]Unknown command: " + escape(cmd),
 		)
 	}
 }
@@ -168,7 +182,7 @@ func (a *App) cmdConnect(serverURL string) {
 
 	serverURL = strings.TrimRight(serverURL, "/")
 
-	a.ui.AddStatus("Connecting to " + serverURL + "...")
+	a.ui.AddStatus("Connecting to " + escape(serverURL) + "...")
 
 	a.mu.Lock()
 	nick := a.nick
@@ -178,29 +192,37 @@ func (a *App) cmdConnect(serverURL string) {
 
 	resp, err := client.CreateSession(nick)
 	if err != nil {
-		a.ui.AddStatus(fmt.Sprintf(
-			"[red]Connection failed: %v", err,
-		))
+		a.ui.AddStatus(
+			"[red]Connection failed: " + escape(err.Error()),
+		)
 
 		return
 	}
 
+	// The poll loop of an earlier connection is stopped in the same
+	// step that replaces the client, so it never polls with the new
+	// one.
 	a.mu.Lock()
 	a.client = client
 	a.nick = resp.Nick
 	a.connected = true
 	a.lastQID = 0
+
+	if a.stopPoll != nil {
+		close(a.stopPoll)
+	}
+
+	stop := make(chan struct{})
+	a.stopPoll = stop
 	a.mu.Unlock()
 
 	a.ui.AddStatus(fmt.Sprintf(
 		"[green]Connected! Nick: %s, Session: %d",
-		resp.Nick, resp.ID,
+		escape(resp.Nick), resp.ID,
 	))
 	a.ui.SetStatus(resp.Nick, "", "connected")
 
-	a.stopPoll = make(chan struct{})
-
-	go a.pollLoop()
+	go a.pollLoop(stop)
 }
 
 func (a *App) cmdNick(nick string) {
@@ -222,7 +244,7 @@ func (a *App) cmdNick(nick string) {
 		a.mu.Unlock()
 
 		a.ui.AddStatus(
-			"Nick set to " + nick +
+			"Nick set to " + escape(nick) +
 				" (will be used on connect)",
 		)
 
@@ -234,9 +256,9 @@ func (a *App) cmdNick(nick string) {
 		Body:    []string{nick},
 	})
 	if err != nil {
-		a.ui.AddStatus(fmt.Sprintf(
-			"[red]Nick change failed: %v", err,
-		))
+		a.ui.AddStatus(
+			"[red]Nick change failed: " + escape(err.Error()),
+		)
 
 		return
 	}
@@ -247,7 +269,7 @@ func (a *App) cmdNick(nick string) {
 	a.mu.Unlock()
 
 	a.ui.SetStatus(nick, target, "connected")
-	a.ui.AddStatus("Nick changed to " + nick)
+	a.ui.AddStatus("Nick changed to " + escape(nick))
 }
 
 func (a *App) cmdJoin(channel string) {
@@ -275,9 +297,9 @@ func (a *App) cmdJoin(channel string) {
 
 	err := a.client.JoinChannel(channel)
 	if err != nil {
-		a.ui.AddStatus(fmt.Sprintf(
-			"[red]Join failed: %v", err,
-		))
+		a.ui.AddStatus(
+			"[red]Join failed: " + escape(err.Error()),
+		)
 
 		return
 	}
@@ -315,9 +337,9 @@ func (a *App) cmdPart(channel string) {
 
 	err := a.client.PartChannel(channel)
 	if err != nil {
-		a.ui.AddStatus(fmt.Sprintf(
-			"[red]Part failed: %v", err,
-		))
+		a.ui.AddStatus(
+			"[red]Part failed: " + escape(err.Error()),
+		)
 
 		return
 	}
@@ -362,9 +384,9 @@ func (a *App) cmdMsg(args string) {
 		Body:    []string{text},
 	})
 	if err != nil {
-		a.ui.AddStatus(fmt.Sprintf(
-			"[red]Send failed: %v", err,
-		))
+		a.ui.AddStatus(
+			"[red]Send failed: " + escape(err.Error()),
+		)
 	}
 }
 
@@ -380,10 +402,16 @@ func (a *App) cmdQuery(nick string) {
 	a.mu.Lock()
 	a.target = nick
 	myNick := a.nick
+	connected := a.connected
 	a.mu.Unlock()
 
+	connStatus := "disconnected"
+	if connected {
+		connStatus = "connected"
+	}
+
 	a.ui.SwitchToBuffer(nick)
-	a.ui.SetStatus(myNick, nick, "connected")
+	a.ui.SetStatus(myNick, nick, connStatus)
 }
 
 func (a *App) cmdTopic(args string) {
@@ -417,9 +445,9 @@ func (a *App) cmdTopic(args string) {
 		Body:    []string{args},
 	})
 	if err != nil {
-		a.ui.AddStatus(fmt.Sprintf(
-			"[red]Topic set failed: %v", err,
-		))
+		a.ui.AddStatus(
+			"[red]Topic set failed: " + escape(err.Error()),
+		)
 	}
 }
 
@@ -443,9 +471,9 @@ func (a *App) cmdNames() {
 
 	members, err := a.client.GetMembers(target)
 	if err != nil {
-		a.ui.AddStatus(fmt.Sprintf(
-			"[red]Names failed: %v", err,
-		))
+		a.ui.AddStatus(
+			"[red]Names failed: " + escape(err.Error()),
+		)
 
 		return
 	}
@@ -458,7 +486,7 @@ func (a *App) cmdNames() {
 
 	a.ui.AddLine(target, fmt.Sprintf(
 		"[cyan]*** Members of %s: %s",
-		target, strings.Join(nicks, " "),
+		escape(target), escape(strings.Join(nicks, " ")),
 	))
 }
 
@@ -489,9 +517,9 @@ func (a *App) cmdList() {
 
 	channels, err := a.client.ListChannels()
 	if err != nil {
-		a.ui.AddStatus(fmt.Sprintf(
-			"[red]List failed: %v", err,
-		))
+		a.ui.AddStatus(
+			"[red]List failed: " + escape(err.Error()),
+		)
 
 		return
 	}
@@ -500,7 +528,7 @@ func (a *App) cmdList() {
 
 	for _, ch := range channels {
 		a.ui.AddStatus(fmt.Sprintf(
-			"  %s %s", ch.Name, ch.Topic,
+			"  %s %s", escape(ch.Name), escape(ch.Topic),
 		))
 	}
 
@@ -522,9 +550,9 @@ func (a *App) cmdMotd() {
 		&api.Message{Command: irc.CmdMotd}, //nolint:exhaustruct
 	)
 	if err != nil {
-		a.ui.AddStatus(fmt.Sprintf(
-			"[red]MOTD failed: %v", err,
-		))
+		a.ui.AddStatus(
+			"[red]MOTD failed: " + escape(err.Error()),
+		)
 	}
 }
 
@@ -560,9 +588,9 @@ func (a *App) cmdWho(args string) {
 		},
 	)
 	if err != nil {
-		a.ui.AddStatus(fmt.Sprintf(
-			"[red]WHO failed: %v", err,
-		))
+		a.ui.AddStatus(
+			"[red]WHO failed: " + escape(err.Error()),
+		)
 	}
 }
 
@@ -591,9 +619,9 @@ func (a *App) cmdWhois(args string) {
 		},
 	)
 	if err != nil {
-		a.ui.AddStatus(fmt.Sprintf(
-			"[red]WHOIS failed: %v", err,
-		))
+		a.ui.AddStatus(
+			"[red]WHOIS failed: " + escape(err.Error()),
+		)
 	}
 }
 
@@ -610,24 +638,37 @@ func (a *App) cmdWindow(args string) {
 
 	_, _ = fmt.Sscanf(args, "%d", &bufIndex)
 
-	a.ui.SwitchBuffer(bufIndex)
-
 	a.mu.Lock()
 	nick := a.nick
+	connected := a.connected
 	a.mu.Unlock()
 
-	if bufIndex >= 0 && bufIndex < a.ui.BufferCount() {
-		buf := a.ui.buffers[bufIndex]
-		if buf.Name != "(status)" {
+	connStatus := "disconnected"
+	if connected {
+		connStatus = "connected"
+	}
+
+	// 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, connStatus,
 			)
 		} else {
-			a.ui.SetStatus(nick, "", "connected")
+			a.mu.Lock()
+			a.target = ""
+			a.mu.Unlock()
+
+			a.ui.SetStatus(nick, "", connStatus)
 		}
 	}
 }
@@ -675,16 +716,23 @@ func (a *App) cmdHelp() {
 	}
 }
 
-// pollLoop long-polls for messages in the background.
-func (a *App) pollLoop() {
+// pollLoop long-polls for messages in the background until stop is
+// closed. A later /connect closes stop under a.mu as it replaces the
+// client and the cursor, so the loop checks stop under a.mu too. A
+// stopped loop then neither polls with the new client nor moves the
+// new cursor.
+func (a *App) pollLoop(stop <-chan struct{}) {
 	for {
+		a.mu.Lock()
+
 		select {
-		case <-a.stopPoll:
+		case <-stop:
+			a.mu.Unlock()
+
 			return
 		default:
 		}
 
-		a.mu.Lock()
 		client := a.client
 		lastQID := a.lastQID
 		a.mu.Unlock()
@@ -702,12 +750,24 @@ func (a *App) pollLoop() {
 			continue
 		}
 
-		if result.LastID > 0 {
+		// A poll sent before stop was closed answers for the earlier
+		// connection.
 		a.mu.Lock()
-			a.lastQID = result.LastID
+
+		select {
+		case <-stop:
 			a.mu.Unlock()
+
+			return
+		default:
 		}
 
+		if result.LastID > 0 {
+			a.lastQID = result.LastID
+		}
+
+		a.mu.Unlock()
+
 		for i := range result.Messages {
 			a.handleServerMessage(&result.Messages[i])
 		}
@@ -764,7 +824,7 @@ func (a *App) handlePrivmsgEvent(
 
 	a.ui.AddLine(target, fmt.Sprintf(
 		"[gray]%s [green]<%s>[white] %s",
-		timestamp, msg.From, text,
+		timestamp, escape(msg.From), escape(text),
 	))
 }
 
@@ -777,7 +837,7 @@ func (a *App) handleJoinEvent(
 
 	a.ui.AddLine(msg.To, fmt.Sprintf(
 		"[gray]%s [yellow]*** %s has joined %s",
-		timestamp, msg.From, msg.To,
+		timestamp, escape(msg.From), escape(msg.To),
 	))
 }
 
@@ -796,11 +856,11 @@ func (a *App) handlePartEvent(
 
 	line := fmt.Sprintf(
 		"[gray]%s [yellow]*** %s has left %s",
-		timestamp, msg.From, msg.To,
+		timestamp, escape(msg.From), escape(msg.To),
 	)
 
 	if reason != "" {
-		line += " (" + reason + ")"
+		line += " (" + escape(reason) + ")"
 	}
 
 	if msg.From == myNick {
@@ -821,12 +881,12 @@ func (a *App) handleQuitEvent(
 	if reason != "" {
 		a.ui.AddStatus(fmt.Sprintf(
 			"[gray]%s [yellow]*** %s has quit (%s)",
-			timestamp, msg.From, reason,
+			timestamp, escape(msg.From), escape(reason),
 		))
 	} else {
 		a.ui.AddStatus(fmt.Sprintf(
 			"[gray]%s [yellow]*** %s has quit",
-			timestamp, msg.From,
+			timestamp, escape(msg.From),
 		))
 	}
 }
@@ -853,7 +913,7 @@ func (a *App) handleNickEvent(
 
 	a.ui.AddStatus(fmt.Sprintf(
 		"[gray]%s [yellow]*** %s is now known as %s",
-		timestamp, msg.From, newNick,
+		timestamp, escape(msg.From), escape(newNick),
 	))
 }
 
@@ -865,7 +925,7 @@ func (a *App) handleNoticeEvent(
 
 	a.ui.AddStatus(fmt.Sprintf(
 		"[gray]%s [magenta]--%s-- %s",
-		timestamp, msg.From, text,
+		timestamp, escape(msg.From), escape(text),
 	))
 }
 
@@ -881,7 +941,7 @@ func (a *App) handleTopicEvent(
 
 	a.ui.AddLine(msg.To, fmt.Sprintf(
 		"[gray]%s [cyan]*** %s set topic: %s",
-		timestamp, msg.From, text,
+		timestamp, escape(msg.From), escape(text),
 	))
 }
 
@@ -891,10 +951,12 @@ func (a *App) handleDefaultEvent(
 	lines := msg.BodyLines()
 	text := strings.Join(lines, " ")
 
+	// The brackets around the command are escaped with it, as tview
+	// reads a command such as "[MODE]" as a tag.
 	if text != "" {
 		a.ui.AddStatus(fmt.Sprintf(
-			"[gray]%s [white][%s] %s",
-			timestamp, msg.Command, text,
+			"[gray]%s [white]%s %s",
+			timestamp, escape("["+msg.Command+"]"), escape(text),
 		))
 	}
 }

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
@@ -27,7 +30,17 @@ type UI struct {
 	buffers       []*Buffer
 	currentBuffer int
 
+	// The nick, target and connection state last passed to
+	// SetStatus.
+	nick       string
+	target     string
+	connStatus string
+
 	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.
@@ -172,13 +185,32 @@ func (ui *UI) SetStatus(
 	nick, target, connStatus string,
 ) {
 	ui.app.QueueUpdateDraw(func() {
-		ui.renderStatusBar(nick, target, connStatus)
+		ui.nick = nick
+		ui.target = target
+		ui.connStatus = connStatus
+
+		ui.refreshStatusBar()
 	})
 }
 
-// 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.
@@ -203,9 +235,21 @@ func (ui *UI) initMessages() {
 	ui.messages.SetBorder(false)
 }
 
+// escape returns text so that the message window shows it exactly
+// as written. It writes each "[" as "[[:]": a "[" followed by
+// another "[" never starts a tag, and the tag "[:]" changes
+// nothing. tview.Escape is not enough: it does not escape a bracket
+// pair holding a symbol such as "|" or "^", and nothing it adds
+// stops a tag with a URL, such as "[:::y|z]".
+func escape(text string) string {
+	return strings.ReplaceAll(text, "[", "[[:]")
+}
+
 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 +270,7 @@ func (ui *UI) initInput() {
 		}
 
 		ui.input.SetText("")
-
-		if ui.onInput != nil {
-			ui.onInput(text)
-		}
+		ui.callOnInput(text)
 	})
 }
 
@@ -240,10 +281,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,8 +295,35 @@ 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)
+	}()
+}
+
+// refreshStatusBar redraws the status bar with the nick, target
+// and connection state last passed to SetStatus.
 func (ui *UI) refreshStatusBar() {
-	// Placeholder; full refresh needs nick/target context.
+	ui.renderStatusBar(ui.nick, ui.target, ui.connStatus)
 }
 
 func (ui *UI) renderStatusBar(

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

@@ -10,13 +10,6 @@ import (
 	"golang.org/x/crypto/bcrypt"
 )
 
-//nolint:gochecknoglobals // var so tests can override via SetBcryptCost
-var bcryptCost = bcrypt.DefaultCost
-
-// SetBcryptCost overrides the bcrypt cost.
-// Use bcrypt.MinCost in tests to avoid slow hashing.
-func SetBcryptCost(cost int) { bcryptCost = cost }
-
 var errNoPassword = errors.New(
 	"account has no password set",
 )
@@ -29,7 +22,7 @@ func (database *Database) SetPassword(
 	password string,
 ) error {
 	hash, err := bcrypt.GenerateFromPassword(
-		[]byte(password), bcryptCost,
+		[]byte(password), bcrypt.DefaultCost,
 	)
 	if err != nil {
 		return fmt.Errorf("hash password: %w", err)

internal/db/db.go

@@ -85,11 +85,6 @@ func New(
 	return database, nil
 }
 
-// GetDB returns the underlying sql.DB connection.
-func (database *Database) GetDB() *sql.DB {
-	return database.conn
-}
-
 func (database *Database) connect(ctx context.Context) error {
 	dbURL := database.params.Config.DBURL
 	if dbURL == "" {

internal/db/export_test.go

@@ -6,6 +6,7 @@ import (
 	"fmt"
 	"log/slog"
 	"testing"
+	"time"
 
 	"sneak.berlin/go/neoirc/internal/dbtest"
 )
@@ -67,3 +68,78 @@ func (database *Database) ExecForTest(
 
 	return nil
 }
+
+// GetDB returns the underlying sql.DB connection.
+func (database *Database) GetDB() *sql.DB {
+	return database.conn
+}
+
+// GetOrCreateChannel returns channel id, creating if needed.
+// Uses INSERT OR IGNORE to avoid TOCTOU races.
+func (database *Database) GetOrCreateChannel(
+	ctx context.Context,
+	name string,
+) (int64, error) {
+	now := time.Now()
+
+	_, err := database.conn.ExecContext(ctx,
+		`INSERT OR IGNORE INTO channels
+		 (name, created_at, updated_at)
+		 VALUES (?, ?, ?)`,
+		name, now, now)
+	if err != nil {
+		return 0, fmt.Errorf("create channel: %w", err)
+	}
+
+	var channelID int64
+
+	err = database.conn.QueryRowContext(
+		ctx,
+		"SELECT id FROM channels WHERE name = ?",
+		name,
+	).Scan(&channelID)
+	if err != nil {
+		return 0, fmt.Errorf("get channel: %w", err)
+	}
+
+	return channelID, nil
+}
+
+// JoinChannel adds a session to a channel.
+func (database *Database) JoinChannel(
+	ctx context.Context,
+	channelID, sessionID int64,
+) error {
+	_, err := database.conn.ExecContext(ctx,
+		`INSERT OR IGNORE INTO channel_members
+		 (channel_id, session_id, joined_at)
+		 VALUES (?, ?, ?)`,
+		channelID, sessionID, time.Now())
+	if err != nil {
+		return fmt.Errorf("join channel: %w", err)
+	}
+
+	return nil
+}
+
+// HasChannelInvite checks if a session has been invited
+// to a channel.
+func (database *Database) HasChannelInvite(
+	ctx context.Context,
+	channelID, sessionID int64,
+) (bool, error) {
+	var count int
+
+	err := database.conn.QueryRowContext(ctx,
+		`SELECT COUNT(*) FROM channel_invites
+		 WHERE channel_id = ? AND session_id = ?`,
+		channelID, sessionID,
+	).Scan(&count)
+	if err != nil {
+		return false, fmt.Errorf(
+			"check invite: %w", err,
+		)
+	}
+
+	return count > 0, nil
+}

internal/db/main_test.go

@@ -1,14 +0,0 @@
-package db_test
-
-import (
-	"os"
-	"testing"
-
-	"golang.org/x/crypto/bcrypt"
-	"sneak.berlin/go/neoirc/internal/db"
-)
-
-func TestMain(m *testing.M) {
-	db.SetBcryptCost(bcrypt.MinCost)
-	os.Exit(m.Run())
-}

internal/db/queries.go

@@ -320,29 +320,6 @@ type ClientHostInfo struct {
 	Hostname string
 }
 
-// GetClientHostInfo returns the IP and hostname for a
-// client.
-func (database *Database) GetClientHostInfo(
-	ctx context.Context,
-	clientID int64,
-) (*ClientHostInfo, error) {
-	var info ClientHostInfo
-
-	err := database.conn.QueryRowContext(
-		ctx,
-		`SELECT ip, hostname
-		 FROM clients WHERE id = ?`,
-		clientID,
-	).Scan(&info.IP, &info.Hostname)
-	if err != nil {
-		return nil, fmt.Errorf(
-			"get client host info: %w", err,
-		)
-	}
-
-	return &info, nil
-}
-
 // SetSessionOper sets the is_oper flag on a session.
 func (database *Database) SetSessionOper(
 	ctx context.Context,
@@ -433,54 +410,6 @@ func (database *Database) GetChannelByName(
 	return channelID, nil
 }
 
-// GetOrCreateChannel returns channel id, creating if needed.
-// Uses INSERT OR IGNORE to avoid TOCTOU races.
-func (database *Database) GetOrCreateChannel(
-	ctx context.Context,
-	name string,
-) (int64, error) {
-	now := time.Now()
-
-	_, err := database.conn.ExecContext(ctx,
-		`INSERT OR IGNORE INTO channels
-		 (name, created_at, updated_at)
-		 VALUES (?, ?, ?)`,
-		name, now, now)
-	if err != nil {
-		return 0, fmt.Errorf("create channel: %w", err)
-	}
-
-	var channelID int64
-
-	err = database.conn.QueryRowContext(
-		ctx,
-		"SELECT id FROM channels WHERE name = ?",
-		name,
-	).Scan(&channelID)
-	if err != nil {
-		return 0, fmt.Errorf("get channel: %w", err)
-	}
-
-	return channelID, nil
-}
-
-// JoinChannel adds a session to a channel.
-func (database *Database) JoinChannel(
-	ctx context.Context,
-	channelID, sessionID int64,
-) error {
-	_, err := database.conn.ExecContext(ctx,
-		`INSERT OR IGNORE INTO channel_members
-		 (channel_id, session_id, joined_at)
-		 VALUES (?, ?, ?)`,
-		channelID, sessionID, time.Now())
-	if err != nil {
-		return fmt.Errorf("join channel: %w", err)
-	}
-
-	return nil
-}
-
 // Errors that CreateOrJoinChannel refuses a join with.
 var (
 	ErrBannedFromChannel = errors.New("banned from channel")
@@ -1127,23 +1056,6 @@ func (database *Database) GetChannelMemberIDs(
 	return scanInt64s(rows)
 }
 
-// GetSessionChannelIDs returns channel IDs for a session.
-func (database *Database) GetSessionChannelIDs(
-	ctx context.Context,
-	sessionID int64,
-) ([]int64, error) {
-	rows, err := database.conn.QueryContext(ctx,
-		`SELECT channel_id FROM channel_members
-		 WHERE session_id = ?`, sessionID)
-	if err != nil {
-		return nil, fmt.Errorf(
-			"get session channel ids: %w", err,
-		)
-	}
-
-	return scanInt64s(rows)
-}
-
 // InsertMessage stores a message and returns its DB ID.
 // toSessionID is the session a DM or INVITE is sent to and
 // toChannelID the channel a channel message is sent to;
@@ -2460,28 +2372,6 @@ func (database *Database) AddChannelInvite(
 	return nil
 }
 
-// HasChannelInvite checks if a session has been invited
-// to a channel.
-func (database *Database) HasChannelInvite(
-	ctx context.Context,
-	channelID, sessionID int64,
-) (bool, error) {
-	var count int
-
-	err := database.conn.QueryRowContext(ctx,
-		`SELECT COUNT(*) FROM channel_invites
-		 WHERE channel_id = ? AND session_id = ?`,
-		channelID, sessionID,
-	).Scan(&count)
-	if err != nil {
-		return false, fmt.Errorf(
-			"check invite: %w", err,
-		)
-	}
-
-	return count > 0, nil
-}
-
 // --- Tier 2: Secret (+s) ---
 
 // IsChannelSecret checks if a channel has +s mode.

internal/db/queries_test.go

@@ -125,7 +125,7 @@ func TestCreateSessionStoresIP(t *testing.T) {
 	database := setupTestDB(t)
 	ctx := t.Context()
 
-	sessionID, clientID, _, err := database.CreateSession(
+	sessionID, _, _, err := database.CreateSession(
 		ctx, "ipuser", "ident", "host.example.com",
 		"192.168.1.42",
 	)
@@ -147,8 +147,8 @@ func TestCreateSessionStoresIP(t *testing.T) {
 		)
 	}
 
-	clientInfo, err := database.GetClientHostInfo(
-		ctx, clientID,
+	clientInfo, err := database.GetLatestClientForSession(
+		ctx, sessionID,
 	)
 	if err != nil {
 		t.Fatal(err)
@@ -169,19 +169,6 @@ func TestCreateSessionStoresIP(t *testing.T) {
 	}
 }
 
-func TestGetClientHostInfoNotFound(t *testing.T) {
-	t.Parallel()
-
-	database := setupTestDB(t)
-
-	_, err := database.GetClientHostInfo(
-		t.Context(), 99999,
-	)
-	if err == nil {
-		t.Fatal("expected error for nonexistent client")
-	}
-}
-
 func TestGetSessionHostInfoNotFound(t *testing.T) {
 	t.Parallel()
 

internal/db/testing.go

@@ -1,25 +0,0 @@
-package db
-
-import (
-	"context"
-	"database/sql"
-	"log/slog"
-)
-
-// NewTestDatabaseFromConn creates a Database wrapping an
-// existing *sql.DB connection.  Intended for integration
-// tests in other packages.
-func NewTestDatabaseFromConn(conn *sql.DB) *Database {
-	return &Database{ //nolint:exhaustruct
-		conn: conn,
-		log:  slog.Default(),
-	}
-}
-
-// RunMigrations applies all schema migrations.  Exposed
-// for integration tests in other packages.
-func (database *Database) RunMigrations(
-	ctx context.Context,
-) error {
-	return database.runMigrations(ctx)
-}

internal/dbtest/dbtest.go

@@ -1,5 +1,5 @@
-// Package dbtest gives each test a database of its own. Only tests
-// may import it.
+// Package dbtest gives each test a database of its own and runs raw
+// SQL on it. Only tests may import it.
 package dbtest
 
 import (
@@ -37,3 +37,23 @@ func NewURL(tb testing.TB) string {
 
 	return dbURL
 }
+
+// Exec runs one raw SQL statement on the database at dbURL, over a
+// connection of its own. A test uses it for what the methods of
+// db.Database cannot do, such as creating a trigger that makes a
+// write fail.
+func Exec(tb testing.TB, dbURL, statement string) {
+	tb.Helper()
+
+	pool, err := sql.Open("sqlite", dbURL)
+	if err != nil {
+		tb.Fatalf("open test database: %v", err)
+	}
+
+	defer func() { _ = pool.Close() }()
+
+	_, err = pool.ExecContext(tb.Context(), statement)
+	if err != nil {
+		tb.Fatalf("run %q: %v", statement, err)
+	}
+}

internal/handlers/api.go

@@ -188,7 +188,7 @@ func (hdlr *Handlers) handleCreateSession(
 
 	var payload createRequest
 
-	err := json.NewDecoder(request.Body).Decode(&payload)
+	err := decodeJSON(request, &payload)
 	if err != nil {
 		hdlr.respondError(
 			writer, request,
@@ -412,7 +412,7 @@ func (hdlr *Handlers) deliverWelcome(
 	// 004 RPL_MYINFO
 	hdlr.enqueueNumeric(
 		ctx, clientID, irc.RplMyInfo, nick,
-		[]string{srvName, version, "", "ikmnostl"},
+		[]string{srvName, version, service.UserModes, "Hbiklmnostv"},
 		"",
 	)
 
@@ -925,7 +925,7 @@ func (hdlr *Handlers) HandleSendCommand() http.HandlerFunc {
 
 		var payload commandRequest
 
-		err := json.NewDecoder(request.Body).Decode(&payload)
+		err := decodeJSON(request, &payload)
 		if err != nil {
 			hdlr.respondError(
 				writer, request,
@@ -994,7 +994,7 @@ func (hdlr *Handlers) dispatchCommand(
 		hdlr.handlePrivmsg(
 			writer, request,
 			sessionID, clientID, nick,
-			command, target, body, meta, bodyLines,
+			command, target, body, meta,
 		)
 	case irc.CmdJoin:
 		hdlr.handleJoin(
@@ -1139,8 +1139,18 @@ func (hdlr *Handlers) handlePrivmsg(
 	nick, command, target string,
 	body json.RawMessage,
 	meta json.RawMessage,
-	bodyLines func() []string,
 ) {
+	lines, ok := checkBodyAndMeta(body, meta)
+	if !ok {
+		hdlr.respondError(
+			writer, request,
+			"invalid request body",
+			http.StatusBadRequest,
+		)
+
+		return
+	}
+
 	if target == "" {
 		hdlr.enqueueNumeric(
 			request.Context(), clientID,
@@ -1155,7 +1165,6 @@ func (hdlr *Handlers) handlePrivmsg(
 		return
 	}
 
-	lines := bodyLines()
 	if len(lines) == 0 {
 		hdlr.enqueueNumeric(
 			request.Context(), clientID,
@@ -1189,6 +1198,44 @@ func (hdlr *Handlers) handlePrivmsg(
 	)
 }
 
+// checkBodyAndMeta returns the lines in body. It returns false
+// when body is present and is not an array of strings, or meta
+// is present and is not an object. Each line is decoded as any
+// because decoding into []string turns a null line into "". A
+// null body or meta decodes without an error into nil.
+func checkBodyAndMeta(body, meta json.RawMessage) ([]string, bool) {
+	var lines []string
+
+	if body != nil {
+		var values []any
+
+		err := json.Unmarshal(body, &values)
+		if err != nil || values == nil {
+			return nil, false
+		}
+
+		for _, value := range values {
+			line, isString := value.(string)
+			if !isString {
+				return nil, false
+			}
+
+			lines = append(lines, line)
+		}
+	}
+
+	if meta != nil {
+		var fields map[string]any
+
+		err := json.Unmarshal(meta, &fields)
+		if err != nil || fields == nil {
+			return nil, false
+		}
+	}
+
+	return lines, true
+}
+
 // respondIRCError enqueues a numeric error reply, notifies
 // the broker, and sends HTTP 200 with {"status":"error"}.
 func (hdlr *Handlers) respondIRCError(
@@ -3191,7 +3238,7 @@ func (hdlr *Handlers) handleWho(
 		// 315 RPL_ENDOFWHO (empty result)
 		hdlr.enqueueNumeric(
 			ctx, clientID, irc.RplEndOfWho, nick,
-			[]string{target},
+			[]string{channel},
 			"End of /WHO list",
 		)
 		hdlr.broker.Notify(sessionID)

internal/handlers/api_test.go

@@ -8,10 +8,12 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"maps"
 	"net/http"
 	"net/http/httptest"
 	"net/url"
 	"os"
+	"reflect"
 	"slices"
 	"strconv"
 	"strings"
@@ -45,22 +47,25 @@ import (
 const templateDBURL = "file:template?mode=memory&cache=shared"
 
 func TestMain(m *testing.M) {
-	db.SetBcryptCost(bcrypt.MinCost)
+	template := fx.New(
+		fx.NopLogger,
+		fx.Supply(
+			&globals.Globals{},
+			&config.Config{DBURL: templateDBURL},
+		),
+		fx.Provide(logger.New, newTestDB),
+		// fx makes the database only if something asks for it.
+		fx.Invoke(func(*db.Database) {}),
+	)
 
-	template, err := sql.Open("sqlite", templateDBURL)
-	if err != nil {
-		panic(err)
-	}
-
-	err = db.NewTestDatabaseFromConn(template).
-		RunMigrations(context.Background())
+	err := template.Start(context.Background())
 	if err != nil {
 		panic(err)
 	}
 
 	code := m.Run()
 
-	_ = template.Close()
+	_ = template.Stop(context.Background())
 
 	os.Exit(code)
 }
@@ -135,6 +140,7 @@ type testServer struct {
 	t          *testing.T
 	fxApp      *fxtest.App
 	broker     *broker.Broker
+	dbURL      string
 	database   *db.Database
 	handlers   *handlers.Handlers
 }
@@ -229,6 +235,7 @@ func newTestServerWith(
 		t:          t,
 		fxApp:      app,
 		broker:     brk,
+		dbURL:      dbURL,
 		database:   database,
 		handlers:   hdlr,
 	}
@@ -795,6 +802,104 @@ func TestCreateSessionMalformed(t *testing.T) {
 	}
 }
 
+func (tserver *testServer) postBody(
+	path, token, body string,
+) (int, map[string]any) {
+	tserver.t.Helper()
+
+	resp, err := doRequestAuth(
+		tserver.t, http.MethodPost, tserver.url(path), token,
+		strings.NewReader(body),
+	)
+	if err != nil {
+		tserver.t.Fatalf("post %s: %v", path, err)
+	}
+
+	defer func() { _ = resp.Body.Close() }()
+
+	var result map[string]any
+
+	_ = json.NewDecoder(resp.Body).Decode(&result)
+
+	return resp.StatusCode, result
+}
+
+// TestRequestBodyLimit sends each endpoint a small valid JSON value
+// followed by other bytes. Only whitespace may follow the value, and
+// the whole body counts towards MAX_MESSAGE_SIZE.
+func TestRequestBodyLimit(t *testing.T) {
+	t.Parallel()
+
+	const (
+		maxMessageSize = 4096 // the default MAX_MESSAGE_SIZE
+		nick           = "alice_bodylimit"
+	)
+
+	endpoints := []struct {
+		name, path, value string
+		acceptedStatus    int
+	}{
+		{
+			"create session", apiSession,
+			`{"nick":"bob_bodylimit"}`,
+			http.StatusCreated,
+		},
+		{
+			"login", "/api/v1/login",
+			`{"nick":"` + nick + `","password":"` + testPassword + `"}`,
+			http.StatusOK,
+		},
+		{
+			"post message", apiMessages,
+			`{"command":"PING"}`,
+			http.StatusOK,
+		},
+	}
+
+	for _, endpoint := range endpoints {
+		t.Run(endpoint.name, func(t *testing.T) {
+			t.Parallel()
+
+			tserver := newTestServer(t)
+			token := tserver.createSession(nick)
+
+			tserver.setPassword(nick)
+
+			bytesToLimit := maxMessageSize - len(endpoint.value)
+
+			for _, trailing := range []string{
+				strings.Repeat(" ", bytesToLimit+1),
+				strings.Repeat("x", bytesToLimit+1),
+				"x",
+				"{}",
+			} {
+				status, result := tserver.postBody(
+					endpoint.path, token, endpoint.value+trailing,
+				)
+				if status != http.StatusBadRequest ||
+					result["error"] != "invalid request body" {
+					t.Errorf(
+						"%d bytes of %.10q after the value: expected "+
+							"400 invalid request body, got %d: %v",
+						len(trailing), trailing, status, result,
+					)
+				}
+			}
+
+			status, result := tserver.postBody(
+				endpoint.path, token,
+				endpoint.value+strings.Repeat(" ", bytesToLimit),
+			)
+			if status != endpoint.acceptedStatus {
+				t.Errorf(
+					"body of exactly the limit: expected %d, got %d: %v",
+					endpoint.acceptedStatus, status, result,
+				)
+			}
+		})
+	}
+}
+
 func TestAuthNoCookie(t *testing.T) {
 	t.Parallel()
 
@@ -999,6 +1104,8 @@ func TestChannelMessage(t *testing.T) {
 	}
 }
 
+// TestMessageMissingBody checks that a PRIVMSG with no body,
+// or an empty one, gets ERR_NOTEXTTOSEND.
 func TestMessageMissingBody(t *testing.T) {
 	t.Parallel()
 
@@ -1013,22 +1120,27 @@ func TestMessageMissingBody(t *testing.T) {
 
 	_, lastID := tserver.pollMessages(token, 0)
 
-	status, _ := tserver.sendCommand(token, map[string]any{
-		commandKey: privmsgCmd, toKey: channel,
-	})
+	for _, request := range []map[string]any{
+		{commandKey: privmsgCmd, toKey: channel},
+		{commandKey: privmsgCmd, toKey: channel, bodyKey: []string{}},
+	} {
+		status, _ := tserver.sendCommand(token, request)
 		if status != http.StatusOK {
-		t.Fatalf("expected 200, got %d", status)
+			t.Fatalf("%v: expected 200, got %d", request, status)
 		}
 
-	msgs, _ := tserver.pollMessages(token, lastID)
+		var msgs []map[string]any
+
+		msgs, lastID = tserver.pollMessages(token, lastID)
 
 		if !findNumeric(msgs, "412") {
 			t.Fatalf(
-			"expected ERR_NOTEXTTOSEND (412), got %v",
-			msgs,
+				"%v: expected ERR_NOTEXTTOSEND (412), got %v",
+				request, msgs,
 			)
 		}
 	}
+}
 
 func TestMessageMissingTo(t *testing.T) {
 	t.Parallel()
@@ -1056,6 +1168,132 @@ func TestMessageMissingTo(t *testing.T) {
 	}
 }
 
+// TestMessageInvalidBodyOrMeta checks that a PRIVMSG or
+// NOTICE, to a channel or a nick, whose body is not an array
+// of strings or whose meta is not an object gets 400 and
+// reaches nobody.
+func TestMessageInvalidBodyOrMeta(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		name   string
+		fields map[string]any
+	}{
+		{"null line", map[string]any{bodyKey: []any{"hi", nil}}},
+		{"number line", map[string]any{bodyKey: []any{"hi", 1}}},
+		{"object line", map[string]any{bodyKey: []any{map[string]any{}}}},
+		{"null body", map[string]any{bodyKey: nil}},
+		{"object body", map[string]any{bodyKey: map[string]any{}}},
+		{"null meta", map[string]any{bodyKey: []string{"hi"}, metaKey: nil}},
+		{"array meta", map[string]any{bodyKey: []string{"hi"}, metaKey: []string{}}},
+		{"string meta", map[string]any{bodyKey: []string{"hi"}, metaKey: "hi"}},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			const channel = "#badmsg"
+
+			tserver := newTestServer(t)
+			aliceToken := tserver.createSession("alice_badmsg")
+			bobToken := tserver.createSession("bob_badmsg")
+
+			tserver.sendCommand(aliceToken, map[string]any{
+				commandKey: joinCmd, toKey: channel,
+			})
+			tserver.sendCommand(bobToken, map[string]any{
+				commandKey: joinCmd, toKey: channel,
+			})
+
+			_, bobLastID := tserver.pollMessages(bobToken, 0)
+
+			for _, command := range []string{privmsgCmd, irc.CmdNotice} {
+				for _, target := range []string{channel, "bob_badmsg"} {
+					request := map[string]any{
+						commandKey: command, toKey: target,
+					}
+					maps.Copy(request, tc.fields)
+
+					status, result := tserver.sendCommand(
+						aliceToken, request,
+					)
+					if status != http.StatusBadRequest ||
+						result["error"] != "invalid request body" {
+						t.Errorf(
+							"%s to %s: expected 400 invalid "+
+								"request body, got %d: %v",
+							command, target, status, result,
+						)
+					}
+				}
+			}
+
+			msgs, _ := tserver.pollMessages(bobToken, bobLastID)
+			if len(msgs) != 0 {
+				t.Fatalf("expected no messages, bob got %v", msgs)
+			}
+		})
+	}
+}
+
+// TestMessageRelaysBodyAndMeta checks that a PRIVMSG or
+// NOTICE, to a channel or a nick, reaches its recipient with
+// body and meta as sent.
+func TestMessageRelaysBodyAndMeta(t *testing.T) {
+	t.Parallel()
+
+	const channel = "#relaymsg"
+
+	tserver := newTestServer(t)
+	aliceToken := tserver.createSession("alice_relaymsg")
+	bobToken := tserver.createSession("bob_relaymsg")
+
+	tserver.sendCommand(aliceToken, map[string]any{
+		commandKey: joinCmd, toKey: channel,
+	})
+	tserver.sendCommand(bobToken, map[string]any{
+		commandKey: joinCmd, toKey: channel,
+	})
+
+	_, bobLastID := tserver.pollMessages(bobToken, 0)
+
+	body := []any{"line one", ""}
+	meta := map[string]any{"sig": "abc", "alg": "ed25519"}
+
+	for _, command := range []string{privmsgCmd, irc.CmdNotice} {
+		for _, target := range []string{channel, "bob_relaymsg"} {
+			status, result := tserver.sendCommand(
+				aliceToken,
+				map[string]any{
+					commandKey: command, toKey: target,
+					bodyKey: body, metaKey: meta,
+				},
+			)
+			if status != http.StatusOK {
+				t.Fatalf(
+					"%s to %s: expected 200, got %d: %v",
+					command, target, status, result,
+				)
+			}
+
+			var msgs []map[string]any
+
+			msgs, bobLastID = tserver.pollMessages(
+				bobToken, bobLastID,
+			)
+			if len(msgs) != 1 ||
+				msgs[0][commandKey] != command ||
+				!reflect.DeepEqual(msgs[0][bodyKey], body) ||
+				!reflect.DeepEqual(msgs[0][metaKey], meta) {
+				t.Fatalf(
+					"%s to %s: bob got %v", command, target, msgs,
+				)
+			}
+		}
+	}
+}
+
 func TestNonMemberCannotSend(t *testing.T) {
 	t.Parallel()
 
@@ -1527,9 +1765,7 @@ func checkQuitRace(
 		firstToken := tserver.createSession(nick)
 		observerToken := tserver.createSession("raceobserver")
 
-		tserver.sendCommand(firstToken, map[string]any{
-			commandKey: irc.CmdPass, bodyKey: []string{testPassword},
-		})
+		tserver.setPassword(nick)
 
 		tokens := []string{firstToken, tserver.login(nick)}
 
@@ -1579,9 +1815,7 @@ func TestLogoutOfOneClientKeepsSession(t *testing.T) {
 	firstToken := tserver.createSession(nick)
 	observerToken := tserver.createSession("logoutobserver")
 
-	tserver.sendCommand(firstToken, map[string]any{
-		commandKey: irc.CmdPass, bodyKey: []string{testPassword},
-	})
+	tserver.setPassword(nick)
 
 	secondToken := tserver.login(nick)
 
@@ -1651,15 +1885,12 @@ func TestFailedLogoutChangesNothing(t *testing.T) {
 
 	_, lastID := tserver.pollMessages(observerToken, 0)
 
-	_, err := tserver.database.GetDB().ExecContext(t.Context(),
+	dbtest.Exec(t, tserver.dbURL,
 		`CREATE TRIGGER keep_sessions
 		 BEFORE DELETE ON sessions
 		 BEGIN
 		   SELECT RAISE(ABORT, 'sessions are kept');
 		 END`)
-	if err != nil {
-		t.Fatal(err)
-	}
 
 	resp, err := doRequestAuth(
 		t, http.MethodPost, tserver.url(apiLogout), token, nil,
@@ -1893,6 +2124,24 @@ func (tserver *testServer) longPoll(
 	return result.Messages, nil
 }
 
+// setPassword gives the session nick the password testPassword
+// without sending PASS. It hashes at bcrypt.MinCost, and a login
+// compares at the cost stored in the hash, so both are fast.
+func (tserver *testServer) setPassword(nick string) {
+	tserver.t.Helper()
+
+	hash, err := bcrypt.GenerateFromPassword(
+		[]byte(testPassword), bcrypt.MinCost,
+	)
+	if err != nil {
+		tserver.t.Fatalf("hash password: %v", err)
+	}
+
+	dbtest.Exec(tserver.t, tserver.dbURL,
+		"UPDATE sessions SET password_hash = '"+string(hash)+
+			"' WHERE nick = '"+nick+"'")
+}
+
 // login logs in to the session nick with testPassword and
 // returns the new client's token.
 func (tserver *testServer) login(nick string) string {
@@ -3500,13 +3749,8 @@ func TestLoginValid(t *testing.T) {
 
 	tserver := newTestServer(t)
 
-	// Create session and set password via PASS command.
-	token := tserver.createSession("loginuser")
-
-	tserver.sendCommand(token, map[string]any{
-		commandKey: irc.CmdPass,
-		bodyKey:    []string{testPassword},
-	})
+	tserver.createSession("loginuser")
+	tserver.setPassword("loginuser")
 
 	// Login with nick + password.
 	loginBody, err := json.Marshal(map[string]string{
@@ -3570,13 +3814,8 @@ func TestLoginWrongPassword(t *testing.T) {
 
 	tserver := newTestServer(t)
 
-	// Create session and set password via PASS command.
-	token := tserver.createSession("wrongpwuser")
-
-	tserver.sendCommand(token, map[string]any{
-		commandKey: irc.CmdPass,
-		bodyKey:    []string{"correctpass1"},
-	})
+	tserver.createSession("wrongpwuser")
+	tserver.setPassword("wrongpwuser")
 
 	postJSONExpectStatus(
 		t, tserver, "/api/v1/login",
@@ -3904,6 +4143,31 @@ func assertWhoReplyUsername(
 	)
 }
 
+func TestWhoUnknownChannelEndReplyAddsHash(t *testing.T) {
+	t.Parallel()
+
+	tserver := newTestServer(t)
+
+	token := tserver.createSession("whoasker")
+
+	_, lastID := tserver.pollMessages(token, 0)
+
+	msgs, _ := sendAndPoll(tserver, token, lastID, map[string]any{
+		commandKey: irc.CmdWho,
+		toKey:      "nosuch",
+	})
+
+	endOfWho := findNumericWithParams(msgs, "315")
+	if endOfWho == nil {
+		t.Fatalf("expected RPL_ENDOFWHO (315), got %v", msgs)
+	}
+
+	params := getNumericParams(endOfWho)
+	if !slices.Equal(params, []string{"#nosuch"}) {
+		t.Fatalf("expected params [#nosuch], got %v", params)
+	}
+}
+
 func TestSessionUsernameDefault(t *testing.T) {
 	t.Parallel()
 
@@ -4022,13 +4286,8 @@ func TestLoginRateLimitAllowsNormalUse(t *testing.T) {
 
 	tserver := newTestServer(t)
 
-	// Create session and set password via PASS command.
-	token := tserver.createSession("normaluser")
-
-	tserver.sendCommand(token, map[string]any{
-		commandKey: irc.CmdPass,
-		bodyKey:    []string{testPassword},
-	})
+	tserver.createSession("normaluser")
+	tserver.setPassword("normaluser")
 
 	// A single login should succeed without rate limiting.
 	loginBody, err := json.Marshal(map[string]string{
@@ -6797,6 +7056,32 @@ func TestISUPPORT(t *testing.T) {
 	}
 }
 
+// TestMyInfoListsModes verifies the 004 numeric lists the
+// user modes o and w as its third parameter, and the HTTP
+// API's channel modes Hbiklmnostv as its fourth.
+func TestMyInfoListsModes(t *testing.T) {
+	t.Parallel()
+
+	tserver := newTestServer(t)
+	token := tserver.createSession("myinfo")
+
+	msgs, _ := tserver.pollMessages(token, 0)
+
+	myInfo := findNumericWithParams(msgs, "004")
+	if myInfo == nil {
+		t.Fatal("expected 004 RPL_MYINFO")
+	}
+
+	params := getNumericParams(myInfo)
+	if len(params) != 4 || params[2] != "ow" ||
+		params[3] != "Hbiklmnostv" {
+		t.Fatalf(
+			"004 params %v, want four ending ow Hbiklmnostv",
+			params,
+		)
+	}
+}
+
 // TestNonOpCannotSetModes verifies non-operators
 // cannot set +i, +s, +k, +l, +b.
 func TestNonOpCannotSetModes(t *testing.T) {

internal/handlers/auth.go

@@ -1,7 +1,6 @@
 package handlers
 
 import (
-	"encoding/json"
 	"net/http"
 	"strings"
 
@@ -55,7 +54,7 @@ func (hdlr *Handlers) handleLogin(
 
 	var payload loginRequest
 
-	err := json.NewDecoder(request.Body).Decode(&payload)
+	err := decodeJSON(request, &payload)
 	if err != nil {
 		hdlr.respondError(
 			writer, request,

internal/handlers/handlers.go

@@ -5,6 +5,7 @@ import (
 	"context"
 	"encoding/json"
 	"errors"
+	"io"
 	"log/slog"
 	"net/http"
 	"time"
@@ -159,6 +160,18 @@ func (hdlr *Handlers) respondError(
 	)
 }
 
+// decodeJSON reads the whole request body and decodes it into dest.
+// It fails if the body is larger than the http.MaxBytesReader limit,
+// or holds anything other than one JSON value and whitespace.
+func decodeJSON(request *http.Request, dest any) error {
+	body, err := io.ReadAll(request.Body)
+	if err != nil {
+		return err
+	}
+
+	return json.Unmarshal(body, dest)
+}
+
 func (hdlr *Handlers) idleTimeout() time.Duration {
 	raw := hdlr.params.Config.SessionIdleTimeout
 	if raw == "" {

internal/ircserver/commands.go

@@ -371,6 +371,7 @@ func (c *Conn) handleQuit(msg *Message) {
 
 	c.mu.Lock()
 	c.closed = true
+	c.quitReason = reason
 	c.mu.Unlock()
 }
 
@@ -1226,9 +1227,12 @@ func (c *Conn) handlePassPostReg(
 		return
 	}
 
+	// The IRC listener cannot add a connection to an existing
+	// session; only the HTTP API login can.
 	c.sendFromServer("NOTICE", c.currentNick(),
-		"Password set. You can reconnect using "+
-			"PASS <password> with your nick.",
+		"Password set. Another client can log in to this "+
+			"session over the HTTP API: POST /api/v1/login "+
+			"with your nick and this password.",
 	)
 }
 

internal/ircserver/conn.go

@@ -69,6 +69,11 @@ type Conn struct {
 	lastQueueID int64
 	closed      bool
 	killed      bool
+
+	// quitReason is the reason in the QUIT that peers are
+	// sent when the connection ends. The client's QUIT
+	// replaces it.
+	quitReason string
 }
 
 func newConn(
@@ -95,6 +100,7 @@ func newConn(
 		svc:        svc,
 		serverSfx:  srvName,
 		remoteIP:   host,
+		quitReason: "Connection closed",
 	}
 
 	conn.commands = conn.buildCommandMap()
@@ -278,6 +284,7 @@ func (c *Conn) cleanup(ctx context.Context) {
 	wasKilled := c.killed
 	sessID := c.sessionID
 	nick := c.nick
+	quitReason := c.quitReason
 	c.closed = true
 	c.mu.Unlock()
 
@@ -287,9 +294,7 @@ func (c *Conn) cleanup(ctx context.Context) {
 		// KILL has already sent the QUIT and deleted the
 		// session.
 		if !wasKilled {
-			c.svc.BroadcastQuit(
-				ctx, sessID, nick, "Connection closed",
-			)
+			c.svc.BroadcastQuit(ctx, sessID, nick, quitReason)
 		}
 	}
 
@@ -605,7 +610,7 @@ func (c *Conn) deliverWelcome() {
 	)
 	c.sendNumeric(
 		irc.RplMyInfo,
-		c.serverSfx, "neoirc", "", "mnst",
+		c.serverSfx, "neoirc", service.UserModes, "Himnostv",
 	)
 	c.sendNumeric(
 		irc.RplIsupport,

internal/ircserver/relay_test.go

@@ -8,6 +8,8 @@ import (
 	"testing"
 	"time"
 
+	"golang.org/x/crypto/bcrypt"
+	"sneak.berlin/go/neoirc/internal/dbtest"
 	"sneak.berlin/go/neoirc/internal/ircserver"
 	"sneak.berlin/go/neoirc/internal/service"
 )
@@ -316,7 +318,7 @@ func TestRelayNickDiffersOnlyInCase(t *testing.T) {
 		{"JOIN #case", ":Alice!Alice@* JOIN #case"},
 		{"NICK Alicia", ":Alice!Alice@* NICK Alicia"},
 		{"NICK Alice", ":Alicia!Alicia@* NICK Alice"}, // back for QUIT
-		{"QUIT", ":Alice!Alice@* QUIT :Quit: Connection closed"},
+		{"QUIT", ":Alice!Alice@* QUIT :Quit: Client quit"},
 	} {
 		capitalAlice.send(step.line)
 
@@ -583,8 +585,10 @@ func ownSessionCopies(
 
 // aliceWithHTTPClient connects alice to the IRC listener and
 // has her join #chan, which bob is on too, then adds an HTTP API
-// client to her session with the password her connection set,
-// as POST /api/v1/login does. It returns her connection, bob's
+// client to her session with a password, as POST /api/v1/login
+// does. It stores that password without sending PASS. It hashes
+// at bcrypt.MinCost, and a login compares at the cost stored in
+// the hash, so both are fast. It returns her connection, bob's
 // connection, her session and her HTTP API client.
 func aliceWithHTTPClient(
 	t *testing.T, env *testEnv,
@@ -594,15 +598,24 @@ func aliceWithHTTPClient(
 	const password = "alicepass"
 
 	alice := env.dial(t)
-	alice.send("PASS " + password)
 	alice.register("alice")
-	// Registration stores the password before the JOIN runs.
 	alice.joinAndDrain("#chan")
 
 	bob := env.dial(t)
 	bob.register("bob")
 	bob.joinAndDrain("#chan")
 
+	hash, err := bcrypt.GenerateFromPassword(
+		[]byte(password), bcrypt.MinCost,
+	)
+	if err != nil {
+		t.Fatalf("hash password: %v", err)
+	}
+
+	dbtest.Exec(t, env.dbURL,
+		"UPDATE sessions SET password_hash = '"+string(hash)+
+			"' WHERE nick = 'alice'")
+
 	sessionID, httpClientID, _, err := env.database.LoginUser(
 		t.Context(), "alice", password, "127.0.0.1", "localhost",
 	)

internal/ircserver/server_test.go

@@ -4,12 +4,14 @@ import (
 	"bufio"
 	"context"
 	"database/sql"
+	"encoding/json"
 	"errors"
 	"fmt"
 	"log/slog"
 	"net"
 	"os"
 	"runtime"
+	"slices"
 	"strings"
 	"sync/atomic"
 	"testing"
@@ -23,20 +25,16 @@ import (
 	"sneak.berlin/go/neoirc/internal/globals"
 	"sneak.berlin/go/neoirc/internal/ircserver"
 	"sneak.berlin/go/neoirc/internal/logger"
+	"sneak.berlin/go/neoirc/pkg/irc"
 
 	_ "modernc.org/sqlite"
 )
 
 const testTimeout = 5 * time.Second
 
-func TestMain(m *testing.M) {
-	db.SetBcryptCost(4)
-
-	os.Exit(m.Run())
-}
-
 // testEnv holds the shared test infrastructure.
 type testEnv struct {
+	dbURL    string
 	database *db.Database
 	brk      *broker.Broker
 	cfg      *config.Config
@@ -107,34 +105,27 @@ func newTestEnvWithResolver(
 ) *testEnv {
 	t.Helper()
 
-	conn, err := sql.Open("sqlite", dbtest.NewURL(t))
-	if err != nil {
-		t.Fatalf("open db: %v", err)
-	}
+	dbURL := dbtest.NewURL(t)
+	lifecycle := fxtest.NewLifecycle(t)
 
-	t.Cleanup(func() {
-		err := conn.Close()
-		if err != nil {
-			t.Logf("close db: %v", err)
-		}
+	dbLog, err := logger.New(lifecycle, logger.Params{
+		Globals: &globals.Globals{},
 	})
-
-	conn.SetMaxOpenConns(1)
-
-	_, err = conn.ExecContext(
-		t.Context(), "PRAGMA foreign_keys = ON",
-	)
 	if err != nil {
-		t.Fatalf("pragma: %v", err)
+		t.Fatalf("new logger: %v", err)
 	}
 
-	database := db.NewTestDatabaseFromConn(conn)
-
-	err = database.RunMigrations(t.Context())
+	database, err := db.New(lifecycle, db.Params{
+		Logger: dbLog,
+		Config: &config.Config{DBURL: dbURL},
+	})
 	if err != nil {
-		t.Fatalf("migrate: %v", err)
+		t.Fatalf("new database: %v", err)
 	}
 
+	lifecycle.RequireStart()
+	t.Cleanup(lifecycle.RequireStop)
+
 	brk := broker.New()
 
 	log := slog.New(slog.NewTextHandler(
@@ -158,6 +149,7 @@ func newTestEnvWithResolver(
 	t.Cleanup(srv.Stop)
 
 	return &testEnv{
+		dbURL:    dbURL,
 		database: database,
 		brk:      brk,
 		cfg:      cfg,
@@ -486,6 +478,22 @@ func TestWelcomeContainsNick(t *testing.T) {
 	}
 }
 
+// TestMyInfoListsModes checks that RPL_MYINFO lists the user
+// modes o and w, then the channel modes MODE accepts on the
+// IRC listener. It compares the whole line, so a missing or
+// extra mode fails it.
+func TestMyInfoListsModes(t *testing.T) {
+	t.Parallel()
+
+	env := newTestEnv(t)
+	lines := env.dial(t).register("carol")
+
+	want := ":test.irc 004 carol test.irc neoirc ow Himnostv"
+	if !slices.Contains(lines, want) {
+		t.Errorf("no line %q in %v", want, lines)
+	}
+}
+
 func TestPingPong(t *testing.T) {
 	t.Parallel()
 
@@ -856,6 +864,107 @@ func TestQuit(t *testing.T) {
 	assertContains(t, lines, "goodbye", "QUIT reason")
 }
 
+// TestQuitReasonReachesPeers checks the reason that an IRC
+// listener user's channel peers see in its QUIT, on both the
+// IRC listener and the HTTP API. It is the reason the user
+// gave, Client quit for a QUIT without one, or Connection
+// closed when the connection ends without a QUIT.
+func TestQuitReasonReachesPeers(t *testing.T) {
+	t.Parallel()
+
+	for _, step := range []struct {
+		name, quit, want string
+	}{
+		{"QUIT with a reason", "QUIT :gone home", "gone home"},
+		{"QUIT without a reason", irc.CmdQuit, "Client quit"},
+		{"connection closed without QUIT", "", "Connection closed"},
+	} {
+		t.Run(step.name, func(t *testing.T) {
+			t.Parallel()
+
+			ircLine, apiBody := quitSeenByPeers(t, step.quit)
+
+			want := ":quitter!quitter@* QUIT :Quit: " + step.want
+			if ircLine != want {
+				t.Errorf("IRC peer got %q, want %q", ircLine, want)
+			}
+
+			if len(apiBody) != 1 || apiBody[0] != step.want {
+				t.Errorf("HTTP API peer got %q, want [%q]", apiBody, step.want)
+			}
+		})
+	}
+}
+
+// quitSeenByPeers starts a server on which quitter, ircpeer on
+// the IRC listener and apipeer on the HTTP API share a channel.
+// quitter sends the line quit, or closes its connection when
+// quit is empty. It returns the QUIT line ircpeer is sent and
+// the body of the QUIT apipeer is sent.
+func quitSeenByPeers(t *testing.T, quit string) (string, []string) {
+	t.Helper()
+
+	env := newTestEnv(t)
+	ctx := t.Context()
+
+	ircPeer := env.dial(t)
+	ircPeer.register("ircpeer")
+	ircPeer.joinAndDrain("#bye")
+
+	apiPeerID, apiPeerClientID, _, err := env.database.CreateSession(
+		ctx, "apipeer", "apipeer", "", "",
+	)
+	if err != nil {
+		t.Fatalf("create peer session: %v", err)
+	}
+
+	_, _, err = env.database.CreateOrJoinChannel(ctx, "#bye", apiPeerID, "")
+	if err != nil {
+		t.Fatalf("join peer: %v", err)
+	}
+
+	quitter := env.dial(t)
+	quitter.register("quitter")
+	quitter.joinAndDrain("#bye")
+
+	if quit == "" {
+		err = quitter.conn.Close()
+		if err != nil {
+			t.Fatalf("close: %v", err)
+		}
+	} else {
+		quitter.send(quit)
+	}
+
+	lines := ircPeer.readUntil(func(l string) bool {
+		return strings.Contains(l, " QUIT ")
+	})
+
+	// The QUIT is queued to both peers at once, so apipeer has
+	// it by now.
+	msgs, _, err := env.database.PollMessages(ctx, apiPeerClientID, 0, 0)
+	if err != nil {
+		t.Fatalf("poll peer: %v", err)
+	}
+
+	for _, msg := range msgs {
+		if msg.Command == irc.CmdQuit && msg.From == "quitter" {
+			var body []string
+
+			err = json.Unmarshal(msg.Body, &body)
+			if err != nil {
+				t.Fatalf("decode QUIT body %s: %v", msg.Body, err)
+			}
+
+			return lines[len(lines)-1], body
+		}
+	}
+
+	t.Fatalf("apipeer was not sent the QUIT: %v", msgs)
+
+	return "", nil
+}
+
 // TestStopEndsSessions checks that stopping the server ends
 // a registered connection's session before Stop returns, as
 // closing the connection does: the session, its client and
@@ -880,12 +989,9 @@ func TestStopEndsSessions(t *testing.T) {
 		t.Fatalf("create peer session: %v", err)
 	}
 
-	channelID, err := env.database.GetChannelByName(ctx, "#shut")
-	if err != nil {
-		t.Fatalf("get channel: %v", err)
-	}
-
-	err = env.database.JoinChannel(ctx, channelID, peerID)
+	channelID, _, err := env.database.CreateOrJoinChannel(
+		ctx, "#shut", peerID, "",
+	)
 	if err != nil {
 		t.Fatalf("join peer: %v", err)
 	}
@@ -943,11 +1049,16 @@ func TestStopReturnsWhileCleanupIsStuck(t *testing.T) {
 
 	client.register("stuck")
 
-	// The test database has one connection. While the test
-	// holds it, the cleanup's first query waits for it.
-	held, err := env.database.GetDB().Conn(t.Context())
+	// While a connection of the test's own holds a write
+	// transaction, the cleanup's first write waits for it to end.
+	holder, err := sql.Open("sqlite", env.dbURL)
 	if err != nil {
-		t.Fatalf("take the database connection: %v", err)
+		t.Fatalf("open a second database connection: %v", err)
+	}
+
+	_, err = holder.ExecContext(t.Context(), "BEGIN IMMEDIATE")
+	if err != nil {
+		t.Fatalf("begin a write transaction: %v", err)
 	}
 
 	stopped := make(chan struct{})
@@ -963,10 +1074,11 @@ func TestStopReturnsWhileCleanupIsStuck(t *testing.T) {
 		t.Error("Stop did not return while a cleanup was stuck")
 	}
 
-	// Lets the cleanup finish before the database is closed.
-	err = held.Close()
+	// Closing ends the transaction, which lets the cleanup finish
+	// before the database is closed.
+	err = holder.Close()
 	if err != nil {
-		t.Errorf("release the database connection: %v", err)
+		t.Errorf("close the second database connection: %v", err)
 	}
 }
 
@@ -1125,6 +1237,9 @@ func TestAwaySetAndClear(t *testing.T) {
 	assertContains(t, clearLines, " 305 ", "RPL_UNAWAY")
 }
 
+// TestHandlePassPostRegistration checks the NOTICE that
+// confirms PASS after registration. It points to the HTTP API
+// login, the only way to add a client to an existing session.
 func TestHandlePassPostRegistration(t *testing.T) {
 	t.Parallel()
 
@@ -1137,7 +1252,11 @@ func TestHandlePassPostRegistration(t *testing.T) {
 	)
 
 	assertContains(
-		t, lines, "Password set", "password confirmation",
+		t, lines,
+		" NOTICE passuser :Password set. Another client can log "+
+			"in to this session over the HTTP API: "+
+			"POST /api/v1/login with your nick and this password.",
+		"password confirmation",
 	)
 }
 
@@ -1238,14 +1357,11 @@ func TestPassPostRegistrationNotStored(t *testing.T) {
 
 	client.register("failpass")
 
-	_, err := env.database.GetDB().ExecContext(t.Context(),
+	dbtest.Exec(t, env.dbURL,
 		`CREATE TRIGGER refuse_password
 		 BEFORE UPDATE OF password_hash ON sessions
 		 BEGIN SELECT RAISE(ABORT, 'refused'); END`,
 	)
-	if err != nil {
-		t.Fatalf("create trigger: %v", err)
-	}
 
 	client.send("PASS :mypassword123")
 

internal/service/service.go

@@ -1169,6 +1169,12 @@ func (s *Service) ApplyUserMode(
 	return s.QueryUserMode(ctx, sessionID)
 }
 
+// UserModes lists the user modes the server supports, as
+// RPL_MYINFO sends them: o (server operator) and w
+// (receives WALLOPS). parseUserModeString must accept the
+// same letters.
+const UserModes = "ow"
+
 // parseUserModeString parses a user mode string such as
 // "+w", "-o" or "+w-o" into the new value of each flag it
 // names, or nil for a flag it does not name; a later letter

internal/service/service_test.go

@@ -9,7 +9,6 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
-	"os"
 	"slices"
 	"strings"
 	"sync"
@@ -18,7 +17,6 @@ import (
 
 	"go.uber.org/fx"
 	"go.uber.org/fx/fxtest"
-	"golang.org/x/crypto/bcrypt"
 	"sneak.berlin/go/neoirc/internal/broker"
 	"sneak.berlin/go/neoirc/internal/config"
 	"sneak.berlin/go/neoirc/internal/db"
@@ -30,14 +28,10 @@ import (
 	"sneak.berlin/go/neoirc/pkg/irc"
 )
 
-func TestMain(m *testing.M) {
-	db.SetBcryptCost(bcrypt.MinCost)
-	os.Exit(m.Run())
-}
-
 // testEnv holds all dependencies for a service test.
 type testEnv struct {
 	svc    *service.Service
+	dbURL  string
 	db     *db.Database
 	broker *broker.Broker
 	app    *fxtest.App
@@ -111,6 +105,7 @@ func newTestEnv(t *testing.T) *testEnv {
 
 	return &testEnv{
 		svc:    svc,
+		dbURL:  dbURL,
 		db:     database,
 		broker: brk,
 		app:    app,
@@ -940,19 +935,16 @@ func TestSendDirectMessageTargetQuits(t *testing.T) {
 	sid := createSession(ctx, t, env.db, "alice")
 	createSession(ctx, t, env.db, "bob")
 
-	_, err := env.db.GetDB().ExecContext(ctx,
+	dbtest.Exec(t, env.dbURL,
 		`CREATE TRIGGER delete_recipient
 		 BEFORE INSERT ON messages
 		 BEGIN
 		   DELETE FROM sessions WHERE id = NEW.to_session_id;
 		 END`)
-	if err != nil {
-		t.Fatalf("create trigger: %v", err)
-	}
 
 	body, _ := json.Marshal([]string{"hi"}) //nolint:errchkjson
 
-	_, err = env.svc.SendDirectMessage(
+	_, err := env.svc.SendDirectMessage(
 		ctx, sid, 0, "alice", irc.CmdPrivmsg, "bob", body, nil,
 	)
 
@@ -978,15 +970,12 @@ func TestSendChannelMessageChannelDeleted(t *testing.T) {
 		t.Fatalf("join alice: %v", err)
 	}
 
-	_, err = env.db.GetDB().ExecContext(ctx,
+	dbtest.Exec(t, env.dbURL,
 		`CREATE TRIGGER delete_recipient
 		 BEFORE INSERT ON messages
 		 BEGIN
 		   DELETE FROM channels WHERE id = NEW.to_channel_id;
 		 END`)
-	if err != nil {
-		t.Fatalf("create trigger: %v", err)
-	}
 
 	body, _ := json.Marshal([]string{"hi"}) //nolint:errchkjson
 

schema/README.md

@@ -20,7 +20,7 @@ are the fields it can have:
 - `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.
+- `from`: the sender's nick, or the server name on a numeric reply or a `PONG`.
 - `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`
@@ -60,29 +60,32 @@ A `PRIVMSG` whose `body` has two strings is a two-line message:
 
 ## Files
 
+Most command files describe both the message a client sends and the message the
+server sends. Their field descriptions say where the two differ. The examples in
+the files leave out `id`, `ts` and `meta`.
+
 Commands, in `commands/`:
 
 - `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.
+- `JOIN.json`: joining a channel.
+- `PART.json`: leaving a channel.
+- `QUIT.json`: leaving the server.
+- `NICK.json`: changing nick.
+- `TOPIC.json`: setting a channel's topic.
+- `MODE.json`: querying or changing a channel's modes or the user's own modes.
+- `KICK.json`: a channel operator removing 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`).
+- `PONG.json`: the answer to a `PING`, which is the HTTP response to it.
 
 Numeric replies, in `numerics/`:
 
-- `001.json`: `RPL_WELCOME`, which welcomes a new user.
+- `001.json`: `RPL_WELCOME`, which welcomes the 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.
+- `003.json`: `RPL_CREATED`, the date the server last started.
+- `004.json`: `RPL_MYINFO`, the server's name, its 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.
@@ -96,71 +99,3 @@ Numeric replies, in `numerics/`:
 - `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.
-
-## Where the files differ from the HTTP API
-
-Where a schema file and the HTTP API disagree, the HTTP API is right:
-
-- `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`.
-
-The HTTP API also accepts some messages that the files do not allow, such as a
-`JOIN` whose `to` has no `#`.

schema/commands/JOIN.json

@@ -2,15 +2,25 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/commands/JOIN.json",
   "title": "JOIN",
-  "description": "Join a channel. C2S: request to join. S2C: notification that a user joined. RFC 1459 §4.2.1.",
+  "description": "Join a channel. A client sends it to join a channel, which the server creates if it does not exist. The server sends it to every member of the channel when a user joins, the new member included. RFC 1459 §4.2.1.",
   "$ref": "../message.json",
   "properties": {
     "command": { "const": "JOIN" },
-    "from": { "type": "string", "description": "Nick that joined (S2C)." },
-    "to": { "type": "string", "description": "Channel name.", "pattern": "^#[a-zA-Z0-9_-]+$" }
+    "from": { "type": "string", "description": "The nick that joined. The server sets it." },
+    "to": {
+      "type": "string",
+      "description": "The channel name: # and then 1 to 63 of a-z, A-Z, 0-9, _ and -. The server adds the # if a client leaves it out.",
+      "pattern": "^#?[a-zA-Z0-9_-]{1,63}$"
+    },
+    "body": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "From a client: the channel key as the first string, which a channel with mode +k needs. From the server: the channel name. After a login, and for GET /api/v1/state?initChannelState=1, the server queues a JOIN for each of the session's channels. That JOIN has an empty body."
+    }
   },
   "required": ["command", "to"],
   "examples": [
-    { "command": "JOIN", "from": "alice", "to": "#general" }
+    { "command": "JOIN", "to": "#general" },
+    { "command": "JOIN", "from": "alice", "to": "#general", "body": ["#general"] }
   ]
 }

schema/commands/KICK.json

@@ -2,28 +2,33 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/commands/KICK.json",
   "title": "KICK",
-  "description": "Kick a user from a channel. RFC 1459 §4.2.8.",
+  "description": "Remove a user from a channel. A client sends it, and only a channel operator may. The server sends it to every member of the channel, the removed user included. RFC 1459 §4.2.8.",
   "$ref": "../message.json",
   "properties": {
     "command": { "const": "KICK" },
-    "from": { "type": "string", "description": "Nick that performed the kick." },
-    "to": { "type": "string", "description": "Channel name.", "pattern": "^#[a-zA-Z0-9_-]+$" },
+    "from": { "type": "string", "description": "The nick that removed the user. The server sets it." },
+    "to": {
+      "type": "string",
+      "description": "The channel name. The server adds the # if a client leaves it out.",
+      "pattern": "^#?[a-zA-Z0-9_-]{1,63}$"
+    },
     "params": {
       "type": "array",
       "items": { "type": "string" },
-      "description": "Kicked nick. e.g. [\"alice\"].",
+      "description": "The removed nick. Only the server sends it.",
       "minItems": 1,
       "maxItems": 1
     },
     "body": {
       "type": "array",
       "items": { "type": "string" },
-      "description": "Optional kick reason.",
-      "maxItems": 1
+      "description": "From a client: the nick to remove, then an optional reason. From the server: the reason, as one string.",
+      "minItems": 1
     }
   },
-  "required": ["command", "to", "params"],
+  "required": ["command", "to", "body"],
   "examples": [
+    { "command": "KICK", "to": "#general", "body": ["troll", "Behave"] },
     { "command": "KICK", "from": "op1", "to": "#general", "params": ["troll"], "body": ["Behave"] }
   ]
 }

schema/commands/MODE.json

@@ -2,28 +2,29 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/commands/MODE.json",
   "title": "MODE",
-  "description": "Set or query channel/user modes. RFC 1459 §4.2.3.",
+  "description": "Query or change a channel's modes or the user's own modes. A client sends it. The server sends it to every member of the channel when a channel mode changes. A +H or -H sent over the HTTP API is the exception. The server answers it with RPL_CHANNELMODEIS (324) and sends no MODE. RFC 1459 §4.2.3.",
   "$ref": "../message.json",
   "properties": {
     "command": { "const": "MODE" },
     "from": {
       "type": "string",
-      "description": "Nick that set the mode (S2C only)."
+      "description": "The nick that changed the mode. The server sets it."
     },
     "to": {
       "type": "string",
-      "description": "Channel name.",
-      "pattern": "^#[a-zA-Z0-9_-]+$"
+      "description": "A channel name, which starts with #, or the user's own nick."
     },
-    "params": {
+    "body": {
       "type": "array",
       "items": { "type": "string" },
-      "description": "Mode string and optional target nick. e.g. [\"+o\", \"alice\"].",
-      "examples": [["+o", "alice"], ["-m"], ["+v", "bob"]]
+      "description": "From a client: the mode change and then its value, as separate strings, such as \"+o\" and \"bob\". A MODE without a body is a query. From the server: the change and its value, as one string, such as \"+o bob\", or as separate strings, such as \"+k\" and \"secret\".",
+      "examples": [["+o", "bob"], ["-m"], ["+o bob"], ["+k", "secret"]]
     }
   },
-  "required": ["command", "to", "params"],
+  "required": ["command", "to"],
   "examples": [
-    { "command": "MODE", "from": "op1", "to": "#general", "params": ["+o", "alice"] }
+    { "command": "MODE", "to": "#general", "body": ["+o", "bob"] },
+    { "command": "MODE", "from": "op1", "to": "#general", "body": ["+o bob"] },
+    { "command": "MODE", "from": "op1", "to": "#general", "body": ["+k", "secret"] }
   ]
 }

schema/commands/NICK.json

@@ -2,21 +2,21 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/commands/NICK.json",
   "title": "NICK",
-  "description": "Change nickname. C2S: request new nick. S2C: notification of nick change. RFC 1459 §4.1.2.",
+  "description": "Change nick. A client sends it to change its nick. The server sends it to the user's own clients and to the users who share a channel with the user. RFC 1459 §4.1.2.",
   "$ref": "../message.json",
   "properties": {
     "command": { "const": "NICK" },
-    "from": { "type": "string", "description": "Old nick (S2C)." },
+    "from": { "type": "string", "description": "The old nick. The server sets it." },
     "body": {
       "type": "array",
       "items": { "type": "string" },
-      "description": "New nick (single-element array).",
-      "minItems": 1,
-      "maxItems": 1
+      "description": "The new nick, as the first string. The server sends one string.",
+      "minItems": 1
     }
   },
   "required": ["command", "body"],
   "examples": [
+    { "command": "NICK", "body": ["newnick"] },
     { "command": "NICK", "from": "oldnick", "body": ["newnick"] }
   ]
 }

schema/commands/NOTICE.json

@@ -2,20 +2,21 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/commands/NOTICE.json",
   "title": "NOTICE",
-  "description": "Send a notice. Like PRIVMSG but must not trigger automatic replies. RFC 1459 §4.4.2.",
+  "description": "A notice: a message to a channel or a user that a client must not answer automatically. The server relays it as it relays a PRIVMSG. A NOTICE to a channel with mode +H needs no hashcash stamp. RFC 1459 §4.4.2.",
   "$ref": "../message.json",
   "properties": {
     "command": { "const": "NOTICE" },
-    "from": { "type": "string" },
-    "to": { "type": "string", "description": "Target: #channel, nick, or * (global)." },
+    "from": { "type": "string", "description": "The sender's nick. The server sets it." },
+    "to": { "type": "string", "description": "A channel name, which starts with #, or a nick." },
     "body": {
       "type": "array",
       "items": { "type": "string" },
-      "description": "Notice text lines."
+      "description": "The lines of the notice, one string per line.",
+      "minItems": 1
     }
   },
   "required": ["command", "to", "body"],
   "examples": [
-    { "command": "NOTICE", "from": "server.example.com", "to": "*", "body": ["Server restarting in 5 minutes"] }
+    { "command": "NOTICE", "from": "alice", "to": "#general", "body": ["Back in five minutes"] }
   ]
 }

schema/commands/PART.json

@@ -2,17 +2,20 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/commands/PART.json",
   "title": "PART",
-  "description": "Leave a channel. C2S: request to leave. S2C: notification that a user left. RFC 1459 §4.2.2.",
+  "description": "Leave a channel. A client sends it to leave. The server sends it to every member of the channel when a user leaves, the leaving user included. RFC 1459 §4.2.2.",
   "$ref": "../message.json",
   "properties": {
     "command": { "const": "PART" },
-    "from": { "type": "string", "description": "Nick that left (S2C)." },
-    "to": { "type": "string", "description": "Channel name.", "pattern": "^#[a-zA-Z0-9_-]+$" },
+    "from": { "type": "string", "description": "The nick that left. The server sets it." },
+    "to": {
+      "type": "string",
+      "description": "The channel name. The server adds the # if a client leaves it out.",
+      "pattern": "^#?[a-zA-Z0-9_-]{1,63}$"
+    },
     "body": {
       "type": "array",
       "items": { "type": "string" },
-      "description": "Optional part reason.",
-      "maxItems": 1
+      "description": "The reason for leaving. A client may send one as the first string. The server always sends one string, which is empty when no reason was given."
     }
   },
   "required": ["command", "to"],

schema/commands/PING.json

@@ -2,19 +2,13 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/commands/PING.json",
   "title": "PING",
-  "description": "Keepalive. C2S or S2S. Server responds with PONG. RFC 1459 §4.6.2.",
+  "description": "A check that the server still answers. A client sends it. The server ignores every field but 'command'. Its answer is a PONG in the HTTP response. RFC 1459 §4.6.2.",
   "$ref": "../message.json",
   "properties": {
-    "command": { "const": "PING" },
-    "body": {
-      "type": "array",
-      "items": { "type": "string" },
-      "description": "Opaque token to be echoed in PONG (single-element array).",
-      "maxItems": 1
-    }
+    "command": { "const": "PING" }
   },
   "required": ["command"],
   "examples": [
-    { "command": "PING", "body": ["1707580000"] }
+    { "command": "PING" }
   ]
 }

schema/commands/PONG.json

@@ -2,20 +2,14 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/commands/PONG.json",
   "title": "PONG",
-  "description": "Keepalive response. S2C or S2S. RFC 1459 §4.6.3.",
+  "description": "The answer to a PING. The server sends it as the HTTP response to the PING, with only 'command' and 'from'. A client's PONG gets ERR_UNKNOWNCOMMAND (421). RFC 1459 §4.6.3.",
   "$ref": "../message.json",
   "properties": {
     "command": { "const": "PONG" },
-    "from": { "type": "string", "description": "Responding server name." },
-    "body": {
-      "type": "array",
-      "items": { "type": "string" },
-      "description": "Echoed token from PING (single-element array).",
-      "maxItems": 1
-    }
+    "from": { "type": "string", "description": "The server name." }
   },
-  "required": ["command"],
+  "required": ["command", "from"],
   "examples": [
-    { "command": "PONG", "from": "server.example.com", "body": ["1707580000"] }
+    { "command": "PONG", "from": "neoirc" }
   ]
 }

schema/commands/PRIVMSG.json

@@ -2,16 +2,16 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/commands/PRIVMSG.json",
   "title": "PRIVMSG",
-  "description": "Send a message to a channel or user. C2S: client sends to server. S2C: server relays to recipients. RFC 1459 §4.4.1.",
+  "description": "A message to a channel or a user. A client sends it. The server relays it to every member of the channel, or to the user, and to the sender's own clients. RFC 1459 §4.4.1.",
   "$ref": "../message.json",
   "properties": {
     "command": { "const": "PRIVMSG" },
-    "from": { "type": "string", "description": "Sender nick (set by server on relay)." },
-    "to": { "type": "string", "description": "Target: #channel or nick.", "examples": ["#general", "alice"] },
+    "from": { "type": "string", "description": "The sender's nick. The server sets it." },
+    "to": { "type": "string", "description": "A channel name, which starts with #, or a nick.", "examples": ["#general", "alice"] },
     "body": {
       "type": "array",
       "items": { "type": "string" },
-      "description": "Message lines. One string per line.",
+      "description": "The lines of the message, one string per line.",
       "minItems": 1
     }
   },
@@ -19,6 +19,6 @@
   "examples": [
     { "command": "PRIVMSG", "from": "bob", "to": "#general", "body": ["hello world"] },
     { "command": "PRIVMSG", "from": "bob", "to": "#general", "body": ["line one", "line two"] },
-    { "command": "PRIVMSG", "from": "bob", "to": "alice", "body": ["hey"], "meta": { "sig": "base64...", "alg": "ed25519" } }
+    { "command": "PRIVMSG", "from": "bob", "to": "alice", "body": ["hey"] }
   ]
 }

schema/commands/PUBKEY.json

@@ -1,37 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://sneak.berlin/go/neoirc/schema/commands/PUBKEY.json",
-  "title": "PUBKEY",
-  "description": "Announce or relay a user's public signing key. C2S: client announces key to channel or server. S2C: server relays to channel members. Protocol extension (not in RFC 1459). Body is a structured object (not an array) containing the key material.",
-  "$ref": "../message.json",
-  "properties": {
-    "command": { "const": "PUBKEY" },
-    "from": { "type": "string", "description": "Nick announcing the key (set by server on relay)." },
-    "to": {
-      "type": "string",
-      "description": "Target: #channel to announce to channel members, or omit for server-wide announcement."
-    },
-    "body": {
-      "type": "object",
-      "description": "Key material.",
-      "properties": {
-        "alg": {
-          "type": "string",
-          "description": "Key algorithm.",
-          "enum": ["ed25519"]
-        },
-        "key": {
-          "type": "string",
-          "description": "Base64-encoded public key."
-        }
-      },
-      "required": ["alg", "key"],
-      "additionalProperties": false
-    }
-  },
-  "required": ["command", "body"],
-  "examples": [
-    { "command": "PUBKEY", "from": "alice", "body": { "alg": "ed25519", "key": "base64-encoded-pubkey" } },
-    { "command": "PUBKEY", "from": "alice", "to": "#general", "body": { "alg": "ed25519", "key": "base64-encoded-pubkey" } }
-  ]
-}

schema/commands/QUIT.json

@@ -2,20 +2,20 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/commands/QUIT.json",
   "title": "QUIT",
-  "description": "User disconnected. S2C only. RFC 1459 §4.1.6.",
+  "description": "A user left the server. A client sends it to end its session. The server sends it to the users who shared a channel with the user who left. RFC 1459 §4.1.6.",
   "$ref": "../message.json",
   "properties": {
     "command": { "const": "QUIT" },
-    "from": { "type": "string", "description": "Nick that quit." },
+    "from": { "type": "string", "description": "The nick that quit. The server sets it." },
     "body": {
       "type": "array",
       "items": { "type": "string" },
-      "description": "Optional quit reason.",
-      "maxItems": 1
+      "description": "The reason for leaving. A client may send one as the first string, and the server uses 'Client quit' when it does not. The server always sends one string."
     }
   },
-  "required": ["command", "from"],
+  "required": ["command"],
   "examples": [
-    { "command": "QUIT", "from": "alice", "body": ["Connection reset"] }
+    { "command": "QUIT", "body": ["Gone for the day"] },
+    { "command": "QUIT", "from": "alice", "body": ["Connection closed"] }
   ]
 }

schema/commands/TOPIC.json

@@ -2,20 +2,24 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/commands/TOPIC.json",
   "title": "TOPIC",
-  "description": "Get or set channel topic. C2S: set topic (body present) or query (body absent). S2C: topic change notification. RFC 1459 §4.2.4.",
+  "description": "Set a channel's topic. A client sends it to set the topic. The server sends it to every member of the channel when the topic changes. RFC 1459 §4.2.4.",
   "$ref": "../message.json",
   "properties": {
     "command": { "const": "TOPIC" },
-    "from": { "type": "string", "description": "Nick that changed the topic (S2C)." },
-    "to": { "type": "string", "description": "Channel name.", "pattern": "^#[a-zA-Z0-9_-]+$" },
+    "from": { "type": "string", "description": "The nick that set the topic. The server sets it." },
+    "to": {
+      "type": "string",
+      "description": "The channel name. The server adds the # if a client leaves it out.",
+      "pattern": "^#?[a-zA-Z0-9_-]{1,63}$"
+    },
     "body": {
       "type": "array",
       "items": { "type": "string" },
-      "description": "New topic text (single-element array). Empty array clears the topic.",
-      "maxItems": 1
+      "description": "The new topic. The server joins a client's strings with spaces, and sends the topic as one string. [\"\"] clears the topic.",
+      "minItems": 1
     }
   },
-  "required": ["command", "to"],
+  "required": ["command", "to", "body"],
   "examples": [
     { "command": "TOPIC", "from": "alice", "to": "#general", "body": ["Welcome to the channel"] }
   ]

schema/message.json

@@ -2,67 +2,55 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/message.json",
   "title": "IRC Message Envelope",
-  "description": "Base envelope for all messages. Mirrors IRC wire format (RFC 1459/2812) encoded as JSON over HTTP. The 'command' field carries either an IRC command name (PRIVMSG, JOIN, etc.) or a three-digit numeric reply code (001, 353, 433, etc.).",
+  "description": "Every message in the HTTP API is one JSON object with these fields. Only 'command' is always present.",
   "type": "object",
   "properties": {
     "id": {
       "type": "string",
       "format": "uuid",
-      "description": "Server-assigned message UUID. Present on all server-originated messages."
+      "description": "The message's UUID, which the server assigns. Present on every message the server queues for a client."
     },
     "command": {
       "type": "string",
-      "description": "IRC command name (PRIVMSG, JOIN, NICK, etc.) or three-digit numeric reply code (001, 353, 433, etc.).",
-      "examples": ["PRIVMSG", "JOIN", "001", "353", "433"]
+      "description": "An IRC command name, such as PRIVMSG, or the name of a numeric reply, such as RPL_WELCOME. The server reads a client's command in any case and sends it in upper case.",
+      "examples": ["PRIVMSG", "JOIN", "RPL_WELCOME", "ERR_NICKNAMEINUSE"]
+    },
+    "code": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 999,
+      "description": "The number of a numeric reply, such as 1 for RPL_WELCOME. Absent on other messages."
     },
     "from": {
       "type": "string",
-      "description": "Source — nick for user messages, server name for server messages. Equivalent to IRC prefix."
+      "description": "The sender's nick, or the server name on a numeric reply or a PONG. The server sets it and ignores it from a client."
     },
     "to": {
       "type": "string",
-      "description": "Target — channel (#name) or nick. Equivalent to first IRC parameter for most commands."
+      "description": "The target: a channel name, such as #general, or a nick. A WALLOPS has * here."
     },
     "params": {
       "type": "array",
       "items": { "type": "string" },
-      "description": "Additional parameters (used primarily by numeric replies). Equivalent to IRC middle parameters."
+      "description": "The message's other parameters, in order. KICK events and many numeric replies have it. The server ignores it from a client."
     },
     "body": {
-      "oneOf": [
-        {
       "type": "array",
       "items": { "type": "string" },
-          "description": "Array of strings (one per line for text messages)."
-        },
-        {
-          "type": "object",
-          "description": "Structured data (e.g. PUBKEY key material).",
-          "additionalProperties": true
-        }
-      ],
-      "description": "Message body. MUST be an array or object, never a raw string. Arrays represent lines of text; objects carry structured data. This enables deterministic canonicalization (RFC 8785 JCS) for signing."
+      "description": "An array of strings, never a bare string. In a PRIVMSG or NOTICE, each string is one line of text."
     },
     "ts": {
       "type": "string",
       "format": "date-time",
-      "description": "Server-assigned timestamp (ISO 8601). Not present in original IRC; added for HTTP transport."
+      "description": "The time the server stored the message, as an RFC 3339 time in UTC."
     },
     "meta": {
       "type": "object",
-      "description": "Extensible metadata. Used for signatures (meta.sig, meta.alg), hashes (meta.hash), and client extensions.",
+      "description": "An object of extra data. Every message the server queues for a client has meta, which is {} when there is none. The server keeps a client's meta only on a PRIVMSG or NOTICE, and relays it unchanged.",
       "properties": {
-        "sig": {
+        "hashcash": {
           "type": "string",
-          "description": "Base64-encoded cryptographic signature over the canonical message form."
-        },
-        "alg": {
-          "type": "string",
-          "description": "Signature algorithm (e.g. 'ed25519')."
-        },
-        "hash": {
-          "type": "string",
-          "description": "Hash of the canonical message form (e.g. 'sha256:base64...')."
+          "description": "A hashcash stamp. A PRIVMSG to a channel with mode +H needs one."
         }
       },
       "additionalProperties": true

schema/numerics/001.json

@@ -2,32 +2,45 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/numerics/001.json",
   "title": "001 RPL_WELCOME",
-  "description": "Welcome message sent after successful session creation. RFC 2812 \u00a75.1.",
+  "description": "Welcomes the user. Sent after a session is created, after a login, and in answer to MOTD. RFC 2812 §5.1.",
   "$ref": "../message.json",
   "properties": {
     "command": {
-      "const": "001"
+      "const": "RPL_WELCOME"
+    },
+    "code": {
+      "const": 1
+    },
+    "from": {
+      "type": "string",
+      "description": "The server name."
     },
     "to": {
       "type": "string",
-      "description": "Target nick."
+      "description": "The user's nick."
     },
     "body": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "Welcome text lines."
+      "description": "One string: 'Welcome to the network, ' and the user's nick.",
+      "minItems": 1,
+      "maxItems": 1
     }
   },
   "required": [
     "command",
+    "code",
+    "from",
     "to",
     "body"
   ],
   "examples": [
     {
-      "command": "001",
+      "command": "RPL_WELCOME",
+      "code": 1,
+      "from": "neoirc",
       "to": "alice",
       "body": [
         "Welcome to the network, alice"

schema/numerics/002.json

@@ -2,34 +2,48 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/numerics/002.json",
   "title": "002 RPL_YOURHOST",
-  "description": "Server host info sent after session creation. RFC 2812 \u00a75.1.",
+  "description": "The server's name and version. Sent right after RPL_WELCOME. RFC 2812 §5.1.",
   "$ref": "../message.json",
   "properties": {
     "command": {
-      "const": "002"
+      "const": "RPL_YOURHOST"
+    },
+    "code": {
+      "const": 2
+    },
+    "from": {
+      "type": "string",
+      "description": "The server name."
     },
     "to": {
-      "type": "string"
+      "type": "string",
+      "description": "The user's nick."
     },
     "body": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "Host info lines."
+      "description": "One string: 'Your host is ', the server name, ', running version ' and the version.",
+      "minItems": 1,
+      "maxItems": 1
     }
   },
   "required": [
     "command",
+    "code",
+    "from",
     "to",
     "body"
   ],
   "examples": [
     {
-      "command": "002",
+      "command": "RPL_YOURHOST",
+      "code": 2,
+      "from": "neoirc",
       "to": "alice",
       "body": [
-        "Your host is neoirc.example.com, running version 0.1.0"
+        "Your host is neoirc, running version dev"
       ]
     }
   ]

schema/numerics/003.json

@@ -2,31 +2,45 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/numerics/003.json",
   "title": "003 RPL_CREATED",
-  "description": "Server creation date. RFC 2812 \u00a75.1.",
+  "description": "The date the server last started. Sent right after RPL_YOURHOST. RFC 2812 §5.1.",
   "$ref": "../message.json",
   "properties": {
     "command": {
-      "const": "003"
+      "const": "RPL_CREATED"
+    },
+    "code": {
+      "const": 3
+    },
+    "from": {
+      "type": "string",
+      "description": "The server name."
     },
     "to": {
-      "type": "string"
+      "type": "string",
+      "description": "The user's nick."
     },
     "body": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "Text lines."
+      "description": "One string: 'This server was created ' and the start date as YYYY-MM-DD.",
+      "minItems": 1,
+      "maxItems": 1
     }
   },
   "required": [
     "command",
+    "code",
+    "from",
     "to",
     "body"
   ],
   "examples": [
     {
-      "command": "003",
+      "command": "RPL_CREATED",
+      "code": 3,
+      "from": "neoirc",
       "to": "alice",
       "body": [
         "This server was created 2026-02-01"

schema/numerics/004.json

@@ -2,37 +2,64 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/numerics/004.json",
   "title": "004 RPL_MYINFO",
-  "description": "Server info (name, version, available modes). RFC 2812 \u00a75.1.",
+  "description": "The server's name, its version, and its lists of user and channel modes. Sent right after RPL_CREATED. RFC 2812 §5.1.",
   "$ref": "../message.json",
   "properties": {
     "command": {
-      "const": "004"
+      "const": "RPL_MYINFO"
+    },
+    "code": {
+      "const": 4
+    },
+    "from": {
+      "type": "string",
+      "description": "The server name."
     },
     "to": {
-      "type": "string"
+      "type": "string",
+      "description": "The user's nick."
     },
     "params": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "[server_name, version, user_modes, channel_modes]."
+      "description": "The server name, the version, the user modes 'ow' and the channel modes 'Hbiklmnostv'.",
+      "minItems": 4,
+      "maxItems": 4
+    },
+    "body": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "One empty string.",
+      "minItems": 1,
+      "maxItems": 1
     }
   },
   "required": [
     "command",
+    "code",
+    "from",
     "to",
-    "params"
+    "params",
+    "body"
   ],
   "examples": [
     {
-      "command": "004",
+      "command": "RPL_MYINFO",
+      "code": 4,
+      "from": "neoirc",
       "to": "alice",
       "params": [
-        "neoirc.example.com",
-        "0.1.0",
-        "o",
-        "imnst+ov"
+        "neoirc",
+        "dev",
+        "ow",
+        "Hbiklmnostv"
+      ],
+      "body": [
+        ""
       ]
     }
   ]

schema/numerics/322.json

@@ -2,38 +2,55 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/numerics/322.json",
   "title": "322 RPL_LIST",
-  "description": "Channel list entry. One per channel in response to LIST. RFC 1459 \u00a76.2.",
+  "description": "One channel in the answer to LIST. The answer has one per channel, except a secret channel, one with mode +s, that the user is not on. RFC 1459 §6.2.",
   "$ref": "../message.json",
   "properties": {
     "command": {
-      "const": "322"
+      "const": "RPL_LIST"
+    },
+    "code": {
+      "const": 322
+    },
+    "from": {
+      "type": "string",
+      "description": "The server name."
     },
     "to": {
-      "type": "string"
+      "type": "string",
+      "description": "The user's nick."
     },
     "params": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "[channel, visible_count]."
+      "description": "The channel name and its number of members.",
+      "minItems": 2,
+      "maxItems": 2
     },
     "body": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "Channel topic."
+      "description": "One string: the channel's topic, empty when it has none.",
+      "minItems": 1,
+      "maxItems": 1
     }
   },
   "required": [
     "command",
+    "code",
+    "from",
     "to",
-    "params"
+    "params",
+    "body"
   ],
   "examples": [
     {
-      "command": "322",
+      "command": "RPL_LIST",
+      "code": 322,
+      "from": "neoirc",
       "to": "alice",
       "params": [
         "#general",

schema/numerics/323.json

@@ -2,26 +2,49 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/numerics/323.json",
   "title": "323 RPL_LISTEND",
-  "description": "End of channel list. RFC 1459 \u00a76.2.",
+  "description": "The end of the answer to LIST. RFC 1459 §6.2.",
   "$ref": "../message.json",
   "properties": {
     "command": {
-      "const": "323"
+      "const": "RPL_LISTEND"
+    },
+    "code": {
+      "const": 323
+    },
+    "from": {
+      "type": "string",
+      "description": "The server name."
     },
     "to": {
-      "type": "string"
+      "type": "string",
+      "description": "The user's nick."
     },
     "body": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "End of /LIST",
+      "description": "One string: 'End of /LIST'.",
+      "minItems": 1,
       "maxItems": 1
     }
   },
   "required": [
     "command",
-    "to"
+    "code",
+    "from",
+    "to",
+    "body"
+  ],
+  "examples": [
+    {
+      "command": "RPL_LISTEND",
+      "code": 323,
+      "from": "neoirc",
+      "to": "alice",
+      "body": [
+        "End of /LIST"
+      ]
+    }
   ]
 }

schema/numerics/332.json

@@ -2,39 +2,55 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/numerics/332.json",
   "title": "332 RPL_TOPIC",
-  "description": "Channel topic (sent on JOIN or TOPIC query). RFC 1459 \u00a76.2.",
+  "description": "A channel's topic. Sent to a client after it sets the topic, and after it joins a channel that has one. Also sent for each of a session's channels that has one after a login, and for GET /api/v1/state?initChannelState=1. RFC 1459 §6.2.",
   "$ref": "../message.json",
   "properties": {
     "command": {
-      "const": "332"
+      "const": "RPL_TOPIC"
+    },
+    "code": {
+      "const": 332
+    },
+    "from": {
+      "type": "string",
+      "description": "The server name."
     },
     "to": {
-      "type": "string"
+      "type": "string",
+      "description": "The user's nick."
     },
     "params": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "[channel]."
+      "description": "The channel name.",
+      "minItems": 1,
+      "maxItems": 1
     },
     "body": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "Topic text."
+      "description": "One string: the topic.",
+      "minItems": 1,
+      "maxItems": 1
     }
   },
   "required": [
     "command",
+    "code",
+    "from",
     "to",
     "params",
     "body"
   ],
   "examples": [
     {
-      "command": "332",
+      "command": "RPL_TOPIC",
+      "code": 332,
+      "from": "neoirc",
       "to": "alice",
       "params": [
         "#general"

schema/numerics/353.json

@@ -2,46 +2,62 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/numerics/353.json",
   "title": "353 RPL_NAMREPLY",
-  "description": "Channel member list. Sent on JOIN or NAMES query. RFC 1459 \u00a76.2.",
+  "description": "A channel's members. Sent to a client after it joins a channel, and in answer to NAMES. Also sent for each of a session's channels after a login, and for GET /api/v1/state?initChannelState=1. RFC 1459 §6.2.",
   "$ref": "../message.json",
   "properties": {
     "command": {
-      "const": "353"
+      "const": "RPL_NAMREPLY"
+    },
+    "code": {
+      "const": 353
+    },
+    "from": {
+      "type": "string",
+      "description": "The server name."
     },
     "to": {
-      "type": "string"
+      "type": "string",
+      "description": "The user's nick."
     },
     "params": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "[channel_type, channel]. channel_type: = (public), * (private), @ (secret)."
+      "description": "'=' and the channel name. The server always sends '='.",
+      "minItems": 2,
+      "maxItems": 2
     },
     "body": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "Space-separated list of nicks. Prefixed with @ for ops, + for voiced."
+      "description": "One string: the members as nick!user@host, separated by spaces. '@' comes before a channel operator and '+' before a voiced member. The host is '*' when the server does not know it.",
+      "minItems": 1,
+      "maxItems": 1
     }
   },
   "required": [
     "command",
+    "code",
+    "from",
     "to",
     "params",
     "body"
   ],
   "examples": [
     {
-      "command": "353",
+      "command": "RPL_NAMREPLY",
+      "code": 353,
+      "from": "neoirc",
       "to": "alice",
       "params": [
         "=",
         "#general"
       ],
       "body": [
-        "@op1 alice bob +voiced1"
+        "@op1!op1@host1 alice!alice@host2 +bob!bob@host3"
       ]
     }
   ]

schema/numerics/366.json

@@ -2,34 +2,62 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/numerics/366.json",
   "title": "366 RPL_ENDOFNAMES",
-  "description": "End of NAMES list. RFC 1459 \u00a76.2.",
+  "description": "The end of a channel's member list. It comes after the RPL_NAMREPLY for the channel. RFC 1459 §6.2.",
   "$ref": "../message.json",
   "properties": {
     "command": {
-      "const": "366"
+      "const": "RPL_ENDOFNAMES"
+    },
+    "code": {
+      "const": 366
+    },
+    "from": {
+      "type": "string",
+      "description": "The server name."
     },
     "to": {
-      "type": "string"
+      "type": "string",
+      "description": "The user's nick."
     },
     "params": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "[channel]."
+      "description": "The channel name.",
+      "minItems": 1,
+      "maxItems": 1
     },
     "body": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "End of /NAMES list",
+      "description": "One string: 'End of /NAMES list'.",
+      "minItems": 1,
       "maxItems": 1
     }
   },
   "required": [
     "command",
+    "code",
+    "from",
     "to",
-    "params"
+    "params",
+    "body"
+  ],
+  "examples": [
+    {
+      "command": "RPL_ENDOFNAMES",
+      "code": 366,
+      "from": "neoirc",
+      "to": "alice",
+      "params": [
+        "#general"
+      ],
+      "body": [
+        "End of /NAMES list"
+      ]
+    }
   ]
 }

schema/numerics/372.json

@@ -2,31 +2,45 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/numerics/372.json",
   "title": "372 RPL_MOTD",
-  "description": "MOTD line. One message per line of the MOTD. RFC 2812 \u00a75.1.",
+  "description": "One line of the message of the day. The server sends one per line, after RPL_MOTDSTART. RFC 2812 §5.1.",
   "$ref": "../message.json",
   "properties": {
     "command": {
-      "const": "372"
+      "const": "RPL_MOTD"
+    },
+    "code": {
+      "const": 372
+    },
+    "from": {
+      "type": "string",
+      "description": "The server name."
     },
     "to": {
-      "type": "string"
+      "type": "string",
+      "description": "The user's nick."
     },
     "body": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "MOTD line text (prefixed with '- ')."
+      "description": "One string: '- ' and the line.",
+      "minItems": 1,
+      "maxItems": 1
     }
   },
   "required": [
     "command",
+    "code",
+    "from",
     "to",
     "body"
   ],
   "examples": [
     {
-      "command": "372",
+      "command": "RPL_MOTD",
+      "code": 372,
+      "from": "neoirc",
       "to": "alice",
       "body": [
         "- Welcome to our server!"

schema/numerics/375.json

@@ -2,25 +2,49 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/numerics/375.json",
   "title": "375 RPL_MOTDSTART",
-  "description": "Start of MOTD. RFC 2812 \u00a75.1.",
+  "description": "The start of the message of the day. Sent after RPL_LUSERME (255) when the server has a message of the day. RFC 2812 §5.1.",
   "$ref": "../message.json",
   "properties": {
     "command": {
-      "const": "375"
+      "const": "RPL_MOTDSTART"
+    },
+    "code": {
+      "const": 375
+    },
+    "from": {
+      "type": "string",
+      "description": "The server name."
     },
     "to": {
-      "type": "string"
+      "type": "string",
+      "description": "The user's nick."
     },
     "body": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "Text lines."
+      "description": "One string: '- ', the server name and ' Message of the Day -'.",
+      "minItems": 1,
+      "maxItems": 1
     }
   },
   "required": [
     "command",
-    "to"
+    "code",
+    "from",
+    "to",
+    "body"
+  ],
+  "examples": [
+    {
+      "command": "RPL_MOTDSTART",
+      "code": 375,
+      "from": "neoirc",
+      "to": "alice",
+      "body": [
+        "- neoirc Message of the Day -"
+      ]
+    }
   ]
 }

schema/numerics/376.json

@@ -2,26 +2,49 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/numerics/376.json",
   "title": "376 RPL_ENDOFMOTD",
-  "description": "End of MOTD. RFC 2812 \u00a75.1.",
+  "description": "The end of the message of the day. RFC 2812 §5.1.",
   "$ref": "../message.json",
   "properties": {
     "command": {
-      "const": "376"
+      "const": "RPL_ENDOFMOTD"
+    },
+    "code": {
+      "const": 376
+    },
+    "from": {
+      "type": "string",
+      "description": "The server name."
     },
     "to": {
-      "type": "string"
+      "type": "string",
+      "description": "The user's nick."
     },
     "body": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "End of /MOTD command",
+      "description": "One string: 'End of /MOTD command.'.",
+      "minItems": 1,
       "maxItems": 1
     }
   },
   "required": [
     "command",
-    "to"
+    "code",
+    "from",
+    "to",
+    "body"
+  ],
+  "examples": [
+    {
+      "command": "RPL_ENDOFMOTD",
+      "code": 376,
+      "from": "neoirc",
+      "to": "alice",
+      "body": [
+        "End of /MOTD command."
+      ]
+    }
   ]
 }

schema/numerics/401.json

@@ -2,45 +2,61 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/numerics/401.json",
   "title": "401 ERR_NOSUCHNICK",
-  "description": "No such nick/channel. RFC 1459 \u00a76.1.",
+  "description": "No user has that nick. RFC 1459 §6.1.",
   "$ref": "../message.json",
   "properties": {
     "command": {
-      "const": "401"
+      "const": "ERR_NOSUCHNICK"
+    },
+    "code": {
+      "const": 401
+    },
+    "from": {
+      "type": "string",
+      "description": "The server name."
     },
     "to": {
-      "type": "string"
+      "type": "string",
+      "description": "The user's nick."
     },
     "params": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "[target_nick]."
+      "description": "The nick that was not found.",
+      "minItems": 1,
+      "maxItems": 1
     },
     "body": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "No such nick/channel",
+      "description": "One string: 'No such nick' in answer to a PRIVMSG or NOTICE, and 'No such nick/channel' in answer to anything else.",
+      "minItems": 1,
       "maxItems": 1
     }
   },
   "required": [
     "command",
+    "code",
+    "from",
     "to",
-    "params"
+    "params",
+    "body"
   ],
   "examples": [
     {
-      "command": "401",
+      "command": "ERR_NOSUCHNICK",
+      "code": 401,
+      "from": "neoirc",
       "to": "alice",
       "params": [
         "bob"
       ],
       "body": [
-        "No such nick/channel"
+        "No such nick"
       ]
     }
   ]

schema/numerics/403.json

@@ -2,39 +2,55 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/numerics/403.json",
   "title": "403 ERR_NOSUCHCHANNEL",
-  "description": "No such channel. RFC 1459 \u00a76.1.",
+  "description": "No channel has that name. A JOIN with a channel name that the server does not allow gets it too. RFC 1459 §6.1.",
   "$ref": "../message.json",
   "properties": {
     "command": {
-      "const": "403"
+      "const": "ERR_NOSUCHCHANNEL"
+    },
+    "code": {
+      "const": 403
+    },
+    "from": {
+      "type": "string",
+      "description": "The server name."
     },
     "to": {
-      "type": "string"
+      "type": "string",
+      "description": "The user's nick."
     },
     "params": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "[channel_name]."
+      "description": "The channel name.",
+      "minItems": 1,
+      "maxItems": 1
     },
     "body": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "No such channel",
+      "description": "One string: 'No such channel'.",
+      "minItems": 1,
       "maxItems": 1
     }
   },
   "required": [
     "command",
+    "code",
+    "from",
     "to",
-    "params"
+    "params",
+    "body"
   ],
   "examples": [
     {
-      "command": "403",
+      "command": "ERR_NOSUCHCHANNEL",
+      "code": 403,
+      "from": "neoirc",
       "to": "alice",
       "params": [
         "#nonexistent"

schema/numerics/433.json

@@ -2,42 +2,58 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/numerics/433.json",
   "title": "433 ERR_NICKNAMEINUSE",
-  "description": "Nickname is already in use. RFC 1459 \u00a76.1.",
+  "description": "Another user has the nick. Sent in answer to a NICK. RFC 1459 §6.1.",
   "$ref": "../message.json",
   "properties": {
     "command": {
-      "const": "433"
+      "const": "ERR_NICKNAMEINUSE"
+    },
+    "code": {
+      "const": 433
+    },
+    "from": {
+      "type": "string",
+      "description": "The server name."
     },
     "to": {
-      "type": "string"
+      "type": "string",
+      "description": "The user's nick, which has not changed."
     },
     "params": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "[requested_nick]."
+      "description": "The nick that was asked for.",
+      "minItems": 1,
+      "maxItems": 1
     },
     "body": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "Nickname is already in use",
+      "description": "One string: 'Nickname is already in use'.",
+      "minItems": 1,
       "maxItems": 1
     }
   },
   "required": [
     "command",
+    "code",
+    "from",
     "to",
-    "params"
+    "params",
+    "body"
   ],
   "examples": [
     {
-      "command": "433",
-      "to": "*",
+      "command": "ERR_NICKNAMEINUSE",
+      "code": 433,
+      "from": "neoirc",
+      "to": "alice",
       "params": [
-        "alice"
+        "bob"
       ],
       "body": [
         "Nickname is already in use"

schema/numerics/442.json

@@ -2,34 +2,62 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/numerics/442.json",
   "title": "442 ERR_NOTONCHANNEL",
-  "description": "You're not on that channel. RFC 1459 \u00a76.1.",
+  "description": "The user is not on that channel. RFC 1459 §6.1.",
   "$ref": "../message.json",
   "properties": {
     "command": {
-      "const": "442"
+      "const": "ERR_NOTONCHANNEL"
+    },
+    "code": {
+      "const": 442
+    },
+    "from": {
+      "type": "string",
+      "description": "The server name."
     },
     "to": {
-      "type": "string"
+      "type": "string",
+      "description": "The user's nick."
     },
     "params": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "[channel]."
+      "description": "The channel name.",
+      "minItems": 1,
+      "maxItems": 1
     },
     "body": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "You're not on that channel",
+      "description": "One string: 'You're not on that channel'.",
+      "minItems": 1,
       "maxItems": 1
     }
   },
   "required": [
     "command",
+    "code",
+    "from",
     "to",
-    "params"
+    "params",
+    "body"
+  ],
+  "examples": [
+    {
+      "command": "ERR_NOTONCHANNEL",
+      "code": 442,
+      "from": "neoirc",
+      "to": "alice",
+      "params": [
+        "#general"
+      ],
+      "body": [
+        "You're not on that channel"
+      ]
+    }
   ]
 }

schema/numerics/482.json

@@ -2,34 +2,62 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/numerics/482.json",
   "title": "482 ERR_CHANOPRIVSNEEDED",
-  "description": "You're not channel operator. RFC 1459 \u00a76.1.",
+  "description": "The user is not a channel operator, and the command needs one. RFC 1459 §6.1.",
   "$ref": "../message.json",
   "properties": {
     "command": {
-      "const": "482"
+      "const": "ERR_CHANOPRIVSNEEDED"
+    },
+    "code": {
+      "const": 482
+    },
+    "from": {
+      "type": "string",
+      "description": "The server name."
     },
     "to": {
-      "type": "string"
+      "type": "string",
+      "description": "The user's nick."
     },
     "params": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "[channel]."
+      "description": "The channel name.",
+      "minItems": 1,
+      "maxItems": 1
     },
     "body": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "You're not channel operator",
+      "description": "One string: 'You're not channel operator'.",
+      "minItems": 1,
       "maxItems": 1
     }
   },
   "required": [
     "command",
+    "code",
+    "from",
     "to",
-    "params"
+    "params",
+    "body"
+  ],
+  "examples": [
+    {
+      "command": "ERR_CHANOPRIVSNEEDED",
+      "code": 482,
+      "from": "neoirc",
+      "to": "alice",
+      "params": [
+        "#general"
+      ],
+      "body": [
+        "You're not channel operator"
+      ]
+    }
   ]
 }