serverless-ircd 0.4.0 → 0.5.0

package/packages/irc-core/src/ports.ts

@@ -7,6 +7,8 @@
  */
 
 import { caseFold } from './case-fold.js';
+import type { ChannelState } from './state/channel.js';
+import type { ConnId, ConnectionState } from './state/connection.js';
 
 /** Read-only wall clock, epoch milliseconds. */
 export interface Clock {
@@ -670,6 +672,183 @@ export class InMemoryNickHistoryStore implements NickHistoryStore {
   }
 }
 
+// ============================================================================
+// Network statistics (LUSERS / STATS)
+// ============================================================================
+
+/**
+ * Snapshot of network-wide counts returned by a {@link ServerStats} backend.
+ *
+ * The shape mirrors the fields the `LUSERS` and `STATS` reducers need to
+ * format their numerics:
+ *   - `users` / `invisible`: the split registered-user counts that drive
+ *     `251 RPL_LUSERCLIENT` ("There are X users and Y invisible on Z
+ *     servers"). `users` is the *visible* (non-`+i`) registered count;
+ *     `invisible` is the `+i` registered count. Total registered users
+ *     is `users + invisible`.
+ *   - `opers`: count of IRC operators; emitted as `252 RPL_LUSEROP` when
+ *     non-zero. An oper counts here regardless of `+i` (an `+o` oper who
+ *     is also `+i` still bumps `opers`, `invisible`, and `users` is
+ *     computed as visible = total-registered − invisible).
+ *   - `unknownConnections`: pre-registration connection count; emitted as
+ *     `253 RPL_LUSERUNKNOWN` when non-zero.
+ *   - `channels`: live channel count; emitted as `254 RPL_LUSERCHANNELS`
+ *     when non-zero.
+ *   - `servers`: server count seen by `251`/`255`. Always 1 for the
+ *     single-server serverless deployment; S2S aggregation is a PLAN
+ *     non-goal.
+ *   - `localConns` / `globalConns`: total connection counts (registered
+ *     + pre-registration) for the optional `265 RPL_LOCALUSERS` /
+ *     `266 RPL_GLOBALUSERS` numerics. Equal for a single-server network.
+ *   - `maxLocalConns` / `maxGlobalConns`: high-water marks accompanying
+ *     `265`/`266`. When the backend has no recorded max it reports the
+ *     current count (so the wire numeric never claims a max below live).
+ *   - `uptimeStartedAt`: epoch-ms the server (or stats backend) started
+ *     counting from. Drives the `STATS u` uptime line.
+ */
+export interface ServerStatsSnapshot {
+  users: number;
+  invisible: number;
+  opers: number;
+  unknownConnections: number;
+  channels: number;
+  servers: number;
+  localConns: number;
+  globalConns: number;
+  maxLocalConns: number;
+  maxGlobalConns: number;
+  uptimeStartedAt: number;
+}
+
+/**
+ * Port that aggregates network-wide statistics for `LUSERS` and `STATS`.
+ *
+ * Unlike the synchronous {@link MotdProvider} / {@link AccountStore} ports
+ * (which reducers consume directly via {@link Ctx}), this port is
+ * **asynchronous** (`Promise`-returning) because the aggregation crosses
+ * every connection and channel in the deployment — it cannot be pre-loaded
+ * into a synchronous view the way MOTD or a credential table can. The
+ * actor layer awaits {@link getStats} once per `LUSERS` / `STATS`
+ * invocation, then passes the resulting {@link ServerStatsSnapshot} to the
+ * pure reducers (`lusersReducer`, `statsReducer`). This mirrors the
+ * `listChannels` → `listReducer` pattern.
+ *
+ * Each adapter implements this against its authoritative store:
+ *   - in-memory runtime: derive from its `Map`s (reference impl
+ *     {@link InMemoryStats}).
+ *   - CF: aggregate via `listChannels` / connection-enumeration RPCs.
+ *   - AWS: `Scan` / `Count` queries against `Connections` / `ChannelMeta`.
+ */
+export interface ServerStats {
+  getStats(): Promise<ServerStatsSnapshot>;
+}
+
+/**
+ * Aggregates a snapshot from already-collected connection state and a
+ * channel count.
+ *
+ * Pure: backends that gather their data through async I/O (CF RPC fan-out,
+ * AWS DynamoDB `Scan`) call this once they have the raw inputs. The
+ * {@link InMemoryStats} reference backend delegates here so the
+ * classification logic (oper / invisible / unknown) lives in exactly one
+ * place and is unit-tested independently of any adapter's I/O.
+ *
+ * Counting rules (RFC 2812 §4.6.2 + modern practice):
+ *   - `users` is the **visible** registered count (total registered minus
+ *     `+i`); the first number in "There are X users and Y invisible".
+ *   - `invisible` is the `+i` registered count; the second number.
+ *   - An oper who is also `+i` increments `opers`, `invisible`, and
+ *     reduces `users` (because they are invisible) — matching charybdis.
+ *   - `localConns` is every tracked connection (registered + unknown).
+ */
+export function computeStatsSnapshot(
+  connections: Iterable<ConnectionState>,
+  channelCount: number,
+  uptimeStartedAt: number,
+  opts?: { maxLocalConns?: number; maxGlobalConns?: number; servers?: number },
+): ServerStatsSnapshot {
+  let registered = 0;
+  let invisible = 0;
+  let opers = 0;
+  let unknown = 0;
+  let total = 0;
+  for (const conn of connections) {
+    total++;
+    if (conn.registration !== 'registered') {
+      unknown++;
+      continue;
+    }
+    registered++;
+    if (conn.userModes.invisible) invisible++;
+    if (conn.userModes.oper) opers++;
+  }
+  return {
+    users: registered - invisible,
+    invisible,
+    opers,
+    unknownConnections: unknown,
+    channels: channelCount,
+    servers: opts?.servers ?? 1,
+    localConns: total,
+    globalConns: total,
+    // The wire numeric must never claim a max below the current live count;
+    // when the backend's recorded max is stale (or never seeded) the live
+    // count is the lower bound.
+    maxLocalConns: Math.max(opts?.maxLocalConns ?? 0, total),
+    maxGlobalConns: Math.max(opts?.maxGlobalConns ?? 0, total),
+    uptimeStartedAt,
+  };
+}
+
+/**
+ * Reference in-memory {@link ServerStats} backed by the live `Map`s the
+ * {@link InMemoryRuntime} (and tests) already maintain.
+ *
+ * The constructor takes *references* to the runtime's mutable maps; later
+ * mutations are visible on the next {@link getStats} call without
+ * re-binding. Used by the local CLI, by integration tests, and as the
+ * contract spec the CF / AWS backends mirror.
+ *
+ * `uptimeStartedAt` is supplied at construction (typically the runtime's
+ * boot time). `maxLocalConns` / `maxGlobalConns` are optional high-water
+ * marks; when omitted the live count is reported as the max so `265`/`266`
+ * never regress below the current connection total.
+ */
+export class InMemoryStats implements ServerStats {
+  private readonly connections: ReadonlyMap<ConnId, ConnectionState>;
+  private readonly channels: ReadonlyMap<string, ChannelState>;
+  private readonly uptimeStartedAt: number;
+  private readonly maxLocalConns: number | undefined;
+  private readonly maxGlobalConns: number | undefined;
+
+  constructor(opts: {
+    connections: ReadonlyMap<ConnId, ConnectionState>;
+    channels: ReadonlyMap<string, ChannelState>;
+    uptimeStartedAt: number;
+    clock?: Clock;
+    maxLocalConns?: number;
+    maxGlobalConns?: number;
+  }) {
+    this.connections = opts.connections;
+    this.channels = opts.channels;
+    this.uptimeStartedAt = opts.uptimeStartedAt;
+    this.maxLocalConns = opts.maxLocalConns;
+    this.maxGlobalConns = opts.maxGlobalConns;
+  }
+
+  async getStats(): Promise<ServerStatsSnapshot> {
+    return computeStatsSnapshot(
+      this.connections.values(),
+      this.channels.size,
+      this.uptimeStartedAt,
+      {
+        ...(this.maxLocalConns !== undefined ? { maxLocalConns: this.maxLocalConns } : {}),
+        ...(this.maxGlobalConns !== undefined ? { maxGlobalConns: this.maxGlobalConns } : {}),
+      },
+    );
+  }
+}
+
 // ============================================================================
 // Observability — structured logger
 // ============================================================================

