@polderlabs/bizar 4.5.2 → 4.7.1

package/bizar-dash/tests/logger.test.mjs

@@ -0,0 +1,207 @@
+/**
+ * tests/logger.test.mjs
+ *
+ * Tests for src/server/logger.mjs — verifies level filtering, JSON
+ * output shape, context merge behaviour, and the child() factory.
+ *
+ * The module reads BIZAR_LOG_LEVEL at import time, so each test that
+ * needs a different level uses Node's --import flag… except that's
+ * hard to do mid-test. Instead we set the env BEFORE the first
+ * dynamic import by using a top-level await and reset modules via
+ * `node:test`'s `mock`.
+ *
+ * Simpler: we always force level='debug' at the top of each test
+ * with a child module that re-exports the logger functions but
+ * respects a per-test override. That mirrors what real callers do
+ * anyway — they call the functions, not the level constant.
+ *
+ * Strategy: capture stdout/stderr by replacing console.{log,warn,error}
+ * in-place for the duration of the test, then assert on the captured
+ * lines. Restore the originals in finally.
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { Writable } from 'node:stream';
+
+function captureConsole() {
+  const original = {
+    log: console.log,
+    warn: console.warn,
+    error: console.error,
+  };
+  const lines = [];
+  const sink = new Writable({
+    write(chunk, _enc, cb) {
+      lines.push(String(chunk).replace(/\n$/, ''));
+      cb();
+    },
+  });
+  // Replace console.* with writes to our sink. The logger calls
+  // console.log/warn/error, so we route each stream independently to
+  // its own bucket so we can verify the level → stream mapping.
+  const buckets = { log: [], warn: [], error: [] };
+  console.log = (...args) => {
+    buckets.log.push(args.map(String).join(' '));
+    sink.write(args.map(String).join(' ') + '\n');
+  };
+  console.warn = (...args) => {
+    buckets.warn.push(args.map(String).join(' '));
+    sink.write(args.map(String).join(' ') + '\n');
+  };
+  console.error = (...args) => {
+    buckets.error.push(args.map(String).join(' '));
+    sink.write(args.map(String).join(' ') + '\n');
+  };
+  return {
+    buckets,
+    lines,
+    restore() {
+      console.log = original.log;
+      console.warn = original.warn;
+      console.error = original.error;
+    },
+  };
+}
+
+/**
+ * Force BIZAR_LOG_LEVEL to the given value BEFORE importing the
+ * logger module. We delete the cached module from require.cache so
+ * the level constant re-evaluates, then dynamic-import it fresh.
+ */
+async function loadLogger(level) {
+  // For ESM the import cache lives on the loader, not require.cache.
+  // Use a unique query string per level to force a fresh module
+  // evaluation (Node treats different specifiers as different modules).
+  const url = `../src/server/logger.mjs?level=${level}`;
+  process.env.BIZAR_LOG_LEVEL = level;
+  return import(url);
+}
+
+test('logger emits JSON with ts/level/msg shape', async () => {
+  process.env.BIZAR_LOG_LEVEL = 'debug';
+  const cap = captureConsole();
+  try {
+    const { info } = await loadLogger('debug');
+    info('server started', { port: 4317 });
+    assert.equal(cap.buckets.log.length, 1);
+    const parsed = JSON.parse(cap.buckets.log[0]);
+    assert.equal(parsed.msg, 'server started');
+    assert.equal(parsed.level, 'info');
+    assert.equal(parsed.port, 4317);
+    assert.ok(typeof parsed.ts === 'string');
+    // ts must look like an ISO timestamp.
+    assert.match(parsed.ts, /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/);
+  } finally {
+    cap.restore();
+  }
+});
+
+test('level filtering — debug suppressed at default level', async () => {
+  process.env.BIZAR_LOG_LEVEL = 'info';
+  const cap = captureConsole();
+  try {
+    const { debug, info } = await loadLogger('info');
+    debug('should not appear');
+    info('should appear');
+    assert.equal(cap.buckets.log.length, 1);
+    const parsed = JSON.parse(cap.buckets.log[0]);
+    assert.equal(parsed.msg, 'should appear');
+    assert.equal(parsed.level, 'info');
+  } finally {
+    cap.restore();
+  }
+});
+
+test('level filtering — warn goes to console.warn, error to console.error', async () => {
+  process.env.BIZAR_LOG_LEVEL = 'debug';
+  const cap = captureConsole();
+  try {
+    const { warn, error } = await loadLogger('debug');
+    warn('a warning', { module: 'test' });
+    error('a failure', { module: 'test', code: 'E_BANG' });
+    assert.equal(cap.buckets.warn.length, 1);
+    assert.equal(cap.buckets.error.length, 1);
+    assert.equal(cap.buckets.log.length, 0);
+    const w = JSON.parse(cap.buckets.warn[0]);
+    assert.equal(w.level, 'warn');
+    assert.equal(w.module, 'test');
+    const e = JSON.parse(cap.buckets.error[0]);
+    assert.equal(e.level, 'error');
+    assert.equal(e.code, 'E_BANG');
+  } finally {
+    cap.restore();
+  }
+});
+
+test('level filtering — error suppressed above error level (none higher exists)', async () => {
+  // There's no level above error, so this is a sanity test: errors
+  // always print. Make sure we didn't accidentally silence them.
+  process.env.BIZAR_LOG_LEVEL = 'error';
+  const cap = captureConsole();
+  try {
+    const { info, warn, error } = await loadLogger('error');
+    info('hidden');
+    warn('hidden');
+    error('visible');
+    assert.equal(cap.buckets.error.length, 1);
+    assert.equal(cap.buckets.log.length, 0);
+    assert.equal(cap.buckets.warn.length, 0);
+    assert.equal(JSON.parse(cap.buckets.error[0]).msg, 'visible');
+  } finally {
+    cap.restore();
+  }
+});
+
+test('child logger binds context to every call', async () => {
+  process.env.BIZAR_LOG_LEVEL = 'debug';
+  const cap = captureConsole();
+  try {
+    const { child } = await loadLogger('debug');
+    const log = child({ module: 'overview', session: 'abc' });
+    log.info('snapshot built', { size: 42 });
+    log.warn('cache miss');
+    // Both calls should carry the bound module + session.
+    const i = JSON.parse(cap.buckets.log[0]);
+    assert.equal(i.msg, 'snapshot built');
+    assert.equal(i.module, 'overview');
+    assert.equal(i.session, 'abc');
+    assert.equal(i.size, 42);
+    const w = JSON.parse(cap.buckets.warn[0]);
+    assert.equal(w.msg, 'cache miss');
+    assert.equal(w.module, 'overview');
+    assert.equal(w.session, 'abc');
+  } finally {
+    cap.restore();
+  }
+});
+
+test('child per-call context overrides bound context', async () => {
+  process.env.BIZAR_LOG_LEVEL = 'debug';
+  const cap = captureConsole();
+  try {
+    const { child } = await loadLogger('debug');
+    const log = child({ module: 'overview', session: 'abc' });
+    log.info('snapshot', { session: 'override' });
+    const parsed = JSON.parse(cap.buckets.log[0]);
+    // Per-call context wins over the bound context for shared keys.
+    assert.equal(parsed.session, 'override');
+    assert.equal(parsed.module, 'overview');
+  } finally {
+    cap.restore();
+  }
+});
+
+test('undefined ctx is ignored without throwing', async () => {
+  process.env.BIZAR_LOG_LEVEL = 'debug';
+  const cap = captureConsole();
+  try {
+    const { info } = await loadLogger('debug');
+    assert.doesNotThrow(() => info('hello'));
+    assert.doesNotThrow(() => info('hello', null));
+    assert.doesNotThrow(() => info('hello', undefined));
+    const parsed = JSON.parse(cap.buckets.log[0]);
+    assert.equal(parsed.msg, 'hello');
+  } finally {
+    cap.restore();
+  }
+});

