255 lines
8.7 KiB
Markdown
255 lines
8.7 KiB
Markdown
# SmartProxy Interface & Type Naming Standardization Plan
|
|
|
|
## Project Goal
|
|
Standardize interface and type naming throughout the SmartProxy codebase to improve maintainability, readability, and developer experience by:
|
|
1. Ensuring all interfaces are prefixed with "I"
|
|
2. Ensuring all type aliases are prefixed with "T"
|
|
3. Maintaining backward compatibility through type aliases
|
|
4. Updating documentation to reflect naming conventions
|
|
|
|
## Phase 2: Core Module Standardization
|
|
|
|
- [ ] Update core module interfaces and types
|
|
- [ ] Rename interfaces in `ts/core/models/common-types.ts`
|
|
- [ ] `AcmeOptions` → `IAcmeOptions`
|
|
- [ ] `DomainOptions` → `IDomainOptions`
|
|
- [ ] Other common interfaces
|
|
- [ ] Add backward compatibility aliases
|
|
- [ ] Update imports throughout core module
|
|
|
|
- [ ] Update core utility type definitions
|
|
- [ ] Update `ts/core/utils/validation-utils.ts`
|
|
- [ ] Update `ts/core/utils/ip-utils.ts`
|
|
- [ ] Standardize event type definitions
|
|
|
|
- [ ] Test core module changes
|
|
- [ ] Run unit tests for core modules
|
|
- [ ] Verify type compatibility
|
|
- [ ] Ensure backward compatibility
|
|
|
|
## Phase 3: Certificate Module Standardization
|
|
|
|
- [ ] Update certificate interfaces
|
|
- [ ] Rename interfaces in `ts/certificate/models/certificate-types.ts`
|
|
- [ ] `CertificateData` → `ICertificateData`
|
|
- [ ] `Certificates` → `ICertificates`
|
|
- [ ] `CertificateFailure` → `ICertificateFailure`
|
|
- [ ] `CertificateExpiring` → `ICertificateExpiring`
|
|
- [ ] `ForwardConfig` → `IForwardConfig`
|
|
- [ ] `DomainForwardConfig` → `IDomainForwardConfig`
|
|
- [ ] Update ACME challenge interfaces
|
|
- [ ] Standardize storage provider interfaces
|
|
|
|
- [ ] Ensure certificate provider compatibility
|
|
- [ ] Update provider implementations
|
|
- [ ] Rename internal interfaces
|
|
- [ ] Maintain public API compatibility
|
|
|
|
- [ ] Test certificate module
|
|
- [ ] Verify ACME functionality
|
|
- [ ] Test certificate provisioning
|
|
- [ ] Validate challenge handling
|
|
|
|
## Phase 4: Forwarding System Standardization
|
|
|
|
- [ ] Update forwarding configuration interfaces
|
|
- [ ] Rename interfaces in `ts/forwarding/config/forwarding-types.ts`
|
|
- [ ] `TargetConfig` → `ITargetConfig`
|
|
- [ ] `HttpOptions` → `IHttpOptions`
|
|
- [ ] `HttpsOptions` → `IHttpsOptions`
|
|
- [ ] `AcmeForwardingOptions` → `IAcmeForwardingOptions`
|
|
- [ ] `SecurityOptions` → `ISecurityOptions`
|
|
- [ ] `AdvancedOptions` → `IAdvancedOptions`
|
|
- [ ] `ForwardConfig` → `IForwardConfig`
|
|
- [ ] Rename type definitions
|
|
- [ ] `ForwardingType` → `TForwardingType`
|
|
- [ ] Update domain configuration interfaces
|
|
|
|
- [ ] Standardize handler interfaces
|
|
- [ ] Update base handler interfaces
|
|
- [ ] Rename handler-specific interfaces
|
|
- [ ] Update factory interfaces
|
|
|
|
- [ ] Verify forwarding system functionality
|
|
- [ ] Test all forwarding types
|
|
- [ ] Verify configuration parsing
|
|
- [ ] Ensure backward compatibility
|
|
|
|
## Phase 5: Proxy Implementation Standardization
|
|
|
|
- [ ] Update SmartProxy interfaces
|
|
- [ ] Rename interfaces in `ts/proxies/smart-proxy/models/interfaces.ts`
|
|
- [ ] Update domain configuration interfaces
|
|
- [ ] Standardize manager interfaces
|
|
|
|
- [ ] Update NetworkProxy interfaces
|
|
- [ ] Rename in `ts/proxies/network-proxy/models/types.ts`
|
|
- [ ] `NetworkProxyOptions` → `INetworkProxyOptions`
|
|
- [ ] `CertificateEntry` → `ICertificateEntry`
|
|
- [ ] `ReverseProxyConfig` → `IReverseProxyConfig`
|
|
- [ ] `ConnectionEntry` → `IConnectionEntry`
|
|
- [ ] `WebSocketWithHeartbeat` → `IWebSocketWithHeartbeat`
|
|
- [ ] `Logger` → `ILogger`
|
|
- [ ] Update request handler interfaces
|
|
- [ ] Standardize connection interfaces
|
|
|
|
- [ ] Update NfTablesProxy interfaces
|
|
- [ ] Rename interfaces in `ts/proxies/nftables-proxy/models/interfaces.ts`
|
|
- [ ] Update configuration interfaces
|
|
- [ ] Standardize firewall rule interfaces
|
|
|
|
- [ ] Test proxy implementations
|
|
- [ ] Verify SmartProxy functionality
|
|
- [ ] Test NetworkProxy with renamed interfaces
|
|
- [ ] Validate NfTablesProxy operations
|
|
|
|
## Phase 6: HTTP & TLS Module Standardization
|
|
|
|
- [ ] Update HTTP interfaces
|
|
- [ ] Rename in `ts/http/port80/acme-interfaces.ts`
|
|
- [ ] `SmartAcmeCert` → `ISmartAcmeCert`
|
|
- [ ] `SmartAcmeOptions` → `ISmartAcmeOptions`
|
|
- [ ] `Http01Challenge` → `IHttp01Challenge`
|
|
- [ ] `SmartAcme` → `ISmartAcme`
|
|
- [ ] Standardize router interfaces
|
|
- [ ] Update port80 handler interfaces
|
|
- [ ] Update redirect interfaces
|
|
|
|
- [ ] Update TLS/SNI interfaces
|
|
- [ ] Standardize SNI handler interfaces
|
|
- [ ] Update client hello parser types
|
|
- [ ] Rename TLS alert interfaces
|
|
|
|
- [ ] Test HTTP & TLS functionality
|
|
- [ ] Verify router operation
|
|
- [ ] Test SNI extraction
|
|
- [ ] Validate redirect functionality
|
|
|
|
## Phase 7: Backward Compatibility Layer
|
|
|
|
- [ ] Implement comprehensive type aliases
|
|
- [ ] Create aliases for all renamed interfaces
|
|
- [ ] Add deprecation notices via JSDoc
|
|
- [ ] Ensure all exports include both named versions
|
|
|
|
- [ ] Update main entry point
|
|
- [ ] Update `ts/index.ts` with all exports
|
|
- [ ] Include both prefixed and non-prefixed names
|
|
- [ ] Organize exports by module
|
|
|
|
- [ ] Add compatibility documentation
|
|
- [ ] Document renaming strategy
|
|
- [ ] Provide migration examples
|
|
- [ ] Create deprecation timeline
|
|
|
|
## Phase 8: Documentation & Examples
|
|
|
|
- [ ] Update README and API documentation
|
|
- [ ] Update interface references in README.md
|
|
- [ ] Document naming convention in README.md
|
|
- [ ] Update API reference documentation
|
|
|
|
- [ ] Update examples
|
|
- [ ] Modify example code to use new interface names
|
|
- [ ] Add compatibility notes
|
|
- [ ] Create migration examples
|
|
|
|
- [ ] Add contributor guidelines
|
|
- [ ] Document naming conventions
|
|
- [ ] Add interface/type style guide
|
|
- [ ] Update PR templates
|
|
|
|
## Phase 9: Testing & Validation
|
|
|
|
- [ ] Run comprehensive test suite
|
|
- [ ] Run all unit tests
|
|
- [ ] Execute integration tests
|
|
- [ ] Verify example code
|
|
|
|
- [ ] Build type declarations
|
|
- [ ] Generate TypeScript declaration files
|
|
- [ ] Verify exported types
|
|
- [ ] Validate documentation generation
|
|
|
|
- [ ] Final compatibility check
|
|
- [ ] Verify import compatibility
|
|
- [ ] Test with existing dependent projects
|
|
- [ ] Validate backward compatibility claims
|
|
|
|
## Implementation Strategy
|
|
|
|
### Naming Pattern Rules
|
|
|
|
1. **Interfaces**:
|
|
- All interfaces should be prefixed with "I"
|
|
- Example: `DomainConfig` → `IDomainConfig`
|
|
|
|
2. **Type Aliases**:
|
|
- All type aliases should be prefixed with "T"
|
|
- Example: `ForwardingType` → `TForwardingType`
|
|
|
|
3. **Enums**:
|
|
- Enums should be named in PascalCase without prefix
|
|
- Example: `CertificateSource`
|
|
|
|
4. **Backward Compatibility**:
|
|
- No Backward compatibility. Remove old names.
|
|
|
|
### Module Implementation Order
|
|
|
|
1. Core module
|
|
2. Certificate module
|
|
3. Forwarding module
|
|
4. Proxy implementations
|
|
5. HTTP & TLS modules
|
|
6. Main exports and entry points
|
|
|
|
### Testing Strategy
|
|
|
|
For each module:
|
|
1. Rename interfaces and types
|
|
2. Add backward compatibility aliases
|
|
3. Update imports throughout the module
|
|
4. Run tests to verify functionality
|
|
5. Commit changes module by module
|
|
|
|
## File-Specific Changes
|
|
|
|
### Core Module Files
|
|
- `ts/core/models/common-types.ts` - Primary interfaces
|
|
- `ts/core/utils/validation-utils.ts` - Validation type definitions
|
|
- `ts/core/utils/ip-utils.ts` - IP utility type definitions
|
|
- `ts/core/utils/event-utils.ts` - Event type definitions
|
|
|
|
### Certificate Module Files
|
|
- `ts/certificate/models/certificate-types.ts` - Certificate interfaces
|
|
- `ts/certificate/acme/acme-factory.ts` - ACME factory types
|
|
- `ts/certificate/providers/cert-provisioner.ts` - Provider interfaces
|
|
- `ts/certificate/storage/file-storage.ts` - Storage interfaces
|
|
|
|
### Forwarding Module Files
|
|
- `ts/forwarding/config/forwarding-types.ts` - Forwarding interfaces and types
|
|
- `ts/forwarding/config/domain-config.ts` - Domain configuration
|
|
- `ts/forwarding/factory/forwarding-factory.ts` - Factory interfaces
|
|
- `ts/forwarding/handlers/*.ts` - Handler interfaces
|
|
|
|
### Proxy Module Files
|
|
- `ts/proxies/network-proxy/models/types.ts` - NetworkProxy interfaces
|
|
- `ts/proxies/smart-proxy/models/interfaces.ts` - SmartProxy interfaces
|
|
- `ts/proxies/nftables-proxy/models/interfaces.ts` - NfTables interfaces
|
|
- `ts/proxies/smart-proxy/connection-manager.ts` - Connection types
|
|
|
|
### HTTP/TLS Module Files
|
|
- `ts/http/models/http-types.ts` - HTTP module interfaces
|
|
- `ts/http/port80/acme-interfaces.ts` - ACME interfaces
|
|
- `ts/tls/sni/client-hello-parser.ts` - TLS parser types
|
|
- `ts/tls/alerts/tls-alert.ts` - TLS alert interfaces
|
|
|
|
## Success Criteria
|
|
|
|
- All interfaces are prefixed with "I"
|
|
- All type aliases are prefixed with "T"
|
|
- All tests pass with new naming conventions
|
|
- Documentation is updated with new naming conventions
|
|
- Backward compatibility is maintained through type aliases
|
|
- Declaration files correctly export both naming conventions |