serverless-ircd 0.4.0 → 0.6.0

package/packages/irc-core/src/commands/rehash.ts

@@ -0,0 +1,119 @@
+/**
+ * Pure reducer for the IRC `REHASH` command (oper-gated config reload).
+ *
+ * PLAN §2.1 location-of-authority: REHASH runs in the Connection entity. The
+ * reducer is pure — it only enforces the oper gate and emits the
+ * `382 RPL_REHASHING` reply. The actual config re-fetch is a request/response
+ * side effect (re-invoke the adapter's bound config loader and swap the live
+ * {@link ServerConfig} reference on the actor), so — exactly like
+ * `lookupNick` / `getConnection` — it is NOT modelled as a fire-and-forget
+ * `Effect`; the actor layer performs it and surfaces success/failure back to
+ * the oper via a second `382` line on failure.
+ *
+ * Wire format:
+ *   - `REHASH` (no params).
+ *   - `382 RPL_REHASHING`:
+ *     `:<server> 382 <nick> :Rehashing from <source>`
+ *   - `481 ERR_NOPRIVILEGES`:
+ *     `:<server> 481 <nick> :Permission Denied - You're not an IRC operator`
+ *
+ * Behaviour:
+ *   - Non-oper → `481 ERR_NOPRIVILEGES`; no reload is signalled.
+ *   - Oper → emits `382` noting the bound config source and signals
+ *     `shouldReload: true`. The actor re-invokes its loader and swaps the
+ *     live config; on failure the previous config stays in effect and a
+ *     graceful error-suffixed `382` follows (handled by the actor).
+ */
+
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import type { IrcMessage } from '../protocol/messages.js';
+import { Numerics } from '../protocol/numerics.js';
+import type { ConnectionState } from '../state/connection.js';
+import type { Ctx } from '../types.js';
+
+/** Fixed text emitted for `481 ERR_NOPRIVILEGES` (matches `mode.ts`). */
+const NOPRIVILEGES_TRAILING_TEXT = "Permission Denied - You're not an IRC operator";
+
+/**
+ * Result of {@link rehashReducer}. Adds a `shouldReload` intent flag on top of
+ * the standard reducer shape so the actor layer knows whether to perform the
+ * async config re-fetch (oper gate passed) without re-deriving the gate.
+ */
+export interface RehashResult {
+  state: ConnectionState;
+  effects: EffectType[];
+  shouldReload: boolean;
+}
+
+/**
+ * Composes the trailing text for the `382 RPL_REHASHING` line. The success
+ * form notes the bound config source; the failure form (used by the actor on
+ * reload rejection) appends the error so the oper sees what went wrong
+ * without being disconnected.
+ */
+export function buildRehashTrailing(configSource: string, error?: string): string {
+  const base = `Rehashing from ${configSource}`;
+  return error === undefined ? base : `${base} failed: ${error}`;
+}
+
+/**
+ * Renders the full `:<server> 382 <nick> :<trailing>` wire line. Shared by
+ * the reducer (optimistic success line) and the actor (error-suffixed line
+ * on reload failure) so the two paths cannot drift in formatting.
+ */
+export function rehashLine(
+  serverName: string,
+  nick: string,
+  configSource: string,
+  error?: string,
+): RawLine {
+  const code = Numerics.RPL_REHASHING.toString().padStart(3, '0');
+  return { text: `:${serverName} ${code} ${nick} :${buildRehashTrailing(configSource, error)}` };
+}
+
+/**
+ * Handles `REHASH`.
+ *
+ * Enforces the oper gate, stamps `lastSeen`, and — for an oper — emits the
+ * `382 RPL_REHASHING` reply and signals the actor to perform the reload via
+ * `shouldReload`. The reducer never performs IO.
+ */
+export function rehashReducer(
+  state: ConnectionState,
+  _msg: IrcMessage,
+  ctx: Ctx,
+  configSource: string,
+): RehashResult {
+  state.lastSeen = ctx.clock.now();
+
+  if (!state.userModes.oper) {
+    return {
+      state,
+      effects: [
+        Effect.send(ctx.connId, [
+          numericLine(ctx, Numerics.ERR_NOPRIVILEGES, NOPRIVILEGES_TRAILING_TEXT),
+        ]),
+      ],
+      shouldReload: false,
+    };
+  }
+
+  const nick = ctx.connection.nick ?? '*';
+  return {
+    state,
+    effects: [Effect.send(ctx.connId, [rehashLine(ctx.serverName, nick, configSource)])],
+    shouldReload: true,
+  };
+}
+
+/**
+ * Builds a `:<server> <code> <nick> :<trailing>` line. The nick falls back to
+ * `*` for an unregistered connection, matching the rest of the codebase's
+ * numeric formatting.
+ */
+function numericLine(ctx: Ctx, code: number, trailing: string): RawLine {
+  const nick = ctx.connection.nick ?? '*';
+  const codeStr = code.toString().padStart(3, '0');
+  return { text: [`:${ctx.serverName}`, codeStr, nick, `:${trailing}`].join(' ') };
+}

