@compforge/harness-toolbox 0.4.2 → 0.4.3

package/README.md

@@ -62,6 +62,26 @@ never close it themselves.
 Version 0.4.2 requires Common 0.5.4. Replace single path arguments with arrays, supply `maxTotalBytes`,
 and handle per-file results. Publish Common before Toolbox; this change has no single-file legacy adapter.
 
+## Redis sources
+
+`RedisClient` owns resolved configuration and reusable node connections. Use `clusterType` to
+select `single`, `cluster` or `sentinel`; `endpoints` contains that mode's seed addresses. Sentinel
+configuration additionally provides `sentinelMasterName` and optional Sentinel credentials,
+separate from data-node credentials. Cluster connections require database zero.
+
+Supply ordered TCP transports through `ConnectionSource`. Only mapping or handshake network
+failures advance to the next transport; authentication and TLS verification failures stop immediately.
+`connectTimeoutMs` bounds each route (mapping and handshake); it defaults to the command
+`timeoutMs`. `acquireTimeoutMs` bounds all candidates together and defaults to the per-route budget
+times the number of routes. A spent total budget does not start another route.
+`onRoute` reports the selected route and the preceding failure code without credentials.
+
+`client.topology()` refreshes topology using the same connections and route policy as
+`client.access.connection(endpoint, database)`. A root signal cancels connection preparation and
+active commands. Commands and pipelines are sent once, with no offline queue or automatic replay;
+a subsequent acquisition replaces an unhealthy connection. The caller owns `dispose()` and transport
+cleanup, and diagnostics own sampling policy and collected observations.
+
 ## Kubernetes resources
 
 Borrow a root `KubernetesClient` through `KubernetesEnvironment` and `ClientManager`. Use

package/dist/{chunk-c6z919qb.js → chunk-5tbzf9wd.js}

