serverless-ircd 0.3.0 → 0.5.0

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

@@ -17,6 +17,7 @@ import type {
   ConnectionState,
   Nick,
   RawLine,
+  ServerConfig,
 } from '@serverless-ircd/irc-core';
 
 export interface IrcRuntime {
@@ -35,6 +36,24 @@ export interface IrcRuntime {
     lines: RawLine[],
     notFoundLines?: RawLine[],
   ): Promise<void>;
+  /**
+   * Global cross-connection fanout for `WALLOPS`. Delivers `lines` to every
+   * live connection whose `+w` user mode is set, skipping `except` (the
+   * originator, so an oper never receives their own wallops). Unlike
+   * {@link broadcast} this is NOT channel-scoped — it reaches connections
+   * with no shared channel membership.
+   *
+   * Each adapter applies its own cost cap and enumeration strategy:
+   *   - in-memory: scans its connection map, filters `+w`.
+   *   - Cloudflare: walks the sharded registry to enumerate connIds, then
+   *     fetches each state to check `+w`. Capped to bound the fan-out RPC
+   *     count; document a ceiling for very large fleets.
+   *   - AWS: `Scan`s the `Connections` table and `PostToConnection`s each
+   *     `+w` row. DynamoDB `Scan` reads scale with table size, so this is
+   *     expensive at high connection counts — callers should bound the
+   *     oper's WALLOPS rate.
+   */
+  broadcastWallops(lines: RawLine[], except?: ConnId): Promise<void>;
 
   // nickname registry
   reserveNick(nick: Nick, conn: ConnId): Promise<{ ok: true } | { ok: false }>;
@@ -58,4 +77,16 @@ export interface IrcRuntime {
   getChannelSnapshot(chan: ChanName): Promise<ChanSnapshot | null>;
   getChannelConnections(chan: ChanName): Promise<ReadonlyMap<ConnId, ConnectionState>>;
   listChannels(): Promise<ChanSnapshot[]>;
+  /**
+   * Re-fetches the deployment's {@link ServerConfig} from the adapter's bound
+   * source (CF: KV/secret env; AWS: Secrets Manager/SSM env; local-cli: the
+   * config file/options) and returns the fresh value. The caller (the
+   * ConnectionActor's `REHASH` route) swaps its live config reference with
+   * the result; on rejection the previous config stays in effect.
+   *
+   * Modelled as a request/response runtime method — like `lookupNick` /
+   * `getConnection` — rather than a fire-and-forget `Effect`, because the
+   * refreshed value must come back to the actor.
+   */
+  reloadConfig(): Promise<ServerConfig>;
 }

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

@@ -0,0 +1,104 @@
+/**
+ * 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.
+ */
+
+import { splitFrameLines } from '@serverless-ircd/irc-core';
+
+export { splitFrameLines };
+
+/**
+ * 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. Re-exported from
+ * `@serverless-ircd/irc-core` (`ws-framing.ts`), which owns the canonical
+ * legacy-tolerant framing so the IRCv3 spec-mode framing and this legacy
+ * behaviour never diverge. 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.
+ */
+
+/**
+ * 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;
+  }
+}