serverless-ircd 0.1.0

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

@@ -0,0 +1,101 @@
+import { describe, expect, it } from 'vitest';
+import {
+  type Clock,
+  FakeClock,
+  type IdFactory,
+  SequentialIdFactory,
+  SystemClock,
+  UuidIdFactory,
+} from '../src/ports';
+
+describe('SystemClock', () => {
+  it('returns a non-decreasing epoch millisecond value', () => {
+    const clock: Clock = SystemClock;
+    const a = clock.now();
+    const b = clock.now();
+    expect(b).toBeGreaterThanOrEqual(a);
+  });
+});
+
+describe('FakeClock', () => {
+  it('starts at zero by default', () => {
+    const clock = new FakeClock();
+    expect(clock.now()).toBe(0);
+  });
+
+  it('starts at the supplied start value', () => {
+    const clock = new FakeClock(1_000);
+    expect(clock.now()).toBe(1_000);
+  });
+
+  it('implements the Clock port', () => {
+    const clock: Clock = new FakeClock();
+    expect(clock.now()).toBe(0);
+  });
+
+  it('advance increases the current time', () => {
+    const clock = new FakeClock(100);
+    clock.advance(50);
+    expect(clock.now()).toBe(150);
+  });
+
+  it('set replaces the current time', () => {
+    const clock = new FakeClock(100);
+    clock.set(1_000);
+    expect(clock.now()).toBe(1_000);
+  });
+});
+
+describe('UuidIdFactory', () => {
+  it('implements the IdFactory port', () => {
+    const f: IdFactory = new UuidIdFactory();
+    expect(typeof f.batchId()).toBe('string');
+  });
+
+  it('returns unique values for batchId', () => {
+    const f = new UuidIdFactory();
+    expect(f.batchId()).not.toBe(f.batchId());
+  });
+
+  it('returns unique values for nonce', () => {
+    const f = new UuidIdFactory();
+    expect(f.nonce()).not.toBe(f.nonce());
+  });
+
+  it('returns unique values for sessionId', () => {
+    const f = new UuidIdFactory();
+    expect(f.sessionId()).not.toBe(f.sessionId());
+  });
+});
+
+describe('SequentialIdFactory', () => {
+  it('implements the IdFactory port', () => {
+    const f: IdFactory = new SequentialIdFactory();
+    expect(typeof f.batchId()).toBe('string');
+  });
+
+  it('returns deterministic sequential batch ids', () => {
+    const f = new SequentialIdFactory();
+    expect(f.batchId()).toBe('batch-0');
+    expect(f.batchId()).toBe('batch-1');
+  });
+
+  it('returns deterministic sequential nonces', () => {
+    const f = new SequentialIdFactory();
+    expect(f.nonce()).toBe('nonce-0');
+    expect(f.nonce()).toBe('nonce-1');
+  });
+
+  it('returns deterministic sequential session ids', () => {
+    const f = new SequentialIdFactory();
+    expect(f.sessionId()).toBe('session-0');
+    expect(f.sessionId()).toBe('session-1');
+  });
+
+  it('shares one counter across methods', () => {
+    const f = new SequentialIdFactory();
+    expect(f.batchId()).toBe('batch-0');
+    expect(f.nonce()).toBe('nonce-1');
+    expect(f.sessionId()).toBe('session-2');
+  });
+});

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

