Improve Project Caching and Invalidation Consistency (#1600)

Enhanced the project caching mechanism with a dual-lookup strategy
that uses project ID as the primary key and API key as a secondary key
to achieve faster and more reliable lookups.

Author: emplam27

api/yorkie/v1/cluster.proto

@@ -90,7 +90,6 @@ enum CacheType {
 }
 
 message InvalidateCacheRequest {
-
   CacheType cache_type = 1;
   string key = 2;
 }

pkg/cache/lru_with_expires.go

@@ -35,8 +35,18 @@ type LRUWithExpires[K comparable, V any] struct {
 }
 
 // NewLRUWithExpires creates a new expirable LRU with the given size and ttl.
-func NewLRUWithExpires[K comparable, V any](size int, ttl time.Duration, name string) (*LRUWithExpires[K, V], error) {
-	c := expirable.NewLRU[K, V](size, nil, ttl)
+func NewLRUWithExpires[K comparable, V any](
+	size int,
+	ttl time.Duration,
+	name string,
+	onEvict ...func(key K, value V),
+) (*LRUWithExpires[K, V], error) {
+	var callback func(key K, value V)
+	if len(onEvict) > 0 {
+		callback = onEvict[0]
+	}
+
+	c := expirable.NewLRU(size, callback, ttl)
 	return &LRUWithExpires[K, V]{
 		cache: c,
 		stats: &Stats{},

server/backend/database/mongo/client.go

@@ -52,7 +52,7 @@ type Client struct {
 	client *mongo.Client
 
 	cacheManager  *cache.Manager
-	projectCache  *cache.LRUWithExpires[string, *database.ProjectInfo]
+	projectCache  *ProjectCache
 	clientCache   *cache.LRU[types.ClientRefKey, *database.ClientInfo]
 	docCache      *cache.LRU[types.DocRefKey, *database.DocInfo]
 	changeCache   *cache.LRU[types.DocRefKey, *ChangeStore]
@@ -104,11 +104,7 @@ func Dial(conf *Config) (*Client, error) {
 
 	cacheManager := cache.NewManager(conf.ParseCacheStatsInterval())
 
-	projectCache, err := cache.NewLRUWithExpires[string, *database.ProjectInfo](
-		conf.ProjectCacheSize,
-		conf.ParseProjectCacheTTL(),
-		"projects",
-	)
+	projectCache, err := NewProjectCache(conf.ProjectCacheSize, conf.ParseProjectCacheTTL())
 	if err != nil {
 		return nil, fmt.Errorf("initialize project cache: %w", err)
 	}
@@ -152,8 +148,7 @@ func Dial(conf *Config) (*Client, error) {
 		config: conf,
 		client: client,
 
-		cacheManager: cacheManager,
-
+		cacheManager:  cacheManager,
 		projectCache:  projectCache,
 		clientCache:   clientCache,
 		docCache:      docCache,
@@ -191,7 +186,9 @@ func (c *Client) Close() error {
 func (c *Client) InvalidateCache(cacheType types.CacheType, key string) {
 	switch cacheType {
 	case types.CacheTypeProject:
-		c.projectCache.Remove(key)
+		if id := types.ID(key); id.Validate() == nil {
+			c.projectCache.Remove(id)
+		}
 	}
 }
 
@@ -566,7 +563,7 @@ func (c *Client) ListProjectInfos(
 
 // FindProjectInfoByPublicKey returns a project by public key.
 func (c *Client) FindProjectInfoByPublicKey(ctx context.Context, publicKey string) (*database.ProjectInfo, error) {
-	if cached, ok := c.projectCache.Get(publicKey); ok {
+	if cached, ok := c.projectCache.GetByAPIKey(publicKey); ok {
 		return cached.DeepCopy(), nil
 	}
 
@@ -583,7 +580,7 @@ func (c *Client) FindProjectInfoByPublicKey(ctx context.Context, publicKey strin
 		return nil, fmt.Errorf("find project by public key %s: %w", publicKey, err)
 	}
 
-	c.projectCache.Add(publicKey, info.DeepCopy())
+	c.projectCache.Add(info)
 
 	return info, nil
 }
@@ -631,6 +628,10 @@ func (c *Client) FindProjectInfoByName(
 
 // FindProjectInfoByID returns a project by the given id.
 func (c *Client) FindProjectInfoByID(ctx context.Context, id types.ID) (*database.ProjectInfo, error) {
+	if cached, ok := c.projectCache.GetByID(id); ok {
+		return cached.DeepCopy(), nil
+	}
+
 	result := c.collection(ColProjects).FindOne(ctx, bson.M{
 		"_id": id,
 	})
@@ -643,6 +644,8 @@ func (c *Client) FindProjectInfoByID(ctx context.Context, id types.ID) (*databas
 		return nil, fmt.Errorf("find project by id %s: %w", id, err)
 	}
 
+	c.projectCache.Add(info)
+
 	return info, nil
 }
 
@@ -682,6 +685,8 @@ func (c *Client) UpdateProjectInfo(
 		return nil, fmt.Errorf("decode project: %w", err)
 	}
 
+	c.projectCache.Remove(info.ID)
+
 	return info, nil
 }
 
@@ -697,7 +702,7 @@ func (c *Client) RotateProjectKeys(
 	prevInfo := &database.ProjectInfo{}
 	res := c.collection(ColProjects).FindOne(ctx, bson.M{"_id": id, "owner": owner})
 	if err := res.Decode(prevInfo); err == nil {
-		c.projectCache.Remove(prevInfo.PublicKey)
+		c.projectCache.Remove(prevInfo.ID)
 	}
 
 	res = c.collection(ColProjects).FindOneAndUpdate(ctx, bson.M{

server/backend/database/mongo/project_cache.go

@@ -0,0 +1,135 @@
+/*
+ * Copyright 2025 The Yorkie Authors. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package mongo
+
+import (
+	"sync"
+	"time"
+
+	"github.com/yorkie-team/yorkie/api/types"
+	"github.com/yorkie-team/yorkie/pkg/cache"
+	"github.com/yorkie-team/yorkie/server/backend/database"
+)
+
+// ProjectCache is a cache for project information with multiple access paths.
+// It uses a single LRU cache with ID as the primary key and maintains a
+// secondary index for API key lookups to minimize memory usage and ensure
+// cache consistency.
+type ProjectCache struct {
+	// Primary cache: ID is the primary key
+	cache *cache.LRUWithExpires[types.ID, *database.ProjectInfo]
+
+	// Secondary index: API key -> ID mapping
+	apiKeyToID sync.Map // map[string]types.ID
+}
+
+// NewProjectCache creates a new project cache with the given size and TTL.
+func NewProjectCache(size int, ttl time.Duration) (*ProjectCache, error) {
+	pc := &ProjectCache{
+		apiKeyToID: sync.Map{},
+	}
+
+	// Create cache with eviction callback to clean up secondary index
+	onEvict := func(id types.ID, info *database.ProjectInfo) {
+		// When an entry is evicted from primary cache (by TTL or LRU),
+		// remove it from the secondary index as well
+		pc.apiKeyToID.Delete(info.PublicKey)
+	}
+
+	c, err := cache.NewLRUWithExpires[types.ID, *database.ProjectInfo](
+		size,
+		ttl,
+		"project",
+		onEvict,
+	)
+	if err != nil {
+		return nil, err
+	}
+
+	pc.cache = c
+	return pc, nil
+}
+
+// Name returns the cache name.
+func (pc *ProjectCache) Name() string {
+	return pc.cache.Name()
+}
+
+// Stats returns the cache statistics.
+func (pc *ProjectCache) Stats() *cache.Stats {
+	return pc.cache.Stats()
+}
+
+// Len returns the number of items in the cache.
+func (pc *ProjectCache) Len() int {
+	return pc.cache.Len()
+}
+
+// GetByAPIKey retrieves a project by API key.
+func (pc *ProjectCache) GetByAPIKey(apiKey string) (*database.ProjectInfo, bool) {
+	// Look up ID from secondary index
+	idVal, ok := pc.apiKeyToID.Load(apiKey)
+	if !ok {
+		return nil, false
+	}
+
+	id := idVal.(types.ID)
+
+	// Get from primary cache
+	info, found := pc.cache.Get(id)
+	if !found {
+		// Primary cache entry was evicted but secondary index still exists
+		// Clean up the stale secondary index entry
+		pc.apiKeyToID.Delete(apiKey)
+		return nil, false
+	}
+
+	return info, true
+}
+
+// GetByID retrieves a project by ID.
+func (pc *ProjectCache) GetByID(id types.ID) (*database.ProjectInfo, bool) {
+	return pc.cache.Get(id)
+}
+
+// Add adds a project to the cache.
+func (pc *ProjectCache) Add(info *database.ProjectInfo) {
+	project := info.DeepCopy()
+
+	// Add to primary cache
+	pc.cache.Add(info.ID, project)
+
+	// Update secondary index
+	pc.apiKeyToID.Store(info.PublicKey, info.ID)
+}
+
+// Remove removes a project from the cache using both API key and ID.
+func (pc *ProjectCache) Remove(id types.ID) {
+	if info, ok := pc.cache.Peek(id); ok {
+		pc.apiKeyToID.Delete(info.PublicKey)
+	}
+	pc.cache.Remove(id)
+}
+
+// Purge removes all entries from the cache.
+func (pc *ProjectCache) Purge() {
+	pc.cache.Purge()
+	pc.apiKeyToID.Range(func(key, _ any) bool {
+		pc.apiKeyToID.Delete(key)
+		return true
+	})
+}

server/rpc/admin_server.go

@@ -239,7 +239,7 @@ func (s *adminServer) UpdateProject(
 	if err := s.backend.BroadcastCacheInvalidation(
 		ctx,
 		types.CacheTypeProject,
-		project.PublicKey,
+		project.ID.String(),
 	); err != nil {
 		logging.From(ctx).Warnf("failed to broadcast cache invalidation: %v", err)
 	}
@@ -817,7 +817,7 @@ func (s *adminServer) RotateProjectKeys(
 	if err := s.backend.BroadcastCacheInvalidation(
 		ctx,
 		types.CacheTypeProject,
-		prev.PublicKey,
+		prev.ID.String(),
 	); err != nil {
 		logging.From(ctx).Warnf("failed to broadcast cache invalidation: %v", err)
 	}