Provide a richer API in actions/cache for sophisticated caching use cases

[bigdaz]

The gradle-build-action is effectively a setup-gradle action that takes care of caching and other setup for the Gradle build tool. This action is quite sophisticated in it's use of the @actions/cache library, extracting multiple cache entries out of the Gradle User Home and providing a detailed report of each entry saved/restored (including the entry size). See here for an example (expand the 'cache entry details' section).

To provide this functionality we are using a patched version of the @actons/cache library, due to some limitations in the main implementation:

• We added a rich response object to cache save/restore, instead of simply returning the cache key. This response object includes the total size of the entry saved/restored, and allows us to report on the total size of cache entries in total and individually.
• When the @actions/cache library recently started to log and swallow any errors that occur during save/restore, we had to undo this change via a npm patch. While swallowing exceptions might be useful for basic uses of the library, it limits our ability to report to users when a save/restore was successful or failed. In addition, the library logs warnings that lack the context that can be added by our action implementation.

Describe the enhancement

I propose that @actions/cache provide a parallel API to saveCache and restoreCache, but that this API be aimed at programmatic users of the cache infrastructure.

Features of this API would be:

• Return value from these functions would be an object containing important information about the action
  • For restoreCache, at least the key and size of downloaded entry
    • Optionally, the ID, github_ref, URL and creation date
  • For saveCache, at least the cacheId and size of uploaded entry
    • Optionally, the key, github_ref and URL of the saved entry
• No implicit logging/warning of cache errors: these will be passed to the caller
  • Allow errors to propagate to caller
  • OR Add error information to return object

Code Snippet
Here is an example calling a modified restoreCache function, reporting on the size of the entry and any errors: https://github.com/gradle/gradle-build-action/blob/main/src/cache-utils.ts#L155-L167
Here is an example calling a modified saveCache function, reporting on the size of the upload and contextualizing any errors: https://github.com/gradle/gradle-build-action/blob/main/src/cache-utils.ts#L171-L181

Additional information
@kotewar @tiwarishub I'd be happy to work on a PR to provide this functionality if it's likely to be accepted.