serverless-ircd 0.1.0

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

@@ -0,0 +1,146 @@
+/**
+ * Pure reducer for the IRC `MOTD` command.
+ *
+ * PLAN §2.1 location-of-authority: MOTD is read-only — it does not mutate
+ * connection or channel state, only emits `Send` numeric replies addressed
+ * to the requester. The reducer runs in the Connection entity (state is
+ * {@link ConnectionState}).
+ *
+ * The MOTD text comes from the {@link MotdProvider} port on {@link Ctx}.
+ * Adapters pre-load the MOTD into the provider at startup (e.g. from KV,
+ * D1, or Secrets Manager) so the reducer itself stays pure and
+ * deterministic — no IO in the handler.
+ *
+ * Wire format (RFC 2812 §5):
+ *   - `375 RPL_MOTDSTART`  — `:<server> 375 <nick> :- <server> Message of the day -`
+ *   - `372 RPL_MOTD`        — `:<server> 372 <nick> :- <line>`  (one per MOTD line)
+ *   - `376 RPL_ENDOFMOTD`  — `:<server> 376 <nick> :End of MOTD command`
+ *   - `422 ERR_NOMOTD`     — `:<server> 422 <nick> :MOTD File is missing`
+ *
+ * Per RFC 1459 §2.3 the maximum wire line length is 512 bytes including the
+ * trailing CR-LF. Over-long MOTD content lines are hard-wrapped at the
+ * 372-line content budget so every emitted line fits within the 512-byte
+ * limit (also leaving headroom for message-tags).
+ */
+
+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';
+
+/** RFC 1459 §2.3: maximum IRC line length in bytes, including the trailing CR-LF. */
+const MAX_LINE_BYTES = 512;
+
+/** Length of the trailing CR-LF that the wire layer appends to each line. */
+const TRAILING_CRLF_LEN = 2;
+
+/** Fixed text emitted for `375 RPL_MOTDSTART` (after `:- `). */
+const MOTDSTART_TRAILING_TEXT = '- $server Message of the day -';
+
+/** Fixed text emitted for `376 RPL_ENDOFMOTD`. */
+const ENDOFMOTD_TRAILING_TEXT = 'End of MOTD command';
+
+/** Fixed text emitted for `422 ERR_NOMOTD`. */
+const NOMOTD_TRAILING_TEXT = 'MOTD File is missing';
+
+/**
+ * Handles `MOTD [server]`.
+ *
+ * The optional `<server>` target parameter is ignored: this is a
+ * single-server implementation (PLAN §1 non-goal: no S2S linking), so a
+ * request addressed to another server still gets the local MOTD. This
+ * matches the behavior of common modern IRC daemons on a single-node
+ * deployment.
+ */
+export const motdReducer: Reducer<ConnectionState> = (state, _msg, ctx) => {
+  state.lastSeen = ctx.clock.now();
+
+  const lines = ctx.motd.lines();
+
+  if (lines.length === 0) {
+    return {
+      state,
+      effects: [
+        Effect.send(ctx.connId, [numericLine(ctx, Numerics.ERR_NOMOTD, NOMOTD_TRAILING_TEXT)]),
+      ],
+    };
+  }
+
+  const out: RawLine[] = [
+    numericLine(
+      ctx,
+      Numerics.RPL_MOTDSTART,
+      MOTDSTART_TRAILING_TEXT.replace('$server', ctx.serverName),
+    ),
+  ];
+
+  const maxContent = maxMotdContentLen(ctx);
+  for (const raw of lines) {
+    for (const chunk of splitForMotd(raw, maxContent)) {
+      out.push(numericLine(ctx, Numerics.RPL_MOTD, `- ${chunk}`));
+    }
+  }
+
+  out.push(numericLine(ctx, Numerics.RPL_ENDOFMOTD, ENDOFMOTD_TRAILING_TEXT));
+
+  const effects: EffectType[] = [Effect.send(ctx.connId, out)];
+  return { state, effects };
+};
+
+/**
+ * Builds a `:<server> <code> <nick> :<trailing>` line. The nick falls back
+ * to `*` when the connection has not yet registered one, matching the rest
+ * of the codebase's numeric-error 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}` };
+}
+
+/**
+ * Returns the maximum content-byte length that fits in a single `372 RPL_MOTD`
+ * line for this connection, given the server name and the connection's nick.
+ *
+ * The 372 wire format is `:<server> 372 <nick> :- <chunk>\r\n`, so the
+ * per-chunk budget is:
+ *
+ *   512
+ *   - 2                              (trailing CR-LF)
+ *   - 1                              (leading `:`)
+ *   - <server>.length
+ *   - 5                              (` 372 `)
+ *   - <nick>.length
+ *   - 4                              (` :- `)
+ *
+ * The result is clamped at 0 so a pathologically long server/nick combo
+ * cannot drive the budget negative.
+ */
+function maxMotdContentLen(ctx: Ctx): number {
+  const nick = ctx.connection.nick ?? '*';
+  const overhead = TRAILING_CRLF_LEN + 1 + ctx.serverName.length + 5 + nick.length + 4;
+  return Math.max(0, MAX_LINE_BYTES - overhead);
+}
+
+/**
+ * Splits a single MOTD content line into chunks that each fit the per-372
+ * content budget.
+ *
+ * Hard-wraps at the byte budget (no word-boundary awareness) — matching the
+ * behavior of mainstream IRC daemons and keeping the reducer deterministic.
+ *
+ * Edge cases:
+ *   - Empty string → `['']` (one empty 372 line, still RFC-conformant).
+ *   - Zero/negative budget (impossible in practice but defensive) → `['']`
+ *     so the reducer always emits at least one 372 per input line.
+ */
+function splitForMotd(text: string, maxLen: number): string[] {
+  if (maxLen <= 0) return [''];
+  if (text.length === 0) return [''];
+  const chunks: string[] = [];
+  for (let i = 0; i < text.length; i += maxLen) {
+    chunks.push(text.slice(i, i + maxLen));
+  }
+  return chunks;
+}

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

