dsh-dl-server 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jestions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# dsh-dl-server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+English | [中文](README.zh.md)
+
+**DLS** — DSH Download Server
+A global download service for DeepSeek Harness: visible across sessions, owned per session, persistent queue, pausable and resumable.
+
+> DLS is all you need
+
+---
+
+## Why
+
+Every existing DSH downloader is one tool function that blocks until the file lands. They make downloads **fast**; they don't solve three things:
+
+- the download dies when the session or the turn ends
+- there is no queue, no pause, no resume
+- nothing survives a restart
+
+DLS is the **queue layer**, not the transport layer.
+
+## Status
+
+`v0.1` — scaffold. Design: [SPEC.md](SPEC.md).
+
+| Module | State |
+| --- | --- |
+| Data model | done |
+| Persistent domain | done |
+| Transport (aria2 JSON-RPC + single-stream fallback) | done |
+| Queue engine (scheduling, ownership, pause reasons, checkpoints, recovery) | done |
+| Seven tools | done |
+| Real DSH install / verification | done (DSH 0.2.1-rc.5) |
+| Hermetic tests (`npm test`) | done |
+| User panel (v3) | later |
+
+## Tools (planned)
+
+```
+download_enqueue    download_status     download_wait
+download_pause      download_resume     download_cancel
+download_cleanup
+```
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,45 @@
+# dsh-dl-server
+
+[English](README.md) | 中文
+
+**DLS** — DSH Download Server
+大肥鱼自己的下载服务器插件
+
+> DLS is all you need
+
+---
+
+## 为什么
+
+现成的 DSH 下载插件都是「一个工具函数 + 阻塞等到下完」。它们让下载**变快**，但没解决三件事：
+
+- 会话或回合结束，下载就断了
+- 不能排队、不能暂停恢复
+- 进程重启，什么都没了
+
+DLS 做的是**队列层**，不是传输层。
+
+## 状态
+
+`v0.1` 脚手架阶段。完整设计见 [SPEC.md](SPEC.md)。
+
+| 模块 | 状态 |
+| --- | --- |
+| 数据模型 | ✅ |
+| 持久化 domain | ✅ |
+| `download_status` | 最小实现 |
+| 队列引擎 | 待做 |
+| 传输层（aria2 / Node 兜底） | 待做 |
+| 其余六个工具 | 待做 |
+
+## 工具（规划）
+
+```
+download_enqueue    download_status     download_wait
+download_pause      download_resume     download_cancel
+download_cleanup
+```
+
+## 许可
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,16 @@
+# dsh-dl-server bundle patch
+- insert:
+    - id: dsh-dl-server
+      name: 'dsh-dl-server'
+      config:
+        maxConcurrentJobs: 3
+        connectionsPerJob: 16
+        aria2Path: ''
+        aria2Port: 16801
+        speedLimitKbps: 0
+        proxy: ''
+        defaultDownloadDir: ''
+        checkpointSeconds: 30
+        autoResumeOnSessionReopen: true
+        autoResumeOnHostRestart: true
+        keepCompletedRecords: 200

package/lib/bootlog.js

@@ -0,0 +1,31 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+/**
+ * Minimal boot trace. Overwritten every boot, so it always describes the latest
+ * start. A support report is "send me %TEMP%/dls-boot.log".
+ */
+export const BOOT_LOG = path.join(os.tmpdir(), 'dls-boot.log')
+
+let started = false
+
+/** @param {string} step @param {string} [detail] */
+export function mark(step, detail) {
+  try {
+    if (!started) {
+      fs.writeFileSync(BOOT_LOG, `dsh-dl-server boot trace\n`)
+      started = true
+    }
+    const line = `${new Date().toISOString()}  ${step}${detail ? `  ${detail}` : ''}`
+    fs.appendFileSync(BOOT_LOG, `${line}\n`)
+  } catch {
+    /* tracing must never break the plugin */
+  }
+}
+
+/** @param {string} step @param {unknown} error */
+export function markFailure(step, error) {
+  const stack = error instanceof Error ? (error.stack ?? error.message) : String(error)
+  mark(`FAILED at ${step}`, stack.split('\n').slice(0, 6).join(' | '))
+}

package/lib/domain.js

