justget 0.1.6 → 0.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/README.browser.md +227 -0
  2. package/README.en.md +26 -1
  3. package/README.md +27 -2
  4. package/dist/browser/core/downloader.d.ts +31 -0
  5. package/dist/browser/core/downloader.d.ts.map +1 -0
  6. package/dist/browser/core/downloader.js +331 -0
  7. package/dist/browser/core/downloader.js.map +1 -0
  8. package/dist/browser/core/http.d.ts +38 -0
  9. package/dist/browser/core/http.d.ts.map +1 -0
  10. package/dist/browser/core/http.js +106 -0
  11. package/dist/browser/core/http.js.map +1 -0
  12. package/dist/browser/index.d.ts +18 -0
  13. package/dist/browser/index.d.ts.map +1 -0
  14. package/dist/browser/index.js +16 -0
  15. package/dist/browser/index.js.map +1 -0
  16. package/dist/browser/utils/buffer.d.ts +11 -0
  17. package/dist/browser/utils/buffer.d.ts.map +1 -0
  18. package/dist/browser/utils/buffer.js +30 -0
  19. package/dist/browser/utils/buffer.js.map +1 -0
  20. package/dist/browser/utils/cache.d.ts +36 -0
  21. package/dist/browser/utils/cache.d.ts.map +1 -0
  22. package/dist/browser/utils/cache.js +101 -0
  23. package/dist/browser/utils/cache.js.map +1 -0
  24. package/dist/browser/utils/hash.d.ts +23 -0
  25. package/dist/browser/utils/hash.d.ts.map +1 -0
  26. package/dist/browser/utils/hash.js +136 -0
  27. package/dist/browser/utils/hash.js.map +1 -0
  28. package/dist/cli.d.ts +8 -1
  29. package/dist/cli.d.ts.map +1 -1
  30. package/dist/cli.js +16 -9
  31. package/dist/cli.js.map +1 -1
  32. package/dist/config.d.ts.map +1 -1
  33. package/dist/config.js +1 -0
  34. package/dist/config.js.map +1 -1
  35. package/dist/core/downloader.d.ts.map +1 -1
  36. package/dist/core/downloader.js +17 -3
  37. package/dist/core/downloader.js.map +1 -1
  38. package/dist/core/temp.d.ts +5 -0
  39. package/dist/core/temp.d.ts.map +1 -1
  40. package/dist/core/temp.js +13 -0
  41. package/dist/core/temp.js.map +1 -1
  42. package/dist/downloader.d.ts +22 -0
  43. package/dist/downloader.d.ts.map +1 -0
  44. package/dist/downloader.js +564 -0
  45. package/dist/downloader.js.map +1 -0
  46. package/dist/types.d.ts +8 -2
  47. package/dist/types.d.ts.map +1 -1
  48. package/package.json +18 -27