@@ -0,0 +1,164 @@
+/**
+ * Pure reducer for the IRC `NAMES` command.
+ *
+ * PLAN §2.1 location-of-authority: NAMES reads channel state (roster +
+ * visibility modes) but does not mutate it, so the reducer's `state`
+ * argument is the channel's authoritative {@link ChannelState}; the
+ * requester is `ctx.connection`.
+ *
+ * Wire format (RFC 2812 §3.2.5):
+ *   - `353 RPL_NAMREPLY`     — `:<server> 353 <nick> <sigil> <chan> :<names>`
+ *   - `366 RPL_ENDOFNAMES`   — `:<server> 366 <nick> <chan> :End of /NAMES list.`
+ *
+ * The `<sigil>` reflects channel visibility: `=` (public), `*` (secret `+s`),
+ * `@` (private `+p`). Private wins over secret when both are set, matching
+ * the JOIN reducer's NAMES reply and RFC 2812 §3.2.4.
+ *
+ * Visibility rules (PLAN §3 + ticket spec):
+ *   - `+s` or `+p` set: requester must be a member to receive the NAMES list.
+ *     Otherwise `442 ERR_NOTONCHANNEL`.
+ *   - Otherwise: any connection may list.
+ *
+ * Multi-prefix (IRCv3): with the `multi-prefix` cap every applicable prefix
+ * is shown (`@+nick`); without the cap only the highest-priority prefix is
+ * shown (`@nick` for an op+voice user).
+ *
+ * Multi-channel (`NAMES #a,#b`) and no-args (`NAMES`) variants are split by
+ * the actor layer; this reducer handles exactly one channel
+ * per invocation.
+ */
+
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import { wrapBatch } from '../protocol/batch.js';
+import { Numerics } from '../protocol/numerics.js';
+import type { ChannelState, RosterEntry } from '../state/channel.js';
+import type { Ctx, Reducer } from '../types.js';
+
+/** Channel-name grammar; mirrors {@link isValidChannelName} in `join.ts`. */
+const CHANNEL_NAME_RE = /^[#&][^\s,:]+$/u;
+
+function isValidChannelName(name: string, maxLen: number): boolean {
+  if (name.length === 0 || name.length > maxLen) return false;
+  return CHANNEL_NAME_RE.test(name);
+}
+
+/** Formats a numeric error/reply line addressed to the connection's nick. */
+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}`);
+  return { text: parts.join(' ') };
+}
+
+/**
+ * Returns the 353 NAMES sigil for a channel given its modes:
+ * `@` for `+p` (private), `*` for `+s` (secret), `=` otherwise (public).
+ *
+ * `+p` wins over `+s` when both are set (RFC 2812 §3.2.4). Identical to the
+ * helper inside `join.ts`; duplicated to keep NAMES self-contained.
+ */
+function namesSigil(state: ChannelState): string {
+  if (state.modes.private) return '@';
+  if (state.modes.secret) return '*';
+  return '=';
+}
+
+/**
+ * Returns the IRC prefix character for the highest-priority mode an entry
+ * holds (`@` beats `+`). Returns `''` for a regular member.
+ */
+function highestPrefix(entry: RosterEntry): string {
+  if (entry.op) return '@';
+  if (entry.voice) return '+';
+  return '';
+}
+
+/**
+ * Returns every applicable prefix character in canonical order (`@` before
+ * `+`). Used when the connection has negotiated `multi-prefix`.
+ */
+function allPrefixes(entry: RosterEntry): string {
+  let out = '';
+  if (entry.op) out += '@';
+  if (entry.voice) out += '+';
+  return out;
+}
+
+/** Returns the prefix-rendering function appropriate for the requester's caps. */
+function prefixFormatter(ctx: Ctx): (entry: RosterEntry) => string {
+  return ctx.connection.caps.has('multi-prefix') ? allPrefixes : highestPrefix;
+}
+
+/** Builds the space-separated NAMES list with mode prefixes for a channel. */
+function buildNamesList(state: ChannelState, ctx: Ctx): string {
+  const format = prefixFormatter(ctx);
+  const names: string[] = [];
+  for (const entry of state.members.values()) {
+    names.push(format(entry) + entry.nick);
+  }
+  return names.join(' ');
+}
+
+/**
+ * Handles `NAMES <chan>`.
+ *
+ * Validation order (deliberate): missing-param → invalid-name →
+ * visibility (+s/+p membership) → success.
+ */
+export const namesReducer: Reducer<ChannelState> = (state, msg, ctx) => {
+  ctx.connection.lastSeen = ctx.clock.now();
+
+  const effects: EffectType[] = [];
+
+  const rawName = msg.params[0];
+  if (rawName === undefined) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericErr(ctx, Numerics.ERR_NEEDMOREPARAMS, 'Not enough parameters', 'NAMES'),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  if (!isValidChannelName(rawName, ctx.serverConfig.channelLen)) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericErr(ctx, Numerics.ERR_NOSUCHCHANNEL, 'No such channel', rawName),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  // Visibility: +s/+p channels cannot be listed by non-members.
+  const isMember = state.members.has(ctx.connId);
+  if ((state.modes.secret || state.modes.private) && !isMember) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericErr(ctx, Numerics.ERR_NOTONCHANNEL, "You're not on that channel", state.name),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  const nick = ctx.connection.nick ?? '*';
+  const sigil = namesSigil(state);
+  const names = buildNamesList(state, ctx);
+  const replyLines: RawLine[] = [
+    { text: `:${ctx.serverName} 353 ${nick} ${sigil} ${state.name} :${names}` },
+    { text: `:${ctx.serverName} 366 ${nick} ${state.name} :End of /NAMES list.` },
+  ];
+
+  // IRCv3 batch: wrap the multi-line reply for clients that negotiated it.
+  // Netbatch ref id allocated via the injected IdFactory so the wrapping is
+  // deterministic in tests.
+  const lines = ctx.connection.caps.has('batch')
+    ? wrapBatch(replyLines, ctx.ids.batchId(), 'names')
+    : replyLines;
+
+  effects.push(Effect.send(ctx.connId, lines));
+
+  return { state, effects };
+};

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

@@ -0,0 +1,118 @@
+/**
+ * Pure reducer for the IRC `PART` command.
+ *
+ * PLAN §2.1 location-of-authority: PART runs in the Channel entity. The
+ * reducer's `state` argument is the channel's authoritative state; the
+ * parter's identity is read from `ctx.connection`. Mutations to both
+ * `state.members` (the roster, via `ApplyChannelDelta`) and
+ * `ctx.connection.joinedChannels` (the connection's joined list) are
+ * expressed as effects / cross-authority mutations the actor layer persists.
+ *
+ * Multi-channel PART (`PART #a,#b :reason`) is split by the actor layer;
+ * this reducer handles one channel per invocation.
+ */
+
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import { Numerics } from '../protocol/numerics.js';
+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';
+
+/** Channel-name validation mirrors JOIN: same grammar, same length cap. */
+const CHANNEL_NAME_RE = /^[#&][^\s,:]+$/u;
+
+function isValidChannelName(name: string, maxLen: number): boolean {
+  if (name.length === 0 || name.length > maxLen) return false;
+  return CHANNEL_NAME_RE.test(name);
+}
+
+/**
+ * Formats a single numeric error line addressed to the connection's current
+ * nick (or `*` when unregistered). Optional `middle` is emitted before the
+ * trailing `:`-prefixed text.
+ */
+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}`);
+  return { text: parts.join(' ') };
+}
+
+/**
+ * Returns the hostmask string for the connection, falling back to the bare
+ * nick (or `?` when the connection has no nick yet). Used as the PART
+ * message source.
+ */
+function parterHostmask(conn: ConnectionState): string {
+  return hostmaskOf(conn) ?? conn.nick ?? '?';
+}
+
+/**
+ * Handles `PART <chan> [:reason]` for a single channel.
+ *
+ * Pre-condition: `state` is the authoritative ChannelState for the channel
+ * named in `msg.params[0]`.
+ *
+ * Validation order (deliberate): missing-param → invalid-name →
+ * not-on-channel → success.
+ */
+export const partReducer: Reducer<ChannelState> = (state, msg, ctx) => {
+  ctx.connection.lastSeen = ctx.clock.now();
+
+  const effects: EffectType[] = [];
+
+  const rawName = msg.params[0];
+  if (rawName === undefined) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericErr(ctx, Numerics.ERR_NEEDMOREPARAMS, 'Not enough parameters', 'PART'),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  if (!isValidChannelName(rawName, ctx.serverConfig.channelLen)) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericErr(ctx, Numerics.ERR_NOSUCHCHANNEL, 'No such channel', rawName),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  // Not on the channel: reject before any mutation.
+  if (!state.members.has(ctx.connId)) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericErr(ctx, Numerics.ERR_NOTONCHANNEL, "You're not on that channel", rawName),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  // All checks passed: build the PART line and remove the parter.
+  const hostmask = parterHostmask(ctx.connection);
+  const reason = msg.params[1];
+  const line: RawLine =
+    reason && reason.length > 0
+      ? { text: `:${hostmask} PART ${state.name} :${reason}` }
+      : { text: `:${hostmask} PART ${state.name}` };
+  effects.push(Effect.broadcast(state.name, [line]));
+
+  // Drop the parter from the roster (the actor layer persists the delta).
+  state.members.delete(ctx.connId);
+  effects.push(
+    Effect.applyChannelDelta(state.name, {
+      memberships: [{ type: 'remove', conn: ctx.connId }],
+    }),
+  );
+
+  // Cross-authority: remove the channel from the connection's joined set.
+  ctx.connection.joinedChannels.delete(state.nameLower);
+
+  return { state, effects };
+};

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

@@ -0,0 +1,47 @@
+/**
+ * Pure reducers for the IRC `PING` / `PONG` commands.
+ *
+ * Per PLAN §2.1 these run in the Connection entity. The reducer for
+ * client-initiated `PING` emits a single `Send(PONG …)` back to the sender;
+ * the reducer for `PONG` (the client's reply to a server-initiated PING)
+ * emits nothing. Server-initiated PINGs and idle / PING bookkeeping are the
+ * runtime's job; the reducers here only refresh `lastSeen` and
+ * emit replies.
+ */
+
+import { Effect } from '../effects.js';
+import type { RawLine } from '../effects.js';
+import type { ConnectionState } from '../state/connection.js';
+import type { Reducer } from '../types.js';
+
+/**
+ * Handles a client-initiated `PING [token]`.
+ *
+ * Replies with `PONG :<token>` when a token was supplied, or a bare `PONG`
+ * when one was not (per modern client behavior). Refreshes `lastSeen`.
+ */
+export const pingReducer: Reducer<ConnectionState> = (state, msg, ctx) => {
+  state.lastSeen = ctx.clock.now();
+
+  const token = msg.params[0];
+  const line: RawLine = token === undefined ? { text: 'PONG' } : { text: `PONG :${token}` };
+
+  return {
+    state,
+    effects: [Effect.send(ctx.connId, [line])],
+  };
+};
+
+/**
+ * Handles a client `PONG` (the reply to a server-initiated PING).
+ *
+ * Emits no effects; only refreshes `lastSeen`. The idle / PING bookkeeping
+ * that consumes `lastSeen` lives in the runtime.
+ */
+export const pongReducer: Reducer<ConnectionState> = (state, _msg, ctx) => {
+  state.lastSeen = ctx.clock.now();
+  return {
+    state,
+    effects: [],
+  };
+};