serverless-ircd 0.1.0 → 0.3.0

package/tools/tcp-ws-forwarder/src/main.ts

@@ -14,6 +14,8 @@
  *   --target <url>        Upstream ws:// or wss:// URL (required).
  *   --listen-port <n>     TCP port to listen on (default 6667).
  *   --listen-host <addr>  Interface to bind (default 127.0.0.1).
+ *   --log-level <level>   debug | info | warn | error (default info,
+ *                         or $LOG_LEVEL if set).
  *   -h, --help            Show this help and exit.
  *
  * Point your IRC client at 127.0.0.1:<listen-port> and it will appear as
@@ -21,15 +23,22 @@
  */
 
 import { startForwarder } from './forwarder.js';
+import { ConsoleLogger, LogLevel, type Logger, logLevelLabel, parseLogLevel } from './logger.js';
 
 interface CliArgs {
   target: string | undefined;
   listenPort: number;
   listenHost: string;
+  logLevel: LogLevel | undefined;
 }
 
 function parseArgs(argv: string[]): CliArgs {
-  const out: CliArgs = { target: undefined, listenPort: 6667, listenHost: '127.0.0.1' };
+  const out: CliArgs = {
+    target: undefined,
+    listenPort: 6667,
+    listenHost: '127.0.0.1',
+    logLevel: undefined,
+  };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === undefined) continue;
@@ -43,6 +52,9 @@ function parseArgs(argv: string[]): CliArgs {
     } else if (a === '--listen-host' && next !== undefined) {
       out.listenHost = next;
       i++;
+    } else if (a === '--log-level' && next !== undefined) {
+      out.logLevel = parseLogLevel(next);
+      i++;
     } else if (a === '--help' || a === '-h') {
       process.stdout.write(
         [
@@ -52,6 +64,7 @@ function parseArgs(argv: string[]): CliArgs {
           '  --target <url>        Upstream ws:// or wss:// URL (required).',
           '  --listen-port <n>     TCP port to listen on (default 6667).',
           '  --listen-host <addr>  Interface to bind (default 127.0.0.1).',
+          '  --log-level <level>   debug | info | warn | error (default info, or $LOG_LEVEL).',
           '  -h, --help            Show this help and exit.',
           '',
         ].join('\n'),
@@ -68,6 +81,14 @@ function parseArgs(argv: string[]): CliArgs {
   return out;
 }
 
+/** Resolves the effective log level: CLI flag, else $LOG_LEVEL, else info. */
+function resolveLogLevel(cli: LogLevel | undefined): LogLevel {
+  if (cli !== undefined) return cli;
+  const env = process.env.LOG_LEVEL;
+  if (env !== undefined && env.trim() !== '') return parseLogLevel(env);
+  return LogLevel.Info;
+}
+
 async function main(): Promise<void> {
   const args = parseArgs(process.argv.slice(2));
   if (args.target === undefined) {
@@ -75,30 +96,28 @@ async function main(): Promise<void> {
     process.exit(2);
   }
 
+  const logLevel = resolveLogLevel(args.logLevel);
+  const logger: Logger = new ConsoleLogger(undefined, logLevel);
+
   const forwarder = await startForwarder({
     listenPort: args.listenPort,
     listenHost: args.listenHost,
     targetUrl: args.target,
+    logLevel,
+  });
+  logger.info('tcp-ws-forwarder listening', {
+    listen: `${forwarder.listenHost}:${forwarder.listenPort}`,
+    target: forwarder.targetUrl,
+    level: logLevelLabel(logLevel),
   });
-  process.stdout.write(
-    `${JSON.stringify({
-      ts: new Date().toISOString(),
-      level: 'info',
-      msg: 'tcp-ws-forwarder listening',
-      listen: `${forwarder.listenHost}:${forwarder.listenPort}`,
-      target: forwarder.targetUrl,
-    })}\n`,
-  );
 
   const shutdown = (signal: string): void => {
-    process.stdout.write(
-      `${JSON.stringify({ ts: new Date().toISOString(), level: 'info', msg: 'shutdown', signal })}\n`,
-    );
+    logger.info('shutdown', { signal });
     forwarder
       .close()
       .then(() => process.exit(0))
       .catch((err) => {
-        process.stderr.write(`shutdown error: ${String(err)}\n`);
+        logger.error('shutdown error', { err });
         process.exit(1);
       });
   };

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

@@ -6,6 +6,7 @@ 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';
+import { LogLevel } from '../src/logger';
 
 /**
  * Integration tests for the TCP↔WS forwarder against real sockets.
@@ -616,3 +617,88 @@ describe('forwarder — error handling', () => {
     errSpy.mockRestore();
   });
 });
+
+describe('forwarder — logging', () => {
+  /** Collects the `msg` field from every JSON line a console sink received. */
+  function msgsFrom(spy: { mock: { calls: unknown[][] } }): string[] {
+    return spy.mock.calls.map((c) => JSON.parse(String(c[0])).msg as string);
+  }
+
+  it('at logLevel debug, logs bridge.accepted (info) + tcp.line/ws.open/ws.frame (debug)', async () => {
+    const target = await startTarget();
+    openServers.push(target);
+    const infoSpy = vi.spyOn(console, 'info').mockImplementation(() => undefined);
+    const debugSpy = vi.spyOn(console, 'debug').mockImplementation(() => undefined);
+
+    const fwd = await startForwarder({
+      listenPort: 0,
+      targetUrl: `ws://127.0.0.1:${target.port}`,
+      logLevel: LogLevel.Debug,
+    });
+    openServers.push(fwd);
+
+    const client = new TcpClient(fwd.listenPort);
+    openClients.push(client);
+    await client.opened();
+    client.send('PING :tok');
+
+    const ws = await target.waitForConnection();
+    ws.send(':srv PONG :tok');
+    await new Promise<void>((res) => ws.once('message', () => res())); // wait TCP→WS
+    await client.waitFor((l) => l.includes('PONG')); // wait WS→TCP
+
+    const debug = msgsFrom(debugSpy);
+    const info = msgsFrom(infoSpy);
+    expect(info).toContain('bridge.accepted');
+    expect(debug).toContain('tcp.line');
+    expect(debug).toContain('ws.open');
+    expect(debug).toContain('ws.frame');
+    infoSpy.mockRestore();
+    debugSpy.mockRestore();
+  });
+
+  it('at the default level (info), suppresses debug trace logs but keeps lifecycle', async () => {
+    const target = await startTarget();
+    openServers.push(target);
+    const infoSpy = vi.spyOn(console, 'info').mockImplementation(() => undefined);
+    const debugSpy = vi.spyOn(console, 'debug').mockImplementation(() => undefined);
+
+    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(debugSpy).not.toHaveBeenCalled();
+    expect(msgsFrom(infoSpy)).toContain('bridge.accepted');
+    infoSpy.mockRestore();
+    debugSpy.mockRestore();
+  });
+
+  it('logs bridge.closed with the tcp-close reason when the client disconnects', async () => {
+    const target = await startTarget();
+    openServers.push(target);
+    const infoSpy = vi.spyOn(console, 'info').mockImplementation(() => undefined);
+    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();
+    await client.close();
+    await new Promise((r) => setImmediate(r)); // let the close event propagate
+
+    const closed = msgsFrom(infoSpy).filter((m) => m === 'bridge.closed');
+    expect(closed).toHaveLength(1);
+    const rec = JSON.parse(
+      String(infoSpy.mock.calls.find((c) => JSON.parse(String(c[0])).msg === 'bridge.closed')?.[0]),
+    );
+    expect(rec.reason).toBe('tcp-close');
+    infoSpy.mockRestore();
+  });
+});

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

@@ -0,0 +1,136 @@
+import { describe, expect, it } from 'vitest';
+import { ConsoleLogger, LogLevel, parseLogLevel } from '../src/logger';
+
+/**
+ * Unit tests for the forwarder's self-contained structured logger.
+ *
+ * The forwarder intentionally has no `@serverless-ircd/*` dependency, so it
+ * ships its own tiny logger that mirrors the irc-core conventions: a numeric
+ * `LogLevel` enum, one JSON line per record, injectable sinks (so tests never
+ * touch the real `console`), and `minLevel` filtering.
+ */
+
+/** Sink that captures every emitted line per level into mutable arrays. */
+function capturingSinks() {
+  const lines = {
+    debug: [] as string[],
+    info: [] as string[],
+    warn: [] as string[],
+    error: [] as string[],
+  };
+  return {
+    lines,
+    sinks: {
+      debug: (l: string) => lines.debug.push(l),
+      info: (l: string) => lines.info.push(l),
+      warn: (l: string) => lines.warn.push(l),
+      error: (l: string) => lines.error.push(l),
+    },
+  };
+}
+
+describe('parseLogLevel', () => {
+  it('maps each canonical lower-case label to its level', () => {
+    expect(parseLogLevel('debug')).toBe(LogLevel.Debug);
+    expect(parseLogLevel('info')).toBe(LogLevel.Info);
+    expect(parseLogLevel('warn')).toBe(LogLevel.Warn);
+    expect(parseLogLevel('error')).toBe(LogLevel.Error);
+  });
+
+  it('is case-insensitive', () => {
+    expect(parseLogLevel('DEBUG')).toBe(LogLevel.Debug);
+    expect(parseLogLevel('Warn')).toBe(LogLevel.Warn);
+  });
+
+  it('trims surrounding whitespace', () => {
+    expect(parseLogLevel('  info  ')).toBe(LogLevel.Info);
+  });
+
+  it('throws for an unknown label', () => {
+    expect(() => parseLogLevel('verbose')).toThrow();
+    expect(() => parseLogLevel('')).toThrow();
+  });
+});
+
+describe('ConsoleLogger — level filtering', () => {
+  it('emits records at or above the configured min level', () => {
+    const { lines, sinks } = capturingSinks();
+    const log = new ConsoleLogger(sinks, LogLevel.Info);
+    log.debug('skip me');
+    log.info('keep me');
+    log.warn('keep too');
+    log.error('keep three');
+    expect(lines.debug).toHaveLength(0);
+    expect(lines.info).toHaveLength(1);
+    expect(lines.warn).toHaveLength(1);
+    expect(lines.error).toHaveLength(1);
+  });
+
+  it('defaults to debug (lowest) so nothing is suppressed', () => {
+    const { lines, sinks } = capturingSinks();
+    const log = new ConsoleLogger(sinks);
+    log.debug('d');
+    log.info('i');
+    expect(lines.debug).toHaveLength(1);
+    expect(lines.info).toHaveLength(1);
+  });
+
+  it('suppresses everything at a level above error (error-only)', () => {
+    // error-only means minLevel = Error: warn and below are dropped.
+    const { lines, sinks } = capturingSinks();
+    const log = new ConsoleLogger(sinks, LogLevel.Error);
+    log.warn('dropped');
+    log.info('dropped');
+    log.error('kept');
+    expect(lines.warn).toHaveLength(0);
+    expect(lines.info).toHaveLength(0);
+    expect(lines.error).toHaveLength(1);
+  });
+});
+
+describe('ConsoleLogger — output shape', () => {
+  it('emits one JSON line with ts, level, msg, and merged fields', () => {
+    const { lines, sinks } = capturingSinks();
+    const log = new ConsoleLogger(sinks, LogLevel.Info);
+    log.info('listening', { listen: '127.0.0.1:6667', target: 'wss://x/' });
+    const rec = JSON.parse(lines.info[0] as string);
+    expect(rec.level).toBe('info');
+    expect(rec.msg).toBe('listening');
+    expect(rec.listen).toBe('127.0.0.1:6667');
+    expect(rec.target).toBe('wss://x/');
+    expect(typeof rec.ts).toBe('string');
+    expect(new Date(rec.ts).toString()).not.toBe('Invalid Date');
+  });
+
+  it('serializes an Error field into { name, message, stack }', () => {
+    const { lines, sinks } = capturingSinks();
+    const log = new ConsoleLogger(sinks, LogLevel.Error);
+    const err = new Error('boom');
+    log.error('forwarder tcp socket error', { err });
+    const rec = JSON.parse(lines.error[0] as string);
+    expect(rec.msg).toBe('forwarder tcp socket error');
+    expect(rec.err).toMatchObject({ name: 'Error', message: 'boom' });
+    expect(typeof rec.err.stack).toBe('string');
+  });
+
+  it('passes a non-Error field through unchanged', () => {
+    const { lines, sinks } = capturingSinks();
+    const log = new ConsoleLogger(sinks, LogLevel.Error);
+    log.error('upstream failure', { err: 'a bare string failure' });
+    const rec = JSON.parse(lines.error[0] as string);
+    expect(rec.err).toBe('a bare string failure');
+  });
+
+  it('routes each level to its matching sink', () => {
+    const { lines, sinks } = capturingSinks();
+    const log = new ConsoleLogger(sinks, LogLevel.Debug);
+    log.debug('d');
+    log.info('i');
+    log.warn('w');
+    log.error('e');
+    expect(JSON.parse(lines.debug[0] as string).msg).toBe('d');
+    expect(JSON.parse(lines.info[0] as string).msg).toBe('i');
+    expect(JSON.parse(lines.warn[0] as string).msg).toBe('w');
+    expect(JSON.parse(lines.error[0] as string).msg).toBe('e');
+  });
+});

package/packages/cf-adapter/tests/integration/index.ts

@@ -1,17 +0,0 @@
-/**
- * In-tree parametrized IRC scenario suite (folded in from the former
- * `@serverless-ircd/integration-tests` workspace package).
- *
- * Each runtime (in-memory now; CF via `../cf-harness.ts`; AWS in Phase 4)
- * ships one {@link IrcHarnessFactory}; the scenario tests run against
- * every registered factory.
- */
-
-export type {
-  ClientHarness,
-  IrcHarness,
-  IrcHarnessFactory,
-  SpawnClientOptions,
-} from './harness.js';
-export { inMemoryHarnessFactory, HARNESS_SERVER_CONFIG } from './in-memory-harness.js';
-export { runIrcScenarios } from './scenarios.js';