bundis 0.1.0

package/src/launch.ts

@@ -0,0 +1,188 @@
+/**
+ * Public launchers for using bundis from another project.
+ *
+ * Two ways to run the server (both return a ready-to-use `redis://` URL for a
+ * stock `Bun.RedisClient`):
+ *
+ * - {@link embedServer}  — in the **current** process. Zero IPC overhead, but
+ *   shares the event loop with the host app (bun:sqlite is synchronous).
+ * - {@link spawnServer}  — in a **separate** Bun process. Isolates the SQLite
+ *   writer and any blocking work from the host app; resolves once the child
+ *   signals readiness on stdout.
+ */
+
+import { startServer, type RunningServer } from "./server";
+import type { ServerConfig } from "./config";
+
+/** stdout JSON `event` value the CLI prints once it is accepting connections. */
+export const READY_EVENT = "bundis:ready";
+
+export interface LaunchOptions {
+  /** Bind address (default "127.0.0.1"; use "0.0.0.0" to expose externally). */
+  host?: string;
+  /** TCP port (default 6379; 0 = pick an ephemeral port). */
+  port?: number;
+  /** SQLite file path (default "./data.db"; ":memory:" for non-persistent). */
+  dbPath?: string;
+  /** When set, clients must AUTH with this password. */
+  password?: string;
+  /** Active-expiry sweep interval in ms (default 100). */
+  reaperIntervalMs?: number;
+}
+
+export interface EmbeddedServer {
+  readonly host: string;
+  /** Actual bound port (resolves `port: 0`). */
+  readonly port: number;
+  /** Connection URL for a stock `new RedisClient(url)`. */
+  readonly url: string;
+  /** Underlying server handle (storage, pub/sub hub, config). */
+  readonly server: RunningServer;
+  /** Stop listening, stop the reaper, close storage. */
+  stop(): void;
+}
+
+/** Start the server inside the current Bun process (main-process mode). */
+export function embedServer(opts: LaunchOptions = {}): EmbeddedServer {
+  const config = resolveConfig(opts);
+  const running = startServer(config);
+  return {
+    host: running.hostname,
+    port: running.port,
+    url: clientUrl(running.hostname, running.port, config.password),
+    server: running,
+    stop: () => running.stop(),
+  };
+}
+
+export interface SpawnedServer {
+  readonly host: string;
+  /** Actual bound port (resolves `port: 0`). */
+  readonly port: number;
+  /** Connection URL for a stock `new RedisClient(url)`. */
+  readonly url: string;
+  readonly pid: number;
+  /** Kill the child process and wait for it to exit. */
+  stop(): Promise<void>;
+}
+
+export interface SpawnServerOptions extends LaunchOptions {
+  /** Bun executable to launch with (default: the currently running bun). */
+  bunPath?: string;
+  /** Max ms to wait for the child's ready signal (default 10_000). */
+  readyTimeoutMs?: number;
+}
+
+/** Start the server as a separate Bun process (sidecar mode). */
+export async function spawnServer(opts: SpawnServerOptions = {}): Promise<SpawnedServer> {
+  const config = resolveConfig(opts);
+  const cliPath = Bun.fileURLToPath(new URL("./cli.ts", import.meta.url));
+  const proc = Bun.spawn(
+    [
+      opts.bunPath ?? process.execPath,
+      cliPath,
+      "--host", config.host,
+      "--port", String(config.port),
+      "--db", config.dbPath,
+      ...(config.password !== null ? ["--password", config.password] : []),
+      "--reaper", String(config.reaperIntervalMs),
+    ],
+    { stdout: "pipe", stderr: "inherit" },
+  );
+
+  let ready: { host: string; port: number };
+  try {
+    ready = await waitForReady(proc.stdout, opts.readyTimeoutMs ?? 10_000);
+  } catch (err) {
+    proc.kill();
+    await proc.exited;
+    throw err;
+  }
+
+  return {
+    host: ready.host,
+    port: ready.port,
+    url: clientUrl(ready.host, ready.port, config.password),
+    pid: proc.pid,
+    async stop() {
+      proc.kill();
+      await proc.exited;
+    },
+  };
+}
+
+// ── helpers ──────────────────────────────────────────────────────────────---
+
+function resolveConfig(opts: LaunchOptions): ServerConfig {
+  return {
+    host: opts.host ?? "127.0.0.1",
+    port: opts.port ?? 6379,
+    dbPath: opts.dbPath ?? "./data.db",
+    password: opts.password ?? null,
+    reaperIntervalMs: opts.reaperIntervalMs ?? 100,
+  };
+}
+
+function clientUrl(host: string, port: number, password: string | null): string {
+  // A wildcard bind address is not connectable; clients use loopback.
+  const h = host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host;
+  const auth = password === null ? "" : `:${encodeURIComponent(password)}@`;
+  return `redis://${auth}${h}:${port}`;
+}
+
+/** Scan child stdout line-by-line until the READY_EVENT JSON line appears. */
+async function waitForReady(
+  stdout: ReadableStream<Uint8Array>,
+  timeoutMs: number,
+): Promise<{ host: string; port: number }> {
+  const reader = stdout.getReader();
+  const decoder = new TextDecoder();
+  const deadline = Date.now() + timeoutMs;
+  let buf = "";
+  for (;;) {
+    const { done, value } = await Promise.race([
+      reader.read(),
+      rejectAfter(deadline - Date.now()),
+    ]);
+    if (done) {
+      reader.releaseLock();
+      throw new Error("bundis child exited before signalling ready");
+    }
+    buf += decoder.decode(value, { stream: true });
+    let nl: number;
+    while ((nl = buf.indexOf("\n")) !== -1) {
+      const line = buf.slice(0, nl).trim();
+      buf = buf.slice(nl + 1);
+      if (!line.startsWith("{")) continue;
+      try {
+        const msg = JSON.parse(line) as { event?: string; host?: string; port?: number };
+        if (msg.event === READY_EVENT && msg.host !== undefined && msg.port !== undefined) {
+          void drain(reader); // keep the pipe from filling if the child logs later
+          return { host: msg.host, port: msg.port };
+        }
+      } catch {
+        // not our line
+      }
+    }
+  }
+}
+
+async function drain(reader: { read(): Promise<{ done: boolean }> }): Promise<void> {
+  try {
+    while (!(await reader.read()).done) {
+      // discard
+    }
+  } catch {
+    // stream torn down with the process
+  }
+}
+
+function rejectAfter(ms: number): Promise<never> {
+  return new Promise((_, reject) => {
+    const t = setTimeout(
+      () => reject(new Error("timed out waiting for bundis ready signal")),
+      Math.max(0, ms),
+    );
+    (t as unknown as { unref?: () => void }).unref?.();
+  });
+}

