Fix: Improve error handling to distinguish network errors from TLS failures

Separates specific network transport errors (`ETIMEDOUT`, `ECONNRESET`)
from genuine TLS handshake failures.

The previous approach incorrectly categorized lower-level connection
issues as "TLS errors," leading to misleading diagnostics for end-users.
This change ensures accurate reporting based on the error pattern:
- "tls handshake": Protocol/certificate issue.
- "etimedout" / "timed out": Network timeout/availability.
- "econnreset": Connection forcefully reset by host/intermediary.

Author: thiyaguk09

src/nodejs-common/util.ts

@@ -256,6 +256,12 @@ export interface ParsedHttpResponseBody {
   err?: Error;
 }
 
+export enum UtilExceptionMessages {
+  TLS_TIMEOUT_ERROR_MESSAGE = 'Request or TLS handshake timed out. This may be due to CPU starvation or a temporary network issue.',
+  ETIMEDOUT_ERROR_MESSAGE = 'Connection timed out. This suggests a network issue or the server took too long to respond.',
+  ECONNRESET_ERROR_MESSAGE = 'Connection reset by peer. The connection was closed unexpectedly, possibly by a firewall or network issue.',
+}
+
 /**
  * Custom error type for API errors.
  *
@@ -914,15 +920,29 @@ export class Util {
         (err: Error | null, response: {}, body: any) => {
           if (err) {
             const lowerCaseMessage = err.message.toLowerCase();
-            const isTLsTimeoutOrConnReset =
-              /tls handshake|timed out|etimedout|econnreset/.test(
-                lowerCaseMessage
+            let newError: Error | undefined;
+
+            if (lowerCaseMessage.includes('tls handshake')) {
+              newError = new Error(
+                UtilExceptionMessages.TLS_TIMEOUT_ERROR_MESSAGE
+              );
+            } else if (
+              lowerCaseMessage.includes('etimedout') ||
+              lowerCaseMessage.includes('timed out')
+            ) {
+              newError = new Error(
+                UtilExceptionMessages.ETIMEDOUT_ERROR_MESSAGE
+              );
+            } else if (lowerCaseMessage.includes('econnreset')) {
+              newError = new Error(
+                UtilExceptionMessages.ECONNRESET_ERROR_MESSAGE
               );
-            if (isTLsTimeoutOrConnReset) {
-              const TLS_TIMEOUT_ERROR_MESSAGE =
-                'Request or TLS handshake timed out. This may be due to CPU starvation or a temporary network issue.';
-              const timeOutError = new Error(TLS_TIMEOUT_ERROR_MESSAGE);
-              err = timeOutError;
+            }
+
+            if (newError) {
+              // Preserve the original stack trace for better debugging
+              newError.stack = err.stack;
+              err = newError;
             }
           }
           util.handleResp(err, response as {} as r.Response, body, callback!);

test/nodejs-common/util.ts

@@ -46,6 +46,7 @@ import {
   MakeRequestConfig,
   ParsedHttpRespMessage,
   Util,
+  UtilExceptionMessages,
 } from '../../src/nodejs-common/util.js';
 import {DEFAULT_PROJECT_ID_TOKEN} from '../../src/nodejs-common/service.js';
 import duplexify from 'duplexify';
@@ -1189,31 +1190,38 @@ describe('common/util', () => {
         });
       });
 
-      describe('TLS handshake errors', () => {
+      describe('Handling of TLS Handshake, Timeout, and Connection Reset Errors in Authenticated Requests', () => {
         const reqOpts = fakeReqOpts;
         beforeEach(() => {
           authClient.authorizeRequest = async () => reqOpts;
           sandbox.stub(fakeGoogleAuth, 'GoogleAuth').returns(authClient);
         });
 
         const testCases = [
-          {name: 'ECONNRESET', error: new Error('ECONNRESET')},
+          {
+            name: 'ECONNRESET',
+            error: new Error('ECONNRESET'),
+            expectedMessage: UtilExceptionMessages.ECONNRESET_ERROR_MESSAGE,
+          },
           {
             name: '"TLS handshake"',
             error: new Error('Request failed due to TLS handshake timeout.'),
+            expectedMessage: UtilExceptionMessages.TLS_TIMEOUT_ERROR_MESSAGE,
           },
           {
             name: 'generic "timed out"',
             error: new Error('The request timed out.'),
+            expectedMessage: UtilExceptionMessages.ETIMEDOUT_ERROR_MESSAGE,
           },
           {
             name: 'ETIMEDOUT',
             error: new Error('Request failed with error: ETIMEDOUT'),
+            expectedMessage: UtilExceptionMessages.ETIMEDOUT_ERROR_MESSAGE,
           },
         ];
 
-        testCases.forEach(({name, error: networkError}) => {
-          it(`should transform raw ${name} into specific TLS/CPU starvation Error`, done => {
+        testCases.forEach(({name, error: networkError, expectedMessage}) => {
+          it(`should transform raw ${name} into specific network error`, done => {
             // Override `retry-request` to simulate a network error.
             retryRequestOverride = (
               // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -1231,10 +1239,7 @@ describe('common/util', () => {
 
             makeAuthenticatedRequest({} as DecorateRequestOptions, err => {
               assert.ok(err);
-              assert.strictEqual(
-                err.message,
-                'Request or TLS handshake timed out. This may be due to CPU starvation or a temporary network issue.'
-              );
+              assert.strictEqual(err!.message, expectedMessage);
               done();
             });
           });