test+docs: add extra test and update README

Author: yosiharan

README.md

@@ -24,6 +24,8 @@ docker run -d \
 - `AUTHZCACHE_INDIRECT_RELATION_CACHE_SIZE_PER_PROJECT` - Indirect relation cache size per project (default: 1,000,000)
 - `AUTHZCACHE_REMOTE_POLLING_INTERVAL_IN_MILLIS` - Remote polling interval in milliseconds (default: 15,000)
 - `AUTHZCACHE_PURGE_COOLDOWN_WINDOW_IN_MINUTES` - Cooldown window in minutes before purging cache on refresh error (default: 0, meaning immediate purge). When set to a positive value, the cache will wait for the specified duration after the first error before purging. If a successful response is received during the cooldown window, the purge is cancelled. This provides a balance between data freshness and availability during temporary service disruptions. During this window, the cache continues serving stale and potentially invalid authorization data, which may not reflect current permissions.
+- `AUTHZCACHE_METRICS_REPORT_ENABLED` - Whether to periodically report cache performance metrics (hit/miss rates, latency) to Descope (TRUE/FALSE, default: TRUE)
+- `AUTHZCACHE_METRICS_REPORT_INTERVAL_IN_SECONDS` - How often to report metrics, in seconds (default: 60, minimum: 10)
 
 ## Ports
 - **8189** - HTTP REST API endpoint

internal/services/authz_test.go

@@ -629,6 +629,38 @@ func TestWhatCanTargetAccess_MetricsRecorded_CacheMiss(t *testing.T) {
 	require.Equal(t, int64(1), agg.SumResultSize)
 }
 
+func TestWhatCanTargetAccess_MetricsRecorded_CacheHit(t *testing.T) {
+	ac, _, mockCache, collector := injectAuthzMocksWithCollector(t)
+	ctx := cctx.AddProjectID(context.TODO(), "proj1")
+	candidates := []*descope.AuthzRelation{
+		{Resource: "doc1", RelationDefinition: "viewer", Namespace: "docs", Target: "u1"},
+		{Resource: "doc2", RelationDefinition: "editor", Namespace: "docs", Target: "u1"},
+		{Resource: "doc3", RelationDefinition: "viewer", Namespace: "docs", Target: "u1"},
+	}
+	mockCache.GetWhatCanTargetAccessCachedFunc = func(_ context.Context, _ string) ([]*descope.AuthzRelation, bool) {
+		return candidates, true
+	}
+	mockCache.SetWhatCanTargetAccessCachedFunc = func(_ context.Context, _ string, _ []*descope.AuthzRelation) {
+		require.Fail(t, "should not update cache on hit")
+	}
+	mockCache.CheckRelationFunc = func(_ context.Context, r *descope.FGARelation) (bool, bool, bool) {
+		return r.Resource != "doc2", true, true // doc2 filtered out
+	}
+	mockCache.UpdateCacheWithChecksFunc = func(_ context.Context, _ []*descope.FGACheck) {}
+	_, err := ac.WhatCanTargetAccess(ctx, "u1")
+	require.NoError(t, err)
+	snapshot := collector.SnapshotAndReset()
+	require.Contains(t, snapshot, "proj1")
+	agg := snapshot["proj1"][metrics.APIWhatCanTargetAccess]
+	require.NotNil(t, agg)
+	require.Equal(t, int64(1), agg.TotalCalls)
+	require.Equal(t, int64(1), agg.HitCount)
+	require.Equal(t, int64(0), agg.MissCount)
+	require.Equal(t, int64(3), agg.SumCandidates)
+	require.Equal(t, int64(1), agg.SumFiltered) // doc2 filtered out
+	require.Equal(t, int64(2), agg.SumResultSize)
+}
+
 func BenchmarkCheck(b *testing.B) {
 	for _, numRelations := range []int{500, 1000, 5000} {
 		name := fmt.Sprintf("relations=%d", numRelations)