feat(cache): add --global flag for overriding scope (#330)

# Summary

Adds the `--global` flag to the `cache get`, `cache set`, and `cache
remove`. This flag force the execution to use the global cache, even
when run within the scope of an executable.

Closes #329

Author: jahvon

cmd/internal/cache.go

@@ -44,10 +44,11 @@ func registerCacheSetCmd(ctx *context.Context, rootCmd *cobra.Command) {
 			cacheSetFunc(ctx, cmd, args)
 		},
 	}
+	RegisterFlag(ctx, subCmd, *flags.GlobalCacheFlag)
 	rootCmd.AddCommand(subCmd)
 }
 
-func cacheSetFunc(ctx *context.Context, _ *cobra.Command, args []string) {
+func cacheSetFunc(ctx *context.Context, cmd *cobra.Command, args []string) {
 	key := args[0]
 
 	var value string
@@ -80,7 +81,12 @@ func cacheSetFunc(ctx *context.Context, _ *cobra.Command, args []string) {
 	if err != nil {
 		logger.Log().FatalErr(err)
 	}
-	if _, err = s.CreateAndSetBucket(store.EnvironmentBucket()); err != nil {
+	bucketName := store.EnvironmentBucket()
+	global := flags.ValueFor[bool](cmd, *flags.GlobalCacheFlag, false)
+	if global {
+		bucketName = store.RootBucket
+	}
+	if _, err = s.CreateAndSetBucket(bucketName); err != nil {
 		logger.Log().FatalErr(err)
 	}
 	defer func() {
@@ -105,17 +111,23 @@ func registerCacheGetCmd(ctx *context.Context, rootCmd *cobra.Command) {
 			cacheGetFunc(ctx, cmd, args)
 		},
 	}
+	RegisterFlag(ctx, subCmd, *flags.GlobalCacheFlag)
 	rootCmd.AddCommand(subCmd)
 }
 
-func cacheGetFunc(_ *context.Context, _ *cobra.Command, args []string) {
+func cacheGetFunc(_ *context.Context, cmd *cobra.Command, args []string) {
 	key := args[0]
 
 	s, err := store.NewStore(store.Path())
 	if err != nil {
 		logger.Log().FatalErr(err)
 	}
-	if _, err = s.CreateAndSetBucket(store.EnvironmentBucket()); err != nil {
+	bucketName := store.EnvironmentBucket()
+	global := flags.ValueFor[bool](cmd, *flags.GlobalCacheFlag, false)
+	if global {
+		bucketName = store.RootBucket
+	}
+	if _, err = s.CreateAndSetBucket(bucketName); err != nil {
 		logger.Log().FatalErr(err)
 	}
 	defer func() {
@@ -184,17 +196,23 @@ func registerCacheRemoveCmd(ctx *context.Context, rootCmd *cobra.Command) {
 			cacheRemoveFunc(ctx, cmd, args)
 		},
 	}
+	RegisterFlag(ctx, subCmd, *flags.GlobalCacheFlag)
 	rootCmd.AddCommand(subCmd)
 }
 
-func cacheRemoveFunc(_ *context.Context, _ *cobra.Command, args []string) {
+func cacheRemoveFunc(_ *context.Context, cmd *cobra.Command, args []string) {
 	key := args[0]
 
 	s, err := store.NewStore(store.Path())
 	if err != nil {
 		logger.Log().FatalErr(err)
 	}
-	if _, err = s.CreateAndSetBucket(store.EnvironmentBucket()); err != nil {
+	bucketName := store.EnvironmentBucket()
+	global := flags.ValueFor[bool](cmd, *flags.GlobalCacheFlag, false)
+	if global {
+		bucketName = store.RootBucket
+	}
+	if _, err = s.CreateAndSetBucket(bucketName); err != nil {
 		logger.Log().FatalErr(err)
 	}
 	defer func() {
@@ -250,4 +268,5 @@ func cacheClearFunc(_ *context.Context, cmd *cobra.Command, _ []string) {
 var dataStoreDescription = "The data store is a key-value store that can be used to persist data across executions. " +
 	"Values that are set outside of an executable will persist across all executions until they are cleared. " +
 	"When set within an executable, the data will only persist across serial or parallel sub-executables but all " +
-	"values will be cleared when the parent executable completes.\n\n"
+	"values will be cleared when the parent executable completes. " +
+	"Use the --global flag to force use of the global cache scope, even when called from within an executable.\n\n"

cmd/internal/flags/types.go

@@ -265,3 +265,11 @@ var VaultFromFileFlag = &Metadata{
 	Default:   "",
 	Required:  false,
 }
+
+var GlobalCacheFlag = &Metadata{
+	Name:      "global",
+	Shorthand: "g",
+	Usage:     "Force use of the global cache scope, even when called from within an executable",
+	Default:   false,
+	Required:  false,
+}

docs/cli/flow_cache_clear.md

@@ -4,7 +4,7 @@ Clear cache data. Use --all to remove data across all scopes.
 
 ### Synopsis
 
-The data store is a key-value store that can be used to persist data across executions. Values that are set outside of an executable will persist across all executions until they are cleared. When set within an executable, the data will only persist across serial or parallel sub-executables but all values will be cleared when the parent executable completes.
+The data store is a key-value store that can be used to persist data across executions. Values that are set outside of an executable will persist across all executions until they are cleared. When set within an executable, the data will only persist across serial or parallel sub-executables but all values will be cleared when the parent executable completes. Use the --global flag to force use of the global cache scope, even when called from within an executable.
 
 This will remove all keys and values from the data store.
 

docs/cli/flow_cache_get.md

@@ -4,7 +4,7 @@ Get cached data by key.
 
 ### Synopsis
 
-The data store is a key-value store that can be used to persist data across executions. Values that are set outside of an executable will persist across all executions until they are cleared. When set within an executable, the data will only persist across serial or parallel sub-executables but all values will be cleared when the parent executable completes.
+The data store is a key-value store that can be used to persist data across executions. Values that are set outside of an executable will persist across all executions until they are cleared. When set within an executable, the data will only persist across serial or parallel sub-executables but all values will be cleared when the parent executable completes. Use the --global flag to force use of the global cache scope, even when called from within an executable.
 
 This will retrieve the value for the given key.
 
@@ -15,7 +15,8 @@ flow cache get KEY [flags]
 ### Options
 
 ```
-  -h, --help   help for get
+  -g, --global   Force use of the global cache scope, even when called from within an executable
+  -h, --help     help for get
 ```
 
 ### Options inherited from parent commands

docs/cli/flow_cache_list.md

@@ -4,7 +4,7 @@ List all keys in the store.
 
 ### Synopsis
 
-The data store is a key-value store that can be used to persist data across executions. Values that are set outside of an executable will persist across all executions until they are cleared. When set within an executable, the data will only persist across serial or parallel sub-executables but all values will be cleared when the parent executable completes.
+The data store is a key-value store that can be used to persist data across executions. Values that are set outside of an executable will persist across all executions until they are cleared. When set within an executable, the data will only persist across serial or parallel sub-executables but all values will be cleared when the parent executable completes. Use the --global flag to force use of the global cache scope, even when called from within an executable.
 
 This will list all keys currently stored in the data store.
 

docs/cli/flow_cache_remove.md

@@ -4,7 +4,7 @@ Remove a key from the cached data store.
 
 ### Synopsis
 
-The data store is a key-value store that can be used to persist data across executions. Values that are set outside of an executable will persist across all executions until they are cleared. When set within an executable, the data will only persist across serial or parallel sub-executables but all values will be cleared when the parent executable completes.
+The data store is a key-value store that can be used to persist data across executions. Values that are set outside of an executable will persist across all executions until they are cleared. When set within an executable, the data will only persist across serial or parallel sub-executables but all values will be cleared when the parent executable completes. Use the --global flag to force use of the global cache scope, even when called from within an executable.
 
 This will remove the specified key and its value from the data store.
 
@@ -15,7 +15,8 @@ flow cache remove KEY [flags]
 ### Options
 
 ```
-  -h, --help   help for remove
+  -g, --global   Force use of the global cache scope, even when called from within an executable
+  -h, --help     help for remove
 ```
 
 ### Options inherited from parent commands

docs/cli/flow_cache_set.md

@@ -4,7 +4,7 @@ Set cached data by key.
 
 ### Synopsis
 
-The data store is a key-value store that can be used to persist data across executions. Values that are set outside of an executable will persist across all executions until they are cleared. When set within an executable, the data will only persist across serial or parallel sub-executables but all values will be cleared when the parent executable completes.
+The data store is a key-value store that can be used to persist data across executions. Values that are set outside of an executable will persist across all executions until they are cleared. When set within an executable, the data will only persist across serial or parallel sub-executables but all values will be cleared when the parent executable completes. Use the --global flag to force use of the global cache scope, even when called from within an executable.
 
 This will overwrite any existing value for the key.
 
@@ -15,7 +15,8 @@ flow cache set KEY [VALUE] [flags]
 ### Options
 
 ```
-  -h, --help   help for set
+  -g, --global   Force use of the global cache scope, even when called from within an executable
+  -h, --help     help for set
 ```
 
 ### Options inherited from parent commands

tests/cache_cmds_e2e_test.go

@@ -130,4 +130,92 @@ var _ = Describe("cache e2e", Ordered, func() {
 			Expect(out).NotTo(ContainSubstring("multi-key"))
 		})
 	})
+
+	When("using the --global flag", Ordered, func() {
+		BeforeAll(func() {
+			Expect(run.Run(ctx.Context, "cache", "clear", "--all")).To(Succeed())
+			utils.ResetTestContext(ctx, GinkgoTB())
+		})
+
+		It("should set a value in the global scope with --global flag", func() {
+			Expect(run.Run(ctx.Context, "cache", "set", "--global", "global-key", "global-value")).To(Succeed())
+			out, err := readFileContent(ctx.StdOut())
+			Expect(err).NotTo(HaveOccurred())
+			Expect(out).To(ContainSubstring("Key \"global-key\" set in the cache"))
+		})
+
+		It("should retrieve a value from the global scope with --global flag", func() {
+			utils.ResetTestContext(ctx, GinkgoTB())
+			stdOut := ctx.StdOut()
+			Expect(run.Run(ctx.Context, "cache", "get", "--global", "global-key")).To(Succeed())
+			out, err := readFileContent(stdOut)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(out).To(ContainSubstring("global-value"))
+		})
+
+		It("should set a value in execution scope without --global flag", func() {
+			utils.ResetTestContext(ctx, GinkgoTB())
+			// Simulate being in an execution by setting the bucket env var
+			GinkgoTB().Setenv("FLOW_PROCESS_BUCKET", "test:exec:scope")
+			Expect(run.Run(ctx.Context, "cache", "set", "exec-key", "exec-value")).To(Succeed())
+			out, err := readFileContent(ctx.StdOut())
+			Expect(err).NotTo(HaveOccurred())
+			Expect(out).To(ContainSubstring("Key \"exec-key\" set in the cache"))
+		})
+
+		It("should retrieve exec scope value without --global flag", func() {
+			utils.ResetTestContext(ctx, GinkgoTB())
+			GinkgoTB().Setenv("FLOW_PROCESS_BUCKET", "test:exec:scope")
+			stdOut := ctx.StdOut()
+			Expect(run.Run(ctx.Context, "cache", "get", "exec-key")).To(Succeed())
+			out, err := readFileContent(stdOut)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(out).To(ContainSubstring("exec-value"))
+		})
+
+		It("should set value in global scope even when in execution context", func() {
+			utils.ResetTestContext(ctx, GinkgoTB())
+			GinkgoTB().Setenv("FLOW_PROCESS_BUCKET", "test:exec:scope")
+			Expect(run.Run(ctx.Context, "cache", "set", "--global", "override-key", "override-value")).To(Succeed())
+			out, err := readFileContent(ctx.StdOut())
+			Expect(err).NotTo(HaveOccurred())
+			Expect(out).To(ContainSubstring("Key \"override-key\" set in the cache"))
+		})
+
+		It("should retrieve global value with --global flag from execution context", func() {
+			utils.ResetTestContext(ctx, GinkgoTB())
+			GinkgoTB().Setenv("FLOW_PROCESS_BUCKET", "test:exec:scope")
+			stdOut := ctx.StdOut()
+			Expect(run.Run(ctx.Context, "cache", "get", "--global", "override-key")).To(Succeed())
+			out, err := readFileContent(stdOut)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(out).To(ContainSubstring("override-value"))
+		})
+
+		It("should retrieve global value without execution context", func() {
+			utils.ResetTestContext(ctx, GinkgoTB())
+			stdOut := ctx.StdOut()
+			Expect(run.Run(ctx.Context, "cache", "get", "--global", "override-key")).To(Succeed())
+			out, err := readFileContent(stdOut)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(out).To(ContainSubstring("override-value"))
+		})
+
+		It("should remove a value from global scope with --global flag", func() {
+			utils.ResetTestContext(ctx, GinkgoTB())
+			Expect(run.Run(ctx.Context, "cache", "remove", "--global", "global-key")).To(Succeed())
+			out, err := readFileContent(ctx.StdOut())
+			Expect(err).NotTo(HaveOccurred())
+			Expect(out).To(ContainSubstring("Key \"global-key\" removed from the cache"))
+		})
+
+		It("should remove a value from global scope with --global in execution context", func() {
+			utils.ResetTestContext(ctx, GinkgoTB())
+			GinkgoTB().Setenv("FLOW_PROCESS_BUCKET", "test:exec:scope")
+			Expect(run.Run(ctx.Context, "cache", "remove", "--global", "override-key")).To(Succeed())
+			out, err := readFileContent(ctx.StdOut())
+			Expect(err).NotTo(HaveOccurred())
+			Expect(out).To(ContainSubstring("Key \"override-key\" removed from the cache"))
+		})
+	})
 })