feat: extract amazon & azure cloud build cache plugins

apps/rush-lib/package.json

@@ -18,8 +18,6 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@azure/identity": "~1.0.0",
-    "@azure/storage-blob": "~12.3.0",
     "@pnpm/link-bins": "~5.3.7",
     "@rushstack/heft-config-file": "workspace:*",
     "@rushstack/node-core-library": "workspace:*",

apps/rush-lib/src/api/BuildCacheConfiguration.ts

@@ -28,15 +28,25 @@ interface IBaseBuildCacheJson {
   cacheProvider: string;
   cacheEntryNamePattern?: string;
 }
-interface ILocalBuildCacheJson extends IBaseBuildCacheJson {
+
+/**
+ * @public
+ */
+export interface ILocalBuildCacheJson extends IBaseBuildCacheJson {
   readonly cacheProvider: 'local-only';
 }
 
-interface ICloudBuildCacheJson extends IBaseBuildCacheJson {
+/**
+ * @public
+ */
+export interface ICloudBuildCacheJson extends IBaseBuildCacheJson {
   readonly cacheProvider: string;
   [otherConfigKey: string]: JsonObject;
 }
 
+/**
+ * @public
+ */
 export type IBuildCacheJson = ICloudBuildCacheJson | ILocalBuildCacheJson;
 
 interface IBuildCacheConfigurationOptions {

apps/rush-lib/src/api/EnvironmentConfiguration.ts

@@ -154,6 +154,7 @@ export const enum EnvironmentVariableNames {
 /**
  * Provides Rush-specific environment variable data. All Rush environment variables must start with "RUSH_". This class
  * is designed to be used by RushConfiguration.
+ * @public
  *
  * @remarks
  * Initialize will throw if any unknown parameters are present.
@@ -474,7 +475,7 @@ export class EnvironmentConfiguration {
    * this function returns undefined.
    *
    * @example
-   * If the following path exists on disk: C:\Folder1\folder2\
+   * If the following path exists on disk: `C:\Folder1\folder2\`
    * _normalizeFirstExistingFolderPath('c:\\folder1\\folder2\\temp\\subfolder')
    * returns 'C:\\Folder1\\folder2\\temp\\subfolder'
    */

apps/rush-lib/src/index.ts

@@ -26,7 +26,7 @@ export {
 
 export { PackageManagerName, PackageManager } from './api/packageManager/PackageManager';
 
-export { EnvironmentVariableNames } from './api/EnvironmentConfiguration';
+export { EnvironmentVariableNames, EnvironmentConfiguration } from './api/EnvironmentConfiguration';
 
 export { RushConfigurationProject } from './api/RushConfigurationProject';
 
@@ -70,6 +70,20 @@ export { Logger, ILogger, ILoggerOptions } from './pluginFramework/logging/Logge
 
 export { RushLifecycleHooks, IRushLifecycle } from './pluginFramework/RushLifeCycle';
 
-export { IBuildCacheJson } from './api/BuildCacheConfiguration';
+export { IBuildCacheJson, ILocalBuildCacheJson, ICloudBuildCacheJson } from './api/BuildCacheConfiguration';
 
 export { CloudBuildCacheProviderBase } from './logic/buildCache/CloudBuildCacheProviderBase';
+
+export { RushConstants } from './logic/RushConstants';
+
+export { CredentialCache, ICredentialCacheOptions, ICredentialCacheEntry } from './logic/CredentialCache';
+
+export { RushUserConfiguration } from './api/RushUserConfiguration';
+
+export {
+  WebClient,
+  IPutFetchOptions,
+  IGetFetchOptions,
+  WebClientResponse,
+  WebClientProxy
+} from './utilities/WebClient';

apps/rush-lib/src/logic/CredentialCache.ts

@@ -22,11 +22,17 @@ interface ICacheEntryJson {
   credential: string;
 }
 
+/**
+ * @beta
+ */
 export interface ICredentialCacheEntry {
   expires?: Date;
   credential: string;
 }
 
+/**
+ * @beta
+ */
 export interface ICredentialCacheOptions {
   supportEditing: boolean;
 }

apps/rush-lib/src/logic/RushConstants.ts

@@ -3,6 +3,7 @@
 
 /**
  * Constants used by the Rush tool.
+ * @public
  *
  * @remarks
  *
@@ -40,7 +41,7 @@ export class RushConstants {
   public static readonly commonFolderName: string = 'common';
 
   /**
-   * The NPM scope ("@rush-temp") that is used for Rush's temporary projects.
+   * The NPM scope ("\@rush-temp") that is used for Rush's temporary projects.
    */
   public static readonly rushTempNpmScope: string = '@rush-temp';
 
@@ -60,7 +61,7 @@ export class RushConstants {
   /**
    * The folder name ("variants") under which named variant configurations for
    * alternate dependency sets may be found.
-   * Example: "C:\MyRepo\common\config\rush\variants"
+   * Example: `C:\MyRepo\common\config\rush\variants`
    */
   public static readonly rushVariantsFolderName: string = 'variants';
 
@@ -164,7 +165,7 @@ export class RushConstants {
   public static readonly rushWebSiteUrl: string = 'https://rushjs.io';
 
   /**
-   * The name of the NPM package for the Rush tool ("@microsoft/rush").
+   * The name of the NPM package for the Rush tool ("\@microsoft/rush").
    */
   public static readonly rushPackageName: string = '@microsoft/rush';
 

apps/rush-lib/src/logic/buildCache/CloudBuildCacheProviderBase.ts

@@ -3,6 +3,9 @@
 
 import { Terminal } from '@rushstack/node-core-library';
 
+/**
+ * @beta
+ */
 export abstract class CloudBuildCacheProviderBase {
   public abstract readonly isCacheWriteAllowed: boolean;
 

apps/rush-lib/src/pluginFramework/PluginManager.ts

@@ -2,10 +2,9 @@
 // See LICENSE in the project root for license information.
 
 import { InternalError, Terminal } from '@rushstack/node-core-library';
+
 import { IRushPluginConfigJson, RushConfiguration } from '../api/RushConfiguration';
 import { Autoinstaller } from '../logic/Autoinstaller';
-import AmazonS3BuildCachePlugin from '../plugins/AmazonS3BuildCachePlugin';
-import AzureStorageBuildCachePlugin from '../plugins/AzureStorageBuildCachePlugin';
 import { IRushPlugin } from './IRushPlugin';
 import { RushSession } from './RushSession';
 
@@ -31,8 +30,6 @@ export class PluginManager {
   private _terminal: Terminal;
   private _rushConfiguration: RushConfiguration;
   private _rushSession: RushSession;
-  private _appliedPlugins: IRushPlugin[] = [];
-  private _appliedPluginNames: Set<string> = new Set<string>();
 
   public constructor(options: IPluginManagerOptions) {
     this._terminal = options.terminal;
@@ -44,10 +41,7 @@ export class PluginManager {
     return this._rushConfiguration.rushConfigurationJson.rushPlugins || [];
   }
 
-  public initializeDefaultPlugins(): void {
-    this._applyPlugin(new AzureStorageBuildCachePlugin());
-    this._applyPlugin(new AmazonS3BuildCachePlugin());
-  }
+  public initializeDefaultPlugins(): void {}
 
   public async initializePluginsFromConfigFileAsync(): Promise<void> {
     const rushPluginConfigurations: IRushPluginConfigJson[] = this.rushPluginConfigurations;
@@ -88,22 +82,16 @@ export class PluginManager {
       options
     );
 
-    if (this._appliedPluginNames.has(plugin.pluginName)) {
-      throw new Error(
-        `Error applying plugin "${resolvedPluginPath}": A plugin with name "${plugin.pluginName}" has ` +
-          'already been applied'
-      );
-    } else {
-      this._applyPlugin(plugin, options);
-    }
+    this._applyPlugin(plugin, options);
   }
 
   private _loadAndValidatePluginPackage(resolvedPluginPath: string, options?: object): IRushPlugin {
-    let pluginPackage: IRushPlugin;
+    type IRushPluginCtor = new () => IRushPlugin<object | void>;
+    let pluginPackage: IRushPluginCtor;
     try {
       // eslint-disable-next-line @typescript-eslint/no-var-requires
-      const loadedPluginPackage: IRushPlugin | { default: IRushPlugin } = require(resolvedPluginPath);
-      pluginPackage = (loadedPluginPackage as { default: IRushPlugin }).default || loadedPluginPackage;
+      const loadedPluginPackage: IRushPluginCtor | { default: IRushPluginCtor } = require(resolvedPluginPath);
+      pluginPackage = (loadedPluginPackage as { default: IRushPluginCtor }).default || loadedPluginPackage;
     } catch (e) {
       throw new InternalError(`Error loading plugin package from "${resolvedPluginPath}": ${e}`);
     }
@@ -114,38 +102,38 @@ export class PluginManager {
 
     this._terminal.writeVerboseLine(`Loaded plugin package from "${resolvedPluginPath}"`);
 
-    if (!pluginPackage.apply || typeof pluginPackage.apply !== 'function') {
+    const plugin: IRushPlugin<object | void> = new pluginPackage();
+
+    if (!plugin.apply || typeof pluginPackage.apply !== 'function') {
       throw new InternalError(
         `Plugin packages must define an "apply" function. The plugin loaded from "${resolvedPluginPath}" ` +
           'either doesn\'t define an "apply" property, or its value isn\'t a function.'
       );
     }
 
-    if (!pluginPackage.pluginName || typeof pluginPackage.pluginName !== 'string') {
+    if (!plugin.pluginName || typeof plugin.pluginName !== 'string') {
       throw new InternalError(
         `Plugin packages must define a "pluginName" property. The plugin loaded from "${resolvedPluginPath}" ` +
           'either doesn\'t define a "pluginName" property, or its value isn\'t a string.'
       );
     }
 
-    if (options && pluginPackage.optionsSchema) {
+    if (options && plugin.optionsSchema) {
       try {
-        pluginPackage.optionsSchema.validateObject(options, 'rush.json');
+        plugin.optionsSchema.validateObject(options, 'rush.json');
       } catch (e) {
         throw new Error(
-          `Provided options for plugin "${pluginPackage.pluginName}" did not match the provided plugin schema.\n${e}`
+          `Provided options for plugin "${plugin.pluginName}" did not match the provided plugin schema.\n${e}`
         );
       }
     }
 
-    return pluginPackage;
+    return plugin;
   }
 
   private _applyPlugin(plugin: IRushPlugin<object | void>, options?: object): void {
     try {
       plugin.apply(this._rushSession, this._rushConfiguration, options);
-      this._appliedPlugins.push(plugin);
-      this._appliedPluginNames.add(plugin.pluginName);
     } catch (e) {
       throw new InternalError(`Error applying "${plugin.pluginName}": ${e}`);
     }

apps/rush-lib/src/utilities/WebClient.ts

@@ -6,6 +6,9 @@ import { Import } from '@rushstack/node-core-library';
 
 const createHttpsProxyAgent: typeof import('https-proxy-agent') = Import.lazy('https-proxy-agent', require);
 
+/**
+ * @public
+ */
 export type WebClientResponse = fetch.Response;
 
 export interface IWebFetchOptionsBase {
@@ -14,21 +17,33 @@ export interface IWebFetchOptionsBase {
   headers?: fetch.Headers;
 }
 
+/**
+ * @public
+ */
 export interface IGetFetchOptions extends IWebFetchOptionsBase {
   verb: 'GET' | never;
 }
 
+/**
+ * @public
+ */
 export interface IPutFetchOptions extends IWebFetchOptionsBase {
   verb: 'PUT';
   body?: Buffer;
 }
 
+/**
+ * @public
+ */
 export enum WebClientProxy {
   None,
   Detect,
   Fiddler
 }
 
+/**
+ * @public
+ */
 export class WebClient {
   public readonly standardHeaders: fetch.Headers = new fetch.Headers();
 

common/config/rush/browser-approved-packages.json

@@ -2,6 +2,18 @@
 {
   "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/approved-packages.schema.json",
   "packages": [
+    {
+      "name": "@rushstack/rush-amazon-s3-build-cache-plugin",
+      "allowedCategories": [ "libraries" ]
+    },
+    {
+      "name": "@rushstack/rush-azure-storage-build-cache-plugin",
+      "allowedCategories": [ "libraries" ]
+    },
+    {
+      "name": "@rushstack/rush-lib",
+      "allowedCategories": [ "libraries" ]
+    },
     {
       "name": "react",
       "allowedCategories": [ "tests" ]

common/reviews/api/rush-amazon-s3-build-cache-plugin.api.md

@@ -0,0 +1,22 @@
+## API Report File for "@rushstack/rush-amazon-s3-build-cache-plugin"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import { IRushPlugin } from '@microsoft/rush-lib';
+import { RushConfiguration } from '@microsoft/rush-lib';
+import { RushSession } from '@microsoft/rush-lib';
+
+// @public (undocumented)
+class RushAmazonS3BuildCachePlugin implements IRushPlugin {
+    // (undocumented)
+    apply(rushSession: RushSession, rushConfig: RushConfiguration): void;
+    // (undocumented)
+    pluginName: string;
+}
+export default RushAmazonS3BuildCachePlugin;
+
+// (No @packageDocumentation comment for this package)
+
+```

common/reviews/api/rush-azure-storage-build-cache-plugin.api.md

@@ -0,0 +1,22 @@
+## API Report File for "@rushstack/rush-azure-storage-build-cache-plugin"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import { IRushPlugin } from '@microsoft/rush-lib';
+import { RushConfiguration } from '@microsoft/rush-lib';
+import { RushSession } from '@microsoft/rush-lib';
+
+// @public (undocumented)
+class RushAzureStorageBuildCachePlugin implements IRushPlugin {
+    // (undocumented)
+    apply(rushSession: RushSession, rushConfig: RushConfiguration): void;
+    // (undocumented)
+    pluginName: string;
+}
+export default RushAzureStorageBuildCachePlugin;
+
+// (No @packageDocumentation comment for this package)
+
+```