smartproxy/readme.md

@push.rocks/smartproxy 🚀

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.

🎯 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

npm install @push.rocks/smartproxy

🚀 Quick Start

Let's get you up and running in 30 seconds:

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
  },
  routes: [
    // Complete HTTPS setup with one line
    ...createCompleteHttpsServer('app.example.com', { 
      host: 'localhost', 
      port: 3000 
    }, {
      certificate: 'auto'  // Magic! 🎩
    })
  ]
});

await proxy.start();
console.log('🚀 Proxy running with automatic HTTPS!');

📚 Core Concepts

🏗️ Route-Based Architecture

SmartProxy uses a powerful match/action pattern that makes routing predictable and maintainable:

{
  match: {
    ports: 443,
    domains: 'api.example.com',
    path: '/v1/*'
  },
  action: {
    type: 'forward',
    targets: [{ host: 'backend', port: 8080 }],
    tls: { mode: 'terminate', certificate: 'auto' }
  }
}

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

💡 Common Use Cases

🌐 Simple HTTP to HTTPS Redirect

import { SmartProxy, createHttpToHttpsRedirect } from '@push.rocks/smartproxy';

const proxy = new SmartProxy({
  routes: [
    // Redirect all HTTP traffic to HTTPS
    createHttpToHttpsRedirect(['example.com', '*.example.com'])
  ]
});

⚖️ Load Balancer with Health Checks

import { createLoadBalancerRoute } from '@push.rocks/smartproxy';

const route = createLoadBalancerRoute(
  'app.example.com',
  [
    { host: 'server1.internal', port: 8080 },
    { host: 'server2.internal', port: 8080 },
    { host: 'server3.internal', port: 8080 }
  ],
  {
    tls: { mode: 'terminate', certificate: 'auto' },
    loadBalancing: {
      algorithm: 'round-robin',
      healthCheck: {
        path: '/health',
        interval: 30000,
        timeout: 5000
      }
    }
  }
);

🔌 WebSocket Proxy

import { createWebSocketRoute } from '@push.rocks/smartproxy';

const route = createWebSocketRoute(
  'ws.example.com',
  { host: 'websocket-server', port: 8080 },
  {
    path: '/socket',
    useTls: true,
    certificate: 'auto',
    pingInterval: 30000  // Keep connections alive
  }
);

🚦 API Gateway with Rate Limiting

import { createApiGatewayRoute, addRateLimiting } from '@push.rocks/smartproxy';

let route = createApiGatewayRoute(
  'api.example.com',
  '/api',
  { host: 'api-backend', port: 8080 },
  {
    useTls: true,
    certificate: 'auto',
    addCorsHeaders: true
  }
);

// Add rate limiting
route = addRateLimiting(route, {
  maxRequests: 100,
  window: 60,  // seconds
  keyBy: 'ip'
});

🎮 Custom Protocol Handler

import { createSocketHandlerRoute, SocketHandlers } from '@push.rocks/smartproxy';

// Pre-built handlers
const echoRoute = createSocketHandlerRoute(
  'echo.example.com', 
  7777, 
  SocketHandlers.echo
);

// Custom handler
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');
      }
    });
  }
);

⚡ High-Performance NFTables Forwarding

For ultra-low latency, use kernel-level forwarding (Linux only, requires root):

import { createNfTablesTerminateRoute } from '@push.rocks/smartproxy';

const route = createNfTablesTerminateRoute(
  'fast.example.com',
  { host: 'backend', port: 8080 },
  {
    ports: 443,
    certificate: 'auto',
    preserveSourceIP: true,
    maxRate: '1gbps'
  }
);

🔧 Advanced Features

🎯 Dynamic Routing

Route traffic based on runtime conditions:

{
  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
    }
  },
  action: {
    type: 'forward',
    targets: [{
      host: (context) => {
        // Dynamic host selection
        return context.path.startsWith('/premium') 
          ? 'premium-backend' 
          : 'standard-backend';
      },
      port: 8080
    }]
  }
}

🔒 Security Controls

Comprehensive security options per route:

{
  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']
    }
  }
}

📊 Runtime Management

Control your proxy without restarts:

// Add/remove ports dynamically
await proxy.addListeningPort(8443);
await proxy.removeListeningPort(8080);

// Update routes on the fly
await proxy.updateRoutes([...newRoutes]);

// Monitor status
const status = proxy.getStatus();
const metrics = proxy.getMetrics();

// Certificate management
await proxy.renewCertificate('example.com');
const certInfo = proxy.getCertificateInfo('example.com');

🔄 Header Manipulation

Transform requests and responses:

{
  action: {
    headers: {
      request: {
        'X-Real-IP': '{clientIp}',           // Template variables
        'X-Request-ID': '{uuid}',
        'X-Custom': 'value'
      },
      response: {
        'X-Powered-By': 'SmartProxy',
        'Strict-Transport-Security': 'max-age=31536000',
        'X-Frame-Options': 'DENY'
      }
    }
  }
}

🏛️ Architecture

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

🎯 Route Configuration Reference

Match Criteria

interface IRouteMatch {
  ports: number | number[] | string;      // 80, [80, 443], '8000-8999'
  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

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;
  };
}

🐛 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

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

Performance Tuning

• ✅ Use NFTables for high-traffic routes
• ✅ Enable connection pooling
• ✅ Adjust keep-alive settings
• ✅ Monitor with built-in metrics

Debug Mode

const proxy = new SmartProxy({
  debug: true,  // Enable verbose 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

📖 API Documentation

SmartProxy Class

class SmartProxy {
  constructor(options: IRoutedSmartProxyOptions);
  
  // 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;
}

Helper Functions

All helper functions are fully typed and documented. Import them from the main package:

import {
  createHttpRoute,
  createHttpsTerminateRoute,
  createHttpsPassthroughRoute,
  createHttpToHttpsRedirect,
  createCompleteHttpsServer,
  createLoadBalancerRoute,
  createApiRoute,
  createWebSocketRoute,
  createSocketHandlerRoute,
  createNfTablesRoute,
  createPortMappingRoute,
  createDynamicRoute,
  createApiGatewayRoute,
  addRateLimiting,
  addBasicAuth,
  addJwtAuth,
  SocketHandlers
} from '@push.rocks/smartproxy';

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 file within this repository.

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.

Company Information

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.

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.