serverless-ircd 0.1.0 → 0.3.0

package/packages/irc-server/src/dispatch.ts

@@ -9,9 +9,16 @@
  *   - Consecutive identical Send effects coalesce into one runtime call
  *     (the test named "dedup").
  *   - The first runtime rejection propagates and stops processing.
+ *
+ * When an optional {@link DispatchOptions.logger} is supplied, dispatch
+ * emits a `dispatch` debug record describing the effect count and a
+ * `dispatch.error` warn record when a handler rejects — both stamped
+ * with the caller's `traceId`/`connectionId` so the actor → runtime
+ * pipeline can be reconstructed end-to-end.
  */
 
-import type { BroadcastEffect, Effect, RawLine } from '@serverless-ircd/irc-core';
+import type { BroadcastEffect, Effect, Logger, RawLine } from '@serverless-ircd/irc-core';
+import { LogLevel } from '@serverless-ircd/irc-core';
 import type { IrcRuntime } from './runtime.js';
 
 /** Discriminated-union handler: each Effect tag maps to one runtime call. */
@@ -33,6 +40,29 @@ const handlers: { [K in Effect['tag']]: Handler<Extract<Effect, { tag: K }>> } =
 
 function noop(): void {}
 
+/**
+ * Optional knobs for {@link dispatch}. All observability-related; the
+ * core effect-interpretation behaviour is unchanged when they are absent.
+ */
+export interface DispatchOptions {
+  /**
+   * Logger to emit `dispatch` / `dispatch.error` records to. When omitted,
+   * dispatch is silent — preserving the default silent contract.
+   */
+  readonly logger?: Logger;
+  /**
+   * Trace id to stamp on every log record. When omitted, records carry
+   * `traceId: undefined` (loggers drop undefined fields, so the field is
+   * absent from the JSON line).
+   */
+  readonly traceId?: string;
+  /**
+   * Connection id the dispatch is serving (the actor's bound connId).
+   * Stamped on every record alongside `traceId`.
+   */
+  readonly connectionId?: string;
+}
+
 /**
  * Returns true iff two effects are interchangeable — used to coalesce
  * consecutive duplicates so a reducer's accidental double-send is a no-op.
@@ -61,24 +91,78 @@ function linesEqual(a: RawLine[], b: RawLine[]): boolean {
 /**
  * Interprets `effects` in order against `runtime`. Returns when every
  * effect has been performed; the first rejection propagates.
+ *
+ * When `opts.logger` is supplied a `dispatch` debug record is emitted
+ * before the loop begins (with the effect count and a per-tag histogram).
  */
