Clarify that the restore-keys input is a string in the docs (#1434)

* Fix Description for restore-keys at Readme

As previously the restore-keys were defined as an ordered lists which is
wrong as per the issue description where the actual format is a
multi-line string with one key per line.

* Added a space between the sentence of restore-keys description

While at the PR review it's been identified there's a need for a space
between the sentence

	```
	An ordered multiline string listing the prefix-matched keys,that are
	used for restoring stale cache if no cache hit occurred for key.
	```

where it's written as "prefix-matched keys,that are" this commit will
address the review comment and introduce a space between
"prefix-matched keys, that are" and change the sentence to

	```
	An ordered multiline string listing the prefix-matched keys, that are
        used for restoring stale cache if no cache hit occurred for key.
	```

* Change restore-keys description at cache/restore/action.yml and cache/action.yml

README.md

@@ -54,7 +54,7 @@ If you are using a `self-hosted` Windows runner, `GNU tar` and `zstd` are requir
 
 * `key` - An explicit key for a cache entry. See [creating a cache key](#creating-a-cache-key).
 * `path` - A list of files, directories, and wildcard patterns to cache and restore. See [`@actions/glob`](https://github.com/actions/toolkit/tree/main/packages/glob) for supported patterns.
-* `restore-keys` - An ordered list of prefix-matched keys to use for restoring stale cache if no cache hit occurred for key.
+* `restore-keys` - An ordered multiline string listing the prefix-matched keys, that are used for restoring stale cache if no cache hit occurred for key.
 * `enableCrossOsArchive` - An optional boolean when enabled, allows Windows runners to save or restore caches that can be restored or saved respectively on other platforms. Default: `false`
 * `fail-on-cache-miss` - Fail the workflow if cache entry is not found. Default: `false`
 * `lookup-only` - If true, only checks if cache entry exists and skips download. Does not change save cache behavior. Default: `false`
@@ -91,7 +91,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
 
     - name: Cache Primes
       id: cache-primes
@@ -122,7 +122,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
 
     - name: Restore cached Primes
       id: cache-primes-restore
@@ -229,7 +229,7 @@ Example:
 
 ```yaml
 steps:
-  - uses: actions/checkout@v3
+  - uses: actions/checkout@v4
 
   - uses: actions/cache@v4
     id: cache
@@ -259,7 +259,7 @@ jobs:
   build-linux:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Cache Primes
         id: cache-primes
@@ -286,7 +286,7 @@ jobs:
   build-windows:
     runs-on: windows-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Cache Primes
         id: cache-primes

RELEASES.md

@@ -1,5 +1,9 @@
 # Releases
 
+### 4.0.2
+
+- Fixed restore `fail-on-cache-miss` not working.
+
 ### 4.0.1
 
 - Updated `isGhes` check

__tests__/restore.test.ts

@@ -260,7 +260,7 @@ test("Fail restore when fail on cache miss is enabled and primary + restore keys
     );
 
     expect(stateMock).toHaveBeenCalledWith("CACHE_KEY", key);
-    expect(setCacheHitOutputMock).toHaveBeenCalledTimes(0);
+    expect(setCacheHitOutputMock).toHaveBeenCalledTimes(1);
 
     expect(failedMock).toHaveBeenCalledWith(
         `Failed to restore cache entry. Exiting as fail-on-cache-miss is set. Input key: ${key}`

__tests__/restoreImpl.test.ts

@@ -449,3 +449,19 @@ test("restore with lookup-only set", async () => {
     );
     expect(failedMock).toHaveBeenCalledTimes(0);
 });
+
+test("restore failure with earlyExit should call process exit", async () => {
+    testUtils.setInput(Inputs.Path, "node_modules");
+    const failedMock = jest.spyOn(core, "setFailed");
+    const restoreCacheMock = jest.spyOn(cache, "restoreCache");
+    const processExitMock = jest.spyOn(process, "exit").mockImplementation();
+
+    // call restoreImpl with `earlyExit` set to true
+    await restoreImpl(new StateProvider(), true);
+
+    expect(restoreCacheMock).toHaveBeenCalledTimes(0);
+    expect(failedMock).toHaveBeenCalledWith(
+        "Input required and not supplied: key"
+    );
+    expect(processExitMock).toHaveBeenCalledWith(1);
+});

__tests__/restoreOnly.test.ts

@@ -86,7 +86,8 @@ test("restore with no cache found", async () => {
     );
 
     expect(outputMock).toHaveBeenCalledWith("cache-primary-key", key);
-    expect(outputMock).toHaveBeenCalledTimes(1);
+    expect(outputMock).toHaveBeenCalledWith("cache-hit", "false");
+    expect(outputMock).toHaveBeenCalledTimes(2);
     expect(failedMock).toHaveBeenCalledTimes(0);
 
     expect(infoMock).toHaveBeenCalledWith(

action.yml

@@ -9,7 +9,7 @@ inputs:
     description: 'An explicit key for restoring and saving the cache'
     required: true
   restore-keys:
-    description: 'An ordered list of keys to use for restoring stale cache if no cache hit occurred for key. Note `cache-hit` returns false in this case.'
+    description: 'An ordered multiline string listing the prefix-matched keys, that are used for restoring stale cache if no cache hit occurred for key. Note `cache-hit` returns false in this case.'
     required: false
   upload-chunk-size:
     description: 'The chunk size used to split up large files during upload, in bytes'

dist/restore-only/index.js

@@ -59392,7 +59392,7 @@ const core = __importStar(__nccwpck_require__(2186));
 const constants_1 = __nccwpck_require__(9042);
 const stateProvider_1 = __nccwpck_require__(1527);
 const utils = __importStar(__nccwpck_require__(6850));
-function restoreImpl(stateProvider) {
+function restoreImpl(stateProvider, earlyExit) {
     return __awaiter(this, void 0, void 0, function* () {
         try {
             if (!utils.isCacheFeatureAvailable()) {
@@ -59415,6 +59415,7 @@ function restoreImpl(stateProvider) {
             const lookupOnly = utils.getInputAsBool(constants_1.Inputs.LookupOnly);
             const cacheKey = yield cache.restoreCache(cachePaths, primaryKey, restoreKeys, { lookupOnly: lookupOnly }, enableCrossOsArchive);
             if (!cacheKey) {
+                core.setOutput(constants_1.Outputs.CacheHit, false.toString());
                 if (failOnCacheMiss) {
                     throw new Error(`Failed to restore cache entry. Exiting as fail-on-cache-miss is set. Input key: ${primaryKey}`);
                 }
@@ -59438,21 +59439,16 @@ function restoreImpl(stateProvider) {
         }
         catch (error) {
             core.setFailed(error.message);
+            if (earlyExit) {
+                process.exit(1);
+            }
         }
     });
 }
 exports.restoreImpl = restoreImpl;
 function run(stateProvider, earlyExit) {
     return __awaiter(this, void 0, void 0, function* () {
-        try {
-            yield restoreImpl(stateProvider);
-        }
-        catch (err) {
-            console.error(err);
-            if (earlyExit) {
-                process.exit(1);
-            }
-        }
+        yield restoreImpl(stateProvider, earlyExit);
         // node will stay alive if any promises are not resolved,
         // which is a possibility if HTTP requests are dangling
         // due to retries or timeouts. We know that if we got here

dist/restore/index.js

@@ -59392,7 +59392,7 @@ const core = __importStar(__nccwpck_require__(2186));
 const constants_1 = __nccwpck_require__(9042);
 const stateProvider_1 = __nccwpck_require__(1527);
 const utils = __importStar(__nccwpck_require__(6850));
-function restoreImpl(stateProvider) {
+function restoreImpl(stateProvider, earlyExit) {
     return __awaiter(this, void 0, void 0, function* () {
         try {
             if (!utils.isCacheFeatureAvailable()) {
@@ -59415,6 +59415,7 @@ function restoreImpl(stateProvider) {
             const lookupOnly = utils.getInputAsBool(constants_1.Inputs.LookupOnly);
             const cacheKey = yield cache.restoreCache(cachePaths, primaryKey, restoreKeys, { lookupOnly: lookupOnly }, enableCrossOsArchive);
             if (!cacheKey) {
+                core.setOutput(constants_1.Outputs.CacheHit, false.toString());
                 if (failOnCacheMiss) {
                     throw new Error(`Failed to restore cache entry. Exiting as fail-on-cache-miss is set. Input key: ${primaryKey}`);
                 }
@@ -59438,21 +59439,16 @@ function restoreImpl(stateProvider) {
         }
         catch (error) {
             core.setFailed(error.message);
+            if (earlyExit) {
+                process.exit(1);
+            }
         }
     });
 }
 exports.restoreImpl = restoreImpl;
 function run(stateProvider, earlyExit) {
     return __awaiter(this, void 0, void 0, function* () {
-        try {
-            yield restoreImpl(stateProvider);
-        }
-        catch (err) {
-            console.error(err);
-            if (earlyExit) {
-                process.exit(1);
-            }
-        }
+        yield restoreImpl(stateProvider, earlyExit);
         // node will stay alive if any promises are not resolved,
         // which is a possibility if HTTP requests are dangling
         // due to retries or timeouts. We know that if we got here

examples.md

@@ -513,6 +513,7 @@ jobs:
 ```yaml
 - name: Get pip cache dir
   id: pip-cache
+  shell: bash
   run: |
     echo "dir=$(pip cache dir)" >> $GITHUB_OUTPUT
 

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "cache",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "lockfileVersion": 2,
   "requires": true,
   "packages": {
     "": {
       "name": "cache",
-      "version": "4.0.1",
+      "version": "4.0.2",
       "license": "MIT",
       "dependencies": {
         "@actions/cache": "^3.2.3",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "cache",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "private": true,
   "description": "Cache dependencies and build outputs",
   "main": "dist/restore/index.js",

restore/action.yml

@@ -9,7 +9,7 @@ inputs:
     description: 'An explicit key for restoring the cache'
     required: true
   restore-keys:
-    description: 'An ordered list of keys to use for restoring stale cache if no cache hit occurred for key. Note `cache-hit` returns false in this case.'
+    description: 'An ordered multiline string listing the prefix-matched keys, that are used for restoring stale cache if no cache hit occurred for key. Note `cache-hit` returns false in this case.'
     required: false
   enableCrossOsArchive:
     description: 'An optional boolean when enabled, allows windows runners to restore caches that were saved on other platforms'

src/restoreImpl.ts

@@ -10,7 +10,8 @@ import {
 import * as utils from "./utils/actionUtils";
 
 export async function restoreImpl(
-    stateProvider: IStateProvider
+    stateProvider: IStateProvider,
+    earlyExit?: boolean | undefined
 ): Promise<string | undefined> {
     try {
         if (!utils.isCacheFeatureAvailable()) {
@@ -50,6 +51,7 @@ export async function restoreImpl(
         );
 
         if (!cacheKey) {
+            core.setOutput(Outputs.CacheHit, false.toString());
             if (failOnCacheMiss) {
                 throw new Error(
                     `Failed to restore cache entry. Exiting as fail-on-cache-miss is set. Input key: ${primaryKey}`
@@ -61,7 +63,6 @@ export async function restoreImpl(
                     ...restoreKeys
                 ].join(", ")}`
             );
-
             return;
         }
 
@@ -83,6 +84,9 @@ export async function restoreImpl(
         return cacheKey;
     } catch (error: unknown) {
         core.setFailed((error as Error).message);
+        if (earlyExit) {
+            process.exit(1);
+        }
     }
 }
 
@@ -90,14 +94,7 @@ async function run(
     stateProvider: IStateProvider,
     earlyExit: boolean | undefined
 ): Promise<void> {
-    try {
-        await restoreImpl(stateProvider);
-    } catch (err) {
-        console.error(err);
-        if (earlyExit) {
-            process.exit(1);
-        }
-    }
+    await restoreImpl(stateProvider, earlyExit);
 
     // node will stay alive if any promises are not resolved,
     // which is a possibility if HTTP requests are dangling