smartproxy/changelog.md

Changelog

2025-12-09 - 22.1.1 - fix(tests)

Normalize route configurations in tests to use name (remove id) and standardize route names

• Removed deprecated id properties from route configurations in multiple tests and rely on the name property instead
• Standardized route.name values to kebab-case / lowercase (examples: 'tcp-forward', 'tls-passthrough', 'domain-a', 'domain-b', 'test-forward', 'nftables-test', 'regular-test', 'forward-test', 'test-forward', 'tls-test')
• Added explicit names for inner and outer proxies in proxy-chain-cleanup test ('inner-backend', 'outer-frontend')
• Updated certificate metadata timestamps in certs/static-route/meta.json

2025-12-09 - 22.1.0 - feat(smart-proxy)

Improve connection/rate-limit atomicity, SNI parsing, HttpProxy & ACME orchestration, and routing utilities

• Fix race conditions for per-IP connection limits by introducing atomic validate-and-track flow (SecurityManager.validateAndTrackIP) and propagating connectionId for atomic tracking.
• Add connection-manager createConnection options (connectionId, skipIpTracking) and avoid double-tracking IPs when validated atomically.
• RouteConnectionHandler now generates connection IDs earlier and uses atomic IP validation to prevent concurrent connection bypasses; cleans up IP tracking on global-limit rejects.
• Enhanced TLS SNI extraction and ClientHello parsing: robust fragmented ClientHello handling, PSK-based SNI extraction for TLS 1.3 resumption, tab-reactivation heuristics and improved logging (new client-hello-parser and sni-extraction modules).
• HttpProxy integration improvements: HttpProxyBridge initialized/synced from SmartProxy, forwardToHttpProxy forwards initial data and preserves client IP via CLIENT_IP header, robust handling of client disconnects during setup.
• Certificate manager (SmartCertManager) improvements: better ACME initialization sequence (deferred provisioning until ports are bound), improved challenge route add/remove handling, custom certificate provisioning hook, expiry handling fallback behavior and safer error messages for port conflicts.
• Route/port orchestration refactor (RouteOrchestrator): port usage mapping, safer add/remove port sequences, NFTables route lifecycle updates and certificate manager recreation on route changes.
• PortManager now refcounts ports and reuses existing listeners instead of rebinding; provides helpers to add/remove/update multiple ports and improved error handling for EADDRINUSE.
• Connection cleanup, inactivity and zombie detection hardened: batched cleanup queue, optimized inactivity checks, half-zombie detection and safer shutdown workflows.
• Metrics, routing helpers and validators: SharedRouteManager exposes expandPortRange/getListeningPorts, route helpers add convenience HTTPS/redirect/loadbalancer builders, route-validator domain rules relaxed to allow 'localhost', '*' and IPs, and tests updated accordingly.
• Tests updated to reflect behavioral changes (connection limit checks adapted to detect closed/ reset connections, HttpProxy integration test skipped in unit suite to avoid complex TLS setup).

2025-12-09 - 22.0.0 - BREAKING CHANGE(smart-proxy/utils/route-validator)

Consolidate and refactor route validators; move to class-based API and update usages

Replaced legacy route-validators.ts with a unified route-validator.ts that provides a class-based RouteValidator plus the previous functional API (isValidPort, isValidDomain, validateRouteMatch, validateRouteAction, validateRouteConfig, validateRoutes, hasRequiredPropertiesForAction, assertValidRoute) for backwards compatibility. Updated utils exports and all imports/tests to reference the new module. Also switched static file loading in certificate manager to use SmartFileFactory.nodeFs(), and added @push.rocks/smartserve to devDependencies.

• Rename and consolidate validator module: route-validators.ts removed; route-validator.ts added with RouteValidator class and duplicated functional API for compatibility.
• Updated exports in ts/proxies/smart-proxy/utils/index.ts and all internal imports/tests to reference './route-validator.js' instead of './route-validators.js'.
• Certificate manager now uses plugins.smartfile.SmartFileFactory.nodeFs() to load key/cert files (safer factory usage instead of direct static calls).
• Added @push.rocks/smartserve to devDependencies in package.json.
• Because the validator filename and some import paths changed, this is a breaking change for consumers importing the old module path.

2025-08-19 - 21.1.7 - fix(route-validator)

