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

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

After

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.