package/packages/irc-core/src/protocol/numerics.ts

@@ -16,6 +16,36 @@ export const Numerics = {
   // Capability / stats admin / version
   RPL_ADMINME: 256,
 
+  // LUSERS (RFC 2812 §4.6.2). Network-wide user/channel/server counts.
+  // 251 is the human-readable summary; 252–254 are emitted only when their
+  // count is non-zero (per RFC). 255 is the local-server summary. 265/266
+  // carry the optional local/global max-connection context.
+  RPL_LUSERCLIENT: 251,
+  RPL_LUSEROP: 252,
+  RPL_LUSERUNKNOWN: 253,
+  RPL_LUSERCHANNELS: 254,
+  RPL_LUSERME: 255,
+  RPL_LOCALUSERS: 265,
+  RPL_GLOBALUSERS: 266,
+
+  // STATS (RFC 2812 §4.6.3 / §5.1). 211 is link-info (the `l` query),
+  // 242 is the uptime line (the `u` query), and 219 terminates every
+  // STATS reply regardless of query letter. The remaining RPL_STATS*
+  // codes (212–218, 240–248) are deferred behind per-letter tests.
+  RPL_STATSLINKINFO: 211,
+  RPL_ENDOFSTATS: 219,
+  RPL_STATSUPTIME: 242,
+
+  // TRACE (RFC 2812 §4.6.3). In a single-server deployment TRACE collapses
+  // to a local-server line (200/206) plus optional per-connection detail
+  // (204 oper / 205 user), terminated by 262. Multi-hop S2S tracing is a
+  // PLAN non-goal.
+  RPL_TRACELINK: 200,
+  RPL_TRACEOPERATOR: 204,
+  RPL_TRACEUSER: 205,
+  RPL_TRACESERVER: 206,
+  RPL_ENDOFTRACE: 262,
+
   // Away / userhost / ison
   RPL_AWAY: 301,
   RPL_USERHOST: 302,
@@ -61,10 +91,8 @@ export const Numerics = {
   RPL_NAMREPLY: 353,
   RPL_ENDOFNAMES: 366,
 
-  // Links / ban / whowas. RPL_LINKS/RPL_ENDOFLINKS retained for the deferred
-  // LINKS verb (S2S server list — PLAN non-goal; see actor default-route triage).
-  RPL_LINKS: 364,
-  RPL_ENDOFLINKS: 365,
+  // Ban / whowas. (The S2S `LINKS` verb and its `RPL_LINKS`/`RPL_ENDOFLINKS`
+  // numerics were dropped — S2S is a PLAN non-goal.)
   RPL_BANLIST: 367,
   RPL_ENDOFBANLIST: 368,
   RPL_ENDOFWHOWAS: 369,
@@ -76,11 +104,12 @@ export const Numerics = {
   RPL_MOTDSTART: 375,
   RPL_ENDOFMOTD: 376,
 
-  // Oper. RPL_REHASHING retained for the deferred REHASH verb (no runtime
-  // config-reload path in serverless; see actor default-route triage).
+  // Oper. RPL_REHASHING is emitted by the oper-gated `REHASH` reducer when a
+  // config reload is requested (the actor re-invokes the adapter's loader).
+  // (The RFC 2812 `SERVICE` verb and its `RPL_YOURESERVICE` numeric were
+  // dropped — obsolete, never widely implemented.)
   RPL_YOUREOPER: 381,
   RPL_REHASHING: 382,
-  RPL_YOURESERVICE: 383,
   RPL_TIME: 391,
 
   // SASL (IRCv3 sasl-3.2)
@@ -102,7 +131,8 @@ export const Numerics = {
   ERR_TOOMANYCHANNELS: 405,
   ERR_WASNOSUCHNICK: 406,
   ERR_TOOMANYTARGETS: 407,
-  ERR_NOSUCHSERVICE: 408, // retained: deferred SERVICE verb (RFC 2812 obsolete)
+  // `ERR_NOSUCHSERVICE` (408) was dropped with the obsolete RFC 2812 `SERVICE`
+  // verb.
   ERR_INVALIDCAPCMD: 410,
   ERR_NORECIPIENT: 411,
   ERR_NOTEXTTOSEND: 412,
@@ -121,8 +151,8 @@ export const Numerics = {
   ERR_NOTONCHANNEL: 442,
   ERR_USERONCHANNEL: 443,
   ERR_NOLOGIN: 444,
-  ERR_SUMMONDISABLED: 445, // retained: deferred SUMMON verb (RFC 2812 obsolete)
-  ERR_USERSDISABLED: 446, // retained: deferred USERS verb (RFC 2812 obsolete)
+  // `ERR_SUMMONDISABLED` (445) / `ERR_USERSDISABLED` (446) were dropped with
+  // the obsolete RFC 2812 `SUMMON`/`USERS` verbs.
   ERR_NOTREGISTERED: 451,
   ERR_NEEDMOREPARAMS: 461,
   ERR_ALREADYREGISTRED: 462,
@@ -140,7 +170,8 @@ export const Numerics = {
   ERR_BANLISTFULL: 478,
   ERR_NOPRIVILEGES: 481,
   ERR_CHANOPRIVSNEEDED: 482,
-  ERR_CANTKILLSERVER: 483, // retained: deferred SQUIT verb (S2S, PLAN non-goal)
+  // `ERR_CANTKILLSERVER` (483) was dropped with the S2S `SQUIT` verb — S2S is
+  // a PLAN non-goal.
   ERR_NOOPERHOST: 491,
   ERR_UMODEUNKNOWNFLAG: 501,
   ERR_USERSDONTMATCH: 502,

package/packages/irc-core/src/protocol/outbound.ts

@@ -16,6 +16,7 @@
  */
 
 import type { RawLine } from '../effects.js';
+import { MAX_WS_MESSAGE_BYTES, type WsFrameMode } from '../ws-framing.js';
 
 /**
  * RFC 1459 §2.3: maximum IRC line length in bytes, including the trailing
@@ -65,7 +66,7 @@ export function applyServerTime(line: RawLine, caps: ReadonlySet<string>, now: n
 }
 
 /**
- * Enforces the IRC 512-byte line limit on `line.text`.
+ * Enforces the IRC line-length budget on `line.text`.
  *
  * For recipients that negotiated `message-tags`, the tag section (the
  * leading `@... ` prefix) is part of the wire budget and is preserved
@@ -73,11 +74,22 @@ export function applyServerTime(line: RawLine, caps: ReadonlySet<string>, now: n
  * For legacy recipients the entire `line.text` is the body and may be
  * truncated from the right.
  *
+ * The optional `mode` selects which byte budget applies: an IRCv3
+ * WebSocket spec mode (`spec-text` / `spec-binary`) caps the message at
+ * {@link MAX_WS_MESSAGE_BYTES} (510) directly, because WebSocket messages
+ * carry no trailing CR-LF; legacy mode (the default) caps at
+ * `MAX_LINE_BYTES - 2` (512 − 2 = 510). Both resolve to 510 today, but the
+ * mode-aware call sites need no edits if either constant ever changes.
+ *
  * The returned {@link RawLine} is the original object when no truncation
  * was needed, otherwise a fresh object with the truncated text.
  */
-export function enforceLineLimit(line: RawLine, caps: ReadonlySet<string>): RawLine {
-  const budget = MAX_LINE_BYTES - TRAILING_CRLF_LEN;
+export function enforceLineLimit(
+  line: RawLine,
+  caps: ReadonlySet<string>,
+  mode?: WsFrameMode,
+): RawLine {
+  const budget = isSpecMode(mode) ? MAX_WS_MESSAGE_BYTES : MAX_LINE_BYTES - TRAILING_CRLF_LEN;
   if (line.text.length <= budget) return line;
 
   const hasTags = caps.has('message-tags') && line.text.startsWith('@');
@@ -143,3 +155,8 @@ function clientTagKey(entry: string): string {
   const eq = entry.indexOf('=');
   return eq === -1 ? entry : entry.slice(0, eq);
 }
+
+/** True when `mode` is an IRCv3 WebSocket spec framing mode (not legacy/absent). */
+function isSpecMode(mode: WsFrameMode | undefined): boolean {
+  return mode === 'spec-text' || mode === 'spec-binary';
+}

package/packages/irc-core/src/types.ts

@@ -48,7 +48,7 @@ export interface OperCred {
  * Per-deployment server configuration. Adapters load this from a KV store
  * (CF) or Secrets Manager / SSM (AWS); the core only reads it.
  *
- * This is the minimum the Phase 1 reducers need; later tickets (SASL,
+ * This is the minimum the Phase 1 reducers need; later phases (SASL,
  * MOTD provider, channel-prefix policy) extend it.
  */
 export interface ServerConfig {
@@ -101,6 +101,13 @@ export interface ServerConfig {
   nickLen: number;
   channelLen: number;
   topicLen: number;
+  /**
+   * Maximum realname (GECOS) length enforced by `SETNAME`. Optional because
+   * registration-time `USER` does not enforce a cap; the parsed config always
+   * supplies a value (schema default), but inline `ServerConfig` literals in
+   * tests may omit it — `SETNAME` then falls back to its built-in default.
+   */
+  readonly realnameLen?: number | undefined;
   quitMessage: string;
   /**
    * Per-connection message-rate flood control. `undefined` → the actor

package/packages/irc-core/src/ws-framing.ts

@@ -0,0 +1,132 @@
+/**
+ * WebSocket IRC-message framing and the IRCv3 510-byte message budget.
+ *
+ * The IRCv3 WebSocket spec
+ * (https://ircv3.net/specs/websockets.html) changes two things about how a
+ * WebSocket text/binary message maps to an IRC message, relative to the
+ * legacy framing a raw-TCP-tolerant adapter uses:
+ *
+ *   1. **One IRC message per WebSocket message.** A frame never carries
+ *      several `\r\n`-joined messages, so framing MUST NOT split on an
+ *      embedded line break. A single optional trailing CR-LF (or bare LF)
+ *      is stripped and the remainder is treated as exactly one IRC line.
+ *
+ *   2. **No trailing CR-LF on the wire.** The 512-byte IRC line limit
+ *      therefore applies to the message content only, giving a hard cap of
+ *      {@link MAX_WS_MESSAGE_BYTES} (510) bytes per WebSocket message.
+ *
+ * The legacy framing (`WsFrameMode === 'legacy'`) preserves the original
+ * adapter behaviour: split the whole frame on `/\r?\n/` so older clients
+ * that concatenate messages into one frame keep working. That is the same
+ * `splitFrameLines` logic the transport layer shipped before subprotocol
+ * negotiation existed.
+ *
+ * Everything here is pure and platform-agnostic so it runs unchanged on
+ * every WebSocket runtime (Node `ws`, Cloudflare Durable Objects, Lambda).
+ */
+
+import type { WsSubprotocol } from './ws-subprotocol.js';
+
+/**
+ * How a WebSocket message is framed into IRC lines.
+ *
+ *   - `spec-text`   — `text.ircv3.net`: one IRC message per frame, trailing
+ *                     CR-LF stripped, never split.
+ *   - `spec-binary` — `binary.ircv3.net`: same framing as `spec-text`.
+ *   - `legacy`      — no IRCv3 subprotocol negotiated: split the frame on
+ *                     `/\r?\n/` (the original adapter behaviour).
+ */
+export type WsFrameMode = 'spec-text' | 'spec-binary' | 'legacy';
+
+/**
+ * Maximum number of bytes allowed in a single IRCv3 WebSocket message.
+ *
+ * The IRC line limit is 512 bytes *including* the trailing CR-LF. WebSocket
+ * messages omit the trailing CR-LF, so the content budget is `512 - 2 = 510`.
+ * Inbound messages exceeding this MUST be rejected.
+ */
+export const MAX_WS_MESSAGE_BYTES = 510;
+
+/**
+ * Maps a negotiated IRCv3 subprotocol onto the matching {@link WsFrameMode}.
+ * `undefined` (no subprotocol) maps to the legacy-tolerant framing.
+ */
+export function wsFrameModeFor(subproto: WsSubprotocol | undefined): WsFrameMode {
+  if (subproto === 'text.ircv3.net') return 'spec-text';
+  if (subproto === 'binary.ircv3.net') return 'spec-binary';
+  return 'legacy';
+}
+
+/**
+ * Strips a single trailing `\r\n` (or bare `\n`) from `s`. Leaves every
+ * other character — including leading or embedded terminators — untouched.
+ * Used by the spec-mode framing to yield one bare IRC line per frame.
+ */
+export function stripTrailingCrLf(s: string): string {
+  if (s.endsWith('\r\n')) return s.slice(0, -2);
+  if (s.endsWith('\n')) return s.slice(0, -1);
+  return s;
+}
+
+/**
+ * Splits a WebSocket text frame into IRC lines using the legacy-tolerant
+ * contract: split the whole frame on `/\r?\n/`, returning every part
+ * (including a possible trailing empty string). The empty frame yields no
+ * lines.
+ *
+ * This is the exact behaviour the transport layer shipped before IRCv3
+ * subprotocol negotiation; spec-mode framing ({@link frameToLines}) does
+ * NOT use it.
+ */
+export function splitFrameLines(text: string): string[] {
+  if (text.length === 0) return [];
+  return text.split(/\r?\n/u);
+}
+
+/**
+ * Frames `frame` into IRC lines according to `mode`.
+ *
+ *   - `spec-text` / `spec-binary`: one IRC message per frame. A single
+ *     trailing CR-LF (or bare LF) is stripped and the remainder is returned
+ *     as the sole element. The frame is never split on an embedded line
+ *     break. An empty frame (or a frame that is only a terminator) yields
+ *     no lines.
+ *   - `legacy`: delegates to {@link splitFrameLines} (split on `/\r?\n/`).
+ */
+export function frameToLines(frame: string, mode: WsFrameMode): string[] {
+  if (mode === 'legacy') return splitFrameLines(frame);
+  const line = stripTrailingCrLf(frame);
+  if (line.length === 0) return [];
+  return [line];
+}
+
+/**
+ * Returns `true` when `frame` fits within the IRCv3 WebSocket 510-byte
+ * message budget, `false` when it exceeds it and MUST be rejected by the
+ * inbound path. Measured in UTF-16 code units, consistent with how
+ * {@link enforceLineLimit} and the input parser cap line length across this
+ * package (every supported runtime exposes `.length`).
+ */
+export function isWithinWsByteBudget(frame: string): boolean {
+  return frame.length <= MAX_WS_MESSAGE_BYTES;
+}
+
+/**
+ * Replaces every unpaired UTF-16 surrogate in `str` with U+FFFD (the
+ * Unicode replacement character).
+ *
+ * `text.ircv3.net` frames are UTF-8 text. A lone surrogate (half of a
+ * surrogate pair) has no valid UTF-8 encoding, so per the Unicode
+ * recommendation it is substituted with U+FFFD before the frame is handed
+ * to the parser. Valid surrogate pairs (supplementary-plane code points)
+ * are preserved unchanged, as is all BMP text.
+ */
+export function sanitizeForTextMode(str: string): string {
+  // A lone high surrogate (0xD800–0xDBFF) NOT followed by a low surrogate,
+  // and a lone low surrogate (0xDC00–0xDFFF) NOT preceded by a high
+  // surrogate. Both are replaced with U+FFFD.
+  return str.replace(
+    /(?:[\uD800-\uDBFF](?![\uDC00-\uDFFF]))|(?:(?<![\uD800-\uDBFF])[\uDC00-\uDFFF])/gu,
+    '\uFFFD',
+  );
+}

package/packages/irc-core/src/ws-subprotocol.ts

@@ -0,0 +1,66 @@
+/**
+ * WebSocket subprotocol negotiation for IRC connections (IRCv3).
+ *
+ * The IRCv3 WebSocket specification defines two subprotocols a client may
+ * offer in its opening handshake via the `Sec-WebSocket-Protocol` header:
+ *
+ *   - `text.ircv3.net`   — UTF-8 text frames, one IRC message per WebSocket
+ *                          message, no trailing CR-LF.
+ *   - `binary.ircv3.net` — binary frames, one IRC message per WebSocket
+ *                          message, no trailing CR-LF.
+ *
+ * The header is a comma-separated list offered in client-preference order.
+ * These pure helpers parse the header and select the single subprotocol the
+ * server should agree to (the first supported entry, honouring the client's
+ * preference). They are dependency-free so they run unchanged on every
+ * runtime (Node, Workers, Lambda).
+ */
+
+/** The IRCv3 binary WebSocket subprotocol. */
+export const WS_SUBPROTO_BINARY = 'binary.ircv3.net';
+
+/** The IRCv3 text WebSocket subprotocol. */
+export const WS_SUBPROTO_TEXT = 'text.ircv3.net';
+
+/** A supported IRCv3 WebSocket subprotocol name. */
+export type WsSubprotocol = typeof WS_SUBPROTO_TEXT | typeof WS_SUBPROTO_BINARY;
+
+/**
+ * Parses the `Sec-WebSocket-Protocol` header value into an ordered list of
+ * offered protocols (client-preference order). Whitespace around each item is
+ * trimmed and empty entries (stray/leading/trailing commas) are dropped.
+ * Duplicate entries are preserved in their original order.
+ *
+ * `null`, `undefined`, or an empty string yield an empty array.
+ *
+ * @param header The raw `Sec-WebSocket-Protocol` header value, if present.
+ */
+export function parseSecWsProtocolOffers(header: string | null | undefined): string[] {
+  if (header === null || header === undefined || header === '') {
+    return [];
+  }
+  const offers: string[] = [];
+  for (const raw of header.split(',')) {
+    const item = raw.trim();
+    if (item !== '') {
+      offers.push(item);
+    }
+  }
+  return offers;
+}
+
+/**
+ * Selects the supported subprotocol to agree to from a list of client offers
+ * (in client-preference order). Returns the first offer that matches a
+ * supported subprotocol, or `null` when none match.
+ *
+ * @param offers The ordered list of offered protocols.
+ */
+export function selectSubprotocol(offers: readonly string[]): WsSubprotocol | null {
+  for (const offer of offers) {
+    if (offer === WS_SUBPROTO_TEXT || offer === WS_SUBPROTO_BINARY) {
+      return offer as WsSubprotocol;
+    }
+  }
+  return null;
+}

package/packages/irc-core/tests/admission.test.ts

@@ -211,6 +211,24 @@ describe('AdmissionStats — release', () => {
     const stats = makeStats(clock);
     expect(() => stats.release('unknown')).not.toThrow();
   });
+
+  it('deletes the per-IP and per-user keys when the last admission is released', () => {
+    // Covers the `next <= 0` delete branch in `release`: a single recorded
+    // admission, when released, must clear the keys entirely rather than
+    // leaving a zero entry in the maps.
+    const clock = new FakeClock(1_000);
+    const stats = makeStats(clock);
+    const d = decideAdmission('5.6.7.8', 'carol', stats, BASE_CONFIG);
+    if (!d.ok) throw new Error('precondition: d should admit');
+    stats.recordAdmission('5.6.7.8', 'carol', d.recordId);
+
+    stats.release(d.recordId);
+
+    // A fresh admission from the same IP/user must be allowed (counts are
+    // back to zero because the keys were deleted, not just decremented).
+    const after = decideAdmission('5.6.7.8', 'carol', stats, BASE_CONFIG);
+    expect(after.ok).toBe(true);
+  });
 });
 
 describe('AdmissionStats — determinism', () => {