serverless-ircd 0.1.0

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

@@ -0,0 +1,175 @@
+import type { IrcMessage, IrcSource } from './messages.js';
+
+/**
+ * Error thrown when a wire line cannot be parsed as an IRC message.
+ * The actor layer treats these as a protocol violation (and typically drops
+ * or 421s the offending input) rather than crashing.
+ */
+export class IrcParseError extends Error {
+  constructor(
+    message: string,
+    /** The original input that failed to parse, for diagnostics. */
+    readonly input: string,
+  ) {
+    super(message);
+    this.name = 'IrcParseError';
+  }
+}
+
+const TAG_ESCAPES: Readonly<Record<string, string>> = {
+  ':': ';',
+  s: ' ',
+  '\\': '\\',
+  r: '\r',
+  n: '\n',
+};
+
+/**
+ * Reverses {@link escapeTagValue} per the IRCv3 Message Tags spec. A `\`
+ * followed by one of the escape codes (`:`, `s`, `\`, `r`, `n`) yields the
+ * corresponding raw character; `\` followed by any other character drops
+ * the backslash (per spec: unknown escapes resolve to the literal char).
+ */
+export function unescapeTagValue(value: string): string {
+  let out = '';
+  for (let i = 0; i < value.length; i++) {
+    const ch = value.charAt(i);
+    if (ch === '\\' && i + 1 < value.length) {
+      const next = value.charAt(i + 1);
+      out += TAG_ESCAPES[next] ?? next;
+      i++;
+    } else {
+      out += ch;
+    }
+  }
+  return out;
+}
+
+function parseTags(section: string): Record<string, string> {
+  const tags: Record<string, string> = {};
+  for (const entry of section.split(';')) {
+    if (entry === '') continue;
+    const eq = entry.indexOf('=');
+    if (eq === -1) {
+      tags[entry] = '';
+    } else {
+      tags[entry.slice(0, eq)] = unescapeTagValue(entry.slice(eq + 1));
+    }
+  }
+  return tags;
+}
+
+function parseSource(raw: string): IrcSource {
+  // Grammar: servername | nick ['!' user] ['@' host]
+  // '!' and '@' are independent, so split host (trailing) first, then user.
+  let beforeHost = raw;
+  let host: string | undefined;
+  const at = raw.lastIndexOf('@');
+  if (at !== -1) {
+    host = raw.slice(at + 1);
+    beforeHost = raw.slice(0, at);
+  }
+
+  let name = beforeHost;
+  let user: string | undefined;
+  const bang = beforeHost.indexOf('!');
+  if (bang !== -1) {
+    name = beforeHost.slice(0, bang);
+    user = beforeHost.slice(bang + 1);
+  }
+
+  const source: IrcSource = { name };
+  if (user !== undefined) source.user = user;
+  if (host !== undefined) source.host = host;
+  return source;
+}
+
+const COMMAND_RE = /^(?:[A-Za-z]+|[0-9]{3})$/;
+
+/**
+ * Parses one IRC message from a single line (with or without a trailing
+ * CR/LF). Throws {@link IrcParseError} on malformed input.
+ *
+ * Lenient where real-world clients are: tolerates missing CR/LF and collapses
+ * accidental runs of spaces between tokens. Strict where the grammar is: a
+ * command token is required and must be all-letters or exactly three digits.
+ */
+export function parse(line: string): IrcMessage {
+  // Strip any trailing CR/LF (frame tolerance for ws text frames or TCP lines).
+  const stripped = line.replace(/[\r\n]+$/u, '');
+  let rest = stripped;
+  if (rest.length === 0) {
+    throw new IrcParseError('empty message', line);
+  }
+
+  let tags: Record<string, string> = {};
+  if (rest.startsWith('@')) {
+    const space = rest.indexOf(' ');
+    if (space === -1) {
+      throw new IrcParseError('tag section with no message body', line);
+    }
+    tags = parseTags(rest.slice(1, space));
+    rest = rest.slice(space + 1).trimStart();
+  }
+
+  let source: IrcSource | undefined;
+  if (rest.startsWith(':')) {
+    const space = rest.indexOf(' ');
+    if (space === -1) {
+      throw new IrcParseError('source prefix with no command', line);
+    }
+    source = parseSource(rest.slice(1, space));
+    rest = rest.slice(space + 1).trimStart();
+  }
+
+  if (rest.length === 0) {
+    throw new IrcParseError('missing command', line);
+  }
+
+  // Split command from the parameter remainder.
+  const firstSpace = rest.indexOf(' ');
+  let command: string;
+  let remainder: string;
+  if (firstSpace === -1) {
+    command = rest;
+    remainder = '';
+  } else {
+    command = rest.slice(0, firstSpace);
+    remainder = rest.slice(firstSpace + 1);
+  }
+
+  command = command.toUpperCase();
+  if (!COMMAND_RE.test(command)) {
+    throw new IrcParseError(`invalid command token: ${command}`, line);
+  }
+
+  const params = parseParams(remainder);
+
+  const message: IrcMessage = { tags, command, params };
+  if (source !== undefined) message.source = source;
+  return message;
+}
+
+function parseParams(remainder: string): string[] {
+  if (remainder.length === 0) return [];
+
+  let middle: string;
+  let trailing: string | undefined;
+
+  if (remainder.startsWith(':')) {
+    // The whole remainder is a trailing param.
+    middle = '';
+    trailing = remainder.slice(1);
+  } else {
+    const trailingMarker = remainder.indexOf(' :');
+    if (trailingMarker === -1) {
+      middle = remainder;
+    } else {
+      middle = remainder.slice(0, trailingMarker);
+      trailing = remainder.slice(trailingMarker + 2);
+    }
+  }
+
+  const middles = middle.length === 0 ? [] : middle.split(' ').filter((p) => p.length > 0);
+  return trailing === undefined ? middles : [...middles, trailing];
+}

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