@@ -0,0 +1,164 @@
+import fc from 'fast-check';
+import { describe, expect, it } from 'vitest';
+import type { IrcMessage, IrcSource } from '../src/protocol/messages';
+import { parse } from '../src/protocol/parser';
+import { serialize, serializeFrame } from '../src/protocol/serializer';
+
+describe('serialize — golden vectors', () => {
+  it('emits the trailing colon for a parameter containing a space', () => {
+    expect(serialize({ tags: {}, command: 'PRIVMSG', params: ['#foo', 'hello world'] })).toBe(
+      'PRIVMSG #foo :hello world',
+    );
+  });
+
+  it('emits a full nick!user@host source', () => {
+    expect(
+      serialize({
+        tags: {},
+        source: { name: 'nick', user: 'user', host: 'host' },
+        command: 'PRIVMSG',
+        params: ['#foo', 'hi'],
+      }),
+    ).toBe(':nick!user@host PRIVMSG #foo :hi');
+  });
+
+  it('emits a server source (name only)', () => {
+    expect(
+      serialize({
+        tags: {},
+        source: { name: 'irc.example.com' },
+        command: 'NOTICE',
+        params: ['*', 'hi'],
+      }),
+    ).toBe(':irc.example.com NOTICE * :hi');
+  });
+
+  it('emits an empty trailing parameter as a dangling colon', () => {
+    expect(serialize({ tags: {}, command: 'TOPIC', params: ['#foo', ''] })).toBe('TOPIC #foo :');
+  });
+
+  it('forces trailing for a parameter that starts with a colon (doubled colon)', () => {
+    expect(serialize({ tags: {}, command: 'PRIVMSG', params: ['#foo', ':x'] })).toBe(
+      'PRIVMSG #foo ::x',
+    );
+  });
+
+  it('uses the trailing colon even for a single safe parameter', () => {
+    expect(serialize({ tags: {}, command: 'JOIN', params: ['#foo'] })).toBe('JOIN :#foo');
+  });
+
+  it('emits just the command when there are no parameters', () => {
+    expect(serialize({ tags: {}, command: 'PONG', params: [] })).toBe('PONG');
+  });
+
+  it('preserves a numeric command verbatim', () => {
+    expect(serialize({ tags: {}, command: '001', params: ['nick', 'Welcome'] })).toBe(
+      '001 nick :Welcome',
+    );
+  });
+});
+
+describe('serialize — message-tags (IRCv3)', () => {
+  it('emits valued tags before the rest of the message', () => {
+    expect(
+      serialize({
+        tags: { time: 't', account: 'a' },
+        command: 'PRIVMSG',
+        params: ['#foo', 'hi'],
+      }),
+    ).toBe('@time=t;account=a PRIVMSG #foo :hi');
+  });
+
+  it('omits the equals sign for a valueless tag', () => {
+    expect(serialize({ tags: { '+away': '' }, command: 'PRIVMSG', params: ['#foo', 'hi'] })).toBe(
+      '@+away PRIVMSG #foo :hi',
+    );
+  });
+
+  it('escapes a semicolon in a tag value', () => {
+    expect(serialize({ tags: { a: 'a;b' }, command: 'PING', params: [] })).toBe('@a=a\\:b PING');
+  });
+
+  it('escapes a space in a tag value', () => {
+    expect(serialize({ tags: { a: 'a b' }, command: 'PING', params: [] })).toBe('@a=a\\sb PING');
+  });
+
+  it('escapes a backslash in a tag value', () => {
+    expect(serialize({ tags: { a: 'a\\b' }, command: 'PING', params: [] })).toBe('@a=a\\\\b PING');
+  });
+
+  it('emits tags, source and body together', () => {
+    expect(
+      serialize({
+        tags: { account: 'foo' },
+        source: { name: 'nick', user: 'u', host: 'h' },
+        command: 'PRIVMSG',
+        params: ['#foo', 'hi'],
+      }),
+    ).toBe('@account=foo :nick!u@h PRIVMSG #foo :hi');
+  });
+});
+
+describe('serializeFrame', () => {
+  it('appends CR LF to a serialized message', () => {
+    expect(serializeFrame({ tags: {}, command: 'PING', params: ['tok'] })).toBe('PING :tok\r\n');
+  });
+});
+
+describe('serialize <-> parse round-trip (property test)', () => {
+  const safeMiddle = fc.stringMatching(/^[A-Za-z0-9._+\-]{1,8}$/);
+  const freeTrailing = fc.stringMatching(/^[A-Za-z0-9._+\- :;\\]{0,24}$/);
+  const commandArb = fc.oneof(fc.stringMatching(/^[A-Z]{1,8}$/), fc.stringMatching(/^[0-9]{3}$/));
+  const tagKey = fc.stringMatching(/^[a-z0-9][a-z0-9/+\\-]{0,14}$/);
+  const tagValue = fc.oneof(fc.constant(''), fc.stringMatching(/^[A-Za-z0-9 :;\\]{0,16}$/));
+  const tagsArb = fc
+    .uniqueArray(fc.tuple(tagKey, tagValue), { selector: (e) => e[0], maxLength: 3 })
+    .map((entries) => Object.fromEntries(entries) as Record<string, string>);
+  const sourceArb = fc
+    .record({
+      name: fc.stringMatching(/^[A-Za-z0-9][A-Za-z0-9.\\-]{0,19}$/),
+      user: fc.option(fc.stringMatching(/^[A-Za-z0-9._~+\\-]{1,10}$/), { nil: undefined }),
+      host: fc.option(fc.stringMatching(/^[A-Za-z0-9.\\-]{1,20}$/), { nil: undefined }),
+    })
+    .map((s): IrcSource => {
+      const out: IrcSource = { name: s.name };
+      if (s.user !== undefined) out.user = s.user;
+      if (s.host !== undefined) out.host = s.host;
+      return out;
+    });
+  const paramsArb = fc
+    .tuple(fc.array(safeMiddle, { maxLength: 6 }), fc.option(freeTrailing, { nil: undefined }))
+    .map(([mids, last]) => (last === undefined ? mids : [...mids, last]));
+
+  const messageArb = fc
+    .record({
+      tags: tagsArb,
+      command: commandArb,
+      params: paramsArb,
+      source: fc.option(sourceArb, { nil: undefined }),
+    })
+    .map((m): IrcMessage => {
+      const out: IrcMessage = { tags: m.tags, command: m.command, params: m.params };
+      if (m.source !== undefined) out.source = m.source;
+      return out;
+    });
+
+  it('parse(serialize(msg)) equals msg for all generated messages', () => {
+    fc.assert(
+      fc.property(messageArb, (msg) => {
+        expect(parse(serialize(msg))).toEqual(msg);
+      }),
+      { numRuns: 500 },
+    );
+  });
+
+  it('never emits CR, LF or NUL in a serialized (non-frame) line', () => {
+    fc.assert(
+      fc.property(messageArb, (msg) => {
+        const line = serialize(msg);
+        expect(line).not.toMatch(/[\r\n\0]/);
+      }),
+      { numRuns: 500 },
+    );
+  });
+});

