serverless-ircd 0.4.0 → 0.6.0

package/packages/irc-core/tests/stats-store.test.ts

@@ -0,0 +1,222 @@
+import { describe, expect, it } from 'vitest';
+import {
+  FakeClock,
+  InMemoryStats,
+  type ServerStats,
+  type ServerStatsSnapshot,
+  computeStatsSnapshot,
+} from '../src/ports';
+import type { ChannelState } from '../src/state/channel';
+import { createChannel } from '../src/state/channel';
+import type { ConnId, ConnectionState } from '../src/state/connection';
+import { createConnection } from '../src/state/connection';
+
+/** Builds a registered connection with the supplied modes. */
+function makeConn(
+  id: ConnId,
+  opts: { oper?: boolean; invisible?: boolean; registered?: boolean } = {},
+): ConnectionState {
+  const s = createConnection({ id, connectedSince: 0 });
+  s.nick = id;
+  s.user = id;
+  s.host = 'example.com';
+  s.realname = id;
+  s.registration = opts.registered === false ? 'pre-registration' : 'registered';
+  if (opts.oper !== undefined) s.userModes.oper = opts.oper;
+  if (opts.invisible !== undefined) s.userModes.invisible = opts.invisible;
+  return s;
+}
+
+function emptyChannel(name: string): ChannelState {
+  return createChannel({ name, nameLower: name.toLowerCase(), createdAt: 0 });
+}
+
+describe('InMemoryStats', () => {
+  it('implements the ServerStats port', () => {
+    const stats: ServerStats = new InMemoryStats({
+      connections: new Map(),
+      channels: new Map(),
+      uptimeStartedAt: 0,
+    });
+    expect(stats).toBeDefined();
+  });
+
+  it('returns zero counts for an empty deployment', async () => {
+    const stats = new InMemoryStats({
+      connections: new Map(),
+      channels: new Map(),
+      uptimeStartedAt: 0,
+    });
+
+    const snap = await stats.getStats();
+
+    expect(snap).toEqual<ServerStatsSnapshot>({
+      users: 0,
+      invisible: 0,
+      opers: 0,
+      unknownConnections: 0,
+      channels: 0,
+      servers: 1,
+      localConns: 0,
+      globalConns: 0,
+      uptimeStartedAt: 0,
+      maxLocalConns: 0,
+      maxGlobalConns: 0,
+    });
+  });
+
+  it('derives the seed counts from the maps (3 conns, 1 oper, 2 channels)', async () => {
+    const conns = new Map<ConnId, ConnectionState>([
+      ['c1', makeConn('c1')],
+      ['c2', makeConn('c2', { invisible: true })],
+      ['c3', makeConn('c3', { oper: true })],
+    ]);
+    const channels = new Map<string, ChannelState>([
+      ['#a', emptyChannel('#a')],
+      ['#b', emptyChannel('#b')],
+    ]);
+    const stats = new InMemoryStats({
+      connections: conns,
+      channels,
+      uptimeStartedAt: 1_000,
+    });
+
+    const snap = await stats.getStats();
+
+    // 3 registered (2 visible + 1 invisible), 1 oper, 0 unknown, 2 channels.
+    expect(snap.users).toBe(2); // visible registered
+    expect(snap.invisible).toBe(1);
+    expect(snap.opers).toBe(1);
+    expect(snap.unknownConnections).toBe(0);
+    expect(snap.channels).toBe(2);
+    expect(snap.servers).toBe(1);
+    expect(snap.localConns).toBe(3);
+    expect(snap.globalConns).toBe(3);
+    expect(snap.uptimeStartedAt).toBe(1_000);
+  });
+
+  it('counts pre-registration connections as unknown', async () => {
+    const conns = new Map<ConnId, ConnectionState>([
+      ['c1', makeConn('c1')],
+      ['c2', makeConn('c2', { registered: false })],
+    ]);
+    const stats = new InMemoryStats({
+      connections: conns,
+      channels: new Map(),
+      uptimeStartedAt: 0,
+    });
+
+    const snap = await stats.getStats();
+
+    expect(snap.users).toBe(1);
+    expect(snap.unknownConnections).toBe(1);
+    expect(snap.localConns).toBe(2);
+  });
+
+  it('reports the live max as equal to current count when never higher', async () => {
+    const conns = new Map<ConnId, ConnectionState>([['c1', makeConn('c1')]]);
+    const stats = new InMemoryStats({
+      connections: conns,
+      channels: new Map(),
+      uptimeStartedAt: 0,
+      maxLocalConns: 5,
+      maxGlobalConns: 7,
+    });
+
+    const snap = await stats.getStats();
+
+    expect(snap.maxLocalConns).toBe(5);
+    expect(snap.maxGlobalConns).toBe(7);
+  });
+
+  it('clamps max to the current count when the live count exceeds the recorded max', async () => {
+    const conns = new Map<ConnId, ConnectionState>([
+      ['c1', makeConn('c1')],
+      ['c2', makeConn('c2')],
+      ['c3', makeConn('c3')],
+    ]);
+    const stats = new InMemoryStats({
+      connections: conns,
+      channels: new Map(),
+      uptimeStartedAt: 0,
+      maxLocalConns: 2,
+      maxGlobalConns: 2,
+    });
+
+    const snap = await stats.getStats();
+
+    // Live count (3) > seeded max (2); the snapshot reports the live value
+    // so the wire numeric never claims a max below the current count.
+    expect(snap.maxLocalConns).toBe(3);
+    expect(snap.maxGlobalConns).toBe(3);
+  });
+
+  it('reflects map mutations on subsequent getStats() calls', async () => {
+    const conns = new Map<ConnId, ConnectionState>([['c1', makeConn('c1')]]);
+    const stats = new InMemoryStats({
+      connections: conns,
+      channels: new Map(),
+      uptimeStartedAt: 0,
+    });
+
+    let snap = await stats.getStats();
+    expect(snap.users).toBe(1);
+
+    conns.set('c2', makeConn('c2'));
+    conns.set('c3', makeConn('c3', { invisible: true }));
+    snap = await stats.getStats();
+    expect(snap.users).toBe(2);
+    expect(snap.invisible).toBe(1);
+    expect(snap.localConns).toBe(3);
+  });
+});
+
+describe('computeStatsSnapshot', () => {
+  it('counts opers separately from users (an oper still counts as a user)', () => {
+    const snap = computeStatsSnapshot([makeConn('c1'), makeConn('c2', { oper: true })], 0, 0);
+    expect(snap.users).toBe(2);
+    expect(snap.opers).toBe(1);
+  });
+
+  it('counts an oper who is also invisible under invisible + opers (not users)', () => {
+    const snap = computeStatsSnapshot([makeConn('c1', { oper: true, invisible: true })], 0, 0);
+    expect(snap.invisible).toBe(1);
+    expect(snap.opers).toBe(1);
+    // users = visible registered (total registered − invisible).
+    expect(snap.users).toBe(0);
+  });
+
+  it('reports users as the visible-only count (total registered − invisible)', () => {
+    const snap = computeStatsSnapshot(
+      [
+        makeConn('c1'),
+        makeConn('c2'),
+        makeConn('c3', { invisible: true }),
+        makeConn('c4', { invisible: true }),
+      ],
+      0,
+      0,
+    );
+    expect(snap.users).toBe(2);
+    expect(snap.invisible).toBe(2);
+    expect(snap.localConns).toBe(4);
+  });
+
+  it('defaults maxConns to the live count when seed omitted', () => {
+    const snap = computeStatsSnapshot([makeConn('c1'), makeConn('c2')], 0, 0);
+    expect(snap.maxLocalConns).toBe(2);
+    expect(snap.maxGlobalConns).toBe(2);
+  });
+
+  it('uses the FakeClock only for uptime (not in the snapshot)', async () => {
+    const clock = new FakeClock(99_000);
+    const stats = new InMemoryStats({
+      connections: new Map(),
+      channels: new Map(),
+      uptimeStartedAt: 1_000,
+      clock,
+    });
+    const snap = await stats.getStats();
+    expect(snap.uptimeStartedAt).toBe(1_000);
+  });
+});

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