@@ -0,0 +1,71 @@
+import type { IrcMessage, IrcSource } from './messages.js';
+
+/**
+ * Escapes a raw tag value per the IRCv3 Message Tags spec so it can appear
+ * inside an `@...` tag section without containing literal `;`, space, `\`,
+ * CR or LF (all of which are structural or forbidden in the wire format).
+ *
+ * Escape table (the reverse of {@link unescapeTagValue}):
+ *   `;` → `\:`   ` ` → `\s`   `\` → `\\`   CR → `\r`   LF → `\n`
+ *
+ * Because `\` is doubled first, the mapping is a bijection and
+ * `unescapeTagValue(escapeTagValue(s)) === s` for every string.
+ */
+export function escapeTagValue(value: string): string {
+  return value
+    .replace(/\\/g, '\\\\')
+    .replace(/;/g, '\\:')
+    .replace(/ /g, '\\s')
+    .replace(/\r/g, '\\r')
+    .replace(/\n/g, '\\n');
+}
+
+function formatSource(source: IrcSource): string {
+  let out = source.name;
+  if (source.user !== undefined) out = `${out}!${source.user}`;
+  if (source.host !== undefined) out = `${out}@${source.host}`;
+  return out;
+}
+
+/**
+ * Serializes a message to its canonical wire form WITHOUT a trailing CR/LF.
+ * Use {@link serializeFrame} when the transport expects CRLF framing.
+ *
+ * The last parameter is ALWAYS emitted in trailing (`:`) form. This matches
+ * the de-facto IRC server convention (replies and message bodies always carry
+ * the colon) and parses correctly on every conformant client.
+ */
+export function serialize(message: IrcMessage): string {
+  const lead: string[] = [];
+
+  const tagEntries = Object.entries(message.tags);
+  if (tagEntries.length > 0) {
+    const tagSection = tagEntries
+      .map(([key, value]) => (value === '' ? key : `${key}=${escapeTagValue(value)}`))
+      .join(';');
+    lead.push(`@${tagSection}`);
+  }
+
+  if (message.source !== undefined) {
+    lead.push(`:${formatSource(message.source)}`);
+  }
+
+  lead.push(message.command);
+
+  const { params } = message;
+  if (params.length === 0) {
+    return lead.join(' ');
+  }
+
+  const lastIndex = params.length - 1;
+  let out = lead.join(' ');
+  for (const [i, param] of params.entries()) {
+    out += i === lastIndex ? ` :${param}` : ` ${param}`;
+  }
+  return out;
+}
+
+/** Serializes a message and appends the canonical IRC CR/LF frame terminator. */
+export function serializeFrame(message: IrcMessage): string {
+  return `${serialize(message)}\r\n`;
+}