package/packages/irc-core/tests/state/channel.test.ts

@@ -0,0 +1,351 @@
+import { describe, expect, it } from 'vitest';
+import {
+  type ChanSnapshot,
+  type ChannelDelta,
+  type ChannelModes,
+  type ChannelTopic,
+  type MembershipDelta,
+  type Roster,
+  type RosterEntry,
+  applyChannelDelta,
+  createChannel,
+  emptyChannelDelta,
+  emptyModes,
+  prefixOf,
+  toSnapshot,
+} from '../../src/state/channel';
+
+describe('emptyModes', () => {
+  it('returns a modes object with every known channel mode disabled', () => {
+    const modes = emptyModes();
+    expect(modes).toEqual<ChannelModes>({
+      inviteOnly: false,
+      topicLock: false,
+      noExternal: false,
+      moderated: false,
+      secret: false,
+      private: false,
+    });
+    // optional fields are absent, not undefined
+    expect('key' in modes).toBe(false);
+    expect('limit' in modes).toBe(false);
+  });
+});
+
+describe('createChannel', () => {
+  it('creates an empty channel with default modes and no members', () => {
+    const chan = createChannel({ name: '#foo', nameLower: '#foo', createdAt: 5 });
+    expect(chan.name).toBe('#foo');
+    expect(chan.nameLower).toBe('#foo');
+    expect(chan.createdAt).toBe(5);
+    expect(chan.members.size).toBe(0);
+    expect(chan.banMasks.size).toBe(0);
+    expect(chan.pendingInvites.size).toBe(0);
+    expect(chan.modes).toEqual(emptyModes());
+    expect(chan.topic).toBeUndefined();
+  });
+
+  it('honors an initial topic', () => {
+    const topic: ChannelTopic = { text: 'hi', setter: 'a!u@h', setAt: 9 };
+    const chan = createChannel({ name: '#x', nameLower: '#x', createdAt: 0, topic });
+    expect(chan.topic).toBe(topic);
+  });
+});
+
+describe('prefixOf', () => {
+  const entry = (over: Partial<RosterEntry>): RosterEntry => ({
+    conn: 'c1',
+    nick: 'n',
+    op: false,
+    voice: false,
+    ...over,
+  });
+
+  it('returns the empty string for a plain member', () => {
+    expect(prefixOf(entry({}))).toBe('');
+  });
+
+  it('returns "@" for an op', () => {
+    expect(prefixOf(entry({ op: true }))).toBe('@');
+  });
+
+  it('returns "+" for a voiced user', () => {
+    expect(prefixOf(entry({ voice: true }))).toBe('+');
+  });
+
+  it('returns "@+" for an op who is also voiced', () => {
+    expect(prefixOf(entry({ op: true, voice: true }))).toBe('@+');
+  });
+});
+
+describe('toSnapshot', () => {
+  it('returns a read-only view of the channel state', () => {
+    const chan = createChannel({ name: '#foo', nameLower: '#foo', createdAt: 7 });
+    chan.members.set('c1', { conn: 'c1', nick: 'a', op: true, voice: false });
+    chan.banMasks.add('*!bad@*');
+    chan.pendingInvites.add('c2');
+    chan.modes.topicLock = true;
+
+    const snap = toSnapshot(chan);
+    expect(snap.name).toBe('#foo');
+    expect(snap.createdAt).toBe(7);
+    expect(snap.members.size).toBe(1);
+    expect(snap.banMasks.has('*!bad@*')).toBe(true);
+    expect(snap.pendingInvites.has('c2')).toBe(true);
+    expect(snap.modes.topicLock).toBe(true);
+    expect(snap.topic).toBeUndefined();
+  });
+
+  it('produces a snapshot with topic when channel has one', () => {
+    const topic: ChannelTopic = { text: 't', setter: 's', setAt: 1 };
+    const chan = createChannel({ name: '#x', nameLower: '#x', createdAt: 0, topic });
+    const snap = toSnapshot(chan);
+    expect(snap.topic).toEqual(topic);
+  });
+});
+
+describe('emptyChannelDelta', () => {
+  it('returns a delta with no memberships, no topic, and no mode changes', () => {
+    const delta = emptyChannelDelta();
+    expect(delta.memberships).toEqual([]);
+    expect(delta.topic).toBeUndefined();
+    expect(delta.modeChanges).toEqual([]);
+    expect(delta.banMaskChanges).toEqual([]);
+  });
+});
+
+describe('applyChannelDelta', () => {
+  it('adds a new member via membership delta', () => {
+    const chan = createChannel({ name: '#f', nameLower: '#f', createdAt: 0 });
+    const delta: ChannelDelta = {
+      memberships: [{ type: 'add', conn: 'c1', nick: 'a', op: true, voice: false }],
+    };
+    const next = applyChannelDelta(chan, delta);
+    expect(next.members.size).toBe(1);
+    expect(next.members.get('c1')?.op).toBe(true);
+  });
+
+  it('updates an existing member via membership delta', () => {
+    const chan = createChannel({ name: '#f', nameLower: '#f', createdAt: 0 });
+    chan.members.set('c1', { conn: 'c1', nick: 'a', op: false, voice: false });
+    const delta: ChannelDelta = {
+      memberships: [{ type: 'add', conn: 'c1', nick: 'a', op: true, voice: true }],
+    };
+    const next = applyChannelDelta(chan, delta);
+    expect(next.members.get('c1')?.op).toBe(true);
+    expect(next.members.get('c1')?.voice).toBe(true);
+  });
+
+  it('removes a member via membership delta', () => {
+    const chan = createChannel({ name: '#f', nameLower: '#f', createdAt: 0 });
+    chan.members.set('c1', { conn: 'c1', nick: 'a', op: false, voice: false });
+    const delta: ChannelDelta = {
+      memberships: [{ type: 'remove', conn: 'c1' }],
+    };
+    const next = applyChannelDelta(chan, delta);
+    expect(next.members.has('c1')).toBe(false);
+  });
+
+  it('ignores removal of a non-existent member', () => {
+    const chan = createChannel({ name: '#f', nameLower: '#f', createdAt: 0 });
+    const delta: ChannelDelta = {
+      memberships: [{ type: 'remove', conn: 'nope' }],
+    };
+    const next = applyChannelDelta(chan, delta);
+    expect(next.members.size).toBe(0);
+  });
+
+  it('skips an add delta that is missing a nick', () => {
+    const chan = createChannel({ name: '#f', nameLower: '#f', createdAt: 0 });
+    const delta: ChannelDelta = {
+      memberships: [{ type: 'add', conn: 'c1' }],
+    };
+    const next = applyChannelDelta(chan, delta);
+    expect(next.members.has('c1')).toBe(false);
+  });
+
+  it('defaults op and voice to false when omitted on add', () => {
+    const chan = createChannel({ name: '#f', nameLower: '#f', createdAt: 0 });
+    const delta: ChannelDelta = {
+      memberships: [{ type: 'add', conn: 'c1', nick: 'a' }],
+    };
+    const next = applyChannelDelta(chan, delta);
+    expect(next.members.get('c1')?.op).toBe(false);
+    expect(next.members.get('c1')?.voice).toBe(false);
+  });
+
+  it('sets a fresh topic', () => {
+    const chan = createChannel({ name: '#f', nameLower: '#f', createdAt: 0 });
+    const topic: ChannelTopic = { text: 'hello', setter: 'a', setAt: 10 };
+    const delta: ChannelDelta = { topic };
+    const next = applyChannelDelta(chan, delta);
+    expect(next.topic).toEqual(topic);
+  });
+
+  it('clears the topic when delta.topic is null', () => {
+    const chan = createChannel({
+      name: '#f',
+      nameLower: '#f',
+      createdAt: 0,
+      topic: { text: 'old', setter: 'a', setAt: 1 },
+    });
+    const delta: ChannelDelta = { topic: null };
+    const next = applyChannelDelta(chan, delta);
+    expect(next.topic).toBeUndefined();
+  });
+
+  it('applies a boolean mode change', () => {
+    const chan = createChannel({ name: '#f', nameLower: '#f', createdAt: 0 });
+    const delta: ChannelDelta = {
+      modeChanges: [{ mode: 'topicLock', set: true }],
+    };
+    const next = applyChannelDelta(chan, delta);
+    expect(next.modes.topicLock).toBe(true);
+  });
+
+  it('applies a key mode change', () => {
+    const chan = createChannel({ name: '#f', nameLower: '#f', createdAt: 0 });
+    const delta: ChannelDelta = {
+      modeChanges: [{ mode: 'key', set: true, arg: 'secret' }],
+    };
+    const next = applyChannelDelta(chan, delta);
+    expect(next.modes.key).toBe('secret');
+  });
+
+  it('clears the key when set=false', () => {
+    const chan = createChannel({ name: '#f', nameLower: '#f', createdAt: 0 });
+    chan.modes.key = 'secret';
+    const delta: ChannelDelta = {
+      modeChanges: [{ mode: 'key', set: false }],
+    };
+    const next = applyChannelDelta(chan, delta);
+    expect(next.modes.key).toBeUndefined();
+  });
+
+  it('applies a limit mode change', () => {
+    const chan = createChannel({ name: '#f', nameLower: '#f', createdAt: 0 });
+    const delta: ChannelDelta = {
+      modeChanges: [{ mode: 'limit', set: true, arg: 50 }],
+    };
+    const next = applyChannelDelta(chan, delta);
+    expect(next.modes.limit).toBe(50);
+  });
+
+  it('clears the limit when set=false', () => {
+    const chan = createChannel({ name: '#f', nameLower: '#f', createdAt: 0 });
+    chan.modes.limit = 10;
+    const delta: ChannelDelta = {
+      modeChanges: [{ mode: 'limit', set: false }],
+    };
+    const next = applyChannelDelta(chan, delta);
+    expect(next.modes.limit).toBeUndefined();
+  });
+
+  it('ignores a key set without a string arg', () => {
+    const chan = createChannel({ name: '#f', nameLower: '#f', createdAt: 0 });
+    const delta: ChannelDelta = {
+      modeChanges: [{ mode: 'key', set: true }],
+    };
+    const next = applyChannelDelta(chan, delta);
+    expect(next.modes.key).toBeUndefined();
+  });
+
+  it('ignores a limit set without a numeric arg', () => {
+    const chan = createChannel({ name: '#f', nameLower: '#f', createdAt: 0 });
+    const delta: ChannelDelta = {
+      modeChanges: [{ mode: 'limit', set: true }],
+    };
+    const next = applyChannelDelta(chan, delta);
+    expect(next.modes.limit).toBeUndefined();
+  });
+
+  it('toggles every boolean mode (inviteOnly, noExternal, moderated, secret, private)', () => {
+    const chan = createChannel({ name: '#f', nameLower: '#f', createdAt: 0 });
+    const delta: ChannelDelta = {
+      modeChanges: [
+        { mode: 'inviteOnly', set: true },
+        { mode: 'noExternal', set: true },
+        { mode: 'moderated', set: true },
+        { mode: 'secret', set: true },
+        { mode: 'private', set: true },
+      ],
+    };
+    const next = applyChannelDelta(chan, delta);
+    expect(next.modes.inviteOnly).toBe(true);
+    expect(next.modes.noExternal).toBe(true);
+    expect(next.modes.moderated).toBe(true);
+    expect(next.modes.secret).toBe(true);
+    expect(next.modes.private).toBe(true);
+  });
+
+  it('applies ban mask changes (add and remove)', () => {
+    const chan = createChannel({ name: '#f', nameLower: '#f', createdAt: 0 });
+    const delta: ChannelDelta = {
+      banMaskChanges: [
+        { type: 'add', mask: '*!bad@*' },
+        { type: 'add', mask: '*!worse@*' },
+        { type: 'remove', mask: '*!bad@*' },
+      ],
+    };
+    const next = applyChannelDelta(chan, delta);
+    expect(next.banMasks.has('*!bad@*')).toBe(false);
+    expect(next.banMasks.has('*!worse@*')).toBe(true);
+  });
+
+  it('applies all delta fields in one call', () => {
+    const chan = createChannel({ name: '#f', nameLower: '#f', createdAt: 0 });
+    chan.members.set('c1', { conn: 'c1', nick: 'a', op: false, voice: false });
+    const delta: ChannelDelta = {
+      memberships: [
+        { type: 'add', conn: 'c2', nick: 'b', op: false, voice: true },
+        { type: 'remove', conn: 'c1' },
+      ],
+      topic: { text: 't', setter: 's', setAt: 1 },
+      modeChanges: [{ mode: 'secret', set: true }],
+      banMaskChanges: [{ type: 'add', mask: '*!x@*' }],
+    };
+    const next = applyChannelDelta(chan, delta);
+    expect(next.members.size).toBe(1);
+    expect(next.members.get('c2')?.voice).toBe(true);
+    expect(next.topic?.text).toBe('t');
+    expect(next.modes.secret).toBe(true);
+    expect(next.banMasks.has('*!x@*')).toBe(true);
+  });
+
+  it('returns the channel unchanged for an empty delta', () => {
+    const chan = createChannel({ name: '#f', nameLower: '#f', createdAt: 0 });
+    const next = applyChannelDelta(chan, emptyChannelDelta());
+    expect(next.members.size).toBe(0);
+    expect(next.modes).toEqual(emptyModes());
+    expect(next.topic).toBeUndefined();
+    expect(next.banMasks.size).toBe(0);
+  });
+
+  it('returns a value equal-but-distinct reference for empty delta (no shared mutable aliasing)', () => {
+    const chan = createChannel({ name: '#f', nameLower: '#f', createdAt: 0 });
+    const next = applyChannelDelta(chan, emptyChannelDelta());
+    // The function should be safe to call without mutating the source.
+    expect(next.name).toBe(chan.name);
+    expect(next).not.toBe(chan);
+  });
+});
+
+describe('Roster type', () => {
+  it('exposes a read-only map alias', () => {
+    const chan = createChannel({ name: '#f', nameLower: '#f', createdAt: 0 });
+    chan.members.set('c1', { conn: 'c1', nick: 'a', op: true, voice: false });
+    const snap: ChanSnapshot = toSnapshot(chan);
+    const roster: Roster = snap.members;
+    expect(roster.size).toBe(1);
+    expect(roster.get('c1')?.nick).toBe('a');
+  });
+});
+
+describe('MembershipDelta', () => {
+  it('has add and remove literal types', () => {
+    const add: MembershipDelta = { type: 'add', conn: 'c1', nick: 'a', op: false, voice: false };
+    const remove: MembershipDelta = { type: 'remove', conn: 'c1' };
+    expect(add.type).toBe('add');
+    expect(remove.type).toBe('remove');
+  });
+});