smartproxy/readme.hints.md

SmartProxy Project Hints

Project Overview

• Package: @push.rocks/smartproxy – high-performance proxy supporting HTTP(S), TCP, WebSocket, and ACME integration.
• Written in TypeScript, compiled output in dist_ts/, uses ESM with NodeNext resolution.

Repository Structure

• ts/ – TypeScript source files:
  • index.ts exports main modules.
  • plugins.ts centralizes native and third-party imports.
  • Subdirectories: networkproxy/, nftablesproxy/, port80handler/, redirect/, smartproxy/.
  • Key classes: ProxyRouter (classes.router.ts), SmartProxy (classes.smartproxy.ts), plus handlers/managers.
• dist_ts/ – transpiled .js and .d.ts files mirroring ts/ structure.
• test/ – test suites in TypeScript:
  • test.router.ts – routing logic (hostname matching, wildcards, path parameters, config management).
  • test.smartproxy.ts – proxy behavior tests (TCP forwarding, SNI handling, concurrency, chaining, timeouts).
  • test/helpers/ – utilities (e.g., certificates).
• assets/certs/ – placeholder certificates for ACME and TLS.

Development Setup

• Requires pnpm (v10+).
• Install dependencies: pnpm install.
• Build: pnpm build (runs tsbuild --web --allowimplicitany).
• Test: pnpm test (runs tstest test/).
• Format: pnpm format (runs gitzone format).

Testing Framework

• Uses @push.rocks/tapbundle (tap, expect, expactAsync).
• Test files: must start with test. and use .ts extension.
• Run specific tests via tsx, e.g., tsx test/test.router.ts.

Coding Conventions

• Import modules via plugins.ts:

  import * as plugins from './plugins.ts';
  const server = new plugins.http.Server();
  

• Reference plugins with full path: plugins.acme, plugins.smartdelay, plugins.minimatch, etc.
• Path patterns support globs (*) and parameters (:param) in ProxyRouter.
• Wildcard hostname matching leverages minimatch patterns.

Key Components

• ProxyRouter
  • Methods: routeReq, routeReqWithDetails.
  • Hostname matching: case-insensitive, strips port, supports exact, wildcard, TLD, complex patterns.
  • Path routing: exact, wildcard, parameter extraction (pathParams), returns pathMatch and pathRemainder.
  • Config API: setNewProxyConfigs, addProxyConfig, removeProxyConfig, getHostnames, getProxyConfigs.
• SmartProxy
  • Manages one or more net.Server instances to forward TCP streams.
  • Options: preserveSourceIP, defaultAllowedIPs, globalPortRanges, sniEnabled.
  • DomainConfigManager: round-robin selection for multiple target IPs.
  • Graceful shutdown in stop(), ensures no lingering servers or sockets.

Notable Points

• TSConfig: module: NodeNext, verbatimModuleSyntax, allows .js extension imports in TS.
• Mermaid diagrams and architecture flows in readme.md illustrate component interactions and protocol flows.
• CLI entrypoint (cli.js) supports command-line usage (ACME, proxy controls).
• ACME and certificate handling via Port80Handler and helpers.certificates.ts.

TODOs / Considerations

• Ensure import extensions in source match build outputs (.ts vs .js).
• Update plugins.ts when adding new dependencies.
• Maintain test coverage for new routing or proxy features.
• Keep ts/ and dist_ts/ in sync after refactors.