serverless-ircd 0.1.0

package/packages/irc-core/src/state/index.ts

@@ -0,0 +1,25 @@
+export * from './connection.js';
+export {
+  type ChannelState,
+  type ChannelModes,
+  type ChannelTopic,
+  type RosterEntry,
+  type Roster,
+  type ChanName,
+  type ChanSnapshot,
+  type MembershipDelta,
+  type ChannelDelta,
+  type ModeChange,
+  type BooleanChannelMode,
+  type ParameterChannelMode,
+  type ChannelModeName,
+  type BanMaskChange,
+  type CreateChannelOptions,
+  emptyModes,
+  createChannel,
+  prefixOf,
+  toSnapshot as toChannelSnapshot,
+  emptyChannelDelta,
+  applyChannelDelta,
+} from './channel.js';
+export * from './registry.js';

package/packages/irc-core/src/state/registry.ts

@@ -0,0 +1,22 @@
+/**
+ * Nick registry state shape.
+ *
+ * The Registry entity owns nick uniqueness. PLAN §2.1 puts the
+ * collision-check authority here, so reservations are structural rather than
+ * optimistic. CF backs this with `RegistryDO`; AWS with conditional puts on
+ * the `Nicks` table.
+ */
+
+import type { ConnId } from './connection.js';
+
+/**
+ * Mutable authoritative nick registry. Map key is the lowercased nick.
+ */
+export interface Registry {
+  nicks: Map<string, ConnId>;
+}
+
+/** Constructs an empty registry. */
+export function createRegistry(): Registry {
+  return { nicks: new Map<string, ConnId>() };
+}

package/packages/irc-core/src/types.ts

@@ -0,0 +1,83 @@
+/**
+ * Reducer signature + the per-invocation {@link Ctx}.
+ *
+ * PLAN §2.1: every command handler is a pure function
+ *   `(state, msg, ctx) => { state, effects }`.
+ * Side effects are values, not performed in the handler.
+ */
+
+import type { Effect } from './effects.js';
+import type { Clock, IdFactory, MotdProvider } from './ports.js';
+import type { IrcMessage } from './protocol/messages.js';
+import type { ConnectionState } from './state/connection.js';
+
+/**
+ * Per-deployment server configuration. Adapters load this from a KV store
+ * (CF) or Secrets Manager / SSM (AWS); the core only reads it.
+ *
+ * This is the minimum the Phase 1 reducers need; later tickets (SASL,
+ * MOTD provider, channel-prefix policy) extend it.
+ */
+export interface ServerConfig {
+  serverName: string;
+  networkName: string;
+  maxChannelsPerUser: number;
+  maxTargetsPerCommand: number;
+  maxListEntries: number;
+  nickLen: number;
+  channelLen: number;
+  topicLen: number;
+  quitMessage: string;
+}
+
+/** Per-invocation context handed to every reducer. */
+export interface Ctx {
+  readonly serverConfig: ServerConfig;
+  /** Convenience: `serverConfig.serverName`. */
+  readonly serverName: string;
+  /** Convenience: `serverConfig.networkName`. */
+  readonly networkName: string;
+  readonly clock: Clock;
+  readonly ids: IdFactory;
+  /** Pre-loaded MOTD source for the `MOTD` reducer. */
+  readonly motd: MotdProvider;
+  /** The connection invoking the command. Reducers mutate this freely. */
+  readonly connection: ConnectionState;
+  /** Convenience: `connection.id`. */
+  readonly connId: string;
+}
+
+/** Result of a single reducer invocation. */
+export interface ReducerResult<S> {
+  state: S;
+  effects: Effect[];
+}
+
+/**
+ * Pure command handler. Returns the next state and the side effects the
+ * actor layer should perform. Handlers MUST NOT await, throw on input
+ * errors (they emit error numerics instead), or read the wall clock.
+ */
+export type Reducer<S> = (state: S, msg: IrcMessage, ctx: Ctx) => ReducerResult<S>;
+
+export interface BuildCtxOptions {
+  serverConfig: ServerConfig;
+  clock: Clock;
+  ids: IdFactory;
+  motd: MotdProvider;
+  connection: ConnectionState;
+}
+
+/** Constructs a {@link Ctx} from the required parts. */
+export function buildCtx(opts: BuildCtxOptions): Ctx {
+  return {
+    serverConfig: opts.serverConfig,
+    serverName: opts.serverConfig.serverName,
+    networkName: opts.serverConfig.networkName,
+    clock: opts.clock,
+    ids: opts.ids,
+    motd: opts.motd,
+    connection: opts.connection,
+    connId: opts.connection.id,
+  };
+}