Relax domain validation to accept 'localhost', prefix wildcards (e.g. *example.com) and IP literals; add comprehensive domain validation tests

• Allow 'localhost' as a valid domain pattern in route validation
• Support prefix wildcard patterns like 'example.com' in addition to '.example.com'
• Accept IPv4 and IPv6 literal addresses in domain validation
• Add test coverage: new test/test.domain-validation.ts with many real-world and edge-case patterns

2025-08-19 - 21.1.6 - fix(ip-utils)

Fix IP wildcard/shorthand handling and add validation test

• Support shorthand IPv4 wildcard patterns (e.g. '10.', '192.168.') by expanding them to full 4-octet patterns before matching
• Normalize and expand patterns in IpUtils.isGlobIPMatch and SharedSecurityManager IP checks to ensure consistent minimatch comparisons
• Relax route validator wildcard checks to accept 1-4 octet wildcard specifications for IPv4 patterns
• Add test harness test-ip-validation.ts to exercise common wildcard/shorthand IP patterns

2025-08-19 - 21.1.5 - fix(core)

Prepare patch release: documentation, tests and stability fixes (metrics, ACME, connection cleanup)

• Byte counting and throughput: per-route and per-IP throughput trackers with per-second sampling; removed double-counting and improved sampling buffers for accurate rates
• HttpProxy and forwarding: Ensure metricsCollector.recordBytes() is called in forwarding paths so throughput is recorded reliably
• ACME / Certificate Manager: support for custom certProvisionFunction with configurable fallback to ACME (http01) and improved challenge route lifecycle
• Connection lifecycle and cleanup: improved lifecycle component timer/listener cleanup, better cleanup queue batching and zombie/half-zombie detection
• Various utilities and stability improvements: enhanced IP utils, path/domain matching improvements, safer socket handling and more robust fragment/ClientHello handling
• Tests and docs: many test files and readme.hints.md updated with byte-counting audit, connection cleanup and ACME guidance

2025-08-14 - 21.1.4 - fix(security)

Critical security and stability fixes

• Fixed critical socket.emit override vulnerability that was breaking TLS connections
• Implemented comprehensive socket cleanup with new socket tracker utility
• Improved code organization by extracting RouteOrchestrator from SmartProxy
• Fixed IPv6 loopback detection for proper IPv6 support
• Added memory bounds to prevent unbounded collection growth
• Fixed certificate manager race conditions with proper synchronization
• Unreferenced long-lived timers to prevent process hanging
• Enhanced route validation for socket-handler actions
• Fixed header parsing when extractFullHeaders option is enabled

2025-07-22 - 21.1.1 - fix(detection)

Fix SNI detection in TLS detector

• Restored proper TLS detector implementation with ClientHello parsing
• Fixed imports to use new protocols module locations
• Added missing detectWithContext method for fragmented detection
• Fixed method names to match BufferAccumulator interface
• Removed unused import readUInt24BE

2025-07-21 - 21.1.0 - feat(protocols)

Refactor protocol utilities into centralized protocols module

• Moved TLS utilities from ts/tls/ to ts/protocols/tls/
• Created centralized protocol modules for HTTP, WebSocket, Proxy, and TLS
• Core utilities now delegate to protocol modules for parsing and utilities
• Maintains backward compatibility through re-exports in original locations
• Improves code organization and separation of concerns

2025-07-22 - 21.0.0 - BREAKING_CHANGE(forwarding)

Remove legacy forwarding module

• Removed the forwarding namespace export from main index
• Removed TForwardingType and all forwarding handlers
• Consolidated route helper functions into route-helpers.ts
• All functionality is now available through the route-based system
• MIGRATION: Replace import { forwarding } from '@push.rocks/smartproxy' with direct imports of route helpers

2025-07-21 - 20.0.2 - fix(docs)

Update documentation to improve clarity

• Enhanced readme with clearer breaking change warning for v20.0.0
• Fixed example email address from ssl@bleu.de to ssl@example.com
• Added load balancing and failover features to feature list
• Improved documentation structure and examples

2025-07-20 - 20.0.1 - BREAKING_CHANGE(routing)

Refactor route configuration to support multiple targets

• Changed route action configuration from single target to targets array
• Enables load balancing and failover capabilities with multiple upstream targets
• Updated all test files to use new targets array syntax
• Automatic certificate metadata refresh

