feat: add CachedCheckResolver for caching Check subproblems

.config-schema.json

@@ -61,7 +61,7 @@
             "type": "array",
             "items": {
                 "type": "string",
-                "enum": []
+                "enum": ["check-query-cache"]
             },
             "default": [],
             "x-env-variable": "OPENFGA_EXPERIMENTALS"
@@ -349,6 +349,30 @@
                     "x-env-variable": "OPENFGA_METRICS_ENABLE_RPC_HISTOGRAMS"
                 }
             }
+        },
+        "checkQueryCache": {
+            "type": "object",
+            "properties": {
+                "enabled": {
+                    "description": "when executing Check and ListObjects requests, enables caching. This will turn Check and ListObjects responses into eventually consistent responses",
+                    "type": "bool",
+                    "default": "false",
+                    "x-env-variable": "OPENFGA_CHECK_QUERY_CACHE_ENABLED"
+                },
+                "limit": {
+                    "description": "if caching of Check and ListObjects calls is enabled, this is the size limit (in items) of the cache",
+                    "type": "integer",
+                    "default": "10000",
+                    "x-env-variable": "OPENFGA_CHECK_QUERY_CACHE_LIMIT"
+                },
+                "ttl": {
+                    "description": "if caching of Check and ListObjects is enabled, this is the TTL of each value",
+                    "type": "string",
+                    "format": "duration",
+                    "default": "10s",
+                    "x-env-variable": "OPENFGA_CHECK_QUERY_CACHE_TTL"
+                }
+            }
         }
     },
     "definitions": {

cmd/run/flags.go

@@ -157,5 +157,14 @@ func bindRunFlagsFunc(flags *pflag.FlagSet) func(*cobra.Command, []string) {
 
 		util.MustBindPFlag("listObjectsMaxResults", flags.Lookup("listObjects-max-results"))
 		util.MustBindEnv("listObjectsMaxResults", "OPENFGA_LIST_OBJECTS_MAX_RESULTS", "OPENFGA_LISTOBJECTSMAXRESULTS")
+
+		util.MustBindPFlag("checkQueryCache.enabled", flags.Lookup("check-query-cache-enabled"))
+		util.MustBindEnv("checkQueryCache.enabled", "OPENFGA_CHECK_QUERY_CACHE_ENABLED")
+
+		util.MustBindPFlag("checkQueryCache.limit", flags.Lookup("check-query-cache-limit"))
+		util.MustBindEnv("checkQueryCache.limit", "OPENFGA_CHECK_QUERY_CACHE_LIMIT")
+
+		util.MustBindPFlag("checkQueryCache.ttl", flags.Lookup("check-query-cache-ttl"))
+		util.MustBindEnv("checkQueryCache.ttl", "OPENFGA_CHECK_QUERY_CACHE_TTL")
 	}
 }

cmd/run/run.go

@@ -179,6 +179,12 @@ func NewRunCommand() *cobra.Command {
 
 	flags.Uint32("listObjects-max-results", defaultConfig.ListObjectsMaxResults, "the maximum results to return in non-streaming ListObjects API responses. If 0, all results can be returned")
 
+	flags.Bool("check-query-cache-enabled", defaultConfig.CheckQueryCache.Enabled, "when executing Check and ListObjects requests, enables caching. This will turn Check and ListObjects responses into eventually consistent responses")
+
+	flags.Uint32("check-query-cache-limit", defaultConfig.CheckQueryCache.Limit, "if caching of Check and ListObjects calls is enabled, this is the size limit of the cache")
+
+	flags.Duration("check-query-cache-ttl", defaultConfig.CheckQueryCache.TTL, "if caching of Check and ListObjects is enabled, this is the TTL of each value")
+
 	// NOTE: if you add a new flag here, update the function below, too
 
 	cmd.PreRun = bindRunFlagsFunc(flags)
@@ -301,6 +307,13 @@ type MetricConfig struct {
 	EnableRPCHistograms bool
 }
 
+// CheckQueryCache defines configuration for caching when resolving check
+type CheckQueryCache struct {
+	Enabled bool
+	Limit   uint32 // (in items)
+	TTL     time.Duration
+}
+
 type Config struct {
 	// If you change any of these settings, please update the documentation at https://github.com/openfga/openfga.dev/blob/main/docs/content/intro/setup-openfga.mdx
 
@@ -338,15 +351,16 @@ type Config struct {
 	// ResolveNodeBreadthLimit indicates how many nodes on a given level can be evaluated concurrently in a query
 	ResolveNodeBreadthLimit uint32
 
-	Datastore  DatastoreConfig
-	GRPC       GRPCConfig
-	HTTP       HTTPConfig
-	Authn      AuthnConfig
-	Log        LogConfig
-	Trace      TraceConfig
-	Playground PlaygroundConfig
-	Profiler   ProfilerConfig
-	Metrics    MetricConfig
+	Datastore       DatastoreConfig
+	GRPC            GRPCConfig
+	HTTP            HTTPConfig
+	Authn           AuthnConfig
+	Log             LogConfig
+	Trace           TraceConfig
+	Playground      PlaygroundConfig
+	Profiler        ProfilerConfig
+	Metrics         MetricConfig
+	CheckQueryCache CheckQueryCache
 }
 
 // DefaultConfig returns the OpenFGA server default configurations.
@@ -410,6 +424,11 @@ func DefaultConfig() *Config {
 			Addr:                "0.0.0.0:2112",
 			EnableRPCHistograms: false,
 		},
+		CheckQueryCache: CheckQueryCache{
+			Enabled: false,
+			Limit:   10000,
+			TTL:     10 * time.Second,
+		},
 	}
 }
 
