feat: Unify Base AuthClient Options

samples/keepalive.js

@@ -30,21 +30,26 @@ const https = require('https');
  * Acquire a client, and make a request to an API that's enabled by default.
  */
 async function main() {
+  // create a new agent with keepAlive enabled
+  const agent = new https.Agent({keepAlive: true});
+
   const auth = new GoogleAuth({
     scopes: 'https://www.googleapis.com/auth/cloud-platform',
+    clientOptions: {
+      transporterOptions: {
+        agent,
+      },
+    },
   });
   const client = await auth.getClient();
   const projectId = await auth.getProjectId();
   const url = `https://dns.googleapis.com/dns/v1/projects/${projectId}`;
 
-  // create a new agent with keepAlive enabled
-  const agent = new https.Agent({keepAlive: true});
-
-  // use the agent as an Axios config param to make the request
-  const res = await client.request({url, agent});
+  // the agent uses the provided agent.
+  const res = await client.request({url});
   console.log(res.data);
 
-  // Re-use the same agent to make the next request over the same connection
+  // Can also use another agent per-request.
   const res2 = await client.request({url, agent});
   console.log(res2.data);
 }

src/auth/authclient.ts

@@ -13,31 +13,91 @@
 // limitations under the License.
 
 import {EventEmitter} from 'events';
-import {GaxiosOptions, GaxiosPromise, GaxiosResponse} from 'gaxios';
+import {Gaxios, GaxiosOptions, GaxiosPromise, GaxiosResponse} from 'gaxios';
 
 import {DefaultTransporter, Transporter} from '../transporters';
 import {Credentials} from './credentials';
 import {Headers} from './oauth2client';
+import {OriginalAndCamel, getOriginalOrCamel as getOpt} from '../util';
 
 /**
- * Defines the root interface for all clients that generate credentials
- * for calling Google APIs. All clients should implement this interface.
+ * Base auth configurations (e.g. from JWT or `.json` files)
  */