package/src/resp/parser.ts

@@ -0,0 +1,133 @@
+/**
+ * L2 inbound RESP parser (streaming).
+ *
+ * TCP has no message boundaries: {@link ../server.ts}'s `data` callback delivers
+ * arbitrary chunks. This parser keeps a per-connection accumulation buffer and
+ * yields complete commands only, preserving arrival order so pipelined commands
+ * stay in order (§4.1.1, §4.1.2).
+ *
+ * The stock `Bun.RedisClient` always sends commands as a RESP Array of Bulk
+ * Strings (`*N\r\n($len\r\n<bytes>\r\n)*`). We parse that shape, plus inline
+ * commands as a tolerant fallback. Argument bytes are preserved verbatim.
+ */
+
+import type { Command } from "./types";
+
+const CR = 13;
+const LF = 10;
+const STAR = 42; // '*'
+const DOLLAR = 36; // '$'
+
+export class RespParser {
+  /** Pending bytes not yet consumed into a full command. */
+  #buf: Uint8Array = new Uint8Array(0);
+
+  /** Append a freshly received chunk to the internal buffer. */
+  push(chunk: Uint8Array): void {
+    if (this.#buf.length === 0) {
+      this.#buf = chunk;
+      return;
+    }
+    const merged = new Uint8Array(this.#buf.length + chunk.length);
+    merged.set(this.#buf, 0);
+    merged.set(chunk, this.#buf.length);
+    this.#buf = merged;
+  }
+
+  /**
+   * Drain all complete commands currently buffered, in order.
+   * Incomplete trailing bytes are retained for the next {@link push}.
+   * Throws on malformed protocol (the caller should reply with an error and
+   * close the connection).
+   */
+  drain(): Command[] {
+    const out: Command[] = [];
+    let offset = 0;
+    for (;;) {
+      const res = this.#parseOne(offset);
+      if (res === null) break; // need more bytes
+      out.push(res.command);
+      offset = res.next;
+    }
+    if (offset > 0) {
+      this.#buf = this.#buf.subarray(offset);
+    }
+    return out;
+  }
+
+  /** Parse a single command starting at `start`, or null if incomplete. */
+  #parseOne(start: number): { command: Command; next: number } | null {
+    const buf = this.#buf;
+    if (start >= buf.length) return null;
+    const first = buf[start]!;
+    if (first === STAR) return this.#parseArray(start);
+    // Inline command fallback: a CRLF- or LF-terminated whitespace-split line.
+    return this.#parseInline(start);
+  }
+
+  #parseArray(start: number): { command: Command; next: number } | null {
+    const buf = this.#buf;
+    const header = this.#readLine(start);
+    if (header === null) return null;
+    const count = parseInt(decodeAscii(buf.subarray(start + 1, header.end)), 10);
+    if (Number.isNaN(count)) throw new ProtocolError("invalid multibulk length");
+    if (count <= 0) {
+      // Empty/negative multibulk: skip, no command produced. Represent as empty.
+      return { command: { name: "", args: [] }, next: header.next };
+    }
+    const args: Uint8Array[] = [];
+    let offset = header.next;
+    for (let i = 0; i < count; i++) {
+      if (offset >= buf.length) return null;
+      if (buf[offset] !== DOLLAR) throw new ProtocolError("expected bulk string");
+      const lenLine = this.#readLine(offset);
+      if (lenLine === null) return null;
+      const len = parseInt(decodeAscii(buf.subarray(offset + 1, lenLine.end)), 10);
+      if (Number.isNaN(len) || len < 0) throw new ProtocolError("invalid bulk length");
+      const dataStart = lenLine.next;
+      const dataEnd = dataStart + len;
+      if (dataEnd + 2 > buf.length) return null; // data + trailing CRLF not all here yet
+      args.push(buf.slice(dataStart, dataEnd)); // copy: detach from the shared buffer
+      offset = dataEnd + 2; // skip trailing CRLF
+    }
+    const name = decodeAscii(args[0]!).toUpperCase();
+    return { command: { name, args }, next: offset };
+  }
+
+  #parseInline(start: number): { command: Command; next: number } | null {
+    const line = this.#readLine(start);
+    if (line === null) return null;
+    const raw = this.#buf.subarray(start, line.end);
+    const text = decodeAscii(raw).trim();
+    if (text.length === 0) {
+      return { command: { name: "", args: [] }, next: line.next };
+    }
+    const tokens = text.split(/\s+/);
+    const args = tokens.map((t) => new TextEncoder().encode(t));
+    return { command: { name: tokens[0]!.toUpperCase(), args }, next: line.next };
+  }
+
+  /**
+   * Locate the next CRLF (or bare LF) at/after `from`.
+   * Returns `end` (index of CR/LF, exclusive of the terminator) and `next`
+   * (index just past the terminator), or null if no line terminator yet.
+   */
+  #readLine(from: number): { end: number; next: number } | null {
+    const buf = this.#buf;
+    for (let i = from; i < buf.length; i++) {
+      if (buf[i] === LF) {
+        const end = i > from && buf[i - 1] === CR ? i - 1 : i;
+        return { end, next: i + 1 };
+      }
+    }
+    return null;
+  }
+}
+
+export class ProtocolError extends Error {}
+
+function decodeAscii(bytes: Uint8Array): string {
+  let s = "";
+  for (let i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i]!);
+  return s;
+}

