ibm-cloud-sdk-core 5.0.1 → 5.1.0

package/es/lib/request-wrapper.js

@@ -9,7 +9,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 /**
- * (C) Copyright IBM Corp. 2014, 2023.
+ * (C) Copyright IBM Corp. 2014, 2024.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -32,6 +32,7 @@ import isStream from 'isstream';
 import { stringify } from 'querystring';
 import { gzipSync } from 'zlib';
 import { buildRequestFileObject, isEmptyObject, isFileData, isFileWithMetadata, isJsonMimeType, stripTrailingSlash, } from './helper';
+import { redactSecrets } from './private-helpers';
 import logger from './logger';
 import { streamToPromise } from './stream-to-promise';
 import { createCookieInterceptor } from './cookie-support';
@@ -86,28 +87,96 @@ export class RequestWrapper {
             }
             this.enableRetries(retryOptions);
         }
-        // set debug interceptors
-        if (process.env.NODE_DEBUG === 'axios' || process.env.DEBUG) {
-            this.axiosInstance.interceptors.request.use((config) => {
-                logger.debug('Request:');
-                logger.debug(config);
-                return config;
+        // If debug logging is requested, set up interceptors to log http request/response messages.
+        if (logger.debug.enabled || process.env.NODE_DEBUG === 'axios') {
+            this.axiosInstance.interceptors.request.use((request) => {
+                logger.debug(`--> HTTP Request:\n${this.formatAxiosRequest(request)}`);
+                return request;
             }, (error) => {
-                logger.error('Error: ');
-                logger.error(error);
+                logger.debug(`<-- HTTP Error:\n${this.formatAxiosError(error)}`);
                 return Promise.reject(error);
             });
             this.axiosInstance.interceptors.response.use((response) => {
-                logger.debug('Response:');
-                logger.debug(response);
+                logger.debug(`<-- HTTP Response:\n${this.formatAxiosResponse(response)}`);
                 return response;
             }, (error) => {
-                logger.error('Error: ');
-                logger.error(error);
+                logger.debug(`<-- HTTP Error:\n${this.formatAxiosError(error)}`);
                 return Promise.reject(error);
             });
         }
     }
+    /**
+     * Formats the specified Axios request for debug logging.
+     * @param request - the request to be logged
+     * @returns the string representation of the request
+     */
+    formatAxiosRequest(request) {
+        const { method, url, data, headers } = request;
+        const headersOutput = this.formatAxiosHeaders(headers);
+        const body = this.formatAxiosBody(data);
+        const output = `${(method || '??').toUpperCase()} ${url || '??'}\n${headersOutput}\n${body}`;
+        return redactSecrets(output);
+    }
+    /**
+     * Formats the specified Axios response for debug logging.
+     * @param response - the response to be logged
+     * @returns the string representation of the response
+     */
+    formatAxiosResponse(response) {
+        const { status, statusText, headers, data } = response;
+        const headersOutput = this.formatAxiosHeaders(headers);
+        const body = this.formatAxiosBody(data);
+        const statusMsg = statusText || `status_code_${status}`;
+        const output = `${status} ${statusMsg}\n${headersOutput}\n${body}`;
+        return redactSecrets(output);
+    }
+    /**
+     * Formats the specified Axios error for debug logging.
+     * @param error - the error to be logged
+     * @returns the string representation of the error
+     */
+    formatAxiosError(error) {
+        const { response } = error;
+        let output = `HTTP error message=${error.message || ''}, code=${error.code || ''}`;
+        if (response) {
+            output = this.formatAxiosResponse(response);
+        }
+        return output;
+    }
+    /**
+     * Formats 'headers' to be included in the debug output
+     * like this:
+     *    Accept: application/json
+     *    Content-Type: application/json
+     *    My-Header: my-value
+     *    ...
+     * @param headers - the headers associated with an Axios request or response
+     * @returns the formatted output to be included in the HTTP message traces
+     */
+    formatAxiosHeaders(headers) {
+        let output = '';
+        if (headers) {
+            const lines = [];
+            Object.keys(headers).forEach((key) => {
+                lines.push(`${key}: ${headers[key]}`);
+            });
+            output = lines.join('\n');
+        }
+        return output;
+    }
+    /**
+     * Formats 'body' (either a string or object/array) to be included in the debug output
+     *
+     * @param body - a string, object or array that contains the request or response body
+     * @returns the formatted output to be included in the HTTP message traces
+     */
+    formatAxiosBody(body) {
+        let output = '';
+        if (body) {
+            output = typeof body === 'string' ? body : JSON.stringify(body);
+        }
+        return output;
+    }
     setCompressRequestData(setting) {
         this.compressRequestData = setting;
     }