@@ -0,0 +1,227 @@
1
+ # justget/browser — 浏览器端竞速下载
2
+
3
+ `justget/browser` 是 `justget` 的浏览器端版本,通过 `import { download } from 'justget/browser'` 使用。
4
+
5
+ ## 设计思路
6
+
7
+ ### 核心差异(与 Node.js 版)
8
+
9
+ | 特性 | Node.js `justget` | 浏览器 `justget/browser` |
10
+ |---|---|---|
11
+ | **分块 Range** | 分块并行下载 | ❌ 不分块,整文件下载 |
12
+ | **浏览器缓存** | 不利用 | ✅ 整文件请求 → 浏览器 HTTP 缓存自然生效 |
13
+ | **镜像策略** | 预热后全部启动 | ✅ 逐步释放,一次一个,按需启动 |
14
+ | **镜像记忆** | 无 | ✅ localStorage 学习型缓存,下次提为主站 |
15
+ | **存储** | 临时文件(fs) | ✅ 内存(Uint8Array[]) |
16
+ | **返回** | 文件路径 | ✅ Blob / Uint8Array |
17
+ | **哈希** | Node crypto | ✅ Web Crypto API |
18
+ | **依赖** | node-fetch, commander, progress | ✅ 零依赖 |
19
+ | **竞速** | 分块竞速 | ✅ 整文件竞速,先完成胜出 |
20
+ | **慢源替换** | 有 | ✅ 保留,慢于最快源 1/3 则 abort |
21
+
22
+ ### 竞速策略
23
+
24
+ ```
25
+ 主源启动 → 预热(5s)
26
+ ├─ 速度达标(>2MB/s) → 单源完成,浏览器缓存
27
+ └─ 速度不达标(<500KB/s) → 启动 mirror-1
28
+ ├─ 现在最快源达标 → 等它完成
29
+ └─ 仍不达标 → 启动 mirror-2
30
+ └─ 仍不达标 → 启动 mirror-3 ...
31
+ └─ 任一完成 → 胜出,abort 其余
32
+ ```
33
+
34
+ ### 学习型缓存(localStorage)
35
+
36
+ ```
37
+ 第1次:主站(慢) → 启动 mirror-1(成功) → 记到 localStorage
38
+ 第2次:查 localStorage → mirror-1 提为主站 → 直接下载,秒开
39
+ ```
40
+
41
+ - key: `justget:cache:{资源URL的FNV哈希}`
42
+ - value: `{ bestUrl, timestamp, successCount }`
43
+ - 7 天自动过期
44
+
45
+ ## 快速开始
46
+
47
+ ```bash
48
+ npm install justget
49
+ ```
50
+
51
+ ```typescript
52
+ import { download } from 'justget/browser';
53
+
54
+ // 基本下载 → 返回 Blob
55
+ const result = await download({
56
+ url: 'https://example.com/models/face-detection.bin',
57
+ });
58
+
59
+ // result.data 是 Blob,可直接用于 createObjectURL
60
+ const url = URL.createObjectURL(result.data as Blob);
61
+ ```
62
+
63
+ ### 带镜像回退
64
+
65
+ ```typescript
66
+ const result = await download({
67
+ url: 'https://github.com/xxx/models/face.bin',
68
+ mirrors: [
69
+ 'https://gh-proxy.com/...',
70
+ 'https://mirror.example.com/...',
71
+ ],
72
+ });
73
+ // 如果 mirror 成功,下次它自动当主站
74
+ ```
75
+
76
+ ### 带进度条
77
+
78
+ ```typescript
79
+ const result = await download({
80
+ url: 'https://example.com/models/large-model.onnx',
81
+ options: {
82
+ onProgress: (p) => {
83
+ console.log(`${p.percentage.toFixed(1)}% | ${(p.speed/1024).toFixed(0)} KB/s`);
84
+ },
85
+ },
86
+ });
87
+ ```
88
+
89
+ ### 获取 Uint8Array(直接喂给 face-api / WebAssembly)
90
+
91
+ ```typescript
92
+ const result = await download({
93
+ url: 'https://example.com/model.bin',
94
+ options: { responseType: 'uint8array' },
95
+ });
96
+ // result.data 是 Uint8Array
97
+ const bytes = result.data as Uint8Array;
98
+ ```
99
+
100
+ ### 校验 checksum
101
+
102
+ ```typescript
103
+ const result = await download({
104
+ url: 'https://example.com/model.bin',
105
+ options: {
106
+ checksum: 'b413e420d6840b2775fba32008db6f3cddb07d485967fb42cfcf379c16a8c589',
107
+ checksumAlgorithm: 'sha256',
108
+ },
109
+ });
110
+ ```
111
+
112
+ ## 与 face-api 集成示例
113
+
114
+ ```typescript
115
+ import { download } from 'justget/browser';
116
+ import * as faceapi from '@vladmandic/face-api';
117
+
118
+ // 下载模型文件(竞速 + SHA-256 校验;不匹配自动剔除该源重跑竞速)
119
+ const modelResult = await download({
120
+ url: 'https://cdn.jsdelivr.net/npm/@vladmandic/face-api@1.7.15/model/face_recognition_model.bin',
121
+ mirrors: [
122
+ 'https://unpkg.com/@vladmandic/face-api@1.7.15/model/face_recognition_model.bin',
123
+ 'https://gitee.com/justdb-mirrors/face-models/releases/download/face-api-1.7.15/face_recognition_model.bin',
124
+ ],
125
+ options: {
126
+ checksum: 'b413e420d6840b2775fba32008db6f3cddb07d485967fb42cfcf379c16a8c589',
127
+ responseType: 'uint8array',
128
+ onProgress: (p) => updateProgressBar(p.percentage),
129
+ },
130
+ });
131
+ const modelBytes = modelResult.data as Uint8Array;
132
+
133
+ // 喂给 face-api:face-api 的 load() 只收 URI 或 Float32Array,没有
134
+ // loadFromBuffer —— 用 fetch 拦截把已下载(已校验)的字节喂给
135
+ // loadFromUri,避免它再从网络拉一遍:
136
+ const MODEL_URL = 'https://cdn.jsdelivr.net/npm/@vladmandic/face-api@1.7.15/model/';
137
+ const origFetch = window.fetch;
138
+ window.fetch = async (input, init) => {
139
+ const u = typeof input === 'string' ? input : (input as Request).url;
140
+ if (u.startsWith(MODEL_URL)) {
141
+ return new Response(modelBytes, {
142
+ headers: { 'Content-Type': 'application/octet-stream' },
143
+ });
144
+ }
145
+ return origFetch(input, init);
146
+ };
147
+ try {
148
+ await faceapi.nets.faceRecognitionNet.loadFromUri(MODEL_URL);
149
+ } finally {
150
+ window.fetch = origFetch; // 用完即还原,不污染全局 fetch
151
+ }
152
+ ```
153
+
154
+ > 注:需要一并拦截/替换 manifest JSON(`loadFromUri` 会先拉
155
+ > `*-weights_manifest.json` 再拉 `.bin`),逐文件下载时把 manifest
156
+ > 也走 download() 校验后一并拦截即可。
157
+
158
+ ## API
159
+
160
+ ### `download(options: DownloadOptions): Promise<DownloadResult>`
161
+
162
+ | 参数 | 类型 | 默认 | 说明 |
163
+ |---|---|---|---|
164
+ | `url` | `string` | — | 主站 URL(必填) |
165
+ | `mirrors` | `string[]` | `[]` | 镜像 URL 列表 |
166
+ | `options.primaryWarmupTime` | `number` | `5000` | 主站预热 ms |
167
+ | `options.speedThreshold` | `number` | `512000` | 速度阈值 B/s,低于此值启动镜像 |
168
+ | `options.fastPrimaryThreshold` | `number` | `2048000` | 快速阈值 B/s,高于此值不启动镜像 |
169
+ | `options.sizeThreshold` | `number` | `52428800` | 文件大小阈值 B |
170
+ | `options.minReplaceTime` | `number` | `30000` | 慢源替换最短等待 ms |
171
+ | `options.replaceCheckInterval` | `number` | `10000` | 检查间隔 ms |
172
+ | `options.retries` | `number` | `3` | 重试次数 |
173
+ | `options.timeout` | `number` | `300000` | 下载超时 ms |
174
+ | `options.connectTimeout` | `number` | `10000` | 连接超时 ms |
175
+ | `options.checksum` | `string` | — | 预期校验和 |
176
+ | `options.checksumAlgorithm` | `'md5'\|'sha1'\|'sha256'\|'sha512'` | `'sha256'` | 校验算法(md5 不受 Web Crypto 支持,会抛错) |
177
+
178
+ **checksum 降级语义**:胜出源校验不匹配不会直接失败——库会在**本次调用内**剔除该源并
179
+ 用剩余源重跑竞速,直至校验通过或源穷尽(穷尽时抛最后一个
180
+ `ChecksumMismatchError`,含 `expected` / `actual` / `badUrl`,调用方可据此
181
+ 自行处理污染源)。镜像清单是调用方意图,库**不跨调用持久化“坏源”**。
182
+ 注意:重跑竞速会重新计耗时与进度回调,`onComplete` 只在最终成功后触发。
183
+ | `options.responseType` | `'blob'\|'uint8array'` | `'blob'` | 返回类型 |
184
+ | `options.onProgress` | `(p: ProgressInfo) => void` | — | 进度回调 |
185
+ | `options.onComplete` | `(r: DownloadResult) => void` | — | 完成回调 |
186
+
187
+ ### 返回 `DownloadResult`
188
+
189
+ ```typescript
190
+ interface DownloadResult {
191
+ data: Blob | Uint8Array; // 下载的数据
192
+ bytes: number; // 总字节数
193
+ duration: number; // 耗时 ms
194
+ averageSpeed: number; // 平均速度 B/s
195
+ sources: SourceResult[]; // 各源结果
196
+ mimeType: string; // MIME 类型
197
+ }
198
+ ```
199
+
200
+ ## 缓存 API(独立使用)
201
+
202
+ ```typescript
203
+ import { saveBestSource, loadBestSource, prioritizeMirrors, recordSuccess } from 'justget/browser';
204
+
205
+ // 手动记录
206
+ saveBestSource('https://example.com/model.bin', 'https://mirror.example.com/model.bin');
207
+
208
+ // 手动读取
209
+ const best = loadBestSource('https://example.com/model.bin');
210
+ // → 'https://mirror.example.com/model.bin'
211
+
212
+ // 重排镜像列表(把缓存的最优源提到主站)
213
+ const { primaryUrl, mirrors } = prioritizeMirrors(
214
+ 'https://example.com/model.bin',
215
+ ['https://mirror1.com/...', 'https://mirror2.com/...'],
216
+ 'https://example.com/model.bin'
217
+ );
218
+ ```
219
+
220
+ ## 开发
221
+
222
+ ```bash
223
+ npm run build # 构建 Node.js + 浏览器版
224
+ npm run build:browser # 仅构建浏览器版
225
+ npm run build:node # 仅构建 Node.js 版
226
+ npm test # 测试
227
+ ```
package/README.en.md CHANGED
@@ -47,6 +47,29 @@ Verified scenarios:
47
47
 
