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 +306 -161
- package/index.d.ts +30 -6
- package/index.js +33 -5
- package/package.json +10 -2
- 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
|
@@ -1,187 +1,332 @@
|
|
|
1
|
-
# libfw-client SDK
|
|
1
|
+
# libfw-client (browser SDK)
|
|
2
2
|
|
|
3
|
-
The browser
|
|
4
|
-
|
|
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
|
-
|
|
7
|
-
|
|
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
|
-
|
|
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: '/',
|
|
18
|
-
concurrency: 4,
|
|
19
|
-
uploadWindow: 8,
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
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')
|
|
32
|
-
|
|
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
|
-
//
|
|
38
|
-
|
|
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
|
-
//
|
|
43
|
-
|
|
44
|
-
await client.upload('your_token_here', input.files);
|
|
60
|
+
// upload a whole folder (showDirectoryPicker)
|
|
61
|
+
await client.upload(token);
|
|
45
62
|
|
|
46
|
-
//
|
|
47
|
-
await client.
|
|
63
|
+
// download a whole folder into a picked local directory
|
|
64
|
+
await client.downloadFolder(token);
|
|
48
65
|
|
|
49
|
-
//
|
|
50
|
-
client.
|
|
51
|
-
client.resume();
|
|
52
|
-
client.cancel();
|
|
66
|
+
// download a single file
|
|
67
|
+
await client.downloadFile(token, 'docs/plan.pdf');
|
|
53
68
|
```
|
|
54
69
|
|
|
55
|
-
|
|
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
|
-
|
|
97
|
-
|
|
98
|
-
|
|
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
|
-
|
|
101
|
-
|
|
121
|
+
```js
|
|
122
|
+
await client.upload(token, [
|
|
123
|
+
{ file, relPath: 'reports/2026/plan.pdf' },
|
|
124
|
+
]);
|
|
102
125
|
```
|
|
103
126
|
|
|
104
|
-
|
|
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
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
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
|
-
##
|
|
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
|
-
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
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
|
-
/**
|
|
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)
|
|
@@ -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
|
|
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
|
|
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.
|
|
4
|
-
"description": "
|
|
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",
|