dsh-dl-server 0.3.1 → 0.4.1

package/lib/tools.js

@@ -80,6 +80,16 @@ export function registerTools({ ctx, queue, config }) {
               type: 'string',
               description: 'Optional expected SHA-256. The job fails if the finished file does not match.',
             },
+            headers: {
+              type: 'object',
+              description:
+                'Optional HTTP request headers sent with every attempt, including mirror probes and ' +
+                'resumes. Use this for CDNs that refuse a bare request — Bilibili media needs ' +
+                '{"Referer": "https://www.bilibili.com"}, some hosts want a Cookie or User-Agent. ' +
+                'Range, Host, Content-Length and similar transport headers cannot be set. ' +
+                'Values are stored locally but never echoed back: job output lists header names only.',
+              additionalProperties: { type: 'string' },
+            },
           },
           required: ['urls', 'dest'],
           additionalProperties: false,
@@ -87,7 +97,12 @@ export function registerTools({ ctx, queue, config }) {
         async execute(args, exec) {
           try {
             const job = await queue.enqueue(
-              { urls: args.urls, destPath: args.dest, expectSha256: args.sha256 },
+              {
+                urls: args.urls,
+                destPath: args.dest,
+                expectSha256: args.sha256,
+                headers: args.headers,
+              },
               withCaller(exec),
             )
             return {

package/lib/transport.js

@@ -7,6 +7,7 @@ import { Readable } from 'node:stream'
 import { pipeline } from 'node:stream/promises'
 import { randomBytes } from 'node:crypto'
 import { sameResource } from './mirrors.js'
+import { toAria2Headers } from './headers.js'
 
 /**
  * Transport layer. Two channels: an aria2c JSON-RPC daemon when one is
@@ -23,6 +24,8 @@ import { sameResource } from './mirrors.js'
  * @property {number} [speedLimitKbps]  0 or absent means unlimited
  * @property {string} [proxy]           e.g. http://127.0.0.1:65532
  * @property {number} [bytesDone]       resume hint for the direct channel
+ * @property {Record<string, string>} [headers]  custom HTTP headers sent with
+ *                                      every attempt (probe, aria2, direct)
  * @property {(url: string, ok: boolean) => void} [onUrlResult]
  * @property {(done: number, total: number) => void} [onProgress]
  * @property {AbortSignal} [signal]
@@ -57,6 +60,30 @@ export function planTransfer(sizeBytes, cap = 16) {
 const IS_WIN = process.platform === 'win32'
 const ARIA2_BIN = IS_WIN ? 'aria2c.exe' : 'aria2c'
 
+/**
+ * The command that installs aria2 on this platform.
+ *
+ * Missing aria2 is the single most common fresh-install problem: the queue keeps
+ * working through the single-stream fallback, so nothing fails loudly and the
+ * user just concludes that DLS is slow. Every surface that mentions the fallback
+ * quotes this string, so the advice cannot drift from the detection code.
+ *
+ * @param {NodeJS.Platform} [platform]
+ * @returns {string}
+ */
+export function aria2InstallHint(platform = process.platform) {
+  switch (platform) {
+    case 'win32':
+      return 'winget install aria2.aria2 （或从 https://github.com/aria2/aria2/releases 下载）'
+    case 'darwin':
+      return 'brew install aria2'
+    case 'linux':
+      return 'sudo apt install aria2 （Fedora: sudo dnf install aria2，Arch: sudo pacman -S aria2）'
+    default:
+      return '安装 aria2 并把 aria2c 放进 PATH'
+  }
+}
+
 /** Absolute locations worth checking beyond PATH. */
 function extraCandidates() {
   if (IS_WIN) {
@@ -193,17 +220,36 @@ export class Transport {
     this.config = config
     this.log = log
     this.mode = 'direct'
+    this.aria2Missing = false
     this.aria2 = undefined
     this.rpc = undefined
     /** @type {Map<string, { verified: string[], rejected: { url: string, reason: string }[] }>} */
     this.mirrorReports = new Map()
   }
 
+  /**
+   * Channel snapshot for `download_status`. When aria2 is missing the view
+   * carries the install hint so an agent reading a slow transfer can tell the
+   * user what to fix instead of guessing.
+   */
+  modeInfo() {
+    if (this.aria2Missing) {
+      return { mode: 'direct', aria2Missing: true, hint: aria2InstallHint() }
+    }
+    return { mode: this.mode }
+  }
+
   /** Detect aria2 and start the daemon if possible. Never throws. */
   async init() {
     const binary = await findAria2(this.config.aria2Path)
     if (!binary) {
-      this.log('info', 'aria2c not found, using the single-stream fallback')
+      this.aria2Missing = true
+      // warn, not info: this is the difference between 136 MB/s and 13 MB/s and
+      // the fallback is silent otherwise.
+      this.log(
+        'warn',
+        `aria2c 未找到，回退到单流模式（速度约为并发的 1/10）。安装：${aria2InstallHint()}`,
+      )
       return
     }
 
@@ -250,11 +296,12 @@ export class Transport {
 
   /** @param {TransferOptions} options @returns {Promise<TransferResult>} */
   async transfer(options) {
-    const origin = await this.#probeHead(options.urls[0], options.signal)
+    const headers = options.headers
+    const origin = await this.#probeHead(options.urls[0], options.signal, headers)
     const plan = planTransfer(origin.length, options.connectionsCap ?? options.connections ?? this.config.connectionsPerJob ?? 16)
     const connections = options.connections ?? plan.connections
 
-    const urls = await this.#verifiedUrls(options.urls, origin, options.signal)
+    const urls = await this.#verifiedUrls(options.urls, origin, options.signal, headers)
     const useAria2 = this.mode === 'aria2' && this.rpc && !options.preferDirect && !plan.direct
 
     if (useAria2) {
@@ -278,8 +325,9 @@ export class Transport {
    * @param {string[]} urls
    * @param {{ length: number, etag?: string }} origin
    * @param {AbortSignal} [signal]
+   * @param {Record<string, string>} [headers]
    */
-  async #verifiedUrls(urls, origin, signal) {
+  async #verifiedUrls(urls, origin, signal, headers) {
     if (urls.length <= 1) return urls
 
     const accepted = [urls[0]]
@@ -287,7 +335,7 @@ export class Transport {
     const rejected = []
 
     for (const mirror of urls.slice(1)) {
-      const head = await this.#probeHead(mirror, signal)
+      const head = await this.#probeHead(mirror, signal, headers)
       const verdict = sameResource(origin, head)
       if (verdict.ok) {
         accepted.push(mirror)
@@ -310,9 +358,10 @@ export class Transport {
    * planner stays conservative.
    * @param {string} url
    * @param {AbortSignal} [signal]
+   * @param {Record<string, string>} [headers] needed for CDNs that 403 a bare HEAD
    * @returns {Promise<{ length: number, etag?: string }>}
    */
-  async #probeHead(url, signal) {
+  async #probeHead(url, signal, headers) {
     if (!url) return { length: -1 }
     const controller = new AbortController()
     const timer = setTimeout(() => controller.abort(), 5000)
@@ -321,7 +370,7 @@ export class Transport {
     signal?.addEventListener('abort', onAbort, { once: true })
 
     try {
-      const response = await fetch(url, { method: 'HEAD', signal: controller.signal })
+      const response = await fetch(url, { method: 'HEAD', headers, signal: controller.signal })
       if (!response.ok) return { length: -1 }
       const length = Number(response.headers.get('content-length') ?? 0)
       const etag = response.headers.get('etag') ?? undefined
@@ -335,7 +384,7 @@ export class Transport {
   }
 
   /** @param {TransferOptions} options */
-  async #transferAria2({ urls, destPath, connections, speedLimitKbps, onProgress, signal }) {
+  async #transferAria2({ urls, destPath, connections, speedLimitKbps, headers, onProgress, signal }) {
     const rpc = this.rpc
     await fs.mkdir(path.dirname(destPath), { recursive: true })
 
@@ -351,6 +400,10 @@ export class Transport {
     }
     const limit = speedLimitKbps ?? this.config.speedLimitKbps ?? 0
     if (limit > 0) options['max-download-limit'] = `${limit}K`
+    // aria2 wants one "Name: Value" string per `--header`; it applies them to
+    // every URI of the download, which is what a mirror group needs.
+    const headerList = toAria2Headers(headers)
+    if (headerList) options.header = headerList
 
     const gid = await rpc.call('aria2.addUri', [urls, options])
 
@@ -385,7 +438,7 @@ export class Transport {
   }
 
   /** @param {TransferOptions} options */
-  async #transferDirect({ urls, destPath, bytesDone = 0, onProgress, onUrlResult, signal }) {
+  async #transferDirect({ urls, destPath, bytesDone = 0, headers, onProgress, onUrlResult, signal }) {
     await fs.mkdir(path.dirname(destPath), { recursive: true })
     const partPath = `${destPath}.part`
     let lastError
@@ -399,10 +452,12 @@ export class Transport {
           offset = bytesDone
         }
 
-        const headers = {}
-        if (offset > 0) headers.range = `bytes=${offset}-`
+        // Custom headers first, then `range` — resume owns that one, and
+        // `normalizeHeaders` already rejects a caller-supplied Range.
+        const requestHeaders = { ...headers }
+        if (offset > 0) requestHeaders.range = `bytes=${offset}-`
 
-        const response = await fetch(url, { headers, signal })
+        const response = await fetch(url, { headers: requestHeaders, signal })
         if (!response.ok) throw new Error(`HTTP ${response.status}`)
 
         const ranged = response.status === 206

package/lib/types.js

@@ -12,6 +12,7 @@
  * @property {string} [origin]       subagent name, display and audit only
  * @property {string[]} urls
  * @property {string} destPath
+ * @property {Record<string, string>} [headers]  custom HTTP headers, sent on every attempt
  * @property {JobState} state
  * @property {PauseReason} [pauseReason]
  * @property {number} createdAt

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-dl-server",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "DLS — DSH Download Server: a global, session-aware, persistent download queue for DeepSeek Harness.",
   "type": "module",
   "main": "lib/index.js",
@@ -42,7 +42,7 @@
   },
   "scripts": {
     "test": "node --test",
-    "check": "node --check lib/index.js && node --check lib/domain.js && node --check lib/types.js"
+    "check": "node --check lib/index.js && node --check lib/domain.js && node --check lib/types.js && node --check lib/headers.js"
   },
   "dependencies": {
     "zod": "^4.4.3"