package/packages/irc-core/tests/batch.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest';
+import type { RawLine } from '../src/effects';
+import { type BatchFrame, wrapBatch } from '../src/protocol/batch';
+
+const L = (text: string): RawLine => ({ text });
+
+// ============================================================================
+// wrapBatch — IRCv3 batch framing
+// ============================================================================
+
+describe('wrapBatch — framing', () => {
+  it('wraps a non-empty line list with BATCH +id / -id markers', () => {
+    const lines = [L(':srv 353 alice = #foo :bob'), L(':srv 366 alice #foo :End of /NAMES list.')];
+
+    const out = wrapBatch(lines, 'abc', 'names');
+
+    expect(out).toEqual<RawLine[]>([
+      L('BATCH +abc names'),
+      L(':srv 353 alice = #foo :bob'),
+      L(':srv 366 alice #foo :End of /NAMES list.'),
+      L('BATCH -abc'),
+    ]);
+  });
+
+  it('emits BATCH +id type :args when args are supplied', () => {
+    const out = wrapBatch([L(':a JOIN #foo')], 'id1', 'netjoin', '#foo');
+
+    expect(out[0]?.text).toBe('BATCH +id1 netjoin #foo');
+    expect(out[out.length - 1]?.text).toBe('BATCH -id1');
+  });
+
+  it('returns the input unchanged when the line list is empty', () => {
+    const out = wrapBatch([], 'abc', 'names');
+    expect(out).toEqual<RawLine[]>([]);
+  });
+
+  it('preserves the order of the inner lines', () => {
+    const lines = [L('one'), L('two'), L('three'), L('four')];
+    const out = wrapBatch(lines, 'x', 'test');
+    expect(out.map((l) => l.text)).toEqual([
+      'BATCH +x test',
+      'one',
+      'two',
+      'three',
+      'four',
+      'BATCH -x',
+    ]);
+  });
+
+  it('produces a stable, round-trippable BatchFrame (start, body, end)', () => {
+    const frame: BatchFrame = wrapBatch([L('inner')], 'id', 'topic');
+    expect(frame.id).toBe('id');
+    expect(frame.type).toBe('topic');
+    expect(frame.start.text).toBe('BATCH +id topic');
+    expect(frame.end.text).toBe('BATCH -id');
+    expect(frame.body).toHaveLength(1);
+    expect(frame.body[0]?.text).toBe('inner');
+  });
+});
+
+// ============================================================================
+// wrapBatch — nested batches
+// ============================================================================
+
+describe('wrapBatch — nested batches', () => {
+  it('supports an outer batch wrapping an already-batched inner sequence', () => {
+    const inner = wrapBatch([L(':a JOIN #foo'), L(':srv 353 a = #foo :a')], 'inner', 'join');
+    const outer = wrapBatch(inner, 'outer', 'netjoin');
+
+    expect(outer.map((l) => l.text)).toEqual([
+      'BATCH +outer netjoin',
+      'BATCH +inner join',
+      ':a JOIN #foo',
+      ':srv 353 a = #foo :a',
+      'BATCH -inner',
+      'BATCH -outer',
+    ]);
+  });
+});

