[rush] Add cacheHashSalt property

microsoft · Oct 4, 2024 · f5c875f · f5c875f
1 parent 4edbbb8
commit f5c875f
Show file tree

Hide file tree

Showing 6 changed files with 37 additions and 0 deletions.
diff --git a/common/changes/@microsoft/rush/split-project-change-analyzer_2024-10-04-21-03.json b/common/changes/@microsoft/rush/split-project-change-analyzer_2024-10-04-21-03.json
@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/rush",
+      "comment": "Add an optional property `cacheHashSalt` to `build-cache.json` to allow repository maintainers to globally force a hash change in build cache entries.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@microsoft/rush"
+}
diff --git a/common/reviews/api/rush-lib.api.md b/common/reviews/api/rush-lib.api.md
@@ -66,6 +66,7 @@ export class ApprovedPackagesPolicy {
 // @beta
 export class BuildCacheConfiguration {
     readonly buildCacheEnabled: boolean;
+    readonly cacheHashSalt: string | undefined;
     cacheWriteEnabled: boolean;
     readonly cloudCacheProvider: ICloudBuildCacheProvider | undefined;
     static getBuildCacheConfigFilePath(rushConfiguration: RushConfiguration): string;

diff --git a/libraries/rush-lib/assets/rush-init/common/config/rush/build-cache.json b/libraries/rush-lib/assets/rush-init/common/config/rush/build-cache.json
@@ -34,6 +34,11 @@
    */
   // "cacheEntryNamePattern": "[projectName:normalize]-[phaseName:normalize]-[hash]"
 
+  /**
+   * (Optional) Salt to inject during calculation of the cache key. This can be used to invalidate the cache for all projects when the salt changes.
+   */
+  // "cacheHashSalt": "1",
+
   /**
    * Use this configuration with "cacheProvider"="azure-blob-storage"
    */

diff --git a/libraries/rush-lib/src/api/BuildCacheConfiguration.ts b/libraries/rush-lib/src/api/BuildCacheConfiguration.ts
@@ -42,6 +42,10 @@ export interface IBaseBuildCacheJson {
    * The token parser is in CacheEntryId.ts
    */
   cacheEntryNamePattern?: string;
+  /**
+   * An optional salt to inject during calculation of the cache key. This can be used to invalidate the cache for all projects when the salt changes.
+   */
+  cacheHashSalt?: string;
 }
 
 /**
@@ -102,6 +106,10 @@ export class BuildCacheConfiguration {
    * The provider for interacting with the cloud build cache, if configured.
    */
   public readonly cloudCacheProvider: ICloudBuildCacheProvider | undefined;
+  /**
+   * An optional salt to inject during calculation of the cache key. This can be used to invalidate the cache for all projects when the salt changes.
+   */
+  public readonly cacheHashSalt: string | undefined;
 
   private constructor({
     getCacheEntryId,
@@ -120,6 +128,7 @@ export class BuildCacheConfiguration {
       rushConfiguration: rushConfiguration
     });
     this.cloudCacheProvider = cloudCacheProvider;
+    this.cacheHashSalt = buildCacheJson.cacheHashSalt;
   }
 
   /**

diff --git a/libraries/rush-lib/src/logic/operations/CacheableOperationPlugin.ts b/libraries/rush-lib/src/logic/operations/CacheableOperationPlugin.ts
@@ -88,6 +88,8 @@ export class CacheableOperationPlugin implements IPhasedCommandPlugin {
   public apply(hooks: PhasedCommandHooks): void {
     const { allowWarningsInSuccessfulBuild, buildCacheConfiguration, cobuildConfiguration } = this._options;
 
+    const { cacheHashSalt } = buildCacheConfiguration;
+
     hooks.beforeExecuteOperations.tap(
       PLUGIN_NAME,
       (
@@ -143,6 +145,12 @@ export class CacheableOperationPlugin implements IPhasedCommandPlugin {
           // of the build cache.
           hasher.update(`${RushConstants.buildCacheVersion}`);
 
+          if (cacheHashSalt !== undefined) {
+            // This allows repository owners to force a cache bust by changing the salt.
+            // A common use case is to invalidate the cache when adding/removing/updating rush plugins that alter the build output.
+            hasher.update(cacheHashSalt);
+          }
+
           for (const dependencyHash of dependencyHashes) {
             hasher.update(dependencyHash);
           }

diff --git a/libraries/rush-lib/src/schemas/build-cache.schema.json b/libraries/rush-lib/src/schemas/build-cache.schema.json
@@ -33,6 +33,10 @@
           "type": "string",
           "description": "Setting this property overrides the cache entry ID. If this property is set, it must contain a [hash] token. It may also contain one of the following tokens: [projectName], [projectName:normalize], [phaseName], [phaseName:normalize], [phaseName:trimPrefix], [os], and [arch]."
         },
+        "cacheHashSalt": {
+          "type": "string",
+          "description": "An optional salt to inject during calculation of the cache key. This can be used to invalidate the cache for all projects when the salt changes."
+        },
         "azureBlobStorageConfiguration": {
           "type": "object",
           "additionalProperties": false,