feat: implement comprehensive caching to prevent 504 timeouts

- Add configurable cache TTL system with environment-aware defaults
- Implement dynamic TTL based on data type (profile: 60m, music: 10m, identity: 24h)
- Add HTTP Cache-Control headers for browser and CDN caching
- Cache identity resolution to reduce Slingshot API calls
- Add stale-while-revalidate for graceful cache updates
- Update environment configuration with optional cache TTL overrides

Fixes 504 Gateway Timeout errors by reducing AT Protocol API calls
and serving cached responses. All cache durations are configurable
via environment variables while maintaining DRY principles.

.env.example

···
 # Use "*" to allow all origins (not recommended for production)
 # Example: https://example.com,https://app.example.com
 PUBLIC_CORS_ALLOWED_ORIGINS="https://your-site-url.com"
+
+# Cache TTL Configuration (optional)
+# Configure how long different types of data are cached (in minutes)
+# Longer TTLs reduce API calls and prevent timeouts, but data may be less fresh
+# Leave empty to use defaults (optimized for production)
+# Profile data (default: 5 min dev, 60 min prod)
+# CACHE_TTL_PROFILE=60
+# Site info (default: 5 min dev, 120 min prod)
+# CACHE_TTL_SITE_INFO=120
+# Links (default: 5 min dev, 60 min prod)
+# CACHE_TTL_LINKS=60
+# Music status (default: 2 min dev, 10 min prod)
+# CACHE_TTL_MUSIC_STATUS=10
+# Kibun status (default: 2 min dev, 15 min prod)
+# CACHE_TTL_KIBUN_STATUS=15
+# Tangled repos (default: 5 min dev, 60 min prod)
+# CACHE_TTL_TANGLED_REPOS=60
+# Blog posts (default: 5 min dev, 30 min prod)
+# CACHE_TTL_BLOG_POSTS=30
+# Publications (default: 5 min dev, 60 min prod)
+# CACHE_TTL_PUBLICATIONS=60
+# Individual posts (default: 5 min dev, 60 min prod)
+# CACHE_TTL_INDIVIDUAL_POST=60
+# Identity resolution (default: 30 min dev, 1440 min/24h prod)
+# CACHE_TTL_IDENTITY=1440

src/hooks.server.ts

···
 import type { Handle } from '@sveltejs/kit';
 import { PUBLIC_CORS_ALLOWED_ORIGINS } from '$env/static/public';
