@zeldrisho/pi-web-fetch 0.5.2 → 0.5.4

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [0.5.4](https://github.com/zeldrisho/pi-packages/compare/pi-web-fetch-v0.5.3...pi-web-fetch-v0.5.4) (2026-08-12)
+
+### Bug fixes
+
+- **web-fetch:** Abort stalled response bodies instead of hanging ([0b0a080](https://github.com/zeldrisho/pi-packages/commit/0b0a080b6231944c3d7788af1a4710c3ca0cee78))
+- Apply CodeRabbit auto-fixes ([ddaa177](https://github.com/zeldrisho/pi-packages/commit/ddaa17764aedf0127c4057d3abb6900acfab2b78))
+
+## [0.5.3](https://github.com/zeldrisho/pi-packages/compare/pi-web-fetch-v0.5.2...pi-web-fetch-v0.5.3) (2026-08-12)
+
+### Bug fixes
+
+- **web-fetch:** Fall back across validated addresses before timing out ([32a000b](https://github.com/zeldrisho/pi-packages/commit/32a000bf367268d4ff38e7b45cb73d45ea894f5d))
+- **web-fetch:** Cancel attempts when the caller signal is already aborted ([2f62c95](https://github.com/zeldrisho/pi-packages/commit/2f62c95906e171cc974c9f5cdbd66cf3ecd65b56))
+
+### Maintenance
+
+- **deps:** Upgrade Vite+ toolchain to 0.2.9 ([9921cf3](https://github.com/zeldrisho/pi-packages/commit/9921cf3ffbed29f9c08ca3ab595a5096fadf2be0))
+
 ## [0.5.2](https://github.com/zeldrisho/pi-packages/compare/pi-web-fetch-v0.5.1...pi-web-fetch-v0.5.2) (2026-08-10)
 
 ### Bug fixes

package/README.md

@@ -20,7 +20,7 @@ The `web_fetch` tool accepts public HTTP and HTTPS URLs. It supports textual con
 
 For safety, the tool blocks URLs containing credentials, local hostnames, private or reserved network targets, unsafe redirects, raw responses larger than 5 MiB, and unsupported content types. The `maxCharacters` parameter controls returned Markdown length; it does not change the raw download limit.
 
-In Pi's interactive UI, fetched content uses Pi's standard collapsed preview; use the configured tool-expansion shortcut (`Ctrl+O` by default) to show all visible tool output. Output sent to the agent remains bounded. The `offset` parameter is a character offset into extracted content, not a byte range into the remote response. When a result is truncated, call the tool again with the returned `nextOffset` as `offset` to continue reading. Fetched and extracted pages are cached in byte-bounded memory for a limited time so continuation requests can reuse the same content. Concurrent requests for the same URL share one fetch; cancelling one caller does not cancel work still needed by another.
+In Pi's interactive UI, fetched content uses Pi's standard collapsed preview; use the configured tool-expansion shortcut (`Ctrl+O` by default) to show all visible tool output. Output sent to the agent remains bounded: each call returns at most `maxCharacters` characters of extracted Markdown (default 6,000) and is additionally capped by Pi's 2,000-line / 50 KiB tool-output limit, so fetching cannot bloat the conversation context. The `offset` parameter is a character offset into extracted content, not a byte range into the remote response. When a result is truncated, call the tool again with the returned `nextOffset` as `offset` to continue reading. Fetched and extracted pages are cached in byte-bounded memory for a limited time so continuation requests can reuse the same content. Concurrent requests for the same URL share one fetch; cancelling one caller does not cancel work still needed by another.
 
 Every result includes `details.truncation`. Complete output reports `{ truncated: false, strategy: "none" }`. Truncated output reports `strategy: "continuation"` and a valid `nextOffset`. The existing top-level `details.truncated` and `details.nextOffset` fields remain available.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeldrisho/pi-web-fetch",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "Pi extension for secure, bounded public web page fetching and Markdown extraction",
   "keywords": [
     "pi",
@@ -39,7 +39,8 @@
     "@earendil-works/pi-tui": "^0.84.0",
     "typebox": "^1.1.24",
     "typescript": "^7.0.0",
-    "vite-plus": "0.2.5"
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.9",
+    "vite-plus": "0.2.9"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",

package/src/fetch.ts

@@ -60,7 +60,10 @@ async function documentFromResponse(
     throw new Error(`web_fetch does not support ${contentType || "this content type"}.`);
   }
 
-  const raw = decodeResponse(await readResponseBytes(response, FETCH_MAX_BYTES), contentTypeHeader);
+  const raw = decodeResponse(
+    await readResponseBytes(response, FETCH_MAX_BYTES, signal),
+    contentTypeHeader,
+  );
   let markdown: string;
   let title: string | undefined;
   let extractor: CompleteDocument["extractor"] = "raw";

package/src/network-policy.ts

@@ -70,12 +70,24 @@ for (const [network, prefix] of GLOBALLY_REACHABLE_IPV6_EXCEPTIONS) {
 
 export interface ValidatedTarget {
   url: URL;
+  /** The preferred address used for the first connection attempt. */
   address: string;
   family: 4 | 6;
+  /**
+   * Every address resolved for the hostname, ordered for connection attempts.
+   * Absent for single-address targets constructed without DNS resolution.
+   */
+  addresses?: string[];
 }
 
 export type ResolveAddresses = (hostname: string) => Promise<string[]>;
 
+/**
+ * Determines whether an IP address belongs to a blocked or reserved address range.
+ *
+ * @param address - The IP address to evaluate
+ * @returns `true` if the address is invalid or blocked, `false` if it is allowed
+ */
 export function isPrivateAddress(address: string): boolean {
   const family = isIP(address);
   if (family === 4) return blockedIPv4Addresses.check(address, "ipv4");
@@ -86,6 +98,23 @@ export function isPrivateAddress(address: string): boolean {
   return true;
 }
 
+/**
+ * Orders addresses with IPv4 addresses before IPv6 addresses while preserving their original order within each family.
+ *
+ * @returns A copy of the addresses ordered with IPv4 addresses first.
+ */
+export function preferIpv4First(addresses: string[]): string[] {
+  return [...addresses].sort((a, b) => Number(isIP(b) === 4) - Number(isIP(a) === 4));
+}
+
+/**
+ * Validates an HTTP or HTTPS URL and resolves it to an allowed network target.
+ *
+ * @param value - The URL to validate.
+ * @param resolveHostname - Optional hostname resolver.
+ * @returns The validated URL, preferred connection address, address family, and ordered resolved addresses.
+ * @throws If the URL uses an unsupported scheme, contains credentials, targets a local hostname, resolves to a private or reserved address, or cannot be resolved to IPv4 or IPv6.
+ */
 export async function validateRemoteUrl(
   value: string | URL,
   resolveHostname?: ResolveAddresses,
@@ -115,8 +144,9 @@ export async function validateRemoteUrl(
   if (addresses.length === 0 || addresses.some(isPrivateAddress)) {
     throw new Error(`web_fetch blocks private or reserved network targets (${hostname}).`);
   }
-  const address = addresses[0];
+  const ordered = preferIpv4First(addresses);
+  const address = ordered[0];
   const family = isIP(address);
   if (family !== 4 && family !== 6) throw new Error(`web_fetch could not resolve ${hostname}.`);
-  return { url, address, family };
+  return { url, address, family, addresses: ordered };
 }

package/src/network-transport.ts

@@ -1,13 +1,35 @@
 import { request as httpRequest, type IncomingMessage } from "node:http";
 import { request as httpsRequest } from "node:https";
-import type { LookupFunction } from "node:net";
+import { isIP, type LookupFunction } from "node:net";
 import { formatSize } from "@earendil-works/pi-coding-agent";
 import type { ValidatedTarget } from "./network-policy";
 
 export const FETCH_MAX_BYTES = 5 * 1_024 * 1_024;
 
+/**
+ * Per-address connect deadline. A hanging address is abandoned after this
+ * budget so the next validated address can be tried inside the overall
+ * request timeout.
+ */
+export const CONNECT_ATTEMPT_TIMEOUT_MS = 4_000;
+
 const encoder = new TextEncoder();
 
+/** Builds an AbortError matching the DOMException name used by the abort signal. */
+function abortedError(): Error {
+  const error = new Error("Operation aborted.");
+  error.name = "AbortError";
+  return error;
+}
+
+/**
+ * Formats an error message for a response that exceeds the raw download limit.
+ *
+ * @param receivedBytes - The number of bytes received or reported by the response.
+ * @param maxBytes - The maximum allowed number of bytes.
+ * @param sizeIsExact - Whether `receivedBytes` is the exact response size.
+ * @returns A message describing the response size and configured limit.
+ */
 function responseTooLargeMessage(
   receivedBytes: number,
   maxBytes: number,
@@ -22,33 +44,118 @@ function responseTooLargeMessage(
   ].join(" ");
 }
 
-export async function requestPinned(
+/**
+ * Sends a request to a specific validated network address.
+ *
+ * @param target - The validated request target.
+ * @param address - The IPv4 or IPv6 address to use for the connection.
+ * @param signal - Signal used to cancel the request.
+ * @param attemptTimeoutMs - Maximum time allowed for the connection attempt.
+ * @returns The received response.
+ * @throws If `address` is not a valid IPv4 or IPv6 address.
+ */
+async function requestOnce(
   target: ValidatedTarget,
+  address: string,
   signal: AbortSignal,
+  attemptTimeoutMs: number,
 ): Promise<IncomingMessage> {
+  const family = isIP(address);
+  if (family !== 4 && family !== 6) throw new Error(`web_fetch could not resolve ${address}.`);
   const lookup: LookupFunction = (_hostname, options, callback) => {
-    if (options.all) callback(null, [{ address: target.address, family: target.family }]);
-    else callback(null, target.address, target.family);
+    if (options.all) callback(null, [{ address, family }]);
+    else callback(null, address, family);
   };
   const request = target.url.protocol === "https:" ? httpsRequest : httpRequest;
   return await new Promise((resolve, reject) => {
+    const controller = new AbortController();
+    let attemptExpired = false;
+    const timer = setTimeout(() => {
+      attemptExpired = true;
+      controller.abort();
+    }, attemptTimeoutMs);
+    const forwardAbort = () => controller.abort();
+    if (signal.aborted) controller.abort();
+    else signal.addEventListener("abort", forwardAbort, { once: true });
+    let settled = false;
+    const finish = (callback: () => void) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      signal.removeEventListener("abort", forwardAbort);
+      callback();
+    };
+    const unreachableError = () =>
+      new Error(`web_fetch could not reach ${address} within ${attemptTimeoutMs} ms.`);
     const outgoing = request(
       target.url,
       {
         lookup,
-        signal,
+        signal: controller.signal,
         headers: {
           Accept: "text/markdown, text/html, text/plain, application/json;q=0.9, */*;q=0.1",
           "User-Agent": "Mozilla/5.0 (compatible; PiWebFetch/1.0; +https://pi.dev)",
         },
       },
-      resolve,
+      (response) => {
+        if (controller.signal.aborted) {
+          // The attempt deadline or caller cancellation fired before response
+          // headers: drop the socket and report the reason.
+          response.destroy();
+          finish(() => reject(attemptExpired ? unreachableError() : abortedError()));
+        } else finish(() => resolve(response));
+      },
     );
-    outgoing.once("error", reject);
+    outgoing.once("error", (error) => {
+      // The per-attempt deadline surfaces as a raw AbortError from the HTTP
+      // client; report it as an unreachable address instead so the next
+      // validated address is tried and the final error explains itself.
+      if (attemptExpired) finish(() => reject(unreachableError()));
+      else finish(() => reject(error));
+    });
     outgoing.end();
   });
 }
 
+export interface RequestPinnedOptions {
+  /** Per-address connect deadline used to fall back to the next address. */
+  attemptTimeoutMs?: number;
+}
+
+/**
+ * Sends a request to the target using its validated addresses in sequence.
+ *
+ * @param options - Optional settings for individual connection attempts.
+ * @param options.attemptTimeoutMs - Maximum time allowed for each connection attempt in milliseconds.
+ * @returns The first successful HTTP response.
+ * @throws The final connection error if all addresses fail, or the abort error if the signal is aborted.
+ */
+export async function requestPinned(
+  target: ValidatedTarget,
+  signal: AbortSignal,
+  options: RequestPinnedOptions = {},
+): Promise<IncomingMessage> {
+  const attemptTimeoutMs = options.attemptTimeoutMs ?? CONNECT_ATTEMPT_TIMEOUT_MS;
+  const addresses = target.addresses?.length ? target.addresses : [target.address];
+  let lastError: unknown;
+  for (const address of addresses) {
+    try {
+      return await requestOnce(target, address, signal, attemptTimeoutMs);
+    } catch (error) {
+      lastError = error;
+      if (signal.aborted) throw error;
+    }
+  }
+  throw lastError ?? new Error("web_fetch could not connect.");
+}
+
+/**
+ * Retrieves a response header value by name.
+ *
+ * @param response - The response containing the header
+ * @param name - The header name to retrieve
+ * @returns The first header value, or `undefined` when the header is absent
+ */
 export function responseHeader(response: IncomingMessage, name: string): string | undefined {
   const value = response.headers[name];
   return Array.isArray(value) ? value[0] : value;
@@ -57,23 +164,41 @@ export function responseHeader(response: IncomingMessage, name: string): string
 export async function readResponseBytes(
   response: IncomingMessage,
   maxBytes: number,
+  signal?: AbortSignal,
 ): Promise<Uint8Array> {
   const declared = Number(responseHeader(response, "content-length"));
   if (Number.isFinite(declared) && declared > maxBytes) {
     response.destroy();
     throw new Error(responseTooLargeMessage(declared, maxBytes, true));
   }
+  // Once response headers arrive the connect deadline and caller signal are no
+  // longer wired to the socket, so a stalled body would otherwise hang the
+  // fetch forever. Keep the caller signal attached for the whole body read and
+  // drop the socket when it fires.
+  const forwardAbort = () => response.destroy();
+  if (signal?.aborted) response.destroy();
+  else signal?.addEventListener("abort", forwardAbort, { once: true });
   const chunks: Uint8Array[] = [];
   let total = 0;
-  for await (const value of response) {
-    const chunk = typeof value === "string" ? encoder.encode(value) : new Uint8Array(value);
-    total += chunk.byteLength;
-    if (total > maxBytes) {
-      response.destroy();
-      throw new Error(responseTooLargeMessage(total, maxBytes, false));
+  try {
+    for await (const value of response) {
+      const chunk = typeof value === "string" ? encoder.encode(value) : new Uint8Array(value);
+      total += chunk.byteLength;
+      if (total > maxBytes) {
+        response.destroy();
+        throw new Error(responseTooLargeMessage(total, maxBytes, false));
+      }
+      chunks.push(chunk);
     }
-    chunks.push(chunk);
+  } catch (error) {
+    if (signal?.aborted) throw abortedError();
+    throw error;
+  } finally {
+    signal?.removeEventListener("abort", forwardAbort);
   }
+  // Destroying the socket can end the stream without an error; detect a
+  // mid-read abort here as well so truncated bodies never look complete.
+  if (signal?.aborted) throw abortedError();
   const output = new Uint8Array(total);
   let offset = 0;
   for (const chunk of chunks) {