push.rocks/smartproxy
3
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
Download Patch File Download Diff File Expand all files Collapse all files

760
readme.plan.md
View File

@@ -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
}
public handleHttpRequest(req: IncomingMessage, res: ServerResponse): void {
// Forward HTTP request to target
const target = this.getTargetFromConfig();
this.proxyRequest(req, res, target);
}
}
- [ ] 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`
/**
* 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');
}
}
### Phase 5: HTTP Component Migration (Week 3)
/**
* 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);
}
}
}
- [ ] 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`
/**
* 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);
}
}
}
```
- [ ] 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
## Benefits of This Approach
- [ ] Migrate router components
- [ ] Move `ts/classes.router.ts` → `src/http/router/proxy-router.ts`
- [ ] Extract route matching to `src/http/router/route-matcher.ts`
1. **Clean, Type-Driven Design**
- Forwarding types clearly express intent
- No backward compatibility compromises
- Code structure follows the domain model
### Phase 6: Proxy Implementation Migration (Weeks 3-4)
2. **Explicit Configuration**
- Configuration directly maps to behavior
- Reduced chance of unexpected behavior
- [ ] 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)
3. **Modular Implementation**
- Each forwarding type handled by dedicated class
- Clear separation of concerns
- Easier to test and extend
- [ ] 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
4. **Simplified Mental Model**
- Users think in terms of use cases, not low-level settings
- Configuration matches mental model
- [ ] Migrate NfTablesProxy
- [ ] Move `ts/nfttablesproxy/classes.nftablesproxy.ts` → `src/proxies/nftables-proxy/nftables-proxy.ts`
5. **Future-Proof**
- Easy to add new forwarding types
- Clean extension points for new features
### 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
// 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