serverless-ircd 0.1.0

package/tools/tcp-ws-forwarder/tests/forwarder.test.ts

@@ -0,0 +1,618 @@
+import { EventEmitter } from 'node:events';
+import http from 'node:http';
+import { type Socket, createConnection, createServer as createNetServer } from 'node:net';
+import type { AddressInfo } from 'node:net';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { RawData, WebSocket } from 'ws';
+import { WebSocketServer as WsServer } from 'ws';
+import { startForwarder } from '../src/forwarder';
+
+/**
+ * Integration tests for the TCP↔WS forwarder against real sockets.
+ *
+ * Each test spins up:
+ *   - a target `ws` server (the stand-in for the deployed ServerlessIRCd
+ *     WebSocket endpoint), and
+ *   - the forwarder, pointed at that target,
+ * then opens a raw TCP socket into the forwarder and asserts the bridge
+ * behaves like an invisible IRC wire in both directions.
+ *
+ * The forwarder is protocol-agnostic; these tests frame behavior in
+ * IRC-shaped lines but assert only on bytes/frames.
+ */
+
+/** Decodes any `ws` RawData variant to a UTF-8 string. */
+function toUtf8(data: RawData): string {
+  const buf = Array.isArray(data)
+    ? Buffer.concat(data)
+    : Buffer.isBuffer(data)
+      ? data
+      : data instanceof ArrayBuffer
+        ? Buffer.from(data)
+        : Buffer.from(data as Uint8Array);
+  return buf.toString('utf8');
+}
+
+/** Reserves an ephemeral port then releases it, returning a now-closed port. */
+async function getClosedPort(): Promise<number> {
+  const s = createNetServer();
+  return new Promise((resolve, reject) => {
+    s.once('error', reject);
+    s.listen(0, '127.0.0.1', () => {
+      const port = (s.address() as AddressInfo).port;
+      s.close(() => resolve(port));
+    });
+  });
+}
+
+interface Target {
+  readonly port: number;
+  readonly frames: string[];
+  readonly connections: WebSocket[];
+  waitForConnection(): Promise<WebSocket>;
+  close(): Promise<void>;
+}
+
+/** Starts a fast (immediate-upgrade) target WS server on an ephemeral port. */
+function startTarget(): Promise<Target> {
+  return startDelayedTarget(0);
+}
+
+/** Starts a target WS server whose upgrade completes after `delayMs`. */
+function startDelayedTarget(delayMs: number): Promise<Target> {
+  const wss = new WsServer({ noServer: true });
+  const server = http.createServer();
+  const frames: string[] = [];
+  const connections: WebSocket[] = [];
+  // Each waitForConnection() call expects the next distinct connection, in
+  // arrival order; queue waiters that resolve one-for-one as connections land.
+  const waiters: Array<(ws: WebSocket) => void> = [];
+  let waitForCount = 0;
+
+  server.on('upgrade', (req, socket, head) => {
+    const finish = () => {
+      wss.handleUpgrade(req, socket, head, (ws) => {
+        connections.push(ws);
+        ws.on('message', (data) => frames.push(toUtf8(data as RawData)));
+        const waiter = waiters.shift();
+        if (waiter) waiter(ws);
+      });
+    };
+    if (delayMs > 0) setTimeout(finish, delayMs);
+    else finish();
+  });
+
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const port = (server.address() as AddressInfo).port;
+      resolve({
+        port,
+        frames,
+        connections,
+        waitForConnection: () =>
+          new Promise((res) => {
+            const want = waitForCount++;
+            if (connections.length > want) res(connections[want] as WebSocket);
+            else waiters.push(res);
+          }),
+        close: () =>
+          new Promise<void>((r) => {
+            for (const ws of connections) ws.close();
+            wss.close(() => server.close(() => r()));
+          }),
+      });
+    });
+  });
+}
+
+/** Minimal line-oriented TCP IRC-style client used to drive the forwarder. */
+class TcpClient extends EventEmitter {
+  readonly socket: Socket;
+  readonly received: string[] = [];
+  private buf = '';
+
+  constructor(port: number, host = '127.0.0.1') {
+    super();
+    this.socket = createConnection({ port, host });
+    this.socket.setEncoding('utf8');
+    this.socket.on('data', (chunk: string) => {
+      this.buf += chunk;
+      let idx = this.buf.indexOf('\n');
+      while (idx !== -1) {
+        const line = this.buf.slice(0, idx).replace(/\r$/u, '');
+        this.buf = this.buf.slice(idx + 1);
+        if (line.length > 0) {
+          this.received.push(line);
+          this.emit('line', line);
+        }
+        idx = this.buf.indexOf('\n');
+      }
+    });
+  }
+
+  opened(): Promise<void> {
+    return new Promise((res, rej) => {
+      if (this.socket.destroyed) return res();
+      this.socket.once('connect', () => res());
+      this.socket.once('error', rej);
+    });
+  }
+
+  send(line: string): void {
+    this.socket.write(`${line}\r\n`);
+  }
+
+  sendRaw(raw: string): void {
+    this.socket.write(raw);
+  }
+
+  waitFor(predicate: (line: string) => boolean, timeoutMs = 2000): Promise<string> {
+    return new Promise((resolve, reject) => {
+      for (const line of this.received) {
+        if (predicate(line)) return resolve(line);
+      }
+      const timer = setTimeout(() => {
+        this.off('line', check);
+        reject(new Error(`timeout; received: ${JSON.stringify(this.received)}`));
+      }, timeoutMs);
+      const check = (line: string) => {
+        if (predicate(line)) {
+          clearTimeout(timer);
+          this.off('line', check);
+          resolve(line);
+        }
+      };
+      this.on('line', check);
+    });
+  }
+
+  /** Resolves when the underlying socket fully closes. */
+  closed(): Promise<void> {
+    return new Promise((res) => {
+      if (this.socket.destroyed) return res();
+      this.socket.once('close', () => res());
+    });
+  }
+
+  close(): Promise<void> {
+    return new Promise((res) => {
+      this.socket.once('close', () => res());
+      this.socket.end();
+    });
+  }
+}
+
+interface PendingCloser {
+  close(): Promise<void>;
+}
+const openServers: PendingCloser[] = [];
+const openClients: TcpClient[] = [];
+
+async function shutdownAll(): Promise<void> {
+  for (const c of openClients.splice(0)) c.socket.destroy();
+  for (const s of openServers.splice(0)) await s.close();
+}
+
+afterEach(async () => {
+  await shutdownAll();
+});
+
+describe('startForwarder — lifecycle', () => {
+  it('binds the requested listen port and exposes targetUrl/hostname', async () => {
+    const target = await startTarget();
+    openServers.push(target);
+    const fwd = await startForwarder({
+      listenPort: 0,
+      listenHost: '127.0.0.1',
+      targetUrl: `ws://127.0.0.1:${target.port}/irctest`,
+    });
+    openServers.push(fwd);
+    expect(fwd.listenPort).toBeGreaterThan(0);
+    expect(fwd.listenHost).toBe('127.0.0.1');
+    expect(fwd.targetUrl).toBe(`ws://127.0.0.1:${target.port}/irctest`);
+  });
+
+  it('defaults listenHost to 127.0.0.1 when omitted', async () => {
+    const target = await startTarget();
+    openServers.push(target);
+    const fwd = await startForwarder({ listenPort: 0, targetUrl: `ws://127.0.0.1:${target.port}` });
+    openServers.push(fwd);
+    expect(fwd.listenHost).toBe('127.0.0.1');
+  });
+
+  it('accepts a TCP connection as soon as it is listening', async () => {
+    const target = await startTarget();
+    openServers.push(target);
+    const fwd = await startForwarder({ listenPort: 0, targetUrl: `ws://127.0.0.1:${target.port}` });
+    openServers.push(fwd);
+    const client = new TcpClient(fwd.listenPort);
+    openClients.push(client);
+    await expect(client.opened()).resolves.toBeUndefined();
+  });
+
+  it('rejects when the listen port is already in use', async () => {
+    const target = await startTarget();
+    openServers.push(target);
+    const first = await startForwarder({
+      listenPort: 0,
+      targetUrl: `ws://127.0.0.1:${target.port}`,
+    });
+    openServers.push(first);
+    await expect(
+      startForwarder({ listenPort: first.listenPort, targetUrl: `ws://127.0.0.1:${target.port}` }),
+    ).rejects.toThrow();
+  });
+
+  it('throws synchronously for a non-ws/wss target scheme', () => {
+    expect(() => startForwarder({ listenPort: 0, targetUrl: 'http://127.0.0.1:6667/' })).toThrow(
+      /ws:\/\/|wss:\/\//u,
+    );
+  });
+
+  it('throws synchronously for an unparseable target URL', () => {
+    expect(() => startForwarder({ listenPort: 0, targetUrl: 'not a url' })).toThrow();
+  });
+
+  it('accepts a wss:// target URL (validates scheme, does not connect on bind)', async () => {
+    const fwd = await startForwarder({ listenPort: 0, targetUrl: 'wss://example.invalid/' });
+    openServers.push(fwd);
+    expect(fwd.targetUrl).toBe('wss://example.invalid/');
+  });
+});
+
+describe('forwarder — TCP→WS framing', () => {
+  it('forwards a single CRLF-terminated line as one WS frame (bare)', async () => {
+    const target = await startTarget();
+    openServers.push(target);
+    const fwd = await startForwarder({ listenPort: 0, targetUrl: `ws://127.0.0.1:${target.port}` });
+    openServers.push(fwd);
+
+    const client = new TcpClient(fwd.listenPort);
+    openClients.push(client);
+    await client.opened();
+    client.send('PING :tok');
+
+    const ws = await target.waitForConnection();
+    await new Promise<void>((res) => ws.once('message', () => res()));
+    expect(target.frames).toEqual(['PING :tok']);
+  });
+
+  it('forwards each of several lines in one TCP chunk as its own WS frame', async () => {
+    const target = await startTarget();
+    openServers.push(target);
+    const fwd = await startForwarder({ listenPort: 0, targetUrl: `ws://127.0.0.1:${target.port}` });
+    openServers.push(fwd);
+
+    const client = new TcpClient(fwd.listenPort);
+    openClients.push(client);
+    await client.opened();
+    client.sendRaw('NICK alice\r\nUSER alice 0 * :Alice\r\n');
+
+    const ws = await target.waitForConnection();
+    // Wait for the second frame.
+    await new Promise<void>((res) => {
+      const onMsg = (): void => {
+        if (target.frames.length >= 2) {
+          ws.off('message', onMsg);
+          res();
+        }
+      };
+      ws.on('message', onMsg);
+    });
+    expect(target.frames).toEqual(['NICK alice', 'USER alice 0 * :Alice']);
+  });
+
+  it('reassembles a line split across two TCP chunks into one WS frame', async () => {
+    const target = await startTarget();
+    openServers.push(target);
+    const fwd = await startForwarder({ listenPort: 0, targetUrl: `ws://127.0.0.1:${target.port}` });
+    openServers.push(fwd);
+
+    const client = new TcpClient(fwd.listenPort);
+    openClients.push(client);
+    await client.opened();
+    client.sendRaw('PI');
+    // Let the first chunk be consumed before the second half is written.
+    await new Promise((r) => setImmediate(r));
+    client.sendRaw('NG :tok\r\n');
+
+    const ws = await target.waitForConnection();
+    await new Promise<void>((res) => ws.once('message', () => res()));
+    expect(target.frames).toEqual(['PING :tok']);
+  });
+
+  it('tolerates a bare-LF line ending from the TCP client', async () => {
+    const target = await startTarget();
+    openServers.push(target);
+    const fwd = await startForwarder({ listenPort: 0, targetUrl: `ws://127.0.0.1:${target.port}` });
+    openServers.push(fwd);
+
+    const client = new TcpClient(fwd.listenPort);
+    openClients.push(client);
+    await client.opened();
+    client.sendRaw('PING :bare\n');
+
+    await target.waitForConnection();
+    await new Promise<void>((res) => setTimeout(res, 25));
+    expect(target.frames).toEqual(['PING :bare']);
+  });
+
+  it('buffers TCP data that arrives before the WS handshake completes', async () => {
+    // A slow-upgrading target guarantees the forwarder sees TCP bytes
+    // while the WS is still CONNECTING, deterministically exercising the
+    // early-data buffer + flush-on-open path.
+    const target = await startDelayedTarget(60);
+    openServers.push(target);
+    const fwd = await startForwarder({ listenPort: 0, targetUrl: `ws://127.0.0.1:${target.port}` });
+    openServers.push(fwd);
+
+    const client = new TcpClient(fwd.listenPort);
+    openClients.push(client);
+    await client.opened();
+    client.send('PING :early'); // written before WS upgrade (60ms) completes
+
+    const ws = await target.waitForConnection();
+    await new Promise<void>((res) => ws.once('message', () => res()));
+    expect(target.frames).toEqual(['PING :early']);
+  });
+});
+
+describe('forwarder — WS→TCP framing', () => {
+  it('writes a server WS frame to the TCP client with CRLF termination', async () => {
+    const target = await startTarget();
+    openServers.push(target);
+    const fwd = await startForwarder({ listenPort: 0, targetUrl: `ws://127.0.0.1:${target.port}` });
+    openServers.push(fwd);
+
+    const client = new TcpClient(fwd.listenPort);
+    openClients.push(client);
+    await client.opened();
+
+    const ws = await target.waitForConnection();
+    ws.send(':srv 001 alice :Welcome');
+    expect(await client.waitFor((l) => l.startsWith(':srv 001'))).toBe(':srv 001 alice :Welcome');
+  });
+
+  it('normalizes a multi-message WS frame into separate CRLF lines for the TCP client', async () => {
+    const target = await startTarget();
+    openServers.push(target);
+    const fwd = await startForwarder({ listenPort: 0, targetUrl: `ws://127.0.0.1:${target.port}` });
+    openServers.push(fwd);
+
+    const client = new TcpClient(fwd.listenPort);
+    openClients.push(client);
+    await client.opened();
+
+    const ws = await target.waitForConnection();
+    // Server joins two messages in one frame (PLAN §9 tolerance).
+    ws.send(':srv 001 alice :Hi\r\n:srv 376 alice :End');
+    await client.waitFor((l) => l.startsWith(':srv 376'));
+    expect(client.received).toEqual([':srv 001 alice :Hi', ':srv 376 alice :End']);
+  });
+
+  it('adds CRLF to a bare server frame that has no terminator', async () => {
+    const target = await startTarget();
+    openServers.push(target);
+    const fwd = await startForwarder({ listenPort: 0, targetUrl: `ws://127.0.0.1:${target.port}` });
+    openServers.push(fwd);
+
+    const client = new TcpClient(fwd.listenPort);
+    openClients.push(client);
+    await client.opened();
+
+    const ws = await target.waitForConnection();
+    ws.send('PONG :bare'); // no trailing CRLF
+    expect(await client.waitFor((l) => l === 'PONG :bare')).toBe('PONG :bare');
+  });
+});
+
+describe('forwarder — close propagation', () => {
+  it('closes the upstream WS when the TCP client disconnects', async () => {
+    const target = await startTarget();
+    openServers.push(target);
+    const fwd = await startForwarder({ listenPort: 0, targetUrl: `ws://127.0.0.1:${target.port}` });
+    openServers.push(fwd);
+
+    const client = new TcpClient(fwd.listenPort);
+    openClients.push(client);
+    await client.opened();
+    const ws = await target.waitForConnection();
+
+    const wsClosed = new Promise<void>((res) => ws.once('close', () => res()));
+    await client.close();
+    await expect(wsClosed).resolves.toBeUndefined();
+  });
+
+  it('closes the TCP client when the upstream WS closes', async () => {
+    const target = await startTarget();
+    openServers.push(target);
+    const fwd = await startForwarder({ listenPort: 0, targetUrl: `ws://127.0.0.1:${target.port}` });
+    openServers.push(fwd);
+
+    const client = new TcpClient(fwd.listenPort);
+    openClients.push(client);
+    await client.opened();
+    const ws = await target.waitForConnection();
+
+    ws.close();
+    await expect(client.closed()).resolves.toBeUndefined();
+  });
+
+  it('keeps serving other connections after one TCP client drops', async () => {
+    const target = await startTarget();
+    openServers.push(target);
+    const fwd = await startForwarder({ listenPort: 0, targetUrl: `ws://127.0.0.1:${target.port}` });
+    openServers.push(fwd);
+
+    const a = new TcpClient(fwd.listenPort);
+    openClients.push(a);
+    await a.opened();
+    await target.waitForConnection();
+    await a.close();
+
+    const b = new TcpClient(fwd.listenPort);
+    openClients.push(b);
+    await b.opened();
+    const ws = await target.waitForConnection();
+    ws.send(':srv PONG :still-up');
+    expect(await b.waitFor((l) => l.includes('still-up'))).toBeDefined();
+  });
+});
+
+describe('forwarder — concurrency & teardown', () => {
+  it('gives each TCP connection its own upstream WS', async () => {
+    const target = await startTarget();
+    openServers.push(target);
+    const fwd = await startForwarder({ listenPort: 0, targetUrl: `ws://127.0.0.1:${target.port}` });
+    openServers.push(fwd);
+
+    const a = new TcpClient(fwd.listenPort);
+    const b = new TcpClient(fwd.listenPort);
+    openClients.push(a, b);
+    await a.opened();
+    await b.opened();
+
+    await target.waitForConnection();
+    await target.waitForConnection();
+    expect(target.connections.length).toBe(2);
+  });
+
+  it('close() tears down the listener and any live bridges', async () => {
+    const target = await startTarget();
+    openServers.push(target);
+    const fwd = await startForwarder({ listenPort: 0, targetUrl: `ws://127.0.0.1:${target.port}` });
+
+    const client = new TcpClient(fwd.listenPort);
+    openClients.push(client);
+    await client.opened();
+    await target.waitForConnection();
+
+    await fwd.close();
+    // The TCP client socket should have been torn down by the forwarder
+    // (its end is destroyed; the client-side close event arrives async).
+    await expect(client.closed()).resolves.toBeUndefined();
+    // A new client can no longer connect.
+    const next = new TcpClient(fwd.listenPort);
+    openClients.push(next);
+    await expect(next.opened()).rejects.toThrow();
+    await target.close();
+  });
+
+  it('close() is idempotent', async () => {
+    const target = await startTarget();
+    openServers.push(target);
+    const fwd = await startForwarder({ listenPort: 0, targetUrl: `ws://127.0.0.1:${target.port}` });
+    await fwd.close();
+    await expect(fwd.close()).resolves.toBeUndefined();
+    await target.close();
+  });
+});
+
+describe('forwarder — IRC-shaped round trip', () => {
+  it('relays a bidirectional PING/PONG exchange through the bridge', async () => {
+    // Target acts as a naive IRC server: echoes any PING line back as PONG.
+    const target = await startTarget();
+    openServers.push(target);
+    const fwd = await startForwarder({ listenPort: 0, targetUrl: `ws://127.0.0.1:${target.port}` });
+    openServers.push(fwd);
+
+    const client = new TcpClient(fwd.listenPort);
+    openClients.push(client);
+    await client.opened();
+
+    const ws = await target.waitForConnection();
+    ws.on('message', (data) => {
+      const line = toUtf8(data as RawData);
+      if (line.startsWith('PING ')) {
+        ws.send(line.replace(/^PING/u, 'PONG'));
+      }
+    });
+
+    client.send('PING :roundtrip');
+    expect(await client.waitFor((l) => l === 'PONG :roundtrip')).toBe('PONG :roundtrip');
+  });
+
+  it('ignores an empty WS frame and keeps bridging subsequent frames', async () => {
+    const target = await startTarget();
+    openServers.push(target);
+    const fwd = await startForwarder({ listenPort: 0, targetUrl: `ws://127.0.0.1:${target.port}` });
+    openServers.push(fwd);
+
+    const client = new TcpClient(fwd.listenPort);
+    openClients.push(client);
+    await client.opened();
+    const ws = await target.waitForConnection();
+
+    ws.send(''); // empty frame: must not error or emit a line
+    ws.send(':srv 001 nick :alive');
+    expect(await client.waitFor((l) => l.includes('alive'))).toBeDefined();
+  });
+});
+
+describe('forwarder — error handling', () => {
+  it('logs a server-side tcp socket Error and tears the bridge down', async () => {
+    const target = await startTarget();
+    openServers.push(target);
+    const fwd = await startForwarder({ listenPort: 0, targetUrl: `ws://127.0.0.1:${target.port}` });
+    openServers.push(fwd);
+
+    const client = new TcpClient(fwd.listenPort);
+    openClients.push(client);
+    await client.opened();
+    await target.waitForConnection();
+
+    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    const serverSide = [...fwd.testSockets][0];
+    if (serverSide === undefined) throw new Error('no server-side socket');
+    serverSide.emit('error', new Error('synthetic tcp failure'));
+    await new Promise((r) => setImmediate(r));
+
+    expect(errSpy).toHaveBeenCalled();
+    const logged = JSON.parse(String(errSpy.mock.calls[0]?.[0]));
+    expect(logged.msg).toBe('forwarder tcp socket error');
+    expect(logged.err.message).toBe('synthetic tcp failure');
+    expect(logged.err.name).toBe('Error');
+    errSpy.mockRestore();
+  });
+
+  it('stringifies a non-Error value surfaced to the tcp error handler', async () => {
+    const target = await startTarget();
+    openServers.push(target);
+    const fwd = await startForwarder({ listenPort: 0, targetUrl: `ws://127.0.0.1:${target.port}` });
+    openServers.push(fwd);
+
+    const client = new TcpClient(fwd.listenPort);
+    openClients.push(client);
+    await client.opened();
+    await target.waitForConnection();
+
+    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    const serverSide = [...fwd.testSockets][0];
+    if (serverSide === undefined) throw new Error('no server-side socket');
+    serverSide.emit('error', 'a bare string failure');
+    await new Promise((r) => setImmediate(r));
+
+    const logged = JSON.parse(String(errSpy.mock.calls[0]?.[0]));
+    expect(logged.err).toBe('a bare string failure');
+    errSpy.mockRestore();
+  });
+
+  it('logs an upstream ws error and closes the tcp client when the target is unreachable', async () => {
+    const closedPort = await getClosedPort();
+    const fwd = await startForwarder({ listenPort: 0, targetUrl: `ws://127.0.0.1:${closedPort}` });
+    openServers.push(fwd);
+
+    const client = new TcpClient(fwd.listenPort);
+    openClients.push(client);
+    await client.opened();
+
+    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    // The upstream ws connect fails (ECONNREFUSED) → 'error' → teardown →
+    // the tcp client is destroyed.
+    await expect(client.closed()).resolves.toBeUndefined();
+    expect(errSpy).toHaveBeenCalled();
+    expect(String(errSpy.mock.calls[0]?.[0])).toContain('forwarder upstream ws error');
+    errSpy.mockRestore();
+  });
+});

