smartproxy/readme.md

# @push.rocks/smartproxy

A proxy for handling high workloads of proxying.

## 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 and versatile package designed to handle complex and high-volume proxying tasks efficiently. It includes features such as SSL redirection, port proxying, WebSocket support, and customizable routing and authentication mechanisms. This guide will provide a detailed walkthrough of how to harness these capabilities effectively. 

### Initial Setup

Before diving into specific features, let's start by configuring and setting up our basic proxy server:

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

// Instantiate the NetworkProxy with desired options
const myNetworkProxy = new NetworkProxy({ port: 443 });

// Define reverse proxy configurations
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-----`,
  },
  // More configurations can be added here
];

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

// Apply proxy configurations
await myNetworkProxy.updateProxyConfigs(proxyConfigs);

// Optionally add default headers to all responses
await myNetworkProxy.addDefaultHeaders({
  'X-Powered-By': 'smartproxy',
});
```

### Configuring SSL Redirection

One essential capability of a robust proxy server is ensuring that all HTTP traffic is redirected to secure HTTPS endpoints. This can be effortlessly accomplished using the `SslRedirect` class within `smartproxy`. This class listens on port 80 (HTTP) and redirects all incoming requests to HTTPS:

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

// Instantiate the SslRedirect for listening on port 80
const mySslRedirect = new SslRedirect(80);

// Start listening and redirect HTTP traffic to HTTPS
await mySslRedirect.start();

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

### Handling Complex Networking with Port Proxy

Port proxying allows redirection of traffic from one port to another. This capability is crucial when dealing with services that need dynamic port forwarding, or when adapting to infrastructure changes without downtime. Smartproxy's `PortProxy` class handles this efficiently:

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

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

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

// To stop the port proxy mechanism:
await myPortProxy.stop();
```

Additionally, smartproxy's port proxying can support intricate scenarios where different forwarding rules are configured based on domain names or allowed IPs:

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

const myComplexPortProxy = new PortProxy({
  fromPort: 6000,
  toPort: 3000,
  domains: [
    {
      domain: 'api.example.com',
      allowedIPs: ['192.168.0.*', '127.0.0.1'],
      targetIP: '192.168.1.100'
    }
    // Define more domain-specific rules if needed
  ],
  sniEnabled: true,  // if SNI (Server Name Indication) is desired
  defaultAllowedIPs: ['*']);
});

// Start listening for complex routing requests
await myComplexPortProxy.start();
```

### WebSocket Support and Load Handling

With the advent of real-time applications, efficient WebSocket handling in proxies is crucial. Smartproxy integrates WebSocket support seamlessly, enabling it to proxy WebSocket traffic while maintaining security and performance:

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

const wsProxy = new NetworkProxy({ port: 443 });

// Assume reverse proxy configurations with WebSocket intentions
const wsProxyConfigs = [
  {
    destinationIp: '127.0.0.1',
    destinationPort: '8080',
    hostName: 'socket.example.com',
    // Add further options such as keys for SSL if needed
  }
];

// Start the network proxy with WebSocket capabilities
await wsProxy.start();
await wsProxy.updateProxyConfigs(wsProxyConfigs);

// Ensure WebSocket connections remain alive
wsProxy.heartbeatInterval = setInterval(() => {
  // logic for keeping connections alive and healthy
}, 60000); // Every 60 seconds

// Gracefully handle server or connection errors to maintain uptime
wsProxy.httpsServer.on('error', (error) => console.log('Server Error:', error));
```

### Comprehensive Routing and Advanced Features

Smartproxy supports dynamic and customizable request routing based on the incoming request's destination. This feature enables extensive use-case scenarios, from simple API endpoint redirection to elaborate B2B service integrations:

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

const dynamicRoutingProxy = new NetworkProxy({ port: 8443 });
dynamicRoutingProxy.router.setNewProxyConfigs([
  {
    destinationIp: '192.168.1.150',
    destinationPort: '80',
    hostName: 'dynamic.example.com',
    authentication: {
      type: 'Basic',
      user: 'admin',
      pass: 'password123'
    }
  }
]);

await dynamicRoutingProxy.start();
```

For those dealing with high volume or regulatory needs, the integration of tools like `iptables` allows broad control over network traffic:

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

// Setting up iptables for advanced network management
const ipTablesProxy = new IPTablesProxy({
  fromPort: 8081,
  toPort: 8080,
  deleteOnExit: true // clean rules upon server shutdown
});

// Begin routing with IPTables
await ipTablesProxy.start();
```

### Combining with HTTP and HTTPS Credentials

When undertaking proxy configurations, handling sensitive data like SSL certificates and keys securely is imperative:

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

try {
  const { privateKey, publicKey } = loadDefaultCertificates(); // adjust path as needed
  console.log('Certificates loaded.');
  // Use these certificates in your SSL-based configurations
} catch (error) {
  console.error('Cannot load certificates:', error);
}
```

### Testing and Validation

Given these powerful capabilities, rigorous testing of configurations and functionality using frameworks like `tap` can ensure high-quality and reliable proxy configurations. Smartproxy integrates with Typescript test setups:

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

tap.test('proxied request should return status 200', async () => {
  // Your test logic here
});

tap.start();
```

In summary, `@push.rocks/smartproxy` offers a plethora of solutions tailored to both common and sophisticated proxying needs. Whether you're seeking straightforward port forwarding, secure SSL redirection, WebSocket management, or robust network routing controls, smartproxy provides the right tools for efficient and effective proxy operations. Through its integration simplicity and versatile configurations, developers can ensure high performance and secure proxying across various environments and applications.

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