48
48
  ## 📦 Install
49
49
 
50
+ > Published on npm: <https://www.npmjs.com/package/justget> (current version `0.1.7`)
51
+
52
+ Requires Node.js ≥ 18.
53
+
54
+ ### Option 1: Global install (use as CLI)
55
+
56
+ ```bash
57
+ npm install -g justget
58
+ # or
59
+ yarn global add justget
60
+ # or
61
+ pnpm add -g justget
62
+ ```
63
+
64
+ Then use it directly from the command line:
65
+
66
+ ```bash
67
+ justget --version
68
+ justget <url> -o file.zip
69
+ ```
70
+
71
+ ### Option 2: Install into your project (use as a library)
72
+
50
73
  ```bash
51
74
  npm install justget
52
75
  # or
@@ -55,7 +78,9 @@ yarn add justget
55
78
  pnpm add justget
56
79
  ```
57
80
 
58
- Requires Node.js ≥ 18.
81
+ ```typescript
82
+ import { download } from 'justget';
83
+ ```
59
84
 
60
85
  ---
61
86
 
package/README.md CHANGED
@@ -9,7 +9,7 @@
9
9
 
10
10
  </div>
11
11
 
12
- **简体中文** · [English](./README.en.md)
12
+ **简体中文** · [English](./README.en.md) · [浏览器版 Browser](./README.browser.md)
13
13
 
