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

new plan

Browse Source
This commit is contained in:
Philipp Kunz 2025-05-09 16:04:02 +00:00
parent cf1c41b27c
commit ec88e9a5b2
1 changed files with 327 additions and 433 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

770
readme.plan.md
View File

@ -1,471 +1,365 @@
# SmartProxy Unified Forwarding Configuration Plan # SmartProxy Project Restructuring Plan
## Project Goal ## 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 ## Current Architecture Analysis
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
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}
};
}
``` ```
/src
### Phase 2: Create New Domain Configuration Interface ├── /core # Core functionality
│ ├── /models # Data models and interfaces
- [ ] Replace existing `IDomainConfig` interface with a new one using the forwarding pattern: │ ├── /utils # Shared utilities (IP validation, logging, etc.)
│ └── /events # Common event definitions
```typescript ├── /certificate # Certificate management
export interface IDomainConfig { │ ├── /acme # ACME-specific functionality
// Core properties │ ├── /providers # Certificate providers (static, ACME)
domains: string[]; // Domain patterns to match │ └── /storage # Certificate storage mechanisms
├── /forwarding # Forwarding system
// Unified forwarding configuration │ ├── /handlers # Various forwarding handlers
forwarding: IForwardConfig; │ │ ├── base-handler.ts # Abstract base handler
} │ │ ├── http-handler.ts # HTTP-only handler
``` │ │ └── ... # Other handlers
│ ├── /config # Configuration models
### Phase 3: Implement Forwarding Handler System │ │ ├── forwarding-types.ts # Type definitions
│ │ ├── domain-config.ts # Domain config utilities
- [ ] Create an implementation strategy focused on the new forwarding types: │ │ └── domain-manager.ts # Domain routing manager
│ └── /factory # Factory for creating handlers
```typescript ├── /proxies # Different proxy implementations
/** │ ├── /smart-proxy # SmartProxy implementation
* Base class for all forwarding handlers │ │ ├── /models # SmartProxy-specific interfaces
*/ │ │ ├── smart-proxy.ts # Main SmartProxy class
abstract class ForwardingHandler { │ │ └── ... # Supporting classes
constructor(protected config: IForwardConfig) {} │ ├── /network-proxy # NetworkProxy implementation
│ │ ├── /models # NetworkProxy-specific interfaces
abstract handleConnection(socket: Socket): void; │ │ ├── network-proxy.ts # Main NetworkProxy class
abstract handleHttpRequest(req: IncomingMessage, res: ServerResponse): void; │ │ └── ... # Supporting classes
} │ └── /nftables-proxy # NfTablesProxy implementation
├── /tls # TLS-specific functionality
/** │ ├── /sni # SNI handling components
* Factory for creating the appropriate handler based on forwarding type │ └── /alerts # TLS alerts system
*/ └── /http # HTTP-specific functionality
class ForwardingHandlerFactory { ├── /port80 # Port80Handler components
public static createHandler(config: IForwardConfig): ForwardingHandler { ├── /router # HTTP routing system
switch (config.type) { └── /redirects # Redirect handlers
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}'
}
}
}
}
``` ```
## Implementation Plan ## Implementation Plan
### Task 1: Core Types and Interfaces (Week 1) ### Phase 1: Project Setup & Core Structure (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
### Task 2: Forwarding Handlers (Week 1-2) - [ ] Create new directory structure
- [ ] Create abstract `ForwardingHandler` base class - [ ] Create `src` directory and core subdirectories
- [ ] Implement concrete handlers for each forwarding type: - [ ] Set up barrel files (`index.ts`) in each directory
- [ ] `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
### Task 3: SmartProxy Integration (Week 2-3) - [ ] Migrate core utilities
- [ ] Update `SmartProxy` class to use the new forwarding system - [ ] Move `ts/plugins.ts` → `src/core/utils/plugins.ts`
- [ ] Modify `ConnectionHandler` to delegate to forwarding handlers - [ ] Move `ts/common/types.ts` → `src/core/models/common-types.ts`
- [ ] Refactor domain configuration processing to use forwarding types - [ ] Move `ts/common/eventUtils.ts` → `src/core/utils/event-utils.ts`
- [ ] Update `Port80Handler` integration to work with the new system - [ ] Extract `ValidationUtils` → `src/core/utils/validation-utils.ts`
- [ ] Extract `IpUtils` → `src/core/utils/ip-utils.ts`
### Task 4: Certificate Management (Week 3) - [ ] Update build and test scripts
- [ ] Create a certificate management system that works with forwarding types - [ ] Modify `package.json` build script for new structure
- [ ] Implement automatic ACME provisioning based on forwarding type - [ ] Create parallel test structure
- [ ] Add custom certificate support
### Task 5: Testing & Helper Functions (Week 4) ### Phase 2: Forwarding System Migration (Weeks 1-2)
- [ ] Create helper functions for common forwarding patterns
- [ ] Implement comprehensive test suite for each forwarding handler
- [ ] Add validation for forwarding configurations
### Task 6: Documentation (Week 4) This component has the cleanest design, so we'll start migration here:
- [ ] Create detailed documentation for the new forwarding system
- [ ] Document the forwarding types and their use cases
- [ ] Update README with the new configuration examples
## 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`
- [ ] 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`
- [ ] 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
### Phase 3: Certificate Management Migration (Week 2)
- [ ] Create certificate management structure
- [ ] Create `src/certificate/models/certificate-types.ts` for interfaces
- [ ] Extract certificate events to `src/certificate/events/`
- [ ] 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`
- [ ] Update certificate utilities
- [ ] Move `ts/helpers.certificates.ts` → `src/certificate/utils/certificate-helpers.ts`
- [ ] Create proper exports in `src/certificate/index.ts`
### Phase 4: TLS & SNI Handling Migration (Week 2-3)
- [ ] 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`
- [ ] 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`
### Phase 5: HTTP Component Migration (Week 3)
- [ ] 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`
- [ ] 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
- [ ] Migrate router components
- [ ] Move `ts/classes.router.ts` → `src/http/router/proxy-router.ts`
- [ ] Extract route matching to `src/http/router/route-matcher.ts`
### Phase 6: Proxy Implementation Migration (Weeks 3-4)
- [ ] 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)
- [ ] 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
- [ ] Migrate NfTablesProxy
- [ ] Move `ts/nfttablesproxy/classes.nftablesproxy.ts` → `src/proxies/nftables-proxy/nftables-proxy.ts`
### Phase 7: Integration & Main Module (Week 4-5)
- [ ] Create main entry points
- [ ] Create `src/index.ts` with all public exports
- [ ] Ensure backward compatibility with type aliases
- [ ] Implement proper namespace exports
- [ ] Update module dependencies
- [ ] Update relative import paths in all modules
- [ ] Resolve circular dependencies if found
- [ ] Test cross-module integration
### Phase 8: Interface Normalization (Week 5)
- [ ] Standardize interface naming
- [ ] Rename `IPortProxySettings` → `SmartProxyOptions`
- [ ] Rename `IDomainConfig` → `DomainConfig`
- [ ] Rename `IConnectionRecord` → `ConnectionRecord`
- [ ] Rename `INetworkProxyOptions` → `NetworkProxyOptions`
- [ ] Rename other interfaces for consistency
- [ ] Provide backward compatibility
- [ ] Add type aliases for renamed interfaces
- [ ] Ensure all exports are compatible with existing code
### Phase 9: Testing & Validation (Weeks 5-6)
- [ ] Reorganize test structure
- [ ] Create test directories matching source structure
- [ ] Move tests to appropriate directories
- [ ] Update test imports and references
- [ ] Add test coverage for new components
- [ ] Create unit tests for extracted utilities
- [ ] Ensure integration tests cover all scenarios
- [ ] Validate backward compatibility
### Phase 10: Documentation (Weeks 6-7)
- [ ] 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 ```typescript
/** // Example: Importing from another component in a nested directory
* The primary forwarding types supported by SmartProxy // From src/forwarding/handlers/http-handler.ts to src/core/utils/validation-utils.ts
*/ import { validateConfig } from '../../../core/utils/validation-utils.js';
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
``` ```
### Type-Specific Behavior 2. **Barrel Files for Convenience**
Each forwarding type has specific default behavior:
#### HTTP-Only
- Handles only HTTP traffic
- No TLS/HTTPS support
- No certificate management
#### HTTPS Passthrough
- Forwards raw TLS traffic to backend (no termination)
- Passes SNI information through
- No HTTP support (TLS only)
- No certificate management
#### 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
#### 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
## Handler Implementation Strategy
```typescript ```typescript
/** // src/forwarding/index.ts
* Handler for HTTP-only forwarding export * from './config/forwarding-types.js';
*/ export * from './handlers/base-handler.js';
class HttpForwardingHandler extends ForwardingHandler { // ... other exports
public handleConnection(socket: Socket): void {
// Process HTTP connection
// For HTTP-only, we'll mostly defer to handleHttpRequest
}
public handleHttpRequest(req: IncomingMessage, res: ServerResponse): void { // Then in consuming code:
// Forward HTTP request to target import { ForwardingHandler, httpOnly } from '../../forwarding/index.js';
const target = this.getTargetFromConfig();
this.proxyRequest(req, res, target);
}
}
/**
* 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);
}
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');
}
}
/**
* Handler for HTTPS termination with HTTP backend
*/
class HttpsTerminateToHttpHandler extends ForwardingHandler {
private tlsContext: SecureContext;
public async initialize(): Promise<void> {
// Set up TLS termination context
this.tlsContext = await this.createTlsContext();
}
public handleConnection(socket: Socket): void {
// Terminate TLS
const tlsSocket = this.createTlsSocket(socket, this.tlsContext);
// Forward to HTTP backend after TLS termination
tlsSocket.on('data', (data) => {
this.forwardToHttpBackend(data);
});
}
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);
}
}
}
/**
* Handler for HTTPS termination with HTTPS backend
*/
class HttpsTerminateToHttpsHandler extends ForwardingHandler {
private tlsContext: SecureContext;
public async initialize(): Promise<void> {
// Set up TLS termination context
this.tlsContext = await this.createTlsContext();
}
public handleConnection(socket: Socket): void {
// Terminate client TLS
const tlsSocket = this.createTlsSocket(socket, this.tlsContext);
// Create new TLS connection to backend
tlsSocket.on('data', (data) => {
this.forwardToHttpsBackend(data);
});
}
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);
}
}
}
``` ```
## Benefits of This Approach 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';
```
1. **Clean, Type-Driven Design** ## Expected Outcomes
- Forwarding types clearly express intent
- No backward compatibility compromises
- Code structure follows the domain model
2. **Explicit Configuration** ### Improved Code Organization
- Configuration directly maps to behavior - Related code will be grouped together in domain-specific directories
- Reduced chance of unexpected behavior - Consistent naming conventions will make code navigation intuitive
- Clear module boundaries will prevent unintended dependencies
3. **Modular Implementation** ### Enhanced Developer Experience
- Each forwarding type handled by dedicated class - Standardized interface naming will improve type clarity
- Clear separation of concerns - Better documentation will help new contributors get started
- Easier to test and extend - Clear and predictable file locations
4. **Simplified Mental Model** ### Maintainability Benefits
- Users think in terms of use cases, not low-level settings - Smaller, focused files with clear responsibilities
- Configuration matches mental model - Unified patterns for common operations
- Improved separation of concerns between components
- Better test organization matching source structure
5. **Future-Proof** ### Performance and Compatibility
- Easy to add new forwarding types - No performance regression from structural changes
- Clean extension points for new features - 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