package/packages/irc-core/tests/caps/capabilities.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, it } from 'vitest';
+import {
+  type Capability,
+  SUPPORTED_CAPABILITIES,
+  SUPPORTED_CAP_NAMES,
+  capToLsString,
+  getLsString,
+  isSupportedCap,
+  splitCapsForWire,
+} from '../../src/caps/capabilities';
+
+describe('SUPPORTED_CAPABILITIES', () => {
+  it('includes every cap from PLAN §3', () => {
+    const names = SUPPORTED_CAPABILITIES.map((c) => c.name).sort();
+    expect(names).toEqual(
+      [
+        'account-tag',
+        'away-notify',
+        'batch',
+        'chghost',
+        'echo-message',
+        'extended-join',
+        'invite-notify',
+        'message-tags',
+        'multi-prefix',
+        'safelist',
+        'sasl',
+        'server-time',
+      ].sort(),
+    );
+  });
+
+  it('declares the sasl value as the advertised mechanism list', () => {
+    const sasl = SUPPORTED_CAPABILITIES.find((c) => c.name === 'sasl');
+    expect(sasl).toBeDefined();
+    expect(sasl?.value).toBe('PLAIN,EXTERNAL');
+  });
+
+  it('does not attach a value to caps that have no parameter', () => {
+    // sasl is the only cap with a value.
+    const noValue = SUPPORTED_CAPABILITIES.filter((c) => c.value === undefined);
+    expect(noValue.length).toBe(SUPPORTED_CAPABILITIES.length - 1);
+  });
+
+  it('advertises safelist as a bare name (no value parameter)', () => {
+    const safelist = SUPPORTED_CAPABILITIES.find((c) => c.name === 'safelist');
+    expect(safelist).toBeDefined();
+    expect(safelist?.value).toBeUndefined();
+  });
+});
+
+describe('SUPPORTED_CAP_NAMES', () => {
+  it('is a set matching the supported cap names', () => {
+    expect(SUPPORTED_CAP_NAMES.size).toBe(SUPPORTED_CAPABILITIES.length);
+    for (const cap of SUPPORTED_CAPABILITIES) {
+      expect(SUPPORTED_CAP_NAMES.has(cap.name)).toBe(true);
+    }
+  });
+});
+
+describe('isSupportedCap', () => {
+  it('returns true for a known cap name', () => {
+    expect(isSupportedCap('server-time')).toBe(true);
+  });
+
+  it('returns true for every advertised cap', () => {
+    for (const cap of SUPPORTED_CAPABILITIES) {
+      expect(isSupportedCap(cap.name)).toBe(true);
+    }
+  });
+
+  it('returns true for safelist', () => {
+    expect(isSupportedCap('safelist')).toBe(true);
+  });
+
+  it('returns false for an unknown cap name', () => {
+    expect(isSupportedCap('does-not-exist')).toBe(false);
+  });
+
+  it('returns false for the empty string', () => {
+    expect(isSupportedCap('')).toBe(false);
+  });
+});
+
+describe('capToLsString', () => {
+  it('returns just the name when no value is defined', () => {
+    const cap: Capability = { name: 'echo-message' };
+    expect(capToLsString(cap)).toBe('echo-message');
+  });
+
+  it('returns name=value when a value is defined', () => {
+    const cap: Capability = { name: 'sasl', value: 'PLAIN,EXTERNAL' };
+    expect(capToLsString(cap)).toBe('sasl=PLAIN,EXTERNAL');
+  });
+});
+
+describe('getLsString', () => {
+  it('joins every supported cap with a single space', () => {
+    const ls = getLsString();
+    const tokens = ls.split(' ');
+    expect(tokens.length).toBe(SUPPORTED_CAPABILITIES.length);
+  });
+
+  it('contains the sasl token with its value', () => {
+    expect(getLsString()).toContain('sasl=PLAIN,EXTERNAL');
+  });
+
+  it('contains server-time as a bare name', () => {
+    expect(getLsString()).toContain('server-time');
+    expect(getLsString()).not.toContain('server-time=');
+  });
+});
+
+describe('splitCapsForWire', () => {
+  it('returns a single chunk when everything fits', () => {
+    const tokens = ['a', 'b', 'c'];
+    expect(splitCapsForWire(tokens, 100)).toEqual(['a b c']);
+  });
+
+  it('returns an array containing an empty string when there are no tokens', () => {
+    expect(splitCapsForWire([], 100)).toEqual(['']);
+  });
+
+  it('splits tokens across multiple lines when they exceed the per-line budget', () => {
+    const tokens = ['aaaa', 'bbbb', 'cccc'];
+    // Budget is 9: "aaaa bbbb" is 9 bytes; "cccc" overflows to a new line.
+    const chunks = splitCapsForWire(tokens, 9);
+    expect(chunks).toEqual(['aaaa bbbb', 'cccc']);
+  });
+
+  it('starts a new line when a single token would overflow the current line', () => {
+    const tokens = ['short', 'verylongtoken'];
+    const chunks = splitCapsForWire(tokens, 10);
+    expect(chunks).toEqual(['short', 'verylongtoken']);
+  });
+
+  it('emits each over-long token on its own line when it alone exceeds the budget', () => {
+    const tokens = ['toolongfortoFit', 'next'];
+    const chunks = splitCapsForWire(tokens, 5);
+    expect(chunks).toEqual(['toolongfortoFit', 'next']);
+  });
+
+  it('packs greedily across many tokens', () => {
+    const tokens = ['x', 'y', 'z', 'w'];
+    const chunks = splitCapsForWire(tokens, 3);
+    expect(chunks).toEqual(['x y', 'z w']);
+  });
+});