14
14
  ---
15
15
 
@@ -64,6 +64,29 @@ justget https://github.com/xxx/releases/download/v1.0/file.zip \
64
64
 
65
65
  ## 📦 安装 / Install
66
66
 
67
+ > 已发布到 npm:<https://www.npmjs.com/package/justget>(当前版本 `0.1.7`)
68
+
69
+ 需要 Node.js ≥ 18。
70
+
71
+ ### 方式一:作为 CLI 全局安装(命令行使用)
72
+
73
+ ```bash
74
+ npm install -g justget
75
+ # 或 / or
76
+ yarn global add justget
77
+ # 或 / or
78
+ pnpm add -g justget
79
+ ```
80
+
81
+ 安装后即可直接使用命令:
82
+
83
+ ```bash
84
+ justget --version
85
+ justget <url> -o file.zip
86
+ ```
87
+
88
+ ### 方式二:作为库安装到项目(代码调用)
89
+
67
90
  ```bash
68
91
  npm install justget
69
92
  # 或 / or
@@ -72,7 +95,9 @@ yarn add justget
72
95
  pnpm add justget
73
96
  ```
74
97
 
75
- 需要 Node.js ≥ 18。
98
+ ```typescript
99
+ import { download } from 'justget';
100
+ ```
76
101
 
77
102
  ---
78
103
 