package/src/resp/serializer.ts

@@ -0,0 +1,114 @@
+/**
+ * L2 outbound RESP3 serializer.
+ *
+ * Walks a {@link Reply} tree and produces wire bytes. Bulk/verbatim lengths are
+ * computed in **bytes** (not characters) so binary-safe values and multi-byte
+ * UTF-8 are framed correctly. This is the only place RESP3 type bytes are chosen.
+ */
+
+import type { Reply } from "./types";
+
+const encoder = new TextEncoder();
+
+/** Serialize one reply to a single Uint8Array. */
+export function serialize(reply: Reply): Uint8Array {
+  const parts: Uint8Array[] = [];
+  write(reply, parts);
+  return concat(parts);
+}
+
+/** Serialize many replies back-to-back (one pipelined write). */
+export function serializeAll(replies: readonly Reply[]): Uint8Array {
+  const parts: Uint8Array[] = [];
+  for (const r of replies) write(r, parts);
+  return concat(parts);
+}
+
+function write(reply: Reply, out: Uint8Array[]): void {
+  switch (reply.t) {
+    case "simple":
+      out.push(encoder.encode(`+${reply.v}\r\n`));
+      return;
+    case "error":
+      out.push(encoder.encode(`-${reply.code} ${reply.msg}\r\n`));
+      return;
+    case "int":
+      out.push(encoder.encode(`:${reply.v}\r\n`));
+      return;
+    case "bignum":
+      out.push(encoder.encode(`(${reply.v}\r\n`));
+      return;
+    case "bool":
+      out.push(encoder.encode(reply.v ? "#t\r\n" : "#f\r\n"));
+      return;
+    case "double":
+      out.push(encoder.encode(`,${formatDouble(reply.v)}\r\n`));
+      return;
+    case "null":
+      out.push(encoder.encode("_\r\n"));
+      return;
+    case "bulk": {
+      if (reply.v === null) {
+        out.push(encoder.encode("_\r\n")); // RESP3 null
+        return;
+      }
+      const body = typeof reply.v === "string" ? encoder.encode(reply.v) : reply.v;
+      out.push(encoder.encode(`$${body.length}\r\n`));
+      out.push(body);
+      out.push(CRLF);
+      return;
+    }
+    case "verbatim": {
+      const body = encoder.encode(`${reply.fmt}:${reply.v}`);
+      out.push(encoder.encode(`=${body.length}\r\n`));
+      out.push(body);
+      out.push(CRLF);
+      return;
+    }
+    case "array": {
+      if (reply.v === null) {
+        out.push(encoder.encode("*-1\r\n"));
+        return;
+      }
+      out.push(encoder.encode(`*${reply.v.length}\r\n`));
+      for (const el of reply.v) write(el, out);
+      return;
+    }
+    case "set":
+      out.push(encoder.encode(`~${reply.v.length}\r\n`));
+      for (const el of reply.v) write(el, out);
+      return;
+    case "push":
+      out.push(encoder.encode(`>${reply.v.length}\r\n`));
+      for (const el of reply.v) write(el, out);
+      return;
+    case "map":
+      out.push(encoder.encode(`%${reply.v.length}\r\n`));
+      for (const [k, val] of reply.v) {
+        write(k, out);
+        write(val, out);
+      }
+      return;
+  }
+}
+
+const CRLF = encoder.encode("\r\n");
+
+function formatDouble(v: number): string {
+  if (Number.isNaN(v)) return "nan";
+  if (v === Infinity) return "inf";
+  if (v === -Infinity) return "-inf";
+  return String(v);
+}
+
+function concat(parts: Uint8Array[]): Uint8Array {
+  let total = 0;
+  for (const p of parts) total += p.length;
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const p of parts) {
+    out.set(p, offset);
+    offset += p.length;
+  }
+  return out;
+}

