smartproxy/readme.plan.md

# 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