package/packages/irc-core/src/state/channel.ts

@@ -0,0 +1,293 @@
+/**
+ * Channel-level state shapes.
+ *
+ * The Channel entity is the authority for the roster, channel modes, topic,
+ * and ban masks. `ChannelDelta` is the value type emitted by reducers and
+ * applied by the runtime — it is how a Connection entity mutates Channel
+ * state without owning it (PLAN §2.1 location-of-authority).
+ */
+
+import type { ConnId, Nick } from './connection.js';
+
+/** Channel name with original case preserved. */
+export type ChanName = string;
+
+/** Per-connection membership within a channel. */
+export interface RosterEntry {
+  conn: ConnId;
+  nick: Nick;
+  op: boolean;
+  voice: boolean;
+}
+
+/** Read-only roster: connection id -> entry. */
+export type Roster = ReadonlyMap<ConnId, RosterEntry>;
+
+/** Topic record (text + setter + epoch ms). */
+export interface ChannelTopic {
+  text: string;
+  setter: string;
+  setAt: number;
+}
+
+/**
+ * Channel-mode flags. Boolean modes are always present. The two
+ * parameterized modes — `k` (key) and `l` (limit) — are optional and use
+ * `undefined` to signal "unset", exactly matching how `MODE` deltas encode
+ * clearing them.
+ */
+export interface ChannelModes {
+  // boolean modes
+  inviteOnly: boolean; // i
+  topicLock: boolean; // t
+  noExternal: boolean; // n
+  moderated: boolean; // m
+  secret: boolean; // s
+  private: boolean; // p
+  // parameterized modes
+  key?: string; // k
+  limit?: number; // l
+}
+
+/** Boolean mode letters we know how to toggle. */
+export type BooleanChannelMode =
+  | 'inviteOnly'
+  | 'topicLock'
+  | 'noExternal'
+  | 'moderated'
+  | 'secret'
+  | 'private';
+
+/** Parameterized mode letters we know how to set/clear. */
+export type ParameterChannelMode = 'key' | 'limit';
+
+/** Any toggleable channel mode name. */
+export type ChannelModeName = BooleanChannelMode | ParameterChannelMode;
+
+/** One mode toggle inside a {@link ChannelDelta}. */
+export interface ModeChange {
+  mode: ChannelModeName;
+  set: boolean;
+  /** Required for `key` (string) and `limit` (number) on set. */
+  arg?: string | number;
+}
+
+/** One roster mutation inside a {@link ChannelDelta}. */
+export interface MembershipDelta {
+  type: 'add' | 'remove';
+  conn: ConnId;
+  /** Required on `add`; ignored on `remove`. */
+  nick?: Nick;
+  op?: boolean;
+  voice?: boolean;
+}
+
+/** One ban-mask mutation inside a {@link ChannelDelta}. */
+export interface BanMaskChange {
+  type: 'add' | 'remove';
+  mask: string;
+}
+
+/**
+ * A batch of mutations to apply atomically to a channel. Every field is
+ * optional; absent fields mean "no change to that aspect".
+ *
+ * `topic: null` clears the topic; an absent `topic` field leaves it alone.
+ */
+export interface ChannelDelta {
+  memberships?: MembershipDelta[];
+  modeChanges?: ModeChange[];
+  banMaskChanges?: BanMaskChange[];
+  /** `null` clears the topic; a {@link ChannelTopic} replaces it. */
+  topic?: ChannelTopic | null;
+}
+
+/** Mutable authoritative channel state. */
+export interface ChannelState {
+  name: ChanName;
+  nameLower: string;
+  modes: ChannelModes;
+  banMasks: Set<string>;
+  topic?: ChannelTopic;
+  members: Map<ConnId, RosterEntry>;
+  /**
+   * Lowercased nicks with a standing invite (created by `INVITE`). A later
+   * `JOIN` by that nick bypasses `+i` and consumes the entry.
+   *
+   * Tracked by nick (not ConnId) because the INVITE reducer is pure and
+   * cannot resolve a nick to a connection id itself; the JOIN reducer
+   * compares against `ctx.connection.nick`.
+   */
+  pendingInvites: Set<Nick>;
+  createdAt: number;
+}
+
+/** Read-only snapshot of a channel used by NAMES, WHO, LIST, PRIVMSG fanout. */
+export interface ChanSnapshot {
+  readonly name: ChanName;
+  readonly nameLower: string;
+  readonly modes: Readonly<ChannelModes>;
+  readonly banMasks: ReadonlySet<string>;
+  readonly topic?: Readonly<ChannelTopic>;
+  readonly members: Roster;
+  readonly pendingInvites: ReadonlySet<Nick>;
+  readonly createdAt: number;
+}
+
+/** Returns a fresh {@link ChannelModes} with every flag disabled. */
+export function emptyModes(): ChannelModes {
+  return {
+    inviteOnly: false,
+    topicLock: false,
+    noExternal: false,
+    moderated: false,
+    secret: false,
+    private: false,
+  };
+}
+
+export interface CreateChannelOptions {
+  name: ChanName;
+  nameLower: string;
+  createdAt: number;
+  topic?: ChannelTopic;
+}
+
+/** Constructs an empty channel with default modes. */
+export function createChannel(opts: CreateChannelOptions): ChannelState {
+  const chan: ChannelState = {
+    name: opts.name,
+    nameLower: opts.nameLower,
+    modes: emptyModes(),
+    banMasks: new Set<string>(),
+    members: new Map<ConnId, RosterEntry>(),
+    pendingInvites: new Set<ConnId>(),
+    createdAt: opts.createdAt,
+  };
+  if (opts.topic !== undefined) chan.topic = opts.topic;
+  return chan;
+}
+
+/**
+ * Returns the canonical IRC prefix string for a roster entry.
+ * Op (`@`) sorts before voice (`+`); a user with both is `@+`.
+ */
+export function prefixOf(entry: RosterEntry): string {
+  let prefix = '';
+  if (entry.op) prefix += '@';
+  if (entry.voice) prefix += '+';
+  return prefix;
+}
+
+/** Freezes a mutable channel state into an immutable snapshot view. */
+export function toSnapshot(chan: ChannelState): ChanSnapshot {
+  return {
+    name: chan.name,
+    nameLower: chan.nameLower,
+    modes: chan.modes,
+    banMasks: chan.banMasks,
+    members: chan.members,
+    pendingInvites: chan.pendingInvites,
+    createdAt: chan.createdAt,
+    ...(chan.topic !== undefined ? { topic: chan.topic } : {}),
+  };
+}
+
+/** Returns an empty {@link ChannelDelta} (no changes). */
+export function emptyChannelDelta(): ChannelDelta {
+  return {
+    memberships: [],
+    modeChanges: [],
+    banMaskChanges: [],
+  };
+}
+
+/**
+ * Applies a delta to a channel, returning a new {@link ChannelState} with
+ * copies of the mutated substructures (modes, members, ban masks). Source
+ * state is left untouched so callers may continue reading it.
+ */
+export function applyChannelDelta(chan: ChannelState, delta: ChannelDelta): ChannelState {
+  const next: ChannelState = {
+    name: chan.name,
+    nameLower: chan.nameLower,
+    modes: { ...chan.modes },
+    banMasks: new Set(chan.banMasks),
+    members: new Map(chan.members),
+    pendingInvites: chan.pendingInvites,
+    createdAt: chan.createdAt,
+  };
+  if (chan.topic !== undefined) next.topic = chan.topic;
+
+  if (delta.memberships !== undefined) {
+    for (const m of delta.memberships) {
+      if (m.type === 'add') {
+        if (m.nick === undefined) continue;
+        next.members.set(m.conn, {
+          conn: m.conn,
+          nick: m.nick,
+          op: m.op ?? false,
+          voice: m.voice ?? false,
+        });
+      } else {
+        next.members.delete(m.conn);
+      }
+    }
+  }
+
+  if (delta.modeChanges !== undefined) {
+    for (const change of delta.modeChanges) {
+      applyModeChange(next.modes, change);
+    }
+  }
+
+  if (delta.banMaskChanges !== undefined) {
+    for (const b of delta.banMaskChanges) {
+      if (b.type === 'add') {
+        next.banMasks.add(b.mask);
+      } else {
+        next.banMasks.delete(b.mask);
+      }
+    }
+  }
+
+  if (delta.topic !== undefined) {
+    if (delta.topic === null) {
+      // biome-ignore lint/performance/noDelete: exactOptionalPropertyTypes forbids `= undefined`.
+      delete next.topic;
+    } else {
+      next.topic = delta.topic;
+    }
+  }
+
+  return next;
+}
+
+function applyModeChange(modes: ChannelModes, change: ModeChange): void {
+  switch (change.mode) {
+    case 'inviteOnly':
+    case 'topicLock':
+    case 'noExternal':
+    case 'moderated':
+    case 'secret':
+    case 'private':
+      modes[change.mode] = change.set;
+      break;
+    case 'key':
+      if (change.set) {
+        if (typeof change.arg === 'string') modes.key = change.arg;
+      } else {
+        // biome-ignore lint/performance/noDelete: exactOptionalPropertyTypes forbids `= undefined`.
+        delete modes.key;
+      }
+      break;
+    case 'limit':
+      if (change.set) {
+        if (typeof change.arg === 'number') modes.limit = change.arg;
+      } else {
+        // biome-ignore lint/performance/noDelete: exactOptionalPropertyTypes forbids `= undefined`.
+        delete modes.limit;
+      }
+      break;
+  }
+}

