cloud-server/src/services/cache.manual-test.md

/**

• Manual Test Instructions for CacheService
• Since Cloudflare Workers Cache API is only available in the Workers runtime,
• these tests must be run in a Cloudflare Workers environment or using Miniflare.
• Test 1: Basic Cache Operations

• ---

• 1. Deploy to Cloudflare Workers development environment
• 2. Initialize cache: const cache = new CacheService(300);
• 3. Set data: await cache.set('test-key', { foo: 'bar' }, 60);
• 4. Get data: const result = await cache.get('test-key');
• 5. Expected: result.data.foo === 'bar', cache_age_seconds ≈ 0
• Test 2: Cache Key Generation

• ---

• 1. Generate key: const key = cache.generateKey({ provider: 'linode', region: 'us-east' });
• 2. Expected: key === 'https://cache.internal/instances?provider=linode&region=us-east'
• 3. Verify sorting: cache.generateKey({ z: 1, a: 2 }) should have 'a' before 'z'
• Test 3: Cache Miss

• ---

• 1. Request non-existent key: const result = await cache.get('non-existent');
• 2. Expected: result === null
• Test 4: Cache Expiration

• ---

• 1. Set with short TTL: await cache.set('expire-test', { data: 'test' }, 2);
• 2. Immediate get: await cache.get('expire-test') → should return data
• 3. Wait 3 seconds
• 4. Get again: await cache.get('expire-test') → should return null (expired)
• Test 5: Cache Age Tracking

• ---

• 1. Set data: await cache.set('age-test', { data: 'test' }, 300);
• 2. Wait 5 seconds
• 3. Get data: const result = await cache.get('age-test');
• 4. Expected: result.cache_age_seconds ≈ 5
• Test 6: Cache Deletion

• ---

• 1. Set data: await cache.set('delete-test', { data: 'test' }, 300);
• 2. Delete: const deleted = await cache.delete('delete-test');
• 3. Expected: deleted === true
• 4. Get data: const result = await cache.get('delete-test');
• 5. Expected: result === null
• Test 7: Error Handling (Graceful Degradation)

• ---

• 1. Test with invalid cache response (manual mock required)
• 2. Expected: No errors thrown, graceful null return
• 3. Verify logs show error message
• Test 8: Integration with Instance API

• ---

• 1. Create cache instance in instance endpoint handler
• 2. Generate key from query params: cache.generateKey(query)
• 3. Check cache: const cached = await cache.get<InstanceData[]>(key);
• 4. If cache hit: return cached.data with cache metadata
• 5. If cache miss: fetch from database, cache result, return data
• 6. Verify cache hit on second request
• Performance Validation:

• ---

• 1. Measure database query time (first request)
• 2. Measure cache hit time (second request)
• 3. Expected: Cache hit 10-50x faster than database query
• 4. Verify cache age increases on subsequent requests
• TTL Strategy Validation:

• ---

• Filtered queries (5 min TTL):
• • cache.set(key, data, 300)
• • Verify expires after 5 minutes
• Full dataset (1 hour TTL):
• • cache.set(key, data, 3600)
• • Verify expires after 1 hour
• Post-sync invalidation:
• • After sync operation, call cache.delete(key) for all relevant keys
• • Verify next request fetches fresh data from database */

import { CacheService } from './cache'; import type { InstanceData } from '../types';

/**

• Example: Using CacheService in API endpoint */ async function exampleInstanceEndpointWithCache( queryParams: Record<string, unknown>, fetchFromDatabase: () => Promise<InstanceData[]> ): Promise<{ data: InstanceData[]; cached?: boolean; cache_age?: number }> { const cache = new CacheService(300); // 5 minutes default TTL

// Generate cache key from query parameters const cacheKey = cache.generateKey(queryParams);

// Try to get from cache const cached = await cache.get<InstanceData[]>(cacheKey);

if (cached) { console.log([API] Cache hit (age: ${cached.cache_age_seconds}s)); return { data: cached.data, cached: true, cache_age: cached.cache_age_seconds, }; }

// Cache miss - fetch from database console.log('[API] Cache miss - fetching from database'); const data = await fetchFromDatabase();

// Determine TTL based on query complexity const hasFilters = Object.keys(queryParams).length > 0; const ttl = hasFilters ? 300 : 3600; // 5 min for filtered, 1 hour for full

// Store in cache await cache.set(cacheKey, data, ttl);

return { data, cached: false, }; }

/**

• Example: Cache invalidation after sync */ async function exampleCacheInvalidationAfterSync( syncedProviders: string[] ): Promise { const cache = new CacheService();

// Invalidate all instance caches for synced providers for (const provider of syncedProviders) { // Note: Since Cloudflare Workers Cache API doesn't support pattern matching, // you need to maintain a list of active cache keys or use KV for indexing const key = cache.generateKey({ provider }); await cache.delete(key); console.log([Sync] Invalidated cache for provider: ${provider}); }

console.log('[Sync] Cache invalidation complete'); }

export { exampleInstanceEndpointWithCache, exampleCacheInvalidationAfterSync };