Configuration Options

/**
 * Options to control cache upload
 */
interface UploadOptions {
  /**
   * Indicates whether to use the Azure Blob SDK to upload caches
   * that are stored on Azure Blob Storage to improve reliability and
   * performance
   * @default false
   */
  useAzureSdk?: boolean;
  
  /**
   * Number of parallel cache uploads
   * @default 4
   */
  uploadConcurrency?: number;
  
  /**
   * Maximum chunk size in bytes for cache upload
   * @default 33554432 (32MB)
   */
  uploadChunkSize?: number;
  
  /**
   * Archive size in bytes (set automatically by the library)
   */
  archiveSizeBytes?: number;
}

import { saveCache, UploadOptions } from '@actions/cache';

// Default upload options
const defaultOptions: UploadOptions = {
  useAzureSdk: false,
  uploadConcurrency: 4,
  uploadChunkSize: 32 * 1024 * 1024 // 32MB
};

// High-performance upload configuration
const performanceOptions: UploadOptions = {
  useAzureSdk: true,
  uploadConcurrency: 8,
  uploadChunkSize: 64 * 1024 * 1024 // 64MB chunks
};

const cacheId = await saveCache(paths, key, performanceOptions);

// Environment variable overrides
// CACHE_UPLOAD_CONCURRENCY - overrides uploadConcurrency (max 32)
// CACHE_UPLOAD_CHUNK_SIZE - overrides uploadChunkSize in MB (max 128MB)

/**
 * Options to control cache download
 */
interface DownloadOptions {
  /**
   * Indicates whether to use the Azure Blob SDK to download caches
   * that are stored on Azure Blob Storage to improve reliability and
   * performance
   * @default false
   */
  useAzureSdk?: boolean;
  
  /**
   * Number of parallel downloads (this option only applies when using
   * the Azure SDK)
   * @default 8
   */
  downloadConcurrency?: number;
  
  /**
   * Indicates whether to use Actions HttpClient with concurrency
   * for Azure Blob Storage
   */
  concurrentBlobDownloads?: boolean;
  
  /**
   * Maximum time for each download request, in milliseconds (this
   * option only applies when using the Azure SDK)
   * @default 30000
   */
  timeoutInMs?: number;
  
  /**
   * Time after which a segment download should be aborted if stuck
   * @default 600000 (10 minutes)
   */
  segmentTimeoutInMs?: number;
  
  /**
   * Whether to skip downloading the cache entry.
   * If lookupOnly is set to true, the restore function will only check if
   * a matching cache entry exists and return the cache key if it does.
   * @default false
   */
  lookupOnly?: boolean;
}

import { restoreCache, DownloadOptions } from '@actions/cache';

// Default download options
const defaultOptions: DownloadOptions = {
  useAzureSdk: false,
  concurrentBlobDownloads: true,
  downloadConcurrency: 8,
  timeoutInMs: 30000,
  segmentTimeoutInMs: 600000, // 10 minutes
  lookupOnly: false
};

// High-performance download configuration
const performanceOptions: DownloadOptions = {
  useAzureSdk: true,
  downloadConcurrency: 16,
  concurrentBlobDownloads: true,
  timeoutInMs: 60000, // 1 minute timeout
  segmentTimeoutInMs: 1800000 // 30 minutes for large files
};

const cacheKey = await restoreCache(paths, primaryKey, restoreKeys, performanceOptions);

// Lookup-only mode (check existence without downloading)
const lookupOptions: DownloadOptions = {
  lookupOnly: true
};

const existingKey = await restoreCache(paths, primaryKey, restoreKeys, lookupOptions);
if (existingKey) {
  console.log(`Cache exists: ${existingKey}`);
  // Decide whether to download later
}

/**
 * Returns a copy of the upload options with defaults filled in
 * @param copy - The original upload options
 * @returns Upload options with defaults applied
 */
function getUploadOptions(copy?: UploadOptions): UploadOptions;

/**
 * Returns a copy of the download options with defaults filled in
 * @param copy - The original download options
 * @returns Download options with defaults applied
 */
function getDownloadOptions(copy?: DownloadOptions): DownloadOptions;

import { getUploadOptions, getDownloadOptions } from '@actions/cache';

// Get upload options with defaults
const uploadOpts = getUploadOptions({
  uploadConcurrency: 6
});
// Result: { useAzureSdk: false, uploadConcurrency: 6, uploadChunkSize: 33554432 }

// Get download options with defaults
const downloadOpts = getDownloadOptions({
  useAzureSdk: true
});
// Result includes all defaults with useAzureSdk overridden to true

// Get completely default options
const defaultUpload = getUploadOptions();
const defaultDownload = getDownloadOptions();

# Set environment variables
export CACHE_UPLOAD_CONCURRENCY=16
export CACHE_UPLOAD_CHUNK_SIZE=64
export SEGMENT_DOWNLOAD_TIMEOUT_MINS=30

# These will override the defaults even when not explicitly set in options

const fastUploadOptions: UploadOptions = {
  useAzureSdk: true,           // Use Azure SDK for better performance
  uploadConcurrency: 8,        // Increase parallel uploads
  uploadChunkSize: 64 * 1024 * 1024  // Larger chunks (64MB)
};

const fastDownloadOptions: DownloadOptions = {
  useAzureSdk: true,           // Use Azure SDK for better performance
  downloadConcurrency: 16,     // Increase parallel downloads
  concurrentBlobDownloads: true,
  timeoutInMs: 60000,          // Longer timeout for large files
  segmentTimeoutInMs: 1800000  // 30 minutes for very large caches
};