Caching

Overview

Caching improves performance by reducing database and network calls. This skill covers in-memory caching patterns suitable for desktop applications.

Definition of Done (DoD)

Frequently accessed data is cached appropriately
Cache has defined TTL (time-to-live) for each entry type
Cache invalidation is implemented for write operations
Memory usage is bounded (max entries or max memory)
Cache misses are logged for monitoring
Thread-safety is ensured for concurrent access

When to Cache

Scenario	Cache?	TTL	Notes
Widget catalog (read-heavy)	✅ Yes	5 min	Invalidate on install/uninstall
Installed widgets list	✅ Yes	10 min	Invalidate on changes
Layout configurations	✅ Yes	5 min	Invalidate on save
User preferences	✅ Yes	Session	Load once, cache for session
Active widget instances	❌ No	-	Already in memory
Real-time data (sync queue)	❌ No	-	Needs fresh data

Cache Service Implementation

Interface

public interface ICacheService
{
    /// <summary>Gets cached value or default if not found/expired.</summary>
    T? Get<T>(string key) where T : class;
    
    /// <summary>Gets cached value or executes factory to populate.</summary>
    Task<T> GetOrCreateAsync<T>(
        string key, 
        Func<CancellationToken, Task<T>> factory,
        TimeSpan? expiration = null,
        CancellationToken cancellationToken = default) where T : class;
    
    /// <summary>Sets value with optional expiration.</summary>
    void Set<T>(string key, T value, TimeSpan? expiration = null) where T : class;
    
    /// <summary>Removes specific key.</summary>
    void Remove(string key);
    
    /// <summary>Removes all keys matching prefix.</summary>
    void RemoveByPrefix(string prefix);
    
    /// <summary>Clears entire cache.</summary>
    void Clear();
    
    /// <summary>Gets cache statistics.</summary>
    CacheStatistics GetStatistics();
}

public record CacheStatistics(int EntryCount, long Hits, long Misses, long Evictions);

Implementation

public class MemoryCacheService : ICacheService, IDisposable
{
    private readonly ConcurrentDictionary<string, CacheEntry> _cache = new();
    private readonly Timer _cleanupTimer;
    private readonly int _maxEntries;
    
    private long _hits;
    private long _misses;
    private long _evictions;
    
    public MemoryCacheService(int maxEntries = 1000, TimeSpan? cleanupInterval = null)
    {
        _maxEntries = maxEntries;
        _cleanupTimer = new Timer(
            CleanupExpired, 
            null, 
            cleanupInterval ?? TimeSpan.FromMinutes(1),
            cleanupInterval ?? TimeSpan.FromMinutes(1));
    }
    
    public T? Get<T>(string key) where T : class
    {
        if (_cache.TryGetValue(key, out var entry) && !entry.IsExpired)
        {
            Interlocked.Increment(ref _hits);
            entry.Touch();
            return (T)entry.Value;
        }
        
        Interlocked.Increment(ref _misses);
        
        if (entry?.IsExpired == true)
        {
            _cache.TryRemove(key, out _);
        }
        
        return null;
    }
    
    public async Task<T> GetOrCreateAsync<T>(
        string key,
        Func<CancellationToken, Task<T>> factory,
        TimeSpan? expiration = null,
        CancellationToken cancellationToken = default) where T : class
    {
        var existing = Get<T>(key);
        if (existing != null)
            return existing;
        
        // Use lock to prevent duplicate factory calls
        var value = await factory(cancellationToken).ConfigureAwait(false);
        Set(key, value, expiration);
        return value;
    }
    
    public void Set<T>(string key, T value, TimeSpan? expiration = null) where T : class
    {
        EnsureCapacity();
        
        var entry = new CacheEntry(value, expiration);
        _cache[key] = entry;
        
        Log.Debug("Cache set: {Key}, Expires: {Expiration}", 
            key, entry.ExpiresAt?.ToString("HH:mm:ss") ?? "never");
    }
    
    public void Remove(string key)
    {
        if (_cache.TryRemove(key, out _))
        {
            Log.Debug("Cache removed: {Key}", key);
        }
    }
    