package/src/resp/types.ts

@@ -0,0 +1,49 @@
+/**
+ * L2 RESP3 reply model.
+ *
+ * A {@link Reply} is a tagged union describing exactly which RESP3 type the
+ * server must emit. The serializer ({@link ./serializer.ts}) walks this tree and
+ * produces bytes. Keeping the wire type explicit (rather than inferring it from a
+ * JS value) is what lets us honor the §2.4 type-conversion contract precisely.
+ */
+
+export type Reply =
+  | { readonly t: "simple"; readonly v: string } // +OK\r\n
+  | { readonly t: "error"; readonly code: string; readonly msg: string } // -CODE msg\r\n
+  | { readonly t: "int"; readonly v: number | bigint } // :1\r\n
+  | { readonly t: "bulk"; readonly v: Uint8Array | string | null } // $len\r\n..\r\n  (null => RESP3 null)
+  | { readonly t: "null" } // _\r\n
+  | { readonly t: "array"; readonly v: readonly Reply[] | null } // *N\r\n..  (null => *-1)
+  | { readonly t: "map"; readonly v: ReadonlyArray<readonly [Reply, Reply]> } // %N\r\n..
+  | { readonly t: "set"; readonly v: readonly Reply[] } // ~N\r\n..
+  | { readonly t: "bool"; readonly v: boolean } // #t\r\n / #f\r\n
+  | { readonly t: "double"; readonly v: number } // ,3.14\r\n
+  | { readonly t: "bignum"; readonly v: bigint } // (123\r\n
+  | { readonly t: "verbatim"; readonly fmt: string; readonly v: string } // =len\r\ntxt:..\r\n
+  | { readonly t: "push"; readonly v: readonly Reply[] }; // >N\r\n..
+
+/** Reply constructors. Use these instead of building object literals by hand. */
+export const R = {
+  simple: (v: string): Reply => ({ t: "simple", v }),
+  ok: (): Reply => ({ t: "simple", v: "OK" }),
+  error: (code: string, msg: string): Reply => ({ t: "error", code, msg }),
+  int: (v: number | bigint): Reply => ({ t: "int", v }),
+  bulk: (v: Uint8Array | string | null): Reply => ({ t: "bulk", v }),
+  nullReply: (): Reply => ({ t: "null" }),
+  array: (v: readonly Reply[] | null): Reply => ({ t: "array", v }),
+  map: (v: ReadonlyArray<readonly [Reply, Reply]>): Reply => ({ t: "map", v }),
+  set: (v: readonly Reply[]): Reply => ({ t: "set", v }),
+  bool: (v: boolean): Reply => ({ t: "bool", v }),
+  double: (v: number): Reply => ({ t: "double", v }),
+  bignum: (v: bigint): Reply => ({ t: "bignum", v }),
+  verbatim: (fmt: string, v: string): Reply => ({ t: "verbatim", fmt, v }),
+  push: (v: readonly Reply[]): Reply => ({ t: "push", v }),
+} as const;
+
+/** A fully parsed inbound command: name is upper-cased ASCII, args keep raw bytes. */
+export interface Command {
+  /** Upper-cased command name, e.g. "SET". */
+  readonly name: string;
+  /** All tokens including the command name, as raw bytes (binary-safe). */
+  readonly args: Uint8Array[];
+}

