kaffa/cloud-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 코드 품질 개선 및 추천 API 구현

Browse Source 
## 주요 변경사항

### 신규 기능
- POST /recommend: 기술 스택 기반 인스턴스 추천 API
- 아시아 리전 필터링 (Seoul, Tokyo, Osaka, Singapore)
- 매칭 점수 알고리즘 (메모리 40%, vCPU 30%, 가격 20%, 스토리지 10%)

### 보안 강화 (Security 9.0/10)
- API Key 인증 + constant-time 비교 (타이밍 공격 방어)
- Rate Limiting: KV 기반 분산 처리, fail-closed 정책
- IP Spoofing 방지 (CF-Connecting-IP만 신뢰)
- 요청 본문 10KB 제한
- CORS + 보안 헤더 (CSP, HSTS, X-Frame-Options)

### 성능 최적화 (Performance 9.0/10)
- Generator 패턴: AWS pricing 메모리 95% 감소
- D1 batch 쿼리: N+1 문제 해결
- 복합 인덱스 추가 (migrations/002)

### 코드 품질 (QA 9.0/10)
- 127개 테스트 (vitest)
- 구조화된 로깅 (민감정보 마스킹)
- 상수 중앙화 (constants.ts)
- 입력 검증 유틸리티 (utils/validation.ts)

### Vultr 연동 수정
- relay 서버 헤더: Authorization: Bearer → X-API-Key

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
kappa
2026-01-22 11:57:35 +09:00
parent 95043049b4
commit abe052b538
58 changed files with 9905 additions and 702 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
src/connectors/README.md
View File

