fable 3.1.70 → 3.1.72

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fable",
-  "version": "3.1.70",
+  "version": "3.1.72",
   "description": "A service dependency injection, configuration and logging library.",
   "main": "source/Fable.js",
   "scripts": {
@@ -52,7 +52,7 @@
   "homepage": "https://github.com/stevenvelozo/fable",
   "devDependencies": {
     "pict-docuserve": "^0.1.5",
-    "quackage": "^1.1.0"
+    "quackage": "^1.2.3"
   },
   "dependencies": {
     "async.eachlimit": "^0.5.2",
@@ -65,7 +65,7 @@
     "fable-log": "^3.0.18",
     "fable-serviceproviderbase": "^3.0.19",
     "fable-settings": "^3.0.16",
-    "fable-uuid": "^3.0.13",
+    "fable-uuid": "^3.0.14",
     "manyfest": "^1.0.49",
     "simple-get": "^4.0.1"
   }

package/source/services/Fable-Service-RestClient.js

@@ -27,42 +27,83 @@ class FableServiceRestClient extends libFableServiceBase
 		// of the request options before they are passed to the request library.
 		this.prepareRequestOptions = (pOptions) => { return pOptions; };
 
-		// Check for keep-alive configuration (from options or fable settings)
-		// Useful in environments where connections are slow to establish
-		// (e.g. inside poorly configured customer networks / VPNs)
-		let tmpKeepAlive = this.options.KeepAlive || this.fable.settings.RestClientKeepAlive;
+		// Default per-request timeout (ms). Applied in preRequest when a caller
+		// does not supply their own. Node 20+ installs a ~5s socket timeout on
+		// http.globalAgent that aborts legitimately long-running requests; any
+		// explicit `timeout` on the request options takes that default out of
+		// play. See the "Request Timeout" test suite for the behaviors covered.
+		if (typeof this.options.RequestTimeout === 'number')
+		{
+			this.defaultRequestTimeout = this.options.RequestTimeout;
+		}
+		else if (typeof this.fable.settings.RestClientRequestTimeout === 'number')
+		{
+			this.defaultRequestTimeout = this.fable.settings.RestClientRequestTimeout;
+		}
+		else
+		{
+			this.defaultRequestTimeout = 60000;
+		}
+
+		// Always install our own http/https agents so every request bypasses
+		// http.globalAgent (and its Node 20+ mystery socket timeout). The
+		// KeepAlive flag only controls whether keepAlive is enabled on our own
+		// agents, not whether we have agents at all. Additional tuning
+		// (maxSockets, agent timeout, etc.) flows through KeepAliveAgentOptions.
+		let tmpKeepAlive = Boolean(this.options.KeepAlive || this.fable.settings.RestClientKeepAlive);
+		let tmpAgentOptions = Object.assign({}, this.options.KeepAliveAgentOptions);
 		if (tmpKeepAlive)
 		{
-			this.initializeKeepAliveAgent(this.options.KeepAliveAgentOptions);
+			tmpAgentOptions.keepAlive = true;
 		}
+		this._installHttpAgents(tmpAgentOptions);
 	}
 
 	/**
 	 * Initialize HTTP keep-alive agents and wire them into prepareRequestOptions.
-	 * Creates both an HTTP and HTTPS agent so the correct one is selected per-request
-	 * based on the URL protocol.
+	 * Back-compat entry point: always forces keepAlive on. Prefer configuring
+	 * the RestClient via the KeepAlive / KeepAliveAgentOptions constructor
+	 * options instead of calling this method directly.
 	 *
 	 * @param {Object} [pAgentOptions] - Additional options passed to the Http/Https Agent constructors (e.g. timeout).
 	 */
 	initializeKeepAliveAgent(pAgentOptions)
 	{
 		let tmpAgentOptions = Object.assign({ keepAlive: true }, pAgentOptions);
+		this._installHttpAgents(tmpAgentOptions);
+	}
 
-		this.httpAgent = new libHttp.Agent(tmpAgentOptions);
-		this.httpsAgent = new libHttps.Agent(tmpAgentOptions);
+	/**
+	 * Construct http/https Agents from the given options and wire them into
+	 * prepareRequestOptions so every request carries an explicit agent.
+	 *
+	 * @param {Object} pAgentOptions - Options passed directly to the Http/Https Agent constructors.
+	 * @private
+	 */
+	_installHttpAgents(pAgentOptions)
+	{
+		this.httpAgent = new libHttp.Agent(pAgentOptions);
+		this.httpsAgent = new libHttps.Agent(pAgentOptions);
 
 		// Capture any previously set prepareRequestOptions so we can chain
 		let tmpPreviousPrepareRequestOptions = this.prepareRequestOptions;
 
 		this.prepareRequestOptions = (pOptions) =>
 		{
-			if (typeof pOptions.url === 'string' && pOptions.url.startsWith('http:'))
+			// Mirror simple-get's protocol decision exactly: it routes through
+			// the https module if and only if the parsed URL protocol is
+			// exactly 'https:'. Everything else — http: URLs, relative URLs
+			// (which simple-get treats as no-host http requests), and option
+			// objects with no .url at all — goes through the http module.
+			// Stamping an httpsAgent on an http request makes Node throw
+			// ERR_INVALID_PROTOCOL when http.request validates agent.protocol.
+			if (typeof pOptions.url === 'string' && pOptions.url.startsWith('https:'))
 			{
-				pOptions.agent = this.httpAgent;
+				pOptions.agent = this.httpsAgent;
 			}
 			else
 			{
-				pOptions.agent = this.httpsAgent;
+				pOptions.agent = this.httpAgent;
 			}
 			return tmpPreviousPrepareRequestOptions(pOptions);
 		};
@@ -103,9 +144,207 @@ class FableServiceRestClient extends libFableServiceBase
 			tmpOptions.url = this.fable.settings.RestClientURLPrefix + tmpOptions.url;
 		}
 