package/packages/irc-core/src/commands/sasl.ts

@@ -35,6 +35,9 @@ import { Numerics } from '../protocol/numerics.js';
 import { hostmaskOf } from '../state/connection.js';
 import type { ConnectionState } from '../state/connection.js';
 import type { Ctx, Reducer } from '../types.js';
+import { emitAccountNotify } from './account-notify.js';
+import { nowAwayLine, replayPersistedAway } from './pre-away.js';
+import { seedReadMarkers } from './read-marker.js';
 
 /** Per-ircdocs.horse: a single `AUTHENTICATE` payload chunk is at most 400 bytes. */
 const SASL_CHUNK_BYTES = 400;
@@ -218,9 +221,29 @@ function applyResult(
 
   if (result.ok) {
     state.account = result.account;
+    // IRCv3 draft/read-marker: restore the user's per-channel last-read
+    // markers from the persisted store so a reconnect resumes at their
+    // last read position. No-op when no ReadMarkerStore is bound.
+    if (ctx.readMarkers !== undefined) {
+      seedReadMarkers(state, ctx.readMarkers, result.account);
+    }
+    // IRCv3 draft/pre-away: replay the user's persisted away reason onto
+    // the fresh connection so a reconnect restores the away state, and
+    // emit the 306 numeric so the user sees they are still away. No-op
+    // when no AwayStore is bound or no reason is stored.
+    const replayedAway =
+      ctx.away !== undefined ? replayPersistedAway(state, ctx.away, result.account) : undefined;
+    const awayEffects: EffectType[] =
+      replayedAway !== undefined
+        ? [Effect.send(ctx.connId, [nowAwayLine(state, ctx.serverName)])]
+        : [];
     return {
       state,
-      effects: [Effect.send(ctx.connId, [loggedIn(ctx, result.account), saslSuccess(ctx)])],
+      effects: [
+        Effect.send(ctx.connId, [loggedIn(ctx, result.account), saslSuccess(ctx)]),
+        ...awayEffects,
+        ...emitAccountNotify({ conn: state, account: result.account }),
+      ],
     };
   }
   return { state, effects: [Effect.send(ctx.connId, [saslFail(ctx)])] };

package/packages/irc-core/src/commands/setname.ts

@@ -0,0 +1,109 @@
+/**
+ * Pure reducer for the IRC `SETNAME` command (RFC 2812 §4.1.7).
+ *
+ * PLAN §2.1 location-of-authority: SETNAME runs in the Connection entity.
+ * The reducer mutates `state.realname` (the GECOS field originally set by
+ * the `USER` reducer) and performs no IO.
+ *
+ * Wire format:
+ *   - `SETNAME :<realname>` — replaces `state.realname`.
+ *   - `461 ERR_NEEDMOREPARAMS` when the realname is missing/empty.
+ *   - `451 ERR_NOTREGISTERED` when issued before registration completes.
+ *
+ * Broadcast decision: there is no standard IRCv3 cap for relaying a
+ * realname change (the `chghost` cap covers user/host, not realname), so
+ * v1 updates `state.realname` silently. A subsequent `WHOIS` reflects the
+ * new value in `311 RPL_WHOISUSER`. A `draft/setname` relay cap is a
+ * documented follow-up.
+ *
+ * Length cap: registration-time `USER` does not enforce a realname length
+ * cap, so this command applies its own via `serverConfig.realnameLen`
+ * (falling back to {@link DEFAULT_REALNAME_LEN}). An over-cap value is
+ * rejected with `432 ERR_ERRONEUSNICKNAME` — the same numeric registration
+ * uses for an over-length `NICK` (the codebase's only registration-time
+ * "value rejected for length" precedent). The offending value is NOT
+ * echoed back so a client cannot amplify a multi-kilobyte payload via the
+ * error reply. Truncation (as `TOPIC` does) is deliberately not used: the
+ * spec frames an over-long realname as a rejection, not a silent trim.
+ */
+
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import { Numerics } from '../protocol/numerics.js';
+import type { ConnectionState } from '../state/connection.js';
+import type { Ctx, Reducer } from '../types.js';
+
+/**
+ * Built-in realname length cap when `serverConfig.realnameLen` is unset.
+ * Matches the schema default and the common ircd-seven GECOS ceiling.
+ */
+const DEFAULT_REALNAME_LEN = 50;
+
+/** Fixed trailing text for `461 ERR_NEEDMOREPARAMS` (matches `USER`/`PASS`). */
+const NEEDMOREPARAMS_TRAILING = 'Not enough parameters';
+
+/** Fixed trailing text for `451 ERR_NOTREGISTERED`. */
+const NOTREGISTERED_TRAILING = 'You have not registered';
+
+/** Fixed trailing text for the over-cap `432` rejection. */
+const ERRONEOUS_REALNAME_TRAILING = 'Erroneous realname';
+
+/**
+ * Handles `SETNAME :<realname>`.
+ *
+ * Stamps `lastSeen`, enforces the registration + length gates, and on
+ * success replaces `state.realname` with no broadcast. The reducer never
+ * performs IO.
+ */
+export const setnameReducer: Reducer<ConnectionState> = (state, msg, ctx) => {
+  state.lastSeen = ctx.clock.now();
+
+  const effects: EffectType[] = [];
+
+  if (state.registration !== 'registered') {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericLine(ctx, Numerics.ERR_NOTREGISTERED, NOTREGISTERED_TRAILING),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  const realname = msg.params[0];
+  if (realname === undefined || realname.length === 0) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericLine(ctx, Numerics.ERR_NEEDMOREPARAMS, NEEDMOREPARAMS_TRAILING, 'SETNAME'),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  const cap = ctx.serverConfig.realnameLen ?? DEFAULT_REALNAME_LEN;
+  if (realname.length > cap) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericLine(ctx, Numerics.ERR_ERRONEUSNICKNAME, ERRONEOUS_REALNAME_TRAILING),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  state.realname = realname;
+  return { state, effects };
+};
+
+/**
+ * Builds a `:<server> <code> <nick> [:<middle>] :<trailing>` line. The nick
+ * falls back to `*` when the connection has not yet registered one, and the
+ * optional `middle` is omitted when not supplied — matching the numeric
+ * formatting used by the registration reducers.
+ */
+function numericLine(ctx: Ctx, code: number, trailing: string, middle?: string): RawLine {
+  const nick = ctx.connection.nick ?? '*';
+  const codeStr = code.toString().padStart(3, '0');
+  const parts = [`:${ctx.serverName}`, codeStr, nick];
+  if (middle !== undefined) parts.push(middle);
+  parts.push(`:${trailing}`);
+  return { text: parts.join(' ') };
+}

package/packages/irc-core/src/commands/stats.ts

@@ -0,0 +1,152 @@
+/**
+ * Pure reducer for the IRC `STATS` command (RFC 2812 §4.6.3).
+ *
+ * PLAN §2.1 location-of-authority: STATS is a read-only diagnostic that
+ * reports server statistics keyed by a single-letter query. The reducer
+ * takes an already-aggregated {@link ServerStatsSnapshot} (the actor
+ * awaits a {@link ServerStats} backend before calling here). The reducer
+ * never mutates anything but the requester's `lastSeen`.
+ *
+ * Wire format (RFC 2812 §5.1 + modern practice):
+ *   - `STATS <query> [<server>]`
+ *   - `211 RPL_STATSLINKINFO` (the `l` query): per-link sendq/byte/msg
+ *     counters. Single-server deployment collapses this to one line for
+ *     the bound server.
+ *   - `242 RPL_STATSUPTIME` (the `u` query):
+ *     `:<server> 242 <nick> :Server Up <d> days, <h>:<mm>:<ss>`
+ *   - `219 RPL_ENDOFSTATS`:
+ *     `:<server> 219 <nick> <query> :End of /STATS report`
+ *   - `402 ERR_NOSUCHSERVER`:
+ *     `:<server> 402 <nick> <server> :No such server`
+ *
+ * Implemented query letters: `u` (uptime), `l` (link info). Unknown letters
+ * follow charybdis semantics: the reducer emits ONLY the `219` terminator
+ * with an empty body (no 461/401/etc). The remaining RFC letters
+ * (`k`/`K`/`q`/`g`/`x`/`z`/…) are deferred behind per-letter tests; the
+ * actor routes them here regardless so a future implementation is just
+ * another case branch.
+ *
+ * `<server>` resolves at the actor layer: a non-local name yields
+ * `402 ERR_NOSUCHSERVER` (single-server network — S2S routing is a PLAN
+ * non-goal). When the actor passes `serverTarget`, the reducer emits ONLY
+ * the 402 and nothing else.
+ */
+
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import type { ServerStatsSnapshot } from '../ports.js';
+import { Numerics } from '../protocol/numerics.js';
+import type { Ctx } from '../types.js';
+
+/** Fixed text emitted for `402 ERR_NOSUCHSERVER`. */
+const NOSUCHSERVER_TRAILING_TEXT = 'No such server';
+
+/** Fixed text emitted for `219 RPL_ENDOFSTATS`. */
+const ENDOFSTATS_TRAILING_TEXT = 'End of /STATS report';
+
+/**
+ * Builds a `:<server> <code> <nick> [<middle>] :<trailing>` numeric line
+ * addressed to the requester. When `middle` is empty the middle field is
+ * still emitted as a bare space-prefixed token (matches charybdis output
+ * for STATS with no query letter).
+ */
+function numericLine(ctx: Ctx, code: number, trailing: string, middle: string): RawLine {
+  const nick = ctx.connection.nick ?? '*';
+  const codeStr = code.toString().padStart(3, '0');
+  const parts = [`:${ctx.serverName}`, codeStr, nick];
+  parts.push(middle);
+  parts.push(`:${trailing}`);
+  return { text: parts.join(' ') };
+}
+
+/**
+ * Formats an uptime delta (ms) as `Server Up <d> days, <h>:<mm>:<ss>`,
+ * matching charybdis's `RPL_STATSUPTIME` text. Days and hours are not
+ * zero-padded; minutes and seconds are.
+ */
+function formatUptime(deltaMs: number): string {
+  let totalSec = Math.floor(deltaMs / 1000);
+  const days = Math.floor(totalSec / 86_400);
+  totalSec -= days * 86_400;
+  const hours = Math.floor(totalSec / 3_600);
+  totalSec -= hours * 3_600;
+  const minutes = Math.floor(totalSec / 60);
+  totalSec -= minutes * 60;
+  const seconds = totalSec;
+  const mm = minutes.toString().padStart(2, '0');
+  const ss = seconds.toString().padStart(2, '0');
+  return `Server Up ${days} days, ${hours}:${mm}:${ss}`;
+}
+
+/**
+ * Handles `STATS <query> [<server>]`.
+ *
+ * @param snapshot      The aggregated network statistics (only `uptimeStartedAt`
+ *   is consulted here; full counts are surfaced by LUSERS).
+ * @param msg           The parsed `STATS` message.
+ * @param ctx           The per-invocation context.
+ * @param serverTarget  When set, the actor determined `<server>` names a
+ *   non-local server; the reducer emits `402 ERR_NOSUCHSERVER` against this
+ *   name.
+ */
+export function statsReducer(
+  snapshot: ServerStatsSnapshot,
+  msg: { command: string; params: readonly string[] },
+  ctx: Ctx,
+  serverTarget?: string,
+): { effects: EffectType[] } {
+  ctx.connection.lastSeen = ctx.clock.now();
+
+  const effects: EffectType[] = [];
+
+  if (serverTarget !== undefined) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericLine(ctx, Numerics.ERR_NOSUCHSERVER, NOSUCHSERVER_TRAILING_TEXT, serverTarget),
+      ]),
+    );
+    return { effects };
+  }
+
+  // Normalise: STATS with no query letter is treated as the empty string;
+  // case is folded to lower so the terminator matches the canonical charybdis
+  // output (`STATS U` and `STATS u` both terminate with `219 <nick> u`).
+  const rawQuery = msg.params[0] ?? '';
+  const query = rawQuery.toLowerCase();
+
+  if (query === 'u') {
+    const uptimeMs = ctx.clock.now() - snapshot.uptimeStartedAt;
+    const code = Numerics.RPL_STATSUPTIME.toString().padStart(3, '0');
+    effects.push(
+      Effect.send(ctx.connId, [
+        {
+          text: `:${ctx.serverName} ${code} ${ctx.connection.nick ?? '*'} :${formatUptime(uptimeMs)}`,
+        },
+      ]),
+    );
+  } else if (query === 'l') {
+    // Single-server: one link-info line for the bound server. All sendq /
+    // byte / message counters are zero for a stateless serverless runtime
+    // (no persistent S2S link); the trailing text is the configured server
+    // version so the client sees a self-describing entry.
+    const code = Numerics.RPL_STATSLINKINFO.toString().padStart(3, '0');
+    const requester = ctx.connection.nick ?? '*';
+    const version = ctx.serverConfig.serverVersion ?? '';
+    effects.push(
+      Effect.send(ctx.connId, [
+        {
+          text: `:${ctx.serverName} ${code} ${requester} ${ctx.serverName} 0 0 0 0 0 0 :${version}`,
+        },
+      ]),
+    );
+  }
+  // Terminator always emitted, even for unknown letters (charybdis
+  // semantics: unknown STATS letters produce no body lines, just 219).
+  effects.push(
+    Effect.send(ctx.connId, [
+      numericLine(ctx, Numerics.RPL_ENDOFSTATS, ENDOFSTATS_TRAILING_TEXT, query),
+    ]),
+  );
+
+  return { effects };
+}

