feat: add framework-agnostic googleapis caching layer to prevent rate limiting

[devin-ai-integration]

Framework-Agnostic Google APIs Caching Layer

🎯 Overview

This PR implements a comprehensive framework-agnostic caching layer for Google Calendar API calls to prevent rate limit quota exhaustion. The solution integrates at the CalendarAuth level to intercept all googleapis calls across both Next.js and Nest.js frameworks without requiring framework detection.

🏗️ Architecture

Core Components

• GoogleApiCache: Request signature-based caching with configurable time windows (default: 30s)
• CacheClient Abstraction: Framework-specific implementations
  • EdgeCacheClient: Uses Next.js unstable_cache for server-side caching
  • RedisCacheClient: Leverages existing Redis infrastructure for Nest.js
  • NoOpCacheClient: Fallback for scenarios where caching is disabled
• CachedCalendarClient: Wrapper for calendar_v3.Calendar with selective caching
• CachedFetchManager: Central manager for request deduplication

Integration Points

• CalendarAuth Level: Transparent API call interception without modifying existing flow
• Explicit Dependency Injection: Cache client type determined at handleNewBooking invocation level
• No Framework Detection: Manual cache client selection in Next.js API routes and Nest.js modules

🎯 Targeted API Methods

The caching layer focuses on read operations that commonly cause rate limiting:

• calendar.events.list - Event listing queries
• calendar.events.get - Individual event retrieval
• calendar.events.instances - Recurring event instances
• calendar.freebusy.query - Availability checking
• calendar.calendarList.list - Calendar enumeration

Write operations (insert, update, delete) bypass caching to prevent data consistency issues.

🔧 Implementation Details

Request Signature Generation

• SHA-256 hash of method + normalized parameters
• Removes timestamp-sensitive fields (requestId, quotaUser)
• Sorts object keys for consistent hashing
• Per-credential isolation to prevent data leakage

Cache Management

• Automatic cleanup of expired entries
• Configurable cache window (default: 30 seconds)
• Maximum cache size limits (default: 1000 entries per credential)
• Comprehensive logging for monitoring and debugging

🚀 Integration Examples

Next.js API Route

// apps/web/pages/api/book/event.ts
import { GoogleApiCacheFactory } from "@calcom/app-store/_utils/googleapis";

const cacheClient = GoogleApiCacheFactory.createEdgeCacheClient();
const result = await handleNewBooking({ 
  ...bookingData, 
  cacheClient 
});

Nest.js Module

// apps/api/v2/src/ee/bookings/2024-08-13/bookings.module.ts
@Module({
  providers: [
    {
      provide: 'CACHE_CLIENT',
      useFactory: () => GoogleApiCacheFactory.createRedisCacheClient(),
    },
  ],
})

📊 Benefits

• Rate Limit Prevention: Eliminates duplicate API calls within configurable time windows
• Performance Improvement: Cached responses reduce API latency
• Framework Agnostic: Works identically in Next.js and Nest.js contexts
• Minimal Disruption: Integrates transparently with existing booking flow
• Security: Per-credential cache isolation prevents data leakage
• Monitoring: Comprehensive logging and cache statistics

🧪 Testing

• Type Safety: All TypeScript compilation passes (yarn type-check:ci)
• Request Deduplication: Identical API calls within cache window return cached responses
• Parameter Normalization: Different parameter order produces same cache key
• Write Operation Bypass: Insert/update/delete operations skip caching
• Cache Expiration: Entries automatically expire after configured time window

📚 Documentation

Comprehensive documentation included:

• ARCHITECTURE.md: System design and component relationships
• INTEGRATION.md: Framework-specific integration guides
• DEPLOYMENT.md: Production deployment considerations
• TESTING.md: Testing strategies and verification steps

🔗 Related

• Addresses rate limiting issues in Google Calendar API integration
• Complements existing CalendarCache system without interference
• Maintains compatibility with current OAuthManager and authentication flows

🎉 Link to Devin run

https://app.devin.ai/sessions/37cfda9d9abb43f8a2ee493f50d87417

Requested by: zomars@cal.com

---

Summary by cubic

Added a framework-agnostic caching layer for Google Calendar API calls to prevent rate limiting, with support for both Next.js and Nest.js through explicit cache client injection.

• New Features
  • Caches read operations like events.list, events.get, and freebusy.query using a request signature-based cache with a default 30-second window.
  • Integrates at the CalendarAuth level for transparent API call interception without changing existing flows.
  • Supports both Next.js (edge cache) and Nest.js (Redis) environments without framework detection.
  • Includes per-credential cache isolation, automatic cleanup, and detailed logging.
  • Adds documentation and testing guides for integration and deployment.

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR that start with 'DevinAI'.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

2 Skipped Deployments

Name	Status	Preview	Comments	Updated (UTC)
cal-eu	⬜️ Ignored (Inspect)	Visit Preview		Jun 23, 2025 6:28pm
cal	⬜️ Skipped (Inspect)			Jun 23, 2025 6:28pm

[github-actions]

E2E results are ready!

• Workflow #64304.1 latest results

[devin-ai-integration]

Closing due to inactivity for more than 7 days. Configure here.