recker 1.0.2-0 → 1.0.3

package/dist/websocket/client.js

@@ -1,5 +1,8 @@
 import { WebSocket } from 'undici';
 import { EventEmitter } from 'events';
+import { pipeline } from 'node:stream/promises';
+import { webToNodeStream } from '../utils/streaming.js';
+import { ReckerError } from '../core/errors.js';
 export class ReckerWebSocket extends EventEmitter {
     ws = null;
     url;
@@ -9,6 +12,9 @@ export class ReckerWebSocket extends EventEmitter {
     heartbeatTimer;
     isClosed = false;
     isReconnecting = false;
+    pongWatchdog;
+    backoff;
+    closedByUser = false;
     constructor(url, options = {}) {
         super();
         this.url = url;
@@ -19,12 +25,38 @@ export class ReckerWebSocket extends EventEmitter {
             reconnectDelay: options.reconnectDelay ?? 1000,
             maxReconnectAttempts: options.maxReconnectAttempts ?? 5,
             heartbeatInterval: options.heartbeatInterval ?? 30000,
+            heartbeatTimeout: options.heartbeatTimeout ?? 10000,
+            dispatcher: options.dispatcher,
+            proxy: options.proxy,
+            tls: options.tls,
+            perMessageDeflate: options.perMessageDeflate ?? false
+        };
+        this.backoff = {
+            base: this.options.reconnectDelay,
+            factor: 2,
+            jitter: true,
+            max: 30000
         };
     }
     async connect() {
         return new Promise((resolve, reject) => {
             try {
-                this.ws = new WebSocket(this.url, this.options.protocols);
+                const wsOptions = {
+                    headers: this.options.headers,
+                    dispatcher: this.options.dispatcher,
+                    perMessageDeflate: this.options.perMessageDeflate,
+                };
+                if (this.options.proxy) {
+                    const proxyConfig = typeof this.options.proxy === 'string'
+                        ? { url: this.options.proxy }
+                        : this.options.proxy;
+                    const { ProxyAgent } = require('undici');
+                    wsOptions.dispatcher = new ProxyAgent(proxyConfig.url);
+                }
+                if (this.options.tls) {
+                    wsOptions.tls = this.options.tls;
+                }
+                this.ws = new WebSocket(this.url, this.options.protocols, wsOptions);
                 this.ws.addEventListener('open', () => {
                     this.reconnectAttempts = 0;
                     this.isReconnecting = false;
@@ -38,17 +70,26 @@ export class ReckerWebSocket extends EventEmitter {
                         isBinary: event.data instanceof Buffer
                     };
                     this.emit('message', message);
+                    this.stopPongWatchdog();
                 });
                 this.ws.addEventListener('close', (event) => {
                     this.stopHeartbeat();
+                    this.stopPongWatchdog();
                     this.emit('close', event.code, event.reason);
-                    if (!this.isClosed && this.options.reconnect) {
+                    if (!this.closedByUser && !this.isClosed && this.options.reconnect) {
                         this.attemptReconnect();
                     }
                 });
                 this.ws.addEventListener('error', (event) => {
-                    this.emit('error', event.error || new Error('WebSocket error'));
-                    reject(event.error || new Error('WebSocket connection failed'));
+                    const err = event.error instanceof Error
+                        ? event.error
+                        : new ReckerError('WebSocket connection error', undefined, undefined, [
+                            'Verify the WebSocket endpoint URL and protocol (ws/wss).',
+                            'Check proxy/TLS settings if connecting through a proxy.',
+                            'Inspect server logs for handshake failures.'
+                        ]);
+                    this.emit('error', err);
+                    reject(err);
                 });
             }
             catch (error) {
@@ -56,17 +97,32 @@ export class ReckerWebSocket extends EventEmitter {
             }
         });
     }
-    send(data) {
+    async send(data, options) {
         if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
-            throw new Error('WebSocket is not connected');
+            throw new ReckerError('WebSocket is not connected', undefined, undefined, [
+                'Call connect() before sending messages.',
+                'Listen to the open event to ensure the socket is ready.',
+                'Check for prior connection errors or closed states.'
+            ]);
         }
+        const awaitDrain = options?.awaitDrain ?? false;
+        const highWaterMark = options?.highWaterMark ?? 16 * 1024;
         this.ws.send(data);
+        if (awaitDrain) {
+            await this.waitForDrain(highWaterMark);
+        }
+    }
+    async sendStream(stream, options) {
+        for await (const chunk of stream) {
+            await this.send(chunk, options);
+        }
     }
     sendJSON(data) {
-        this.send(JSON.stringify(data));
+        void this.send(JSON.stringify(data));
     }
     close(code = 1000, reason = '') {
         this.isClosed = true;
+        this.closedByUser = true;
         this.stopHeartbeat();
         this.clearReconnectTimer();
         if (this.ws) {
@@ -75,13 +131,22 @@ export class ReckerWebSocket extends EventEmitter {
         }
     }
     ping() {
-        if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
+            return;
+        const anyWs = this.ws;
+        if (typeof anyWs.ping === 'function') {
             try {
-                this.ws.send('__heartbeat__');
+                anyWs.ping();
+                return;
             }
-            catch (e) {
+            catch {
             }
         }
+        try {
+            this.ws.send('__heartbeat__');
+        }
+        catch {
+        }
     }
     get readyState() {
         return this.ws?.readyState ?? WebSocket.CLOSED;
@@ -89,6 +154,29 @@ export class ReckerWebSocket extends EventEmitter {
     get isConnected() {
         return this.ws?.readyState === WebSocket.OPEN;
     }
+    toReadable() {
+        if (!this.ws)
+            return null;
+        const wsAny = this.ws;
+        if (wsAny.readable) {
+            return webToNodeStream(wsAny.readable);
+        }
+        return null;
+    }
+    async pipeFrom(source, options) {
+        await this.sendStream(source, options);
+    }
+    async pipeTo(destination) {
+        const readable = this.toReadable();
+        if (!readable) {
+            throw new ReckerError('WebSocket has no readable stream', undefined, undefined, [
+                'Ensure the WebSocket is connected before piping.',
+                'Verify the runtime supports readable streams on WebSocket.',
+                'Fallback to event-based message handling if streaming is unavailable.'
+            ]);
+        }
+        await pipeline(readable, destination);
+    }
     async *[Symbol.asyncIterator]() {
         const queue = [];
         let resolveNext = null;
@@ -146,13 +234,15 @@ export class ReckerWebSocket extends EventEmitter {
         }
         this.isReconnecting = true;
         this.reconnectAttempts++;
-        const delay = this.options.reconnectDelay * Math.pow(2, this.reconnectAttempts - 1);
-        this.emit('reconnecting', this.reconnectAttempts, delay);
+        const baseDelay = this.backoff.base * Math.pow(this.backoff.factor, this.reconnectAttempts - 1);
+        const capped = this.backoff.max ? Math.min(baseDelay, this.backoff.max) : baseDelay;
+        const jittered = this.backoff.jitter ? randomJitter(capped) : capped;
+        this.emit('reconnecting', this.reconnectAttempts, jittered);
         this.reconnectTimer = setTimeout(() => {
             this.connect().catch((error) => {
                 this.emit('reconnect-error', error);
             });
-        }, delay);
+        }, jittered);
     }
     clearReconnectTimer() {
         if (this.reconnectTimer) {
@@ -166,6 +256,7 @@ export class ReckerWebSocket extends EventEmitter {
         this.heartbeatTimer = setInterval(() => {
             if (this.isConnected) {
                 this.ping();
+                this.startPongWatchdog();
             }
         }, this.options.heartbeatInterval);
     }
@@ -174,6 +265,43 @@ export class ReckerWebSocket extends EventEmitter {
             clearInterval(this.heartbeatTimer);
             this.heartbeatTimer = undefined;
         }
+        this.stopPongWatchdog();
+    }
+    startPongWatchdog() {
+        this.stopPongWatchdog();
+        if (this.options.heartbeatTimeout <= 0)
+            return;
+        this.pongWatchdog = setTimeout(() => {
+            this.emit('heartbeat-timeout');
+            if (!this.closedByUser && this.options.reconnect) {
+                this.ws?.close(4000, 'heartbeat timeout');
+            }
+        }, this.options.heartbeatTimeout);
+    }
+    stopPongWatchdog() {
+        if (this.pongWatchdog) {
+            clearTimeout(this.pongWatchdog);
+            this.pongWatchdog = undefined;
+        }
+    }
+    getBufferedAmount() {
+        return this.ws?.bufferedAmount ?? 0;
+    }
+    async waitForDrain(highWaterMark) {
+        const buffered = this.getBufferedAmount();
+        if (buffered <= highWaterMark)
+            return;
+        await new Promise((resolve) => {
+            const check = () => {
+                if (this.getBufferedAmount() <= highWaterMark || !this.isConnected) {
+                    resolve();
+                }
+                else {
+                    setTimeout(check, 10);
+                }
+            };
+            setTimeout(check, 10);
+        });
     }
 }
 export function websocket(url, options) {
@@ -182,3 +310,7 @@ export function websocket(url, options) {
     });
     return ws;
 }
+function randomJitter(value) {
+    const jitter = 0.2 * value;
+    return value - jitter + Math.random() * (2 * jitter);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "recker",
-  "version": "1.0.2-0",
+  "version": "1.0.3",
   "description": "AI & DevX focused HTTP client for Node.js 18+",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -26,9 +26,12 @@
     "whois",
     "dns",
     "proxy",
-    "ai"
+    "ai",
+    "scraping",
+    "cheerio",
+    "html-parser"
   ],
-  "author": "Forattini Dev",
+  "author": "fforattini",
   "license": "MIT",
   "homepage": "https://forattini-dev.github.io/recker",
   "repository": {
@@ -53,10 +56,22 @@
       "types": "./dist/core/client.d.ts",
       "import": "./dist/core/client.js"
     },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
+    },
+    "./presets": {
+      "types": "./dist/presets/index.d.ts",
+      "import": "./dist/presets/index.js"
+    },
     "./plugins/*": {
       "types": "./dist/plugins/*.d.ts",
       "import": "./dist/plugins/*.js"
     },
+    "./scrape": {
+      "types": "./dist/scrape/index.d.ts",
+      "import": "./dist/scrape/index.js"
+    },
     "./utils/*": {
       "types": "./dist/utils/*.d.ts",
       "import": "./dist/utils/*.js"
@@ -70,20 +85,41 @@
     "access": "public"
   },
   "dependencies": {
+    "basic-ftp": "^5.0.5",
+    "glob": "^13.0.0",
+    "ssh2-sftp-client": "^12.0.1",
+    "telnet-client": "^2.2.9",
     "undici": "^7.16.0",
     "zod": "^4.1.13"
   },
+  "peerDependencies": {
+    "cheerio": "^1.0.0",
+    "ioredis": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "cheerio": {
+      "optional": true
+    },
+    "ioredis": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@types/needle": "^3.3.0",
     "@types/node": "^24.10.1",
+    "@types/ssh2-sftp-client": "^9.0.5",
+    "@types/superagent": "^8.1.9",
     "@vitest/coverage-v8": "^3.2.4",
     "axios": "^1.13.2",
-    "docsify-darklight-theme": "^3.2.0",
-    "docsify-mermaid": "^2.0.1",
+    "cheerio": "^1.0.0",
+    "docsify-cli": "^4.4.4",
+    "domhandler": "^5.0.3",
     "got": "^14.6.5",
     "husky": "^9.1.7",
     "ky": "^1.14.0",
-    "mermaid": "^11.12.1",
     "mitata": "^1.0.34",
+    "needle": "^3.3.1",
+    "superagent": "^10.2.3",
     "tsx": "^4.20.6",
     "typescript": "^5.9.3",
     "vitest": "^3.2.4"
@@ -94,7 +130,8 @@
     "test:coverage": "vitest run --coverage",
     "bench": "tsx benchmark/index.ts",
     "bench:all": "tsx benchmark/run-all.ts",
-    "docs:dev": "npx -y docsify-cli serve docs --port 3000",
-    "docs:preview": "npx -y docsify-cli serve docs --port 3000 --open"
+    "docs:dev": "docsify serve docs --port 3000",
+    "docs:preview": "npx -y docsify-cli serve docs --port 3000 --open",
+    "lint": "echo \"No linting configured for this project.\" && exit 0"
   }
 }