@valkey/valkey-glide 2.1.1 → 2.2.0-rc1

package/build-ts/BaseClient.d.ts

@@ -1,3 +1,6 @@
+/**
+ * Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
+ */
 import * as net from "net";
 import { Buffer, Writer } from "protobufjs/minimal";
 import { AggregationType, BaseScanOptions, BitFieldGet, // eslint-disable-line @typescript-eslint/no-unused-vars
@@ -109,8 +112,27 @@ export type ReturnTypeXinfoStream = Record<string, StreamEntries | Record<string
  * See {@link ReturnTypeXinfoStream}.
  */
 export type StreamEntries = GlideString | number | (GlideString | number | GlideString[])[][];
+/** Represents the types of services that can be used for IAM authentication. */
+export declare enum ServiceType {
+    Elasticache = "Elasticache",
+    MemoryDB = "MemoryDB"
+}
+/** Configuration settings for IAM authentication. */
+export interface IamAuthConfig {
+    /** The name of the ElastiCache/MemoryDB cluster. */
+    clusterName: string;
+    /** The type of service being used (ElastiCache or MemoryDB). */
+    service: ServiceType;
+    /** The AWS region where the ElastiCache/MemoryDB cluster is located. */
+    region: string;
+    /**
+     * Optional refresh interval in seconds for renewing IAM authentication tokens.
+     * If not provided, defaults to 300 seconds (5 min).
+     */
+    refreshIntervalSeconds?: number;
+}
 /** Represents the credentials for connecting to a server. */
-export interface ServerCredentials {
+export type ServerCredentials = {
     /**
      * The username that will be used for authenticating connections to the Valkey servers.
      * If not supplied, "default" will be used.
@@ -118,9 +140,18 @@ export interface ServerCredentials {
     username?: string;
     /**
      * The password that will be used for authenticating connections to the Valkey servers.
+     * (mutually exclusive with iamConfig).
      */
     password: string;
-}
+} | {
+    /** Username is REQUIRED for IAM (Valkey AUTH <username> <token>). */
+    username: string;
+    /**
+     * IAM config (mutually exclusive with password).
+     * The client will automatically generate and refresh the authentication token based on the provided configuration.
+     */
+    iamConfig: IamAuthConfig;
+};
 /** Represents the client's read from strategy. */
 export type ReadFrom = 
 /** Always get from primary, in order to get the freshest data.*/
@@ -450,6 +481,17 @@ export interface AdvancedBaseClientConfiguration {
          * - Default: false (verification is enforced).
          */
         insecure?: boolean;
+        /**
+         * Custom root certificate data for TLS connections.
+         *
+         * - When provided, these certificates will be used instead of the system's default trust store.
+         *   If not provided, the system's default certificate trust store will be used.
+         *
+         * - The certificate data should be in PEM format as a string or Buffer.
+         *
+         * - This is useful when connecting to servers with self-signed certificates or custom certificate authorities.
+         */
+        rootCertificates?: string | Buffer;
     };
 }
 /**
@@ -502,6 +544,7 @@ export declare class BaseClient {
     private writeBufferedRequestsToSocket;
     protected ensureClientIsOpen(): void;
     protected createUpdateConnectionPasswordPromise(command: command_request.UpdateConnectionPassword): Promise<GlideString>;
+    protected createRefreshIamTokenPromise(command: command_request.RefreshIamToken): Promise<GlideString>;
     protected createScriptInvocationPromise<T = GlideString>(command: command_request.ScriptInvocation, options?: {
         keys?: GlideString[];
         args?: GlideString[];
@@ -6377,6 +6420,19 @@ export declare class BaseClient {
      * ```
      */
     updateConnectionPassword(password: string | null, immediateAuth?: boolean): Promise<GlideString>;
