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

feat(docs): update README with installation, improved feature table, expanded quick-start, ACME/email example, API options interface, and clarified licensing/trademark text

Browse Source
This commit is contained in:
Jürgen Kunz
2026-01-30 09:22:41 +00:00
parent 90e8f92e86
commit 9b1adb1d7a
3 changed files with 246 additions and 173 deletions
Download Patch File Download Diff File Expand all files Collapse all files

407
readme.md
View File

@@ -2,32 +2,40 @@
**The Swiss Army Knife of Node.js Proxies** - A unified, high-performance proxy toolkit that handles everything from simple HTTP forwarding to complex enterprise routing scenarios.
## 📦 Installation
```bash
npm install @push.rocks/smartproxy
# or
pnpm add @push.rocks/smartproxy
```
## Issue Reporting and Security
For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
## 🎯 What is SmartProxy?
SmartProxy is a modern, production-ready proxy solution that brings order to the chaos of traffic management. Whether you're building microservices, deploying edge infrastructure, or need a battle-tested reverse proxy, SmartProxy has you covered.
### ⚡ Key Features
- **🔀 Unified Route-Based Configuration** - Clean match/action patterns for intuitive traffic routing
- **🔒 Automatic SSL/TLS with Let's Encrypt** - Zero-config HTTPS with automatic certificate provisioning
- **🎯 Flexible Matching Patterns** - Route by port, domain, path, client IP, TLS version, or custom logic
- **🚄 High-Performance Forwarding** - Choose between user-space or kernel-level (NFTables) forwarding
- **⚖️ Built-in Load Balancing** - Distribute traffic across multiple backends with health checks
- **🛡️ Enterprise Security** - IP filtering, rate limiting, authentication, and connection limits
- **🔌 WebSocket Support** - First-class WebSocket proxying with ping/pong management
- **🎮 Custom Socket Handlers** - Implement any protocol with full socket control
- **📊 Dynamic Port Management** - Add/remove ports at runtime without restarts
- **🔧 Protocol Detection** - Smart protocol detection for mixed-mode operation
## 📦 Installation
```bash
npm install @push.rocks/smartproxy
```
| Feature | Description |
|---------|-------------|
| 🔀 **Unified Route-Based Config** | Clean match/action patterns for intuitive traffic routing |
| 🔒 **Automatic SSL/TLS** | Zero-config HTTPS with Let's Encrypt ACME integration |
| 🎯 **Flexible Matching** | Route by port, domain, path, client IP, TLS version, or custom logic |
| 🚄 **High-Performance** | Choose between user-space or kernel-level (NFTables) forwarding |
| ⚖️ **Load Balancing** | Distribute traffic with health checks and multiple algorithms |
| 🛡️ **Enterprise Security** | IP filtering, rate limiting, authentication, connection limits |
| 🔌 **WebSocket Support** | First-class WebSocket proxying with ping/pong keep-alive |
| 🎮 **Custom Protocols** | Socket handlers for implementing any protocol |
| 📊 **Live Metrics** | Real-time throughput, connection counts, and performance data |
| 🔧 **Dynamic Management** | Add/remove ports and routes at runtime without restarts |
## 🚀 Quick Start
Let's get you up and running in 30 seconds:
Get up and running in 30 seconds:
```typescript
import { SmartProxy, createCompleteHttpsServer } from '@push.rocks/smartproxy';
@@ -35,14 +43,14 @@ import { SmartProxy, createCompleteHttpsServer } from '@push.rocks/smartproxy';
// Create a proxy with automatic HTTPS
const proxy = new SmartProxy({
acme: {
email: 'ssl@example.com', // Your email for Let's Encrypt
useProduction: true // Use Let's Encrypt production servers
email: 'ssl@yourdomain.com', // Your email for Let's Encrypt
useProduction: true // Use production servers
},
routes: [
// Complete HTTPS setup with one line
...createCompleteHttpsServer('app.example.com', {
host: 'localhost',
port: 3000
// Complete HTTPS setup in one line! ✨
...createCompleteHttpsServer('app.example.com', {
host: 'localhost',
port: 3000
}, {
certificate: 'auto' // Magic! 🎩
})
@@ -57,10 +65,11 @@ console.log('🚀 Proxy running with automatic HTTPS!');
### 🏗️ Route-Based Architecture
SmartProxy uses a powerful match/action pattern that makes routing predictable and maintainable:
SmartProxy uses a powerful **match/action** pattern that makes routing predictable and maintainable:
```typescript
{
name: 'api-route',
match: {
ports: 443,
domains: 'api.example.com',
@@ -74,22 +83,31 @@ SmartProxy uses a powerful match/action pattern that makes routing predictable a
}
```
Every route has:
- **Match criteria** - What traffic to capture
- **Action** - What to do with it
- **Security** (optional) - Access controls and limits
- **Metadata** (optional) - Name, priority, tags
Every route consists of:
- **Match** - What traffic to capture (ports, domains, paths, IPs)
- **Action** - What to do with it (forward, redirect, block, socket-handler)
- **Security** (optional) - Access controls, rate limits, authentication
- **Name/Priority** (optional) - For identification and ordering
### 🔄 TLS Modes
SmartProxy supports three TLS handling modes:
| Mode | Description | Use Case |
|------|-------------|----------|
| `passthrough` | Forward encrypted traffic as-is | Backend handles TLS |
| `terminate` | Decrypt at proxy, forward plain | Standard reverse proxy |
| `terminate-and-reencrypt` | Decrypt, then re-encrypt to backend | Zero-trust environments |
## 💡 Common Use Cases
### 🌐 Simple HTTP to HTTPS Redirect
### 🌐 HTTP to HTTPS Redirect
```typescript
import { SmartProxy, createHttpToHttpsRedirect } from '@push.rocks/smartproxy';
const proxy = new SmartProxy({
routes: [
// Redirect all HTTP traffic to HTTPS
createHttpToHttpsRedirect(['example.com', '*.example.com'])
]
});
@@ -133,7 +151,8 @@ const route = createWebSocketRoute(
path: '/socket',
useTls: true,
certificate: 'auto',
pingInterval: 30000 // Keep connections alive
pingInterval: 30000, // Keep connections alive
pingTimeout: 10000
}
);
```
@@ -154,51 +173,64 @@ let route = createApiGatewayRoute(
}
);
// Add rate limiting
// Add rate limiting - 100 requests per minute per IP
route = addRateLimiting(route, {
maxRequests: 100,
window: 60, // seconds
window: 60,
keyBy: 'ip'
});
```
### 🎮 Custom Protocol Handler
SmartProxy lets you implement any protocol with full socket control:
```typescript
import { createSocketHandlerRoute, SocketHandlers } from '@push.rocks/smartproxy';
// Pre-built handlers
// Use pre-built handlers
const echoRoute = createSocketHandlerRoute(
'echo.example.com',
7777,
'echo.example.com',
7777,
SocketHandlers.echo
);
// Custom handler
// Or create your own custom protocol
const customRoute = createSocketHandlerRoute(
'custom.example.com',
9999,
async (socket, context) => {
console.log(`Connection from ${context.clientIp}`);
socket.write('Welcome to my custom protocol!\n');
socket.on('data', (data) => {
const command = data.toString().trim();
if (command === 'HELLO') {
socket.write('World!\n');
} else if (command === 'EXIT') {
socket.end('Goodbye!\n');
switch (command) {
case 'PING': socket.write('PONG\n'); break;
case 'TIME': socket.write(`${new Date().toISOString()}\n`); break;
case 'QUIT': socket.end('Goodbye!\n'); break;
default: socket.write(`Unknown: ${command}\n`);
}
});
}
);
```
**Pre-built Socket Handlers:**
| Handler | Description |
|---------|-------------|
| `SocketHandlers.echo` | Echo server - returns everything sent |
| `SocketHandlers.proxy(host, port)` | TCP proxy to another server |
| `SocketHandlers.lineProtocol(handler)` | Line-based text protocol |
| `SocketHandlers.httpResponse(code, body)` | Simple HTTP response |
| `SocketHandlers.httpRedirect(url, code)` | HTTP redirect with templates |
| `SocketHandlers.httpServer(handler)` | Full HTTP request/response handling |
| `SocketHandlers.block(message)` | Block with optional message |
### ⚡ High-Performance NFTables Forwarding
For ultra-low latency, use kernel-level forwarding (Linux only, requires root):
For ultra-low latency on Linux, use kernel-level forwarding (requires root):
```typescript
import { createNfTablesTerminateRoute } from '@push.rocks/smartproxy';
@@ -209,8 +241,8 @@ const route = createNfTablesTerminateRoute(
{
ports: 443,
certificate: 'auto',
preserveSourceIP: true,
maxRate: '1gbps'
preserveSourceIP: true, // Backend sees real client IP
maxRate: '1gbps' // QoS rate limiting
}
);
```
@@ -223,21 +255,18 @@ Route traffic based on runtime conditions:
```typescript
{
name: 'business-hours-only',
match: {
ports: 443,
customMatcher: async (context) => {
// Route based on time of day
const hour = new Date().getHours();
return hour >= 9 && hour < 17; // Business hours only
}
domains: 'internal.example.com'
},
action: {
type: 'forward',
targets: [{
host: (context) => {
// Dynamic host selection
return context.path.startsWith('/premium')
? 'premium-backend'
// Dynamic host selection based on path
return context.path?.startsWith('/premium')
? 'premium-backend'
: 'standard-backend';
},
port: 8080
@@ -248,30 +277,29 @@ Route traffic based on runtime conditions:
### 🔒 Security Controls
Comprehensive security options per route:
Comprehensive per-route security options:
```typescript
{
name: 'secure-api',
match: { ports: 443, domains: 'api.example.com' },
action: {
type: 'forward',
targets: [{ host: 'api-backend', port: 8080 }]
},
security: {
// IP-based access control
ipAllowList: ['10.0.0.0/8', '192.168.*'],
ipBlockList: ['192.168.1.100'],
// Connection limits
maxConnections: 1000,
maxConnectionsPerIp: 10,
// Rate limiting
rateLimit: {
maxRequests: 100,
windowMs: 60000
},
// Authentication
authentication: {
type: 'jwt',
secret: process.env.JWT_SECRET,
algorithms: ['HS256']
}
}
}
@@ -282,7 +310,7 @@ Comprehensive security options per route:
Control your proxy without restarts:
```typescript
// Add/remove ports dynamically
// Dynamic port management
await proxy.addListeningPort(8443);
await proxy.removeListeningPort(8080);
@@ -291,25 +319,31 @@ await proxy.updateRoutes([...newRoutes]);
// Monitor status
const status = proxy.getStatus();
console.log(`Active connections: ${status.activeConnections}`);
// Get detailed metrics
const metrics = proxy.getMetrics();
console.log(`Throughput: ${metrics.throughput.bytesPerSecond} bytes/sec`);
// Certificate management
await proxy.renewCertificate('example.com');
const certInfo = proxy.getCertificateInfo('example.com');
console.log(`Certificate expires: ${certInfo.expiresAt}`);
```
### 🔄 Header Manipulation
Transform requests and responses:
Transform requests and responses with template variables:
```typescript
{
action: {
type: 'forward',
targets: [{ host: 'backend', port: 8080 }],
headers: {
request: {
'X-Real-IP': '{clientIp}', // Template variables
'X-Real-IP': '{clientIp}',
'X-Request-ID': '{uuid}',
'X-Custom': 'value'
'X-Forwarded-Proto': 'https'
},
response: {
'X-Powered-By': 'SmartProxy',
@@ -327,13 +361,15 @@ SmartProxy is built with a modular, extensible architecture:
```
SmartProxy
├── 📋 Route Manager # Route matching and prioritization
├── 🔌 Port Manager # Dynamic port lifecycle
├── 🔒 Certificate Manager # ACME/Let's Encrypt automation
├── 🚦 Connection Manager # Connection pooling and limits
├── 📊 Metrics Collector # Performance monitoring
├── 🛡️ Security Manager # Access control and rate limiting
└── 🔧 Protocol Detectors # Smart protocol identification
├── 📋 RouteManager # Route matching and prioritization
├── 🔌 PortManager # Dynamic port lifecycle management
├── 🔒 SmartCertManager # ACME/Let's Encrypt automation
├── 🚦 ConnectionManager # Connection pooling and tracking
├── 📊 MetricsCollector # Real-time performance monitoring
├── 🛡️ SecurityManager # Access control and rate limiting
├── 🔧 ProtocolDetector # Smart HTTP/TLS/WebSocket detection
├── ⚡ NFTablesManager # Kernel-level forwarding (Linux)
└── 🌐 HttpProxyBridge # HTTP/HTTPS request handling
```
## 🎯 Route Configuration Reference
@@ -346,87 +382,115 @@ interface IRouteMatch {
domains?: string | string[]; // 'example.com', '*.example.com'
path?: string; // '/api/*', '/users/:id'
clientIp?: string | string[]; // '10.0.0.0/8', ['192.168.*']
protocol?: 'tcp' | 'udp' | 'http' | 'https' | 'ws' | 'wss';
tlsVersion?: string | string[]; // ['TLSv1.2', 'TLSv1.3']
customMatcher?: (context) => boolean; // Custom logic
}
```
### Action Types
| Type | Description |
|------|-------------|
| `forward` | Proxy to one or more backend targets |
| `redirect` | HTTP redirect with status code |
| `block` | Block the connection |
| `socket-handler` | Custom socket handling function |
### TLS Options
```typescript
interface IRouteAction {
type: 'forward' | 'redirect' | 'block' | 'socket-handler';
// For 'forward'
targets?: Array<{
host: string | string[] | ((context) => string);
port: number | ((context) => number);
}>;
// For 'redirect'
redirectUrl?: string; // With {domain}, {path}, {clientIp} templates
redirectCode?: number; // 301, 302, etc.
// For 'socket-handler'
socketHandler?: (socket, context) => void | Promise<void>;
// TLS options
tls?: {
mode: 'terminate' | 'passthrough' | 'terminate-and-reencrypt';
certificate: 'auto' | { key: string; cert: string };
};
// WebSocket options
websocket?: {
enabled: boolean;
pingInterval?: number;
pingTimeout?: number;
interface IRouteTls {
mode: 'passthrough' | 'terminate' | 'terminate-and-reencrypt';
certificate: 'auto' | { key: string; cert: string };
// For terminate-and-reencrypt:
reencrypt?: {
host: string;
port: number;
ca?: string; // Custom CA for backend
};
}
```
## 🛠️ Helper Functions Reference
All helpers are fully typed and documented:
```typescript
import {
// HTTP/HTTPS
createHttpRoute,
createHttpsTerminateRoute,
createHttpsPassthroughRoute,
createHttpToHttpsRedirect,
createCompleteHttpsServer,
// Load Balancing
createLoadBalancerRoute,
createSmartLoadBalancer,
// API & WebSocket
createApiRoute,
createApiGatewayRoute,
createWebSocketRoute,
// Custom Protocols
createSocketHandlerRoute,
SocketHandlers,
// NFTables (Linux)
createNfTablesRoute,
createNfTablesTerminateRoute,
createCompleteNfTablesHttpsServer,
// Dynamic Routing
createPortMappingRoute,
createOffsetPortMappingRoute,
createDynamicRoute,
// Security Modifiers
addRateLimiting,
addBasicAuth,
addJwtAuth
} from '@push.rocks/smartproxy';
```
## 🐛 Troubleshooting
### Certificate Issues
- ✅ Ensure domain points to your server
- ✅ Port 80 must be accessible for ACME challenges
- ✅ Check DNS propagation with `nslookup`
- ✅ Verify email in ACME configuration
- ✅ Ensure domain DNS points to your server
- ✅ Port 80 must be accessible for ACME HTTP-01 challenges
- ✅ Check DNS propagation with `dig` or `nslookup`
- ✅ Verify the email in ACME configuration is valid
### Connection Problems
- ✅ Check route priorities (higher = matched first)
- ✅ Verify security rules aren't blocking
- ✅ Test with `curl -v` for detailed output
- ✅ Enable debug mode for verbose logging
- ✅ Check route priorities (higher number = matched first)
- ✅ Verify security rules aren't blocking legitimate traffic
- ✅ Test with `curl -v` for detailed connection output
- ✅ Enable debug logging for verbose output
### Performance Tuning
- ✅ Use NFTables for high-traffic routes
- ✅ Enable connection pooling
- ✅ Adjust keep-alive settings
- ✅ Monitor with built-in metrics
- ✅ Use NFTables forwarding for high-traffic routes (Linux only)
- ✅ Enable connection keep-alive where appropriate
- ✅ Monitor metrics to identify bottlenecks
- ✅ Adjust `maxConnections` based on your server resources
### Debug Mode
```typescript
const proxy = new SmartProxy({
debug: true, // Enable verbose logging
enableDetailedLogging: true, // Verbose connection logging
routes: [...]
});
```
## 🚀 Migration from v20.x to v21.x
No breaking changes! v21.x adds enhanced socket cleanup, improved connection tracking, and better process exit handling.
## 🏆 Best Practices
1. **📝 Use Helper Functions** - They provide sensible defaults and prevent errors
2. **🎯 Set Route Priorities** - More specific routes should have higher priority
3. **🔒 Always Enable Security** - Use IP filtering and rate limiting for public services
4. **📊 Monitor Performance** - Use metrics to identify bottlenecks
5. **🔄 Regular Certificate Checks** - Monitor expiration and renewal status
6. **🛑 Graceful Shutdown** - Always call `proxy.stop()` for clean shutdown
7. **🎮 Test Your Routes** - Use the route testing utilities before production
1. **📝 Use Helper Functions** - They provide sensible defaults and prevent common mistakes
2. **🎯 Set Route Priorities** - More specific routes should have higher priority values
3. **🔒 Enable Security** - Always use IP filtering and rate limiting for public services
4. **📊 Monitor Metrics** - Use the built-in metrics to identify issues early
5. **🔄 Certificate Monitoring** - Set up alerts for certificate expiration
6. **🛑 Graceful Shutdown** - Always call `proxy.stop()` for clean connection termination
7. **🔧 Test Routes** - Validate your route configurations before deploying to production
## 📖 API Documentation
@@ -434,74 +498,73 @@ No breaking changes! v21.x adds enhanced socket cleanup, improved connection tra
```typescript
class SmartProxy {
constructor(options: IRoutedSmartProxyOptions);
constructor(options: ISmartProxyOptions);
// Lifecycle
start(): Promise<void>;
stop(): Promise<void>;
// Route Management
updateRoutes(routes: IRouteConfig[]): Promise<void>;
addRoute(route: IRouteConfig): Promise<void>;
removeRoute(routeName: string): Promise<void>;
findMatchingRoute(context: Partial<IRouteContext>): IRouteConfig | null;
// Port Management
addListeningPort(port: number): Promise<void>;
removeListeningPort(port: number): Promise<void>;
getListeningPorts(): number[];
// Certificate Management
getCertificateInfo(domain: string): ICertificateInfo | null;
renewCertificate(domain: string): Promise<void>;
// Monitoring
getStatus(): IProxyStatus;
getMetrics(): IProxyMetrics;
getMetrics(): IMetrics;
// Certificate Management
getCertificateInfo(domain: string): ICertStatus | null;
}
```
### Helper Functions
All helper functions are fully typed and documented. Import them from the main package:
### Configuration Options
```typescript
import {
createHttpRoute,
createHttpsTerminateRoute,
createHttpsPassthroughRoute,
createHttpToHttpsRedirect,
createCompleteHttpsServer,
createLoadBalancerRoute,
createApiRoute,
createWebSocketRoute,
createSocketHandlerRoute,
createNfTablesRoute,
createPortMappingRoute,
createDynamicRoute,
createApiGatewayRoute,
addRateLimiting,
addBasicAuth,
addJwtAuth,
SocketHandlers
} from '@push.rocks/smartproxy';
interface ISmartProxyOptions {
routes: IRouteConfig[]; // Required: array of route configs
// ACME/Let's Encrypt
acme?: {
email: string; // Contact email
useProduction?: boolean; // Use production servers (default: false)
port?: number; // Challenge port (default: 80)
renewThresholdDays?: number; // Days before expiry to renew (default: 30)
};
// Defaults
defaults?: {
target?: { host: string; port: number };
security?: IRouteSecurity;
tls?: IRouteTls;
};
// Behavior
enableDetailedLogging?: boolean;
gracefulShutdownTimeout?: number; // ms to wait for connections to close
}
```
## License and Legal Information
This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.
This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
### Trademarks
This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.
This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
### Company Information
Task Venture Capital GmbH
Registered at District court Bremen HRB 35230 HB, Germany
Task Venture Capital GmbH
Registered at District Court Bremen HRB 35230 HB, Germany
For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
For any legal inquiries or further information, please contact us via email at hello@task.vc.
By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.
By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.