@compforge/harness-toolbox 0.4.1 → 0.4.3

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/file/client.d.ts

@@ -1,17 +1,22 @@
-import type { FileClient, FileReadOptions } from "@compforge/harness-common";
+import type { FileClient, FileReadOptions, FileReadResult } from "@compforge/harness-common";
 export interface FileClientOptions {
     concurrency: number;
 }
+export interface FileCaptureSink {
+    receive(index: number, bytes: Uint8Array): void;
+    complete(index: number, error?: Error): void;
+}
 export declare function fileClientOptions(options: FileClientOptions): Readonly<FileClientOptions>;
-/** Shared limits and lifecycle; transports stream bytes and own per-read resource cleanup. */
+export declare function filePaths(paths: readonly string[]): readonly string[];
+/** Group lifecycle and budgets; a per-file failure releases its partial bytes and preserves sibling results. */
 export declare abstract class BoundedFileClient implements FileClient {
     #private;
-    readonly path: string;
-    constructor(path: string, options: FileClientOptions, signal: AbortSignal);
+    readonly paths: readonly string[];
+    constructor(paths: readonly string[], options: FileClientOptions, signal: AbortSignal);
     initialize(): Promise<void>;
     protected initializeAccess(): Promise<void>;
-    protected abstract capture(signal: AbortSignal, limits: Pick<FileReadOptions, "maxBytes" | "timeoutMs">, receive: (bytes: Uint8Array) => void): Promise<void>;
-    /** @spec Limits apply while streaming; a failed read never publishes partial bytes. */
-    read(options: FileReadOptions): Promise<Uint8Array>;
+    protected abstract capture(signal: AbortSignal, limits: FileReadOptions, sink: FileCaptureSink): Promise<void>;
+    /** @spec Enforce budgets while streaming; file failures discard only that file, never publish partial bytes. */
+    read(options: FileReadOptions): Promise<readonly FileReadResult[]>;
     dispose(): Promise<void>;
 }

package/dist/file/client.js

@@ -1,10 +1,12 @@
 import {
   BoundedFileClient,
-  fileClientOptions
-} from "../chunk-mzdz6wwc.js";
+  fileClientOptions,
+  filePaths
+} from "../chunk-kkts16w9.js";
 import"../chunk-20kv4wc3.js";
 import"../chunk-v3hxvnrc.js";
 export {
+  filePaths,
   fileClientOptions,
   BoundedFileClient
 };

package/dist/file/index.d.ts

@@ -1,4 +1,4 @@
-export { FileDataSource, type FileClient, type FileReadOptions } from "@compforge/harness-common";
+export { FileDataSource, type FileClient, type FileReadOptions, type FileReadResult } from "@compforge/harness-common";
 export { FileError } from "../errors";
 export type { FileClientOptions } from "./client";
 export { LocalFileDataSource, LocalFileClient } from "./local";

package/dist/file/index.js

@@ -1,12 +1,12 @@
 import {
   PodFileClient,
   PodFileDataSource
-} from "../chunk-mxyvpy79.js";
+} from "../chunk-grpygk6f.js";
 import {
   LocalFileClient,
   LocalFileDataSource
-} from "../chunk-ba883sdp.js";
-import"../chunk-mzdz6wwc.js";
+} from "../chunk-sqbew04a.js";
+import"../chunk-kkts16w9.js";
 import {
   FileError
 } from "../chunk-20kv4wc3.js";

package/dist/file/local.d.ts

@@ -1,13 +1,13 @@
 import { FileDataSource, type ClientManager, type FileReadOptions } from "@compforge/harness-common";
-import { BoundedFileClient, type FileClientOptions } from "./client";
+import { BoundedFileClient, type FileClientOptions, type FileCaptureSink } from "./client";
 export declare class LocalFileClient extends BoundedFileClient {
-    protected capture(signal: AbortSignal, limits: Pick<FileReadOptions, "maxBytes" | "timeoutMs">, receive: (bytes: Uint8Array) => void): Promise<void>;
+    protected capture(signal: AbortSignal, limits: FileReadOptions, sink: FileCaptureSink): Promise<void>;
 }
