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`:
  ```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.