Name the peer and the stalled phase on a connect timeout, and quote an untyped value

src/client.ts

@@ -56,14 +56,19 @@ const defaults = {
 function armConnectTimeout(
 	sock: Socket,
 	connectTimeout: number | undefined,
+	peer: string,
 	settle: (result: Result<{ sock: Socket }>) => void,
 ): NodeJS.Timeout | undefined {
 	if (connectTimeout === undefined) return undefined;
 
-	// The connecting socket is what holds the process, so this wait never has to.
+	// A firewall and a stalled handshake need different answers, and only the phase tells them apart.
+	let phase = `connecting to ${peer}`;
+
+	sock.once('connect', () => { phase = `completing the TLS handshake with ${peer}`; });
+
 	return setTimeout(() => {
 		sock.destroy();
-		settle({ err: new Error(`Timed out connecting after ${String(connectTimeout)} ms`) });
+		settle({ err: new Error(`Timed out ${phase} after ${String(connectTimeout)} ms`) });
 	}, connectTimeout).unref();
 }
 
@@ -115,7 +120,7 @@ function openSocket(options: ClientOptions): Promise<Result<{ sock: Socket }>> {
 			settle({ sock });
 		});
 
-		const timer = armConnectTimeout(sock, connectTimeout, settle);
+		const timer = armConnectTimeout(sock, connectTimeout, `${host}:${String(port)}`, settle);
 	});
 }
 

src/session-options.ts

@@ -168,20 +168,19 @@ function limitsOf(options: CheckableOptions): [string, number, number][] {
 	];
 }
 
-/** Node's timers are 32-bit, and a delay above this one fires after 1 ms instead of never. */
 const maxTimerDelay = 2_147_483_647;
 
-function checkConnectTimeout(connectTimeout: number | undefined): VoidResult {
+function checkConnectTimeout(connectTimeout: unknown): VoidResult {
 	if (connectTimeout === undefined) return {};
 
-	const got = String(connectTimeout);
+	const got = typeof connectTimeout === 'string' ? `"${connectTimeout}"` : namedValue(connectTimeout);
 
-	if (!Number.isInteger(connectTimeout) || connectTimeout < 1) {
-		return { err: new Error(`connectTimeout must be a whole number of milliseconds, 1 or more, got ${got}; omit it to wait the OS out`) };
+	if (typeof connectTimeout !== 'number' || !Number.isInteger(connectTimeout) || connectTimeout < 1) {
+		return { err: new Error(`connectTimeout must be a whole number of milliseconds, 1 or more, got ${got}; omit it or pass undefined to wait the OS out`) };
 	}
 
 	if (connectTimeout > maxTimerDelay) {
-		return { err: new Error(`connectTimeout must be ${String(maxTimerDelay)} or less, got ${got}`) };
+		return { err: new Error(`connectTimeout must be ${String(maxTimerDelay)} ms or less (about 24 days), got ${got}`) };
 	}
 
 	return {};
@@ -265,7 +264,7 @@ function checkSmsIdFormat(smsIdFormat: unknown): VoidResult {
 
 /** What the checker reads, as it arrives: a caller without types can put anything in it. */
 export type CheckableOptions = {
-	connectTimeout?: number | undefined;
+	connectTimeout?: unknown;
 	/** Not an option: the one spelling is inside reconnect, and this is where the other is refused. */
 	fromStart?: unknown;
 	idleTimeout?: number | undefined;