@ferricstore/ferricstore 0.1.3 → 0.1.5

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 import tls from 'node:tls';
+import { Buffer as Buffer$1 } from 'node:buffer';
 
 interface Codec<T = unknown> {
     encode(value: T | null | undefined): Buffer;
@@ -13,26 +14,244 @@ declare class JsonCodec<T = unknown> implements Codec<T> {
     decode(value: Buffer | null | undefined): T | null;
 }
 
-type CommandArgument = string | Buffer | number | boolean | null | undefined;
+type CommandArgument = string | Buffer | number | boolean | Record<string, unknown> | null | undefined;
 type Command = readonly CommandArgument[];
 
+type EndpointPolicy = "seed_hosts" | "any" | "none" | {
+    readonly allowHosts: readonly string[];
+};
+interface RoutingEndpoint {
+    readonly node: string;
+    readonly host: string;
+    readonly nativePort: number;
+    readonly nativeTlsPort?: number;
+}
+interface RoutingRoute {
+    readonly shard: number;
+    readonly laneId: number;
+    readonly endpointKey: string;
+    readonly endpoint: RoutingEndpoint;
+    readonly leaderNode: string;
+    readonly slot?: number;
+}
+declare class RoutingTopology {
+    readonly routeEpoch: number;
+    readonly shardCount: number;
+    readonly slots: readonly (RoutingRoute | undefined)[];
+    readonly endpoints: ReadonlyMap<string, RoutingEndpoint>;
+    private constructor();
+    static empty(): RoutingTopology;
+    static build(payload: unknown): RoutingTopology;
+    static slotForKey(key: string | Buffer$1): number;
+    routeKey(key: string | Buffer$1): RoutingRoute;
+}
+declare class TopologyNativeAdapterPool implements CommandExecutor {
+    private readonly adapterOptions;
+    private readonly adapters;
+    private readonly endpointPolicy;
+    private readonly endpointValidator?;
+    private readonly seedEndpointKeys;
+    private readonly seedUrls;
+    private readonly tls;
+    private readonly trustedHosts;
+    private readonly warmConnections;
+    private topologyValue;
+    private constructor();
+    static fromUrls(urls: readonly string[], options?: NativeAdapterOptions): Promise<TopologyNativeAdapterPool>;
+    get topology(): RoutingTopology;
+    refreshTopology(): Promise<RoutingTopology>;
+    route(key: string | Buffer$1): RoutingRoute;
+    executeCommand(...args: CommandArgument[]): Promise<unknown>;
+    executePipeline(commands: readonly Command[], options?: ExecutePipelineOptions): Promise<unknown[]>;
+    close(): Promise<void>;
+    private routeData;
+    private singleRouteForCommands;
+    private controlAdapter;
+    private adapterForUrl;
+    private adapterForEndpoint;
+    private validateEndpoint;
+    private refreshCandidateUrls;
+}
+
+declare const COMMAND_OPCODES: {
+    readonly HELLO: 1;
+    readonly AUTH: 2;
+    readonly PING: 3;
+    readonly "CLIENT.SETNAME": 4;
+    readonly "CLIENT.INFO": 5;
+    readonly ROUTE: 6;
+    readonly SHARDS: 7;
+    readonly BACKPRESSURE: 8;
+    readonly QUIT: 9;
+    readonly GOAWAY: 10;
+    readonly OPTIONS: 11;
+    readonly STARTUP: 12;
+    readonly WINDOW_UPDATE: 13;
+    readonly PIPELINE: 14;
+    readonly ROUTE_BATCH: 15;
+    readonly EVENT: 16;
+    readonly SUBSCRIBE_EVENTS: 17;
+    readonly UNSUBSCRIBE_EVENTS: 18;
+    readonly COMMAND_EXEC: 256;
+    readonly GET: 257;
+    readonly SET: 258;
+    readonly DEL: 259;
+    readonly MGET: 260;
+    readonly MSET: 261;
+    readonly CAS: 262;
+    readonly LOCK: 263;
+    readonly UNLOCK: 264;
+    readonly EXTEND: 265;
+    readonly "RATELIMIT.ADD": 266;
+    readonly FETCH_OR_COMPUTE: 267;
+    readonly FETCH_OR_COMPUTE_RESULT: 268;
+    readonly FETCH_OR_COMPUTE_ERROR: 269;
+    readonly HSET: 272;
+    readonly HGET: 273;
+    readonly HMGET: 274;
+    readonly HGETALL: 275;
+    readonly LPUSH: 288;
+    readonly RPUSH: 289;
+    readonly LPOP: 290;
+    readonly RPOP: 291;
+    readonly LRANGE: 292;
+    readonly SADD: 304;
+    readonly SREM: 305;
+    readonly SMEMBERS: 306;
+    readonly SISMEMBER: 307;
+    readonly ZADD: 320;
+    readonly ZREM: 321;
+    readonly ZRANGE: 322;
+    readonly ZSCORE: 323;
+    readonly "FLOW.CREATE": 513;
+    readonly "FLOW.GET": 514;
+    readonly "FLOW.CLAIM_DUE": 515;
+    readonly "FLOW.COMPLETE": 516;
+    readonly "FLOW.TRANSITION": 517;
+    readonly "FLOW.RETRY": 518;
+    readonly "FLOW.FAIL": 519;
+    readonly "FLOW.CANCEL": 520;
+    readonly "FLOW.EXTEND_LEASE": 521;
+    readonly "FLOW.HISTORY": 522;
+    readonly "FLOW.VALUE.PUT": 523;
+    readonly "FLOW.VALUE.MGET": 524;
+    readonly "FLOW.SIGNAL": 525;
+    readonly "FLOW.LIST": 526;
+    readonly "FLOW.CREATE_MANY": 527;
+    readonly "FLOW.COMPLETE_MANY": 528;
+    readonly "FLOW.TRANSITION_MANY": 529;
+    readonly "FLOW.RETRY_MANY": 530;
+    readonly "FLOW.FAIL_MANY": 531;
+    readonly "FLOW.CANCEL_MANY": 532;
+    readonly "FLOW.RECLAIM": 533;
+    readonly "FLOW.REWIND": 534;
+    readonly "FLOW.TERMINALS": 535;
+    readonly "FLOW.FAILURES": 536;
+    readonly "FLOW.BY_PARENT": 537;
+    readonly "FLOW.BY_ROOT": 538;
+    readonly "FLOW.BY_CORRELATION": 539;
+    readonly "FLOW.INFO": 540;
+    readonly "FLOW.STUCK": 541;
+    readonly "FLOW.POLICY.SET": 542;
+    readonly "FLOW.POLICY.GET": 543;
+    readonly "FLOW.SPAWN_CHILDREN": 544;
+    readonly "FLOW.RETENTION_CLEANUP": 545;
+    readonly "FLOW.STEP_CONTINUE": 546;
+    readonly "FLOW.START_AND_CLAIM": 547;
+    readonly "FLOW.RUN_STEPS_MANY": 548;
+    readonly "FLOW.SCHEDULE.CREATE": 549;
+    readonly "FLOW.SCHEDULE.GET": 550;
+    readonly "FLOW.SCHEDULE.DELETE": 551;
+    readonly "FLOW.SCHEDULE.FIRE_DUE": 552;
+    readonly "FLOW.SCHEDULE.LIST": 553;
+    readonly "FLOW.SCHEDULE.FIRE": 554;
+    readonly "FLOW.SCHEDULE.PAUSE": 555;
+    readonly "FLOW.SCHEDULE.RESUME": 556;
+    readonly "FLOW.STATS": 557;
+    readonly "FLOW.ATTRIBUTES": 558;
+    readonly "FLOW.ATTRIBUTE_VALUES": 559;
+    readonly "FLOW.SEARCH": 560;
+    readonly "FLOW.EFFECT.RESERVE": 576;
+    readonly "FLOW.EFFECT.CONFIRM": 577;
+    readonly "FLOW.EFFECT.FAIL": 578;
+    readonly "FLOW.EFFECT.COMPENSATE": 579;
+    readonly "FLOW.EFFECT.GET": 580;
+    readonly "FLOW.GOVERNANCE.LEDGER": 581;
+    readonly "FLOW.APPROVAL.REQUEST": 582;
+    readonly "FLOW.APPROVAL.APPROVE": 583;
+    readonly "FLOW.APPROVAL.REJECT": 584;
+    readonly "FLOW.APPROVAL.GET": 585;
+    readonly "FLOW.CIRCUIT.OPEN": 586;
+    readonly "FLOW.CIRCUIT.CLOSE": 587;
+    readonly "FLOW.CIRCUIT.GET": 588;
+    readonly "FLOW.BUDGET.RESERVE": 589;
+    readonly "FLOW.BUDGET.GET": 590;
+    readonly "FLOW.LIMIT.LEASE": 591;
+    readonly "FLOW.LIMIT.SPEND": 592;
+    readonly "FLOW.LIMIT.RELEASE": 593;
+    readonly "FLOW.LIMIT.GET": 594;
+    readonly "FLOW.APPROVAL.LIST": 595;
+    readonly "FLOW.GOVERNANCE.OVERVIEW": 596;
+    readonly "FLOW.BUDGET.LIST": 597;
+    readonly "FLOW.LIMIT.LIST": 598;
+    readonly "FLOW.BUDGET.COMMIT": 599;
+    readonly "FLOW.BUDGET.RELEASE": 600;
+    readonly "CLUSTER.HEALTH": 769;
+    readonly "CLUSTER.STATS": 770;
+    readonly "CLUSTER.KEYSLOT": 771;
+    readonly "CLUSTER.SLOTS": 772;
+    readonly "CLUSTER.STATUS": 773;
+    readonly "CLUSTER.JOIN": 774;
+    readonly "CLUSTER.LEAVE": 775;
+    readonly "CLUSTER.FAILOVER": 776;
+    readonly "CLUSTER.PROMOTE": 777;
+    readonly "CLUSTER.DEMOTE": 778;
+    readonly "CLUSTER.ROLE": 779;
+    readonly "FERRICSTORE.KEY_INFO": 780;
+    readonly "FERRICSTORE.CONFIG": 781;
+    readonly "FERRICSTORE.HOTNESS": 782;
+    readonly "FERRICSTORE.METRICS": 783;
+    readonly "FERRICSTORE.BLOBGC": 784;
+};
+interface ProtocolCommand {
+    readonly opcode: number;
+    readonly payload: unknown;
+    readonly flags?: number;
+    readonly laneId?: number;
+}
+
 interface CommandExecutor {
     executeCommand(...args: CommandArgument[]): Promise<unknown>;
     executePipeline?(commands: readonly Command[], options?: ExecutePipelineOptions): Promise<unknown[]>;
+    refreshTopology?(): Promise<RoutingTopology>;
+    route?(key: string | Buffer$1): Promise<RoutingRoute> | RoutingRoute;
     close?(): Promise<void> | void;
 }
 interface ExecutePipelineOptions {
     throwOnItemError?: boolean;
 }
 interface NativeAdapterOptions {
+    autoReconnect?: boolean | ReconnectOptions;
     clientName?: string;
     connectTimeoutMs?: number;
+    endpointPolicy?: EndpointPolicy;
+    endpointValidator?: (endpoint: RoutingEndpoint) => boolean | void;
+    haRouting?: boolean;
+    heartbeatIntervalMs?: number;
+    keepAlive?: boolean;
+    keepAliveInitialDelayMs?: number;
     maxChunkBytes?: number;
     protocolLanes?: number;
+    seeds?: readonly string[];
     timeoutMs?: number;
+    trustedHosts?: readonly string[];
     username?: string;
     password?: string;
     tlsOptions?: tls.ConnectionOptions;
+    warmConnections?: boolean;
+}
+interface ReconnectOptions {
+    maxRetries?: number;
 }
 declare class NativeAdapter implements CommandExecutor {
     private readonly socket;
@@ -45,15 +264,23 @@ 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>;
     executeCommand(...args: CommandArgument[]): Promise<unknown>;
+    executeProtocolCommand(command: ProtocolCommand, laneId?: number): Promise<unknown>;
     executePipeline(commands: readonly Command[], options?: ExecutePipelineOptions): Promise<unknown[]>;
     close(): Promise<void>;
     private startup;
     private auth;
     private request;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private sendHeartbeat;
     private onData;
     private handleFrame;
     private failAll;
@@ -61,6 +288,22 @@ 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[]>;
+    refreshTopology(): Promise<RoutingTopology>;
+    route(key: string | Buffer$1): Promise<RoutingRoute>;
+    close(): Promise<void>;
+    private withReconnect;
+    private reconnect;
+}
+declare function isReconnectableClosedConnectionError(error: unknown): boolean;
 
 interface StoreCommandClient {
     readonly codec: Codec;
@@ -494,7 +737,9 @@ interface CreateItem {
     valueRefs?: Record<string, string>;
     stateMeta?: StateMeta;
 }
+/** @internal */
 declare const CLAIMED_ITEM_WIRE: unique symbol;
+/** @internal */
 interface ClaimedItemWire {
     id: Buffer;
     partitionKey?: Buffer | null;
@@ -511,6 +756,7 @@ interface ClaimedItem<TPayload = unknown> {
     runState?: string;
     payload?: TPayload | null;
     attributes?: Record<string, unknown>;
+    /** @internal */
     [CLAIMED_ITEM_WIRE]?: ClaimedItemWire;
 }
 interface FencedItem {
@@ -576,6 +822,10 @@ interface FerricStoreClientOptions {
     codec?: Codec;
     backpressure?: BackpressurePolicy;
 }
+interface FerricStoreClientFromUrlOptions extends FerricStoreClientOptions {
+    nativeOptions?: NativeAdapterOptions;
+    reconnect?: boolean | ReconnectOptions;
+}
 interface CreateOptions {
     type: string;
     state?: string;
@@ -675,6 +925,12 @@ interface ReadOptions {
     includeCold?: boolean;
     consistentProjection?: boolean;
 }
+type SearchStateMeta = StateMeta | Record<string, StateMeta>;
+interface SearchOptions extends ReadOptions {
+    attributes?: Record<string, CommandArgument>;
+    stateMeta?: SearchStateMeta;
+}
+type ManagementPairs = Record<string, CommandArgument>;
 declare class FerricStoreClient {
     readonly executor: CommandExecutor;
     readonly codec: Codec;
@@ -695,12 +951,13 @@ 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>;
+    static fromUrls(urls: readonly string[], options?: FerricStoreClientFromUrlOptions): Promise<FerricStoreClient>;
     command(...args: CommandArgument[]): Promise<unknown>;
     pipeline(commands: readonly Command[]): Promise<unknown[]>;
     close(): Promise<void>;
+    refreshTopology(): Promise<RoutingTopology>;
+    route(key: string | Buffer): Promise<RoutingRoute>;
     ping(message?: CommandArgument): Promise<unknown>;
     echo(message: CommandArgument): Promise<unknown>;
     serverInfo(section?: string): Promise<string>;
@@ -747,10 +1004,11 @@ declare class FerricStoreClient {
     pubsubChannels(pattern?: string): Promise<unknown[]>;
     pubsubNumSub(...channels: string[]): Promise<unknown[]>;
     pubsubNumPat(): Promise<number>;
-    aclSetUser(username: string, rules: string[]): Promise<boolean>;
+    aclSetUser(username: string, rules: string | readonly string[]): Promise<boolean>;
     aclDelUser(...usernames: string[]): Promise<number>;
     aclGetUser(username: string): Promise<unknown>;
     aclList(): Promise<unknown[]>;
+    aclListUsers(): Promise<unknown[]>;
     aclWhoami(): Promise<string>;
     aclSave(): Promise<boolean>;
     aclLoad(): Promise<boolean>;
@@ -793,6 +1051,18 @@ declare class FerricStoreClient {
     ferricstoreMetrics(...args: CommandArgument[]): Promise<Record<string, unknown>>;
     ferricstoreBlobgc(...args: CommandArgument[]): Promise<unknown>;
     ferricstoreDoctor(...args: CommandArgument[]): Promise<unknown>;
+    capabilities(): Promise<Record<string, unknown>>;
+    ensureNamespace(prefix: string, attrs?: ManagementPairs): Promise<unknown>;
+    getNamespace(prefix: string): Promise<unknown>;
+    listNamespaces(): Promise<unknown>;
+    deleteNamespace(prefix: string): Promise<unknown>;
+    setQuota(namespace: string, quotaSpec?: ManagementPairs): Promise<unknown>;
+    getQuota(namespace: string): Promise<unknown>;
+    quotaUsage(namespace: string): Promise<unknown>;
+    clusterInfo(): Promise<Record<string, unknown>>;
+    namespaceUsage(prefix: string): Promise<Record<string, unknown>>;
+    flowQuery(attrs?: ManagementPairs): Promise<unknown[]>;
+    flowHistory(id: string, attrs?: ManagementPairs): Promise<unknown[]>;
     create(id: string, options: CreateOptions): Promise<FlowRecord | Buffer | unknown>;
     enqueue(id: string, options: Omit<CreateOptions, "state"> & {
         state?: string;
@@ -912,6 +1182,7 @@ declare class FerricStoreClient {
         full?: boolean;
     }): Promise<FlowRecord<TPayload> | undefined>;
     list(type: string, options?: ReadOptions): Promise<FlowRecord[]>;
+    search(type: string, options?: SearchOptions): Promise<FlowRecord[]>;
     terminals(type: string, options?: ReadOptions): Promise<FlowRecord[]>;
     failures(type: string, options?: ReadOptions): Promise<FlowRecord[]>;
     byParent(parentFlowId: string, options?: ReadOptions): Promise<FlowRecord[]>;
@@ -1289,4 +1560,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, COMMAND_OPCODES, 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 EndpointPolicy, 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 ManagementPairs, type MutateOptions, type NamedValueMutation, NativeAdapter, type NativeAdapterOptions, type Outcome, OverloadedError, type ProtocolCommand, Queue, type QueueBatchHandler, QueueClient, type QueueHandler, type QueueJob, type QueueOptions, QueueWorker, type QueueWorkerResult, type RangeLimit, type RateLimitResult, RawCodec, type ReadOptions, type ReclaimOptions, type ReconnectOptions, ReconnectingExecutor, type RetryOptions, type RetryOutcome, type RetryPolicy, type RoutingEndpoint, type RoutingRoute, RoutingTopology, type ScanOptions, type SearchOptions, type SearchStateMeta, type SetOptions, SetStore, SortedSetStore, StaleLeaseError, type StateMeta, type StateMetaValue, type StateOptions, type StateRegistration, type StoreCommandClient, StreamStore, type TDigestCreateOptions, type TDigestMergeOptions, TDigestStore, type TopKReserveOptions, TopKStore, TopologyNativeAdapterPool, 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 };