+import { HTTP_CACHE_HEADERS } from '$lib/config/cache.config';
 
 /**
  * Global request handler with CORS support
···
 
 	const response = await resolve(event, {
 		filterSerializedResponseHeaders: (name) => {
-			return name === 'content-type' || name.startsWith('x-');
+			return name === 'content-type' || name === 'cache-control' || name.startsWith('x-');
 		}
 	});
+
+	// Add HTTP caching headers for better performance and reduced timeouts
+	// Layout data (root route) is cached aggressively since profile/site info changes infrequently
+	if (!event.url.pathname.startsWith('/api/')) {
+		// Root layout loads profile and site info - cache aggressively
+		if (event.url.pathname === '/' || event.url.pathname === '') {
+			response.headers.set('Cache-Control', HTTP_CACHE_HEADERS.LAYOUT);
+		}
+		// Blog listing pages
+		else if (event.url.pathname.startsWith('/blog') || event.url.pathname.startsWith('/archive')) {
+			response.headers.set('Cache-Control', HTTP_CACHE_HEADERS.BLOG_LISTING);
+		}
+		// Individual blog post pages
+		else if (event.url.pathname.match(/^\/[a-z0-9-]+$/)) {
+			response.headers.set('Cache-Control', HTTP_CACHE_HEADERS.BLOG_POST);
+		}
+		// Other pages get moderate caching
+		else {
+			response.headers.set('Cache-Control', HTTP_CACHE_HEADERS.LAYOUT);
+		}
+	}
 
 	// Add CORS headers for API routes
 	if (event.url.pathname.startsWith('/api/')) {

src/lib/config/cache.config.ts

···
+import { dev } from '$app/environment';
+
+/**
+ * Cache configuration with environment-aware TTL values
+ *
+ * Development: Shorter TTLs for faster iteration
+ * Production: Longer TTLs to reduce API calls and prevent timeouts
+ */
+
+// Parse environment variable or use default (in milliseconds)
+const getEnvTTL = (key: string, defaultMinutes: number): number => {
+	if (typeof process !== 'undefined' && process.env?.[key]) {
+		const minutes = parseInt(process.env[key], 10);
+		return isNaN(minutes) ? defaultMinutes * 60 * 1000 : minutes * 60 * 1000;
+	}
+	return defaultMinutes * 60 * 1000;
+};
+
+/**
+ * Default TTL values (in minutes) for different data types
+ *
+ * Profile data changes infrequently, so we can cache it longer
+ * Music and Kibun statuses change frequently, so shorter cache
+ */
+const DEFAULT_TTL = {
+	// Profile data: 60 minutes (changes infrequently)
+	PROFILE: dev ? 5 : 60,
+
+	// Site info: 120 minutes (rarely changes)
+	SITE_INFO: dev ? 5 : 120,
+
+	// Links: 60 minutes (changes occasionally)
+	LINKS: dev ? 5 : 60,
+
+	// Music status: 10 minutes (changes frequently)
+	MUSIC_STATUS: dev ? 2 : 10,
+
+	// Kibun status: 15 minutes (changes occasionally)
+	KIBUN_STATUS: dev ? 2 : 15,
+
+	// Tangled repos: 60 minutes (changes occasionally)
+	TANGLED_REPOS: dev ? 5 : 60,
+
+	// Blog posts: 30 minutes (balance between freshness and performance)
+	BLOG_POSTS: dev ? 5 : 30,
+
+	// Publications: 60 minutes (rarely changes)
+	PUBLICATIONS: dev ? 5 : 60,
+
+	// Individual posts: 60 minutes (content doesn't change)
+	INDIVIDUAL_POST: dev ? 5 : 60,
+
+	// Identity resolution: 1440 minutes (24 hours - DIDs are stable)
+	IDENTITY: dev ? 30 : 1440
+};
+
+/**
+ * Cache TTL configuration
+ * Values are loaded from environment variables with fallbacks to defaults
+ */
+export const CACHE_TTL = {
+	PROFILE: getEnvTTL('CACHE_TTL_PROFILE', DEFAULT_TTL.PROFILE),
+	SITE_INFO: getEnvTTL('CACHE_TTL_SITE_INFO', DEFAULT_TTL.SITE_INFO),
+	LINKS: getEnvTTL('CACHE_TTL_LINKS', DEFAULT_TTL.LINKS),
+	MUSIC_STATUS: getEnvTTL('CACHE_TTL_MUSIC_STATUS', DEFAULT_TTL.MUSIC_STATUS),
+	KIBUN_STATUS: getEnvTTL('CACHE_TTL_KIBUN_STATUS', DEFAULT_TTL.KIBUN_STATUS),
+	TANGLED_REPOS: getEnvTTL('CACHE_TTL_TANGLED_REPOS', DEFAULT_TTL.TANGLED_REPOS),
+	BLOG_POSTS: getEnvTTL('CACHE_TTL_BLOG_POSTS', DEFAULT_TTL.BLOG_POSTS),
+	PUBLICATIONS: getEnvTTL('CACHE_TTL_PUBLICATIONS', DEFAULT_TTL.PUBLICATIONS),
+	INDIVIDUAL_POST: getEnvTTL('CACHE_TTL_INDIVIDUAL_POST', DEFAULT_TTL.INDIVIDUAL_POST),
+	IDENTITY: getEnvTTL('CACHE_TTL_IDENTITY', DEFAULT_TTL.IDENTITY)
+} as const;
+
+/**
+ * HTTP Cache-Control header values for different routes
+ * These tell browsers and CDNs how long to cache responses
+ *
+ * Format: max-age=X (browser cache), s-maxage=Y (CDN cache), stale-while-revalidate=Z
+ */
+export const HTTP_CACHE_HEADERS = {
+	// Layout data (profile, site info) - cache aggressively
+	LAYOUT: `public, max-age=${CACHE_TTL.PROFILE / 1000}, s-maxage=${CACHE_TTL.PROFILE / 1000}, stale-while-revalidate=${CACHE_TTL.PROFILE / 1000}`,
+
+	// Blog posts listing - moderate caching
+	BLOG_LISTING: `public, max-age=${CACHE_TTL.BLOG_POSTS / 1000}, s-maxage=${CACHE_TTL.BLOG_POSTS / 1000}, stale-while-revalidate=${CACHE_TTL.BLOG_POSTS / 1000}`,
+
+	// Individual blog post - cache aggressively (content doesn't change)
+	BLOG_POST: `public, max-age=${CACHE_TTL.INDIVIDUAL_POST / 1000}, s-maxage=${CACHE_TTL.INDIVIDUAL_POST / 1000}, stale-while-revalidate=${CACHE_TTL.INDIVIDUAL_POST / 1000}`,
+
+	// Music status - short cache (changes frequently)
+	MUSIC_STATUS: `public, max-age=${CACHE_TTL.MUSIC_STATUS / 1000}, s-maxage=${CACHE_TTL.MUSIC_STATUS / 1000}, stale-while-revalidate=${CACHE_TTL.MUSIC_STATUS / 1000}`,
+
+	// API endpoints - moderate caching
+	API: `public, max-age=300, s-maxage=300, stale-while-revalidate=600`
+} as const;