2025-06-01 - 19.5.19 - fix(smartproxy)

Fix connection handling and improve route matching edge cases

• Enhanced cleanup logic to prevent connection accumulation under rapid retry scenarios
• Improved matching for wildcard domains and path parameters in the route configuration
• Minor refactoring in async utilities and internal socket handling for better performance
• Updated test suites and documentation for clearer configuration examples

2025-05-29 - 19.5.3 - fix(smartproxy)

Fix route security configuration location and improve ACME timing tests and socket mock implementations

• Move route security from action.security to the top-level route.security to correctly enforce IP allow/block lists (addresses failing in test.route-security.ts)
• Update readme.problems.md to document the routing security configuration issue with proper instructions
• Adjust certificate metadata in certs/static-route/meta.json with updated timestamps
• Update test.acme-timing.ts to export default tap.start() instead of tap.start() to ensure proper parsing
• Improve socket simulation and event handling mocks in test.http-fix-verification.ts and test.http-forwarding-fix.ts to more reliably mimic net.Socket behavior
• Minor adjustments in multiple test files to ensure proper port binding, race condition handling and route lookups (e.g. getRoutesForPort implementation)

2025-05-29 - 19.5.2 - fix(test)

Fix ACME challenge route creation and HTTP request parsing in tests

• Replaced the legacy ACME email 'test@example.com' with 'test@acmetest.local' to avoid forbidden domain issues.
• Mocked the CertificateManager in test/test.acme-route-creation to simulate immediate ACME challenge route addition.
• Adjusted updateRoutes callback to capture and verify challenge route creation.
• Enhanced the HTTP request parsing in socket handler by capturing and asserting parsed request details (method, path, headers).

2025-05-29 - 19.5.1 - fix(socket-handler)

Fix socket handler race condition by differentiating between async and sync handlers. Now, async socket handlers complete their setup before initial data is emitted, ensuring that no data is lost. Documentation and tests have been updated to reflect this change.

• Added detailed explanation in readme.hints.md about the race condition issue, root cause, and solution implementation.
• Provided a code snippet that checks if the socket handler returns a Promise and waits for its resolution before emitting initial data.
• Updated tests (test.socket-handler-race.ts, test.socket-handler.simple.ts, test.socket-handler.ts) to verify correct behavior of async handlers.

2025-05-28 - 19.5.0 - feat(socket-handler)

Add socket-handler support for custom socket handling in SmartProxy

• Introduce new action type 'socket-handler' in IRouteAction to allow users to provide a custom socket handler function.
• Update the RouteConnectionHandler to detect 'socket-handler' actions and invoke the handler with the raw socket, giving full control to the user.
• Provide optional context (such as route configuration, client IP, and port) to the socket handler if needed.
• Add helper functions in route-helpers for creating socket handler routes and common patterns like echo, proxy, and line-based protocols.
• Include a detailed implementation plan and usage examples in readme.plan.md.

2025-05-28 - 19.4.3 - fix(smartproxy)

Improve port binding intelligence and ACME challenge route management; update route configuration tests and dependency versions.

• Bumped dev dependency versions in package.json (tsbuild from ^2.5.1 to ^2.6.4, tstest from ^1.9.0 to ^2.3.1, @types/node updated, smartfile from ^11.2.0 to ^11.2.5, smartlog from ^3.1.7 to ^3.1.8)
• Removed readme.plan.md containing legacy development plan information
• Normalized route configuration properties across tests (using 'ports' and 'domains' instead of legacy 'port' or 'domain')
• Enhanced PortManager with reference counting and smarter port conflict detection to avoid redundant bindings
• Refined ACME challenge route integration to merge with existing port bindings and improve error handling
• Adjusted test expectations (e.g. using toEqual instead of toBe, and improved timeout handling) to align with current API changes

2025-05-20 - 19.4.2 - fix(dependencies)

Update dependency versions: upgrade @types/node to ^22.15.20 and @push.rocks/smartlog to ^3.1.7 in package.json

• Bump @types/node from ^22.15.19 to ^22.15.20
• Bump @push.rocks/smartlog from ^3.1.3 to ^3.1.7

2025-05-20 - 19.4.1 - fix(smartproxy)

Bump @push.rocks/smartlog to ^3.1.3 and improve ACME port binding behavior in SmartProxy