package/packages/irc-core/src/commands/tagmsg.ts

@@ -27,10 +27,58 @@ import type { ChannelState } from '../state/channel.js';
 import { hostmaskOf } from '../state/connection.js';
 import type { ConnectionState } from '../state/connection.js';
 import type { Ctx, Reducer } from '../types.js';
+import {
+  READ_MARKER_CAP,
+  isReadMarkerTagmsg,
+  persistReadMarker,
+  readMarkerMsgid,
+} from './read-marker.js';
 
 /** The cap name advertising message-tags support. */
 const MESSAGE_TAGS_CAP = 'message-tags';
 
+/**
+ * The cap name advertising IRCv3 `draft/typing` support. Typing TAGMSGs
+ * (those carrying the `+draft/typing` client tag) fan out to members that
+ * announced EITHER `message-tags` (the baseline for every TAGMSG) OR
+ * `draft/typing` (the spec's client-tag exception for peers that did not
+ * negotiate `message-tags`).
+ */
+const TYPING_CAP = 'draft/typing';
+
+/**
+ * The client-tag key that identifies a typing TAGMSG. Presence of this key
+ * (regardless of value, including the valueless form) triggers the OR-caps
+ * broadcast above.
+ */
+const TYPING_TAG = '+draft/typing';
+
+/** Returns true iff `tags` carries the `+draft/typing` client tag. */
+function isTypingTagmsg(tags: Readonly<Record<string, string>>): boolean {
+  return TYPING_TAG in tags;
+}
+
+/**
+ * Returns the OR-semantics cap list a TAGMSG fanout should use, or `undefined`
+ * when the plain single-cap (`message-tags`) broadcast path applies.
+ *
+ * A TAGMSG carrying `+draft/typing` widens to `message-tags` OR `draft/typing`;
+ * one carrying `+draft/read-marker` widens to `message-tags` OR
+ * `draft/read-marker`. Both spec exceptions let a peer that announced only the
+ * draft cap (not `message-tags`) still receive the notification. The baseline
+ * `message-tags` cap always leads the list so message-tags peers keep receiving
+ * every TAGMSG.
+ */
+function widenAudienceCaps(tags: Readonly<Record<string, string>>): readonly string[] | undefined {
+  const typing = isTypingTagmsg(tags);
+  const readMarker = isReadMarkerTagmsg(tags);
+  if (!typing && !readMarker) return undefined;
+  const caps = [MESSAGE_TAGS_CAP];
+  if (typing) caps.push(TYPING_CAP);
+  if (readMarker) caps.push(READ_MARKER_CAP);
+  return caps;
+}
+
 /**
  * Returns true iff `hostmask` matches the IRC ban mask `mask`. Identical to
  * the implementation in `privmsg.ts`; duplicated to keep the message path
@@ -149,10 +197,32 @@ export const tagmsgChannelReducer: Reducer<ChannelState> = (state, msg, ctx) =>
     });
   }
 
+  // IRCv3 draft/read-marker: a TAGMSG carrying `+draft/read-marker=<msgid>`
+  // marks `<msgid>` as the last read message for the sender's account in
+  // this channel. Persist the marker (advances the connection's in-memory
+  // marker too); a valueless tag carries no msgid and is dropped here. The
+  // TAGMSG still fans out below so the user's other connections learn it.
+  if (isReadMarkerTagmsg(msg.tags)) {
+    const msgid = readMarkerMsgid(msg.tags);
+    if (msgid !== undefined) {
+      persistReadMarker(ctx, state.nameLower, msgid);
+    }
+  }
+
   // Broadcast the tag-bearing line to message-tags-enabled members only.
+  // When the TAGMSG carries `+draft/typing` or `+draft/read-marker`, the
+  // audience widens to also include members that announced the matching
+  // draft cap (the spec's client-tag exception): such peers receive the
+  // notification even without `message-tags`. The caps are passed via
+  // `caps` so dispatch applies OR semantics per recipient.
   const tagPrefix = serializeTags(msg.tags);
   const line: RawLine = { text: `${tagPrefix}:${hostmask} TAGMSG ${state.name}` };
-  effects.push(Effect.broadcast(state.name, [line], ctx.connId, MESSAGE_TAGS_CAP));
+  const widenCaps = widenAudienceCaps(msg.tags);
+  if (widenCaps !== undefined) {
+    effects.push(Effect.broadcast(state.name, [line], ctx.connId, undefined, undefined, widenCaps));
+  } else {
+    effects.push(Effect.broadcast(state.name, [line], ctx.connId, MESSAGE_TAGS_CAP));
+  }
 
   // IRCv3 echo-message: echo the same line back to the sender, after
   // the broadcast effect so clients observe their own message last.

package/packages/irc-core/src/commands/topic.ts

@@ -35,12 +35,10 @@ function isValidChannelName(name: string, maxLen: number): boolean {
 }
 
 /** Formats a numeric error/reply line addressed to the connection's nick. */