package/src/server.ts

@@ -0,0 +1,92 @@
+/**
+ * L1 Transport — Bun.listen TCP server and socket lifecycle.
+ *
+ * Per connection (§4.1): accumulate bytes in the parser, drain complete commands
+ * in arrival order, dispatch each serially (handlers are synchronous over
+ * bun:sqlite), and write replies in order. Connection state lives on
+ * `socket.data`. Backpressure is handled via the `drain` callback.
+ */
+
+import type { Socket, TCPSocketListener } from "bun";
+import { Connection } from "./connection";
+import { dispatch } from "./dispatcher";
+import { ProtocolError } from "./resp/parser";
+import { R } from "./resp/types";
+import { SqliteStorage } from "./storage/sqlite";
+import { PubSubHub } from "./sidecar/pubsub";
+import { WatchRegistry } from "./sidecar/watch";
+import { ExpiryReaper } from "./sidecar/reaper";
+import type { ServerConfig } from "./config";
+import type { ServerContext } from "./engine/context";
+
+export interface RunningServer {
+  /** Actual bound port (resolves `port: 0` used by tests). */
+  readonly port: number;
+  readonly hostname: string;
+  readonly server: ServerContext;
+  /** Stop accepting connections, stop the reaper, and close storage. */
+  stop(): void;
+}
+
+export function startServer(config: ServerConfig): RunningServer {
+  const watch = new WatchRegistry();
+  const storage = new SqliteStorage(config.dbPath, { onWrite: watch.bump });
+  const hub = new PubSubHub();
+  const ctx: ServerContext = { storage, hub, watch, config };
+
+  const reaper = new ExpiryReaper(storage, config.reaperIntervalMs);
+  reaper.start();
+
+  const listener: TCPSocketListener<Connection> = Bun.listen<Connection>({
+    hostname: config.host,
+    port: config.port,
+    socket: {
+      open(socket: Socket<Connection>) {
+        socket.data = new Connection(socket);
+      },
+      data(socket: Socket<Connection>, chunk: Buffer) {
+        const conn = socket.data;
+        conn.parser.push(new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength));
+        let commands;
+        try {
+          commands = conn.parser.drain();
+        } catch (err) {
+          if (err instanceof ProtocolError) {
+            conn.send(R.error("ERR", `Protocol error: ${err.message}`));
+            socket.end();
+            return;
+          }
+          throw err;
+        }
+        const now = Date.now();
+        for (const command of commands) {
+          dispatch(conn, command, ctx, now);
+        }
+      },
+      drain(socket: Socket<Connection>) {
+        socket.data?.flush();
+      },
+      close(socket: Socket<Connection>) {
+        const conn = socket.data;
+        if (conn) {
+          conn.markClosed();
+          hub.drop(conn);
+        }
+      },
+      error(socket: Socket<Connection>) {
+        socket.data?.markClosed();
+      },
+    },
+  });
+
+  return {
+    port: listener.port,
+    hostname: listener.hostname,
+    server: ctx,
+    stop() {
+      reaper.stop();
+      listener.stop(true);
+      storage.close();
+    },
+  };
+}