    public void RemoveByPrefix(string prefix)
    {
        var keysToRemove = _cache.Keys
            .Where(k => k.StartsWith(prefix, StringComparison.OrdinalIgnoreCase))
            .ToList();
        
        foreach (var key in keysToRemove)
        {
            _cache.TryRemove(key, out _);
        }
        
        Log.Debug("Cache cleared {Count} entries with prefix: {Prefix}", 
            keysToRemove.Count, prefix);
    }
    
    public void Clear()
    {
        var count = _cache.Count;
        _cache.Clear();
        Log.Information("Cache cleared: {Count} entries removed", count);
    }
    
    public CacheStatistics GetStatistics() => 
        new(_cache.Count, _hits, _misses, _evictions);
    
    private void EnsureCapacity()
    {
        if (_cache.Count < _maxEntries)
            return;
        
        // Evict oldest entries (LRU)
        var toEvict = _cache
            .OrderBy(x => x.Value.LastAccessed)
            .Take(_cache.Count / 4)  // Evict 25%
            .Select(x => x.Key)
            .ToList();
        
        foreach (var key in toEvict)
        {
            if (_cache.TryRemove(key, out _))
            {
                Interlocked.Increment(ref _evictions);
            }
        }
        
        Log.Debug("Cache evicted {Count} entries", toEvict.Count);
    }
    
    private void CleanupExpired(object? state)
    {
        var expired = _cache
            .Where(x => x.Value.IsExpired)
            .Select(x => x.Key)
            .ToList();
        
        foreach (var key in expired)
        {
            _cache.TryRemove(key, out _);
        }
        
        if (expired.Count > 0)
        {
            Log.Debug("Cache cleanup: {Count} expired entries removed", expired.Count);
        }
    }
    
    public void Dispose()
    {
        _cleanupTimer.Dispose();
    }
    
    private class CacheEntry
    {
        public object Value { get; }
        public DateTimeOffset? ExpiresAt { get; }
        public DateTimeOffset LastAccessed { get; private set; }
        public bool IsExpired => ExpiresAt.HasValue && DateTimeOffset.UtcNow > ExpiresAt;
        
        public CacheEntry(object value, TimeSpan? expiration)
        {
            Value = value;
            LastAccessed = DateTimeOffset.UtcNow;
            ExpiresAt = expiration.HasValue 
                ? DateTimeOffset.UtcNow.Add(expiration.Value) 
                : null;
        }
        
        public void Touch() => LastAccessed = DateTimeOffset.UtcNow;
    }
}

Cache Keys Convention

Use hierarchical keys for easy invalidation:

public static class CacheKeys
{
    // Pattern: {entity}:{scope}:{identifier}
    
    public const string WidgetCatalog = "widgets:catalog:all";
    public const string InstalledWidgets = "widgets:installed:all";
    
    public static string Widget(string widgetKey) => $"widgets:detail:{widgetKey}";
    public static string Layout(Guid layoutId) => $"layouts:detail:{layoutId}";
    public static string UserSettings(string key) => $"settings:user:{key}";
    
    // Prefixes for bulk invalidation
    public const string WidgetsPrefix = "widgets:";
    public const string LayoutsPrefix = "layouts:";
}

Repository with Caching

public class CachedWidgetRepository : IWidgetRepository
{
    private readonly IWidgetRepository _inner;
    private readonly ICacheService _cache;
    
    private static readonly TimeSpan CacheDuration = TimeSpan.FromMinutes(5);
    
    public CachedWidgetRepository(IWidgetRepository inner, ICacheService cache)
    {
        _inner = inner;
        _cache = cache;
    }
    
    public async Task<IReadOnlyList<Widget>> GetAllAsync(CancellationToken ct = default)
    {
        return await _cache.GetOrCreateAsync(
            CacheKeys.WidgetCatalog,
            async token => (await _inner.GetAllAsync(token)).ToList(),
            CacheDuration,
            ct);
    }
    
    public async Task<Widget?> GetByKeyAsync(string widgetKey, CancellationToken ct = default)
    {
        return await _cache.GetOrCreateAsync(
            CacheKeys.Widget(widgetKey),
            token => _inner.GetByKeyAsync(widgetKey, token),
            CacheDuration,
            ct);
    }
    