+		// Apply the default request timeout when the caller hasn't supplied
+		// one. Setting any numeric value (including 0) suppresses the Node 20+
+		// http.globalAgent ~5s socket timeout.
+		if (typeof tmpOptions.timeout !== 'number')
+		{
+			tmpOptions.timeout = this.defaultRequestTimeout;
+		}
+
 		return this.prepareRequestOptions(tmpOptions);
 	}
 
+	/**
+	 * Extract the hostname from a URL string. Returns null for relative URLs
+	 * or anything else that doesn't parse cleanly.
+	 *
+	 * @private
+	 * @param {string} pUrl
+	 * @return {string|null}
+	 */
+	_parseHostname(pUrl)
+	{
+		if (typeof pUrl !== 'string')
+		{
+			return null;
+		}
+		try
+		{
+			return new URL(pUrl).hostname || null;
+		}
+		catch (e)
+		{
+			return null;
+		}
+	}
+
+	/**
+	 * Resolve a Location header against the URL of the request that produced
+	 * it. Handles absolute Locations (returned as-is) and RFC 7231-compliant
+	 * relative Locations (resolved against the current URL).
+	 *
+	 * @private
+	 * @param {string} pCurrentURL - The URL of the request that produced the redirect.
+	 * @param {string} pLocation - The Location header value.
+	 * @return {string}
+	 */
+	_resolveRedirectURL(pCurrentURL, pLocation)
+	{
+		if (typeof pLocation !== 'string' || pLocation.length === 0)
+		{
+			return pLocation;
+		}
+		try
+		{
+			return new URL(pLocation, pCurrentURL).toString();
+		}
+		catch (e)
+		{
+			// Either pCurrentURL is itself relative or pLocation is malformed.
+			// Fall back to passing it through verbatim — simple-get's parser
+			// will give the next hop a final say.
+			return pLocation;
+		}
+	}
+
+	/**
+	 * Build the options object for the next hop of a redirect chain. Applies
+	 * the same hop-rewrite rules simple-get does, plus an RFC-correct relative
+	 * Location resolution that simple-get itself doesn't do:
+	 *   - Resolve the Location against the current URL (absolute or relative).
+	 *   - Strip simple-get's URL-derived state (protocol/hostname/port/path/auth)
+	 *     so the next hop re-parses the URL cleanly.
+	 *   - Drop the host header (re-derived from the new URL by simple-get).
+	 *   - Cross-origin: drop cookie + authorization to prevent leak.
+	 *   - 301/302 + POST: switch to GET, drop body and content headers.
+	 *
+	 * @private
+	 * @param {Object} pOptions - The options used for the previous hop (post-simple-get mutation).
+	 * @param {import('http').IncomingMessage} pResponse - The 3xx response.
+	 * @param {string|undefined} pOriginalURL - The URL of the previous hop, captured before simple-get deleted it.
+	 * @param {string|null} pOriginalHost - The hostname of the previous hop, for cross-origin detection.
+	 * @return {Object}
+	 */
+	_buildRedirectedOptions(pOptions, pResponse, pOriginalURL, pOriginalHost)
+	{
+		const tmpNew = Object.assign({}, pOptions);
+		tmpNew.url = this._resolveRedirectURL(pOriginalURL, pResponse.headers.location);
+
+		// Strip simple-get's own URL-derived fields so the next call re-parses cleanly.
+		delete tmpNew.protocol;
+		delete tmpNew.hostname;
+		delete tmpNew.port;
+		delete tmpNew.path;
+		delete tmpNew.auth;
+
+		// We set followRedirects=false on the previous hop to disable
+		// simple-get's auto-follow; that's our own internal flag, not caller
+		// intent. Drop it so the recursive _executeWithRedirects entry treats
+		// the next hop as another redirect-following call.
+		delete tmpNew.followRedirects;
+
+		// Headers — clone (don't mutate the caller's) and prune.
+		if (tmpNew.headers)
+		{
+			tmpNew.headers = Object.assign({}, tmpNew.headers);
+			delete tmpNew.headers.host;
+		}
+
+		// Cross-origin redirect: drop cookie and authorization to prevent leak (matches simple-get #73).
+		const tmpRedirectHost = this._parseHostname(tmpNew.url);
+		if (tmpRedirectHost !== null && tmpRedirectHost !== pOriginalHost && tmpNew.headers)
+		{
+			delete tmpNew.headers.cookie;
+			delete tmpNew.headers.authorization;
+		}
+
+		// 301/302 + POST → GET (matches simple-get #35 and RFC 7231 §6.4.2/6.4.3).
+		// Body and content headers come off; 307/308 preserve method/body so we leave them alone.
+		if (tmpNew.method === 'POST' && (pResponse.statusCode === 301 || pResponse.statusCode === 302))
+		{
+			tmpNew.method = 'GET';
+			if (tmpNew.headers)
+			{
+				delete tmpNew.headers['content-length'];
+				delete tmpNew.headers['content-type'];
+			}
+			delete tmpNew.body;
+			delete tmpNew.form;
+		}
+
+		return tmpNew;
+	}
+
+	/**
+	 * Dispatch a request via simple-get, transparently following 3xx redirects
+	 * until a non-redirect response or hard error.
+	 *
+	 * Why we drive the loop ourselves: simple-get's own redirect path
+	 * (index.js lines 50-69) recurses with the original opts.agent intact, so
+	 * an http→https redirect ends up calling https.request with an httpAgent
+	 * (or vice versa) and Node throws ERR_INVALID_PROTOCOL synchronously.
+	 * By disabling simple-get's auto-follow and running prepareRequestOptions
+	 * on each hop, the agent gets re-picked to match the new URL's protocol.
+	 *
+	 * Caller can opt out by setting `followRedirects: false` on options
+	 * (matches simple-get's contract) — in that case we hand the 3xx straight
+	 * back without following.
+	 *
+	 * @private
+	 * @param {Object} pOptions - Already passed through preRequest on the first call; on recursion, already passed through prepareRequestOptions.
+	 * @param {(err?: Error, res?: import('http').IncomingMessage) => void} fCallback
+	 */
+	_executeWithRedirects(pOptions, fCallback)
+	{
+		if (pOptions.followRedirects === false)
+		{
+			return libSimpleGet(pOptions, fCallback);
+		}
+
+		// Disable simple-get's own redirect loop — we own it from here.
+		pOptions.followRedirects = false;
+		const tmpOriginalURL = pOptions.url;
+		const tmpOriginalHost = this._parseHostname(tmpOriginalURL);
+
+		return libSimpleGet(pOptions, (pError, pResponse) =>
+		{
+			if (pError)
+			{
+				return fCallback(pError, pResponse);
+			}
+
+			if (pResponse.statusCode < 300 || pResponse.statusCode >= 400 || !pResponse.headers.location)
+			{
+				return fCallback(null, pResponse);
+			}
+
+			// 3xx with Location — drain and follow.
+			pResponse.resume();
+
+			let tmpRedirectsRemaining = (typeof pOptions.maxRedirects === 'number') ? pOptions.maxRedirects : 10;
+			if (tmpRedirectsRemaining <= 0)
+			{
+				return fCallback(new Error('too many redirects'));
+			}
+
+			const tmpNextOptions = this._buildRedirectedOptions(pOptions, pResponse, tmpOriginalURL, tmpOriginalHost);
+			tmpNextOptions.maxRedirects = tmpRedirectsRemaining - 1;
+
+			// Re-run the agent picker so the next hop's agent matches the
+			// (possibly different) protocol of the redirect target. We do
+			// NOT re-run preRequest in full — RestClientURLPrefix and
+			// prepareCookies are first-call-only.
+			const tmpPreparedNext = this.prepareRequestOptions(tmpNextOptions);
+
+			if (this.TraceLog)
+			{
+				this.fable.log.debug(`--> redirect ${pResponse.statusCode} to ${tmpPreparedNext.url}`);
+			}
+			return this._executeWithRedirects(tmpPreparedNext, fCallback);
+		});
+	}
+
 	executeChunkedRequest(pOptions, fCallback)
 	{
 		let tmpOptions = this.preRequest(pOptions);
@@ -117,7 +356,7 @@ class FableServiceRestClient extends libFableServiceBase
 			this.fable.log.debug(`Beginning ${tmpOptions.method} request to ${tmpOptions.url} at ${tmpOptions.RequestStartTime}`);
 		}
 
