From fc13e894935977251bfe151c18259f83409e504a Mon Sep 17 00:00:00 2001
From: Aditya Agarwal <itsmeadityaagarwal@gmail.com>
Date: Wed, 6 May 2026 12:43:05 +0200
Subject: [PATCH] feat: make node agent keep-alive settings configurable

Expose Node HTTP/HTTPS agent options in ClientOptions so integrators can tune keep-alive behavior and socket pool limits to reduce EMFILE risk under load.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 src/client.ts                 | 24 +++++++++++++++++--
 test/unit/node/client_test.js | 43 +++++++++++++++++++++++++++++++++++
 2 files changed, 65 insertions(+), 2 deletions(-)

diff --git a/src/client.ts b/src/client.ts
index 4e1531e1..7c47fa63 100644
--- a/src/client.ts
+++ b/src/client.ts
@@ -61,10 +61,16 @@ export type ClientOptions = {
   expireTokens?: boolean;
   fayeUrl?: string;
   group?: string;
+  httpAgent?: http.Agent;
+  httpsAgent?: https.Agent;
   keepAlive?: boolean;
+  keepAliveMsecs?: number;
   local?: boolean;
   location?: string;
+  maxFreeSockets?: number;
+  maxSockets?: number;
   protocol?: string;
+  scheduling?: 'fifo' | 'lifo';
   timeout?: number;
   urlOverride?: Record<string, string>;
   version?: string;
@@ -272,9 +278,23 @@ export class StreamClient<StreamFeedGenerics extends DefaultGenerics = DefaultGe
 
     if (this.node) {
       const keepAlive = this.options.keepAlive === undefined ? true : this.options.keepAlive;
+      const keepAliveMsecs = this.options.keepAliveMsecs ?? 3000;
+      const agentOptions: http.AgentOptions = {
+        keepAlive,
+        keepAliveMsecs,
+      };
+      if (this.options.maxSockets !== undefined) {
+        agentOptions.maxSockets = this.options.maxSockets;
+      }
+      if (this.options.maxFreeSockets !== undefined) {
+        agentOptions.maxFreeSockets = this.options.maxFreeSockets;
+      }
+      if (this.options.scheduling !== undefined) {
+        agentOptions.scheduling = this.options.scheduling;
+      }
       this.nodeOptions = {
-        httpAgent: new http.Agent({ keepAlive, keepAliveMsecs: 3000 }),
-        httpsAgent: new https.Agent({ keepAlive, keepAliveMsecs: 3000 }),
+        httpAgent: this.options.httpAgent ?? new http.Agent(agentOptions),
+        httpsAgent: this.options.httpsAgent ?? new https.Agent(agentOptions),
       };
     }
 
diff --git a/test/unit/node/client_test.js b/test/unit/node/client_test.js
index 622288cf..e714eb57 100644
--- a/test/unit/node/client_test.js
+++ b/test/unit/node/client_test.js
@@ -2,6 +2,8 @@ import expect from 'expect.js';
 import * as td from 'testdouble';
 import { jwtDecode } from 'jwt-decode';
 import { createRequire } from 'node:module';
+import * as http from 'node:http';
+import * as https from 'node:https';
 import { connect, StreamClient, StreamFeed } from '../../../src';
 import { beforeEachFn } from '../utils/hooks';
 
@@ -16,6 +18,47 @@ describe('[UNIT] Stream Client instantiation (Node)', function () {
   it('without secret', function () {
     new StreamClient('stub-key', null, 9498); // eslint-disable-line no-new
   });
+
+  it('uses default node agent options', function () {
+    const client = new StreamClient('stub-key', 'stub-secret', 9498);
+    expect(client.nodeOptions?.httpAgent.options.keepAlive).to.be(true);
+    expect(client.nodeOptions?.httpsAgent.options.keepAlive).to.be(true);
+    expect(client.nodeOptions?.httpAgent.options.keepAliveMsecs).to.be(3000);
+    expect(client.nodeOptions?.httpsAgent.options.keepAliveMsecs).to.be(3000);
+  });
+
+  it('supports configurable node agent options', function () {
+    const client = new StreamClient('stub-key', 'stub-secret', 9498, {
+      keepAlive: false,
+      keepAliveMsecs: 12345,
+      maxSockets: 10,
+      maxFreeSockets: 5,
+      scheduling: 'lifo',
+    });
+
+    expect(client.nodeOptions?.httpAgent.options.keepAlive).to.be(false);
+    expect(client.nodeOptions?.httpsAgent.options.keepAlive).to.be(false);
+    expect(client.nodeOptions?.httpAgent.options.keepAliveMsecs).to.be(12345);
+    expect(client.nodeOptions?.httpsAgent.options.keepAliveMsecs).to.be(12345);
+    expect(client.nodeOptions?.httpAgent.options.maxSockets).to.be(10);
+    expect(client.nodeOptions?.httpsAgent.options.maxSockets).to.be(10);
+    expect(client.nodeOptions?.httpAgent.options.maxFreeSockets).to.be(5);
+    expect(client.nodeOptions?.httpsAgent.options.maxFreeSockets).to.be(5);
+    expect(client.nodeOptions?.httpAgent.options.scheduling).to.be('lifo');
+    expect(client.nodeOptions?.httpsAgent.options.scheduling).to.be('lifo');
+  });
+
+  it('supports custom node agents', function () {
+    const httpAgent = new http.Agent({ keepAlive: true, keepAliveMsecs: 9000 });
+    const httpsAgent = new https.Agent({ keepAlive: true, keepAliveMsecs: 9000 });
+    const client = new StreamClient('stub-key', 'stub-secret', 9498, {
+      httpAgent,
+      httpsAgent,
+    });
+
+    expect(client.nodeOptions?.httpAgent).to.be(httpAgent);
+    expect(client.nodeOptions?.httpsAgent).to.be(httpsAgent);
+  });
 });
 
 describe('[UNIT] Stream Client (Node)', function () {