    public async Task AddAsync(Widget widget, CancellationToken ct = default)
    {
        await _inner.AddAsync(widget, ct);
        
        // Invalidate related caches
        _cache.Remove(CacheKeys.WidgetCatalog);
        _cache.Remove(CacheKeys.Widget(widget.WidgetKey));
    }
    
    public async Task UpdateAsync(Widget widget, CancellationToken ct = default)
    {
        await _inner.UpdateAsync(widget, ct);
        
        _cache.Remove(CacheKeys.Widget(widget.WidgetKey));
        _cache.Remove(CacheKeys.WidgetCatalog);
    }
    
    public async Task DeleteAsync(string widgetKey, CancellationToken ct = default)
    {
        await _inner.DeleteAsync(widgetKey, ct);
        
        _cache.RemoveByPrefix(CacheKeys.WidgetsPrefix);
    }
}

Cache-Aside Pattern

For more control over cache population:

public async Task<Widget?> GetWidgetAsync(string widgetKey, CancellationToken ct)
{
    // 1. Check cache
    var cached = _cache.Get<Widget>(CacheKeys.Widget(widgetKey));
    if (cached != null)
        return cached;
    
    // 2. Load from database
    var widget = await _repository.GetByKeyAsync(widgetKey, ct);
    
    // 3. Populate cache (even if null, to prevent repeated lookups)
    if (widget != null)
    {
        _cache.Set(CacheKeys.Widget(widgetKey), widget, TimeSpan.FromMinutes(5));
    }
    
    return widget;
}

Cache Warming

Pre-populate cache at startup:

public class CacheWarmupService
{
    private readonly ICacheService _cache;
    private readonly IWidgetRepository _widgetRepo;
    private readonly ILayoutRepository _layoutRepo;
    
    public async Task WarmupAsync(CancellationToken ct)
    {
        Log.Information("Starting cache warmup");
        
        var tasks = new[]
        {
            WarmWidgetsAsync(ct),
            WarmLayoutsAsync(ct)
        };
        
        await Task.WhenAll(tasks);
        
        var stats = _cache.GetStatistics();
        Log.Information("Cache warmup complete: {Count} entries", stats.EntryCount);
    }
    
    private async Task WarmWidgetsAsync(CancellationToken ct)
    {
        var widgets = await _widgetRepo.GetAllAsync(ct);
        _cache.Set(CacheKeys.WidgetCatalog, widgets.ToList(), TimeSpan.FromMinutes(10));
        
        foreach (var widget in widgets)
        {
            _cache.Set(CacheKeys.Widget(widget.WidgetKey), widget, TimeSpan.FromMinutes(10));
        }
    }
    
    private async Task WarmLayoutsAsync(CancellationToken ct)
    {
        // Similar pattern...
    }
}

Best Practices

Practice	Reason
Always set TTL	Prevents stale data and memory leaks
Invalidate on writes	Ensures cache consistency
Use hierarchical keys	Enables prefix-based invalidation
Bound cache size	Prevents unbounded memory growth
Log cache metrics	Helps tune cache effectiveness
Don't cache nulls (usually)	Unless preventing repeated lookups

Anti-Patterns

Anti-Pattern	Problem	Solution
Unbounded cache	Memory leak	Set max entries
No TTL	Stale data forever	Always set expiration
Cache complex graphs	Inconsistent updates	Cache simple DTOs
Distributed cache for desktop	Over-engineering	Use simple in-memory
Caching mutable objects	Race conditions	Cache immutable/copies

Monitoring

// Log cache effectiveness periodically
public void LogCacheMetrics()
{
    var stats = _cache.GetStatistics();
    var hitRate = stats.Hits + stats.Misses > 0 
        ? (double)stats.Hits / (stats.Hits + stats.Misses) * 100 
        : 0;
    
    Log.Information(
        "Cache metrics - Entries: {Entries}, HitRate: {HitRate:F1}%, " +
        "Hits: {Hits}, Misses: {Misses}, Evictions: {Evictions}",
        stats.EntryCount, hitRate, stats.Hits, stats.Misses, stats.Evictions);
}

caching

SKILL.md

name: caching description: In-memory caching patterns for the 3SC widget host. Covers cache strategies, invalidation, TTL policies, and when to cache vs when to fetch.