serverless-ircd 0.2.0 → 0.4.0

package/packages/irc-server/tests/dispatch.test.ts

@@ -146,23 +146,6 @@ describe('dispatch', () => {
     expect(calls[0]).toEqual({ method: 'applyChannelDelta', args: ['#foo', delta] });
   });
 
-  it('invokes lookupNick, getConnectionInfo, getChannelSnapshot lookups', async () => {
-    const calls: RecordedCall[] = [];
-    await dispatch(
-      [
-        Effect.lookupNick('alice'),
-        Effect.getConnectionInfo('c1'),
-        Effect.getChannelSnapshot('#foo'),
-      ],
-      fakeRuntime(calls),
-    );
-    expect(calls.map((c) => c.method)).toEqual([
-      'lookupNick',
-      'getConnectionInfo',
-      'getChannelSnapshot',
-    ]);
-  });
-
   it('awaits each effect in sequence (one fails, the rest after it do not run)', async () => {
     const calls: RecordedCall[] = [];
     const failing: IrcRuntime = {

package/packages/irc-server/tests/routing.test.ts

@@ -109,10 +109,12 @@ describe('buildRoutedReducers', () => {
     const reducers = buildRoutedReducers(baseServerConfig);
     expect(Object.keys(reducers).sort()).toEqual(
       [
+        'admin',
         'authenticate',
         'away',
         'cap',
         'channelMode',
+        'info',
         'invite',
         'join',
         'kick',
@@ -121,6 +123,7 @@ describe('buildRoutedReducers', () => {
         'nick',
         'noticeChannel',
         'noticeUser',
+        'oper',
         'part',
         'pass',
         'ping',
@@ -128,9 +131,13 @@ describe('buildRoutedReducers', () => {
         'privmsgChannel',
         'privmsgUser',
         'quit',
+        'tagmsgChannel',
+        'tagmsgUser',
+        'time',
         'topic',
         'user',
         'userMode',
+        'version',
       ].sort(),
     );
   });

package/packages/irc-server/tests/transport.test.ts

@@ -0,0 +1,230 @@
+import { describe, expect, it } from 'vitest';
+import { TcpByteStreamTransport, WsTextFrameTransport } from '../src/transport';
+import type { Transport } from '../src/transport';
+
+// ---------------------------------------------------------------------------
+// Transport seam: the generalized line-framing contract shared by the
+// WebSocket and raw TCP+TLS transports (PLAN §9, ADR-009).
+//
+// Two transports share one parser/reducer/dispatch pipeline:
+//   - WsTextFrameTransport  — one (or N `\r\n`-joined) IRC message(s) per WS
+//                             text frame; a frame is a complete unit, so a
+//                             trailing unterminated line is still emitted.
+//   - TcpByteStreamTransport — stateful `\r\n` byte-stream framing across
+//                             arbitrary chunks with partial-line buffering.
+// ---------------------------------------------------------------------------
+
+describe('WsTextFrameTransport', () => {
+  it('returns [] for an empty frame', () => {
+    const t = new WsTextFrameTransport();
+    expect(t.feed('')).toEqual([]);
+  });
+
+  it('emits a trailing unterminated line (a WS frame is a complete unit)', () => {
+    const t = new WsTextFrameTransport();
+    expect(t.feed('PING :tok')).toEqual(['PING :tok']);
+  });
+
+  it('splits a CRLF-terminated single line', () => {
+    const t = new WsTextFrameTransport();
+    expect(t.feed('PING :tok\r\n')).toEqual(['PING :tok', '']);
+  });
+
+  it('splits a frame with N CRLF-joined messages into N lines (in order)', () => {
+    const t = new WsTextFrameTransport();
+    expect(t.feed('PING :a\r\nPING :b\r\nPING :c\r\n')).toEqual([
+      'PING :a',
+      'PING :b',
+      'PING :c',
+      '',
+    ]);
+  });
+
+  it('tolerates bare LF endings', () => {
+    const t = new WsTextFrameTransport();
+    expect(t.feed('PING :a\nPING :b\n')).toEqual(['PING :a', 'PING :b', '']);
+  });
+
+  it('keeps empty lines between messages (the actor skips them)', () => {
+    const t = new WsTextFrameTransport();
+    expect(t.feed('PING :a\r\n\r\nPING :b\r\n')).toEqual(['PING :a', '', 'PING :b', '']);
+  });
+
+  it('is stateless: the same frame fed twice yields the same result', () => {
+    const t = new WsTextFrameTransport();
+    const first = t.feed('PING :a\r\n');
+    const second = t.feed('PING :a\r\n');
+    expect(second).toEqual(first);
+  });
+});
+
+describe('TcpByteStreamTransport', () => {
+  it('returns [] for an empty chunk', () => {
+    const t = new TcpByteStreamTransport();
+    expect(t.feed('')).toEqual([]);
+  });
+
+  it('emits one complete CRLF-terminated line in a single chunk', () => {
+    const t = new TcpByteStreamTransport();
+    expect(t.feed('PRIVMSG #foo :hello\r\n')).toEqual(['PRIVMSG #foo :hello']);
+  });
+
+  it('buffers a partial line and emits nothing until the terminator arrives', () => {
+    const t = new TcpByteStreamTransport();
+    expect(t.feed('PRIVMSG #foo :hel')).toEqual([]);
+    expect(t.feed('lo\r\n')).toEqual(['PRIVMSG #foo :hello']);
+  });
+
+  it('two chunks split mid-line produce exactly one complete line (no loss, no duplication)', () => {
+    const t = new TcpByteStreamTransport();
+    expect(t.feed('PRIVMSG #foo :hel')).toEqual([]);
+    expect(t.feed('lo\r\n')).toEqual(['PRIVMSG #foo :hello']);
+    // A third empty chunk must not re-emit anything.
+    expect(t.feed('')).toEqual([]);
+  });
+
+  it('emits multiple complete lines delivered in one chunk, in order', () => {
+    const t = new TcpByteStreamTransport();
+    expect(t.feed('PING :a\r\nPING :b\r\nPING :c\r\n')).toEqual(['PING :a', 'PING :b', 'PING :c']);
+  });
+
+  it('terminates on bare LF (mixed/legacy clients)', () => {
+    const t = new TcpByteStreamTransport();
+    expect(t.feed('PING :a\nPING :b\n')).toEqual(['PING :a', 'PING :b']);
+  });
+
+  it('handles mixed CRLF and LF terminators in one stream', () => {
+    const t = new TcpByteStreamTransport();
+    expect(t.feed('A\r\nB\nC\r\n')).toEqual(['A', 'B', 'C']);
+  });
+
+  it('emits empty lines for consecutive terminators (the actor skips them)', () => {
+    const t = new TcpByteStreamTransport();
+    expect(t.feed('PING :a\r\n\r\nPING :b\r\n')).toEqual(['PING :a', '', 'PING :b']);
+  });
+
+  it('emits an empty line for a chunk that is only a terminator', () => {
+    const t = new TcpByteStreamTransport();
+    expect(t.feed('\r\n')).toEqual(['']);
+  });
+
+  it('emits an empty line when a chunk starts with a bare LF (no preceding CR)', () => {
+    const t = new TcpByteStreamTransport();
+    expect(t.feed('\n')).toEqual(['']);
+  });
+
+  it('reassembles a line split across more than two chunks', () => {
+    const t = new TcpByteStreamTransport();
+    expect(t.feed('PRI')).toEqual([]);
+    expect(t.feed('VMSG')).toEqual([]);
+    expect(t.feed(' #foo :')).toEqual([]);
+    expect(t.feed('hi\r\n')).toEqual(['PRIVMSG #foo :hi']);
+  });
+
+  it('handles a CRLF terminator split across chunks (CR in one, LF in next)', () => {
+    const t = new TcpByteStreamTransport();
+    expect(t.feed('PING :tok\r')).toEqual([]);
+    expect(t.feed('\n')).toEqual(['PING :tok']);
+  });
+
+  it('does not treat a stray CR without a following LF as a terminator', () => {
+    const t = new TcpByteStreamTransport();
+    // A bare CR mid-line is part of the line until a LF terminates it.
+    expect(t.feed('PING :a\rb\r\n')).toEqual(['PING :a\rb']);
+  });
+
+  it('preserves a trailing unterminated line across a flush of complete lines', () => {
+    const t = new TcpByteStreamTransport();
+    // Two complete lines plus the start of a third still in flight.
+    expect(t.feed('PING :a\r\nPING :b\r\nPI')).toEqual(['PING :a', 'PING :b']);
+    expect(t.feed('NG :c\r\n')).toEqual(['PING :c']);
+  });
+
+  it('satisfies the Transport interface contract', () => {
+    const t: Transport = new TcpByteStreamTransport();
+    expect(typeof t.feed).toBe('function');
+    expect(t.feed('x\r\n')).toEqual(['x']);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Buffer save/restore: the NLB+Lambda TCP adapter must persist
+// the partial-line buffer across independent Lambda invocations. The
+// TcpByteStreamTransport exposes getBuffer/restore so the handler can
+// snapshot the in-flight bytes to DynamoDB and rehydrate them on the next
+// chunk from the same NLB flow.
+// ---------------------------------------------------------------------------
+
+describe('TcpByteStreamTransport — buffer save/restore', () => {
+  it('getBuffer returns "" when no partial line is buffered', () => {
+    const t = new TcpByteStreamTransport();
+    expect(t.getBuffer()).toBe('');
+  });
+
+  it('getBuffer returns the buffered partial line after a feed', () => {
+    const t = new TcpByteStreamTransport();
+    t.feed('PRIVMSG #foo :hel');
+    expect(t.getBuffer()).toBe('PRIVMSG #foo :hel');
+  });
+
+  it('getBuffer returns "" after all buffered bytes have been terminated', () => {
+    const t = new TcpByteStreamTransport();
+    t.feed('PRIVMSG #foo :hel');
+    t.feed('lo\r\n');
+    expect(t.getBuffer()).toBe('');
+  });
+
+  it('restore seeds the buffer so a subsequent chunk completes the line', () => {
+    const t = new TcpByteStreamTransport();
+    t.restore('PRIVMSG #foo :hel');
+    expect(t.feed('lo\r\n')).toEqual(['PRIVMSG #foo :hello']);
+  });
+
+  it('a fresh transport restored from a snapshot + fed the next chunk matches the original', () => {
+    const original = new TcpByteStreamTransport();
+    original.feed('PING :a\r\nPRIV');
+    const snapshot = original.getBuffer();
+
+    const restored = new TcpByteStreamTransport();
+    restored.restore(snapshot);
+    expect(restored.feed('MSG #b :hi\r\n')).toEqual(['PRIVMSG #b :hi']);
+    expect(restored.getBuffer()).toBe('');
+  });
+
+  it('restore("") behaves like a fresh transport (empty buffer)', () => {
+    const t = new TcpByteStreamTransport();
+    t.restore('');
+    expect(t.getBuffer()).toBe('');
+    expect(t.feed('PING :x\r\n')).toEqual(['PING :x']);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Equivalence: a fully-terminated message stream produces the same complete
+// lines regardless of how it is chunked across feed() calls.
+// ---------------------------------------------------------------------------
+
+describe('Transport — WS vs TCP framing equivalence', () => {
+  it('a fully-terminated single line yields the same complete line from both', () => {
+    const ws = new WsTextFrameTransport();
+    const tcp = new TcpByteStreamTransport();
+    const frame = 'PRIVMSG #foo :hello\r\n';
+    // Both transports emit the same complete line (the WS transport also
+    // yields a trailing '' from the final terminator, which the actor skips).
+    expect(ws.feed(frame)[0]).toBe(tcp.feed(frame)[0]);
+  });
+
+  it('chunking the same bytes arbitrarily never changes the reassembled lines', () => {
+    const stream = 'PRIVMSG #a :1\r\nPRIVMSG #b :2\r\nNOTICE #c :3\r\n';
+    const wsAll = new WsTextFrameTransport().feed(stream).filter((l) => l.length > 0);
+
+    // Feed the TCP transport the same bytes in arbitrary 5-byte chunks.
+    const tcp = new TcpByteStreamTransport();
+    const tcpLines: string[] = [];
+    for (let i = 0; i < stream.length; i += 5) {
+      tcpLines.push(...tcp.feed(stream.slice(i, i + 5)));
+    }
+    // Empty artifacts filtered, the reassembled lines are byte-identical.
+    expect(tcpLines.filter((l) => l.length > 0)).toEqual(wsAll);
+  });
+});

package/packages/irc-test-support/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/irc-test-support",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "private": true,
   "description": "Shared IRC scenario runner + harness seam used by every adapter's integration suite",
   "license": "BSD-3-Clause",

package/packages/irc-test-support/src/harness.ts

@@ -5,20 +5,37 @@
  * scenarios pass in-memory + CF + AWS." This file defines the seam:
  *
  *   - {@link IrcHarnessFactory} builds a fresh, isolated world per test.
- *     Each runtime (in-memory now; CF in Phase 3; AWS in Phase 4) ships
- *     one factory. Adding a runtime to the parametrized suite is exactly
- *     "register another factory in the `describe.each` table".
+ *     Each (runtime × transport) combination ships one factory. Adding a
+ *     runtime OR a transport to the parametrized suite is exactly "register
+ *     another factory in the `describe.each` table".
  *   - {@link IrcHarness} spawns clients, each a single IRC connection.
  *   - {@link ClientHarness} is the per-connection handle: send a raw IRC
- *     line, observe received lines, await a predicate, register the
- *     connection (NICK+USER), close.
+ *     line, feed raw transport bytes (for framing tests), observe received
+ *     lines, await a predicate, register the connection (NICK+USER), close.
  *
  * The harness hides platform-specific transport (in-memory actor,
- * HibernatingWebSocket in a ConnectionDO, APIGW `$default` Lambda) behind
- * one synchronous-looking API. Tests are written once and exercise the
- * full pipeline: bytes → framed messages → reducer → dispatch → runtime.
+ * HibernatingWebSocket in a ConnectionDO, APIGW `$default` Lambda, raw
+ * TCP+TLS byte stream) behind one synchronous-looking API. Tests are
+ * written once and exercise the full pipeline: bytes → framed messages →
+ * reducer → dispatch.
  */
 
+/**
+ * The kind of line-framing transport a factory binds. Drives the
+ * (runtime × transport) parametrized matrix:
+ *   - `ws`  — one WebSocket text frame per inbound unit (one or N
+ *             `\r\n`-joined messages); a trailing unterminated line is
+ *             still emitted because a frame is a complete unit.
+ *   - `tcp` — a raw TCP+TLS byte stream; arbitrary chunk boundaries with
+ *             stateful `\r\n` framing and partial-line buffering across
+ *             chunks (PLAN §9, ADR-009).
+ *
+ * The scenario runner uses this to gate transport-specific cases: the
+ * TCP-framing scenarios (chunk boundaries, slow-loris partial sends, bare
+ * `\n` tolerance) only run against `transport: 'tcp'` factories.
+ */
+export type TransportKind = 'ws' | 'tcp';
+
 import type { ConnId } from '@serverless-ircd/irc-core';
 
 /**
@@ -29,8 +46,14 @@ import type { ConnId } from '@serverless-ircd/irc-core';
  * once per `it(...)` and immediately tears down via {@link IrcHarness.close}.
  */
 export interface IrcHarnessFactory {
-  /** Human-readable label for `describe.each` output (e.g. `"in-memory"`). */
+  /** Human-readable label for `describe.each` output (e.g. `"in-memory+ws"`). */
   readonly name: string;
+  /**
+   * The line-framing transport this factory binds. Drives the
+   * (runtime × transport) matrix and gates transport-specific scenarios
+   * (the TCP-framing block only runs against `transport: 'tcp'`).
+   */
+  readonly transport: TransportKind;
   /** Constructs a new harness. MUST NOT retain state across invocations. */
   create(): Promise<IrcHarness>;
 }
@@ -83,8 +106,20 @@ export interface ClientHarness {
   /**
    * Sends one IRC line as this connection. The harness frames it
    * (`line + \r\n`) and routes through the runtime's full pipeline.
+   * Equivalent to {@link feed} with a single complete terminated line;
+   * prefer `send` for ordinary one-line-per-call test setup.
    */
   send(line: string): Promise<void>;
+  /**
+   * Feeds raw transport input as this connection — one WebSocket text
+   * frame for the `ws` transport, one arbitrary byte chunk for the `tcp`
+   * transport. Use this to exercise transport-specific line framing:
+   * chunk boundaries, partial-line buffering, slow-loris-style partial
+   * sends, mixed `\r\n` / bare `\n` endings. The chunk is routed through
+   * the bound {@link Transport} and the resulting complete lines dispatch
+   * through the full pipeline.
+   */
+  feed(chunk: string): Promise<void>;
   /**
    * Resolves with the first line (already-seen or future) matching
    * `predicate`. Rejects after `timeoutMs` (default 1000) with the

package/packages/irc-test-support/src/in-memory-harness.ts

@@ -24,12 +24,18 @@ import {
   StaticMotdProvider,
   createConnection,
 } from '@serverless-ircd/irc-core';
-import { ConnectionActor } from '@serverless-ircd/irc-server';
+import {
+  ConnectionActor,
+  TcpByteStreamTransport,
+  type Transport,
+  WsTextFrameTransport,
+} from '@serverless-ircd/irc-server';
 import type {
   ClientHarness,
   IrcHarness,
   IrcHarnessFactory,
   SpawnClientOptions,
+  TransportKind,
 } from './harness.js';
 
 /** Default tick for the polling waitFor* implementations (ms). */
@@ -52,10 +58,11 @@ export const HARNESS_SERVER_CONFIG = {
 } as const;
 
 /**
- * Default MOTD lines exposed to every spawned client. The welcome block
- * always emits the placeholder 375/372/376 numerics; an explicit `MOTD`
- * command after registration reads these lines via the {@link MotdProvider}
- * port. Tests assert against this content (scenario: MOTD).
+ * Default MOTD lines exposed to every spawned client. The registration
+ * welcome block renders these lines as `375`/`372`×N/`376` numerics, and
+ * an explicit `MOTD` command after registration reads them again via the
+ * {@link MotdProvider} port. Tests assert against this content
+ * (scenario: MOTD).
  */
 export const HARNESS_MOTD_LINES = [
   'Welcome to the ServerlessIRCd integration-test harness.',
@@ -63,16 +70,44 @@ export const HARNESS_MOTD_LINES = [
 ];
 
 /**
- * Factory entry for the in-memory runtime. Append this to a suite's
- * FACTORIES array to opt the scenarios into the in-memory matrix.
+ * Factory entry for the in-memory runtime over the WebSocket text-frame
+ * transport (PLAN §9, ADR-009). Append this to a suite's FACTORIES array
+ * to opt the scenarios into the in-memory+ws cell of the
+ * (runtime × transport) matrix.
+ */
+export const inMemoryWsHarnessFactory: IrcHarnessFactory = Object.freeze({
+  name: 'in-memory+ws',
+  transport: 'ws',
+  async create() {
+    return new InMemoryHarness('ws');
+  },
+});
+
+/**
+ * Factory entry for the in-memory runtime over the raw TCP+TLS byte-stream
+ * transport (stateful `\r\n` framing with partial-line buffering across
+ * chunks — PLAN §9, ADR-009). Append this to a suite's FACTORIES array to
+ * opt the scenarios into the in-memory+tcp cell of the
+ * (runtime × transport) matrix. Lights up the TCP-framing
+ * scenario block (chunk boundaries, slow-loris sends, bare `\n`).
  */
-export const inMemoryHarnessFactory: IrcHarnessFactory = Object.freeze({
-  name: 'in-memory',
+export const inMemoryTcpHarnessFactory: IrcHarnessFactory = Object.freeze({
+  name: 'in-memory+tcp',
+  transport: 'tcp',
   async create() {
-    return new InMemoryHarness();
+    return new InMemoryHarness('tcp');
   },
 });
 
+/**
+ * Legacy alias for {@link inMemoryWsHarnessFactory}. Before the
+ * transport dimension was added, the in-memory runtime registered a
+ * single factory with no transport dimension; that factory was
+ * implicitly the WebSocket transport. Kept so existing adapter suites
+ * and tests referencing `inMemoryHarnessFactory` keep compiling unchanged.
+ */
+export const inMemoryHarnessFactory: IrcHarnessFactory = inMemoryWsHarnessFactory;
+
 interface TrackedClient {
   harness: InMemoryClientHarness;
   disconnect: () => void;
@@ -84,9 +119,22 @@ export class InMemoryHarness implements IrcHarness {
   private readonly ids = new SequentialIdFactory();
   private readonly motd = new StaticMotdProvider(HARNESS_MOTD_LINES);
   private readonly clients = new Map<ConnId, TrackedClient>();
+  private readonly transportKind: TransportKind;
   private nextId = 0;
   private closed = false;
 
+  /**
+   * @param transportKind The line-framing transport each spawned client's
+   *   actor binds. `'ws'` (default) uses a stateless
+   *   {@link WsTextFrameTransport}; `'tcp'` uses a stateful
+   *   {@link TcpByteStreamTransport} so chunk-boundary scenarios exercise
+   *   real byte-stream framing. One transport instance per client (TCP
+   *   transports own a per-connection partial-line buffer).
+   */
+  constructor(transportKind: TransportKind = 'ws') {
+    this.transportKind = transportKind;
+  }
+
   async spawnClient(opts?: SpawnClientOptions): Promise<ClientHarness> {
     if (this.closed) throw new Error('spawnClient called on a closed harness');
     const id = opts?.id ?? `c${this.nextId++}`;
@@ -118,6 +166,7 @@ export class InMemoryHarness implements IrcHarness {
       clock: this.clock,
       ids: this.ids,
       motd: this.motd,
+      transport: this.newTransport(),
     });
     client.bindActor(actor);
 
@@ -135,6 +184,15 @@ export class InMemoryHarness implements IrcHarness {
     return client;
   }
 
+  /**
+   * Allocates a fresh transport instance for one client. TCP transports
+   * carry per-connection partial-line state, so each client MUST receive
+   * its own instance rather than a shared one.
+   */
+  private newTransport(): Transport {
+    return this.transportKind === 'tcp' ? new TcpByteStreamTransport() : new WsTextFrameTransport();
+  }
+
   async clientByNick(nick: string): Promise<ClientHarness | undefined> {
     const connId = await this.runtime.lookupNick(nick);
     if (connId === null) return undefined;
@@ -172,13 +230,20 @@ class InMemoryClientHarness implements ClientHarness {
   }
 
   async send(line: string): Promise<void> {
+    // `send` is `feed` with one complete terminated line; routing both
+    // through the bound transport guarantees a transport change lights up
+    // identically across the scenario suite.
+    await this.feed(`${line}\r\n`);
+  }
+
+  async feed(chunk: string): Promise<void> {
     /* istanbul ignore next -- defensive: bindActor is called by the
        harness before the client is returned, so the unbound-actor branch
        is unreachable through the public API. */
     if (this.actor === undefined) {
       throw new Error(`client ${this.id} has no bound actor`);
     }
-    await this.actor.receiveTextFrame(`${line}\r\n`);
+    await this.actor.receive(chunk);
   }
 
   async waitForLine(
@@ -216,8 +281,8 @@ class InMemoryClientHarness implements ClientHarness {
     // disconnect handler is wired by the harness to unregister.
     if (this.actor !== undefined) {
       try {
-        await this.actor.receiveTextFrame('QUIT :client closed\r\n');
-        /* istanbul ignore next -- defensive: receiveTextFrame swallows
+        await this.actor.receive('QUIT :client closed\r\n');
+        /* istanbul ignore next -- defensive: receive swallows
            every error internally; the catch is purely a teardown safety
            net for catastrophic runtime failures. */
       } catch {

package/packages/irc-test-support/src/index.ts

@@ -14,11 +14,14 @@ export type {
   IrcHarness,
   IrcHarnessFactory,
   SpawnClientOptions,
+  TransportKind,
 } from './harness.js';
 export {
   HARNESS_MOTD_LINES,
   HARNESS_SERVER_CONFIG,
   InMemoryHarness,
   inMemoryHarnessFactory,
+  inMemoryTcpHarnessFactory,
+  inMemoryWsHarnessFactory,
 } from './in-memory-harness.js';
 export { runIrcScenarios } from './scenarios.js';