+    /**
+     * Manually refresh the IAM token for the current connection.
+     *
+     * This method is only available if the client was created with IAM authentication.
+     * It triggers an immediate refresh of the IAM token and updates the connection.
+     *
+     * @throws ConfigurationError if the client is not using IAM authentication.
+     * @example
+     * ```typescript
+     * await client.refreshToken();
+     * ```
+     */
+    refreshIamToken(): Promise<GlideString>;
     /**
      * Return a statistics
      *

package/build-ts/BaseClient.js

@@ -1,4 +1,7 @@
 "use strict";
+/**
+ * Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
+ */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -36,13 +39,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BaseClient = exports.ObjectType = exports.Decoder = exports.ProtocolVersion = void 0;
+exports.BaseClient = exports.ObjectType = exports.ServiceType = exports.Decoder = exports.ProtocolVersion = void 0;
 exports.convertGlideRecord = convertGlideRecord;
 exports.convertGlideRecordToRecord = convertGlideRecordToRecord;
 exports.isGlideRecord = isGlideRecord;
 exports.convertRecordToGlideRecord = convertRecordToGlideRecord;
 /**
- * Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
+ * Note: 'eslint-disable-line @typescript-eslint/no-unused-vars' is used intentionally
+ * to suppress unused import errors for types referenced only in JSDoc.
  */
 const long_1 = __importDefault(require("long"));
 const net = __importStar(require("net"));
@@ -155,6 +159,12 @@ class PointerResponse {
         this.low = low;
     }
 }
