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