bundis 0.1.0

package/src/commands/transaction.ts

@@ -0,0 +1,85 @@
+/**
+ * Transaction commands (Phase 2): MULTI, EXEC, DISCARD, WATCH, UNWATCH, RESET.
+ *
+ * MULTI starts queueing on the connection (handled in the dispatcher, which
+ * replies +QUEUED). EXEC runs the queued commands inside one SQLite transaction
+ * and returns the result array; if any WATCHed key changed since WATCH, EXEC
+ * returns nil (optimistic lock, §6.3). Under the single-writer assumption a
+ * simple version comparison via {@link WatchRegistry} is sufficient.
+ */
+
+import { R, type Reply } from "../resp/types";
+import { Errors } from "../engine/errors";
+import { executeCore } from "../dispatcher";
+import type { CommandContext } from "../engine/context";
+import { hashKey, type WatchSnapshot } from "../sidecar/watch";
+
+export function multi(ctx: CommandContext): Reply {
+  if (ctx.conn.txn) return R.error("ERR", "MULTI calls can not be nested");
+  ctx.conn.txn = { queued: [], error: false };
+  return R.ok();
+}
+
+export function discard(ctx: CommandContext): Reply {
+  if (!ctx.conn.txn) throw Errors.discardWithoutMulti();
+  ctx.conn.txn = null;
+  ctx.conn.watch = null;
+  return R.ok();
+}
+
+export function exec(ctx: CommandContext): Reply {
+  const conn = ctx.conn;
+  const txn = conn.txn;
+  if (!txn) throw Errors.execWithoutMulti();
+  conn.txn = null;
+
+  if (txn.error) {
+    conn.watch = null;
+    throw Errors.execAbort();
+  }
+  if (conn.watch && isWatchDirty(conn.watch, ctx)) {
+    conn.watch = null;
+    return R.nullReply(); // a watched key changed → abort
+  }
+  conn.watch = null;
+
+  const results = ctx.storage.withTransaction(() =>
+    txn.queued.map((cmd) => {
+      const reply = executeCore(conn, cmd, ctx.server, ctx.nowMs);
+      return reply ?? R.nullReply();
+    }),
+  );
+  return R.array(results);
+}
+
+export function watch(ctx: CommandContext): Reply {
+  ctx.requireArgc(1);
+  if (ctx.conn.txn) return R.error("ERR", "WATCH inside MULTI is not allowed");
+  const snap: WatchSnapshot = ctx.conn.watch ?? new Map();
+  for (let i = 0; i < ctx.argc; i++) {
+    const key = ctx.arg(i);
+    snap.set(hashKey(key), { key, version: ctx.server.watch.version(key) });
+  }
+  ctx.conn.watch = snap;
+  return R.ok();
+}
+
+export function unwatch(ctx: CommandContext): Reply {
+  ctx.conn.watch = null;
+  return R.ok();
+}
+
+export function reset(ctx: CommandContext): Reply {
+  ctx.conn.txn = null;
+  ctx.conn.watch = null;
+  ctx.server.hub.drop(ctx.conn);
+  ctx.conn.state = "READY";
+  return R.simple("RESET");
+}
+
+function isWatchDirty(snap: WatchSnapshot, ctx: CommandContext): boolean {
+  for (const { key, version } of snap.values()) {
+    if (ctx.server.watch.version(key) !== version) return true;
+  }
+  return false;
+}

package/src/config.ts

