refactor: switch HTTP layer to undici with connection pooling

Replace node:http with undici for HTTP requests. A shared Agent manages
per-origin connection pools with keep-alive, so sequential requests to the
same device reuse TCP connections. Granular timeouts (connect, headers,
body) are derived from the caller's overall timeout budget.

Author: micthiesen

package.json

@@ -58,12 +58,13 @@
     "ajv-formats": "^3.0.1",
     "chalk": "^5.4.1",
     "semver": "^7.7.4",
-    "tplink-smarthome-api": "~5.0.0"
+    "tplink-smarthome-api": "~5.0.0",
+    "undici": "^7.24.6"
   },
   "devDependencies": {
+    "@biomejs/biome": "2.4.8",
     "@types/node": "^22.19.15",
     "@types/semver": "^7.7.1",
-    "@biomejs/biome": "2.4.8",
     "cspell": "^9.7.0",
     "hap-nodejs": "~0.14.2",
     "homebridge": "~1.11.3",

pnpm-lock.yaml

@@ -1,56 +1,74 @@
-import * as http from "node:http";
+import { Agent, request } from "undici";
+
+const CONNECT_TIMEOUT_MS = 3_000;
+
+const agent = new Agent({
+  connect: { timeout: CONNECT_TIMEOUT_MS },
+  keepAliveTimeout: 30_000,
+  keepAliveMaxTimeout: 60_000,
+  pipelining: 1,
+});
+
+export type HttpHeaders = Record<string, string | string[] | undefined>;
 
 export interface HttpResponse {
   statusCode: number;
-  headers: http.IncomingHttpHeaders;
+  headers: HttpHeaders;
   body: Buffer;
 }
 
 /**
- * Simple HTTP POST using Node's built-in http module.
+ * Derive granular timeouts from an overall timeout budget.
+ *
+ * - headersTimeout: 60% of overall (time to receive response headers after request sent)
+ * - bodyTimeout: 80% of overall (max time between body data chunks)
+ *
+ * The overall timeout is still enforced as a hard deadline via AbortSignal.
+ */
+function deriveTimeouts(overallMs: number) {
+  return {
+    headersTimeout: Math.round(overallMs * 0.6),
+    bodyTimeout: Math.round(overallMs * 0.8),
+  };
+}
+
+/**
+ * HTTP POST using undici with connection pooling and granular timeouts.
+ *
+ * Connections to the same origin are reused via keep-alive. Connect timeout
+ * is fixed at 3s (suitable for local network IoT devices). Per-request
+ * headers and body timeouts are derived from the caller's overall timeout.
  */
-export function httpPost(
+export async function httpPost(
   url: string,
   body: Buffer | string,
   headers: Record<string, string>,
   timeoutMs: number,
 ): Promise<HttpResponse> {
-  return new Promise((resolve, reject) => {
-    const parsed = new URL(url);
-    const reqBody = typeof body === "string" ? Buffer.from(body, "utf-8") : body;
-
-    const req = http.request(
-      {
-        hostname: parsed.hostname,
-        port: parsed.port || 80,
-        path: parsed.pathname + parsed.search,
-        method: "POST",
-        headers: {
-          ...headers,
-          "Content-Length": String(reqBody.length),
-        },
-        timeout: timeoutMs,
-      },
-      (res) => {
-        const chunks: Buffer[] = [];
-        res.on("data", (chunk: Buffer) => chunks.push(chunk));
-        res.on("end", () => {
-          resolve({
-            statusCode: res.statusCode ?? 0,
-            headers: res.headers,
-            body: Buffer.concat(chunks),
-          });
-        });
-        res.on("error", reject);
-      },
-    );
-
-    req.on("error", reject);
-    req.on("timeout", () => {
-      req.destroy(new Error(`HTTP request timed out after ${timeoutMs}ms`));
-    });
-
-    req.write(reqBody);
-    req.end();
+  const reqBody = typeof body === "string" ? Buffer.from(body, "utf-8") : body;
+  const { headersTimeout, bodyTimeout } = deriveTimeouts(timeoutMs);
+
+  const resp = await request(url, {
+    method: "POST",
+    headers: {
+      ...headers,
+      "Content-Length": String(reqBody.length),
+    },
+    body: reqBody,
+    dispatcher: agent,
+    headersTimeout,
+    bodyTimeout,
+    signal: AbortSignal.timeout(timeoutMs),
   });
+
+  const chunks: Buffer[] = [];
+  for await (const chunk of resp.body) {
+    chunks.push(Buffer.from(chunk));
+  }
+
+  return {
+    statusCode: resp.statusCode,
+    headers: resp.headers as HttpHeaders,
+    body: Buffer.concat(chunks),
+  };
 }

src/klap/http.ts

@@ -1,4 +1,4 @@
-import type * as http from "node:http";
+import type { HttpHeaders } from "./http.js";
 
 /**
  * Parse TP_SESSIONID from Set-Cookie header(s).
@@ -7,9 +7,7 @@ import type * as http from "node:http";
  * TP_SESSIONID or SESSIONID and return the raw cookie string suitable
  * for sending back in a Cookie header.
  */
-export function parseSessionCookie(
-  headers: http.IncomingHttpHeaders,
-): string | undefined {
+export function parseSessionCookie(headers: HttpHeaders): string | undefined {
   const raw = headers["set-cookie"];
   if (!raw) return undefined;
 
@@ -26,9 +24,7 @@ export function parseSessionCookie(
 /**
  * Parse the TIMEOUT value from Set-Cookie headers (seconds).
  */
-export function parseTimeoutCookie(
-  headers: http.IncomingHttpHeaders,
-): number | undefined {
+export function parseTimeoutCookie(headers: HttpHeaders): number | undefined {
   const raw = headers["set-cookie"];
   if (!raw) return undefined;