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 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. The download path buffers in-flight
105
- chunks for reordering, so peak memory is roughly
106
- `downloadWindow × chunkSize`.
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, compress each chunk into zrip frames, probe
217
- the server's received ranges (`x-libfw-session-status`), POST only the
218
- missing chunks with their absolute offset (out of order), then commit with
219
- `x-libfw-final: 1`. A commit that fails re-probes and refills rather than
220
- failing the task.
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 (~100 ms of data, clamped into the advertised range); the
266
- zrip level is a policy, never ramped. Errors halve the parameters and require
267
- two stable windows before settling.
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
- /** Negotiate zrip compression. Default `true`. */
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
- /** Shared chunk size in bytes for uploads and parallel downloads. Default 2 MiB. */
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 (~100 ms of it,
178
- * clamped into the advertised range) and the zrip level is a client policy
179
- * from `compressLevel`, never ramped. When disabled the configured static
180
- * values are used as-is. Default `false`.
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 (~100 ms of it, clamped into the
251
- * advertised range) and the zrip level is a client policy from
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.6",
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",
@@ -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>;