7.1.3

changelog.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 2025-04-28 - 7.1.3 - fix(docs)
+Update project hints documentation in readme.hints.md
+
+- Added comprehensive hints covering project overview, repository structure, and development setup.
+- Outlined testing framework, coding conventions, and key components including ProxyRouter and SmartProxy.
+- Included detailed information on TSConfig settings, Mermaid diagrams, CLI usage, and future TODOs.
+
+## 2025-04-19 - 7.1.2 - fix(networkproxy/requesthandler)
+Improve HTTP/2 request handling and error management in the proxy request handler; add try-catch around routing and update header processing to support per-backend protocol overrides.
+
+- Wrapped the routing call (router.routeReq) in a try-catch block to better handle errors and missing host headers.
+- Returns a 500 error and increments failure metrics if routing fails.
+- Refactored HTTP/2 branch to copy all headers appropriately and map response headers into HTTP/1 response.
+- Added support for per-backend protocol override via the new backendProtocol option in IReverseProxyConfig.
+
 ## 2025-04-19 - 7.1.1 - fix(commit-info)
 Update commit metadata and synchronize project configuration (no code changes)
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartproxy",
-  "version": "7.1.1",
+  "version": "7.1.3",
   "private": false,
   "description": "A powerful proxy package that effectively handles high traffic, with features such as SSL/TLS support, port proxying, WebSocket handling, dynamic routing with authentication options, and automatic ACME certificate management.",
   "main": "dist_ts/index.js",

readme.hints.md

@@ -1 +1,64 @@
- 
+# 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.

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartproxy',
-  version: '7.1.1',
+  version: '7.1.3',
   description: 'A powerful proxy package that effectively handles high traffic, with features such as SSL/TLS support, port proxying, WebSocket handling, dynamic routing with authentication options, and automatic ACME certificate management.'
 }

ts/networkproxy/classes.np.requesthandler.ts

@@ -132,23 +132,32 @@ export class RequestHandler {
     
     // Apply default headers
     this.applyDefaultHeaders(res);
-    // If configured to proxy to backends over HTTP/2, use HTTP/2 client sessions
-    if (this.options.backendProtocol === 'http2') {
-      // Route and validate config
-      const proxyConfig = this.router.routeReq(req);
-      if (!proxyConfig) {
-        this.logger.warn(`No proxy configuration for host: ${req.headers.host}`);
-        res.statusCode = 404;
-        res.end('Not Found: No proxy configuration for this host');
-        if (this.metricsTracker) this.metricsTracker.incrementFailedRequests();
-        return;
-      }
-      // Determine backend target
+    
+    // Determine routing configuration
+    let proxyConfig: IReverseProxyConfig | undefined;
+    try {
+      proxyConfig = this.router.routeReq(req);
+    } catch (err) {
+      this.logger.error('Error routing request', err);
+      res.statusCode = 500;
+      res.end('Internal Server Error');
+      if (this.metricsTracker) this.metricsTracker.incrementFailedRequests();
+      return;
+    }
+    if (!proxyConfig) {
+      this.logger.warn(`No proxy configuration for host: ${req.headers.host}`);
+      res.statusCode = 404;
+      res.end('Not Found: No proxy configuration for this host');
+      if (this.metricsTracker) this.metricsTracker.incrementFailedRequests();
+      return;
+    }
+    // Determine protocol to backend (per-domain override or global)
+    const backendProto = proxyConfig.backendProtocol || this.options.backendProtocol;
+    if (backendProto === 'http2') {
       const destination = this.connectionPool.getNextTarget(
         proxyConfig.destinationIps,
         proxyConfig.destinationPorts[0]
       );
-      // Obtain or create HTTP/2 session
       const key = `${destination.host}:${destination.port}`;
       let session = this.h2Sessions.get(key);
       if (!session || session.closed || (session as any).destroyed) {
@@ -158,40 +167,30 @@ export class RequestHandler {
         session.on('close', () => this.h2Sessions.delete(key));
       }
       // Build headers for HTTP/2 request
-      const h2Headers: Record<string, string> = {
-        ':method': req.method || 'GET',
-        ':path': req.url || '/',
+      const hdrs: Record<string, any> = {
+        ':method': req.method,
+        ':path': req.url,
         ':authority': `${destination.host}:${destination.port}`
       };
-      for (const [k, v] of Object.entries(req.headers)) {
-        if (typeof v === 'string' && !k.startsWith(':')) {
-          h2Headers[k] = v;
-        }
+      for (const [hk, hv] of Object.entries(req.headers)) {
+        if (typeof hv === 'string') hdrs[hk] = hv;
       }
-      // Open HTTP/2 stream
-      const h2Stream = session.request(h2Headers);
-      // Pipe client request body to backend
+      const h2Stream = session.request(hdrs);
       req.pipe(h2Stream);
-      // Handle backend response
-      h2Stream.on('response', (headers, flags) => {
-        const status = headers[':status'] as number || 502;
-        // Map headers
-        for (const [hk, hv] of Object.entries(headers)) {
-          if (!hk.startsWith(':') && hv) {
-            res.setHeader(hk, hv as string);
+      h2Stream.on('response', (hdrs2: any) => {
+        const status = (hdrs2[':status'] as number) || 502;
+        res.statusCode = status;
+        // Copy headers from HTTP/2 response to HTTP/1 response
+        for (const [hk, hv] of Object.entries(hdrs2)) {
+          if (!hk.startsWith(':') && hv != null) {
+            res.setHeader(hk, hv as string | string[]);
           }
         }
-        res.statusCode = status;
         h2Stream.pipe(res);
       });
       h2Stream.on('error', (err) => {
-        this.logger.error(`HTTP/2 proxy error: ${err.message}`);
-        if (!res.headersSent) {
-          res.statusCode = 502;
-          res.end(`Bad Gateway: ${err.message}`);
-        } else {
-          res.end();
-        }
+        res.statusCode = 502;
+        res.end(`Bad Gateway: ${err.message}`);
         if (this.metricsTracker) this.metricsTracker.incrementFailedRequests();
       });
       return;

ts/networkproxy/classes.np.types.ts

@@ -60,6 +60,11 @@ export interface IReverseProxyConfig {
     pass: string;
   };
   rewriteHostHeader?: boolean;
+  /**
+   * Protocol to use when proxying to this backend: 'http1' or 'http2'.
+   * Overrides the global backendProtocol option if set.
+   */
+  backendProtocol?: 'http1' | 'http2';
 }
 
 /**