Merge pull request #111 from buildkite-plugins/toote_extra_key_data

Extra key data

Author: pzeballos

README.md

@@ -88,6 +88,34 @@ Remove compression artifacts after they are used. Default: `false`.
 
 Note that if you turn on this option, every execution will create temporary files that may fill up your agent's storage.
 
+### `key-extra`
+
+Additional data used to compute the cache key. You can use this additional parameter to further differentiate within a given level.
+
+For example when used in conjunction with a build matrix:
+
+```yaml
+steps:
+  - matrix:
+      - "darwin"
+      - "Linux"
+      - "Windows"
+    label: "{{matrix}} build"
+    command: "GOOS={{matrix}} go build"
+    env:
+      os: "{{matrix}}"
+      GOMODCACHE: pkg/cache
+    plugins:
+      - cache#v1.5.2:
+          path: pkg/cache
+          manifest:
+            - go.mod
+            - go.sum
+          restore: file
+          save: file
+          key-extra: "{{matrix}}"
+```
+
 ### `manifest` (string or list of strings, required if using `file` caching level)
 
 One or more paths to files or folders that will be hashed to create and restore file-level caches. If multiple files or folders are specified its ordering does not matter.
@@ -105,6 +133,8 @@ This plugin uses the following hierarchical structure for caches to be valid (me
 
 When restoring from cache, **all levels, in the described order, up to the one specified** will be checked. The first one available will be restored and no further levels or checks will be made.
 
+Note: you can use the [`key-extra`](#key-extra) option to further differentiate within a level
+
 ## Customizable backends
 
 One of the greatest flexibilities of this plugin is its flexible backend architecture. You can provide whatever value you want for the `backend` option of this plugin (`X` for example) as long as there is an executable script accessible to the agent named `cache_X` that respects the following execution protocol:

lib/shared.bash

@@ -40,6 +40,7 @@ build_key() {
   local LEVEL="$1"
   local CACHE_PATH="$2"
   local COMPRESSION="${3:-}"
+  local EXTRA="${BUILDKITE_PLUGIN_CACHE_KEY_EXTRA:-}"
 
   if [ "${LEVEL}" = 'file' ]; then
     plugin_read_list_into_result MANIFEST
@@ -57,7 +58,7 @@ build_key() {
     exit 1
   fi
 
-  echo "cache-${LEVEL}-${BASE}-${CACHE_PATH}-${COMPRESSION}" | "$(sha)" | cut -d\  -f1
+  echo "cache-${LEVEL}-${BASE}-${CACHE_PATH}-${COMPRESSION}${EXTRA}" | "$(sha)" | cut -d\  -f1
 }
 
 backend_exec() {

plugin.yml

@@ -21,6 +21,8 @@ configuration:
       type: boolean
     keep-compressed-artifacts:
       type: boolean
+    key-extra:
+      type: string
     manifest:
       oneOf:
         - type: string

tests/shared.bats

@@ -90,6 +90,36 @@ teardown() {
   refute_output "${EMPTY_FILE}"
   assert_output "${MODIFIED_FILE}"
 
+  # using extra data changes the key
+  export BUILDKITE_PLUGIN_CACHE_KEY_EXTRA=extra
+
+  run build_key file FOLDER
+  EXTRA_KEY="${output}"
+
+  assert_success
+  refute_output "${MODIFIED_FILE}"
+  refute_output "${EMPTY_FILE}"
+
+  # different extra data changes the key
+  export BUILDKITE_PLUGIN_CACHE_KEY_EXTRA=other_extra
+
+  run build_key file FOLDER
+
+  assert_success
+
+  refute_output "${MODIFIED_FILE}"
+  refute_output "${EMPTY_FILE}"
+  refute_output "${EXTRA_KEY}"
+
+  # empty extra data returns key to expected
+  export BUILDKITE_PLUGIN_CACHE_KEY_EXTRA=''
+  run build_key file FOLDER
+
+  assert_success
+  assert_output "${MODIFIED_FILE}"
+  refute_output "${EMPTY_FILE}"
+  refute_output "${EXTRA_KEY}"
+
   rm test.file
   rm -rf FOLDER
   rm other.file
@@ -131,6 +161,36 @@ teardown() {
   refute_output "${EMPTY_FOLDER}"
   assert_output "${MODIFIED_FOLDER}"
 
+  # using extra data changes the key
+  export BUILDKITE_PLUGIN_CACHE_KEY_EXTRA=extra
+
+  run build_key file FOLDER
+  EXTRA_KEY="${output}"
+
+  assert_success
+  refute_output "${MODIFIED_FOLDER}"
+  refute_output "${EMPTY_FOLDER}"
+
+  # different extra data changes the key
+  export BUILDKITE_PLUGIN_CACHE_KEY_EXTRA=other_extra
+
+  run build_key file FOLDER
+
+  assert_success
+  refute_output "${MODIFIED_FOLDER}"
+  refute_output "${EMPTY_FOLDER}"
+  refute_output "${EXTRA_KEY}"
+
+  # empty extra data returns key to expected
+  export BUILDKITE_PLUGIN_CACHE_KEY_EXTRA=''
+
+  run build_key file FOLDER
+
+  assert_success
+  assert_output "${MODIFIED_FOLDER}"
+  refute_output "${EMPTY_FOLDER}"
+  refute_output "${EXTRA_KEY}"
+
   rm -rf test.folder
   rm -rf FOLDER
 }
@@ -153,4 +213,33 @@ teardown() {
   run build_key file FOLDER another_thing
   assert_success
   refute_output "${GENERATED_KEY}"
+
+  # extra data changes the key
+  export BUILDKITE_PLUGIN_CACHE_KEY_EXTRA=extra
+
+  run build_key file FOLDER something
+  EXTRA_KEY="${output}"
+
+  assert_success
+  refute_output "${GENERATED_KEY}"
+  refute_output "${EMPTY_KEY}"
+
+  # different extra data changes the key
+  export BUILDKITE_PLUGIN_CACHE_KEY_EXTRA=other_extra
+  run build_key file FOLDER something
+
+  assert_success
+  refute_output "${GENERATED_KEY}"
+  refute_output "${EMPTY_KEY}"
+  refute_output "${EXTRA_KEY}"
+
+  # empty extra data returns key to expected
+  export BUILDKITE_PLUGIN_CACHE_KEY_EXTRA=''
+  run build_key file FOLDER something
+
+  assert_success
+  assert_output "${GENERATED_KEY}"
+  refute_output "${EMPTY_KEY}"
+  refute_output "${EXTRA_KEY}"
+
 }