@@ -0,0 +1,51 @@
+import { z } from 'zod'
+import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain'
+
+const JobRecordSchema = z.object({
+  id: z.string(),
+  seq: z.number().int().nonnegative(),
+
+  ownerWorkspace: z.string(),
+  ownerSession: z.string(),
+  origin: z.string().optional(),
+
+  urls: z.array(z.string()).min(1),
+  destPath: z.string(),
+
+  state: z.enum(['queued', 'running', 'paused', 'completed', 'failed', 'canceled']),
+  pauseReason: z.enum(['user', 'session_closed', 'host_restart']).optional(),
+
+  createdAt: z.number(),
+  updatedAt: z.number(),
+
+  bytesTotal: z.number(),
+  bytesCheckpoint: z.number(),
+
+  attempts: z.number().int().nonnegative(),
+  lastError: z.string().optional(),
+
+  expectSha256: z.string().optional(),
+  finalBytes: z.number().optional(),
+})
+
+/**
+ * The persistent queue domain.
+ *
+ * per-record: one corrupt job must not make the whole queue unreadable.
+ * backup-and-skip: move the bad document aside and keep booting.
+ * global.nextSeq: the global counter behind J# ids.
+ */
+export const JobDomain = defineDomain({
+  // Domain names must match /^[a-z][a-z0-9_]*$/ — hyphens are rejected at load.
+  name: 'dsh_dl_jobs',
+  version: 1,
+  layout: 'per-record',
+  invalidRecords: 'backup-and-skip',
+  tables: {
+    jobs: domainTable(JobRecordSchema),
+  },
+  global: {
+    initial: { nextSeq: 1 },
+    schema: z.object({ nextSeq: z.number().int().positive() }),
+  },
+})

package/lib/index.js

@@ -0,0 +1,92 @@
+import { JobDomain } from './domain.js'
+import { Queue } from './queue.js'
+import { Transport } from './transport.js'
+import { registerTools } from './tools.js'
+import { mark, markFailure } from './bootlog.js'
+
+export const name = 'dsh-dl-server'
+export const inject = ['tools', 'storageDomain']
+
+const DEFAULTS = Object.freeze({
+  maxConcurrentJobs: 3,
+  connectionsPerJob: 16,
+  aria2Path: '',
+  aria2Port: 16801,
+  speedLimitKbps: 0,
+  proxy: '',
+  defaultDownloadDir: '',
+  checkpointSeconds: 30,
+  autoResumeOnSessionReopen: true,
+  autoResumeOnHostRestart: true,
+  keepCompletedRecords: 200,
+})
+
+/**
+ * Use the host logger when one is available so INFO lines never land on stdout.
+ * @param {any} ctx
+ */
+function makeLog(ctx) {
+  try {
+    const factory = ctx?.logger
+    if (typeof factory === 'function') {
+      const logger = factory('dsh-dl-server')
+      if (logger && typeof logger.info === 'function') {
+        return (level, message) => {
+          const fn = logger[level] ?? logger.info
+          fn.call(logger, message)
+        }
+      }
+    }
+  } catch {
+    /* fall through to the console fallback */
+  }
+  return (level, message) => {
+    // DLS_DEBUG=1 surfaces INFO lines on stderr; useful when no host logger is wired.
+    if (process.env.DLS_DEBUG === '1' || level === 'warn' || level === 'error') {
+      console.error(`[dsh-dl-server] ${message}`)
+    }
+  }
+}
+
+/**
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {Partial<typeof DEFAULTS>} [rawConfig]
+ */
+export async function apply(ctx, rawConfig) {
+  mark('apply enter')
+
+  const config = { ...DEFAULTS, ...(rawConfig ?? {}) }
+  const log = makeLog(ctx)
+
+  try {
+    mark('opening domain')
+    const domain = await ctx.storageDomain.open(JobDomain)
+    mark('domain open')
+
+    const transport = new Transport(config, log)
+    await transport.init()
+    mark('transport ready', `mode=${transport.mode}`)
+
+    const queue = new Queue({ domain, transport, config, log })
+    await queue.recover()
+    mark('queue ready')
+
+    registerTools({ ctx, queue, config })
+    // The tools themselves register inside the deferred ctx.inject callback;
+    // this mark only records that the subscription was installed.
+    mark('registerTools dispatched')
+
+    ctx.effect(() => async () => {
+      await queue.close()
+      await transport.dispose()
+      await domain.close()
+    })
+    mark('effect installed')
+
+    log('info', `ready (transport: ${transport.mode}, concurrency: ${config.maxConcurrentJobs})`)
+    mark('apply done')
+  } catch (error) {
+    markFailure('apply', error)
+    throw error
+  }
+}