@wwkit/shared 1.0.29 → 1.0.31

package/src/http.js

@@ -1,482 +1,482 @@
-/**
- * 共享 HTTP 工具（支持代理隧道）
- *
- * 统一 wwkit monorepo 各子包的 HTTP 请求、文件下载、代理隧道实现：
- *   - parseProxy: 解析代理 URL
- *   - openTunnel: 建立代理隧道 socket（SOCKS5 + HTTP CONNECT）
- *   - fetchText: 获取 URL 文本内容（支持代理 + 重定向）
- *   - downloadToFile: 下载文件到本地（支持代理 + 进度 + 重定向）
- *
- * 无代理时使用 native fetch；有代理时根据代理协议建立隧道：
- *   - http(s)://  HTTP 代理：HTTPS 目标走 CONNECT 隧道，HTTP 目标直接以绝对 URI 转发
- *   - socks5(h):// Socks5 代理：握手后隧道转发（支持无认证 / username-password 认证）
- */
-
-import fs from 'node:fs'
-import http from 'node:http'
-import net from 'node:net'
-import https from 'node:https'
-import tls from 'node:tls'
-
-const DEFAULT_TIMEOUT = 15000
-
-/**
- * 解析代理 URL 字符串
- * @param {string} raw - 代理 URL（如 socks5://user:pass@host:1080）
- * @returns {URL|null} URL 对象，无效时返回 null
- */
-export function parseProxy(raw) {
-  if (!raw) return null
-  try {
-    const u = new URL(raw)
-    if (!u.hostname) return null
-    if (u.protocol !== 'http:' && u.protocol !== 'https:' &&
-        u.protocol !== 'socks5:' && u.protocol !== 'socks:') {
-      return null
-    }
-    return u
-  } catch {
-    return null
-  }
-}
-
-/**
- * 建立裸 TCP 连接
- * @param {string} host
- * @param {number} port
- * @param {number} timeout
- * @returns {Promise<import('node:net').Socket>}
- * @private
- */
-function openTcp(host, port, timeout) {
-  return new Promise((resolve, reject) => {
-    const socket = net.connect({ host, port })
-    socket.setTimeout(timeout)
-    socket.setNoDelay(true)
-    socket.once('connect', () => {
-      socket.setTimeout(0)
-      resolve(socket)
-    })
-    socket.once('error', reject)
-    socket.once('timeout', () => {
-      socket.destroy()
-      reject(new Error('tcp connect timeout'))
-    })
-  })
-}
-
-/**
- * 对已连接的 socket 执行 TLS 握手
- * @param {import('node:net').Socket} socket
- * @param {string} host - SNI
- * @param {number} timeout
- * @returns {Promise<import('node:tls').TLSSocket>}
- * @private
- */
-function wrapTls(socket, host, timeout) {
-  return new Promise((resolve, reject) => {
-    const tlsSocket = tls.connect({ socket, servername: host, timeout }, () => {
-      tlsSocket.setTimeout(0)
-      resolve(tlsSocket)
-    })
-    tlsSocket.once('error', (err) => {
-      socket.destroy()
-      reject(err)
-    })
-    tlsSocket.once('timeout', () => {
-      tlsSocket.destroy()
-      reject(new Error('tls handshake timeout'))
-    })
-  })
-}
-
-/**
- * 通过 HTTP 代理建立 CONNECT 隧道
- * @param {URL} proxyUrl
- * @param {string} host
- * @param {number} port
- * @param {number} timeout
- * @returns {Promise<import('node:net').Socket>}
- * @private
- */
-function httpConnect(proxyUrl, host, port, timeout) {
-  return new Promise((resolve, reject) => {
-    const req = http.request({
-      host: proxyUrl.hostname,
-      port: proxyUrl.port || 80,
-      method: 'CONNECT',
-      path: `${host}:${port}`,
-      timeout
-    })
-    req.once('connect', (res, socket) => {
-      if (res.statusCode !== 200) {
-        socket.destroy()
-        reject(new Error(`CONNECT failed: ${res.statusCode}`))
-        return
-      }
-      socket.setTimeout(0)
-      resolve(socket)
-    })
-    req.once('error', reject)
-    req.once('timeout', () => {
-      req.destroy()
-      reject(new Error('CONNECT timeout'))
-    })
-    req.end()
-  })
-}
-
-/**
- * 通过 Socks5 代理建立隧道（RFC 1928）
- *
- * 支持三种地址类型（DOMAIN/IPv4/IPv6）与两种认证方式：
- * 无认证（0x00）、username/password（0x02，RFC 1929）。
- * 代理 URL 带用户名密码时自动使用 0x02 认证。
- *
- * @param {URL} proxyUrl - socks5://host:port 或 socks5://user:pass@host:port
- * @param {string} host - 目标主机名
- * @param {number} port - 目标端口
- * @param {number} timeout
- * @returns {Promise<import('node:net').Socket>}
- * @private
- */
-function socks5Connect(proxyUrl, host, port, timeout) {
-  const auth = proxyUrl.username
-    ? {
-        user: decodeURIComponent(proxyUrl.username),
-        pass: decodeURIComponent(proxyUrl.password || '')
-      }
-    : null
-
-  return openTcp(proxyUrl.hostname, proxyUrl.port || 1080, timeout).then(
-    (socket) =>
-      new Promise((resolve, reject) => {
-        const fail = (err) => {
-          socket.destroy()
-          reject(err instanceof Error ? err : new Error(String(err)))
-        }
-
-        const methods = auth ? [0x00, 0x02] : [0x00]
-        socket.write(Buffer.from([0x05, methods.length, ...methods]))
-
-        let stage = 'greeting'
-        let buf = Buffer.alloc(0)
-
-        const sendConnect = () => {
-          stage = 'connect'
-          const hostBuf = Buffer.from(host, 'utf8')
-          const req = Buffer.alloc(7 + hostBuf.length)
-          req[0] = 0x05
-          req[1] = 0x01
-          req[2] = 0x00
-          req[3] = 0x03
-          req[4] = hostBuf.length
-          hostBuf.copy(req, 5)
-          req.writeUInt16BE(port, 5 + hostBuf.length)
-          socket.write(req)
-        }
-
-        const onData = (chunk) => {
-          buf = Buffer.concat([buf, chunk])
-          try {
-            if (stage === 'greeting') {
-              if (buf.length < 2) return
-              const method = buf.readUInt8(1)
-              buf = buf.subarray(2)
-              if (method === 0xff) {
-                throw new Error('socks5: no acceptable auth method')
-              }
-              if (method === 0x02) {
-                if (!auth) {
-                  throw new Error('socks5: server requires auth, but none provided')
-                }
-                const userBuf = Buffer.from(auth.user, 'utf8')
-                const passBuf = Buffer.from(auth.pass, 'utf8')
-                const req = Buffer.alloc(3 + userBuf.length + passBuf.length)
-                req[0] = 0x01
-                req[1] = userBuf.length
-                userBuf.copy(req, 2)
-                req[2 + userBuf.length] = passBuf.length
-                passBuf.copy(req, 3 + userBuf.length)
-                socket.write(req)
-                stage = 'auth'
-                return
-              }
-              sendConnect()
-              return
-            }
-            if (stage === 'auth') {
-              if (buf.length < 2) return
-              if (buf.readUInt8(1) !== 0x00) {
-                throw new Error('socks5: username/password auth failed')
-              }
-              buf = buf.subarray(2)
-              sendConnect()
-              return
-            }
-            if (stage === 'connect') {
-              if (buf.length < 4) return
-              if (buf.readUInt8(0) !== 0x05) {
-                throw new Error('socks5: invalid reply version')
-              }
-              const rep = buf.readUInt8(1)
-              if (rep !== 0x00) {
-                throw new Error(`socks5: connect failed with code ${rep}`)
-              }
-              const atyp = buf.readUInt8(3)
-              let addrLen
-              if (atyp === 0x01) addrLen = 4
-              else if (atyp === 0x03) addrLen = buf.readUInt8(4) + 1
-              else if (atyp === 0x04) addrLen = 16
-              else {
-                throw new Error('socks5: invalid address type')
-              }
-              const total = 4 + addrLen + 2
-              if (buf.length < total) return
-              cleanup()
-              socket.setTimeout(0)
-              resolve(socket)
-            }
-          } catch (err) {
-            cleanup()
-            fail(err)
-          }
-        }
-
-        const cleanup = () => {
-          socket.removeListener('data', onData)
-          socket.removeListener('error', onError)
-          socket.removeListener('timeout', onTimeout)
-        }
-
-        const onError = (err) => {
-          cleanup()
-          fail(err)
-        }
-
-        const onTimeout = () => {
-          cleanup()
-          fail(new Error('socks5: timeout'))
-        }
-
-        socket.setTimeout(timeout)
-        socket.on('data', onData)
-        socket.on('error', onError)
-        socket.on('timeout', onTimeout)
-      })
-  )
-}
-
-/**
- * 建立到目标主机的隧道 socket（HTTPS 目标会完成 TLS 握手）
- *
- * @param {URL} proxyUrl - 代理 URL（已解析）
- * @param {string} scheme - 代理协议（http/https/socks5/socks5h）
- * @param {string} host - 目标主机名
- * @param {number} port - 目标端口
- * @param {boolean} isHttps - 目标是否为 HTTPS
- * @param {number} timeout - 超时（ms）
- * @returns {Promise<import('node:net').Socket>}
- * @private
- */
-function tunnelConnect(proxyUrl, scheme, host, port, isHttps, timeout) {
-  if (scheme === 'socks5' || scheme === 'socks5h' || scheme === 'socks') {
-    return socks5Connect(proxyUrl, host, port, timeout).then((socket) =>
-      isHttps ? wrapTls(socket, host, timeout) : socket
-    )
-  }
-  if (scheme === 'http' || scheme === 'https') {
-    if (isHttps) {
-      return httpConnect(proxyUrl, host, port, timeout).then((socket) =>
-        wrapTls(socket, host, timeout)
-      )
-    }
-    return openTcp(proxyUrl.hostname, proxyUrl.port || 80, timeout)
-  }
-  return Promise.reject(new Error(`Unsupported proxy scheme: ${scheme}`))
-}
-
-/**
- * 建立到目标 URL 的代理隧道 socket
- *
- * 高层接口：传入代理 URL 字符串和目标 URL，返回已建立隧道的 socket
- * （HTTPS 目标会完成 TLS 握手）。
- *
- * @param {URL|string} proxy - 代理 URL（字符串或已解析的 URL 对象）
- * @param {URL|string} target - 目标 URL（字符串或已解析的 URL 对象）
- * @param {number} [timeout=15000] - 超时（ms）
- * @returns {Promise<import('node:net').Socket>}
- */
-export function openTunnel(proxy, target, timeout = DEFAULT_TIMEOUT) {
-  const proxyUrl = typeof proxy === 'string' ? new URL(proxy) : proxy
-  const targetUrl = typeof target === 'string' ? new URL(target) : target
-  const scheme = proxyUrl.protocol.replace(/:$/, '')
-  const isHttps = targetUrl.protocol === 'https:'
-  const port = Number(targetUrl.port) || (isHttps ? 443 : 80)
-  return tunnelConnect(proxyUrl, scheme, targetUrl.hostname, port, isHttps, timeout)
-}
-
-/**
- * 把响应流写入文件（附进度回调）
- * @param {import('node:http').IncomingMessage} res
- * @param {string} destPath
- * @param {string} url
- * @param {(pct: number) => void} [onProgress]
- * @returns {Promise<void>}
- * @private
- */
-function pipeToFile(res, destPath, url, onProgress) {
-  return new Promise((resolve, reject) => {
-    const file = fs.createWriteStream(destPath)
-    const total = parseInt(res.headers['content-length'] || '0', 10)
-    let written = 0
-    let lastPct = 0
-    res.on('data', (chunk) => {
-      written += chunk.length
-      if (total > 0 && onProgress) {
-        const pct = Math.floor(written * 100 / total)
-        if (pct >= lastPct + 10 || written === total) {
-          lastPct = pct
-          onProgress(pct)
-        }
-      }
-    })
-    res.pipe(file)
-    file.on('finish', () => { file.close(); resolve() })
-    file.on('error', reject)
-    res.on('error', reject)
-  })
-}
-
-/**
- * 通过代理或直连把 URL 内容流式下载到文件
- *
- * @param {string} url - 请求 URL
- * @param {string} destPath - 目标文件路径
- * @param {{ proxy?: string, timeout?: number, onProgress?: (pct: number) => void }} [opts]
- * @returns {Promise<void>}
- */
-export async function downloadToFile(url, destPath, { proxy, timeout = 600000, onProgress } = {}) {
-  const target = new URL(url)
-  const isHttps = target.protocol === 'https:'
-  const targetPort = target.port || (isHttps ? 443 : 80)
-
-  if (!proxy) {
-    await new Promise((resolve, reject) => {
-      const proto = isHttps ? https : http
-      const req = proto.get(url, { timeout }, (res) => {
-        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
-          res.resume()
-          const next = new URL(res.headers.location, url).href
-          downloadToFile(next, destPath, { proxy, timeout, onProgress }).then(resolve, reject)
-          return
-        }
-        if (res.statusCode !== 200) {
-          reject(new Error(`HTTP ${res.statusCode}: ${url}`))
-          return
-        }
-        pipeToFile(res, destPath, url, onProgress).then(resolve, reject)
-      })
-      req.on('error', reject)
-      req.on('timeout', () => { req.destroy(); reject(new Error(`download timeout: ${url}`)) })
-    })
-    return
-  }
-
-  const proxyUrl = new URL(proxy)
-  const scheme = proxyUrl.protocol.replace(/:$/, '')
-
-  await new Promise((resolve, reject) => {
-    tunnelConnect(proxyUrl, scheme, target.hostname, targetPort, isHttps, timeout)
-      .then((socket) => {
-        const isProxiedPlainHttp = !isHttps && (scheme === 'http' || scheme === 'https')
-        const req = http.request({
-          createConnection: () => socket,
-          method: 'GET',
-          path: isProxiedPlainHttp ? url : target.pathname + target.search,
-          headers: { Host: target.host },
-          timeout,
-        }, (res) => {
-          if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
-            res.resume()
-            const next = new URL(res.headers.location, url).href
-            downloadToFile(next, destPath, { proxy, timeout, onProgress }).then(resolve, reject)
-            return
-          }
-          if (res.statusCode !== 200) {
-            reject(new Error(`HTTP ${res.statusCode}: ${url}`))
-            return
-          }
-          pipeToFile(res, destPath, url, onProgress).then(resolve, reject)
-        })
-        req.on('error', reject)
-        req.on('timeout', () => { req.destroy(); reject(new Error(`download timeout: ${url}`)) })
-        req.end()
-      })
-      .catch(reject)
-  })
-}
-
-/**
- * 通过代理或直连获取 URL 文本内容
- *
- * @param {string} url - 请求 URL
- * @param {{ proxy?: string, timeout?: number, maxRedirects?: number }} [opts] - 选项
- * @returns {Promise<string|null>}
- */
-export async function fetchText(url, { proxy, timeout = DEFAULT_TIMEOUT, maxRedirects = 5 } = {}) {
-  if (!proxy) {
-    try {
-      const resp = await fetch(url, { signal: AbortSignal.timeout(timeout) })
-      if (!resp.ok) return null
-      return await resp.text()
-    } catch {
-      return null
-    }
-  }
-
-  const target = new URL(url)
-  const proxyUrl = new URL(proxy)
-  const isHttps = target.protocol === 'https:'
-  const targetPort = target.port || (isHttps ? 443 : 80)
-  const scheme = proxyUrl.protocol.replace(/:$/, '')
-
-  return new Promise((resolve) => {
-    if (maxRedirects <= 0) {
-      resolve(null)
-      return
-    }
-
-    tunnelConnect(proxyUrl, scheme, target.hostname, targetPort, isHttps, timeout)
-      .then((socket) => {
-        const isProxiedPlainHttp = !isHttps && (scheme === 'http' || scheme === 'https')
-
-        const req = http.request({
-          createConnection: () => socket,
-          method: 'GET',
-          path: isProxiedPlainHttp ? url : target.pathname + target.search,
-          headers: { Host: target.host },
-          timeout
-        }, (response) => {
-          if (response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
-            const redirectUrl = new URL(response.headers.location, url).href
-            fetchText(redirectUrl, { proxy, timeout, maxRedirects: maxRedirects - 1 }).then(resolve)
-            return
-          }
-          if (response.statusCode < 200 || response.statusCode >= 300) {
-            resolve(null)
-            return
-          }
-          let data = ''
-          response.setEncoding('utf8')
-          response.on('data', (chunk) => { data += chunk })
-          response.on('end', () => resolve(data))
-        })
-
-        req.on('error', () => resolve(null))
-        req.on('timeout', () => { req.destroy(); resolve(null) })
-        req.end()
-      })
-      .catch(() => resolve(null))
-  })
-}
+/**
+ * 共享 HTTP 工具（支持代理隧道）
+ *
+ * 统一 wwkit monorepo 各子包的 HTTP 请求、文件下载、代理隧道实现：
+ *   - parseProxy: 解析代理 URL
+ *   - openTunnel: 建立代理隧道 socket（SOCKS5 + HTTP CONNECT）
+ *   - fetchText: 获取 URL 文本内容（支持代理 + 重定向）
+ *   - downloadToFile: 下载文件到本地（支持代理 + 进度 + 重定向）
+ *
+ * 无代理时使用 native fetch；有代理时根据代理协议建立隧道：
+ *   - http(s)://  HTTP 代理：HTTPS 目标走 CONNECT 隧道，HTTP 目标直接以绝对 URI 转发
+ *   - socks5(h):// Socks5 代理：握手后隧道转发（支持无认证 / username-password 认证）
+ */
+
+import fs from 'node:fs'
+import http from 'node:http'
+import net from 'node:net'
+import https from 'node:https'
+import tls from 'node:tls'
+
+const DEFAULT_TIMEOUT = 15000
+
+/**
+ * 解析代理 URL 字符串
+ * @param {string} raw - 代理 URL（如 socks5://user:pass@host:1080）
+ * @returns {URL|null} URL 对象，无效时返回 null
+ */
+export function parseProxy(raw) {
+  if (!raw) return null
+  try {
+    const u = new URL(raw)
+    if (!u.hostname) return null
+    if (u.protocol !== 'http:' && u.protocol !== 'https:' &&
+        u.protocol !== 'socks5:' && u.protocol !== 'socks:') {
+      return null
+    }
+    return u
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 建立裸 TCP 连接
+ * @param {string} host
+ * @param {number} port
+ * @param {number} timeout
+ * @returns {Promise<import('node:net').Socket>}
+ * @private
+ */
+function openTcp(host, port, timeout) {
+  return new Promise((resolve, reject) => {
+    const socket = net.connect({ host, port })
+    socket.setTimeout(timeout)
+    socket.setNoDelay(true)
+    socket.once('connect', () => {
+      socket.setTimeout(0)
+      resolve(socket)
+    })
+    socket.once('error', reject)
+    socket.once('timeout', () => {
+      socket.destroy()
+      reject(new Error('tcp connect timeout'))
+    })
+  })
+}
+
+/**
+ * 对已连接的 socket 执行 TLS 握手
+ * @param {import('node:net').Socket} socket
+ * @param {string} host - SNI
+ * @param {number} timeout
+ * @returns {Promise<import('node:tls').TLSSocket>}
+ * @private
+ */
+function wrapTls(socket, host, timeout) {
+  return new Promise((resolve, reject) => {
+    const tlsSocket = tls.connect({ socket, servername: host, timeout }, () => {
+      tlsSocket.setTimeout(0)
+      resolve(tlsSocket)
+    })
+    tlsSocket.once('error', (err) => {
+      socket.destroy()
+      reject(err)
+    })
+    tlsSocket.once('timeout', () => {
+      tlsSocket.destroy()
+      reject(new Error('tls handshake timeout'))
+    })
+  })
+}
+
+/**
+ * 通过 HTTP 代理建立 CONNECT 隧道
+ * @param {URL} proxyUrl
+ * @param {string} host
+ * @param {number} port
+ * @param {number} timeout
+ * @returns {Promise<import('node:net').Socket>}
+ * @private
+ */
+function httpConnect(proxyUrl, host, port, timeout) {
+  return new Promise((resolve, reject) => {
+    const req = http.request({
+      host: proxyUrl.hostname,
+      port: proxyUrl.port || 80,
+      method: 'CONNECT',
+      path: `${host}:${port}`,
+      timeout
+    })
+    req.once('connect', (res, socket) => {
+      if (res.statusCode !== 200) {
+        socket.destroy()
+        reject(new Error(`CONNECT failed: ${res.statusCode}`))
+        return
+      }
+      socket.setTimeout(0)
+      resolve(socket)
+    })
+    req.once('error', reject)
+    req.once('timeout', () => {
+      req.destroy()
+      reject(new Error('CONNECT timeout'))
+    })
+    req.end()
+  })
+}
+
+/**
+ * 通过 Socks5 代理建立隧道（RFC 1928）
+ *
+ * 支持三种地址类型（DOMAIN/IPv4/IPv6）与两种认证方式：
+ * 无认证（0x00）、username/password（0x02，RFC 1929）。
+ * 代理 URL 带用户名密码时自动使用 0x02 认证。
+ *
+ * @param {URL} proxyUrl - socks5://host:port 或 socks5://user:pass@host:port
+ * @param {string} host - 目标主机名
+ * @param {number} port - 目标端口
+ * @param {number} timeout
+ * @returns {Promise<import('node:net').Socket>}
+ * @private
+ */
+function socks5Connect(proxyUrl, host, port, timeout) {
+  const auth = proxyUrl.username
+    ? {
+        user: decodeURIComponent(proxyUrl.username),
+        pass: decodeURIComponent(proxyUrl.password || '')
+      }
+    : null
+
+  return openTcp(proxyUrl.hostname, proxyUrl.port || 1080, timeout).then(
+    (socket) =>
+      new Promise((resolve, reject) => {
+        const fail = (err) => {
+          socket.destroy()
+          reject(err instanceof Error ? err : new Error(String(err)))
+        }
+
+        const methods = auth ? [0x00, 0x02] : [0x00]
+        socket.write(Buffer.from([0x05, methods.length, ...methods]))
+
+        let stage = 'greeting'
+        let buf = Buffer.alloc(0)
+
+        const sendConnect = () => {
+          stage = 'connect'
+          const hostBuf = Buffer.from(host, 'utf8')
+          const req = Buffer.alloc(7 + hostBuf.length)
+          req[0] = 0x05
+          req[1] = 0x01
+          req[2] = 0x00
+          req[3] = 0x03
+          req[4] = hostBuf.length
+          hostBuf.copy(req, 5)
+          req.writeUInt16BE(port, 5 + hostBuf.length)
+          socket.write(req)
+        }
+
+        const onData = (chunk) => {
+          buf = Buffer.concat([buf, chunk])
+          try {
+            if (stage === 'greeting') {
+              if (buf.length < 2) return
+              const method = buf.readUInt8(1)
+              buf = buf.subarray(2)
+              if (method === 0xff) {
+                throw new Error('socks5: no acceptable auth method')
+              }
+              if (method === 0x02) {
+                if (!auth) {
+                  throw new Error('socks5: server requires auth, but none provided')
+                }
+                const userBuf = Buffer.from(auth.user, 'utf8')
+                const passBuf = Buffer.from(auth.pass, 'utf8')
+                const req = Buffer.alloc(3 + userBuf.length + passBuf.length)
+                req[0] = 0x01
+                req[1] = userBuf.length
+                userBuf.copy(req, 2)
+                req[2 + userBuf.length] = passBuf.length
+                passBuf.copy(req, 3 + userBuf.length)
+                socket.write(req)
+                stage = 'auth'
+                return
+              }
+              sendConnect()
+              return
+            }
+            if (stage === 'auth') {
+              if (buf.length < 2) return
+              if (buf.readUInt8(1) !== 0x00) {
+                throw new Error('socks5: username/password auth failed')
+              }
+              buf = buf.subarray(2)
+              sendConnect()
+              return
+            }
+            if (stage === 'connect') {
+              if (buf.length < 4) return
+              if (buf.readUInt8(0) !== 0x05) {
+                throw new Error('socks5: invalid reply version')
+              }
+              const rep = buf.readUInt8(1)
+              if (rep !== 0x00) {
+                throw new Error(`socks5: connect failed with code ${rep}`)
+              }
+              const atyp = buf.readUInt8(3)
+              let addrLen
+              if (atyp === 0x01) addrLen = 4
+              else if (atyp === 0x03) addrLen = buf.readUInt8(4) + 1
+              else if (atyp === 0x04) addrLen = 16
+              else {
+                throw new Error('socks5: invalid address type')
+              }
+              const total = 4 + addrLen + 2
+              if (buf.length < total) return
+              cleanup()
+              socket.setTimeout(0)
+              resolve(socket)
+            }
+          } catch (err) {
+            cleanup()
+            fail(err)
+          }
+        }
+
+        const cleanup = () => {
+          socket.removeListener('data', onData)
+          socket.removeListener('error', onError)
+          socket.removeListener('timeout', onTimeout)
+        }
+
+        const onError = (err) => {
+          cleanup()
+          fail(err)
+        }
+
+        const onTimeout = () => {
+          cleanup()
+          fail(new Error('socks5: timeout'))
+        }
+
+        socket.setTimeout(timeout)
+        socket.on('data', onData)
+        socket.on('error', onError)
+        socket.on('timeout', onTimeout)
+      })
+  )
+}
+
+/**
+ * 建立到目标主机的隧道 socket（HTTPS 目标会完成 TLS 握手）
+ *
+ * @param {URL} proxyUrl - 代理 URL（已解析）
+ * @param {string} scheme - 代理协议（http/https/socks5/socks5h）
+ * @param {string} host - 目标主机名
+ * @param {number} port - 目标端口
+ * @param {boolean} isHttps - 目标是否为 HTTPS
+ * @param {number} timeout - 超时（ms）
+ * @returns {Promise<import('node:net').Socket>}
+ * @private
+ */
+function tunnelConnect(proxyUrl, scheme, host, port, isHttps, timeout) {
+  if (scheme === 'socks5' || scheme === 'socks5h' || scheme === 'socks') {
+    return socks5Connect(proxyUrl, host, port, timeout).then((socket) =>
+      isHttps ? wrapTls(socket, host, timeout) : socket
+    )
+  }
+  if (scheme === 'http' || scheme === 'https') {
+    if (isHttps) {
+      return httpConnect(proxyUrl, host, port, timeout).then((socket) =>
+        wrapTls(socket, host, timeout)
+      )
+    }
+    return openTcp(proxyUrl.hostname, proxyUrl.port || 80, timeout)
+  }
+  return Promise.reject(new Error(`Unsupported proxy scheme: ${scheme}`))
+}
+
+/**
+ * 建立到目标 URL 的代理隧道 socket
+ *
+ * 高层接口：传入代理 URL 字符串和目标 URL，返回已建立隧道的 socket
+ * （HTTPS 目标会完成 TLS 握手）。
+ *
+ * @param {URL|string} proxy - 代理 URL（字符串或已解析的 URL 对象）
+ * @param {URL|string} target - 目标 URL（字符串或已解析的 URL 对象）
+ * @param {number} [timeout=15000] - 超时（ms）
+ * @returns {Promise<import('node:net').Socket>}
+ */
+export function openTunnel(proxy, target, timeout = DEFAULT_TIMEOUT) {
+  const proxyUrl = typeof proxy === 'string' ? new URL(proxy) : proxy
+  const targetUrl = typeof target === 'string' ? new URL(target) : target
+  const scheme = proxyUrl.protocol.replace(/:$/, '')
+  const isHttps = targetUrl.protocol === 'https:'
+  const port = Number(targetUrl.port) || (isHttps ? 443 : 80)
+  return tunnelConnect(proxyUrl, scheme, targetUrl.hostname, port, isHttps, timeout)
+}
+
+/**
+ * 把响应流写入文件（附进度回调）
+ * @param {import('node:http').IncomingMessage} res
+ * @param {string} destPath
+ * @param {string} url
+ * @param {(pct: number) => void} [onProgress]
+ * @returns {Promise<void>}
+ * @private
+ */
+function pipeToFile(res, destPath, url, onProgress) {
+  return new Promise((resolve, reject) => {
+    const file = fs.createWriteStream(destPath)
+    const total = parseInt(res.headers['content-length'] || '0', 10)
+    let written = 0
+    let lastPct = 0
+    res.on('data', (chunk) => {
+      written += chunk.length
+      if (total > 0 && onProgress) {
+        const pct = Math.floor(written * 100 / total)
+        if (pct >= lastPct + 10 || written === total) {
+          lastPct = pct
+          onProgress(pct)
+        }
+      }
+    })
+    res.pipe(file)
+    file.on('finish', () => { file.close(); resolve() })
+    file.on('error', reject)
+    res.on('error', reject)
+  })
+}
+
+/**
+ * 通过代理或直连把 URL 内容流式下载到文件
+ *
+ * @param {string} url - 请求 URL
+ * @param {string} destPath - 目标文件路径
+ * @param {{ proxy?: string, timeout?: number, onProgress?: (pct: number) => void }} [opts]
+ * @returns {Promise<void>}
+ */
+export async function downloadToFile(url, destPath, { proxy, timeout = 600000, onProgress } = {}) {
+  const target = new URL(url)
+  const isHttps = target.protocol === 'https:'
+  const targetPort = target.port || (isHttps ? 443 : 80)
+
+  if (!proxy) {
+    await new Promise((resolve, reject) => {
+      const proto = isHttps ? https : http
+      const req = proto.get(url, { timeout }, (res) => {
+        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          res.resume()
+          const next = new URL(res.headers.location, url).href
+          downloadToFile(next, destPath, { proxy, timeout, onProgress }).then(resolve, reject)
+          return
+        }
+        if (res.statusCode !== 200) {
+          reject(new Error(`HTTP ${res.statusCode}: ${url}`))
+          return
+        }
+        pipeToFile(res, destPath, url, onProgress).then(resolve, reject)
+      })
+      req.on('error', reject)
+      req.on('timeout', () => { req.destroy(); reject(new Error(`download timeout: ${url}`)) })
+    })
+    return
+  }
+
+  const proxyUrl = new URL(proxy)
+  const scheme = proxyUrl.protocol.replace(/:$/, '')
+
+  await new Promise((resolve, reject) => {
+    tunnelConnect(proxyUrl, scheme, target.hostname, targetPort, isHttps, timeout)
+      .then((socket) => {
+        const isProxiedPlainHttp = !isHttps && (scheme === 'http' || scheme === 'https')
+        const req = http.request({
+          createConnection: () => socket,
+          method: 'GET',
+          path: isProxiedPlainHttp ? url : target.pathname + target.search,
+          headers: { Host: target.host },
+          timeout,
+        }, (res) => {
+          if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+            res.resume()
+            const next = new URL(res.headers.location, url).href
+            downloadToFile(next, destPath, { proxy, timeout, onProgress }).then(resolve, reject)
+            return
+          }
+          if (res.statusCode !== 200) {
+            reject(new Error(`HTTP ${res.statusCode}: ${url}`))
+            return
+          }
+          pipeToFile(res, destPath, url, onProgress).then(resolve, reject)
+        })
+        req.on('error', reject)
+        req.on('timeout', () => { req.destroy(); reject(new Error(`download timeout: ${url}`)) })
+        req.end()
+      })
+      .catch(reject)
+  })
+}
+
+/**
+ * 通过代理或直连获取 URL 文本内容
+ *
+ * @param {string} url - 请求 URL
+ * @param {{ proxy?: string, timeout?: number, maxRedirects?: number }} [opts] - 选项
+ * @returns {Promise<string|null>}
+ */
+export async function fetchText(url, { proxy, timeout = DEFAULT_TIMEOUT, maxRedirects = 5 } = {}) {
+  if (!proxy) {
+    try {
+      const resp = await fetch(url, { signal: AbortSignal.timeout(timeout) })
+      if (!resp.ok) return null
+      return await resp.text()
+    } catch {
+      return null
+    }
+  }
+
+  const target = new URL(url)
+  const proxyUrl = new URL(proxy)
+  const isHttps = target.protocol === 'https:'
+  const targetPort = target.port || (isHttps ? 443 : 80)
+  const scheme = proxyUrl.protocol.replace(/:$/, '')
+
+  return new Promise((resolve) => {
+    if (maxRedirects <= 0) {
+      resolve(null)
+      return
+    }
+
+    tunnelConnect(proxyUrl, scheme, target.hostname, targetPort, isHttps, timeout)
+      .then((socket) => {
+        const isProxiedPlainHttp = !isHttps && (scheme === 'http' || scheme === 'https')
+
+        const req = http.request({
+          createConnection: () => socket,
+          method: 'GET',
+          path: isProxiedPlainHttp ? url : target.pathname + target.search,
+          headers: { Host: target.host },
+          timeout
+        }, (response) => {
+          if (response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
+            const redirectUrl = new URL(response.headers.location, url).href
+            fetchText(redirectUrl, { proxy, timeout, maxRedirects: maxRedirects - 1 }).then(resolve)
+            return
+          }
+          if (response.statusCode < 200 || response.statusCode >= 300) {
+            resolve(null)
+            return
+          }
+          let data = ''
+          response.setEncoding('utf8')
+          response.on('data', (chunk) => { data += chunk })
+          response.on('end', () => resolve(data))
+        })
+
+        req.on('error', () => resolve(null))
+        req.on('timeout', () => { req.destroy(); resolve(null) })
+        req.end()
+      })
+      .catch(() => resolve(null))
+  })
+}