push.rocks/smartproxy
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update

Browse Source
This commit is contained in:
Philipp Kunz
2025-05-10 15:09:58 +00:00
parent ffc8b22533
commit f85698c06a
5 changed files with 1849 additions and 206 deletions
Download Patch File Download Diff File Expand all files Collapse all files

258
readme.md
View File

@ -105,63 +105,86 @@ Install via npm:
npm install @push.rocks/smartproxy
```
## Quick Start with SmartProxy v14.0.0
## Quick Start with SmartProxy
SmartProxy v14.0.0 introduces a new unified route-based configuration system that makes configuring proxies more flexible and intuitive.
SmartProxy v16.0.0 continues the evolution of the unified route-based configuration system making your proxy setup more flexible and intuitive with improved helper functions.
```typescript
import {
SmartProxy,
createHttpRoute,
createHttpsRoute,
createPassthroughRoute,
createHttpToHttpsRedirect
import {
SmartProxy,
createHttpRoute,
createHttpsTerminateRoute,
createHttpsPassthroughRoute,
createHttpToHttpsRedirect,
createCompleteHttpsServer,
createLoadBalancerRoute,
createStaticFileRoute,
createApiRoute,
createWebSocketRoute,
createSecurityConfig
} from '@push.rocks/smartproxy';
// Create a new SmartProxy instance with route-based configuration
const proxy = new SmartProxy({
// Define all your routing rules in one array
// Define all your routing rules in a single array
routes: [
// Basic HTTP route - forward traffic from port 80 to internal service
createHttpRoute({
ports: 80,
domains: 'api.example.com',
target: { host: 'localhost', port: 3000 }
}),
createHttpRoute('api.example.com', { host: 'localhost', port: 3000 }),
// HTTPS route with TLS termination and automatic certificates
createHttpsRoute({
ports: 443,
domains: 'secure.example.com',
target: { host: 'localhost', port: 8080 },
createHttpsTerminateRoute('secure.example.com', { host: 'localhost', port: 8080 }, {
certificate: 'auto' // Use Let's Encrypt
}),
// HTTPS passthrough for legacy systems
createPassthroughRoute({
ports: 443,
domains: 'legacy.example.com',
target: { host: '192.168.1.10', port: 443 }
createHttpsPassthroughRoute('legacy.example.com', { host: '192.168.1.10', port: 443 }),
// Redirect HTTP to HTTPS for all domains and subdomains
createHttpToHttpsRedirect(['example.com', '*.example.com']),
// Complete HTTPS server (creates both HTTPS route and HTTP redirect)
...createCompleteHttpsServer('complete.example.com', { host: 'localhost', port: 3000 }, {
certificate: 'auto'
}),
// Redirect HTTP to HTTPS
createHttpToHttpsRedirect({
domains: ['example.com', '*.example.com']
}),
// Complex load balancer setup with security controls
createLoadBalancerRoute({
domains: ['app.example.com'],
targets: ['192.168.1.10', '192.168.1.11', '192.168.1.12'],
targetPort: 8080,
tlsMode: 'terminate',
// API route with CORS headers
createApiRoute('api.service.com', '/v1', { host: 'api-backend', port: 8081 }, {
useTls: true,
certificate: 'auto',
security: {
allowedIps: ['10.0.0.*', '192.168.1.*'],
blockedIps: ['1.2.3.4'],
maxConnections: 1000
addCorsHeaders: true
}),
// WebSocket route for real-time communication
createWebSocketRoute('ws.example.com', '/socket', { host: 'socket-server', port: 8082 }, {
useTls: true,
certificate: 'auto',
pingInterval: 30000
}),
// Static file server for web assets
createStaticFileRoute('static.example.com', '/var/www/html', {
serveOnHttps: true,
certificate: 'auto',
indexFiles: ['index.html', 'index.htm', 'default.html']
}),
// Load balancer with multiple backend servers
createLoadBalancerRoute(
'app.example.com',
['192.168.1.10', '192.168.1.11', '192.168.1.12'],
8080,
{
tls: {
mode: 'terminate',
certificate: 'auto'
},
security: createSecurityConfig({
allowedIps: ['10.0.0.*', '192.168.1.*'],
blockedIps: ['1.2.3.4'],
maxConnections: 1000
})
}
})
)
],
// Global settings that apply to all routes
@ -189,9 +212,7 @@ await proxy.start();
// Dynamically add new routes later
await proxy.addRoutes([
createHttpsRoute({
domains: 'new-domain.com',
target: { host: 'localhost', port: 9000 },
createHttpsTerminateRoute('new-domain.com', { host: 'localhost', port: 9000 }, {
certificate: 'auto'
})
]);
@ -445,37 +466,33 @@ const route = {
name: 'Web Server'
};
// Use the helper function:
const route = createHttpRoute({
domains: 'example.com',
target: { host: 'localhost', port: 8080 },
// Use the helper function for cleaner syntax:
const route = createHttpRoute('example.com', { host: 'localhost', port: 8080 }, {
name: 'Web Server'
});
```
Available helper functions:
- `createRoute()` - Basic function to create any route configuration
- `createHttpRoute()` - Create an HTTP forwarding route
- `createHttpsRoute()` - Create an HTTPS route with TLS termination
- `createPassthroughRoute()` - Create an HTTPS passthrough route
- `createRedirectRoute()` - Create a generic redirect route
- `createHttpsTerminateRoute()` - Create an HTTPS route with TLS termination
- `createHttpsPassthroughRoute()` - Create an HTTPS passthrough route
- `createHttpToHttpsRedirect()` - Create an HTTP to HTTPS redirect
- `createBlockRoute()` - Create a route to block specific traffic
- `createLoadBalancerRoute()` - Create a route for load balancing
- `createHttpsServer()` - Create a complete HTTPS server setup with HTTP redirect
- `createPortRange()` - Helper to create port range configurations from various formats
- `createSecurityConfig()` - Helper to create security configuration objects
- `createCompleteHttpsServer()` - Create a complete HTTPS server setup with HTTP redirect
- `createLoadBalancerRoute()` - Create a route for load balancing across multiple backends
- `createStaticFileRoute()` - Create a route for serving static files
- `createTestRoute()` - Create a test route for debugging and testing purposes
- `createApiRoute()` - Create an API route with path matching and CORS support
- `createWebSocketRoute()` - Create a route for WebSocket connections
- `createPortRange()` - Helper to create port range configurations
- `createSecurityConfig()` - Helper to create security configuration objects
- `createBlockRoute()` - Create a route to block specific traffic
- `createTestRoute()` - Create a test route for debugging and testing
## What You Can Do with SmartProxy
1. **Route-Based Traffic Management**
```typescript
// Route requests for different domains to different backend servers
createHttpsRoute({
domains: 'api.example.com',
target: { host: 'api-server', port: 3000 },
createHttpsTerminateRoute('api.example.com', { host: 'api-server', port: 3000 }, {
certificate: 'auto'
})
```
@ -483,9 +500,7 @@ Available helper functions:
2. **Automatic SSL with Let's Encrypt**
```typescript
// Get and automatically renew certificates
createHttpsRoute({
domains: 'secure.example.com',
target: { host: 'localhost', port: 8080 },
createHttpsTerminateRoute('secure.example.com', { host: 'localhost', port: 8080 }, {
certificate: 'auto'
})
```
@ -493,21 +508,23 @@ Available helper functions:
3. **Load Balancing**
```typescript
// Distribute traffic across multiple backend servers
createLoadBalancerRoute({
domains: 'app.example.com',
targets: ['10.0.0.1', '10.0.0.2', '10.0.0.3'],
targetPort: 8080,
tlsMode: 'terminate',
certificate: 'auto'
})
createLoadBalancerRoute(
'app.example.com',
['10.0.0.1', '10.0.0.2', '10.0.0.3'],
8080,
{
tls: {
mode: 'terminate',
certificate: 'auto'
}
}
)
```
4. **Security Controls**
```typescript
// Restrict access based on IP addresses
createHttpsRoute({
domains: 'admin.example.com',
target: { host: 'localhost', port: 8080 },
createHttpsTerminateRoute('admin.example.com', { host: 'localhost', port: 8080 }, {
certificate: 'auto',
security: {
allowedIps: ['10.0.0.*', '192.168.1.*'],
@ -519,19 +536,14 @@ Available helper functions:
5. **Wildcard Domains**
```typescript
// Handle all subdomains with one config
createPassthroughRoute({
domains: ['example.com', '*.example.com'],
target: { host: 'backend-server', port: 443 }
})
createHttpsPassthroughRoute(['example.com', '*.example.com'], { host: 'backend-server', port: 443 })
```
6. **Path-Based Routing**
```typescript
// Route based on URL path
createHttpsRoute({
domains: 'example.com',
path: '/api/*',
target: { host: 'api-server', port: 3000 },
createApiRoute('example.com', '/api', { host: 'api-server', port: 3000 }, {
useTls: true,
certificate: 'auto'
})
```
@ -539,8 +551,7 @@ Available helper functions:
7. **Block Malicious Traffic**
```typescript
// Block traffic from specific IPs
createBlockRoute({
ports: [80, 443],
createBlockRoute([80, 443], {
clientIp: ['1.2.3.*', '5.6.7.*'],
priority: 1000 // High priority to ensure blocking
})
@ -611,19 +622,20 @@ const redirect = new SslRedirect(80);
await redirect.start();
```
## Migration from v13.x to v14.0.0
## Migration to v16.0.0
Version 14.0.0 introduces a breaking change with the new route-based configuration system:
Version 16.0.0 completes the migration to a fully unified route-based configuration system with improved helper functions:
### Key Changes
1. **Configuration Structure**: The configuration now uses the match/action pattern instead of the old domain-based and port-based approach
2. **SmartProxy Options**: Now takes an array of route configurations instead of `domainConfigs` and port ranges
3. **Helper Functions**: New helper functions have been introduced to simplify configuration
1. **Pure Route-Based API**: The configuration now exclusively uses the match/action pattern with no legacy interfaces
2. **Improved Helper Functions**: Enhanced helper functions with cleaner parameter signatures
3. **Removed Legacy Support**: Legacy domain-based APIs have been completely removed
4. **More Route Pattern Helpers**: Additional helper functions for common routing patterns
### Migration Example
**v13.x Configuration**:
**Legacy Configuration (pre-v14)**:
```typescript
import { SmartProxy, createDomainConfig, httpOnly, tlsTerminateToHttp } from '@push.rocks/smartproxy';
@ -639,29 +651,48 @@ const proxy = new SmartProxy({
});
```
**v14.0.0 Configuration**:
**Current Configuration (v16.0.0)**:
```typescript
import { SmartProxy, createHttpsRoute } from '@push.rocks/smartproxy';
import { SmartProxy, createHttpsTerminateRoute } from '@push.rocks/smartproxy';
const proxy = new SmartProxy({
routes: [
createHttpsRoute({
ports: 443,
domains: 'example.com',
target: { host: 'localhost', port: 8080 },
createHttpsTerminateRoute('example.com', { host: 'localhost', port: 8080 }, {
certificate: 'auto'
})
]
],
acme: {
enabled: true,
useProduction: true
}
});
```
### Migration Steps
### Migration from v14.x/v15.x to v16.0.0
1. Replace `domainConfigs` with an array of route configurations using `routes`
2. Convert each domain configuration to use the new helper functions
3. Update any code that uses `updateDomainConfigs()` to use `addRoutes()` or `updateRoutes()`
4. For port-only configurations, create route configurations with port matching only
5. For SNI-based routing, SNI is now automatically enabled when needed
If you're already using route-based configuration, update your helper function calls:
```typescript
// Old v14.x/v15.x style:
createHttpsRoute({
domains: 'example.com',
target: { host: 'localhost', port: 8080 },
certificate: 'auto'
})
// New v16.0.0 style:
createHttpsTerminateRoute('example.com', { host: 'localhost', port: 8080 }, {
certificate: 'auto'
})
```
### Complete Migration Steps
1. Replace any remaining `domainConfigs` with route-based configuration using the `routes` array
2. Update helper function calls to use the newer parameter format (domain first, target second, options third)
3. Use the new specific helper functions (e.g., `createHttpsTerminateRoute` instead of `createHttpsRoute`)
4. Update any code that uses `updateDomainConfigs()` to use `addRoutes()` or `updateRoutes()`
5. For port-only configurations, create route configurations with port matching only
## Architecture & Flow Diagrams
@ -810,33 +841,26 @@ The SmartProxy component with route-based configuration offers a clean, unified
Create a flexible API gateway to route traffic to different microservices based on domain and path:
```typescript
import { SmartProxy, createHttpsRoute } from '@push.rocks/smartproxy';
import { SmartProxy, createApiRoute, createHttpsTerminateRoute } from '@push.rocks/smartproxy';
const apiGateway = new SmartProxy({
routes: [
// Users API
createHttpsRoute({
ports: 443,
domains: 'api.example.com',
path: '/users/*',
target: { host: 'users-service', port: 3000 },
certificate: 'auto'
createApiRoute('api.example.com', '/users', { host: 'users-service', port: 3000 }, {
useTls: true,
certificate: 'auto',
addCorsHeaders: true
}),
// Products API
createHttpsRoute({
ports: 443,
domains: 'api.example.com',
path: '/products/*',
target: { host: 'products-service', port: 3001 },
certificate: 'auto'
createApiRoute('api.example.com', '/products', { host: 'products-service', port: 3001 }, {
useTls: true,
certificate: 'auto',
addCorsHeaders: true
}),
// Admin dashboard with extra security
createHttpsRoute({
ports: 443,
domains: 'admin.example.com',
target: { host: 'admin-dashboard', port: 8080 },
createHttpsTerminateRoute('admin.example.com', { host: 'admin-dashboard', port: 8080 }, {
certificate: 'auto',
security: {
allowedIps: ['10.0.0.*', '192.168.1.*'] // Only allow internal network