memcache 1.2.0 → 1.4.0

package/dist/index.d.ts

@@ -6,10 +6,13 @@ interface MemcacheNodeOptions {
     keepAlive?: boolean;
     keepAliveDelay?: number;
     weight?: number;
+    /** SASL authentication credentials */
+    sasl?: SASLCredentials;
 }
 interface CommandOptions {
     isMultiline?: boolean;
     isStats?: boolean;
+    isConfig?: boolean;
     requestedKeys?: string[];
 }
 type CommandQueueItem = {
@@ -18,6 +21,7 @@ type CommandQueueItem = {
     reject: (reason?: any) => void;
     isMultiline?: boolean;
     isStats?: boolean;
+    isConfig?: boolean;
     requestedKeys?: string[];
     foundKeys?: string[];
 };
@@ -39,6 +43,9 @@ declare class MemcacheNode extends Hookified {
     private _currentCommand;
     private _multilineData;
     private _pendingValueBytes;
+    private _sasl;
+    private _authenticated;
+    private _binaryBuffer;
     constructor(host: string, port: number, options?: MemcacheNodeOptions);
     /**
      * Get the host of this node
@@ -88,6 +95,14 @@ declare class MemcacheNode extends Hookified {
      * Get the command queue
      */
     get commandQueue(): CommandQueueItem[];
+    /**
+     * Get whether SASL authentication is configured
+     */
+    get hasSaslCredentials(): boolean;
+    /**
+     * Get whether the node is authenticated (only relevant if SASL is configured)
+     */
+    get isAuthenticated(): boolean;
     /**
      * Connect to the memcache server
      */
@@ -100,6 +115,71 @@ declare class MemcacheNode extends Hookified {
      * Reconnect to the memcache server by disconnecting and connecting again
      */
     reconnect(): Promise<void>;
+    /**
+     * Perform SASL PLAIN authentication using the binary protocol
+     */
+    private performSaslAuth;
+    /**
+     * Send a binary protocol request and wait for response.
+     * Used internally for SASL-authenticated connections.
+     */
+    private binaryRequest;
+    /**
+     * Binary protocol GET operation
+     */
+    binaryGet(key: string): Promise<string | undefined>;
+    /**
+     * Binary protocol SET operation
+     */
+    binarySet(key: string, value: string, exptime?: number, flags?: number): Promise<boolean>;
+    /**
+     * Binary protocol ADD operation
+     */
+    binaryAdd(key: string, value: string, exptime?: number, flags?: number): Promise<boolean>;
+    /**
+     * Binary protocol REPLACE operation
+     */
+    binaryReplace(key: string, value: string, exptime?: number, flags?: number): Promise<boolean>;
+    /**
+     * Binary protocol DELETE operation
+     */
+    binaryDelete(key: string): Promise<boolean>;
+    /**
+     * Binary protocol INCREMENT operation
+     */
+    binaryIncr(key: string, delta?: number, initial?: number, exptime?: number): Promise<number | undefined>;
+    /**
+     * Binary protocol DECREMENT operation
+     */
+    binaryDecr(key: string, delta?: number, initial?: number, exptime?: number): Promise<number | undefined>;
+    /**
+     * Binary protocol APPEND operation
+     */
+    binaryAppend(key: string, value: string): Promise<boolean>;
+    /**
+     * Binary protocol PREPEND operation
+     */
+    binaryPrepend(key: string, value: string): Promise<boolean>;
+    /**
+     * Binary protocol TOUCH operation
+     */
+    binaryTouch(key: string, exptime: number): Promise<boolean>;
+    /**
+     * Binary protocol FLUSH operation
+     */
+    binaryFlush(exptime?: number): Promise<boolean>;
+    /**
+     * Binary protocol VERSION operation
+     */
+    binaryVersion(): Promise<string | undefined>;
+    /**
+     * Binary protocol STATS operation
+     */
+    binaryStats(): Promise<Record<string, string>>;
+    /**
+     * Binary protocol QUIT operation
+     */
+    binaryQuit(): Promise<void>;
     /**
      * Gracefully quit the connection (send quit command then disconnect)
      */
@@ -137,6 +217,24 @@ declare class MemcacheNode extends Hookified {
  */
 declare function createNode(host: string, port: number, options?: MemcacheNodeOptions): MemcacheNode;
 
+/**
+ * SASL authentication credentials for connecting to a secured memcache server.
+ */
+interface SASLCredentials {
+    /**
+     * Username for SASL authentication
+     */
+    username: string;
+    /**
+     * Password for SASL authentication
+     */
+    password: string;
+    /**
+     * SASL mechanism to use (default: 'PLAIN')
+     * Currently only 'PLAIN' is supported.
+     */
+    mechanism?: "PLAIN";
+}
 declare enum MemcacheEvents {
     CONNECT = "connect",
     QUIT = "quit",
@@ -146,8 +244,18 @@ declare enum MemcacheEvents {
     WARN = "warn",
     INFO = "info",
     TIMEOUT = "timeout",
-    CLOSE = "close"
+    CLOSE = "close",
+    AUTO_DISCOVER = "autoDiscover",
+    AUTO_DISCOVER_ERROR = "autoDiscoverError",
+    AUTO_DISCOVER_UPDATE = "autoDiscoverUpdate"
 }
+/**
+ * Function to calculate delay between retry attempts.
+ * @param attempt - The current attempt number (0-indexed)
+ * @param baseDelay - The base delay in milliseconds
+ * @returns The delay in milliseconds before the next retry
+ */
+type RetryBackoffFunction = (attempt: number, baseDelay: number) => number;
 interface HashProvider {
     name: string;
     nodes: Array<MemcacheNode>;
@@ -183,20 +291,327 @@ interface MemcacheOptions {
      * on the number of nodes and hashing. By default it uses KetamaHash as the provider
      */
     hash?: HashProvider;
+    /**
+     * The number of retry attempts for failed commands.
+     * Set to 0 to disable retries.
+     * @default 0
+     */
+    retries?: number;
+    /**
+     * The base delay in milliseconds between retry attempts.
+     * @default 100
+     */
+    retryDelay?: number;
+    /**
+     * Function to calculate backoff delay between retries.
+     * Receives (attempt, baseDelay) and returns delay in ms.
+     * @default defaultRetryBackoff (fixed delay)
+     */
+    retryBackoff?: RetryBackoffFunction;
+    /**
+     * When true, retries are only performed for commands marked as idempotent.
+     * This prevents accidental double-execution of non-idempotent operations
+     * (like incr, decr, append) if the server applies the command but the
+     * client doesn't receive the response before a timeout/disconnect.
+     * @default true
+     */
+    retryOnlyIdempotent?: boolean;
+    /**
+     * SASL authentication credentials for all nodes.
+     * When provided, nodes will authenticate using SASL PLAIN mechanism
+     * before accepting commands.
+     */
+    sasl?: SASLCredentials;
+    /**
+     * AWS ElastiCache Auto Discovery configuration.
+     * When enabled, the client will periodically poll the configuration endpoint
+     * to detect cluster topology changes and automatically update the node list.
+     */
+    autoDiscover?: AutoDiscoverOptions;
 }
 interface MemcacheStats {
     [key: string]: string;
 }
+/**
+ * Configuration for AWS ElastiCache Auto Discovery.
+ * When enabled, the client connects to a configuration endpoint and periodically
+ * polls for cluster topology changes, automatically adding/removing nodes.
+ */
+interface AutoDiscoverOptions {
+    /**
+     * Enable auto discovery of cluster nodes.
+     */
+    enabled: boolean;
+    /**
+     * How often to poll for topology changes, in milliseconds.
+     * @default 60000
+     */
+    pollingInterval?: number;
+    /**
+     * The configuration endpoint to use for discovery.
+     * This is typically the .cfg endpoint from ElastiCache.
+     * If not specified, the first node in the nodes array will be used.
+     */
+    configEndpoint?: string;
+    /**
+     * Use the legacy `get AmazonElastiCache:cluster` command
+     * instead of `config get cluster` (for engine versions < 1.4.14).
+     * @default false
+     */
+    useLegacyCommand?: boolean;
+}
+/**
+ * Represents a discovered node from the ElastiCache cluster configuration.
+ */
+interface DiscoveredNode {
+    /** The hostname of the node */
+    hostname: string;
+    /** The IP address of the node (may be empty string) */
+    ip: string;
+    /** The port number of the node */
+    port: number;
+}
+/**
+ * Represents the parsed result of an ElastiCache cluster config response.
+ */
+interface ClusterConfig {
+    /** The config version number (increments on topology changes) */
+    version: number;
+    /** The list of discovered nodes */
+    nodes: DiscoveredNode[];
+}
 interface ExecuteOptions {
     /** Command options passed to node.command() */
     commandOptions?: CommandOptions;
+    /**
+     * Override the number of retries for this specific execution.
+     * If undefined, uses the instance-level retries setting.
+     */
+    retries?: number;
+    /**
+     * Override the retry delay for this specific execution.
+     * If undefined, uses the instance-level retryDelay setting.
+     */
+    retryDelay?: number;
+    /**
+     * Override the backoff function for this specific execution.
+     * If undefined, uses the instance-level retryBackoff setting.
+     */
+    retryBackoff?: RetryBackoffFunction;
+    /**
+     * Mark this command as idempotent, allowing retries even when
+     * retryOnlyIdempotent is true. Set this for read operations (get, gets)
+     * or operations that are safe to repeat (set with same value).
+     * @default false
+     */
+    idempotent?: boolean;
+}
+
+interface AutoDiscoveryOptions {
+    configEndpoint: string;
+    pollingInterval: number;
+    useLegacyCommand: boolean;
+    timeout: number;
+    keepAlive: boolean;
+    keepAliveDelay: number;
+    sasl?: SASLCredentials;
+}
+/**
+ * Handles AWS ElastiCache Auto Discovery for memcache clusters.
+ * Connects to a configuration endpoint, periodically polls for cluster
+ * topology changes, and emits events when nodes are added or removed.
+ */
+declare class AutoDiscovery extends Hookified {
+    private _configEndpoint;
+    private _pollingInterval;
+    private _useLegacyCommand;
+    private _configVersion;
+    private _pollingTimer;
+    private _configNode;
+    private _timeout;
+    private _keepAlive;
+    private _keepAliveDelay;
+    private _sasl;
+    private _isRunning;
+    private _isPolling;
+    constructor(options: AutoDiscoveryOptions);
+    /** Current config version. -1 means no config has been fetched yet. */
+    get configVersion(): number;
+    /** Whether auto discovery is currently running. */
+    get isRunning(): boolean;
+    /** The configuration endpoint being used. */
+    get configEndpoint(): string;
+    /**
+     * Start the auto discovery process.
+     * Performs an initial discovery, then starts the polling timer.
+     */
+    start(): Promise<ClusterConfig>;
+    /**
+     * Stop the auto discovery process.
+     */
+    stop(): Promise<void>;
+    /**
+     * Perform a single discovery cycle.
+     * Returns the ClusterConfig if the version has changed, or undefined if unchanged.
+     */
+    discover(): Promise<ClusterConfig | undefined>;
+    /**
+     * Parse the raw response data from a config get cluster command.
+     * The raw data is the value content between the CONFIG/VALUE header and END.
+     * Format: "<version>\n<host1>|<ip1>|<port1> <host2>|<ip2>|<port2>\n"
+     */
+    static parseConfigResponse(rawData: string[]): ClusterConfig;
+    /**
+     * Parse a single node entry in the format "hostname|ip|port".
+     */
+    static parseNodeEntry(entry: string): DiscoveredNode;
+    /**
+     * Build a node ID from a DiscoveredNode.
+     * Prefers IP when available, falls back to hostname.
+     */
+    static nodeId(node: DiscoveredNode): string;
+    private ensureConfigNode;
+    private fetchConfig;
+    private poll;
+    private parseEndpoint;
+}
+
+/**
+ * Function that returns an unsigned 32-bit hash of the input.
+ */
+type HashFunction = (input: Buffer) => number;
+/**
+ * A distribution hash implementation using modulo-based hashing.
+ * This class provides a simple key distribution strategy where keys are
+ * assigned to nodes using `hash(key) % nodeCount`.
+ *
+ * Unlike consistent hashing (Ketama), modulo hashing redistributes all keys
+ * when nodes are added or removed. This makes it suitable for:
+ * - Fixed-size clusters
+ * - Testing environments
+ * - Scenarios where simplicity is preferred over minimal redistribution
+ *
+ * @example
+ * ```typescript
+ * const distribution = new ModulaHash();
+ * distribution.addNode(node1);
+ * distribution.addNode(node2);
+ * const targetNode = distribution.getNodesByKey('my-key')[0];
+ * ```
+ */
+declare class ModulaHash implements HashProvider {
+    /** The name of this distribution strategy */
+    readonly name = "modula";
+    /** The hash function used to compute key hashes */
+    private readonly hashFn;
+    /** Map of node IDs to MemcacheNode instances */
+    private nodeMap;
+    /**
+     * Weighted list of node IDs for modulo distribution.
+     * Nodes with higher weights appear multiple times.
+     */
+    private nodeList;
+    /**
+     * Creates a new ModulaHash instance.
+     *
+     * @param hashFn - Hash function to use (string algorithm name or custom function, defaults to "sha1")
+     *
+     * @example
+     * ```typescript
+     * // Use default SHA-1 hashing
+     * const distribution = new ModulaHash();
+     *
+     * // Use MD5 hashing
+     * const distribution = new ModulaHash('md5');
+     *
+     * // Use custom hash function
+     * const distribution = new ModulaHash((buf) => buf.readUInt32BE(0));
+     * ```
+     */
+    constructor(hashFn?: string | HashFunction);
+    /**
+     * Gets all nodes in the distribution.
+     * @returns Array of all MemcacheNode instances
+     */
+    get nodes(): Array<MemcacheNode>;
+    /**
+     * Adds a node to the distribution with its weight.
+     * Weight determines how many times the node appears in the distribution list.
+     *
+     * @param node - The MemcacheNode to add
+     *
+     * @example
+     * ```typescript
+     * const node = new MemcacheNode('localhost', 11211, { weight: 2 });
+     * distribution.addNode(node);
+     * ```
+     */
+    addNode(node: MemcacheNode): void;
+    /**
+     * Removes a node from the distribution by its ID.
+     *
+     * @param id - The node ID (e.g., "localhost:11211")
+     *
+     * @example
+     * ```typescript
+     * distribution.removeNode('localhost:11211');
+     * ```
+     */
+    removeNode(id: string): void;
+    /**
+     * Gets a specific node by its ID.
+     *
+     * @param id - The node ID (e.g., "localhost:11211")
+     * @returns The MemcacheNode if found, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * const node = distribution.getNode('localhost:11211');
+     * if (node) {
+     *   console.log(`Found node: ${node.uri}`);
+     * }
+     * ```
+     */
+    getNode(id: string): MemcacheNode | undefined;
+    /**
+     * Gets the nodes responsible for a given key using modulo hashing.
+     * Uses `hash(key) % nodeCount` to determine the target node.
+     *
+     * @param key - The cache key to find the responsible node for
+     * @returns Array containing the responsible node(s), empty if no nodes available
+     *
+     * @example
+     * ```typescript
+     * const nodes = distribution.getNodesByKey('user:123');
+     * if (nodes.length > 0) {
+     *   console.log(`Key will be stored on: ${nodes[0].id}`);
+     * }
+     * ```
+     */
+    getNodesByKey(key: string): Array<MemcacheNode>;
 }
+
+/**
+ * Default backoff function - returns fixed delay
+ */
+declare const defaultRetryBackoff: RetryBackoffFunction;
+/**
+ * Exponential backoff function - doubles delay each attempt
+ */
+declare const exponentialRetryBackoff: RetryBackoffFunction;
 declare class Memcache extends Hookified {
     private _nodes;
     private _timeout;
     private _keepAlive;
     private _keepAliveDelay;
     private _hash;
+    private _retries;
+    private _retryDelay;
+    private _retryBackoff;
+    private _retryOnlyIdempotent;
+    private _sasl;
+    private _autoDiscovery;
+    private _autoDiscoverOptions;
     constructor(options?: string | MemcacheOptions);
     /**
      * Get the list of nodes
@@ -274,6 +689,58 @@ declare class Memcache extends Hookified {
      * @default 1000
      */
     set keepAliveDelay(value: number);
+    /**
+     * Get the number of retry attempts for failed commands.
+     * @returns {number}
+     * @default 0
+     */
+    get retries(): number;
+    /**
+     * Set the number of retry attempts for failed commands.
+     * Set to 0 to disable retries.
+     * @param {number} value
+     * @default 0
+     */
+    set retries(value: number);
+    /**
+     * Get the base delay in milliseconds between retry attempts.
+     * @returns {number}
+     * @default 100
+     */
+    get retryDelay(): number;
+    /**
+     * Set the base delay in milliseconds between retry attempts.
+     * @param {number} value
+     * @default 100
+     */
+    set retryDelay(value: number);
+    /**
+     * Get the backoff function for retry delays.
+     * @returns {RetryBackoffFunction}
+     * @default defaultRetryBackoff
+     */
+    get retryBackoff(): RetryBackoffFunction;
+    /**
+     * Set the backoff function for retry delays.
+     * @param {RetryBackoffFunction} value
+     * @default defaultRetryBackoff
+     */
+    set retryBackoff(value: RetryBackoffFunction);
+    /**
+     * Get whether retries are restricted to idempotent commands only.
+     * @returns {boolean}
+     * @default true
+     */
+    get retryOnlyIdempotent(): boolean;
+    /**
+     * Set whether retries are restricted to idempotent commands only.
+     * When true (default), retries only occur for commands explicitly marked
+     * as idempotent via ExecuteOptions. This prevents accidental double-execution
+     * of non-idempotent operations like incr, decr, append, etc.
+     * @param {boolean} value
+     * @default true
+     */
+    set retryOnlyIdempotent(value: boolean);
     /**
      * Get an array of all MemcacheNode instances
      * @returns {MemcacheNode[]}
@@ -479,10 +946,10 @@ declare class Memcache extends Hookified {
      */
     getNodesByKey(key: string): Promise<Array<MemcacheNode>>;
     /**
-     * Execute a command on the specified nodes.
+     * Execute a command on the specified nodes with retry support.
      * @param {string} command - The memcache command string to execute
      * @param {MemcacheNode[]} nodes - Array of MemcacheNode instances to execute on
-     * @param {ExecuteOptions} options - Optional execution options
+     * @param {ExecuteOptions} options - Optional execution options including retry overrides
      * @returns {Promise<unknown[]>} Promise resolving to array of results from each node
      */
     execute(command: string, nodes: MemcacheNode[], options?: ExecuteOptions): Promise<unknown[]>;
@@ -500,6 +967,23 @@ declare class Memcache extends Hookified {
      * ```
      */
     validateKey(key: string): void;
+    /**
+     * Sleep utility for retry delays.
+     * @param {number} ms - Milliseconds to sleep
+     * @returns {Promise<void>}
+     */
+    private sleep;
+    /**
+     * Execute a command on a single node with retry logic.
+     * @param {MemcacheNode} node - The node to execute on
+     * @param {string} command - The command string
+     * @param {CommandOptions} commandOptions - Optional command options
+     * @param {number} maxRetries - Maximum number of retry attempts
+     * @param {number} retryDelay - Base delay between retries in milliseconds
+     * @param {RetryBackoffFunction} retryBackoff - Function to calculate backoff delay
+     * @returns {Promise<unknown>} Result or undefined on failure
+     */
+    private executeWithRetry;
     /**
      * Update all nodes with current keepAlive settings
      */
@@ -508,6 +992,8 @@ declare class Memcache extends Hookified {
      * Forward events from a MemcacheNode to the Memcache instance
      */
     private forwardNodeEvents;
+    private startAutoDiscovery;
+    private applyClusterConfig;
 }
 
-export { type ExecuteOptions, type HashProvider, Memcache, MemcacheEvents, type MemcacheOptions, type MemcacheStats, createNode, Memcache as default };
+export { type AutoDiscoverOptions, AutoDiscovery, type ClusterConfig, type DiscoveredNode, type ExecuteOptions, type HashProvider, Memcache, MemcacheEvents, MemcacheNode, type MemcacheOptions, type MemcacheStats, ModulaHash, type RetryBackoffFunction, type SASLCredentials, createNode, Memcache as default, defaultRetryBackoff, exponentialRetryBackoff };