64 lines
3.3 KiB
Markdown
64 lines
3.3 KiB
Markdown
# 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. |