@ferricstore/ferricstore 0.1.2 → 0.1.4

package/dist/index.d.ts

@@ -25,8 +25,12 @@ interface ExecutePipelineOptions {
     throwOnItemError?: boolean;
 }
 interface NativeAdapterOptions {
+    autoReconnect?: boolean | ReconnectOptions;
     clientName?: string;
     connectTimeoutMs?: number;
+    heartbeatIntervalMs?: number;
+    keepAlive?: boolean;
+    keepAliveInitialDelayMs?: number;
     maxChunkBytes?: number;
     protocolLanes?: number;
     timeoutMs?: number;
@@ -34,6 +38,9 @@ interface NativeAdapterOptions {
     password?: string;
     tlsOptions?: tls.ConnectionOptions;
 }
+interface ReconnectOptions {
+    maxRetries?: number;
+}
 declare class NativeAdapter implements CommandExecutor {
     private readonly socket;
     private readonly pending;
@@ -45,6 +52,10 @@ declare class NativeAdapter implements CommandExecutor {
     private readonly maxChunkBytes;
     private requestId;
     private readonly protocolLanes;
+    private readonly heartbeatIntervalMs?;
+    private heartbeatInFlight;
+    private heartbeatTimer?;
+    private lastActivityMs;
     private readonly timeoutMs;
     private constructor();
     static fromUrl(url: string, options?: NativeAdapterOptions): Promise<NativeAdapter>;
@@ -54,6 +65,9 @@ declare class NativeAdapter implements CommandExecutor {
     private startup;
     private auth;
     private request;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private sendHeartbeat;
     private onData;
     private handleFrame;
     private failAll;
@@ -61,6 +75,20 @@ declare class NativeAdapter implements CommandExecutor {
     private nextRequestId;
     private assignLane;
 }
+declare class ReconnectingExecutor implements CommandExecutor {
+    private readonly createExecutor;
+    private closed;
+    private readonly maxRetries;
+    private executorPromise;
+    private reconnectPromise?;
+    constructor(createExecutor: () => Promise<CommandExecutor>, options?: ReconnectOptions);
+    executeCommand(...args: CommandArgument[]): Promise<unknown>;
+    executePipeline(commands: readonly Command[], options?: ExecutePipelineOptions): Promise<unknown[]>;
+    close(): Promise<void>;
+    private withReconnect;
+    private reconnect;
+}
+declare function isReconnectableClosedConnectionError(error: unknown): boolean;
 
 interface StoreCommandClient {
     readonly codec: Codec;
@@ -576,6 +604,10 @@ interface FerricStoreClientOptions {
     codec?: Codec;
     backpressure?: BackpressurePolicy;
 }
+interface FerricStoreClientFromUrlOptions extends FerricStoreClientOptions {
+    nativeOptions?: NativeAdapterOptions;
+    reconnect?: boolean | ReconnectOptions;
+}
 interface CreateOptions {
     type: string;
     state?: string;
@@ -695,9 +727,7 @@ declare class FerricStoreClient {
     readonly topk: TopKStore;
     readonly zset: SortedSetStore;
     constructor(executor: CommandExecutor, options?: FerricStoreClientOptions);
-    static fromUrl(url: string, options?: FerricStoreClientOptions & {
-        nativeOptions?: NativeAdapterOptions;
-    }): Promise<FerricStoreClient>;
+    static fromUrl(url: string, options?: FerricStoreClientFromUrlOptions): Promise<FerricStoreClient>;
     command(...args: CommandArgument[]): Promise<unknown>;
     pipeline(commands: readonly Command[]): Promise<unknown[]>;
     close(): Promise<void>;
@@ -1289,4 +1319,4 @@ declare class WorkflowWorker {
     private applyHandlerError;
 }
 
-export { type AutoBatchOptions, type BackoffKind, type BackpressurePolicy, BitmapStore, BloomFilterStore, type CancelOptions, type ChildSpec, type ClaimDueOptions, type ClaimedItem, type Codec, type Command, type CommandArgument, type CommandExecutor, type CompleteOptions, type CompleteOutcome, type CountMinMergeOptions, CountMinSketchStore, type CreateItem, type CreateManyOptions, type CreateOptions, CuckooFilterStore, type ExceptionPolicy, type ExecutePipelineOptions, type FailOptions, type FailOutcome, type FencedItem, FerricStoreClient, type FerricStoreClientOptions, FerricStoreError, type FetchOrComputeResult, FlowAlreadyExistsError, FlowNotFoundError, type FlowRecord, FlowWrongStateError, type GeoAddOptions, type GeoMember, GeoStore, type GetExOptions, HashStore, HyperLogLogStore, InvalidCommandError, JsonCodec, type JsonSetOptions, JsonStore, type KeyInfo, KeyValueStore, ListStore, LockHeldError, LockNotOwnedError, type MutateOptions, type NamedValueMutation, NativeAdapter, type NativeAdapterOptions, type Outcome, OverloadedError, Queue, type QueueBatchHandler, QueueClient, type QueueHandler, type QueueOptions, QueueWorker, type QueueWorkerResult, type RangeLimit, type RateLimitResult, RawCodec, type ReadOptions, type ReclaimOptions, type RetryOptions, type RetryOutcome, type RetryPolicy, type ScanOptions, type SetOptions, SetStore, SortedSetStore, StaleLeaseError, type StateMeta, type StateMetaValue, type StateOptions, type StateRegistration, type StoreCommandClient, StreamStore, type TDigestCreateOptions, type TDigestMergeOptions, TDigestStore, type TopKReserveOptions, TopKStore, type TransitionOptions, type TransitionOutcome, type ValueConfig, type WorkerConfig, type WorkerProfile, Workflow, WorkflowClient, WorkflowContext, WorkflowFlowCommands, type WorkflowHandler, type WorkflowOptions, WorkflowWorker, type WorkflowWorkerResult, type XReadStream, type ZAddMember, type ZAddOptions, classifyServerError, complete, fail, mapException, retry, transition };
+export { type AutoBatchOptions, type BackoffKind, type BackpressurePolicy, BitmapStore, BloomFilterStore, type CancelOptions, type ChildSpec, type ClaimDueOptions, type ClaimedItem, type Codec, type Command, type CommandArgument, type CommandExecutor, type CompleteOptions, type CompleteOutcome, type CountMinMergeOptions, CountMinSketchStore, type CreateItem, type CreateManyOptions, type CreateOptions, CuckooFilterStore, type ExceptionPolicy, type ExecutePipelineOptions, type FailOptions, type FailOutcome, type FencedItem, FerricStoreClient, type FerricStoreClientFromUrlOptions, type FerricStoreClientOptions, FerricStoreError, type FetchOrComputeResult, FlowAlreadyExistsError, FlowNotFoundError, type FlowRecord, FlowWrongStateError, type GeoAddOptions, type GeoMember, GeoStore, type GetExOptions, HashStore, HyperLogLogStore, InvalidCommandError, JsonCodec, type JsonSetOptions, JsonStore, type KeyInfo, KeyValueStore, ListStore, LockHeldError, LockNotOwnedError, type MutateOptions, type NamedValueMutation, NativeAdapter, type NativeAdapterOptions, type Outcome, OverloadedError, Queue, type QueueBatchHandler, QueueClient, type QueueHandler, type QueueOptions, QueueWorker, type QueueWorkerResult, type RangeLimit, type RateLimitResult, RawCodec, type ReadOptions, type ReclaimOptions, type ReconnectOptions, ReconnectingExecutor, type RetryOptions, type RetryOutcome, type RetryPolicy, type ScanOptions, type SetOptions, SetStore, SortedSetStore, StaleLeaseError, type StateMeta, type StateMetaValue, type StateOptions, type StateRegistration, type StoreCommandClient, StreamStore, type TDigestCreateOptions, type TDigestMergeOptions, TDigestStore, type TopKReserveOptions, TopKStore, type TransitionOptions, type TransitionOutcome, type ValueConfig, type WorkerConfig, type WorkerProfile, Workflow, WorkflowClient, WorkflowContext, WorkflowFlowCommands, type WorkflowHandler, type WorkflowOptions, WorkflowWorker, type WorkflowWorkerResult, type XReadStream, type ZAddMember, type ZAddOptions, classifyServerError, complete, fail, isReconnectableClosedConnectionError, mapException, retry, transition };

package/dist/index.js

@@ -1393,15 +1393,21 @@ var NativeAdapter = class _NativeAdapter {
   maxChunkBytes;
   requestId = 0n;
   protocolLanes;
+  heartbeatIntervalMs;
+  heartbeatInFlight = false;
+  heartbeatTimer;
+  lastActivityMs = Date.now();
   timeoutMs;
-  constructor(socket, timeoutMs, protocolLanes, maxChunkBytes) {
+  constructor(socket, timeoutMs, protocolLanes, maxChunkBytes, heartbeatIntervalMs) {
     this.socket = socket;
     this.maxChunkBytes = Math.max(1, Math.trunc(maxChunkBytes));
     this.timeoutMs = timeoutMs;
     this.protocolLanes = Math.max(1, Math.trunc(protocolLanes));
+    this.heartbeatIntervalMs = normalizeHeartbeatInterval(heartbeatIntervalMs);
     this.socket.on("data", (chunk) => this.onData(chunk));
     this.socket.on("error", (error) => this.failAll(error));
     this.socket.on("close", () => this.failAll(new FerricStoreError("FerricStore connection closed")));
+    this.startHeartbeat();
   }
   static async fromUrl(url, options = {}) {
     const parsed = parseFerricUrl(url);
@@ -1410,7 +1416,8 @@ var NativeAdapter = class _NativeAdapter {
       socket,
       options.timeoutMs ?? 3e4,
       options.protocolLanes ?? 8,
-      options.maxChunkBytes ?? 64 * 1024 * 1024
+      options.maxChunkBytes ?? 64 * 1024 * 1024,
+      options.heartbeatIntervalMs
     );
     await adapter.startup(options.clientName);
     const password = options.password ?? parsed.password;
@@ -1434,6 +1441,7 @@ var NativeAdapter = class _NativeAdapter {
       return;
     }
     this.closed = true;
+    this.stopHeartbeat();
     this.socket.end();
   }
   async startup(clientName) {
@@ -1455,6 +1463,7 @@ var NativeAdapter = class _NativeAdapter {
     if (this.closed) {
       throw new FerricStoreError("FerricStore connection is closed");
     }
+    this.lastActivityMs = Date.now();
     const requestId = this.nextRequestId();
     const frame = encodeRequest(this.assignLane(command), requestId);
     return await new Promise((resolve, reject) => {
@@ -1468,10 +1477,12 @@ var NativeAdapter = class _NativeAdapter {
         opcode: command.opcode,
         reject: (reason) => {
           clearTimeout(timer);
+          this.lastActivityMs = Date.now();
           reject(reason instanceof Error ? reason : classifyServerError(String(reason), reason));
         },
         resolve: (value) => {
           clearTimeout(timer);
+          this.lastActivityMs = Date.now();
           resolve(value);
         }
       });
@@ -1480,11 +1491,43 @@ var NativeAdapter = class _NativeAdapter {
           this.pending.delete(requestId);
           this.cleanupChunksForRequest(requestId);
           clearTimeout(timer);
+          this.lastActivityMs = Date.now();
           reject(error);
         }
       });
     });
   }
+  startHeartbeat() {
+    if (this.heartbeatIntervalMs == null) {
+      return;
+    }
+    this.heartbeatTimer = setInterval(() => {
+      void this.sendHeartbeat();
+    }, this.heartbeatIntervalMs);
+    this.heartbeatTimer.unref?.();
+  }
+  stopHeartbeat() {
+    if (this.heartbeatTimer == null) {
+      return;
+    }
+    clearInterval(this.heartbeatTimer);
+    this.heartbeatTimer = void 0;
+  }
+  async sendHeartbeat() {
+    if (this.closed || this.heartbeatInFlight || this.pending.size > 0 || this.heartbeatIntervalMs == null) {
+      return;
+    }
+    if (Date.now() - this.lastActivityMs < this.heartbeatIntervalMs) {
+      return;
+    }
+    this.heartbeatInFlight = true;
+    try {
+      await this.request(buildProtocolCommand(["PING"]));
+    } catch {
+    } finally {
+      this.heartbeatInFlight = false;
+    }
+  }
   onData(chunk) {
     try {
       this.buffer = this.buffer.byteLength === 0 ? chunk : Buffer3.concat([this.buffer, chunk]);
@@ -1543,6 +1586,7 @@ var NativeAdapter = class _NativeAdapter {
       return;
     }
     this.closed = true;
+    this.stopHeartbeat();
     const error = reason instanceof Error ? reason : classifyServerError(String(reason), reason);
     for (const pending of this.pending.values()) {
       pending.reject(error);
@@ -1575,6 +1619,74 @@ var NativeAdapter = class _NativeAdapter {
     return { ...command, laneId: this.dataLane };
   }
 };
+var ReconnectingExecutor = class {
+  constructor(createExecutor, options = {}) {
+    this.createExecutor = createExecutor;
+    this.maxRetries = Math.max(0, Math.trunc(options.maxRetries ?? 1));
+    this.executorPromise = createExecutor();
+  }
+  createExecutor;
+  closed = false;
+  maxRetries;
+  executorPromise;
+  reconnectPromise;
+  async executeCommand(...args) {
+    return await this.withReconnect((executor) => executor.executeCommand(...args));
+  }
+  async executePipeline(commands, options = {}) {
+    return await this.withReconnect(async (executor) => {
+      if (executor.executePipeline != null) {
+        return await executor.executePipeline(commands, options);
+      }
+      return await Promise.all(commands.map((command) => executor.executeCommand(...command)));
+    });
+  }
+  async close() {
+    if (this.closed) {
+      return;
+    }
+    this.closed = true;
+    const executor = await this.executorPromise.catch(() => void 0);
+    await Promise.resolve(executor?.close?.());
+  }
+  async withReconnect(operation) {
+    let executor = await this.executorPromise;
+    for (let attempt = 0; ; attempt++) {
+      try {
+        return await operation(executor);
+      } catch (error) {
+        if (this.closed || attempt >= this.maxRetries || !isReconnectableClosedConnectionError(error)) {
+          throw error;
+        }
+        executor = await this.reconnect(executor);
+      }
+    }
+  }
+  async reconnect(staleExecutor) {
+    if (this.closed) {
+      throw new FerricStoreError("FerricStore client is closed");
+    }
+    if (this.reconnectPromise != null) {
+      return await this.reconnectPromise;
+    }
+    const currentExecutor = await this.executorPromise.catch(() => void 0);
+    if (currentExecutor != null && currentExecutor !== staleExecutor) {
+      return currentExecutor;
+    }
+    this.reconnectPromise = (async () => {
+      await Promise.resolve(staleExecutor.close?.()).catch(() => void 0);
+      const nextExecutor = await this.createExecutor();
+      this.executorPromise = Promise.resolve(nextExecutor);
+      return nextExecutor;
+    })().finally(() => {
+      this.reconnectPromise = void 0;
+    });
+    return await this.reconnectPromise;
+  }
+};
+function isReconnectableClosedConnectionError(error) {
+  return error instanceof Error && error.message === "FerricStore connection is closed";
+}
 function parseFerricUrl(value) {
   const url = new URL(value);
   if (url.protocol !== "ferric:" && url.protocol !== "ferrics:") {
@@ -1598,6 +1710,7 @@ async function connect(parsed, options) {
     }, timeoutMs);
     timer.unref?.();
     socket.setNoDelay(true);
+    socket.setKeepAlive(options.keepAlive ?? true, normalizeKeepAliveInitialDelay(options.keepAliveInitialDelayMs));
     socket.once("connect", () => {
       clearTimeout(timer);
       resolve(socket);
@@ -1608,6 +1721,15 @@ async function connect(parsed, options) {
     });
   });
 }
+function normalizeHeartbeatInterval(value) {
+  if (value != null && value <= 0) {
+    return void 0;
+  }
+  return Math.trunc(value ?? 6e4);
+}
+function normalizeKeepAliveInitialDelay(value) {
+  return Math.max(0, Math.trunc(value ?? 3e4));
+}
 
 // src/codecs.ts
 var RawCodec = class {
@@ -2998,7 +3120,10 @@ var FerricStoreClient = class _FerricStoreClient {
     this.zset = new SortedSetStore(this);
   }
   static async fromUrl(url, options = {}) {
-    return new _FerricStoreClient(await NativeAdapter.fromUrl(url, options.nativeOptions), options);
+    const reconnectOptions = options.reconnect ?? options.nativeOptions?.autoReconnect ?? true;
+    const createExecutor = async () => await NativeAdapter.fromUrl(url, options.nativeOptions);
+    const executor = reconnectOptions === false ? await createExecutor() : new ReconnectingExecutor(createExecutor, reconnectOptions === true ? {} : reconnectOptions);
+    return new _FerricStoreClient(executor, options);
   }
   async command(...args) {
     return await this.executor.executeCommand(...args);
@@ -5120,6 +5245,7 @@ export {
   QueueClient,
   QueueWorker,
   RawCodec,
+  ReconnectingExecutor,
   SetStore,
   SortedSetStore,
   StaleLeaseError,
@@ -5134,6 +5260,7 @@ export {
   classifyServerError,
   complete,
   fail,
+  isReconnectableClosedConnectionError,
   mapException,
   retry,
   transition