cloud-server/CONSTANTS_MIGRATION.md

# Constants Centralization - Migration Summary

## Overview
Successfully centralized all magic numbers and duplicate constants into `/Users/kaffa/cloud-server/src/constants.ts`.

## Created File
- **src/constants.ts** - Centralized constants file with comprehensive documentation

## Constants Organized by Category

### 1. Provider Configuration
- `SUPPORTED_PROVIDERS` - ['linode', 'vultr', 'aws']
- `SupportedProvider` - Type definition

### 2. Cache Configuration
- `CACHE_TTL` - Cache TTL values in seconds
  - `INSTANCES`: 300 (5 minutes)
  - `HEALTH`: 30 (30 seconds)
  - `PRICING`: 3600 (1 hour)
  - `DEFAULT`: 300 (5 minutes)
- `CACHE_TTL_MS` - Cache TTL values in milliseconds

### 3. Rate Limiting Configuration
- `RATE_LIMIT_DEFAULTS`
  - `WINDOW_MS`: 60000 (1 minute)
  - `MAX_REQUESTS_INSTANCES`: 100
  - `MAX_REQUESTS_SYNC`: 10

### 4. Pagination Configuration
- `PAGINATION`
  - `DEFAULT_PAGE`: 1
  - `DEFAULT_LIMIT`: 50
  - `MAX_LIMIT`: 100
  - `DEFAULT_OFFSET`: 0

### 5. HTTP Status Codes
- `HTTP_STATUS`
  - `OK`: 200
  - `CREATED`: 201
  - `NO_CONTENT`: 204
  - `BAD_REQUEST`: 400
  - `UNAUTHORIZED`: 401
  - `NOT_FOUND`: 404
  - `TOO_MANY_REQUESTS`: 429
  - `INTERNAL_ERROR`: 500
  - `SERVICE_UNAVAILABLE`: 503

### 6. Database Configuration
- `TABLES` - Database table names
  - `PROVIDERS`, `REGIONS`, `INSTANCE_TYPES`, `PRICING`, `PRICE_HISTORY`

### 7. Query Configuration
- `VALID_SORT_FIELDS` - Array of valid sort fields
- `SORT_ORDERS` - ['asc', 'desc']
- `INSTANCE_FAMILIES` - ['general', 'compute', 'memory', 'storage', 'gpu']

### 8. CORS Configuration
- `CORS`
  - `DEFAULT_ORIGIN`: '*'
  - `MAX_AGE`: '86400' (24 hours)

### 9. Timeout Configuration
- `TIMEOUTS`
  - `AWS_REQUEST`: 15000 (15 seconds)
  - `DEFAULT_REQUEST`: 30000 (30 seconds)

### 10. Validation Constants
- `VALIDATION`
  - `MIN_MEMORY_MB`: 1
  - `MIN_VCPU`: 1
  - `MIN_PRICE`: 0

## Files Modified

### Routes
- ✅ **src/routes/instances.ts**
  - Removed duplicate `SUPPORTED_PROVIDERS`, `VALID_SORT_FIELDS`, `VALID_FAMILIES`
  - Replaced `DEFAULT_LIMIT`, `MAX_LIMIT`, `DEFAULT_OFFSET` with `PAGINATION` constants
  - Replaced magic numbers (300, 400, 500, 200) with `HTTP_STATUS` and `CACHE_TTL` constants

- ✅ **src/routes/sync.ts**
  - Removed duplicate `SUPPORTED_PROVIDERS`
  - Replaced HTTP status codes with `HTTP_STATUS` constants

- ✅ **src/routes/recommend.ts**
  - Replaced HTTP status codes with `HTTP_STATUS` constants

- ✅ **src/routes/health.ts**
  - Replaced HTTP status codes (200, 503) with `HTTP_STATUS` constants

### Services
- ✅ **src/services/cache.ts**
  - Updated default TTL to use `CACHE_TTL.DEFAULT`
  - Updated example documentation

### Middleware
- ✅ **src/middleware/rateLimit.ts**
  - Replaced hardcoded rate limit values with `RATE_LIMIT_DEFAULTS`
  - Replaced 429 status code with `HTTP_STATUS.TOO_MANY_REQUESTS`

### Main Entry Point
- ✅ **src/index.ts**
  - Replaced CORS constants with `CORS` configuration
  - Replaced HTTP status codes with `HTTP_STATUS` constants

### Connectors
- ✅ **src/connectors/aws.ts**
  - Replaced 15000 timeout with `TIMEOUTS.AWS_REQUEST`
  - Replaced 500 status code with `HTTP_STATUS.INTERNAL_ERROR`

- ✅ **src/connectors/vultr.ts**
  - Replaced 500, 429 status codes with `HTTP_STATUS` constants

- ✅ **src/connectors/linode.ts**
  - Replaced 500, 429 status codes with `HTTP_STATUS` constants

- ✅ **src/connectors/vault.ts**
  - Replaced 500 status code with `HTTP_STATUS.INTERNAL_ERROR`

## Benefits

### 1. Single Source of Truth
- All constants defined in one location
- No more duplicate definitions across files
- Easy to find and update values

### 2. Type Safety
- Exported types ensure compile-time validation
- Prevents typos and invalid values

### 3. Maintainability
- Changes only need to be made in one place
- Clear documentation for each constant
- Easier to understand configuration at a glance

### 4. Consistency
- Ensures same values are used across the codebase
- Reduces bugs from inconsistent magic numbers

### 5. Documentation
- Each constant group has clear comments
- Example usage in documentation
- Semantic names improve code readability

## Migration Impact

### No Breaking Changes
- All changes are internal refactoring
- API behavior remains unchanged
- Existing functionality preserved

### Type Check Results
✅ TypeScript compilation successful (only pre-existing test warnings remain)

## Usage Examples

### Before
```typescript
const cache = new CacheService(300); // What does 300 mean?
return Response.json(data, { status: 400 }); // Magic number
const limit = 50; // Hardcoded default
```

### After
```typescript
const cache = new CacheService(CACHE_TTL.INSTANCES); // Clear semantic meaning
return Response.json(data, { status: HTTP_STATUS.BAD_REQUEST }); // Self-documenting
const limit = PAGINATION.DEFAULT_LIMIT; // Single source of truth
```

## Future Improvements

### Additional Constants to Consider
- Log level constants
- API version strings
- Default batch sizes
- Retry attempt limits
- Timeout values for other services

### Environment-Based Configuration
- Consider moving some constants to environment variables
- Example: `CACHE_TTL` could be configurable per environment

## Verification Steps

1. ✅ Created centralized constants file
2. ✅ Updated all route handlers
3. ✅ Updated all service files
4. ✅ Updated all middleware
5. ✅ Updated all connectors
6. ✅ TypeScript compilation successful
7. ✅ No breaking changes introduced

## Conclusion

All magic numbers and duplicate constants have been successfully centralized into `src/constants.ts`. The codebase is now more maintainable, type-safe, and self-documenting. All changes maintain backward compatibility while improving code quality.