smartproxy/readme.md

# @push.rocks/smartproxy

A robust and versatile proxy package designed to handle high workloads, offering features like SSL redirection, port proxying, WebSocket support, and customizable routing and authentication.

## Install

To install `@push.rocks/smartproxy`, run the following command in your project's root directory:

```bash
npm install @push.rocks/smartproxy --save
```

This will add `@push.rocks/smartproxy` to your project's dependencies.

## Usage

`@push.rocks/smartproxy` is a comprehensive package that provides advanced functionalities for handling proxy tasks efficiently, including SSL redirection, port proxying, WebSocket support, and dynamic routing with authentication capabilities. Here is an extensive guide on how to utilize these features effectively, ensuring robust and secure proxy operations.

### Initial Setup

Before exploring the advanced features of `smartproxy`, you need to set up a basic proxy server. This setup serves as the foundation for incorporating additional functionalities later on:

```typescript
import { NetworkProxy } from '@push.rocks/smartproxy';

// Create an instance of NetworkProxy with the desired configuration
const myNetworkProxy = new NetworkProxy({ port: 443 });

// Define reverse proxy configurations for the domains you wish to proxy
const proxyConfigs = [
  {
    destinationIp: '127.0.0.1',
    destinationPort: '3000',
    hostName: 'example.com',
    privateKey: `-----BEGIN PRIVATE KEY-----
PRIVATE_KEY_CONTENT
-----END PRIVATE KEY-----`,
    publicKey: `-----BEGIN CERTIFICATE-----
CERTIFICATE_CONTENT
-----END CERTIFICATE-----`,
  },
  // Additional configurations can be added here
];

// Start the network proxy to enable forwarding
await myNetworkProxy.start();

// Apply the configurations you defined earlier
await myNetworkProxy.updateProxyConfigs(proxyConfigs);

// Optionally, you can set default headers to be included in all responses
await myNetworkProxy.addDefaultHeaders({
  'X-Powered-By': 'smartproxy',
});
```

### Configuring SSL Redirection

A critical feature of modern proxy servers is the ability to redirect HTTP traffic to secure HTTPS endpoints. The `SslRedirect` class in `smartproxy` simplifies this process by automatically redirecting requests from HTTP port 80 to HTTPS:

```typescript
import { SslRedirect } from '@push.rocks/smartproxy';

// Create an SslRedirect instance to listen on port 80
const mySslRedirect = new SslRedirect(80);

// Start the redirect to enforce HTTPS
await mySslRedirect.start();

// To stop HTTP redirection, use the following command:
await mySslRedirect.stop();
```

### Managing Port Proxying

Port proxying is essential for forwarding traffic from one port to another, an important feature for services that require dynamic port changes without downtime. Smartproxy's `PortProxy` class efficiently handles these scenarios:

```typescript
import { PortProxy } from '@push.rocks/smartproxy';

// Set up a PortProxy to forward traffic from port 5000 to 3000
const myPortProxy = new PortProxy(5000, 3000);

// Initiate the port proxy
await myPortProxy.start();

// To halt the port proxy, execute:
await myPortProxy.stop();
```

For more intricate setups—such as forwarding based on specific domain rules or IP allowances—smartproxy allows detailed configurations:

```typescript
import { PortProxy } from '@push.rocks/smartproxy';

// Configure complex port proxy rules
const advancedPortProxy = new PortProxy({
  fromPort: 6000,
  toPort: 3000,
  domains: [
    {
      domain: 'api.example.com',
      allowedIPs: ['192.168.0.*', '127.0.0.1'],
      targetIP: '192.168.1.100'
    }
    // Additional domain rules can be added as needed
  ],
  sniEnabled: true,  // Server Name Indication (SNI) support
  defaultAllowedIPs: ['*'],
});

// Activate the proxy with conditional rules
await advancedPortProxy.start();
```

### WebSocket Handling

With real-time applications becoming more prevalent, effective WebSocket handling is crucial in a proxy server. Smartproxy natively incorporates WebSocket support to manage WebSocket traffic securely and efficiently:

```typescript
import { NetworkProxy } from '@push.rocks/smartproxy';

// Create a NetworkProxy instance for WebSocket traffic
const wsNetworkProxy = new NetworkProxy({ port: 443 });

// Define proxy configurations targeted for WebSocket traffic
const websocketConfig = [
  {
    destinationIp: '127.0.0.1',
    destinationPort: '8080',
    hostName: 'socket.example.com',
    // Include SSL details if necessary
  }
];

// Start the proxy and apply WebSocket settings
await wsNetworkProxy.start();
await wsNetworkProxy.updateProxyConfigs(websocketConfig);

// Set heartbeat intervals to maintain WebSocket connections
wsNetworkProxy.heartbeatInterval = setInterval(() => {
  // Logic for connection health checks
}, 60000); // every minute

// Capture and handle server errors for resiliency
wsNetworkProxy.httpsServer.on('error', (error) => console.log('Server Error:', error));
```

### Advanced Routing and Custom Features

Smartproxy shines with its dynamic routing capabilities, allowing for custom and advanced request routing based on the request's destination. This enables extensive flexibility, such as directing API requests or facilitating intricate B2B integrations:

```typescript
import { NetworkProxy } from '@push.rocks/smartproxy';

// Instantiate a proxy with dynamic routing
const routeProxy = new NetworkProxy({ port: 8443 });

routeProxy.router.setNewProxyConfigs([
  {
    destinationIp: '192.168.1.150',
    destinationPort: '80',
    hostName: 'dynamic.example.com',
    authentication: {
      type: 'Basic',
      user: 'admin',
      pass: 'password123'
    }
  }
]);

// Activate the routing proxy
await routeProxy.start();
```

For those who require granular traffic control, integrating tools like `iptables` offers additional power over network management:

```typescript
import { IPTablesProxy } from '@push.rocks/smartproxy';

// Set up IPTables for sophisticated network traffic management
const iptablesProxy = new IPTablesProxy({
  fromPort: 8081,
  toPort: 8080,
  deleteOnExit: true // Clean up rules when the server shuts down
});

// Enable routing through IPTables
await iptablesProxy.start();
```

### Integrating SSL and HTTP/HTTPS Credentials

Handling sensitive data like SSL keys and certificates securely is crucial in proxy configurations:

```typescript
import { loadDefaultCertificates } from '@push.rocks/smartproxy';

try {
  const { privateKey, publicKey } = loadDefaultCertificates(); // Adjust path if necessary
  console.log('SSL certificates loaded successfully.');
  // Use these credentials in your configurations
} catch (error) {
  console.error('Error loading certificates:', error);
}
```

### Testing and Validation

Smartproxy supports extensive testing to ensure your proxy configurations operate as expected. Leveraging `tap` alongside TypeScript testing frameworks supports quality assurance:

```typescript
import { expect, tap } from '@push.rocks/tapbundle';
import { NetworkProxy } from '@push.rocks/smartproxy';

tap.test('Check proxied request returns status 200', async () => {
  // Testing logic
});

tap.start();
```

### Conclusion

`@push.rocks/smartproxy` is designed for both simple and complex proxying demands, offering tools for high-performance and secure proxy management across diverse environments. Its efficient configurations are capable of supporting SSL redirection, WebSocket traffic, dynamic routing, and other advanced functionalities, making it indispensable for developers seeking robust and adaptable proxy solutions. By integrating these capabilities with ease of use, `smartproxy` stands out as an essential tool in modern software architecture.

## 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. 

**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.