• Updated package.json to use @push.rocks/smartlog version ^3.1.3
• Enhanced tests (test.http-port8080-simple.ts) to verify improved port binding intelligence for ACME challenge routes
• Ensured that existing port listeners are reused and not re-bound when updating routes

2025-05-20 - 19.4.0 - feat(certificate-manager, smart-proxy)

Improve port binding intelligence for ACME challenges

• Reordered SmartProxy initialization flow to bind ports before initializing the certificate manager
• Enhanced port binding logic to better handle ACME challenge routes
• Improved error detection and reporting for port binding conflicts
• Added better diagnostics for ACME challenge port issues
• Made route updates more intelligent with detailed port tracking
• Fixed race condition where ACME routes were added before port 80 was bound
• Added special handling for ACME port conflicts with improved error messages

2025-05-20 - 19.3.14 - fix(certificate-manager, smart-proxy)

Add error handling around logger calls in route update callback

• Added try/catch blocks around logger calls in certificate-manager.ts
• Added try/catch blocks around logger calls in smart-proxy.ts related to route updates
• Provided fallback to console.log when logger fails
• Ensured core route update functionality continues to work even if logging fails

2025-05-20 - 19.3.13 - fix(port-manager, certificate-manager)

Improve port binding and ACME challenge route integration in SmartProxy

• Added reference counting in PortManager so that routes sharing the same port reuse the existing binding.
• Enhanced error handling to distinguish internal port conflicts from external ones, with more descriptive messages.
• Adjusted ACME challenge route addition to merge with existing port bindings when port is already in use.
• Refactored updateRoutes to release orphaned ports and bind only new required ports, minimizing rebinding operations.
• Improved certificate-manager logic to provide clearer error notifications when ACME port conflicts occur.

2025-05-19 - 19.3.12 - fix(tests)

Update test mocks to include provisionAllCertificates methods in certificate manager stubs and related objects.

• Added async provisionAllCertificates functions to several test mocks (e.g. in test.port80-management.node.ts, test.route-callback-simple.ts, test.route-update-callback.node.ts, and test.simple-acme-mock.ts) to simulate ACME certificate provisioning.
• Enhanced logging and port-add history debugging for ACME challenge port addition.

2025-05-19 - 19.3.11 - fix(logger)

Replace raw console logging calls with structured logger usage across certificate management, connection handling, and route processing for improved observability.

• Replaced console.log, console.warn, and console.error in SmartCertManager with logger.log for more consistent logging.
• Updated ConnectionManager and RouteConnectionHandler to log detailed connection events using a structured logger.
• Enhanced logging statements with contextual metadata such as connection IDs, remote IPs, target information, and component identifiers.
• Standardized log output across proxy modules to aid in debugging and monitoring.

2025-05-19 - 19.3.10 - fix(certificate-manager, smart-proxy)

Fix race condition in ACME certificate provisioning and refactor certificate manager initialization to defer provisioning until after port listeners are active

• Removed superfluous provisionCertificatesAfterPortsReady method
• Made provisionAllCertificates public so that SmartProxy.start() calls it after ports are listening
• Updated SmartProxy.start() to wait for port setup (via PortManager) before triggering certificate provisioning
• Improved ACME HTTP-01 challenge timing so that port 80 (or configured ACME port) is guaranteed to be ready
• Updated documentation (changelog and Acme timing docs) and tests to reflect the change

2025-05-19 - 19.3.10 - refactor(certificate-manager, smart-proxy)

Simplify certificate provisioning code by removing unnecessary wrapper method

• Removed superfluous SmartCertManager.provisionCertificatesAfterPortsReady() method
• Made SmartCertManager.provisionAllCertificates() public instead
• Updated SmartProxy.start() to call provisionAllCertificates() directly
• Updated documentation and tests to reflect the change
• No functional changes, just code simplification

2025-05-19 - 19.3.9 - fix(certificate-manager, smart-proxy)

Fix ACME certificate provisioning timing to ensure ports are listening first

• Fixed race condition where certificate provisioning would start before ports were listening
• Modified SmartCertManager.initialize() to defer certificate provisioning
• Added SmartCertManager.provisionCertificatesAfterPortsReady() for delayed provisioning
• Updated SmartProxy.start() to call certificate provisioning after ports are ready