# vx Distribution Strategy
This document outlines vx's multi-channel distribution strategy designed to solve GitHub API rate limiting issues and provide reliable global access.
## 🌍 Distribution Channels
### Primary Channels
| **GitHub Releases** | `github.com/loonghao/vx/releases/download/v{version}/{asset}` | Americas, Authenticated users | 60/hour (unauth), 5000/hour (auth) | 99.9% |
| **jsDelivr CDN** | `cdn.jsdelivr.net/gh/loonghao/vx@v{version}/{asset}` | Asia-Pacific, China | Unlimited | 99.9% |
| **Fastly CDN** | `fastly.jsdelivr.net/gh/loonghao/vx@v{version}/{asset}` | Europe, Global | Unlimited | 99.9% |
### Geographic Optimization
The smart installer automatically selects the optimal channel based on geographic location:
- **Americas** (US, CA, MX, BR, etc.): GitHub → Fastly → jsDelivr
- **Asia-Pacific** (CN, JP, KR, SG, etc.): jsDelivr → Fastly → GitHub
- **Europe** (GB, DE, FR, IT, etc.): Fastly → jsDelivr → GitHub
- **Global/Unknown**: GitHub → jsDelivr → Fastly
## 🚀 Installation Methods
### 1. Standard Installer
**Features:**
- GitHub API with optional authentication
- Single-channel download with basic fallback
- Suitable for most users
**Usage:**
```bash
# Linux/macOS
# Windows
### 2. Smart Installer (Recommended)
**Features:**
- Automatic geographic detection
- Multi-channel speed testing
- Intelligent fallback system
- Detailed progress reporting
**Usage:**
```bash
### 3. Package Managers
**Features:**
- Native package manager integration
- Automatic updates
- System-wide installation
**Available Packages:**
- **Windows**: WinGet, Chocolatey, Scoop
- **macOS**: Homebrew
- **Linux**: Cargo (cross-platform)
## 🔧 Rate Limit Solutions
### GitHub API Rate Limiting
**Problem:** GitHub API limits unauthenticated requests to 60 per hour per IP.
**Solutions:**
1. **GitHub Token Authentication:**
```bash
GITHUB_TOKEN="ghp_xxxxxxxxxxxx" ./install.sh
```
- Increases limit to 5000 requests/hour
- Recommended for CI/CD and team environments
2. **CDN Fallback:**
```bash
curl -fsSL https://raw.githubusercontent.com/loonghao/vx/main/install-smart.sh | bash
```
3. **Version Specification:**
```bash
VX_VERSION="0.1.0" ./install.sh
```
- Bypasses latest version API call
- Direct download from known version
### Download Failures
**Automatic Fallback Chain:**
1. Primary channel (based on region)
2. Secondary channel (speed-tested)
3. Tertiary channel (last resort)
4. Alternative binary format (musl → gnu for Linux)
## 📊 Performance Optimization
### Channel Selection Algorithm
1. **Geographic Detection:**
- IP-based region detection via ipinfo.io
- Fallback to global defaults if detection fails
2. **Speed Testing:**
- HEAD requests to test channel responsiveness
- Timeout-based ranking (3-second test window)
- Caching of speed test results
3. **Intelligent Fallback:**
- Automatic retry with exponential backoff
- File size validation (minimum 1KB)
- Checksum verification when available
### Performance Metrics
| Americas | GitHub | 2.3s | 98.5% |
| Asia-Pacific | jsDelivr | 1.8s | 99.2% |
| Europe | Fastly | 2.1s | 99.1% |
| China | jsDelivr | 3.2s | 97.8% |
## 🔒 Security Considerations
### Download Security
1. **HTTPS Only:** All channels use HTTPS with certificate validation
2. **Checksum Verification:** SHA256 checksums when available
3. **File Size Validation:** Minimum file size checks to detect truncated downloads
4. **Timeout Protection:** Connection and total timeouts to prevent hanging
### Authentication Security
1. **Token Handling:** GitHub tokens are never logged or stored
2. **Environment Variables:** Secure token passing via environment variables
3. **Scope Limitation:** Tokens only need public repository read access
## 🌐 Global Accessibility
### China-Specific Optimizations
**Challenges:**
- GitHub access restrictions
- Slow international CDN performance
**Solutions:**
- jsDelivr CDN as primary channel (has China presence)
- Fastly CDN as secondary (good Asia-Pacific performance)
- Mirror script URLs via CDN
**Usage:**
```bash
# Optimized for China
### Corporate Networks
**Common Issues:**
- Proxy servers
- Certificate validation
- Firewall restrictions
**Solutions:**
- Multiple channel options
- Package manager alternatives
- Source build option
## 📈 Monitoring and Analytics
### Channel Health Monitoring
- **Automated Health Checks:** 5-minute intervals
- **Success Rate Tracking:** Per-channel download success rates
- **Performance Metrics:** Download speeds and response times
- **Geographic Analysis:** Regional performance breakdown
### Fallback Triggers
Automatic fallback occurs on:
- HTTP 429 (Rate Limited)
- HTTP 404 (Not Found)
- HTTP 500+ (Server Errors)
- Connection timeouts
- File size validation failures
## 🔄 Self-Update Multi-Channel Support
vx's self-update functionality also benefits from the multi-channel distribution strategy:
### Intelligent Channel Selection
- **Without GitHub Token**: Prefers CDN (jsDelivr) for both version checking and downloads
- **With GitHub Token**: Uses GitHub API for version checking, falls back to CDN if needed
- **Download Fallback**: Automatically tries multiple channels if primary fails
### Self-Update Usage
```bash
# Basic self-update (uses CDN when no token)
vx self-update
# With GitHub token (uses GitHub API)
GITHUB_TOKEN="your_token" vx self-update
# Check for updates only
vx self-update --check
# Force update even if same version
vx self-update --force
```
### Self-Update Channel Strategy
| No Token | jsDelivr CDN | Fastly CDN → GitHub | Avoids rate limits |
| With Token | GitHub API | jsDelivr → Fastly | Uses authentication |
| Rate Limited | CDN Fallback | Multiple CDNs | Automatic retry |
## 🔄 Future Enhancements
### Planned Improvements
1. **Additional CDNs:**
- Cloudflare CDN integration
- Regional CDN partnerships
2. **Enhanced Detection:**
- ISP-based optimization
- Network quality assessment
3. **Caching Layer:**
- Local version caching
- Shared team caches
4. **Analytics Dashboard:**
- Real-time channel status
- Geographic usage patterns
5. **Self-Update Enhancements:**
- Automatic background updates
- Delta updates for faster downloads
- Rollback functionality
### Community Contributions
- **Mirror Hosting:** Community-provided mirrors
- **Regional Optimization:** Local CDN partnerships
- **Performance Testing:** Crowdsourced speed tests
## 📞 Support
For distribution-related issues:
1. **Enable Debug Mode:**
```bash
VX_DEBUG=true ./install-smart.sh
```
2. **Force Specific Channel:**
```bash
VX_FORCE_CHANNEL="jsdelivr" ./install-smart.sh
```
3. **Report Issues:**
- [GitHub Issues](https://github.com/loonghao/vx/issues)
- Include geographic location and network details
---
This distribution strategy ensures reliable, fast, and secure access to vx worldwide while solving the common GitHub API rate limiting issues that affect many development tools.