package/packages/irc-core/tests/commands/away.test.ts

@@ -0,0 +1,233 @@
+import { describe, expect, it } from 'vitest';
+import { awayReducer } from '../../src/commands/away';
+import { Effect } from '../../src/effects';
+import type { Effect as EffectType, RawLine } from '../../src/effects';
+import { EmptyMotdProvider, FakeClock, SequentialIdFactory } from '../../src/ports';
+import { type ConnectionState, createConnection } from '../../src/state/connection';
+import { type Ctx, type ServerConfig, buildCtx } from '../../src/types';
+
+const serverConfig: ServerConfig = {
+  serverName: 'irc.example.com',
+  networkName: 'ExampleNet',
+  maxChannelsPerUser: 30,
+  maxTargetsPerCommand: 10,
+  maxListEntries: 50,
+  nickLen: 30,
+  channelLen: 50,
+  topicLen: 390,
+  quitMessage: 'Client Quit',
+};
+
+function makeCtx(conn: ConnectionState, clock = new FakeClock(1_000)): Ctx {
+  return buildCtx({
+    serverConfig,
+    clock,
+    ids: new SequentialIdFactory(),
+    motd: EmptyMotdProvider,
+    connection: conn,
+  });
+}
+
+function makeConn(id = 'c1', nick = 'alice'): ConnectionState {
+  const s = createConnection({ id, connectedSince: 0 });
+  s.nick = nick;
+  s.user = nick;
+  s.host = 'example.com';
+  s.realname = nick.charAt(0).toUpperCase() + nick.slice(1);
+  s.registration = 'registered';
+  return s;
+}
+
+const L = (text: string): RawLine => ({ text });
+
+// ============================================================================
+// awayReducer — setting AWAY
+// ============================================================================
+
+describe('awayReducer — setting away', () => {
+  it('emits 306 RPL_NOWAWAY to the sender when a reason is given (no away-notify peers)', () => {
+    const conn = makeConn();
+    const ctx = makeCtx(conn);
+
+    const out = awayReducer(conn, { command: 'AWAY', params: ['gone fishing'], tags: {} }, ctx);
+
+    expect(out.effects).toEqual<EffectType[]>([
+      Effect.send('c1', [L(':irc.example.com 306 alice :You have been marked as being away')]),
+    ]);
+    expect(conn.away).toBe('gone fishing');
+  });
+
+  it('unsets away when no parameter is given, emitting 305 RPL_UNAWAY', () => {
+    const conn = makeConn();
+    conn.away = 'old reason';
+    const ctx = makeCtx(conn);
+
+    const out = awayReducer(conn, { command: 'AWAY', params: [], tags: {} }, ctx);
+
+    expect(out.effects).toEqual<EffectType[]>([
+      Effect.send('c1', [L(':irc.example.com 305 alice :You are no longer marked as being away')]),
+    ]);
+    expect(conn.away).toBeUndefined();
+  });
+
+  it('unsets away when the parameter is empty, emitting 305 RPL_UNAWAY', () => {
+    const conn = makeConn();
+    conn.away = 'old reason';
+    const ctx = makeCtx(conn);
+
+    const out = awayReducer(conn, { command: 'AWAY', params: [''], tags: {} }, ctx);
+
+    expect(out.effects).toEqual<EffectType[]>([
+      Effect.send('c1', [L(':irc.example.com 305 alice :You are no longer marked as being away')]),
+    ]);
+    expect(conn.away).toBeUndefined();
+  });
+
+  it('overwrites an existing away reason when a new reason is given', () => {
+    const conn = makeConn();
+    conn.away = 'old';
+    const ctx = makeCtx(conn);
+
+    awayReducer(conn, { command: 'AWAY', params: ['new'], tags: {} }, ctx);
+
+    expect(conn.away).toBe('new');
+  });
+
+  it('updates lastSeen to ctx.clock.now()', () => {
+    const conn = makeConn();
+    const clock = new FakeClock(7_700);
+    const ctx = makeCtx(conn, clock);
+
+    awayReducer(conn, { command: 'AWAY', params: ['x'], tags: {} }, ctx);
+
+    expect(conn.lastSeen).toBe(7_700);
+  });
+});
+
+// ============================================================================
+// awayReducer — away-notify cap fanout
+// ============================================================================
+
+describe('awayReducer — away-notify cap fanout', () => {
+  it('emits an AWAY broadcast with the reason to cap-enabled peers in shared channels', () => {
+    const conn = makeConn();
+    conn.joinedChannels.add('#foo');
+    conn.joinedChannels.add('#bar');
+    const ctx = makeCtx(conn);
+
+    const out = awayReducer(conn, { command: 'AWAY', params: ['gone'], tags: {} }, ctx);
+
+    // Two cap-only broadcasts (one per shared channel), plus the 306 numeric.
+    const broadcasts = out.effects.filter(
+      (e): e is Extract<EffectType, { tag: 'Broadcast' }> => e.tag === 'Broadcast',
+    );
+    expect(broadcasts).toHaveLength(2);
+    expect(broadcasts[0]?.cap).toBe('away-notify');
+    expect(broadcasts[0]?.lines).toEqual<RawLine[]>([L(':alice!alice@example.com AWAY :gone')]);
+    expect(broadcasts[0]?.capLines).toBeUndefined();
+    expect(broadcasts[1]?.lines).toEqual<RawLine[]>([L(':alice!alice@example.com AWAY :gone')]);
+  });
+
+  it('emits an AWAY broadcast with no trailing param when unsetting (away-notify)', () => {
+    const conn = makeConn();
+    conn.joinedChannels.add('#foo');
+    conn.away = 'previously away';
+    const ctx = makeCtx(conn);
+
+    const out = awayReducer(conn, { command: 'AWAY', params: [], tags: {} }, ctx);
+
+    const broadcasts = out.effects.filter(
+      (e): e is Extract<EffectType, { tag: 'Broadcast' }> => e.tag === 'Broadcast',
+    );
+    expect(broadcasts).toHaveLength(1);
+    expect(broadcasts[0]?.lines).toEqual<RawLine[]>([L(':alice!alice@example.com AWAY')]);
+    expect(broadcasts[0]?.cap).toBe('away-notify');
+  });
+
+  it('emits no broadcast when the user has no joined channels (away set)', () => {
+    const conn = makeConn();
+    const ctx = makeCtx(conn);
+
+    const out = awayReducer(conn, { command: 'AWAY', params: ['gone'], tags: {} }, ctx);
+
+    const broadcasts = out.effects.filter(
+      (e): e is Extract<EffectType, { tag: 'Broadcast' }> => e.tag === 'Broadcast',
+    );
+    expect(broadcasts).toHaveLength(0);
+    // The numeric is still emitted.
+    expect(out.effects).toHaveLength(1);
+    expect(out.effects[0]?.tag).toBe('Send');
+  });
+
+  it('places the AWAY broadcast AFTER the numeric reply', () => {
+    const conn = makeConn();
+    conn.joinedChannels.add('#foo');
+    const ctx = makeCtx(conn);
+
+    const out = awayReducer(conn, { command: 'AWAY', params: ['gone'], tags: {} }, ctx);
+
+    expect(out.effects[0]?.tag).toBe('Send');
+    expect(out.effects[1]?.tag).toBe('Broadcast');
+  });
+
+  it('uses cap-only broadcast so non-cap peers receive nothing', () => {
+    const conn = makeConn();
+    conn.joinedChannels.add('#foo');
+    const ctx = makeCtx(conn);
+
+    const out = awayReducer(conn, { command: 'AWAY', params: ['gone'], tags: {} }, ctx);
+
+    const broadcast = out.effects.find(
+      (e): e is Extract<EffectType, { tag: 'Broadcast' }> => e.tag === 'Broadcast',
+    );
+    expect(broadcast?.cap).toBe('away-notify');
+    expect(broadcast?.capLines).toBeUndefined();
+  });
+});
+
+// ============================================================================
+// awayReducer — defensive paths
+// ============================================================================
+
+describe('awayReducer — defensive', () => {
+  it('uses * in the numeric reply when the connection has no nick', () => {
+    const conn = createConnection({ id: 'c1', connectedSince: 0 });
+    conn.registration = 'registered';
+    const ctx = makeCtx(conn);
+
+    const out = awayReducer(conn, { command: 'AWAY', params: ['gone'], tags: {} }, ctx);
+
+    expect(out.effects).toEqual<EffectType[]>([
+      Effect.send('c1', [L(':irc.example.com 306 * :You have been marked as being away')]),
+    ]);
+  });
+
+  it('falls back to nick-only hostmask when user/host are absent', () => {
+    const conn = createConnection({ id: 'c1', connectedSince: 0 });
+    conn.nick = 'alice';
+    conn.registration = 'registered';
+    conn.joinedChannels.add('#foo');
+    const ctx = makeCtx(conn);
+
+    const out = awayReducer(conn, { command: 'AWAY', params: ['gone'], tags: {} }, ctx);
+
+    const broadcast = out.effects.find(
+      (e): e is Extract<EffectType, { tag: 'Broadcast' }> => e.tag === 'Broadcast',
+    );
+    expect(broadcast?.lines[0]?.text).toBe(':alice AWAY :gone');
+  });
+
+  it('falls back to ?-prefixed source when nick is also absent', () => {
+    const conn = createConnection({ id: 'c1', connectedSince: 0 });
+    conn.registration = 'registered';
+    conn.joinedChannels.add('#foo');
+    const ctx = makeCtx(conn);
+
+    const out = awayReducer(conn, { command: 'AWAY', params: ['gone'], tags: {} }, ctx);
+
+    const broadcast = out.effects.find(
+      (e): e is Extract<EffectType, { tag: 'Broadcast' }> => e.tag === 'Broadcast',
+    );
+    expect(broadcast?.lines[0]?.text).toBe(':? AWAY :gone');
+  });
+});