@@ -131,6 +131,33 @@ describe('Ctx / Reducer types', () => {
     const ctx = makeCtx();
     expect(ctx.history).toBeUndefined();
   });
+
+  it('threads an inbound label through buildCtx onto ctx.label', () => {
+    const ctx = buildCtx({
+      serverConfig: {
+        serverName: 'irc.example.com',
+        networkName: 'ExampleNet',
+        maxChannelsPerUser: 30,
+        maxTargetsPerCommand: 10,
+        maxListEntries: 50,
+        nickLen: 30,
+        channelLen: 50,
+        topicLen: 390,
+        quitMessage: 'Client Quit',
+      },
+      clock: new FakeClock(1_000),
+      ids: new SequentialIdFactory(),
+      motd: EmptyMotdProvider,
+      connection: createConnection({ id: 'c1', connectedSince: 0 }),
+      label: 'foo',
+    });
+    expect(ctx.label).toBe('foo');
+  });
+
+  it('omits ctx.label when no label is supplied', () => {
+    const ctx = makeCtx();
+    expect(ctx.label).toBeUndefined();
+  });
 });
 
 describe('ServerConfig shape', () => {

package/packages/irc-core/tests/ws-framing.test.ts

@@ -0,0 +1,213 @@
+import { describe, expect, it } from 'vitest';
+import {
+  MAX_WS_MESSAGE_BYTES,
+  type WsFrameMode,
+  frameToLines,
+  isWithinWsByteBudget,
+  sanitizeForTextMode,
+  stripTrailingCrLf,
+  wsFrameModeFor,
+} from '../src/ws-framing';
+
+// ============================================================================
+// MAX_WS_MESSAGE_BYTES constant
+// ============================================================================
+
+describe('MAX_WS_MESSAGE_BYTES', () => {
+  it('is 510 (the IRC line-content limit; WS spec omits the trailing CRLF)', () => {
+    expect(MAX_WS_MESSAGE_BYTES).toBe(510);
+  });
+});
+
+// ============================================================================
+// wsFrameModeFor — subprotocol → WsFrameMode mapping
+// ============================================================================
+
+describe('wsFrameModeFor', () => {
+  it('maps text.ircv3.net to spec-text', () => {
+    expect(wsFrameModeFor('text.ircv3.net')).toBe('spec-text');
+  });
+
+  it('maps binary.ircv3.net to spec-binary', () => {
+    expect(wsFrameModeFor('binary.ircv3.net')).toBe('spec-binary');
+  });
+
+  it('maps undefined (no subprotocol) to legacy', () => {
+    expect(wsFrameModeFor(undefined)).toBe('legacy');
+  });
+});
+
+// ============================================================================
+// stripTrailingCrLf
+// ============================================================================
+
+describe('stripTrailingCrLf', () => {
+  it('strips a trailing CR-LF', () => {
+    expect(stripTrailingCrLf('NICK bob\r\n')).toBe('NICK bob');
+  });
+
+  it('strips a trailing bare LF', () => {
+    expect(stripTrailingCrLf('NICK bob\n')).toBe('NICK bob');
+  });
+
+  it('leaves a string with no trailing terminator unchanged', () => {
+    expect(stripTrailingCrLf('NICK bob')).toBe('NICK bob');
+  });
+
+  it('strips only a single trailing terminator', () => {
+    expect(stripTrailingCrLf('a\r\n\r\n')).toBe('a\r\n');
+  });
+
+  it('returns the empty string unchanged', () => {
+    expect(stripTrailingCrLf('')).toBe('');
+  });
+
+  it('does not strip a leading CR-LF', () => {
+    expect(stripTrailingCrLf('\r\nNICK bob')).toBe('\r\nNICK bob');
+  });
+});
+
+// ============================================================================
+// frameToLines — spec-text / spec-binary modes (one IRC message per frame)
+// ============================================================================
+
+describe('frameToLines — spec-text', () => {
+  it('strips a trailing CR-LF and returns a single-element array', () => {
+    expect(frameToLines('NICK bob\r\n', 'spec-text')).toEqual(['NICK bob']);
+  });
+
+  it('strips a trailing bare LF', () => {
+    expect(frameToLines('NICK bob\n', 'spec-text')).toEqual(['NICK bob']);
+  });
+
+  it('does not split on an embedded LF (one WS message === one IRC line)', () => {
+    expect(frameToLines('NICK bob\nextra', 'spec-text')).toEqual(['NICK bob\nextra']);
+  });
+
+  it('returns an empty array for an empty frame', () => {
+    expect(frameToLines('', 'spec-text')).toEqual([]);
+  });
+
+  it('returns an empty array for a frame that is only a terminator', () => {
+    expect(frameToLines('\r\n', 'spec-text')).toEqual([]);
+  });
+
+  it('returns a single bare line unchanged when there is no terminator', () => {
+    expect(frameToLines('PING :tok', 'spec-text')).toEqual(['PING :tok']);
+  });
+});
+
+describe('frameToLines — spec-binary', () => {
+  it('behaves identically to spec-text (single line, terminator stripped)', () => {
+    expect(frameToLines('NICK bob\n', 'spec-binary')).toEqual(['NICK bob']);
+  });
+
+  it('does not split on an embedded LF', () => {
+    expect(frameToLines('a\nb', 'spec-binary')).toEqual(['a\nb']);
+  });
+});
+
+// ============================================================================
+// frameToLines — legacy mode (the pre-spec split-on-/\r?\n/ behaviour)
+// ============================================================================
+
+describe('frameToLines — legacy', () => {
+  it('splits on CR-LF into separate lines', () => {
+    expect(frameToLines('a\r\nb', 'legacy')).toEqual(['a', 'b']);
+  });
+
+  it('splits on bare LF', () => {
+    expect(frameToLines('a\nb', 'legacy')).toEqual(['a', 'b']);
+  });
+
+  it('returns an empty array for the empty string', () => {
+    expect(frameToLines('', 'legacy')).toEqual([]);
+  });
+
+  it('returns a single bare line with no terminator unchanged', () => {
+    expect(frameToLines('PING :tok', 'legacy')).toEqual(['PING :tok']);
+  });
+
+  it('emits a trailing empty string for a terminated frame', () => {
+    expect(frameToLines('PING :tok\r\n', 'legacy')).toEqual(['PING :tok', '']);
+  });
+
+  it('splits several joined messages keeping a trailing empty string', () => {
+    expect(frameToLines('a\r\nb\r\n', 'legacy')).toEqual(['a', 'b', '']);
+  });
+});
+
+// Exhaustiveness guard: every declared mode is covered by the specs above.
+describe('frameToLines — mode coverage', () => {
+  const modes: WsFrameMode[] = ['spec-text', 'spec-binary', 'legacy'];
+  for (const mode of modes) {
+    it(`accepts the '${mode}' mode without throwing`, () => {
+      expect(Array.isArray(frameToLines('x', mode))).toBe(true);
+    });
+  }
+});
+
+// ============================================================================
+// isWithinWsByteBudget — the IRCv3 WS message byte cap
+// ============================================================================
+
+describe('isWithinWsByteBudget', () => {
+  it('accepts a frame whose length equals the 510-byte budget', () => {
+    expect(isWithinWsByteBudget('a'.repeat(510))).toBe(true);
+  });
+
+  it('rejects a frame whose length is one byte over the budget', () => {
+    expect(isWithinWsByteBudget('a'.repeat(511))).toBe(false);
+  });
+
+  it('accepts the empty string', () => {
+    expect(isWithinWsByteBudget('')).toBe(true);
+  });
+
+  it('accepts a short frame', () => {
+    expect(isWithinWsByteBudget('NICK bob')).toBe(true);
+  });
+});
+
+// ============================================================================
+// sanitizeForTextMode — replace lone surrogates with U+FFFD
+// ============================================================================
+
+describe('sanitizeForTextMode', () => {
+  it('replaces a lone high surrogate with U+FFFD', () => {
+    expect(sanitizeForTextMode('\uD800')).toBe('\uFFFD');
+  });
+
+  it('replaces a lone low surrogate with U+FFFD', () => {
+    expect(sanitizeForTextMode('\uDC00')).toBe('\uFFFD');
+  });
+
+  it('leaves a valid surrogate pair (a supplementary code point) unchanged', () => {
+    // U+10000 = \uD800\uDC00
+    expect(sanitizeForTextMode('\uD800\uDC00')).toBe('\uD800\uDC00');
+  });
+
+  it('leaves plain ASCII text unchanged', () => {
+    expect(sanitizeForTextMode('hello')).toBe('hello');
+  });
+
+  it('replaces a lone surrogate embedded in normal text', () => {
+    expect(sanitizeForTextMode('a\uD800b')).toBe('a\uFFFDb');
+  });
+
+  it('replaces two consecutive lone high surrogates with two U+FFFD', () => {
+    expect(sanitizeForTextMode('\uD800\uD800')).toBe('\uFFFD\uFFFD');
+  });
+
+  it('preserves a valid pair surrounded by normal text', () => {
+    expect(sanitizeForTextMode('x\uD83D\uDE00y')).toBe('x\uD83D\uDE00y');
+  });
+
+  it('replaces a lone high surrogate followed later by a lone low surrogate', () => {
+    expect(sanitizeForTextMode('\uD800a\uDC00')).toBe('\uFFFDa\uFFFD');
+  });
+
+  it('returns the empty string unchanged', () => {
+    expect(sanitizeForTextMode('')).toBe('');
+  });
+});

package/packages/irc-core/tests/ws-subprotocol.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, it } from 'vitest';
+import {
+  WS_SUBPROTO_BINARY,
+  WS_SUBPROTO_TEXT,
+  type WsSubprotocol,
+  parseSecWsProtocolOffers,
+  selectSubprotocol,
+} from '../src/ws-subprotocol';
+
+// ============================================================================
+// constants & type
+// ============================================================================
+
+describe('WS subprotocol constants', () => {
+  it('exposes the IRCv3 text subprotocol name', () => {
+    expect(WS_SUBPROTO_TEXT).toBe('text.ircv3.net');
+  });
+
+  it('exposes the IRCv3 binary subprotocol name', () => {
+    expect(WS_SUBPROTO_BINARY).toBe('binary.ircv3.net');
+  });
+
+  it('the WsSubprotocol type resolves to the two literal names', () => {
+    const a: WsSubprotocol = WS_SUBPROTO_TEXT;
+    const b: WsSubprotocol = WS_SUBPROTO_BINARY;
+    expect([a, b]).toEqual([WS_SUBPROTO_TEXT, WS_SUBPROTO_BINARY]);
+  });
+});
+
+// ============================================================================
+// parseSecWsProtocolOffers — header parsing
+// ============================================================================
+
+describe('parseSecWsProtocolOffers', () => {
+  it('splits a comma-separated list into ordered offers', () => {
+    expect(parseSecWsProtocolOffers('text.ircv3.net, binary.ircv3.net')).toEqual([
+      'text.ircv3.net',
+      'binary.ircv3.net',
+    ]);
+  });
+
+  it('trims whitespace around each item', () => {
+    expect(parseSecWsProtocolOffers(' text.ircv3.net , binary.ircv3.net ')).toEqual([
+      'text.ircv3.net',
+      'binary.ircv3.net',
+    ]);
+  });
+
+  it('preserves client-preference order', () => {
+    expect(parseSecWsProtocolOffers('binary.ircv3.net, text.ircv3.net')).toEqual([
+      'binary.ircv3.net',
+      'text.ircv3.net',
+    ]);
+  });
+
+  it('returns an empty array for null', () => {
+    expect(parseSecWsProtocolOffers(null)).toEqual([]);
+  });
+
+  it('returns an empty array for undefined', () => {
+    expect(parseSecWsProtocolOffers(undefined)).toEqual([]);
+  });
+
+  it('returns an empty array for an empty string', () => {
+    expect(parseSecWsProtocolOffers('')).toEqual([]);
+  });
+
+  it('drops empty entries produced by stray commas', () => {
+    expect(parseSecWsProtocolOffers('text.ircv3.net,, ,binary.ircv3.net')).toEqual([
+      'text.ircv3.net',
+      'binary.ircv3.net',
+    ]);
+  });
+
+  it('preserves duplicate entries in order', () => {
+    expect(parseSecWsProtocolOffers('text.ircv3.net, text.ircv3.net')).toEqual([
+      'text.ircv3.net',
+      'text.ircv3.net',
+    ]);
+  });
+});
+
+// ============================================================================
+// selectSubprotocol — preference-ordered selection
+// ============================================================================
+
+describe('selectSubprotocol', () => {
+  it('returns the first supported offer in client-preference order (text first)', () => {
+    expect(selectSubprotocol(['text.ircv3.net', 'binary.ircv3.net'])).toBe('text.ircv3.net');
+  });
+
+  it('honours client preference when binary is offered first', () => {
+    expect(selectSubprotocol(['binary.ircv3.net', 'text.ircv3.net'])).toBe('binary.ircv3.net');
+  });
+
+  it('returns null when only unsupported protocols are offered', () => {
+    expect(selectSubprotocol(['foo', 'bar'])).toBeNull();
+  });
+
+  it('returns null for an empty offer list', () => {
+    expect(selectSubprotocol([])).toBeNull();
+  });
+
+  it('skips unsupported offers and selects the first supported one', () => {
+    expect(selectSubprotocol(['foo', 'binary.ircv3.net'])).toBe('binary.ircv3.net');
+  });
+
+  it('returns the first occurrence for duplicate supported offers', () => {
+    expect(selectSubprotocol(['text.ircv3.net', 'text.ircv3.net'])).toBe('text.ircv3.net');
+  });
+});

package/packages/irc-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/irc-server",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "private": true,
   "description": "Orchestration layer: IrcRuntime port, dispatch interpreter, ConnectionActor",
   "license": "BSD-3-Clause",