@@ -0,0 +1,57 @@
+/**
+ * Server configuration, resolved from CLI flags and environment.
+ *
+ * Precedence: CLI flag > env var > default. Kept tiny and dependency-free.
+ *   --host / REDIS_HOST          (default 0.0.0.0)
+ *   --port / REDIS_PORT          (default 6379; 0 = ephemeral, used by tests)
+ *   --db   / REDIS_DB_PATH       (default ./data.db; ":memory:" for in-memory)
+ *   --password / REDIS_PASSWORD  (default none → AUTH always succeeds)
+ */
+
+export interface ServerConfig {
+  host: string;
+  port: number;
+  dbPath: string;
+  password: string | null;
+  /** Active-expiry sweep interval in ms. */
+  reaperIntervalMs: number;
+}
+
+export function loadConfig(argv: string[] = Bun.argv.slice(2)): ServerConfig {
+  const flags = parseFlags(argv);
+  const env = Bun.env;
+  return {
+    host: flags.host ?? env.REDIS_HOST ?? "0.0.0.0",
+    port: int(flags.port ?? env.REDIS_PORT, 6379),
+    dbPath: flags.db ?? env.REDIS_DB_PATH ?? "./data.db",
+    password: flags.password ?? env.REDIS_PASSWORD ?? null,
+    reaperIntervalMs: int(flags.reaper ?? env.REDIS_REAPER_MS, 100),
+  };
+}
+
+function parseFlags(argv: string[]): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (!a.startsWith("--")) continue;
+    const eq = a.indexOf("=");
+    if (eq !== -1) {
+      out[a.slice(2, eq)] = a.slice(eq + 1);
+    } else {
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith("--")) {
+        out[a.slice(2)] = next;
+        i++;
+      } else {
+        out[a.slice(2)] = "true";
+      }
+    }
+  }
+  return out;
+}
+
+function int(v: string | undefined, fallback: number): number {
+  if (v === undefined) return fallback;
+  const n = parseInt(v, 10);
+  return Number.isNaN(n) ? fallback : n;
+}

package/src/connection.ts

