A high-performance gateway service that provides easy access to WVM Network bundles with local file caching, application tracking, and automatic content-type detection.
A hosted gateway deployed from this repo is available to test at resolver.bot
- Local file caching with SQLite database
- Application-based content organization
- Automatic content-type detection
- Cache management and cleanup
- Comprehensive logging
- Cache statistics and monitoring
- Docker deployment support
- CORS enabled
# Install dependencies
npm install
# Create configuration
cp config/example.json config/default.json
# Start the server
npm start# Build and start the container
docker compose up -d
# View logs
docker compose logs -fWe provide a development helper script for common tasks:
# Make script executable
chmod +x scripts/dev.sh
# Show available commands
./scripts/dev.sh help
# Set up development environment
./scripts/dev.sh setup
# Start development server
./scripts/dev.sh start
# Run tests
./scripts/dev.sh testFor more detailed development instructions, see Development Guide.
The gateway can be configured using JSON configuration files. See Configuration Guide for detailed settings documentation.
Environment-specific configurations:
config/default.json- Default settingsconfig/development.json- Development settings (smaller cache, more logging)config/example.json- Example configuration template
GET /bundle/:txHash/:index
txHash: Transaction hash of the bundleindex: Index of the envelope within the bundle (zero-based)
Content-Type: Automatically detected content typeContent-Length: Size of the content in bytesCache-Control: public, max-age=31536000 (1 year)X-Cache: HIT/MISS (indicates if content was served from cache)
curl http://localhost:3001/bundle/0xf4aa3cc6580d1ecbc93a9c015087718bee67290a6cf14587bbae7ef69e8e65fe/0GET /cache/stats
Returns overall cache statistics.
GET /cache/apps
Returns list of applications with cached content.
GET /cache/apps/:appName
Returns all cached content for an application.
GET /cache/apps/:appName/stats
Returns statistics for an application.
POST /cache/clear # Clear all cache
POST /cache/apps/:appName/clear # Clear application cache
The gateway uses these tags from bundles:
Content-Type: Content type (optional)Application-Name: Application grouping (optional, defaults to "unknown")
.
├── config/ # Configuration files
├── docker/ # Docker documentation
├── scripts/ # Helper scripts
├── src/
│ └── lib/ # Core modules
│ ├── config.js # Configuration management
│ ├── database.js # SQLite database operations
│ ├── logger.js # Logging functionality
│ └── cacheManager.js # Cache management
├── tests/
│ ├── unit/ # Unit tests
│ ├── integration/ # Integration tests
│ └── fixtures/ # Test fixtures
└── index.js # Application entry point
Run tests:
npm test # Run all tests
npm run test:watch # Watch mode
npm run test:coverage # Coverage reportnpm run lint # Run ESLint
npm run format # Format with Prettier- Node.js 16 or higher
- Persistent storage for cache
- Write access to cache/logs directories
- Using Installation Script:
sudo ./scripts/install-service.sh- Using Docker: See Docker Deployment Guide
The installation script:
- Creates service user and group
- Sets up directories and permissions
- Installs systemd service
- Configures monitoring and log rotation
- Starts and enables the service
NODE_ENV: Environment mode (development, production)CONFIG_PATH: Path to configuration filePORT: Server port (overrides config)HOST: Server host (overrides config)LOG_LEVEL: Logging level (overrides config)
# View cache statistics
npm run cache:stats
# List applications
npm run cache:apps
# Verify cache integrity
npm run cache:verify
# Run cache cleanup
npm run cache:cleanup
# Advanced cache operations
./scripts/cache-manager.js helpThe gateway includes automated monitoring:
- Service health checks (every 5 minutes)
- Cache cleanup (daily)
- Cache integrity verification (weekly)
- Statistics export (daily)
- Log rotation (weekly)
Configure monitoring alerts:
- Edit scripts/monitor.sh
- Set ALERT_EMAIL for email notifications
- Set SLACK_WEBHOOK for Slack notifications
View monitoring status:
# Run manual check
./scripts/monitor.sh
# View monitoring logs
tail -f /var/log/wvm-gateway/monitor.logLogs are automatically rotated with these settings:
- Application logs: Daily rotation, 14 days retention
- Statistics files: Weekly rotation, 52 weeks retention
- All logs are compressed after rotation
Log locations:
- Application logs: /var/log/wvm-gateway/*.log
- Statistics: /var/log/wvm-gateway/stats/*.json
- System logs: journalctl -u wvm-gateway
The gateway provides multiple backup options:
- Configuration backup
- Cache data backup
- Log files backup
Use the uninstall script with backup option:
sudo ./scripts/uninstall.sh
# Choose 'y' when prompted for backup- Stop the service:
sudo systemctl stop wvm-gateway- Update files and restart:
git pull
sudo systemctl restart wvm-gatewayTo remove the gateway and all its components:
sudo ./scripts/uninstall.shThe script will:
- Stop and disable the service
- Remove configuration files
- Clean up cache and logs
- Remove system user and group
- Optionally create backups
The API returns appropriate status codes:
400: Invalid parameters/input404: Envelope not found500: Internal server error- Status codes from bundler.wvm.network are passed through
For detailed error handling information, see System Administration Guide.
ISC