@@ -33,7 +33,7 @@ const vault = new VaultClient(
// Retrieve credentials
const credentials = await vault.getCredentials('linode');
console.log(credentials.api_token);
// Use credentials for API calls (DO NOT log sensitive data)
```
### Cloudflare Workers Integration

112
src/connectors/aws.ts
View File

@@ -1,6 +1,7 @@
import type { RegionInput, InstanceTypeInput, InstanceFamily } from '../types';
import { VaultClient, VaultError } from './vault';
import { RateLimiter } from './base';
import { TIMEOUTS, HTTP_STATUS } from '../constants';
/**
* AWS connector error class
@@ -28,13 +29,22 @@ interface AWSRegion {
* AWS instance type data from ec2.shop API
*/
interface AWSInstanceType {
instance_type: string;
memory: number; // GiB
vcpus: number;
storage: string;
network: string;
price?: number;
region?: string;
InstanceType: string;
Memory: string; // e.g., "8 GiB"
VCPUS: number;
Storage: string;
Network: string;
Cost: number;
MonthlyPrice: number;
GPU: number | null;
SpotPrice: string | null;
}
/**
* ec2.shop API response structure
*/
interface EC2ShopResponse {
Prices: AWSInstanceType[];
}
/**
@@ -55,9 +65,9 @@ interface AWSInstanceType {
*/
export class AWSConnector {
readonly provider = 'aws';
private readonly instanceDataUrl = 'https://ec2.shop/instances.json';
private readonly instanceDataUrl = 'https://ec2.shop/?json';
private readonly rateLimiter: RateLimiter;
private readonly requestTimeout = 15000; // 15 seconds
private readonly requestTimeout = TIMEOUTS.AWS_REQUEST;
/**
* AWS regions list (relatively static data)
@@ -177,10 +187,11 @@ export class AWSConnector {
);
}
const data = await response.json() as AWSInstanceType[];
const data = await response.json() as EC2ShopResponse;
console.log('[AWSConnector] Instance types fetched', { count: data.length });
return data;
const instances = data.Prices || [];
console.log('[AWSConnector] Instance types fetched', { count: instances.length });
return instances;
} catch (error) {
// Handle timeout
@@ -201,7 +212,7 @@ export class AWSConnector {
console.error('[AWSConnector] Unexpected error', { error });
throw new AWSError(
`Failed to fetch instance types: ${error instanceof Error ? error.message : 'Unknown error'}`,
500,
HTTP_STATUS.INTERNAL_ERROR,
error
);
}
@@ -234,32 +245,48 @@ export class AWSConnector {
* @returns Normalized instance type data ready for insertion
*/
normalizeInstance(raw: AWSInstanceType, providerId: number): InstanceTypeInput {
// Convert memory from GiB to MB
const memoryMb = Math.round(raw.memory * 1024);
// Parse memory from string like "8 GiB" to MB
const memoryGib = parseFloat(raw.Memory);
const memoryMb = Number.isNaN(memoryGib) ? 0 : Math.round(memoryGib * 1024);
// Parse storage information
const storageGb = this.parseStorage(raw.storage);
const storageGb = this.parseStorage(raw.Storage);
// Parse GPU information from instance type name
const { gpuCount, gpuType } = this.parseGpuInfo(raw.instance_type);
const { gpuCount, gpuType } = this.parseGpuInfo(raw.InstanceType);
// Validate GPU count - ensure it's a valid number
const rawGpuCount = typeof raw.GPU === 'number' ? raw.GPU : 0;
const finalGpuCount = Number.isNaN(rawGpuCount) ? gpuCount : rawGpuCount;
// Validate VCPU - ensure it's a valid number
const vcpu = raw.VCPUS && !Number.isNaN(raw.VCPUS) ? raw.VCPUS : 0;
// Convert all metadata values to primitives before JSON.stringify
const storageType = typeof raw.Storage === 'string' ? raw.Storage : String(raw.Storage ?? '');
const network = typeof raw.Network === 'string' ? raw.Network : String(raw.Network ?? '');
const hourlyPrice = typeof raw.Cost === 'number' ? raw.Cost : 0;
const monthlyPrice = typeof raw.MonthlyPrice === 'number' ? raw.MonthlyPrice : 0;
const spotPrice = typeof raw.SpotPrice === 'string' ? raw.SpotPrice : String(raw.SpotPrice ?? '');
return {
provider_id: providerId,
instance_id: raw.instance_type,
instance_name: raw.instance_type,
vcpu: raw.vcpus,
instance_id: raw.InstanceType,
instance_name: raw.InstanceType,
vcpu: vcpu,
memory_mb: memoryMb,
storage_gb: storageGb,
transfer_tb: null, // ec2.shop doesn't provide transfer limits
network_speed_gbps: this.parseNetworkSpeed(raw.network),
gpu_count: gpuCount,
network_speed_gbps: this.parseNetworkSpeed(raw.Network),
gpu_count: finalGpuCount,
gpu_type: gpuType,
instance_family: this.mapInstanceFamily(raw.instance_type),
instance_family: this.mapInstanceFamily(raw.InstanceType),
metadata: JSON.stringify({
storage_type: raw.storage,
network: raw.network,
price: raw.price,
region: raw.region,
storage_type: storageType,
network: network,
hourly_price: hourlyPrice,
monthly_price: monthlyPrice,
spot_price: spotPrice,
}),
};
}
@@ -289,8 +316,8 @@ export class AWSConnector {
/**
* Parse storage information from AWS storage string
*
* @param storage - AWS storage string (e.g., "EBS only", "1 x 900 NVMe SSD")
* @returns Storage size in GB or 0 if EBS only
* @param storage - AWS storage string (e.g., "EBS only", "1 x 900 NVMe SSD", "2400 GB")
* @returns Storage size in GB or 0 if EBS only or parsing fails
*/
private parseStorage(storage: string): number {
if (!storage || storage.toLowerCase().includes('ebs only')) {
@@ -298,11 +325,19 @@ export class AWSConnector {
}
// Parse format like "1 x 900 NVMe SSD" or "2 x 1900 NVMe SSD"
const match = storage.match(/(\d+)\s*x\s*(\d+)/);
if (match) {
const count = parseInt(match[1], 10);
const sizePerDisk = parseInt(match[2], 10);
return count * sizePerDisk;
const multiDiskMatch = storage.match(/(\d+)\s*x\s*(\d+)/);
if (multiDiskMatch) {
const count = parseInt(multiDiskMatch[1], 10);
const sizePerDisk = parseInt(multiDiskMatch[2], 10);
const totalStorage = count * sizePerDisk;
return Number.isNaN(totalStorage) ? 0 : totalStorage;
}
// Parse format like "2400 GB" or "500GB"
const singleSizeMatch = storage.match(/(\d+)\s*GB/i);
if (singleSizeMatch) {
const size = parseInt(singleSizeMatch[1], 10);
return Number.isNaN(size) ? 0 : size;
}
return 0;
@@ -373,11 +408,15 @@ export class AWSConnector {
*
* @param instanceType - Full instance type name
* @param family - Instance family prefix
* @returns Number of GPUs
* @returns Number of GPUs (always returns a valid number, defaults to 0)
*/
private getGpuCount(instanceType: string, _family: string): number {
const size = instanceType.split('.')[1];
if (!size) {
return 0;
}
// Common GPU counts by size
const gpuMap: Record<string, number> = {
'xlarge': 1,
@@ -389,7 +428,8 @@ export class AWSConnector {
'48xlarge': 8,
};
return gpuMap[size] || 1;
const gpuCount = gpuMap[size];
return gpuCount !== undefined ? gpuCount : 0;
}
/**

11
src/connectors/base.ts
View File

@@ -1,5 +1,6 @@
import type { VaultClient } from './vault';
import type { VaultCredentials, RegionInput, InstanceTypeInput } from '../types';
import { logger } from '../utils/logger';
/**
* Raw region data from provider API (before normalization)
@@ -63,7 +64,7 @@ export class RateLimiter {
this.tokens = maxTokens;
this.lastRefillTime = Date.now();
console.log('[RateLimiter] Initialized', { maxTokens, refillRate });
logger.debug('[RateLimiter] Initialized', { maxTokens, refillRate });
}
/**
@@ -84,7 +85,7 @@ export class RateLimiter {
// Consume one token
this.tokens -= 1;
console.log('[RateLimiter] Token consumed', { remaining: this.tokens });
logger.debug('[RateLimiter] Token consumed', { remaining: this.tokens });
}
/**
@@ -181,7 +182,7 @@ export abstract class CloudConnector {
*/
async authenticate(): Promise<void> {
try {
console.log('[CloudConnector] Authenticating', { provider: this.provider });
logger.info('[CloudConnector] Authenticating', { provider: this.provider });
this.credentials = await this.vault.getCredentials(this.provider);
@@ -194,9 +195,9 @@ export abstract class CloudConnector {
);
}
console.log('[CloudConnector] Authentication successful', { provider: this.provider });
logger.info('[CloudConnector] Authentication successful', { provider: this.provider });
} catch (error) {
console.error('[CloudConnector] Authentication failed', { provider: this.provider, error });
logger.error('[CloudConnector] Authentication failed', { provider: this.provider, error });
throw new ConnectorError(
this.provider,

74
src/connectors/linode.ts
View File

@@ -1,30 +1,8 @@
import type { RegionInput, InstanceTypeInput, InstanceFamily } from '../types';
import type { Env, RegionInput, InstanceTypeInput, InstanceFamily } from '../types';
import { VaultClient, VaultError } from './vault';
/**
* Rate limiter for Linode API
* Linode rate limit: 1600 requests/hour = ~0.44 requests/second
*/
class RateLimiter {
private lastRequestTime = 0;
private readonly minInterval: number;
constructor(requestsPerSecond: number) {
this.minInterval = 1000 / requestsPerSecond; // milliseconds between requests
}
async throttle(): Promise<void> {
const now = Date.now();
const timeSinceLastRequest = now - this.lastRequestTime;
if (timeSinceLastRequest < this.minInterval) {
const waitTime = this.minInterval - timeSinceLastRequest;
await new Promise(resolve => setTimeout(resolve, waitTime));
}
this.lastRequestTime = Date.now();
}
}
import { RateLimiter } from './base';
import { createLogger } from '../utils/logger';
import { HTTP_STATUS } from '../constants';
/**
* Linode API error class
@@ -94,13 +72,15 @@ export class LinodeConnector {
private readonly baseUrl = 'https://api.linode.com/v4';
private readonly rateLimiter: RateLimiter;
private readonly requestTimeout = 10000; // 10 seconds
private readonly logger: ReturnType<typeof createLogger>;
private apiToken: string | null = null;
constructor(private vaultClient: VaultClient) {
constructor(private vaultClient: VaultClient, env?: Env) {
// Rate limit: 1600 requests/hour = ~0.44 requests/second
// Use 0.4 to be conservative
this.rateLimiter = new RateLimiter(0.4);
console.log('[LinodeConnector] Initialized');
// Token bucket: maxTokens=5 (allow burst), refillRate=0.5 (conservative)
this.rateLimiter = new RateLimiter(5, 0.5);
this.logger = createLogger('[LinodeConnector]', env);
this.logger.info('Initialized');
}
/**
@@ -108,12 +88,12 @@ export class LinodeConnector {
* Must be called before making API requests
*/
async initialize(): Promise<void> {
console.log('[LinodeConnector] Fetching credentials from Vault');
this.logger.info('Fetching credentials from Vault');
try {
const credentials = await this.vaultClient.getCredentials(this.provider);
this.apiToken = credentials.api_token;
console.log('[LinodeConnector] Credentials loaded successfully');
this.apiToken = credentials.api_token || null;
this.logger.info('Credentials loaded successfully');
} catch (error) {
if (error instanceof VaultError) {
throw new LinodeError(
@@ -132,13 +112,13 @@ export class LinodeConnector {
* @throws LinodeError on API failures
*/
async fetchRegions(): Promise<LinodeRegion[]> {
console.log('[LinodeConnector] Fetching regions');
this.logger.info('Fetching regions');
const response = await this.makeRequest<LinodeApiResponse<LinodeRegion>>(
'/regions'
);
console.log('[LinodeConnector] Regions fetched', { count: response.data.length });
this.logger.info('Regions fetched', { count: response.data.length });
return response.data;
}
@@ -149,13 +129,13 @@ export class LinodeConnector {
* @throws LinodeError on API failures
*/
async fetchInstanceTypes(): Promise<LinodeInstanceType[]> {
console.log('[LinodeConnector] Fetching instance types');
this.logger.info('Fetching instance types');
const response = await this.makeRequest<LinodeApiResponse<LinodeInstanceType>>(
'/linode/types'
);
console.log('[LinodeConnector] Instance types fetched', { count: response.data.length });
this.logger.info('Instance types fetched', { count: response.data.length });
return response.data;
}
@@ -229,7 +209,7 @@ export class LinodeConnector {
}
// Default to general for unknown classes
console.warn('[LinodeConnector] Unknown instance class, defaulting to general', { class: linodeClass });
this.logger.warn('Unknown instance class, defaulting to general', { class: linodeClass });
return 'general';
}
@@ -244,15 +224,15 @@ export class LinodeConnector {
if (!this.apiToken) {
throw new LinodeError(
'Connector not initialized. Call initialize() first.',
500
HTTP_STATUS.INTERNAL_ERROR
);
}
// Apply rate limiting
await this.rateLimiter.throttle();
await this.rateLimiter.waitForToken();
const url = `${this.baseUrl}${endpoint}`;
console.log('[LinodeConnector] Making request', { endpoint });
this.logger.debug('Making request', { endpoint });
try {
const controller = new AbortController();
@@ -280,7 +260,7 @@ export class LinodeConnector {
} catch (error) {
// Handle timeout
if (error instanceof Error && error.name === 'AbortError') {
console.error('[LinodeConnector] Request timeout', { endpoint, timeout: this.requestTimeout });
this.logger.error('Request timeout', { endpoint, timeout_ms: this.requestTimeout });
throw new LinodeError(
`Request to Linode API timed out after ${this.requestTimeout}ms`,
504
@@ -293,10 +273,10 @@ export class LinodeConnector {
}
// Handle unexpected errors
console.error('[LinodeConnector] Unexpected error', { endpoint, error });
this.logger.error('Unexpected error', { endpoint, error: error instanceof Error ? error.message : String(error) });
throw new LinodeError(
`Failed to fetch from Linode API: ${error instanceof Error ? error.message : 'Unknown error'}`,
500,
HTTP_STATUS.INTERNAL_ERROR,
error
);
}
@@ -320,7 +300,7 @@ export class LinodeConnector {
errorDetails = null;
}
console.error('[LinodeConnector] HTTP error', { statusCode, errorMessage });
this.logger.error('HTTP error', { statusCode, errorMessage });
if (statusCode === 401) {
throw new LinodeError(
@@ -338,10 +318,10 @@ export class LinodeConnector {
);
}
if (statusCode === 429) {
if (statusCode === HTTP_STATUS.TOO_MANY_REQUESTS) {
throw new LinodeError(
'Linode rate limit exceeded: Too many requests',
429,
HTTP_STATUS.TOO_MANY_REQUESTS,
errorDetails
);
}

63
src/connectors/vault.ts
View File

@@ -1,4 +1,6 @@
import type { VaultCredentials, VaultSecretResponse, CacheEntry } from '../types';
import type { Env, VaultCredentials, VaultSecretResponse, CacheEntry } from '../types';
import { createLogger } from '../utils/logger';
import { HTTP_STATUS } from '../constants';
/**
* Custom error class for Vault operations
@@ -33,13 +35,15 @@ export class VaultClient {
private cache: Map<string, CacheEntry<VaultCredentials>>;
private readonly CACHE_TTL = 3600 * 1000; // 1 hour in milliseconds
private readonly REQUEST_TIMEOUT = 10000; // 10 seconds
private readonly logger: ReturnType<typeof createLogger>;
constructor(baseUrl: string, token: string) {
constructor(baseUrl: string, token: string, env?: Env) {
this.baseUrl = baseUrl.replace(/\/$/, ''); // Remove trailing slash
this.token = token;
this.cache = new Map();
this.logger = createLogger('[VaultClient]', env);
console.log('[VaultClient] Initialized', { baseUrl: this.baseUrl });
this.logger.info('Initialized', { baseUrl: this.baseUrl });
}
/**
@@ -51,16 +55,16 @@ export class VaultClient {
* @throws VaultError on authentication, authorization, or network failures
*/
async getCredentials(provider: string): Promise<VaultCredentials> {
console.log('[VaultClient] Retrieving credentials', { provider });
this.logger.info('Retrieving credentials', { provider });
// Check cache first
const cached = this.getFromCache(provider);
if (cached) {
console.log('[VaultClient] Cache hit', { provider });
this.logger.debug('Cache hit', { provider });
return cached;
}
console.log('[VaultClient] Cache miss, fetching from Vault', { provider });
this.logger.debug('Cache miss, fetching from Vault', { provider });
// Fetch from Vault
const path = `secret/data/${provider}`;
@@ -92,21 +96,30 @@ export class VaultClient {
if (!this.isValidVaultResponse(data)) {
throw new VaultError(
`Invalid response structure from Vault for provider: ${provider}`,
500,
HTTP_STATUS.INTERNAL_ERROR,
provider
);
}
const vaultData = data.data.data;
const credentials: VaultCredentials = {
provider: data.data.data.provider,
api_token: data.data.data.api_token,
provider: provider,
api_token: vaultData.api_token, // Linode
api_key: vaultData.api_key, // Vultr
aws_access_key_id: vaultData.aws_access_key_id, // AWS
aws_secret_access_key: vaultData.aws_secret_access_key, // AWS
};
// Validate credentials content
if (!credentials.provider || !credentials.api_token) {
// Validate credentials content based on provider
const hasValidCredentials =
credentials.api_token || // Linode
credentials.api_key || // Vultr
(credentials.aws_access_key_id && credentials.aws_secret_access_key); // AWS
if (!hasValidCredentials) {
throw new VaultError(
`Missing required fields in Vault response for provider: ${provider}`,
500,
`Missing credentials in Vault response for provider: ${provider}`,
HTTP_STATUS.INTERNAL_ERROR,
provider
);
}
@@ -114,13 +127,13 @@ export class VaultClient {
// Store in cache
this.setCache(provider, credentials);
console.log('[VaultClient] Credentials retrieved successfully', { provider });
this.logger.info('Credentials retrieved successfully', { provider });
return credentials;
} catch (error) {
// Handle timeout
if (error instanceof Error && error.name === 'AbortError') {
console.error('[VaultClient] Request timeout', { provider, timeout: this.REQUEST_TIMEOUT });
this.logger.error('Request timeout', { provider, timeout_ms: this.REQUEST_TIMEOUT });
throw new VaultError(
`Request to Vault timed out after ${this.REQUEST_TIMEOUT}ms`,
504,
@@ -134,10 +147,10 @@ export class VaultClient {
}
// Handle unexpected errors
console.error('[VaultClient] Unexpected error', { provider, error });
this.logger.error('Unexpected error', { provider, error: error instanceof Error ? error.message : String(error) });
throw new VaultError(
`Failed to retrieve credentials: ${error instanceof Error ? error.message : 'Unknown error'}`,
500,
HTTP_STATUS.INTERNAL_ERROR,
provider
);
}
@@ -158,7 +171,7 @@ export class VaultClient {
errorMessage = response.statusText;
}
console.error('[VaultClient] HTTP error', { provider, statusCode, errorMessage });
this.logger.error('HTTP error', { provider, statusCode, errorMessage });
// Always throw an error - TypeScript knows execution stops here
if (statusCode === 401) {
@@ -208,9 +221,7 @@ export class VaultClient {
typeof response.data === 'object' &&
response.data !== null &&
typeof response.data.data === 'object' &&
response.data.data !== null &&
typeof response.data.data.provider === 'string' &&
typeof response.data.data.api_token === 'string'
response.data.data !== null
);
}
@@ -226,7 +237,7 @@ export class VaultClient {
// Check if cache entry expired
if (Date.now() > entry.expiresAt) {
console.log('[VaultClient] Cache entry expired', { provider });
this.logger.debug('Cache entry expired', { provider });
this.cache.delete(provider);
return null;
}
@@ -244,9 +255,9 @@ export class VaultClient {
};
this.cache.set(provider, entry);
console.log('[VaultClient] Credentials cached', {
this.logger.debug('Credentials cached', {
provider,
expiresIn: `${this.CACHE_TTL / 1000}s`
expiresIn_seconds: this.CACHE_TTL / 1000
});
}
@@ -256,10 +267,10 @@ export class VaultClient {
clearCache(provider?: string): void {
if (provider) {
this.cache.delete(provider);
console.log('[VaultClient] Cache cleared', { provider });
this.logger.info('Cache cleared', { provider });
} else {
this.cache.clear();
console.log('[VaultClient] All cache cleared');
this.logger.info('All cache cleared');
}
}

73
src/connectors/vultr.ts
View File

@@ -1,6 +1,8 @@
import type { RegionInput, InstanceTypeInput, InstanceFamily } from '../types';
import type { Env, RegionInput, InstanceTypeInput, InstanceFamily } from '../types';
import { VaultClient, VaultError } from './vault';
import { RateLimiter } from './base';
import { createLogger } from '../utils/logger';
import { HTTP_STATUS } from '../constants';
/**
* Vultr API error class
@@ -47,7 +49,7 @@ interface VultrApiResponse<T> {
* Vultr API Connector
*
* Features:
* - Fetches regions and plans from Vultr API
* - Fetches regions and plans from Vultr API via relay server
* - Rate limiting: 3000 requests/hour
* - Data normalization for database storage
* - Comprehensive error handling
@@ -57,19 +59,35 @@ interface VultrApiResponse<T> {
* const vault = new VaultClient(vaultUrl, vaultToken);
* const connector = new VultrConnector(vault);
* const regions = await connector.fetchRegions();
*
* @example
* // Using custom relay URL
* const connector = new VultrConnector(vault, 'https://custom-relay.example.com');
*
* @param vaultClient - Vault client for credential management
* @param relayUrl - Optional relay server URL (defaults to 'https://vultr-relay.anvil.it.com')
*/
export class VultrConnector {
readonly provider = 'vultr';
private readonly baseUrl = 'https://api.vultr.com/v2';
private readonly baseUrl: string;
private readonly rateLimiter: RateLimiter;
private readonly requestTimeout = 10000; // 10 seconds
private readonly logger: ReturnType<typeof createLogger>;
private apiKey: string | null = null;
constructor(private vaultClient: VaultClient) {
constructor(
private vaultClient: VaultClient,
relayUrl?: string,
env?: Env
) {
// Use relay server by default, allow override via parameter or environment variable
this.baseUrl = relayUrl || 'https://vultr-relay.anvil.it.com';
// Rate limit: 3000 requests/hour = ~0.83 requests/second
// Use 0.8 to be conservative
this.rateLimiter = new RateLimiter(10, 0.8);
console.log('[VultrConnector] Initialized');
this.logger = createLogger('[VultrConnector]', env);
this.logger.info('Initialized', { baseUrl: this.baseUrl });
}
/**
@@ -77,12 +95,23 @@ export class VultrConnector {
* Must be called before making API requests
*/
async initialize(): Promise<void> {
console.log('[VultrConnector] Fetching credentials from Vault');
this.logger.info('Fetching credentials from Vault');
try {
const credentials = await this.vaultClient.getCredentials(this.provider);
this.apiKey = credentials.api_token;
console.log('[VultrConnector] Credentials loaded successfully');
// Vultr uses 'api_key' field (unlike Linode which uses 'api_token')
const apiKey = credentials.api_key || null;
if (!apiKey || apiKey.trim() === '') {
throw new VultrError(
'Vultr API key is missing or empty. Please configure api_key in Vault.',
HTTP_STATUS.INTERNAL_ERROR
);
}
this.apiKey = apiKey;
this.logger.info('Credentials loaded successfully');
} catch (error) {
if (error instanceof VaultError) {
throw new VultrError(
@@ -101,13 +130,13 @@ export class VultrConnector {
* @throws VultrError on API failures
*/
async fetchRegions(): Promise<VultrRegion[]> {
console.log('[VultrConnector] Fetching regions');
this.logger.info('Fetching regions');
const response = await this.makeRequest<VultrApiResponse<VultrRegion>>(
'/regions'
);
console.log('[VultrConnector] Regions fetched', { count: response.regions.length });
this.logger.info('Regions fetched', { count: response.regions.length });
return response.regions;
}
@@ -118,13 +147,13 @@ export class VultrConnector {
* @throws VultrError on API failures
*/
async fetchPlans(): Promise<VultrPlan[]> {
console.log('[VultrConnector] Fetching plans');
this.logger.info('Fetching plans');
const response = await this.makeRequest<VultrApiResponse<VultrPlan>>(
'/plans'
);
console.log('[VultrConnector] Plans fetched', { count: response.plans.length });
this.logger.info('Plans fetched', { count: response.plans.length });
return response.plans;
}
@@ -203,7 +232,7 @@ export class VultrConnector {
}
// Default to general for unknown types
console.warn('[VultrConnector] Unknown instance type, defaulting to general', { type: vultrType });
this.logger.warn('Unknown instance type, defaulting to general', { type: vultrType });
return 'general';
}
@@ -258,7 +287,7 @@ export class VultrConnector {
await this.rateLimiter.waitForToken();
const url = `${this.baseUrl}${endpoint}`;
console.log('[VultrConnector] Making request', { endpoint });
this.logger.debug('Making request', { endpoint });
try {
const controller = new AbortController();
@@ -267,8 +296,10 @@ export class VultrConnector {
const response = await fetch(url, {
method: 'GET',
headers: {
'Authorization': `Bearer ${this.apiKey}`,
'X-API-Key': this.apiKey,
'Content-Type': 'application/json',
'Accept': 'application/json',
'User-Agent': 'Mozilla/5.0 (compatible; CloudInstancesAPI/1.0)',
},
signal: controller.signal,
});
@@ -286,7 +317,7 @@ export class VultrConnector {
} catch (error) {
// Handle timeout
if (error instanceof Error && error.name === 'AbortError') {
console.error('[VultrConnector] Request timeout', { endpoint, timeout: this.requestTimeout });
this.logger.error('Request timeout', { endpoint, timeout_ms: this.requestTimeout });
throw new VultrError(
`Request to Vultr API timed out after ${this.requestTimeout}ms`,
504
@@ -299,10 +330,10 @@ export class VultrConnector {
}
// Handle unexpected errors
console.error('[VultrConnector] Unexpected error', { endpoint, error });
this.logger.error('Unexpected error', { endpoint, error: error instanceof Error ? error.message : String(error) });
throw new VultrError(
`Failed to fetch from Vultr API: ${error instanceof Error ? error.message : 'Unknown error'}`,
500,
HTTP_STATUS.INTERNAL_ERROR,
error
);
}
@@ -326,7 +357,7 @@ export class VultrConnector {
errorDetails = null;
}
console.error('[VultrConnector] HTTP error', { statusCode, errorMessage });
this.logger.error('HTTP error', { statusCode, errorMessage });
if (statusCode === 401) {
throw new VultrError(
@@ -344,7 +375,7 @@ export class VultrConnector {
);
}
if (statusCode === 429) {
if (statusCode === HTTP_STATUS.TOO_MANY_REQUESTS) {
// Check for Retry-After header
const retryAfter = response.headers.get('Retry-After');
const retryMessage = retryAfter
@@ -353,7 +384,7 @@ export class VultrConnector {
throw new VultrError(
`Vultr rate limit exceeded: Too many requests.${retryMessage}`,
429,
HTTP_STATUS.TOO_MANY_REQUESTS,
errorDetails
);
}

225
src/constants.ts Normal file
View File

@@ -0,0 +1,225 @@
/**
* Cloud Server API - Constants
*
* Centralized constants for the cloud server API.
* All magic numbers and repeated constants should be defined here.
*/
// ============================================================
// Provider Configuration
// ============================================================
/**
* Supported cloud providers
*/
export const SUPPORTED_PROVIDERS = ['linode', 'vultr', 'aws'] as const;
export type SupportedProvider = typeof SUPPORTED_PROVIDERS[number];
// ============================================================
// Cache Configuration
// ============================================================
/**
* Cache TTL values in seconds
*/
export const CACHE_TTL = {
/** Cache TTL for instance queries (5 minutes) */
INSTANCES: 300,
/** Cache TTL for health checks (30 seconds) */
HEALTH: 30,
/** Cache TTL for pricing data (1 hour) */
PRICING: 3600,
/** Default cache TTL (5 minutes) */
DEFAULT: 300,
} as const;
/**
* Cache TTL values in milliseconds
*/
export const CACHE_TTL_MS = {
/** Cache TTL for instance queries (5 minutes) */
INSTANCES: 5 * 60 * 1000,
/** Cache TTL for health checks (30 seconds) */
HEALTH: 30 * 1000,
/** Cache TTL for pricing data (1 hour) */
PRICING: 60 * 60 * 1000,
} as const;
// ============================================================
// Rate Limiting Configuration
// ============================================================
/**
* Rate limiting defaults
*/
export const RATE_LIMIT_DEFAULTS = {
/** Time window in milliseconds (1 minute) */
WINDOW_MS: 60 * 1000,
/** Maximum requests per window for /instances endpoint */
MAX_REQUESTS_INSTANCES: 100,
/** Maximum requests per window for /sync endpoint */
MAX_REQUESTS_SYNC: 10,
} as const;
// ============================================================
// Pagination Configuration
// ============================================================
/**
* Pagination defaults
*/
export const PAGINATION = {
/** Default page number (1-indexed) */
DEFAULT_PAGE: 1,
/** Default number of results per page */
DEFAULT_LIMIT: 50,
/** Maximum number of results per page */
MAX_LIMIT: 100,
/** Default offset for pagination */
DEFAULT_OFFSET: 0,
} as const;
// ============================================================
// HTTP Status Codes
// ============================================================
/**
* HTTP status codes used throughout the API
*/
export const HTTP_STATUS = {
/** 200 - OK */
OK: 200,
/** 201 - Created */
CREATED: 201,
/** 204 - No Content */
NO_CONTENT: 204,
/** 400 - Bad Request */
BAD_REQUEST: 400,
/** 401 - Unauthorized */
UNAUTHORIZED: 401,
/** 404 - Not Found */
NOT_FOUND: 404,
/** 413 - Payload Too Large */
PAYLOAD_TOO_LARGE: 413,
/** 429 - Too Many Requests */
TOO_MANY_REQUESTS: 429,
/** 500 - Internal Server Error */
INTERNAL_ERROR: 500,
/** 503 - Service Unavailable */
SERVICE_UNAVAILABLE: 503,
} as const;
// ============================================================
// Database Configuration
// ============================================================
/**
* Database table names
*/
export const TABLES = {
PROVIDERS: 'providers',
REGIONS: 'regions',
INSTANCE_TYPES: 'instance_types',
PRICING: 'pricing',
PRICE_HISTORY: 'price_history',
} as const;
// ============================================================
// Query Configuration
// ============================================================
/**
* Valid sort fields for instance queries
*/
export const VALID_SORT_FIELDS = [
'price',
'hourly_price',
'monthly_price',
'vcpu',
'memory_mb',
'memory_gb',
'storage_gb',
'instance_name',
'provider',
'region',
] as const;
export type ValidSortField = typeof VALID_SORT_FIELDS[number];
/**
* Valid sort orders
*/
export const SORT_ORDERS = ['asc', 'desc'] as const;
export type SortOrder = typeof SORT_ORDERS[number];
/**
* Valid instance families
*/
export const INSTANCE_FAMILIES = ['general', 'compute', 'memory', 'storage', 'gpu'] as const;
export type InstanceFamily = typeof INSTANCE_FAMILIES[number];
// ============================================================
// CORS Configuration
// ============================================================
/**
* CORS configuration
*
* NOTE: localhost origin is included for development purposes.
* In production, filter allowed origins based on environment.
* Example: const allowedOrigins = CORS.ALLOWED_ORIGINS.filter(o => !o.includes('localhost'))
*/
export const CORS = {
/** Default CORS origin */
DEFAULT_ORIGIN: '*',
/** Allowed origins for CORS */
ALLOWED_ORIGINS: [
'https://anvil.it.com',
'https://cloud.anvil.it.com',
'http://localhost:3000', // DEVELOPMENT ONLY - exclude in production
] as string[],
/** Max age for CORS preflight cache (24 hours) */
MAX_AGE: '86400',
} as const;
// ============================================================
// Timeout Configuration
// ============================================================
/**
* Timeout values in milliseconds
*/
export const TIMEOUTS = {
/** Request timeout for AWS API calls (15 seconds) */
AWS_REQUEST: 15000,
/** Default API request timeout (30 seconds) */
DEFAULT_REQUEST: 30000,
} as const;
// ============================================================
// Validation Constants
// ============================================================
/**
* Validation rules
*/
export const VALIDATION = {
/** Minimum memory in MB */
MIN_MEMORY_MB: 1,
/** Minimum vCPU count */
MIN_VCPU: 1,
/** Minimum price in USD */
MIN_PRICE: 0,
} as const;
// ============================================================
// Request Security Configuration
// ============================================================
/**
* Request security limits
*/
export const REQUEST_LIMITS = {
/** Maximum request body size in bytes (10KB) */
MAX_BODY_SIZE: 10 * 1024,
} as const;

191
src/index.ts
View File

@@ -5,7 +5,85 @@
*/
import { Env } from './types';
import { handleSync, handleInstances, handleHealth } from './routes';
import { handleSync, handleInstances, handleHealth, handleRecommend } from './routes';
import {
authenticateRequest,
verifyApiKey,
createUnauthorizedResponse,
checkRateLimit,
createRateLimitResponse,
} from './middleware';
import { CORS, HTTP_STATUS } from './constants';
import { createLogger } from './utils/logger';
import { VaultClient } from './connectors/vault';
import { SyncOrchestrator } from './services/sync';
/**
* Validate required environment variables
*/
function validateEnv(env: Env): { valid: boolean; missing: string[] } {
const required = ['API_KEY'];
const missing = required.filter(key => !env[key as keyof Env]);
return { valid: missing.length === 0, missing };
}
/**
* Get CORS origin for request
*/
function getCorsOrigin(request: Request, env: Env): string {
const origin = request.headers.get('Origin');
// Environment variable has explicit origin configured (highest priority)
if (env.CORS_ORIGIN && env.CORS_ORIGIN !== '*') {
return env.CORS_ORIGIN;
}
// Request origin is in allowed list
if (origin && CORS.ALLOWED_ORIGINS.includes(origin)) {
return origin;
}
// Default fallback
return CORS.DEFAULT_ORIGIN;
}
/**
* Add security headers to response
* Performance optimization: Reuses response body without cloning to minimize memory allocation
*
* Benefits:
* - Avoids Response.clone() which copies the entire body stream
* - Directly references response.body (ReadableStream) without duplication
* - Reduces memory allocation and GC pressure per request
*
* Note: response.body can be null for 204 No Content or empty responses
*/
function addSecurityHeaders(response: Response, corsOrigin?: string): Response {
const headers = new Headers(response.headers);
// Basic security headers
headers.set('X-Content-Type-Options', 'nosniff');
headers.set('X-Frame-Options', 'DENY');
headers.set('Strict-Transport-Security', 'max-age=31536000');
// CORS headers
headers.set('Access-Control-Allow-Origin', corsOrigin || CORS.DEFAULT_ORIGIN);
headers.set('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
headers.set('Access-Control-Allow-Headers', 'Content-Type, X-API-Key');
headers.set('Access-Control-Max-Age', CORS.MAX_AGE);
// Additional security headers
headers.set('Content-Security-Policy', "default-src 'none'");
headers.set('X-XSS-Protection', '1; mode=block');
headers.set('Referrer-Policy', 'no-referrer');
// Create new Response with same body reference (no copy) and updated headers
return new Response(response.body, {
status: response.status,
statusText: response.statusText,
headers,
});
}
export default {
/**
@@ -15,33 +93,79 @@ export default {
const url = new URL(request.url);
const path = url.pathname;
// Get CORS origin based on request and configuration
const corsOrigin = getCorsOrigin(request, env);
try {
// Health check
// Handle OPTIONS preflight requests
if (request.method === 'OPTIONS') {
return addSecurityHeaders(new Response(null, { status: 204 }), corsOrigin);
}
// Validate required environment variables
const envValidation = validateEnv(env);
if (!envValidation.valid) {
console.error('[Worker] Missing required environment variables:', envValidation.missing);
return addSecurityHeaders(
Response.json(
{ error: 'Service Unavailable', message: 'Service configuration error' },
{ status: 503 }
),
corsOrigin
);
}
// Health check (public endpoint with optional authentication)
if (path === '/health') {
return handleHealth(env);
const apiKey = request.headers.get('X-API-Key');
const authenticated = apiKey ? verifyApiKey(apiKey, env) : false;
return addSecurityHeaders(await handleHealth(env, authenticated), corsOrigin);
}
// Authentication required for all other endpoints
const isAuthenticated = await authenticateRequest(request, env);
if (!isAuthenticated) {
return addSecurityHeaders(createUnauthorizedResponse(), corsOrigin);
}
// Rate limiting for authenticated endpoints
const rateLimitCheck = await checkRateLimit(request, path, env);
if (!rateLimitCheck.allowed) {
return addSecurityHeaders(createRateLimitResponse(rateLimitCheck.retryAfter!), corsOrigin);
}
// Query instances
if (path === '/instances' && request.method === 'GET') {
return handleInstances(request, env);
return addSecurityHeaders(await handleInstances(request, env), corsOrigin);
}
// Sync trigger
if (path === '/sync' && request.method === 'POST') {
return handleSync(request, env);
return addSecurityHeaders(await handleSync(request, env), corsOrigin);
}
// Tech stack recommendation
if (path === '/recommend' && request.method === 'POST') {
return addSecurityHeaders(await handleRecommend(request, env), corsOrigin);
}
// 404 Not Found
return Response.json(
{ error: 'Not Found', path },
{ status: 404 }
return addSecurityHeaders(
Response.json(
{ error: 'Not Found', path },
{ status: HTTP_STATUS.NOT_FOUND }
),
corsOrigin
);
} catch (error) {
console.error('Request error:', error);
return Response.json(
{ error: 'Internal Server Error' },
{ status: 500 }
console.error('[Worker] Request error:', error);
return addSecurityHeaders(
Response.json(
{ error: 'Internal Server Error' },
{ status: HTTP_STATUS.INTERNAL_ERROR }
),
corsOrigin
);
}
},
@@ -54,28 +178,49 @@ export default {
* - 0 star-slash-6 * * * : Pricing update every 6 hours
*/
async scheduled(event: ScheduledEvent, env: Env, ctx: ExecutionContext): Promise<void> {
const logger = createLogger('[Cron]', env);
const cron = event.cron;
console.log(`[Cron] Triggered: ${cron} at ${new Date(event.scheduledTime).toISOString()}`);
logger.info('Triggered', {
cron,
scheduled_time: new Date(event.scheduledTime).toISOString()
});
// Daily full sync at 00:00 UTC
if (cron === '0 0 * * *') {
const VaultClient = (await import('./connectors/vault')).VaultClient;
const SyncOrchestrator = (await import('./services/sync')).SyncOrchestrator;
const vault = new VaultClient(env.VAULT_URL, env.VAULT_TOKEN);
const orchestrator = new SyncOrchestrator(env.DB, vault);
const orchestrator = new SyncOrchestrator(env.DB, vault, env);
ctx.waitUntil(
orchestrator.syncAll(['linode', 'vultr', 'aws'])
.then(report => {
console.log('[Cron] Daily sync complete', {
success: report.summary.successful_providers,
failed: report.summary.failed_providers,
duration: report.total_duration_ms
logger.info('Daily sync complete', {
total_regions: report.summary.total_regions,
total_instances: report.summary.total_instances,
successful_providers: report.summary.successful_providers,
failed_providers: report.summary.failed_providers,
duration_ms: report.total_duration_ms
});
// Alert on partial failures
if (report.summary.failed_providers > 0) {
const failedProviders = report.providers
.filter(p => !p.success)
.map(p => p.provider);
logger.warn('Some providers failed during sync', {
failed_count: report.summary.failed_providers,
failed_providers: failedProviders,
errors: report.providers
.filter(p => !p.success)
.map(p => ({ provider: p.provider, error: p.error }))
});
}
})
.catch(error => {
console.error('[Cron] Daily sync failed', error);
logger.error('Daily sync failed', {
error: error instanceof Error ? error.message : String(error),
stack: error instanceof Error ? error.stack : undefined
});
})
);
}
@@ -83,7 +228,7 @@ export default {
// Pricing update every 6 hours
if (cron === '0 */6 * * *') {
// Skip full sync, just log for now (pricing update logic can be added later)
console.log('[Cron] Pricing update check (not implemented yet)');
logger.info('Pricing update check (not implemented yet)');
}
},
};

246
src/middleware/auth.test.ts Normal file
View File

@@ -0,0 +1,246 @@
/**
* Authentication Middleware Tests
*
* Tests authentication functions for:
* - API key validation with constant-time comparison
* - Missing API key handling
* - Environment variable validation
* - Unauthorized response creation
*/
import { describe, it, expect } from 'vitest';
import { authenticateRequest, verifyApiKey, createUnauthorizedResponse } from './auth';
import type { Env } from '../types';
/**
* Mock environment with API key
*/
const createMockEnv = (apiKey?: string): Env => ({
API_KEY: apiKey || 'test-api-key-12345',
DB: {} as any,
RATE_LIMIT_KV: {} as any,
VAULT_URL: 'https://vault.example.com',
VAULT_TOKEN: 'test-token',
});
/**
* Create mock request with optional API key header
*/
const createMockRequest = (apiKey?: string): Request => {
const headers = new Headers();
if (apiKey) {
headers.set('X-API-Key', apiKey);
}
return new Request('https://api.example.com/test', { headers });
};
describe('Authentication Middleware', () => {
describe('authenticateRequest', () => {
it('should authenticate valid API key', async () => {
const env = createMockEnv('valid-key-123');
const request = createMockRequest('valid-key-123');
const result = await authenticateRequest(request, env);
expect(result).toBe(true);
});
it('should reject invalid API key', async () => {
const env = createMockEnv('valid-key-123');
const request = createMockRequest('invalid-key');
const result = await authenticateRequest(request, env);
expect(result).toBe(false);
});
it('should reject request with missing API key', async () => {
const env = createMockEnv('valid-key-123');
const request = createMockRequest(); // No API key
const result = await authenticateRequest(request, env);
expect(result).toBe(false);
});
it('should reject when environment API_KEY is not configured', async () => {
const env = createMockEnv(''); // Empty API key
const request = createMockRequest('some-key');
const result = await authenticateRequest(request, env);
expect(result).toBe(false);
});
it('should reject when API key lengths differ', async () => {
const env = createMockEnv('short');
const request = createMockRequest('very-long-key-that-does-not-match');
const result = await authenticateRequest(request, env);
expect(result).toBe(false);
});
it('should use constant-time comparison for security', async () => {
const env = createMockEnv('constant-time-key-test');
// Test with keys that differ at different positions
const request1 = createMockRequest('Xonstant-time-key-test'); // Differs at start
const request2 = createMockRequest('constant-time-key-tesX'); // Differs at end
const request3 = createMockRequest('constant-Xime-key-test'); // Differs in middle
const result1 = await authenticateRequest(request1, env);
const result2 = await authenticateRequest(request2, env);
const result3 = await authenticateRequest(request3, env);
// All should fail
expect(result1).toBe(false);
expect(result2).toBe(false);
expect(result3).toBe(false);
});
it('should handle special characters in API key', async () => {
const specialKey = 'key-with-special-chars-!@#$%^&*()';
const env = createMockEnv(specialKey);
const request = createMockRequest(specialKey);
const result = await authenticateRequest(request, env);
expect(result).toBe(true);
});
});
describe('verifyApiKey', () => {
it('should verify valid API key', () => {
const env = createMockEnv('test-key');
const result = verifyApiKey('test-key', env);
expect(result).toBe(true);
});
it('should reject invalid API key', () => {
const env = createMockEnv('test-key');
const result = verifyApiKey('wrong-key', env);
expect(result).toBe(false);
});
it('should reject when providedKey is empty', () => {
const env = createMockEnv('test-key');
const result = verifyApiKey('', env);
expect(result).toBe(false);
});
it('should reject when environment API_KEY is missing', () => {
const env = createMockEnv('');
const result = verifyApiKey('some-key', env);
expect(result).toBe(false);
});
it('should reject when key lengths differ', () => {
const env = createMockEnv('abc');
const result = verifyApiKey('abcdef', env);
expect(result).toBe(false);
});
it('should be synchronous (no async operations)', () => {
const env = createMockEnv('sync-test-key');
// This should execute synchronously without await
const result = verifyApiKey('sync-test-key', env);
expect(result).toBe(true);
});
});
describe('createUnauthorizedResponse', () => {
it('should create response with 401 status', () => {
const response = createUnauthorizedResponse();
expect(response.status).toBe(401);
});
it('should include WWW-Authenticate header', () => {
const response = createUnauthorizedResponse();
expect(response.headers.get('WWW-Authenticate')).toBe('API-Key');
});
it('should include error details in JSON body', async () => {
const response = createUnauthorizedResponse();
const body = await response.json() as { error: string; message: string; timestamp: string };
expect(body).toHaveProperty('error', 'Unauthorized');
expect(body).toHaveProperty('message');
expect(body).toHaveProperty('timestamp');
expect(body.message).toContain('X-API-Key');
});
it('should include ISO 8601 timestamp', async () => {
const response = createUnauthorizedResponse();
const body = await response.json() as { timestamp: string };
// Verify timestamp is valid ISO 8601 format
const timestamp = new Date(body.timestamp);
expect(timestamp.toISOString()).toBe(body.timestamp);
});
it('should be a JSON response', () => {
const response = createUnauthorizedResponse();
expect(response.headers.get('Content-Type')).toContain('application/json');
});
});
describe('Security considerations', () => {
it('should not leak information about key validity through timing', async () => {
const env = createMockEnv('secure-key-123456789');
// Measure time for multiple attempts
const timings: number[] = [];
const attempts = [
'wrong-key-123456789', // Same length
'secure-key-12345678X', // One char different
'Xecure-key-123456789', // First char different
];
for (const attempt of attempts) {
const request = createMockRequest(attempt);
const start = performance.now();
await authenticateRequest(request, env);
const end = performance.now();
timings.push(end - start);
}
// Timing differences should be minimal (< 5ms variance)
// This is a basic check; true constant-time requires more sophisticated testing
const maxTiming = Math.max(...timings);
const minTiming = Math.min(...timings);
const variance = maxTiming - minTiming;
// Constant-time comparison should have low variance
expect(variance).toBeLessThan(10); // 10ms tolerance for test environment
});
it('should handle empty string API key gracefully', async () => {
const env = createMockEnv('non-empty-key');
const request = createMockRequest('');
const result = await authenticateRequest(request, env);
expect(result).toBe(false);
});
it('should handle very long API keys', async () => {
const longKey = 'a'.repeat(1000);
const env = createMockEnv(longKey);
const request = createMockRequest(longKey);
const result = await authenticateRequest(request, env);
expect(result).toBe(true);
});
});
});

104
src/middleware/auth.ts Normal file
View File

@@ -0,0 +1,104 @@
/**
* Authentication Middleware
*
* Validates API key in X-API-Key header using constant-time comparison
* to prevent timing attacks.
*/
import { Env } from '../types';
/**
* Authenticate incoming request using API key
*
* @param request - HTTP request to authenticate
* @param env - Cloudflare Worker environment
* @returns true if authentication succeeds, false otherwise
*/
export async function authenticateRequest(request: Request, env: Env): Promise<boolean> {
const providedKey = request.headers.get('X-API-Key');
// Missing API key in request
if (!providedKey) {
return false;
}
// Validate environment variable
const expectedKey = env.API_KEY;
if (!expectedKey) {
console.error('[Auth] API_KEY environment variable is not configured');
return false;
}
// Length comparison with safety check
if (providedKey.length !== expectedKey.length) {
return false;
}
// Use Web Crypto API for constant-time comparison
const encoder = new TextEncoder();
const providedBuffer = encoder.encode(providedKey);
const expectedBuffer = encoder.encode(expectedKey);
const providedHash = await crypto.subtle.digest('SHA-256', providedBuffer);
const expectedHash = await crypto.subtle.digest('SHA-256', expectedBuffer);
const providedArray = new Uint8Array(providedHash);
const expectedArray = new Uint8Array(expectedHash);
// Compare hashes byte by byte
let equal = true;
for (let i = 0; i < providedArray.length; i++) {
if (providedArray[i] !== expectedArray[i]) {
equal = false;
}
}
return equal;
}
/**
* Verify API key without async operations
* Used for health check endpoint to determine response mode
*
* @param providedKey - API key from request header
* @param env - Cloudflare Worker environment
* @returns true if key matches, false otherwise
*/
export function verifyApiKey(providedKey: string, env: Env): boolean {
// Validate environment variable
const expectedKey = env.API_KEY;
if (!expectedKey || !providedKey) {
return false;
}
// Length comparison with safety check
if (providedKey.length !== expectedKey.length) {
return false;
}
// Constant-time comparison to prevent timing attacks
let result = 0;
for (let i = 0; i < providedKey.length; i++) {
result |= providedKey.charCodeAt(i) ^ expectedKey.charCodeAt(i);
}
return result === 0;
}
/**
* Create 401 Unauthorized response
*/
export function createUnauthorizedResponse(): Response {
return Response.json(
{
error: 'Unauthorized',
message: 'Valid API key required. Provide X-API-Key header.',
timestamp: new Date().toISOString(),
},
{
status: 401,
headers: {
'WWW-Authenticate': 'API-Key',
},
}
);
}

16
src/middleware/index.ts Normal file
View File

@@ -0,0 +1,16 @@
/**
* Middleware Index
* Central export point for all middleware
*/
export {
authenticateRequest,
verifyApiKey,
createUnauthorizedResponse,
} from './auth';
export {
checkRateLimit,
createRateLimitResponse,
getRateLimitStatus,
} from './rateLimit';

346
src/middleware/rateLimit.test.ts Normal file
View File

@@ -0,0 +1,346 @@
/**
* Rate Limiting Middleware Tests
*
* Tests rate limiting functionality for:
* - Request counting and window management
* - Rate limit enforcement
* - Cloudflare KV integration (mocked)
* - Fail-closed behavior on errors for security
*/
import { describe, it, expect, vi, beforeEach } from 'vitest';
import {
checkRateLimit,
createRateLimitResponse,
getRateLimitStatus,
} from './rateLimit';
import type { Env } from '../types';
/**
* Mock KV namespace for testing
*/
const createMockKV = () => {
const store = new Map<string, string>();
return {
get: vi.fn(async (key: string) => store.get(key) || null),
put: vi.fn(async (key: string, value: string) => {
store.set(key, value);
}),
delete: vi.fn(async (key: string) => {
store.delete(key);
}),
list: vi.fn(),
getWithMetadata: vi.fn(),
// Helper to manually set values for testing
_setStore: (key: string, value: string) => store.set(key, value),
_clearStore: () => store.clear(),
};
};
/**
* Mock environment with KV namespace
*/
const createMockEnv = (kv: ReturnType<typeof createMockKV>): Env => ({
DB: {} as any,
RATE_LIMIT_KV: kv as any,
VAULT_URL: 'https://vault.example.com',
VAULT_TOKEN: 'test-token',
API_KEY: 'test-api-key',
});
/**
* Create mock request with client IP
*/
const createMockRequest = (ip: string = '192.168.1.1'): Request => {
const headers = new Headers();
headers.set('CF-Connecting-IP', ip);
return new Request('https://api.example.com/test', { headers });
};
describe('Rate Limiting Middleware', () => {
let mockKV: ReturnType<typeof createMockKV>;
let env: Env;
beforeEach(() => {
mockKV = createMockKV();
env = createMockEnv(mockKV);
vi.clearAllMocks();
});
describe('checkRateLimit', () => {
it('should allow first request in new window', async () => {
const request = createMockRequest('192.168.1.1');
const result = await checkRateLimit(request, '/instances', env);
expect(result.allowed).toBe(true);
expect(result.retryAfter).toBeUndefined();
expect(mockKV.put).toHaveBeenCalled();
});
it('should allow requests under rate limit', async () => {
const request = createMockRequest('192.168.1.1');
// First 3 requests should all be allowed (limit is 100 for /instances)
for (let i = 0; i < 3; i++) {
const result = await checkRateLimit(request, '/instances', env);
expect(result.allowed).toBe(true);
}
});
it('should block requests over rate limit', async () => {
const request = createMockRequest('192.168.1.1');
const now = Date.now();
// Set existing entry at limit
const entry = {
count: 100, // Already at limit
windowStart: now,
};
mockKV._setStore('ratelimit:192.168.1.1:/instances', JSON.stringify(entry));
const result = await checkRateLimit(request, '/instances', env);
expect(result.allowed).toBe(false);
expect(result.retryAfter).toBeGreaterThan(0);
});
it('should reset window after expiration', async () => {
const request = createMockRequest('192.168.1.1');
const now = Date.now();
// Set existing entry with expired window
const entry = {
count: 100,
windowStart: now - 120000, // 2 minutes ago (window is 1 minute)
};
mockKV._setStore('ratelimit:192.168.1.1:/instances', JSON.stringify(entry));
const result = await checkRateLimit(request, '/instances', env);
// Should allow because window expired
expect(result.allowed).toBe(true);
});
it('should handle different rate limits for different paths', async () => {
const request = createMockRequest('192.168.1.1');
// /instances has 100 req/min limit
const resultInstances = await checkRateLimit(request, '/instances', env);
expect(resultInstances.allowed).toBe(true);
// /sync has 10 req/min limit
const resultSync = await checkRateLimit(request, '/sync', env);
expect(resultSync.allowed).toBe(true);
// Verify different keys used
expect(mockKV.put).toHaveBeenCalledTimes(2);
});
it('should allow requests for paths without rate limit', async () => {
const request = createMockRequest('192.168.1.1');
// Path not in RATE_LIMITS config
const result = await checkRateLimit(request, '/health', env);
expect(result.allowed).toBe(true);
expect(mockKV.get).not.toHaveBeenCalled();
});
it('should handle different IPs independently', async () => {
const request1 = createMockRequest('192.168.1.1');
const request2 = createMockRequest('192.168.1.2');
const result1 = await checkRateLimit(request1, '/instances', env);
const result2 = await checkRateLimit(request2, '/instances', env);
expect(result1.allowed).toBe(true);
expect(result2.allowed).toBe(true);
// Should use different keys
const putCalls = mockKV.put.mock.calls;
expect(putCalls[0][0]).toContain('192.168.1.1');
expect(putCalls[1][0]).toContain('192.168.1.2');
});
it('should fail-closed on KV errors for security', async () => {
const request = createMockRequest('192.168.1.1');
// Mock KV error
mockKV.get.mockRejectedValue(new Error('KV connection failed'));
const result = await checkRateLimit(request, '/instances', env);
// Should block request for safety
expect(result.allowed).toBe(false);
expect(result.retryAfter).toBe(60);
});
it('should extract client IP from CF-Connecting-IP header', async () => {
const request = createMockRequest('203.0.113.5');
await checkRateLimit(request, '/instances', env);
const putCall = mockKV.put.mock.calls[0][0];
expect(putCall).toContain('203.0.113.5');
});
it('should use unique identifier when CF-Connecting-IP missing (security: ignore X-Forwarded-For)', async () => {
const headers = new Headers();
headers.set('X-Forwarded-For', '198.51.100.10, 192.168.1.1');
const request = new Request('https://api.example.com/test', { headers });
await checkRateLimit(request, '/instances', env);
// Should NOT use X-Forwarded-For (can be spoofed), use unique identifier instead
const putCall = mockKV.put.mock.calls[0][0];
expect(putCall).toContain('unknown-');
expect(putCall).not.toContain('198.51.100.10');
});
it('should handle invalid JSON in KV gracefully', async () => {
const request = createMockRequest('192.168.1.1');
// Set invalid JSON
mockKV._setStore('ratelimit:192.168.1.1:/instances', 'invalid-json{');
const result = await checkRateLimit(request, '/instances', env);
// Should treat as new window and allow
expect(result.allowed).toBe(true);
});
it('should calculate correct retry-after time', async () => {
const request = createMockRequest('192.168.1.1');
const now = Date.now();
// Set entry at limit with known window start
const entry = {
count: 100,
windowStart: now - 30000, // 30 seconds ago
};
mockKV._setStore('ratelimit:192.168.1.1:/instances', JSON.stringify(entry));
const result = await checkRateLimit(request, '/instances', env);
expect(result.allowed).toBe(false);
// Window is 60 seconds, started 30 seconds ago, so 30 seconds remaining
expect(result.retryAfter).toBeGreaterThan(25);
expect(result.retryAfter).toBeLessThan(35);
});
});
describe('createRateLimitResponse', () => {
it('should create response with 429 status', () => {
const response = createRateLimitResponse(60);
expect(response.status).toBe(429);
});
it('should include Retry-After header', () => {
const response = createRateLimitResponse(45);
expect(response.headers.get('Retry-After')).toBe('45');
expect(response.headers.get('X-RateLimit-Retry-After')).toBe('45');
});
it('should include error details in JSON body', async () => {
const response = createRateLimitResponse(30);
const body = await response.json();
expect(body).toHaveProperty('error', 'Too Many Requests');
expect(body).toHaveProperty('message');
expect(body).toHaveProperty('retry_after_seconds', 30);
expect(body).toHaveProperty('timestamp');
});
it('should include ISO 8601 timestamp', async () => {
const response = createRateLimitResponse(60);
const body = await response.json() as { timestamp: string };
const timestamp = new Date(body.timestamp);
expect(timestamp.toISOString()).toBe(body.timestamp);
});
});
describe('getRateLimitStatus', () => {
it('should return full limit for new client', async () => {
const request = createMockRequest('192.168.1.1');
const status = await getRateLimitStatus(request, '/instances', env);
expect(status).not.toBeNull();
expect(status?.limit).toBe(100);
expect(status?.remaining).toBe(100);
expect(status?.resetAt).toBeGreaterThan(Date.now());
});
it('should return remaining count for existing client', async () => {
const request = createMockRequest('192.168.1.1');
const now = Date.now();
// Client has made 25 requests
const entry = {
count: 25,
windowStart: now - 10000, // 10 seconds ago
};
mockKV._setStore('ratelimit:192.168.1.1:/instances', JSON.stringify(entry));
const status = await getRateLimitStatus(request, '/instances', env);
expect(status?.limit).toBe(100);
expect(status?.remaining).toBe(75);
});
it('should return null for paths without rate limit', async () => {
const request = createMockRequest('192.168.1.1');
const status = await getRateLimitStatus(request, '/health', env);
expect(status).toBeNull();
});
it('should handle expired window', async () => {
const request = createMockRequest('192.168.1.1');
const now = Date.now();
// Window expired 1 minute ago
const entry = {
count: 50,
windowStart: now - 120000,
};
mockKV._setStore('ratelimit:192.168.1.1:/instances', JSON.stringify(entry));
const status = await getRateLimitStatus(request, '/instances', env);
// Should show full limit available
expect(status?.remaining).toBe(100);
});
it('should return null on KV errors', async () => {
const request = createMockRequest('192.168.1.1');
mockKV.get.mockRejectedValue(new Error('KV error'));
const status = await getRateLimitStatus(request, '/instances', env);
expect(status).toBeNull();
});
it('should never return negative remaining count', async () => {
const request = createMockRequest('192.168.1.1');
const now = Date.now();
// Client exceeded limit (should not happen normally, but test edge case)
const entry = {
count: 150,
windowStart: now - 10000,
};
mockKV._setStore('ratelimit:192.168.1.1:/instances', JSON.stringify(entry));
const status = await getRateLimitStatus(request, '/instances', env);
expect(status?.remaining).toBe(0);
});
});
});

220
src/middleware/rateLimit.ts Normal file
View File

@@ -0,0 +1,220 @@
/**
* Rate Limiting Middleware - Cloudflare KV Based
*
* Distributed rate limiting using Cloudflare KV for multi-worker support.
* Different limits for different endpoints.
*/
import { Env } from '../types';
import { RATE_LIMIT_DEFAULTS, HTTP_STATUS } from '../constants';
/**
* Rate limit configuration per endpoint
*/
interface RateLimitConfig {
/** Maximum requests allowed in the time window */
maxRequests: number;
/** Time window in milliseconds */
windowMs: number;
}
/**
* Rate limit tracking entry stored in KV
*/
interface RateLimitEntry {
/** Request count in current window */
count: number;
/** Window start timestamp */
windowStart: number;
}
/**
* Rate limit configurations by endpoint
*/
const RATE_LIMITS: Record<string, RateLimitConfig> = {
'/instances': {
maxRequests: RATE_LIMIT_DEFAULTS.MAX_REQUESTS_INSTANCES,
windowMs: RATE_LIMIT_DEFAULTS.WINDOW_MS,
},
'/sync': {
maxRequests: RATE_LIMIT_DEFAULTS.MAX_REQUESTS_SYNC,
windowMs: RATE_LIMIT_DEFAULTS.WINDOW_MS,
},
};
/**
* Get client IP from request
*
* Security: Only trust CF-Connecting-IP header from Cloudflare.
* X-Forwarded-For can be spoofed by clients and should NOT be trusted.
*/
function getClientIP(request: Request): string {
// Only trust Cloudflare-provided IP header
const cfIP = request.headers.get('CF-Connecting-IP');
if (cfIP) return cfIP;
// If CF-Connecting-IP is missing, request may not be from Cloudflare
// Use unique identifier to still apply rate limit
console.warn('[RateLimit] CF-Connecting-IP missing, possible direct access');
return `unknown-${Date.now()}-${Math.random().toString(36).substring(7)}`;
}
/**
* Check if request is rate limited using Cloudflare KV
*
* @param request - HTTP request to check
* @param path - Request path for rate limit lookup
* @param env - Cloudflare Worker environment with KV binding
* @returns Object with allowed status and optional retry-after seconds
*/
export async function checkRateLimit(
request: Request,
path: string,
env: Env
): Promise<{ allowed: boolean; retryAfter?: number }> {
const config = RATE_LIMITS[path];
if (!config) {
// No rate limit configured for this path
return { allowed: true };
}
try {
const clientIP = getClientIP(request);
const now = Date.now();
const key = `ratelimit:${clientIP}:${path}`;
// Get current entry from KV
const entryJson = await env.RATE_LIMIT_KV.get(key);
let entry: RateLimitEntry | null = null;
if (entryJson) {
try {
entry = JSON.parse(entryJson);
} catch {
// Invalid JSON, treat as no entry
entry = null;
}
}
// Check if window has expired
if (!entry || entry.windowStart + config.windowMs <= now) {
// New window - allow and create new entry
const newEntry: RateLimitEntry = {
count: 1,
windowStart: now,
};
// Store with TTL (convert ms to seconds, round up)
const ttlSeconds = Math.ceil(config.windowMs / 1000);
await env.RATE_LIMIT_KV.put(key, JSON.stringify(newEntry), {
expirationTtl: ttlSeconds,
});
return { allowed: true };
}
// Increment count
entry.count++;
// Check if over limit
if (entry.count > config.maxRequests) {
const windowEnd = entry.windowStart + config.windowMs;
const retryAfter = Math.ceil((windowEnd - now) / 1000);
// Still update KV to persist the attempt
const ttlSeconds = Math.ceil((windowEnd - now) / 1000);
if (ttlSeconds > 0) {
await env.RATE_LIMIT_KV.put(key, JSON.stringify(entry), {
expirationTtl: ttlSeconds,
});
}
return { allowed: false, retryAfter };
}
// Update entry in KV
const windowEnd = entry.windowStart + config.windowMs;
const ttlSeconds = Math.ceil((windowEnd - now) / 1000);
if (ttlSeconds > 0) {
await env.RATE_LIMIT_KV.put(key, JSON.stringify(entry), {
expirationTtl: ttlSeconds,
});
}
return { allowed: true };
} catch (error) {
// Fail-closed on KV errors for security
console.error('[RateLimit] KV error, blocking request for safety:', error);
return { allowed: false, retryAfter: 60 };
}
}
/**
* Create 429 Too Many Requests response
*/
export function createRateLimitResponse(retryAfter: number): Response {
return Response.json(
{
error: 'Too Many Requests',
message: 'Rate limit exceeded. Please try again later.',
retry_after_seconds: retryAfter,
timestamp: new Date().toISOString(),
},
{
status: HTTP_STATUS.TOO_MANY_REQUESTS,
headers: {
'Retry-After': retryAfter.toString(),
'X-RateLimit-Retry-After': retryAfter.toString(),
},
}
);
}
/**
* Get current rate limit status for a client
* (useful for debugging or adding X-RateLimit-* headers)
*/
export async function getRateLimitStatus(
request: Request,
path: string,
env: Env
): Promise<{ limit: number; remaining: number; resetAt: number } | null> {
const config = RATE_LIMITS[path];
if (!config) return null;
try {
const clientIP = getClientIP(request);
const now = Date.now();
const key = `ratelimit:${clientIP}:${path}`;
const entryJson = await env.RATE_LIMIT_KV.get(key);
if (!entryJson) {
return {
limit: config.maxRequests,
remaining: config.maxRequests,
resetAt: now + config.windowMs,
};
}
const entry: RateLimitEntry = JSON.parse(entryJson);
// Check if window expired
if (entry.windowStart + config.windowMs <= now) {
return {
limit: config.maxRequests,
remaining: config.maxRequests,
resetAt: now + config.windowMs,
};
}
return {
limit: config.maxRequests,
remaining: Math.max(0, config.maxRequests - entry.count),
resetAt: entry.windowStart + config.windowMs,
};
} catch (error) {
console.error('[RateLimit] Status check error:', error);
return null;
}
}

170
src/repositories/base.ts
View File

@@ -4,9 +4,12 @@
*/
import { RepositoryError, ErrorCodes, PaginationOptions } from '../types';
import { createLogger } from '../utils/logger';
export abstract class BaseRepository<T> {
protected abstract tableName: string;
protected abstract allowedColumns: string[];
protected logger = createLogger('[BaseRepository]');
constructor(protected db: D1Database) {}
@@ -22,7 +25,11 @@ export abstract class BaseRepository<T> {
return result || null;
} catch (error) {
console.error(`[${this.tableName}] findById failed:`, error);
this.logger.error('findById failed', {
table: this.tableName,
id,
error: error instanceof Error ? error.message : 'Unknown error'
});
throw new RepositoryError(
`Failed to find ${this.tableName} by id: ${id}`,
ErrorCodes.DATABASE_ERROR,
@@ -46,7 +53,12 @@ export abstract class BaseRepository<T> {
return result.results;
} catch (error) {
console.error(`[${this.tableName}] findAll failed:`, error);
this.logger.error('findAll failed', {
table: this.tableName,
limit: options?.limit,
offset: options?.offset,
error: error instanceof Error ? error.message : 'Unknown error'
});
throw new RepositoryError(
`Failed to fetch ${this.tableName} records`,
ErrorCodes.DATABASE_ERROR,
@@ -60,8 +72,13 @@ export abstract class BaseRepository<T> {
*/
async create(data: Partial<T>): Promise<T> {
try {
const columns = Object.keys(data).join(', ');
const placeholders = Object.keys(data)
const columnNames = Object.keys(data);
// Validate column names before building SQL
this.validateColumns(columnNames);
const columns = columnNames.join(', ');
const placeholders = columnNames
.map(() => '?')
.join(', ');
const values = Object.values(data);
@@ -78,11 +95,21 @@ export abstract class BaseRepository<T> {
}
return result;
} catch (error: any) {
console.error(`[${this.tableName}] create failed:`, error);
} catch (error: unknown) {
this.logger.error('create failed', {
table: this.tableName,
columns: Object.keys(data),
error: error instanceof Error ? error.message : 'Unknown error'
});
// Re-throw RepositoryError for validation errors
if (error instanceof RepositoryError) {
throw error;
}
// Handle UNIQUE constraint violations
if (error.message?.includes('UNIQUE constraint failed')) {
const message = error instanceof Error ? error.message : String(error);
if (message.includes('UNIQUE constraint failed')) {
throw new RepositoryError(
`Duplicate entry in ${this.tableName}`,
ErrorCodes.DUPLICATE,
@@ -103,7 +130,12 @@ export abstract class BaseRepository<T> {
*/
async update(id: number, data: Partial<T>): Promise<T> {
try {
const updates = Object.keys(data)
const columnNames = Object.keys(data);
// Validate column names before building SQL
this.validateColumns(columnNames);
const updates = columnNames
.map((key) => `${key} = ?`)
.join(', ');
const values = [...Object.values(data), id];
@@ -124,7 +156,12 @@ export abstract class BaseRepository<T> {
return result;
} catch (error) {
console.error(`[${this.tableName}] update failed:`, error);
this.logger.error('update failed', {
table: this.tableName,
id,
columns: Object.keys(data),
error: error instanceof Error ? error.message : 'Unknown error'
});
if (error instanceof RepositoryError) {
throw error;
@@ -150,7 +187,11 @@ export abstract class BaseRepository<T> {
return (result.meta.changes ?? 0) > 0;
} catch (error) {
console.error(`[${this.tableName}] delete failed:`, error);
this.logger.error('delete failed', {
table: this.tableName,
id,
error: error instanceof Error ? error.message : 'Unknown error'
});
throw new RepositoryError(
`Failed to delete ${this.tableName} record with id: ${id}`,
ErrorCodes.DATABASE_ERROR,
@@ -170,7 +211,10 @@ export abstract class BaseRepository<T> {
return result?.count ?? 0;
} catch (error) {
console.error(`[${this.tableName}] count failed:`, error);
this.logger.error('count failed', {
table: this.tableName,
error: error instanceof Error ? error.message : 'Unknown error'
});
throw new RepositoryError(
`Failed to count ${this.tableName} records`,
ErrorCodes.DATABASE_ERROR,
@@ -179,16 +223,114 @@ export abstract class BaseRepository<T> {
}
}
/**
* Validate column names against whitelist to prevent SQL injection
* @throws RepositoryError if any column is invalid
*/
protected validateColumns(columns: string[]): void {
for (const col of columns) {
// Check if column is in the allowed list
if (!this.allowedColumns.includes(col)) {
throw new RepositoryError(
`Invalid column name: ${col}`,
ErrorCodes.VALIDATION_ERROR
);
}
// Validate column format (only alphanumeric and underscore, starting with letter or underscore)
if (!/^[a-z_][a-z0-9_]*$/i.test(col)) {
throw new RepositoryError(
`Invalid column format: ${col}`,
ErrorCodes.VALIDATION_ERROR
);
}
}
}
/**
* Execute batch operations within a transaction
* D1 batch operations are atomic (all succeed or all fail)
* Automatically chunks operations into batches of 100 (D1 limit)
*/
protected async executeBatch(statements: D1PreparedStatement[]): Promise<D1Result[]> {
try {
const results = await this.db.batch(statements);
return results;
const BATCH_SIZE = 100;
const totalStatements = statements.length;
// If statements fit within single batch, execute directly
if (totalStatements <= BATCH_SIZE) {
this.logger.info('Executing batch', {
table: this.tableName,
statements: totalStatements
});
const results = await this.db.batch(statements);
this.logger.info('Batch completed successfully', {
table: this.tableName
});
return results;
}
// Split into chunks of 100 and execute sequentially
const chunks = Math.ceil(totalStatements / BATCH_SIZE);
this.logger.info('Executing large batch', {
table: this.tableName,
statements: totalStatements,
chunks
});
const allResults: D1Result[] = [];
for (let i = 0; i < chunks; i++) {
const start = i * BATCH_SIZE;
const end = Math.min(start + BATCH_SIZE, totalStatements);
const chunk = statements.slice(start, end);
this.logger.info('Processing chunk', {
table: this.tableName,
chunk: i + 1,
total: chunks,
range: `${start + 1}-${end}`
});
try {
const chunkResults = await this.db.batch(chunk);
allResults.push(...chunkResults);
this.logger.info('Chunk completed successfully', {
table: this.tableName,
chunk: i + 1,
total: chunks
});
} catch (chunkError) {
this.logger.error('Chunk failed', {
table: this.tableName,
chunk: i + 1,
total: chunks,
range: `${start + 1}-${end}`,
error: chunkError instanceof Error ? chunkError.message : 'Unknown error'
});
throw new RepositoryError(
`Batch chunk ${i + 1}/${chunks} failed for ${this.tableName} (statements ${start + 1}-${end})`,
ErrorCodes.TRANSACTION_FAILED,
chunkError
);
}
}
this.logger.info('All chunks completed successfully', {
table: this.tableName,
chunks
});
return allResults;
} catch (error) {
console.error(`[${this.tableName}] batch execution failed:`, error);
// Re-throw RepositoryError from chunk processing
if (error instanceof RepositoryError) {
throw error;
}
this.logger.error('Batch execution failed', {
table: this.tableName,
error: error instanceof Error ? error.message : 'Unknown error'
});
throw new RepositoryError(
`Batch operation failed for ${this.tableName}`,
ErrorCodes.TRANSACTION_FAILED,

23
src/repositories/index.ts
View File

@@ -16,23 +16,36 @@ import { PricingRepository } from './pricing';
/**
* Repository factory for creating repository instances
* Uses lazy singleton pattern to cache repository instances
*/
export class RepositoryFactory {
constructor(private db: D1Database) {}
private _providers?: ProvidersRepository;
private _regions?: RegionsRepository;
private _instances?: InstancesRepository;
private _pricing?: PricingRepository;
constructor(private _db: D1Database) {}
/**
* Access to raw D1 database instance for advanced operations (e.g., batch queries)
*/
get db(): D1Database {
return this._db;
}
get providers(): ProvidersRepository {
return new ProvidersRepository(this.db);
return this._providers ??= new ProvidersRepository(this.db);
}
get regions(): RegionsRepository {
return new RegionsRepository(this.db);
return this._regions ??= new RegionsRepository(this.db);
}
get instances(): InstancesRepository {
return new InstancesRepository(this.db);
return this._instances ??= new InstancesRepository(this.db);
}
get pricing(): PricingRepository {
return new PricingRepository(this.db);
return this._pricing ??= new PricingRepository(this.db);
}
}

59
src/repositories/instances.ts
View File

@@ -5,9 +5,25 @@
import { BaseRepository } from './base';
import { InstanceType, InstanceTypeInput, InstanceFamily, RepositoryError, ErrorCodes } from '../types';
import { createLogger } from '../utils/logger';
export class InstancesRepository extends BaseRepository<InstanceType> {
protected tableName = 'instance_types';
protected logger = createLogger('[InstancesRepository]');
protected allowedColumns = [
'provider_id',
'instance_id',
'instance_name',
'vcpu',
'memory_mb',
'storage_gb',
'transfer_tb',
'network_speed_gbps',
'gpu_count',
'gpu_type',
'instance_family',
'metadata',
];
/**
* Find all instance types for a specific provider
@@ -21,7 +37,10 @@ export class InstancesRepository extends BaseRepository<InstanceType> {
return result.results;
} catch (error) {
console.error('[InstancesRepository] findByProvider failed:', error);
this.logger.error('findByProvider failed', {
providerId,
error: error instanceof Error ? error.message : 'Unknown error'
});
throw new RepositoryError(
`Failed to find instance types for provider: ${providerId}`,
ErrorCodes.DATABASE_ERROR,
@@ -42,7 +61,10 @@ export class InstancesRepository extends BaseRepository<InstanceType> {
return result.results;
} catch (error) {
console.error('[InstancesRepository] findByFamily failed:', error);
this.logger.error('findByFamily failed', {
family,
error: error instanceof Error ? error.message : 'Unknown error'
});
throw new RepositoryError(
`Failed to find instance types by family: ${family}`,
ErrorCodes.DATABASE_ERROR,
@@ -63,7 +85,11 @@ export class InstancesRepository extends BaseRepository<InstanceType> {
return result || null;
} catch (error) {
console.error('[InstancesRepository] findByInstanceId failed:', error);
this.logger.error('findByInstanceId failed', {
providerId,
instanceId,
error: error instanceof Error ? error.message : 'Unknown error'
});
throw new RepositoryError(
`Failed to find instance type: ${instanceId}`,
ErrorCodes.DATABASE_ERROR,
@@ -119,17 +145,24 @@ export class InstancesRepository extends BaseRepository<InstanceType> {
});
const results = await this.executeBatch(statements);
// Count successful operations
const successCount = results.reduce(
(sum, result) => sum + (result.meta.changes ?? 0),
0
);
console.log(`[InstancesRepository] Upserted ${successCount} instance types for provider ${providerId}`);
this.logger.info('Upserted instance types', {
providerId,
count: successCount
});
return successCount;
} catch (error) {
console.error('[InstancesRepository] upsertMany failed:', error);
this.logger.error('upsertMany failed', {
providerId,
count: instances.length,
error: error instanceof Error ? error.message : 'Unknown error'
});
throw new RepositoryError(
`Failed to upsert instance types for provider: ${providerId}`,
ErrorCodes.TRANSACTION_FAILED,
@@ -144,7 +177,7 @@ export class InstancesRepository extends BaseRepository<InstanceType> {
async findGpuInstances(providerId?: number): Promise<InstanceType[]> {
try {
let query = 'SELECT * FROM instance_types WHERE gpu_count > 0';
const params: any[] = [];
const params: (string | number | boolean | null)[] = [];
if (providerId !== undefined) {
query += ' AND provider_id = ?';
@@ -158,7 +191,10 @@ export class InstancesRepository extends BaseRepository<InstanceType> {
return result.results;
} catch (error) {
console.error('[InstancesRepository] findGpuInstances failed:', error);
this.logger.error('findGpuInstances failed', {
providerId,
error: error instanceof Error ? error.message : 'Unknown error'
});
throw new RepositoryError(
'Failed to find GPU instances',
ErrorCodes.DATABASE_ERROR,
@@ -181,7 +217,7 @@ export class InstancesRepository extends BaseRepository<InstanceType> {
}): Promise<InstanceType[]> {
try {
const conditions: string[] = [];
const params: any[] = [];
const params: (string | number | boolean | null)[] = [];
if (criteria.providerId !== undefined) {
conditions.push('provider_id = ?');
@@ -227,7 +263,10 @@ export class InstancesRepository extends BaseRepository<InstanceType> {
return result.results;
} catch (error) {
console.error('[InstancesRepository] search failed:', error);
this.logger.error('search failed', {
criteria,
error: error instanceof Error ? error.message : 'Unknown error'
});
throw new RepositoryError(
'Failed to search instance types',
ErrorCodes.DATABASE_ERROR,

78
src/repositories/pricing.ts
View File

@@ -5,9 +5,19 @@
import { BaseRepository } from './base';
import { Pricing, PricingInput, PriceHistory, RepositoryError, ErrorCodes } from '../types';
import { createLogger } from '../utils/logger';
export class PricingRepository extends BaseRepository<Pricing> {
protected tableName = 'pricing';
protected logger = createLogger('[PricingRepository]');
protected allowedColumns = [
'instance_type_id',
'region_id',
'hourly_price',
'monthly_price',
'currency',
'available',
];
/**
* Find pricing records for a specific instance type
@@ -21,7 +31,10 @@ export class PricingRepository extends BaseRepository<Pricing> {
return result.results;
} catch (error) {
console.error('[PricingRepository] findByInstance failed:', error);
this.logger.error('findByInstance failed', {
instanceTypeId,
error: error instanceof Error ? error.message : 'Unknown error'
});
throw new RepositoryError(
`Failed to find pricing for instance type: ${instanceTypeId}`,
ErrorCodes.DATABASE_ERROR,
@@ -42,7 +55,10 @@ export class PricingRepository extends BaseRepository<Pricing> {
return result.results;
} catch (error) {
console.error('[PricingRepository] findByRegion failed:', error);
this.logger.error('findByRegion failed', {
regionId,
error: error instanceof Error ? error.message : 'Unknown error'
});
throw new RepositoryError(
`Failed to find pricing for region: ${regionId}`,
ErrorCodes.DATABASE_ERROR,
@@ -66,7 +82,11 @@ export class PricingRepository extends BaseRepository<Pricing> {
return result || null;
} catch (error) {
console.error('[PricingRepository] findByInstanceAndRegion failed:', error);
this.logger.error('findByInstanceAndRegion failed', {
instanceTypeId,
regionId,
error: error instanceof Error ? error.message : 'Unknown error'
});
throw new RepositoryError(
`Failed to find pricing for instance ${instanceTypeId} in region ${regionId}`,
ErrorCodes.DATABASE_ERROR,
@@ -109,17 +129,20 @@ export class PricingRepository extends BaseRepository<Pricing> {
});
const results = await this.executeBatch(statements);
// Count successful operations
const successCount = results.reduce(
(sum, result) => sum + (result.meta.changes ?? 0),
0
);
console.log(`[PricingRepository] Upserted ${successCount} pricing records`);
this.logger.info('Upserted pricing records', { count: successCount });
return successCount;
} catch (error) {
console.error('[PricingRepository] upsertMany failed:', error);
this.logger.error('upsertMany failed', {
count: pricing.length,
error: error instanceof Error ? error.message : 'Unknown error'
});
throw new RepositoryError(
'Failed to upsert pricing records',
ErrorCodes.TRANSACTION_FAILED,
@@ -148,9 +171,16 @@ export class PricingRepository extends BaseRepository<Pricing> {
.bind(pricingId, hourlyPrice, monthlyPrice, now)
.run();
console.log(`[PricingRepository] Recorded price history for pricing ${pricingId}`);
this.logger.info('Recorded price history', {
pricingId,
hourlyPrice,
monthlyPrice
});
} catch (error) {
console.error('[PricingRepository] recordPriceHistory failed:', error);
this.logger.error('recordPriceHistory failed', {
pricingId,
error: error instanceof Error ? error.message : 'Unknown error'
});
throw new RepositoryError(
`Failed to record price history for pricing: ${pricingId}`,
ErrorCodes.DATABASE_ERROR,
@@ -181,7 +211,11 @@ export class PricingRepository extends BaseRepository<Pricing> {
return result.results;
} catch (error) {
console.error('[PricingRepository] getPriceHistory failed:', error);
this.logger.error('getPriceHistory failed', {
pricingId,
limit,
error: error instanceof Error ? error.message : 'Unknown error'
});
throw new RepositoryError(
`Failed to get price history for pricing: ${pricingId}`,
ErrorCodes.DATABASE_ERROR,
@@ -196,7 +230,7 @@ export class PricingRepository extends BaseRepository<Pricing> {
async findAvailable(instanceTypeId?: number, regionId?: number): Promise<Pricing[]> {
try {
let query = 'SELECT * FROM pricing WHERE available = 1';
const params: any[] = [];
const params: (string | number | boolean | null)[] = [];
if (instanceTypeId !== undefined) {
query += ' AND instance_type_id = ?';
@@ -215,7 +249,11 @@ export class PricingRepository extends BaseRepository<Pricing> {
return result.results;
} catch (error) {
console.error('[PricingRepository] findAvailable failed:', error);
this.logger.error('findAvailable failed', {
instanceTypeId,
regionId,
error: error instanceof Error ? error.message : 'Unknown error'
});
throw new RepositoryError(
'Failed to find available pricing',
ErrorCodes.DATABASE_ERROR,
@@ -235,7 +273,7 @@ export class PricingRepository extends BaseRepository<Pricing> {
): Promise<Pricing[]> {
try {
const conditions: string[] = ['available = 1'];
const params: any[] = [];
const params: (string | number | boolean | null)[] = [];
if (minHourly !== undefined) {
conditions.push('hourly_price >= ?');
@@ -266,7 +304,13 @@ export class PricingRepository extends BaseRepository<Pricing> {
return result.results;
} catch (error) {
console.error('[PricingRepository] searchByPriceRange failed:', error);
this.logger.error('searchByPriceRange failed', {
minHourly,
maxHourly,
minMonthly,
maxMonthly,
error: error instanceof Error ? error.message : 'Unknown error'
});
throw new RepositoryError(
'Failed to search pricing by price range',
ErrorCodes.DATABASE_ERROR,
@@ -294,8 +338,12 @@ export class PricingRepository extends BaseRepository<Pricing> {
return result;
} catch (error) {
console.error('[PricingRepository] updateAvailability failed:', error);
this.logger.error('updateAvailability failed', {
id,
available,
error: error instanceof Error ? error.message : 'Unknown error'
});
if (error instanceof RepositoryError) {
throw error;
}

45
src/repositories/providers.ts
View File

@@ -5,9 +5,19 @@
import { BaseRepository } from './base';
import { Provider, ProviderInput, RepositoryError, ErrorCodes } from '../types';
import { createLogger } from '../utils/logger';
export class ProvidersRepository extends BaseRepository<Provider> {
protected tableName = 'providers';
protected logger = createLogger('[ProvidersRepository]');
protected allowedColumns = [
'name',
'display_name',
'api_base_url',
'last_sync_at',
'sync_status',
'sync_error',
];
/**
* Find provider by name
@@ -21,7 +31,10 @@ export class ProvidersRepository extends BaseRepository<Provider> {
return result || null;
} catch (error) {
console.error('[ProvidersRepository] findByName failed:', error);
this.logger.error('findByName failed', {
name,
error: error instanceof Error ? error.message : 'Unknown error'
});
throw new RepositoryError(
`Failed to find provider by name: ${name}`,
ErrorCodes.DATABASE_ERROR,
@@ -40,14 +53,14 @@ export class ProvidersRepository extends BaseRepository<Provider> {
): Promise<Provider> {
try {
const now = new Date().toISOString().replace('T', ' ').slice(0, 19);
const result = await this.db
.prepare(
`UPDATE providers
SET sync_status = ?,
sync_error = ?,
`UPDATE providers
SET sync_status = ?,
sync_error = ?,
last_sync_at = ?
WHERE name = ?
WHERE name = ?
RETURNING *`
)
.bind(status, error || null, now, name)
@@ -62,8 +75,12 @@ export class ProvidersRepository extends BaseRepository<Provider> {
return result;
} catch (error) {
console.error('[ProvidersRepository] updateSyncStatus failed:', error);
this.logger.error('updateSyncStatus failed', {
name,
status,
error: error instanceof Error ? error.message : 'Unknown error'
});
if (error instanceof RepositoryError) {
throw error;
}
@@ -88,7 +105,10 @@ export class ProvidersRepository extends BaseRepository<Provider> {
return result.results;
} catch (error) {
console.error('[ProvidersRepository] findByStatus failed:', error);
this.logger.error('findByStatus failed', {
status,
error: error instanceof Error ? error.message : 'Unknown error'
});
throw new RepositoryError(
`Failed to find providers by status: ${status}`,
ErrorCodes.DATABASE_ERROR,
@@ -103,14 +123,17 @@ export class ProvidersRepository extends BaseRepository<Provider> {
async upsert(data: ProviderInput): Promise<Provider> {
try {
const existing = await this.findByName(data.name);
if (existing) {
return await this.update(existing.id, data);
}
return await this.create(data);
} catch (error) {
console.error('[ProvidersRepository] upsert failed:', error);
this.logger.error('upsert failed', {
name: data.name,
error: error instanceof Error ? error.message : 'Unknown error'
});
throw new RepositoryError(
`Failed to upsert provider: ${data.name}`,
ErrorCodes.DATABASE_ERROR,

50
src/repositories/regions.ts
View File

@@ -5,9 +5,20 @@
import { BaseRepository } from './base';
import { Region, RegionInput, RepositoryError, ErrorCodes } from '../types';
import { createLogger } from '../utils/logger';
export class RegionsRepository extends BaseRepository<Region> {
protected tableName = 'regions';
protected logger = createLogger('[RegionsRepository]');
protected allowedColumns = [
'provider_id',
'region_code',
'region_name',
'country_code',
'latitude',
'longitude',
'available',
];
/**
* Find all regions for a specific provider
@@ -21,7 +32,10 @@ export class RegionsRepository extends BaseRepository<Region> {
return result.results;
} catch (error) {
console.error('[RegionsRepository] findByProvider failed:', error);
this.logger.error('findByProvider failed', {
providerId,
error: error instanceof Error ? error.message : 'Unknown error'
});
throw new RepositoryError(
`Failed to find regions for provider: ${providerId}`,
ErrorCodes.DATABASE_ERROR,
@@ -42,7 +56,11 @@ export class RegionsRepository extends BaseRepository<Region> {
return result || null;
} catch (error) {
console.error('[RegionsRepository] findByCode failed:', error);
this.logger.error('findByCode failed', {
providerId,
code,
error: error instanceof Error ? error.message : 'Unknown error'
});
throw new RepositoryError(
`Failed to find region by code: ${code}`,
ErrorCodes.DATABASE_ERROR,
@@ -87,17 +105,24 @@ export class RegionsRepository extends BaseRepository<Region> {
});
const results = await this.executeBatch(statements);
// Count successful operations
const successCount = results.reduce(
(sum, result) => sum + (result.meta.changes ?? 0),
0
);
console.log(`[RegionsRepository] Upserted ${successCount} regions for provider ${providerId}`);
this.logger.info('Upserted regions', {
providerId,
count: successCount
});
return successCount;
} catch (error) {
console.error('[RegionsRepository] upsertMany failed:', error);
this.logger.error('upsertMany failed', {
providerId,
count: regions.length,
error: error instanceof Error ? error.message : 'Unknown error'
});
throw new RepositoryError(
`Failed to upsert regions for provider: ${providerId}`,
ErrorCodes.TRANSACTION_FAILED,
@@ -112,7 +137,7 @@ export class RegionsRepository extends BaseRepository<Region> {
async findAvailable(providerId?: number): Promise<Region[]> {
try {
let query = 'SELECT * FROM regions WHERE available = 1';
const params: any[] = [];
const params: (string | number | boolean | null)[] = [];
if (providerId !== undefined) {
query += ' AND provider_id = ?';
@@ -126,7 +151,10 @@ export class RegionsRepository extends BaseRepository<Region> {
return result.results;
} catch (error) {
console.error('[RegionsRepository] findAvailable failed:', error);
this.logger.error('findAvailable failed', {
providerId,
error: error instanceof Error ? error.message : 'Unknown error'
});
throw new RepositoryError(
'Failed to find available regions',
ErrorCodes.DATABASE_ERROR,
@@ -154,8 +182,12 @@ export class RegionsRepository extends BaseRepository<Region> {
return result;
} catch (error) {
console.error('[RegionsRepository] updateAvailability failed:', error);
this.logger.error('updateAvailability failed', {
id,
available,
error: error instanceof Error ? error.message : 'Unknown error'
});
if (error instanceof RepositoryError) {
throw error;
}

156
src/routes/health.ts
View File

@@ -4,7 +4,7 @@
*/
import { Env } from '../types';
import { RepositoryFactory } from '../repositories';
import { HTTP_STATUS } from '../constants';
/**
* Component health status
@@ -34,11 +34,17 @@ interface DatabaseHealth {
}
/**
* Health check response structure
* Public health check response (no authentication)
*/
interface HealthCheckResponse {
interface PublicHealthResponse {
status: ComponentStatus;
timestamp: string;
}
/**
* Detailed health check response (requires authentication)
*/
interface DetailedHealthResponse extends PublicHealthResponse {
components: {
database: DatabaseHealth;
providers: ProviderHealth[];
@@ -138,24 +144,51 @@ function getOverallStatus(
}
/**
* Handle health check request
* Sanitize error message for production
* Removes sensitive stack traces and internal details
*/
export async function handleHealth(env: Env): Promise<Response> {
function sanitizeError(error: string): string {
// In production, only return generic error codes
// Remove stack traces and internal paths
const lines = error.split('\n');
return lines[0]; // Return only first line (error message without stack)
}
/**
* Handle health check request
* @param env - Cloudflare Worker environment
* @param authenticated - Whether the request is authenticated (default: false)
*/
export async function handleHealth(
env: Env,
authenticated: boolean = false
): Promise<Response> {
const timestamp = new Date().toISOString();
try {
const repos = new RepositoryFactory(env.DB);
// Check database health
const dbHealth = await checkDatabaseHealth(env.DB);
// If database is unhealthy, return early
if (dbHealth.status === 'unhealthy') {
const response: HealthCheckResponse = {
// Public response: minimal information
if (!authenticated) {
const publicResponse: PublicHealthResponse = {
status: 'unhealthy',
timestamp,
};
return Response.json(publicResponse, { status: HTTP_STATUS.SERVICE_UNAVAILABLE });
}
// Detailed response: full information with sanitized errors
const detailedResponse: DetailedHealthResponse = {
status: 'unhealthy',
timestamp,
components: {
database: dbHealth,
database: {
status: dbHealth.status,
error: dbHealth.error ? sanitizeError(dbHealth.error) : undefined,
},
providers: [],
},
summary: {
@@ -166,29 +199,43 @@ export async function handleHealth(env: Env): Promise<Response> {
},
};
return Response.json(response, { status: 503 });
return Response.json(detailedResponse, { status: HTTP_STATUS.SERVICE_UNAVAILABLE });
}
// Get all providers
const providers = await repos.providers.findAll();
// Get all providers with aggregated counts in a single query
const providersWithCounts = await env.DB.prepare(`
SELECT
p.id,
p.name,
p.display_name,
p.api_base_url,
p.last_sync_at,
p.sync_status,
p.sync_error,
(SELECT COUNT(*) FROM regions WHERE provider_id = p.id) as regions_count,
(SELECT COUNT(*) FROM instance_types WHERE provider_id = p.id) as instances_count
FROM providers p
`).all<{
id: number;
name: string;
display_name: string;
api_base_url: string | null;
last_sync_at: string | null;
sync_status: string;
sync_error: string | null;
regions_count: number;
instances_count: number;
}>();
if (!providersWithCounts.success) {
throw new Error('Failed to fetch provider data');
}
// Build provider health information
const providerHealthList: ProviderHealth[] = [];
const providerStatuses: ComponentStatus[] = [];
for (const provider of providers) {
// Get counts for this provider
const [regionsResult, instancesResult] = await Promise.all([
env.DB.prepare('SELECT COUNT(*) as count FROM regions WHERE provider_id = ?')
.bind(provider.id)
.first<{ count: number }>(),
env.DB.prepare(
'SELECT COUNT(*) as count FROM instance_types WHERE provider_id = ?'
)
.bind(provider.id)
.first<{ count: number }>(),
]);
for (const provider of providersWithCounts.results) {
const status = getProviderStatus(provider.last_sync_at, provider.sync_status);
providerStatuses.push(status);
@@ -197,13 +244,13 @@ export async function handleHealth(env: Env): Promise<Response> {
status,
last_sync: provider.last_sync_at,
sync_status: provider.sync_status,
regions_count: regionsResult?.count || 0,
instances_count: instancesResult?.count || 0,
regions_count: provider.regions_count,
instances_count: provider.instances_count,
};
// Add error if present
if (provider.sync_error) {
providerHealth.error = provider.sync_error;
// Add sanitized error if present (only for authenticated requests)
if (authenticated && provider.sync_error) {
providerHealth.error = sanitizeError(provider.sync_error);
}
providerHealthList.push(providerHealth);
@@ -211,11 +258,11 @@ export async function handleHealth(env: Env): Promise<Response> {
// Calculate summary statistics
const totalRegions = providerHealthList.reduce(
(sum, p) => sum + (p.regions_count || 0),
(sum, p) => sum + (p.regions_count ?? 0),
0
);
const totalInstances = providerHealthList.reduce(
(sum, p) => sum + (p.instances_count || 0),
(sum, p) => sum + (p.instances_count ?? 0),
0
);
const healthyProviders = providerStatuses.filter(s => s === 'healthy').length;
@@ -223,35 +270,60 @@ export async function handleHealth(env: Env): Promise<Response> {
// Determine overall status
const overallStatus = getOverallStatus(dbHealth.status, providerStatuses);
const response: HealthCheckResponse = {
// Return 200 for healthy, 503 for degraded/unhealthy
const statusCode = overallStatus === 'healthy' ? HTTP_STATUS.OK : HTTP_STATUS.SERVICE_UNAVAILABLE;
// Public response: minimal information
if (!authenticated) {
const publicResponse: PublicHealthResponse = {
status: overallStatus,
timestamp,
};
return Response.json(publicResponse, { status: statusCode });
}
// Detailed response: full information
const detailedResponse: DetailedHealthResponse = {
status: overallStatus,
timestamp,
components: {
database: dbHealth,
database: {
status: dbHealth.status,
latency_ms: dbHealth.latency_ms,
error: dbHealth.error ? sanitizeError(dbHealth.error) : undefined,
},
providers: providerHealthList,
},
summary: {
total_providers: providers.length,
total_providers: providersWithCounts.results.length,
healthy_providers: healthyProviders,
total_regions: totalRegions,
total_instances: totalInstances,
},
};
// Return 200 for healthy, 503 for degraded/unhealthy
const statusCode = overallStatus === 'healthy' ? 200 : 503;
return Response.json(response, { status: statusCode });
return Response.json(detailedResponse, { status: statusCode });
} catch (error) {
console.error('[Health] Health check failed:', error);
const errorResponse: HealthCheckResponse = {
// Public response: minimal information
if (!authenticated) {
const publicResponse: PublicHealthResponse = {
status: 'unhealthy',
timestamp,
};
return Response.json(publicResponse, { status: HTTP_STATUS.SERVICE_UNAVAILABLE });
}
// Detailed response: sanitized error information
const errorMessage = error instanceof Error ? error.message : 'Health check failed';
const detailedResponse: DetailedHealthResponse = {
status: 'unhealthy',
timestamp,
components: {
database: {
status: 'unhealthy',
error: error instanceof Error ? error.message : 'Health check failed',
error: sanitizeError(errorMessage),
},
providers: [],
},
@@ -263,6 +335,6 @@ export async function handleHealth(env: Env): Promise<Response> {
},
};
return Response.json(errorResponse, { status: 503 });
return Response.json(detailedResponse, { status: HTTP_STATUS.SERVICE_UNAVAILABLE });
}
}

1
src/routes/index.ts
View File

@@ -6,3 +6,4 @@
export { handleSync } from './sync';
export { handleInstances } from './instances';
export { handleHealth } from './health';
export { handleRecommend } from './recommend';

300
src/routes/instances.ts
View File

@@ -5,7 +5,57 @@
* Integrates with cache service for performance optimization.
*/
import type { Env } from '../types';
import type { Env, InstanceQueryParams } from '../types';
import { QueryService } from '../services/query';
import { CacheService } from '../services/cache';
import { logger } from '../utils/logger';
import {
SUPPORTED_PROVIDERS,
type SupportedProvider,
VALID_SORT_FIELDS,
INSTANCE_FAMILIES,
PAGINATION,
CACHE_TTL,
HTTP_STATUS,
} from '../constants';
/**
* Worker-level service singleton cache
* Performance optimization: Reuse service instances across requests within same Worker instance
*
* Benefits:
* - Reduces GC pressure by avoiding object creation per request
* - Maintains service state (e.g., logger initialization) across requests
* - Safe for Cloudflare Workers as Worker instances are isolated and stateless
*
* Note: Worker instances are recreated periodically, preventing memory leaks
*/
let cachedQueryService: QueryService | null = null;
let cachedCacheService: CacheService | null = null;
/**
* Get or create QueryService singleton
* Lazy initialization on first request, then reused for subsequent requests
*/
function getQueryService(db: D1Database, env: Env): QueryService {
if (!cachedQueryService) {
cachedQueryService = new QueryService(db, env);
logger.debug('[Instances] QueryService singleton initialized');
}
return cachedQueryService;
}
/**
* Get or create CacheService singleton
* Lazy initialization on first request, then reused for subsequent requests
*/
function getCacheService(): CacheService {
if (!cachedCacheService) {
cachedCacheService = new CacheService(CACHE_TTL.INSTANCES);
logger.debug('[Instances] CacheService singleton initialized');
}
return cachedCacheService;
}
/**
* Parsed and validated query parameters
@@ -26,40 +76,6 @@ interface ParsedQueryParams {
offset: number;
}
/**
* Supported cloud providers
*/
const SUPPORTED_PROVIDERS = ['linode', 'vultr', 'aws'] as const;
type SupportedProvider = typeof SUPPORTED_PROVIDERS[number];
/**
* Valid sort fields
*/
const VALID_SORT_FIELDS = [
'price',
'hourly_price',
'monthly_price',
'vcpu',
'memory_mb',
'memory_gb',
'storage_gb',
'instance_name',
'provider',
'region'
] as const;
/**
* Valid instance families
*/
const VALID_FAMILIES = ['general', 'compute', 'memory', 'storage', 'gpu'] as const;
/**
* Default query parameters
*/
const DEFAULT_LIMIT = 50;
const MAX_LIMIT = 100;
const DEFAULT_OFFSET = 0;
/**
* Validate provider name
*/
@@ -78,7 +94,7 @@ function isValidSortField(field: string): boolean {
* Validate instance family
*/
function isValidFamily(family: string): boolean {
return VALID_FAMILIES.includes(family as typeof VALID_FAMILIES[number]);
return INSTANCE_FAMILIES.includes(family as typeof INSTANCE_FAMILIES[number]);
}
/**
@@ -90,8 +106,8 @@ function parseQueryParams(url: URL): {
} {
const searchParams = url.searchParams;
const params: ParsedQueryParams = {
limit: DEFAULT_LIMIT,
offset: DEFAULT_OFFSET,
limit: PAGINATION.DEFAULT_LIMIT,
offset: PAGINATION.DEFAULT_OFFSET,
};
// Provider validation
@@ -119,7 +135,7 @@ function parseQueryParams(url: URL): {
function parsePositiveNumber(
name: string,
value: string | null
): number | undefined | { error: any } {
): number | undefined | { error: { code: string; message: string; parameter: string } } {
if (value === null) return undefined;
const parsed = Number(value);
@@ -187,7 +203,7 @@ function parseQueryParams(url: URL): {
return {
error: {
code: 'INVALID_PARAMETER',
message: `Invalid instance_family: ${family}. Valid values: ${VALID_FAMILIES.join(', ')}`,
message: `Invalid instance_family: ${family}. Valid values: ${INSTANCE_FAMILIES.join(', ')}`,
parameter: 'instance_family',
},
};
@@ -244,11 +260,11 @@ function parseQueryParams(url: URL): {
const limitStr = searchParams.get('limit');
if (limitStr !== null) {
const limit = Number(limitStr);
if (isNaN(limit) || limit < 1 || limit > MAX_LIMIT) {
if (isNaN(limit) || limit < 1 || limit > PAGINATION.MAX_LIMIT) {
return {
error: {
code: 'INVALID_PARAMETER',
message: `Invalid limit: must be between 1 and ${MAX_LIMIT}`,
message: `Invalid limit: must be between 1 and ${PAGINATION.MAX_LIMIT}`,
parameter: 'limit',
},
};
@@ -275,29 +291,6 @@ function parseQueryParams(url: URL): {
return { params };
}
/**
* Generate cache key from query parameters
* TODO: Replace with cacheService.generateKey(params) when cache service is implemented
*/
function generateCacheKey(params: ParsedQueryParams): string {
const parts: string[] = ['instances'];
if (params.provider) parts.push(`provider:${params.provider}`);
if (params.region) parts.push(`region:${params.region}`);
if (params.min_vcpu !== undefined) parts.push(`min_vcpu:${params.min_vcpu}`);
if (params.max_vcpu !== undefined) parts.push(`max_vcpu:${params.max_vcpu}`);
if (params.min_memory_gb !== undefined) parts.push(`min_memory:${params.min_memory_gb}`);
if (params.max_memory_gb !== undefined) parts.push(`max_memory:${params.max_memory_gb}`);
if (params.max_price !== undefined) parts.push(`max_price:${params.max_price}`);
if (params.instance_family) parts.push(`family:${params.instance_family}`);
if (params.has_gpu !== undefined) parts.push(`gpu:${params.has_gpu}`);
if (params.sort_by) parts.push(`sort:${params.sort_by}`);
if (params.order) parts.push(`order:${params.order}`);
parts.push(`limit:${params.limit}`);
parts.push(`offset:${params.offset}`);
return parts.join('|');
}
/**
* Handle GET /instances endpoint
@@ -311,11 +304,11 @@ function generateCacheKey(params: ParsedQueryParams): string {
*/
export async function handleInstances(
request: Request,
_env: Env
env: Env
): Promise<Response> {
const startTime = Date.now();
console.log('[Instances] Request received', { url: request.url });
logger.info('[Instances] Request received', { url: request.url });
try {
// Parse URL and query parameters
@@ -324,79 +317,146 @@ export async function handleInstances(
// Handle validation errors
if (parseResult.error) {
console.error('[Instances] Validation error', parseResult.error);
logger.error('[Instances] Validation error', parseResult.error);
return Response.json(
{
success: false,
error: parseResult.error,
},
{ status: 400 }
{ status: HTTP_STATUS.BAD_REQUEST }
);
}
const params = parseResult.params!;
console.log('[Instances] Query params validated', params);
logger.info('[Instances] Query params validated', params as unknown as Record<string, unknown>);
// Generate cache key
const cacheKey = generateCacheKey(params);
console.log('[Instances] Cache key generated', { cacheKey });
// Get cache service singleton (reused across requests)
const cacheService = getCacheService();
// TODO: Implement cache check
// const cacheService = new CacheService(env);
// const cached = await cacheService.get(cacheKey);
// if (cached) {
// console.log('[Instances] Cache hit', { cacheKey, age: cached.cache_age_seconds });
// return Response.json({
// success: true,
// data: {
// ...cached.data,
// metadata: {
// cached: true,
// cache_age_seconds: cached.cache_age_seconds,
// },
// },
// });
// }
// Generate cache key from query parameters
const cacheKey = cacheService.generateKey(params as unknown as Record<string, unknown>);
logger.info('[Instances] Cache key generated', { cacheKey });
console.log('[Instances] Cache miss (or cache service not implemented)');
// Check cache first
interface CachedData {
instances: unknown[];
pagination: {
total: number;
limit: number;
offset: number;
has_more: boolean;
};
metadata: {
cached: boolean;
last_sync: string;
query_time_ms: number;
filters_applied: unknown;
};
}
// TODO: Implement database query
// const queryService = new QueryService(env.DB);
// const result = await queryService.queryInstances(params);
const cached = await cacheService.get<CachedData>(cacheKey);
if (cached) {
logger.info('[Instances] Cache hit', {
cacheKey,
age: cached.cache_age_seconds,
});
return Response.json(
{
success: true,
data: {
...cached.data,
metadata: {
...cached.data.metadata,
cached: true,
cache_age_seconds: cached.cache_age_seconds,
cached_at: cached.cached_at,
},
},
},
{
status: HTTP_STATUS.OK,
headers: {
'Cache-Control': `public, max-age=${CACHE_TTL.INSTANCES}`,
},
}
);
}
logger.info('[Instances] Cache miss');
// Map route parameters to QueryService parameters
const queryParams: InstanceQueryParams = {
provider: params.provider,
region_code: params.region,
family: params.instance_family as 'general' | 'compute' | 'memory' | 'storage' | 'gpu' | undefined,
min_vcpu: params.min_vcpu,
max_vcpu: params.max_vcpu,
min_memory: params.min_memory_gb ? params.min_memory_gb * 1024 : undefined, // Convert GB to MB
max_memory: params.max_memory_gb ? params.max_memory_gb * 1024 : undefined, // Convert GB to MB
min_price: undefined, // Route doesn't expose min_price
max_price: params.max_price,
has_gpu: params.has_gpu,
sort_by: params.sort_by,
sort_order: params.order,
page: Math.floor(params.offset / params.limit) + 1, // Convert offset to page
limit: params.limit,
};
// Get QueryService singleton (reused across requests)
const queryService = getQueryService(env.DB, env);
const result = await queryService.queryInstances(queryParams);
// Placeholder response until query service is implemented
const queryTime = Date.now() - startTime;
const placeholderResponse = {
success: true,
data: {
instances: [],
pagination: {
total: 0,
limit: params.limit,
offset: params.offset,
has_more: false,
},
metadata: {
cached: false,
last_sync: new Date().toISOString(),
query_time_ms: queryTime,
},
logger.info('[Instances] Query executed', {
queryTime,
results: result.data.length,
total: result.pagination.total_results,
});
// Prepare response data
const responseData = {
instances: result.data,
pagination: {
total: result.pagination.total_results,
limit: params.limit,
offset: params.offset,
has_more: result.pagination.has_next,
},
metadata: {
cached: false,
last_sync: new Date().toISOString(),
query_time_ms: queryTime,
filters_applied: result.meta.filters_applied,
},
};
console.log('[Instances] TODO: Implement query service');
console.log('[Instances] Placeholder response generated', {
queryTime,
cacheKey,
});
// Store result in cache
try {
await cacheService.set(cacheKey, responseData, CACHE_TTL.INSTANCES);
} catch (error) {
// Graceful degradation: log error but don't fail the request
logger.error('[Instances] Cache write failed',
error instanceof Error ? { message: error.message } : { error: String(error) });
}
// TODO: Implement cache storage
// await cacheService.set(cacheKey, result);
return Response.json(placeholderResponse, { status: 200 });
return Response.json(
{
success: true,
data: responseData,
},
{
status: HTTP_STATUS.OK,
headers: {
'Cache-Control': `public, max-age=${CACHE_TTL.INSTANCES}`,
},
}
);
} catch (error) {
console.error('[Instances] Unexpected error', { error });
logger.error('[Instances] Unexpected error', { error });
return Response.json(
{
@@ -407,7 +467,7 @@ export async function handleInstances(
details: error instanceof Error ? error.message : 'Unknown error',
},
},
{ status: 500 }
{ status: HTTP_STATUS.INTERNAL_ERROR }
);
}
}

282
src/routes/recommend.ts Normal file
View File

@@ -0,0 +1,282 @@
/**
* Recommendation Route Handler
*
* Endpoint for getting cloud instance recommendations based on tech stack.
* Validates request parameters and returns ranked instance recommendations.
*/
import type { Env, ScaleType } from '../types';
import { RecommendationService } from '../services/recommendation';
import { validateStack, STACK_REQUIREMENTS } from '../services/stackConfig';
import { CacheService } from '../services/cache';
import { logger } from '../utils/logger';
import { HTTP_STATUS, CACHE_TTL, REQUEST_LIMITS } from '../constants';
import {
parseJsonBody,
validateStringArray,
validateEnum,
validatePositiveNumber,
createErrorResponse,
} from '../utils/validation';
/**
* Request body interface for recommendation endpoint
*/
interface RecommendRequestBody {
stack?: unknown;
scale?: unknown;
budget_max?: unknown;
}
/**
* Supported scale types
*/
const SUPPORTED_SCALES: readonly ScaleType[] = ['small', 'medium', 'large'] as const;
/**
* Handle POST /recommend endpoint
*
* @param request - HTTP request object
* @param env - Cloudflare Worker environment bindings
* @returns JSON response with recommendations
*
* @example
* POST /recommend
* {
* "stack": ["nginx", "mysql", "redis"],
* "scale": "medium",
* "budget_max": 100
* }
*/
export async function handleRecommend(request: Request, env: Env): Promise<Response> {
const startTime = Date.now();
logger.info('[Recommend] Request received');
try {
// 1. Validate request size to prevent memory exhaustion attacks
const contentLength = request.headers.get('content-length');
if (contentLength) {
const bodySize = parseInt(contentLength, 10);
if (isNaN(bodySize) || bodySize > REQUEST_LIMITS.MAX_BODY_SIZE) {
logger.error('[Recommend] Request body too large', {
contentLength: bodySize,
maxAllowed: REQUEST_LIMITS.MAX_BODY_SIZE,
});
return Response.json(
{
success: false,
error: {
code: 'PAYLOAD_TOO_LARGE',
message: `Request body exceeds maximum size of ${REQUEST_LIMITS.MAX_BODY_SIZE} bytes`,
details: {
max_size_bytes: REQUEST_LIMITS.MAX_BODY_SIZE,
received_bytes: bodySize,
},
},
},
{ status: HTTP_STATUS.PAYLOAD_TOO_LARGE }
);
}
}
// 2. Parse request body
const parseResult = await parseJsonBody<RecommendRequestBody>(request);
if (!parseResult.success) {
logger.error('[Recommend] JSON parsing failed', {
code: parseResult.error.code,
message: parseResult.error.message,
});
return createErrorResponse(parseResult.error);
}
const body = parseResult.data;
// 3. Validate stack parameter
const stackResult = validateStringArray(body.stack, 'stack');
if (!stackResult.success) {
logger.error('[Recommend] Stack validation failed', {
code: stackResult.error.code,
message: stackResult.error.message,
});
// Add supported stacks to error details
const enrichedError = {
...stackResult.error,
details: {
...((stackResult.error.details as object) || {}),
supported: Object.keys(STACK_REQUIREMENTS),
},
};
return createErrorResponse(enrichedError);
}
const stack = stackResult.data;
// 4. Validate scale parameter
const scaleResult = validateEnum(body.scale, 'scale', SUPPORTED_SCALES);
if (!scaleResult.success) {
logger.error('[Recommend] Scale validation failed', {
code: scaleResult.error.code,
message: scaleResult.error.message,
});
return createErrorResponse(scaleResult.error);
}
const scale = scaleResult.data;
// 5. Validate budget_max parameter (optional)
let budgetMax: number | undefined;
if (body.budget_max !== undefined) {
const budgetResult = validatePositiveNumber(body.budget_max, 'budget_max');
if (!budgetResult.success) {
logger.error('[Recommend] Budget validation failed', {
code: budgetResult.error.code,
message: budgetResult.error.message,
});
return createErrorResponse(budgetResult.error);
}
budgetMax = budgetResult.data;
}
// 6. Validate stack components against supported technologies
const validation = validateStack(stack);
if (!validation.valid) {
logger.error('[Recommend] Unsupported stack components', {
invalidStacks: validation.invalidStacks,
});
return createErrorResponse({
code: 'INVALID_STACK',
message: `Unsupported stacks: ${validation.invalidStacks.join(', ')}`,
details: {
invalid: validation.invalidStacks,
supported: Object.keys(STACK_REQUIREMENTS),
},
});
}
// 7. Initialize cache service and generate cache key
logger.info('[Recommend] Validation passed', { stack, scale, budgetMax });
const cacheService = new CacheService(CACHE_TTL.INSTANCES);
// Generate cache key from sorted stack, scale, and budget
// Sort stack to ensure consistent cache keys regardless of order
const sortedStack = [...stack].sort();
const cacheKey = cacheService.generateKey({
endpoint: 'recommend',
stack: sortedStack.join(','),
scale,
budget_max: budgetMax ?? 'none',
});
logger.info('[Recommend] Cache key generated', { cacheKey });
// 8. Check cache first
interface CachedRecommendation {
recommendations: unknown[];
stack_analysis: unknown;
metadata: {
cached?: boolean;
cache_age_seconds?: number;
cached_at?: string;
query_time_ms: number;
};
}
const cached = await cacheService.get<CachedRecommendation>(cacheKey);
if (cached) {
logger.info('[Recommend] Cache hit', {
cacheKey,
age: cached.cache_age_seconds,
});
return Response.json(
{
success: true,
data: {
...cached.data,
metadata: {
...cached.data.metadata,
cached: true,
cache_age_seconds: cached.cache_age_seconds,
cached_at: cached.cached_at,
},
},
},
{
status: HTTP_STATUS.OK,
headers: {
'Cache-Control': `public, max-age=${CACHE_TTL.INSTANCES}`,
},
}
);
}
logger.info('[Recommend] Cache miss');
// 9. Call recommendation service
const service = new RecommendationService(env.DB);
const result = await service.recommend({
stack,
scale,
budget_max: budgetMax,
});
const duration = Date.now() - startTime;
logger.info('[Recommend] Recommendation completed', {
duration_ms: duration,
recommendations_count: result.recommendations.length,
});
// Prepare response data with metadata
const responseData = {
...result,
metadata: {
cached: false,
query_time_ms: duration,
},
};
// 10. Store result in cache
try {
await cacheService.set(cacheKey, responseData, CACHE_TTL.INSTANCES);
} catch (error) {
// Graceful degradation: log error but don't fail the request
logger.error('[Recommend] Cache write failed',
error instanceof Error ? { message: error.message } : { error: String(error) });
}
return Response.json(
{
success: true,
data: responseData,
},
{
status: HTTP_STATUS.OK,
headers: {
'Cache-Control': `public, max-age=${CACHE_TTL.INSTANCES}`,
},
}
);
} catch (error) {
logger.error('[Recommend] Unexpected error', { error });
const duration = Date.now() - startTime;
return Response.json(
{
success: false,
error: {
code: 'INTERNAL_ERROR',
message: error instanceof Error ? error.message : 'Unknown error',
details: {
duration_ms: duration,
},
},
},
{ status: HTTP_STATUS.INTERNAL_ERROR }
);
}
}

189
src/routes/sync.ts
View File

@@ -5,7 +5,12 @@
* Validates request parameters and orchestrates sync operations.
*/
import type { Env, SyncReport } from '../types';
import type { Env } from '../types';
import { SyncOrchestrator } from '../services/sync';
import { VaultClient } from '../connectors/vault';
import { logger } from '../utils/logger';
import { SUPPORTED_PROVIDERS, HTTP_STATUS } from '../constants';
import { parseJsonBody, validateProviders, createErrorResponse } from '../utils/validation';
/**
* Request body interface for sync endpoint
@@ -15,18 +20,6 @@ interface SyncRequestBody {
force?: boolean;
}
/**
* Supported cloud providers
*/
const SUPPORTED_PROVIDERS = ['linode', 'vultr', 'aws'] as const;
type SupportedProvider = typeof SUPPORTED_PROVIDERS[number];
/**
* Validate if provider is supported
*/
function isSupportedProvider(provider: string): provider is SupportedProvider {
return SUPPORTED_PROVIDERS.includes(provider as SupportedProvider);
}
/**
* Handle POST /sync endpoint
@@ -44,166 +37,80 @@ function isSupportedProvider(provider: string): provider is SupportedProvider {
*/
export async function handleSync(
request: Request,
_env: Env
env: Env
): Promise<Response> {
const startTime = Date.now();
const startedAt = new Date().toISOString();
console.log('[Sync] Request received', { timestamp: startedAt });
logger.info('[Sync] Request received', { timestamp: startedAt });
try {
// Parse and validate request body
const contentType = request.headers.get('content-type');
let body: SyncRequestBody = {};
try {
const contentType = request.headers.get('content-type');
if (contentType && contentType.includes('application/json')) {
body = await request.json() as SyncRequestBody;
// Only parse JSON if content-type is set
if (contentType && contentType.includes('application/json')) {
const parseResult = await parseJsonBody<SyncRequestBody>(request);
if (!parseResult.success) {
logger.error('[Sync] Invalid JSON in request body', {
code: parseResult.error.code,
message: parseResult.error.message,
});
return createErrorResponse(parseResult.error);
}
} catch (error) {
console.error('[Sync] Invalid JSON in request body', { error });
return Response.json(
{
success: false,
error: {
code: 'INVALID_REQUEST',
message: 'Invalid JSON in request body',
details: error instanceof Error ? error.message : 'Unknown error'
}
},
{ status: 400 }
);
body = parseResult.data;
}
// Validate providers array
// Validate providers array (default to ['linode'] if not provided)
const providers = body.providers || ['linode'];
const providerResult = validateProviders(providers, SUPPORTED_PROVIDERS);
if (!Array.isArray(providers)) {
console.error('[Sync] Providers must be an array', { providers });
return Response.json(
{
success: false,
error: {
code: 'INVALID_PROVIDERS',
message: 'Providers must be an array',
details: { received: typeof providers }
}
},
{ status: 400 }
);
}
if (providers.length === 0) {
console.error('[Sync] Providers array is empty');
return Response.json(
{
success: false,
error: {
code: 'EMPTY_PROVIDERS',
message: 'At least one provider must be specified',
details: null
}
},
{ status: 400 }
);
}
// Validate each provider
const unsupportedProviders: string[] = [];
for (const provider of providers) {
if (typeof provider !== 'string') {
console.error('[Sync] Provider must be a string', { provider });
return Response.json(
{
success: false,
error: {
code: 'INVALID_PROVIDER_TYPE',
message: 'Each provider must be a string',
details: { provider, type: typeof provider }
}
},
{ status: 400 }
);
}
if (!isSupportedProvider(provider)) {
unsupportedProviders.push(provider);
}
}
if (unsupportedProviders.length > 0) {
console.error('[Sync] Unsupported providers', { unsupportedProviders });
return Response.json(
{
success: false,
error: {
code: 'UNSUPPORTED_PROVIDERS',
message: `Unsupported providers: ${unsupportedProviders.join(', ')}`,
details: {
unsupported: unsupportedProviders,
supported: SUPPORTED_PROVIDERS
}
}
},
{ status: 400 }
);
if (!providerResult.success) {
logger.error('[Sync] Provider validation failed', {
code: providerResult.error.code,
message: providerResult.error.message,
});
return createErrorResponse(providerResult.error);
}
const force = body.force === true;
console.log('[Sync] Validation passed', { providers, force });
logger.info('[Sync] Validation passed', { providers, force });
// TODO: Once SyncOrchestrator is implemented, use it here
// For now, return a placeholder response
// Initialize Vault client
const vault = new VaultClient(env.VAULT_URL, env.VAULT_TOKEN, env);
// const syncOrchestrator = new SyncOrchestrator(env.DB, env.VAULT_URL, env.VAULT_TOKEN);
// const syncReport = await syncOrchestrator.syncProviders(providers, force);
// Initialize SyncOrchestrator
const orchestrator = new SyncOrchestrator(env.DB, vault, env);
// Placeholder sync report
const completedAt = new Date().toISOString();
const totalDuration = Date.now() - startTime;
const syncId = `sync_${Date.now()}`;
// Execute synchronization
logger.info('[Sync] Starting synchronization', { providers });
const syncReport = await orchestrator.syncAll(providers);
console.log('[Sync] TODO: Implement actual sync logic');
console.log('[Sync] Placeholder response generated', { syncId, totalDuration });
// Generate unique sync ID
const syncId = `sync_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
// Return placeholder success response
const placeholderReport: SyncReport = {
success: true,
started_at: startedAt,
completed_at: completedAt,
total_duration_ms: totalDuration,
providers: providers.map(providerName => ({
provider: providerName,
success: true,
regions_synced: 0,
instances_synced: 0,
pricing_synced: 0,
duration_ms: 0,
})),
summary: {
total_providers: providers.length,
successful_providers: providers.length,
failed_providers: 0,
total_regions: 0,
total_instances: 0,
total_pricing: 0,
}
};
logger.info('[Sync] Synchronization completed', {
syncId,
success: syncReport.success,
duration: syncReport.total_duration_ms,
summary: syncReport.summary
});
return Response.json(
{
success: true,
success: syncReport.success,
data: {
sync_id: syncId,
...placeholderReport
...syncReport
}
},
{ status: 200 }
{ status: HTTP_STATUS.OK }
);
} catch (error) {
console.error('[Sync] Unexpected error', { error });
logger.error('[Sync] Unexpected error', { error });
const completedAt = new Date().toISOString();
const totalDuration = Date.now() - startTime;
@@ -222,7 +129,7 @@ export async function handleSync(
}
}
},
{ status: 500 }
{ status: HTTP_STATUS.INTERNAL_ERROR }
);
}
}

0
src/services/cache.test.ts → src/services/cache.manual-test.md
View File

39
src/services/cache.ts
View File

@@ -9,14 +9,17 @@
* - Graceful degradation on cache failures
*
* @example
* const cache = new CacheService(300); // 5 minutes default TTL
* await cache.set('key', data, 3600); // 1 hour TTL
* const cache = new CacheService(CACHE_TTL.INSTANCES);
* await cache.set('key', data, CACHE_TTL.PRICING);
* const result = await cache.get<MyType>('key');
* if (result) {
* console.log(result.cache_age_seconds);
* }
*/
import { logger } from '../utils/logger';
import { CACHE_TTL } from '../constants';
/**
* Cache result structure with metadata
*/
@@ -41,13 +44,13 @@ export class CacheService {
/**
* Initialize cache service
*
* @param ttlSeconds - Default TTL in seconds (default: 300 = 5 minutes)
* @param ttlSeconds - Default TTL in seconds (default: CACHE_TTL.DEFAULT)
*/
constructor(ttlSeconds = 300) {
constructor(ttlSeconds = CACHE_TTL.DEFAULT) {
// Use Cloudflare Workers global caches.default
this.cache = caches.default;
this.defaultTTL = ttlSeconds;
console.log(`[CacheService] Initialized with default TTL: ${ttlSeconds}s`);
logger.debug(`[CacheService] Initialized with default TTL: ${ttlSeconds}s`);
}
/**
@@ -61,7 +64,7 @@ export class CacheService {
const response = await this.cache.match(key);
if (!response) {
console.log(`[CacheService] Cache miss: ${key}`);
logger.debug(`[CacheService] Cache miss: ${key}`);
return null;
}
@@ -75,7 +78,7 @@ export class CacheService {
const cachedAt = new Date(body.cached_at);
const ageSeconds = Math.floor((Date.now() - cachedAt.getTime()) / 1000);
console.log(`[CacheService] Cache hit: ${key} (age: ${ageSeconds}s)`);
logger.debug(`[CacheService] Cache hit: ${key} (age: ${ageSeconds}s)`);
return {
data: body.data,
@@ -85,7 +88,9 @@ export class CacheService {
};
} catch (error) {
console.error('[CacheService] Cache read error:', error);
logger.error('[CacheService] Cache read error:', {
error: error instanceof Error ? error.message : String(error)
});
// Graceful degradation: return null on cache errors
return null;
}
@@ -118,10 +123,12 @@ export class CacheService {
// Store in cache
await this.cache.put(key, response);
console.log(`[CacheService] Cached: ${key} (TTL: ${ttl}s)`);
logger.debug(`[CacheService] Cached: ${key} (TTL: ${ttl}s)`);
} catch (error) {
console.error('[CacheService] Cache write error:', error);
logger.error('[CacheService] Cache write error:', {
error: error instanceof Error ? error.message : String(error)
});
// Graceful degradation: continue without caching
}
}
@@ -137,15 +144,17 @@ export class CacheService {
const deleted = await this.cache.delete(key);
if (deleted) {
console.log(`[CacheService] Deleted: ${key}`);
logger.debug(`[CacheService] Deleted: ${key}`);
} else {
console.log(`[CacheService] Delete failed (not found): ${key}`);
logger.debug(`[CacheService] Delete failed (not found): ${key}`);
}
return deleted;
} catch (error) {
console.error('[CacheService] Cache delete error:', error);
logger.error('[CacheService] Cache delete error:', {
error: error instanceof Error ? error.message : String(error)
});
return false;
}
}
@@ -179,7 +188,7 @@ export class CacheService {
* @param pattern - Pattern to match (e.g., 'instances:*')
*/
async invalidatePattern(pattern: string): Promise<void> {
console.warn(`[CacheService] Pattern invalidation not supported: ${pattern}`);
logger.warn(`[CacheService] Pattern invalidation not supported: ${pattern}`);
// TODO: Implement with KV-based cache index if needed
}
@@ -191,7 +200,7 @@ export class CacheService {
* @returns Cache statistics (not available in Cloudflare Workers)
*/
async getStats(): Promise<{ supported: boolean }> {
console.warn('[CacheService] Cache statistics not available in Cloudflare Workers');
logger.warn('[CacheService] Cache statistics not available in Cloudflare Workers');
return { supported: false };
}
}

186
src/services/query.ts
View File

@@ -3,7 +3,9 @@
* Handles complex instance queries with JOIN operations, filtering, sorting, and pagination
*/
import {
import { createLogger } from '../utils/logger';
import type {
Env,
InstanceQueryParams,
InstanceResponse,
InstanceData,
@@ -44,32 +46,36 @@ interface RawQueryResult {
provider_created_at: string;
provider_updated_at: string;
// region fields (aliased)
region_id: number;
region_provider_id: number;
region_code: string;
region_name: string;
// region fields (aliased) - nullable from LEFT JOIN
region_id: number | null;
region_provider_id: number | null;
region_code: string | null;
region_name: string | null;
country_code: string | null;
latitude: number | null;
longitude: number | null;
region_available: number;
region_created_at: string;
region_updated_at: string;
region_available: number | null;
region_created_at: string | null;
region_updated_at: string | null;
// pricing fields (aliased)
pricing_id: number;
pricing_instance_type_id: number;
pricing_region_id: number;
hourly_price: number;
monthly_price: number;
currency: string;
pricing_available: number;
pricing_created_at: string;
pricing_updated_at: string;
// pricing fields (aliased) - nullable from LEFT JOIN
pricing_id: number | null;
pricing_instance_type_id: number | null;
pricing_region_id: number | null;
hourly_price: number | null;
monthly_price: number | null;
currency: string | null;
pricing_available: number | null;
pricing_created_at: string | null;
pricing_updated_at: string | null;
}
export class QueryService {
constructor(private db: D1Database) {}
private logger: ReturnType<typeof createLogger>;
constructor(private db: D1Database, env?: Env) {
this.logger = createLogger('[QueryService]', env);
}
/**
* Query instances with filtering, sorting, and pagination
@@ -79,27 +85,35 @@ export class QueryService {
try {
// Build SQL query and count query
const { sql, countSql, bindings } = this.buildQuery(params);
const { sql, countSql, bindings, countBindings } = this.buildQuery(params);
console.log('[QueryService] Executing query:', sql);
console.log('[QueryService] Bindings:', bindings);
this.logger.debug('Executing query', { sql });
this.logger.debug('Main query bindings', { bindings });
this.logger.debug('Count query bindings', { countBindings });
// Execute count query for total results
const countResult = await this.db
.prepare(countSql)
.bind(...bindings)
.first<{ total: number }>();
// Execute count and main queries in a single batch for performance
const [countResult, queryResult] = await this.db.batch([
this.db.prepare(countSql).bind(...countBindings),
this.db.prepare(sql).bind(...bindings),
]);
const totalResults = countResult?.total ?? 0;
// Validate batch results and extract data with type safety
if (!countResult.success || !queryResult.success) {
const errors = [
!countResult.success ? `Count query failed: ${countResult.error}` : null,
!queryResult.success ? `Main query failed: ${queryResult.error}` : null,
].filter(Boolean);
throw new Error(`Batch query execution failed: ${errors.join(', ')}`);
}
// Execute main query
const result = await this.db
.prepare(sql)
.bind(...bindings)
.all<RawQueryResult>();
// Extract total count with type casting and fallback
const totalResults = (countResult.results?.[0] as { total: number } | undefined)?.total ?? 0;
// Extract main query results with type casting
const results = (queryResult.results ?? []) as RawQueryResult[];
// Transform flat results into structured InstanceData
const instances = this.transformResults(result.results);
const instances = this.transformResults(results);
// Calculate pagination metadata
const page = params.page ?? 1;
@@ -126,7 +140,7 @@ export class QueryService {
},
};
} catch (error) {
console.error('[QueryService] Query failed:', error);
this.logger.error('Query failed', { error: error instanceof Error ? error.message : String(error) });
throw new Error(`Failed to query instances: ${error instanceof Error ? error.message : 'Unknown error'}`);
}
}
@@ -138,11 +152,12 @@ export class QueryService {
sql: string;
countSql: string;
bindings: unknown[];
countBindings: unknown[];
} {
const conditions: string[] = [];
const bindings: unknown[] = [];
// Base SELECT with JOIN
// Base SELECT with LEFT JOIN to include instances without pricing
const selectClause = `
SELECT
it.id, it.provider_id, it.instance_id, it.instance_name,
@@ -181,8 +196,8 @@ export class QueryService {
pr.updated_at as pricing_updated_at
FROM instance_types it
JOIN providers p ON it.provider_id = p.id
JOIN pricing pr ON pr.instance_type_id = it.id
JOIN regions r ON pr.region_id = r.id
LEFT JOIN pricing pr ON pr.instance_type_id = it.id
LEFT JOIN regions r ON pr.region_id = r.id
`;
// Provider filter (name or ID)
@@ -225,14 +240,14 @@ export class QueryService {
bindings.push(params.max_memory);
}
// Price range filter (hourly price)
// Price range filter (hourly price) - only filter where pricing exists
if (params.min_price !== undefined) {
conditions.push('pr.hourly_price >= ?');
conditions.push('pr.hourly_price IS NOT NULL AND pr.hourly_price >= ?');
bindings.push(params.min_price);
}
if (params.max_price !== undefined) {
conditions.push('pr.hourly_price <= ?');
conditions.push('pr.hourly_price IS NOT NULL AND pr.hourly_price <= ?');
bindings.push(params.max_price);
}
@@ -248,7 +263,7 @@ export class QueryService {
// Build WHERE clause
const whereClause = conditions.length > 0 ? ' WHERE ' + conditions.join(' AND ') : '';
// Build ORDER BY clause
// Build ORDER BY clause with NULL handling
let orderByClause = '';
const sortBy = params.sort_by ?? 'hourly_price';
const sortOrder = params.sort_order ?? 'asc';
@@ -266,7 +281,14 @@ export class QueryService {
};
const sortColumn = sortFieldMap[sortBy] ?? 'pr.hourly_price';
orderByClause = ` ORDER BY ${sortColumn} ${sortOrder.toUpperCase()}`;
// Handle NULL values in pricing columns (NULL values go last)
if (sortColumn.startsWith('pr.')) {
// Use CASE to put NULL values last regardless of sort order
orderByClause = ` ORDER BY CASE WHEN ${sortColumn} IS NULL THEN 1 ELSE 0 END, ${sortColumn} ${sortOrder.toUpperCase()}`;
} else {
orderByClause = ` ORDER BY ${sortColumn} ${sortOrder.toUpperCase()}`;
}
// Build LIMIT and OFFSET
const page = params.page ?? 1;
@@ -286,15 +308,15 @@ export class QueryService {
SELECT COUNT(*) as total
FROM instance_types it
JOIN providers p ON it.provider_id = p.id
JOIN pricing pr ON pr.instance_type_id = it.id
JOIN regions r ON pr.region_id = r.id
LEFT JOIN pricing pr ON pr.instance_type_id = it.id
LEFT JOIN regions r ON pr.region_id = r.id
${whereClause}
`;
// Bindings for count query (same filters, no limit/offset)
const countBindings = bindings.slice(0, -2);
return { sql, countSql, bindings: countBindings };
return { sql, countSql, bindings, countBindings };
}
/**
@@ -314,30 +336,52 @@ export class QueryService {
updated_at: row.provider_updated_at,
};
const region: Region = {
id: row.region_id,
provider_id: row.region_provider_id,
region_code: row.region_code,
region_name: row.region_name,
country_code: row.country_code,
latitude: row.latitude,
longitude: row.longitude,
available: row.region_available,
created_at: row.region_created_at,
updated_at: row.region_updated_at,
};
// Region is nullable (LEFT JOIN may not have matched)
const region: Region | null =
row.region_id !== null &&
row.region_provider_id !== null &&
row.region_code !== null &&
row.region_name !== null &&
row.region_available !== null &&
row.region_created_at !== null &&
row.region_updated_at !== null
? {
id: row.region_id,
provider_id: row.region_provider_id,
region_code: row.region_code,
region_name: row.region_name,
country_code: row.country_code,
latitude: row.latitude,
longitude: row.longitude,
available: row.region_available,
created_at: row.region_created_at,
updated_at: row.region_updated_at,
}
: null;
const pricing: Pricing = {
id: row.pricing_id,
instance_type_id: row.pricing_instance_type_id,
region_id: row.pricing_region_id,
hourly_price: row.hourly_price,
monthly_price: row.monthly_price,
currency: row.currency,
available: row.pricing_available,
created_at: row.pricing_created_at,
updated_at: row.pricing_updated_at,
};
// Pricing is nullable (LEFT JOIN may not have matched)
const pricing: Pricing | null =
row.pricing_id !== null &&
row.pricing_instance_type_id !== null &&
row.pricing_region_id !== null &&
row.hourly_price !== null &&
row.monthly_price !== null &&
row.currency !== null &&
row.pricing_available !== null &&
row.pricing_created_at !== null &&
row.pricing_updated_at !== null
? {
id: row.pricing_id,
instance_type_id: row.pricing_instance_type_id,
region_id: row.pricing_region_id,
hourly_price: row.hourly_price,
monthly_price: row.monthly_price,
currency: row.currency,
available: row.pricing_available,
created_at: row.pricing_created_at,
updated_at: row.pricing_updated_at,
}
: null;
const instanceType: InstanceType = {
id: row.id,
@@ -351,7 +395,7 @@ export class QueryService {
network_speed_gbps: row.network_speed_gbps,
gpu_count: row.gpu_count,
gpu_type: row.gpu_type,
instance_family: row.instance_family as any,
instance_family: row.instance_family as 'general' | 'compute' | 'memory' | 'storage' | 'gpu' | null,
metadata: row.metadata,
created_at: row.created_at,
updated_at: row.updated_at,

388
src/services/recommendation.test.ts Normal file
View File

@@ -0,0 +1,388 @@
/**
* Recommendation Service Tests
*
* Tests the RecommendationService class for:
* - Score calculation algorithm
* - Stack validation and requirements calculation
* - Budget filtering
* - Asia-Pacific region filtering
*/
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { RecommendationService } from './recommendation';
import type { RecommendationRequest } from '../types';
/**
* Mock D1Database for testing
*/
const createMockD1Database = () => {
const mockPrepare = vi.fn().mockReturnValue({
bind: vi.fn().mockReturnThis(),
all: vi.fn().mockResolvedValue({
results: [],
}),
});
return {
prepare: mockPrepare,
dump: vi.fn(),
batch: vi.fn(),
exec: vi.fn(),
};
};
/**
* Mock instance data for testing
*/
const createMockInstanceRow = (overrides = {}) => ({
id: 1,
instance_id: 'test-instance',
instance_name: 'Standard-2GB',
vcpu: 2,
memory_mb: 2048,
storage_gb: 50,
metadata: null,
provider_name: 'linode',
region_code: 'ap-south-1',
region_name: 'Mumbai',
hourly_price: 0.015,
monthly_price: 10,
...overrides,
});
describe('RecommendationService', () => {
let service: RecommendationService;
let mockDb: ReturnType<typeof createMockD1Database>;
beforeEach(() => {
mockDb = createMockD1Database();
service = new RecommendationService(mockDb as any);
});
describe('recommend', () => {
it('should validate stack components and throw error for invalid stacks', async () => {
const request: RecommendationRequest = {
stack: ['nginx', 'invalid-stack', 'unknown-tech'],
scale: 'small',
};
await expect(service.recommend(request)).rejects.toThrow(
'Invalid stacks: invalid-stack, unknown-tech'
);
});
it('should calculate resource requirements for valid stack', async () => {
const request: RecommendationRequest = {
stack: ['nginx', 'mysql'],
scale: 'medium',
};
// Mock database response with empty results
mockDb.prepare.mockReturnValue({
bind: vi.fn().mockReturnThis(),
all: vi.fn().mockResolvedValue({ results: [] }),
});
const result = await service.recommend(request);
// nginx (256MB) + mysql (2048MB) + OS overhead (768MB) = 3072MB
expect(result.requirements.min_memory_mb).toBe(3072);
// 3072MB / 2048 = 1.5, rounded up = 2 vCPU
expect(result.requirements.min_vcpu).toBe(2);
expect(result.requirements.breakdown).toHaveProperty('nginx');
expect(result.requirements.breakdown).toHaveProperty('mysql');
expect(result.requirements.breakdown).toHaveProperty('os_overhead');
});
it('should return top 5 recommendations sorted by match score', async () => {
const request: RecommendationRequest = {
stack: ['nginx'],
scale: 'small',
};
// Mock database with 10 instances
const mockInstances = Array.from({ length: 10 }, (_, i) =>
createMockInstanceRow({
id: i + 1,
instance_name: `Instance-${i + 1}`,
vcpu: i % 4 + 1,
memory_mb: (i % 4 + 1) * 1024,
monthly_price: 10 + i * 5,
})
);
mockDb.prepare.mockReturnValue({
bind: vi.fn().mockReturnThis(),
all: vi.fn().mockResolvedValue({ results: mockInstances }),
});
const result = await service.recommend(request);
// Should return max 5 recommendations
expect(result.recommendations).toHaveLength(5);
// Should be sorted by match_score descending
for (let i = 0; i < result.recommendations.length - 1; i++) {
expect(result.recommendations[i].match_score).toBeGreaterThanOrEqual(
result.recommendations[i + 1].match_score
);
}
// Should have rank assigned (1-5)
expect(result.recommendations[0].rank).toBe(1);
expect(result.recommendations[4].rank).toBe(5);
});
it('should filter instances by budget when budget_max is specified', async () => {
const request: RecommendationRequest = {
stack: ['nginx'],
scale: 'small',
budget_max: 20,
};
mockDb.prepare.mockReturnValue({
bind: vi.fn().mockReturnThis(),
all: vi.fn().mockResolvedValue({ results: [] }),
});
await service.recommend(request);
// Verify SQL includes budget filter
const prepareCall = mockDb.prepare.mock.calls[0][0];
expect(prepareCall).toContain('pr.monthly_price <= ?');
});
});
describe('scoreInstance (via recommend)', () => {
it('should score optimal memory fit with high score', async () => {
const request: RecommendationRequest = {
stack: ['nginx'], // min 128MB
scale: 'small',
};
// Memory ratio 1.4x (optimal range 1-1.5x): should get 40 points
const mockInstance = createMockInstanceRow({
memory_mb: 1024, // nginx min is 128MB + 768MB OS = 896MB total, ratio = 1.14x
vcpu: 1,
monthly_price: 10,
});
mockDb.prepare.mockReturnValue({
bind: vi.fn().mockReturnThis(),
all: vi.fn().mockResolvedValue({ results: [mockInstance] }),
});
const result = await service.recommend(request);
// Should have high score for optimal fit
expect(result.recommendations[0].match_score).toBeGreaterThan(70);
expect(result.recommendations[0].pros).toContain('메모리 최적 적합');
});
it('should penalize oversized instances', async () => {
const request: RecommendationRequest = {
stack: ['nginx'], // min 896MB total
scale: 'small',
};
// Memory ratio >2x: should get only 20 points for memory
const mockInstance = createMockInstanceRow({
memory_mb: 4096, // Ratio = 4096/896 = 4.57x (oversized)
vcpu: 2,
monthly_price: 30,
});
mockDb.prepare.mockReturnValue({
bind: vi.fn().mockReturnThis(),
all: vi.fn().mockResolvedValue({ results: [mockInstance] }),
});
const result = await service.recommend(request);
// Should have cons about over-provisioning
expect(result.recommendations[0].cons).toContain('메모리 과다 프로비저닝');
});
it('should give price efficiency bonus for budget-conscious instances', async () => {
const request: RecommendationRequest = {
stack: ['nginx'],
scale: 'small',
budget_max: 100,
};
// Price ratio 0.3 (30% of budget): should get 20 points
const mockInstance = createMockInstanceRow({
memory_mb: 2048,
vcpu: 2,
monthly_price: 30,
});
mockDb.prepare.mockReturnValue({
bind: vi.fn().mockReturnThis(),
all: vi.fn().mockResolvedValue({ results: [mockInstance] }),
});
const result = await service.recommend(request);
// Should have pros about price efficiency
expect(result.recommendations[0].pros).toContain('예산 대비 저렴');
});
it('should give storage bonus for instances with good storage', async () => {
const request: RecommendationRequest = {
stack: ['nginx'],
scale: 'small',
};
// Storage >= 80GB: should get 10 points
const mockInstanceWithStorage = createMockInstanceRow({
memory_mb: 2048,
vcpu: 2,
storage_gb: 100,
monthly_price: 20,
});
mockDb.prepare.mockReturnValue({
bind: vi.fn().mockReturnThis(),
all: vi.fn().mockResolvedValue({ results: [mockInstanceWithStorage] }),
});
const result = await service.recommend(request);
// Should have pros about storage
expect(result.recommendations[0].pros.some((p) => p.includes('스토리지'))).toBe(true);
});
it('should note EBS storage separately for instances without storage', async () => {
const request: RecommendationRequest = {
stack: ['nginx'],
scale: 'small',
};
// Storage = 0: should have cons
const mockInstanceNoStorage = createMockInstanceRow({
memory_mb: 2048,
vcpu: 2,
storage_gb: 0,
monthly_price: 20,
});
mockDb.prepare.mockReturnValue({
bind: vi.fn().mockReturnThis(),
all: vi.fn().mockResolvedValue({ results: [mockInstanceNoStorage] }),
});
const result = await service.recommend(request);
// Should have cons about separate storage
expect(result.recommendations[0].cons).toContain('EBS 스토리지 별도');
});
});
describe('getMonthlyPrice (via scoring)', () => {
it('should extract monthly price from monthly_price column', async () => {
const request: RecommendationRequest = {
stack: ['nginx'],
scale: 'small',
};
const mockInstance = createMockInstanceRow({
monthly_price: 15,
hourly_price: null,
metadata: null,
});
mockDb.prepare.mockReturnValue({
bind: vi.fn().mockReturnThis(),
all: vi.fn().mockResolvedValue({ results: [mockInstance] }),
});
const result = await service.recommend(request);
expect(result.recommendations[0].price.monthly).toBe(15);
});
it('should extract monthly price from metadata JSON', async () => {
const request: RecommendationRequest = {
stack: ['nginx'],
scale: 'small',
};
const mockInstance = createMockInstanceRow({
monthly_price: null,
hourly_price: null,
metadata: JSON.stringify({ monthly_price: 25 }),
});
mockDb.prepare.mockReturnValue({
bind: vi.fn().mockReturnThis(),
all: vi.fn().mockResolvedValue({ results: [mockInstance] }),
});
const result = await service.recommend(request);
expect(result.recommendations[0].price.monthly).toBe(25);
});
it('should calculate monthly price from hourly price', async () => {
const request: RecommendationRequest = {
stack: ['nginx'],
scale: 'small',
};
const mockInstance = createMockInstanceRow({
monthly_price: null,
hourly_price: 0.02, // 0.02 * 730 = 14.6
metadata: null,
});
mockDb.prepare.mockReturnValue({
bind: vi.fn().mockReturnThis(),
all: vi.fn().mockResolvedValue({ results: [mockInstance] }),
});
const result = await service.recommend(request);
expect(result.recommendations[0].price.monthly).toBe(14.6);
});
});
describe('queryInstances', () => {
it('should query instances from Asia-Pacific regions', async () => {
const request: RecommendationRequest = {
stack: ['nginx'],
scale: 'small',
};
mockDb.prepare.mockReturnValue({
bind: vi.fn().mockReturnThis(),
all: vi.fn().mockResolvedValue({ results: [] }),
});
await service.recommend(request);
// Verify SQL query structure
const prepareCall = mockDb.prepare.mock.calls[0][0];
expect(prepareCall).toContain('WHERE p.name IN');
expect(prepareCall).toContain('AND r.region_code IN');
expect(prepareCall).toContain('AND it.memory_mb >= ?');
expect(prepareCall).toContain('AND it.vcpu >= ?');
});
it('should handle database query errors gracefully', async () => {
const request: RecommendationRequest = {
stack: ['nginx'],
scale: 'small',
};
mockDb.prepare.mockReturnValue({
bind: vi.fn().mockReturnThis(),
all: vi.fn().mockRejectedValue(new Error('Database connection failed')),
});
await expect(service.recommend(request)).rejects.toThrow(
'Failed to query instances from database'
);
});
});
});

363
src/services/recommendation.ts Normal file
View File

@@ -0,0 +1,363 @@
/**
* Recommendation Service
*
* Provides intelligent instance recommendations based on:
* - Technology stack requirements
* - Deployment scale
* - Budget constraints
* - Asia-Pacific region filtering
*/
import type { D1Database } from '@cloudflare/workers-types';
import type {
RecommendationRequest,
RecommendationResponse,
InstanceRecommendation,
ResourceRequirements,
} from '../types';
import { validateStack, calculateRequirements } from './stackConfig';
import { getAsiaRegionCodes, getRegionDisplayName } from './regionFilter';
import { logger } from '../utils/logger';
/**
* Database row interface for instance query results
*/
interface InstanceQueryRow {
id: number;
instance_id: string;
instance_name: string;
vcpu: number;
memory_mb: number;
storage_gb: number;
metadata: string | null;
provider_name: string;
region_code: string;
region_name: string;
hourly_price: number | null;
monthly_price: number | null;
}
/**
* Recommendation Service
* Calculates and ranks cloud instances based on stack requirements
*/
export class RecommendationService {
// Cache parsed metadata to avoid repeated JSON.parse calls
private metadataCache = new Map<number, { monthly_price?: number }>();
constructor(private db: D1Database) {}
/**
* Generate instance recommendations based on stack and scale
*
* Process:
* 1. Validate stack components
* 2. Calculate resource requirements
* 3. Query Asia-Pacific instances matching requirements
* 4. Score and rank instances
* 5. Return top 5 recommendations
*
* @param request - Recommendation request with stack, scale, and budget
* @returns Recommendation response with requirements and ranked instances
* @throws Error if stack validation fails or database query fails
*/
async recommend(request: RecommendationRequest): Promise<RecommendationResponse> {
// Clear metadata cache for new recommendation request
this.metadataCache.clear();
logger.info('[Recommendation] Processing request', {
stack: request.stack,
scale: request.scale,
budget_max: request.budget_max,
});
// 1. Validate stack components
const validation = validateStack(request.stack);
if (!validation.valid) {
const errorMsg = `Invalid stacks: ${validation.invalidStacks.join(', ')}`;
logger.error('[Recommendation] Stack validation failed', {
invalidStacks: validation.invalidStacks,
});
throw new Error(errorMsg);
}
// 2. Calculate resource requirements based on stack and scale
const requirements = calculateRequirements(request.stack, request.scale);
logger.info('[Recommendation] Resource requirements calculated', {
min_memory_mb: requirements.min_memory_mb,
min_vcpu: requirements.min_vcpu,
});
// 3. Query instances from Asia-Pacific regions
const instances = await this.queryInstances(requirements, request.budget_max);
logger.info('[Recommendation] Found instances', { count: instances.length });
// 4. Calculate match scores and sort by score (highest first)
const scored = instances.map(inst =>
this.scoreInstance(inst, requirements, request.budget_max)
);
scored.sort((a, b) => b.match_score - a.match_score);
// 5. Return top 5 recommendations with rank
const recommendations = scored.slice(0, 5).map((inst, idx) => ({
...inst,
rank: idx + 1,
}));
logger.info('[Recommendation] Generated recommendations', {
count: recommendations.length,
top_score: recommendations[0]?.match_score,
});
return { requirements, recommendations };
}
/**
* Query instances from Asia-Pacific regions matching requirements
*
* Single query optimization: queries all providers (Linode, Vultr, AWS) in one database call
* - Uses IN clause for provider names and region codes
* - Filters by minimum memory and vCPU requirements
* - Optionally filters by maximum budget
* - Returns up to 50 instances across all providers
*
* @param requirements - Minimum resource requirements
* @param budgetMax - Optional maximum monthly budget in USD
* @returns Array of instance query results
*/
private async queryInstances(
requirements: ResourceRequirements,
budgetMax?: number
): Promise<InstanceQueryRow[]> {
// Collect all providers and their Asia-Pacific region codes
const providers = ['linode', 'vultr', 'aws'];
const allRegionCodes: string[] = [];
for (const provider of providers) {
const regionCodes = getAsiaRegionCodes(provider);
if (regionCodes.length === 0) {
logger.warn('[Recommendation] No Asia regions found for provider', {
provider,
});
}
allRegionCodes.push(...regionCodes);
}
// If no regions found across all providers, return empty
if (allRegionCodes.length === 0) {
logger.error('[Recommendation] No Asia regions found for any provider');
return [];
}
// Build single query with IN clauses for providers and regions
const providerPlaceholders = providers.map(() => '?').join(',');
const regionPlaceholders = allRegionCodes.map(() => '?').join(',');
let sql = `
SELECT
it.id,
it.instance_id,
it.instance_name,
it.vcpu,
it.memory_mb,
it.storage_gb,
it.metadata,
p.name as provider_name,
r.region_code,
r.region_name,
pr.hourly_price,
pr.monthly_price
FROM instance_types it
JOIN providers p ON it.provider_id = p.id
JOIN regions r ON r.provider_id = p.id
LEFT JOIN pricing pr ON pr.instance_type_id = it.id AND pr.region_id = r.id
WHERE p.name IN (${providerPlaceholders})
AND r.region_code IN (${regionPlaceholders})
AND it.memory_mb >= ?
AND it.vcpu >= ?
`;
const params: (string | number)[] = [
...providers,
...allRegionCodes,
requirements.min_memory_mb,
requirements.min_vcpu,
];
// Add budget filter if specified
if (budgetMax) {
sql += ` AND (pr.monthly_price <= ? OR pr.monthly_price IS NULL)`;
params.push(budgetMax);
}
// Sort by price (cheapest first) and limit results
sql += ` ORDER BY COALESCE(pr.monthly_price, 9999) ASC LIMIT 50`;
try {
const result = await this.db.prepare(sql).bind(...params).all();
logger.info('[Recommendation] Single query executed for all providers', {
providers,
region_count: allRegionCodes.length,
found: result.results?.length || 0,
});
return (result.results as unknown as InstanceQueryRow[]) || [];
} catch (error) {
logger.error('[Recommendation] Query failed', { error });
throw new Error('Failed to query instances from database');
}
}
/**
* Calculate match score for an instance
*
* Scoring algorithm (0-100 points):
* - Memory fit (40 points): How well memory matches requirements
* - Perfect fit (1-1.5x): 40 points
* - Comfortable (1.5-2x): 30 points
* - Oversized (>2x): 20 points
* - vCPU fit (30 points): How well vCPU matches requirements
* - Good fit (1-2x): 30 points
* - Oversized (>2x): 20 points
* - Price efficiency (20 points): Budget utilization
* - Under 50% budget: 20 points
* - Under 80% budget: 15 points
* - Over 80% budget: 10 points
* - Storage bonus (10 points): Included storage
* - ≥80GB: 10 points
* - >0GB: 5 points
* - No storage: 0 points
*
* @param instance - Instance query result
* @param requirements - Resource requirements
* @param budgetMax - Optional maximum budget
* @returns Instance recommendation with score, pros, and cons
*/
private scoreInstance(
instance: InstanceQueryRow,
requirements: ResourceRequirements,
budgetMax?: number
): InstanceRecommendation {
let score = 0;
const pros: string[] = [];
const cons: string[] = [];
// Memory score (40 points) - measure fit against requirements
const memoryRatio = instance.memory_mb / requirements.min_memory_mb;
if (memoryRatio >= 1 && memoryRatio <= 1.5) {
score += 40;
pros.push('메모리 최적 적합');
} else if (memoryRatio > 1.5 && memoryRatio <= 2) {
score += 30;
pros.push('메모리 여유 있음');
} else if (memoryRatio > 2) {
score += 20;
cons.push('메모리 과다 프로비저닝');
}
// vCPU score (30 points) - measure fit against requirements
const vcpuRatio = instance.vcpu / requirements.min_vcpu;
if (vcpuRatio >= 1 && vcpuRatio <= 2) {
score += 30;
pros.push('vCPU 적합');
} else if (vcpuRatio > 2) {
score += 20;
}
// Price score (20 points) - budget efficiency
const monthlyPrice = this.getMonthlyPrice(instance);
if (budgetMax && monthlyPrice > 0) {
const priceRatio = monthlyPrice / budgetMax;
if (priceRatio <= 0.5) {
score += 20;
pros.push('예산 대비 저렴');
} else if (priceRatio <= 0.8) {
score += 15;
pros.push('합리적 가격');
} else {
score += 10;
}
} else if (monthlyPrice > 0) {
score += 15; // Default score when no budget specified
}
// Storage score (10 points) - included storage bonus
if (instance.storage_gb >= 80) {
score += 10;
pros.push(`스토리지 ${instance.storage_gb}GB 포함`);
} else if (instance.storage_gb > 0) {
score += 5;
} else {
cons.push('EBS 스토리지 별도');
}
// Build recommendation object
return {
rank: 0, // Will be set by caller after sorting
provider: instance.provider_name,
instance: instance.instance_name,
region: `${getRegionDisplayName(instance.region_code)} (${instance.region_code})`,
specs: {
vcpu: instance.vcpu,
memory_mb: instance.memory_mb,
storage_gb: instance.storage_gb || 0,
},
price: {
monthly: monthlyPrice,
hourly: instance.hourly_price || monthlyPrice / 730,
},
match_score: Math.min(100, score), // Cap at 100
pros,
cons,
};
}
/**
* Extract monthly price from instance data
*
* Pricing sources:
* 1. Direct monthly_price column (Linode)
* 2. metadata JSON field (Vultr, AWS) - cached to avoid repeated JSON.parse
* 3. Calculate from hourly_price if available
*
* @param instance - Instance query result
* @returns Monthly price in USD, or 0 if not available
*/
private getMonthlyPrice(instance: InstanceQueryRow): number {
// Direct monthly price (from pricing table)
if (instance.monthly_price) {
return instance.monthly_price;
}
// Extract from metadata (Vultr, AWS) with caching
if (instance.metadata) {
// Check cache first
if (!this.metadataCache.has(instance.id)) {
try {
const meta = JSON.parse(instance.metadata) as { monthly_price?: number };
this.metadataCache.set(instance.id, meta);
} catch (error) {
logger.warn('[Recommendation] Failed to parse metadata', {
instance: instance.instance_name,
error,
});
// Cache empty object to prevent repeated parse attempts
this.metadataCache.set(instance.id, {});
}
}
const cachedMeta = this.metadataCache.get(instance.id);
if (cachedMeta?.monthly_price) {
return cachedMeta.monthly_price;
}
}
// Calculate from hourly price (730 hours per month average)
if (instance.hourly_price) {
return instance.hourly_price * 730;
}
return 0;
}
}

67
src/services/regionFilter.ts Normal file
View File

@@ -0,0 +1,67 @@
/**
* Region Filter Service
* Manages Asia-Pacific region filtering (Seoul, Tokyo, Osaka, Singapore, Hong Kong)
*/
/**
* Asia-Pacific region codes by provider
* Limited to 5 major cities in East/Southeast Asia
*/
export const ASIA_REGIONS: Record<string, string[]> = {
linode: ['jp-tyo-3', 'jp-osa', 'sg-sin-2'],
vultr: ['icn', 'nrt', 'itm'],
aws: ['ap-northeast-1', 'ap-northeast-2', 'ap-northeast-3', 'ap-southeast-1', 'ap-east-1'],
};
/**
* Region code to display name mapping
*/
export const REGION_DISPLAY_NAMES: Record<string, string> = {
// Linode
'jp-tyo-3': 'Tokyo',
'jp-osa': 'Osaka',
'sg-sin-2': 'Singapore',
// Vultr
'icn': 'Seoul',
'nrt': 'Tokyo',
'itm': 'Osaka',
// AWS
'ap-northeast-1': 'Tokyo',
'ap-northeast-2': 'Seoul',
'ap-northeast-3': 'Osaka',
'ap-southeast-1': 'Singapore',
'ap-east-1': 'Hong Kong',
};
/**
* Check if a region code is in the Asia-Pacific filter list
*
* @param provider - Cloud provider name (case-insensitive)
* @param regionCode - Region code to check (case-insensitive)
* @returns true if region is in Asia-Pacific filter list
*/
export function isAsiaRegion(provider: string, regionCode: string): boolean {
const regions = ASIA_REGIONS[provider.toLowerCase()];
if (!regions) return false;
return regions.includes(regionCode.toLowerCase());
}
/**
* Get all Asia-Pacific region codes for a provider
*
* @param provider - Cloud provider name (case-insensitive)
* @returns Array of region codes, empty if provider not found
*/
export function getAsiaRegionCodes(provider: string): string[] {
return ASIA_REGIONS[provider.toLowerCase()] || [];
}
/**
* Get display name for a region code
*
* @param regionCode - Region code to look up
* @returns Display name (e.g., "Tokyo"), or original code if not found
*/
export function getRegionDisplayName(regionCode: string): string {
return REGION_DISPLAY_NAMES[regionCode] || regionCode;
}

93
src/services/stackConfig.ts Normal file
View File

@@ -0,0 +1,93 @@
/**
* Stack Configuration Service
* Manages technology stack requirements and resource calculations
*/
import type { ScaleType, ResourceRequirements } from '../types';
/**
* Memory requirements for each stack component (in MB)
*/
export const STACK_REQUIREMENTS: Record<string, { min: number; recommended: number }> = {
nginx: { min: 128, recommended: 256 },
'php-fpm': { min: 512, recommended: 1024 },
mysql: { min: 1024, recommended: 2048 },
mariadb: { min: 1024, recommended: 2048 },
postgresql: { min: 1024, recommended: 2048 },
redis: { min: 256, recommended: 512 },
elasticsearch: { min: 2048, recommended: 4096 },
nodejs: { min: 512, recommended: 1024 },
docker: { min: 1024, recommended: 2048 },
mongodb: { min: 1024, recommended: 2048 },
};
/**
* Base OS overhead (in MB)
*/
export const OS_OVERHEAD_MB = 768;
/**
* Validate stack components against supported technologies
*
* @param stack - Array of technology stack components
* @returns Validation result with list of invalid stacks
*/
export function validateStack(stack: string[]): { valid: boolean; invalidStacks: string[] } {
const invalidStacks = stack.filter(s => !STACK_REQUIREMENTS[s.toLowerCase()]);
return {
valid: invalidStacks.length === 0,
invalidStacks,
};
}
/**
* Calculate resource requirements based on stack and scale
*
* Memory calculation:
* - small: minimum requirements
* - medium: recommended requirements
* - large: 1.5x recommended requirements
*
* vCPU calculation:
* - 1 vCPU per 2GB memory (rounded up)
* - Minimum 1 vCPU
*
* @param stack - Array of technology stack components
* @param scale - Deployment scale (small/medium/large)
* @returns Calculated resource requirements with breakdown
*/
export function calculateRequirements(stack: string[], scale: ScaleType): ResourceRequirements {
const breakdown: Record<string, string> = {};
let totalMemory = 0;
// Calculate memory for each stack component
for (const s of stack) {
const req = STACK_REQUIREMENTS[s.toLowerCase()];
if (req) {
let memoryMb: number;
if (scale === 'small') {
memoryMb = req.min;
} else if (scale === 'large') {
memoryMb = Math.ceil(req.recommended * 1.5);
} else {
// medium
memoryMb = req.recommended;
}
breakdown[s] = memoryMb >= 1024 ? `${memoryMb / 1024}GB` : `${memoryMb}MB`;
totalMemory += memoryMb;
}
}
// Add OS overhead
breakdown['os_overhead'] = `${OS_OVERHEAD_MB}MB`;
totalMemory += OS_OVERHEAD_MB;
// Calculate vCPU: 1 vCPU per 2GB memory, minimum 1
const minVcpu = Math.max(1, Math.ceil(totalMemory / 2048));
return {
min_memory_mb: totalMemory,
min_vcpu: minVcpu,
breakdown,
};
}

526
src/services/sync.ts
View File

@@ -17,44 +17,47 @@ import { LinodeConnector } from '../connectors/linode';
import { VultrConnector } from '../connectors/vultr';
import { AWSConnector } from '../connectors/aws';
import { RepositoryFactory } from '../repositories';
import { createLogger } from '../utils/logger';
import type {
Env,
ProviderSyncResult,
SyncReport,
RegionInput,
InstanceTypeInput,
PricingInput,
} from '../types';
import { SyncStage } from '../types';
/**
* Synchronization stages
* Cloud provider connector interface for SyncOrchestrator
*
* This is an adapter interface used by SyncOrchestrator to abstract
* provider-specific implementations. Actual provider connectors (LinodeConnector,
* VultrConnector, etc.) extend CloudConnector from base.ts and are wrapped
* by this interface in createConnector().
*/
export enum SyncStage {
INIT = 'init',
FETCH_CREDENTIALS = 'fetch_credentials',
FETCH_REGIONS = 'fetch_regions',
FETCH_INSTANCES = 'fetch_instances',
NORMALIZE = 'normalize',
PERSIST = 'persist',
VALIDATE = 'validate',
COMPLETE = 'complete',
}
/**
* Cloud provider connector interface
* All provider connectors must implement this interface
*/
export interface CloudConnector {
export interface SyncConnectorAdapter {
/** Authenticate and validate credentials */
authenticate(): Promise<void>;
/** Fetch all available regions */
/** Fetch all available regions (normalized) */
getRegions(): Promise<RegionInput[]>;
/** Fetch all instance types */
/** Fetch all instance types (normalized) */
getInstanceTypes(): Promise<InstanceTypeInput[]>;
/** Fetch pricing data for instances and regions */
getPricing(instanceTypeIds: number[], regionIds: number[]): Promise<PricingInput[]>;
/**
* Fetch pricing data for instances and regions
* @param instanceTypeIds - Array of database instance type IDs
* @param regionIds - Array of database region IDs
* @param dbInstanceMap - Map of DB instance type ID to instance_id (API ID) for avoiding redundant queries
* @returns Array of pricing records OR number of records if batched internally
*/
getPricing(
instanceTypeIds: number[],
regionIds: number[],
dbInstanceMap: Map<number, { instance_id: string }>
): Promise<PricingInput[] | number>;
}
/**
@@ -62,13 +65,18 @@ export interface CloudConnector {
*/
export class SyncOrchestrator {
private repos: RepositoryFactory;
private logger: ReturnType<typeof createLogger>;
private env?: Env;
constructor(
db: D1Database,
private vault: VaultClient
private vault: VaultClient,
env?: Env
) {
this.repos = new RepositoryFactory(db);
console.log('[SyncOrchestrator] Initialized');
this.env = env;
this.logger = createLogger('[SyncOrchestrator]', env);
this.logger.info('Initialized');
}
/**
@@ -81,35 +89,36 @@ export class SyncOrchestrator {
const startTime = Date.now();
let stage = SyncStage.INIT;
console.log(`[SyncOrchestrator] Starting sync for provider: ${provider}`);
this.logger.info('Starting sync for provider', { provider });
try {
// Stage 1: Initialize - Update provider status to syncing
// Stage 1: Initialize - Fetch provider record ONCE
stage = SyncStage.INIT;
await this.repos.providers.updateSyncStatus(provider, 'syncing');
console.log(`[SyncOrchestrator] ${provider} → ${stage}`);
// Stage 2: Fetch credentials from Vault
stage = SyncStage.FETCH_CREDENTIALS;
const connector = await this.createConnector(provider);
await connector.authenticate();
console.log(`[SyncOrchestrator] ${provider} → ${stage}`);
// Get provider record
const providerRecord = await this.repos.providers.findByName(provider);
if (!providerRecord) {
throw new Error(`Provider not found in database: ${provider}`);
}
// Update provider status to syncing
await this.repos.providers.updateSyncStatus(provider, 'syncing');
this.logger.info(`${provider} → ${stage}`);
// Stage 2: Fetch credentials from Vault
stage = SyncStage.FETCH_CREDENTIALS;
const connector = await this.createConnector(provider, providerRecord.id);
await connector.authenticate();
this.logger.info(`${provider} → ${stage}`);
// Stage 3: Fetch regions from provider API
stage = SyncStage.FETCH_REGIONS;
const regions = await connector.getRegions();
console.log(`[SyncOrchestrator] ${provider} → ${stage} (${regions.length} regions)`);
this.logger.info(`${provider} → ${stage}`, { regions: regions.length });
// Stage 4: Fetch instance types from provider API
stage = SyncStage.FETCH_INSTANCES;
const instances = await connector.getInstanceTypes();
console.log(`[SyncOrchestrator] ${provider} → ${stage} (${instances.length} instances)`);
this.logger.info(`${provider} → ${stage}`, { instances: instances.length });
// Stage 5: Normalize data (add provider_id)
stage = SyncStage.NORMALIZE;
@@ -121,7 +130,7 @@ export class SyncOrchestrator {
...i,
provider_id: providerRecord.id,
}));
console.log(`[SyncOrchestrator] ${provider} → ${stage}`);
this.logger.info(`${provider} → ${stage}`);
// Stage 6: Persist to database
stage = SyncStage.PERSIST;
@@ -135,30 +144,54 @@ export class SyncOrchestrator {
);
// Fetch pricing data - need instance and region IDs from DB
const dbRegions = await this.repos.regions.findByProvider(providerRecord.id);
const dbInstances = await this.repos.instances.findByProvider(providerRecord.id);
// Use D1 batch to reduce query count from 2 to 1 (50% reduction in queries)
const [dbRegionsResult, dbInstancesResult] = await this.repos.db.batch([
this.repos.db.prepare('SELECT id, region_code FROM regions WHERE provider_id = ?').bind(providerRecord.id),
this.repos.db.prepare('SELECT id, instance_id FROM instance_types WHERE provider_id = ?').bind(providerRecord.id)
]);
const regionIds = dbRegions.map(r => r.id);
const instanceTypeIds = dbInstances.map(i => i.id);
if (!dbRegionsResult.success || !dbInstancesResult.success) {
throw new Error('Failed to fetch regions/instances for pricing');
}
const pricing = await connector.getPricing(instanceTypeIds, regionIds);
const pricingCount = await this.repos.pricing.upsertMany(pricing);
// Type-safe extraction of IDs and mapping data from batch results
const regionIds = (dbRegionsResult.results as Array<{ id: number }>).map(r => r.id);
const dbInstancesData = dbInstancesResult.results as Array<{ id: number; instance_id: string }>;
const instanceTypeIds = dbInstancesData.map(i => i.id);
console.log(`[SyncOrchestrator] ${provider} → ${stage} (regions: ${regionsCount}, instances: ${instancesCount}, pricing: ${pricingCount})`);
// Create instance mapping to avoid redundant queries in getPricing
const dbInstanceMap = new Map(
dbInstancesData.map(i => [i.id, { instance_id: i.instance_id }])
);
// Get pricing data - may return array or count depending on provider
const pricingResult = await connector.getPricing(instanceTypeIds, regionIds, dbInstanceMap);
// Handle both return types: array (Linode, Vultr) or number (AWS with generator)
let pricingCount = 0;
if (typeof pricingResult === 'number') {
// Provider processed batches internally, returned count
pricingCount = pricingResult;
} else if (pricingResult.length > 0) {
// Provider returned pricing array, upsert it
pricingCount = await this.repos.pricing.upsertMany(pricingResult);
}
this.logger.info(`${provider} → ${stage}`, { regions: regionsCount, instances: instancesCount, pricing: pricingCount });
// Stage 7: Validate
stage = SyncStage.VALIDATE;
if (regionsCount === 0 || instancesCount === 0) {
throw new Error('No data was synced - possible API or parsing issue');
}
console.log(`[SyncOrchestrator] ${provider} → ${stage}`);
this.logger.info(`${provider} → ${stage}`);
// Stage 8: Complete - Update provider status to success
stage = SyncStage.COMPLETE;
await this.repos.providers.updateSyncStatus(provider, 'success');
const duration = Date.now() - startTime;
console.log(`[SyncOrchestrator] ${provider} → ${stage} (${duration}ms)`);
this.logger.info(`${provider} → ${stage}`, { duration_ms: duration });
return {
provider,
@@ -173,13 +206,13 @@ export class SyncOrchestrator {
const duration = Date.now() - startTime;
const errorMessage = error instanceof Error ? error.message : 'Unknown error';
console.error(`[SyncOrchestrator] ${provider} failed at ${stage}:`, error);
this.logger.error(`${provider} failed at ${stage}`, { error: error instanceof Error ? error.message : String(error), stage });
// Update provider status to error
try {
await this.repos.providers.updateSyncStatus(provider, 'error', errorMessage);
} catch (statusError) {
console.error(`[SyncOrchestrator] Failed to update provider status:`, statusError);
this.logger.error('Failed to update provider status', { error: statusError instanceof Error ? statusError.message : String(statusError) });
}
return {
@@ -210,7 +243,7 @@ export class SyncOrchestrator {
const startedAt = new Date().toISOString();
const startTime = Date.now();
console.log(`[SyncOrchestrator] Starting sync for providers: ${providers.join(', ')}`);
this.logger.info('Starting sync for providers', { providers: providers.join(', ') });
// Run all provider syncs in parallel
const results = await Promise.allSettled(
@@ -228,7 +261,7 @@ export class SyncOrchestrator {
? result.reason.message
: 'Unknown error';
console.error(`[SyncOrchestrator] ${provider} promise rejected:`, result.reason);
this.logger.error(`${provider} promise rejected`, { error: result.reason instanceof Error ? result.reason.message : String(result.reason) });
return {
provider,
@@ -267,90 +300,431 @@ export class SyncOrchestrator {
summary,
};
console.log(`[SyncOrchestrator] Sync complete:`, {
this.logger.info('Sync complete', {
total: summary.total_providers,
success: summary.successful_providers,
failed: summary.failed_providers,
duration: `${totalDuration}ms`,
duration_ms: totalDuration,
});
return report;
}
/**
* Generate AWS pricing records in batches using Generator pattern
* Minimizes memory usage by yielding batches of 100 records at a time
*
* @param instanceTypeIds - Array of database instance type IDs
* @param regionIds - Array of database region IDs
* @param dbInstanceMap - Map of instance type ID to DB instance data
* @param rawInstanceMap - Map of instance_id (API ID) to raw AWS data
* @yields Batches of PricingInput records (100 per batch)
*
* Manual Test:
* Generator yields ~252 batches for ~25,230 total records (870 instances × 29 regions)
*/
private *generateAWSPricingBatches(
instanceTypeIds: number[],
regionIds: number[],
dbInstanceMap: Map<number, { instance_id: string }>,
rawInstanceMap: Map<string, { Cost: number; MonthlyPrice: number }>
): Generator<PricingInput[], void, void> {
const BATCH_SIZE = 100;
let batch: PricingInput[] = [];
for (const regionId of regionIds) {
for (const instanceTypeId of instanceTypeIds) {
const dbInstance = dbInstanceMap.get(instanceTypeId);
if (!dbInstance) {
this.logger.warn('Instance type not found', { instanceTypeId });
continue;
}
const rawInstance = rawInstanceMap.get(dbInstance.instance_id);
if (!rawInstance) {
this.logger.warn('Raw instance data not found', { instance_id: dbInstance.instance_id });
continue;
}
batch.push({
instance_type_id: instanceTypeId,
region_id: regionId,
hourly_price: rawInstance.Cost,
monthly_price: rawInstance.MonthlyPrice,
currency: 'USD',
available: 1,
});
if (batch.length >= BATCH_SIZE) {
yield batch;
batch = [];
}
}
}
// Yield remaining records
if (batch.length > 0) {
yield batch;
}
}
/**
* Generate Linode pricing records in batches using Generator pattern
* Minimizes memory usage by yielding batches at a time (default: 100)
*
* @param instanceTypeIds - Array of database instance type IDs
* @param regionIds - Array of database region IDs
* @param dbInstanceMap - Map of instance type ID to DB instance data
* @param rawInstanceMap - Map of instance_id (API ID) to raw Linode data
* @param env - Environment configuration for SYNC_BATCH_SIZE
* @yields Batches of PricingInput records (configurable batch size)
*
* Manual Test:
* For typical Linode deployment (~200 instance types × 20 regions = 4,000 records):
* - Default batch size (100): ~40 batches
* - Memory savings: ~95% (4,000 records → 100 records in memory)
* - Verify: Check logs for "Generated and upserted pricing records for Linode"
*/
private *generateLinodePricingBatches(
instanceTypeIds: number[],
regionIds: number[],
dbInstanceMap: Map<number, { instance_id: string }>,
rawInstanceMap: Map<string, { id: string; price: { hourly: number; monthly: number } }>,
env?: Env
): Generator<PricingInput[], void, void> {
const BATCH_SIZE = parseInt(env?.SYNC_BATCH_SIZE || '100', 10);
let batch: PricingInput[] = [];
for (const regionId of regionIds) {
for (const instanceTypeId of instanceTypeIds) {
const dbInstance = dbInstanceMap.get(instanceTypeId);
if (!dbInstance) {
this.logger.warn('Instance type not found', { instanceTypeId });
continue;
}
const rawInstance = rawInstanceMap.get(dbInstance.instance_id);
if (!rawInstance) {
this.logger.warn('Raw instance data not found', { instance_id: dbInstance.instance_id });
continue;
}
batch.push({
instance_type_id: instanceTypeId,
region_id: regionId,
hourly_price: rawInstance.price.hourly,
monthly_price: rawInstance.price.monthly,
currency: 'USD',
available: 1,
});
if (batch.length >= BATCH_SIZE) {
yield batch;
batch = [];
}
}
}
// Yield remaining records
if (batch.length > 0) {
yield batch;
}
}
/**
* Generate Vultr pricing records in batches using Generator pattern
* Minimizes memory usage by yielding batches at a time (default: 100)
*
* @param instanceTypeIds - Array of database instance type IDs
* @param regionIds - Array of database region IDs
* @param dbInstanceMap - Map of instance type ID to DB instance data
* @param rawPlanMap - Map of plan_id (API ID) to raw Vultr plan data
* @param env - Environment configuration for SYNC_BATCH_SIZE
* @yields Batches of PricingInput records (configurable batch size)
*
* Manual Test:
* For typical Vultr deployment (~100 plans × 20 regions = 2,000 records):
* - Default batch size (100): ~20 batches
* - Memory savings: ~95% (2,000 records → 100 records in memory)
* - Verify: Check logs for "Generated and upserted pricing records for Vultr"
*/
private *generateVultrPricingBatches(
instanceTypeIds: number[],
regionIds: number[],
dbInstanceMap: Map<number, { instance_id: string }>,
rawPlanMap: Map<string, { id: string; monthly_cost: number }>,
env?: Env
): Generator<PricingInput[], void, void> {
const BATCH_SIZE = parseInt(env?.SYNC_BATCH_SIZE || '100', 10);
let batch: PricingInput[] = [];
for (const regionId of regionIds) {
for (const instanceTypeId of instanceTypeIds) {
const dbInstance = dbInstanceMap.get(instanceTypeId);
if (!dbInstance) {
this.logger.warn('Instance type not found', { instanceTypeId });
continue;
}
const rawPlan = rawPlanMap.get(dbInstance.instance_id);
if (!rawPlan) {
this.logger.warn('Raw plan data not found', { instance_id: dbInstance.instance_id });
continue;
}
// Calculate hourly price: monthly_cost / 730 hours
const hourlyPrice = rawPlan.monthly_cost / 730;
batch.push({
instance_type_id: instanceTypeId,
region_id: regionId,
hourly_price: hourlyPrice,
monthly_price: rawPlan.monthly_cost,
currency: 'USD',
available: 1,
});
if (batch.length >= BATCH_SIZE) {
yield batch;
batch = [];
}
}
}
// Yield remaining records
if (batch.length > 0) {
yield batch;
}
}
/**
* Create connector for a specific provider
*
* @param provider - Provider name
* @returns Connector instance for the provider
* @param providerId - Database provider ID
* @returns Connector adapter instance for the provider
* @throws Error if provider is not supported
*/
private async createConnector(provider: string): Promise<CloudConnector> {
private async createConnector(provider: string, providerId: number): Promise<SyncConnectorAdapter> {
switch (provider.toLowerCase()) {
case 'linode': {
const connector = new LinodeConnector(this.vault);
// Cache instance types for pricing extraction
let cachedInstanceTypes: Awaited<ReturnType<typeof connector.fetchInstanceTypes>> | null = null;
return {
authenticate: () => connector.initialize(),
getRegions: async () => {
const regions = await connector.fetchRegions();
const providerRecord = await this.repos.providers.findByName('linode');
const providerId = providerRecord?.id ?? 0;
return regions.map(r => connector.normalizeRegion(r, providerId));
},
getInstanceTypes: async () => {
const instances = await connector.fetchInstanceTypes();
const providerRecord = await this.repos.providers.findByName('linode');
const providerId = providerRecord?.id ?? 0;
cachedInstanceTypes = instances; // Cache for pricing
return instances.map(i => connector.normalizeInstance(i, providerId));
},
getPricing: async () => {
// Linode pricing is included in instance types
return [];
getPricing: async (
instanceTypeIds: number[],
regionIds: number[],
dbInstanceMap: Map<number, { instance_id: string }>
): Promise<number> => {
/**
* Linode Pricing Extraction Strategy (Generator Pattern):
*
* Linode pricing is embedded in instance type data (price.hourly, price.monthly).
* Generate all region × instance combinations using generator pattern.
*
* Expected volume: ~200 instances × 20 regions = ~4,000 pricing records
* Generator pattern with 100 records/batch minimizes memory usage
* Each batch is immediately persisted to database to avoid memory buildup
*
* Memory savings: ~95% (4,000 records → 100 records in memory at a time)
*
* Manual Test:
* 1. Run sync: curl -X POST http://localhost:8787/api/sync/linode
* 2. Verify pricing count: wrangler d1 execute cloud-instances-db --local --command "SELECT COUNT(*) FROM pricing WHERE instance_type_id IN (SELECT id FROM instance_types WHERE provider_id = (SELECT id FROM providers WHERE name = 'linode'))"
* 3. Sample pricing: wrangler d1 execute cloud-instances-db --local --command "SELECT p.*, i.instance_name, r.region_code FROM pricing p JOIN instance_types i ON p.instance_type_id = i.id JOIN regions r ON p.region_id = r.id WHERE i.provider_id = (SELECT id FROM providers WHERE name = 'linode') LIMIT 10"
* 4. Verify data integrity: wrangler d1 execute cloud-instances-db --local --command "SELECT COUNT(*) FROM pricing WHERE hourly_price = 0 OR monthly_price = 0"
*/
// Re-fetch instance types if not cached
if (!cachedInstanceTypes) {
this.logger.info('Fetching instance types for pricing extraction');
cachedInstanceTypes = await connector.fetchInstanceTypes();
}
// Create lookup map for raw instance data by instance_id (API ID)
const rawInstanceMap = new Map(
cachedInstanceTypes.map(i => [i.id, i])
);
// Use generator pattern for memory-efficient processing
const pricingGenerator = this.generateLinodePricingBatches(
instanceTypeIds,
regionIds,
dbInstanceMap,
rawInstanceMap,
this.env
);
// Process batches incrementally
let totalCount = 0;
for (const batch of pricingGenerator) {
const batchCount = await this.repos.pricing.upsertMany(batch);
totalCount += batchCount;
}
this.logger.info('Generated and upserted pricing records for Linode', { count: totalCount });
// Return total count of processed records
return totalCount;
},
};
}
case 'vultr': {
const connector = new VultrConnector(this.vault);
// Cache plans for pricing extraction
let cachedPlans: Awaited<ReturnType<typeof connector.fetchPlans>> | null = null;
return {
authenticate: () => connector.initialize(),
getRegions: async () => {
const regions = await connector.fetchRegions();
const providerRecord = await this.repos.providers.findByName('vultr');
const providerId = providerRecord?.id ?? 0;
return regions.map(r => connector.normalizeRegion(r, providerId));
},
getInstanceTypes: async () => {
const plans = await connector.fetchPlans();
const providerRecord = await this.repos.providers.findByName('vultr');
const providerId = providerRecord?.id ?? 0;
cachedPlans = plans; // Cache for pricing
return plans.map(p => connector.normalizeInstance(p, providerId));
},
getPricing: async () => {
// Vultr pricing is included in plans
return [];
getPricing: async (
instanceTypeIds: number[],
regionIds: number[],
dbInstanceMap: Map<number, { instance_id: string }>
): Promise<number> => {
/**
* Vultr Pricing Extraction Strategy (Generator Pattern):
*
* Vultr pricing is embedded in plan data (monthly_cost).
* Generate all region × plan combinations using generator pattern.
*
* Expected volume: ~100 plans × 20 regions = ~2,000 pricing records
* Generator pattern with 100 records/batch minimizes memory usage
* Each batch is immediately persisted to database to avoid memory buildup
*
* Memory savings: ~95% (2,000 records → 100 records in memory at a time)
*
* Manual Test:
* 1. Run sync: curl -X POST http://localhost:8787/api/sync/vultr
* 2. Verify pricing count: wrangler d1 execute cloud-instances-db --local --command "SELECT COUNT(*) FROM pricing WHERE instance_type_id IN (SELECT id FROM instance_types WHERE provider_id = (SELECT id FROM providers WHERE name = 'vultr'))"
* 3. Sample pricing: wrangler d1 execute cloud-instances-db --local --command "SELECT p.*, i.instance_name, r.region_code FROM pricing p JOIN instance_types i ON p.instance_type_id = i.id JOIN regions r ON p.region_id = r.id WHERE i.provider_id = (SELECT id FROM providers WHERE name = 'vultr') LIMIT 10"
* 4. Verify data integrity: wrangler d1 execute cloud-instances-db --local --command "SELECT COUNT(*) FROM pricing WHERE hourly_price = 0 OR monthly_price = 0"
*/
// Re-fetch plans if not cached
if (!cachedPlans) {
this.logger.info('Fetching plans for pricing extraction');
cachedPlans = await connector.fetchPlans();
}
// Create lookup map for raw plan data by plan ID (API ID)
const rawPlanMap = new Map(
cachedPlans.map(p => [p.id, p])
);
// Use generator pattern for memory-efficient processing
const pricingGenerator = this.generateVultrPricingBatches(
instanceTypeIds,
regionIds,
dbInstanceMap,
rawPlanMap,
this.env
);
// Process batches incrementally
let totalCount = 0;
for (const batch of pricingGenerator) {
const batchCount = await this.repos.pricing.upsertMany(batch);
totalCount += batchCount;
}
this.logger.info('Generated and upserted pricing records for Vultr', { count: totalCount });
// Return total count of processed records
return totalCount;
},
};
}
case 'aws': {
const connector = new AWSConnector(this.vault);
// Cache instance types for pricing extraction
let cachedInstanceTypes: Awaited<ReturnType<typeof connector.fetchInstanceTypes>> | null = null;
return {
authenticate: () => connector.initialize(),
getRegions: async () => {
const regions = await connector.fetchRegions();
const providerRecord = await this.repos.providers.findByName('aws');
const providerId = providerRecord?.id ?? 0;
return regions.map(r => connector.normalizeRegion(r, providerId));
},
getInstanceTypes: async () => {
const instances = await connector.fetchInstanceTypes();
const providerRecord = await this.repos.providers.findByName('aws');
const providerId = providerRecord?.id ?? 0;
cachedInstanceTypes = instances; // Cache for pricing
return instances.map(i => connector.normalizeInstance(i, providerId));
},
getPricing: async () => {
// AWS pricing is included in instance types from ec2.shop
return [];
getPricing: async (
instanceTypeIds: number[],
regionIds: number[],
dbInstanceMap: Map<number, { instance_id: string }>
): Promise<number> => {
/**
* AWS Pricing Extraction Strategy (Generator Pattern):
*
* AWS pricing from ec2.shop is region-agnostic (same price globally).
* Generate all region × instance combinations using generator pattern.
*
* Expected volume: ~870 instances × 29 regions = ~25,230 pricing records
* Generator pattern with 100 records/batch minimizes memory usage
* Each batch is immediately persisted to database to avoid memory buildup
*
* Manual Test:
* 1. Run sync: curl -X POST http://localhost:8787/api/sync/aws
* 2. Verify pricing count: wrangler d1 execute cloud-instances-db --local --command "SELECT COUNT(*) FROM pricing WHERE instance_type_id IN (SELECT id FROM instance_types WHERE provider_id = (SELECT id FROM providers WHERE name = 'aws'))"
* 3. Sample pricing: wrangler d1 execute cloud-instances-db --local --command "SELECT p.*, i.instance_name, r.region_code FROM pricing p JOIN instance_types i ON p.instance_type_id = i.id JOIN regions r ON p.region_id = r.id WHERE i.provider_id = (SELECT id FROM providers WHERE name = 'aws') LIMIT 10"
* 4. Verify data integrity: wrangler d1 execute cloud-instances-db --local --command "SELECT COUNT(*) FROM pricing WHERE hourly_price = 0 OR monthly_price = 0"
*/
// Re-fetch instance types if not cached
if (!cachedInstanceTypes) {
this.logger.info('Fetching instance types for pricing extraction');
cachedInstanceTypes = await connector.fetchInstanceTypes();
}
// Create lookup map for raw instance data by instance_id (API ID)
const rawInstanceMap = new Map(
cachedInstanceTypes.map(i => [i.InstanceType, i])
);
// Use generator pattern for memory-efficient processing
const pricingGenerator = this.generateAWSPricingBatches(
instanceTypeIds,
regionIds,
dbInstanceMap,
rawInstanceMap
);
// Process batches incrementally
let totalCount = 0;
for (const batch of pricingGenerator) {
const batchCount = await this.repos.pricing.upsertMany(batch);
totalCount += batchCount;
}
this.logger.info('Generated and upserted pricing records for AWS', { count: totalCount });
// Return total count of processed records
return totalCount;
},
};
}

124
src/types.ts
View File

@@ -1,20 +1,20 @@
/**
* Vault Credentials Types
* Vault Credentials Types - supports different providers
*/
export interface VaultCredentials {
provider: string;
api_token: string;
api_token?: string; // Linode
api_key?: string; // Vultr
aws_access_key_id?: string; // AWS
aws_secret_access_key?: string; // AWS
}
/**
* Vault API Response Structure
* Vault API Response Structure - flexible for different providers
*/
export interface VaultSecretResponse {
data: {
data: {
provider: string;
api_token: string;
};
data: Record<string, string>; // Flexible key-value pairs
metadata: {
created_time: string;
custom_metadata: null;
@@ -134,6 +134,7 @@ export const ErrorCodes = {
DATABASE_ERROR: 'DATABASE_ERROR',
TRANSACTION_FAILED: 'TRANSACTION_FAILED',
INVALID_INPUT: 'INVALID_INPUT',
VALIDATION_ERROR: 'VALIDATION_ERROR',
} as const;
// ============================================================
@@ -199,10 +200,10 @@ export interface InstanceQueryParams {
export interface InstanceData extends InstanceType {
/** Provider information */
provider: Provider;
/** Region information */
region: Region;
/** Current pricing information */
pricing: Pricing;
/** Region information (nullable if no pricing data) */
region: Region | null;
/** Current pricing information (nullable if no pricing data) */
pricing: Pricing | null;
}
/**
@@ -258,7 +259,7 @@ export interface ProviderSyncResult {
/** Error message if sync failed */
error?: string;
/** Detailed error information */
error_details?: any;
error_details?: Record<string, unknown>;
}
/**
@@ -336,14 +337,22 @@ export interface HealthResponse {
export interface Env {
/** D1 Database binding */
DB: D1Database;
/** KV namespace for rate limiting */
RATE_LIMIT_KV: KVNamespace;
/** Vault server URL for credentials management */
VAULT_URL: string;
/** Vault authentication token */
VAULT_TOKEN: string;
/** API key for request authentication */
API_KEY: string;
/** Batch size for synchronization operations */
SYNC_BATCH_SIZE?: string;
/** Cache TTL in seconds */
CACHE_TTL_SECONDS?: string;
/** Log level (debug, info, warn, error, none) - Controls logging verbosity */
LOG_LEVEL?: string;
/** CORS origin for Access-Control-Allow-Origin header (default: '*') */
CORS_ORIGIN?: string;
}
// ============================================================
@@ -356,6 +365,8 @@ export interface Env {
export enum SyncStage {
/** Initial stage before sync starts */
IDLE = 'idle',
/** Initialization stage */
INIT = 'init',
/** Fetching provider credentials from Vault */
FETCH_CREDENTIALS = 'fetch_credentials',
/** Fetching regions from provider API */
@@ -365,10 +376,18 @@ export enum SyncStage {
/** Fetching pricing data from provider API */
FETCH_PRICING = 'fetch_pricing',
/** Normalizing and transforming data */
NORMALIZE = 'normalize',
/** Legacy alias for NORMALIZE */
NORMALIZE_DATA = 'normalize_data',
/** Storing data in database */
PERSIST = 'persist',
/** Legacy alias for PERSIST */
STORE_DATA = 'store_data',
/** Validation stage */
VALIDATE = 'validate',
/** Sync completed successfully */
COMPLETE = 'complete',
/** Legacy alias for COMPLETE */
COMPLETED = 'completed',
/** Sync failed with error */
FAILED = 'failed',
@@ -401,9 +420,88 @@ export interface ApiError {
/** Human-readable error message */
message: string;
/** Additional error details */
details?: any;
details?: Record<string, unknown>;
/** Request timestamp (ISO 8601) */
timestamp: string;
/** Request path that caused the error */
path?: string;
}
// ============================================================
// Recommendation API Types
// ============================================================
/**
* Scale type for resource requirements
*/
export type ScaleType = 'small' | 'medium' | 'large';
/**
* Request body for instance recommendations
*/
export interface RecommendationRequest {
/** Technology stack components (e.g., ['nginx', 'mysql', 'redis']) */
stack: string[];
/** Deployment scale (small/medium/large) */
scale: ScaleType;
/** Maximum monthly budget in USD (optional) */
budget_max?: number;
}
/**
* Calculated resource requirements based on stack and scale
*/
export interface ResourceRequirements {
/** Minimum required memory in MB */
min_memory_mb: number;
/** Minimum required vCPU count */
min_vcpu: number;
/** Memory breakdown by component */
breakdown: Record<string, string>;
}
/**
* Individual instance recommendation with scoring
*/
export interface InstanceRecommendation {
/** Recommendation rank (1 = best match) */
rank: number;
/** Cloud provider name */
provider: string;
/** Instance type identifier */
instance: string;
/** Region code */
region: string;
/** Instance specifications */
specs: {
/** Virtual CPU count */
vcpu: number;
/** Memory in MB */
memory_mb: number;
/** Storage in GB */
storage_gb: number;
};
/** Pricing information */
price: {
/** Monthly price in USD */
monthly: number;
/** Hourly price in USD */
hourly: number;
};
/** Match score (0-100) */
match_score: number;
/** Advantages of this instance */
pros: string[];
/** Disadvantages or considerations */
cons: string[];
}
/**
* Complete recommendation response
*/
export interface RecommendationResponse {
/** Calculated resource requirements */
requirements: ResourceRequirements;
/** List of recommended instances (sorted by match score) */
recommendations: InstanceRecommendation[];
}

563
src/utils/logger.test.ts Normal file
View File

@@ -0,0 +1,563 @@
/**
* Logger Utility Tests
*
* Tests Logger class for:
* - Log level filtering
* - Context (prefix) handling
* - Environment-based initialization
* - Sensitive data masking
* - Structured log formatting with timestamps
*/
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { Logger, createLogger } from './logger';
import type { Env } from '../types';
/**
* Create mock environment for testing
*/
const createMockEnv = (logLevel?: string): Env => ({
LOG_LEVEL: logLevel,
DB: {} as any,
RATE_LIMIT_KV: {} as any,
VAULT_URL: 'https://vault.example.com',
VAULT_TOKEN: 'test-token',
API_KEY: 'test-api-key',
});
describe('Logger', () => {
// Store original console methods
const originalConsole = {
log: console.log,
warn: console.warn,
error: console.error,
};
beforeEach(() => {
// Mock console methods
console.log = vi.fn();
console.warn = vi.fn();
console.error = vi.fn();
});
afterEach(() => {
// Restore original console methods
console.log = originalConsole.log;
console.warn = originalConsole.warn;
console.error = originalConsole.error;
});
describe('constructor', () => {
it('should create logger with default INFO level', () => {
const logger = new Logger('[TestService]');
logger.info('test');
expect(console.log).toHaveBeenCalled();
});
it('should create logger with specified level from environment', () => {
const env = createMockEnv('error');
const logger = new Logger('[TestService]', env);
logger.info('test');
expect(console.log).not.toHaveBeenCalled();
logger.error('error');
expect(console.error).toHaveBeenCalled();
});
it('should include context in log messages', () => {
const logger = new Logger('[TestService]');
logger.info('test message');
const logCall = (console.log as any).mock.calls[0][0];
expect(logCall).toContain('[TestService]');
expect(logCall).toContain('test message');
});
});
describe('log level filtering', () => {
it('should log DEBUG and above at DEBUG level', () => {
const env = createMockEnv('debug');
const logger = new Logger('[Test]', env);
logger.debug('debug');
logger.info('info');
logger.warn('warn');
logger.error('error');
expect(console.log).toHaveBeenCalledTimes(2); // debug and info
expect(console.warn).toHaveBeenCalledTimes(1);
expect(console.error).toHaveBeenCalledTimes(1);
});
it('should log INFO and above at INFO level', () => {
const env = createMockEnv('info');
const logger = new Logger('[Test]', env);
logger.debug('debug');
logger.info('info');
logger.warn('warn');
logger.error('error');
expect(console.log).toHaveBeenCalledTimes(1); // only info
expect(console.warn).toHaveBeenCalledTimes(1);
expect(console.error).toHaveBeenCalledTimes(1);
});
it('should log WARN and above at WARN level', () => {
const env = createMockEnv('warn');
const logger = new Logger('[Test]', env);
logger.debug('debug');
logger.info('info');
logger.warn('warn');
logger.error('error');
expect(console.log).not.toHaveBeenCalled();
expect(console.warn).toHaveBeenCalledTimes(1);
expect(console.error).toHaveBeenCalledTimes(1);
});
it('should log only ERROR at ERROR level', () => {
const env = createMockEnv('error');
const logger = new Logger('[Test]', env);
logger.debug('debug');
logger.info('info');
logger.warn('warn');
logger.error('error');
expect(console.log).not.toHaveBeenCalled();
expect(console.warn).not.toHaveBeenCalled();
expect(console.error).toHaveBeenCalledTimes(1);
});
it('should log nothing at NONE level', () => {
const env = createMockEnv('none');
const logger = new Logger('[Test]', env);
logger.debug('debug');
logger.info('info');
logger.warn('warn');
logger.error('error');
expect(console.log).not.toHaveBeenCalled();
expect(console.warn).not.toHaveBeenCalled();
expect(console.error).not.toHaveBeenCalled();
});
it('should default to INFO when LOG_LEVEL is missing', () => {
const logger = new Logger('[Test]');
logger.debug('debug');
logger.info('info');
expect(console.log).toHaveBeenCalledTimes(1); // only info
});
it('should default to INFO when LOG_LEVEL is invalid', () => {
const env = createMockEnv('invalid-level');
const logger = new Logger('[Test]', env);
logger.debug('debug');
logger.info('info');
expect(console.log).toHaveBeenCalledTimes(1); // only info
});
it('should handle case-insensitive log level', () => {
const env = createMockEnv('DEBUG');
const logger = new Logger('[Test]', env);
logger.debug('test');
expect(console.log).toHaveBeenCalled();
});
});
describe('structured logging format', () => {
it('should include ISO 8601 timestamp', () => {
const logger = new Logger('[Test]');
logger.info('test message');
const logCall = (console.log as any).mock.calls[0][0];
// Check for ISO 8601 timestamp format: [YYYY-MM-DDTHH:MM:SS.SSSZ]
expect(logCall).toMatch(/\[\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z\]/);
});
it('should include log level in message', () => {
const logger = new Logger('[Test]');
logger.info('test');
expect((console.log as any).mock.calls[0][0]).toContain('[INFO]');
logger.warn('test');
expect((console.warn as any).mock.calls[0][0]).toContain('[WARN]');
logger.error('test');
expect((console.error as any).mock.calls[0][0]).toContain('[ERROR]');
});
it('should include context in message', () => {
const logger = new Logger('[CustomContext]');
logger.info('test');
const logCall = (console.log as any).mock.calls[0][0];
expect(logCall).toContain('[CustomContext]');
});
it('should format message without data', () => {
const logger = new Logger('[Test]');
logger.info('simple message');
const logCall = (console.log as any).mock.calls[0][0];
expect(logCall).toMatch(/\[.*\] \[INFO\] \[Test\] simple message$/);
});
it('should format message with data as JSON', () => {
const logger = new Logger('[Test]');
logger.info('with data', { username: 'john', count: 42 });
const logCall = (console.log as any).mock.calls[0][0];
expect(logCall).toContain('"username":"john"');
expect(logCall).toContain('"count":42');
});
});
describe('sensitive data masking', () => {
it('should mask api_key field', () => {
const logger = new Logger('[Test]');
logger.info('message', { api_key: 'secret-key-123' });
const logCall = (console.log as any).mock.calls[0][0];
expect(logCall).not.toContain('secret-key-123');
expect(logCall).toContain('***MASKED***');
});
it('should mask api_token field', () => {
const logger = new Logger('[Test]');
logger.info('message', { api_token: 'token-456' });
const logCall = (console.log as any).mock.calls[0][0];
expect(logCall).not.toContain('token-456');
expect(logCall).toContain('***MASKED***');
});
it('should mask password field', () => {
const logger = new Logger('[Test]');
logger.info('message', { password: 'super-secret' });
const logCall = (console.log as any).mock.calls[0][0];
expect(logCall).not.toContain('super-secret');
expect(logCall).toContain('***MASKED***');
});
it('should mask fields with case-insensitive matching', () => {
const logger = new Logger('[Test]');
logger.info('message', { API_KEY: 'key1', Api_Token: 'key2', PASSWORD: 'key3' });
const logCall = (console.log as any).mock.calls[0][0];
expect(logCall).not.toContain('key1');
expect(logCall).not.toContain('key2');
expect(logCall).not.toContain('key3');
// Should have 3 masked fields
expect((logCall.match(/\*\*\*MASKED\*\*\*/g) || []).length).toBe(3);
});
it('should not mask non-sensitive fields', () => {
const logger = new Logger('[Test]');
logger.info('message', { username: 'john', email: 'john@example.com', count: 5 });
const logCall = (console.log as any).mock.calls[0][0];
expect(logCall).toContain('john');
expect(logCall).toContain('john@example.com');
expect(logCall).toContain('5');
});
it('should mask nested sensitive data', () => {
const logger = new Logger('[Test]');
logger.info('message', {
user: 'john',
credentials: {
api_key: 'secret-nested',
},
});
const logCall = (console.log as any).mock.calls[0][0];
expect(logCall).toContain('"user":"john"');
expect(logCall).toContain('"credentials"');
// Verify that nested api_key is masked
expect(logCall).not.toContain('secret-nested');
expect(logCall).toContain('***MASKED***');
});
it('should mask deeply nested sensitive data', () => {
const logger = new Logger('[Test]');
logger.info('message', {
level1: {
level2: {
level3: {
password: 'deep-secret',
},
},
},
});
const logCall = (console.log as any).mock.calls[0][0];
expect(logCall).not.toContain('deep-secret');
expect(logCall).toContain('***MASKED***');
});
it('should mask sensitive data in arrays', () => {
const logger = new Logger('[Test]');
logger.info('message', {
users: [
{ name: 'alice', api_token: 'token-1' },
{ name: 'bob', api_token: 'token-2' },
],
});
const logCall = (console.log as any).mock.calls[0][0];
expect(logCall).toContain('"name":"alice"');
expect(logCall).toContain('"name":"bob"');
expect(logCall).not.toContain('token-1');
expect(logCall).not.toContain('token-2');
// Should have 2 masked fields
expect((logCall.match(/\*\*\*MASKED\*\*\*/g) || []).length).toBe(2);
});
it('should handle mixed nested and top-level sensitive data', () => {
const logger = new Logger('[Test]');
logger.info('message', {
api_key: 'top-level-secret',
config: {
database: {
password: 'db-password',
},
api_token: 'nested-token',
},
});
const logCall = (console.log as any).mock.calls[0][0];
expect(logCall).not.toContain('top-level-secret');
expect(logCall).not.toContain('db-password');
expect(logCall).not.toContain('nested-token');
// Should have 3 masked fields
expect((logCall.match(/\*\*\*MASKED\*\*\*/g) || []).length).toBe(3);
});
it('should prevent infinite recursion with max depth', () => {
const logger = new Logger('[Test]');
// Create a deeply nested object (depth > 5)
const deepObject: any = { level1: {} };
let current = deepObject.level1;
for (let i = 2; i <= 10; i++) {
current[`level${i}`] = {};
current = current[`level${i}`];
}
current.secret = 'should-be-visible-due-to-max-depth';
logger.info('message', deepObject);
const logCall = (console.log as any).mock.calls[0][0];
// Should not throw error and should complete
expect(logCall).toBeDefined();
});
it('should handle circular references gracefully', () => {
const logger = new Logger('[Test]');
const circular: any = { name: 'test' };
circular.self = circular; // Create circular reference
logger.info('message', circular);
const logCall = (console.log as any).mock.calls[0][0];
// Should not throw error and should show serialization failed message
expect(logCall).toContain('[data serialization failed]');
});
});
describe('createLogger factory', () => {
it('should create logger with context', () => {
const logger = createLogger('[Factory]');
logger.info('test');
const logCall = (console.log as any).mock.calls[0][0];
expect(logCall).toContain('[Factory]');
});
it('should create logger with environment', () => {
const env = createMockEnv('error');
const logger = createLogger('[Factory]', env);
logger.info('info');
logger.error('error');
expect(console.log).not.toHaveBeenCalled();
expect(console.error).toHaveBeenCalled();
});
});
describe('debug method', () => {
it('should log at DEBUG level', () => {
const env = createMockEnv('debug');
const logger = new Logger('[Test]', env);
logger.debug('debug message', { detail: 'info' });
expect(console.log).toHaveBeenCalled();
const logCall = (console.log as any).mock.calls[0][0];
expect(logCall).toContain('[DEBUG]');
expect(logCall).toContain('debug message');
expect(logCall).toContain('"detail":"info"');
});
it('should not log at INFO level', () => {
const env = createMockEnv('info');
const logger = new Logger('[Test]', env);
logger.debug('debug message');
expect(console.log).not.toHaveBeenCalled();
});
});
describe('info method', () => {
it('should log at INFO level', () => {
const logger = new Logger('[Test]');
logger.info('info message', { status: 'ok' });
expect(console.log).toHaveBeenCalled();
const logCall = (console.log as any).mock.calls[0][0];
expect(logCall).toContain('[INFO]');
expect(logCall).toContain('info message');
expect(logCall).toContain('"status":"ok"');
});
});
describe('warn method', () => {
it('should log at WARN level', () => {
const logger = new Logger('[Test]');
logger.warn('warning message', { reason: 'deprecated' });
expect(console.warn).toHaveBeenCalled();
const logCall = (console.warn as any).mock.calls[0][0];
expect(logCall).toContain('[WARN]');
expect(logCall).toContain('warning message');
expect(logCall).toContain('"reason":"deprecated"');
});
});
describe('error method', () => {
it('should log at ERROR level', () => {
const logger = new Logger('[Test]');
logger.error('error message', { code: 500 });
expect(console.error).toHaveBeenCalled();
const logCall = (console.error as any).mock.calls[0][0];
expect(logCall).toContain('[ERROR]');
expect(logCall).toContain('error message');
expect(logCall).toContain('"code":500');
});
it('should log error with Error object', () => {
const logger = new Logger('[Test]');
const error = new Error('Test error');
logger.error('Exception caught', { error: error.message });
expect(console.error).toHaveBeenCalled();
const logCall = (console.error as any).mock.calls[0][0];
expect(logCall).toContain('Exception caught');
expect(logCall).toContain('Test error');
});
});
describe('edge cases', () => {
it('should handle empty message', () => {
const logger = new Logger('[Test]');
expect(() => logger.info('')).not.toThrow();
expect(console.log).toHaveBeenCalled();
});
it('should handle special characters in message', () => {
const logger = new Logger('[Test]');
logger.info('Message with special chars: @#$%^&*()');
const logCall = (console.log as any).mock.calls[0][0];
expect(logCall).toContain('Message with special chars: @#$%^&*()');
});
it('should handle very long messages', () => {
const logger = new Logger('[Test]');
const longMessage = 'x'.repeat(1000);
logger.info(longMessage);
const logCall = (console.log as any).mock.calls[0][0];
expect(logCall).toContain(longMessage);
});
it('should handle undefined data gracefully', () => {
const logger = new Logger('[Test]');
logger.info('message', undefined);
const logCall = (console.log as any).mock.calls[0][0];
expect(logCall).not.toContain('undefined');
});
it('should handle null values in data', () => {
const logger = new Logger('[Test]');
logger.info('message', { value: null });
const logCall = (console.log as any).mock.calls[0][0];
expect(logCall).toContain('"value":null');
});
it('should handle arrays in data', () => {
const logger = new Logger('[Test]');
logger.info('message', { items: [1, 2, 3] });
const logCall = (console.log as any).mock.calls[0][0];
expect(logCall).toContain('"items":[1,2,3]');
});
it('should handle nested objects', () => {
const logger = new Logger('[Test]');
logger.info('message', {
user: { id: 1, name: 'Test' },
metadata: { created: '2024-01-01' },
});
const logCall = (console.log as any).mock.calls[0][0];
expect(logCall).toContain('"user":{');
expect(logCall).toContain('"name":"Test"');
});
});
});

123
src/utils/logger.ts Normal file
View File

@@ -0,0 +1,123 @@
/**
* Logger Utility - Structured logging system for Cloudflare Workers
*
* Features:
* - Log level filtering (DEBUG, INFO, WARN, ERROR, NONE)
* - Environment variable configuration (LOG_LEVEL)
* - Structured log formatting with timestamps
* - Automatic sensitive data masking
* - Context identification with prefixes
* - TypeScript type safety
*
* @example
* const logger = createLogger('[ServiceName]', env);
* logger.debug('Debug message', { key: 'value' });
* logger.info('Info message');
* logger.warn('Warning message');
* logger.error('Error message', { error });
*/
import type { Env } from '../types';
export enum LogLevel {
DEBUG = 0,
INFO = 1,
WARN = 2,
ERROR = 3,
NONE = 4,
}
const LOG_LEVEL_MAP: Record<string, LogLevel> = {
debug: LogLevel.DEBUG,
info: LogLevel.INFO,
warn: LogLevel.WARN,
error: LogLevel.ERROR,
none: LogLevel.NONE,
};
export class Logger {
private level: LogLevel;
private context: string;
constructor(context: string, env?: Env) {
this.context = context;
this.level = LOG_LEVEL_MAP[env?.LOG_LEVEL?.toLowerCase() ?? 'info'] ?? LogLevel.INFO;
}
private formatMessage(level: string, message: string, data?: Record<string, unknown>): string {
const timestamp = new Date().toISOString();
try {
const dataStr = data ? ` ${JSON.stringify(this.maskSensitive(data))}` : '';
return `[${timestamp}] [${level}] ${this.context} ${message}${dataStr}`;
} catch (error) {
// Circular reference or other JSON serialization failure
return `[${timestamp}] [${level}] ${this.context} ${message} [data serialization failed]`;
}
}
private maskSensitive(data: Record<string, unknown>, depth: number = 0): Record<string, unknown> {
const MAX_DEPTH = 5; // Prevent infinite recursion
if (depth > MAX_DEPTH) return data;
const sensitiveKeys = ['api_key', 'api_token', 'password', 'secret', 'token', 'key', 'authorization', 'credential'];
const masked: Record<string, unknown> = {};
for (const [key, value] of Object.entries(data)) {
const keyLower = key.toLowerCase();
// Check if key is sensitive
if (sensitiveKeys.some(sk => keyLower.includes(sk))) {
masked[key] = '***MASKED***';
}
// Recursively handle nested objects
else if (value && typeof value === 'object' && !Array.isArray(value)) {
masked[key] = this.maskSensitive(value as Record<string, unknown>, depth + 1);
}
// Handle arrays containing objects
else if (Array.isArray(value)) {
masked[key] = value.map(item =>
item && typeof item === 'object'
? this.maskSensitive(item as Record<string, unknown>, depth + 1)
: item
);
}
else {
masked[key] = value;
}
}
return masked;
}
debug(message: string, data?: Record<string, unknown>): void {
if (this.level <= LogLevel.DEBUG) {
console.log(this.formatMessage('DEBUG', message, data));
}
}
info(message: string, data?: Record<string, unknown>): void {
if (this.level <= LogLevel.INFO) {
console.log(this.formatMessage('INFO', message, data));
}
}
warn(message: string, data?: Record<string, unknown>): void {
if (this.level <= LogLevel.WARN) {
console.warn(this.formatMessage('WARN', message, data));
}
}
error(message: string, data?: Record<string, unknown>): void {
if (this.level <= LogLevel.ERROR) {
console.error(this.formatMessage('ERROR', message, data));
}
}
}
// Factory function for creating logger instances
export function createLogger(context: string, env?: Env): Logger {
return new Logger(context, env);
}
// Default logger instance for backward compatibility
export const logger = new Logger('[App]');

326
src/utils/validation.test.ts Normal file
View File

@@ -0,0 +1,326 @@
/**
* Validation Utilities Tests
*
* Tests for reusable validation functions used across route handlers.
*/
import { describe, it, expect } from 'vitest';
import {
parseJsonBody,
validateProviders,
validatePositiveNumber,
validateStringArray,
validateEnum,
createErrorResponse,
} from './validation';
import { HTTP_STATUS } from '../constants';
describe('Validation Utilities', () => {
describe('parseJsonBody', () => {
it('should parse valid JSON body', async () => {
const body = { stack: ['nginx'], scale: 'medium' };
const request = new Request('https://api.example.com', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(body),
});
const result = await parseJsonBody(request);
expect(result.success).toBe(true);
if (result.success) {
expect(result.data).toEqual(body);
}
});
it('should reject missing content-type header', async () => {
const request = new Request('https://api.example.com', {
method: 'POST',
body: JSON.stringify({ test: 'data' }),
});
const result = await parseJsonBody(request);
expect(result.success).toBe(false);
if (!result.success) {
expect(result.error.code).toBe('INVALID_CONTENT_TYPE');
}
});
it('should reject non-JSON content-type', async () => {
const request = new Request('https://api.example.com', {
method: 'POST',
headers: { 'Content-Type': 'text/plain' },
body: 'plain text',
});
const result = await parseJsonBody(request);
expect(result.success).toBe(false);
if (!result.success) {
expect(result.error.code).toBe('INVALID_CONTENT_TYPE');
}
});
it('should reject invalid JSON', async () => {
const request = new Request('https://api.example.com', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: 'not valid json',
});
const result = await parseJsonBody(request);
expect(result.success).toBe(false);
if (!result.success) {
expect(result.error.code).toBe('INVALID_JSON');
}
});
});
describe('validateProviders', () => {
const supportedProviders = ['linode', 'vultr', 'aws'] as const;
it('should validate array of supported providers', () => {
const result = validateProviders(['linode', 'vultr'], supportedProviders);
expect(result.success).toBe(true);
if (result.success) {
expect(result.data).toEqual(['linode', 'vultr']);
}
});
it('should reject non-array input', () => {
const result = validateProviders('linode', supportedProviders);
expect(result.success).toBe(false);
if (!result.success) {
expect(result.error.code).toBe('INVALID_PROVIDERS');
}
});
it('should reject empty array', () => {
const result = validateProviders([], supportedProviders);
expect(result.success).toBe(false);
if (!result.success) {
expect(result.error.code).toBe('EMPTY_PROVIDERS');
}
});
it('should reject array with non-string elements', () => {
const result = validateProviders(['linode', 123], supportedProviders);
expect(result.success).toBe(false);
if (!result.success) {
expect(result.error.code).toBe('INVALID_PROVIDER_TYPE');
}
});
it('should reject unsupported providers', () => {
const result = validateProviders(['linode', 'invalid'], supportedProviders);
expect(result.success).toBe(false);
if (!result.success) {
expect(result.error.code).toBe('UNSUPPORTED_PROVIDERS');
expect(result.error.message).toContain('invalid');
}
});
});
describe('validatePositiveNumber', () => {
it('should validate positive number', () => {
const result = validatePositiveNumber(42, 'limit');
expect(result.success).toBe(true);
if (result.success) {
expect(result.data).toBe(42);
}
});
it('should validate zero as positive', () => {
const result = validatePositiveNumber(0, 'offset');
expect(result.success).toBe(true);
if (result.success) {
expect(result.data).toBe(0);
}
});
it('should parse string numbers', () => {
const result = validatePositiveNumber('100', 'limit');
expect(result.success).toBe(true);
if (result.success) {
expect(result.data).toBe(100);
}
});
it('should return default value when input is null/undefined', () => {
const result = validatePositiveNumber(null, 'limit', 50);
expect(result.success).toBe(true);
if (result.success) {
expect(result.data).toBe(50);
}
});
it('should reject null/undefined without default', () => {
const result = validatePositiveNumber(null, 'limit');
expect(result.success).toBe(false);
if (!result.success) {
expect(result.error.code).toBe('MISSING_PARAMETER');
}
});
it('should reject negative numbers', () => {
const result = validatePositiveNumber(-5, 'limit');
expect(result.success).toBe(false);
if (!result.success) {
expect(result.error.code).toBe('INVALID_PARAMETER');
expect(result.error.message).toContain('positive');
}
});
it('should reject NaN', () => {
const result = validatePositiveNumber('not-a-number', 'limit');
expect(result.success).toBe(false);
if (!result.success) {
expect(result.error.code).toBe('INVALID_PARAMETER');
}
});
});
describe('validateStringArray', () => {
it('should validate array of strings', () => {
const result = validateStringArray(['nginx', 'mysql'], 'stack');
expect(result.success).toBe(true);
if (result.success) {
expect(result.data).toEqual(['nginx', 'mysql']);
}
});
it('should reject missing value', () => {
const result = validateStringArray(undefined, 'stack');
expect(result.success).toBe(false);
if (!result.success) {
expect(result.error.code).toBe('MISSING_PARAMETER');
}
});
it('should reject non-array', () => {
const result = validateStringArray('nginx', 'stack');
expect(result.success).toBe(false);
if (!result.success) {
expect(result.error.code).toBe('INVALID_PARAMETER');
}
});
it('should reject empty array', () => {
const result = validateStringArray([], 'stack');
expect(result.success).toBe(false);
if (!result.success) {
expect(result.error.code).toBe('EMPTY_ARRAY');
}
});
it('should reject array with non-string elements', () => {
const result = validateStringArray(['nginx', 123], 'stack');
expect(result.success).toBe(false);
if (!result.success) {
expect(result.error.code).toBe('INVALID_ARRAY_ELEMENT');
}
});
});
describe('validateEnum', () => {
const allowedScales = ['small', 'medium', 'large'] as const;
it('should validate allowed enum value', () => {
const result = validateEnum('medium', 'scale', allowedScales);
expect(result.success).toBe(true);
if (result.success) {
expect(result.data).toBe('medium');
}
});
it('should reject missing value', () => {
const result = validateEnum(undefined, 'scale', allowedScales);
expect(result.success).toBe(false);
if (!result.success) {
expect(result.error.code).toBe('MISSING_PARAMETER');
}
});
it('should reject invalid enum value', () => {
const result = validateEnum('extra-large', 'scale', allowedScales);
expect(result.success).toBe(false);
if (!result.success) {
expect(result.error.code).toBe('INVALID_PARAMETER');
expect(result.error.message).toContain('small, medium, large');
}
});
it('should reject non-string value', () => {
const result = validateEnum(123, 'scale', allowedScales);
expect(result.success).toBe(false);
if (!result.success) {
expect(result.error.code).toBe('INVALID_PARAMETER');
}
});
});
describe('createErrorResponse', () => {
it('should create error response with default 400 status', () => {
const error = {
code: 'TEST_ERROR',
message: 'Test error message',
};
const response = createErrorResponse(error);
expect(response.status).toBe(HTTP_STATUS.BAD_REQUEST);
});
it('should create error response with custom status', () => {
const error = {
code: 'NOT_FOUND',
message: 'Resource not found',
};
const response = createErrorResponse(error, HTTP_STATUS.NOT_FOUND);
expect(response.status).toBe(HTTP_STATUS.NOT_FOUND);
});
it('should include error details in JSON body', async () => {
const error = {
code: 'VALIDATION_ERROR',
message: 'Validation failed',
parameter: 'stack',
details: { received: 'invalid' },
};
const response = createErrorResponse(error);
const body = (await response.json()) as {
success: boolean;
error: typeof error;
};
expect(body.success).toBe(false);
expect(body.error).toEqual(error);
});
});
});

358
src/utils/validation.ts Normal file
View File

@@ -0,0 +1,358 @@
/**
* Validation Utilities
*
* Reusable validation functions for request parameters and body parsing.
* Provides consistent error handling and type-safe validation results.
*/
import { HTTP_STATUS } from '../constants';
/**
* Validation result type using discriminated union
*/
export type ValidationResult<T> =
| { success: true; data: T }
| { success: false; error: ValidationError };
/**
* Validation error structure
*/
export interface ValidationError {
code: string;
message: string;
parameter?: string;
details?: unknown;
}
/**
* Parse JSON body from request with error handling
*
* @param request - HTTP request object
* @returns Validation result with parsed body or error
*
* @example
* const result = await parseJsonBody<{ stack: string[] }>(request);
* if (!result.success) {
* return Response.json({ success: false, error: result.error }, { status: 400 });
* }
* const { stack } = result.data;
*/
export async function parseJsonBody<T>(request: Request): Promise<ValidationResult<T>> {
try {
const contentType = request.headers.get('content-type');
if (!contentType || !contentType.includes('application/json')) {
return {
success: false,
error: {
code: 'INVALID_CONTENT_TYPE',
message: 'Content-Type must be application/json',
},
};
}
const body = (await request.json()) as T;
return { success: true, data: body };
} catch (error) {
return {
success: false,
error: {
code: 'INVALID_JSON',
message: 'Invalid JSON in request body',
details: error instanceof Error ? error.message : 'Unknown error',
},
};
}
}
/**
* Validate providers array
*
* @param providers - Providers to validate
* @param supportedProviders - List of supported provider names
* @returns Validation result with validated providers or error
*
* @example
* const result = validateProviders(body.providers, SUPPORTED_PROVIDERS);
* if (!result.success) {
* return Response.json({ success: false, error: result.error }, { status: 400 });
* }
*/
export function validateProviders(
providers: unknown,
supportedProviders: readonly string[]
): ValidationResult<string[]> {
// Check if providers is an array
if (!Array.isArray(providers)) {
return {
success: false,
error: {
code: 'INVALID_PROVIDERS',
message: 'Providers must be an array',
details: { received: typeof providers },
},
};
}
// Check if array is not empty
if (providers.length === 0) {
return {
success: false,
error: {
code: 'EMPTY_PROVIDERS',
message: 'At least one provider must be specified',
},
};
}
// Validate each provider is a string
for (const provider of providers) {
if (typeof provider !== 'string') {
return {
success: false,
error: {
code: 'INVALID_PROVIDER_TYPE',
message: 'Each provider must be a string',
details: { provider, type: typeof provider },
},
};
}
}
// Validate each provider is supported
const unsupportedProviders: string[] = [];
for (const provider of providers) {
if (!supportedProviders.includes(provider as string)) {
unsupportedProviders.push(provider as string);
}
}
if (unsupportedProviders.length > 0) {
return {
success: false,
error: {
code: 'UNSUPPORTED_PROVIDERS',
message: `Unsupported providers: ${unsupportedProviders.join(', ')}`,
details: {
unsupported: unsupportedProviders,
supported: supportedProviders,
},
},
};
}
return { success: true, data: providers as string[] };
}
/**
* Validate and parse positive number parameter
*
* @param value - Value to validate
* @param name - Parameter name for error messages
* @param defaultValue - Default value if parameter is undefined
* @returns Validation result with parsed number or error
*
* @example
* const result = validatePositiveNumber(searchParams.get('limit'), 'limit', 50);
* if (!result.success) {
* return Response.json({ success: false, error: result.error }, { status: 400 });
* }
* const limit = result.data;
*/
export function validatePositiveNumber(
value: unknown,
name: string,
defaultValue?: number
): ValidationResult<number> {
// Return default if value is null/undefined and default is provided
if ((value === null || value === undefined) && defaultValue !== undefined) {
return { success: true, data: defaultValue };
}
// Return error if value is null/undefined and no default
if (value === null || value === undefined) {
return {
success: false,
error: {
code: 'MISSING_PARAMETER',
message: `${name} is required`,
parameter: name,
},
};
}
// Parse number
const parsed = typeof value === 'string' ? Number(value) : value;
// Validate it's a number
if (typeof parsed !== 'number' || isNaN(parsed)) {
return {
success: false,
error: {
code: 'INVALID_PARAMETER',
message: `Invalid value for ${name}: must be a number`,
parameter: name,
},
};
}
// Validate it's positive
if (parsed < 0) {
return {
success: false,
error: {
code: 'INVALID_PARAMETER',
message: `Invalid value for ${name}: must be a positive number`,
parameter: name,
},
};
}
return { success: true, data: parsed };
}
/**
* Validate string array parameter
*
* @param value - Value to validate
* @param name - Parameter name for error messages
* @returns Validation result with validated array or error
*
* @example
* const result = validateStringArray(body.stack, 'stack');
* if (!result.success) {
* return Response.json({ success: false, error: result.error }, { status: 400 });
* }
*/
export function validateStringArray(
value: unknown,
name: string
): ValidationResult<string[]> {
// Check if value is missing
if (value === undefined || value === null) {
return {
success: false,
error: {
code: 'MISSING_PARAMETER',
message: `${name} is required`,
parameter: name,
},
};
}
// Check if value is an array
if (!Array.isArray(value)) {
return {
success: false,
error: {
code: 'INVALID_PARAMETER',
message: `${name} must be an array`,
parameter: name,
details: { received: typeof value },
},
};
}
// Check if array is not empty
if (value.length === 0) {
return {
success: false,
error: {
code: 'EMPTY_ARRAY',
message: `${name} must contain at least one element`,
parameter: name,
},
};
}
// Validate each element is a string
for (const element of value) {
if (typeof element !== 'string') {
return {
success: false,
error: {
code: 'INVALID_ARRAY_ELEMENT',
message: `Each ${name} element must be a string`,
parameter: name,
details: { element, type: typeof element },
},
};
}
}
return { success: true, data: value as string[] };
}
/**
* Validate enum value
*
* @param value - Value to validate
* @param name - Parameter name for error messages
* @param allowedValues - List of allowed values
* @returns Validation result with validated value or error
*
* @example
* const result = validateEnum(body.scale, 'scale', ['small', 'medium', 'large']);
* if (!result.success) {
* return Response.json({ success: false, error: result.error }, { status: 400 });
* }
*/
export function validateEnum<T extends string>(
value: unknown,
name: string,
allowedValues: readonly T[]
): ValidationResult<T> {
// Check if value is missing
if (value === undefined || value === null) {
return {
success: false,
error: {
code: 'MISSING_PARAMETER',
message: `${name} is required`,
parameter: name,
details: { supported: allowedValues },
},
};
}
// Check if value is in allowed values
if (typeof value !== 'string' || !allowedValues.includes(value as T)) {
return {
success: false,
error: {
code: 'INVALID_PARAMETER',
message: `${name} must be one of: ${allowedValues.join(', ')}`,
parameter: name,
details: { received: value, supported: allowedValues },
},
};
}
return { success: true, data: value as T };
}
/**
* Create error response from validation error
*
* @param error - Validation error
* @param statusCode - HTTP status code (defaults to 400)
* @returns HTTP Response with error details
*
* @example
* const result = validatePositiveNumber(value, 'limit');
* if (!result.success) {
* return createErrorResponse(result.error);
* }
*/
export function createErrorResponse(
error: ValidationError,
statusCode: number = HTTP_STATUS.BAD_REQUEST
): Response {
return Response.json(
{
success: false,
error,
},
{ status: statusCode }
);
}