-export async function dispatch(effects: Effect[], runtime: IrcRuntime): Promise<void> {
+export async function dispatch(
+  effects: Effect[],
+  runtime: IrcRuntime,
+  opts?: DispatchOptions,
+): Promise<void> {
+  if (opts?.logger !== undefined) {
+    logDispatch(opts.logger, opts.traceId, opts.connectionId, effects);
+  }
   let previous: Effect | undefined;
   for (const effect of effects) {
     if (previous !== undefined && isSameSend(previous, effect)) {
       previous = effect;
       continue;
     }
-    await handle(effect, runtime);
+    await handle(effect, runtime, opts);
     previous = effect;
   }
 }
 
-async function handle(effect: Effect, runtime: IrcRuntime): Promise<void> {
+async function handle(effect: Effect, runtime: IrcRuntime, opts?: DispatchOptions): Promise<void> {
   // The dispatch table is keyed by tag; the cast is the standard TS pattern
   // for exhaustive-union dispatch.
   const handler = handlers[effect.tag] as Handler<Effect>;
-  await handler(effect, runtime);
+  try {
+    await handler(effect, runtime);
+  } catch (err) {
+    if (opts?.logger !== undefined) {
+      opts.logger.on(logLevelFor(err), 'dispatch.error', {
+        traceId: opts.traceId,
+        connectionId: opts.connectionId,
+        effect: effect.tag,
+        err: err instanceof Error ? { name: err.name, message: err.message } : String(err),
+      });
+    }
+    throw err;
+  }
+}
+
+/**
+ * Emits one `dispatch` debug record per call with a per-tag histogram so
+ * dashboards can slice "broadcasts per frame", "sends per frame", etc.
+ */
+function logDispatch(
+  logger: Logger,
+  traceId: string | undefined,
+  connectionId: string | undefined,
+  effects: Effect[],
+): void {
+  const histogram: Record<string, number> = {};
+  for (const e of effects) {
+    histogram[e.tag] = (histogram[e.tag] ?? 0) + 1;
+  }
+  logger.on(LogLevel.Debug, 'dispatch', {
+    traceId,
+    connectionId,
+    effects: effects.map((e) => e.tag),
+    histogram,
+  });
+}
+
+/**
+ * Maps a thrown error to the level dispatch should log it at. Today every
+ * dispatch rejection is operational (transient network / DO fetch issues),
+ * so warn is appropriate; handlers do not throw for input-shape problems
+ * (those surface as IRC numerics via Send effects).
+ */
+function logLevelFor(_err: unknown): LogLevel {
+  return LogLevel.Warn;
 }
 
 /**

package/packages/irc-server/src/index.ts

@@ -9,3 +9,5 @@ export type { IrcRuntime } from './runtime.js';
 export { dispatch } from './dispatch.js';
 export { ConnectionActor, splitFrameLines } from './actor.js';
 export type { ActorChannelAccess, ConnectionActorOptions } from './actor.js';
+export { buildRoutedReducers, resolveFloodControl } from './routing.js';
+export type { RoutedReducers } from './routing.js';

package/packages/irc-server/src/routing.ts

@@ -0,0 +1,160 @@
+/**
+ * Routed reducer map construction for the {@link ConnectionActor}.
+ *
+ * Every command the actor dispatches runs through one of the reducers in
+ * this map. {@link buildRoutedReducers} wraps each reducer with the
+ * per-connection flood-control token bucket so a flooding client is
+ * disconnected end-to-end regardless of whether the routed command mutates
+ * connection state (PING/USER/…) or channel state (JOIN/PRIVMSG/…). Flood
+ * control bounds bytes-in from the client, not which authority owns the
+ * state the command touches.
+ *
+ * The wrapper reads `ctx.clock` (the actor's injected {@link Clock}) and
+ * stores the bucket on `ctx.connection.floodBucket`, so the same time source
+ * the rest of the actor uses drives refill. Extracted as a pure helper so the
+ * actor and unit tests can inspect the wrapped map without spinning up a full
+ * actor + fake runtime.
+ *
+ * Three reducers (`listReducer`, `whoReducer`, `whoisReducer`) take a bespoke
+ * signature that fetches runtime state before invocation; they do not fit the
+ * `Reducer<S>` shape the flood wrapper operates on and are therefore left
+ * unwrapped here. They are read-only query paths; the per-connection bucket
+ * still bounds the write-path commands a client can issue around them.
+ */
+
+import {
+  type ChannelState,
+  type ConnectionState,
+  DEFAULT_FLOOD_CONTROL_CONFIG,
+  type FloodControlConfig,
+  type Reducer,
+  type ServerConfig,
+  authenticateReducer,
+  awayReducer,
+  capReducer,
+  channelModeReducer,
+  defaultCommandCost,
+  inviteReducer,
+  joinReducer,
+  kickReducer,
+  motdReducer,
+  namesReducer,
+  nickReducer,
+  noticeChannelReducer,
+  noticeUserReducer,
+  operReducer,
+  partReducer,
+  passReducer,
+  pingReducer,
+  pongReducer,
+  privmsgChannelReducer,
+  privmsgUserReducer,
+  quitReducer,
+  tagmsgChannelReducer,
+  tagmsgUserReducer,
+  topicReducer,
+  userModeReducer,
+  userReducer,
+  wrapWithFloodControl,
+} from '@serverless-ircd/irc-core';
+
+/**
+ * The wrapped reducer for every command the actor routes by name. Keyed by
+ * logical command rather than IRC verb because PRIVMSG/NOTICE/MODE each fan
+ * out to two reducers depending on the target shape (channel vs. user).
+ */
+export interface RoutedReducers {
+  // Connection-authority reducers.
+  readonly ping: Reducer<ConnectionState>;
+  readonly pong: Reducer<ConnectionState>;
+  readonly nick: Reducer<ConnectionState>;
+  readonly user: Reducer<ConnectionState>;
+  readonly pass: Reducer<ConnectionState>;
+  readonly quit: Reducer<ConnectionState>;
+  readonly motd: Reducer<ConnectionState>;
+  readonly oper: Reducer<ConnectionState>;
+  readonly cap: Reducer<ConnectionState>;
+  readonly authenticate: Reducer<ConnectionState>;
+  readonly away: Reducer<ConnectionState>;
+  // Channel-authority reducers.
+  readonly join: Reducer<ChannelState>;
+  readonly part: Reducer<ChannelState>;
+  readonly topic: Reducer<ChannelState>;
+  readonly names: Reducer<ChannelState>;
+  readonly kick: Reducer<ChannelState>;
+  readonly invite: Reducer<ChannelState>;
+  // Target-dependent reducers.
+  readonly privmsgChannel: Reducer<ChannelState>;
+  readonly privmsgUser: Reducer<ConnectionState>;
+  readonly noticeChannel: Reducer<ChannelState>;
+  readonly noticeUser: Reducer<ConnectionState>;
+  readonly tagmsgChannel: Reducer<ChannelState>;
+  readonly tagmsgUser: Reducer<ConnectionState>;
+  readonly channelMode: Reducer<ChannelState>;
+  readonly userMode: Reducer<ConnectionState>;
+}
+
+/**
+ * Resolves the effective flood-control config for a deployment.
+ *
+ * - `serverConfig.floodControl === null` → returns `null` (disabled; the
+ *   actor skips wrapping entirely).
+ * - `undefined` → the documented {@link DEFAULT_FLOOD_CONTROL_CONFIG}.
+ * - an object → those thresholds.
+ *
+ * Control-plane commands (`PING`/`PONG`/`CAP`/`AUTHENTICATE`/`QUIT`) are
+ * exempt by default via {@link defaultCommandCost}. A caller-supplied
+ * `commandCost` (only possible on a code-constructed config — it cannot be
+ * serialized) is preserved as-is.
+ */
+export function resolveFloodControl(serverConfig: ServerConfig): FloodControlConfig | null {
+  const fc = serverConfig.floodControl;
+  if (fc === null) return null;
+  if (fc === undefined) {
+    return { ...DEFAULT_FLOOD_CONTROL_CONFIG, commandCost: defaultCommandCost };
+  }
+  return { ...fc, commandCost: fc.commandCost ?? defaultCommandCost };
+}
+
+/**
+ * Builds the wrapped reducer map for a connection.
+ *
+ * When flood control is disabled (`floodControl: null`), returns the raw
+ * reducers unchanged so existing behaviour is preserved bit-for-bit.
+ * Otherwise every reducer is wrapped with {@link wrapWithFloodControl} using
+ * the resolved config, so the token-bucket check runs on every dispatched
+ * command.
+ */
+export function buildRoutedReducers(serverConfig: ServerConfig): RoutedReducers {
+  const floodControl = resolveFloodControl(serverConfig);
+  const wrap = <S>(reducer: Reducer<S>): Reducer<S> =>
+    floodControl === null ? reducer : wrapWithFloodControl(reducer, floodControl);
+
+  return {
+    ping: wrap(pingReducer),
+    pong: wrap(pongReducer),
+    nick: wrap(nickReducer),
+    user: wrap(userReducer),
+    pass: wrap(passReducer),
+    quit: wrap(quitReducer),
+    motd: wrap(motdReducer),
+    oper: wrap(operReducer),
+    cap: wrap(capReducer),
+    authenticate: wrap(authenticateReducer),
+    away: wrap(awayReducer),
+    join: wrap(joinReducer),
+    part: wrap(partReducer),
+    topic: wrap(topicReducer),
+    names: wrap(namesReducer),
+    kick: wrap(kickReducer),
+    invite: wrap(inviteReducer),
+    privmsgChannel: wrap(privmsgChannelReducer),
+    privmsgUser: wrap(privmsgUserReducer),
+    noticeChannel: wrap(noticeChannelReducer),
+    noticeUser: wrap(noticeUserReducer),
+    tagmsgChannel: wrap(tagmsgChannelReducer),
+    tagmsgUser: wrap(tagmsgUserReducer),
+    channelMode: wrap(channelModeReducer),
+    userMode: wrap(userModeReducer),
+  };
+}