serverless-ircd 0.1.0 → 0.2.0

package/packages/irc-core/tests/flood-control.test.ts

@@ -0,0 +1,394 @@
+import { describe, expect, it } from 'vitest';
+import { Effect } from '../src/effects';
+import type { Effect as EffectType, RawLine } from '../src/effects';
+import {
+  EXCESS_FLOOD_REASON,
+  type FloodControlConfig,
+  defaultCommandCost,
+  wrapWithFloodControl,
+} from '../src/flood-control';
+import { EmptyMotdProvider, FakeClock, SequentialIdFactory } from '../src/ports';
+import { type ConnectionState, createConnection } from '../src/state/connection';
+import {
+  type Ctx,
+  type Reducer,
+  type ReducerResult,
+  type ServerConfig,
+  buildCtx,
+} from '../src/types';
+
+const serverConfig: ServerConfig = {
+  serverName: 'irc.example.com',
+  networkName: 'ExampleNet',
+  maxChannelsPerUser: 30,
+  maxTargetsPerCommand: 10,
+  maxListEntries: 50,
+  nickLen: 30,
+  channelLen: 50,
+  topicLen: 390,
+  quitMessage: 'Client Quit',
+};
+
+function makeCtx(state: ConnectionState, clock: FakeClock): Ctx {
+  return buildCtx({
+    serverConfig,
+    clock,
+    ids: new SequentialIdFactory(),
+    motd: EmptyMotdProvider,
+    connection: state,
+  });
+}
+
+function makeState(id = 'c1'): ConnectionState {
+  return createConnection({ id, connectedSince: 0 });
+}
+
+const L = (text: string): RawLine => ({ text });
+
+/**
+ * Inner reducer for tests: counts invocations and emits a single Send so the
+ * wrapper's pass-through behaviour is observable.
+ */
+function countingReducer(): { reducer: Reducer<ConnectionState>; getCalls: () => number } {
+  let calls = 0;
+  const reducer: Reducer<ConnectionState> = (state, _msg, ctx): ReducerResult<ConnectionState> => {
+    calls += 1;
+    return {
+      state,
+      effects: [Effect.send(ctx.connId, [L('inner-ok')])],
+    };
+  };
+  return { reducer, getCalls: () => calls };
+}
+
+function privmsg(text: string): {
+  command: string;
+  params: string[];
+  tags: Record<string, string>;
+} {
+  return { command: 'PRIVMSG', params: ['#foo', text], tags: {} };
+}
+
+function ircMessage(
+  command: string,
+  params: string[] = [],
+): {
+  command: string;
+  params: string[];
+  tags: Record<string, string>;
+} {
+  return { command, params, tags: {} };
+}
+
+const CAP_10: FloodControlConfig = {
+  capacity: 10,
+  refillRatePerSecond: 1,
+  disconnectThreshold: 0,
+};
+
+const CAP_5: FloodControlConfig = {
+  capacity: 5,
+  refillRatePerSecond: 1,
+  disconnectThreshold: 0,
+};
+
+describe('wrapWithFloodControl — under-limit messages pass through', () => {
+  it('invokes the inner reducer for every message when the burst fits the bucket', () => {
+    const state = makeState();
+    const clock = new FakeClock(1_000);
+    const ctx = makeCtx(state, clock);
+    const inner = countingReducer();
+    const wrapped = wrapWithFloodControl(inner.reducer, CAP_10);
+
+    for (let i = 0; i < 10; i++) {
+      const out = wrapped(state, privmsg(`m${i}`), ctx);
+      expect(out.effects).toEqual<EffectType[]>([Effect.send('c1', [L('inner-ok')])]);
+    }
+    expect(inner.getCalls()).toBe(10);
+  });
+
+  it('returns the inner reducer result untouched on the happy path', () => {
+    const state = makeState();
+    const clock = new FakeClock(1_000);
+    const ctx = makeCtx(state, clock);
+    const inner = countingReducer();
+    const wrapped = wrapWithFloodControl(inner.reducer, CAP_10);
+
+    const expectedEffects = [Effect.send('c1', [L('inner-ok')])];
+    const out = wrapped(state, privmsg('hello'), ctx);
+    expect(out.effects).toEqual(expectedEffects);
+    expect(out.state).toBe(state);
+  });
+
+  it('initializes the bucket lazily on the first message', () => {
+    const state = makeState();
+    const clock = new FakeClock(42_000);
+    const ctx = makeCtx(state, clock);
+    const inner = countingReducer();
+    const wrapped = wrapWithFloodControl(inner.reducer, CAP_10);
+
+    expect(state.floodBucket).toBeUndefined();
+    wrapped(state, privmsg('first'), ctx);
+    expect(state.floodBucket).toBeDefined();
+    expect(state.floodBucket?.lastRefill).toBe(42_000);
+  });
+});
+
+describe('wrapWithFloodControl — over-limit burst disconnects with "Excess Flood"', () => {
+  it('emits Disconnect("Excess Flood") once capacity is exhausted (10 PRIVMSG in 1ms with capacity 5)', () => {
+    const state = makeState();
+    const clock = new FakeClock(1_000);
+    const ctx = makeCtx(state, clock);
+    const inner = countingReducer();
+    const wrapped = wrapWithFloodControl(inner.reducer, CAP_5);
+
+    const results: ReducerResult<ConnectionState>[] = [];
+    for (let i = 0; i < 10; i++) {
+      results.push(wrapped(state, privmsg(`m${i}`), ctx));
+    }
+
+    // First 5 messages pass through to the inner reducer.
+    expect(inner.getCalls()).toBe(5);
+    for (let i = 0; i < 5; i++) {
+      expect(results[i]?.effects).toEqual<EffectType[]>([Effect.send('c1', [L('inner-ok')])]);
+    }
+    // 6th message onward: Disconnect with the canonical reason, inner NOT called.
+    for (let i = 5; i < 10; i++) {
+      expect(results[i]?.effects).toEqual<EffectType[]>([
+        Effect.disconnect('c1', EXCESS_FLOOD_REASON),
+      ]);
+    }
+  });
+
+  it('uses the literal "Excess Flood" string per RFC 2812 §6', () => {
+    expect(EXCESS_FLOOD_REASON).toBe('Excess Flood');
+  });
+
+  it('does NOT call the inner reducer for the message that triggers the disconnect', () => {
+    const state = makeState();
+    const clock = new FakeClock(1_000);
+    const ctx = makeCtx(state, clock);
+    const inner = countingReducer();
+    const wrapped = wrapWithFloodControl(inner.reducer, CAP_5);
+
+    for (let i = 0; i < 5; i++) wrapped(state, privmsg(`m${i}`), ctx);
+    const callsBefore = inner.getCalls();
+    wrapped(state, privmsg('over'), ctx);
+    expect(inner.getCalls()).toBe(callsBefore);
+  });
+
+  it('threshold allows bursts that exceed capacity by up to the threshold', () => {
+    const state = makeState();
+    const clock = new FakeClock(1_000);
+    const ctx = makeCtx(state, clock);
+    const inner = countingReducer();
+    const config: FloodControlConfig = {
+      capacity: 10,
+      refillRatePerSecond: 1,
+      disconnectThreshold: 2,
+    };
+    const wrapped = wrapWithFloodControl(inner.reducer, config);
+
+    const results: ReducerResult<ConnectionState>[] = [];
+    for (let i = 0; i < 13; i++) {
+      results.push(wrapped(state, privmsg(`m${i}`), ctx));
+    }
+    // Threshold = 2 means 12 messages pass (capacity 10 + 2 slack), 13th kills.
+    expect(inner.getCalls()).toBe(12);
+    for (let i = 0; i < 12; i++) {
+      expect(results[i]?.effects).toEqual<EffectType[]>([Effect.send('c1', [L('inner-ok')])]);
+    }
+    expect(results[12]?.effects).toEqual<EffectType[]>([
+      Effect.disconnect('c1', EXCESS_FLOOD_REASON),
+    ]);
+  });
+});
+
+describe('wrapWithFloodControl — refill', () => {
+  it('refills the bucket as wall-clock time advances, allowing further messages', () => {
+    const state = makeState();
+    const clock = new FakeClock(1_000);
+    const ctx = makeCtx(state, clock);
+    const inner = countingReducer();
+    const config: FloodControlConfig = {
+      capacity: 5,
+      refillRatePerSecond: 5,
+      disconnectThreshold: 0,
+    };
+    const wrapped = wrapWithFloodControl(inner.reducer, config);
+
+    for (let i = 0; i < 5; i++) wrapped(state, privmsg(`m${i}`), ctx);
+    expect(inner.getCalls()).toBe(5);
+
+    clock.advance(1_000);
+    const out = wrapped(state, privmsg('after-refill'), ctx);
+    expect(out.effects).toEqual<EffectType[]>([Effect.send('c1', [L('inner-ok')])]);
+    expect(inner.getCalls()).toBe(6);
+  });
+
+  it('caps refill at the bucket capacity (no overflow)', () => {
+    const state = makeState();
+    const clock = new FakeClock(1_000);
+    const ctx = makeCtx(state, clock);
+    const inner = countingReducer();
+    const config: FloodControlConfig = {
+      capacity: 5,
+      refillRatePerSecond: 1_000,
+      disconnectThreshold: 0,
+    };
+    const wrapped = wrapWithFloodControl(inner.reducer, config);
+
+    wrapped(state, privmsg('first'), ctx);
+    expect(state.floodBucket?.tokens).toBe(4);
+
+    clock.advance(10_000);
+    wrapped(state, privmsg('second'), ctx);
+    expect(state.floodBucket?.tokens).toBe(4);
+  });
+});
+
+describe('wrapWithFloodControl — determinism', () => {
+  it('returns the same decision for the same Clock readings + message stream', () => {
+    const run = (): { innerCalls: number; disconnects: number } => {
+      const state = makeState();
+      const clock = new FakeClock(1_000);
+      const ctx = makeCtx(state, clock);
+      const inner = countingReducer();
+      const wrapped = wrapWithFloodControl(inner.reducer, CAP_5);
+      let disconnects = 0;
+      for (let i = 0; i < 7; i++) {
+        const out = wrapped(state, privmsg(`m${i}`), ctx);
+        if (out.effects.some((e) => e.tag === 'Disconnect')) disconnects += 1;
+      }
+      return { innerCalls: inner.getCalls(), disconnects };
+    };
+    expect(run()).toEqual(run());
+  });
+});
+
+describe('wrapWithFloodControl — generic over inner state', () => {
+  it('works with a reducer whose state is not ConnectionState (e.g. a counter)', () => {
+    interface Counter {
+      n: number;
+    }
+    const inc: Reducer<Counter> = (s) => ({ state: { n: s.n + 1 }, effects: [] });
+
+    const state: Counter = { n: 0 };
+    const conn = makeState();
+    const clock = new FakeClock(1_000);
+    const ctx = makeCtx(conn, clock);
+    const wrapped = wrapWithFloodControl(inc, CAP_10);
+    const out = wrapped(state, privmsg('x'), ctx);
+    expect(out.state.n).toBe(1);
+    expect(out.effects).toEqual([]);
+  });
+});
+
+describe('wrapWithFloodControl — per-command cost (commandCost)', () => {
+  it('defaultCommandCost returns 0 for the control-plane exempt set and 1 otherwise', () => {
+    for (const command of ['PING', 'PONG', 'CAP', 'AUTHENTICATE', 'QUIT']) {
+      expect(defaultCommandCost(command)).toBe(0);
+    }
+    expect(defaultCommandCost('PRIVMSG')).toBe(1);
+    expect(defaultCommandCost('JOIN')).toBe(1);
+  });
+
+  it('delegates a cost-0 PING to the inner reducer even when the bucket is exhausted', () => {
+    const state = makeState();
+    const clock = new FakeClock(1_000);
+    const ctx = makeCtx(state, clock);
+    const inner = countingReducer();
+    const wrapped = wrapWithFloodControl(inner.reducer, {
+      ...CAP_5,
+      commandCost: defaultCommandCost,
+    });
+
+    for (let i = 0; i < 5; i++) wrapped(state, privmsg(`m${i}`), ctx);
+    expect(inner.getCalls()).toBe(5);
+
+    const out = wrapped(state, ircMessage('PING', ['12345']), ctx);
+    expect(out.effects).toEqual<EffectType[]>([Effect.send('c1', [L('inner-ok')])]);
+    expect(inner.getCalls()).toBe(6);
+  });
+
+  it('a cost-0 command does NOT decrement the bucket', () => {
+    const state = makeState();
+    const clock = new FakeClock(1_000);
+    const ctx = makeCtx(state, clock);
+    const inner = countingReducer();
+    const wrapped = wrapWithFloodControl(inner.reducer, {
+      ...CAP_5,
+      commandCost: defaultCommandCost,
+    });
+
+    for (let i = 0; i < 5; i++) wrapped(state, privmsg(`m${i}`), ctx);
+    expect(state.floodBucket?.tokens).toBe(0);
+
+    wrapped(state, ircMessage('PING', ['12345']), ctx);
+    expect(state.floodBucket?.tokens).toBe(0);
+  });
+
+  it('a CAP LS burst (10 frames in 1ms with capacity 5) does NOT disconnect when CAP costs 0', () => {
+    const state = makeState();
+    const clock = new FakeClock(1_000);
+    const ctx = makeCtx(state, clock);
+    const inner = countingReducer();
+    const wrapped = wrapWithFloodControl(inner.reducer, {
+      capacity: 5,
+      refillRatePerSecond: 1,
+      disconnectThreshold: 0,
+      commandCost: (c) => (c === 'CAP' ? 0 : 1),
+    });
+
+    let disconnects = 0;
+    for (let i = 0; i < 10; i++) {
+      const out = wrapped(state, ircMessage('CAP', ['LS']), ctx);
+      if (out.effects.some((e) => e.tag === 'Disconnect')) disconnects += 1;
+    }
+    expect(disconnects).toBe(0);
+    expect(inner.getCalls()).toBe(10);
+  });
+
+  it('throws at construction when commandCost returns a negative cost', () => {
+    expect(() =>
+      wrapWithFloodControl(countingReducer().reducer, {
+        ...CAP_5,
+        commandCost: () => -1,
+      }),
+    ).toThrow();
+  });
+
+  it('omitting commandCost keeps the flat-cost behaviour so a PING can still disconnect (regression)', () => {
+    const state = makeState();
+    const clock = new FakeClock(1_000);
+    const ctx = makeCtx(state, clock);
+    const inner = countingReducer();
+    const wrapped = wrapWithFloodControl(inner.reducer, CAP_5);
+
+    for (let i = 0; i < 5; i++) wrapped(state, privmsg(`m${i}`), ctx);
+    expect(inner.getCalls()).toBe(5);
+
+    const out = wrapped(state, ircMessage('PING', ['12345']), ctx);
+    expect(out.effects).toEqual<EffectType[]>([Effect.disconnect('c1', EXCESS_FLOOD_REASON)]);
+    expect(inner.getCalls()).toBe(5);
+  });
+
+  it('a custom cost greater than 1 deducts multiple tokens per message', () => {
+    const state = makeState();
+    const clock = new FakeClock(1_000);
+    const ctx = makeCtx(state, clock);
+    const inner = countingReducer();
+    const wrapped = wrapWithFloodControl(inner.reducer, {
+      capacity: 5,
+      refillRatePerSecond: 1,
+      disconnectThreshold: 0,
+      commandCost: () => 2,
+    });
+
+    wrapped(state, privmsg('first'), ctx);
+    expect(state.floodBucket?.tokens).toBe(3);
+
+    wrapped(state, privmsg('second'), ctx);
+    expect(state.floodBucket?.tokens).toBe(1);
+  });
+});