new plan
This commit is contained in:
parent
cf1c41b27c
commit
ec88e9a5b2
740
readme.plan.md
740
readme.plan.md
@ -1,471 +1,365 @@
|
||||
# SmartProxy Unified Forwarding Configuration Plan
|
||||
# SmartProxy Project Restructuring Plan
|
||||
|
||||
## Project Goal
|
||||
Create a clean, use-case driven forwarding configuration interface for SmartProxy that elegantly handles all forwarding scenarios: SNI-based forwarding, termination-based forwarding (NetworkProxy), HTTP forwarding, and ACME challenge forwarding.
|
||||
Reorganize the SmartProxy codebase to improve maintainability, readability, and developer experience through:
|
||||
1. Standardized naming conventions
|
||||
2. Consistent directory structure
|
||||
3. Modern TypeScript patterns
|
||||
4. Clear separation of concerns
|
||||
|
||||
## Current State
|
||||
Currently, SmartProxy has several different forwarding mechanisms configured separately:
|
||||
1. **HTTPS/SNI forwarding** via `IDomainConfig` properties
|
||||
2. **NetworkProxy forwarding** via `useNetworkProxy` in domain configs
|
||||
3. **HTTP forwarding** via Port80Handler's `forward` configuration
|
||||
4. **ACME challenge forwarding** via `acmeForward` configuration
|
||||
## Current Architecture Analysis
|
||||
|
||||
This separation creates configuration complexity and reduced cohesion between related settings.
|
||||
Based on code analysis, SmartProxy has several well-defined but inconsistently named modules:
|
||||
|
||||
## Proposed Solution: Clean Use-Case Driven Forwarding Interface
|
||||
1. **SmartProxy** - Primary TCP/SNI-based proxy with configurable routing
|
||||
2. **NetworkProxy** - HTTP/HTTPS reverse proxy with TLS termination
|
||||
3. **Port80Handler** - HTTP port 80 handling for ACME and redirects
|
||||
4. **NfTablesProxy** - Low-level port forwarding via nftables
|
||||
5. **Forwarding System** - New unified configuration for all forwarding types
|
||||
|
||||
### Phase 1: Design Streamlined Forwarding Interface
|
||||
The codebase employs several strong design patterns:
|
||||
- **Factory Pattern** for creating forwarding handlers
|
||||
- **Strategy Pattern** for implementing different forwarding methods
|
||||
- **Manager Pattern** for encapsulating domain, connection, and security logic
|
||||
- **Event-Driven Architecture** for loose coupling between components
|
||||
|
||||
- [ ] Create a use-case driven `IForwardConfig` interface that simplifies configuration:
|
||||
## Target Directory Structure
|
||||
|
||||
```typescript
|
||||
export interface IForwardConfig {
|
||||
// Define the primary forwarding type - use-case driven approach
|
||||
type: 'http-only' | 'https-passthrough' | 'https-terminate-to-http' | 'https-terminate-to-https';
|
||||
|
||||
// Target configuration
|
||||
target: {
|
||||
host: string | string[]; // Support single host or round-robin
|
||||
port: number;
|
||||
};
|
||||
|
||||
// HTTP-specific options
|
||||
http?: {
|
||||
enabled?: boolean; // Defaults to true for http-only, optional for others
|
||||
redirectToHttps?: boolean; // Redirect HTTP to HTTPS
|
||||
headers?: Record<string, string>; // Custom headers for HTTP responses
|
||||
};
|
||||
|
||||
// HTTPS-specific options
|
||||
https?: {
|
||||
customCert?: { // Use custom cert instead of auto-provisioned
|
||||
key: string;
|
||||
cert: string;
|
||||
};
|
||||
forwardSni?: boolean; // Forward SNI info in passthrough mode
|
||||
};
|
||||
|
||||
// ACME certificate handling
|
||||
acme?: {
|
||||
enabled?: boolean; // Enable ACME certificate provisioning
|
||||
maintenance?: boolean; // Auto-renew certificates
|
||||
production?: boolean; // Use production ACME servers
|
||||
forwardChallenges?: { // Forward ACME challenges
|
||||
host: string;
|
||||
port: number;
|
||||
useTls?: boolean;
|
||||
};
|
||||
};
|
||||
|
||||
// Security options
|
||||
security?: {
|
||||
allowedIps?: string[]; // IPs allowed to connect
|
||||
blockedIps?: string[]; // IPs blocked from connecting
|
||||
maxConnections?: number; // Max simultaneous connections
|
||||
};
|
||||
|
||||
// Advanced options
|
||||
advanced?: {
|
||||
portRanges?: Array<{ from: number; to: number }>; // Allowed port ranges
|
||||
networkProxyPort?: number; // Custom NetworkProxy port if using terminate mode
|
||||
keepAlive?: boolean; // Enable TCP keepalive
|
||||
timeout?: number; // Connection timeout in ms
|
||||
headers?: Record<string, string>; // Custom headers with support for variables like {sni}
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 2: Create New Domain Configuration Interface
|
||||
|
||||
- [ ] Replace existing `IDomainConfig` interface with a new one using the forwarding pattern:
|
||||
|
||||
```typescript
|
||||
export interface IDomainConfig {
|
||||
// Core properties
|
||||
domains: string[]; // Domain patterns to match
|
||||
|
||||
// Unified forwarding configuration
|
||||
forwarding: IForwardConfig;
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 3: Implement Forwarding Handler System
|
||||
|
||||
- [ ] Create an implementation strategy focused on the new forwarding types:
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* Base class for all forwarding handlers
|
||||
*/
|
||||
abstract class ForwardingHandler {
|
||||
constructor(protected config: IForwardConfig) {}
|
||||
|
||||
abstract handleConnection(socket: Socket): void;
|
||||
abstract handleHttpRequest(req: IncomingMessage, res: ServerResponse): void;
|
||||
}
|
||||
|
||||
/**
|
||||
* Factory for creating the appropriate handler based on forwarding type
|
||||
*/
|
||||
class ForwardingHandlerFactory {
|
||||
public static createHandler(config: IForwardConfig): ForwardingHandler {
|
||||
switch (config.type) {
|
||||
case 'http-only':
|
||||
return new HttpForwardingHandler(config);
|
||||
|
||||
case 'https-passthrough':
|
||||
return new HttpsPassthroughHandler(config);
|
||||
|
||||
case 'https-terminate-to-http':
|
||||
return new HttpsTerminateToHttpHandler(config);
|
||||
|
||||
case 'https-terminate-to-https':
|
||||
return new HttpsTerminateToHttpsHandler(config);
|
||||
|
||||
default:
|
||||
throw new Error(`Unknown forwarding type: ${config.type}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Usage Examples for Common Scenarios
|
||||
|
||||
### 1. Basic HTTP Server
|
||||
|
||||
```typescript
|
||||
{
|
||||
domains: ['example.com'],
|
||||
forwarding: {
|
||||
type: 'http-only',
|
||||
target: {
|
||||
host: 'localhost',
|
||||
port: 3000
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. HTTPS Termination with HTTP Backend
|
||||
|
||||
```typescript
|
||||
{
|
||||
domains: ['secure.example.com'],
|
||||
forwarding: {
|
||||
type: 'https-terminate-to-http',
|
||||
target: {
|
||||
host: 'localhost',
|
||||
port: 3000
|
||||
},
|
||||
acme: {
|
||||
production: true // Use production Let's Encrypt
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. HTTPS Termination with HTTPS Backend
|
||||
|
||||
```typescript
|
||||
{
|
||||
domains: ['secure-backend.example.com'],
|
||||
forwarding: {
|
||||
type: 'https-terminate-to-https',
|
||||
target: {
|
||||
host: 'internal-api',
|
||||
port: 8443
|
||||
},
|
||||
http: {
|
||||
redirectToHttps: true // Redirect HTTP requests to HTTPS
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. SNI Passthrough
|
||||
|
||||
```typescript
|
||||
{
|
||||
domains: ['passthrough.example.com'],
|
||||
forwarding: {
|
||||
type: 'https-passthrough',
|
||||
target: {
|
||||
host: '10.0.0.5',
|
||||
port: 443
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 5. Mixed HTTP/HTTPS with Custom ACME Forwarding
|
||||
|
||||
```typescript
|
||||
{
|
||||
domains: ['mixed.example.com'],
|
||||
forwarding: {
|
||||
type: 'https-terminate-to-http',
|
||||
target: {
|
||||
host: 'localhost',
|
||||
port: 3000
|
||||
},
|
||||
http: {
|
||||
redirectToHttps: false // Allow both HTTP and HTTPS access
|
||||
},
|
||||
acme: {
|
||||
enabled: true,
|
||||
maintenance: true,
|
||||
forwardChallenges: {
|
||||
host: '192.168.1.100',
|
||||
port: 8080
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 6. Load-Balanced Backend
|
||||
|
||||
```typescript
|
||||
{
|
||||
domains: ['api.example.com'],
|
||||
forwarding: {
|
||||
type: 'https-terminate-to-https',
|
||||
target: {
|
||||
host: ['10.0.0.10', '10.0.0.11', '10.0.0.12'], // Round-robin
|
||||
port: 8443
|
||||
},
|
||||
security: {
|
||||
allowedIps: ['10.0.0.*', '192.168.1.*'] // Restrict access
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 7. Advanced Proxy Chain with Custom Headers
|
||||
|
||||
```typescript
|
||||
{
|
||||
domains: ['secure-chain.example.com'],
|
||||
forwarding: {
|
||||
type: 'https-terminate-to-https',
|
||||
target: {
|
||||
host: 'backend-gateway.internal',
|
||||
port: 443
|
||||
},
|
||||
advanced: {
|
||||
// Pass original client info to backend
|
||||
headers: {
|
||||
'X-Original-SNI': '{sni}',
|
||||
'X-Client-IP': '{clientIp}'
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
/src
|
||||
├── /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
|
||||
```
|
||||
|
||||
## Implementation Plan
|
||||
|
||||
### Task 1: Core Types and Interfaces (Week 1)
|
||||
- [ ] Create the new `IForwardConfig` interface in `classes.pp.interfaces.ts`
|
||||
- [ ] Design the new `IDomainConfig` interface using the forwarding property
|
||||
- [ ] Define the internal data types for expanded configuration
|
||||
### Phase 1: Project Setup & Core Structure (Week 1)
|
||||
|
||||
### Task 2: Forwarding Handlers (Week 1-2)
|
||||
- [ ] Create abstract `ForwardingHandler` base class
|
||||
- [ ] Implement concrete handlers for each forwarding type:
|
||||
- [ ] `HttpForwardingHandler` - For HTTP-only configurations
|
||||
- [ ] `HttpsPassthroughHandler` - For SNI passthrough
|
||||
- [ ] `HttpsTerminateToHttpHandler` - For TLS termination to HTTP backends
|
||||
- [ ] `HttpsTerminateToHttpsHandler` - For TLS termination to HTTPS backends
|
||||
- [ ] Implement `ForwardingHandlerFactory` to create the appropriate handler
|
||||
- [ ] Create new directory structure
|
||||
- [ ] Create `src` directory and core subdirectories
|
||||
- [ ] Set up barrel files (`index.ts`) in each directory
|
||||
|
||||
### Task 3: SmartProxy Integration (Week 2-3)
|
||||
- [ ] Update `SmartProxy` class to use the new forwarding system
|
||||
- [ ] Modify `ConnectionHandler` to delegate to forwarding handlers
|
||||
- [ ] Refactor domain configuration processing to use forwarding types
|
||||
- [ ] Update `Port80Handler` integration to work with the new system
|
||||
- [ ] Migrate core utilities
|
||||
- [ ] Move `ts/plugins.ts` → `src/core/utils/plugins.ts`
|
||||
- [ ] Move `ts/common/types.ts` → `src/core/models/common-types.ts`
|
||||
- [ ] Move `ts/common/eventUtils.ts` → `src/core/utils/event-utils.ts`
|
||||
- [ ] Extract `ValidationUtils` → `src/core/utils/validation-utils.ts`
|
||||
- [ ] Extract `IpUtils` → `src/core/utils/ip-utils.ts`
|
||||
|
||||
### Task 4: Certificate Management (Week 3)
|
||||
- [ ] Create a certificate management system that works with forwarding types
|
||||
- [ ] Implement automatic ACME provisioning based on forwarding type
|
||||
- [ ] Add custom certificate support
|
||||
- [ ] Update build and test scripts
|
||||
- [ ] Modify `package.json` build script for new structure
|
||||
- [ ] Create parallel test structure
|
||||
|
||||
### Task 5: Testing & Helper Functions (Week 4)
|
||||
- [ ] Create helper functions for common forwarding patterns
|
||||
- [ ] Implement comprehensive test suite for each forwarding handler
|
||||
- [ ] Add validation for forwarding configurations
|
||||
### Phase 2: Forwarding System Migration (Weeks 1-2)
|
||||
|
||||
### Task 6: Documentation (Week 4)
|
||||
- [ ] Create detailed documentation for the new forwarding system
|
||||
- [ ] Document the forwarding types and their use cases
|
||||
- [ ] Update README with the new configuration examples
|
||||
This component has the cleanest design, so we'll start migration here:
|
||||
|
||||
## Detailed Type Documentation
|
||||
- [ ] Migrate forwarding types and interfaces
|
||||
- [ ] Move `ts/smartproxy/types/forwarding.types.ts` → `src/forwarding/config/forwarding-types.ts`
|
||||
- [ ] Normalize interface names (remove 'I' prefix where appropriate)
|
||||
|
||||
### Core Forwarding Types
|
||||
- [ ] Migrate domain configuration
|
||||
- [ ] Move `ts/smartproxy/forwarding/domain-config.ts` → `src/forwarding/config/domain-config.ts`
|
||||
- [ ] Move `ts/smartproxy/forwarding/domain-manager.ts` → `src/forwarding/config/domain-manager.ts`
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* The primary forwarding types supported by SmartProxy
|
||||
*/
|
||||
export type ForwardingType =
|
||||
| 'http-only' // HTTP forwarding only (no HTTPS)
|
||||
| 'https-passthrough' // Pass-through TLS traffic (SNI forwarding)
|
||||
| 'https-terminate-to-http' // Terminate TLS and forward to HTTP backend
|
||||
| 'https-terminate-to-https'; // Terminate TLS and forward to HTTPS backend
|
||||
```
|
||||
- [ ] Migrate handler implementations
|
||||
- [ ] Move base handler: `forwarding.handler.ts` → `src/forwarding/handlers/base-handler.ts`
|
||||
- [ ] Move HTTP handler: `http.handler.ts` → `src/forwarding/handlers/http-handler.ts`
|
||||
- [ ] Move passthrough handler: `https-passthrough.handler.ts` → `src/forwarding/handlers/https-passthrough-handler.ts`
|
||||
- [ ] Move TLS termination handlers to respective files in `src/forwarding/handlers/`
|
||||
- [ ] Move factory: `forwarding.factory.ts` → `src/forwarding/factory/forwarding-factory.ts`
|
||||
|
||||
### Type-Specific Behavior
|
||||
- [ ] Create proper forwarding system exports
|
||||
- [ ] Update all imports in forwarding components using relative paths
|
||||
- [ ] Create comprehensive barrel file in `src/forwarding/index.ts`
|
||||
- [ ] Test forwarding system in isolation
|
||||
|
||||
Each forwarding type has specific default behavior:
|
||||
### Phase 3: Certificate Management Migration (Week 2)
|
||||
|
||||
#### HTTP-Only
|
||||
- Handles only HTTP traffic
|
||||
- No TLS/HTTPS support
|
||||
- No certificate management
|
||||
- [ ] Create certificate management structure
|
||||
- [ ] Create `src/certificate/models/certificate-types.ts` for interfaces
|
||||
- [ ] Extract certificate events to `src/certificate/events/`
|
||||
|
||||
#### HTTPS Passthrough
|
||||
- Forwards raw TLS traffic to backend (no termination)
|
||||
- Passes SNI information through
|
||||
- No HTTP support (TLS only)
|
||||
- No certificate management
|
||||
- [ ] Migrate certificate providers
|
||||
- [ ] Move `ts/classes.pp.certprovisioner.ts` → `src/certificate/providers/cert-provisioner.ts`
|
||||
- [ ] Move `ts/common/acmeFactory.ts` → `src/certificate/acme/acme-factory.ts`
|
||||
- [ ] Extract ACME challenge handling to `src/certificate/acme/challenge-handler.ts`
|
||||
|
||||
#### HTTPS Terminate to HTTP
|
||||
- Terminates TLS at SmartProxy
|
||||
- Connects to backend using HTTP (non-TLS)
|
||||
- Manages certificates automatically (ACME)
|
||||
- Supports HTTP requests with option to redirect to HTTPS
|
||||
- [ ] Update certificate utilities
|
||||
- [ ] Move `ts/helpers.certificates.ts` → `src/certificate/utils/certificate-helpers.ts`
|
||||
- [ ] Create proper exports in `src/certificate/index.ts`
|
||||
|
||||
#### HTTPS Terminate to HTTPS
|
||||
- Terminates client TLS at SmartProxy
|
||||
- Creates new TLS connection to backend
|
||||
- Manages certificates automatically (ACME)
|
||||
- Supports HTTP requests with option to redirect to HTTPS
|
||||
### Phase 4: TLS & SNI Handling Migration (Week 2-3)
|
||||
|
||||
## Handler Implementation Strategy
|
||||
- [ ] Migrate TLS alert system
|
||||
- [ ] Move `ts/smartproxy/classes.pp.tlsalert.ts` → `src/tls/alerts/tls-alert.ts`
|
||||
- [ ] Extract common TLS utilities to `src/tls/utils/tls-utils.ts`
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* Handler for HTTP-only forwarding
|
||||
*/
|
||||
class HttpForwardingHandler extends ForwardingHandler {
|
||||
public handleConnection(socket: Socket): void {
|
||||
// Process HTTP connection
|
||||
// For HTTP-only, we'll mostly defer to handleHttpRequest
|
||||
}
|
||||
- [ ] Migrate SNI handling
|
||||
- [ ] Move `ts/smartproxy/classes.pp.snihandler.ts` → `src/tls/sni/sni-handler.ts`
|
||||
- [ ] Extract SNI extraction to `src/tls/sni/sni-extraction.ts`
|
||||
- [ ] Extract ClientHello parsing to `src/tls/sni/client-hello-parser.ts`
|
||||
|
||||
public handleHttpRequest(req: IncomingMessage, res: ServerResponse): void {
|
||||
// Forward HTTP request to target
|
||||
const target = this.getTargetFromConfig();
|
||||
this.proxyRequest(req, res, target);
|
||||
}
|
||||
}
|
||||
### Phase 5: HTTP Component Migration (Week 3)
|
||||
|
||||
/**
|
||||
* Handler for HTTPS passthrough (SNI forwarding)
|
||||
*/
|
||||
class HttpsPassthroughHandler extends ForwardingHandler {
|
||||
public handleConnection(socket: Socket): void {
|
||||
// Extract SNI from TLS ClientHello if needed
|
||||
// Forward raw TLS traffic to target without termination
|
||||
const target = this.getTargetFromConfig();
|
||||
this.forwardTlsConnection(socket, target);
|
||||
}
|
||||
- [ ] Migrate Port80Handler
|
||||
- [ ] Move `ts/port80handler/classes.port80handler.ts` → `src/http/port80/port80-handler.ts`
|
||||
- [ ] Extract ACME challenge handling to `src/http/port80/challenge-responder.ts`
|
||||
|
||||
public handleHttpRequest(req: IncomingMessage, res: ServerResponse): void {
|
||||
// HTTP not supported in SNI passthrough mode
|
||||
res.statusCode = 404;
|
||||
res.end('HTTP not supported for this domain');
|
||||
}
|
||||
}
|
||||
- [ ] Migrate redirect handlers
|
||||
- [ ] Move `ts/redirect/classes.redirect.ts` → `src/http/redirects/redirect-handler.ts`
|
||||
- [ ] Create `src/http/redirects/ssl-redirect.ts` for specialized redirects
|
||||
|
||||
/**
|
||||
* Handler for HTTPS termination with HTTP backend
|
||||
*/
|
||||
class HttpsTerminateToHttpHandler extends ForwardingHandler {
|
||||
private tlsContext: SecureContext;
|
||||
- [ ] Migrate router components
|
||||
- [ ] Move `ts/classes.router.ts` → `src/http/router/proxy-router.ts`
|
||||
- [ ] Extract route matching to `src/http/router/route-matcher.ts`
|
||||
|
||||
public async initialize(): Promise<void> {
|
||||
// Set up TLS termination context
|
||||
this.tlsContext = await this.createTlsContext();
|
||||
}
|
||||
### Phase 6: Proxy Implementation Migration (Weeks 3-4)
|
||||
|
||||
public handleConnection(socket: Socket): void {
|
||||
// Terminate TLS
|
||||
const tlsSocket = this.createTlsSocket(socket, this.tlsContext);
|
||||
- [ ] Migrate SmartProxy components
|
||||
- [ ] First, migrate interfaces to `src/proxies/smart-proxy/models/`
|
||||
- [ ] Move core class: `ts/smartproxy/classes.smartproxy.ts` → `src/proxies/smart-proxy/smart-proxy.ts`
|
||||
- [ ] Move supporting classes using consistent naming
|
||||
- [ ] Normalize interface names (SmartProxyOptions instead of IPortProxySettings)
|
||||
|
||||
// Forward to HTTP backend after TLS termination
|
||||
tlsSocket.on('data', (data) => {
|
||||
this.forwardToHttpBackend(data);
|
||||
});
|
||||
}
|
||||
- [ ] Migrate NetworkProxy components
|
||||
- [ ] First, migrate interfaces to `src/proxies/network-proxy/models/`
|
||||
- [ ] Move core class: `ts/networkproxy/classes.np.networkproxy.ts` → `src/proxies/network-proxy/network-proxy.ts`
|
||||
- [ ] Move supporting classes using consistent naming
|
||||
|
||||
public handleHttpRequest(req: IncomingMessage, res: ServerResponse): void {
|
||||
if (this.config.http?.redirectToHttps) {
|
||||
// Redirect to HTTPS if configured
|
||||
this.redirectToHttps(req, res);
|
||||
} else {
|
||||
// Handle HTTP request
|
||||
const target = this.getTargetFromConfig();
|
||||
this.proxyRequest(req, res, target);
|
||||
}
|
||||
}
|
||||
}
|
||||
- [ ] Migrate NfTablesProxy
|
||||
- [ ] Move `ts/nfttablesproxy/classes.nftablesproxy.ts` → `src/proxies/nftables-proxy/nftables-proxy.ts`
|
||||
|
||||
/**
|
||||
* Handler for HTTPS termination with HTTPS backend
|
||||
*/
|
||||
class HttpsTerminateToHttpsHandler extends ForwardingHandler {
|
||||
private tlsContext: SecureContext;
|
||||
### Phase 7: Integration & Main Module (Week 4-5)
|
||||
|
||||
public async initialize(): Promise<void> {
|
||||
// Set up TLS termination context
|
||||
this.tlsContext = await this.createTlsContext();
|
||||
}
|
||||
- [ ] Create main entry points
|
||||
- [ ] Create `src/index.ts` with all public exports
|
||||
- [ ] Ensure backward compatibility with type aliases
|
||||
- [ ] Implement proper namespace exports
|
||||
|
||||
public handleConnection(socket: Socket): void {
|
||||
// Terminate client TLS
|
||||
const tlsSocket = this.createTlsSocket(socket, this.tlsContext);
|
||||
- [ ] Update module dependencies
|
||||
- [ ] Update relative import paths in all modules
|
||||
- [ ] Resolve circular dependencies if found
|
||||
- [ ] Test cross-module integration
|
||||
|
||||
// Create new TLS connection to backend
|
||||
tlsSocket.on('data', (data) => {
|
||||
this.forwardToHttpsBackend(data);
|
||||
});
|
||||
}
|
||||
### Phase 8: Interface Normalization (Week 5)
|
||||
|
||||
public handleHttpRequest(req: IncomingMessage, res: ServerResponse): void {
|
||||
if (this.config.http?.redirectToHttps) {
|
||||
// Redirect to HTTPS if configured
|
||||
this.redirectToHttps(req, res);
|
||||
} else {
|
||||
// Handle HTTP request via HTTPS to backend
|
||||
const target = this.getTargetFromConfig();
|
||||
this.proxyRequestOverHttps(req, res, target);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
- [ ] Standardize interface naming
|
||||
- [ ] Rename `IPortProxySettings` → `SmartProxyOptions`
|
||||
- [ ] Rename `IDomainConfig` → `DomainConfig`
|
||||
- [ ] Rename `IConnectionRecord` → `ConnectionRecord`
|
||||
- [ ] Rename `INetworkProxyOptions` → `NetworkProxyOptions`
|
||||
- [ ] Rename other interfaces for consistency
|
||||
|
||||
## Benefits of This Approach
|
||||
- [ ] Provide backward compatibility
|
||||
- [ ] Add type aliases for renamed interfaces
|
||||
- [ ] Ensure all exports are compatible with existing code
|
||||
|
||||
1. **Clean, Type-Driven Design**
|
||||
- Forwarding types clearly express intent
|
||||
- No backward compatibility compromises
|
||||
- Code structure follows the domain model
|
||||
### Phase 9: Testing & Validation (Weeks 5-6)
|
||||
|
||||
2. **Explicit Configuration**
|
||||
- Configuration directly maps to behavior
|
||||
- Reduced chance of unexpected behavior
|
||||
- [ ] Reorganize test structure
|
||||
- [ ] Create test directories matching source structure
|
||||
- [ ] Move tests to appropriate directories
|
||||
- [ ] Update test imports and references
|
||||
|
||||
3. **Modular Implementation**
|
||||
- Each forwarding type handled by dedicated class
|
||||
- Clear separation of concerns
|
||||
- Easier to test and extend
|
||||
- [ ] Add test coverage for new components
|
||||
- [ ] Create unit tests for extracted utilities
|
||||
- [ ] Ensure integration tests cover all scenarios
|
||||
- [ ] Validate backward compatibility
|
||||
|
||||
4. **Simplified Mental Model**
|
||||
- Users think in terms of use cases, not low-level settings
|
||||
- Configuration matches mental model
|
||||
### Phase 10: Documentation (Weeks 6-7)
|
||||
|
||||
5. **Future-Proof**
|
||||
- Easy to add new forwarding types
|
||||
- Clean extension points for new features
|
||||
- [ ] Update core documentation
|
||||
- [ ] Update README.md with new structure and examples
|
||||
- [ ] Create architecture diagram showing component relationships
|
||||
- [ ] Document import patterns and best practices
|
||||
|
||||
- [ ] Create specialized documentation
|
||||
- [ ] `ARCHITECTURE.md` for system overview
|
||||
- [ ] `FORWARDING.md` for forwarding system specifics
|
||||
- [ ] `CERTIFICATE.md` for certificate management details
|
||||
- [ ] `DEVELOPMENT.md` for contributor guidelines
|
||||
|
||||
- [ ] Update example files
|
||||
- [ ] Update existing examples to use new structure
|
||||
- [ ] Add new examples demonstrating key scenarios
|
||||
|
||||
### Phase 11: Release & Migration Guide (Week 8)
|
||||
|
||||
- [ ] Prepare for release
|
||||
- [ ] Final testing and validation
|
||||
- [ ] Performance comparison with previous version
|
||||
- [ ] Create detailed changelog
|
||||
|
||||
- [ ] Create migration guide
|
||||
- [ ] Document breaking changes
|
||||
- [ ] Provide upgrade instructions
|
||||
- [ ] Include code examples for common scenarios
|
||||
|
||||
## Detailed File Migration Table
|
||||
|
||||
| Current File | New File | Status |
|
||||
|--------------|----------|--------|
|
||||
| **Core/Common Files** | | |
|
||||
| ts/common/types.ts | src/core/models/common-types.ts | ❌ |
|
||||
| ts/common/eventUtils.ts | src/core/utils/event-utils.ts | ❌ |
|
||||
| ts/common/acmeFactory.ts | src/certificate/acme/acme-factory.ts | ❌ |
|
||||
| ts/plugins.ts | src/core/utils/plugins.ts | ❌ |
|
||||
| ts/00_commitinfo_data.ts | src/core/utils/commit-info.ts | ❌ |
|
||||
| **Certificate Management** | | |
|
||||
| ts/helpers.certificates.ts | src/certificate/utils/certificate-helpers.ts | ❌ |
|
||||
| ts/classes.pp.certprovisioner.ts | src/certificate/providers/cert-provisioner.ts | ❌ |
|
||||
| **TLS and SNI Handling** | | |
|
||||
| ts/smartproxy/classes.pp.tlsalert.ts | src/tls/alerts/tls-alert.ts | ❌ |
|
||||
| ts/smartproxy/classes.pp.snihandler.ts | src/tls/sni/sni-handler.ts | ❌ |
|
||||
| **HTTP Components** | | |
|
||||
| ts/port80handler/classes.port80handler.ts | src/http/port80/port80-handler.ts | ❌ |
|
||||
| ts/redirect/classes.redirect.ts | src/http/redirects/redirect-handler.ts | ❌ |
|
||||
| ts/classes.router.ts | src/http/router/proxy-router.ts | ❌ |
|
||||
| **SmartProxy Components** | | |
|
||||
| ts/smartproxy/classes.smartproxy.ts | src/proxies/smart-proxy/smart-proxy.ts | ❌ |
|
||||
| ts/smartproxy/classes.pp.interfaces.ts | src/proxies/smart-proxy/models/interfaces.ts | ❌ |
|
||||
| ts/smartproxy/classes.pp.connectionhandler.ts | src/proxies/smart-proxy/connection-handler.ts | ❌ |
|
||||
| ts/smartproxy/classes.pp.connectionmanager.ts | src/proxies/smart-proxy/connection-manager.ts | ❌ |
|
||||
| ts/smartproxy/classes.pp.domainconfigmanager.ts | src/proxies/smart-proxy/domain-config-manager.ts | ❌ |
|
||||
| ts/smartproxy/classes.pp.portrangemanager.ts | src/proxies/smart-proxy/port-range-manager.ts | ❌ |
|
||||
| ts/smartproxy/classes.pp.securitymanager.ts | src/proxies/smart-proxy/security-manager.ts | ❌ |
|
||||
| ts/smartproxy/classes.pp.timeoutmanager.ts | src/proxies/smart-proxy/timeout-manager.ts | ❌ |
|
||||
| ts/smartproxy/classes.pp.networkproxybridge.ts | src/proxies/smart-proxy/network-proxy-bridge.ts | ❌ |
|
||||
| **NetworkProxy Components** | | |
|
||||
| ts/networkproxy/classes.np.networkproxy.ts | src/proxies/network-proxy/network-proxy.ts | ❌ |
|
||||
| ts/networkproxy/classes.np.certificatemanager.ts | src/proxies/network-proxy/certificate-manager.ts | ❌ |
|
||||
| ts/networkproxy/classes.np.connectionpool.ts | src/proxies/network-proxy/connection-pool.ts | ❌ |
|
||||
| ts/networkproxy/classes.np.requesthandler.ts | src/proxies/network-proxy/request-handler.ts | ❌ |
|
||||
| ts/networkproxy/classes.np.websockethandler.ts | src/proxies/network-proxy/websocket-handler.ts | ❌ |
|
||||
| ts/networkproxy/classes.np.types.ts | src/proxies/network-proxy/models/types.ts | ❌ |
|
||||
| **NFTablesProxy Components** | | |
|
||||
| ts/nfttablesproxy/classes.nftablesproxy.ts | src/proxies/nftables-proxy/nftables-proxy.ts | ❌ |
|
||||
| **Forwarding System** | | |
|
||||
| ts/smartproxy/types/forwarding.types.ts | src/forwarding/config/forwarding-types.ts | ❌ |
|
||||
| ts/smartproxy/forwarding/domain-config.ts | src/forwarding/config/domain-config.ts | ❌ |
|
||||
| ts/smartproxy/forwarding/domain-manager.ts | src/forwarding/config/domain-manager.ts | ❌ |
|
||||
| ts/smartproxy/forwarding/forwarding.handler.ts | src/forwarding/handlers/base-handler.ts | ❌ |
|
||||
| ts/smartproxy/forwarding/http.handler.ts | src/forwarding/handlers/http-handler.ts | ❌ |
|
||||
| ts/smartproxy/forwarding/https-passthrough.handler.ts | src/forwarding/handlers/https-passthrough-handler.ts | ❌ |
|
||||
| ts/smartproxy/forwarding/https-terminate-to-http.handler.ts | src/forwarding/handlers/https-terminate-to-http-handler.ts | ❌ |
|
||||
| ts/smartproxy/forwarding/https-terminate-to-https.handler.ts | src/forwarding/handlers/https-terminate-to-https-handler.ts | ❌ |
|
||||
| ts/smartproxy/forwarding/forwarding.factory.ts | src/forwarding/factory/forwarding-factory.ts | ❌ |
|
||||
| ts/smartproxy/forwarding/index.ts | src/forwarding/index.ts | ❌ |
|
||||
| **Examples and Entry Points** | | |
|
||||
| ts/examples/forwarding-example.ts | src/examples/forwarding-example.ts | ❌ |
|
||||
| ts/index.ts | src/index.ts | ❌ |
|
||||
|
||||
## Import Strategy
|
||||
|
||||
Since path aliases will not be used, we'll maintain standard relative imports throughout the codebase:
|
||||
|
||||
1. **Import Strategy for Deeply Nested Files**
|
||||
```typescript
|
||||
// Example: Importing from another component in a nested directory
|
||||
// From src/forwarding/handlers/http-handler.ts to src/core/utils/validation-utils.ts
|
||||
import { validateConfig } from '../../../core/utils/validation-utils.js';
|
||||
```
|
||||
|
||||
2. **Barrel Files for Convenience**
|
||||
```typescript
|
||||
// src/forwarding/index.ts
|
||||
export * from './config/forwarding-types.js';
|
||||
export * from './handlers/base-handler.js';
|
||||
// ... other exports
|
||||
|
||||
// Then in consuming code:
|
||||
import { ForwardingHandler, httpOnly } from '../../forwarding/index.js';
|
||||
```
|
||||
|
||||
3. **Flattened Imports Where Sensible**
|
||||
```typescript
|
||||
// Avoid excessive nesting with targeted exports
|
||||
// src/index.ts will export key components for external use
|
||||
import { SmartProxy, NetworkProxy } from '../index.js';
|
||||
```
|
||||
|
||||
## Expected Outcomes
|
||||
|
||||
### Improved Code Organization
|
||||
- Related code will be grouped together in domain-specific directories
|
||||
- Consistent naming conventions will make code navigation intuitive
|
||||
- Clear module boundaries will prevent unintended dependencies
|
||||
|
||||
### Enhanced Developer Experience
|
||||
- Standardized interface naming will improve type clarity
|
||||
- Better documentation will help new contributors get started
|
||||
- Clear and predictable file locations
|
||||
|
||||
### Maintainability Benefits
|
||||
- Smaller, focused files with clear responsibilities
|
||||
- Unified patterns for common operations
|
||||
- Improved separation of concerns between components
|
||||
- Better test organization matching source structure
|
||||
|
||||
### Performance and Compatibility
|
||||
- No performance regression from structural changes
|
||||
- Backward compatibility through type aliases and consistent exports
|
||||
- Clear migration path for dependent projects
|
||||
|
||||
## Migration Strategy
|
||||
|
||||
To ensure a smooth transition, we'll follow this approach for each component:
|
||||
|
||||
1. Create the new file structure first
|
||||
2. Migrate code while updating relative imports
|
||||
3. Test each component as it's migrated
|
||||
4. Only remove old files once all dependencies are updated
|
||||
5. Use a phased approach to allow parallel work
|
||||
|
||||
This approach ensures the codebase remains functional throughout the restructuring process while progressively adopting the new organization.
|
||||
|
||||
## Measuring Success
|
||||
|
||||
We'll measure the success of this restructuring by:
|
||||
|
||||
1. Reduced complexity in the directory structure
|
||||
2. Improved code coverage through better test organization
|
||||
3. Faster onboarding time for new developers
|
||||
4. Less time spent navigating the codebase
|
||||
5. Cleaner git blame output showing cohesive component changes
|
||||
|
||||
## Special Considerations
|
||||
|
||||
- We'll maintain backward compatibility for all public APIs
|
||||
- We'll provide detailed upgrade guides for any breaking changes
|
||||
- We'll ensure the build process produces compatible output
|
||||
- We'll preserve commit history using git move operations where possible
|
||||
Loading…
x
Reference in New Issue
Block a user