@@ -720,6 +739,9 @@ func (s *ServerContext) Run(ctx context.Context, config *Config) error {
 		server.WithListObjectsMaxResults(config.ListObjectsMaxResults),
 		server.WithMaxConcurrentReadsForListObjects(config.MaxConcurrentReadsForListObjects),
 		server.WithMaxConcurrentReadsForCheck(config.MaxConcurrentReadsForCheck),
+		server.WithCheckQueryCacheEnabled(config.CheckQueryCache.Enabled),
+		server.WithCheckQueryCacheLimit(config.CheckQueryCache.Limit),
+		server.WithCheckQueryCacheTTL(config.CheckQueryCache.TTL),
 		server.WithExperimentals(experimentals...),
 	)
 

cmd/run/run_test.go

@@ -1059,6 +1059,18 @@ func TestDefaultConfig(t *testing.T) {
 	val = res.Get("properties.trace.properties.serviceName.default")
 	require.True(t, val.Exists())
 	require.Equal(t, val.String(), cfg.Trace.ServiceName)
+
+	val = res.Get("properties.checkQueryCache.properties.enabled.default")
+	require.True(t, val.Exists())
+	require.Equal(t, val.Bool(), cfg.CheckQueryCache.Enabled)
+
+	val = res.Get("properties.checkQueryCache.properties.limit.default")
+	require.True(t, val.Exists())
+	require.EqualValues(t, val.Int(), cfg.CheckQueryCache.Limit)
+
+	val = res.Get("properties.checkQueryCache.properties.ttl.default")
+	require.True(t, val.Exists())
+	require.Equal(t, val.String(), cfg.CheckQueryCache.TTL.String())
 }
 
 func TestRunCommandNoConfigDefaultValues(t *testing.T) {
@@ -1067,6 +1079,9 @@ func TestRunCommandNoConfigDefaultValues(t *testing.T) {
 	runCmd.RunE = func(cmd *cobra.Command, _ []string) error {
 		require.Equal(t, "", viper.GetString(datastoreEngineFlag))
 		require.Equal(t, "", viper.GetString(datastoreURIFlag))
+		require.False(t, viper.GetBool("check-query-cache-enabled"))
+		require.Equal(t, uint32(0), viper.GetUint32("check-query-cache-limit"))
+		require.Equal(t, 0*time.Second, viper.GetDuration("check-query-cache-ttl"))
 		return nil
 	}
 
@@ -1096,6 +1111,30 @@ func TestRunCommandConfigFileValuesAreParsed(t *testing.T) {
 	require.Nil(t, rootCmd.Execute())
 }
 
+func TestParseConfig(t *testing.T) {
+	config := `checkQueryCache:
+    enabled: true
+    limit: 100
+    TTL: 5s
+`
+	util.PrepareTempConfigFile(t, config)
+
+	runCmd := NewRunCommand()
+	runCmd.RunE = func(cmd *cobra.Command, _ []string) error {
+		return nil
+	}
+	rootCmd := cmd.NewRootCommand()
+	rootCmd.AddCommand(runCmd)
+	rootCmd.SetArgs([]string{"run"})
+	require.Nil(t, rootCmd.Execute())
+
+	cfg, err := ReadConfig()
+	require.NoError(t, err)
+	require.True(t, cfg.CheckQueryCache.Enabled)
+	require.Equal(t, uint32(100), cfg.CheckQueryCache.Limit)
+	require.Equal(t, 5*time.Second, cfg.CheckQueryCache.TTL)
+}
+
 func TestRunCommandConfigIsMerged(t *testing.T) {
 	config := `datastore:
     engine: postgres
@@ -1104,12 +1143,18 @@ func TestRunCommandConfigIsMerged(t *testing.T) {
 
 	t.Setenv("OPENFGA_DATASTORE_URI", "postgres://postgres:PASS2@127.0.0.1:5432/postgres")
 	t.Setenv("OPENFGA_MAX_TYPES_PER_AUTHORIZATION_MODEL", "1")
+	t.Setenv("OPENFGA_CHECK_QUERY_CACHE_ENABLED", "true")
+	t.Setenv("OPENFGA_CHECK_QUERY_CACHE_LIMIT", "33")
+	t.Setenv("OPENFGA_CHECK_QUERY_CACHE_TTL", "5s")
 
 	runCmd := NewRunCommand()
 	runCmd.RunE = func(cmd *cobra.Command, _ []string) error {
 		require.Equal(t, "postgres", viper.GetString(datastoreEngineFlag))
 		require.Equal(t, "postgres://postgres:PASS2@127.0.0.1:5432/postgres", viper.GetString(datastoreURIFlag))
 		require.Equal(t, "1", viper.GetString("max-types-per-authorization-model"))
+		require.True(t, viper.GetBool("check-query-cache-enabled"))
+		require.Equal(t, uint32(33), viper.GetUint32("check-query-cache-limit"))
+		require.Equal(t, 5*time.Second, viper.GetDuration("check-query-cache-ttl"))
 		return nil
 	}