-function numericErr(ctx: Ctx, code: number, trailing: string, middle?: string): RawLine {
+function numericErr(ctx: Ctx, code: number, trailing: string, middle: string): RawLine {
   const nick = ctx.connection.nick ?? '*';
   const codeStr = code.toString().padStart(3, '0');
-  const parts = [`:${ctx.serverName}`, codeStr, nick];
-  if (middle !== undefined) parts.push(middle);
-  parts.push(`:${trailing}`);
+  const parts = [`:${ctx.serverName}`, codeStr, nick, middle, `:${trailing}`];
   return { text: parts.join(' ') };
 }
 

package/packages/irc-core/src/commands/trace.ts

@@ -0,0 +1,137 @@
+/**
+ * Pure reducer for the IRC `TRACE` command (RFC 2812 §4.6.3).
+ *
+ * PLAN §2.1 location-of-authority: TRACE is a query-only diagnostic. The
+ * actor layer resolves the optional `<target>` and — when it is a nick —
+ * hands the resolved {@link ConnectionState} here. The reducer never
+ * mutates anything but the requester's `lastSeen`.
+ *
+ * In a single-server serverless IRCd, multi-hop routing collapses to the
+ * local server. The classic `200 RPL_TRACELINK` / `206 RPL_TRACESERVER`
+ * server-link dump is therefore trivial (one server, zero hops); modern
+ * daemons emit just the per-connection `205`/`204` lines and the
+ * terminating `262 RPL_ENDOFTRACE`. This reducer follows that convention.
+ *
+ * Wire format (RFC 2812 §4.6.3 + modern practice):
+ *   - `TRACE [<target>]`
+ *   - `205 RPL_TRACEUSER`:
+ *     `:<server> 205 <nick> User <hops> <user> <host>` (per matched conn)
+ *   - `204 RPL_TRACEOPERATOR`:
+ *     `:<server> 204 <nick> Oper <hops> <user> <host>` (oper conns only)
+ *   - `262 RPL_ENDOFTRACE`:
+ *     `:<server> 262 <nick> <target> :End of TRACE`
+ *   - `402 ERR_NOSUCHSERVER`:
+ *     `:<server> 402 <nick> <server> :No such server`
+ *
+ * Detail visibility is oper-gated:
+ *   - Non-opers see only the `262` terminator (no per-connection detail),
+ *     so a non-oper cannot use `TRACE` to enumerate online users. This
+ *     also implicitly enforces `+i` invisibility for non-opers.
+ *   - Opers see one `205`/`204` line per matched connection and bypass
+ *     the `+i` filter (RFC 2812 §4.6.3).
+ */
+
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import { Numerics } from '../protocol/numerics.js';
+import type { ConnectionState } from '../state/connection.js';
+import type { Ctx } from '../types.js';
+
+/** Fixed text emitted for `402 ERR_NOSUCHSERVER`. */
+const NOSUCHSERVER_TRAILING_TEXT = 'No such server';
+
+/** Fixed text emitted for `262 RPL_ENDOFTRACE`. */
+const ENDOFTRACE_TRAILING_TEXT = 'End of TRACE';
+
+/**
+ * Builds a `:<server> <code> <nick> <Class> <hops> <nick> <user> <host>`
+ * line for one matched connection. `<Class>` is `Oper` for an oper,
+ * otherwise `User` (matching RFC 2812 §4.6.3 + common client rendering).
+ * `<hops>` is always 0 in a single-server deployment.
+ */
+function traceDetailLine(ctx: Ctx, code: number, cls: string, target: ConnectionState): RawLine {
+  const requesterNick = ctx.connection.nick ?? '*';
+  const codeStr = code.toString().padStart(3, '0');
+  const tNick = target.nick ?? '*';
+  const tUser = target.user ?? '?';
+  const tHost = target.host ?? '?';
+  return {
+    text: `:${ctx.serverName} ${codeStr} ${requesterNick} ${cls} 0 ${tNick} ${tUser} ${tHost}`,
+  };
+}
+
+/**
+ * Builds a `:<server> <code> <nick> [<middle>] :<trailing>` numeric line
+ * addressed to the requester. When `middle` is empty the middle field is
+ * omitted entirely.
+ */
+function numericLine(ctx: Ctx, code: number, trailing: string, middle: string): RawLine {
+  const nick = ctx.connection.nick ?? '*';
+  const codeStr = code.toString().padStart(3, '0');
+  const parts = [`:${ctx.serverName}`, codeStr, nick];
+  if (middle !== '') parts.push(middle);
+  parts.push(`:${trailing}`);
+  return { text: parts.join(' ') };
+}
+
+/**
+ * Handles `TRACE [<target>]`.
+ *
+ * The actor layer resolves `<target>`:
+ *   - Empty / absent / equal to the local server name → `target` is
+ *     `undefined` and `serverTarget` is unset; the reducer emits only the
+ *     terminating `262`.
+ *   - A nick that resolves → `target` is the live
+ *     {@link ConnectionState}; the reducer emits `205`/`204` (oper
+ *     requester only) then `262`.
+ *   - A nick that does not resolve → `target` is `undefined`; the reducer
+ *     emits only the `262` (carrying the requested nick).
+ *   - A name that is not the local server (treated as a remote server) →
+ *     the actor passes `serverTarget = '<name>'`; the reducer emits
+ *     `402 ERR_NOSUCHSERVER`.
+ *
+ * @param target        The resolved target connection, or `undefined`.
+ * @param msg           The parsed `TRACE` message.
+ * @param ctx           The per-invocation context.
+ * @param serverTarget  When set, the actor determined `<target>` names a
+ *   non-local server; the reducer emits `402` against this name.
+ */
+export function traceReducer(
+  target: ConnectionState | undefined,
+  msg: { command: string; params: readonly string[] },
+  ctx: Ctx,
+  serverTarget?: string,
+): { effects: EffectType[] } {
+  ctx.connection.lastSeen = ctx.clock.now();
+
+  const effects: EffectType[] = [];
+  const rawTarget = msg.params[0] ?? '';
+
+  if (serverTarget !== undefined) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericLine(ctx, Numerics.ERR_NOSUCHSERVER, NOSUCHSERVER_TRAILING_TEXT, serverTarget),
+      ]),
+    );
+    return { effects };
+  }
+
+  const isOper = ctx.connection.userModes.oper;
+  if (target !== undefined && isOper) {
+    // Per-connection detail is oper-gated, which also implicitly enforces
+    // `+i` invisibility for non-opers (they never receive detail). Opers
+    // bypass `+i` per RFC 2812 §4.6.3 and always see the matched conn.
+    const code = target.userModes.oper ? Numerics.RPL_TRACEOPERATOR : Numerics.RPL_TRACEUSER;
+    const cls = target.userModes.oper ? 'Oper' : 'User';
+    effects.push(Effect.send(ctx.connId, [traceDetailLine(ctx, code, cls, target)]));
+  }
+
+  const endMiddle = rawTarget.length > 0 ? rawTarget : '';
+  effects.push(
+    Effect.send(ctx.connId, [
+      numericLine(ctx, Numerics.RPL_ENDOFTRACE, ENDOFTRACE_TRAILING_TEXT, endMiddle),
+    ]),
+  );
+
+  return { effects };
+}