fix: ensure single shared SyncPrefixHashTable instance across Store a…

[penfree]

Fix: Ensure Single Shared SyncPrefixHashTable Instance Across Components

Problem

Multiple components created separate instances of SyncPrefixHashTable, leading to inconsistent prefix cache state:

• Store (pkg/cache/cache_init.go:566) created its own instance
• kvSyncPrefixCacheRouter (pkg/plugins/gateway/algorithms/prefix_cache.go:303) created another instance

Impact:

• ❌ Prefix cache state divergence between gateway and storage layers
• ❌ Cache misses due to different indexer instances
• ❌ Inconsistent KV sync behavior

Example Scenario

Request Flow:
  1. kvSyncRouter adds prefix to its SyncPrefixHashTable (instance A)
  2. Store's KV event handler updates its SyncPrefixHashTable (instance B)
  3. Next request queries instance A, but prefix data is in instance B
  4. Result: Cache miss ❌

Root Cause

The SyncPrefixHashTable was designed to be a shared, centralized index. However, the code directly called NewSyncPrefixHashTable() in multiple locations without ensuring a single shared instance.

Solution

Implement singleton pattern to guarantee all components reference the same instance:

1. Add Singleton Function

File: pkg/utils/syncprefixcacheindexer/sync_hash.go

var (
    sharedSyncOnce     sync.Once
    sharedSyncInstance *SyncPrefixHashTable
)

// GetSharedSyncPrefixHashTable returns the shared singleton instance
func GetSharedSyncPrefixHashTable() *SyncPrefixHashTable {
    sharedSyncOnce.Do(func() {
        sharedSyncInstance = NewSyncPrefixHashTable()
    })
    return sharedSyncInstance
}

Features:

• Thread-safe initialization using sync.Once
• Lazy initialization on first access
• Follows the same pattern as GetSharedPrefixHashTable

2. Update All Call Sites

# pkg/cache/cache_init.go
- s.syncPrefixIndexer = syncindexer.NewSyncPrefixHashTable()
+ s.syncPrefixIndexer = syncindexer.GetSharedSyncPrefixHashTable()

# pkg/plugins/gateway/algorithms/prefix_cache.go
  kvSyncRouter := &kvSyncPrefixCacheRouter{
-     syncIndexer:    syncindexer.NewSyncPrefixHashTable(),
+     syncIndexer:    syncindexer.GetSharedSyncPrefixHashTable(),
  }

Testing

New Test Suite

Added pkg/utils/syncprefixcacheindexer/singleton_test.go with tests for:

1. Single Instance Verification - Multiple calls return the same instance
2. Concurrent Access Safety - 100 goroutines verify thread-safe initialization
3. Functionality Persistence - Data persists across different references

[gemini-code-assist]

Code Review

This pull request transitions the SyncPrefixHashTable to a singleton pattern to ensure consistent indexing across different components such as the Store and the gateway router. While the implementation correctly uses sync.Once for thread-safe initialization, the transition introduces a significant lifecycle risk: calling Close() on the shared instance (for example, during Store cleanup) will permanently stop the background eviction worker for all components without a way to restart it. Additionally, the new unit tests should be updated to close the existing instance before resetting the singleton state to prevent leaking background goroutines.