-/** @spec Resolve relative paths once at declaration; reads reopen the path to observe replaced mounted files. */
+/** @spec Resolve paths once at declaration; each group read reopens them to observe replaced mounted files. */
 export declare class LocalFileDataSource extends FileDataSource<LocalFileClient> {
     #private;
-    readonly path: string;
+    readonly paths: readonly string[];
     readonly clientKey: string;
-    constructor(path: string, options: FileClientOptions);
+    constructor(paths: readonly string[], options: FileClientOptions);
     createClient(_clients: Pick<ClientManager, "get">, signal: AbortSignal): LocalFileClient;
 }

package/dist/file/local.js

@@ -1,8 +1,8 @@
 import {
   LocalFileClient,
   LocalFileDataSource
-} from "../chunk-ba883sdp.js";
-import"../chunk-mzdz6wwc.js";
+} from "../chunk-sqbew04a.js";
+import"../chunk-kkts16w9.js";
 import"../chunk-20kv4wc3.js";
 import"../chunk-v3hxvnrc.js";
 export {

package/dist/file/pod.d.ts

@@ -1,6 +1,6 @@
 import { FileDataSource, type ClientManager, type ClientProvider, type FileReadOptions } from "@compforge/harness-common";
 import type { KubernetesClient } from "../kubernetes/client";
-import { BoundedFileClient, type FileClientOptions } from "./client";
+import { BoundedFileClient, type FileClientOptions, type FileCaptureSink } from "./client";
 export interface PodFileTarget {
     namespace: string;
     pod: string;
@@ -11,21 +11,22 @@ export declare class PodFileClient extends BoundedFileClient {
     #private;
     readonly target: Readonly<PodFileTarget>;
     private readonly acquire;
-    constructor(path: string, target: Readonly<PodFileTarget>, options: FileClientOptions, signal: AbortSignal, acquire: () => Promise<PodFileAccess>);
+    constructor(paths: readonly string[], target: Readonly<PodFileTarget>, options: FileClientOptions, signal: AbortSignal, acquire: () => Promise<PodFileAccess>);
     protected initializeAccess(): Promise<void>;
-    protected capture(signal: AbortSignal, limits: Pick<FileReadOptions, "maxBytes" | "timeoutMs">, receive: (bytes: Uint8Array) => void): Promise<void>;
+    /** @spec The whole declared group uses exactly one exec; file failures are records, never implicit retries. */
+    protected capture(signal: AbortSignal, limits: FileReadOptions, sink: FileCaptureSink): Promise<void>;
 }
 /**
- * @spec One explicit Pod/container/path per source; workload discovery and replica traversal belong to callers.
+ * @spec One explicit Pod/container and one caller-declared acquisition group; discovery belongs to consumers.
  * @rule Borrow Kubernetes access from the root manager; file clients never dispose that shared dependency.
  * @see {@link component://../../../docs/toolbox.md}
  */
 export declare class PodFileDataSource extends FileDataSource<PodFileClient> {
     #private;
     private readonly kubernetes;
-    readonly path: string;
+    readonly paths: readonly string[];
     readonly target: Readonly<PodFileTarget>;
     readonly clientKey: string;
-    constructor(kubernetes: ClientProvider<PodFileAccess>, target: PodFileTarget, path: string, options: FileClientOptions);
+    constructor(kubernetes: ClientProvider<PodFileAccess>, target: PodFileTarget, paths: readonly string[], options: FileClientOptions);
     createClient(clients: Pick<ClientManager, "get">, signal: AbortSignal): PodFileClient;
 }

package/dist/file/pod.js

@@ -1,8 +1,8 @@
 import {
   PodFileClient,
   PodFileDataSource
-} from "../chunk-mxyvpy79.js";
-import"../chunk-mzdz6wwc.js";
+} from "../chunk-grpygk6f.js";
+import"../chunk-kkts16w9.js";
 import"../chunk-20kv4wc3.js";
 import"../chunk-v3hxvnrc.js";
 export {

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;