package/tools/tcp-ws-forwarder/tests/framing.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest';
+import type { RawData } from 'ws';
+import { splitFrameLines, toBuffer } from '../src/forwarder';
+
+/**
+ * Pure-function unit tests for the WS-side framing helpers. These edges
+ * (empty frames, and the ArrayBuffer/Uint8Array/Buffer[] RawData variants
+ * that ws only emits under non-default settings) are awkward to reach
+ * through real sockets, so they are pinned here in isolation.
+ */
+describe('splitFrameLines', () => {
+  it('returns no lines for an empty frame', () => {
+    expect(splitFrameLines('')).toEqual([]);
+  });
+
+  it('returns a bare unterminated line as a single element', () => {
+    expect(splitFrameLines('PING :tok')).toEqual(['PING :tok']);
+  });
+
+  it('splits a CRLF-joined multi-message frame', () => {
+    expect(splitFrameLines(':srv 001\r\n:srv 376')).toEqual([':srv 001', ':srv 376']);
+  });
+
+  it('keeps the trailing empty string for a terminated frame (consumer filters it)', () => {
+    // Documents the raw split behavior; the forwarder drops empty lines.
+    expect(splitFrameLines('A\r\nB\r\n')).toEqual(['A', 'B', '']);
+  });
+});
+
+describe('toBuffer', () => {
+  it('returns a Buffer payload unchanged', () => {
+    const src = Buffer.from('hello', 'utf8');
+    expect(toBuffer(src)).toBe(src);
+  });
+
+  it('concatenates a Buffer[] payload', () => {
+    const out = toBuffer([Buffer.from('foo', 'utf8'), Buffer.from('bar', 'utf8')] as RawData);
+    expect(out.toString('utf8')).toBe('foobar');
+  });
+
+  it('wraps an ArrayBuffer payload', () => {
+    const src = new ArrayBuffer(3);
+    new Uint8Array(src).set([0x41, 0x42, 0x43]); // 'ABC'
+    expect(toBuffer(src as RawData).toString('utf8')).toBe('ABC');
+  });
+
+  it('copies a Uint8Array payload', () => {
+    const src = new Uint8Array([0x41, 0x42, 0x43]);
+    expect(toBuffer(src as RawData).toString('utf8')).toBe('ABC');
+  });
+});