serverless-ircd 0.4.0 → 0.6.0

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

@@ -0,0 +1,204 @@
+/**
+ * Pure reducer for the IRC `LUSERS` command (RFC 2812 §4.6.2).
+ *
+ * PLAN §2.1 location-of-authority: LUSERS is a read-only diagnostic that
+ * reports network-wide counts. The reducer takes an already-aggregated
+ * {@link ServerStatsSnapshot} (the actor layer awaits a {@link ServerStats}
+ * backend before calling here — same pattern as `listChannels` →
+ * `listReducer`). The reducer never mutates anything but the requester's
+ * `lastSeen`.
+ *
+ * Wire format (RFC 2812 §5.1):
+ *   - `LUSERS [<mask> [<server>]]`
+ *   - `251 RPL_LUSERCLIENT`:
+ *     `:<server> 251 <nick> :There are <users> users and <invisible>
+ *      invisible on <servers> servers`
+ *   - `252 RPL_LUSEROP`:
+ *     `:<server> 252 <nick> <count> :operator(s) online` (only when non-zero)
+ *   - `253 RPL_LUSERUNKNOWN`:
+ *     `:<server> 253 <nick> <count> :unknown connection(s)` (only when
+ *     non-zero)
+ *   - `254 RPL_LUSERCHANNELS`:
+ *     `:<server> 254 <nick> <count> :channel(s) formed` (only when non-zero)
+ *   - `255 RPL_LUSERME`:
+ *     `:<server> 255 <nick> :I have <localConns> clients and <servers>
+ *      servers`
+ *   - `265 RPL_LOCALUSERS`:
+ *     `:<server> 265 <nick> <cur> <max> :Current local users <cur>, max
+ *      <max>`
+ *   - `266 RPL_GLOBALUSERS`:
+ *     `:<server> 266 <nick> <cur> <max> :Current global users <cur>, max
+ *      <max>`
+ *   - `402 ERR_NOSUCHSERVER`:
+ *     `:<server> 402 <nick> <server> :No such server`
+ *
+ * Non-zero omission: 252/253/254 are suppressed when their count is zero
+ * (per RFC 2812). 251, 255, 265, and 266 are always emitted — modern
+ * clients rely on 265/266 for the user-list count and charybdis emits
+ * them unconditionally.
+ *
+ * Single-server deployment: `servers` is always 1 (PLAN §1 — S2S linking
+ * is a non-goal). `<mask>` is accepted for RFC compliance but not applied
+ * (the serverless deployment has one server, so a wildcard match is
+ * trivially true).
+ */
+
+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';
+
+/** Human-readable trailing templates per numeric. */
+const LUSERCLIENT_TEXT = (users: number, invisible: number, servers: number): string =>
+  `There are ${users} users and ${invisible} invisible on ${servers} servers`;
+const LUSEROP_TEXT = 'operator(s) online';
+const LUSERUNKNOWN_TEXT = 'unknown connection(s)';
+const LUSERCHANNELS_TEXT = 'channel(s) formed';
+const LUSERME_TEXT = (localConns: number, servers: number): string =>
+  `I have ${localConns} clients and ${servers} servers`;
+const LOCALUSERS_TEXT = (cur: number, max: number): string =>
+  `Current local users ${cur}, max ${max}`;
+const GLOBALUSERS_TEXT = (cur: number, max: number): string =>
+  `Current global users ${cur}, max ${max}`;
+
+/**
+ * Builds a `:<server> <code> <nick> :<trailing>` line. The middle field is
+ * empty for the summary numerics; the count-formatting helpers below carry
+ * a `<count>` middle for 252/253/254.
+ */
+function trailingLine(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}`,
+  };
+}
+
+/**
+ * Builds a `:<server> <code> <nick> <count> :<trailing>` line for the
+ * count-carrying numerics (252/253/254).
+ */
+function countLine(ctx: Ctx, code: number, count: number, trailing: string): RawLine {
+  const nick = ctx.connection.nick ?? '*';
+  const codeStr = code.toString().padStart(3, '0');
+  return {
+    text: `:${ctx.serverName} ${codeStr} ${nick} ${count} :${trailing}`,
+  };
+}
+
+/**
+ * Builds a `:<server> <code> <nick> <cur> <max> :<trailing>` line for
+ * 265/266.
+ */
+function usageLine(ctx: Ctx, code: number, cur: number, max: number, trailing: string): RawLine {
+  const nick = ctx.connection.nick ?? '*';
+  const codeStr = code.toString().padStart(3, '0');
+  return {
+    text: `:${ctx.serverName} ${codeStr} ${nick} ${cur} ${max} :${trailing}`,
+  };
+}
+
+/**
+ * Handles `LUSERS [<mask> [<server>]]`.
+ *
+ * @param snapshot      The aggregated network statistics (counts).
+ * @param _msg          The parsed `LUSERS` message. The optional `<mask>`
+ *   is accepted for RFC compliance but not applied — single-server
+ *   deployments collapse any wildcard match to the local server.
+ * @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 and nothing else.
+ */
+export function lusersReducer(
+  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) {
+    const nick = ctx.connection.nick ?? '*';
+    const code = Numerics.ERR_NOSUCHSERVER.toString().padStart(3, '0');
+    effects.push(
+      Effect.send(ctx.connId, [
+        {
+          text: `:${ctx.serverName} ${code} ${nick} ${serverTarget} :${NOSUCHSERVER_TRAILING_TEXT}`,
+        },
+      ]),
+    );
+    return { effects };
+  }
+
+  // 251 always.
+  effects.push(
+    Effect.send(ctx.connId, [
+      trailingLine(
+        ctx,
+        Numerics.RPL_LUSERCLIENT,
+        LUSERCLIENT_TEXT(snapshot.users, snapshot.invisible, snapshot.servers),
+      ),
+    ]),
+  );
+
+  // 252/253/254 only when non-zero (RFC: omit zero-count summary lines).
+  if (snapshot.opers > 0) {
+    effects.push(
+      Effect.send(ctx.connId, [countLine(ctx, Numerics.RPL_LUSEROP, snapshot.opers, LUSEROP_TEXT)]),
+    );
+  }
+  if (snapshot.unknownConnections > 0) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        countLine(ctx, Numerics.RPL_LUSERUNKNOWN, snapshot.unknownConnections, LUSERUNKNOWN_TEXT),
+      ]),
+    );
+  }
+  if (snapshot.channels > 0) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        countLine(ctx, Numerics.RPL_LUSERCHANNELS, snapshot.channels, LUSERCHANNELS_TEXT),
+      ]),
+    );
+  }
+
+  // 255 always.
+  effects.push(
+    Effect.send(ctx.connId, [
+      trailingLine(ctx, Numerics.RPL_LUSERME, LUSERME_TEXT(snapshot.localConns, snapshot.servers)),
+    ]),
+  );
+
+  // 265/266 always (modern clients depend on them).
+  effects.push(
+    Effect.send(ctx.connId, [
+      usageLine(
+        ctx,
+        Numerics.RPL_LOCALUSERS,
+        snapshot.localConns,
+        snapshot.maxLocalConns,
+        LOCALUSERS_TEXT(snapshot.localConns, snapshot.maxLocalConns),
+      ),
+    ]),
+  );
+  effects.push(
+    Effect.send(ctx.connId, [
+      usageLine(
+        ctx,
+        Numerics.RPL_GLOBALUSERS,
+        snapshot.globalConns,
+        snapshot.maxGlobalConns,
+        GLOBALUSERS_TEXT(snapshot.globalConns, snapshot.maxGlobalConns),
+      ),
+    ]),
+  );
+
+  return { effects };
+}

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

@@ -191,14 +191,10 @@ export const channelModeReducer: Reducer<ChannelState> = (state, msg, ctx) => {
     // authority BEFORE the broadcast so distributed runtimes (CF
     // ChannelDO) have persisted the change before any peer's next
     // prefetch observes it. In the in-memory runtime the actor's
-    // `state` IS authoritative so this is redundant.
-    if (
-      (delta.modeChanges !== undefined && delta.modeChanges.length > 0) ||
-      (delta.banMaskChanges !== undefined && delta.banMaskChanges.length > 0) ||
-      (delta.memberships !== undefined && delta.memberships.length > 0)
-    ) {
-      effects.push(Effect.applyChannelDelta(state.name, delta));
-    }
+    // `state` IS authoritative so this is redundant. Every non-null
+    // `applyChannelOp` result is paired with at least one delta push,
+    // so `delta` is guaranteed non-empty here.
+    effects.push(Effect.applyChannelDelta(state.name, delta));
     const hostmask = callerHostmask(ctx.connection);
     effects.push(Effect.broadcast(state.name, [buildModeBroadcast(hostmask, state.name, applied)]));
   }
@@ -532,7 +528,7 @@ const USER_MODE_LETTERS: Readonly<Record<string, keyof ConnectionState['userMode
 };
 
 /** User-mode letters in canonical 221 output order. */
-const USER_MODE_LETTER_ORDER = ['i', 'w', 's', 'o'] as const;
+const USER_MODE_LETTER_ORDER = ['i', 'w', 's', 'o', 'S'] as const;
 
 /**
  * Handles `MODE <nick> [<modestring>]`.
@@ -644,6 +640,13 @@ export const userModeReducer: Reducer<ConnectionState> = (state, msg, ctx) => {
 function buildUserModeString(state: ConnectionState): string {
   let modeStr = '+';
   for (const letter of USER_MODE_LETTER_ORDER) {
+    // `S` (TLS connected) is read-only: it is not in USER_MODE_LETTERS
+    // (the write-side map the parser consults) so `MODE nick +S` rejects
+    // with 501. Surface it on the read side directly from its field.
+    if (letter === 'S') {
+      if (state.userModes.tls) modeStr += 'S';
+      continue;
+    }
     const field = USER_MODE_LETTERS[letter];
     if (field !== undefined && state.userModes[field]) modeStr += letter;
   }

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

@@ -0,0 +1,327 @@
+/**
+ * Pure reducer for the IRCv3 `MONITOR` command.
+ *
+ * IRCv3 MONITOR spec <https://ircv3.net/specs/extensions/monitor-3.2.html>:
+ *
+ *   - `MONITOR + <nick>{,<nick>}` — add targets to the watchlist.
+ *   - `MONITOR - <nick>{,<nick>}` — remove targets from the watchlist.
+ *   - `MONITOR C`                 — clear the watchlist.
+ *   - `MONITOR L`                 — list the watchlist (`732` per line +
+ *                                   `733` terminator).
+ *   - `MONITOR S`                 — status: `730 RPL_MONONLINE` for the
+ *                                   online subset, `731 RPL_MONOFFLINE`
+ *                                   for the rest.
+ *
+ * Numerics:
+ *   - `730 RPL_MONONLINE`    `:<server> 730 <nick> :<online>{,<online>}`
+ *   - `731 RPL_MONOFFLINE`   `:<server> 731 <nick> :<offline>{,<offline>}`
+ *   - `732 RPL_MONLIST`      `:<server> 732 <nick> :<entry>`
+ *   - `733 RPL_ENDOFMONLIST` `:<server> 733 <nick> :End of MONITOR list`
+ *   - `734 ERR_MONLISTFULL`  `:<server> 734 <nick> <limit> :<rejected>{,<rejected>}`
+ *
+ * The watchlist lives on {@link ConnectionState.monitorList} (folded nicks,
+ * case-insensitive membership). The reducer resolves each requested nick
+ * against the supplied `online` map (folded-keyed → display spelling); the
+ * actor builds that map from the nick registry before invoking the reducer,
+ * mirroring the {@link isonReducer} pattern.
+ *
+ * Asynchronous `730`/`731` pushes on online/offline transitions are emitted
+ * by the actor layer (it watches `ReserveNick` / `ReleaseNick` effects
+ * against the watchlists); the pure reducer only handles the request/reply
+ * subcommands above.
+ */
+
+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, ReducerResult } from '../types.js';
+
+/** Wire name of the IRCv3 MONITOR capability. */
+export const MONITOR_CAP = 'monitor';
+
+/** Default monitor cap (max watchlist size) advertised via `MONITOR=<n>`. */
+export const DEFAULT_MONITOR_LIMIT = 30;
+
+/**
+ * Handles the IRCv3 `MONITOR` subcommands.
+ *
+ * Signature is bespoke (not {@link Reducer}) because the actor must resolve
+ * the requested nicks asynchronously before formatting — mirrors
+ * {@link isonReducer} / {@link whoisReducer}.
+ *
+ * @param online       Folded-keyed → display-spelling map of currently
+ *                     online nicks (built by the actor from the nick
+ *                     registry).
+ * @param maxMonitor   Server-wide cap on the per-connection watchlist size
+ *                     (advertised via `MONITOR=<n>` in `005`).
+ * @param msg          Parsed `MONITOR <sub> [<args>]` message.
+ * @param ctx          Per-invocation context.
+ */
+export function monitorReducer(
+  online: ReadonlyMap<string, string>,
+  maxMonitor: number,
+  msg: { params: readonly string[] },
+  ctx: Ctx,
+): ReducerResult<ConnectionState> {
+  ctx.connection.lastSeen = ctx.clock.now();
+
+  const state = ctx.connection;
+  const nick = state.nick ?? '*';
+  const serverName = ctx.serverName;
+
+  const sub = (msg.params[0] ?? '').toUpperCase();
+
+  // No subcommand at all → 461 NEEDMOREPARAMS (the parser hands us an
+  // empty string when the sender wrote bare `MONITOR`). A non-empty but
+  // unknown subcommand (e.g. `MONITOR Z`) is also 461 with a different
+  // trailing string per the IRCv3 MONITOR dispatch table.
+  if (sub.length === 0) {
+    return {
+      state,
+      effects: [
+        Effect.send(ctx.connId, [
+          numericLine(
+            serverName,
+            Numerics.ERR_NEEDMOREPARAMS,
+            nick,
+            'MONITOR',
+            'Not enough parameters',
+          ),
+        ]),
+      ],
+    };
+  }
+
+  switch (sub) {
+    case '+':
+      return handleAdd(state, online, maxMonitor, msg.params[1] ?? '', nick, serverName);
+    case '-':
+      return handleRemove(state, msg.params[1] ?? '');
+    case 'C':
+      return handleClear(state);
+    case 'L':
+      return handleList(state, nick, serverName);
+    case 'S':
+      return handleStatus(state, online, nick, serverName);
+    default:
+      return {
+        state,
+        effects: [
+          Effect.send(ctx.connId, [
+            numericLine(
+              serverName,
+              Numerics.ERR_NEEDMOREPARAMS,
+              nick,
+              'MONITOR',
+              'Unknown command',
+            ),
+          ]),
+        ],
+      };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Subcommand handlers
+// ---------------------------------------------------------------------------
+
+function handleAdd(
+  state: ConnectionState,
+  online: ReadonlyMap<string, string>,
+  maxMonitor: number,
+  targetList: string,
+  nick: string,
+  serverName: string,
+): ReducerResult<ConnectionState> {
+  if (targetList.length === 0) {
+    return {
+      state,
+      effects: [
+        Effect.send(state.id, [
+          numericLine(
+            serverName,
+            Numerics.ERR_NEEDMOREPARAMS,
+            nick,
+            'MONITOR',
+            'Not enough parameters',
+          ),
+        ]),
+      ],
+    };
+  }
+
+  const watchlist = ensureWatchlist(state);
+
+  const added: { folded: string; display: string }[] = [];
+  const rejected: string[] = [];
+  for (const requested of splitNicks(targetList)) {
+    const folded = requested.toLowerCase();
+    if (watchlist.has(folded)) continue; // already monitored; no output
+    if (watchlist.size >= maxMonitor) {
+      rejected.push(requested);
+      continue;
+    }
+    watchlist.add(folded);
+    // For the display spelling prefer the online map (canonical) and fall
+    // back to the requester spelling when the nick is offline.
+    const display = online.get(folded) ?? requested;
+    added.push({ folded, display });
+  }
+
+  const effects: EffectType[] = [];
+
+  const onlineDisplays = added.filter((a) => online.has(a.folded)).map((a) => a.display);
+  const offlineDisplays = added.filter((a) => !online.has(a.folded)).map((a) => a.display);
+
+  if (onlineDisplays.length > 0) {
+    effects.push(
+      Effect.send(state.id, [
+        monLine(Numerics.RPL_MONONLINE, serverName, nick, onlineDisplays.join(',')),
+      ]),
+    );
+  }
+  if (offlineDisplays.length > 0) {
+    effects.push(
+      Effect.send(state.id, [
+        monLine(Numerics.RPL_MONOFFLINE, serverName, nick, offlineDisplays.join(',')),
+      ]),
+    );
+  }
+  if (rejected.length > 0) {
+    effects.push(
+      Effect.send(state.id, [monListFullLine(serverName, nick, maxMonitor, rejected.join(','))]),
+    );
+  }
+
+  return { state, effects };
+}
+
+function handleRemove(state: ConnectionState, targetList: string): ReducerResult<ConnectionState> {
+  if (state.monitorList === undefined) return { state, effects: [] };
+  if (targetList.length === 0) return { state, effects: [] };
+  for (const requested of splitNicks(targetList)) {
+    state.monitorList.delete(requested.toLowerCase());
+  }
+  return { state, effects: [] };
+}
+
+function handleClear(state: ConnectionState): ReducerResult<ConnectionState> {
+  // Allocate the set on first clear so callers observe a stable post-state
+  // (size 0) regardless of whether the watchlist previously existed.
+  if (state.monitorList === undefined) {
+    state.monitorList = new Set<string>();
+  } else {
+    state.monitorList.clear();
+  }
+  return { state, effects: [] };
+}
+
+function handleList(
+  state: ConnectionState,
+  nick: string,
+  serverName: string,
+): ReducerResult<ConnectionState> {
+  const effects: EffectType[] = [];
+  if (state.monitorList !== undefined) {
+    for (const entry of state.monitorList) {
+      effects.push(Effect.send(state.id, [monLine(Numerics.RPL_MONLIST, serverName, nick, entry)]));
+    }
+  }
+  effects.push(
+    Effect.send(state.id, [
+      monLine(Numerics.RPL_ENDOFMONLIST, serverName, nick, 'End of MONITOR list'),
+    ]),
+  );
+  return { state, effects };
+}
+
+function handleStatus(
+  state: ConnectionState,
+  online: ReadonlyMap<string, string>,
+  nick: string,
+  serverName: string,
+): ReducerResult<ConnectionState> {
+  if (state.monitorList === undefined || state.monitorList.size === 0) {
+    return { state, effects: [] };
+  }
+  const onlineDisplays: string[] = [];
+  const offlineDisplays: string[] = [];
+  for (const folded of state.monitorList) {
+    const display = online.get(folded);
+    if (display !== undefined) {
+      onlineDisplays.push(display);
+    } else {
+      offlineDisplays.push(folded);
+    }
+  }
+  const effects: EffectType[] = [];
+  if (onlineDisplays.length > 0) {
+    effects.push(
+      Effect.send(state.id, [
+        monLine(Numerics.RPL_MONONLINE, serverName, nick, onlineDisplays.join(',')),
+      ]),
+    );
+  }
+  if (offlineDisplays.length > 0) {
+    effects.push(
+      Effect.send(state.id, [
+        monLine(Numerics.RPL_MONOFFLINE, serverName, nick, offlineDisplays.join(',')),
+      ]),
+    );
+  }
+  return { state, effects };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the connection's watchlist, lazily allocating it on first use.
+ * Existing persisted state migrates without a schema bump (the field stays
+ * optional; reducers that pre-date MONITOR never touch it).
+ */
+function ensureWatchlist(state: ConnectionState): Set<string> {
+  if (state.monitorList === undefined) {
+    state.monitorList = new Set<string>();
+  }
+  return state.monitorList;
+}
+
+/** Splits a comma-separated nick list, dropping empty entries. */
+function splitNicks(csv: string): string[] {
+  return csv
+    .split(',')
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+/** `:<server> <code> <nick> :<trailing>` — used by 730/731/732/733. */
+function monLine(code: number, serverName: string, nick: string, trailing: string): RawLine {
+  const codeStr = code.toString().padStart(3, '0');
+  return { text: `:${serverName} ${codeStr} ${nick} :${trailing}` };
+}
+
+/** `:<server> 734 <nick> <limit> :<rejected>` (ERR_MONLISTFULL). */
+function monListFullLine(
+  serverName: string,
+  nick: string,
+  limit: number,
+  rejected: string,
+): RawLine {
+  const codeStr = Numerics.ERR_MONLISTFULL.toString().padStart(3, '0');
+  return { text: `:${serverName} ${codeStr} ${nick} ${limit} :${rejected}` };
+}
+
+/** `:<server> <code> <nick> <cmd> :<trailing>` — used by 461-style errors. */
+function numericLine(
+  serverName: string,
+  code: number,
+  nick: string,
+  cmd: string,
+  trailing: string,
+): RawLine {
+  const codeStr = code.toString().padStart(3, '0');
+  return { text: `:${serverName} ${codeStr} ${nick} ${cmd} :${trailing}` };
+}