;
- if (typeof message?.content === 'string') {
- content = message.content;
- } else {
- throw new Error('Unexpected AI response format');
- }
- } else {
- console.error('[AI] Unexpected response format:', response);
- throw new Error('Unexpected AI response format');
- }
- } else {
- console.error('[AI] Unexpected response format:', response);
- throw new Error('Unexpected AI response format');
- }
-
- // Remove markdown code blocks if present
- content = content.replace(/```json\s*/g, '').replace(/```\s*/g, '').trim();
-
- // Find JSON object in response
- const jsonMatch = content.match(/\{[\s\S]*\}/);
- if (!jsonMatch) {
- throw new Error('No JSON found in AI response');
- }
-
- const parsed = JSON.parse(jsonMatch[0]);
-
- if (!parsed.recommendations || !Array.isArray(parsed.recommendations)) {
- throw new Error('Invalid recommendations structure');
- }
-
- // Validate each recommendation with type guard
- const validRecommendations = parsed.recommendations.filter(isValidAIRecommendation);
- if (validRecommendations.length === 0 && parsed.recommendations.length > 0) {
- console.warn('[AI] All recommendations failed validation, raw:', JSON.stringify(parsed.recommendations[0]).slice(0, 200));
- throw new Error('AI recommendations failed validation');
- }
-
- return {
- recommendations: validRecommendations,
- infrastructure_tips: Array.isArray(parsed.infrastructure_tips) ? parsed.infrastructure_tips : [],
- } as AIRecommendationResponse;
- } catch (error) {
- console.error('[AI] Parse error:', error);
- console.error('[AI] Response parse failed, length:', typeof response === 'string' ? response.length : 'N/A', 'preview:', typeof response === 'string' ? response.substring(0, 100).replace(/[^\x20-\x7E]/g, '?') : 'Invalid response type');
- throw new Error(`Failed to parse AI response: ${error instanceof Error ? error.message : 'Unknown error'}`);
- }
-}
diff --git a/src/handlers/report.ts b/src/handlers/report.ts
index e6ee20b..024c306 100644
--- a/src/handlers/report.ts
+++ b/src/handlers/report.ts
@@ -7,7 +7,7 @@
*/
import type { Env, RecommendationResult, BandwidthEstimate } from '../types';
-import { jsonResponse } from '../utils';
+import { jsonResponse, escapeHtml } from '../utils';
interface ReportData {
recommendations: RecommendationResult[];
@@ -208,7 +208,7 @@ function generateReportHTML(
${labels.score}: ${score}/100
- ${server.provider_name} - ${server.instance_name}
+ ${escapeHtml(server.provider_name)} - ${escapeHtml(server.instance_name)}
@@ -225,7 +225,7 @@ function generateReportHTML(
${labels.region}
- ${server.region_name}
+ ${escapeHtml(server.region_name)}
${labels.price}
@@ -264,23 +264,23 @@ function generateReportHTML(
${bandwidth_info.currency === 'KRW' ? `₩${Math.round(bandwidth_info.total_estimated_cost).toLocaleString()}` : `$${bandwidth_info.total_estimated_cost.toFixed(2)}`}${labels.perMonth}
- ${bandwidth_info.warning ? `${bandwidth_info.warning}
` : ''}
+ ${bandwidth_info.warning ? `${escapeHtml(bandwidth_info.warning)}
` : ''}
` : ''}
${labels.analysis}
- ${labels.techFit}: ${analysis.tech_fit}
+ ${labels.techFit}: ${escapeHtml(analysis.tech_fit)}
- ${labels.capacity}: ${analysis.capacity}
+ ${labels.capacity}: ${escapeHtml(analysis.capacity)}
- ${labels.costEfficiency}: ${analysis.cost_efficiency}
+ ${labels.costEfficiency}: ${escapeHtml(analysis.cost_efficiency)}
- ${labels.scalability}: ${analysis.scalability}
+ ${labels.scalability}: ${escapeHtml(analysis.scalability)}
@@ -599,7 +599,7 @@ function generateReportHTML(
${labels.techStack}
- ${request.tech_stack.join(', ')}
+ ${escapeHtml(request.tech_stack.join(', '))}
${labels.expectedUsers}
@@ -607,7 +607,7 @@ function generateReportHTML(
${labels.useCase}
- ${request.use_case}
+ ${escapeHtml(request.use_case)}
diff --git a/src/handlers/servers.ts b/src/handlers/servers.ts
index 1f5ed31..2da30e4 100644
--- a/src/handlers/servers.ts
+++ b/src/handlers/servers.ts
@@ -3,11 +3,8 @@
*/
import type { Env } from '../types';
-import { jsonResponse, isValidServer } from '../utils';
-import {
- DEFAULT_ANVIL_REGION_FILTER_SQL,
- buildFlexibleRegionConditionsAnvil
-} from '../region-utils';
+import { jsonResponse } from '../utils';
+import { AnvilServerRepository } from '../repositories/AnvilServerRepository';
/**
* GET /api/servers - Server list with filtering
@@ -42,81 +39,33 @@ export async function handleGetServers(
}
}
- // Build SQL query using anvil_* tables
- let query = `
- SELECT
- ai.id,
- 'Anvil' as provider_name,
- ai.name as instance_id,
- ai.display_name as instance_name,
- ai.vcpus as vcpu,
- CAST(ai.memory_gb * 1024 AS INTEGER) as memory_mb,
- ai.memory_gb,
- ai.disk_gb as storage_gb,
- ai.network_gbps as network_speed_gbps,
- ai.category as instance_family,
- CASE WHEN ai.gpu_model IS NOT NULL THEN 1 ELSE 0 END as gpu_count,
- ai.gpu_model as gpu_type,
- ap.monthly_price,
- ar.display_name as region_name,
- ar.name as region_code
- FROM anvil_instances ai
- JOIN anvil_pricing ap ON ap.anvil_instance_id = ai.id
- JOIN anvil_regions ar ON ap.anvil_region_id = ar.id
- WHERE ai.active = 1 AND ar.active = 1
- AND ${DEFAULT_ANVIL_REGION_FILTER_SQL}
- `;
-
- const params: (string | number)[] = [];
+ // Validate and parse parameters
+ let parsedCpu: number | undefined;
+ let parsedMemory: number | undefined;
if (minCpu) {
- const parsedCpu = parseInt(minCpu, 10);
+ parsedCpu = parseInt(minCpu, 10);
if (isNaN(parsedCpu)) {
return jsonResponse({ error: 'Invalid minCpu parameter' }, 400, corsHeaders);
}
- query += ` AND ai.vcpus >= ?`;
- params.push(parsedCpu);
}
if (minMemory) {
- const parsedMemory = parseInt(minMemory, 10);
+ parsedMemory = parseInt(minMemory, 10);
if (isNaN(parsedMemory)) {
return jsonResponse({ error: 'Invalid minMemory parameter' }, 400, corsHeaders);
}
- // minMemory is in GB, anvil_instances stores memory_gb
- query += ` AND ai.memory_gb >= ?`;
- params.push(parsedMemory);
}
- if (region) {
- // Flexible region matching: supports country names, codes, city names
- const { conditions, params: regionParams } = buildFlexibleRegionConditionsAnvil([region]);
- query += ` AND (${conditions.join(' OR ')})`;
- params.push(...regionParams);
- }
-
- query += ` ORDER BY ap.monthly_price ASC LIMIT 100`;
-
- const result = await env.DB.prepare(query).bind(...params).all();
-
- if (!result.success) {
- throw new Error('Database query failed');
- }
-
- // Add USD currency to each result and validate with type guard
- const serversWithCurrency = (result.results as unknown[]).map(server => {
- if (typeof server === 'object' && server !== null) {
- return { ...server, currency: 'USD' };
- }
- return server;
+ // Use repository to fetch servers
+ const repository = new AnvilServerRepository(env.DB);
+ const servers = await repository.findServers({
+ minCpu: parsedCpu,
+ minMemoryGb: parsedMemory,
+ region: region ? [region] : undefined,
+ limit: 100,
});
- const servers = serversWithCurrency.filter(isValidServer);
- const invalidCount = result.results.length - servers.length;
- if (invalidCount > 0) {
- console.warn(`[GetServers] Filtered out ${invalidCount} invalid server records`);
- }
-
console.log('[GetServers] Found servers:', servers.length);
const responseData = {
diff --git a/src/repositories/AnvilServerRepository.ts b/src/repositories/AnvilServerRepository.ts
new file mode 100644
index 0000000..c7eb109
--- /dev/null
+++ b/src/repositories/AnvilServerRepository.ts
@@ -0,0 +1,186 @@
+/**
+ * Repository pattern for Anvil server queries
+ * Centralizes DB query logic to eliminate code duplication
+ */
+
+import type { D1Database } from '@cloudflare/workers-types';
+import type { Server } from '../types';
+import { buildFlexibleRegionConditionsAnvil, DEFAULT_ANVIL_REGION_FILTER_SQL } from '../region-utils';
+import { isValidServer } from '../utils';
+
+export interface ServerFilters {
+ minCpu?: number;
+ minMemoryGb?: number;
+ region?: string[];
+ budgetLimit?: number;
+ limit?: number;
+}
+
+/**
+ * Repository for Anvil server data access
+ * Handles all queries to anvil_instances, anvil_pricing, anvil_regions, anvil_transfer_pricing
+ */
+export class AnvilServerRepository {
+ constructor(private db: D1Database) {}
+
+ /**
+ * Find servers matching the given filters
+ * Used by both /api/servers and /api/recommend endpoints
+ */
+ async findServers(filters: ServerFilters): Promise {
+ const {
+ minCpu,
+ minMemoryGb,
+ region,
+ budgetLimit,
+ limit = 100
+ } = filters;
+
+ // Build base query joining all Anvil tables
+ let query = `
+ SELECT
+ ap.id,
+ 'Anvil' as provider_name,
+ ai.name as instance_id,
+ ai.display_name as instance_name,
+ ai.vcpus as vcpu,
+ CAST(ai.memory_gb * 1024 AS INTEGER) as memory_mb,
+ ai.memory_gb,
+ ai.disk_gb as storage_gb,
+ ai.network_gbps as network_speed_gbps,
+ ai.category as instance_family,
+ CASE WHEN ai.gpu_model IS NOT NULL THEN 1 ELSE 0 END as gpu_count,
+ ai.gpu_model as gpu_type,
+ ap.monthly_price,
+ ar.display_name as region_name,
+ ar.name as region_code,
+ ar.country_code,
+ ai.transfer_tb,
+ atp.price_per_gb as transfer_price_per_gb
+ FROM anvil_instances ai
+ JOIN anvil_pricing ap ON ap.anvil_instance_id = ai.id
+ JOIN anvil_regions ar ON ap.anvil_region_id = ar.id
+ LEFT JOIN anvil_transfer_pricing atp ON atp.anvil_region_id = ar.id
+ WHERE ai.active = 1 AND ar.active = 1
+ `;
+
+ const params: (string | number)[] = [];
+
+ // Apply default region filter if no specific region requested
+ if (!region || region.length === 0) {
+ query += ` AND ${DEFAULT_ANVIL_REGION_FILTER_SQL}`;
+ }
+
+ // Filter by minimum vCPU
+ if (minCpu !== undefined && minCpu > 0) {
+ query += ` AND ai.vcpus >= ?`;
+ params.push(minCpu);
+ console.log(`[AnvilServerRepository] Filtering by minimum vCPU: ${minCpu}`);
+ }
+
+ // Filter by minimum memory (input is in GB)
+ if (minMemoryGb !== undefined && minMemoryGb > 0) {
+ query += ` AND ai.memory_gb >= ?`;
+ params.push(minMemoryGb);
+ console.log(`[AnvilServerRepository] Filtering by minimum memory: ${(minMemoryGb * 1024).toFixed(0)}MB (${minMemoryGb.toFixed(1)}GB)`);
+ }
+
+ // Filter by region preference
+ if (region && region.length > 0) {
+ const { conditions, params: regionParams } = buildFlexibleRegionConditionsAnvil(region);
+ if (conditions.length > 0) {
+ query += ` AND (${conditions.join(' OR ')})`;
+ params.push(...regionParams);
+ console.log(`[AnvilServerRepository] Filtering by regions: ${region.join(', ')}`);
+ }
+ }
+
+ // Filter by budget limit
+ if (budgetLimit !== undefined && budgetLimit > 0) {
+ query += ` AND ap.monthly_price <= ?`;
+ params.push(budgetLimit);
+ }
+
+ // Order by price ascending and apply limit
+ query += ` ORDER BY ap.monthly_price ASC LIMIT ?`;
+ params.push(limit);
+
+ // Execute query
+ const result = await this.db.prepare(query).bind(...params).all();
+
+ if (!result.success) {
+ throw new Error('Database query failed for server search');
+ }
+
+ // Add currency field and validate results
+ const serversWithCurrency = (result.results as unknown[]).map(server => {
+ if (typeof server === 'object' && server !== null) {
+ const s = server as Record;
+ return {
+ ...s,
+ monthly_price: s.monthly_price as number,
+ currency: 'USD' as const,
+ transfer_tb: s.transfer_tb as number | null,
+ transfer_price_per_gb: s.transfer_price_per_gb as number | null
+ };
+ }
+ return server;
+ });
+
+ const validServers = serversWithCurrency.filter(isValidServer);
+ const invalidCount = result.results.length - validServers.length;
+
+ if (invalidCount > 0) {
+ console.warn(`[AnvilServerRepository] Filtered out ${invalidCount} invalid server records`);
+ }
+
+ console.log(`[AnvilServerRepository] Found ${validServers.length} servers matching filters`);
+
+ return validServers;
+ }
+
+ /**
+ * Find a single server by ID (pricing ID, unique per instance+region)
+ */
+ async findServerById(id: number): Promise {
+ const query = `
+ SELECT
+ ap.id,
+ 'Anvil' as provider_name,
+ ai.name as instance_id,
+ ai.display_name as instance_name,
+ ai.vcpus as vcpu,
+ CAST(ai.memory_gb * 1024 AS INTEGER) as memory_mb,
+ ai.memory_gb,
+ ai.disk_gb as storage_gb,
+ ai.network_gbps as network_speed_gbps,
+ ai.category as instance_family,
+ CASE WHEN ai.gpu_model IS NOT NULL THEN 1 ELSE 0 END as gpu_count,
+ ai.gpu_model as gpu_type,
+ ap.monthly_price,
+ ar.display_name as region_name,
+ ar.name as region_code,
+ ar.country_code,
+ ai.transfer_tb,
+ atp.price_per_gb as transfer_price_per_gb
+ FROM anvil_instances ai
+ JOIN anvil_pricing ap ON ap.anvil_instance_id = ai.id
+ JOIN anvil_regions ar ON ap.anvil_region_id = ar.id
+ LEFT JOIN anvil_transfer_pricing atp ON atp.anvil_region_id = ar.id
+ WHERE ap.id = ? AND ai.active = 1 AND ar.active = 1
+ `;
+
+ const result = await this.db.prepare(query).bind(id).first();
+
+ if (!result) {
+ return null;
+ }
+
+ const serverWithCurrency = {
+ ...result,
+ currency: 'USD' as const
+ };
+
+ return isValidServer(serverWithCurrency) ? serverWithCurrency : null;
+ }
+}
diff --git a/src/services/ai-service.ts b/src/services/ai-service.ts
new file mode 100644
index 0000000..4bda95b
--- /dev/null
+++ b/src/services/ai-service.ts
@@ -0,0 +1,695 @@
+/**
+ * AI service module - OpenAI GPT-4o-mini integration
+ * Handles AI-powered server recommendations and response parsing
+ */
+
+import type {
+ Env,
+ RecommendRequest,
+ Server,
+ BenchmarkData,
+ VPSBenchmark,
+ TechSpec,
+ BandwidthEstimate,
+ RecommendationResult,
+ AIRecommendationResponse,
+ BenchmarkReference,
+} from '../types';
+import { i18n, LIMITS } from '../config';
+import {
+ sanitizeForAIPrompt,
+ isValidAIRecommendation,
+ calculateBandwidthInfo,
+} from '../utils';
+
+/**
+ * Get AI-powered recommendations using OpenAI GPT-4o-mini
+ */
+export async function getAIRecommendations(
+ env: Env,
+ apiKey: string,
+ req: RecommendRequest,
+ candidates: Server[],
+ benchmarkData: BenchmarkData[],
+ vpsBenchmarks: VPSBenchmark[],
+ techSpecs: TechSpec[],
+ bandwidthEstimate: BandwidthEstimate,
+ lang: string = 'en',
+ exchangeRate: number = 1
+): Promise<{ recommendations: RecommendationResult[]; infrastructure_tips?: string[] }> {
+ // Validate API key before making any API calls
+ if (!apiKey || !apiKey.trim()) {
+ console.error('[AI] OPENAI_API_KEY is not configured or empty');
+ throw new Error('OPENAI_API_KEY not configured. Please set the secret via: wrangler secret put OPENAI_API_KEY');
+ }
+ if (!apiKey.startsWith('sk-')) {
+ console.error('[AI] OPENAI_API_KEY has invalid format (should start with sk-)');
+ throw new Error('Invalid OPENAI_API_KEY format');
+ }
+ console.log('[AI] API key validated (format: sk-***)');
+
+ // Build dynamic tech specs prompt from database
+ const techSpecsPrompt = formatTechSpecsForPrompt(techSpecs);
+
+ // Ensure lang is valid
+ const validLang = ['en', 'zh', 'ja', 'ko'].includes(lang) ? lang : 'en';
+ const languageInstruction = i18n[validLang].aiLanguageInstruction;
+
+ // Build system prompt with benchmark awareness
+ const systemPrompt = `You are a cloud infrastructure expert focused on COST-EFFECTIVE solutions. Your goal is to recommend the SMALLEST and CHEAPEST server that can handle the user's requirements.
+
+CRITICAL RULES:
+1. NEVER over-provision. Recommend the minimum specs needed.
+2. Cost efficiency is the PRIMARY factor - cheaper is better if it meets requirements.
+3. A 1-2 vCPU server can handle 100-500 concurrent users for most web workloads.
+4. Nginx/reverse proxy needs very little resources - 1 vCPU can handle 1000+ req/sec.
+5. Provide 3 options: Budget (cheapest viable), Balanced (some headroom), Premium (growth ready).
+6. NEVER recommend the same server twice. Each recommendation MUST have a DIFFERENT server_id.
+7. If only 2 suitable servers exist, recommend only 2. Do NOT duplicate.
+
+BANDWIDTH CONSIDERATIONS:
+- Estimated monthly bandwidth is provided based on concurrent users and use case.
+- TOTAL COST = Base server price + Bandwidth overage charges
+- Always mention bandwidth implications in cost_efficiency analysis
+
+${techSpecsPrompt}
+
+Use REAL BENCHMARK DATA to validate capacity estimates.
+
+${languageInstruction}`;
+
+ // Build user prompt with requirements and candidates
+ console.log('[AI] Bandwidth estimate:', bandwidthEstimate);
+
+ // Detect high-traffic based on bandwidth estimate (more accurate than keyword matching)
+ const isHighTraffic = bandwidthEstimate.category === 'heavy' || bandwidthEstimate.category === 'very_heavy';
+
+ // Format benchmark data for the prompt
+ const benchmarkSummary = formatBenchmarkSummary(benchmarkData);
+ const vpsBenchmarkSummary = formatVPSBenchmarkSummary(vpsBenchmarks);
+
+ // Pre-filter candidates to reduce AI prompt size and cost
+ // Ensure region diversity when no region_preference is specified
+ let topCandidates: Server[];
+ const hasRegionPreference = req.region_preference && req.region_preference.length > 0;
+
+ if (hasRegionPreference) {
+ // If region preference specified, just take top 15 cheapest
+ topCandidates = candidates
+ .sort((a, b) => a.monthly_price - b.monthly_price)
+ .slice(0, 15);
+ } else {
+ // No region preference: pick ONLY the best server from EACH region
+ // This forces AI to recommend different regions (no choice!)
+ const bestByRegion = new Map();
+ for (const server of candidates) {
+ const region = server.region_name;
+ const existing = bestByRegion.get(region);
+ // Keep the cheapest server that meets requirements for each region
+ if (!existing || server.monthly_price < existing.monthly_price) {
+ bestByRegion.set(region, server);
+ }
+ }
+
+ // Convert to array and sort by price
+ topCandidates = Array.from(bestByRegion.values())
+ .sort((a, b) => a.monthly_price - b.monthly_price);
+
+ console.log(`[AI] Region diversity FORCED: ${topCandidates.length} regions, 1 server each`);
+ console.log(`[AI] Regions: ${topCandidates.map(s => s.region_name).join(', ')}`);
+ }
+
+ console.log(`[AI] Filtered ${candidates.length} candidates to ${topCandidates.length} for AI analysis`);
+
+ // Sanitize user inputs to prevent prompt injection
+ const sanitizedTechStack = req.tech_stack.map(t => sanitizeForAIPrompt(t, 50)).join(', ');
+ const sanitizedUseCase = sanitizeForAIPrompt(req.use_case, 200);
+
+ const userPrompt = `Analyze these server options and recommend the top 3 best matches.
+
+## User Requirements
+- Tech Stack: ${sanitizedTechStack}
+- Expected Concurrent Users: ${req.expected_users} ${req.traffic_pattern === 'spiky' ? '(with traffic spikes)' : req.traffic_pattern === 'growing' ? '(growing user base)' : '(steady traffic)'}
+- **Estimated DAU (Daily Active Users)**: ${bandwidthEstimate.estimated_dau_min.toLocaleString()}-${bandwidthEstimate.estimated_dau_max.toLocaleString()}명 (동시 접속 ${req.expected_users}명 기준)
+- Use Case: ${sanitizedUseCase}
+- Traffic Pattern: ${req.traffic_pattern || 'steady'}
+- **Estimated Monthly Bandwidth**: ${bandwidthEstimate.monthly_tb >= 1 ? `${bandwidthEstimate.monthly_tb} TB` : `${bandwidthEstimate.monthly_gb} GB`} (${bandwidthEstimate.category})
+${isHighTraffic ? `- ⚠️ HIGH BANDWIDTH WORKLOAD (${bandwidthEstimate.monthly_tb} TB/month): Consider bandwidth overage costs when evaluating total cost.` : ''}
+${req.budget_limit ? `- Budget Limit: $${req.budget_limit}/month` : ''}
+
+## Real VPS Benchmark Data (Geekbench 6 normalized - actual VPS tests)
+${vpsBenchmarkSummary || 'No similar VPS benchmark data available.'}
+
+## CPU Benchmark Reference (from Phoronix Test Suite)
+${benchmarkSummary || 'No relevant CPU benchmark data available.'}
+
+## Available Servers (IMPORTANT: Use the server_id value, NOT the list number!)
+${topCandidates.map((s) => `[server_id=${s.id}] ${s.provider_name} - ${s.instance_name}
+ vCPU: ${s.vcpu} | RAM: ${s.memory_gb}GB | Storage: ${s.storage_gb}GB${s.gpu_count > 0 ? ` | GPU: ${s.gpu_count}x ${s.gpu_type}` : ''}
+ Price: ${s.currency === 'KRW' ? '₩' : '$'}${s.currency === 'KRW' ? Math.round(s.monthly_price).toLocaleString() : s.monthly_price.toFixed(2)}/mo | Region: ${s.region_name}`).join('\n')}
+
+Return ONLY a valid JSON object (no markdown, no code blocks) with this exact structure:
+{
+ "recommendations": [
+ {
+ "server_id": 2045, // Use the actual server_id from [server_id=XXXX] above, NOT list position!
+ "score": 95,
+ "analysis": {
+ "tech_fit": "Why this server fits the tech stack",
+ "capacity": "MUST mention: '동시 접속 X명 요청 (DAU A-B명), 최대 동시 Y명까지 처리 가능' format",
+ "cost_efficiency": "MUST include: base price + bandwidth cost estimate. Example: '$5/month + ~$X bandwidth = ~$Y total'",
+ "scalability": "Scalability potential including bandwidth headroom"
+ },
+ "estimated_capacity": {
+ "max_concurrent_users": 7500,
+ "requests_per_second": 1000
+ }
+ }
+ ],
+ "infrastructure_tips": [
+ "Practical tip 1",
+ "Practical tip 2"
+ ]
+}
+
+Provide exactly 3 recommendations:
+1. BUDGET option: Cheapest TOTAL cost (base + bandwidth) that can handle the load
+2. BALANCED option: Some headroom for traffic spikes
+3. PREMIUM option: Ready for 2-3x growth
+
+SCORING (100 points total):
+- Total Cost Efficiency (40%): Base price + estimated bandwidth overage. Lower total = higher score.
+- Capacity Fit (30%): Can it handle the concurrent users and bandwidth?
+- Scalability (30%): Room for growth in CPU, memory, AND bandwidth allowance.
+
+The option with the LOWEST TOTAL MONTHLY COST (including bandwidth) should have the HIGHEST score.`;
+
+ // Use AI Gateway if configured (bypasses regional restrictions like HKG)
+ // AI Gateway URL format: https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_name}/openai
+ const useAIGateway = !!env.AI_GATEWAY_URL;
+ const apiEndpoint = useAIGateway
+ ? `${env.AI_GATEWAY_URL}/chat/completions`
+ : 'https://api.openai.com/v1/chat/completions';
+
+ console.log(`[AI] Sending request to ${useAIGateway ? 'AI Gateway → ' : ''}OpenAI GPT-4o-mini`);
+ if (useAIGateway) {
+ console.log('[AI] Using Cloudflare AI Gateway to bypass regional restrictions');
+ }
+
+ // Create AbortController with 30 second timeout
+ const controller = new AbortController();
+ const timeoutId = setTimeout(() => controller.abort(), 30000);
+
+ try {
+ const openaiResponse = await fetch(apiEndpoint, {
+ method: 'POST',
+ headers: {
+ 'Content-Type': 'application/json',
+ 'Authorization': `Bearer ${apiKey}`,
+ },
+ body: JSON.stringify({
+ model: 'gpt-4o-mini',
+ messages: [
+ { role: 'system', content: systemPrompt },
+ { role: 'user', content: userPrompt },
+ ],
+ max_tokens: 2000,
+ temperature: 0.3,
+ }),
+ signal: controller.signal,
+ });
+
+ clearTimeout(timeoutId);
+
+ if (!openaiResponse.ok) {
+ const errorText = await openaiResponse.text();
+
+ // Parse error details for better debugging
+ let errorDetails = '';
+ try {
+ const errorObj = JSON.parse(errorText);
+ errorDetails = errorObj?.error?.message || errorObj?.error?.type || '';
+ } catch {
+ errorDetails = errorText.slice(0, 200);
+ }
+
+ // Sanitize API keys from error messages
+ const sanitized = errorDetails.replace(/sk-[a-zA-Z0-9-_]+/g, 'sk-***');
+
+ // Enhanced logging for specific error codes
+ if (openaiResponse.status === 403) {
+ const isRegionalBlock = errorDetails.includes('Country') || errorDetails.includes('region') || errorDetails.includes('territory');
+ if (isRegionalBlock && !useAIGateway) {
+ console.error('[AI] ❌ REGIONAL BLOCK (403) - OpenAI blocked this region');
+ console.error('[AI] Worker is running in a blocked region (e.g., HKG)');
+ console.error('[AI] FIX: Set AI_GATEWAY_URL secret to use Cloudflare AI Gateway');
+ console.error('[AI] 1. Create AI Gateway: https://dash.cloudflare.com → AI → AI Gateway');
+ console.error('[AI] 2. Run: wrangler secret put AI_GATEWAY_URL');
+ console.error('[AI] 3. Enter: https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_name}/openai');
+ } else {
+ console.error('[AI] ❌ AUTH FAILED (403) - Possible causes:');
+ console.error('[AI] 1. Invalid or expired OPENAI_API_KEY');
+ console.error('[AI] 2. API key not properly set in Cloudflare secrets');
+ console.error('[AI] 3. Account billing issue or quota exceeded');
+ }
+ console.error('[AI] Error details:', sanitized);
+ } else if (openaiResponse.status === 429) {
+ console.error('[AI] ⚠️ RATE LIMITED (429) - Too many requests');
+ console.error('[AI] Error details:', sanitized);
+ } else if (openaiResponse.status === 401) {
+ console.error('[AI] ❌ UNAUTHORIZED (401) - API key invalid');
+ console.error('[AI] Error details:', sanitized);
+ } else {
+ console.error('[AI] OpenAI API error:', openaiResponse.status, sanitized);
+ }
+
+ throw new Error(`OpenAI API error: ${openaiResponse.status}`);
+ }
+
+ const openaiResult = await openaiResponse.json() as {
+ choices: Array<{ message: { content: string } }>;
+ };
+
+ const response = openaiResult.choices[0]?.message?.content || '';
+
+ console.log('[AI] Response received from OpenAI, length:', response.length);
+
+ // Parse AI response
+ const aiResult = parseAIResponse(response);
+ console.log('[AI] Parsed recommendations count:', aiResult.recommendations.length);
+
+ // Pre-index VPS benchmarks by provider for O(1) lookups
+ const vpsByProvider = new Map();
+ for (const vps of vpsBenchmarks) {
+ const providerKey = vps.provider_name.toLowerCase();
+ const existing = vpsByProvider.get(providerKey) || [];
+ existing.push(vps);
+ vpsByProvider.set(providerKey, existing);
+ }
+
+ // Map AI recommendations to full results (with deduplication)
+ const results: RecommendationResult[] = [];
+ const seenServerIds = new Set();
+
+ for (const aiRec of aiResult.recommendations) {
+ // Handle both string and number server_id from AI
+ const serverId = Number(aiRec.server_id);
+
+ // Skip duplicate server IDs
+ if (seenServerIds.has(serverId)) {
+ console.warn('[AI] Skipping duplicate server_id:', serverId);
+ continue;
+ }
+
+ const server = candidates.find((s) => s.id === serverId);
+ if (!server) {
+ console.warn('[AI] Server not found:', aiRec.server_id);
+ continue;
+ }
+
+ seenServerIds.add(serverId);
+
+ // Get benchmark reference for this server's CPU count
+ const benchmarkRef = getBenchmarkReference(benchmarkData, server.vcpu);
+
+ // Find matching VPS benchmark using pre-indexed data
+ const providerName = server.provider_name.toLowerCase();
+ let matchingVPS: VPSBenchmark | undefined;
+
+ // Try to find from indexed provider benchmarks
+ for (const [providerKey, benchmarks] of vpsByProvider.entries()) {
+ if (providerKey.includes(providerName) || providerName.includes(providerKey)) {
+ // First try exact or close vCPU match
+ matchingVPS = benchmarks.find(
+ (v) => v.vcpu === server.vcpu || (v.vcpu >= server.vcpu - 1 && v.vcpu <= server.vcpu + 1)
+ );
+ // Fallback to any from this provider
+ if (!matchingVPS && benchmarks.length > 0) {
+ matchingVPS = benchmarks[0];
+ }
+ if (matchingVPS) break;
+ }
+ }
+
+ // Final fallback: similar specs from any provider
+ if (!matchingVPS) {
+ matchingVPS = vpsBenchmarks.find(
+ (v) => v.vcpu === server.vcpu || (v.vcpu >= server.vcpu - 1 && v.vcpu <= server.vcpu + 1)
+ );
+ }
+
+ // Calculate bandwidth info for this server (with currency conversion for Korean)
+ const bandwidthInfo = calculateBandwidthInfo(server, bandwidthEstimate, lang, exchangeRate);
+
+ // Find all available regions for the same server spec
+ const availableRegions = candidates
+ .filter(c =>
+ c.provider_name === server.provider_name &&
+ c.instance_id === server.instance_id &&
+ c.region_code !== server.region_code // Exclude current region
+ )
+ .map(c => ({
+ region_name: c.region_name,
+ region_code: c.region_code,
+ monthly_price: c.monthly_price
+ }))
+ .sort((a, b) => a.monthly_price - b.monthly_price);
+
+ results.push({
+ server: server,
+ score: aiRec.score,
+ analysis: aiRec.analysis,
+ estimated_capacity: aiRec.estimated_capacity,
+ bandwidth_info: bandwidthInfo,
+ benchmark_reference: benchmarkRef,
+ vps_benchmark_reference: matchingVPS
+ ? {
+ plan_name: matchingVPS.plan_name,
+ geekbench_single: matchingVPS.geekbench_single,
+ geekbench_multi: matchingVPS.geekbench_multi,
+ monthly_price_usd: matchingVPS.monthly_price_usd,
+ performance_per_dollar: matchingVPS.performance_per_dollar,
+ }
+ : undefined,
+ available_regions: availableRegions.length > 0 ? availableRegions : undefined,
+ });
+
+ if (results.length >= 3) break;
+ }
+
+ return {
+ recommendations: results,
+ infrastructure_tips: aiResult.infrastructure_tips,
+ };
+ } catch (error) {
+ clearTimeout(timeoutId);
+ // Handle timeout specifically
+ if (error instanceof Error && error.name === 'AbortError') {
+ console.error('[AI] Request timed out after 30 seconds');
+ throw new Error('AI request timed out - please try again');
+ }
+ console.error('[AI] Error:', error);
+ throw new Error(`AI processing failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+ }
+}
+
+/**
+ * Parse AI response and extract JSON
+ */
+export function parseAIResponse(response: unknown): AIRecommendationResponse {
+ try {
+ // Handle different response formats
+ let content: string;
+
+ if (typeof response === 'string') {
+ content = response;
+ } else if (typeof response === 'object' && response !== null) {
+ // Type guard for response object with different structures
+ const resp = response as Record;
+
+ if (typeof resp.response === 'string') {
+ content = resp.response;
+ } else if (typeof resp.result === 'object' && resp.result !== null) {
+ const result = resp.result as Record;
+ if (typeof result.response === 'string') {
+ content = result.response;
+ } else {
+ throw new Error('Unexpected AI response format');
+ }
+ } else if (Array.isArray(resp.choices) && resp.choices.length > 0) {
+ const choice = resp.choices[0] as Record;
+ const message = choice?.message as Record;
+ if (typeof message?.content === 'string') {
+ content = message.content;
+ } else {
+ throw new Error('Unexpected AI response format');
+ }
+ } else {
+ console.error('[AI] Unexpected response format:', response);
+ throw new Error('Unexpected AI response format');
+ }
+ } else {
+ console.error('[AI] Unexpected response format:', response);
+ throw new Error('Unexpected AI response format');
+ }
+
+ // Remove markdown code blocks if present
+ content = content.replace(/```json\s*/g, '').replace(/```\s*/g, '').trim();
+
+ // Find JSON object in response
+ const jsonMatch = content.match(/\{[\s\S]*\}/);
+ if (!jsonMatch) {
+ throw new Error('No JSON found in AI response');
+ }
+
+ const parsed = JSON.parse(jsonMatch[0]);
+
+ if (!parsed.recommendations || !Array.isArray(parsed.recommendations)) {
+ throw new Error('Invalid recommendations structure');
+ }
+
+ // Validate each recommendation with type guard
+ const validRecommendations = parsed.recommendations.filter(isValidAIRecommendation);
+ if (validRecommendations.length === 0 && parsed.recommendations.length > 0) {
+ console.warn('[AI] All recommendations failed validation, raw:', JSON.stringify(parsed.recommendations[0]).slice(0, 200));
+ throw new Error('AI recommendations failed validation');
+ }
+
+ return {
+ recommendations: validRecommendations,
+ infrastructure_tips: Array.isArray(parsed.infrastructure_tips) ? parsed.infrastructure_tips : [],
+ } as AIRecommendationResponse;
+ } catch (error) {
+ console.error('[AI] Parse error:', error);
+ console.error('[AI] Response parse failed, length:', typeof response === 'string' ? response.length : 'N/A', 'preview:', typeof response === 'string' ? response.substring(0, 100).replace(/[^\x20-\x7E]/g, '?') : 'Invalid response type');
+ throw new Error(`Failed to parse AI response: ${error instanceof Error ? error.message : 'Unknown error'}`);
+ }
+}
+
+/**
+ * Format tech specs for AI prompt
+ */
+export function formatTechSpecsForPrompt(techSpecs: TechSpec[]): string {
+ if (!techSpecs || techSpecs.length === 0) {
+ return `Tech stack resource guidelines:
+- Default: 1 vCPU per 100-300 users, 1-2GB RAM`;
+ }
+
+ const lines = ['Tech stack resource guidelines (MUST follow minimum RAM requirements):'];
+
+ for (const spec of techSpecs) {
+ const vcpuRange = spec.vcpu_per_users_max
+ ? `${spec.vcpu_per_users}-${spec.vcpu_per_users_max}`
+ : `${spec.vcpu_per_users}`;
+
+ // Convert MB to GB for readability
+ const minMemoryGB = (spec.min_memory_mb / 1024).toFixed(1).replace('.0', '');
+ const maxMemoryGB = spec.max_memory_mb ? (spec.max_memory_mb / 1024).toFixed(1).replace('.0', '') : null;
+ const memoryRange = maxMemoryGB ? `${minMemoryGB}-${maxMemoryGB}GB` : `${minMemoryGB}GB+`;
+
+ let line = `- ${spec.name}: 1 vCPU per ${vcpuRange} users, MINIMUM ${minMemoryGB}GB RAM`;
+
+ // Add warnings for special requirements
+ const warnings: string[] = [];
+ if (spec.is_memory_intensive) warnings.push('⚠️ MEMORY-INTENSIVE: must have at least ' + minMemoryGB + 'GB RAM');
+ if (spec.is_cpu_intensive) warnings.push('⚠️ CPU-INTENSIVE');
+ if (warnings.length > 0) {
+ line += ` [${warnings.join(', ')}]`;
+ }
+
+ lines.push(line);
+ }
+
+ // Add explicit warning for memory-intensive apps
+ const memoryIntensive = techSpecs.filter(s => s.is_memory_intensive);
+ if (memoryIntensive.length > 0) {
+ const maxMinMemory = Math.max(...memoryIntensive.map(s => s.min_memory_mb));
+ lines.push('');
+ lines.push(`⚠️ CRITICAL: This tech stack includes memory-intensive apps. Servers with less than ${(maxMinMemory / 1024).toFixed(0)}GB RAM will NOT work properly!`);
+ }
+
+ return lines.join('\n');
+}
+
+/**
+ * Format benchmark data for AI prompt
+ */
+export function formatBenchmarkSummary(benchmarks: BenchmarkData[]): string {
+ if (benchmarks.length === 0) {
+ return '';
+ }
+
+ // Group by benchmark type
+ const byType = new Map();
+ for (const b of benchmarks) {
+ const existing = byType.get(b.benchmark_name) || [];
+ existing.push(b);
+ byType.set(b.benchmark_name, existing);
+ }
+
+ const lines: string[] = [];
+ for (const [type, data] of byType) {
+ // Get top 3 performers for this benchmark
+ const top3 = data.slice(0, 3);
+ const scores = top3.map(d =>
+ `${d.processor_name}${d.cores ? ` (${d.cores} cores)` : ''}: ${d.score} (${d.percentile}th percentile)`
+ );
+ lines.push(`### ${type} (${data[0].category})`);
+ lines.push(scores.join('\n'));
+ lines.push('');
+ }
+
+ return lines.join('\n');
+}
+
+/**
+ * Format VPS benchmark data for AI prompt
+ * Uses GB6-normalized scores (GB5 scores converted with ×1.45 factor)
+ */
+export function formatVPSBenchmarkSummary(benchmarks: VPSBenchmark[]): string {
+ if (benchmarks.length === 0) {
+ return '';
+ }
+
+ const lines = ['Real VPS performance data (Geekbench 6 normalized):'];
+ for (const b of benchmarks.slice(0, 5)) {
+ const versionNote = b.geekbench_version?.startsWith('5.') ? ' [GB5→6]' : '';
+ lines.push(
+ `- ${b.plan_name} (${b.country_code}): Single=${b.gb6_single_normalized}, Multi=${b.gb6_multi_normalized}${versionNote}, $${b.monthly_price_usd}/mo, Perf/$=${b.performance_per_dollar.toFixed(1)}`
+ );
+ }
+
+ return lines.join('\n');
+}
+
+/**
+ * Get benchmark reference for a server
+ */
+function getBenchmarkReference(
+ benchmarks: BenchmarkData[],
+ vcpu: number
+): BenchmarkReference | undefined {
+ // Find benchmarks from processors with similar core count
+ const similarBenchmarks = benchmarks.filter(b =>
+ b.cores === null || (b.cores >= vcpu - 2 && b.cores <= vcpu + 4)
+ );
+
+ if (similarBenchmarks.length === 0) {
+ return undefined;
+ }
+
+ // Group by processor and get the best match
+ const byProcessor = new Map();
+ for (const b of similarBenchmarks) {
+ const existing = byProcessor.get(b.processor_name) || [];
+ existing.push(b);
+ byProcessor.set(b.processor_name, existing);
+ }
+
+ // Find processor with most benchmark data
+ let bestProcessor = '';
+ let maxBenchmarks = 0;
+ for (const [name, data] of byProcessor) {
+ if (data.length > maxBenchmarks) {
+ maxBenchmarks = data.length;
+ bestProcessor = name;
+ }
+ }
+
+ if (!bestProcessor) {
+ return undefined;
+ }
+
+ const processorBenchmarks = byProcessor.get(bestProcessor)!;
+ return {
+ processor_name: bestProcessor,
+ benchmarks: processorBenchmarks.map(b => ({
+ name: b.benchmark_name,
+ category: b.category,
+ score: b.score,
+ percentile: b.percentile,
+ })),
+ };
+}
+
+/**
+ * AI 실패 시 규칙 기반으로 추천 생성
+ * 가격순 정렬 → 스펙 필터링 → 상위 3개 선택 (Budget/Balanced/Premium)
+ */
+export function generateRuleBasedRecommendations(
+ candidates: Server[],
+ req: RecommendRequest,
+ minVcpu: number,
+ minMemoryMb: number,
+ bandwidthEstimate: BandwidthEstimate,
+ lang: string = 'en',
+ exchangeRate: number = 1
+): RecommendationResult[] {
+ // 가격순 정렬
+ const sorted = [...candidates].sort((a, b) => a.monthly_price - b.monthly_price);
+
+ if (sorted.length === 0) {
+ return [];
+ }
+
+ // 3개 티어 선택: 가장 저렴(Budget), 중간(Balanced), 상위 25%(Premium)
+ const budget = sorted[0];
+ const balanced = sorted[Math.floor(sorted.length / 2)] || sorted[0];
+ const premium = sorted[Math.floor(sorted.length * 0.75)] || sorted[sorted.length - 1] || sorted[0];
+
+ const tiers = [
+ { server: budget, tier: 'budget' as const, score: 85 },
+ { server: balanced, tier: 'balanced' as const, score: 80 },
+ { server: premium, tier: 'premium' as const, score: 75 },
+ ].filter(t => t.server);
+
+ // 중복 제거
+ const seen = new Set();
+ const unique = tiers.filter(t => {
+ if (seen.has(t.server.id)) return false;
+ seen.add(t.server.id);
+ return true;
+ });
+
+ // RecommendationResult 형식으로 변환
+ return unique.map(({ server, score }) => {
+ const bandwidthInfo = calculateBandwidthInfo(server, bandwidthEstimate, lang, exchangeRate);
+
+ const fallbackMessage = lang === 'ko'
+ ? '규칙 기반 추천 (AI 일시 불가)'
+ : 'Rule-based recommendation (AI temporarily unavailable)';
+
+ const capacityMessage = lang === 'ko'
+ ? `${server.vcpu} vCPU, ${server.memory_gb}GB RAM (동시 접속 ${req.expected_users}명 기준)`
+ : `${server.vcpu} vCPU, ${server.memory_gb}GB RAM (for ${req.expected_users} concurrent users)`;
+
+ const scalabilityMessage = lang === 'ko'
+ ? '수동 스케일링 필요'
+ : 'Manual scaling required';
+
+ const currencySymbol = server.currency === 'KRW' ? '₩' : '$';
+ const formattedPrice = server.currency === 'KRW'
+ ? Math.round(server.monthly_price).toLocaleString()
+ : server.monthly_price.toFixed(2);
+
+ const costMessage = lang === 'ko'
+ ? `월 ${currencySymbol}${formattedPrice}`
+ : `${currencySymbol}${formattedPrice}/month`;
+
+ return {
+ server,
+ score,
+ analysis: {
+ tech_fit: fallbackMessage,
+ capacity: capacityMessage,
+ scalability: scalabilityMessage,
+ cost_efficiency: costMessage,
+ },
+ estimated_capacity: {
+ max_concurrent_users: Math.floor(server.vcpu * 100), // 간단한 추정: vCPU당 100명
+ requests_per_second: Math.floor(server.vcpu * 50), // vCPU당 50 RPS
+ },
+ bandwidth_info: bandwidthInfo,
+ };
+ });
+}
diff --git a/src/types.ts b/src/types.ts
index e62446d..18c436b 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -15,7 +15,7 @@ export interface ValidationError {
missing_fields?: string[];
invalid_fields?: { field: string; reason: string }[];
schema: Record;
- example: Record;
+ example: Record;
}
export interface RecommendRequest {
diff --git a/src/utils.ts b/src/utils.ts
index 54deb0e..e6e9a19 100644
--- a/src/utils.ts
+++ b/src/utils.ts
@@ -1,800 +1,8 @@
/**
- * Utility functions
+ * Legacy utils.ts - Re-exports from modularized structure
+ * This file maintains backward compatibility while delegating to domain-specific modules
+ *
+ * @deprecated Import from './utils/index' or specific modules instead
*/
-import type {
- RecommendRequest,
- ValidationError,
- Server,
- VPSBenchmark,
- TechSpec,
- BenchmarkData,
- AIRecommendationResponse,
- UseCaseConfig,
- BandwidthEstimate,
- BandwidthInfo,
- Env,
- ExchangeRateCache
-} from './types';
-import { USE_CASE_CONFIGS, i18n, LIMITS } from './config';
-
-/**
- * JSON response helper
- */
-export function jsonResponse(
- data: any,
- status: number,
- headers: Record = {}
-): Response {
- return new Response(JSON.stringify(data), {
- status,
- headers: {
- 'Content-Type': 'application/json',
- 'Content-Security-Policy': "default-src 'none'",
- 'X-Content-Type-Options': 'nosniff',
- 'X-Frame-Options': 'DENY',
- 'Strict-Transport-Security': 'max-age=31536000; includeSubDomains',
- 'Cache-Control': 'no-store',
- ...headers,
- },
- });
-}
-
-/**
- * Simple hash function for strings
- */
-export function hashString(str: string): string {
- let hash = 0;
- for (let i = 0; i < str.length; i++) {
- const char = str.charCodeAt(i);
- hash = ((hash << 5) - hash) + char;
- hash = hash & hash; // Convert to 32-bit integer
- }
- // Use >>> 0 to convert to unsigned 32-bit integer
- return (hash >>> 0).toString(36);
-}
-
-/**
- * Sanitize special characters for cache key
- */
-export function sanitizeCacheValue(value: string): string {
- // Use URL-safe base64 encoding to avoid collisions
- try {
- return btoa(value).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
- } catch {
- // Fallback for non-ASCII characters
- return encodeURIComponent(value).replace(/[%]/g, '_');
- }
-}
-
-/**
- * Generate cache key from request parameters
- */
-export function generateCacheKey(req: RecommendRequest): string {
- // Don't mutate original arrays - create sorted copies
- const sortedStack = [...req.tech_stack].sort();
- const sanitizedStack = sortedStack.map(sanitizeCacheValue).join(',');
-
- // Hash use_case to avoid special characters and length issues
- const useCaseHash = hashString(req.use_case);
-
- const parts = [
- `stack:${sanitizedStack}`,
- `users:${req.expected_users}`,
- `case:${useCaseHash}`,
- ];
-
- if (req.traffic_pattern) {
- parts.push(`traffic:${req.traffic_pattern}`);
- }
-
- if (req.budget_limit) {
- parts.push(`budget:${req.budget_limit}`);
- }
-
- // Include region preference in cache key
- if (req.region_preference && req.region_preference.length > 0) {
- const sortedRegions = [...req.region_preference].sort();
- const sanitizedRegions = sortedRegions.map(sanitizeCacheValue).join(',');
- parts.push(`region:${sanitizedRegions}`);
- }
-
- // Include language in cache key
- if (req.lang) {
- parts.push(`lang:${req.lang}`);
- }
-
- return `recommend:${parts.join('|')}`;
-}
-
-/**
- * Re-export region utilities from region-utils.ts for backward compatibility
- */
-export {
- DEFAULT_ANVIL_REGION_FILTER_SQL,
- COUNTRY_NAME_TO_REGIONS,
- escapeLikePattern,
- buildFlexibleRegionConditions,
- buildFlexibleRegionConditionsAnvil
-} from './region-utils';
-
-/**
- * Type guard to validate Server object structure
- */
-export function isValidServer(obj: unknown): obj is Server {
- if (!obj || typeof obj !== 'object') return false;
- const s = obj as Record;
- return (
- typeof s.id === 'number' &&
- typeof s.provider_name === 'string' &&
- typeof s.instance_id === 'string' &&
- typeof s.vcpu === 'number' &&
- typeof s.memory_mb === 'number' &&
- typeof s.monthly_price === 'number'
- );
-}
-
-/**
- * Type guard to validate VPSBenchmark object structure
- */
-export function isValidVPSBenchmark(obj: unknown): obj is VPSBenchmark {
- if (!obj || typeof obj !== 'object') return false;
- const v = obj as Record;
- return (
- typeof v.id === 'number' &&
- typeof v.provider_name === 'string' &&
- typeof v.vcpu === 'number' &&
- typeof v.geekbench_single === 'number'
- );
-}
-
-/**
- * Type guard to validate TechSpec object structure
- */
-export function isValidTechSpec(obj: unknown): obj is TechSpec {
- if (!obj || typeof obj !== 'object') return false;
- const t = obj as Record;
- return (
- typeof t.id === 'number' &&
- typeof t.name === 'string' &&
- typeof t.vcpu_per_users === 'number' &&
- typeof t.min_memory_mb === 'number'
- );
-}
-
-/**
- * Type guard to validate BenchmarkData object structure
- */
-export function isValidBenchmarkData(obj: unknown): obj is BenchmarkData {
- if (!obj || typeof obj !== 'object') return false;
- const b = obj as Record;
- return (
- typeof b.id === 'number' &&
- typeof b.processor_name === 'string' &&
- typeof b.benchmark_name === 'string' &&
- typeof b.score === 'number'
- );
-}
-
-/**
- * Type guard to validate AI recommendation structure
- */
-export function isValidAIRecommendation(obj: unknown): obj is AIRecommendationResponse['recommendations'][0] {
- if (!obj || typeof obj !== 'object') return false;
- const r = obj as Record;
- return (
- (typeof r.server_id === 'number' || typeof r.server_id === 'string') &&
- typeof r.score === 'number' &&
- r.analysis !== null &&
- typeof r.analysis === 'object' &&
- r.estimated_capacity !== null &&
- typeof r.estimated_capacity === 'object'
- );
-}
-
-/**
- * Validate recommendation request
- */
-export function validateRecommendRequest(body: any, lang: string = 'en'): ValidationError | null {
- // Ensure lang is valid
- const validLang = ['en', 'zh', 'ja', 'ko'].includes(lang) ? lang : 'en';
- const messages = i18n[validLang];
-
- if (!body || typeof body !== 'object') {
- return {
- error: 'Request body must be a JSON object',
- missing_fields: ['tech_stack', 'expected_users', 'use_case'],
- schema: messages.schema,
- example: messages.example
- };
- }
-
- const missingFields: string[] = [];
- const invalidFields: { field: string; reason: string }[] = [];
-
- // Check required fields
- if (!body.tech_stack) {
- missingFields.push('tech_stack');
- } else if (!Array.isArray(body.tech_stack) || body.tech_stack.length === 0) {
- invalidFields.push({ field: 'tech_stack', reason: 'must be a non-empty array of strings' });
- } else if (body.tech_stack.length > LIMITS.MAX_TECH_STACK) {
- invalidFields.push({ field: 'tech_stack', reason: `must not exceed ${LIMITS.MAX_TECH_STACK} items` });
- } else if (!body.tech_stack.every((item: unknown) =>
- typeof item === 'string' && item.length <= 50
- )) {
- invalidFields.push({ field: 'tech_stack', reason: messages.techStackItemLength || 'all items must be strings with max 50 characters' });
- }
-
- if (body.expected_users === undefined) {
- missingFields.push('expected_users');
- } else if (typeof body.expected_users !== 'number' || body.expected_users < 1) {
- invalidFields.push({ field: 'expected_users', reason: 'must be a positive number' });
- } else if (body.expected_users > 10000000) {
- invalidFields.push({ field: 'expected_users', reason: 'must not exceed 10,000,000' });
- }
-
- if (!body.use_case) {
- missingFields.push('use_case');
- } else if (typeof body.use_case !== 'string' || body.use_case.trim().length === 0) {
- invalidFields.push({ field: 'use_case', reason: 'must be a non-empty string' });
- } else if (body.use_case.length > LIMITS.MAX_USE_CASE_LENGTH) {
- invalidFields.push({ field: 'use_case', reason: `must not exceed ${LIMITS.MAX_USE_CASE_LENGTH} characters` });
- }
-
- // Check optional fields if provided
- if (body.traffic_pattern !== undefined && !['steady', 'spiky', 'growing'].includes(body.traffic_pattern)) {
- invalidFields.push({ field: 'traffic_pattern', reason: "must be one of: 'steady', 'spiky', 'growing'" });
- }
-
- if (body.budget_limit !== undefined && (typeof body.budget_limit !== 'number' || body.budget_limit < 0)) {
- invalidFields.push({ field: 'budget_limit', reason: 'must be a non-negative number' });
- }
-
- // Validate lang field if provided
- if (body.lang !== undefined && !['en', 'zh', 'ja', 'ko'].includes(body.lang)) {
- invalidFields.push({ field: 'lang', reason: "must be one of: 'en', 'zh', 'ja', 'ko'" });
- }
-
- // Return error if any issues found
- if (missingFields.length > 0 || invalidFields.length > 0) {
- return {
- error: missingFields.length > 0 ? messages.missingFields : messages.invalidFields,
- ...(missingFields.length > 0 && { missing_fields: missingFields }),
- ...(invalidFields.length > 0 && { invalid_fields: invalidFields }),
- schema: messages.schema,
- example: messages.example
- };
- }
-
- return null;
-}
-
-/**
- * Helper function to get allowed CORS origin
- */
-export function getAllowedOrigin(request: Request): string {
- const allowedOrigins = [
- 'https://server-recommend.kappa-d8e.workers.dev',
- ];
- const origin = request.headers.get('Origin');
-
- // If Origin is provided and matches allowed list, return it
- if (origin && allowedOrigins.includes(origin)) {
- return origin;
- }
-
- // For requests without Origin (non-browser: curl, API clients, server-to-server)
- // Return empty string - CORS headers won't be sent but request is still processed
- // This is safe because CORS only affects browser requests
- if (!origin) {
- return '';
- }
-
- // Origin provided but not in allowed list - return first allowed origin
- // Browser will block the response due to CORS mismatch
- return allowedOrigins[0];
-}
-
-/**
- * Find use case configuration by matching patterns
- */
-export function findUseCaseConfig(useCase: string): UseCaseConfig {
- const useCaseLower = useCase.toLowerCase();
-
- for (const config of USE_CASE_CONFIGS) {
- if (config.patterns.test(useCaseLower)) {
- return config;
- }
- }
-
- // Default configuration
- return {
- category: 'default',
- patterns: /.*/,
- dauMultiplier: { min: 10, max: 14 },
- activeRatio: 0.5
- };
-}
-
-/**
- * Get DAU multiplier based on use case (how many daily active users per concurrent user)
- */
-export function getDauMultiplier(useCase: string): { min: number; max: number } {
- return findUseCaseConfig(useCase).dauMultiplier;
-}
-
-/**
- * Get active user ratio (what percentage of DAU actually performs the bandwidth-heavy action)
- */
-export function getActiveUserRatio(useCase: string): number {
- return findUseCaseConfig(useCase).activeRatio;
-}
-
-/**
- * Estimate monthly bandwidth based on concurrent users and use case
- */
-export function estimateBandwidth(concurrentUsers: number, useCase: string, trafficPattern?: string): BandwidthEstimate {
- const useCaseLower = useCase.toLowerCase();
-
- // Get use case configuration
- const config = findUseCaseConfig(useCase);
- const useCaseCategory = config.category;
-
- // Calculate DAU estimate from concurrent users with use-case-specific multipliers
- const dauMultiplier = config.dauMultiplier;
- const estimatedDauMin = Math.round(concurrentUsers * dauMultiplier.min);
- const estimatedDauMax = Math.round(concurrentUsers * dauMultiplier.max);
- const dailyUniqueVisitors = Math.round((estimatedDauMin + estimatedDauMax) / 2);
- const activeUserRatio = config.activeRatio;
- const activeDau = Math.round(dailyUniqueVisitors * activeUserRatio);
-
- // Traffic pattern adjustment
- let patternMultiplier = 1.0;
- if (trafficPattern === 'spiky') {
- patternMultiplier = 1.5; // Account for peak loads
- } else if (trafficPattern === 'growing') {
- patternMultiplier = 1.3; // Headroom for growth
- }
-
- let dailyBandwidthGB: number;
- let bandwidthModel: string;
-
- // ========== IMPROVED BANDWIDTH MODELS ==========
- // Each use case uses the most appropriate calculation method
-
- switch (useCaseCategory) {
- case 'video': {
- // VIDEO/STREAMING: Bitrate-based model
- const is4K = /4k|uhd|ultra/i.test(useCaseLower);
- const bitrateGBperHour = is4K ? 11.25 : 2.25; // 4K vs HD
- const avgWatchTimeHours = is4K ? 1.0 : 1.5;
- const gbPerActiveUser = bitrateGBperHour * avgWatchTimeHours;
- dailyBandwidthGB = activeDau * gbPerActiveUser * patternMultiplier;
- bandwidthModel = `bitrate-based: ${activeDau} active × ${bitrateGBperHour} GB/hr × ${avgWatchTimeHours}hr`;
- break;
- }
-
- case 'file': {
- // FILE DOWNLOAD: File-size based model
- const isLargeFiles = /iso|video|backup|대용량/.test(useCaseLower);
- const avgFileSizeGB = isLargeFiles ? 2.0 : 0.2;
- const downloadsPerUser = isLargeFiles ? 1 : 3;
- const gbPerActiveUser = avgFileSizeGB * downloadsPerUser;
- dailyBandwidthGB = activeDau * gbPerActiveUser * patternMultiplier;
- bandwidthModel = `file-based: ${activeDau} active × ${avgFileSizeGB} GB × ${downloadsPerUser} downloads`;
- break;
- }
-
- case 'gaming': {
- // GAMING: Session-duration based model
- const isMinecraft = /minecraft|마인크래프트/.test(useCaseLower);
- const mbPerHour = isMinecraft ? 150 : 80;
- const avgSessionHours = isMinecraft ? 3 : 2.5;
- const gbPerActiveUser = (mbPerHour * avgSessionHours) / 1024;
- dailyBandwidthGB = activeDau * gbPerActiveUser * patternMultiplier;
- bandwidthModel = `session-based: ${activeDau} active × ${mbPerHour} MB/hr × ${avgSessionHours}hr`;
- break;
- }
-
- case 'api': {
- // API/SAAS: Request-based model
- const avgRequestKB = 20;
- const requestsPerUserPerDay = 1000;
- const gbPerActiveUser = (avgRequestKB * requestsPerUserPerDay) / (1024 * 1024);
- dailyBandwidthGB = activeDau * gbPerActiveUser * patternMultiplier;
- bandwidthModel = `request-based: ${activeDau} active × ${avgRequestKB}KB × ${requestsPerUserPerDay} req`;
- break;
- }
-
- case 'ecommerce': {
- // E-COMMERCE: Page-based model (images heavy)
- const avgPageSizeMB = 2.5;
- const pagesPerSession = 20;
- const gbPerActiveUser = (avgPageSizeMB * pagesPerSession) / 1024;
- dailyBandwidthGB = activeDau * gbPerActiveUser * patternMultiplier;
- bandwidthModel = `page-based: ${activeDau} active × ${avgPageSizeMB}MB × ${pagesPerSession} pages`;
- break;
- }
-
- case 'forum': {
- // FORUM/COMMUNITY: Page-based model (text + some images)
- const avgPageSizeMB = 0.7;
- const pagesPerSession = 30;
- const gbPerActiveUser = (avgPageSizeMB * pagesPerSession) / 1024;
- dailyBandwidthGB = activeDau * gbPerActiveUser * patternMultiplier;
- bandwidthModel = `page-based: ${activeDau} active × ${avgPageSizeMB}MB × ${pagesPerSession} pages`;
- break;
- }
-
- case 'blog': {
- // STATIC/BLOG: Lightweight page-based model
- const avgPageSizeMB = 1.5;
- const pagesPerSession = 4;
- const gbPerActiveUser = (avgPageSizeMB * pagesPerSession) / 1024;
- dailyBandwidthGB = activeDau * gbPerActiveUser * patternMultiplier;
- bandwidthModel = `page-based: ${activeDau} active × ${avgPageSizeMB}MB × ${pagesPerSession} pages`;
- break;
- }
-
- case 'chat': {
- // CHAT/MESSAGING: Message-based model
- const textBandwidthMB = (3 * 200) / 1024; // 3KB × 200 messages
- const attachmentBandwidthMB = 20; // occasional images/files
- const gbPerActiveUser = (textBandwidthMB + attachmentBandwidthMB) / 1024;
- dailyBandwidthGB = activeDau * gbPerActiveUser * patternMultiplier;
- bandwidthModel = `message-based: ${activeDau} active × ~20MB/user (text+attachments)`;
- break;
- }
-
- default: {
- // DEFAULT: General web app (page-based)
- const avgPageSizeMB = 1.0;
- const pagesPerSession = 10;
- const gbPerActiveUser = (avgPageSizeMB * pagesPerSession) / 1024;
- dailyBandwidthGB = activeDau * gbPerActiveUser * patternMultiplier;
- bandwidthModel = `page-based (default): ${activeDau} active × ${avgPageSizeMB}MB × ${pagesPerSession} pages`;
- break;
- }
- }
-
- console.log(`[Bandwidth] Model: ${bandwidthModel}`);
- console.log(`[Bandwidth] DAU: ${dailyUniqueVisitors} (${dauMultiplier.min}-${dauMultiplier.max}x), Active: ${activeDau} (${(activeUserRatio * 100).toFixed(0)}%), Daily: ${dailyBandwidthGB.toFixed(1)} GB`);
-
- // Monthly bandwidth
- const monthlyGB = dailyBandwidthGB * 30;
- const monthlyTB = monthlyGB / 1024;
-
- // Categorize
- let category: 'light' | 'moderate' | 'heavy' | 'very_heavy';
- let description: string;
-
- if (monthlyTB < 0.5) {
- category = 'light';
- description = `~${Math.round(monthlyGB)} GB/month - Most VPS plans include sufficient bandwidth`;
- } else if (monthlyTB < 2) {
- category = 'moderate';
- description = `~${monthlyTB.toFixed(1)} TB/month - Check provider bandwidth limits`;
- } else if (monthlyTB < 6) {
- category = 'heavy';
- description = `~${monthlyTB.toFixed(1)} TB/month - Prefer providers with generous bandwidth (Linode: 1-6TB included)`;
- } else {
- category = 'very_heavy';
- description = `~${monthlyTB.toFixed(1)} TB/month - HIGH BANDWIDTH: Linode strongly recommended for cost savings`;
- }
-
- return {
- monthly_gb: Math.round(monthlyGB),
- monthly_tb: Math.round(monthlyTB * 10) / 10,
- daily_gb: Math.round(dailyBandwidthGB * 10) / 10,
- category,
- description,
- estimated_dau_min: estimatedDauMin,
- estimated_dau_max: estimatedDauMax,
- active_ratio: activeUserRatio
- };
-}
-
-/**
- * Get provider bandwidth allocation based on memory size
- * Returns included transfer in TB/month
- */
-export function getProviderBandwidthAllocation(providerName: string, memoryGb: number): {
- included_tb: number;
- overage_per_gb: number;
- overage_per_tb: number;
-} {
- const provider = providerName.toLowerCase();
-
- if (provider.includes('linode')) {
- // Linode: roughly 1TB per 1GB RAM (Nanode 1GB = 1TB, 2GB = 2TB, etc.)
- const includedTb = Math.min(Math.max(memoryGb, 1), 20);
- return {
- included_tb: includedTb,
- overage_per_gb: 0.005, // $0.005/GB = $5/TB
- overage_per_tb: 5
- };
- } else if (provider.includes('vultr')) {
- // Vultr: varies by plan, roughly 1-2TB for small, up to 10TB for large
- let includedTb: number;
- if (memoryGb <= 2) includedTb = 1;
- else if (memoryGb <= 4) includedTb = 2;
- else if (memoryGb <= 8) includedTb = 3;
- else if (memoryGb <= 16) includedTb = 4;
- else if (memoryGb <= 32) includedTb = 5;
- else includedTb = Math.min(memoryGb / 4, 10);
-
- return {
- included_tb: includedTb,
- overage_per_gb: 0.01, // $0.01/GB = $10/TB
- overage_per_tb: 10
- };
- } else {
- // Default/Other providers: conservative estimate
- return {
- included_tb: Math.min(memoryGb, 5),
- overage_per_gb: 0.01,
- overage_per_tb: 10
- };
- }
-}
-
-/**
- * Calculate bandwidth cost info for a server
- * Uses actual DB values from anvil_transfer_pricing when available
- * @param server Server object
- * @param bandwidthEstimate Bandwidth estimate
- * @param lang Language code (ko = KRW, others = USD)
- * @param exchangeRate Exchange rate (USD to KRW)
- */
-export function calculateBandwidthInfo(
- server: import('./types').Server,
- bandwidthEstimate: BandwidthEstimate,
- lang: string = 'en',
- exchangeRate: number = 1
-): BandwidthInfo {
- // Use actual DB values if available (Anvil servers), fallback to provider-based estimation
- let includedTb: number;
- let overagePerGbUsd: number;
- let overagePerTbUsd: number;
-
- if (server.transfer_tb !== null && server.transfer_price_per_gb !== null) {
- // Use actual values from anvil_instances + anvil_transfer_pricing
- includedTb = server.transfer_tb;
- overagePerGbUsd = server.transfer_price_per_gb;
- overagePerTbUsd = server.transfer_price_per_gb * 1024;
- } else {
- // Fallback to provider-based estimation for non-Anvil servers
- const allocation = getProviderBandwidthAllocation(server.provider_name, server.memory_gb);
- includedTb = allocation.included_tb;
- overagePerGbUsd = allocation.overage_per_gb;
- overagePerTbUsd = allocation.overage_per_tb;
- }
-
- const estimatedTb = bandwidthEstimate.monthly_tb;
- const overageTb = Math.max(0, estimatedTb - includedTb);
- const overageCostUsd = overageTb * overagePerTbUsd;
-
- // Get server price in USD for total calculation
- const serverPriceUsd = server.currency === 'KRW'
- ? server.monthly_price / exchangeRate
- : server.monthly_price;
-
- const totalCostUsd = serverPriceUsd + overageCostUsd;
-
- // Convert to KRW if Korean language, round to nearest 100
- const isKorean = lang === 'ko';
- const currency: 'USD' | 'KRW' = isKorean ? 'KRW' : 'USD';
-
- // KRW: GB당은 1원 단위, TB당/총 비용은 100원 단위 반올림
- const roundKrw100 = (usd: number) => Math.round((usd * exchangeRate) / 100) * 100;
- const toKrw = (usd: number) => Math.round(usd * exchangeRate);
-
- const overagePerGb = isKorean ? toKrw(overagePerGbUsd) : overagePerGbUsd;
- const overagePerTb = isKorean ? roundKrw100(overagePerTbUsd) : overagePerTbUsd;
- const overageCost = isKorean ? roundKrw100(overageCostUsd) : Math.round(overageCostUsd * 100) / 100;
- const totalCost = isKorean ? roundKrw100(totalCostUsd) : Math.round(totalCostUsd * 100) / 100;
-
- let warning: string | undefined;
- if (overageTb > includedTb) {
- const costStr = isKorean ? `₩${overageCost.toLocaleString()}` : `$${overageCost.toFixed(0)}`;
- warning = `⚠️ 예상 트래픽(${estimatedTb.toFixed(1)}TB)이 기본 포함량(${includedTb}TB)의 2배 이상입니다. 상위 플랜을 고려하세요.`;
- } else if (overageTb > 0) {
- const costStr = isKorean ? `₩${overageCost.toLocaleString()}` : `$${overageCost.toFixed(0)}`;
- warning = isKorean
- ? `예상 초과 트래픽: ${overageTb.toFixed(1)}TB (추가 비용 ~${costStr}/월)`
- : `예상 초과 트래픽: ${overageTb.toFixed(1)}TB (추가 비용 ~${costStr}/월)`;
- }
-
- return {
- included_transfer_tb: includedTb,
- overage_cost_per_gb: isKorean ? Math.round(overagePerGb) : Math.round(overagePerGb * 10000) / 10000,
- overage_cost_per_tb: isKorean ? Math.round(overagePerTb) : Math.round(overagePerTb * 100) / 100,
- estimated_monthly_tb: Math.round(estimatedTb * 10) / 10,
- estimated_overage_tb: Math.round(overageTb * 10) / 10,
- estimated_overage_cost: overageCost,
- total_estimated_cost: totalCost,
- currency,
- warning
- };
-}
-
-/**
- * Sanitize user input for AI prompts to prevent prompt injection
- */
-export function sanitizeForAIPrompt(input: string, maxLength: number = 200): string {
- // 1. Normalize Unicode (NFKC form collapses homoglyphs)
- let sanitized = input.normalize('NFKC');
-
- // 2. Remove zero-width characters
- sanitized = sanitized.replace(/[\u200B-\u200D\uFEFF\u00AD]/g, '');
-
- // 3. Expanded blocklist patterns
- const dangerousPatterns = [
- /ignore\s*(all|previous|above)?\s*instruction/gi,
- /system\s*prompt/gi,
- /you\s*are\s*(now|a)/gi,
- /pretend\s*(to\s*be|you)/gi,
- /act\s*as/gi,
- /disregard/gi,
- /forget\s*(everything|all|previous)/gi,
- /new\s*instruction/gi,
- /override/gi,
- /\[system\]/gi,
- /<\|im_start\|>/gi,
- /<\|im_end\|>/gi,
- /```[\s\S]*?```/g, // Code blocks that might contain injection
- /"""/g, // Triple quotes
- /---+/g, // Horizontal rules/delimiters
- ];
-
- for (const pattern of dangerousPatterns) {
- sanitized = sanitized.replace(pattern, '[filtered]');
- }
-
- return sanitized.slice(0, maxLength);
-}
-
-/**
- * Exchange rate constants
- */
-const EXCHANGE_RATE_CACHE_KEY = 'exchange_rate:USD_KRW';
-const EXCHANGE_RATE_TTL_SECONDS = 3600; // 1 hour
-const EXCHANGE_RATE_FALLBACK = 1450; // Fallback KRW rate if API fails
-
-/**
- * Get USD to KRW exchange rate with KV caching
- * Uses open.er-api.com free API
- */
-export async function getExchangeRate(env: Env): Promise {
- // Try to get cached rate from KV
- if (env.CACHE) {
- try {
- const cached = await env.CACHE.get(EXCHANGE_RATE_CACHE_KEY);
- if (cached) {
- const data = JSON.parse(cached) as ExchangeRateCache;
- console.log(`[ExchangeRate] Using cached rate: ${data.rate}`);
- return data.rate;
- }
- } catch (error) {
- console.warn('[ExchangeRate] Cache read error:', error);
- }
- }
-
- // Fetch fresh rate from API
- try {
- const controller = new AbortController();
- const timeoutId = setTimeout(() => controller.abort(), 5000); // 5 second timeout
-
- const response = await fetch('https://open.er-api.com/v6/latest/USD', {
- headers: { 'Accept': 'application/json' },
- signal: controller.signal,
- });
-
- clearTimeout(timeoutId);
-
- if (!response.ok) {
- throw new Error(`API returned ${response.status}`);
- }
-
- const data = await response.json() as { rates?: { KRW?: number } };
- const rate = data?.rates?.KRW;
-
- if (!rate || typeof rate !== 'number' || rate < 1000 || rate > 2000) {
- console.warn('[ExchangeRate] Invalid rate from API:', rate);
- return EXCHANGE_RATE_FALLBACK;
- }
-
- console.log(`[ExchangeRate] Fetched fresh rate: ${rate}`);
-
- // Cache the rate
- if (env.CACHE) {
- try {
- const cacheData: ExchangeRateCache = {
- rate,
- timestamp: Date.now(),
- };
- await env.CACHE.put(EXCHANGE_RATE_CACHE_KEY, JSON.stringify(cacheData), {
- expirationTtl: EXCHANGE_RATE_TTL_SECONDS,
- });
- } catch (error) {
- console.warn('[ExchangeRate] Cache write error:', error);
- }
- }
-
- return rate;
- } catch (error) {
- if (error instanceof Error && error.name === 'AbortError') {
- console.warn('[ExchangeRate] Request timed out, using fallback');
- } else {
- console.error('[ExchangeRate] API error:', error);
- }
- return EXCHANGE_RATE_FALLBACK;
- }
-}
-
-// In-memory fallback for rate limiting when CACHE KV is unavailable
-const inMemoryRateLimit = new Map();
-
-/**
- * Rate limiting check using KV storage with in-memory fallback
- */
-export async function checkRateLimit(clientIP: string, env: import('./types').Env): Promise<{ allowed: boolean; requestId: string }> {
- const requestId = crypto.randomUUID();
- const now = Date.now();
- const maxRequests = LIMITS.RATE_LIMIT_MAX_REQUESTS;
- const windowMs = LIMITS.RATE_LIMIT_WINDOW_MS;
-
- // Use in-memory fallback if CACHE unavailable
- if (!env.CACHE) {
- const record = inMemoryRateLimit.get(clientIP);
-
- if (!record || record.resetTime < now) {
- // New window or expired
- inMemoryRateLimit.set(clientIP, { count: 1, resetTime: now + windowMs });
- return { allowed: true, requestId };
- }
-
- if (record.count >= maxRequests) {
- return { allowed: false, requestId };
- }
-
- // Increment count
- record.count++;
- return { allowed: true, requestId };
- }
-
- // KV-based rate limiting
- const kvKey = `ratelimit:${clientIP}`;
-
- try {
- const recordJson = await env.CACHE.get(kvKey);
- const record = recordJson ? JSON.parse(recordJson) as { count: number; resetTime: number } : null;
-
- if (!record || record.resetTime < now) {
- // New window
- await env.CACHE.put(
- kvKey,
- JSON.stringify({ count: 1, resetTime: now + windowMs }),
- { expirationTtl: 60 }
- );
- return { allowed: true, requestId };
- }
-
- if (record.count >= maxRequests) {
- return { allowed: false, requestId };
- }
-
- // Increment count
- record.count++;
- await env.CACHE.put(
- kvKey,
- JSON.stringify(record),
- { expirationTtl: 60 }
- );
- return { allowed: true, requestId };
- } catch (error) {
- console.error('[RateLimit] KV error:', error);
- // On error, deny the request (fail closed) for security
- return { allowed: false, requestId };
- }
-}
+export * from './utils/index';
diff --git a/src/utils/ai.ts b/src/utils/ai.ts
new file mode 100644
index 0000000..6acbd94
--- /dev/null
+++ b/src/utils/ai.ts
@@ -0,0 +1,39 @@
+/**
+ * AI utility functions
+ */
+
+/**
+ * Sanitize user input for AI prompts to prevent prompt injection
+ */
+export function sanitizeForAIPrompt(input: string, maxLength: number = 200): string {
+ // 1. Normalize Unicode (NFKC form collapses homoglyphs)
+ let sanitized = input.normalize('NFKC');
+
+ // 2. Remove zero-width characters
+ sanitized = sanitized.replace(/[\u200B-\u200D\uFEFF\u00AD]/g, '');
+
+ // 3. Expanded blocklist patterns
+ const dangerousPatterns = [
+ /ignore\s*(all|previous|above)?\s*instruction/gi,
+ /system\s*prompt/gi,
+ /you\s*are\s*(now|a)/gi,
+ /pretend\s*(to\s*be|you)/gi,
+ /act\s*as/gi,
+ /disregard/gi,
+ /forget\s*(everything|all|previous)/gi,
+ /new\s*instruction/gi,
+ /override/gi,
+ /\[system\]/gi,
+ /<\|im_start\|>/gi,
+ /<\|im_end\|>/gi,
+ /```[\s\S]*?```/g, // Code blocks that might contain injection
+ /"""/g, // Triple quotes
+ /---+/g, // Horizontal rules/delimiters
+ ];
+
+ for (const pattern of dangerousPatterns) {
+ sanitized = sanitized.replace(pattern, '[filtered]');
+ }
+
+ return sanitized.slice(0, maxLength);
+}
diff --git a/src/utils/bandwidth.ts b/src/utils/bandwidth.ts
new file mode 100644
index 0000000..2b258a1
--- /dev/null
+++ b/src/utils/bandwidth.ts
@@ -0,0 +1,329 @@
+/**
+ * Bandwidth estimation utility functions
+ */
+
+import type { BandwidthEstimate, BandwidthInfo, UseCaseConfig } from '../types';
+import { USE_CASE_CONFIGS } from '../config';
+
+/**
+ * Find use case configuration by matching patterns
+ */
+export function findUseCaseConfig(useCase: string): UseCaseConfig {
+ const useCaseLower = useCase.toLowerCase();
+
+ for (const config of USE_CASE_CONFIGS) {
+ if (config.patterns.test(useCaseLower)) {
+ return config;
+ }
+ }
+
+ // Default configuration
+ return {
+ category: 'default',
+ patterns: /.*/,
+ dauMultiplier: { min: 10, max: 14 },
+ activeRatio: 0.5
+ };
+}
+
+/**
+ * Get DAU multiplier based on use case (how many daily active users per concurrent user)
+ */
+export function getDauMultiplier(useCase: string): { min: number; max: number } {
+ return findUseCaseConfig(useCase).dauMultiplier;
+}
+
+/**
+ * Get active user ratio (what percentage of DAU actually performs the bandwidth-heavy action)
+ */
+export function getActiveUserRatio(useCase: string): number {
+ return findUseCaseConfig(useCase).activeRatio;
+}
+
+/**
+ * Estimate monthly bandwidth based on concurrent users and use case
+ */
+export function estimateBandwidth(concurrentUsers: number, useCase: string, trafficPattern?: string): BandwidthEstimate {
+ const useCaseLower = useCase.toLowerCase();
+
+ // Get use case configuration
+ const config = findUseCaseConfig(useCase);
+ const useCaseCategory = config.category;
+
+ // Calculate DAU estimate from concurrent users with use-case-specific multipliers
+ const dauMultiplier = config.dauMultiplier;
+ const estimatedDauMin = Math.round(concurrentUsers * dauMultiplier.min);
+ const estimatedDauMax = Math.round(concurrentUsers * dauMultiplier.max);
+ const dailyUniqueVisitors = Math.round((estimatedDauMin + estimatedDauMax) / 2);
+ const activeUserRatio = config.activeRatio;
+ const activeDau = Math.round(dailyUniqueVisitors * activeUserRatio);
+
+ // Traffic pattern adjustment
+ let patternMultiplier = 1.0;
+ if (trafficPattern === 'spiky') {
+ patternMultiplier = 1.5; // Account for peak loads
+ } else if (trafficPattern === 'growing') {
+ patternMultiplier = 1.3; // Headroom for growth
+ }
+
+ let dailyBandwidthGB: number;
+ let bandwidthModel: string;
+
+ // ========== IMPROVED BANDWIDTH MODELS ==========
+ // Each use case uses the most appropriate calculation method
+
+ switch (useCaseCategory) {
+ case 'video': {
+ // VIDEO/STREAMING: Bitrate-based model
+ const is4K = /4k|uhd|ultra/i.test(useCaseLower);
+ const bitrateGBperHour = is4K ? 11.25 : 2.25; // 4K vs HD
+ const avgWatchTimeHours = is4K ? 1.0 : 1.5;
+ const gbPerActiveUser = bitrateGBperHour * avgWatchTimeHours;
+ dailyBandwidthGB = activeDau * gbPerActiveUser * patternMultiplier;
+ bandwidthModel = `bitrate-based: ${activeDau} active × ${bitrateGBperHour} GB/hr × ${avgWatchTimeHours}hr`;
+ break;
+ }
+
+ case 'file': {
+ // FILE DOWNLOAD: File-size based model
+ const isLargeFiles = /iso|video|backup|대용량/.test(useCaseLower);
+ const avgFileSizeGB = isLargeFiles ? 2.0 : 0.2;
+ const downloadsPerUser = isLargeFiles ? 1 : 3;
+ const gbPerActiveUser = avgFileSizeGB * downloadsPerUser;
+ dailyBandwidthGB = activeDau * gbPerActiveUser * patternMultiplier;
+ bandwidthModel = `file-based: ${activeDau} active × ${avgFileSizeGB} GB × ${downloadsPerUser} downloads`;
+ break;
+ }
+
+ case 'gaming': {
+ // GAMING: Session-duration based model
+ const isMinecraft = /minecraft|마인크래프트/.test(useCaseLower);
+ const mbPerHour = isMinecraft ? 150 : 80;
+ const avgSessionHours = isMinecraft ? 3 : 2.5;
+ const gbPerActiveUser = (mbPerHour * avgSessionHours) / 1024;
+ dailyBandwidthGB = activeDau * gbPerActiveUser * patternMultiplier;
+ bandwidthModel = `session-based: ${activeDau} active × ${mbPerHour} MB/hr × ${avgSessionHours}hr`;
+ break;
+ }
+
+ case 'api': {
+ // API/SAAS: Request-based model
+ const avgRequestKB = 20;
+ const requestsPerUserPerDay = 1000;
+ const gbPerActiveUser = (avgRequestKB * requestsPerUserPerDay) / (1024 * 1024);
+ dailyBandwidthGB = activeDau * gbPerActiveUser * patternMultiplier;
+ bandwidthModel = `request-based: ${activeDau} active × ${avgRequestKB}KB × ${requestsPerUserPerDay} req`;
+ break;
+ }
+
+ case 'ecommerce': {
+ // E-COMMERCE: Page-based model (images heavy)
+ const avgPageSizeMB = 2.5;
+ const pagesPerSession = 20;
+ const gbPerActiveUser = (avgPageSizeMB * pagesPerSession) / 1024;
+ dailyBandwidthGB = activeDau * gbPerActiveUser * patternMultiplier;
+ bandwidthModel = `page-based: ${activeDau} active × ${avgPageSizeMB}MB × ${pagesPerSession} pages`;
+ break;
+ }
+
+ case 'forum': {
+ // FORUM/COMMUNITY: Page-based model (text + some images)
+ const avgPageSizeMB = 0.7;
+ const pagesPerSession = 30;
+ const gbPerActiveUser = (avgPageSizeMB * pagesPerSession) / 1024;
+ dailyBandwidthGB = activeDau * gbPerActiveUser * patternMultiplier;
+ bandwidthModel = `page-based: ${activeDau} active × ${avgPageSizeMB}MB × ${pagesPerSession} pages`;
+ break;
+ }
+
+ case 'blog': {
+ // STATIC/BLOG: Lightweight page-based model
+ const avgPageSizeMB = 1.5;
+ const pagesPerSession = 4;
+ const gbPerActiveUser = (avgPageSizeMB * pagesPerSession) / 1024;
+ dailyBandwidthGB = activeDau * gbPerActiveUser * patternMultiplier;
+ bandwidthModel = `page-based: ${activeDau} active × ${avgPageSizeMB}MB × ${pagesPerSession} pages`;
+ break;
+ }
+
+ case 'chat': {
+ // CHAT/MESSAGING: Message-based model
+ const textBandwidthMB = (3 * 200) / 1024; // 3KB × 200 messages
+ const attachmentBandwidthMB = 20; // occasional images/files
+ const gbPerActiveUser = (textBandwidthMB + attachmentBandwidthMB) / 1024;
+ dailyBandwidthGB = activeDau * gbPerActiveUser * patternMultiplier;
+ bandwidthModel = `message-based: ${activeDau} active × ~20MB/user (text+attachments)`;
+ break;
+ }
+
+ default: {
+ // DEFAULT: General web app (page-based)
+ const avgPageSizeMB = 1.0;
+ const pagesPerSession = 10;
+ const gbPerActiveUser = (avgPageSizeMB * pagesPerSession) / 1024;
+ dailyBandwidthGB = activeDau * gbPerActiveUser * patternMultiplier;
+ bandwidthModel = `page-based (default): ${activeDau} active × ${avgPageSizeMB}MB × ${pagesPerSession} pages`;
+ break;
+ }
+ }
+
+ console.log(`[Bandwidth] Model: ${bandwidthModel}`);
+ console.log(`[Bandwidth] DAU: ${dailyUniqueVisitors} (${dauMultiplier.min}-${dauMultiplier.max}x), Active: ${activeDau} (${(activeUserRatio * 100).toFixed(0)}%), Daily: ${dailyBandwidthGB.toFixed(1)} GB`);
+
+ // Monthly bandwidth
+ const monthlyGB = dailyBandwidthGB * 30;
+ const monthlyTB = monthlyGB / 1024;
+
+ // Categorize
+ let category: 'light' | 'moderate' | 'heavy' | 'very_heavy';
+ let description: string;
+
+ if (monthlyTB < 0.5) {
+ category = 'light';
+ description = `~${Math.round(monthlyGB)} GB/month - Most VPS plans include sufficient bandwidth`;
+ } else if (monthlyTB < 2) {
+ category = 'moderate';
+ description = `~${monthlyTB.toFixed(1)} TB/month - Check provider bandwidth limits`;
+ } else if (monthlyTB < 6) {
+ category = 'heavy';
+ description = `~${monthlyTB.toFixed(1)} TB/month - Prefer providers with generous bandwidth (Linode: 1-6TB included)`;
+ } else {
+ category = 'very_heavy';
+ description = `~${monthlyTB.toFixed(1)} TB/month - HIGH BANDWIDTH: Linode strongly recommended for cost savings`;
+ }
+
+ return {
+ monthly_gb: Math.round(monthlyGB),
+ monthly_tb: Math.round(monthlyTB * 10) / 10,
+ daily_gb: Math.round(dailyBandwidthGB * 10) / 10,
+ category,
+ description,
+ estimated_dau_min: estimatedDauMin,
+ estimated_dau_max: estimatedDauMax,
+ active_ratio: activeUserRatio
+ };
+}
+
+/**
+ * Get provider bandwidth allocation based on memory size
+ * Returns included transfer in TB/month
+ */
+export function getProviderBandwidthAllocation(providerName: string, memoryGb: number): {
+ included_tb: number;
+ overage_per_gb: number;
+ overage_per_tb: number;
+} {
+ const provider = providerName.toLowerCase();
+
+ if (provider.includes('linode')) {
+ // Linode: roughly 1TB per 1GB RAM (Nanode 1GB = 1TB, 2GB = 2TB, etc.)
+ const includedTb = Math.min(Math.max(memoryGb, 1), 20);
+ return {
+ included_tb: includedTb,
+ overage_per_gb: 0.005, // $0.005/GB = $5/TB
+ overage_per_tb: 5
+ };
+ } else if (provider.includes('vultr')) {
+ // Vultr: varies by plan, roughly 1-2TB for small, up to 10TB for large
+ let includedTb: number;
+ if (memoryGb <= 2) includedTb = 1;
+ else if (memoryGb <= 4) includedTb = 2;
+ else if (memoryGb <= 8) includedTb = 3;
+ else if (memoryGb <= 16) includedTb = 4;
+ else if (memoryGb <= 32) includedTb = 5;
+ else includedTb = Math.min(memoryGb / 4, 10);
+
+ return {
+ included_tb: includedTb,
+ overage_per_gb: 0.01, // $0.01/GB = $10/TB
+ overage_per_tb: 10
+ };
+ } else {
+ // Default/Other providers: conservative estimate
+ return {
+ included_tb: Math.min(memoryGb, 5),
+ overage_per_gb: 0.01,
+ overage_per_tb: 10
+ };
+ }
+}
+
+/**
+ * Calculate bandwidth cost info for a server
+ * Uses actual DB values from anvil_transfer_pricing when available
+ * @param server Server object
+ * @param bandwidthEstimate Bandwidth estimate
+ * @param lang Language code (ko = KRW, others = USD)
+ * @param exchangeRate Exchange rate (USD to KRW)
+ */
+export function calculateBandwidthInfo(
+ server: import('../types').Server,
+ bandwidthEstimate: BandwidthEstimate,
+ lang: string = 'en',
+ exchangeRate: number = 1
+): BandwidthInfo {
+ // Use actual DB values if available (Anvil servers), fallback to provider-based estimation
+ let includedTb: number;
+ let overagePerGbUsd: number;
+ let overagePerTbUsd: number;
+
+ if (server.transfer_tb !== null && server.transfer_price_per_gb !== null) {
+ // Use actual values from anvil_instances + anvil_transfer_pricing
+ includedTb = server.transfer_tb;
+ overagePerGbUsd = server.transfer_price_per_gb;
+ overagePerTbUsd = server.transfer_price_per_gb * 1024;
+ } else {
+ // Fallback to provider-based estimation for non-Anvil servers
+ const allocation = getProviderBandwidthAllocation(server.provider_name, server.memory_gb);
+ includedTb = allocation.included_tb;
+ overagePerGbUsd = allocation.overage_per_gb;
+ overagePerTbUsd = allocation.overage_per_tb;
+ }
+
+ const estimatedTb = bandwidthEstimate.monthly_tb;
+ const overageTb = Math.max(0, estimatedTb - includedTb);
+ const overageCostUsd = overageTb * overagePerTbUsd;
+
+ // Get server price in USD for total calculation
+ const serverPriceUsd = server.currency === 'KRW'
+ ? server.monthly_price / exchangeRate
+ : server.monthly_price;
+
+ const totalCostUsd = serverPriceUsd + overageCostUsd;
+
+ // Convert to KRW if Korean language, round to nearest 100
+ const isKorean = lang === 'ko';
+ const currency: 'USD' | 'KRW' = isKorean ? 'KRW' : 'USD';
+
+ // KRW: GB당은 1원 단위, TB당/총 비용은 100원 단위 반올림
+ const roundKrw100 = (usd: number) => Math.round((usd * exchangeRate) / 100) * 100;
+ const toKrw = (usd: number) => Math.round(usd * exchangeRate);
+
+ const overagePerGb = isKorean ? toKrw(overagePerGbUsd) : overagePerGbUsd;
+ const overagePerTb = isKorean ? roundKrw100(overagePerTbUsd) : overagePerTbUsd;
+ const overageCost = isKorean ? roundKrw100(overageCostUsd) : Math.round(overageCostUsd * 100) / 100;
+ const totalCost = isKorean ? roundKrw100(totalCostUsd) : Math.round(totalCostUsd * 100) / 100;
+
+ let warning: string | undefined;
+ if (overageTb > includedTb) {
+ const costStr = isKorean ? `₩${overageCost.toLocaleString()}` : `$${overageCost.toFixed(0)}`;
+ warning = `⚠️ 예상 트래픽(${estimatedTb.toFixed(1)}TB)이 기본 포함량(${includedTb}TB)의 2배 이상입니다. 상위 플랜을 고려하세요.`;
+ } else if (overageTb > 0) {
+ const costStr = isKorean ? `₩${overageCost.toLocaleString()}` : `$${overageCost.toFixed(0)}`;
+ warning = isKorean
+ ? `예상 초과 트래픽: ${overageTb.toFixed(1)}TB (추가 비용 ~${costStr}/월)`
+ : `예상 초과 트래픽: ${overageTb.toFixed(1)}TB (추가 비용 ~${costStr}/월)`;
+ }
+
+ return {
+ included_transfer_tb: includedTb,
+ overage_cost_per_gb: isKorean ? Math.round(overagePerGb) : Math.round(overagePerGb * 10000) / 10000,
+ overage_cost_per_tb: isKorean ? Math.round(overagePerTb) : Math.round(overagePerTb * 100) / 100,
+ estimated_monthly_tb: Math.round(estimatedTb * 10) / 10,
+ estimated_overage_tb: Math.round(overageTb * 10) / 10,
+ estimated_overage_cost: overageCost,
+ total_estimated_cost: totalCost,
+ currency,
+ warning
+ };
+}
diff --git a/src/utils/cache.ts b/src/utils/cache.ts
new file mode 100644
index 0000000..aa013eb
--- /dev/null
+++ b/src/utils/cache.ts
@@ -0,0 +1,140 @@
+/**
+ * Cache and rate limiting utility functions
+ */
+
+import type { RecommendRequest, Env } from '../types';
+import { LIMITS } from '../config';
+
+/**
+ * Simple hash function for strings
+ */
+export function hashString(str: string): string {
+ let hash = 0;
+ for (let i = 0; i < str.length; i++) {
+ const char = str.charCodeAt(i);
+ hash = ((hash << 5) - hash) + char;
+ hash = hash & hash; // Convert to 32-bit integer
+ }
+ // Use >>> 0 to convert to unsigned 32-bit integer
+ return (hash >>> 0).toString(36);
+}
+
+/**
+ * Sanitize special characters for cache key
+ */
+export function sanitizeCacheValue(value: string): string {
+ // Use URL-safe base64 encoding to avoid collisions
+ try {
+ return btoa(value).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+ } catch {
+ // Fallback for non-ASCII characters
+ return encodeURIComponent(value).replace(/[%]/g, '_');
+ }
+}
+
+/**
+ * Generate cache key from request parameters
+ */
+export function generateCacheKey(req: RecommendRequest): string {
+ // Don't mutate original arrays - create sorted copies
+ const sortedStack = [...req.tech_stack].sort();
+ const sanitizedStack = sortedStack.map(sanitizeCacheValue).join(',');
+
+ // Hash use_case to avoid special characters and length issues
+ const useCaseHash = hashString(req.use_case);
+
+ const parts = [
+ `stack:${sanitizedStack}`,
+ `users:${req.expected_users}`,
+ `case:${useCaseHash}`,
+ ];
+
+ if (req.traffic_pattern) {
+ parts.push(`traffic:${req.traffic_pattern}`);
+ }
+
+ if (req.budget_limit) {
+ parts.push(`budget:${req.budget_limit}`);
+ }
+
+ // Include region preference in cache key
+ if (req.region_preference && req.region_preference.length > 0) {
+ const sortedRegions = [...req.region_preference].sort();
+ const sanitizedRegions = sortedRegions.map(sanitizeCacheValue).join(',');
+ parts.push(`region:${sanitizedRegions}`);
+ }
+
+ // Include language in cache key
+ if (req.lang) {
+ parts.push(`lang:${req.lang}`);
+ }
+
+ return `recommend:${parts.join('|')}`;
+}
+
+// In-memory fallback for rate limiting when CACHE KV is unavailable
+const inMemoryRateLimit = new Map();
+
+/**
+ * Rate limiting check using KV storage with in-memory fallback
+ */
+export async function checkRateLimit(clientIP: string, env: Env): Promise<{ allowed: boolean; requestId: string }> {
+ const requestId = crypto.randomUUID();
+ const now = Date.now();
+ const maxRequests = LIMITS.RATE_LIMIT_MAX_REQUESTS;
+ const windowMs = LIMITS.RATE_LIMIT_WINDOW_MS;
+
+ // Use in-memory fallback if CACHE unavailable
+ if (!env.CACHE) {
+ const record = inMemoryRateLimit.get(clientIP);
+
+ if (!record || record.resetTime < now) {
+ // New window or expired
+ inMemoryRateLimit.set(clientIP, { count: 1, resetTime: now + windowMs });
+ return { allowed: true, requestId };
+ }
+
+ if (record.count >= maxRequests) {
+ return { allowed: false, requestId };
+ }
+
+ // Increment count
+ record.count++;
+ return { allowed: true, requestId };
+ }
+
+ // KV-based rate limiting
+ const kvKey = `ratelimit:${clientIP}`;
+
+ try {
+ const recordJson = await env.CACHE.get(kvKey);
+ const record = recordJson ? JSON.parse(recordJson) as { count: number; resetTime: number } : null;
+
+ if (!record || record.resetTime < now) {
+ // New window
+ await env.CACHE.put(
+ kvKey,
+ JSON.stringify({ count: 1, resetTime: now + windowMs }),
+ { expirationTtl: 60 }
+ );
+ return { allowed: true, requestId };
+ }
+
+ if (record.count >= maxRequests) {
+ return { allowed: false, requestId };
+ }
+
+ // Increment count
+ record.count++;
+ await env.CACHE.put(
+ kvKey,
+ JSON.stringify(record),
+ { expirationTtl: 60 }
+ );
+ return { allowed: true, requestId };
+ } catch (error) {
+ console.error('[RateLimit] KV error:', error);
+ // On error, deny the request (fail closed) for security
+ return { allowed: false, requestId };
+ }
+}
diff --git a/src/utils/exchange-rate.ts b/src/utils/exchange-rate.ts
new file mode 100644
index 0000000..fde2599
--- /dev/null
+++ b/src/utils/exchange-rate.ts
@@ -0,0 +1,83 @@
+/**
+ * Exchange rate utility functions
+ */
+
+import type { Env, ExchangeRateCache } from '../types';
+
+/**
+ * Exchange rate constants
+ */
+const EXCHANGE_RATE_CACHE_KEY = 'exchange_rate:USD_KRW';
+const EXCHANGE_RATE_TTL_SECONDS = 3600; // 1 hour
+export const EXCHANGE_RATE_FALLBACK = 1450; // Fallback KRW rate if API fails
+
+/**
+ * Get USD to KRW exchange rate with KV caching
+ * Uses open.er-api.com free API
+ */
+export async function getExchangeRate(env: Env): Promise {
+ // Try to get cached rate from KV
+ if (env.CACHE) {
+ try {
+ const cached = await env.CACHE.get(EXCHANGE_RATE_CACHE_KEY);
+ if (cached) {
+ const data = JSON.parse(cached) as ExchangeRateCache;
+ console.log(`[ExchangeRate] Using cached rate: ${data.rate}`);
+ return data.rate;
+ }
+ } catch (error) {
+ console.warn('[ExchangeRate] Cache read error:', error);
+ }
+ }
+
+ // Fetch fresh rate from API
+ try {
+ const controller = new AbortController();
+ const timeoutId = setTimeout(() => controller.abort(), 5000); // 5 second timeout
+
+ const response = await fetch('https://open.er-api.com/v6/latest/USD', {
+ headers: { 'Accept': 'application/json' },
+ signal: controller.signal,
+ });
+
+ clearTimeout(timeoutId);
+
+ if (!response.ok) {
+ throw new Error(`API returned ${response.status}`);
+ }
+
+ const data = await response.json() as { rates?: { KRW?: number } };
+ const rate = data?.rates?.KRW;
+
+ if (!rate || typeof rate !== 'number' || rate < 1000 || rate > 2000) {
+ console.warn('[ExchangeRate] Invalid rate from API:', rate);
+ return EXCHANGE_RATE_FALLBACK;
+ }
+
+ console.log(`[ExchangeRate] Fetched fresh rate: ${rate}`);
+
+ // Cache the rate
+ if (env.CACHE) {
+ try {
+ const cacheData: ExchangeRateCache = {
+ rate,
+ timestamp: Date.now(),
+ };
+ await env.CACHE.put(EXCHANGE_RATE_CACHE_KEY, JSON.stringify(cacheData), {
+ expirationTtl: EXCHANGE_RATE_TTL_SECONDS,
+ });
+ } catch (error) {
+ console.warn('[ExchangeRate] Cache write error:', error);
+ }
+ }
+
+ return rate;
+ } catch (error) {
+ if (error instanceof Error && error.name === 'AbortError') {
+ console.warn('[ExchangeRate] Request timed out, using fallback');
+ } else {
+ console.error('[ExchangeRate] API error:', error);
+ }
+ return EXCHANGE_RATE_FALLBACK;
+ }
+}
diff --git a/src/utils/http.ts b/src/utils/http.ts
new file mode 100644
index 0000000..19640a1
--- /dev/null
+++ b/src/utils/http.ts
@@ -0,0 +1,63 @@
+/**
+ * HTTP utility functions
+ */
+
+/**
+ * Escape HTML special characters to prevent XSS
+ */
+export function escapeHtml(unsafe: string): string {
+ return unsafe
+ .replace(/&/g, "&")
+ .replace(//g, ">")
+ .replace(/"/g, """)
+ .replace(/'/g, "'");
+}
+
+/**
+ * JSON response helper
+ */
+export function jsonResponse(
+ data: T,
+ status: number,
+ headers: Record = {}
+): Response {
+ return new Response(JSON.stringify(data), {
+ status,
+ headers: {
+ 'Content-Type': 'application/json',
+ 'Content-Security-Policy': "default-src 'none'",
+ 'X-Content-Type-Options': 'nosniff',
+ 'X-Frame-Options': 'DENY',
+ 'Strict-Transport-Security': 'max-age=31536000; includeSubDomains',
+ 'Cache-Control': 'no-store',
+ ...headers,
+ },
+ });
+}
+
+/**
+ * Helper function to get allowed CORS origin
+ */
+export function getAllowedOrigin(request: Request): string {
+ const allowedOrigins = [
+ 'https://server-recommend.kappa-d8e.workers.dev',
+ ];
+ const origin = request.headers.get('Origin');
+
+ // If Origin is provided and matches allowed list, return it
+ if (origin && allowedOrigins.includes(origin)) {
+ return origin;
+ }
+
+ // For requests without Origin (non-browser: curl, API clients, server-to-server)
+ // Return empty string - CORS headers won't be sent but request is still processed
+ // This is safe because CORS only affects browser requests
+ if (!origin) {
+ return '';
+ }
+
+ // Origin provided but not in allowed list - return first allowed origin
+ // Browser will block the response due to CORS mismatch
+ return allowedOrigins[0];
+}
diff --git a/src/utils/index.ts b/src/utils/index.ts
new file mode 100644
index 0000000..046b8bd
--- /dev/null
+++ b/src/utils/index.ts
@@ -0,0 +1,59 @@
+/**
+ * Central export point for all utility functions
+ * Organized by domain responsibility
+ */
+
+// HTTP utilities (responses, CORS, XSS protection)
+export {
+ escapeHtml,
+ jsonResponse,
+ getAllowedOrigin
+} from './http';
+
+// Validation utilities (type guards, request validation)
+export {
+ isValidServer,
+ isValidVPSBenchmark,
+ isValidTechSpec,
+ isValidBenchmarkData,
+ isValidAIRecommendation,
+ validateRecommendRequest
+} from './validation';
+
+// Bandwidth estimation utilities
+export {
+ findUseCaseConfig,
+ getDauMultiplier,
+ getActiveUserRatio,
+ estimateBandwidth,
+ getProviderBandwidthAllocation,
+ calculateBandwidthInfo
+} from './bandwidth';
+
+// Cache and rate limiting utilities
+export {
+ hashString,
+ sanitizeCacheValue,
+ generateCacheKey,
+ checkRateLimit
+} from './cache';
+
+// AI utilities (prompt sanitization)
+export {
+ sanitizeForAIPrompt
+} from './ai';
+
+// Exchange rate utilities
+export {
+ getExchangeRate,
+ EXCHANGE_RATE_FALLBACK
+} from './exchange-rate';
+
+// Re-export region utilities from region-utils.ts for backward compatibility
+export {
+ DEFAULT_ANVIL_REGION_FILTER_SQL,
+ COUNTRY_NAME_TO_REGIONS,
+ escapeLikePattern,
+ buildFlexibleRegionConditions,
+ buildFlexibleRegionConditionsAnvil
+} from '../region-utils';
diff --git a/src/utils/validation.ts b/src/utils/validation.ts
new file mode 100644
index 0000000..ff2d858
--- /dev/null
+++ b/src/utils/validation.ts
@@ -0,0 +1,179 @@
+/**
+ * Validation utility functions
+ */
+
+import type {
+ RecommendRequest,
+ ValidationError,
+ Server,
+ VPSBenchmark,
+ TechSpec,
+ BenchmarkData,
+ AIRecommendationResponse
+} from '../types';
+import { i18n, LIMITS } from '../config';
+
+/**
+ * Type guard to validate Server object structure
+ */
+export function isValidServer(obj: unknown): obj is Server {
+ if (!obj || typeof obj !== 'object') return false;
+ const s = obj as Record;
+ return (
+ typeof s.id === 'number' &&
+ typeof s.provider_name === 'string' &&
+ typeof s.instance_id === 'string' &&
+ typeof s.vcpu === 'number' &&
+ typeof s.memory_mb === 'number' &&
+ typeof s.monthly_price === 'number'
+ );
+}
+
+/**
+ * Type guard to validate VPSBenchmark object structure
+ */
+export function isValidVPSBenchmark(obj: unknown): obj is VPSBenchmark {
+ if (!obj || typeof obj !== 'object') return false;
+ const v = obj as Record;
+ return (
+ typeof v.id === 'number' &&
+ typeof v.provider_name === 'string' &&
+ typeof v.vcpu === 'number' &&
+ typeof v.geekbench_single === 'number'
+ );
+}
+
+/**
+ * Type guard to validate TechSpec object structure
+ */
+export function isValidTechSpec(obj: unknown): obj is TechSpec {
+ if (!obj || typeof obj !== 'object') return false;
+ const t = obj as Record;
+ return (
+ typeof t.id === 'number' &&
+ typeof t.name === 'string' &&
+ typeof t.vcpu_per_users === 'number' &&
+ typeof t.min_memory_mb === 'number'
+ );
+}
+
+/**
+ * Type guard to validate BenchmarkData object structure
+ */
+export function isValidBenchmarkData(obj: unknown): obj is BenchmarkData {
+ if (!obj || typeof obj !== 'object') return false;
+ const b = obj as Record;
+ return (
+ typeof b.id === 'number' &&
+ typeof b.processor_name === 'string' &&
+ typeof b.benchmark_name === 'string' &&
+ typeof b.score === 'number'
+ );
+}
+
+/**
+ * Type guard to validate AI recommendation structure
+ */
+export function isValidAIRecommendation(obj: unknown): obj is AIRecommendationResponse['recommendations'][0] {
+ if (!obj || typeof obj !== 'object') return false;
+ const r = obj as Record;
+ return (
+ (typeof r.server_id === 'number' || typeof r.server_id === 'string') &&
+ typeof r.score === 'number' &&
+ r.analysis !== null &&
+ typeof r.analysis === 'object' &&
+ r.estimated_capacity !== null &&
+ typeof r.estimated_capacity === 'object'
+ );
+}
+
+/**
+ * Validate recommendation request
+ */
+export function validateRecommendRequest(body: unknown, lang: string = 'en'): ValidationError | null {
+ // Ensure lang is valid
+ const validLang = ['en', 'zh', 'ja', 'ko'].includes(lang) ? lang : 'en';
+ const messages = i18n[validLang];
+
+ if (!body || typeof body !== 'object') {
+ return {
+ error: 'Request body must be a JSON object',
+ missing_fields: ['tech_stack', 'expected_users', 'use_case'],
+ schema: messages.schema,
+ example: messages.example
+ };
+ }
+
+ // Type guard: assert body is an object with unknown properties
+ const req = body as Record;
+
+ const missingFields: string[] = [];
+ const invalidFields: { field: string; reason: string }[] = [];
+
+ // Check required fields
+ if (!req.tech_stack) {
+ missingFields.push('tech_stack');
+ } else if (!Array.isArray(req.tech_stack) || req.tech_stack.length === 0) {
+ invalidFields.push({ field: 'tech_stack', reason: 'must be a non-empty array of strings' });
+ } else if (req.tech_stack.length > LIMITS.MAX_TECH_STACK) {
+ invalidFields.push({ field: 'tech_stack', reason: `must not exceed ${LIMITS.MAX_TECH_STACK} items` });
+ } else if (!req.tech_stack.every((item: unknown) =>
+ typeof item === 'string' && item.length <= 50
+ )) {
+ invalidFields.push({ field: 'tech_stack', reason: messages.techStackItemLength || 'all items must be strings with max 50 characters' });
+ }
+
+ if (req.expected_users === undefined) {
+ missingFields.push('expected_users');
+ } else if (typeof req.expected_users !== 'number' || req.expected_users < 1) {
+ invalidFields.push({ field: 'expected_users', reason: 'must be a positive number' });
+ } else if (req.expected_users > 10000000) {
+ invalidFields.push({ field: 'expected_users', reason: 'must not exceed 10,000,000' });
+ }
+
+ if (!req.use_case) {
+ missingFields.push('use_case');
+ } else if (typeof req.use_case !== 'string' || req.use_case.trim().length === 0) {
+ invalidFields.push({ field: 'use_case', reason: 'must be a non-empty string' });
+ } else if (req.use_case.length > LIMITS.MAX_USE_CASE_LENGTH) {
+ invalidFields.push({ field: 'use_case', reason: `must not exceed ${LIMITS.MAX_USE_CASE_LENGTH} characters` });
+ }
+
+ // Check optional fields if provided
+ if (req.traffic_pattern !== undefined && !['steady', 'spiky', 'growing'].includes(req.traffic_pattern as string)) {
+ invalidFields.push({ field: 'traffic_pattern', reason: "must be one of: 'steady', 'spiky', 'growing'" });
+ }
+
+ if (req.budget_limit !== undefined && (typeof req.budget_limit !== 'number' || req.budget_limit < 0)) {
+ invalidFields.push({ field: 'budget_limit', reason: 'must be a non-negative number' });
+ }
+
+ // Validate lang field if provided
+ if (req.lang !== undefined && !['en', 'zh', 'ja', 'ko'].includes(req.lang as string)) {
+ invalidFields.push({ field: 'lang', reason: "must be one of: 'en', 'zh', 'ja', 'ko'" });
+ }
+
+ // Validate region_preference if provided
+ if (req.region_preference !== undefined) {
+ if (!Array.isArray(req.region_preference)) {
+ invalidFields.push({ field: 'region_preference', reason: 'must be an array of strings' });
+ } else if (req.region_preference.length > LIMITS.MAX_REGION_PREFERENCE) {
+ invalidFields.push({ field: 'region_preference', reason: `must not exceed ${LIMITS.MAX_REGION_PREFERENCE} items` });
+ } else if (!req.region_preference.every((r: unknown) => typeof r === 'string' && r.length > 0 && r.length <= 50)) {
+ invalidFields.push({ field: 'region_preference', reason: 'all items must be non-empty strings with max 50 characters' });
+ }
+ }
+
+ // Return error if any issues found
+ if (missingFields.length > 0 || invalidFields.length > 0) {
+ return {
+ error: missingFields.length > 0 ? messages.missingFields : messages.invalidFields,
+ ...(missingFields.length > 0 && { missing_fields: missingFields }),
+ ...(invalidFields.length > 0 && { invalid_fields: invalidFields }),
+ schema: messages.schema,
+ example: messages.example
+ };
+ }
+
+ return null;
+}
diff --git a/vitest.config.ts b/vitest.config.ts
new file mode 100644
index 0000000..8e730d5
--- /dev/null
+++ b/vitest.config.ts
@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+ test: {
+ globals: true,
+ environment: 'node',
+ },
+});