libfw-client 0.4.5 → 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
@@ -1,187 +1,332 @@
1
- # libfw-client SDK
1
+ # libfw-client (browser SDK)
2
2
 
3
- The browser SDK for [libfw](../README.md): a zero-config wrapper around the
4
- WASM engine, the File System Access API and IndexedDB.
3
+ The official browser client for [libfw](../README.md). It wraps the WASM
4
+ engine, the File System Access API and IndexedDB behind one small ESM class:
5
+ you call `upload` / `downloadFolder` / `downloadFile` with a bearer token.
5
6
 
6
- > The same protocol engine is also available as a **native Rust client** for
7
- > non-browser programs — `libfw_client::native::NativeClient` (async
8
- > `tokio` + `reqwest`), with a runnable CLI in
9
- > [`examples/rust-client`](../examples/rust-client/README.md).
7
+ The same protocol engine is available natively for non-browser programs —
8
+ see [docs/native-client.md](../docs/native-client.md).
10
9
 
11
- ## Usage
10
+ - [Install](#install)
11
+ - [Quick start](#quick-start)
12
+ - [Options](#options)
13
+ - [API](#api)
14
+ - [Events](#events)
15
+ - [Errors](#errors)
16
+ - [How transfers work](#how-transfers-work)
17
+ - [Resume and page refresh](#resume-and-page-refresh)
18
+ - [Download modes and ZIP fallback](#download-modes-and-zip-fallback)
19
+ - [Adaptive tuning](#adaptive-tuning)
20
+ - [Building the package](#building-the-package)
21
+ - [Browser support and security](#browser-support-and-security)
22
+
23
+ ## Install
24
+
25
+ ```bash
26
+ npm install libfw-client
27
+ ```
28
+
29
+ Or use it from source in this repository:
30
+
31
+ ```bash
32
+ wasm-pack build crates/libfw-client --target web --out-dir ../../sdk/pkg --release
33
+ ```
34
+
35
+ The package ships the ESM entry (`index.js`), TypeScript types
36
+ (`index.d.ts`), the dependency-free ZIP writer (`zip.js`) and the
37
+ `wasm-pack` output under `pkg/`. It does not bundle or fetch anything else.
38
+
39
+ ## Quick start
12
40
 
13
41
  ```js
14
42
  import { LibfwClient } from 'libfw-client';
15
43
 
16
44
  const client = new LibfwClient({
17
- baseUrl: '/', // server origin (same-origin when empty)
18
- concurrency: 4, // max parallel file transfers (independent HTTP streams)
19
- uploadWindow: 8, // in-flight chunks per single file upload (raise to
20
- // reduce upload stutter on high-latency links)
21
- downloadWindow: 4, // parallel byte-range GETs per single file download
22
- // (raise to reduce download stutter on high-latency links)
23
- compress: true, // zrip per-block compression
24
- compressLevel: 'auto',// zrip level policy: 'auto' benchmarks uploads
25
- // (needs autoTune) / 'fast' / 'balanced' / 'max' / N
26
- autoTune: true, // adaptive tuning: probes /capabilities and ramps
27
- tuneTtlMs: 3600000, // how long a settled result stays cached (browser,
28
- // localStorage); 0 = never cache, re-ramp each time
29
- // concurrency/windows/chunk size from real stats
45
+ baseUrl: '/', // where libfw-server is mounted (same origin by default)
46
+ concurrency: 4, // parallel files
47
+ uploadWindow: 8, // in-flight chunks per file upload
48
+ downloadWindow: 4, // parallel range GETs per file download
49
+ compress: true,
50
+ autoTune: true,
30
51
  onEvent: (e) => {
31
- if (e.type === 'progress') updateProgressBar(e.done, e.total);
32
- else if (e.type === 'tuning') renderTuning(e.phase, e.params, e.stats);
33
- // other types: fileStart, fileCompleted, ...
52
+ if (e.type === 'progress') bar.value = e.done / e.total;
53
+ if (e.type === 'tuning') console.log(e.phase, e.params, e.stats);
34
54
  },
35
55
  });
36
56
 
37
- // Download a whole folder. Uses showDirectoryPicker when the File System
38
- // Access API is available; otherwise the folder is zipped and saved via a
39
- // traditional browser download — no feature detection needed by the caller.
40
- await client.downloadFolder('your_token_here');
57
+ // upload <input type="file" multiple>
58
+ await client.upload(token, document.querySelector('input[type=file]').files);
41
59
 
42
- // Upload a FileList
43
- const input = document.querySelector('input[type=file]');
44
- await client.upload('your_token_here', input.files);
60
+ // upload a whole folder (showDirectoryPicker)
61
+ await client.upload(token);
45
62
 
46
- // Or upload a whole folder
47
- await client.upload('your_token_here');
63
+ // download a whole folder into a picked local directory
64
+ await client.downloadFolder(token);
48
65
 
49
- // Controls
50
- client.pause();
51
- client.resume();
52
- client.cancel();
66
+ // download a single file
67
+ await client.downloadFile(token, 'docs/plan.pdf');
53
68
  ```
54
69
 
55
- ## How it works
56
-
57
- - **HTTP transport, not WebSocket** — the engine drives all control commands
58
- (directory listing, metadata) and data over plain HTTP. This is what keeps
59
- transfers robust on lossy/unstable links: each transfer uses **independent
60
- parallel HTTP streams**, so a lost packet stalls only that one stream
61
- (which retries just its own bytes) instead of blocking a whole multiplexed
62
- WebSocket connection.
63
- - **Downloads** — `downloadFolder(token, dirPath?)` / `downloadFile(token,
64
- filePath)` list the tree (for folders) and fetch each large file as
65
- `downloadWindow` concurrent `Range` GETs (tus-style parallel transfer, one
66
- independent connection per range). Each chunk is retried independently
67
- (only the lost part is re-fetched); the engine reorders the chunks in
68
- memory and pushes `Uint8Array`s to the SDK **strictly in order**.
69
- `Range`/`If-Range`/`416` give natural resume against the server ETag (the
70
- server is the source of truth). With the File System Access API the SDK
71
- streams chunks to disk via `fileHandle.createWritable()`; without it (or
72
- with `downloadMode: 'browser'`) it buffers the chunks and saves the result
73
- through a traditional browser download — a single file as-is, a folder
74
- packed into a `.zip`.
75
- - **Uploads** — `upload(token, files?)` slices each file into chunks, reads
76
- them via `readFile`, compresses each into one zstd frame and POSTs the
77
- missing chunks concurrently (out of order) with `x-libfw-offset` into a
78
- shared per-session temp on the server (positional writes). A final
79
- `x-libfw-final` commit validates the size and atomically renames the temp
80
- into place. Only the chunks the server still misses are re-sent
81
- (`x-libfw-session-status` probe seeds resume), so interrupted uploads
82
- resume BitTorrent-style (only the broken/lost parts are re-transmitted).
83
- A dropped connection (page refresh, crashed tab) keeps that partial on the
84
- server, so a reloaded page resumes exactly where it stopped.
85
- - Resume state (`etag`, `offset`, `size`) is persisted per path in
86
- IndexedDB and re-validated on every retry. `createWritable()` only
87
- publishes a file on `close()`, so a download **checkpoints** its prefix to
88
- disk every time the engine reports a durable offset (~4 MiB) — a hard page
89
- refresh mid-download therefore resumes from the last checkpoint instead of
90
- restarting from byte 0.
91
- - Pause/resume/cancel drive the WASM state machine
92
- (`idle → downloading/uploading → paused → resumed → completed/failed`).
93
-
94
- ## Build
70
+ `downloadFolder` / `downloadFile` / the argument-less `upload` call a
71
+ directory picker, so they must run from a user gesture (a click handler).
95
72
 
96
- ```bash
97
- # 1. Compile the WASM engine + generate the web glue (requires wasm-pack)
98
- npm run build:wasm
73
+ ## Options
74
+
75
+ | Option | Default | Meaning |
76
+ | --- | --- | --- |
77
+ | `baseUrl` | `''` | origin/prefix where libfw is mounted; `''` = same origin |
78
+ | `concurrency` | `4` | max files transferred in parallel |
79
+ | `uploadWindow` | `8` | in-flight chunks per single-file upload |
80
+ | `downloadWindow` | `4` | in-flight `Range` GETs per single-file download (`1` = sequential) |
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
+ | `compressLevel` | `'balanced'` | `'auto'` \| `'fast'` \| `'balanced'` \| `'max'` \| number; `'auto'` benchmarks uploads |
83
+ | `chunkSize` | `2097152` (2 MiB) | shared chunk size for uploads and download ranges |
84
+ | `maxRetries` | `3` | retries per chunk/file |
85
+ | `baseRetryDelayMs` | `500` | initial exponential backoff |
86
+ | `maxRetryDelayMs` | `30000` | backoff ceiling |
87
+ | `timeoutMs` | `60000` | per-request stall timeout |
88
+ | `autoTune` | `false` | enable the adaptive ramp |
89
+ | `tuneTtlMs` | `3600000` (1 h) | how long a cached settle stays usable; `0` disables caching |
90
+ | `wasmUrl` | auto | explicit URL of `libfw_client_bg.wasm` |
91
+ | `downloadMode` | `'auto'` | `'auto'` \| `'fs'` \| `'browser'` |
92
+ | `maxFallbackBytes` | `536870912` (512 MiB) | memory cap for the `'browser'` fallback; `0` disables |
93
+ | `onEvent` | — | progress/lifecycle/tuning listener |
94
+ | `directoryHandle` | — | pre-selected handle (or resolver) instead of `showDirectoryPicker` |
95
+ | `resolveDisplayName` | — | map a server path to the on-disk / archive name |
96
+ | `resolveUploadPath` | — | map an upload entry to its virtual server path |
97
+
98
+ Notes:
99
+
100
+ - `concurrency` is the cross-file fan-out. The engine sizes its shared
101
+ in-flight request budget as `concurrency × max(uploadWindow,
102
+ downloadWindow)`, so raising a window actually increases parallelism (it
103
+ used to be capped by `concurrency` alone).
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.
112
+ - `compressLevel` is a client *policy*, resolved against the server's
113
+ advertised range. `'auto'` additionally micro-benchmarks the range on a
114
+ real sample of the first uploaded file; downloads request the resolved
115
+ level from the server.
116
+ - `tuneTtlMs` only matters with `autoTune`. It is ignored by the native
117
+ client.
118
+
119
+ Example with a per-file virtual path:
99
120
 
100
- # 2. (optional) bundle a UMD build
101
- npm run build:umd
121
+ ```js
122
+ await client.upload(token, [
123
+ { file, relPath: 'reports/2026/plan.pdf' },
124
+ ]);
102
125
  ```
103
126
 
104
- The resulting package contains:
127
+ ## API
128
+
129
+ ### Transfers
130
+
131
+ | Method | Returns | Description |
132
+ | --- | --- | --- |
133
+ | `downloadFolder(token, dirPath?)` | bytes written | download a remote folder into a picked local folder (`''` = root) |
134
+ | `downloadFile(token, filePath, opts?)` | bytes written | download one file; `opts.fileName` overrides the leaf name |
135
+ | `upload(token, files?)` | bytes sent | `FileList`, `File[]`, `UploadFileEntry[]`, `UploadEntry[]`, or no argument = pick a folder |
136
+
137
+ ### Controls and state
138
+
139
+ | Method | Description |
140
+ | --- | --- |
141
+ | `pause()` | pause the active transfer |
142
+ | `resume()` | resume it (state is revalidated first) |
143
+ | `cancel()` | cancel it → state `failed` |
144
+ | `state()` | `idle` \| `downloading` \| `uploading` \| `paused` \| `completed` \| `failed` |
145
+ | `progress()` | `0..1` |
146
+ | `doneBytes()` | bytes transferred so far |
147
+ | `totalBytes()` | total bytes to transfer |
148
+ | `tuneStatus()` | `{ phase, params, stats, capsHash }` or `null` |
149
+ | `clearResumeStore(direction?)` | remove persisted resume records (`'upload'` / `'download'`), returns the count |
150
+
151
+ `tuneStatus()` shape:
105
152
 
153
+ ```js
154
+ {
155
+ phase: 'settled', // uninitialized | ramping | settled | degraded
156
+ params: {
157
+ concurrency: 4,
158
+ uploadWindow: 8,
159
+ downloadWindow: 4,
160
+ chunkSize: 4194304,
161
+ compressLevel: 1, // resolved policy (what downloads request)
162
+ },
163
+ stats: { rttMs: 12.4, mbps: 87.3 },
164
+ capsHash: 'sha256-…',
165
+ }
106
166
  ```
107
- pkg/ wasm-pack output (wasm + wasm-bindgen web glue)
108
- index.js ESM SDK
109
- zip.js dependency-free ZIP writer (browser-download fallback)
110
- index.d.ts TypeScript types
111
- dist/libfw-client.umd.js UMD bundle (after build:umd)
167
+
168
+ ## Events
169
+
170
+ `onEvent` receives one of:
171
+
172
+ | Event | Fields | When |
173
+ | --- | --- | --- |
174
+ | `fileStart` | `path`, `done: 0`, `total: size` | a file starts |
175
+ | `fileCompleted` | `path` | a file finishes |
176
+ | `progress` | `done`, `total` | byte progress (frequent — keep the handler cheap) |
177
+ | `tuning` | `phase`, `params`, `stats` | tuning phase/window changes (only with `autoTune`) |
178
+
179
+ `progress` is emitted per received body slice, not per chunk, so a large range
180
+ GET still animates. Downloads also emit monotonically increasing totals
181
+ across files.
182
+
183
+ ## Errors
184
+
185
+ Every rejection is a `LibfwError` with a stable `code`:
186
+
187
+ | Code | Meaning |
188
+ | --- | --- |
189
+ | `unknown` | unclassified |
190
+ | `wasm` | engine initialization/panic surfaced |
191
+ | `abort` | `AbortController` fired |
192
+ | `unsupported` | a required browser API is missing |
193
+ | `path` | invalid/unsafe path |
194
+ | `storage` | local file write / seek failure |
195
+ | `idb` | IndexedDB failure |
196
+ | `http` | non-success HTTP status (`http 404 for \`/file/x\``) |
197
+ | `network` | transport failure |
198
+ | `decompress` | bad compressed stream |
199
+ | `compress` | compression failure |
200
+ | `protocol` | malformed server payload |
201
+ | `cancelled` | user cancelled |
202
+ | `too-large` | would exceed `maxFallbackBytes` |
203
+
204
+ ```js
205
+ try {
206
+ await client.downloadFolder(token);
207
+ } catch (err) {
208
+ console.error(err.code, err.message);
209
+ }
112
210
  ```
113
211
 
114
- ## API
212
+ ## How transfers work
213
+
214
+ - **Plain HTTP, no WebSocket.** Control commands (listing, metadata) and data
215
+ share the same transport, so proxies and CDNs behave predictably.
216
+ - **Downloads** — `HEAD` for the authoritative size/ETag, then parallel
217
+ `Range` GETs (`downloadWindow`), reordered in the engine and streamed to
218
+ disk in order. Each range retries independently; `Range`/`If-Range`/`416`
219
+ give resume against the server ETag. Files at or below 512 KiB stay on the
220
+ sequential path.
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.
228
+ - **State machine** — `idle → downloading/uploading → paused → resumed →
229
+ completed/failed`. `pause()` stops scheduling new work; in-flight requests
230
+ are allowed to finish.
231
+
232
+ ## Resume and page refresh
233
+
234
+ - Resume records (`etag`, `offset`, `size`) live in IndexedDB, keyed per
235
+ path and direction, and are revalidated on every retry. `clearResumeStore`
236
+ wipes them.
237
+ - **Download resume requires a real partial file**: `downloadMode: 'fs'`
238
+ (or an injected `directoryHandle`). A hard refresh runs no cleanup code,
239
+ so `createWritable()` would otherwise discard the `.crswap` and the target
240
+ would be 0 bytes. The SDK therefore **checkpoints**: whenever the engine
241
+ reports a durable offset (about every 4 MiB) it closes the writable and
242
+ reopens it with `keepExistingData` + `seek`, so a reload resumes from the
243
+ last checkpoint. Worst-case loss on a hard kill is one checkpoint
244
+ interval. The in-memory `'browser'` fallback always restarts from 0.
245
+ - **Upload resume** works because the session temp lives on the server and
246
+ the session id is the file's ETag (size + mtime): a reloaded page probes
247
+ the same session and sends only the missing chunks. A request whose
248
+ connection dies mid-body keeps the blocks already received.
249
+
250
+ ## Download modes and ZIP fallback
251
+
252
+ | `downloadMode` | Behavior |
253
+ | --- | --- |
254
+ | `'fs'` | stream to disk via `showDirectoryPicker` / `createWritable`; folders are recreated; resumable |
255
+ | `'browser'` | buffer in memory, then trigger a normal browser download; folders become a `.zip`; not resumable |
256
+ | `'auto'` (default) | `'fs'` when the API exists, otherwise `'browser'` |
257
+
258
+ In `'browser'` mode each file is pre-checked against `maxFallbackBytes`
259
+ (512 MiB by default) and rejected with `too-large` rather than risking an
260
+ OOM.
261
+
262
+ The ZIP writer is dependency-free and emits UTF-8 entry names with the
263
+ general-purpose bit 11 (EFS) set, so CJK and other non-ASCII folder names
264
+ extract correctly on Windows, macOS and Linux. Illegal filesystem characters
265
+ are sanitized; `..` and drive-like segments are rejected.
266
+
267
+ ## Adaptive tuning
268
+
269
+ With `autoTune: true` the engine fetches `/capabilities`, starts at the
270
+ advertised minimums and ramps the per-file window, then cross-file
271
+ concurrency, from 1-second EWMA measurements. The chunk size follows the
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.
278
+
279
+ A settle is reused by later transfers in the same client **and** cached in
280
+ `localStorage`:
281
+
282
+ - Key: `libfw.tune.v1.<upload|download>.<origin>`.
283
+ - Tagged with the `/capabilities` hash; a changed advertisement invalidates it.
284
+ - Expires `tuneTtlMs` after the ramp settled (not after the last reuse), so a
285
+ link measured long ago is re-measured even if it is used constantly.
286
+ - Discarded on transfer failure.
287
+ - Storage failures (private mode, quota) are swallowed: caching is an
288
+ optimization and never fails a transfer.
289
+
290
+ `tuneTtlMs: 0` disables the cache entirely, so every transfer re-ramps.
291
+
292
+ A server without `/capabilities` (for example the actix example, which omits
293
+ the route) disables tuning and the configured static values are used as-is.
294
+
295
+ ## Building the package
296
+
297
+ ```bash
298
+ # from the repo root
299
+ wasm-pack build crates/libfw-client --target web --out-dir ../../sdk/pkg --release
300
+
301
+ # optional UMD bundle (rollup)
302
+ npm --prefix sdk run build:umd
303
+ ```
304
+
305
+ Layout produced:
306
+
307
+ ```text
308
+ sdk/
309
+ index.js ESM SDK
310
+ index.d.ts TypeScript types
311
+ zip.js dependency-free ZIP writer
312
+ pkg/ wasm-pack output (wasm + wasm-bindgen glue)
313
+ dist/ UMD bundle (after build:umd)
314
+ ```
315
+
316
+ The demo server serves this directory at `/sdk/*`, so the page can import
317
+ `/sdk/index.js` directly during development.
318
+
319
+ ## Browser support and security
115
320
 
116
- - `new LibfwClient(options?)`
117
- - `downloadWindow: number` (default `4`) — in-flight byte-range window per
118
- single file download (how many concurrent `Range` GETs); raise it on
119
- high-latency links. `1` disables parallelism (sequential downloads).
120
- - `chunkSize: number` (default `2097152`, 2 MiB) — shared size used for
121
- both upload chunks and parallel download ranges; the engine reorders
122
- in-flight chunks in memory (worst case ≈ `downloadWindow * chunkSize`
123
- bytes) so the SDK still receives data in order.
124
- - `compress: boolean` (default `true`) — master switch for zrip
125
- compression; `false` sends every body as identity.
126
- - `compressLevel: number | 'auto' | 'fast' | 'balanced' | 'max'` (default
127
- `'balanced'`) — zrip level policy when `compress` is on. `'fast'` is the
128
- advertised minimum (least CPU, worst ratio), `'balanced'` the advertised
129
- default, `'max'` the advertised maximum (best ratio); a number is clamped
130
- into the advertised range. `'auto'` additionally micro-benchmarks the
131
- advertised range against a real sample of the first uploaded file (while
132
- `autoTune` is enabled) and picks the best bytes-saved-vs-CPU-time
133
- trade-off for the measured link speed; downloads request the resolved
134
- level from the server.
135
- - `downloadMode: 'auto' | 'fs' | 'browser'` (default `'auto'`) — `'fs'`
136
- streams downloads through the File System Access API; `'browser'` buffers
137
- and triggers a traditional browser download (folders become `.zip`);
138
- `'auto'` uses `'fs'` when the API exists and falls back to `'browser'`.
139
- **Download resume requires `'fs'`** (or an injected `directoryHandle`):
140
- an interrupted fs-mode download is continued from the bytes already on
141
- disk, while the memory-backed `'browser'` fallback always restarts from
142
- byte 0 — there is no partial file to continue from.
143
- - `maxFallbackBytes: number` (default `536870912`, 512 MiB) — memory cap
144
- for the in-memory `'browser'` fallback. File sizes are pre-checked
145
- against it before buffering; a download that would exceed it rejects
146
- with a `too-large` `LibfwError` instead of risking an OOM. `0` disables.
147
- - `autoTune: boolean` (default `false`) — enable the adaptive tuning
148
- engine. The engine probes the server's `/capabilities` limits and
149
- TCP-style ramps the per-file window and cross-file concurrency from the
150
- advertised minimums using real transfer stats; the chunk size follows the
151
- measured throughput (~100 ms of it, clamped into the advertised range) and
152
- the zrip level is a client policy from `compressLevel`, never ramped. When
153
- disabled, the configured static values are used as-is. Tuning state is
154
- **in memory** for the lifetime of the client (a settle is reused by later
155
- transfers and dropped on failure) **and** is cached in `localStorage` per
156
- origin + direction, so a page refresh does not re-ramp — see `tuneTtlMs`.
157
- - `tuneTtlMs: number` (default `3600000`, 1 hour) — how long a cached
158
- tuning result stays usable. The cache is keyed by origin **and**
159
- direction (an upload settle says nothing about a download), is tagged with
160
- the `/capabilities` it was measured against, and expires `tuneTtlMs`
161
- *after the ramp settled* — not after the last reuse — so a link measured
162
- long ago is re-measured even if it is used constantly. An entry is also
163
- discarded early when the capabilities change or a transfer fails. `0`
164
- disables the cache entirely (every transfer re-ramps). Ignored unless
165
- `autoTune` is enabled. Storage failures (private mode, quota, disabled
166
- storage) are swallowed: caching is an optimisation and never fails a
167
- transfer.
168
- - `downloadFolder(token, dirPath?) → Promise<number>`
169
- - `downloadFile(token, filePath) → Promise<number>`
170
- - `upload(token, files?) → Promise<number>`
171
- - `clearResumeStore(direction?) → Promise<number>`
172
- - `pause()`, `resume()`, `cancel()`
173
- - `state()`, `progress()`, `doneBytes()`, `totalBytes()`
174
- - `tuneStatus() → { phase, params, stats, capsHash } | null` — live
175
- adaptive-tuning status. `phase` is `uninitialized | ramping | settled |
176
- degraded`; `params` is `{ concurrency, uploadWindow, downloadWindow,
177
- chunkSize, compressLevel }` (the zrip level is the resolved *policy*, i.e.
178
- what downloads request — uploads may use an `'auto'`-benchmarked level for
179
- the session); `stats` is
180
- `{ rttMs, mbps }` (EWMA request RTT, last-window throughput). `null`
181
- until the WASM engine is initialised.
182
- - Events: with `autoTune` enabled, `onEvent` additionally receives
183
- `{ type: 'tuning', phase, params, stats }` on every phase transition /
184
- window evaluation.
185
- - Errors: every rejection is a `LibfwError` with a stable `code`.
186
-
187
- See `index.d.ts` for the full type surface.
321
+ - **Chromium-based browsers** for anything that needs
322
+ `showDirectoryPicker` / `createWritable` (folder download/upload,
323
+ resumable downloads). `downloadMode: 'auto'` falls back to a plain browser
324
+ download elsewhere; explicit `'fs'` calls reject with `unsupported`.
325
+ - **Tokens** are passed per call, not stored by the SDK. Do not embed
326
+ long-lived tokens in public pages — issue short-lived ones from your
327
+ backend and let the page fetch them. libfw never issues tokens; see
328
+ [docs/authorization.md](../docs/authorization.md).
329
+ - **`/capabilities` is public** and must not contain sensitive data.
330
+ - The SDK writes to IndexedDB (resume records) and `localStorage` (tuning
331
+ cache); both are per-origin. `clearResumeStore()` removes resume records,
332
+ and `tuneTtlMs: 0` disables the tuning cache.
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)
@@ -347,7 +352,7 @@ export class LibfwClient {
347
352
  // ESM-only `import.meta.url` fallback is never exercised — that
348
353
  // fallback throws when the SDK is bundled for a classic <script>/UMD
349
354
  // context. See _wasmUrl() for how the URL is resolved. The
350
- // `{ module_or_path }` object form is the glue's non-deprecated API.
355
+ // `{ module_or_path }` object form is the glue's supported API.
351
356
  this._initPromise = init({ module_or_path: this._wasmUrl() }).catch((err) => {
352
357
  this._initPromise = null;
353
358
  throw toLibfwError(err);
@@ -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
  },
@@ -1061,7 +1067,7 @@ export class LibfwClient {
1061
1067
  if (!this._dirHandle) return null;
1062
1068
  try {
1063
1069
  // Same display-name mapping as `_ensureFileHandle` so a resume finds
1064
- // the file previously written under its resolved (display) name.
1070
+ // the file already written under its resolved (display) name.
1065
1071
  const segments = splitPath(await this._safeEntryName(path));
1066
1072
  if (segments.length === 0) return null;
1067
1073
  let dir = this._dirHandle;
@@ -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.5",
4
- "description": "High-performance streaming file & folder transfer SDK for the browser (libfw WASM engine + File System Access API + IndexedDB resume).",
3
+ "version": "0.4.7",
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",