package/packages/irc-core/src/state/connection.ts

@@ -0,0 +1,153 @@
+/**
+ * Connection-level state shapes.
+ *
+ * The Connection entity is the authority for registration (NICK/USER/PASS),
+ * per-client modes (away, invisible, oper), and the list of channels the
+ * connection has joined. Adapters (CF ConnectionDO, AWS Connections table)
+ * persist this shape verbatim.
+ */
+
+import type { ChanName } from './channel.js';
+
+/** Stable identifier for a transport connection. */
+export type ConnId = string;
+
+/** IRC nickname, with its original case preserved. */
+export type Nick = string;
+
+/** Lifetime of a connection from handshake through welcome numerics. */
+export type RegistrationState = 'pre-registration' | 'registering' | 'registered';
+
+/**
+ * User modes applied to a connection. The IRC user-mode letters are
+ * `i` (invisible), `o` (oper), `w` (wallops), `s` (server notices).
+ */
+export interface UserModes {
+  invisible: boolean;
+  oper: boolean;
+  wallops: boolean;
+  serverNotices: boolean;
+}
+
+/**
+ * Mutable, authoritative per-connection state.
+ *
+ * Adapters persist this verbatim. Reducers receive it as their `state`
+ * argument and return a new value (with mutation permitted for performance
+ * since the previous value is discarded).
+ */
+export interface ConnectionState {
+  id: ConnId;
+  /** Reserved nick once `NICK` is accepted; absent until then. */
+  nick?: Nick;
+  /** Ident/user name set by `USER`. */
+  user?: string;
+  /** Visible host (post-cloak). */
+  host?: string;
+  /** Real name set by `USER`. */
+  realname?: string;
+  /** Stashed `PASS` value, consumed during registration. */
+  passAttempt?: string;
+  /** SASL-authenticated account name, if any. */
+  account?: string;
+  registration: RegistrationState;
+  /**
+   * True once the client has sent `CAP LS` or `CAP REQ` and not yet sent
+   * `CAP END`. While true the registration welcome block is deferred until
+   * `CAP END` arrives (per IRCv3 capability-negotiation spec).
+   */
+  capNegotiating: boolean;
+  /** IRCv3 capabilities negotiated via `CAP`. */
+  caps: Set<string>;
+  /** Away reason; absent when not away. */
+  away?: string;
+  /** Lowercased channel names this connection has JOINed. */
+  joinedChannels: Set<ChanName>;
+  userModes: UserModes;
+  /** Last-seen epoch ms (drives idle / PING bookkeeping). */
+  lastSeen: number;
+  /** Connect-time epoch ms (drives WHOIS signon time). */
+  connectedSince: number;
+}
+
+/**
+ * Read-only snapshot of a connection used by reducers that need a peer's
+ * view (PRIVMSG routing, WHOIS, NAMES) without mutating it. The actor layer
+ * builds these by calling {@link toSnapshot} on the authoritative state.
+ */
+export interface ConnSnapshot {
+  readonly id: ConnId;
+  readonly nick?: Nick;
+  readonly user?: string;
+  readonly host?: string;
+  readonly realname?: string;
+  readonly account?: string;
+  readonly registration: RegistrationState;
+  readonly caps: ReadonlySet<string>;
+  readonly away?: string;
+  readonly joinedChannels: ReadonlySet<ChanName>;
+  readonly userModes: Readonly<UserModes>;
+  readonly lastSeen: number;
+  readonly connectedSince: number;
+  /** Derived `nick!user@host`; absent when nick is missing. */
+  readonly hostmask?: string;
+}
+
+export interface CreateConnectionOptions {
+  id: ConnId;
+  connectedSince: number;
+  /** Defaults to {@link connectedSince}. */
+  lastSeen?: number;
+}
+
+/** Constructs a fresh pre-registration connection. */
+export function createConnection(opts: CreateConnectionOptions): ConnectionState {
+  return {
+    id: opts.id,
+    registration: 'pre-registration',
+    capNegotiating: false,
+    caps: new Set<string>(),
+    joinedChannels: new Set<ChanName>(),
+    userModes: {
+      invisible: false,
+      oper: false,
+      wallops: false,
+      serverNotices: false,
+    },
+    lastSeen: opts.lastSeen ?? opts.connectedSince,
+    connectedSince: opts.connectedSince,
+  };
+}
+
+/** Builds the canonical `nick!user@host` string, omitting absent parts. */
+export function hostmaskOf(conn: ConnectionState): string | undefined {
+  if (conn.nick === undefined) return undefined;
+  let out = conn.nick;
+  if (conn.user !== undefined) out = `${out}!${conn.user}`;
+  if (conn.host !== undefined) out = `${out}@${conn.host}`;
+  return out;
+}
+
+/** Freezes a mutable connection state into an immutable snapshot view. */
+export function toSnapshot(conn: ConnectionState): ConnSnapshot {
+  const hostmask = hostmaskOf(conn);
+  // Build as a plain object literal with optional keys omitted entirely
+  // (exactOptionalPropertyTypes + readonly fields forbid assign-after-build).
+  const snap: ConnSnapshot = {
+    id: conn.id,
+    registration: conn.registration,
+    caps: conn.caps,
+    joinedChannels: conn.joinedChannels,
+    userModes: conn.userModes,
+    lastSeen: conn.lastSeen,
+    connectedSince: conn.connectedSince,
+    ...(conn.nick !== undefined ? { nick: conn.nick } : {}),
+    ...(conn.user !== undefined ? { user: conn.user } : {}),
+    ...(conn.host !== undefined ? { host: conn.host } : {}),
+    ...(conn.realname !== undefined ? { realname: conn.realname } : {}),
+    ...(conn.account !== undefined ? { account: conn.account } : {}),
+    ...(conn.away !== undefined ? { away: conn.away } : {}),
+    ...(hostmask !== undefined ? { hostmask } : {}),
+  };
+  return snap;
+}