mcp-wordpress 1.1.7 → 1.2.2

package/docs/CACHING.md

@@ -0,0 +1,340 @@
+# Intelligent Caching System
+
+The WordPress MCP Server includes a comprehensive intelligent caching system that dramatically improves performance by reducing API calls and providing faster response times.
+
+## 🚀 **Performance Benefits**
+
+- **50-70% reduction** in taxonomy API calls (categories, tags)
+- **40-60% reduction** in authentication requests  
+- **30-50% reduction** in user profile lookups
+- **Significantly improved** response times for static data
+- **Better rate limit utilization** - 60 requests/minute becomes much more effective
+
+## 🏗️ **Architecture Overview**
+
+### **Multi-Layer Caching System**
+
+```
+Request → Cache Check → API Call (if miss) → Cache Store → Response
+     ↑                                              ↓
+     └── ETag Validation ← HTTP Headers ←──────────┘
+```
+
+**Layer 1: HTTP Response Cache**
+- ETags support for efficient revalidation
+- Cache-Control headers based on data volatility  
+- Conditional requests (If-None-Match)
+
+**Layer 2: In-Memory Application Cache**
+- TTL-based expiration by data type
+- LRU eviction for memory management
+- Site-specific cache keys for multi-site support
+
+**Layer 3: Intelligent Invalidation**
+- Event-based cache clearing on content changes
+- Pattern-based invalidation of related data
+- Cascading invalidation (e.g., post changes clear category counts)
+
+## 📊 **Cache Strategies by Data Type**
+
+### **Static Data (4 hour TTL)**
+- Site settings, user roles, capabilities
+- Cache-Control: `public, max-age=14400`
+- **Why**: Changes very rarely, safe to cache long-term
+
+### **Semi-Static Data (2 hour TTL)**  
+- Categories, tags, user profiles
+- Cache-Control: `public, max-age=7200`
+- **Why**: Changes occasionally but stable for hours
+
+### **Dynamic Data (15 minute TTL)**
+- Posts, pages, comments
+- Cache-Control: `public, max-age=900`  
+- **Why**: Content changes frequently, shorter cache needed
+
+### **Session Data (30 minute TTL)**
+- Authentication status, current user info
+- Cache-Control: `private, max-age=1800`
+- **Why**: User-specific data, moderate stability
+
+## 🛠️ **Cache Management Tools**
+
+The system includes dedicated cache management tools:
+
+### **wp_cache_stats**
+Get detailed cache statistics for performance monitoring.
+
+```bash
+wp_cache_stats --site="site1"
+```
+
+**Returns:**
+- Hit/miss rates
+- Total cache entries  
+- Eviction statistics
+- Invalidation queue status
+
+### **wp_cache_clear**
+Clear cache entries with optional pattern matching.
+
+```bash
+# Clear all cache
+wp_cache_clear --site="site1"
+
+# Clear specific patterns
+wp_cache_clear --site="site1" --pattern="posts"
+wp_cache_clear --site="site1" --pattern="categories"
+```
+
+### **wp_cache_warm**
+Pre-populate cache with essential WordPress data.
+
+```bash
+wp_cache_warm --site="site1"
+```
+
+Warms cache with:
+- Current user information
+- Categories and tags
+- Site settings
+
+### **wp_cache_info**
+Get detailed cache configuration and status.
+
+```bash
+wp_cache_info --site="site1"
+```
+
+## ⚙️ **Configuration**
+
+### **Enable/Disable Caching**
+
+Caching is **enabled by default**. To disable:
+
+```bash
+export DISABLE_CACHE=true
+```
+
+### **Cache Settings** 
+
+Configure via `SecurityConfig.cache` in `src/security/SecurityConfig.ts`:
+
+```typescript
+cache: {
+  enabled: true,
+  maxSize: 1000,           // Maximum cache entries
+  defaultTTL: 15 * 60 * 1000,  // 15 minutes default
+  enableLRU: true,
+  enableStats: true,
+  
+  // TTL presets by data type
+  ttlPresets: {
+    static: 4 * 60 * 60 * 1000,      // 4 hours
+    semiStatic: 2 * 60 * 60 * 1000,  // 2 hours  
+    dynamic: 15 * 60 * 1000,         // 15 minutes
+    session: 30 * 60 * 1000,         // 30 minutes
+    realtime: 60 * 1000              // 1 minute
+  }
+}
+```
+
+## 🔄 **Cache Invalidation**
+
+### **Automatic Invalidation Rules**
+
+The system automatically invalidates related cache entries when content changes:
+
+**Post Operations:**
+- **Create Post** → Clears posts listings, categories, tags, search
+- **Update Post** → Clears specific post, posts listings, search  
+- **Delete Post** → Clears posts listings, categories, tags, search
+
+**Category/Tag Operations:**
+- **Create/Update/Delete** → Clears taxonomies AND related posts
+- **Cascading Effect** → Post cache cleared when categories change
+
+**User Operations:**
+- **Update User** → Clears user cache, current user cache
+- **User Role Changes** → Clears capability-dependent caches
+
+### **Manual Invalidation**
+
+```bash
+# Clear specific patterns
+wp_cache_clear --pattern="posts.*"      # All post-related cache
+wp_cache_clear --pattern="categories"   # Category cache
+wp_cache_clear --pattern="users"        # User cache
+
+# Clear everything (nuclear option)
+wp_cache_clear
+```
+
+## 🧪 **Testing & Benchmarking**
+
+### **Run Cache Tests**
+
+```bash
+npm run build
+node scripts/test-caching.js
+```
+
+**Tests Include:**
+- Cache infrastructure performance
+- Memory usage analysis
+- Hit/miss rate calculations
+- Invalidation timing
+- Configuration validation
+
+### **Performance Monitoring**
+
+Monitor cache effectiveness:
+
+```bash
+# Check cache statistics
+wp_cache_stats --site="your-site"
+
+# Monitor hit rates over time
+while true; do
+  wp_cache_stats --site="your-site" | grep "hit_rate"
+  sleep 30
+done
+```
+
+### **Expected Performance Gains**
+
+**Before Caching:**
+- Categories API call: ~200-500ms
+- Repeated user lookups: ~150-300ms each
+- Site settings: ~100-200ms each call
+
+**After Caching:**
+- Categories (cached): ~1-5ms  
+- User lookups (cached): ~1-3ms
+- Site settings (cached): ~1-2ms
+
+## 🔐 **Multi-Site Support**
+
+Each WordPress site gets isolated cache:
+
+**Cache Key Format:**
+```
+{siteId}:{endpoint}:{params_hash}
+```
+
+**Examples:**
+```
+site1:posts:abc123        # Site 1 posts listing
+site2:posts:abc123        # Site 2 posts listing (separate)  
+site1:categories:def456   # Site 1 categories
+```
+
+**Site-Specific Operations:**
+```bash
+wp_cache_clear --site="site1"              # Clear only site1 cache
+wp_cache_clear --site="site2" --pattern="posts"  # Clear site2 posts only
+```
+
+## 🚨 **Troubleshooting**
+
+### **Cache Not Working**
+
+1. **Check if caching is enabled:**
+   ```bash
+   wp_cache_info --site="your-site"
+   ```
+
+2. **Verify no DISABLE_CACHE environment variable:**
+   ```bash
+   echo $DISABLE_CACHE  # Should be empty or 'false'
+   ```
+
+3. **Check cache statistics:**
+   ```bash
+   wp_cache_stats --site="your-site"
+   ```
+   - Hit rate should increase over time
+   - Total entries should grow with usage
+
+### **Poor Cache Performance**
+
+1. **Monitor hit rates:**
+   - Good: >60% hit rate after warm-up
+   - Poor: <30% hit rate indicates issues
+
+2. **Check TTL settings:**
+   - Too short: Frequent cache misses
+   - Too long: Stale data issues
+
+3. **Memory pressure:**
+   - LRU evictions happening too frequently
+   - Consider increasing `maxSize` in config
+
+### **Stale Data Issues**
+
+1. **Check invalidation:**
+   ```bash
+   wp_cache_info --site="your-site"
+   ```
+   - Verify invalidation rules are active
+   - Check queue processing status
+
+2. **Manual cache clear:**
+   ```bash
+   wp_cache_clear --site="your-site" --pattern="problematic_endpoint"
+   ```
+
+3. **Verify TTL appropriateness:**
+   - Static data: 4h is usually safe
+   - Dynamic content: Consider shorter TTL
+
+## 📈 **Optimization Tips**
+
+### **For High-Traffic Sites**
+
+1. **Increase cache size:**
+   ```typescript
+   maxSize: 2000  // From default 1000
+   ```
+
+2. **Tune TTL values:**
+   ```typescript
+   ttlPresets: {
+     static: 8 * 60 * 60 * 1000,      // 8 hours for very stable data
+     semiStatic: 4 * 60 * 60 * 1000,  // 4 hours
+     dynamic: 30 * 60 * 1000,         // 30 minutes for less active sites
+   }
+   ```
+
+3. **Pre-warm cache on deployment:**
+   ```bash
+   wp_cache_warm --site="production-site"
+   ```
+
+### **For Development**
+
+1. **Shorter TTL for faster iteration:**
+   ```typescript
+   ttlPresets: {
+     dynamic: 30 * 1000,  // 30 seconds for development
+   }
+   ```
+
+2. **Easy cache clearing:**
+   ```bash
+   # Add to development scripts
+   wp_cache_clear  # Clear all during development
+   ```
+
+## 🔮 **Future Enhancements**
+
+Planned improvements:
+
+- **Redis backend** for distributed caching
+- **Cache warming strategies** based on access patterns  
+- **Adaptive TTL** based on content change frequency
+- **Cache compression** for larger datasets
+- **Metrics dashboard** for cache performance visualization
+
+---
+
+The intelligent caching system provides significant performance improvements while maintaining data freshness appropriate for each content type. It's designed to work transparently with existing WordPress operations while providing tools for monitoring and management.