@@ -0,0 +1,97 @@
+/**
+ * L3 Connection — per-socket state machine and write path.
+ *
+ * Owns everything isolated to one client connection (§4.1.3): handshake/auth
+ * state, selected DB, the streaming parser buffer, pub/sub subscriptions, the
+ * MULTI transaction queue, and the WATCH snapshot. Also implements the
+ * backpressure-aware {@link send} used by both the dispatcher and the PubSubHub.
+ */
+
+import type { Socket } from "bun";
+import { serialize } from "./resp/serializer";
+import { RespParser } from "./resp/parser";
+import type { Command, Reply } from "./resp/types";
+import type { WatchSnapshot } from "./sidecar/watch";
+
+export type ConnState = "HANDSHAKE" | "READY" | "SUBSCRIBED";
+
+/** A buffered MULTI transaction. */
+export interface TxnState {
+  queued: Command[];
+  /** Set if a command failed to queue (bad arity / unknown) → EXEC aborts. */
+  error: boolean;
+}
+
+let nextId = 1;
+
+export class Connection {
+  readonly id = nextId++;
+  state: ConnState = "HANDSHAKE";
+  db = 0;
+  authed = false;
+  proto = 2; // upgraded to 3 on HELLO 3
+  name = "";
+
+  readonly parser = new RespParser();
+
+  // pub/sub
+  readonly channels = new Set<string>();
+  readonly patterns = new Set<string>();
+
+  // transactions
+  txn: TxnState | null = null;
+  watch: WatchSnapshot | null = null;
+
+  /** Bytes awaiting a `drain` event when the socket buffer was full. */
+  #outbox: Uint8Array[] = [];
+  #closed = false;
+
+  constructor(readonly socket: Socket<Connection>) {}
+
+  /** Total active (P)SUBSCRIBE count, used in reply frames. */
+  subscriptionCount(): number {
+    return this.channels.size + this.patterns.size;
+  }
+
+  /** True once the client has at least one active subscription. */
+  inSubscribeMode(): boolean {
+    return this.subscriptionCount() > 0;
+  }
+
+  /** Serialize and write a reply, honoring backpressure. */
+  send(reply: Reply): void {
+    this.write(serialize(reply));
+  }
+
+  /** Write raw bytes, buffering any unflushed remainder for `drain`. */
+  write(bytes: Uint8Array): void {
+    if (this.#closed) return;
+    if (this.#outbox.length > 0) {
+      // Preserve ordering: once we're behind, everything queues.
+      this.#outbox.push(bytes);
+      return;
+    }
+    const written = this.socket.write(bytes);
+    if (written < bytes.length) {
+      this.#outbox.push(bytes.subarray(written));
+    }
+  }
+
+  /** Called from the socket `drain` handler: flush what we can, in order. */
+  flush(): void {
+    while (this.#outbox.length > 0 && !this.#closed) {
+      const chunk = this.#outbox[0]!;
+      const written = this.socket.write(chunk);
+      if (written < chunk.length) {
+        this.#outbox[0] = chunk.subarray(written);
+        return; // still backpressured
+      }
+      this.#outbox.shift();
+    }
+  }
+
+  markClosed(): void {
+    this.#closed = true;
+    this.#outbox.length = 0;
+  }
+}

package/src/dispatcher.ts

@@ -0,0 +1,204 @@
+/**
+ * L4 Dispatcher — command routing table + execution policy.
+ *
+ * Compatibility extends by adding cases here (§3.3). `dispatch` applies the
+ * connection-level policy (auth gate, SUBSCRIBED-mode restriction, MULTI
+ * queueing) then delegates to `executeCore`, which looks up the handler, builds
+ * the context, and turns thrown errors into RESP error replies. EXEC reuses
+ * `executeCore` directly to run queued commands.
+ */
+
+import { R, type Reply } from "./resp/types";
+import type { Command } from "./resp/types";
+import { CommandContext, type ServerContext } from "./engine/context";
+import { Errors, toRespError } from "./engine/errors";
+import type { Connection } from "./connection";
+
+import * as handshake from "./commands/handshake";
+import * as string from "./commands/string";
+import * as expire from "./commands/expire";
+import * as multikey from "./commands/multikey";
+import * as hash from "./commands/hash";
+import * as set from "./commands/set";
+import * as pubsub from "./commands/pubsub";
+import * as txn from "./commands/transaction";
+
+/** A command handler. Returns the reply, or null if it wrote its own output. */
+export type Handler = (ctx: CommandContext) => Reply | null;
+
+const TABLE: Record<string, Handler> = {
+  // handshake / connection
+  HELLO: handshake.hello,
+  AUTH: handshake.auth,
+  PING: handshake.ping,
+  SELECT: handshake.select,
+  ECHO: handshake.echo,
+  QUIT: handshake.quit,
+  INFO: handshake.info,
+  CLIENT: handshake.client,
+
+  // string / kv
+  SET: string.set,
+  GET: string.get,
+  GETSET: string.getset,
+  GETDEL: string.getdel,
+  APPEND: string.append,
+  STRLEN: string.strlen,
+  DEL: string.del,
+  UNLINK: string.del,
+  EXISTS: string.exists,
+  INCR: string.incr,
+  DECR: string.decr,
+  INCRBY: string.incrby,
+  DECRBY: string.decrby,
+  INCRBYFLOAT: string.incrbyfloat,
+
+  // multi-key
+  MGET: multikey.mget,
+  MSET: multikey.mset,
+  MSETNX: multikey.msetnx,
+  SETEX: multikey.setex,
+  PSETEX: multikey.psetex,
+  SETNX: multikey.setnx,
+
+  // expiry
+  EXPIRE: expire.expire,
+  PEXPIRE: expire.pexpire,
+  EXPIREAT: expire.expireat,
+  PEXPIREAT: expire.pexpireat,
+  TTL: expire.ttl,
+  PTTL: expire.pttl,
+  PERSIST: expire.persist,
+
+  // hash
+  HSET: hash.hset,
+  HMSET: hash.hmset,
+  HSETNX: hash.hsetnx,
+  HGET: hash.hget,
+  HMGET: hash.hmget,
+  HGETALL: hash.hgetall,
+  HDEL: hash.hdel,
+  HEXISTS: hash.hexists,
+  HKEYS: hash.hkeys,
+  HVALS: hash.hvals,
+  HLEN: hash.hlen,
+  HINCRBY: hash.hincrby,
+  HINCRBYFLOAT: hash.hincrbyfloat,
+
+  // set
+  SADD: set.sadd,
+  SREM: set.srem,
+  SISMEMBER: set.sismember,
+  SMEMBERS: set.smembers,
+  SCARD: set.scard,
+  SRANDMEMBER: set.srandmember,
+  SPOP: set.spop,
+
+  // pub/sub
+  SUBSCRIBE: pubsub.subscribe,
+  UNSUBSCRIBE: pubsub.unsubscribe,
+  PSUBSCRIBE: pubsub.psubscribe,
+  PUNSUBSCRIBE: pubsub.punsubscribe,
+  PUBLISH: pubsub.publish,
+  PUBSUB: pubsub.pubsub,
+
+  // transactions
+  MULTI: txn.multi,
+  EXEC: txn.exec,
+  DISCARD: txn.discard,
+  WATCH: txn.watch,
+  UNWATCH: txn.unwatch,
+  RESET: txn.reset,
+};
+
+/** Commands permitted while in SUBSCRIBED mode (§6.1). */
+const SUBSCRIBE_ALLOWED = new Set([
+  "SUBSCRIBE",
+  "UNSUBSCRIBE",
+  "PSUBSCRIBE",
+  "PUNSUBSCRIBE",
+  "PING",
+  "QUIT",
+  "RESET",
+]);
+
+/** Commands allowed before auth when a password is configured. */
+const PREAUTH_ALLOWED = new Set(["HELLO", "AUTH", "QUIT", "RESET"]);
+
+/** Commands that are not queued during MULTI (they drive the transaction). */
+const TXN_CONTROL = new Set(["EXEC", "DISCARD", "MULTI", "WATCH", "RESET"]);
+
+/**
+ * Top-level entry for one inbound command. Applies connection policy and writes
+ * the reply (handlers that manage their own output return null).
+ */
+export function dispatch(
+  conn: Connection,
+  command: Command,
+  server: ServerContext,
+  nowMs: number,
+): void {
+  if (command.name === "") return; // empty multibulk / blank inline line
+
+  // Auth gate.
+  if (
+    server.config.password !== null &&
+    !conn.authed &&
+    !PREAUTH_ALLOWED.has(command.name)
+  ) {
+    conn.send(errReply(Errors.noAuth()));
+    return;
+  }
+
+  // SUBSCRIBED-mode restriction.
+  if (conn.inSubscribeMode() && !SUBSCRIBE_ALLOWED.has(command.name)) {
+    conn.send(errReply(Errors.unsupportedInSubscribe(command.name)));
+    return;
+  }
+
+  // MULTI queueing.
+  if (conn.txn && !TXN_CONTROL.has(command.name)) {
+    if (!TABLE[command.name]) {
+      conn.txn.error = true;
+      conn.send(errReply(Errors.unknownCmd(command.name, argStrings(command))));
+      return;
+    }
+    conn.txn.queued.push(command);
+    conn.send(R.simple("QUEUED"));
+    return;
+  }
+
+  const reply = executeCore(conn, command, server, nowMs);
+  if (reply !== null) conn.send(reply);
+}
+
+/**
+ * Look up and run a single command, returning its reply (or null if the handler
+ * wrote its own output). Never throws: thrown errors become RESP error replies.
+ */
+export function executeCore(
+  conn: Connection,
+  command: Command,
+  server: ServerContext,
+  nowMs: number,
+): Reply | null {
+  const handler = TABLE[command.name];
+  if (!handler) {
+    return errReply(Errors.unknownCmd(command.name, argStrings(command)));
+  }
+  const ctx = new CommandContext(conn, server, command.args, nowMs);
+  try {
+    return handler(ctx);
+  } catch (err) {
+    return errReply(toRespError(err));
+  }
+}
+
+function errReply(e: { code: string; message: string }): Reply {
+  return R.error(e.code, e.message);
+}
+
+function argStrings(command: Command): string[] {
+  const dec = new TextDecoder();
+  return command.args.slice(1).map((a) => dec.decode(a));
+}

package/src/engine/context.ts

@@ -0,0 +1,95 @@
+/**
+ * CommandContext — everything a command handler needs, plus arg helpers.
+ *
+ * Handlers receive a single context: the connection, the storage engine, the
+ * pub/sub hub, the server registry, and the parsed argument bytes. The helpers
+ * centralize the (binary-safe) byte↔string/number conversions and arity checks
+ * so each handler stays focused on semantics.
+ */
+
+import type { Connection } from "../connection";
+import type { StorageEngine } from "../storage/types";
+import type { PubSubHub } from "../sidecar/pubsub";
+import type { WatchRegistry } from "../sidecar/watch";
+import type { ServerConfig } from "../config";
+import { Errors, NotIntegerError } from "./errors";
+
+export interface ServerContext {
+  readonly storage: StorageEngine;
+  readonly hub: PubSubHub;
+  readonly watch: WatchRegistry;
+  readonly config: ServerConfig;
+}
+
+const decoder = new TextDecoder();
+
+export class CommandContext {
+  constructor(
+    readonly conn: Connection,
+    readonly server: ServerContext,
+    /** All tokens including the command name (args[0]). */
+    readonly args: Uint8Array[],
+    /** Captured once per command so all sub-operations agree on "now". */
+    readonly nowMs: number,
+  ) {}
+
+  get storage(): StorageEngine {
+    return this.server.storage;
+  }
+
+  get cmd(): string {
+    return decoder.decode(this.args[0]).toUpperCase();
+  }
+
+  /** Number of arguments excluding the command name. */
+  get argc(): number {
+    return this.args.length - 1;
+  }
+
+  /** Raw bytes of argument `i` (0-based, excluding command name). */
+  arg(i: number): Uint8Array {
+    const v = this.args[i + 1];
+    if (v === undefined) throw Errors.wrongArgs(this.cmd);
+    return v;
+  }
+
+  /** Optional raw bytes of argument `i`, or undefined if absent. */
+  argOpt(i: number): Uint8Array | undefined {
+    return this.args[i + 1];
+  }
+
+  /** UTF-8 string of argument `i`. */
+  str(i: number): string {
+    return decoder.decode(this.arg(i));
+  }
+
+  /** Upper-cased ASCII of argument `i` (for option keywords). */
+  upper(i: number): string {
+    return this.str(i).toUpperCase();
+  }
+
+  /** Base-10 bigint of argument `i`; throws ERR not-integer on bad input. */
+  int(i: number): bigint {
+    const s = this.str(i).trim();
+    if (!/^[+-]?\d+$/.test(s)) throw new NotIntegerError();
+    return BigInt(s);
+  }
+
+  /** Finite float of argument `i`; throws ERR not-float on bad input. */
+  float(i: number): number {
+    const s = this.str(i).trim();
+    const n = Number(s);
+    if (s.length === 0 || Number.isNaN(n)) throw Errors.notFloat();
+    return n;
+  }
+
+  /** Require at least `n` arguments (excluding command name). */
+  requireArgc(n: number): void {
+    if (this.argc < n) throw Errors.wrongArgs(this.cmd);
+  }
+
+  /** Require exactly `n` arguments (excluding command name). */
+  requireExactArgc(n: number): void {
+    if (this.argc !== n) throw Errors.wrongArgs(this.cmd);
+  }
+}

package/src/engine/errors.ts

@@ -0,0 +1,93 @@
+/**
+ * Domain + RESP error model.
+ *
+ * Command handlers throw {@link RespError}; the dispatcher catches it and emits a
+ * RESP error reply (`-CODE msg`). The storage layer must stay free of Redis
+ * concepts (§3.2), so it throws the generic {@link TypeMismatchError}, which the
+ * command layer translates into a `WRONGTYPE` RespError at the boundary.
+ */
+
+import type { RedisType } from "../storage/types";
+
+/** An error that maps directly to a RESP error reply. `code` is the prefix. */
+export class RespError extends Error {
+  constructor(
+    readonly code: string,
+    override readonly message: string,
+  ) {
+    super(message);
+    this.name = "RespError";
+  }
+}
+
+/**
+ * Thrown by the storage layer when an operation targets a key whose stored type
+ * differs from what the operation expects. Carries no RESP vocabulary.
+ */
+export class TypeMismatchError extends Error {
+  constructor(
+    readonly actual: RedisType,
+    readonly expected: RedisType,
+  ) {
+    super(`type mismatch: have ${actual}, want ${expected}`);
+    this.name = "TypeMismatchError";
+  }
+}
+
+/** Stored value is not a base-10 integer (INCR/DECR/HINCRBY on bad data). */
+export class NotIntegerError extends Error {
+  constructor() {
+    super("value is not an integer or out of range");
+    this.name = "NotIntegerError";
+  }
+}
+
+/** Stored value is not a valid float (INCRBYFLOAT/HINCRBYFLOAT on bad data). */
+export class NotFloatError extends Error {
+  constructor() {
+    super("value is not a valid float");
+    this.name = "NotFloatError";
+  }
+}
+
+const WRONGTYPE_MSG =
+  "Operation against a key holding the wrong kind of value";
+
+export const Errors = {
+  wrongType: () => new RespError("WRONGTYPE", WRONGTYPE_MSG),
+  wrongPass: () =>
+    new RespError("WRONGPASS", "invalid username-password pair or user is disabled."),
+  noAuth: () => new RespError("NOAUTH", "Authentication required."),
+  syntax: () => new RespError("ERR", "syntax error"),
+  notInt: () => new RespError("ERR", "value is not an integer or out of range"),
+  notFloat: () => new RespError("ERR", "value is not a valid float"),
+  wrongArgs: (cmd: string) =>
+    new RespError("ERR", `wrong number of arguments for '${cmd.toLowerCase()}' command`),
+  unknownCmd: (cmd: string, args: string[]) =>
+    new RespError(
+      "ERR",
+      `unknown command '${cmd}', with args beginning with: ${args
+        .slice(0, 1)
+        .map((a) => `'${a}'`)
+        .join(", ")}`,
+    ),
+  unsupportedInSubscribe: (cmd: string) =>
+    new RespError(
+      "ERR",
+      `Can't execute '${cmd.toLowerCase()}': only (P)SUBSCRIBE / (P)UNSUBSCRIBE / PING / QUIT / RESET are allowed in this context`,
+    ),
+  execWithoutMulti: () => new RespError("ERR", "EXEC without MULTI"),
+  discardWithoutMulti: () => new RespError("ERR", "DISCARD without MULTI"),
+  execAbort: () =>
+    new RespError("EXECABORT", "Transaction discarded because of previous errors."),
+} as const;
+
+/** Translate a thrown error into a RESP error, mapping storage errors. */
+export function toRespError(err: unknown): RespError {
+  if (err instanceof RespError) return err;
+  if (err instanceof TypeMismatchError) return Errors.wrongType();
+  if (err instanceof NotIntegerError) return Errors.notInt();
+  if (err instanceof NotFloatError) return Errors.notFloat();
+  const msg = err instanceof Error ? err.message : String(err);
+  return new RespError("ERR", msg);
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Public API of bundis.
+ *
+ * - embedServer(): run the server in the current process (main-process mode).
+ * - spawnServer(): run the server as a separate Bun process (sidecar mode).
+ * - startServer(): lower-level handle taking a full ServerConfig.
+ *
+ * For a standalone daemon, use the CLI: `bun run src/cli.ts` / `bunx bundis`.
+ */
+
+export { startServer, type RunningServer } from "./server";
+export { loadConfig, type ServerConfig } from "./config";
+export {
+  embedServer,
+  spawnServer,
+  READY_EVENT,
+  type LaunchOptions,
+  type EmbeddedServer,
+  type SpawnedServer,
+  type SpawnServerOptions,
+} from "./launch";