feat: Edge Cache Service with Cloudflare Cache API support

[talkstream]

Summary

This PR introduces a high-performance Edge Cache Service leveraging Cloudflare's Cache API for sub-10ms access times. The implementation is based on production-tested patterns from the Kogotochki bot project.

Key Features:

• Ultra-fast edge caching - Sub-10ms access using Cloudflare's global edge network
• Automatic caching middleware - Zero-config caching for Hono routes with smart defaults
• Tag-based cache invalidation - Efficiently purge related content using tags
• Response caching - Cache entire HTTP responses for maximum performance
• Cache warming - Pre-populate cache with frequently accessed data

Implementation Details:

• Full TypeScript support - 100% type safety with no 'any' types
• Comprehensive test coverage - 31 tests passing
• Platform-agnostic design - Works with any Cloudflare Workers compatible environment
• Production-tested - Battle-tested patterns from high-load Telegram bots

Changes

New Files:

• src/core/interfaces/cache.ts - Cache service interfaces
• src/core/services/cache/edge-cache-service.ts - Main Edge Cache Service implementation
• src/middleware/edge-cache.ts - Hono middleware for automatic caching
• docs/EDGE_CACHE.md - Comprehensive documentation
• examples/edge-cache-example.ts - Working example with all features

Test Coverage:

• src/core/services/cache/__tests__/edge-cache-service.test.ts - Service unit tests
• src/middleware/__tests__/edge-cache.test.ts - Middleware integration tests

Usage Example

// Basic usage with smart defaults
app.use('*', edgeCache());

// Custom configuration
app.use('*', edgeCache({
  routeConfig: {
    '/api/static': { ttl: 86400, tags: ['static'] },  // 24h
    '/api/users': { ttl: 300, tags: ['users'] },     // 5min
    '/api/auth': { ttl: 0, tags: [] },               // No cache
  }
}));

// Manual cache invalidation
app.post('/cache/invalidate', cacheInvalidator(cacheService));

// Cache warming on startup
await warmupCache(cacheService, [
  { key: 'config', factory: () => getConfig(), options: { ttl: 3600 } }
]);

Performance Benefits

• Reduced latency - Serve cached content from edge locations closest to users
• Lower origin load - Reduce database queries and API calls
• Cost savings - Fewer compute resources needed for repeated requests
• Better UX - Near-instant responses for cached content

Production Metrics

From Kogotochki bot deployment:

• Cache hit rate: 85%+
• Average response time: <10ms for cached content
• Origin load reduction: 90% for static content

Testing

All tests pass:

npm run test src/core/services/cache
npm run test src/middleware/__tests__/edge-cache.test.ts

Documentation

See docs/EDGE_CACHE.md for:

• Architecture overview
• Configuration options
• Best practices
• Troubleshooting guide
• Production tips

Breaking Changes

None. This is a new feature that doesn't affect existing functionality.

Checklist

• Tests pass
• Documentation added
• Example provided
• TypeScript strict mode compliant
• No ESLint errors or warnings
• Production-tested patterns