@homeflare/alchemy 0.43.0 → 0.45.0

package/src/valkey/provider-socket-fixture.ts

@@ -0,0 +1,71 @@
+/** Test-only RESP listener around the stateful fake. Listener EPERM is a test failure. */
+import * as Effect from 'effect/Effect';
+import { type Socket, createServer } from 'node:net';
+import { type FakeValkey, makeFakeValkey } from './fake-valkey.ts';
+import type { ValkeyReply } from './transport.ts';
+
+const bulk = (value: string | null): string =>
+  value === null ? '$-1\r\n' : `$${Buffer.byteLength(value)}\r\n${value}\r\n`;
+const encode = (reply: ValkeyReply): string => {
+  if (reply.kind === 'error') return `-${reply.message}\r\n`;
+  if (reply.kind === 'bulk') return bulk(reply.value);
+  return `*${reply.values.length}\r\n${reply.values.map(bulk).join('')}`;
+};
+
+const command = (buf: Buffer): { args: string[]; bytes: number } | undefined => {
+  const end = buf.indexOf('\r\n');
+  if (end < 0) return undefined;
+  const count = Number(buf.subarray(1, end).toString());
+  const args: string[] = [];
+  let offset = end + 2;
+  for (let i = 0; i < count; i++) {
+    const lengthEnd = buf.indexOf('\r\n', offset);
+    if (lengthEnd < 0) return undefined;
+    const length = Number(buf.subarray(offset + 1, lengthEnd).toString());
+    const start = lengthEnd + 2;
+    if (buf.length < start + length + 2) return undefined;
+    args.push(buf.subarray(start, start + length).toString());
+    offset = start + length + 2;
+  }
+  return { args, bytes: offset };
+};
+
+export interface ProviderServer {
+  readonly fake: FakeValkey;
+  readonly port: number;
+  readonly close: () => Promise<void>;
+}
+
+export const providerServer = (user: string): Promise<ProviderServer> =>
+  new Promise((resolve, reject) => {
+    const fake = makeFakeValkey({ acl: { [user]: `user ${user} on nopass -@all` } });
+    const peers = new Set<Socket>();
+    const server = createServer((peer) => {
+      peers.add(peer);
+      peer.on('close', () => peers.delete(peer));
+      let pending = Buffer.alloc(0);
+      peer.on('data', (chunk) => {
+        pending = Buffer.concat([pending, chunk]);
+        let parsed = command(pending);
+        while (parsed !== undefined) {
+          pending = pending.subarray(parsed.bytes);
+          peer.write(encode(Effect.runSync(fake.send(parsed.args))));
+          parsed = command(pending);
+        }
+      });
+    });
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address();
+      if (address === null || typeof address === 'string') return reject(new Error('no port'));
+      resolve({
+        fake,
+        port: address.port,
+        close: () =>
+          new Promise((done) => {
+            for (const peer of peers) peer.destroy();
+            server.close(() => done());
+          }),
+      });
+    });
+  });

package/src/valkey/providers.test.ts