@@ -293,7 +362,8 @@ export class RequestWrapper {
             instance: axiosInstance,
             backoffType: 'exponential',
             checkRetryAfter: true,
-            maxRetryDelay: 30 * 1000, // default to 30 sec max delay
+            maxRetryDelay: 30 * 1000,
+            shouldRetry: this.retryPolicy,
         };
         if (retryOptions) {
             if (typeof retryOptions.maxRetries === 'number') {
@@ -314,13 +384,42 @@ export class RequestWrapper {
         }
         this.raxConfig = RequestWrapper.getRaxConfig(this.axiosInstance, retryOptions);
         this.retryInterceptorId = rax.attach(this.axiosInstance);
+        logger.debug(`Enabled retries; maxRetries=${this.raxConfig.retry}, maxRetryInterval=${this.raxConfig.maxRetryDelay}`);
     }
     disableRetries() {
         if (typeof this.retryInterceptorId === 'number') {
             rax.detach(this.retryInterceptorId, this.axiosInstance);
             delete this.retryInterceptorId;
             delete this.raxConfig;
+            logger.debug('Disabled retries');
+        }
+    }
+    /**
+     * Returns true iff the previously-failed request contained in "error" should be retried.
+     * @param error - an AxiosError instance that contains a previously-failed request
+     * @returns true iff the request should be retried
+     */
+    static retryPolicy(error) {
+        if (logger.debug.enabled) {
+            const details = [];
+            if (error.response) {
+                const statusText = error.response.statusText || ``;
+                details.push(`status_code=${error.response.status} (${statusText})`);
+            }
+            if (error.config) {
+                if (error.config.method) {
+                    details.push(`method=${error.config.method.toUpperCase()}`);
+                }
+                if (error.config.url) {
+                    details.push(`url=${error.config.url}`);
+                }
+            }
+            logger.debug(`Considering retry attempt; ${details.join(', ')}`);
         }
+        // Delegate to the default function defined by retry-axios.
+        const shouldRetry = rax.shouldRetryRequest(error);
+        logger.debug(`Retry will ${shouldRetry ? '' : 'not '}be attempted`);
+        return shouldRetry;
     }
     gzipRequestBody(data, headers) {
         return __awaiter(this, void 0, void 0, function* () {

package/etc/ibm-cloud-sdk-core.api.md

@@ -13,10 +13,10 @@ import { OutgoingHttpHeaders } from 'http';
 import { Stream } from 'stream';
 
 // @public
-export function atLeastOne(a: any, b: any): boolean;
+export function atLeastOne(...args: any): boolean;
 
 // @public
-export function atMostOne(a: any, b: any): boolean;
+export function atMostOne(...args: any): boolean;
 
 // @public
 export class Authenticator implements AuthenticatorInterface {
@@ -34,6 +34,8 @@ export class Authenticator implements AuthenticatorInterface {
     // (undocumented)
     static AUTHTYPE_IAM: string;
     // (undocumented)
+    static AUTHTYPE_IAM_ASSUME: string;
+    // (undocumented)
     static AUTHTYPE_MCSP: string;
     // (undocumented)
     static AUTHTYPE_NOAUTH: string;
@@ -130,6 +132,7 @@ export class ContainerAuthenticator extends IamRequestBasedAuthenticator {
     // Warning: (ae-forgotten-export) The symbol "Options_8" needs to be exported by the entry point index.d.ts
     constructor(options: Options_8);
     authenticationType(): string;
+    getRefreshToken(): string;
     setCrTokenFilename(crTokenFilename: string): void;
     setIamProfileId(iamProfileId: string): void;
     setIamProfileName(iamProfileName: string): void;
@@ -142,6 +145,7 @@ export class ContainerTokenManager extends IamRequestBasedTokenManager {
     // Warning: (ae-forgotten-export) The symbol "Options_7" needs to be exported by the entry point index.d.ts
     constructor(options: Options_7);
     protected getCrToken(): string;
+    getRefreshToken(): string;
     protected requestToken(): Promise<any>;
     setCrTokenFilename(crTokenFilename: string): void;
     setIamProfileId(iamProfileId: string): void;
@@ -224,11 +228,37 @@ export function getNewLogger(moduleName: string): SDKLogger;
 // @public
 export function getQueryParam(urlStr: string, param: string): string;
 
+// Warning: (ae-forgotten-export) The symbol "IamRequestBasedAuthenticatorImmutable" needs to be exported by the entry point index.d.ts
+//
+// @public
+export class IamAssumeAuthenticator extends IamRequestBasedAuthenticatorImmutable {
+    // Warning: (ae-forgotten-export) The symbol "Options_14" needs to be exported by the entry point index.d.ts
+    constructor(options: Options_14);
+    authenticationType(): string;
+    // (undocumented)
+    protected tokenManager: IamAssumeTokenManager;
+}
+
+// @public
+export class IamAssumeTokenManager extends IamRequestBasedTokenManager {
+    // Warning: (ae-forgotten-export) The symbol "Options_13" needs to be exported by the entry point index.d.ts
+    constructor(options: Options_13);
+    protected requestToken(): Promise<any>;
+    // (undocumented)
+    protected requiredOptions: string[];
+    protected saveTokenInfo(tokenResponse: any): void;
+    setClientIdAndSecret(clientId: string, clientSecret: string): void;
+    setDisableSslVerification(value: boolean): void;
+    setHeaders(headers: OutgoingHttpHeaders): void;
+    setScope(scope: string): void;
+}
+
 // @public
 export class IamAuthenticator extends IamRequestBasedAuthenticator {
     // Warning: (ae-forgotten-export) The symbol "Options_6" needs to be exported by the entry point index.d.ts
     constructor(options: Options_6);
     authenticationType(): string;
+    getRefreshToken(): string;
     // (undocumented)
     protected requiredOptions: string[];
     // (undocumented)
@@ -236,33 +266,29 @@ export class IamAuthenticator extends IamRequestBasedAuthenticator {
 }
 
 // @public
-export class IamRequestBasedAuthenticator extends TokenRequestBasedAuthenticator {
-    // Warning: (ae-forgotten-export) The symbol "IamRequestOptions_2" needs to be exported by the entry point index.d.ts
-    constructor(options: IamRequestOptions_2);
-    // (undocumented)
-    protected clientId: string;
-    // (undocumented)
-    protected clientSecret: string;
-    getRefreshToken(): string;
-    // (undocumented)
-    protected scope: string;
+export class IamRequestBasedAuthenticator extends IamRequestBasedAuthenticatorImmutable {
     setClientIdAndSecret(clientId: string, clientSecret: string): void;
+    setDisableSslVerification(value: boolean): void;
+    setHeaders(headers: OutgoingHttpHeaders): void;
     setScope(scope: string): void;
-    // (undocumented)
-    protected tokenManager: IamRequestBasedTokenManager;
 }
 
 // @public
 export class IamRequestBasedTokenManager extends JwtTokenManager {
     constructor(options: IamRequestOptions);
     // (undocumented)
+    protected clientId: string;
+    // (undocumented)
+    protected clientSecret: string;
+    // (undocumented)
     protected formData: any;
-    getRefreshToken(): string;
     protected isTokenExpired(): boolean;
     // (undocumented)
     protected refreshToken: string;
     protected requestToken(): Promise<any>;
     protected saveTokenInfo(tokenResponse: any): void;
+    // (undocumented)
+    protected scope: string;
     setClientIdAndSecret(clientId: string, clientSecret: string): void;
     setScope(scope: string): void;
 }
@@ -281,6 +307,7 @@ export interface IamRequestOptions extends JwtTokenManagerOptions {
 export class IamTokenManager extends IamRequestBasedTokenManager {
     // Warning: (ae-forgotten-export) The symbol "Options_5" needs to be exported by the entry point index.d.ts
     constructor(options: Options_5);
+    getRefreshToken(): string;
     // (undocumented)
     protected requiredOptions: string[];
 }
@@ -343,7 +370,7 @@ export class NoAuthAuthenticator extends Authenticator {
 }
 
 // @public
-export function onlyOne(a: any, b: any): boolean;
+export function onlyOne(...args: any): boolean;
 
 // @public
 export const qs: {
@@ -420,21 +447,12 @@ export type TokenManagerOptions = {
     [propName: string]: any;
 };
 
+// Warning: (ae-forgotten-export) The symbol "TokenRequestBasedAuthenticatorImmutable" needs to be exported by the entry point index.d.ts
+//
 // @public
-export class TokenRequestBasedAuthenticator extends Authenticator {
-    // Warning: (ae-forgotten-export) The symbol "BaseOptions" needs to be exported by the entry point index.d.ts
-    constructor(options: BaseOptions);
-    authenticate(requestOptions: AuthenticateOptions): Promise<void>;
-    // (undocumented)
-    protected disableSslVerification: boolean;
-    // (undocumented)
-    protected headers: OutgoingHttpHeaders;
+export class TokenRequestBasedAuthenticator extends TokenRequestBasedAuthenticatorImmutable {
     setDisableSslVerification(value: boolean): void;
     setHeaders(headers: OutgoingHttpHeaders): void;
-    // (undocumented)
-    protected tokenManager: JwtTokenManager;
-    // (undocumented)
-    protected url: string;
 }
 
 // @public