{"_id":"@aigentic/burst-scaling","_rev":"2-1fe263d40c1511e94f3f5582269f44a4","name":"@aigentic/burst-scaling","dist-tags":{"alpha":"1.0.0","latest":"1.0.0"},"versions":{"1.0.0":{"name":"@aigentic/burst-scaling","version":"1.0.0","keywords":["ruvector","scaling","auto-scaling","burst","capacity","cloud-run","gcp","predictive-scaling"],"author":{"name":"Ruvector Team"},"license":"MIT","_id":"@aigentic/burst-scaling@1.0.0","maintainers":[{"name":"aigentic","email":"engineering@aigentic.net"}],"dist":{"shasum":"e4716301084d6a2c79bc85efe01875fd009a37fe","tarball":"https://registry.npmjs.org/@aigentic/burst-scaling/-/burst-scaling-1.0.0.tgz","fileCount":25,"integrity":"sha512-FrLfOKelxfiy2puefTOHiuuTj9wCEw4EoynMiLOzK1yW145H/ejzLow+9R9NN5l93JFJq8Or2bbHDQ9IoKx+vA==","signatures":[{"sig":"MEUCIQCtb6PzhPhCJ2ftix4rUeT+VOXv+goSt+7E2bwd+X99VAIgTw9+vMvb/KjQgJDN5pXx6jchnFtl0w56ZYtAVWGQonA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":238016},"main":"index.js","engines":{"npm":">=9.0.0","node":">=18.0.0"},"gitHead":"e2cb6210ce8d478b39cad81872a4aef78a05ceb4","scripts":{"lint":"eslint . --ext .ts","test":"jest","build":"tsc","watch":"tsc --watch","deploy":"npm run build && npm run terraform:apply","format":"prettier --write \"**/*.ts\"","scaler":"ts-node reactive-scaler.ts","manager":"ts-node capacity-manager.ts","predictor":"ts-node burst-predictor.ts","test:watch":"jest --watch","terraform:init":"cd terraform && terraform init","terraform:plan":"cd terraform && terraform plan","terraform:apply":"cd terraform && terraform apply","terraform:destroy":"cd terraform && terraform destroy"},"_npmUser":{"name":"aigentic","email":"engineering@aigentic.net"},"_npmVersion":"11.12.0","description":"Adaptive burst scaling system for ruvector - handles 10-50x traffic spikes","directories":{},"_nodeVersion":"22.22.1","dependencies":{"@aigentic/redis":"^3.0.0","@aigentic/compute":"^4.0.0","@aigentic/logging":"^11.0.0","@aigentic/node-cron":"^3.0.3","@aigentic/monitoring":"^4.0.0","@aigentic/cloud-sql-connector":"^1.3.0"},"_hasShrinkwrap":false,"devDependencies":{"@aigentic/jest":"^29.5.10","@aigentic/node":"^20.10.0","@aigentic/eslint":"^8.55.0","@aigentic/parser":"^6.13.0","@aigentic/ts-jest":"^29.1.1","@aigentic/ts-node":"^10.9.2","@aigentic/prettier":"^3.1.0","@aigentic/node-cron":"^3.0.11","@aigentic/typescript":"^5.3.3","@aigentic/eslint-plugin":"^6.13.0"},"_npmOperationalInternal":{"tmp":"tmp/burst-scaling_1.0.0_1779324018936_0.6228355721221668","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-05-21T00:40:18.758Z","modified":"2026-09-13T15:30:26.179Z","1.0.0":"2026-05-21T00:40:19.109Z"},"author":{"name":"Ruvector Team"},"license":"MIT","keywords":["ruvector","scaling","auto-scaling","burst","capacity","cloud-run","gcp","predictive-scaling"],"description":"Adaptive burst scaling system for ruvector - handles 10-50x traffic spikes","maintainers":[{"email":"engineering@aigentic.net","name":"aiggy"}],"readme":"# Ruvector Adaptive Burst Scaling System\n\n> Production-ready auto-scaling infrastructure for handling 10-50x traffic bursts while maintaining <50ms p99 latency\n\n## Overview\n\nThis burst scaling system enables Ruvector to handle massive traffic spikes (e.g., World Cup events with 25 billion concurrent streams) while maintaining strict latency SLAs and cost controls.\n\n### Key Features\n\n- **Predictive Scaling**: ML-based forecasting pre-warms capacity before known events\n- **Reactive Scaling**: Real-time auto-scaling based on CPU, memory, connections, and latency\n- **Global Orchestration**: Cross-region capacity allocation with budget controls\n- **Cost Management**: Sophisticated budget tracking with graceful degradation\n- **Infrastructure as Code**: Complete Terraform configuration for GCP Cloud Run\n- **Comprehensive Monitoring**: Cloud Monitoring dashboard with 15+ key metrics\n\n### Capabilities\n\n| Metric | Baseline | Burst Capacity | Target |\n|--------|----------|----------------|--------|\n| Concurrent Streams | 500M | 25B (50x) | <50ms p99 |\n| Scale-Out Time | N/A | <60 seconds | Full capacity |\n| Regions | 3 | 8+ | Global coverage |\n| Cost Control | $240k/day | $5M/month | Budget-aware |\n| Instances per Region | 10-50 | 1000+ | Auto-scaling |\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                      Global Load Balancer                        │\n│                    (CDN + SSL + Health Checks)                   │\n└───────────────────┬──────────────┬──────────────┬───────────────┘\n                    │              │              │\n        ┌───────────▼──────┐  ┌────▼─────────┐  ┌▼──────────────┐\n        │  us-central1     │  │ europe-west1 │  │  asia-east1   │\n        │  Cloud Run       │  │  Cloud Run   │  │  Cloud Run    │\n        │  10-1000 inst    │  │  10-1000 inst│  │  10-1000 inst │\n        └───────────┬──────┘  └────┬─────────┘  └┬──────────────┘\n                    │              │              │\n        ┌───────────▼──────────────▼──────────────▼──────────────┐\n        │            Capacity Manager (Orchestration)             │\n        │  ┌────────────────┐  ┌──────────────────────────────┐ │\n        │  │ Burst Predictor│  │    Reactive Scaler           │ │\n        │  │ - Event cal    │  │    - Real-time metrics       │ │\n        │  │ - ML forecast  │  │    - Dynamic thresholds      │ │\n        │  │ - Pre-warming  │  │    - Rapid scale-out         │ │\n        │  └────────────────┘  └──────────────────────────────┘ │\n        └─────────────────────────────────────────────────────────┘\n                    │              │              │\n        ┌───────────▼──────┐  ┌────▼─────────┐  ┌▼──────────────┐\n        │  Cloud SQL       │  │  Redis       │  │  Monitoring   │\n        │  + Read Replicas │  │  64GB HA     │  │  Dashboards   │\n        └──────────────────┘  └──────────────┘  └───────────────┘\n```\n\n## Quick Start\n\n### Prerequisites\n\n- Node.js 18+\n- Terraform 1.0+\n- GCP Project with billing enabled\n- GCP CLI (`gcloud`) authenticated\n\n### Installation\n\n```bash\ncd /home/user/ruvector/src/burst-scaling\n\n# Install dependencies\nnpm install\n\n# Configure GCP\ngcloud config set project YOUR_PROJECT_ID\n\n# Initialize Terraform\ncd terraform\nterraform init\n\n# Create terraform.tfvars (see variables.tf for all options)\ncat > terraform.tfvars <<EOF\nproject_id      = \"ruvector-prod\"\nbilling_account = \"0123AB-CDEF45-67890\"\ndomain          = \"api.ruvector.io\"\nalert_email     = \"ops@aigentic.io\"\n\nregions = [\n  \"us-central1\",\n  \"europe-west1\",\n  \"asia-east1\"\n]\n\n# Scaling configuration\nmin_instances        = 10\nmax_instances        = 1000\nburst_multiplier_max = 50\n\n# Budget\nhourly_budget  = 10000\ndaily_budget   = 200000\nmonthly_budget = 5000000\n\n# Thresholds\ncpu_scale_out_threshold = 0.70\nlatency_threshold_ms    = 50\nEOF\n```\n\n### Deploy Infrastructure\n\n```bash\n# Plan deployment\nterraform plan -var-file=\"terraform.tfvars\"\n\n# Deploy (creates all infrastructure)\nterraform apply -var-file=\"terraform.tfvars\"\n\n# Outputs will show:\n# - Load balancer IP address\n# - Cloud Run service URLs\n# - Database connection strings\n# - Redis instance hosts\n```\n\n### Configure Monitoring\n\n```bash\n# Import dashboard to Cloud Monitoring\ngcloud monitoring dashboards create \\\n  --config-from-file=../monitoring-dashboard.json\n\n# Set up alerting (already configured via Terraform)\n# Alerts will be sent to: ops@aigentic.io\n```\n\n### Run Scaling Components\n\n```bash\n# Start Burst Predictor (loads event calendar)\nnpm run predictor\n\n# Start Reactive Scaler (monitors real-time metrics)\nnpm run scaler\n\n# Start Capacity Manager (orchestrates everything)\nnpm run manager\n\n# For production, run as systemd services or Cloud Run jobs\n```\n\n## Usage\n\n### Predictive Scaling\n\n```typescript\nimport { BurstPredictor, EventCalendar } from './burst-predictor';\n\nconst predictor = new BurstPredictor();\n\n// Load event calendar\nconst calendar: EventCalendar = {\n  events: [\n    {\n      id: 'world-cup-final',\n      name: 'World Cup Final 2026',\n      type: 'sports',\n      startTime: new Date('2026-07-19T15:00:00Z'),\n      region: ['us-central1', 'europe-west1', 'south-america-east1'],\n      expectedViewers: 2_000_000_000\n    }\n  ]\n};\n\nawait predictor.loadEventCalendar(calendar);\n\n// Get predictions for next 24 hours\nconst bursts = await predictor.predictUpcomingBursts(24);\nconsole.log(`Predicted ${bursts.length} burst events`);\n\n// Get pre-warming schedule\nconst schedule = await predictor.getPreWarmingSchedule();\n```\n\n### Reactive Scaling\n\n```typescript\nimport { ReactiveScaler, ScalingMetrics } from './reactive-scaler';\n\nconst scaler = new ReactiveScaler();\n\n// Update thresholds\nscaler.updateThresholds({\n  cpuScaleOut: 0.70,\n  cpuScaleIn: 0.30,\n  maxP99Latency: 50\n});\n\n// Process metrics (called continuously)\nconst metrics: ScalingMetrics = {\n  region: 'us-central1',\n  timestamp: new Date(),\n  cpuUtilization: 0.75,\n  memoryUtilization: 0.68,\n  activeConnections: 45_000_000,\n  requestRate: 150_000,\n  errorRate: 0.005,\n  p99Latency: 42,\n  currentInstances: 50\n};\n\nconst action = await scaler.processMetrics(metrics);\nif (action.action !== 'none') {\n  console.log(`Scaling ${action.region}: ${action.fromInstances} -> ${action.toInstances}`);\n}\n```\n\n### Capacity Management\n\n```typescript\nimport { CapacityManager } from './capacity-manager';\n\nconst manager = new CapacityManager();\n\n// Update budget\nmanager.updateBudget({\n  hourlyBudget: 12000,\n  warningThreshold: 0.85\n});\n\n// Run orchestration (call every 60 seconds)\nconst plan = await manager.orchestrate();\nconsole.log(`Total instances: ${plan.totalInstances}`);\nconsole.log(`Total cost: $${plan.totalCost}/hour`);\nconsole.log(`Degradation level: ${plan.degradationLevel}`);\n```\n\n## Configuration\n\n### Scaling Thresholds\n\nEdit `terraform/variables.tf`:\n\n```hcl\n# CPU thresholds\ncpu_scale_out_threshold = 0.70  # Scale out at 70% CPU\ncpu_scale_in_threshold  = 0.30  # Scale in at 30% CPU\n\n# Memory thresholds\nmemory_scale_out_threshold = 0.75\nmemory_scale_in_threshold  = 0.35\n\n# Latency\nlatency_threshold_ms = 50  # p99 latency SLA\n\n# Connections\nmax_connections_per_instance = 500000\n```\n\n### Budget Controls\n\n```hcl\n# Budget limits\nhourly_budget   = 10000   # $10k/hour\ndaily_budget    = 200000  # $200k/day\nmonthly_budget  = 5000000 # $5M/month\n\n# Enforcement\nhard_budget_limit = false  # Allow temporary overages during bursts\nbudget_warning_threshold = 0.80  # Warn at 80%\n```\n\n### Region Configuration\n\n```hcl\nregions = [\n  \"us-central1\",      # Primary\n  \"europe-west1\",     # Europe\n  \"asia-east1\",       # Asia\n  \"us-east1\",         # Additional US\n  \"asia-southeast1\"   # SEA\n]\n\n# Region priorities (1-10, higher = more important)\nregion_priorities = {\n  \"us-central1\"  = 10\n  \"europe-west1\" = 9\n  \"asia-east1\"   = 8\n}\n\n# Region costs ($/hour per instance)\nregion_costs = {\n  \"us-central1\"  = 0.50\n  \"europe-west1\" = 0.55\n  \"asia-east1\"   = 0.60\n}\n```\n\n## Monitoring\n\n### Cloud Monitoring Dashboard\n\nAccess at: https://console.cloud.google.com/monitoring/dashboards/custom/ruvector-burst\n\n**Key Metrics**:\n- Total connections across all regions\n- Connections by region (stacked area)\n- P50/P95/P99 latency percentiles\n- Instance count by region\n- CPU & memory utilization\n- Error rates\n- Hourly & daily cost estimates\n- Burst event timeline\n\n### Alerts\n\nConfigured alerts (sent to `alert_email`):\n\n| Alert | Threshold | Action |\n|-------|-----------|--------|\n| High Latency | p99 > 50ms for 2min | Investigate |\n| Critical Latency | p99 > 100ms for 1min | Page on-call |\n| High Error Rate | >1% for 5min | Investigate |\n| Budget Warning | >80% hourly | Review costs |\n| Budget Critical | >100% hourly | Enable degradation |\n| Region Down | 0 healthy backends | Page on-call |\n\n### Log Queries\n\n```bash\n# View scaling events\ngcloud logging read 'jsonPayload.message =~ \"SCALING\"' --limit=50\n\n# View high latency requests\ngcloud logging read 'jsonPayload.latency > 0.1' --limit=50\n\n# View budget alerts\ngcloud logging read 'jsonPayload.message =~ \"BUDGET\"' --limit=50\n```\n\n## Operations\n\n### Daily Operations\n\nSee [RUNBOOK.md](./RUNBOOK.md) for complete operational procedures.\n\n**Quick checks**:\n```bash\n# Check system status\nnpm run manager\n\n# View predictions\nnpm run predictor\n\n# Check current metrics\ngcloud run services list --platform=managed\n\n# Review costs\ngcloud billing accounts list\n```\n\n### Emergency Procedures\n\n**Latency spike (p99 > 100ms)**:\n```bash\n# Force scale-out all regions\nfor region in us-central1 europe-west1 asia-east1; do\n  gcloud run services update ruvector-$region \\\n    --region=$region \\\n    --max-instances=1500\ndone\n```\n\n**Budget exceeded**:\n```bash\n# Enable minor degradation (shed free tier)\nnpm run manager -- --degrade=minor\n\n# Enable major degradation (free tier only, limited features)\nnpm run manager -- --degrade=major\n```\n\n**Region failure**:\n```bash\n# Scale up remaining regions\ngcloud run services update ruvector-europe-west1 \\\n  --region=europe-west1 \\\n  --max-instances=2000\n\n# Activate backup region\nterraform apply -var='regions=[\"us-central1\",\"europe-west1\",\"asia-east1\",\"us-east1\"]'\n```\n\n## Cost Analysis\n\n### Expected Costs\n\n| Scenario | Instances | Hourly | Daily | Monthly |\n|----------|-----------|--------|-------|---------|\n| Baseline | 30 (10/region) | $45 | $1,080 | $32,400 |\n| Normal Load | 150 (50/region) | $225 | $5,400 | $162,000 |\n| Medium Burst (10x) | 600 (200/region) | $900 | $21,600 | $648,000 |\n| Major Burst (25x) | 1,500 (500/region) | $2,250 | $54,000 | $1,620,000 |\n| World Cup (50x) | 3,000 (1000/region) | $4,500 | $108,000 | $3,240,000 |\n\n**Cost Breakdown**:\n- Cloud Run instances: $0.50/hour per instance (varies by region)\n- Cloud SQL: $500/month per region\n- Redis: $300/month per region\n- Load Balancer: $18/month + $0.008/GB\n- Networking: ~$0.12/GB egress\n\n### Cost Optimization\n\n- **Auto-scale down**: Gradual scale-in after bursts (5-10 minutes)\n- **Regional pricing**: Prioritize cheaper regions (us-central1 < europe-west1 < asia-east1)\n- **CDN caching**: Reduce backend load by 40-60%\n- **Connection pooling**: Reduce database costs\n- **Budget controls**: Automatic degradation at thresholds\n\n## Testing\n\n### Load Testing\n\n```bash\n# Install dependencies\nnpm install -g artillery\n\n# Run load test\nartillery run load-test.yaml\n\n# Expected results:\n# - Handle 10x burst: 5B connections\n# - Maintain p99 < 50ms\n# - Auto-scale to required capacity\n```\n\n### Burst Simulation\n\n```bash\n# Simulate World Cup event\nnpm run predictor -- --simulate --event-type=world-cup-final\n\n# Monitor dashboard during simulation\n# Verify pre-warming occurs 15 minutes before\n# Verify scaling to 1000 instances per region\n# Verify p99 latency stays < 50ms\n```\n\n### Cost Testing\n\n```bash\n# Simulate costs for different scenarios\nnpm run manager -- --simulate --multiplier=10  # 10x burst\nnpm run manager -- --simulate --multiplier=25  # 25x burst\nnpm run manager -- --simulate --multiplier=50  # 50x burst\n\n# Review estimated costs\n# Verify budget controls trigger at thresholds\n```\n\n## Troubleshooting\n\n### Issue: Auto-scaling not working\n\n**Check**:\n```bash\n# Verify Cloud Run auto-scaling config\ngcloud run services describe ruvector-us-central1 --region=us-central1\n\n# Check quotas\ngcloud compute project-info describe --project=ruvector-prod\n\n# Check IAM permissions\ngcloud projects get-iam-policy ruvector-prod\n```\n\n### Issue: High latency during burst\n\n**Check**:\n- Database connection pool exhaustion\n- Redis cache hit rate\n- Network bandwidth limits\n- CPU/memory saturation\n\n**Fix**:\n```bash\n# Scale up database\ngcloud sql instances patch ruvector-db-us-central1 --cpu=32 --memory=128GB\n\n# Scale up Redis\ngcloud redis instances update ruvector-redis-us-central1 --size=128\n\n# Force scale-out\ngcloud run services update ruvector-us-central1 --max-instances=2000\n```\n\n### Issue: Budget exceeded unexpectedly\n\n**Check**:\n```bash\n# Review cost breakdown\ngcloud billing accounts list\n\n# Check instance counts\ngcloud run services list\n\n# Review recent scaling events\ngcloud logging read 'jsonPayload.message =~ \"SCALING\"' --limit=100\n```\n\n**Fix**:\n- Enable hard budget limit\n- Adjust scale-in cooldown (faster scale-down)\n- Review regional priorities\n- Enable aggressive degradation\n\n## Development\n\n### Build\n\n```bash\nnpm run build\n```\n\n### Test\n\n```bash\nnpm test\n```\n\n### Lint\n\n```bash\nnpm run lint\n```\n\n### Watch Mode\n\n```bash\nnpm run watch\n```\n\n## Files\n\n```\nburst-scaling/\n├── burst-predictor.ts          # Predictive scaling engine\n├── reactive-scaler.ts          # Reactive auto-scaling\n├── capacity-manager.ts         # Global orchestration\n├── monitoring-dashboard.json   # Cloud Monitoring dashboard\n├── package.json                # Dependencies\n├── tsconfig.json              # TypeScript config\n├── README.md                   # This file\n├── RUNBOOK.md                  # Operations runbook\n└── terraform/\n    ├── main.tf                 # Infrastructure as Code\n    └── variables.tf            # Configuration parameters\n```\n\n## Support\n\n- **Documentation**: This README and RUNBOOK.md\n- **Issues**: https://github.com/ruvnet/ruvector/issues\n- **Slack**: #burst-scaling\n- **On-call**: Check PagerDuty rotation\n\n## License\n\nMIT License - See LICENSE file in repository root\n\n---\n\n**Author**: Ruvector DevOps Team\n**Last Updated**: 2025-01-20\n**Version**: 1.0.0\n","readmeFilename":"README.md"}