src/lib/config/index.ts

···
 export * from './slugs';
+export * from './cache.config';

src/lib/services/atproto/agents.ts

···
 import { AtpAgent } from '@atproto/api';
 import type { ResolvedIdentity } from './types';
+import { cache } from './cache';
 
 /**
  * Creates an AtpAgent with optional fetch function injection
···
 
 /**
  * Resolves a DID to find its PDS endpoint using Slingshot.
+ * Results are cached to reduce resolution calls.
  */
 export async function resolveIdentity(
 	did: string,
···
 ): Promise<ResolvedIdentity> {
 	console.info(`[Identity] Resolving DID: ${did}`);
 
+	// Check cache first
+	const cacheKey = `identity:${did}`;
+	const cached = cache.get<ResolvedIdentity>(cacheKey);
+	if (cached) {
+		console.info('[Identity] Using cached identity resolution');
+		return cached;
+	}
+
 	// Prefer an injected fetch (from SvelteKit load), fall back to global fetch
 	const _fetch = fetchFn ?? globalThis.fetch;
 
···
 	if (!data.did || !data.pds) {
 		throw new Error('Invalid response from identity resolver');
 	}
+
+	// Cache the resolved identity
+	console.info('[Identity] Caching resolved identity');
+	cache.set(cacheKey, data);
 
 	return data;
 }

src/lib/services/atproto/cache.ts

···
 import type { CacheEntry } from './types';
+import { CACHE_TTL } from '$lib/config/cache.config';
 
 /**
- * Simple in-memory cache with TTL support
+ * Simple in-memory cache with configurable TTL support
+ *
+ * TTL values are configured per data type in cache.config.ts
+ * and can be overridden via environment variables
  */
 export class ATProtoCache {
 	private cache = new Map<string, CacheEntry<any>>();
-	private readonly TTL = 5 * 60 * 1000; // 5 minutes
+
+	/**
+	 * Get TTL for a cache key based on its prefix
+	 */
+	private getTTL(key: string): number {
+		if (key.startsWith('profile:')) return CACHE_TTL.PROFILE;
+		if (key.startsWith('siteinfo:')) return CACHE_TTL.SITE_INFO;
+		if (key.startsWith('links:')) return CACHE_TTL.LINKS;
+		if (key.startsWith('music-status:')) return CACHE_TTL.MUSIC_STATUS;
+		if (key.startsWith('kibun-status:')) return CACHE_TTL.KIBUN_STATUS;
+		if (key.startsWith('tangled:')) return CACHE_TTL.TANGLED_REPOS;
+		if (key.startsWith('blog-posts:')) return CACHE_TTL.BLOG_POSTS;
+		if (key.startsWith('publications:')) return CACHE_TTL.PUBLICATIONS;
+		if (key.startsWith('post:')) return CACHE_TTL.INDIVIDUAL_POST;
+		if (key.startsWith('identity:')) return CACHE_TTL.IDENTITY;
+
+		// Default fallback (30 minutes)
+		return 30 * 60 * 1000;
+	}
 
 	get<T>(key: string): T | null {
-		console.debug(`[Cache] Getting key: ${key}`);
+		console.info(`[Cache] Getting key: ${key}`);
 		const entry = this.cache.get(key);
 		if (!entry) {
-			console.debug(`[Cache] Cache miss for key: ${key}`);
+			console.info(`[Cache] Cache miss for key: ${key}`);
 			return null;
 		}
 
-		if (Date.now() - entry.timestamp > this.TTL) {
-			console.debug(`[Cache] Entry expired for key: ${key}`);
+		const ttl = this.getTTL(key);
+		const age = Date.now() - entry.timestamp;
+
+		if (age > ttl) {
+			console.info(`[Cache] Entry expired for key: ${key} (age: ${Math.round(age / 1000)}s, ttl: ${Math.round(ttl / 1000)}s)`);
 			this.cache.delete(key);
 			return null;
 		}
 
-		console.debug(`[Cache] Cache hit for key: ${key}`);
+		console.info(`[Cache] Cache hit for key: ${key} (age: ${Math.round(age / 1000)}s, ttl: ${Math.round(ttl / 1000)}s)`);
 		return entry.data;
 	}
 
 	set<T>(key: string, data: T): void {
-		console.debug(`[Cache] Setting key: ${key}`, data);
+		const ttl = this.getTTL(key);
+		console.info(`[Cache] Setting key: ${key} (ttl: ${Math.round(ttl / 1000)}s)`);
 		this.cache.set(key, {
 			data,
 			timestamp: Date.now()
···
 	}
 
 	delete(key: string): void {
-		console.debug(`[Cache] Deleting key: ${key}`);
+		console.info(`[Cache] Deleting key: ${key}`);
 		this.cache.delete(key);
 	}