@@ -0,0 +1,129 @@
+/** Resolve providers from the public layer, exactly as the engine does. */
+import { expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { ValkeyAclFile } from './acl.ts';
+import { ValkeyInstance } from './instance.ts';
+import { valkeyProviders } from './providers.ts';
+import { resolveValkeyConnection } from './connection-service.ts';
+import { context, required } from './handler-test-fixture.ts';
+import { providerServer } from './provider-socket-fixture.ts';
+
+const config = (instance: string, port: number) => ({ instance, host: '127.0.0.1', port });
+
+test('valkeyProviders retains the named connection for an AclFile provider read', async () => {
+  const server = await providerServer('seat');
+  try {
+    const output = await Effect.runPromise(
+      Effect.gen(function* () {
+        const provider = yield* ValkeyAclFile.Provider;
+        return yield* required(provider.read)({
+          ...context,
+          olds: { instance: 'seats', users: {} },
+          output: undefined,
+        });
+      }).pipe(Effect.provide(valkeyProviders(config('seats', server.port)))),
+    );
+    expect(Object.keys(required(output).users)).toEqual(['seat']);
+    expect(server.fake.commands.map(({ args }) => args)).toEqual([['ACL', 'LIST']]);
+  } finally {
+    await server.close();
+  }
+});
+
+test('combined provider layers route both resources and exclusive ACL writes to their instance', async () => {
+  const seats = await providerServer('seat');
+  try {
+    const cache = await providerServer('cache');
+    try {
+      await Effect.runPromise(
+        Effect.gen(function* () {
+          const acl = yield* ValkeyAclFile.Provider;
+          const instance = yield* ValkeyInstance.Provider;
+          for (const [name, server, user] of [
+            ['seats', seats, 'seat'],
+            ['cache', cache, 'cache'],
+          ] as const) {
+            const props = { instance: name, users: {}, exclusive: true };
+            const read = yield* required(acl.read)({ ...context, olds: props, output: undefined });
+            expect(Object.keys(required(read).users)).toEqual([user]);
+            const before = server.fake.commands.length;
+            yield* required(instance.read)({
+              ...context,
+              olds: { name, port: server.port },
+              output: undefined,
+            });
+            expect(server.fake.commands.slice(before).map(({ args }) => args[0])).toEqual([
+              'INFO',
+              'CONFIG',
+            ]);
+            yield* acl.reconcile({ ...context, news: props, olds: props, output: undefined });
+            expect(server.fake.acl.size).toBe(0);
+            if (name === 'seats') expect(cache.fake.acl.has('cache')).toBe(true);
+          }
+        }).pipe(
+          Effect.provide(
+            Layer.mergeAll(
+              valkeyProviders(config('seats', seats.port)),
+              valkeyProviders(config('cache', cache.port)),
+            ),
+          ),
+        ),
+      );
+    } finally {
+      await cache.close();
+    }
+  } finally {
+    await seats.close();
+  }
+});
+
+test('named connection selection survives either layer order without a listener', async () => {
+  const layers = [
+    valkeyProviders(config('seats', 56380)),
+    valkeyProviders(config('cache', 56381)),
+  ] as const;
+  for (const providers of [Layer.mergeAll(...layers), Layer.mergeAll(layers[1], layers[0])]) {
+    await Effect.runPromise(
+      Effect.gen(function* () {
+        expect((yield* resolveValkeyConnection('seats')).port).toBe(56380);
+        expect((yield* resolveValkeyConnection('cache')).port).toBe(56381);
+        const provider = yield* ValkeyAclFile.Provider;
+        const error = yield* Effect.flip(
+          required(provider.read)({
+            ...context,
+            olds: { instance: 'typo', users: {} },
+            output: undefined,
+          }),
+        );
+        expect(error._tag).toBe('ValkeyConnectionMissing');
+        expect(error.instance).toBe('typo');
+      }).pipe(Effect.provide(providers)),
+    );
+  }
+});
+
+test('refused socket acquisition maps all ACL operations to ValkeyInstanceUnreachable', async () => {
+  const server = await providerServer('seat');
+  const port = server.port;
+  await server.close();
+  await Effect.runPromise(
+    Effect.gen(function* () {
+      const provider = yield* ValkeyAclFile.Provider;
+      const props = { instance: 'seats', users: {} };
+      for (const operation of [
+        required(provider.read)({ ...context, olds: props, output: undefined }),
+        provider.reconcile({ ...context, news: props, olds: props, output: undefined }),
+        provider.delete({ ...context, olds: props, output: props }),
+      ]) {
+        const error = yield* Effect.flip(operation);
+        expect(error).toMatchObject({
+          _tag: 'ValkeyInstanceUnreachable',
+          instance: 'seats',
+          host: '127.0.0.1',
+          port,
+        });
+      }
+    }).pipe(Effect.provide(valkeyProviders(config('seats', port)))),
+  );
+});

package/src/valkey/providers.ts

@@ -0,0 +1,21 @@
+/**
+ * The Valkey provider, pre-wired to one instance:
+ *
+ *     const providers = valkeyProviders({ instance: 'valkey-seats', host: '127.0.0.1', port: 6381 });
+ *
+ * ★ THE INSTANCE IS A PARAMETER, NOT A DEFAULT (S15). This kit is PUBLIC; CT100's host, the two
+ *   ports (6380/6381) and the ACL user a seat authenticates as are the CONSUMING stack's values,
+ *   never baked in here. Each resource selects the connection by its instance name, so the
+ *   fixed provider tags cannot redirect one instance's ACL to another server.
+ */
+import * as Layer from 'effect/Layer';
+import { ValkeyAclFileProvider } from './acl.ts';
+import { type ValkeyConnectionConfig, valkeyConnection } from './connection.ts';
+import { ValkeyInstanceProvider } from './instance.ts';
+
+// ⚠️ As in postgres/providers.ts and caddy/providers.ts, plain provide hides the connection
+//   from lifecycle handlers invoked later by Alchemy. Keep the named service in the output.
+export const valkeyProviders = (config: ValkeyConnectionConfig & { readonly instance: string }) =>
+  Layer.mergeAll(ValkeyInstanceProvider(), ValkeyAclFileProvider()).pipe(
+    Layer.provideMerge(valkeyConnection(config)),
+  );

package/src/valkey/resp.ts

@@ -0,0 +1,212 @@
+/**
+ * One RESP reply, pulled off the socket this family owns.
+ *
+ * ⛔ THE SERVER'S `$N` / `*N` IS NOT A BUDGET. `INFO`, `ACL LIST` and `CONFIG GET` are
+ *   small. `$2147483647` or `*1000000000` would grow memory or loop in the same process
+ *   that holds every other provider (measured 2026-09-30: both reads stayed pending).
+ *   Past the cap the read fails `ValkeySocketError` before it waits for the body.
+ * ★ THE PER-READ DEADLINE DOES NOT RESET WHEN A BYTE ARRIVES. `socket.setTimeout` is an
+ *   idle timer; a peer that dribbles would stretch it. This abort does not.
+ */
+import * as Effect from 'effect/Effect';
+import type { Socket } from 'node:net';
+import {
+  type ValkeyReply,
+  ValkeyServerError,
+  ValkeySocketError,
+  type ValkeyTransportError,
+} from './transport-error.ts';
+
+/** 1 MiB. The three replies this family reads are kilobytes. */
+export const MAX_BULK_BYTES = 1_048_576;
+
+/** `ACL LIST` is one element per user; `CONFIG GET` is two per key. */
+export const MAX_ARRAY_ITEMS = 10_000;
+
+const CRLF = '\r\n';
+
+/** A mutable buffer shared between recursive RESP reads so array items consume bytes
+ * from the same stream the outer `*` marker was read from. */
+export interface ReadBuf {
+  buf: Buffer;
+  /** Bytes already accepted in this reply. A sum of in-cap bulks must not pass the cap either. */
+  taken: number;
+}
+
+/** The in-flight read, so a lifetime `error` listener can fail it. `fail` is `null` when
+ * no read is waiting — `undefined` is not assignable under `exactOptionalPropertyTypes`. */
+export interface InFlight {
+  fail: ((reason: string) => void) | null;
+}
+
+type ParsedLine = { readonly value: string; readonly drop: number } | undefined;
+
+/** `-1` (RESP nil) or a non-negative integer at most `cap`. Anything else is a refusal. */
+const boundedCount = (raw: string, cap: number): number | undefined => {
+  if (!/^(?:-1|\d+)$/.test(raw)) return undefined;
+  const n = Number(raw);
+  if (!Number.isSafeInteger(n) || n > cap) return undefined;
+  return n;
+};
+
+const readUntil = (
+  socket: Socket,
+  state: ReadBuf,
+  inFlight: InFlight,
+  timeoutMs: number,
+  done: (buffer: Buffer) => ParsedLine,
+): Effect.Effect<string, ValkeySocketError> =>
+  Effect.tryPromise({
+    try: (signal) =>
+      new Promise<string>((resolve, reject) => {
+        let settled = false;
+        // Assigned only when this read has to wait. The early path (bytes already buffered)
+        // never registers listeners, so they live on one object the finish path can clear.
+        const wait: {
+          timer?: ReturnType<typeof setTimeout>;
+          onData?: (chunk: Buffer) => void;
+          onEnd?: () => void;
+        } = {};
+        const finish = (fn: () => void) => {
+          if (settled) return;
+          settled = true;
+          if (wait.timer !== undefined) clearTimeout(wait.timer);
+          if (wait.onData !== undefined) socket.off('data', wait.onData);
+          if (wait.onEnd !== undefined) socket.off('end', wait.onEnd);
+          signal.removeEventListener('abort', onAbort);
+          if (inFlight.fail === failRead) inFlight.fail = null;
+          fn();
+        };
+        const failRead = (reason: string) => {
+          finish(() => reject(new ValkeySocketError({ reason })));
+        };
+        const onAbort = () => failRead('read interrupted');
+        const settle = (parsed: Exclude<ParsedLine, undefined>) => {
+          state.buf = state.buf.subarray(parsed.drop);
+          finish(() => resolve(parsed.value));
+        };
+        // Pull first: the bytes this read needs may already be in the buffer.
+        const immediate = done(state.buf);
+        if (immediate !== undefined) {
+          settle(immediate);
+          return;
+        }
+        if (socket.readableEnded || socket.destroyed) {
+          failRead('socket closed mid-reply');
+          return;
+        }
+        wait.onData = (chunk: Buffer) => {
+          state.buf = Buffer.concat([state.buf, chunk]);
+          // A length line with no CRLF would otherwise buffer until the peer stopped.
+          if (state.buf.length > MAX_BULK_BYTES + 64) {
+            failRead(`reply exceeded ${String(MAX_BULK_BYTES)} bytes`);
+            return;
+          }
+          const parsed = done(state.buf);
+          if (parsed === undefined) return;
+          settle(parsed);
+        };
+        wait.onEnd = () => failRead('socket closed mid-reply');
+        wait.timer = setTimeout(() => failRead('socket timed out'), timeoutMs);
+        inFlight.fail = failRead;
+        signal.addEventListener('abort', onAbort);
+        socket.on('data', wait.onData);
+        socket.on('end', wait.onEnd);
+      }),
+    catch: (cause) =>
+      cause instanceof ValkeySocketError ? cause : new ValkeySocketError({ reason: String(cause) }),
+  });
+
+/**
+ * Read one RESP value. Recursion depth is the protocol's nesting, and this family
+ * rejects nesting rather than flattening it — see the nested-array branch.
+ *
+ * ★ PULL FIRST, THEN LISTEN. A reply the socket delivered whole sits in `state.buf`
+ *   before this read begins. Only a genuinely incomplete prefix waits for the next chunk.
+ */
+export const readReply = (
+  socket: Socket,
+  state: ReadBuf,
+  command: string,
+  inFlight: InFlight,
+  timeoutMs: number,
+): Effect.Effect<ValkeyReply, ValkeyTransportError> => {
+  const readLine = (): Effect.Effect<string, ValkeySocketError> =>
+    readUntil(socket, state, inFlight, timeoutMs, (buffer) => {
+      const nl = buffer.indexOf(CRLF);
+      return nl === -1
+        ? undefined
+        : { value: buffer.subarray(0, nl).toString('utf8'), drop: nl + 2 };
+    });
+
+  const readBytes = (n: number): Effect.Effect<string, ValkeySocketError> =>
+    Effect.gen(function* () {
+      if (state.taken + n > MAX_BULK_BYTES) {
+        return yield* Effect.fail(
+          new ValkeySocketError({
+            reason: `reply exceeded ${String(MAX_BULK_BYTES)} bytes`,
+          }),
+        );
+      }
+      state.taken += n;
+      return yield* readUntil(socket, state, inFlight, timeoutMs, (buffer) =>
+        buffer.length < n + 2
+          ? undefined
+          : { value: buffer.subarray(0, n).toString('utf8'), drop: n + 2 },
+      );
+    });
+
+  return Effect.gen(function* () {
+    const line = yield* readLine();
+    const prefix = line[0];
+    if (prefix === '+') return { kind: 'bulk', value: line.slice(1) } as const;
+    if (prefix === '-') {
+      return yield* Effect.fail(new ValkeyServerError({ detail: line.slice(1) }));
+    }
+    if (prefix === '$') {
+      const n = boundedCount(line.slice(1), MAX_BULK_BYTES);
+      if (n === undefined) {
+        return yield* Effect.fail(
+          new ValkeySocketError({
+            reason: `bulk length ${line.slice(1)} exceeds ${String(MAX_BULK_BYTES)}`,
+          }),
+        );
+      }
+      if (n === -1) return { kind: 'bulk', value: null } as const;
+      return { kind: 'bulk', value: yield* readBytes(n) } as const;
+    }
+    if (prefix === '*') {
+      const n = boundedCount(line.slice(1), MAX_ARRAY_ITEMS);
+      if (n === undefined) {
+        return yield* Effect.fail(
+          new ValkeySocketError({
+            reason: `array length ${line.slice(1)} exceeds ${String(MAX_ARRAY_ITEMS)}`,
+          }),
+        );
+      }
+      if (n === -1) return { kind: 'array', values: [] } as const;
+      const values: Array<string | null> = [];
+      for (let i = 0; i < n; i += 1) {
+        const item = yield* readReply(socket, state, command, inFlight, timeoutMs);
+        // ⛔ A NESTED ARRAY IS A REPLY THIS FAMILY DOES NOT UNDERSTAND — failing beats
+        //   null-flattening it: `values` is typed flat, so a `*1` inside `ACL GETUSER` would
+        //   silently lose every flag, password and command rule it carries. The commands this
+        //   family reads (`ACL LIST`, `CONFIG GET`) answer flat arrays; a future command that
+        //   needs nesting must extend this union with a test, not hope.
+        if (item.kind !== 'bulk') {
+          return yield* Effect.fail(
+            new ValkeyServerError({
+              detail: `nested array inside the reply to ${command}: this family reads only flat arrays`,
+            }),
+          );
+        }
+        values.push(item.value);
+      }
+      return { kind: 'array', values } as const;
+    }
+    if (prefix === ':') return { kind: 'bulk', value: line.slice(1) } as const;
+    return yield* Effect.fail(
+      new ValkeyServerError({ detail: `unexpected RESP prefix ${prefix}` }),
+    );
+  });
+};

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

@@ -0,0 +1,150 @@
+/**
+ * Bounds on the socket this family owns. `transport.test.ts` covers split replies and
+ * `end`; these cases are the ones that stall or kill a deploy: an `error` after connect,
+ * a reply length the server names, and a deadline on a socket that never answers.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { EventEmitter } from 'node:events';
+import { type Socket as NetSocket, createServer } from 'node:net';
+import { valkeyConnection, withValkey } from './connection.ts';
+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;
+};
+
+const push = async (socket: ScriptedSocket, chunk: string): Promise<void> => {
+  await new Promise<void>((resolve) => {
+    setTimeout(() => {
+      socket.emit('data', Buffer.from(chunk));
+      resolve();
+    }, 0);
+  });
+};
+
+const send = (socket: ScriptedSocket, chunks: ReadonlyArray<string>): Promise<ValkeyReply> => {
+  const pending = Effect.runPromise(makeSocketExecutor(socket as never).send(['INFO']));
+  return chunks
+    .reduce((chain, chunk) => chain.then(() => push(socket, chunk)), Promise.resolve())
+    .then(() => pending);
+};
+
+const tagOf = async (pending: Promise<unknown>): Promise<{ _tag?: string; reason?: string }> =>
+  (await pending.catch((cause: unknown) => cause)) as { _tag?: string; reason?: string };
+
+const listen = (hold: boolean): Promise<{ port: number; close: () => Promise<void> }> =>
+  new Promise((resolve, reject) => {
+    const peers: NetSocket[] = [];
+    const server = createServer((peer) => {
+      peers.push(peer);
+      if (!hold) peer.resetAndDestroy();
+    });
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address();
+      const port = typeof address === 'object' && address !== null ? address.port : 0;
+      resolve({
+        port,
+        close: () =>
+          new Promise((done) => {
+            for (const peer of peers) peer.destroy();
+            server.close(() => done());
+          }),
+      });
+    });
+  });
+
+describe('socket error after connect', () => {
+  test('an error during a read is ValkeySocketError, not an uncaught throw', async () => {
+    const socket = scriptedSocket();
+    const executor = makeSocketExecutor(socket as never, 500);
+    const pending = Effect.runPromise(executor.send(['PING']));
+    await new Promise<void>((resolve) => setTimeout(resolve, 0));
+    expect(() => socket.emit('error', new Error('read ECONNRESET'))).not.toThrow();
+    const error = await tagOf(pending);
+    expect(error._tag).toBe('ValkeySocketError');
+    expect(error.reason).toContain('ECONNRESET');
+  });
+
+  test('an error with no in-flight read does not throw', () => {
+    const socket = scriptedSocket();
+    makeSocketExecutor(socket as never);
+    expect(() => socket.emit('error', new Error('read ECONNRESET'))).not.toThrow();
+  });
+
+  test('a peer RST during a read returns ValkeySocketError', async () => {
+    const server = await listen(false);
+    try {
+      const error = await Effect.runPromise(
+        Effect.flip(
+          withValkey((executor) => executor.send(['PING'])).pipe(
+            Effect.provide(
+              valkeyConnection({ host: '127.0.0.1', port: server.port, timeoutMs: 1_000 }),
+            ),
+          ),
+        ),
+      );
+      expect((error as { _tag?: string })._tag).toBe('ValkeySocketError');
+    } finally {
+      await server.close();
+    }
+  });
+});
+
+describe('reply caps', () => {
+  test('a bulk length of 2147483647 fails instead of waiting for the body', async () => {
+    const error = await tagOf(send(scriptedSocket(), ['$2147483647\r\n']));
+    expect(error._tag).toBe('ValkeySocketError');
+  });
+
+  test('an array count of 1000000000 fails instead of looping', async () => {
+    const error = await tagOf(send(scriptedSocket(), ['*1000000000\r\n']));
+    expect(error._tag).toBe('ValkeySocketError');
+  });
+});
+
+describe('deadlines on a real socket', () => {
+  test('connect to a blackholed host fails with ValkeySocketError', async () => {
+    const started = Date.now();
+    const error = await Effect.runPromise(
+      Effect.flip(
+        withValkey((executor) => executor.send(['PING'])).pipe(
+          Effect.provide(valkeyConnection({ host: '192.0.2.1', port: 1, timeoutMs: 200 })),
+        ),
+      ),
+    );
+    expect((error as { _tag?: string })._tag).toBe('ValkeySocketError');
+    expect(Date.now() - started).toBeLessThan(1_500);
+  });
+
+  test('an accepted socket that sends nothing fails with ValkeySocketError', async () => {
+    const server = await listen(true);
+    const started = Date.now();
+    try {
+      const error = await Effect.runPromise(
+        Effect.flip(
+          withValkey((executor) => executor.send(['PING'])).pipe(
+            Effect.provide(
+              valkeyConnection({ host: '127.0.0.1', port: server.port, timeoutMs: 200 }),
+            ),
+          ),
+        ),
+      );
+      expect((error as { _tag?: string })._tag).toBe('ValkeySocketError');
+      expect(Date.now() - started).toBeLessThan(1_500);
+    } finally {
+      await server.close();
+    }
+  });
+});

package/src/valkey/transport-error.ts

@@ -0,0 +1,37 @@
+/**
+ * Transport failures and the reply shapes a `ValkeyExecutor` returns.
+ *
+ * Split from `transport.ts` so the RESP reader can fail these tags without importing
+ * the executor. `transport.ts` re-exports them; callers keep importing from there.
+ */
+import * as Data from 'effect/Data';
+
+export type ValkeyReply =
+  | { readonly kind: 'bulk'; readonly value: string | null }
+  | { readonly kind: 'array'; readonly values: ReadonlyArray<string | null> }
+  | { readonly kind: 'error'; readonly message: string };
+
+/** A reply that came back as an error line (`-ERR …`). `detail` is the server's own error text;
+ * the `message` getter names it without recursing. */
+export class ValkeyServerError extends Data.TaggedError('ValkeyServerError')<{
+  readonly detail: string;
+}> {
+  override get message(): string {
+    return this.detail;
+  }
+}
+
+/** A socket-level failure (connection refused, reset, closed mid-reply, a reply past the cap,
+ * a deadline) — distinct from a protocol-level `ValkeyServerError` so callers can tell "server
+ * said no" from "never reached it" or "the socket this family owns was not bounded". */
+export class ValkeySocketError extends Data.TaggedError('ValkeySocketError')<{
+  readonly reason: string;
+}> {
+  override get message(): string {
+    return this.reason;
+  }
+}
+
+/** The two transport-level failures every `ValkeyExecutor` can surface, as one union so a
+ * caller's declared error channel stays short. */
+export type ValkeyTransportError = ValkeyServerError | ValkeySocketError;