-export interface CredentialsClient {
+export interface AuthJSONOptions {
   /**
    * The project ID corresponding to the current credentials if available.
    */
-  projectId?: string | null;
+  project_id: string | null;
 
   /**
-   * The expiration threshold in milliseconds before forcing token refresh.
+   * The quota project ID. The quota project can be used by client libraries for the billing purpose.
+   * See {@link https://cloud.google.com/docs/quota Working with quotas}
    */
-  eagerRefreshThresholdMillis: number;
+  quota_project_id: string;
 
   /**
-   * Whether to force refresh on failure when making an authorization request.
+   * The default service domain for a given Cloud universe
    */
-  forceRefreshOnFailure: boolean;
+  universe_domain: string;
+}
+
+/**
+ * Base Auth Client configuration
+ */
+export type AuthClientOptions = Partial<
+  OriginalAndCamel<AuthJSONOptions> & {
+    credentials: Credentials;
+
+    /**
+     * A `Gaxios` or `Transporter` instance to use for `AuthClient` requests.
+     */
+    transporter: Gaxios | Transporter;
+
+    /**
+     * Provides default options to the transporter, such as {@link GaxiosOptions.agent `agent`} or
+     *  {@link GaxiosOptions.retryConfig `retryConfig`}.
+     */
+    transporterOptions: GaxiosOptions;
+
+    /**
+     * The expiration threshold in milliseconds before forcing token refresh of
+     * unexpired tokens.
+     */
+    eagerRefreshThresholdMillis: number;
+
+    /**
+     * Whether to attempt to refresh tokens on status 401/403 responses
+     * even if an attempt is made to refresh the token preemptively based
+     * on the expiry_date.
+     */
+    forceRefreshOnFailure: boolean;
+  }
+>;
+
+/**
+ * The default cloud universe
+ *
+ * @see {@link AuthJSONOptions.universe_domain}
+ */
+export const DEFAULT_UNIVERSE = 'googleapis.com';
+
+/**
+ * The default {@link AuthClientOptions.eagerRefreshThresholdMillis}
+ */
+export const DEFAULT_EAGER_REFRESH_THRESHOLD_MILLIS = 5 * 60 * 1000;
+
+/**
+ * Defines the root interface for all clients that generate credentials
+ * for calling Google APIs. All clients should implement this interface.
+ */
+export interface CredentialsClient {
+  projectId?: AuthClientOptions['projectId'];
+  eagerRefreshThresholdMillis: NonNullable<
+    AuthClientOptions['eagerRefreshThresholdMillis']
+  >;
+  forceRefreshOnFailure: NonNullable<
+    AuthClientOptions['forceRefreshOnFailure']
+  >;
 
   /**
    * @return A promise that resolves with the current GCP access token
@@ -88,16 +148,40 @@ export abstract class AuthClient
   extends EventEmitter
   implements CredentialsClient
 {
+  projectId?: string | null;
   /**
    * The quota project ID. The quota project can be used by client libraries for the billing purpose.
-   * See {@link https://cloud.google.com/docs/quota| Working with quotas}
+   * See {@link https://cloud.google.com/docs/quota Working with quotas}
    */
   quotaProjectId?: string;
-  transporter: Transporter = new DefaultTransporter();
+  transporter: Transporter;
   credentials: Credentials = {};
-  projectId?: string | null;
-  eagerRefreshThresholdMillis = 5 * 60 * 1000;
+  eagerRefreshThresholdMillis = DEFAULT_EAGER_REFRESH_THRESHOLD_MILLIS;
   forceRefreshOnFailure = false;
+  universeDomain = DEFAULT_UNIVERSE;
+
+  constructor(opts: AuthClientOptions = {}) {
+    super();
+
+    // Shared auth options
+    this.projectId = getOpt(opts, 'project_id') ?? null;
+    this.quotaProjectId = getOpt(opts, 'quota_project_id');
+    this.credentials = getOpt(opts, 'credentials') ?? {};
+    this.universeDomain = getOpt(opts, 'universe_domain') ?? DEFAULT_UNIVERSE;
+
+    // Shared client options
+    this.transporter = opts.transporter ?? new DefaultTransporter();
+
+    if (opts.transporterOptions) {
+      this.transporter.defaults = opts.transporterOptions;
+    }
+
+    if (opts.eagerRefreshThresholdMillis) {
+      this.eagerRefreshThresholdMillis = opts.eagerRefreshThresholdMillis;
+    }
+
+    this.forceRefreshOnFailure = opts.forceRefreshOnFailure ?? false;
+  }
 
   /**
    * Provides an alternative Gaxios request implementation with auth credentials

src/auth/awsclient.ts

@@ -19,7 +19,8 @@ import {
   BaseExternalAccountClient,
   BaseExternalAccountClientOptions,
 } from './baseexternalclient';
-import {RefreshOptions, Headers} from './oauth2client';
+import {Headers} from './oauth2client';
+import {AuthClientOptions} from './authclient';
 
 /**
  * AWS credentials JSON interface. This is used for AWS workloads.
@@ -85,7 +86,10 @@ export class AwsClient extends BaseExternalAccountClient {
    *   options. These currently customize expiration threshold time and
    *   whether to retry on 401/403 API request errors.
    */
-  constructor(options: AwsClientOptions, additionalOptions?: RefreshOptions) {
+  constructor(
+    options: AwsClientOptions,
+    additionalOptions?: AuthClientOptions
+  ) {
     super(options, additionalOptions);
     this.environmentId = options.credential_source.environment_id;
     // This is only required if the AWS region is not available in the

src/auth/baseexternalclient.ts

@@ -21,9 +21,9 @@ import {
 import * as stream from 'stream';
 
 import {Credentials} from './credentials';
-import {AuthClient} from './authclient';
+import {AuthClient, AuthClientOptions} from './authclient';
 import {BodyResponseCallback} from '../transporters';
-import {GetAccessTokenResponse, Headers, RefreshOptions} from './oauth2client';
+import {GetAccessTokenResponse, Headers} from './oauth2client';
 import * as sts from './stscredentials';
 import {ClientAuthentication} from './oauth2common';
 
@@ -63,18 +63,13 @@ const WORKFORCE_AUDIENCE_PATTERN =
 const pkg = require('../../../package.json');
 
 /**
- * The default cloud universe
+ * For backwards compatibility.
  */
-export const DEFAULT_UNIVERSE = 'googleapis.com';
+export {DEFAULT_UNIVERSE} from './authclient';
 
-export interface SharedExternalAccountClientOptions {
+export interface SharedExternalAccountClientOptions extends AuthClientOptions {
   audience: string;
   token_url: string;
-  quota_project_id?: string;
-  /**
-   * universe domain is the default service domain for a given Cloud universe
-   */
-  universe_domain?: string;
 }
 
 /**
@@ -151,11 +146,7 @@ export abstract class BaseExternalAccountClient extends AuthClient {
   private readonly stsCredential: sts.StsCredentials;
   private readonly clientAuth?: ClientAuthentication;
   private readonly workforcePoolUserProject?: string;
-  public universeDomain = DEFAULT_UNIVERSE;
-  public projectId: string | null;
   public projectNumber: string | null;
-  public readonly eagerRefreshThresholdMillis: number;
-  public readonly forceRefreshOnFailure: boolean;
   private readonly configLifetimeRequested: boolean;
   protected credentialSourceType?: string;
   /**
@@ -169,9 +160,10 @@ export abstract class BaseExternalAccountClient extends AuthClient {
    */
   constructor(
     options: BaseExternalAccountClientOptions,
-    additionalOptions?: RefreshOptions
+    additionalOptions?: AuthClientOptions
   ) {
-    super();
+    super({...options, ...additionalOptions});
+
     if (options.type !== EXTERNAL_ACCOUNT_TYPE) {
       throw new Error(
         `Expected "${EXTERNAL_ACCOUNT_TYPE}" type but ` +
@@ -194,7 +186,6 @@ export abstract class BaseExternalAccountClient extends AuthClient {
     this.cachedAccessToken = null;
     this.audience = options.audience;
     this.subjectTokenType = options.subject_token_type;
-    this.quotaProjectId = options.quota_project_id;
     this.workforcePoolUserProject = options.workforce_pool_user_project;
     const workforceAudiencePattern = new RegExp(WORKFORCE_AUDIENCE_PATTERN);
     if (
@@ -217,22 +208,8 @@ export abstract class BaseExternalAccountClient extends AuthClient {
       this.configLifetimeRequested = false;
       this.serviceAccountImpersonationLifetime = DEFAULT_TOKEN_LIFESPAN;
     }
-    // As threshold could be zero,
-    // eagerRefreshThresholdMillis || EXPIRATION_TIME_OFFSET will override the
-    // zero value.
-    if (typeof additionalOptions?.eagerRefreshThresholdMillis !== 'number') {
-      this.eagerRefreshThresholdMillis = EXPIRATION_TIME_OFFSET;
-    } else {
-      this.eagerRefreshThresholdMillis = additionalOptions!
-        .eagerRefreshThresholdMillis as number;
-    }
-    this.forceRefreshOnFailure = !!additionalOptions?.forceRefreshOnFailure;
-    this.projectId = null;
-    this.projectNumber = this.getProjectNumber(this.audience);
 
-    if (options.universe_domain) {
-      this.universeDomain = options.universe_domain;
-    }
+    this.projectNumber = this.getProjectNumber(this.audience);
   }
 
   /** The service account email to be impersonated, if available. */

src/auth/computeclient.ts

@@ -16,9 +16,13 @@ import {GaxiosError} from 'gaxios';
 import * as gcpMetadata from 'gcp-metadata';
 
 import {CredentialRequest, Credentials} from './credentials';
-import {GetTokenResponse, OAuth2Client, RefreshOptions} from './oauth2client';
+import {
+  GetTokenResponse,
+  OAuth2Client,
+  OAuth2ClientOptions,
+} from './oauth2client';
 
-export interface ComputeOptions extends RefreshOptions {
+export interface ComputeOptions extends OAuth2ClientOptions {
   /**
    * The service account email to use, or 'default'. A Compute Engine instance
    * may have multiple service accounts.

src/auth/downscopedclient.ts

@@ -22,9 +22,9 @@ import * as stream from 'stream';
 
 import {BodyResponseCallback} from '../transporters';
 import {Credentials} from './credentials';
-import {AuthClient} from './authclient';
+import {AuthClient, AuthClientOptions} from './authclient';
 
-import {GetAccessTokenResponse, Headers, RefreshOptions} from './oauth2client';
+import {GetAccessTokenResponse, Headers} from './oauth2client';
 import * as sts from './stscredentials';
 
 /**
@@ -107,8 +107,6 @@ interface AvailabilityCondition {
 export class DownscopedClient extends AuthClient {
   private cachedDownscopedAccessToken: CredentialsWithResponse | null;
   private readonly stsCredential: sts.StsCredentials;
-  public readonly eagerRefreshThresholdMillis: number;
-  public readonly forceRefreshOnFailure: boolean;
 
   /**
    * Instantiates a downscoped client object using the provided source
@@ -126,18 +124,17 @@ export class DownscopedClient extends AuthClient {
    *   permissions that are available on that resource and an optional
    *   condition to further restrict permissions.
    * @param additionalOptions Optional additional behavior customization
-   *   options. These currently customize expiration threshold time and
-   *   whether to retry on 401/403 API request errors.
+   *   options.
    * @param quotaProjectId Optional quota project id for setting up in the
    *   x-goog-user-project header.
    */
   constructor(
     private readonly authClient: AuthClient,
     private readonly credentialAccessBoundary: CredentialAccessBoundary,
-    additionalOptions?: RefreshOptions,
+    additionalOptions?: AuthClientOptions,
     quotaProjectId?: string
   ) {
-    super();
+    super({...additionalOptions, quotaProjectId});
     // Check 1-10 Access Boundary Rules are defined within Credential Access
     // Boundary.
     if (
@@ -167,17 +164,6 @@ export class DownscopedClient extends AuthClient {
 
     this.stsCredential = new sts.StsCredentials(STS_ACCESS_TOKEN_URL);
     this.cachedDownscopedAccessToken = null;
-    // As threshold could be zero,
-    // eagerRefreshThresholdMillis || EXPIRATION_TIME_OFFSET will override the
-    // zero value.
-    if (typeof additionalOptions?.eagerRefreshThresholdMillis !== 'number') {
-      this.eagerRefreshThresholdMillis = EXPIRATION_TIME_OFFSET;
-    } else {
-      this.eagerRefreshThresholdMillis = additionalOptions!
-        .eagerRefreshThresholdMillis as number;
-    }
-    this.forceRefreshOnFailure = !!additionalOptions?.forceRefreshOnFailure;
-    this.quotaProjectId = quotaProjectId;
   }
 
   /**