Documentation
¶
Overview ¶
Package cache provides response caching for MCP tools
Index ¶
- type Cache
- type CacheStats
- type Config
- type Entry
- type KeyGenerator
- type MemoryCache
- func (c *MemoryCache) CleanExpired() int
- func (c *MemoryCache) Clear(ctx context.Context) error
- func (c *MemoryCache) Close() error
- func (c *MemoryCache) Delete(ctx context.Context, key string) error
- func (c *MemoryCache) Get(ctx context.Context, key string) (*Entry, error)
- func (c *MemoryCache) Len() int
- func (c *MemoryCache) Set(ctx context.Context, key string, value json.RawMessage, ttl time.Duration) error
- func (c *MemoryCache) Stats() CacheStats
- type NoOpCache
- func (c *NoOpCache) Clear(ctx context.Context) error
- func (c *NoOpCache) Close() error
- func (c *NoOpCache) Delete(ctx context.Context, key string) error
- func (c *NoOpCache) Get(ctx context.Context, key string) (*Entry, error)
- func (c *NoOpCache) Set(ctx context.Context, key string, value json.RawMessage, ttl time.Duration) error
- func (c *NoOpCache) Stats() CacheStats
- type Type
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Cache ¶
type Cache interface {
// Get retrieves a cached response
// Returns error if key not found or entry expired
Get(ctx context.Context, key string) (*Entry, error)
// Set stores a response in the cache
// value MUST be JSON-serializable (json.RawMessage)
Set(ctx context.Context, key string, value json.RawMessage, ttl time.Duration) error
// Delete removes a cached entry
// Returns error if key not found
Delete(ctx context.Context, key string) error
// Clear removes all cached entries
Clear(ctx context.Context) error
// Stats returns cache statistics
Stats() CacheStats
// Close closes the cache and releases resources
Close() error
}
Cache defines the interface for response caching All implementations must be thread-safe
type CacheStats ¶
type CacheStats struct {
Hits int64 `json:"hits"` // Total cache hits
Misses int64 `json:"misses"` // Total cache misses
Sets int64 `json:"sets"` // Total set operations
Deletes int64 `json:"deletes"` // Total delete operations
Evictions int64 `json:"evictions"` // Total evictions (LRU/TTL)
Size int `json:"size"` // Current number of entries
MaxSize int `json:"max_size"` // Maximum capacity
HitRate float64 `json:"hit_rate"` // Hit rate (hits / (hits + misses))
}
CacheStats holds cache statistics
type Config ¶
type Config struct {
// Type of cache ("short" or "long")
Type Type `json:"type" yaml:"type"`
// TTL is the time to live for cached entries
// For TypeShort: seconds
// For TypeLong: minutes
TTL int `json:"ttl" yaml:"ttl"`
// MaxSize is the maximum number of entries (for memory cache)
// Ignored for file-based cache
MaxSize int `json:"max_size" yaml:"max_size"`
// Directory for file-based cache
// Ignored for memory cache
Directory string `json:"directory" yaml:"directory"`
// Enabled enables/disables caching globally
// Default: false (SAFE DEFAULT - must opt-in)
// This is intentional for safety - caching is disabled by default
Enabled bool `json:"enabled" yaml:"enabled"`
// ToolTTL provides per-tool TTL overrides
// Key: tool name, Value: TTL duration
ToolTTL map[string]time.Duration `json:"tool_ttl,omitempty" yaml:"tool_ttl,omitempty"`
}
Config holds cache configuration
func DefaultConfig ¶
func DefaultConfig() *Config
DefaultConfig returns the default cache configuration Cache is DISABLED by default for safety Tools must explicitly opt-in to caching
func (*Config) GetTTLDuration ¶
GetTTLDuration returns the default TTL as a time.Duration
func (*Config) GetToolTTL ¶
GetToolTTL returns TTL for a specific tool Returns default TTL if no override exists
func (*Config) SetToolTTL ¶
SetToolTTL sets a TTL override for a specific tool
type Entry ¶
type Entry struct {
Key string `json:"key"` // Cache key (SHA-256 hash)
Value json.RawMessage `json:"value"` // Cached JSON response
ExpiresAt time.Time `json:"expires_at"` // Expiration timestamp
CreatedAt time.Time `json:"created_at"` // Creation timestamp
Hits int64 `json:"hits"` // Number of cache hits
}
Entry represents a cached item Uses json.RawMessage to ensure JSON-safe storage
type KeyGenerator ¶
type KeyGenerator struct{}
KeyGenerator generates deterministic cache keys CRITICAL: Keys must be deterministic - same logical input = same key This prevents cache misses due to Go's random map iteration order
func NewKeyGenerator ¶
func NewKeyGenerator() *KeyGenerator
NewKeyGenerator creates a new key generator
func (*KeyGenerator) Generate ¶
func (kg *KeyGenerator) Generate(toolName string, args map[string]interface{}) (string, error)
Generate generates a cache key from tool name and arguments Uses SHA-256 hash of canonicalized JSON
CRITICAL FIX: Arguments are normalized before hashing to ensure deterministic keys regardless of map iteration order
Example:
args1 := {"b": 2, "a": 1} // Random order
args2 := {"a": 1, "b": 2} // Different order
Generate("tool", args1) == Generate("tool", args2) // ✅ Same key!
func (*KeyGenerator) GenerateSimple ¶
func (kg *KeyGenerator) GenerateSimple(toolName string) string
GenerateSimple generates a simple cache key without arguments Useful for testing or tools with no parameters
type MemoryCache ¶
type MemoryCache struct {
// contains filtered or unexported fields
}
MemoryCache implements an in-memory LRU cache with TTL support Thread-safe with O(1) get/set operations
Architecture:
map[string]*list.Element → O(1) lookup by key doubly-linked list → O(1) LRU eviction [Front = MRU] ← → ← → [Back = LRU]
On Get: Move to front (most recently used) On Set: Add to front, evict from back if full
func NewMemoryCache ¶
func NewMemoryCache(maxSize int, ttl time.Duration) *MemoryCache
NewMemoryCache creates a new in-memory cache
func (*MemoryCache) CleanExpired ¶
func (c *MemoryCache) CleanExpired() int
CleanExpired removes all expired entries Returns the number of entries removed
func (*MemoryCache) Clear ¶
func (c *MemoryCache) Clear(ctx context.Context) error
Clear removes all entries
func (*MemoryCache) Close ¶
func (c *MemoryCache) Close() error
Close closes the cache (clears all entries)
func (*MemoryCache) Delete ¶
func (c *MemoryCache) Delete(ctx context.Context, key string) error
Delete removes an entry from the cache
func (*MemoryCache) Get ¶
Get retrieves a cached entry Returns error if key not found or entry expired
type NoOpCache ¶
type NoOpCache struct {
// contains filtered or unexported fields
}
NoOpCache is a cache implementation that does nothing Used when caching is disabled
Source Files