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

feat(docs): Update README to reflect new modular architecture and expanded core utilities: add Project Architecture Overview, update export paths and API references, and mark plan tasks as completed

Browse Source
This commit is contained in:
Philipp Kunz
2025-05-09 22:11:56 +00:00
parent 5e97c088bf
commit 6b910587ab
9 changed files with 408 additions and 501 deletions
Download Patch File Download Diff File Expand all files Collapse all files

122
readme.md
View File

@ -8,30 +8,77 @@ A high-performance proxy toolkit for Node.js, offering:
- Advanced TCP/SNI-based proxying with IP filtering and rules
- Unified forwarding configuration system for all proxy types
## Project Architecture Overview
SmartProxy has been restructured using a modern, modular architecture to improve maintainability and clarity:
```
/ts
├── /core # Core functionality
│ ├── /models # Data models and interfaces
│ ├── /utils # Shared utilities (IP validation, logging, etc.)
│ └── /events # Common event definitions
├── /certificate # Certificate management
│ ├── /acme # ACME-specific functionality
│ ├── /providers # Certificate providers (static, ACME)
│ └── /storage # Certificate storage mechanisms
├── /forwarding # Forwarding system
│ ├── /handlers # Various forwarding handlers
│ │ ├── base-handler.ts # Abstract base handler
│ │ ├── http-handler.ts # HTTP-only handler
│ │ └── ... # Other handlers
│ ├── /config # Configuration models
│ │ ├── forwarding-types.ts # Type definitions
│ │ ├── domain-config.ts # Domain config utilities
│ │ └── domain-manager.ts # Domain routing manager
│ └── /factory # Factory for creating handlers
├── /proxies # Different proxy implementations
│ ├── /smart-proxy # SmartProxy implementation
│ │ ├── /models # SmartProxy-specific interfaces
│ │ ├── smart-proxy.ts # Main SmartProxy class
│ │ └── ... # Supporting classes
│ ├── /network-proxy # NetworkProxy implementation
│ │ ├── /models # NetworkProxy-specific interfaces
│ │ ├── network-proxy.ts # Main NetworkProxy class
│ │ └── ... # Supporting classes
│ └── /nftables-proxy # NfTablesProxy implementation
├── /tls # TLS-specific functionality
│ ├── /sni # SNI handling components
│ └── /alerts # TLS alerts system
└── /http # HTTP-specific functionality
├── /port80 # Port80Handler components
├── /router # HTTP routing system
└── /redirects # Redirect handlers
```
## Exports
The following classes and interfaces are provided:
- **NetworkProxy** (ts/networkproxy/classes.np.networkproxy.ts)
- **NetworkProxy** (`ts/proxies/network-proxy/network-proxy.ts`)
HTTP/HTTPS reverse proxy with TLS termination, WebSocket support,
connection pooling, and optional ACME integration.
- **Port80Handler** (ts/port80handler/classes.port80handler.ts)
- **Port80Handler** (`ts/http/port80/port80-handler.ts`)
ACME HTTP-01 challenge handler and certificate manager.
- **NfTablesProxy** (ts/nfttablesproxy/classes.nftablesproxy.ts)
- **NfTablesProxy** (`ts/proxies/nftables-proxy/nftables-proxy.ts`)
Low-level port forwarding using nftables NAT rules.
- **Redirect**, **SslRedirect** (ts/redirect/classes.redirect.ts)
- **Redirect**, **SslRedirect** (`ts/http/redirects/redirect-handler.ts`)
HTTP/HTTPS redirect server and shortcut for HTTP→HTTPS.
- **SmartProxy** (ts/smartproxy/classes.smartproxy.ts)
- **SmartProxy** (`ts/proxies/smart-proxy/smart-proxy.ts`)
TCP/SNI-based proxy with dynamic routing, IP filtering, and unified certificates.
- **SniHandler** (ts/smartproxy/classes.pp.snihandler.ts)
- **SniHandler** (`ts/tls/sni/sni-handler.ts`)
Static utilities to extract SNI hostnames from TLS handshakes.
- **Forwarding Handlers** (ts/smartproxy/forwarding/*.ts)
- **Forwarding Handlers** (`ts/forwarding/handlers/*.ts`)
Unified forwarding handlers for different connection types (HTTP, HTTPS passthrough, TLS termination).
- **Core Utilities**
- **ValidationUtils** (`ts/core/utils/validation-utils.ts`) for domain, port, and configuration validation
- **IpUtils** (`ts/core/utils/ip-utils.ts`) for IP address validation and filtering
- **Interfaces**
- IPortProxySettings, IDomainConfig (ts/smartproxy/classes.pp.interfaces.ts)
- INetworkProxyOptions (ts/networkproxy/classes.np.types.ts)
- IAcmeOptions, IDomainOptions (ts/common/types.ts)
- INfTableProxySettings (ts/nfttablesproxy/classes.nftablesproxy.ts)
- IForwardConfig, ForwardingType (ts/smartproxy/types/forwarding.types.ts)
- `SmartProxyOptions`, `DomainConfig` (`ts/proxies/smart-proxy/models/interfaces.ts`)
- `NetworkProxyOptions` (`ts/proxies/network-proxy/models/types.ts`)
- `AcmeOptions`, `DomainOptions` (`ts/core/models/common-types.ts`)
- `NfTableProxySettings` (`ts/proxies/nftables-proxy/models/interfaces.ts`)
- `ForwardConfig`, `ForwardingType` (`ts/forwarding/config/forwarding-types.ts`)
## Installation
Install via npm:
@ -189,16 +236,34 @@ const sni = SniHandler.extractSNI(buffer);
const complete = SniHandler.handleFragmentedClientHello(buf, connId);
```
### 7. Core Utilities (ValidationUtils, IpUtils)
```typescript
import { ValidationUtils, IpUtils } from '@push.rocks/smartproxy';
// Validate a domain name
const isValidDomain = ValidationUtils.isValidDomainName('example.com');
// Check if an IP is allowed based on filters
const isAllowed = IpUtils.isIPAuthorized(
'192.168.1.1',
['192.168.1.*'], // allowed IPs
['192.168.1.100'] // blocked IPs
);
// Convert CIDR to glob patterns
const globPatterns = IpUtils.cidrToGlobPatterns('10.0.0.0/24');
```
## API Reference
For full configuration options and type definitions, see the TypeScript interfaces in the `ts/` directory:
- `INetworkProxyOptions` (ts/networkproxy/classes.np.types.ts)
- `IAcmeOptions`, `IDomainOptions`, `IForwardConfig` (ts/common/types.ts)
- `INfTableProxySettings` (ts/nfttablesproxy/classes.nftablesproxy.ts)
- `IPortProxySettings`, `IDomainConfig` (ts/smartproxy/classes.pp.interfaces.ts)
For full configuration options and type definitions, see the TypeScript interfaces:
- `NetworkProxyOptions` (`ts/proxies/network-proxy/models/types.ts`)
- `AcmeOptions`, `DomainOptions` (`ts/core/models/common-types.ts`)
- `ForwardConfig` (`ts/forwarding/config/forwarding-types.ts`)
- `NfTableProxySettings` (`ts/proxies/nftables-proxy/models/interfaces.ts`)
- `SmartProxyOptions`, `DomainConfig` (`ts/proxies/smart-proxy/models/interfaces.ts`)
## Architecture & Flow Diagrams
```mermaid
flowchart TB
Client([Client])
@ -400,6 +465,9 @@ sequenceDiagram
- SNI Utilities (SniHandler)
• Robust ClientHello parsing, fragmentation & session resumption support
- Core Utilities
• ValidationUtils and IpUtils for configuration validation and IP management
## Certificate Hooks & Events
Listen for certificate events via EventEmitter:
@ -522,7 +590,7 @@ For more complex scenarios, additional options can be specified:
### Extended Configuration Options
#### IForwardConfig
#### ForwardConfig
- `type`: 'http-only' | 'https-passthrough' | 'https-terminate-to-http' | 'https-terminate-to-https'
- `target`: { host: string | string[], port: number }
- `http?`: { enabled?: boolean, redirectToHttps?: boolean, headers?: Record<string, string> }
@ -533,7 +601,7 @@ For more complex scenarios, additional options can be specified:
## Configuration Options
### NetworkProxy (INetworkProxyOptions)
### NetworkProxy (NetworkProxyOptions)
- `port` (number, required)
- `backendProtocol` ('http1'|'http2', default 'http1')
- `maxConnections` (number, default 10000)
@ -542,11 +610,11 @@ For more complex scenarios, additional options can be specified:
- `cors` (object)
- `connectionPoolSize` (number, default 50)
- `logLevel` ('error'|'warn'|'info'|'debug')
- `acme` (IAcmeOptions)
- `acme` (AcmeOptions)
- `useExternalPort80Handler` (boolean)
- `portProxyIntegration` (boolean)
### Port80Handler (IAcmeOptions)
### Port80Handler (AcmeOptions)
- `enabled` (boolean, default true)
- `port` (number, default 80)
- `contactEmail` (string)
@ -555,9 +623,9 @@ For more complex scenarios, additional options can be specified:
- `autoRenew` (boolean, default true)
- `certificateStore` (string)
- `skipConfiguredCerts` (boolean)
- `domainForwards` (IDomainForwardConfig[])
- `domainForwards` (DomainForwardConfig[])
### NfTablesProxy (INfTableProxySettings)
### NfTablesProxy (NfTableProxySettings)
- `fromPort` / `toPort` (number|range|array)
- `toHost` (string, default 'localhost')
- `preserveSourceIP`, `deleteOnExit`, `protocol`, `enableLogging`, `ipv6Support` (booleans)
@ -568,14 +636,14 @@ For more complex scenarios, additional options can be specified:
### Redirect / SslRedirect
- Constructor options: `httpPort`, `httpsPort`, `sslOptions`, `rules` (RedirectRule[])
### SmartProxy (IPortProxySettings)
### SmartProxy (SmartProxyOptions)
- `fromPort`, `toPort` (number)
- `domainConfigs` (IDomainConfig[]) - Using unified forwarding configuration
- `domainConfigs` (DomainConfig[]) - Using unified forwarding configuration
- `sniEnabled`, `preserveSourceIP` (booleans)
- `defaultAllowedIPs`, `defaultBlockedIPs` (string[]) - Default IP allowlists/blocklists
- Timeouts: `initialDataTimeout`, `socketTimeout`, `inactivityTimeout`, etc.
- Socket opts: `noDelay`, `keepAlive`, `enableKeepAliveProbes`
- `acme` (IAcmeOptions), `certProvisionFunction` (callback)
- `acme` (AcmeOptions), `certProvisionFunction` (callback)
- `useNetworkProxy` (number[]), `networkProxyPort` (number)
- `globalPortRanges` (Array<{ from: number; to: number }>)