@homeflare/alchemy 0.43.0 → 0.45.0

package/src/valkey/transport.test.ts

@@ -0,0 +1,158 @@
+/**
+ * The RESP parser against a scripted `node:net` socket — the byte-level cases a recording fake
+ * `ValkeyExecutor` cannot reach, because the fake answers `ValkeyReply` objects and never crosses
+ * the wire. Two classes of bug live only here: a reply that arrives SPLIT across `data` chunks
+ * (the parser must wait mid-token), and a reply that arrives WHOLE in one chunk while the parser
+ * needs several sequential reads (nested arrays, bulk-after-array) — the second is the bug this
+ * file was written to catch, measured on the 9.1.1 scratch on 2026-09-29: without the
+ * read-once-before-listening pull, the bytes sat in the buffer while the parser waited for a
+ * `data` event that had already fired.
+ *
+ * ⛔ THE MOCK IS A `Socket`-SHAPED OBJECT, NOT A REAL SOCKET. `readReply` touches `on`, `off`,
+ *   `write`, `readableEnded` and `destroyed` and nothing else, so an event emitter with a sink
+ *   for `write` is the whole contract; a live server would add a second source of truth, not a
+ *   test.
+ * ★ ONE `data` EVENT PER MACROTASK, like a real socket: Effect's continuation between two reads
+ *   runs as a microtask, which a real socket always lets finish before the next chunk arrives.
+ *   Emitting two chunks in one macrotask would swallow the second and hang — a test bug, not a
+ *   parser property.
+ */
+import { describe, expect, test } from 'bun:test';
+import { EventEmitter } from 'node:events';
+import * as Effect from 'effect/Effect';
+import { type ValkeyReply, makeSocketExecutor } from './transport.ts';
+
+interface ScriptedSocket extends EventEmitter {
+  write: (data: string) => boolean;
+  readableEnded: boolean;
+  destroyed: boolean;
+}
+
+const scriptedSocket = (): ScriptedSocket => {
+  const socket = new EventEmitter() as ScriptedSocket;
+  socket.write = () => true;
+  socket.readableEnded = false;
+  socket.destroyed = false;
+  return socket;
+};
+
+/** One chunk per macrotask, in order — the timing of a real TCP socket. */
+const push = async (socket: ScriptedSocket, ...chunks: Array<string | Buffer>): Promise<void> => {
+  for (const chunk of chunks) {
+    await new Promise<void>((resolve) => {
+      setTimeout(() => {
+        socket.emit('data', Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        resolve();
+      }, 0);
+    });
+  }
+};
+
+/** Send a command and let the scripted reply arrive. Returns the promise so a test can also
+ * assert on a rejection. */
+const send = (
+  socket: ScriptedSocket,
+  args: ReadonlyArray<string>,
+  chunks: Array<string | Buffer>,
+): Promise<ValkeyReply> => {
+  const executor = makeSocketExecutor(socket as never);
+  const pending = Effect.runPromise(executor.send(args));
+  return push(socket, ...chunks).then(() => pending) as Promise<ValkeyReply>;
+};
+
+describe('flat replies', () => {
+  test('a simple string arrives as a bulk value', async () => {
+    expect(await send(scriptedSocket(), ['PING'], ['+PONG\r\n'])).toEqual({
+      kind: 'bulk',
+      value: 'PONG',
+    });
+  });
+
+  test('a nil bulk is null, not the empty string', async () => {
+    expect(await send(scriptedSocket(), ['GET', 'x'], ['$-1\r\n'])).toEqual({
+      kind: 'bulk',
+      value: null,
+    });
+  });
+
+  test('an integer reply carries its digits as a bulk value', async () => {
+    expect(await send(scriptedSocket(), ['DEL', 'x'], [':2\r\n'])).toEqual({
+      kind: 'bulk',
+      value: '2',
+    });
+  });
+
+  test('an error line fails with the server tag, not a die', async () => {
+    const socket = scriptedSocket();
+    const error = (await send(socket, ['ACL', 'LIST'], ['-ERR unknown command\r\n']).catch(
+      (cause: unknown) => cause,
+    )) as { _tag?: string; detail?: string };
+    expect(error._tag).toBe('ValkeyServerError');
+    expect(error.detail).toBe('ERR unknown command');
+  });
+});
+
+describe('split and accumulated chunks', () => {
+  test('a bulk split mid-length and mid-body is reassembled', async () => {
+    const reply = await send(scriptedSocket(), ['INFO'], ['$9\r\nred', 'isvers\r\n']);
+    expect(reply).toEqual({ kind: 'bulk', value: 'redisvers' });
+  });
+
+  test('a flat array split across three chunks is reassembled in order', async () => {
+    const reply = await send(
+      scriptedSocket(),
+      ['ACL', 'LIST'],
+      ['*2\r\n$4\r\n', 'user\r', '\n$5\r\ncs-ar\r\n'],
+    );
+    expect(reply).toEqual({ kind: 'array', values: ['user', 'cs-ar'] });
+  });
+
+  test('a whole nested-array reply in ONE chunk is read to the end — the 2026-09-29 hang', async () => {
+    // `ACL GETUSER`'s real shape on Valkey 9.1.1: outer `*N`, some items nested `*1`/`*0`
+    // arrays. This family reads only flat arrays, so the parser must FAIL LOUDLY on the nested
+    // item instead of null-flattening it — and must never hang waiting for bytes it holds.
+    const socket = scriptedSocket();
+    const chunk = '*2\r\n$2\r\nok\r\n*2\r\n$1\r\na\r\n$1\r\nb\r\n';
+    const error = (await send(socket, ['ACL', 'GETUSER', 'x'], [chunk]).catch(
+      (cause: unknown) => cause,
+    )) as { _tag?: string; detail?: string };
+    expect(error._tag).toBe('ValkeyServerError');
+    expect(error.detail).toContain('nested array');
+  });
+
+  test('sequential sends on one socket each start a fresh reply buffer', async () => {
+    const socket = scriptedSocket();
+    const executor = makeSocketExecutor(socket as never);
+    const first = Effect.runPromise(executor.send(['PING']));
+    await push(socket, '+PONG\r\n');
+    expect(await first).toEqual({ kind: 'bulk', value: 'PONG' });
+    const second = Effect.runPromise(executor.send(['PING']));
+    await push(socket, '+PONG\r\n');
+    expect(await second).toEqual({ kind: 'bulk', value: 'PONG' });
+  });
+});
+
+describe('a socket that closes', () => {
+  test('closed before the read starts fails fast instead of hanging', async () => {
+    const socket = scriptedSocket();
+    socket.readableEnded = true;
+    const error = (await Effect.runPromise(
+      makeSocketExecutor(socket as never).send(['PING']),
+    ).catch((cause: unknown) => cause)) as { _tag?: string };
+    expect(error._tag).toBe('ValkeySocketError');
+  });
+
+  test('closed mid-reply rejects the pending read', async () => {
+    const socket = scriptedSocket();
+    const executor = makeSocketExecutor(socket as never);
+    const pending = Effect.runPromise(executor.send(['INFO']));
+    await push(socket, '$10\r\nred'); // partial bulk, then the server goes away
+    socket.emit('end');
+    const error = (await pending.catch((cause: unknown) => cause)) as {
+      _tag?: string;
+      reason?: string;
+    };
+    expect(error._tag).toBe('ValkeySocketError');
+    expect(error.reason).toBe('socket closed mid-reply');
+  });
+});

package/src/valkey/transport.ts

@@ -0,0 +1,109 @@
+/**
+ * The RESP wire the `Valkey` family speaks, hand-rolled the same way `postgres/database-sql.ts`
+ * hand-rolls its four statements: there is no `@distilled.cloud/valkey` SDK (registry 404, checked
+ * 2026-09-29), and `effect@4.0.0-rc.115` ships no Valkey/Redis client, so the family declares a
+ * `ValkeyExecutor` seam — the real socket client below, or `fake-valkey.ts` in tests — and every
+ * lifecycle function depends only on that small interface, never on `node:net`.
+ * ★ Alchemy beta.79 DOES ship Redis.connect. Its internal parser/queue cannot enforce our
+ *   reply caps before allocating, and it exposes no deadline settings. The audited exception
+ *   and executable measurements are in `docs/valkey-transport.md`.
+ *
+ * ⛔ RESP, NOT A TAG TO VALKEY'S C VERSION. The protocol is line-and-prefix oriented and stable
+ *   across Valkey's releases; the commands this family issues (`INFO`, `CONFIG GET`, `ACL LIST`,
+ *   `ACL SETUSER`, `PING`) are all long-settled. Nothing here parses a version-specific field.
+ * ★ RUNTIME-NEUTRAL. The executor is a function of `node:net` sockets, no Bun API; a Bun-only
+ *   consumer would be a regression the postgres family's own `PgClient` avoided.
+ * ⛔ AN `error` EVENT WITH NO LISTENER EXITS THE PROCESS. `openSocket` listens only until
+ *   `connect`. This executor installs the listener that stays for the life of the socket, and
+ *   fails the in-flight read with `ValkeySocketError` (measured 2026-09-30: a peer RST after
+ *   the connect listener was dropped was `uncaughtException` `read ECONNRESET`, exit 1).
+ */
+import * as Effect from 'effect/Effect';
+import type { Socket } from 'node:net';
+import { type InFlight, type ReadBuf, readReply } from './resp.ts';
+import {
+  type ValkeyReply,
+  ValkeySocketError,
+  type ValkeyTransportError,
+} from './transport-error.ts';
+
+export type { ValkeyReply, ValkeyTransportError } from './transport-error.ts';
+export { ValkeyServerError, ValkeySocketError } from './transport-error.ts';
+
+/** One command with its arguments, as the byte strings that go on the wire. */
+export interface ValkeyCommand {
+  readonly args: ReadonlyArray<string>;
+}
+
+/** The smallest thing a lifecycle function needs from a client: send one command, read the reply
+ * as one of the three RESP top-level shapes the family interprets — a bulk string, a flat array of
+ * bulk strings, or an error. `null` is the RESP "nil" reply (a missing key). Failures are the two
+ * transport tags: a server error reply, or a socket failure. */
+export interface ValkeyExecutor {
+  readonly send: (args: ReadonlyArray<string>) => Effect.Effect<ValkeyReply, ValkeyTransportError>;
+}
+
+/** The per-read abort, and the idle/`connect` deadline `withValkey` sets on the socket. */
+export const DEFAULT_SOCKET_TIMEOUT_MS = 10_000;
+
+const CRLF = '\r\n';
+
+const encodeArgs = (args: ReadonlyArray<string>): string =>
+  `*${args.length}${CRLF}${args.map((a) => `$${Buffer.byteLength(a)}${CRLF}${a}`).join(CRLF)}${CRLF}`;
+
+/**
+ * The real executor over a `node:net` socket. `socket` is supplied by the caller (which owns
+ * connect/close), so `withValkey` can open one socket per operation and close it after.
+ * `timeoutMs` bounds each read; the default matches the socket deadline in `connection.ts`.
+ */
+export const makeSocketExecutor = (
+  socket: Socket,
+  timeoutMs: number = DEFAULT_SOCKET_TIMEOUT_MS,
+): ValkeyExecutor => {
+  const inFlight: InFlight = { fail: null };
+  let socketFailure: string | undefined;
+  const onError = (error: Error) => {
+    socketFailure = error.message;
+    inFlight.fail?.(error.message);
+  };
+  socket.on('error', onError);
+  return {
+    send: (args) => {
+      if (socketFailure !== undefined || socket.destroyed) {
+        return Effect.fail(new ValkeySocketError({ reason: socketFailure ?? 'socket closed' }));
+      }
+      const state: ReadBuf = { buf: Buffer.alloc(0), taken: 0 };
+      // Command name only. The full argv of `AUTH` / `ACL SETUSER` includes `>password`.
+      const command = args[0] ?? 'command';
+      try {
+        socket.write(encodeArgs(args));
+      } catch (cause) {
+        return Effect.fail(
+          new ValkeySocketError({
+            reason: cause instanceof Error ? cause.message : String(cause),
+          }),
+        );
+      }
+      // `write` can emit `error` synchronously (a peer RST already in the buffer). The
+      // lifetime listener stashes it; failing here beats starting a read nothing will answer.
+      if (socketFailure !== undefined || socket.destroyed) {
+        return Effect.fail(new ValkeySocketError({ reason: socketFailure ?? 'socket closed' }));
+      }
+      return readReply(socket, state, command, inFlight, timeoutMs);
+    },
+  };
+};
+
+/**
+ * Decode a flat array reply into `Map<string, string | null>` for the `key value key value`
+ * shape `CONFIG GET` answers. Null values are preserved; a missing key is `null`, never `''`.
+ */
+export const arrayPairs = (
+  values: ReadonlyArray<string | null>,
+): ReadonlyMap<string, string | null> => {
+  const out = new Map<string, string | null>();
+  for (let i = 0; i + 1 < values.length; i += 2) {
+    out.set(values[i] ?? '', values[i + 1] ?? null);
+  }
+  return out;
+};

package/src/valkey/upstream-bounds.test.ts

@@ -0,0 +1,14 @@
+/** Executable evidence for the documented beta.79 transport exception; no listener required. */
+import { expect, test } from 'bun:test';
+import { Parser } from 'alchemy/Redis';
+
+test('upstream accepts replies beyond this provider’s byte and array caps', () => {
+  const bytes = new TextEncoder();
+  const bulk = new Parser();
+  const length = 1024 * 1024 + 1;
+  bulk.push(bytes.encode(`$${length}\r\n${'x'.repeat(length)}\r\n`));
+  expect(bulk.next()._tag).toBe('Reply');
+  const array = new Parser();
+  array.push(bytes.encode(`*10001\r\n${'$-1\r\n'.repeat(10001)}`));
+  expect(array.next()._tag).toBe('Reply');
+});