@@ -26,7 +26,7 @@ function sentinelRows(value) {
   });
 }
 async function discoverSentinel(access, config) {
-  const sentinels = config.sentinelHosts.length ? config.sentinelHosts : config.endpoints;
+  const sentinels = config.endpoints;
   let lastError;
   for (const sentinel of sentinels) {
     try {

package/dist/chunk-yp6tcw22.js

@@ -0,0 +1,366 @@
+import {
+  discoverRedisTopology
+} from "./chunk-5tbzf9wd.js";
+import {
+  ToolboxError
+} from "./chunk-20kv4wc3.js";
+import {
+  isConnectionNetworkError
+} from "./chunk-h8fwx0k7.js";
+
+// src/redis/client.ts
+import { createClient, SocketClosedUnexpectedlyError, ConnectionTimeoutError } from "@redis/client";
+function stringValue(value) {
+  if (Buffer.isBuffer(value))
+    return value.toString("utf8");
+  return String(value ?? "");
+}
+function scalar(value) {
+  if (/^-?(?:\d+|\d+\.\d+)$/.test(value))
+    return Number(value);
+  return value;
+}
+function parseRedisInfo(raw) {
+  const result = {};
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line || line.startsWith("#"))
+      continue;
+    const separator = line.indexOf(":");
+    if (separator < 1)
+      continue;
+    const name = line.slice(0, separator);
+    const value = line.slice(separator + 1);
+    if (/^db\d+$/.test(name)) {
+      result[name] = Object.fromEntries(value.split(",").map((item) => {
+        const index = item.indexOf("=");
+        return [item.slice(0, index), scalar(item.slice(index + 1))];
+      }));
+    } else {
+      result[name] = scalar(value);
+    }
+  }
+  return result;
+}
+async function abortable(pending, signal, cancel) {
+  if (signal.aborted) {
+    cancel?.();
+    pending.catch(() => {});
+    signal.throwIfAborted();
+  }
+  let abort;
+  const cancelled = new Promise((_, reject) => {
+    abort = () => {
+      cancel?.();
+      reject(signal.reason);
+    };
+    signal.addEventListener("abort", abort, { once: true });
+  });
+  try {
+    return await Promise.race([pending, cancelled]);
+  } finally {
+    signal.removeEventListener("abort", abort);
+  }
+}
+
+class RedisConnection {
+  endpoint;
+  client;
+  timeoutMs;
+  lastError;
+  signal;
+  #abort;
+  constructor(endpoint, client, timeoutMs, lastError, signal) {
+    this.endpoint = endpoint;
+    this.client = client;
+    this.timeoutMs = timeoutMs;
+    this.lastError = lastError;
+    this.signal = signal;
+    this.#abort = () => this.close();
+    signal?.addEventListener("abort", this.#abort, { once: true });
+  }
+  static async connect(endpoint, mapped, config, clientFactory = createClient) {
+    config.signal?.throwIfAborted();
+    config.connectSignal?.throwIfAborted();
+    const baseSocket = {
+      host: mapped.host,
+      port: mapped.port,
+      connectTimeout: config.connectTimeoutMs ?? config.timeoutMs,
+      reconnectStrategy: false
+    };
+    const socket = config.useSsl ? { ...baseSocket, tls: true, servername: mapped.servername ?? endpoint.host } : { ...baseSocket, tls: false };
+    const client = clientFactory({
+      socket,
+      database: config.database,
+      username: config.username,
+      password: config.password,
+      disableOfflineQueue: true,
+      commandOptions: { timeout: config.timeoutMs }
+    });
+    let lastError;
+    client.on("error", (err) => {
+      lastError = err instanceof Error ? err : new Error(String(err));
+    });
+    const timeout = new AbortController;
+    const timer = setTimeout(() => timeout.abort(new ToolboxError("Redis handshake timed out", { kind: "timeout", code: "ETIMEDOUT" })), config.connectTimeoutMs ?? config.timeoutMs);
+    const signal = AbortSignal.any([
+      timeout.signal,
+      ...config.signal ? [config.signal] : [],
+      ...config.connectSignal ? [config.connectSignal] : []
+    ]);
+    const close = () => {
+      if (client.isOpen)
+        client.destroy();
+    };
+    try {
+      await abortable(client.connect(), signal, close);
+      signal.throwIfAborted();
+      return new RedisConnection(endpoint, client, config.timeoutMs, () => lastError, config.signal);
+    } catch (error) {
+      close();
+      throw error;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  get isReady() {
+    return !this.signal?.aborted && this.client.isReady;
+  }
+  async#execute(operationName, operation) {
+    this.signal?.throwIfAborted();
+    if (!this.client.isOpen) {
+      const reason = this.lastError()?.message;
+      throw new Error(`Redis connection is closed${reason ? `: ${reason}` : ""}`);
+    }
+    const timeout = new AbortController;
+    const timer = setTimeout(() => timeout.abort(new ToolboxError(`Redis ${operationName} timed out after ${this.timeoutMs}ms (${this.endpoint.host}:${this.endpoint.port})`, { kind: "timeout", code: "ETIMEDOUT" })), this.timeoutMs);
+    const signal = this.signal ? AbortSignal.any([this.signal, timeout.signal]) : timeout.signal;
+    try {
+      return await abortable(Promise.resolve().then(() => {
+        signal.throwIfAborted();
+        return operation();
+      }), signal, () => this.close());
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  ping() {
+    return this.#execute("PING", () => this.client.ping());
+  }
+  async info(section) {
+    const raw = await this.#execute(section ? `INFO ${section}` : "INFO", () => section ? this.client.sendCommand(["INFO", section]) : this.client.sendCommand(["INFO"]));
+    return parseRedisInfo(stringValue(raw));
+  }
+  async dbSize() {
+    return Number(await this.#execute("DBSIZE", () => this.client.sendCommand(["DBSIZE"])));
+  }
+  command(args) {
+    return this.#execute(args[0]?.toUpperCase() ?? "command", () => this.client.sendCommand(args));
+  }
+  async pipeline(commands) {
+    const commandNames = new Set(commands.map((command) => command[0]?.toUpperCase()).filter(Boolean));
+    const operationName = commandNames.size === 1 ? `${[...commandNames][0]} pipeline` : "pipeline";
+    return await this.#execute(operationName, () => {
+      const pipeline = this.client.multi();
+      for (const command of commands)
+        pipeline.addCommand(command);
+      return pipeline.execAsPipeline();
+    });
+  }
+  async scan(cursor, count) {
+    const reply = await this.command(["SCAN", cursor, "COUNT", String(count)]);
+    if (!Array.isArray(reply) || !Array.isArray(reply[1]))
+      throw new Error("Redis SCAN 返回格式无效");
+    return { cursor: stringValue(reply[0]), keys: reply[1].map(stringValue) };
+  }
+  close() {
+    if (this.#abort)
+      this.signal?.removeEventListener("abort", this.#abort);
+    if (this.client.isOpen)
+      this.client.destroy();
+  }
+}
+
+class RedisAccess {
+  baseConfig;
+  connectionFactory;
+  lifecycle;
+  #connections = new Map;
+  #controller = new AbortController;
+  #signal;
+  #transports;
+  #closing;
+  constructor(transports, baseConfig, connectionFactory = RedisConnection.connect, lifecycle = {}) {
+    this.baseConfig = baseConfig;
+    this.connectionFactory = connectionFactory;
+    this.lifecycle = lifecycle;
+    this.#transports = Array.isArray(transports) ? transports : [transports];
+    if (!this.#transports.length)
+      throw new Error("Redis requires a TCP transport");
+    for (const value of [
+      baseConfig.timeoutMs,
+      baseConfig.connectTimeoutMs ?? baseConfig.timeoutMs,
+      baseConfig.acquireTimeoutMs ?? (baseConfig.connectTimeoutMs ?? baseConfig.timeoutMs) * this.#transports.length
+    ]) {
+      if (!Number.isFinite(value) || value <= 0)
+        throw new Error("Redis timeouts must be positive milliseconds");
+    }
+    this.#signal = lifecycle.signal ? AbortSignal.any([lifecycle.signal, this.#controller.signal]) : this.#controller.signal;
+  }
+  async connection(endpoint, database, credentials = this.baseConfig) {
+    this.#signal.throwIfAborted();
+    const key = [endpoint.host, endpoint.port, database, credentials.username ?? "", credentials.password ?? ""].join("\x00");
+    const existing = this.#connections.get(key);
+    if (existing) {
+      const connection = await existing;
+      this.#signal.throwIfAborted();
+      if (connection.isReady)
+        return connection;
+      if (this.#connections.get(key) === existing) {
+        this.#connections.delete(key);
+        connection.close();
+      }
+      return this.connection(endpoint, database, credentials);
+    }
+    const pending = this.#open(endpoint, database, credentials);
+    this.#connections.set(key, pending);
+    pending.catch(() => {
+      if (this.#connections.get(key) === pending)
+        this.#connections.delete(key);
+    });
+    return pending;
+  }
+  async#open(endpoint, database, credentials) {
+    const timeout = new AbortController;
+    const attemptBudget = this.baseConfig.connectTimeoutMs ?? this.baseConfig.timeoutMs;
+    const budget = this.baseConfig.acquireTimeoutMs ?? attemptBudget * this.#transports.length;
+    const deadline = performance.now() + budget;
+    const timer = setTimeout(() => timeout.abort(new ToolboxError(`Redis connection timed out after ${budget}ms (${endpoint.host}:${endpoint.port})`, { kind: "timeout", code: "ETIMEDOUT" })), budget);
+    const signal = AbortSignal.any([this.#signal, timeout.signal]);
+    let reason;
+    try {
+      for (let index = 0;index < this.#transports.length; index++) {
+        signal.throwIfAborted();
+        const transport = this.#transports[index];
+        const attempt = new AbortController;
+        const remaining = Math.min(attemptBudget, Math.max(1, Math.ceil(deadline - performance.now())));
+        const attemptTimer = setTimeout(() => attempt.abort(new ToolboxError(`Redis connection attempt timed out (${transport.name})`, { kind: "timeout", code: "ETIMEDOUT" })), remaining);
+        const attemptSignal = AbortSignal.any([signal, attempt.signal]);
+        try {
+          const mapped = await abortable(transport.connect(endpoint), attemptSignal);
+          attemptSignal.throwIfAborted();
+          const pending = this.connectionFactory(endpoint, mapped, {
+            ...this.baseConfig,
+            ...credentials,
+            database,
+            connectTimeoutMs: remaining,
+            signal: this.#signal,
+            connectSignal: attemptSignal
+          });
+          const prepared = pending.then((connection2) => {
+            if (attemptSignal.aborted) {
+              connection2.close();
+              attemptSignal.throwIfAborted();
+            }
+            return connection2;
+          });
+          const connection = await abortable(prepared, attemptSignal);
+          this.lifecycle.onRoute?.({ transport: mapped.host === endpoint.host && mapped.port === endpoint.port ? "direct" : transport.name, reason });
+          return connection;
+        } catch (failure) {
+          signal.throwIfAborted();
+          const error = attemptSignal.aborted ? attemptSignal.reason : failure;
+          const network = isConnectionNetworkError(error) || error instanceof SocketClosedUnexpectedlyError || error instanceof ConnectionTimeoutError;
+          if (!network || index === this.#transports.length - 1)
+            throw error;
+          reason = error instanceof SocketClosedUnexpectedlyError ? "connection_lost" : error instanceof ConnectionTimeoutError ? "ETIMEDOUT" : String(error.code);
+        } finally {
+          clearTimeout(attemptTimer);
+        }
+      }
+      throw new Error("Redis requires a TCP transport");
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  close() {
+    return this.#closing ??= (async () => {
+      this.#controller.abort(new Error("Redis access is closed"));
+      const settled = await Promise.allSettled(this.#connections.values());
+      this.#connections.clear();
+      const errors = [];
+      for (const result of settled)
+        if (result.status === "fulfilled") {
+          try {
+            result.value.close();
+          } catch (error) {
+            errors.push(error);
+          }
+        }
+      if (errors.length)
+        throw new AggregateError(errors, "Redis connection cleanup failed");
+    })();
+  }
+}
+
+class RedisClient {
+  source;
+  lifecycle;
+  #controller = new AbortController;
+  signal;
+  #initialization;
+  #disposal;
+  #access;
+  #target;
+  constructor(source, lifecycle = {}) {
+    this.source = source;
+    this.lifecycle = lifecycle;
+    this.signal = lifecycle.signal ? AbortSignal.any([lifecycle.signal, this.#controller.signal]) : this.#controller.signal;
+  }
+  initialize() {
+    this.signal.throwIfAborted();
+    return this.#initialization ??= (async () => {
+      this.#target = await this.source.resolve();
+      this.signal.throwIfAborted();
+      if (!this.source.transports.length || this.source.transports.some((transport) => transport.kind !== "tcp")) {
+        throw new Error("Redis requires TCP transports");
+      }
+      if (this.#target.clusterType === "cluster" && this.#target.database !== 0)
+        throw new Error("Redis Cluster requires database 0");
+      this.#access = new RedisAccess(this.source.transports, this.#target, undefined, { ...this.lifecycle, signal: this.signal });
+    })();
+  }
+  get access() {
+    this.signal.throwIfAborted();
+    if (!this.#access)
+      throw new Error("Redis client is not initialized");
+    return this.#access;
+  }
+  topology() {
+    return discoverRedisTopology(this.access, this.target);
+  }
+  get target() {
+    if (!this.#target)
+      throw new Error("Redis client is not initialized");
+    return this.#target;
+  }
+  dispose() {
+    return this.#disposal ??= (async () => {
+      this.#controller.abort(new Error("Redis client disposed"));
+      await this.#initialization?.catch(() => {});
+      await this.#access?.close();
+    })();
+  }
+}
+async function openRedis(source, lifecycle = {}) {
+  const client = new RedisClient(source, lifecycle);
+  try {
+    await client.initialize();
+  } catch (error) {
+    await client.dispose();
+    throw error;
+  }
+  lifecycle.onDispose?.(() => client.dispose());
+  return client;
+}
+
+export { parseRedisInfo, RedisConnection, RedisAccess, RedisClient, openRedis };

package/dist/redis/client.d.ts

@@ -1,6 +1,7 @@
 import type { Client } from "../client";
 import type { ConnectionSource, ClientLifecycle } from "../datasource";
-import type { TcpTransport } from "../transport";
+import { type TcpTransport } from "../transport";
+import { type RedisTopologyConfig, type RedisTopology } from "./topology";
 import { createClient, type RedisClientType } from "@redis/client";
 export interface RedisEndpoint {
     host: string;
@@ -17,6 +18,10 @@ export interface RedisConnectionConfig extends RedisCredentials {
     database: number;
     useSsl: boolean;
     timeoutMs: number;
+    /** Per-route mapping and handshake budget; defaults to timeoutMs. */
+    connectTimeoutMs?: number;
+    /** Total acquisition budget; defaults to connectTimeoutMs times the number of routes. */
+    acquireTimeoutMs?: number;
 }
 export type RedisEndpointMapper = (endpoint: RedisEndpoint) => Promise<RedisMappedEndpoint>;
 type NodeRedisClient = RedisClientType;
@@ -25,7 +30,10 @@ export interface RedisManagedConnection extends RedisConnectionApi {
     readonly isReady: boolean;
     close(): void;
 }
-export type RedisConnectionFactory = (endpoint: RedisEndpoint, mapped: RedisMappedEndpoint, config: RedisConnectionConfig) => Promise<RedisManagedConnection>;
+export type RedisConnectionFactory = (endpoint: RedisEndpoint, mapped: RedisMappedEndpoint, config: RedisConnectionConfig & {
+    signal?: AbortSignal;
+    connectSignal?: AbortSignal;
+}) => Promise<RedisManagedConnection>;
 /** Redis INFO wire 文本解析；协议适配留在 infra，领域层只接收结构化字段。 */
 export declare function parseRedisInfo(raw: string): Record<string, unknown>;
 export interface RedisConnectionApi {
@@ -44,14 +52,19 @@ export interface RedisAccessApi {
     connection(endpoint: RedisEndpoint, database: number, credentials?: RedisCredentials): Promise<RedisConnectionApi>;
     close(): Promise<void>;
 }
+/** @spec A command is sent once; a later operation may acquire a new connection after failure. */
 export declare class RedisConnection implements RedisManagedConnection {
     #private;
     readonly endpoint: RedisEndpoint;
     private readonly client;
     private readonly timeoutMs;
     private readonly lastError;
+    private readonly signal?;
     private constructor();
-    static connect(endpoint: RedisEndpoint, mapped: RedisMappedEndpoint, config: RedisConnectionConfig, clientFactory?: NodeRedisClientFactory): Promise<RedisConnection>;
+    static connect(endpoint: RedisEndpoint, mapped: RedisMappedEndpoint, config: RedisConnectionConfig & {
+        signal?: AbortSignal;
+        connectSignal?: AbortSignal;
+    }, clientFactory?: NodeRedisClientFactory): Promise<RedisConnection>;
     get isReady(): boolean;
     ping(): Promise<string>;
     info(section?: string): Promise<Record<string, unknown>>;
@@ -64,25 +77,31 @@ export declare class RedisConnection implements RedisManagedConnection {
     }>;
     close(): void;
 }
+/**
+ * @spec Only connection establishment can advance to another transport; protocol operations are never replayed.
+ * @why Every topology node needs the same route policy, credentials, deadline and root cancellation.
+ */
 export declare class RedisAccess implements RedisAccessApi {
     #private;
-    private readonly transport;
     private readonly baseConfig;
     private readonly connectionFactory;
-    constructor(transport: TcpTransport, baseConfig: Omit<RedisConnectionConfig, "database">, connectionFactory?: RedisConnectionFactory);
+    private readonly lifecycle;
+    constructor(transports: TcpTransport | readonly TcpTransport[], baseConfig: Omit<RedisConnectionConfig, "database">, connectionFactory?: RedisConnectionFactory, lifecycle?: ClientLifecycle);
     connection(endpoint: RedisEndpoint, database: number, credentials?: RedisCredentials): Promise<RedisManagedConnection>;
     close(): Promise<void>;
 }
-export interface RedisDataSourceTarget extends RedisConnectionConfig {
-    endpoints: RedisEndpoint[];
-}
+/** Connection configuration includes topology; diagnostics do not need a second target model. */
+export type RedisDataSourceTarget = RedisConnectionConfig & RedisTopologyConfig;
 export declare class RedisClient implements Client {
     #private;
     private readonly source;
+    private readonly lifecycle;
     readonly signal: AbortSignal;
     constructor(source: ConnectionSource<RedisDataSourceTarget>, lifecycle?: ClientLifecycle);
     initialize(): Promise<void>;
     get access(): RedisAccess;
+    /** Refresh topology for this observation, while retaining reusable node connections. */
+    topology(): Promise<RedisTopology>;
     get target(): RedisDataSourceTarget;
     dispose(): Promise<void>;
 }

package/dist/redis/client.js

@@ -4,7 +4,15 @@ import {
   RedisConnection,
   openRedis,
   parseRedisInfo
-} from "../chunk-ajhdd4hp.js";
+} from "../chunk-yp6tcw22.js";
+import"../chunk-5tbzf9wd.js";
+import"../chunk-20kv4wc3.js";
+import"../chunk-h8fwx0k7.js";
+import"../chunk-wv4jwhvj.js";
+import"../chunk-631vce5z.js";
+import"../chunk-hmah9t8e.js";
+import"../chunk-mn6dwsvh.js";
+import"../chunk-ssj93brx.js";
 export {
   parseRedisInfo,
   openRedis,

package/dist/redis/index.js

@@ -2,16 +2,23 @@ import {
   collectRedisKeyStats,
   redisGroupedSampleSizes
 } from "../chunk-jr9y0ghr.js";
-import {
-  discoverRedisTopology
-} from "../chunk-c6z919qb.js";
 import {
   RedisAccess,
   RedisClient,
   RedisConnection,
   openRedis,
   parseRedisInfo
-} from "../chunk-ajhdd4hp.js";
+} from "../chunk-yp6tcw22.js";
+import {
+  discoverRedisTopology
+} from "../chunk-5tbzf9wd.js";
+import"../chunk-20kv4wc3.js";
+import"../chunk-h8fwx0k7.js";
+import"../chunk-wv4jwhvj.js";
+import"../chunk-631vce5z.js";
+import"../chunk-hmah9t8e.js";
+import"../chunk-mn6dwsvh.js";
+import"../chunk-ssj93brx.js";
 export {
   redisGroupedSampleSizes,
   parseRedisInfo,

package/dist/redis/topology.d.ts

@@ -1,13 +1,16 @@
 import type { RedisAccessApi, RedisCredentials, RedisEndpoint } from "./client";
-export interface RedisTopologyConfig extends RedisCredentials {
+/** Endpoints are standalone/cluster seeds or Sentinel seeds according to clusterType. */
+export type RedisTopologyConfig = RedisCredentials & {
     endpoints: RedisEndpoint[];
     database: number;
-    clusterType: "single" | "sentinel" | "cluster";
-    sentinelHosts: RedisEndpoint[];
+} & ({
+    clusterType: "single" | "cluster";
+} | {
+    clusterType: "sentinel";
     sentinelMasterName: string;
     sentinelUsername?: string;
     sentinelPassword?: string;
-}
+});
 export interface RedisSlotRange {
     start: number;
     end: number;

package/dist/redis/topology.js

@@ -1,6 +1,6 @@
 import {
   discoverRedisTopology
-} from "../chunk-c6z919qb.js";
+} from "../chunk-5tbzf9wd.js";
 export {
   discoverRedisTopology
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compforge/harness-toolbox",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "Shared infrastructure clients, transports and bounded data capture",
   "type": "module",
   "scripts": {

package/dist/chunk-ajhdd4hp.js

@@ -1,267 +0,0 @@
-// src/redis/client.ts
-import { createClient } from "@redis/client";
-function stringValue(value) {
-  if (Buffer.isBuffer(value))
-    return value.toString("utf8");
-  return String(value ?? "");
-}
-function scalar(value) {
-  if (/^-?(?:\d+|\d+\.\d+)$/.test(value))
-    return Number(value);
-  return value;
-}
-function parseRedisInfo(raw) {
-  const result = {};
-  for (const line of raw.split(/\r?\n/)) {
-    if (!line || line.startsWith("#"))
-      continue;
-    const separator = line.indexOf(":");
-    if (separator < 1)
-      continue;
-    const name = line.slice(0, separator);
-    const value = line.slice(separator + 1);
-    if (/^db\d+$/.test(name)) {
-      result[name] = Object.fromEntries(value.split(",").map((item) => {
-        const index = item.indexOf("=");
-        return [item.slice(0, index), scalar(item.slice(index + 1))];
-      }));
-    } else {
-      result[name] = scalar(value);
-    }
-  }
-  return result;
-}
-
-class RedisConnection {
-  endpoint;
-  client;
-  timeoutMs;
-  lastError;
-  constructor(endpoint, client, timeoutMs, lastError) {
-    this.endpoint = endpoint;
-    this.client = client;
-    this.timeoutMs = timeoutMs;
-    this.lastError = lastError;
-  }
-  static async connect(endpoint, mapped, config, clientFactory = createClient) {
-    const baseSocket = {
-      host: mapped.host,
-      port: mapped.port,
-      connectTimeout: config.timeoutMs,
-      reconnectStrategy: (retries) => retries >= 2 ? false : 100 * 2 ** retries
-    };
-    const socket = config.useSsl ? {
-      ...baseSocket,
-      tls: true,
-      servername: mapped.servername ?? endpoint.host
-    } : {
-      ...baseSocket,
-      tls: false
-    };
-    const client = clientFactory({
-      socket,
-      database: config.database,
-      username: config.username,
-      password: config.password,
-      commandOptions: { timeout: config.timeoutMs }
-    });
-    let lastError;
-    client.on("error", (err) => {
-      lastError = err instanceof Error ? err : new Error(String(err));
-    });
-    try {
-      await client.connect();
-    } catch (error) {
-      if (client.isOpen)
-        client.destroy();
-      throw error;
-    }
-    return new RedisConnection(endpoint, client, config.timeoutMs, () => lastError);
-  }
-  get isReady() {
-    return this.client.isReady;
-  }
-  async#execute(operationName, operation) {
-    try {
-      return await this.#executeOnce(operationName, operation);
-    } catch (err) {
-      if (this.client.isOpen && !this.client.isReady)
-        return this.#executeOnce(operationName, operation);
-      throw err;
-    }
-  }
-  async#executeOnce(operationName, operation) {
-    if (!this.client.isOpen) {
-      const reason = this.lastError()?.message;
-      throw new Error(`Redis connection is closed${reason ? `: ${reason}` : ""}`);
-    }
-    let timer;
-    const deadline = new Promise((_, reject) => {
-      timer = setTimeout(() => {
-        reject(new Error(`Redis ${operationName} timed out after ${this.timeoutMs}ms (${this.endpoint.host}:${this.endpoint.port})`));
-        this.close();
-      }, this.timeoutMs);
-    });
-    try {
-      return await Promise.race([Promise.resolve().then(operation), deadline]);
-    } finally {
-      if (timer)
-        clearTimeout(timer);
-    }
-  }
-  ping() {
-    return this.#execute("PING", () => this.client.ping());
-  }
-  async info(section) {
-    const raw = await this.#execute(section ? `INFO ${section}` : "INFO", () => section ? this.client.sendCommand(["INFO", section]) : this.client.sendCommand(["INFO"]));
-    return parseRedisInfo(stringValue(raw));
-  }
-  async dbSize() {
-    return Number(await this.#execute("DBSIZE", () => this.client.sendCommand(["DBSIZE"])));
-  }
-  command(args) {
-    return this.#execute(args[0]?.toUpperCase() ?? "command", () => this.client.sendCommand(args));
-  }
-  async pipeline(commands) {
-    const commandNames = new Set(commands.map((command) => command[0]?.toUpperCase()).filter(Boolean));
-    const operationName = commandNames.size === 1 ? `${[...commandNames][0]} pipeline` : "pipeline";
-    return await this.#execute(operationName, () => {
-      const pipeline = this.client.multi();
-      for (const command of commands)
-        pipeline.addCommand(command);
-      return pipeline.execAsPipeline();
-    });
-  }
-  async scan(cursor, count) {
-    const reply = await this.command(["SCAN", cursor, "COUNT", String(count)]);
-    if (!Array.isArray(reply) || !Array.isArray(reply[1]))
-      throw new Error("Redis SCAN 返回格式无效");
-    return { cursor: stringValue(reply[0]), keys: reply[1].map(stringValue) };
-  }
-  close() {
-    if (this.client.isOpen)
-      this.client.destroy();
-  }
-}
-
-class RedisAccess {
-  transport;
-  baseConfig;
-  connectionFactory;
-  #connections = new Map;
-  #closing;
-  constructor(transport, baseConfig, connectionFactory = RedisConnection.connect) {
-    this.transport = transport;
-    this.baseConfig = baseConfig;
-    this.connectionFactory = connectionFactory;
-  }
-  async connection(endpoint, database, credentials = this.baseConfig) {
-    if (this.#closing)
-      throw new Error("Redis access is closed");
-    const key = [
-      endpoint.host,
-      endpoint.port,
-      database,
-      credentials.username ?? "",
-      credentials.password ?? ""
-    ].join("\x00");
-    let pending = this.#connections.get(key);
-    if (pending) {
-      const connection = await pending;
-      if (this.#closing)
-        throw new Error("Redis access is closed");
-      if (connection.isReady)
-        return connection;
-      if (this.#connections.get(key) === pending) {
-        this.#connections.delete(key);
-        connection.close();
-      } else {
-        return this.connection(endpoint, database, credentials);
-      }
-    }
-    pending = this.transport.connect(endpoint).then((mapped) => this.connectionFactory(endpoint, mapped, {
-      ...this.baseConfig,
-      ...credentials,
-      database
-    }));
-    this.#connections.set(key, pending);
-    pending.catch(() => {
-      if (this.#connections.get(key) === pending)
-        this.#connections.delete(key);
-    });
-    return await pending;
-  }
-  close() {
-    return this.#closing ??= (async () => {
-      const settled = await Promise.allSettled(this.#connections.values());
-      this.#connections.clear();
-      const errors = [];
-      for (const result of settled)
-        if (result.status === "fulfilled") {
-          try {
-            result.value.close();
-          } catch (error) {
-            errors.push(error);
-          }
-        }
-      if (errors.length)
-        throw new AggregateError(errors, "Redis connection cleanup failed");
-    })();
-  }
-}
-
-class RedisClient {
-  source;
-  #controller = new AbortController;
-  signal;
-  #initialization;
-  #disposal;
-  #access;
-  #target;
-  constructor(source, lifecycle = {}) {
-    this.source = source;
-    this.signal = lifecycle.signal ? AbortSignal.any([lifecycle.signal, this.#controller.signal]) : this.#controller.signal;
-  }
-  initialize() {
-    this.signal.throwIfAborted();
-    return this.#initialization ??= (async () => {
-      this.#target = await this.source.resolve();
-      this.signal.throwIfAborted();
-      const transport = this.source.transports[0];
-      if (!transport || transport.kind !== "tcp")
-        throw new Error("Redis requires a TCP transport");
-      this.#access = new RedisAccess(transport, this.#target);
-    })();
-  }
-  get access() {
-    this.signal.throwIfAborted();
-    if (!this.#access)
-      throw new Error("Redis client is not initialized");
-    return this.#access;
-  }
-  get target() {
-    if (!this.#target)
-      throw new Error("Redis client is not initialized");
-    return this.#target;
-  }
-  dispose() {
-    return this.#disposal ??= (async () => {
-      this.#controller.abort(new Error("Redis client disposed"));
-      await this.#initialization?.catch(() => {});
-      await this.#access?.close();
-    })();
-  }
-}
-async function openRedis(source, lifecycle = {}) {
-  const client = new RedisClient(source, lifecycle);
-  try {
-    await client.initialize();
-  } catch (error) {
-    await client.dispose();
-    throw error;
-  }
-  lifecycle.onDispose?.(() => client.dispose());
-  return client;
-}
-
-export { parseRedisInfo, RedisConnection, RedisAccess, RedisClient, openRedis };