libfw-client 0.4.6 → 0.4.7
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.
- package/README.md +22 -12
- package/index.d.ts +30 -6
- package/index.js +31 -3
- package/package.json +9 -1
- package/pkg/libfw_client.d.ts +0 -142
- package/pkg/libfw_client.js +0 -972
- package/pkg/libfw_client_bg.wasm +0 -0
- package/pkg/libfw_client_bg.wasm.d.ts +0 -35
- package/pkg/package.json +0 -28
package/README.md
CHANGED
|
@@ -78,7 +78,7 @@ directory picker, so they must run from a user gesture (a click handler).
|
|
|
78
78
|
| `concurrency` | `4` | max files transferred in parallel |
|
|
79
79
|
| `uploadWindow` | `8` | in-flight chunks per single-file upload |
|
|
80
80
|
| `downloadWindow` | `4` | in-flight `Range` GETs per single-file download (`1` = sequential) |
|
|
81
|
-
| `compress` | `true` | request/send zrip (zstd) compression |
|
|
81
|
+
| `compress` | `true` | request/send zrip (zstd) compression — costs CPU per byte; on a link faster than the compressor (LAN, ≥30 MiB/s) `false` is several times faster, and uploads then take a zero-copy `Blob` path |
|
|
82
82
|
| `compressLevel` | `'balanced'` | `'auto'` \| `'fast'` \| `'balanced'` \| `'max'` \| number; `'auto'` benchmarks uploads |
|
|
83
83
|
| `chunkSize` | `2097152` (2 MiB) | shared chunk size for uploads and download ranges |
|
|
84
84
|
| `maxRetries` | `3` | retries per chunk/file |
|
|
@@ -101,9 +101,14 @@ Notes:
|
|
|
101
101
|
in-flight request budget as `concurrency × max(uploadWindow,
|
|
102
102
|
downloadWindow)`, so raising a window actually increases parallelism (it
|
|
103
103
|
used to be capped by `concurrency` alone).
|
|
104
|
-
- `chunkSize` is used by both directions
|
|
105
|
-
|
|
106
|
-
`
|
|
104
|
+
- `chunkSize` is used by both directions and is the unit of per-request
|
|
105
|
+
overhead — a bigger chunk means fewer requests, which on a fast link beats
|
|
106
|
+
more parallelism. It is also the starting point of an `autoTune` ramp (the
|
|
107
|
+
tuner tracks the measured link from there, inside the advertised range).
|
|
108
|
+
The download path buffers in-flight chunks for reordering, so peak memory is
|
|
109
|
+
roughly `downloadWindow × chunkSize`; when `concurrency × window × chunkSize`
|
|
110
|
+
exceeds the engine budget the in-flight window shrinks first (down to two
|
|
111
|
+
requests per file), not the chunk.
|
|
107
112
|
- `compressLevel` is a client *policy*, resolved against the server's
|
|
108
113
|
advertised range. `'auto'` additionally micro-benchmarks the range on a
|
|
109
114
|
real sample of the first uploaded file; downloads request the resolved
|
|
@@ -213,11 +218,13 @@ try {
|
|
|
213
218
|
disk in order. Each range retries independently; `Range`/`If-Range`/`416`
|
|
214
219
|
give resume against the server ETag. Files at or below 512 KiB stay on the
|
|
215
220
|
sequential path.
|
|
216
|
-
- **Uploads** — slice each file,
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
+
- **Uploads** — slice each file, probe the server's received ranges
|
|
222
|
+
(`x-libfw-session-status`), POST only the missing chunks with their absolute
|
|
223
|
+
offset (out of order), then commit with `x-libfw-final: 1`. Chunks are
|
|
224
|
+
compressed into zrip frames when `compress` is on; when it is off the engine
|
|
225
|
+
hands the browser a `Blob` of the chunk instead, so the bytes are streamed
|
|
226
|
+
straight from the file and never enter JS or WASM memory. A commit that fails
|
|
227
|
+
re-probes and refills rather than failing the task.
|
|
221
228
|
- **State machine** — `idle → downloading/uploading → paused → resumed →
|
|
222
229
|
completed/failed`. `pause()` stops scheduling new work; in-flight requests
|
|
223
230
|
are allowed to finish.
|
|
@@ -262,9 +269,12 @@ are sanitized; `..` and drive-like segments are rejected.
|
|
|
262
269
|
With `autoTune: true` the engine fetches `/capabilities`, starts at the
|
|
263
270
|
advertised minimums and ramps the per-file window, then cross-file
|
|
264
271
|
concurrency, from 1-second EWMA measurements. The chunk size follows the
|
|
265
|
-
measured throughput (~
|
|
266
|
-
|
|
267
|
-
|
|
272
|
+
measured throughput (~400 ms of data, clamped into the advertised range), and a
|
|
273
|
+
fresh ramp starts from the configured `chunkSize` rather than the advertised
|
|
274
|
+
minimum: a chunk is the unit of per-request overhead, so starting small means
|
|
275
|
+
thousands of round trips for bytes the link could have carried in a few big
|
|
276
|
+
requests. The zrip level is a policy, never ramped. Errors halve the parameters
|
|
277
|
+
and require two stable windows before settling.
|
|
268
278
|
|
|
269
279
|
A settle is reused by later transfers in the same client **and** cached in
|
|
270
280
|
`localStorage`:
|
package/index.d.ts
CHANGED
|
@@ -125,7 +125,17 @@ export interface LibfwClientOptions {
|
|
|
125
125
|
* parallelism (sequential downloads). Default `4`.
|
|
126
126
|
*/
|
|
127
127
|
downloadWindow?: number;
|
|
128
|
-
/**
|
|
128
|
+
/**
|
|
129
|
+
* Negotiate zrip compression. Default `true`.
|
|
130
|
+
*
|
|
131
|
+
* Compression runs in WASM, so it costs CPU per byte: on a fast link
|
|
132
|
+
* (LAN/loopback, or anything above roughly 30 MiB/s) turning it off is
|
|
133
|
+
* several times faster end to end — the same 32 MiB file uploaded at
|
|
134
|
+
* ~19 MiB/s compressed and ~125 MiB/s uncompressed in Chromium. It pays for
|
|
135
|
+
* itself only when the link is slower than the compressor (WAN, mobile).
|
|
136
|
+
* With `false`, uploads also take the zero-copy path: the engine hands the
|
|
137
|
+
* browser a `Blob` of the chunk and never touches the bytes itself.
|
|
138
|
+
*/
|
|
129
139
|
compress?: boolean;
|
|
130
140
|
/**
|
|
131
141
|
* zrip level policy when `compress` is on. `'fast'` = advertised minimum
|
|
@@ -139,7 +149,19 @@ export interface LibfwClientOptions {
|
|
|
139
149
|
* Downloads request the resolved level from the server.
|
|
140
150
|
*/
|
|
141
151
|
compressLevel?: number | 'auto' | 'fast' | 'balanced' | 'max';
|
|
142
|
-
/**
|
|
152
|
+
/**
|
|
153
|
+
* Shared chunk size in bytes for uploads and parallel downloads. Default
|
|
154
|
+
* 2 MiB.
|
|
155
|
+
*
|
|
156
|
+
* This is the unit of per-request overhead: raising it is what reduces the
|
|
157
|
+
* request count, so on a fast link (or behind a proxy that charges a round
|
|
158
|
+
* trip per request) a larger value is materially faster than many small
|
|
159
|
+
* ones. It is also the starting point of an `autoTune` ramp — the tuner then
|
|
160
|
+
* tracks the measured link from there, inside the server's advertised range
|
|
161
|
+
* (up to 32 MiB by default). Peak memory per transfer is
|
|
162
|
+
* `concurrency × window × chunkSize`, bounded by the engine; when the product
|
|
163
|
+
* does not fit, the in-flight window shrinks, not the chunk.
|
|
164
|
+
*/
|
|
143
165
|
chunkSize?: number;
|
|
144
166
|
/** Retries per chunk/file before failing. Default `3`. */
|
|
145
167
|
maxRetries?: number;
|
|
@@ -174,10 +196,12 @@ export interface LibfwClientOptions {
|
|
|
174
196
|
* Enable the adaptive tuning engine: the engine probes the server's
|
|
175
197
|
* `/capabilities` limits and TCP-style ramps the per-file window and
|
|
176
198
|
* cross-file concurrency from the advertised minimums using real transfer
|
|
177
|
-
* stats. The chunk size follows the measured throughput (~
|
|
178
|
-
* clamped into the advertised range)
|
|
179
|
-
*
|
|
180
|
-
*
|
|
199
|
+
* stats. The chunk size follows the measured throughput (~400 ms of it,
|
|
200
|
+
* clamped into the advertised range), starting from the configured
|
|
201
|
+
* `chunkSize` — a chunk is the unit of per-request overhead, so a small
|
|
202
|
+
* start costs thousands of round trips for the same bytes. The zrip level
|
|
203
|
+
* is a client policy from `compressLevel`, never ramped. When disabled the
|
|
204
|
+
* configured static values are used as-is. Default `false`.
|
|
181
205
|
*
|
|
182
206
|
* Tuning state lives in memory for this client instance (a settle is reused
|
|
183
207
|
* by later transfers and dropped on failure) **and** is cached in
|
package/index.js
CHANGED
|
@@ -224,7 +224,11 @@ export class LibfwClient {
|
|
|
224
224
|
* @param {number} [options.chunkSize=2097152] shared chunk size in bytes for
|
|
225
225
|
* both upload chunks and parallel download ranges. The same value is
|
|
226
226
|
* used on both paths, and any value works as long as the server and
|
|
227
|
-
* memory budget permit it (larger = fewer, bigger requests
|
|
227
|
+
* memory budget permit it (larger = fewer, bigger requests — the
|
|
228
|
+
* per-request overhead is what makes a small chunk slow on a fast
|
|
229
|
+
* link, so raise this on a LAN/fast link or behind a proxy that
|
|
230
|
+
* charges a round trip per request). It is also the starting point of
|
|
231
|
+
* an `autoTune` ramp.
|
|
228
232
|
* @param {number} [options.maxRetries=3] retries per chunk/file before failing
|
|
229
233
|
* @param {number} [options.baseRetryDelayMs=500] initial backoff (ms)
|
|
230
234
|
* @param {number} [options.maxRetryDelayMs=30000] backoff ceiling (ms)
|
|
@@ -247,8 +251,9 @@ export class LibfwClient {
|
|
|
247
251
|
* engine: the engine probes the server's `/capabilities` limits and
|
|
248
252
|
* TCP-style ramps the per-file window and cross-file concurrency from
|
|
249
253
|
* the advertised minimums using real transfer stats; the chunk size
|
|
250
|
-
* follows the measured throughput (~
|
|
251
|
-
* advertised range)
|
|
254
|
+
* follows the measured throughput (~400 ms of it, clamped into the
|
|
255
|
+
* advertised range) starting from the configured `chunkSize`, and the
|
|
256
|
+
* zrip level is a client policy from
|
|
252
257
|
* `compressLevel`, never ramped. When disabled the configured static
|
|
253
258
|
* values are used as-is. A settled result is kept in memory for this
|
|
254
259
|
* client instance (reused by later transfers, dropped on failure)
|
|
@@ -456,6 +461,7 @@ export class LibfwClient {
|
|
|
456
461
|
},
|
|
457
462
|
getFileList: () => this._getFileList(),
|
|
458
463
|
readFile: (path, offset, length) => this._readFile(path, offset, length),
|
|
464
|
+
readFileBlob: (path, offset, length) => this._readFileBlob(path, offset, length),
|
|
459
465
|
log: (msg) => {
|
|
460
466
|
if (typeof console !== 'undefined') console.debug(`[libfw] ${msg}`);
|
|
461
467
|
},
|
|
@@ -1322,6 +1328,28 @@ export class LibfwClient {
|
|
|
1322
1328
|
return new Uint8Array(buffer);
|
|
1323
1329
|
}
|
|
1324
1330
|
|
|
1331
|
+
/**
|
|
1332
|
+
* Engine callback: a `Blob` view of `length` bytes of an upload file.
|
|
1333
|
+
*
|
|
1334
|
+
* Used by the pass-through path (`compress: false`): the engine hands this
|
|
1335
|
+
* `Blob` straight to `XMLHttpRequest`, so the browser streams the range out
|
|
1336
|
+
* of the file and no byte is read into JS or copied into WASM. Keeps the
|
|
1337
|
+
* promise shape of {@link LibfwClient#_readFile} because the engine awaits
|
|
1338
|
+
* every file callback.
|
|
1339
|
+
* @param {string} path
|
|
1340
|
+
* @param {number} offset
|
|
1341
|
+
* @param {number} length
|
|
1342
|
+
* @returns {Promise<Blob>}
|
|
1343
|
+
* @private
|
|
1344
|
+
*/
|
|
1345
|
+
async _readFileBlob(path, offset, length) {
|
|
1346
|
+
const file = this._uploadFiles.get(path);
|
|
1347
|
+
if (!file) {
|
|
1348
|
+
throw new LibfwError(`upload source not found: ${path}`, 'storage');
|
|
1349
|
+
}
|
|
1350
|
+
return file.slice(offset, offset + length);
|
|
1351
|
+
}
|
|
1352
|
+
|
|
1325
1353
|
// ------------------------------------------------------------- controls
|
|
1326
1354
|
|
|
1327
1355
|
/** Pause the active transfer (state → `paused`). */
|
package/package.json
CHANGED
|
@@ -1,8 +1,16 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "libfw-client",
|
|
3
|
-
"version": "0.4.
|
|
3
|
+
"version": "0.4.7",
|
|
4
4
|
"description": "libfw client for browsers, providing high performance file transfer capabilities using WebAssembly.",
|
|
5
5
|
"license": "MIT",
|
|
6
|
+
"repository": {
|
|
7
|
+
"type": "git",
|
|
8
|
+
"url": "git+https://github.com/ArthurZhou/libfw.git"
|
|
9
|
+
},
|
|
10
|
+
"publishConfig": {
|
|
11
|
+
"access": "public",
|
|
12
|
+
"registry": "https://registry.npmjs.org/"
|
|
13
|
+
},
|
|
6
14
|
"type": "module",
|
|
7
15
|
"main": "index.js",
|
|
8
16
|
"module": "index.js",
|
package/pkg/libfw_client.d.ts
DELETED
|
@@ -1,142 +0,0 @@
|
|
|
1
|
-
/* tslint:disable */
|
|
2
|
-
/* eslint-disable */
|
|
3
|
-
|
|
4
|
-
/**
|
|
5
|
-
* WASM engine facade. Construct via `new LibfwClient(options)`.
|
|
6
|
-
*/
|
|
7
|
-
export class LibfwClient {
|
|
8
|
-
free(): void;
|
|
9
|
-
[Symbol.dispose](): void;
|
|
10
|
-
/**
|
|
11
|
-
* Cancel the active transfer (state → `failed`).
|
|
12
|
-
*/
|
|
13
|
-
cancel(): void;
|
|
14
|
-
/**
|
|
15
|
-
* Bytes transferred so far.
|
|
16
|
-
*/
|
|
17
|
-
done_bytes(): number;
|
|
18
|
-
/**
|
|
19
|
-
* Download a single file at `file_path` into the chosen local directory.
|
|
20
|
-
*/
|
|
21
|
-
download_file(base_url: string, token: string, file_path: string): Promise<any>;
|
|
22
|
-
/**
|
|
23
|
-
* Download every file under the virtual `dirPath` (empty = root).
|
|
24
|
-
*/
|
|
25
|
-
download_folder(base_url: string, token: string, dir_path: string): Promise<any>;
|
|
26
|
-
/**
|
|
27
|
-
* Whether callbacks have been installed.
|
|
28
|
-
*/
|
|
29
|
-
has_callbacks(): boolean;
|
|
30
|
-
/**
|
|
31
|
-
* Create an engine. `options` may include:
|
|
32
|
-
* `{ concurrency, uploadWindow, downloadWindow, compress,
|
|
33
|
-
* compressLevel, chunkSize, maxRetries, baseRetryDelayMs,
|
|
34
|
-
* maxRetryDelayMs, timeoutMs, autoTune, tuneTtlMs }`.
|
|
35
|
-
*/
|
|
36
|
-
constructor(opts: any);
|
|
37
|
-
/**
|
|
38
|
-
* Pause the active transfer (state → `paused`).
|
|
39
|
-
*/
|
|
40
|
-
pause(): void;
|
|
41
|
-
/**
|
|
42
|
-
* Progress in `[0, 1]`.
|
|
43
|
-
*/
|
|
44
|
-
progress(): number;
|
|
45
|
-
/**
|
|
46
|
-
* Resume a paused transfer.
|
|
47
|
-
*/
|
|
48
|
-
resume(): void;
|
|
49
|
-
/**
|
|
50
|
-
* Install the JS callbacks object (required before any transfer).
|
|
51
|
-
*/
|
|
52
|
-
set_callbacks(callbacks: any): void;
|
|
53
|
-
/**
|
|
54
|
-
* Install an `onTuning(phase, params, stats)` callback, invoked on
|
|
55
|
-
* every tuning state change (phase transitions and window evaluations).
|
|
56
|
-
*/
|
|
57
|
-
set_tune_callback(cb: any): void;
|
|
58
|
-
/**
|
|
59
|
-
* Current state: `idle | downloading | uploading | paused | completed |
|
|
60
|
-
* failed`.
|
|
61
|
-
*/
|
|
62
|
-
state(): string;
|
|
63
|
-
/**
|
|
64
|
-
* Total bytes to transfer.
|
|
65
|
-
*/
|
|
66
|
-
total_bytes(): number;
|
|
67
|
-
/**
|
|
68
|
-
* Snapshot the tuning engine: `{ phase, params, stats, capsHash }`.
|
|
69
|
-
*/
|
|
70
|
-
tune_state(): any;
|
|
71
|
-
/**
|
|
72
|
-
* Upload the files reported by the JS `getFileList` callback.
|
|
73
|
-
*/
|
|
74
|
-
upload(base_url: string, token: string): Promise<any>;
|
|
75
|
-
}
|
|
76
|
-
|
|
77
|
-
/**
|
|
78
|
-
* Read an optional string field from a JS object (helper for the SDK).
|
|
79
|
-
*/
|
|
80
|
-
export function js_option_string(obj: any, key: string): string | undefined;
|
|
81
|
-
|
|
82
|
-
export function start(): void;
|
|
83
|
-
|
|
84
|
-
export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
|
|
85
|
-
|
|
86
|
-
export interface InitOutput {
|
|
87
|
-
readonly memory: WebAssembly.Memory;
|
|
88
|
-
readonly __wbg_libfwclient_free: (a: number, b: number) => void;
|
|
89
|
-
readonly js_option_string: (a: any, b: number, c: number) => [number, number];
|
|
90
|
-
readonly libfwclient_cancel: (a: number) => void;
|
|
91
|
-
readonly libfwclient_done_bytes: (a: number) => number;
|
|
92
|
-
readonly libfwclient_download_file: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => any;
|
|
93
|
-
readonly libfwclient_download_folder: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => any;
|
|
94
|
-
readonly libfwclient_has_callbacks: (a: number) => number;
|
|
95
|
-
readonly libfwclient_new: (a: any) => number;
|
|
96
|
-
readonly libfwclient_pause: (a: number) => void;
|
|
97
|
-
readonly libfwclient_progress: (a: number) => number;
|
|
98
|
-
readonly libfwclient_resume: (a: number) => void;
|
|
99
|
-
readonly libfwclient_set_callbacks: (a: number, b: any) => void;
|
|
100
|
-
readonly libfwclient_set_tune_callback: (a: number, b: any) => void;
|
|
101
|
-
readonly libfwclient_state: (a: number) => [number, number];
|
|
102
|
-
readonly libfwclient_total_bytes: (a: number) => number;
|
|
103
|
-
readonly libfwclient_tune_state: (a: number) => any;
|
|
104
|
-
readonly libfwclient_upload: (a: number, b: number, c: number, d: number, e: number) => any;
|
|
105
|
-
readonly start: () => void;
|
|
106
|
-
readonly wasm_bindgen_fcaa1ccc421e504f___convert__closures_____invoke___wasm_bindgen_fcaa1ccc421e504f___JsValue__core_37ee0ce0c4cd57d5___result__Result_____wasm_bindgen_fcaa1ccc421e504f___JsError___true_: (a: number, b: number, c: any) => [number, number];
|
|
107
|
-
readonly wasm_bindgen_fcaa1ccc421e504f___convert__closures_____invoke___js_sys_acd39e4161e779fb___Function_fn_wasm_bindgen_fcaa1ccc421e504f___JsValue_____wasm_bindgen_fcaa1ccc421e504f___sys__Undefined___js_sys_acd39e4161e779fb___Function_fn_wasm_bindgen_fcaa1ccc421e504f___JsValue_____wasm_bindgen_fcaa1ccc421e504f___sys__Undefined_______true_: (a: number, b: number, c: any, d: any) => void;
|
|
108
|
-
readonly wasm_bindgen_fcaa1ccc421e504f___convert__closures_____invoke___wasm_bindgen_fcaa1ccc421e504f___JsValue______true_: (a: number, b: number, c: any) => void;
|
|
109
|
-
readonly wasm_bindgen_fcaa1ccc421e504f___convert__closures_____invoke___wasm_bindgen_fcaa1ccc421e504f___JsValue______true__2: (a: number, b: number, c: any) => void;
|
|
110
|
-
readonly wasm_bindgen_fcaa1ccc421e504f___convert__closures_____invoke_______true_: (a: number, b: number) => void;
|
|
111
|
-
readonly __wbindgen_malloc: (a: number, b: number) => number;
|
|
112
|
-
readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
|
|
113
|
-
readonly __wbindgen_exn_store: (a: number) => void;
|
|
114
|
-
readonly __externref_table_alloc: () => number;
|
|
115
|
-
readonly __wbindgen_externrefs: WebAssembly.Table;
|
|
116
|
-
readonly __wbindgen_free: (a: number, b: number, c: number) => void;
|
|
117
|
-
readonly __wbindgen_destroy_closure: (a: number, b: number) => void;
|
|
118
|
-
readonly __externref_table_dealloc: (a: number) => void;
|
|
119
|
-
readonly __wbindgen_start: () => void;
|
|
120
|
-
}
|
|
121
|
-
|
|
122
|
-
export type SyncInitInput = BufferSource | WebAssembly.Module;
|
|
123
|
-
|
|
124
|
-
/**
|
|
125
|
-
* Instantiates the given `module`, which can either be bytes or
|
|
126
|
-
* a precompiled `WebAssembly.Module`.
|
|
127
|
-
*
|
|
128
|
-
* @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
|
|
129
|
-
*
|
|
130
|
-
* @returns {InitOutput}
|
|
131
|
-
*/
|
|
132
|
-
export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
|
|
133
|
-
|
|
134
|
-
/**
|
|
135
|
-
* If `module_or_path` is {RequestInfo} or {URL}, makes a request and
|
|
136
|
-
* for everything else, calls `WebAssembly.instantiate` directly.
|
|
137
|
-
*
|
|
138
|
-
* @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
|
|
139
|
-
*
|
|
140
|
-
* @returns {Promise<InitOutput>}
|
|
141
|
-
*/
|
|
142
|
-
export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;
|