-		return libSimpleGet(tmpOptions,
+		return this._executeWithRedirects(tmpOptions,
 			(pError, pResponse)=>
 			{
 				if (pError)
@@ -170,7 +409,7 @@ class FableServiceRestClient extends libFableServiceBase
 		tmpOptions.json = false;
 		tmpOptions.encoding = null;
 
-		return libSimpleGet(tmpOptions,
+		return this._executeWithRedirects(tmpOptions,
 			(pError, pResponse)=>
 			{
 				if (pError)
@@ -241,7 +480,7 @@ class FableServiceRestClient extends libFableServiceBase
 			this.fable.log.debug(`Beginning ${tmpOptions.method} JSON request to ${tmpOptions.url} at ${tmpOptions.RequestStartTime}`);
 		}
 
-		return libSimpleGet(tmpOptions,
+		return this._executeWithRedirects(tmpOptions,
 			(pError, pResponse)=>
 			{
 				if (pError)
@@ -419,7 +658,7 @@ class FableServiceRestClient extends libFableServiceBase
 
 		tmpOptions.json = false;
 
-		return libSimpleGet(tmpOptions,
+		return this._executeWithRedirects(tmpOptions,
 			(pError, pResponse) =>
 			{
 				if (pError)

package/test/RestClient_test.js

@@ -148,73 +148,84 @@ suite
 
 				suite
 					(
-						'KeepAlive Agent',
+						'HTTP Agent',
 						function ()
 						{
 							test
 								(
-									'Initialize keep-alive agents via options.',
+									'Always installs http/https agents, even when KeepAlive is not set.',
 									function ()
 									{
+										// Without an explicit agent, requests would fall through to
+										// http.globalAgent and hit the Node 20+ ~5s socket timeout.
 										let testFable = new libFable();
-										let tmpRestClient = testFable.instantiateServiceProvider('RestClient', { KeepAlive: true }, 'RestClient-KeepAlive-Options');
+										let tmpRestClient = testFable.instantiateServiceProvider('RestClient', {}, 'RestClient-DefaultAgent');
 
 										Expect(tmpRestClient.httpAgent).to.be.an('object');
 										Expect(tmpRestClient.httpsAgent).to.be.an('object');
+										Expect(Boolean(tmpRestClient.httpAgent.keepAlive)).to.equal(false);
+										Expect(Boolean(tmpRestClient.httpsAgent.keepAlive)).to.equal(false);
+									}
+								);
+							test
+								(
+									'Enables keepAlive on agents when KeepAlive option is set.',
+									function ()
+									{
+										let testFable = new libFable();
+										let tmpRestClient = testFable.instantiateServiceProvider('RestClient', { KeepAlive: true }, 'RestClient-KeepAlive-Options');
+
 										Expect(tmpRestClient.httpAgent.keepAlive).to.equal(true);
 										Expect(tmpRestClient.httpsAgent.keepAlive).to.equal(true);
 									}
 								);
 							test
 								(
-									'Initialize keep-alive agents via fable settings.',
+									'Enables keepAlive on agents via fable settings.',
 									function ()
 									{
 										let testFable = new libFable({ RestClientKeepAlive: true });
 										let tmpRestClient = testFable.instantiateServiceProvider('RestClient', {}, 'RestClient-KeepAlive-Settings');
 
-										Expect(tmpRestClient.httpAgent).to.be.an('object');
-										Expect(tmpRestClient.httpsAgent).to.be.an('object');
 										Expect(tmpRestClient.httpAgent.keepAlive).to.equal(true);
 										Expect(tmpRestClient.httpsAgent.keepAlive).to.equal(true);
 									}
 								);
 							test
 								(
-									'Pass additional agent options via KeepAliveAgentOptions.',
+									'Passes additional agent options through KeepAliveAgentOptions.',
 									function ()
 									{
 										let testFable = new libFable();
 										let tmpRestClient = testFable.instantiateServiceProvider('RestClient',
 											{
 												KeepAlive: true,
-												KeepAliveAgentOptions: { timeout: 300000 }
+												KeepAliveAgentOptions: { timeout: 300000, maxSockets: 32 }
 											}, 'RestClient-KeepAlive-AgentOpts');
 
-										Expect(tmpRestClient.httpAgent).to.be.an('object');
-										Expect(tmpRestClient.httpsAgent).to.be.an('object');
 										Expect(tmpRestClient.httpAgent.keepAlive).to.equal(true);
-										Expect(tmpRestClient.httpsAgent.keepAlive).to.equal(true);
-										// Verify the custom timeout was passed through
 										Expect(tmpRestClient.httpAgent.options.timeout).to.equal(300000);
+										Expect(tmpRestClient.httpAgent.options.maxSockets).to.equal(32);
 										Expect(tmpRestClient.httpsAgent.options.timeout).to.equal(300000);
 									}
 								);
-						test
+							test
 								(
-									'Do not create agents when KeepAlive is not set.',
+									'KeepAliveAgentOptions apply even when KeepAlive is not enabled.',
 									function ()
 									{
+										// Tuning options still flow through when keepAlive is off.
 										let testFable = new libFable();
-										let tmpRestClient = testFable.instantiateServiceProvider('RestClient', {}, 'RestClient-NoKeepAlive');
+										let tmpRestClient = testFable.instantiateServiceProvider('RestClient',
+											{ KeepAliveAgentOptions: { maxSockets: 8 } }, 'RestClient-AgentOpts-NoKeepAlive');
 
-										Expect(tmpRestClient.httpAgent).to.equal(undefined);
-										Expect(tmpRestClient.httpsAgent).to.equal(undefined);
+										Expect(Boolean(tmpRestClient.httpAgent.keepAlive)).to.equal(false);
+										Expect(tmpRestClient.httpAgent.options.maxSockets).to.equal(8);
 									}
 								);
 							test
 								(
-									'Inject HTTP agent into request options for http URLs.',
+									'Injects the http agent on http:// URLs.',
 									function (fTestComplete)
 									{
 										var tmpServer = libHTTP.createServer(function (pReq, pRes)
@@ -227,9 +238,8 @@ suite
 										{
 											var tmpPort = tmpServer.address().port;
 											var testFable = new libFable();
-											var tmpRestClient = testFable.instantiateServiceProvider('RestClient', { KeepAlive: true }, 'RestClient-KeepAlive-HTTP');
+											var tmpRestClient = testFable.instantiateServiceProvider('RestClient', {}, 'RestClient-AgentInject-HTTP');
 
-											// Wrap prepareRequestOptions to capture the final options
 											var tmpOriginalPrepare = tmpRestClient.prepareRequestOptions;
 											var tmpCapturedAgent = null;
 											tmpRestClient.prepareRequestOptions = function (pOptions)
@@ -243,7 +253,6 @@ suite
 												function (pError, pResponse, pBody)
 												{
 													Expect(tmpCapturedAgent).to.equal(tmpRestClient.httpAgent);
-													Expect(pBody).to.be.an('object');
 													Expect(pBody.OK).to.equal(true);
 													tmpServer.close();
 													fTestComplete();
@@ -253,7 +262,92 @@ suite
 								);
 							test
 								(
-									'Chain with previously set prepareRequestOptions.',
+									'Selects the https agent for https:// URLs.',
+									function ()
+									{
+										// We don't need a live HTTPS server to verify the selection
+										// logic — invoke prepareRequestOptions directly and inspect
+										// which agent was chosen.
+										let testFable = new libFable();
+										let tmpRestClient = testFable.instantiateServiceProvider('RestClient', {}, 'RestClient-AgentInject-HTTPS');
+
+										let tmpHttps = tmpRestClient.prepareRequestOptions({ url: 'https://example.com/x' });
+										let tmpHttp = tmpRestClient.prepareRequestOptions({ url: 'http://example.com/x' });
+
+										Expect(tmpHttps.agent).to.equal(tmpRestClient.httpsAgent);
+										Expect(tmpHttp.agent).to.equal(tmpRestClient.httpAgent);
+									}
+								);
+							test
+								(
+									'Selects the http agent for relative URLs and option objects without a URL.',
+									function ()
+									{
+										// simple-get's protocol decision is `opts.protocol === 'https:'
+										// ? https : http`, so a URL with no protocol — including a
+										// relative path or a pre-parsed options object — routes through
+										// the http module. The agent we stamp on must match, otherwise
+										// Node throws ERR_INVALID_PROTOCOL on dispatch.
+										let testFable = new libFable();
+										let tmpRestClient = testFable.instantiateServiceProvider('RestClient', {}, 'RestClient-AgentInject-Relative');
+
+										let tmpRelative = tmpRestClient.prepareRequestOptions({ url: '/1.0/Users/Count' });
+										let tmpNoUrl = tmpRestClient.prepareRequestOptions({ hostname: 'localhost', port: 8086, path: '/1.0/Users' });
+
+										Expect(tmpRelative.agent).to.equal(tmpRestClient.httpAgent);
+										Expect(tmpNoUrl.agent).to.equal(tmpRestClient.httpAgent);
+									}
+								);
+							test
+								(
+									'A relative URL is dispatched without throwing ERR_INVALID_PROTOCOL.',
+									function (fTestComplete)
+									{
+										// End-to-end regression: before the fix, fable stamped the
+										// httpsAgent on relative URLs while simple-get routed them
+										// through http.request, which made Node throw synchronously.
+										// We point fable at a real http server via RestClientURLPrefix
+										// so the relative URL becomes resolvable, and assert that the
+										// request completes (rather than throwing on dispatch).
+										var tmpServer = libHTTP.createServer(function (pReq, pRes)
+										{
+											pRes.writeHead(200, { 'Content-Type': 'application/json' });
+											pRes.end(JSON.stringify({ Path: pReq.url }));
+										});
+
+										tmpServer.listen(0, function ()
+										{
+											var tmpPort = tmpServer.address().port;
+											var testFable = new libFable({ RestClientURLPrefix: 'http://localhost:' + tmpPort });
+											var tmpRestClient = testFable.instantiateServiceProvider('RestClient', {}, 'RestClient-RelativeURL-Dispatch');
+
+											var tmpOriginalPrepare = tmpRestClient.prepareRequestOptions;
+											var tmpCapturedAgent = null;
+											tmpRestClient.prepareRequestOptions = function (pOptions)
+											{
+												let tmpResult = tmpOriginalPrepare(pOptions);
+												if (tmpCapturedAgent === null)
+												{
+													tmpCapturedAgent = tmpResult.agent;
+												}
+												return tmpResult;
+											};
+
+											tmpRestClient.getJSON('/relative/path',
+												function (pError, pResponse, pBody)
+												{
+													Expect(pError).to.equal(null);
+													Expect(tmpCapturedAgent).to.equal(tmpRestClient.httpAgent);
+													Expect(pBody.Path).to.equal('/relative/path');
+													tmpServer.close();
+													fTestComplete();
+												});
+										});
+									}
+								);
+							test
+								(
+									'Chains with previously set prepareRequestOptions.',
 									function (fTestComplete)
 									{
 										var tmpServer = libHTTP.createServer(function (pReq, pRes)
@@ -268,13 +362,10 @@ suite
 											var testFable = new libFable();
 											var tmpRestClient = testFable.instantiateServiceProvider('RestClient', { KeepAlive: true }, 'RestClient-KeepAlive-Chain');
 
-											// Set a custom prepareRequestOptions AFTER keep-alive init to verify chaining
-											var tmpKeepAlivePrepare = tmpRestClient.prepareRequestOptions;
+											var tmpInstalledPrepare = tmpRestClient.prepareRequestOptions;
 											tmpRestClient.prepareRequestOptions = function (pOptions)
 											{
-												// Apply keep-alive first
-												let tmpResult = tmpKeepAlivePrepare(pOptions);
-												// Then add custom header
+												let tmpResult = tmpInstalledPrepare(pOptions);
 												if (!tmpResult.headers)
 												{
 													tmpResult.headers = {};
@@ -286,7 +377,6 @@ suite
 											tmpRestClient.getJSON('http://localhost:' + tmpPort + '/test',
 												function (pError, pResponse, pBody)
 												{
-													Expect(pBody).to.be.an('object');
 													Expect(pBody.CustomHeader).to.equal('test-value');
 													tmpServer.close();
 													fTestComplete();
@@ -294,6 +384,440 @@ suite
 										});
 									}
 								);
+							test
+								(
+									'initializeKeepAliveAgent remains a back-compat entry point.',
+									function ()
+									{
+										let testFable = new libFable();
+										let tmpRestClient = testFable.instantiateServiceProvider('RestClient', {}, 'RestClient-BackCompat');
+
+										// Default constructor: no keepAlive
+										Expect(Boolean(tmpRestClient.httpAgent.keepAlive)).to.equal(false);
+
+										// Calling the legacy method flips keepAlive on
+										tmpRestClient.initializeKeepAliveAgent({ maxSockets: 4 });
+										Expect(tmpRestClient.httpAgent.keepAlive).to.equal(true);
+										Expect(tmpRestClient.httpAgent.options.maxSockets).to.equal(4);
+									}
+								);
+						}
+					);
+
+				suite
+					(
+						'Request Timeout',
+						function ()
+						{
+							// Helper: spin up a local HTTP server that never responds so we can
+							// verify that the simple-get 'Request timed out' path fires on our
+							// configured timeout rather than any ambient http.globalAgent default.
+							var createHangingServer = function (fOnListen)
+							{
+								var tmpServer = libHTTP.createServer(function (pReq, pRes)
+								{
+									// Intentionally never write or end the response
+								});
+								tmpServer.listen(0, function ()
+								{
+									fOnListen(tmpServer, tmpServer.address().port);
+								});
+								return tmpServer;
+							};
+
+							test
+								(
+									'Applies the library default timeout (60000ms) when none is supplied.',
+									function ()
+									{
+										let testFable = new libFable();
+										let tmpRestClient = testFable.instantiateServiceProvider('RestClient', {}, 'RestClient-DefaultTimeout');
+
+										Expect(tmpRestClient.defaultRequestTimeout).to.equal(60000);
+
+										let tmpPrepared = tmpRestClient.preRequest({ url: 'http://example.com/x', method: 'GET' });
+										Expect(tmpPrepared.timeout).to.equal(60000);
+									}
+								);
+							test
+								(
+									'RequestTimeout constructor option overrides the library default.',
+									function ()
+									{
+										let testFable = new libFable();
+										let tmpRestClient = testFable.instantiateServiceProvider('RestClient', { RequestTimeout: 60000 }, 'RestClient-OptTimeout');
+
+										Expect(tmpRestClient.defaultRequestTimeout).to.equal(60000);
+
+										let tmpPrepared = tmpRestClient.preRequest({ url: 'http://example.com/x', method: 'GET' });
+										Expect(tmpPrepared.timeout).to.equal(60000);
+									}
+								);
+							test
+								(
+									'RestClientRequestTimeout fable setting overrides the library default.',
+									function ()
+									{
+										let testFable = new libFable({ RestClientRequestTimeout: 45000 });
+										let tmpRestClient = testFable.instantiateServiceProvider('RestClient', {}, 'RestClient-SettingTimeout');
+
+										Expect(tmpRestClient.defaultRequestTimeout).to.equal(45000);
+									}
+								);
+							test
+								(
+									'Constructor option takes precedence over fable setting.',
+									function ()
+									{
+										let testFable = new libFable({ RestClientRequestTimeout: 45000 });
+										let tmpRestClient = testFable.instantiateServiceProvider('RestClient', { RequestTimeout: 15000 }, 'RestClient-TimeoutPrecedence');
+
+										Expect(tmpRestClient.defaultRequestTimeout).to.equal(15000);
+									}
+								);
+							test
+								(
+									'Caller-supplied timeout on the request options is preserved.',
+									function ()
+									{
+										let testFable = new libFable();
+										let tmpRestClient = testFable.instantiateServiceProvider('RestClient', {}, 'RestClient-CallerTimeout');
+
+										let tmpPrepared = tmpRestClient.preRequest({ url: 'http://example.com/x', method: 'GET', timeout: 1234 });
+										Expect(tmpPrepared.timeout).to.equal(1234);
+									}
+								);
+							test
+								(
+									'Explicit timeout of 0 on the request options is preserved.',
+									function ()
+									{
+										// 0 is a valid numeric value — it signals "override the mystery
+										// default with no timeout" and must not be replaced.
+										let testFable = new libFable();
+										let tmpRestClient = testFable.instantiateServiceProvider('RestClient', {}, 'RestClient-ZeroTimeout');
+
+										let tmpPrepared = tmpRestClient.preRequest({ url: 'http://example.com/x', method: 'GET', timeout: 0 });
+										Expect(tmpPrepared.timeout).to.equal(0);
+									}
+								);
+							test
+								(
+									'RequestTimeout value of 0 is honored.',
+									function ()
+									{
+										let testFable = new libFable();
+										let tmpRestClient = testFable.instantiateServiceProvider('RestClient', { RequestTimeout: 0 }, 'RestClient-ZeroOptTimeout');
+
+										Expect(tmpRestClient.defaultRequestTimeout).to.equal(0);
+
+										let tmpPrepared = tmpRestClient.preRequest({ url: 'http://example.com/x', method: 'GET' });
+										Expect(tmpPrepared.timeout).to.equal(0);
+									}
+								);
+							test
+								(
+									'A short RequestTimeout actually aborts a hanging request.',
+									function (fTestComplete)
+									{
+										this.timeout(5000);
+										var tmpServer;
+										tmpServer = createHangingServer(function (pServer, pPort)
+										{
+											var testFable = new libFable();
+											var tmpRestClient = testFable.instantiateServiceProvider('RestClient', { RequestTimeout: 300 }, 'RestClient-LiveTimeout');
+
+											var tmpStart = Date.now();
+											tmpRestClient.getJSON('http://localhost:' + pPort + '/hangs',
+												function (pError, pResponse, pBody)
+												{
+													var tmpElapsed = Date.now() - tmpStart;
+													Expect(pError).to.be.an.instanceof(Error);
+													Expect(pError.message).to.contain('timed out');
+													// Guard against the Node 20+ ~5s globalAgent timeout
+													// silently beating our 300ms setting.
+													Expect(tmpElapsed).to.be.lessThan(2500);
+													pServer.close();
+													fTestComplete();
+												});
+										});
+									}
+								);
+						}
+					);
+
+				suite
+					(
+						'Redirect Following',
+						function ()
+						{
+							test
+								(
+									'Follows a basic 301 redirect end-to-end.',
+									function (fTestComplete)
+									{
+										// Single server: /start returns 301 to /dest, /dest returns 200 + JSON.
+										var tmpServer = libHTTP.createServer(function (pReq, pRes)
+										{
+											if (pReq.url === '/start')
+											{
+												pRes.writeHead(301, { Location: '/dest' });
+												pRes.end();
+												return;
+											}
+											pRes.writeHead(200, { 'Content-Type': 'application/json' });
+											pRes.end(JSON.stringify({ Reached: pReq.url }));
+										});
+										tmpServer.listen(0, function ()
+										{
+											var tmpPort = tmpServer.address().port;
+											var testFable = new libFable();
+											var tmpRestClient = testFable.instantiateServiceProvider('RestClient', {}, 'RestClient-Redirect-Basic');
+											tmpRestClient.getJSON('http://localhost:' + tmpPort + '/start',
+												function (pError, pResponse, pBody)
+												{
+													Expect(pError).to.equal(null);
+													Expect(pBody.Reached).to.equal('/dest');
+													tmpServer.close();
+													fTestComplete();
+												});
+										});
+									}
+								);
+							test
+								(
+									'Re-picks the agent on a protocol-changing redirect.',
+									function (fTestComplete)
+									{
+										// http server redirects to an https URL. We don't need the https
+										// destination to be reachable — we just need to verify that
+										// prepareRequestOptions runs again on the redirect target and
+										// stamps the httpsAgent on the second hop.
+										var tmpAssignedAgents = [];
+										var tmpServer = libHTTP.createServer(function (pReq, pRes)
+										{
+											pRes.writeHead(302, { Location: 'https://nowhere.invalid/x' });
+											pRes.end();
+										});
+										tmpServer.listen(0, function ()
+										{
+											var tmpPort = tmpServer.address().port;
+											var testFable = new libFable();
+											var tmpRestClient = testFable.instantiateServiceProvider('RestClient', {}, 'RestClient-Redirect-ProtoSwitch');
+
+											var tmpOriginalPrepare = tmpRestClient.prepareRequestOptions;
+											tmpRestClient.prepareRequestOptions = function (pOptions)
+											{
+												var tmpResult = tmpOriginalPrepare(pOptions);
+												tmpAssignedAgents.push({ url: tmpResult.url, agent: tmpResult.agent });
+												return tmpResult;
+											};
+
+											tmpRestClient.getJSON('http://localhost:' + tmpPort + '/start',
+												function (pError)
+												{
+													// The second hop will fail (DNS lookup of nowhere.invalid)
+													// but the agent re-pick must have already happened
+													// before that — and crucially, must NOT have thrown
+													// ERR_INVALID_PROTOCOL synchronously like the old code.
+													Expect(tmpAssignedAgents.length).to.be.at.least(2);
+													Expect(tmpAssignedAgents[0].agent).to.equal(tmpRestClient.httpAgent);
+													Expect(tmpAssignedAgents[1].agent).to.equal(tmpRestClient.httpsAgent);
+													Expect(tmpAssignedAgents[1].url).to.equal('https://nowhere.invalid/x');
+													tmpServer.close();
+													fTestComplete();
+												});
+										});
+									}
+								);
+							test
+								(
+									'Bails with "too many redirects" when the budget is exceeded.',
+									function (fTestComplete)
+									{
+										// Self-redirecting server. Cap at 3 hops so the test stays quick.
+										var tmpServer = libHTTP.createServer(function (pReq, pRes)
+										{
+											pRes.writeHead(302, { Location: pReq.url });
+											pRes.end();
+										});
+										tmpServer.listen(0, function ()
+										{
+											var tmpPort = tmpServer.address().port;
+											var testFable = new libFable();
+											var tmpRestClient = testFable.instantiateServiceProvider('RestClient', {}, 'RestClient-Redirect-Loop');
+											tmpRestClient.getJSON({ url: 'http://localhost:' + tmpPort + '/loop', maxRedirects: 3 },
+												function (pError)
+												{
+													Expect(pError).to.be.an.instanceof(Error);
+													Expect(pError.message).to.equal('too many redirects');
+													tmpServer.close();
+													fTestComplete();
+												});
+										});
+									}
+								);
+							test
+								(
+									'Drops cookie and authorization on cross-origin redirect.',
+									function (fTestComplete)
+									{
+										// Two servers on different ports. We use 127.0.0.1 vs localhost
+										// to make them count as different hostnames per
+										// _parseHostname's URL-string check.
+										var tmpReceivedAtA = null;
+										var tmpReceivedAtB = null;
+										var tmpServerB = libHTTP.createServer(function (pReq, pRes)
+										{
+											tmpReceivedAtB = pReq.headers;
+											pRes.writeHead(200, { 'Content-Type': 'application/json' });
+											pRes.end(JSON.stringify({ ok: true }));
+										});
+										tmpServerB.listen(0, function ()
+										{
+											var tmpPortB = tmpServerB.address().port;
+											var tmpServerA = libHTTP.createServer(function (pReq, pRes)
+											{
+												tmpReceivedAtA = pReq.headers;
+												pRes.writeHead(302, { Location: 'http://127.0.0.1:' + tmpPortB + '/dest' });
+												pRes.end();
+											});
+											tmpServerA.listen(0, function ()
+											{
+												var tmpPortA = tmpServerA.address().port;
+												var testFable = new libFable();
+												var tmpRestClient = testFable.instantiateServiceProvider('RestClient', {}, 'RestClient-Redirect-CrossOrigin');
+												tmpRestClient.getJSON({
+													url: 'http://localhost:' + tmpPortA + '/start',
+													headers: { cookie: 'session=abc', authorization: 'Bearer xyz' }
+												},
+												function (pError, pResponse, pBody)
+												{
+													Expect(pError).to.equal(null);
+													Expect(pBody.ok).to.equal(true);
+													Expect(tmpReceivedAtA.cookie).to.equal('session=abc');
+													Expect(tmpReceivedAtA.authorization).to.equal('Bearer xyz');
+													Expect(tmpReceivedAtB.cookie).to.equal(undefined);
+													Expect(tmpReceivedAtB.authorization).to.equal(undefined);
+													tmpServerA.close();
+													tmpServerB.close();
+													fTestComplete();
+												});
+											});
+										});
+									}
+								);
+							test
+								(
+									'Converts POST to GET on a 301/302 redirect and drops the body.',
+									function (fTestComplete)
+									{
+										var tmpDestRequest = null;
+										var tmpServer = libHTTP.createServer(function (pReq, pRes)
+										{
+											if (pReq.url === '/start')
+											{
+												pRes.writeHead(301, { Location: '/dest' });
+												pRes.end();
+												return;
+											}
+											tmpDestRequest = { method: pReq.method, headers: pReq.headers };
+											var tmpBody = '';
+											pReq.on('data', function (pChunk) { tmpBody += pChunk; });
+											pReq.on('end', function ()
+											{
+												tmpDestRequest.body = tmpBody;
+												pRes.writeHead(200, { 'Content-Type': 'application/json' });
+												pRes.end(JSON.stringify({ ok: true }));
+											});
+										});
+										tmpServer.listen(0, function ()
+										{
+											var tmpPort = tmpServer.address().port;
+											var testFable = new libFable();
+											var tmpRestClient = testFable.instantiateServiceProvider('RestClient', {}, 'RestClient-Redirect-PostToGet');
+											tmpRestClient.postJSON({ url: 'http://localhost:' + tmpPort + '/start', body: { foo: 'bar' } },
+												function (pError, pResponse, pBody)
+												{
+													Expect(pError).to.equal(null);
+													Expect(pBody.ok).to.equal(true);
+													Expect(tmpDestRequest.method).to.equal('GET');
+													Expect(tmpDestRequest.body).to.equal('');
+													Expect(tmpDestRequest.headers['content-type']).to.equal(undefined);
+													Expect(tmpDestRequest.headers['content-length']).to.equal(undefined);
+													tmpServer.close();
+													fTestComplete();
+												});
+										});
+									}
+								);
+							test
+								(
+									'Resolves a relative Location header against the current URL.',
+									function (fTestComplete)
+									{
+										// Server returns a relative Location ("dest" instead of "/dest").
+										// RFC 7231 allows this; the next hop's URL must be resolved
+										// against the URL that produced the redirect.
+										var tmpDestRequestURL = null;
+										var tmpServer = libHTTP.createServer(function (pReq, pRes)
+										{
+											if (pReq.url === '/section/start')
+											{
+												pRes.writeHead(302, { Location: 'dest' });
+												pRes.end();
+												return;
+											}
+											tmpDestRequestURL = pReq.url;
+											pRes.writeHead(200, { 'Content-Type': 'application/json' });
+											pRes.end(JSON.stringify({ ok: true }));
+										});
+										tmpServer.listen(0, function ()
+										{
+											var tmpPort = tmpServer.address().port;
+											var testFable = new libFable();
+											var tmpRestClient = testFable.instantiateServiceProvider('RestClient', {}, 'RestClient-Redirect-RelativeLocation');
+											tmpRestClient.getJSON('http://localhost:' + tmpPort + '/section/start',
+												function (pError, pResponse, pBody)
+												{
+													Expect(pError).to.equal(null);
+													Expect(pBody.ok).to.equal(true);
+													Expect(tmpDestRequestURL).to.equal('/section/dest');
+													tmpServer.close();
+													fTestComplete();
+												});
+										});
+									}
+								);
+							test
+								(
+									'Honors followRedirects: false by handing the 3xx straight back.',
+									function (fTestComplete)
+									{
+										// When the caller opts out, we shouldn't follow the redirect —
+										// the JSON parser will fail because the 3xx body is empty,
+										// which is the expected pre-fix behavior.
+										var tmpServer = libHTTP.createServer(function (pReq, pRes)
+										{
+											pRes.writeHead(302, { Location: '/dest' });
+											pRes.end();
+										});
+										tmpServer.listen(0, function ()
+										{
+											var tmpPort = tmpServer.address().port;
+											var testFable = new libFable();
+											var tmpRestClient = testFable.instantiateServiceProvider('RestClient', {}, 'RestClient-Redirect-OptOut');
+											tmpRestClient.getJSON({ url: 'http://localhost:' + tmpPort + '/start', followRedirects: false },
+												function (pError, pResponse)
+												{
+													Expect(pResponse.statusCode).to.equal(302);
+													Expect(pResponse.headers.location).to.equal('/dest');
+													tmpServer.close();
+													fTestComplete();
+												});
+										});
+									}
+								);
 						}
 					);