Skip to content

README.md

Latest commit

 

History

History
148 lines (111 loc) · 4.05 KB

README.md

File metadata and controls

148 lines (111 loc) · 4.05 KB

Evergreen API

An API for Evergreen built on Javascript and Cloudflare Workers with hybrid caching implementation.

API Tests Caching Validation Security & Dependencies

🚀 Features

  • Hybrid Caching System: 2-tier caching (Memory + KV) with 12-hour TTL
  • Performance Optimized: Reduces KV reads to stay within free tier limits
  • Comprehensive Testing: Automated validation of API functionality and caching
  • Security Focused: Regular security audits and dependency updates
  • Production Ready: Robust error handling and monitoring

🔧 Architecture

Caching Strategy

  1. Memory Cache (Tier 1): Instant access for frequently requested data
  2. KV Storage (Tier 2): Persistent storage with automatic memory promotion
  3. 12-Hour TTL: Optimal balance between freshness and performance

Monitoring

  • Cache hit/miss tracking via X-Cache-Status headers
  • Performance metrics and response time monitoring
  • Automated health checks and diagnostics

📊 API Endpoints

Endpoint Description Cache TTL
/apps List all supported applications 12 hours
/app/{appId} Get specific application details 12 hours
/endpoints/versions Version check endpoints 12 hours
/endpoints/downloads Download endpoints 12 hours
/health System health and diagnostics No cache

🧪 Testing

Automated Testing

  • Pull Request Validation: Automatic testing on PR creation
  • Multi-Environment: Tests against both production and development APIs
  • Performance Testing: Cache behavior and response time validation
  • Security Scanning: Dependency audits and vulnerability checks

Manual Testing

# Run test suite
cd tests
npm install
npm test

# Test caching behavior
./test-caching-simple.sh

🔒 Security

  • Regular dependency audits
  • API security validation
  • Input sanitization and validation
  • Rate limiting awareness
  • License compliance checking

📈 Performance

Cache Performance

  • Memory Cache Hit: ~1ms response time
  • KV Cache Miss: ~50-100ms response time
  • Cache Efficiency: 90%+ hit rate for popular endpoints
  • KV Read Reduction: 95% reduction in KV operations

Monitoring

# Check cache status
curl -H "User-Agent: YourApp/1.0.0" https://evergreen-api.stealthpuppy.com/health

# Monitor cache headers
curl -I -H "User-Agent: YourApp/1.0.0" https://evergreen-api.stealthpuppy.com/apps

🛠️ Development

Local Development

# Install dependencies
npm install

# Start development server
wrangler dev

# Run tests
cd tests && npm test

Deployment

# Deploy to staging
wrangler deploy --env staging

# Deploy to production
wrangler deploy --env production

📚 Documentation

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make changes with tests
  4. Submit pull request
  5. Automated workflows will validate your changes

Guidelines

  • Include tests for new features
  • Maintain API compatibility
  • Update documentation as needed
  • Follow security best practices

📋 Requirements

  • Node.js 18+ for development
  • Cloudflare Workers account
  • KV namespace: EVERGREEN
  • R2 bucket: evergreen-api (for logging)

🔧 Configuration

Environment Variables

  • ENVIRONMENT: deployment environment (production/staging/dev)

Bindings

  • EVERGREEN: KV namespace for application data
  • LOGS_BUCKET: R2 bucket for request logging

🚨 Monitoring & Alerts

  • GitHub Actions for CI/CD pipeline
  • Automated security scanning
  • Performance regression detection
  • Dependency update notifications