microsoft
diff --git a/‎common/changes/@microsoft/rush/copilot-stream-cache-entry-for-http-plugin_2026-04-05-03-56.json‎
Lines changed: 11 additions & 0 deletions b/‎common/changes/@microsoft/rush/copilot-stream-cache-entry-for-http-plugin_2026-04-05-03-56.json‎
Lines changed: 11 additions & 0 deletions
diff --git a/‎common/reviews/api/rush-amazon-s3-build-cache-plugin.api.md‎
Lines changed: 2 additions & 0 deletions b/‎common/reviews/api/rush-amazon-s3-build-cache-plugin.api.md‎
Lines changed: 2 additions & 0 deletions
diff --git a/‎common/reviews/api/rush-lib.api.md‎
Lines changed: 5 additions & 1 deletion b/‎common/reviews/api/rush-lib.api.md‎
Lines changed: 5 additions & 1 deletion
diff --git a/‎libraries/rush-lib/src/api/ExperimentsConfiguration.ts‎
Lines changed: 9 additions & 0 deletions b/‎libraries/rush-lib/src/api/ExperimentsConfiguration.ts‎
Lines changed: 9 additions & 0 deletions
diff --git a/‎libraries/rush-lib/src/cli/RushCommandLineParser.ts‎
Lines changed: 1 addition & 2 deletions b/‎libraries/rush-lib/src/cli/RushCommandLineParser.ts‎
Lines changed: 1 addition & 2 deletions
diff --git a/‎libraries/rush-lib/src/cli/scriptActions/PhasedScriptAction.ts‎
Lines changed: 26 additions & 16 deletions b/‎libraries/rush-lib/src/cli/scriptActions/PhasedScriptAction.ts‎
Lines changed: 26 additions & 16 deletions
diff --git a/‎libraries/rush-lib/src/logic/PublishUtilities.ts‎
Lines changed: 5 additions & 1 deletion b/‎libraries/rush-lib/src/logic/PublishUtilities.ts‎
Lines changed: 5 additions & 1 deletion
diff --git a/‎libraries/rush-lib/src/logic/buildCache/FileSystemBuildCacheProvider.ts‎
Lines changed: 10 additions & 13 deletions b/‎libraries/rush-lib/src/logic/buildCache/FileSystemBuildCacheProvider.ts‎
Lines changed: 10 additions & 13 deletions
diff --git a/‎libraries/rush-lib/src/logic/buildCache/ICloudBuildCacheProvider.ts‎
Lines changed: 30 additions & 0 deletions b/‎libraries/rush-lib/src/logic/buildCache/ICloudBuildCacheProvider.ts‎
Lines changed: 30 additions & 0 deletions
@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "Add optional file-based transfer APIs (`tryDownloadCacheEntryToFileAsync`, `tryUploadCacheEntryFromFileAsync`) to `ICloudBuildCacheProvider`, allowing cache plugins to transfer cache entries directly to and from files on disk without buffering entire contents in memory. Implement in `@rushstack/rush-http-build-cache-plugin`, `@rushstack/rush-amazon-s3-build-cache-plugin`, and `@rushstack/rush-azure-storage-build-cache-plugin`. Gated behind the `useDirectFileTransfersForBuildCache` experiment.",
+      "type": "none",
+      "packageName": "@microsoft/rush"
+    }
+  ],
+  "packageName": "@microsoft/rush",
+  "email": "198982749+Copilot@users.noreply.github.com"
+}
@@ -15,6 +15,7 @@ import { WebClient } from '@rushstack/rush-sdk/lib/utilities/WebClient';
 // @public
 export class AmazonS3Client {
     constructor(credentials: IAmazonS3Credentials | undefined, options: IAmazonS3BuildCacheProviderOptionsAdvanced, webClient: WebClient, terminal: ITerminal);
+    downloadObjectToFileAsync(objectName: string, localFilePath: string): Promise<boolean>;
     // (undocumented)
     getObjectAsync(objectName: string): Promise<Buffer | undefined>;
     // (undocumented)
@@ -25,6 +26,7 @@ export class AmazonS3Client {
     static tryDeserializeCredentials(credentialString: string | undefined): IAmazonS3Credentials | undefined;
     // (undocumented)
     uploadObjectAsync(objectName: string, objectBuffer: Buffer): Promise<void>;
+    uploadObjectFromFileAsync(objectName: string, localFilePath: string): Promise<void>;
     // (undocumented)
     static UriEncode(input: string): string;
 }
 
@@ -313,7 +313,7 @@ export class ExperimentsConfiguration {
 // @beta
 export class FileSystemBuildCacheProvider {
     constructor(options: IFileSystemBuildCacheProviderOptions);
-    getCacheEntryPath(cacheId: string): string;
+    readonly getCacheEntryPath: (cacheId: string) => string;
     tryGetCacheEntryPathByIdAsync(terminal: ITerminal, cacheId: string): Promise<string | undefined>;
     trySetCacheEntryBufferAsync(terminal: ITerminal, cacheId: string, entryBuffer: Buffer): Promise<string>;
 }
@@ -354,10 +354,12 @@ export interface ICloudBuildCacheProvider {
     deleteCachedCredentialsAsync(terminal: ITerminal): Promise<void>;
     // (undocumented)
     readonly isCacheWriteAllowed: boolean;
+    tryDownloadCacheEntryToFileAsync?(terminal: ITerminal, cacheId: string, localFilePath: string): Promise<boolean>;
     // (undocumented)
     tryGetCacheEntryBufferByIdAsync(terminal: ITerminal, cacheId: string): Promise<Buffer | undefined>;
     // (undocumented)
     trySetCacheEntryBufferAsync(terminal: ITerminal, cacheId: string, entryBuffer: Buffer): Promise<boolean>;
+    tryUploadCacheEntryFromFileAsync?(terminal: ITerminal, cacheId: string, localFilePath: string): Promise<boolean>;
     // (undocumented)
     updateCachedCredentialAsync(terminal: ITerminal, credential: string): Promise<void>;
     // (undocumented)
@@ -487,6 +489,7 @@ export interface IExperimentsJson {
     printEventHooksOutputToConsole?: boolean;
     rushAlerts?: boolean;
     strictChangefileValidation?: boolean;
+    useDirectFileTransfersForBuildCache?: boolean;
     useIPCScriptsInWatchMode?: boolean;
     usePnpmFrozenLockfileForRushInstall?: boolean;
     usePnpmLockfileOnlyThenFrozenLockfileForRushUpdate?: boolean;
@@ -600,6 +603,7 @@ export interface _IOperationBuildCacheOptions {
     buildCacheConfiguration: BuildCacheConfiguration;
     excludeAppleDoubleFiles: boolean;
     terminal: ITerminal;
+    useDirectFileTransfersForBuildCache: boolean;
 }
 
 // @alpha
 
@@ -144,6 +144,15 @@ export interface IExperimentsJson {
    * policy's main project.
    */
   strictChangefileValidation?: boolean;
+
+  /**
+   * If true, the build cache will use file-based APIs to transfer cache entries to and from cloud
+   * storage. This avoids loading the entire cache entry into memory, which can prevent out-of-memory
+   * errors for large build outputs and allow cache entries to exceed the limit of a single Buffer.
+   * The cloud cache provider plugin must implement the optional file-based methods for this to take
+   * effect; otherwise it falls back to the buffer-based approach.
+   */
+  useDirectFileTransfersForBuildCache?: boolean;
 }
 
 const _EXPERIMENTS_JSON_SCHEMA: JsonSchema = JsonSchema.fromLoadedObject(schemaJson);
 
@@ -221,8 +221,7 @@ export class RushCommandLineParser extends CommandLineParser {
       }
     }
 
-    const quietModeValue: string | undefined =
-      process.env[EnvironmentVariableNames.RUSH_QUIET_MODE];
+    const quietModeValue: string | undefined = process.env[EnvironmentVariableNames.RUSH_QUIET_MODE];
     if (quietModeValue === '1' || quietModeValue === 'true') {
       return true;
     }
 
@@ -308,6 +308,11 @@ export class PhasedScriptAction extends BaseScriptAction<IPhasedCommandConfig> i
     // Initialize the stopwatch's start time at 0 (process startup).
     const stopwatch: Stopwatch = Stopwatch.start(0);
 
+    const {
+      defaultSubspace,
+      subspacesFeatureEnabled,
+      pnpmOptions: { useWorkspaces }
+    } = this.rushConfiguration;
     if (this._alwaysInstall || this._installParameter?.value) {
       await measureAsyncFn(`${PERF_PREFIX}:install`, async () => {
         const { doBasicInstallAsync } = await import(
@@ -331,7 +336,7 @@ export class PhasedScriptAction extends BaseScriptAction<IPhasedCommandConfig> i
           afterInstallAsync: (subspace: Subspace) =>
             this.rushSession.hooks.afterInstall.promise(this, subspace, variant),
           // Eventually we may want to allow a subspace to be selected here
-          subspace: this.rushConfiguration.defaultSubspace
+          subspace: defaultSubspace
         });
       });
     }
@@ -340,14 +345,12 @@ export class PhasedScriptAction extends BaseScriptAction<IPhasedCommandConfig> i
       await measureAsyncFn(`${PERF_PREFIX}:checkInstallFlag`, async () => {
         // TODO: Replace with last-install.flag when "rush link" and "rush unlink" are removed
         const lastLinkFlag: FlagFile = new FlagFile(
-          this.rushConfiguration.defaultSubspace.getSubspaceTempFolderPath(),
+          defaultSubspace.getSubspaceTempFolderPath(),
           RushConstants.lastLinkFlagFilename,
           {}
         );
         // Only check for a valid link flag when subspaces is not enabled
-        if (!(await lastLinkFlag.isValidAsync()) && !this.rushConfiguration.subspacesFeatureEnabled) {
-          const useWorkspaces: boolean =
-            this.rushConfiguration.pnpmOptions && this.rushConfiguration.pnpmOptions.useWorkspaces;
+        if (!(await lastLinkFlag.isValidAsync()) && !subspacesFeatureEnabled) {
           if (useWorkspaces) {
             throw new Error('Link flag invalid.\nDid you run "rush install" or "rush update"?');
           } else {
@@ -473,18 +476,27 @@ export class PhasedScriptAction extends BaseScriptAction<IPhasedCommandConfig> i
           ).IPCOperationRunnerPlugin().apply(this.hooks);
         }
 
+        const {
+          experimentsConfiguration: {
+            configuration: {
+              buildCacheWithAllowWarningsInSuccessfulBuild = false,
+              buildSkipWithAllowWarningsInSuccessfulBuild,
+              omitAppleDoubleFilesFromBuildCache: excludeAppleDoubleFiles = false,
+              useDirectFileTransfersForBuildCache = false,
+              usePnpmSyncForInjectedDependencies
+            }
+          },
+          isPnpm
+        } = this.rushConfiguration;
         if (buildCacheConfiguration?.buildCacheEnabled) {
           terminal.writeVerboseLine(`Incremental strategy: cache restoration`);
           new CacheableOperationPlugin({
-            allowWarningsInSuccessfulBuild:
-              !!this.rushConfiguration.experimentsConfiguration.configuration
-                .buildCacheWithAllowWarningsInSuccessfulBuild,
+            allowWarningsInSuccessfulBuild: buildCacheWithAllowWarningsInSuccessfulBuild,
             buildCacheConfiguration,
             cobuildConfiguration,
             terminal,
-            excludeAppleDoubleFiles:
-              !!this.rushConfiguration.experimentsConfiguration.configuration
-                .omitAppleDoubleFilesFromBuildCache
+            excludeAppleDoubleFiles,
+            useDirectFileTransfersForBuildCache
           }).apply(this.hooks);
 
           if (this._debugBuildCacheIdsParameter.value) {
@@ -494,9 +506,7 @@ export class PhasedScriptAction extends BaseScriptAction<IPhasedCommandConfig> i
           terminal.writeVerboseLine(`Incremental strategy: output preservation`);
           // Explicitly disabling the build cache also disables legacy skip detection.
           new LegacySkipPlugin({
-            allowWarningsInSuccessfulBuild:
-              this.rushConfiguration.experimentsConfiguration.configuration
-                .buildSkipWithAllowWarningsInSuccessfulBuild,
+            allowWarningsInSuccessfulBuild: buildSkipWithAllowWarningsInSuccessfulBuild,
             terminal,
             changedProjectsOnly,
             isIncrementalBuildAllowed: this._isIncrementalBuildAllowed
@@ -511,12 +521,12 @@ export class PhasedScriptAction extends BaseScriptAction<IPhasedCommandConfig> i
           if (!buildCacheConfiguration?.buildCacheEnabled) {
             throw new Error('You must have build cache enabled to use this option.');
           }
+
           const { BuildPlanPlugin } = await import('../../logic/operations/BuildPlanPlugin');
           new BuildPlanPlugin(terminal).apply(this.hooks);
         }
 
-        const { configuration: experiments } = this.rushConfiguration.experimentsConfiguration;
-        if (this.rushConfiguration?.isPnpm && experiments?.usePnpmSyncForInjectedDependencies) {
+        if (isPnpm && usePnpmSyncForInjectedDependencies) {
           const { PnpmSyncCopyOperationPlugin } = await import(
             '../../logic/operations/PnpmSyncCopyOperationPlugin'
           );
 
@@ -390,7 +390,11 @@ export class PublishUtilities {
           currentWorkingDirectory: path.dirname(filename)
         }
       );
-      const { stdout: fileLog, exitCode, signal } = await Executable.waitForExitAsync(gitProcess, {
+      const {
+        stdout: fileLog,
+        exitCode,
+        signal
+      } = await Executable.waitForExitAsync(gitProcess, {
         encoding: 'utf8'
       });
       if (exitCode !== 0 || signal) {
 
@@ -1,8 +1,6 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
-import * as path from 'node:path';
-
 import { FileSystem } from '@rushstack/node-core-library';
 import type { ITerminal } from '@rushstack/terminal';
 
@@ -32,19 +30,17 @@ const DEFAULT_BUILD_CACHE_FOLDER_NAME: string = 'build-cache';
  * @beta
  */
 export class FileSystemBuildCacheProvider {
-  private readonly _cacheFolderPath: string;
-
-  public constructor(options: IFileSystemBuildCacheProviderOptions) {
-    this._cacheFolderPath =
-      options.rushUserConfiguration.buildCacheFolder ||
-      path.join(options.rushConfiguration.commonTempFolder, DEFAULT_BUILD_CACHE_FOLDER_NAME);
-  }
-
   /**
    * Returns the absolute disk path for the specified cache id.
    */
-  public getCacheEntryPath(cacheId: string): string {
-    return path.join(this._cacheFolderPath, cacheId);
+  public readonly getCacheEntryPath: (cacheId: string) => string;
+
+  public constructor(options: IFileSystemBuildCacheProviderOptions) {
+    const {
+      rushConfiguration: { commonTempFolder },
+      rushUserConfiguration: { buildCacheFolder = `${commonTempFolder}/${DEFAULT_BUILD_CACHE_FOLDER_NAME}` }
+    } = options;
+    this.getCacheEntryPath = (cacheId: string) => `${buildCacheFolder}/${cacheId}`;
   }
 
   /**
@@ -55,7 +51,8 @@ export class FileSystemBuildCacheProvider {
     cacheId: string
   ): Promise<string | undefined> {
     const cacheEntryFilePath: string = this.getCacheEntryPath(cacheId);
-    if (await FileSystem.existsAsync(cacheEntryFilePath)) {
+    const cacheEntryExists: boolean = await FileSystem.existsAsync(cacheEntryFilePath);
+    if (cacheEntryExists) {
       return cacheEntryFilePath;
     } else {
       return undefined;
 
@@ -11,6 +11,36 @@ export interface ICloudBuildCacheProvider {
 
   tryGetCacheEntryBufferByIdAsync(terminal: ITerminal, cacheId: string): Promise<Buffer | undefined>;
   trySetCacheEntryBufferAsync(terminal: ITerminal, cacheId: string, entryBuffer: Buffer): Promise<boolean>;
+
+  /**
+   * If implemented, the build cache will prefer to use this method over
+   * {@link ICloudBuildCacheProvider.tryGetCacheEntryBufferByIdAsync} to avoid loading the entire
+   * cache entry into memory, if possible. The implementation should download the cache entry and write it
+   * to the specified local file path.
+   *
+   * @returns `true` if the cache entry was found and written to the file; otherwise `false`.
+   * Implementations typically log transfer failures and return `false`, but may still throw for
+   * unexpected errors.
+   */
+  tryDownloadCacheEntryToFileAsync?(
+    terminal: ITerminal,
+    cacheId: string,
+    localFilePath: string
+  ): Promise<boolean>;
+  /**
+   * If implemented, the build cache will prefer to use this method over
+   * {@link ICloudBuildCacheProvider.trySetCacheEntryBufferAsync} to avoid loading the entire
+   * cache entry into memory, if possible. The implementation should read the cache entry from
+   * the specified local file path and upload it.
+   *
+   * @returns `true` if the cache entry was written to the cache, otherwise `false`.
+   */
+  tryUploadCacheEntryFromFileAsync?(
+    terminal: ITerminal,
+    cacheId: string,
+    localFilePath: string
+  ): Promise<boolean>;
+
   updateCachedCredentialAsync(terminal: ITerminal, credential: string): Promise<void>;
   updateCachedCredentialInteractiveAsync(terminal: ITerminal): Promise<void>;
   deleteCachedCredentialsAsync(terminal: ITerminal): Promise<void>;
Original file line number	Diff line number	Diff line change
`@@ -221,8 +221,7 @@ export class RushCommandLineParser extends CommandLineParser {`
`221`	`221`	`}`
`222`	`222`	`}`
`223`	`223`
`224`		`- const quietModeValue: string \| undefined =`
`225`		`- process.env[EnvironmentVariableNames.RUSH_QUIET_MODE];`
	`224`	`+ const quietModeValue: string \| undefined = process.env[EnvironmentVariableNames.RUSH_QUIET_MODE];`
`226`	`225`	`if (quietModeValue === '1' \|\| quietModeValue === 'true') {`
`227`	`226`	`return true;`
`228`	`227`	`}`