caching.yaml

# Caching Code Review Guidelines
# Comprehensive rules for caching strategies, invalidation, and best practices

description: Caching best practices for cache strategies, invalidation, distributed caching, and HTTP caching
globs:
  - "**/*.py"
  - "**/*.java"
  - "**/*.ts"
  - "**/*.js"
  - "**/*.go"
  - "**/*.rb"
  - "**/*cache*"
  - "**/*redis*"
  - "**/*memcache*"
  - "**/*.rs"
  - "**/*.cs"

rules:
  # Cache Strategy Rules
  - name: use-cache-aside-pattern
    description: >
      Cache-aside (lazy loading) reads from cache first, loads from DB on miss, then populates cache.
      Application manages cache population. Best for read-heavy workloads where stale data is acceptable.
      Always set TTL to prevent indefinite stale data. Handle cache failures gracefully by falling back to DB.
    severity: medium

  - name: use-write-through-for-consistency
    description: >
      Write-through writes to both cache and database synchronously. Ensures cache consistency but
      increases write latency. Use for data that's frequently read after write. Consider async
      write-behind if write latency is critical but some data loss risk is acceptable.
    severity: medium

  - name: use-write-behind-carefully
    description: >
      Write-behind (write-back) queues writes and flushes to database asynchronously. Reduces write
      latency but risks data loss on failures. Use only when eventual consistency is acceptable.
      Implement proper durability guarantees for the write queue. Monitor queue depth and flush failures.
    severity: high

  - name: implement-read-through-caching
    description: >
      Read-through cache handles data fetching transparently - the cache itself loads data on miss.
      Simplifies application code but requires cache library support. Combine with TTL-based
      expiration. Ensure proper error handling for data source failures during cache population.
    severity: low

  # Cache Invalidation Rules
  - name: set-appropriate-ttl
    description: >
      Always set TTL (time-to-live) on cached data to prevent indefinite staleness. Choose TTL
      based on data volatility and staleness tolerance. Shorter TTLs for frequently changing data,
      longer for stable data. Never cache without TTL unless explicitly managing invalidation.
    severity: high

  - name: implement-event-driven-invalidation
    description: >
      Use event-driven cache invalidation for immediate consistency needs. Publish invalidation
      events on data changes. Consider using message queues for reliable delivery. Combine with
      TTL as a fallback. Handle out-of-order events and duplicate deliveries gracefully.
    severity: medium

  - name: prevent-cache-stampede
    description: >
      Cache stampede occurs when many requests hit DB simultaneously after cache expiration.
      Implement mitigation strategies: probabilistic early expiration, locking/mutex during refresh,
      background refresh before expiration, or request coalescing. Critical for high-traffic systems.
    severity: high

  - name: implement-stale-while-revalidate
    description: >
      Stale-while-revalidate serves stale data while refreshing cache in background. Improves
      latency at cost of serving slightly outdated data. Set appropriate stale window. Use for
      data where freshness is less critical than availability and response time.
    severity: medium

  # Cache Key Design Rules
  - name: design-cache-keys-carefully
    description: >
      Design cache keys to be unique, predictable, and debuggable. Include entity type, identifier,
      and version. Avoid special characters that may cause issues. Use namespacing to prevent
      collisions. Keep keys reasonably short to minimize memory overhead. Document key patterns.
    severity: medium

  - name: version-cache-keys
    description: >
      Include version in cache keys when data schema changes. This prevents deserializing old
      format data after deployments. Use format like "user:v2:{id}". Allows gradual migration
      without cache flush. Consider automatic cache warming for new versions.
    severity: medium

  - name: namespace-cache-keys
    description: >
      Use namespacing to organize cache keys and prevent collisions between different services
      or features. Format like "service:feature:entity:{id}". Enables easy bulk invalidation
      by namespace. Facilitates monitoring and debugging. Document namespace conventions.
    severity: low

  # Distributed Caching Rules
  - name: handle-distributed-cache-consistency
    description: >
      In distributed caches, handle eventual consistency. Use CAS (check-and-set) operations
      for conditional updates. Be aware of race conditions between nodes. Consider using
      consistent hashing for key distribution. Monitor replication lag in clustered setups.
    severity: high

  - name: use-proper-serialization
    description: >
      Choose appropriate serialization for cached data. JSON for interoperability, Protocol
      Buffers or MessagePack for performance. Consider schema evolution and backward
      compatibility. Be aware of serialization overhead for complex objects. Compress large values.
    severity: medium

  - name: implement-cache-failover
    description: >
      Handle cache failures gracefully. Implement circuit breakers to prevent cascade failures.
      Fall back to database on cache unavailability. Use local cache as fallback for remote cache.
      Never let cache failures break application functionality. Log cache errors for monitoring.
    severity: high

  # HTTP Caching Rules
  - name: use-cache-control-headers
    description: >
      Set appropriate Cache-Control headers for HTTP responses. Use max-age for cacheable
      resources, no-store for sensitive data, must-revalidate for conditional caching.
      Understand public vs private caching. Consider CDN caching implications. Document caching strategy.
    severity: high

  - name: implement-etag-validation
    description: >
      Use ETag headers for efficient cache validation. Generate ETags from content hash or
      version. Handle If-None-Match requests, returning 304 Not Modified when appropriate.
      Strong ETags for byte-identical content, weak ETags for semantic equivalence.
    severity: medium

  - name: use-conditional-requests
    description: >
      Implement conditional requests with If-Modified-Since and If-None-Match headers.
      Reduces bandwidth by transferring only changed content. Essential for large resources.
      Properly handle 304 responses in clients. Use with appropriate validators (ETag, Last-Modified).
    severity: medium

  - name: set-vary-header-correctly
    description: >
      Set Vary header to indicate which request headers affect response caching. Common values:
      Accept-Encoding, Accept-Language, Authorization. Incorrect Vary causes cache pollution
      or incorrect cached responses. Be specific - Vary: * effectively disables caching.
    severity: medium

  # Common Pitfalls Rules
  - name: avoid-caching-user-specific-data-publicly
    description: >
      Never cache user-specific or sensitive data in public/shared caches. Use Cache-Control:
      private for user-specific responses. Include user identifier in cache keys for private
      caches. Audit cache contents regularly. Implement proper cache isolation.
    severity: critical

  - name: handle-stale-data-appropriately
    description: >
      Plan for stale data in cache. Define staleness tolerance for each data type. Implement
      refresh strategies. Communicate data freshness to users when relevant. Use stale-while-revalidate
      pattern where appropriate. Monitor cache hit rates and freshness metrics.
    severity: high

  - name: prevent-memory-pressure
    description: >
      Monitor cache memory usage and set appropriate limits. Implement eviction policies
      (LRU, LFU, TTL-based). Size cache based on working set, not total data size. Monitor
      eviction rates - high eviction indicates undersized cache. Consider tiered caching.
    severity: high

  - name: warm-cache-on-cold-start
    description: >
      Implement cache warming strategies for cold starts after deployments or failures.
      Pre-populate frequently accessed data. Use background jobs for warming. Implement
      gradual rollout to avoid thundering herd on cold cache. Monitor cold start latency.
    severity: medium

  - name: monitor-cache-metrics
    description: >
      Track cache hit rate, miss rate, latency, eviction rate, and memory usage. Set up
      alerts for anomalies. Low hit rate indicates ineffective caching or wrong data selection.
      High eviction rate indicates memory pressure. Use metrics to guide cache tuning.
    severity: medium

  - name: avoid-caching-negative-results
    description: >
      Be careful when caching negative results (not found, empty responses). Set shorter TTL
      for negative caches. Implement specific negative cache strategy. Avoid amplifying
      impact of missing data. Consider if negative caching is appropriate for your use case.
    severity: medium

  - name: invalidate-on-write-correctly
    description: >
      Ensure cache invalidation on data writes. Delete or update cached entries when source
      data changes. Use transactions to coordinate database write and cache invalidation.
      Consider eventual consistency if synchronous invalidation isn't feasible.
    severity: high