perf: async cache update after Check to reduce write lock contention

UpdateCacheWithChecks holds a write lock while doing N LRU insertions,
blocking all concurrent readers (CheckRelation needs RLock). With 500+
relations this becomes a bottleneck. Make the cache update async by
default (configurable via AUTHZCACHE_ASYNC_CACHE_UPDATE) so results
return to clients immediately.

Resolves descope/etc#14193

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: yosiharan

internal/config/config.go

@@ -17,6 +17,7 @@ const (
 	ConfigKeyLookupCacheSizePerProject = "AUTHZCACHE_LOOKUP_CACHE_SIZE_PER_PROJECT" // max entries per project
 	ConfigKeyLookupCacheTTLInSeconds   = "AUTHZCACHE_LOOKUP_CACHE_TTL_IN_SECONDS"   // TTL for lookup cache entries
 	ConfigKeyLookupCacheMaxResultSize  = "AUTHZCACHE_LOOKUP_CACHE_MAX_RESULT_SIZE"  // max result size to cache (skip caching large results)
+	ConfigKeyAsyncCacheUpdate          = "AUTHZCACHE_ASYNC_CACHE_UPDATE"            // TRUE/FALSE, default is TRUE
 )
 
 func GetDirectRelationCacheSizePerProject() int {
@@ -54,3 +55,7 @@ func GetLookupCacheTTLInSeconds() int {
 func GetLookupCacheMaxResultSize() int {
 	return cconfig.GetIntOrProvidedLocal(ConfigKeyLookupCacheMaxResultSize, 1000)
 }
+
+func GetAsyncCacheUpdate() bool {
+	return cconfig.GetBoolOrProvidedLocal(ConfigKeyAsyncCacheUpdate, true)
+}

internal/config/config_test.go

@@ -137,6 +137,43 @@ func TestGetSDKDebugLog(t *testing.T) {
 	}
 }
 
+func TestGetAsyncCacheUpdate(t *testing.T) {
+	tests := []struct {
+		name     string
+		value    string
+		setEnv   bool
+		expected bool
+	}{
+		{
+			name:     "Config value not set (default true)",
+			setEnv:   false,
+			expected: true,
+		},
+		{
+			name:     "Config value set to false",
+			value:    "false",
+			setEnv:   true,
+			expected: false,
+		},
+		{
+			name:     "Config value set to true",
+			value:    "true",
+			setEnv:   true,
+			expected: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if tt.setEnv {
+				t.Setenv(ConfigKeyAsyncCacheUpdate, tt.value)
+			}
+			actual := GetAsyncCacheUpdate()
+			require.Equal(t, tt.expected, actual)
+		})
+	}
+}
+
 func TestGetPurgeCooldownWindowInMinutes(t *testing.T) {
 	tests := []struct {
 		name     string

internal/services/authz.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"sync"
 
+	"github.com/descope/authzcache/internal/config"
 	"github.com/descope/authzcache/internal/services/caches"
 	cctx "github.com/descope/common/pkg/common/context"
 	"github.com/descope/go-sdk/descope"
@@ -127,7 +128,11 @@ func (a *authzCache) Check(ctx context.Context, relations []*descope.FGARelation
 		return nil, err // notest
 	}
 	// update cache
-	projectCache.UpdateCacheWithChecks(ctx, sdkChecks)
+	if config.GetAsyncCacheUpdate() {
+		go projectCache.UpdateCacheWithChecks(context.WithoutCancel(ctx), sdkChecks)
+	} else {
+		projectCache.UpdateCacheWithChecks(ctx, sdkChecks)
+	}
 	// merge cached and sdk checks in the same order as input relations and return them
 	var result []*descope.FGACheck
 	var j int

internal/services/authz_test.go

@@ -2,8 +2,12 @@ package services
 
 import (
 	"context"
+	"fmt"
+	"sync"
+	"sync/atomic"
 	"testing"
 
+	"github.com/descope/authzcache/internal/config"
 	"github.com/descope/authzcache/internal/services/caches"
 	"github.com/descope/go-sdk/descope"
 	"github.com/descope/go-sdk/descope/logger"
@@ -531,3 +535,122 @@ func TestWhatCanTargetAccess_IndirectRelationRemoved_FilteredImmediately(t *test
 	require.Len(t, result, 1)
 	require.Equal(t, "doc1", result[0].Resource)
 }
+
+func TestCheckAsyncCacheUpdate(t *testing.T) {
+	t.Setenv(config.ConfigKeyAsyncCacheUpdate, "true")
+	// setup mocks
+	ac, mockSDK, mockCache := injectAuthzMocks(t)
+	relations := []*descope.FGARelation{{Resource: "mario", Target: "luigi", Relation: "bigBro"}}
+	sdkChecks := []*descope.FGACheck{{Allowed: true, Relation: relations[0], Info: &descope.FGACheckInfo{Direct: true}}}
+	mockSDK.MockFGA.CheckResponse = sdkChecks
+	mockCache.CheckRelationFunc = func(_ context.Context, _ *descope.FGARelation) (bool, bool, bool) {
+		return false, false, false
+	}
+	// use a WaitGroup to detect when the async goroutine calls UpdateCacheWithChecks
+	var wg sync.WaitGroup
+	wg.Add(1)
+	mockCache.UpdateCacheWithChecksFunc = func(_ context.Context, checks []*descope.FGACheck) {
+		defer wg.Done()
+		require.Equal(t, sdkChecks, checks)
+	}
+	// run test
+	result, err := ac.Check(context.TODO(), relations)
+	require.NoError(t, err)
+	require.Equal(t, sdkChecks, result)
+	// wait for the async cache update to complete
+	wg.Wait()
+}
+
+func TestCheckSyncCacheUpdate(t *testing.T) {
+	t.Setenv(config.ConfigKeyAsyncCacheUpdate, "false")
+	// setup mocks
+	ac, mockSDK, mockCache := injectAuthzMocks(t)
+	relations := []*descope.FGARelation{{Resource: "mario", Target: "luigi", Relation: "bigBro"}}
+	sdkChecks := []*descope.FGACheck{{Allowed: true, Relation: relations[0], Info: &descope.FGACheckInfo{Direct: true}}}
+	mockSDK.MockFGA.CheckResponse = sdkChecks
+	mockCache.CheckRelationFunc = func(_ context.Context, _ *descope.FGARelation) (bool, bool, bool) {
+		return false, false, false
+	}
+	// track that UpdateCacheWithChecks is called before Check returns
+	cacheUpdated := false
+	mockCache.UpdateCacheWithChecksFunc = func(_ context.Context, checks []*descope.FGACheck) {
+		require.Equal(t, sdkChecks, checks)
+		cacheUpdated = true
+	}
+	// run test
+	result, err := ac.Check(context.TODO(), relations)
+	require.NoError(t, err)
+	require.Equal(t, sdkChecks, result)
+	// in sync mode, cache must already be updated when Check returns
+	require.True(t, cacheUpdated, "UpdateCacheWithChecks should be called synchronously before Check returns")
+}
+
+func BenchmarkCheck(b *testing.B) {
+	for _, numRelations := range []int{500, 1000, 5000} {
+		for _, async := range []bool{false, true} {
+			name := fmt.Sprintf("relations=%d/async=%v", numRelations, async)
+			b.Run(name, func(b *testing.B) {
+				if async {
+					b.Setenv(config.ConfigKeyAsyncCacheUpdate, "true")
+				} else {
+					b.Setenv(config.ConfigKeyAsyncCacheUpdate, "false")
+				}
+				// setup: real cache + mock SDK returning instant results
+				ctx := context.TODO()
+				projectCache, err := caches.NewProjectAuthzCache(ctx, nil)
+				if err != nil {
+					b.Fatal(err)
+				}
+				// fixed SDK response — same length as input, reused across goroutines (read-only)
+				sdkResponse := make([]*descope.FGACheck, numRelations)
+				for i := range sdkResponse {
+					sdkResponse[i] = &descope.FGACheck{
+						Allowed:  i%2 == 0,
+						Relation: &descope.FGARelation{Resource: fmt.Sprintf("sdk-r-%d", i), Target: fmt.Sprintf("sdk-t-%d", i), Relation: "viewer", ResourceType: "doc"},
+						Info:     &descope.FGACheckInfo{Direct: true},
+					}
+				}
+				mockFGA := &mocksmgmt.MockFGA{CheckResponse: sdkResponse}
+				mockSDK := &mocksmgmt.MockManagement{
+					MockFGA:   mockFGA,
+					MockAuthz: &mocksmgmt.MockAuthz{},
+				}
+				mockRemoteClientCreator := func(_ string, _ logger.LoggerInterface) (sdk.Management, error) {
+					return mockSDK, nil
+				}
+				mockCacheCreator := func(_ context.Context, _ caches.RemoteChangesChecker) (caches.ProjectAuthzCache, error) {
+					return projectCache, nil
+				}
+				ac, err := New(ctx, mockCacheCreator, mockRemoteClientCreator)
+				if err != nil {
+					b.Fatal(err)
+				}
+				// warm up: trigger project cache creation
+				warmupRel := []*descope.FGARelation{{Resource: "warmup", Target: "warmup", Relation: "viewer", ResourceType: "doc"}}
+				origResp := mockFGA.CheckResponse
+				mockFGA.CheckResponse = []*descope.FGACheck{{Allowed: true, Relation: warmupRel[0], Info: &descope.FGACheckInfo{Direct: true}}}
+				_, _ = ac.Check(ctx, warmupRel)
+				mockFGA.CheckResponse = origResp
+
+				var counter atomic.Int64
+				b.ResetTimer()
+				b.RunParallel(func(pb *testing.PB) {
+					for pb.Next() {
+						id := counter.Add(1)
+						// unique relations per call — always cache misses
+						rels := make([]*descope.FGARelation, numRelations)
+						for j := range numRelations {
+							rels[j] = &descope.FGARelation{
+								Resource:     fmt.Sprintf("r-%d-%d", id, j),
+								Target:       fmt.Sprintf("t-%d-%d", id, j),
+								Relation:     "viewer",
+								ResourceType: "doc",
+							}
+						}
+						_, _ = ac.Check(ctx, rels)
+					}
+				})
+			})
+		}
+	}
+}