serverless-ircd 0.2.0 → 0.4.0

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

@@ -26,9 +26,11 @@
  */
 
 import {
+  type AccountStore,
   type ChanName,
   type ChannelState,
   type Clock,
+  type ConnSnapshot,
   type ConnectionState,
   Effect,
   type Effect as EffectType,
@@ -38,6 +40,8 @@ import {
   type Logger,
   type MessageStore,
   type MotdProvider,
+  type MtlsIdentityProvider,
+  type NickHistoryStore,
   NoopLoggerInstance,
   Numerics,
   type RawLine,
@@ -46,15 +50,20 @@ import {
   chathistoryReducer,
   handleJoinZero,
   isChannelTarget,
+  isonReducer,
   listReducer,
   parse,
+  toSnapshot,
+  userhostReducer,
   whoReducer,
   whoisReducer,
+  whowasReducer,
 } from '@serverless-ircd/irc-core';
 import { dispatch } from './dispatch.js';
 import type { DispatchOptions } from './dispatch.js';
 import { type RoutedReducers, buildRoutedReducers } from './routing.js';
 import type { IrcRuntime } from './runtime.js';
+import { type Transport, WsTextFrameTransport } from './transport.js';
 
 /**
  * Channel-state access for the actor.
@@ -103,6 +112,32 @@ export interface ConnectionActorOptions {
    * opt in.
    */
   readonly messages?: MessageStore;
+  /**
+   * SASL account verification source (absent when no accounts are
+   * configured). When bound, `ctx.accounts` is defined so the
+   * `AUTHENTICATE` reducer can verify PLAIN credentials end-to-end.
+   * Omitted (→ `ctx.accounts` undefined) preserves the existing
+   * behaviour for callers/tests that do not opt in: a client completing
+   * `AUTHENTICATE PLAIN` receives `904 ERR_SASLFAIL` because no store
+   * can vouch for the credentials.
+   */
+  readonly accounts?: AccountStore;
+  /**
+   * mTLS client-cert identity source for SASL EXTERNAL (absent when mTLS
+   * is not configured). When bound, `ctx.mtlsIdentity` is defined so the
+   * `AUTHENTICATE EXTERNAL` reducer can resolve the connection's verified
+   * certificate subject. Omitted (→ `ctx.mtlsIdentity` undefined) means
+   * EXTERNAL is rejected with `904 ERR_SASLFAIL`.
+   */
+  readonly mtlsIdentity?: MtlsIdentityProvider;
+  /**
+   * Nick-history source for the `WHOWAS` command (absent when WHOWAS
+   * history retention is disabled). When bound, `ctx.history` is defined
+   * so the QUIT and NICK-change reducers record sign-off entries and the
+   * WHOWAS reducer replays them. Omitted (→ `ctx.history` undefined)
+   * preserves the no-store behaviour: `WHOWAS <nick>` emits `406`+`369`.
+   */
+  readonly history?: NickHistoryStore;
   /**
    * Structured-logger port. When omitted the actor runs
    * silently — observability is purely opt-in. When supplied, every
@@ -116,6 +151,15 @@ export interface ConnectionActorOptions {
    * still uniquely identifiable in logs.
    */
   readonly traceId?: string;
+  /**
+   * Line-framing seam (PLAN §9, ADR-009). Turns inbound transport input
+   * into complete IRC lines. Defaults to a {@link WsTextFrameTransport}
+   * (one message per WebSocket text frame, the serverless default). A raw
+   * TCP+TLS adapter injects a {@link TcpByteStreamTransport} for stateful
+   * `\r\n` byte-stream framing across chunks. The parser/reducer/dispatch
+   * pipeline is shared unchanged across both transports.
+   */
+  readonly transport?: Transport;
 }
 
 export class ConnectionActor {
@@ -127,7 +171,17 @@ export class ConnectionActor {
   private readonly ids: IdFactory;
   private readonly motd: MotdProvider;
   private readonly messages: MessageStore | undefined;
+  private readonly accounts: AccountStore | undefined;
+  private readonly mtlsIdentity: MtlsIdentityProvider | undefined;
+  private readonly history: NickHistoryStore | undefined;
   private readonly reducers: RoutedReducers;
+  /**
+   * Line-framing seam. Turns inbound input (a WS text frame or a raw TCP
+   * chunk) into complete IRC lines. Defaulted to a WS-frame transport for
+   * the serverless default; a TCP+TLS adapter injects the stateful
+   * byte-stream transport at construction.
+   */
+  private readonly transport: Transport;
   /**
    * Bound logger. Defaults to a no-op so the actor pipeline has no
    * observable side effects when callers do not opt in.
@@ -150,6 +204,9 @@ export class ConnectionActor {
     this.ids = opts.ids;
     this.motd = opts.motd ?? EmptyMotdProvider;
     this.messages = opts.messages;
+    this.accounts = opts.accounts;
+    this.mtlsIdentity = opts.mtlsIdentity;
+    this.history = opts.history;
     this.logger = opts.logger ?? NoopLoggerInstance;
     this.pinnedTraceId = opts.traceId;
     // Bind the connection id once so every record the actor emits carries
@@ -163,15 +220,19 @@ export class ConnectionActor {
     // reducer when flood control is disabled) so a flooding client is bounded
     // regardless of which authority owns the command's state.
     this.reducers = buildRoutedReducers(opts.serverConfig);
+    this.transport = opts.transport ?? new WsTextFrameTransport();
   }
 
   /**
-   * Processes one WebSocket text frame. Splits on `\r\n` (tolerating bare
-   * `\n`) and dispatches each non-empty line in order. A parse failure on
-   * one line emits a `421` and processing continues with the next line.
+   * Transport-agnostic entry point: feeds `chunk` through the bound
+   * {@link Transport} and dispatches each complete, non-empty line in order.
+   * A WS adapter passes one text frame per call; a raw TCP+TLS adapter
+   * passes one arbitrary byte chunk per call and the transport buffers any
+   * partial trailing line across calls. A parse failure on one line emits a
+   * `421` and processing continues with the next line.
    */
-  async receiveTextFrame(text: string): Promise<void> {
-    const lines = splitFrameLines(text);
+  async receive(chunk: string): Promise<void> {
+    const lines = this.transport.feed(chunk);
     if (lines.length === 0) return;
     const traceId = this.pinnedTraceId ?? this.ids.traceId();
     const log = this.logger.child({ traceId });
@@ -181,6 +242,17 @@ export class ConnectionActor {
     }
   }
 
+  /**
+   * Processes one WebSocket text frame. Equivalent to {@link receive} — kept
+   * as the named entry point every WS adapter already calls. Splits on
+   * `\r\n` (tolerating bare `\n`) via the default WS-frame transport and
+   * dispatches each non-empty line in order. A parse failure on one line
+   * emits a `421` and processing continues with the next line.
+   */
+  async receiveTextFrame(text: string): Promise<void> {
+    await this.receive(text);
+  }
+
   private async processLine(line: string, log: Logger, traceId: string): Promise<void> {
     let msg: IrcMessage;
     let parseFailed = false;
@@ -242,6 +314,9 @@ export class ConnectionActor {
       motd: this.motd,
       connection: this.state,
       ...(this.messages !== undefined ? { messages: this.messages } : {}),
+      ...(this.accounts !== undefined ? { accounts: this.accounts } : {}),
+      ...(this.mtlsIdentity !== undefined ? { mtlsIdentity: this.mtlsIdentity } : {}),
+      ...(this.history !== undefined ? { history: this.history } : {}),
     });
 
     switch (msg.command) {
@@ -260,6 +335,8 @@ export class ConnectionActor {
         return this.reducers.quit(this.state, msg, ctx).effects;
       case 'MOTD':
         return this.reducers.motd(this.state, msg, ctx).effects;
+      case 'OPER':
+        return this.reducers.oper(this.state, msg, ctx).effects;
       case 'CAP':
         return this.reducers.cap(this.state, msg, ctx).effects;
       case 'AUTHENTICATE':
@@ -267,6 +344,20 @@ export class ConnectionActor {
       case 'AWAY':
         return this.reducers.away(this.state, msg, ctx).effects;
 
+      // -------- Server-info query commands --------
+      case 'VERSION':
+        return this.reducers.version(this.state, msg, ctx).effects;
+      case 'TIME':
+        return this.reducers.time(this.state, msg, ctx).effects;
+      case 'ADMIN':
+        return this.reducers.admin(this.state, msg, ctx).effects;
+      case 'INFO':
+        return this.reducers.info(this.state, msg, ctx).effects;
+      case 'USERHOST':
+        return this.routeUserhost(msg, ctx);
+      case 'ISON':
+        return this.routeIson(msg, ctx);
+
       // -------- Channel-authority commands --------
       case 'JOIN':
         return this.routeJoin(msg, ctx);
@@ -289,6 +380,8 @@ export class ConnectionActor {
         return this.routeWho(msg, ctx);
       case 'WHOIS':
         return this.routeWhois(msg, ctx);
+      case 'WHOWAS':
+        return this.routeWhowas(msg, ctx);
       case 'CHATHISTORY':
         return this.routeChathistory(msg, ctx);
 
@@ -307,6 +400,13 @@ export class ConnectionActor {
           this.reducers.noticeUser,
           ctx,
         );
+      case 'TAGMSG':
+        return this.routeMessageTarget(
+          msg,
+          this.reducers.tagmsgChannel,
+          this.reducers.tagmsgUser,
+          ctx,
+        );
       case 'MODE':
         return isChannelTarget(msg.params[0] ?? '')
           ? this.routeSingleChannel(
@@ -316,6 +416,16 @@ export class ConnectionActor {
           : this.reducers.userMode(this.state, msg, ctx).effects;
 
       default:
+        // Remaining standard IRC verbs not yet implemented. They fall through
+        // to a graceful `421 ERR_UNKNOWNCOMMAND`. Triage of remaining verbs:
+        //   - Deferred (serverless-incompatible / S2S / needs new infra):
+        //     LUSERS (needs cross-adapter getStats), KILL (oper disconnect),
+        //     REHASH (no runtime config reload), CONNECT/SQUIT (S2S, PLAN
+        //     non-goal), TRACE (complex routing info), STATS (stats backend),
+        //     WALLOPS (oper broadcast mechanism), SETNAME (CHGHOST plumbing),
+        //     LINKS (S2S server list).
+        //   - Obsolete (RFC 2812, never widely implemented): SERVICE, SUMMON,
+        //     USERS.
         return [this.unknownCommandEffect(msg.command)];
     }
   }
@@ -364,6 +474,72 @@ export class ConnectionActor {
     return whoisReducer(target, channels, msg, ctx).effects;
   }
 
+  /**
+   * Routes `WHOWAS <nick>{,<nick>} [<count>]` to the whowas reducer. The
+   * command is query-only: it reads the bound nick-history store
+   * (`this.history`, absent when no store is wired) and emits
+   * `314`/`369`/`406` numerics. No runtime lookups are needed — the store
+   * is synchronous and self-contained.
+   */
+  private async routeWhowas(
+    msg: IrcMessage,
+    ctx: ReturnType<typeof buildCtx>,
+  ): Promise<EffectType[]> {
+    return whowasReducer(this.history, msg, ctx).effects;
+  }
+
+  /**
+   * Routes `USERHOST <nick>{ <nick>}` to the userhost reducer. Resolves each
+   * requested nick via the nick registry + connection lookup, passing the
+   * resulting snapshots (or `null` for offline nicks) to the pure formatter.
+   * The number of queried nicks is capped at
+   * `serverConfig.maxTargetsPerCommand` by the reducer.
+   */
+  private async routeUserhost(
+    msg: IrcMessage,
+    ctx: ReturnType<typeof buildCtx>,
+  ): Promise<EffectType[]> {
+    const cap = ctx.serverConfig.maxTargetsPerCommand;
+    const nicks = msg.params.slice(0, cap);
+    const resolved = new Map<string, ConnSnapshot | null>();
+    for (const nick of nicks) {
+      if (nick.length === 0) continue;
+      const connId = await this.runtime.lookupNick(nick);
+      if (connId === null) {
+        resolved.set(nick, null);
+        continue;
+      }
+      const conn = await this.runtime.getConnection(connId);
+      resolved.set(nick, conn === null ? null : toSnapshot(conn));
+    }
+    return userhostReducer(resolved, msg, ctx).effects;
+  }
+
+  /**
+   * Routes `ISON <nick>{ <nick>}` to the ison reducer. Resolves each requested
+   * nick via the nick registry; for online nicks, fetches the connection to
+   * recover the registered (display) spelling. Passes a folded→display map to
+   * the pure formatter.
+   */
+  private async routeIson(
+    msg: IrcMessage,
+    ctx: ReturnType<typeof buildCtx>,
+  ): Promise<EffectType[]> {
+    const cap = ctx.serverConfig.maxTargetsPerCommand;
+    const nicks = msg.params.slice(0, cap);
+    const online = new Map<string, string>();
+    for (const nick of nicks) {
+      if (nick.length === 0) continue;
+      const connId = await this.runtime.lookupNick(nick);
+      if (connId === null) continue;
+      const conn = await this.runtime.getConnection(connId);
+      if (conn?.nick !== undefined) {
+        online.set(conn.nick.toLowerCase(), conn.nick);
+      }
+    }
+    return isonReducer(online, msg, ctx).effects;
+  }
+
   /**
    * Routes `CHATHISTORY <sub> <target> [<args>...]` to the chathistory
    * reducer. The command is query-only and must NOT create a channel as a
@@ -508,15 +684,6 @@ export class ConnectionActor {
   }
 }
 
-/**
- * Splits a WebSocket text frame into IRC lines. Tolerates `\r\n`, bare `\n`,
- * and missing trailing terminators. Returns each line bare (no CRLF).
- */
-export function splitFrameLines(text: string): string[] {
-  if (text.length === 0) return [];
-  return text.split(/\r?\n/u);
-}
-
 /** Returns the first whitespace-delimited token of `line`, or `''`. */
 function firstToken(line: string): string {
   const m = line.match(/^\S+/u);
@@ -557,6 +724,7 @@ function channelTargetsForMessage(msg: IrcMessage): ChanName[] {
     case 'MODE':
     case 'PRIVMSG':
     case 'NOTICE':
+    case 'TAGMSG':
       return splitCsv(msg.params[0] ?? '').filter(isChannelTarget) as ChanName[];
     case 'INVITE':
       // INVITE <nick> <channel> — the channel is the second param.

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

@@ -33,9 +33,6 @@ const handlers: { [K in Effect['tag']]: Handler<Extract<Effect, { tag: K }>> } =
   ChangeNick: (e, r) => r.changeNick(e.conn, e.oldNick, e.newNick).then(noop),
   ReleaseNick: (e, r) => r.releaseNick(e.nick),
   ApplyChannelDelta: (e, r) => r.applyChannelDelta(e.chan, e.delta),
-  LookupNick: (e, r) => r.lookupNick(e.nick).then(noop),
-  GetConnectionInfo: (e, r) => r.getConnectionInfo(e.conn).then(noop),
-  GetChannelSnapshot: (e, r) => r.getChannelSnapshot(e.chan).then(noop),
 };
 
 function noop(): void {}

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

@@ -3,11 +3,19 @@
  *
  * Orchestration layer: defines the {@link IrcRuntime} port, the {@link dispatch}
  * interpreter that runs an `Effect[]` against it, and the {@link ConnectionActor}
- * that turns a WebSocket text frame into reducer invocations + dispatch.
+ * that turns inbound transport input (a WebSocket text frame or a raw TCP byte
+ * chunk) into reducer invocations + dispatch via the transport-agnostic
+ * {@link Transport} framing seam.
  */
 export type { IrcRuntime } from './runtime.js';
 export { dispatch } from './dispatch.js';
-export { ConnectionActor, splitFrameLines } from './actor.js';
+export { ConnectionActor } from './actor.js';
 export type { ActorChannelAccess, ConnectionActorOptions } from './actor.js';
+export {
+  splitFrameLines,
+  WsTextFrameTransport,
+  TcpByteStreamTransport,
+} from './transport.js';
+export type { Transport } from './transport.js';
 export { buildRoutedReducers, resolveFloodControl } from './routing.js';
 export type { RoutedReducers } from './routing.js';

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

@@ -29,11 +29,13 @@ import {
   type FloodControlConfig,
   type Reducer,
   type ServerConfig,
+  adminReducer,
   authenticateReducer,
   awayReducer,
   capReducer,
   channelModeReducer,
   defaultCommandCost,
+  infoReducer,
   inviteReducer,
   joinReducer,
   kickReducer,
@@ -42,6 +44,7 @@ import {
   nickReducer,
   noticeChannelReducer,
   noticeUserReducer,
+  operReducer,
   partReducer,
   passReducer,
   pingReducer,
@@ -49,9 +52,13 @@ import {
   privmsgChannelReducer,
   privmsgUserReducer,
   quitReducer,
+  tagmsgChannelReducer,
+  tagmsgUserReducer,
+  timeReducer,
   topicReducer,
   userModeReducer,
   userReducer,
+  versionReducer,
   wrapWithFloodControl,
 } from '@serverless-ircd/irc-core';
 
@@ -69,9 +76,14 @@ export interface RoutedReducers {
   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>;
+  readonly version: Reducer<ConnectionState>;
+  readonly time: Reducer<ConnectionState>;
+  readonly admin: Reducer<ConnectionState>;
+  readonly info: Reducer<ConnectionState>;
   // Channel-authority reducers.
   readonly join: Reducer<ChannelState>;
   readonly part: Reducer<ChannelState>;
@@ -84,6 +96,8 @@ export interface RoutedReducers {
   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>;
 }
@@ -132,9 +146,14 @@ export function buildRoutedReducers(serverConfig: ServerConfig): RoutedReducers
     pass: wrap(passReducer),
     quit: wrap(quitReducer),
     motd: wrap(motdReducer),
+    oper: wrap(operReducer),
     cap: wrap(capReducer),
     authenticate: wrap(authenticateReducer),
     away: wrap(awayReducer),
+    version: wrap(versionReducer),
+    time: wrap(timeReducer),
+    admin: wrap(adminReducer),
+    info: wrap(infoReducer),
     join: wrap(joinReducer),
     part: wrap(partReducer),
     topic: wrap(topicReducer),
@@ -145,6 +164,8 @@ export function buildRoutedReducers(serverConfig: ServerConfig): RoutedReducers
     privmsgUser: wrap(privmsgUserReducer),
     noticeChannel: wrap(noticeChannelReducer),
     noticeUser: wrap(noticeUserReducer),
+    tagmsgChannel: wrap(tagmsgChannelReducer),
+    tagmsgUser: wrap(tagmsgUserReducer),
     channelMode: wrap(channelModeReducer),
     userMode: wrap(userModeReducer),
   };

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

@@ -0,0 +1,101 @@
+/**
+ * Transport seam: turns raw transport input into complete IRC lines.
+ *
+ * PLAN §9 (ADR-009) — the pure reducer core + `ConnectionActor` are shared
+ * across both the WebSocket (`wss`) and the raw TCP+TLS (`irc+tls :6697`)
+ * transports. The only transport-specific concern is line framing:
+ *   - A WebSocket text frame is a complete unit (one or N `\r\n`-joined
+ *     messages), so a trailing unterminated line is still emitted.
+ *   - A raw TCP byte stream arrives in arbitrary chunks, so a partial line
+ *     at a chunk boundary must be buffered until its `\r\n` terminator
+ *     arrives.
+ *
+ * Both transports emit complete lines (no terminators); the actor skips
+ * empty lines and parses each non-empty one through the shared
+ * parser/reducer/dispatch pipeline.
+ */
+
+/**
+ * The line-framing contract a {@link ConnectionActor} consumes. `feed`
+ * returns the complete IRC lines terminated within `chunk`; a stateful
+ * transport buffers any incomplete trailing line for the next call.
+ */
+export interface Transport {
+  feed(chunk: string): string[];
+}
+
+/**
+ * Splits a WebSocket text frame into IRC lines. Tolerates `\r\n`, bare `\n`,
+ * and a missing trailing terminator (a WS frame is a complete unit). Returns
+ * each line bare (no CRLF). This is the legacy-tolerant WS contract.
+ */
+export function splitFrameLines(text: string): string[] {
+  if (text.length === 0) return [];
+  return text.split(/\r?\n/u);
+}
+
+/**
+ * Stateless WS-frame transport: one {@link feed} call per inbound text frame.
+ * A frame may carry one message or N `\r\n`-joined messages; a trailing
+ * unterminated line is emitted because the frame itself is the unit of
+ * completeness. This is the default transport for the WebSocket adapters.
+ */
+export class WsTextFrameTransport implements Transport {
+  feed(chunk: string): string[] {
+    return splitFrameLines(chunk);
+  }
+}
+
+/**
+ * Stateful TCP byte-stream transport: reassembles `\r\n`- (or bare `\n`-)
+ * terminated lines across arbitrary chunks, buffering any partial trailing
+ * line until its terminator arrives. Used by the raw TCP+TLS adapter path
+ * (PLAN §9). One instance owns one connection's buffer for its lifetime.
+ *
+ * For long-lived TCP connections fronted by request/response compute (AWS
+ * NLB + Lambda) each client chunk arrives in a fresh Lambda
+ * invocation. The partial-line buffer must persist across those
+ * invocations. {@link getBuffer} / {@link restore} snapshot the in-flight
+ * bytes so the adapter can round-trip them through its data store
+ * (DynamoDB) between chunks.
+ */
+export class TcpByteStreamTransport implements Transport {
+  private buffer = '';
+
+  feed(chunk: string): string[] {
+    if (chunk.length === 0) return [];
+    this.buffer += chunk;
+    const lines: string[] = [];
+    let start = 0;
+    for (let i = 0; i < this.buffer.length; i++) {
+      if (this.buffer[i] === '\n') {
+        // A `\n` terminates a line. Strip a preceding `\r` so both `\r\n`
+        // and bare `\n` yield the same bare line.
+        const lineEnd = i > 0 && this.buffer[i - 1] === '\r' ? i - 1 : i;
+        lines.push(this.buffer.slice(start, lineEnd));
+        start = i + 1;
+      }
+    }
+    this.buffer = this.buffer.slice(start);
+    return lines;
+  }
+
+  /**
+   * Returns the partial-line bytes currently buffered (not yet terminated).
+   * Empty when every fed byte has been emitted as a complete line. The
+   * adapter persists this between compute invocations so a chunk split
+   * across two requests is reassembled correctly.
+   */
+  getBuffer(): string {
+    return this.buffer;
+  }
+
+  /**
+   * Replaces the internal buffer with `buffer`. Call before {@link feed}
+   * when restoring from a persisted snapshot. An empty (or omitted)
+   * `buffer` resets the transport to a fresh state.
+   */
+  restore(buffer: string): void {
+    this.buffer = buffer;
+  }
+}