package/bizar-dash/tests/metrics.test.mjs

@@ -0,0 +1,183 @@
+/**
+ * tests/metrics.test.mjs
+ *
+ * Tests for src/server/metrics.mjs — verifies counter/gauge/histogram
+ * accumulators, label handling, and Prometheus text exposition output.
+ *
+ * Each test resets the registry in finally so order doesn't matter
+ * and tests are independent.
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+const METRICS_URL = '../src/server/metrics.mjs';
+
+async function loadMetrics() {
+  // Bump the URL per-test-call to force fresh module load (the
+  // registry state lives at module scope, so a fresh import = a fresh
+  // empty registry). Tests reset() in finally too as belt-and-braces.
+  const url = `${METRICS_URL}?v=${Date.now()}-${Math.random()}`;
+  return import(url);
+}
+
+test('counter increments without labels', async () => {
+  const m = await loadMetrics();
+  try {
+    const c = m.counter('hits_total', 'Total hits');
+    c.inc();
+    c.inc();
+    c.inc();
+    const out = m.render();
+    assert.match(out, /^# HELP hits_total Total hits/m);
+    assert.match(out, /^# TYPE hits_total counter/m);
+    assert.match(out, /^hits_total 3$/m);
+  } finally {
+    m.reset();
+  }
+});
+
+test('counter increments are partitioned by labels', async () => {
+  const m = await loadMetrics();
+  try {
+    const c = m.counter('http_requests_total', 'HTTP requests');
+    c.inc({ method: 'GET', status: '200' });
+    c.inc({ method: 'GET', status: '200' });
+    c.inc({ method: 'POST', status: '200' });
+    c.inc({ method: 'GET', status: '500' });
+    const out = m.render();
+    // Two GET 200 → value 2.
+    assert.match(out, /^http_requests_total\{method="GET",status="200"\} 2$/m);
+    // One of each for the other combinations.
+    assert.match(out, /^http_requests_total\{method="POST",status="200"\} 1$/m);
+    assert.match(out, /^http_requests_total\{method="GET",status="500"\} 1$/m);
+  } finally {
+    m.reset();
+  }
+});
+
+test('gauge stores last value per label set', async () => {
+  const m = await loadMetrics();
+  try {
+    const g = m.gauge('ws_clients', 'Active WS clients');
+    g.set(3);
+    g.set(7); // overwrites the 3
+    g.set(12, { shard: 'a' });
+    g.set(5, { shard: 'b' });
+    const out = m.render();
+    assert.match(out, /^# TYPE ws_clients gauge/m);
+    assert.match(out, /^ws_clients 7$/m);
+    assert.match(out, /^ws_clients\{shard="a"\} 12$/m);
+    assert.match(out, /^ws_clients\{shard="b"\} 5$/m);
+  } finally {
+    m.reset();
+  }
+});
+
+test('histogram tracks count/sum + bucket counts', async () => {
+  const m = await loadMetrics();
+  try {
+    const h = m.histogram('latency_seconds', 'Request latency', {
+      buckets: [0.1, 0.5, 1, 5],
+    });
+    h.observe(0.05); // bucket le=0.1
+    h.observe(0.2);  // bucket le=0.5
+    h.observe(0.2);  // bucket le=0.5
+    h.observe(2);    // bucket le=5
+    h.observe(10);   // +Inf
+    const out = m.render();
+    assert.match(out, /^# TYPE latency_seconds histogram/m);
+    // Bucket counts: cumulative per Prometheus convention.
+    assert.match(out, /^latency_seconds_bucket\{le="0\.1"\} 1$/m);
+    assert.match(out, /^latency_seconds_bucket\{le="0\.5"\} 3$/m);
+    assert.match(out, /^latency_seconds_bucket\{le="1"\} 3$/m);
+    assert.match(out, /^latency_seconds_bucket\{le="5"\} 4$/m);
+    assert.match(out, /^latency_seconds_bucket\{le="\+Inf"\} 5$/m);
+    // Count + sum.
+    assert.match(out, /^latency_seconds_count 5$/m);
+    assert.match(out, /^latency_seconds_sum 12\.45$/m);
+  } finally {
+    m.reset();
+  }
+});
+
+test('histogram uses default buckets when none provided', async () => {
+  const m = await loadMetrics();
+  try {
+    const h = m.histogram('req_dur', 'Request duration');
+    h.observe(0.001); // fits in default 0.005 bucket
+    const out = m.render();
+    // We don't assert specific default values — just that the
+    // standard bucket boundaries appear in the output.
+    assert.match(out, /le="0\.005"/);
+    assert.match(out, /le="\+Inf"/);
+    assert.match(out, /^req_dur_count 1$/m);
+  } finally {
+    m.reset();
+  }
+});
+
+test('render returns empty string when no metrics registered', async () => {
+  const m = await loadMetrics();
+  try {
+    assert.equal(m.render(), '');
+  } finally {
+    m.reset();
+  }
+});
+
+test('render combines counters, gauges, histograms in order', async () => {
+  const m = await loadMetrics();
+  try {
+    m.counter('first_total', 'first').inc();
+    m.gauge('second', 'second').set(42);
+    m.histogram('third', 'third').observe(1);
+    const out = m.render();
+    const i1 = out.indexOf('# TYPE first_total');
+    const i2 = out.indexOf('# TYPE second');
+    const i3 = out.indexOf('# TYPE third');
+    assert.ok(i1 >= 0 && i2 > i1 && i3 > i2, 'metrics must render in registration order');
+  } finally {
+    m.reset();
+  }
+});
+
+test('label values are escaped', async () => {
+  const m = await loadMetrics();
+  try {
+    const c = m.counter('events_total', 'Events');
+    c.inc({ name: 'has "quote"' });
+    const out = m.render();
+    assert.match(out, /events_total\{name="has \\"quote\\""\} 1/);
+  } finally {
+    m.reset();
+  }
+});
+
+test('reset clears all metric types', async () => {
+  const m = await loadMetrics();
+  m.counter('c', 'c').inc();
+  m.gauge('g', 'g').set(1);
+  m.histogram('h', 'h').observe(1);
+  assert.notEqual(m.render(), '');
+  m.reset();
+  assert.equal(m.render(), '');
+});
+
+test('labels with same content but different key order collapse to one bucket', async () => {
+  // Prometheus convention is that label sets are unordered, so
+  // {a:'1',b:'2'} and {b:'2',a:'1'} must be the same series. Our
+  // implementation sorts keys before stringifying so this holds.
+  const m = await loadMetrics();
+  try {
+    const c = m.counter('mixed_total', 'mixed');
+    c.inc({ a: '1', b: '2' });
+    c.inc({ b: '2', a: '1' });
+    const out = m.render();
+    // Only one series line — both inc calls collapsed.
+    const matches = out.match(/^mixed_total\{/gm) || [];
+    assert.equal(matches.length, 1);
+    assert.match(out, /^mixed_total\{a="1",b="2"\} 2$/m);
+  } finally {
+    m.reset();
+  }
+});

package/bizar-dash/tests/rate-limit.test.mjs

@@ -0,0 +1,298 @@
+/**
+ * tests/rate-limit.test.mjs
+ *
+ * v4.8.0 — Tests for src/server/lib/rate-limit.mjs.
+ *
+ * Run with:
+ *   node --test tests/rate-limit.test.mjs
+ *
+ * Covers:
+ *   - Request within capacity returns 200 + X-RateLimit-* headers
+ *   - Request over capacity returns 429 with Retry-After + JSON body
+ *   - Bucket refills over time (verified via mock.timers tick)
+ *   - Different IPs have independent buckets
+ *   - Different scopes (chat vs event) have independent buckets
+ *   - clearBuckets() resets state between tests
+ *   - Constructor validates inputs
+ *   - 429 response carries X-RateLimit-Scope so server.mjs can log it
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mock } from 'node:test';
+import express from 'express';
+
+import {
+  createRateLimiter,
+  clearBuckets,
+  _peekBucket,
+  _bucketSize,
+} from '../src/server/lib/rate-limit.mjs';
+
+// ── Helpers ───────────────────────────────────────────────────────────────
+
+/**
+ * Build a minimal Express app with one route guarded by the given
+ * limiter. We override `req.ip` via the `trust proxy` setting on the
+ * app instance so tests can set it deterministically.
+ */
+function buildApp({ capacity, refillPerSecond, scope = 'test' }) {
+  const app = express();
+  app.set('trust proxy', true);
+  const limiter = createRateLimiter({ capacity, refillPerSecond, scope });
+  app.get('/ping', limiter, (_req, res) => res.json({ ok: true }));
+  return app;
+}
+
+/**
+ * Drive the Express app without binding a TCP socket. Returns the
+ * (status, headers, body) of the response so tests can assert without
+ * the noise of supertest.
+ */
+function drive(app, { ip = '127.0.0.1', method = 'GET', path = '/ping' } = {}) {
+  return new Promise((resolve, reject) => {
+    const req = {
+      method,
+      url: path,
+      ip,
+      socket: { remoteAddress: ip },
+      headers: {},
+    };
+    const resHeaders = {};
+    const res = {
+      statusCode: 200,
+      headersSent: false,
+      finished: false,
+      set(name, value) {
+        resHeaders[name.toLowerCase()] = value;
+        return this;
+      },
+      setHeader(name, value) {
+        resHeaders[name.toLowerCase()] = value;
+        return this;
+      },
+      getHeader(name) {
+        return resHeaders[name.toLowerCase()];
+      },
+      status(code) {
+        this.statusCode = code;
+        return this;
+      },
+      json(body) {
+        this.headersSent = true;
+        this.finished = true;
+        resolve({ status: this.statusCode, headers: resHeaders, body });
+        return this;
+      },
+      send(body) {
+        this.headersSent = true;
+        this.finished = true;
+        resolve({ status: this.statusCode, headers: resHeaders, body });
+        return this;
+      },
+      end(body) {
+        this.headersSent = true;
+        this.finished = true;
+        resolve({ status: this.statusCode, headers: resHeaders, body });
+        return this;
+      },
+      on() {
+        return this;
+      },
+      once() {
+        return this;
+      },
+      emit() {
+        return true;
+      },
+    };
+    try {
+      app._router.handle(req, res, (err) => {
+        if (err) reject(err);
+        else if (!res.finished) {
+          // Should not happen — limiter always responds.
+          reject(new Error('handler fell through without responding'));
+        }
+      });
+    } catch (err) {
+      reject(err);
+    }
+  });
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────
+
+test('accepts request within capacity and emits X-RateLimit-* headers', async () => {
+  clearBuckets();
+  const app = buildApp({ capacity: 5, refillPerSecond: 1, scope: 'test1' });
+  const r = await drive(app, { ip: '10.0.0.1' });
+  assert.equal(r.status, 200);
+  assert.deepEqual(r.body, { ok: true });
+  assert.equal(r.headers['x-ratelimit-limit'], '5');
+  // 1 token consumed from a full bucket of 5 → 4 remain.
+  assert.equal(r.headers['x-ratelimit-remaining'], '4');
+  assert.equal(r.headers['x-ratelimit-scope'], 'test1');
+  assert.equal(r.headers['retry-after'], undefined);
+});
+
+test('rejects over-capacity requests with 429 + Retry-After + JSON body', async () => {
+  clearBuckets();
+  const app = buildApp({ capacity: 2, refillPerSecond: 0.5, scope: 'test2' });
+  // Drain the bucket.
+  await drive(app, { ip: '10.0.0.2' });
+  await drive(app, { ip: '10.0.0.2' });
+  // Third request must be throttled.
+  const r = await drive(app, { ip: '10.0.0.2' });
+  assert.equal(r.status, 429);
+  assert.equal(r.body.error, 'rate_limited');
+  assert.equal(r.body.scope, 'test2');
+  assert.ok(typeof r.body.retryAfter === 'number' && r.body.retryAfter >= 1);
+  assert.equal(r.headers['x-ratelimit-limit'], '2');
+  assert.equal(r.headers['x-ratelimit-remaining'], '0');
+  assert.equal(r.headers['x-ratelimit-scope'], 'test2');
+  assert.ok(r.headers['retry-after']);
+  // retry-after is a string of an integer ≥ 1.
+  assert.match(r.headers['retry-after'], /^[1-9]\d*$/);
+});
+
+test('bucket refills over time', () => {
+  clearBuckets();
+  mock.timers.enable({ apis: ['Date'] });
+  try {
+    const limiter = createRateLimiter({
+      capacity: 5,
+      refillPerSecond: 1,
+      scope: 'refill',
+    });
+    // Build a minimal req/res pair; we'll call the middleware directly.
+    function fakeRes() {
+      const headers = {};
+      let status = 200;
+      return {
+        statusCode: status,
+        set(name, value) { headers[name.toLowerCase()] = value; return this; },
+        getHeader(name) { return headers[name.toLowerCase()]; },
+        status(code) { this.statusCode = code; return this; },
+        json() { /* swallow */ },
+        headers,
+      };
+    }
+    function fakeReq(ip) {
+      return { ip, socket: { remoteAddress: ip } };
+    }
+
+    // Drain 5 tokens instantly.
+    for (let i = 0; i < 5; i++) {
+      limiter(fakeReq('10.0.0.3'), fakeRes(), () => {});
+    }
+    // The 6th request must be rejected.
+    const denied = fakeRes();
+    let nextCalled = false;
+    limiter(fakeReq('10.0.0.3'), denied, () => { nextCalled = true; });
+    assert.equal(denied.statusCode, 429);
+    assert.equal(nextCalled, false);
+
+    // Advance time by 1 second → 1 token regenerated.
+    mock.timers.tick(1000);
+    const accepted = fakeRes();
+    let acceptedNext = false;
+    limiter(fakeReq('10.0.0.3'), accepted, () => { acceptedNext = true; });
+    assert.equal(accepted.statusCode, 200);
+    assert.equal(acceptedNext, true);
+
+    // Bucket state sanity check.
+    const bucket = _peekBucket('refill:10.0.0.3');
+    assert.ok(bucket, 'expected bucket to exist');
+    assert.ok(bucket.tokens >= 0 && bucket.tokens < 5);
+  } finally {
+    mock.timers.reset();
+    clearBuckets();
+  }
+});
+
+test('different IPs have independent buckets', async () => {
+  clearBuckets();
+  const app = buildApp({ capacity: 1, refillPerSecond: 0.01, scope: 'iso-ip' });
+  // Drain IP A.
+  const a1 = await drive(app, { ip: '10.0.0.10' });
+  assert.equal(a1.status, 200);
+  const a2 = await drive(app, { ip: '10.0.0.10' });
+  assert.equal(a2.status, 429);
+  // IP B still has full budget.
+  const b1 = await drive(app, { ip: '10.0.0.11' });
+  assert.equal(b1.status, 200);
+  assert.equal(b1.headers['x-ratelimit-remaining'], '0');
+});
+
+test('different scopes (chat vs event) have independent buckets', async () => {
+  clearBuckets();
+  const chatApp = buildApp({ capacity: 1, refillPerSecond: 0.01, scope: 'chat' });
+  const eventApp = buildApp({ capacity: 1, refillPerSecond: 0.01, scope: 'event' });
+  // Drain chat for this IP.
+  const c1 = await drive(chatApp, { ip: '10.0.0.20' });
+  assert.equal(c1.status, 200);
+  const c2 = await drive(chatApp, { ip: '10.0.0.20' });
+  assert.equal(c2.status, 429);
+  assert.equal(c2.body.scope, 'chat');
+  // Event scope for the SAME ip still has full budget.
+  const e1 = await drive(eventApp, { ip: '10.0.0.20' });
+  assert.equal(e1.status, 200);
+  assert.equal(e1.headers['x-ratelimit-scope'], 'event');
+});
+
+test('clearBuckets() resets state', async () => {
+  clearBuckets();
+  const app = buildApp({ capacity: 1, refillPerSecond: 0.01, scope: 'clear' });
+  await drive(app, { ip: '10.0.0.30' });
+  assert.equal(_bucketSize(), 1);
+  // Bucket exhausted — next request 429.
+  const r = await drive(app, { ip: '10.0.0.30' });
+  assert.equal(r.status, 429);
+  // Reset and retry — fresh budget.
+  clearBuckets();
+  assert.equal(_bucketSize(), 0);
+  const r2 = await drive(app, { ip: '10.0.0.30' });
+  assert.equal(r2.status, 200);
+});
+
+test('rejects invalid constructor arguments', () => {
+  assert.throws(() => createRateLimiter({ capacity: 0, refillPerSecond: 1 }), /capacity/);
+  assert.throws(() => createRateLimiter({ capacity: -1, refillPerSecond: 1 }), /capacity/);
+  assert.throws(() => createRateLimiter({ capacity: 'x', refillPerSecond: 1 }), /capacity/);
+  assert.throws(() => createRateLimiter({ capacity: 5, refillPerSecond: 0 }), /refillPerSecond/);
+  assert.throws(() => createRateLimiter({ capacity: 5, refillPerSecond: -1 }), /refillPerSecond/);
+  assert.throws(() => createRateLimiter({ capacity: 5, refillPerSecond: 1, scope: '' }), /scope/);
+  assert.throws(() => createRateLimiter({ capacity: 5, refillPerSecond: 1, scope: 42 }), /scope/);
+});
+
+test('falls back to socket.remoteAddress when req.ip missing', async () => {
+  clearBuckets();
+  const app = buildApp({ capacity: 1, refillPerSecond: 0.01, scope: 'sock' });
+  // Build a request WITHOUT ip but WITH socket.remoteAddress. We have
+  // to drive it manually because buildApp always sets ip.
+  const limiter = createRateLimiter({
+    capacity: 1,
+    refillPerSecond: 0.01,
+    scope: 'sock',
+  });
+  function fakeRes() {
+    const headers = {};
+    return {
+      statusCode: 200,
+      set(name, value) { headers[name.toLowerCase()] = value; return this; },
+      getHeader(name) { return headers[name.toLowerCase()]; },
+      status(code) { this.statusCode = code; return this; },
+      json() { /* swallow */ },
+      headers,
+    };
+  }
+  // No req.ip, no socket — must default to 'unknown'.
+  const req = {};
+  const res1 = fakeRes();
+  limiter(req, res1, () => {});
+  assert.equal(res1.statusCode, 200);
+  const res2 = fakeRes();
+  limiter(req, res2, () => {});
+  assert.equal(res2.statusCode, 429);
+  // The unknown-IP bucket must exist.
+  assert.ok(_peekBucket('sock:unknown'));
+});

package/bizar-dash/tests/server-bugfixes.test.mjs

@@ -312,7 +312,7 @@ describe('Bug S3 — chat.mjs per-session delta cap', () => {
     );
     assert.match(src, /CHAT_DELTA_BUFFER_CAP\s*=\s*1000/,
       'cap constant should be set to 1000');
-    assert.match(src, /console\.warn\(/,
-      'cap-exceeded path should log a warning');
+    assert.match(src, /logWarn\(/,
+      'cap-exceeded path should log a warning via the structured logger');
   });
 });