@@ -0,0 +1,31 @@
1
+ /**
2
+ * 核心下载器(浏览器版):整文件竞速 + 镜像学习缓存,内存存储
3
+ * Browser downloader: full-file racing + learning cache, in-memory
4
+ *
5
+ * 设计要点:
6
+ * 1. 不分块 Range,整文件下载 → 浏览器缓存友好
7
+ * 2. 主源先启动,预热后速度慢则逐步释放镜像(一次一个)
8
+ * 3. 先完成者胜出,其余 abort
9
+ * 4. 全程内存存储(Uint8Array[]),无临时文件
10
+ * 5. 支持 checksum 校验(Web Crypto API)
11
+ * 6. 学习型缓存(localStorage):记住哪个镜像成功过,下次提为主站
12
+ */
13
+ import type { DownloadOptions, DownloadResult } from '../../types.js';
14
+ /** checksum 不匹配:可降级错误(剔除胜者源后重跑竞速) */
15
+ export declare class ChecksumMismatchError extends Error {
16
+ readonly expected: string;
17
+ readonly actual: string;
18
+ readonly badUrl: string;
19
+ constructor(expected: string, actual: string, badUrl: string);
20
+ }
21
+ /**
22
+ * 多源整文件竞速下载(浏览器版)
23
+ * 主源 → 速度慢则逐步释放镜像 → 先完成者胜出
24
+ */
25
+ export declare function download(options: DownloadOptions): Promise<DownloadResult>;
26
+ export declare class Downloader {
27
+ private options;
28
+ constructor(options: DownloadOptions);
29
+ start(): Promise<DownloadResult>;
30
+ }
31
+ //# sourceMappingURL=downloader.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"downloader.d.ts","sourceRoot":"","sources":["../../../src/browser/core/downloader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAQH,OAAO,KAAK,EACV,eAAe,EAEf,cAAc,EAIf,MAAM,gBAAgB,CAAC;AAmCxB,qCAAqC;AACrC,qBAAa,qBAAsB,SAAQ,KAAK;aAE5B,QAAQ,EAAE,MAAM;aAChB,MAAM,EAAE,MAAM;aACd,MAAM,EAAE,MAAM;gBAFd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM;CAKjC;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAgChF;AAiQD,qBAAa,UAAU;IACrB,OAAO,CAAC,OAAO,CAAkB;gBACrB,OAAO,EAAE,eAAe;IACpC,KAAK,IAAI,OAAO,CAAC,cAAc,CAAC;CACjC"}
@@ -0,0 +1,331 @@
1
+ /**
2
+ * 核心下载器(浏览器版):整文件竞速 + 镜像学习缓存,内存存储
3
+ * Browser downloader: full-file racing + learning cache, in-memory
4
+ *
5
+ * 设计要点:
6
+ * 1. 不分块 Range,整文件下载 → 浏览器缓存友好
7
+ * 2. 主源先启动,预热后速度慢则逐步释放镜像(一次一个)
8
+ * 3. 先完成者胜出,其余 abort
9
+ * 4. 全程内存存储(Uint8Array[]),无临时文件
10
+ * 5. 支持 checksum 校验(Web Crypto API)
11
+ * 6. 学习型缓存(localStorage):记住哪个镜像成功过,下次提为主站
12
+ */
13
+ import { mergeConfig, validateConfig, isImmediateFailure, REPLACEMENT_CONFIG } from '../../config.js';
14
+ import { SpeedMonitor } from '../../speed/speed-monitor.js';
15
+ import { openStream, consumeBody } from './http.js';
16
+ import { concatBuffers } from '../utils/buffer.js';
17
+ import { digest } from '../utils/hash.js';
18
+ import { prioritizeMirrors, recordSuccess } from '../utils/cache.js';
19
+ function sleep(ms) {
20
+ return new Promise((resolve) => setTimeout(resolve, ms));
21
+ }
22
+ /** checksum 不匹配:可降级错误(剔除胜者源后重跑竞速) */
23
+ export class ChecksumMismatchError extends Error {
24
+ expected;
25
+ actual;
26
+ badUrl;
27
+ constructor(expected, actual, badUrl) {
28
+ super(`Checksum mismatch: expected ${expected}, got ${actual}`);
29
+ this.expected = expected;
30
+ this.actual = actual;
31
+ this.badUrl = badUrl;
32
+ this.name = 'ChecksumMismatchError';
33
+ }
34
+ }
35
+ /**
36
+ * 多源整文件竞速下载(浏览器版)
37
+ * 主源 → 速度慢则逐步释放镜像 → 先完成者胜出
38
+ */
39
+ export async function download(options) {
40
+ const startedAt = Date.now();
41
+ const { url, mirrors = [] } = options;
42
+ if (!url)
43
+ throw new Error('url is required');
44
+ const cfg = mergeConfig(options.options);
45
+ validateConfig(cfg);
46
+ // checksum 校验失败 → 剔除胜者源、重跑竞速,直至校验通过或源穷尽
47
+ // (仅在本次调用内降级;不持久化“坏源”——镜像清单是调用方意图,库不默默丢源)
48
+ let candidates = [url, ...mirrors];
49
+ let lastMismatch;
50
+ let result;
51
+ for (;;) {
52
+ if (candidates.length === 0) {
53
+ throw lastMismatch ?? new Error('Download failed: no source could complete');
54
+ }
55
+ try {
56
+ result = await runDownload(candidates[0], candidates.slice(1), cfg, options.url);
57
+ break;
58
+ }
59
+ catch (err) {
60
+ if (err instanceof ChecksumMismatchError) {
61
+ candidates = candidates.filter((u) => u !== err.badUrl);
62
+ lastMismatch = err;
63
+ continue;
64
+ }
65
+ throw err;
66
+ }
67
+ }
68
+ const final = { ...result, duration: Date.now() - startedAt };
69
+ if (cfg.onComplete)
70
+ cfg.onComplete(final);
71
+ return final;
72
+ }
73
+ async function runDownload(url, mirrors, cfg, resourceUrl) {
74
+ const startedAt = Date.now();
75
+ // 0) 学习型缓存:上次成功过的镜像直接提为主站
76
+ const reordered = prioritizeMirrors(url, mirrors, resourceUrl);
77
+ url = reordered.primaryUrl;
78
+ mirrors = reordered.mirrors;
79
+ // 1) HEAD 探测(拿文件大小 + Content-Type)
80
+ let contentLength;
81
+ let mimeType = 'application/octet-stream';
82
+ try {
83
+ const headRes = await fetch(url, { method: 'HEAD', redirect: 'follow' });
84
+ if (headRes.ok) {
85
+ const cl = headRes.headers.get('content-length');
86
+ if (cl)
87
+ contentLength = Number(cl);
88
+ const ct = headRes.headers.get('content-type');
89
+ if (ct)
90
+ mimeType = ct.split(';')[0].trim();
91
+ }
92
+ }
93
+ catch { /* 不影响 GET */ }
94
+ const ctx = {
95
+ contentLength,
96
+ workers: [],
97
+ cfg,
98
+ done: false,
99
+ mirrorsStartedCount: 0,
100
+ primaryFailedImmediately: false,
101
+ winner: null,
102
+ overallStartedAt: startedAt,
103
+ };
104
+ const emitProgress = () => {
105
+ if (!cfg.onProgress)
106
+ return;
107
+ const sources = ctx.workers.map((w) => ({
108
+ id: w.id, url: w.url,
109
+ downloadedBytes: w.bytesWritten,
110
+ speed: w.monitor.getCurrentSpeed(),
111
+ status: w.status,
112
+ }));
113
+ const downloadedBytes = ctx.winner
114
+ ? ctx.winner.chunks.reduce((s, c) => s + c.byteLength, 0)
115
+ : ctx.workers.reduce((sum, w) => sum + w.bytesWritten, 0);
116
+ const total = contentLength ?? downloadedBytes;
117
+ const instant = ctx.workers.reduce((sum, w) => sum + w.monitor.getCurrentSpeed(), 0);
118
+ const elapsedMs = Math.max(1, Date.now() - startedAt);
119
+ const speed = instant > 0 ? instant : downloadedBytes > 0 ? (downloadedBytes / elapsedMs) * 1000 : 0;
120
+ cfg.onProgress({
121
+ downloadedBytes, totalBytes: total,
122
+ percentage: total > 0 ? (downloadedBytes / total) * 100 : 0,
123
+ speed, eta: speed > 0 ? ((total - downloadedBytes) / speed) * 1000 : 0,
124
+ sources,
125
+ });
126
+ };
127
+ // 2) 镜像启动决策:逐步释放,一次一个
128
+ const needMoreMirrors = () => {
129
+ if (mirrors.length === 0)
130
+ return false;
131
+ if (ctx.mirrorsStartedCount >= mirrors.length)
132
+ return false;
133
+ const active = ctx.workers.filter((w) => w.status === 'active' && !w.aborted);
134
+ if (active.length === 0)
135
+ return true;
136
+ const fastest = active.reduce((a, b) => a.monitor.getCurrentSpeed() > b.monitor.getCurrentSpeed() ? a : b);
137
+ const fastestSpeed = fastest.monitor.getCurrentSpeed();
138
+ if (fastestSpeed >= (cfg.fastPrimaryThreshold ?? 2_048_000))
139
+ return false;
140
+ const size = contentLength ?? 0;
141
+ if (size < (cfg.sizeThreshold ?? 50 * 1024 * 1024))
142
+ return false;
143
+ if (fastestSpeed < (cfg.speedThreshold ?? 512_000))
144
+ return true;
145
+ return false;
146
+ };
147
+ const startNextMirror = () => {
148
+ const nextIndex = ctx.mirrorsStartedCount++;
149
+ if (nextIndex >= mirrors.length)
150
+ return;
151
+ const w = {
152
+ id: `mirror-${nextIndex}`,
153
+ url: mirrors[nextIndex],
154
+ isPrimary: false,
155
+ monitor: new SpeedMonitor(),
156
+ controller: new AbortController(),
157
+ aborted: false, slowChecks: 0, bytesWritten: 0,
158
+ startedAt: Date.now(), status: 'active', chunks: [],
159
+ };
160
+ startWorker(w);
161
+ };
162
+ const maybeStartMirrors = () => {
163
+ if (ctx.done || mirrors.length === 0)
164
+ return;
165
+ if (ctx.primaryFailedImmediately) {
166
+ while (ctx.mirrorsStartedCount < mirrors.length && !ctx.done)
167
+ startNextMirror();
168
+ return;
169
+ }
170
+ if (needMoreMirrors())
171
+ startNextMirror();
172
+ };
173
+ const startWorker = (w) => {
174
+ ctx.workers.push(w);
175
+ w.monitor.startSampling(() => w.bytesWritten);
176
+ void runWorker(w, ctx, emitProgress).catch((err) => {
177
+ w.error = err;
178
+ w.status = 'failed';
179
+ ctx.lastError = ctx.lastError ?? err;
180
+ if (w.isPrimary && isImmediateFailure(err, err.status)) {
181
+ ctx.primaryFailedImmediately = true;
182
+ maybeStartMirrors();
183
+ }
184
+ });
185
+ };
186
+ // 3) 启动主源
187
+ const primaryWorker = {
188
+ id: 'primary', url, isPrimary: true,
189
+ monitor: new SpeedMonitor(), controller: new AbortController(),
190
+ aborted: false, slowChecks: 0, bytesWritten: 0,
191
+ startedAt: Date.now(), status: 'active', chunks: [],
192
+ };
193
+ startWorker(primaryWorker);
194
+ // 4) 预热后决策
195
+ const warmupTimer = setTimeout(() => maybeStartMirrors(), cfg.primaryWarmupTime ?? 5000);
196
+ // 5) 定期检查:慢源替换 + 逐步释放镜像
197
+ const replaceCheck = setInterval(() => {
198
+ if (ctx.done)
199
+ return;
200
+ maybeStartMirrors();
201
+ const active = ctx.workers.filter((w) => w.status === 'active' && !w.aborted);
202
+ if (active.length < 2)
203
+ return;
204
+ if (Date.now() - startedAt < (cfg.minReplaceTime ?? 30_000))
205
+ return;
206
+ const fastest = active.reduce((a, b) => a.monitor.getCurrentSpeed() > b.monitor.getCurrentSpeed() ? a : b);
207
+ const fastestSpeed = fastest.monitor.getCurrentSpeed();
208
+ if (fastestSpeed <= 0)
209
+ return;
210
+ for (const w of active) {
211
+ if (w === fastest)
212
+ continue;
213
+ const ratio = w.monitor.getCurrentSpeed() / fastestSpeed;
214
+ if (ratio < REPLACEMENT_CONFIG.slowThresholdRatio) {
215
+ if (++w.slowChecks >= REPLACEMENT_CONFIG.maxSlowChecks) {
216
+ w.aborted = true;
217
+ w.status = 'failed';
218
+ w.controller.abort();
219
+ emitProgress();
220
+ }
221
+ }
222
+ else
223
+ w.slowChecks = 0;
224
+ }
225
+ }, cfg.replaceCheckInterval ?? 10_000);
226
+ // 6) 进度回调
227
+ const progressTimer = setInterval(emitProgress, 200);
228
+ try {
229
+ await waitForCompletion(ctx, cfg);
230
+ if (!ctx.done || !ctx.winner) {
231
+ throw ctx.lastError ?? new Error('Download failed: no source could complete');
232
+ }
233
+ for (const w of ctx.workers) {
234
+ if (w.status === 'active')
235
+ w.status = 'completed';
236
+ }
237
+ const data = concatBuffers(ctx.winner.chunks);
238
+ // 校验 checksum:不匹配抛 ChecksumMismatchError(由 download() 剔除该源后重跑竞速)
239
+ if (cfg.checksum) {
240
+ const algorithm = cfg.checksumAlgorithm ?? 'sha256';
241
+ const actual = await digest(data, algorithm);
242
+ if (actual !== cfg.checksum.toLowerCase()) {
243
+ throw new ChecksumMismatchError(cfg.checksum.toLowerCase(), actual, ctx.winner.url);
244
+ }
245
+ }
246
+ // 记录成功源到缓存(下次优先使用)
247
+ if (ctx.winner.url !== resourceUrl) {
248
+ recordSuccess(resourceUrl, ctx.winner.url);
249
+ }
250
+ const finalData = cfg.responseType === 'uint8array'
251
+ ? data
252
+ : new Blob([data], { type: mimeType });
253
+ const finalSize = contentLength ?? data.byteLength;
254
+ return summarize(finalData, finalSize, mimeType, ctx.workers, startedAt);
255
+ }
256
+ finally {
257
+ clearTimeout(warmupTimer);
258
+ clearInterval(replaceCheck);
259
+ clearInterval(progressTimer);
260
+ for (const w of ctx.workers) {
261
+ w.controller.abort();
262
+ w.monitor.stopSampling();
263
+ }
264
+ }
265
+ }
266
+ /** 整体看门狗:默认 timeout×3(竞速 + 慢源替换本身消耗时间,单源
267
+ * timeout 不适合做总限;×3 是竞速场景的经验余量) */
268
+ async function waitForCompletion(ctx, cfg) {
269
+ const overall = (cfg.timeout ?? 300_000) * 3;
270
+ const deadline = Date.now() + overall;
271
+ while (Date.now() < deadline) {
272
+ if (ctx.done)
273
+ return;
274
+ if (!ctx.workers.some((w) => w.status === 'active' && !w.aborted) && ctx.workers.length > 0) {
275
+ throw ctx.lastError ?? new Error('All sources failed');
276
+ }
277
+ await sleep(100);
278
+ }
279
+ throw new Error(`Download timeout (${overall}ms = timeout×3)`);
280
+ }
281
+ async function runWorker(w, ctx, emit) {
282
+ const stream = await openStream(w.url, {
283
+ connectTimeout: ctx.cfg.connectTimeout,
284
+ timeout: ctx.cfg.timeout,
285
+ signal: w.controller.signal,
286
+ });
287
+ try {
288
+ await consumeBody(stream.body, (chunk) => {
289
+ if (w.aborted)
290
+ throw new Error('Aborted');
291
+ w.chunks.push(chunk);
292
+ w.bytesWritten += chunk.byteLength;
293
+ }, w.controller.signal);
294
+ }
295
+ finally {
296
+ stream.cleanup(); // 自然完成也要清 bodyTimer,否则 300s 看门狗悬挂进程
297
+ }
298
+ if (!ctx.done) {
299
+ ctx.done = true;
300
+ ctx.winner = { chunks: w.chunks, mimeType: '', url: w.url };
301
+ w.status = 'completed';
302
+ for (const other of ctx.workers) {
303
+ if (other !== w && !other.aborted) {
304
+ other.aborted = true;
305
+ other.status = 'failed';
306
+ other.controller.abort();
307
+ }
308
+ }
309
+ emit();
310
+ }
311
+ }
312
+ function summarize(data, bytes, mimeType, workers, startedAt) {
313
+ const sources = workers.map((w) => ({
314
+ id: w.id, url: w.url, bytes: w.bytesWritten,
315
+ duration: Date.now() - w.startedAt,
316
+ averageSpeed: (w.bytesWritten / Math.max(1, Date.now() - w.startedAt)) * 1000,
317
+ status: w.status,
318
+ }));
319
+ const duration = Date.now() - startedAt;
320
+ return {
321
+ data, bytes, duration,
322
+ averageSpeed: duration > 0 ? (bytes / duration) * 1000 : 0,
323
+ sources, mimeType,
324
+ };
325
+ }
326
+ export class Downloader {
327
+ options;
328
+ constructor(options) { this.options = options; }
329
+ start() { return download(this.options); }
330
+ }
331
+ //# sourceMappingURL=downloader.js.map