+/** Represents the types of services that can be used for IAM authentication. */
+var ServiceType;
+(function (ServiceType) {
+    ServiceType["Elasticache"] = "Elasticache";
+    ServiceType["MemoryDB"] = "MemoryDB";
+})(ServiceType || (exports.ServiceType = ServiceType = {}));
 /**
  * Enum of Valkey data types
  * `STRING`
@@ -509,6 +519,19 @@ class BaseClient {
             });
         });
     }
+    createRefreshIamTokenPromise(command) {
+        this.ensureClientIsOpen();
+        return new Promise((resolve, reject) => {
+            const callbackIdx = this.getCallbackIndex();
+            this.promiseCallbackFunctions[callbackIdx] = [resolve, reject];
+            this.writeOrBufferRequest(new ProtobufMessage_1.command_request.CommandRequest({
+                callbackIdx,
+                refreshIamToken: command,
+            }), (message, writer) => {
+                ProtobufMessage_1.command_request.CommandRequest.encodeDelimited(message, writer);
+            });
+        });
+    }
     createScriptInvocationPromise(command, options = {}) {
         this.ensureClientIsOpen();
         return new Promise((resolve, reject) => {
@@ -6938,13 +6961,42 @@ class BaseClient {
         const readFrom = options.readFrom
             ? this.MAP_READ_FROM_STRATEGY[options.readFrom]
             : ProtobufMessage_1.connection_request.ReadFrom.Primary;
-        const authenticationInfo = options.credentials !== undefined &&
-            "password" in options.credentials
-            ? {
-                password: options.credentials.password,
-                username: options.credentials.username,
+        const creds = options.credentials;
+        // Build a protobuf AuthenticationInfo
+        let authenticationInfo;
+        if (creds) {
+            if ("iamConfig" in creds) {
+                if (!creds.username) {
+                    throw new _1.ConfigurationError("IAM authentication requires a username.");
+                }
+                const iamCredentials = ProtobufMessage_1.connection_request.IamCredentials.create({
+                    clusterName: creds.iamConfig.clusterName,
+                    region: creds.iamConfig.region,
+                    serviceType: creds.iamConfig.service === ServiceType.Elasticache
+                        ? ProtobufMessage_1.connection_request.ServiceType.ELASTICACHE
+                        : ProtobufMessage_1.connection_request.ServiceType.MEMORYDB,
+                    // leave undefined if not provided (optional field)
+                    refreshIntervalSeconds: creds.iamConfig.refreshIntervalSeconds,
+                });
+                authenticationInfo =
+                    ProtobufMessage_1.connection_request.AuthenticationInfo.create({
+                        username: creds.username, // REQUIRED for IAM
+                        iamCredentials,
+                        // do NOT set password in IAM mode
+                    });
             }
-            : undefined;
+            else if ("password" in creds) {
+                // Password branch
+                authenticationInfo =
+                    ProtobufMessage_1.connection_request.AuthenticationInfo.create({
+                        username: creds.username ?? "", // optional
+                        password: creds.password ?? "", // empty means “no password”
+                    });
+            }
+            else {
+                authenticationInfo = undefined;
+            }
+        }
         const protocol = options.protocol;
         // Validate that clientAz is set when using AZ affinity strategies
         if ((options.readFrom === "AZAffinity" ||
@@ -6978,12 +7030,21 @@ class BaseClient {
             options.connectionTimeout ??
                 _1.DEFAULT_CONNECTION_TIMEOUT_IN_MILLISECONDS;
         // Apply TLS configuration if present
-        if (options.tlsAdvancedConfiguration?.insecure) {
-            if (request.tlsMode === ProtobufMessage_1.connection_request.TlsMode.SecureTls) {
+        if (options.tlsAdvancedConfiguration) {
+            // request.tlsMode is either SecureTls or InsecureTls here
+            if (request.tlsMode === ProtobufMessage_1.connection_request.TlsMode.NoTls) {
+                throw new _1.ConfigurationError("TLS advanced configuration cannot be set when useTLS is disabled.");
+            }
+            // If options.tlsAdvancedConfiguration.insecure is true then use InsecureTls mode
+            if (options.tlsAdvancedConfiguration.insecure) {
                 request.tlsMode = ProtobufMessage_1.connection_request.TlsMode.InsecureTls;
             }
-            else if (request.tlsMode === ProtobufMessage_1.connection_request.TlsMode.NoTls) {
-                throw new _1.ConfigurationError("InsecureTls cannot be enabled when useTLS is disabled.");
+            if (options.tlsAdvancedConfiguration.rootCertificates) {
+                const certData = typeof options.tlsAdvancedConfiguration.rootCertificates ===
+                    "string"
+                    ? Buffer.from(options.tlsAdvancedConfiguration.rootCertificates, "utf-8")
+                    : options.tlsAdvancedConfiguration.rootCertificates;
+                request.rootCerts = [new Uint8Array(certData)];
             }
         }
     }
@@ -7025,8 +7086,10 @@ class BaseClient {
      */
     static async __createClientInternal(options, connectedSocket, constructor) {
         const connection = constructor(connectedSocket, options);
+        const connectStart = Date.now();
         await connection.connectToServer(options);
-        _1.Logger.log("info", "Client lifetime", "connected to server");
+        const connectTime = Date.now() - connectStart;
+        _1.Logger.log("info", "Client lifetime", `connected to server in ${connectTime}ms`);
         return connection;
     }
     /**
@@ -7045,10 +7108,17 @@ class BaseClient {
      * @internal
      */
     static async createClientInternal(options, constructor) {
+        const overallStart = Date.now();
         const path = await (0, _1.StartSocketConnection)();
+        const socketStart = Date.now();
         const socket = await this.GetSocket(path);
+        const socketTime = Date.now() - socketStart;
+        _1.Logger.log("info", "Client lifetime", `socket connection established in ${socketTime}ms`);
         try {
-            return await this.__createClientInternal(options, socket, constructor);
+            const client = await this.__createClientInternal(options, socket, constructor);
+            const totalTime = Date.now() - overallStart;
+            _1.Logger.log("info", "Client lifetime", `total client creation time: ${totalTime}ms`);
+            return client;
         }
         catch (err) {
             // Ensure socket is closed
@@ -7077,6 +7147,12 @@ class BaseClient {
      * ```
      */
     async updateConnectionPassword(password, immediateAuth = false) {
+        // If we’re on IAM, forbid password updates to avoid confusion.
+        const creds = this.config?.credentials;
+        const usingIam = !!creds && "iamConfig" in creds;
+        if (usingIam) {
+            throw new _1.ConfigurationError("updateConnectionPassword is not supported when IAM authentication is enabled.");
+        }
         const updateConnectionPassword = ProtobufMessage_1.command_request.UpdateConnectionPassword.create({
             password,
             immediateAuth,
@@ -7093,6 +7169,27 @@ class BaseClient {
         }
         return response;
     }
+    /**
+     * Manually refresh the IAM token for the current connection.
+     *
+     * This method is only available if the client was created with IAM authentication.
+     * It triggers an immediate refresh of the IAM token and updates the connection.
+     *
+     * @throws ConfigurationError if the client is not using IAM authentication.
+     * @example
+     * ```typescript
+     * await client.refreshToken();
+     * ```
+     */
+    async refreshIamToken() {
+        if (!this.config?.credentials ||
+            !("iamConfig" in this.config.credentials)) {
+            throw new _1.ConfigurationError("refreshIamToken is only available when IAM authentication is enabled.");
+        }
+        const refresh = ProtobufMessage_1.command_request.RefreshIamToken.create({});
+        const response = await this.createRefreshIamTokenPromise(refresh);
+        return response; // "OK"
+    }
     /**
      * Return a statistics
      *

package/build-ts/Batch.d.ts

@@ -1,6 +1,10 @@
 /**
  * Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
  */
+/**
+ * Note: 'eslint-disable-line @typescript-eslint/no-unused-vars' is used intentionally
+ * to suppress unused import errors for types referenced only in JSDoc.
+ */
 import { AggregationType, BaseScanOptions, BitFieldGet, // eslint-disable-line @typescript-eslint/no-unused-vars
 BitFieldSubCommands, // eslint-disable-line @typescript-eslint/no-unused-vars
 BitOffsetOptions, BitwiseOperation, Boundary, // eslint-disable-line @typescript-eslint/no-unused-vars

package/build-ts/Batch.js

@@ -4,6 +4,10 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Transaction = exports.ClusterTransaction = exports.ClusterBatch = exports.Batch = exports.BaseBatch = void 0;
+/**
+ * Note: 'eslint-disable-line @typescript-eslint/no-unused-vars' is used intentionally
+ * to suppress unused import errors for types referenced only in JSDoc.
+ */
 const _1 = require(".");
 /**
  * Base class encompassing shared commands for both standalone and cluster mode implementations in a Batch.

package/build-ts/Commands.d.ts

@@ -1,7 +1,8 @@
 /**
  * Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
  */
-import { GlideString, HashDataType, ObjectType, SingleNodeRoute } from ".";
+import { GlideString, HashDataType, ObjectType } from "./BaseClient";
+import { SingleNodeRoute } from "./GlideClusterClient";
 /**
  * @test
  */

package/build-ts/Commands.js

@@ -227,15 +227,20 @@ exports.createXGroupSetid = createXGroupSetid;
 exports.createScriptExists = createScriptExists;
 exports.createScriptFlush = createScriptFlush;
 exports.createScriptKill = createScriptKill;
+/**
+ * Note: 'eslint-disable-line @typescript-eslint/no-unused-vars' is used intentionally
+ * to suppress unused import errors for types referenced only in JSDoc.
+ */
 const long_1 = __importDefault(require("long"));
-const _1 = require(".");
+const BaseClient_1 = require("./BaseClient");
+const native_1 = require("../build-ts/native");
 const ProtobufMessage_1 = require("../build-ts/ProtobufMessage");
 var RequestType = ProtobufMessage_1.command_request.RequestType;
 function isLargeCommand(args) {
     let lenSum = 0;
     for (const arg of args) {
         lenSum += arg.length;
-        if (lenSum >= _1.MAX_REQUEST_ARGS_LEN) {
+        if (lenSum >= native_1.MAX_REQUEST_ARGS_LEN) {
             return true;
         }
     }
@@ -278,7 +283,7 @@ function createCommand(requestType, args) {
     const argsBytes = toBuffersArray(args);
     if (isLargeCommand(args)) {
         // pass as a pointer
-        const pointerArr = (0, _1.createLeakedStringVec)(argsBytes);
+        const pointerArr = (0, native_1.createLeakedStringVec)(argsBytes);
         const pointer = new long_1.default(pointerArr[0], pointerArr[1]);
         singleCommand.argsVecPointer = pointer;
     }
@@ -2100,7 +2105,7 @@ var FlushMode;
  */
 function convertKeysAndEntries(record) {
     if (!Array.isArray(record)) {
-        return (0, _1.convertRecordToGlideRecord)(record);
+        return (0, BaseClient_1.convertRecordToGlideRecord)(record);
     }
     return record;
 }

package/build-ts/GlideClient.d.ts

@@ -1,7 +1,9 @@
 /**
  * Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
  */
-import { AdvancedBaseClientConfiguration, BaseClient, BaseClientConfiguration, Batch, BatchOptions, DecoderOption, FlushMode, FunctionListOptions, FunctionListResponse, FunctionRestorePolicy, FunctionStatsFullResponse, GlideReturnType, GlideString, InfoOptions, LolwutOptions, PubSubMsg, ScanOptions } from ".";
+import { AdvancedBaseClientConfiguration, BaseClient, BaseClientConfiguration, DecoderOption, GlideReturnType, GlideString, PubSubMsg } from "./BaseClient";
+import { Batch } from "./Batch";
+import { BatchOptions, FlushMode, FunctionListOptions, FunctionListResponse, FunctionRestorePolicy, FunctionStatsFullResponse, InfoOptions, LolwutOptions, ScanOptions } from "./Commands";
 export declare namespace GlideClientConfiguration {
     /**
      * Enum representing pubsub subscription modes.