@wherever-dev/client 0.7.0 → 0.8.0

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/dist/client.js CHANGED
@@ -5,6 +5,119 @@ import { skillInvocationIdentity, } from "./types.js";
5
5
  function generateClientKey() {
6
6
  return `ck-${Math.random().toString(36).slice(2)}${Date.now().toString(36)}`;
7
7
  }
8
+ // --- Uploads (docs/adr/0012, frames in docs/USAGE.md) ----------------------
9
+ /** The capability a server advertises in `connected` for chunked uploads. */
10
+ export const UPLOAD_CAPABILITY = 'upload.v1';
11
+ const KiB = 1024;
12
+ /**
13
+ * Chunked-upload pacing. The window is the number of BYTES in flight (sent, not
14
+ * yet acked): about UPLOAD_WINDOW_SECONDS worth at the throughput measured from
15
+ * acks, clamped to [UPLOAD_WINDOW_MIN, UPLOAD_WINDOW_MAX]. Before any ack has
16
+ * been timed it is the minimum, so a slow uplink is never flooded (a queue of
17
+ * bytes ahead of the heartbeat pong is what used to kill the socket). Each chunk
18
+ * is `min(window, UPLOAD_CHUNK_MAX)`, well under the server's 1 MiB cap.
19
+ */
20
+ const UPLOAD_WINDOW_MIN = 64 * KiB;
21
+ const UPLOAD_WINDOW_MAX = 1024 * KiB;
22
+ const UPLOAD_CHUNK_MAX = 256 * KiB;
23
+ const UPLOAD_WINDOW_SECONDS = 2;
24
+ // Weight of the newest throughput sample in the moving average.
25
+ const UPLOAD_RATE_ALPHA = 0.3;
26
+ // Legacy base64 is built from reads of this many bytes: a multiple of 3, so
27
+ // each piece encodes without `=` padding and the pieces simply concatenate.
28
+ const LEGACY_READ_BYTES = 3 * 256 * KiB;
29
+ const NOT_READABLE_MESSAGE = 'The file is no longer readable, pick it again';
30
+ /** `[u8 kind=1][u8 version=1][u8 idLen][uploadId ascii][u64 offset BE][payload]` */
31
+ export function encodeChunkFrame(uploadId, offset, payload) {
32
+ const head = 3 + uploadId.length;
33
+ const frame = new Uint8Array(head + 8 + payload.length);
34
+ frame[0] = 1;
35
+ frame[1] = 1;
36
+ frame[2] = uploadId.length;
37
+ for (let i = 0; i < uploadId.length; i++)
38
+ frame[3 + i] = uploadId.charCodeAt(i);
39
+ const view = new DataView(frame.buffer);
40
+ view.setUint32(head, Math.floor(offset / 2 ** 32));
41
+ view.setUint32(head + 4, offset >>> 0);
42
+ frame.set(payload, head + 8);
43
+ return frame;
44
+ }
45
+ function bytesToBinaryString(bytes) {
46
+ let out = '';
47
+ for (let i = 0; i < bytes.length; i += 0x8000) {
48
+ out += String.fromCharCode.apply(null, bytes.subarray(i, i + 0x8000));
49
+ }
50
+ return out;
51
+ }
52
+ /**
53
+ * 128 random bits, base64url without padding (22 characters, matching the
54
+ * server's `^[A-Za-z0-9_-]{22,64}$`). The id is what makes a resume
55
+ * unguessable, so it comes from `crypto.getRandomValues`; Math.random is only a
56
+ * last resort for a runtime without Web Crypto.
57
+ */
58
+ function generateUploadId() {
59
+ const bytes = new Uint8Array(16);
60
+ const c = globalThis.crypto;
61
+ if (c && typeof c.getRandomValues === 'function') {
62
+ c.getRandomValues(bytes);
63
+ }
64
+ else {
65
+ for (let i = 0; i < bytes.length; i++)
66
+ bytes[i] = Math.floor(Math.random() * 256);
67
+ }
68
+ return btoa(bytesToBinaryString(bytes)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
69
+ }
70
+ class UploadReadError extends Error {
71
+ code;
72
+ }
73
+ // The error an upload fails with when its byte source cannot be read.
74
+ function uploadReadError(err) {
75
+ if (err instanceof UploadReadError)
76
+ return err;
77
+ if (err && err.name === 'NotReadableError') {
78
+ const e = new UploadReadError(NOT_READABLE_MESSAGE);
79
+ e.code = 'not_readable';
80
+ return e;
81
+ }
82
+ return new UploadReadError(`Failed to read the file: ${(err && err.message) || err}`);
83
+ }
84
+ // A read that returned fewer (or other) bytes than asked: the file changed or
85
+ // was invalidated under us, which to the user is the same as unreadable.
86
+ function shortReadError() {
87
+ const e = new UploadReadError(NOT_READABLE_MESSAGE);
88
+ e.code = 'not_readable';
89
+ return e;
90
+ }
91
+ // The host as it goes on the socket URL: a pasted `http(s)://` prefix is dropped.
92
+ function socketHost(host) {
93
+ return host.startsWith('http') ? host.replace(/^https?:\/\//, '') : host;
94
+ }
95
+ // 32-bit FNV-1a over the UTF-16 code units, as 8 hex digits. NOT a security
96
+ // hash: it only keeps the raw token out of the key (and out of IndexedDB keys)
97
+ // while still telling two tokens apart.
98
+ function fnv1a(input) {
99
+ let h = 0x811c9dc5;
100
+ for (let i = 0; i < input.length; i++) {
101
+ h ^= input.charCodeAt(i);
102
+ h = Math.imul(h, 0x01000193);
103
+ }
104
+ return (h >>> 0).toString(16).padStart(8, '0');
105
+ }
106
+ /**
107
+ * The identity of the server a config points at: `host:port#<fnv1a(token)>`.
108
+ * Two configured servers (or one server with a rotated token) never share a
109
+ * key, so the web's conversation cache can never show one server's
110
+ * conversation for another (ADR 0013).
111
+ *
112
+ * Synchronous and pure on purpose: `connect()` is synchronous and must compare
113
+ * it with the stamp before deciding whether to preserve the store, and
114
+ * `crypto.subtle` is both async and missing on plain-http LAN origins. The
115
+ * scheme (`secure`) is deliberately NOT part of the key: ws vs wss to the same
116
+ * host:port is the same server.
117
+ */
118
+ export function serverKey(config) {
119
+ return `${socketHost(config.host)}:${config.port}#${fnv1a(config.token ?? '')}`;
120
+ }
8
121
  const defaultState = {
9
122
  connected: false,
10
123
  connecting: false,
@@ -35,6 +148,8 @@ const defaultState = {
35
148
  historyTotalCount: 0,
36
149
  historyOffset: 0,
37
150
  loadingMoreHistory: false,
151
+ historyAuthoritative: false,
152
+ serverKey: null,
38
153
  contextUsage: null,
39
154
  pendingSteering: [],
40
155
  skills: [],
@@ -100,6 +215,22 @@ export class WhereverClient {
100
215
  static TURN_STALL_MS = 45_000;
101
216
  // Send a keepalive well under STALE_SOCKET_MS so the pong refreshes liveness.
102
217
  static HEARTBEAT_MS = 25_000;
218
+ // Probe-before-teardown (docs/adr/0011): silence past the threshold never
219
+ // tears a socket down by itself. The watchdog pings and waits this long; ANY
220
+ // inbound frame in that window (onMessage) cancels the probe, and only a
221
+ // socket still silent when it expires is torn down. Needed because on a thaw
222
+ // the timers fire BEFORE the frames queued during the freeze are dispatched,
223
+ // so the raw silence verdict is routinely false on a phone.
224
+ static PROBE_GRACE_MS = 5_000;
225
+ // The pending probe's grace timer, and the socket it was started on. Cleared
226
+ // by any inbound frame, by stopLivenessWatchdog (every socket change), and
227
+ // ignored if the socket it belongs to is no longer current.
228
+ probeTimer = null;
229
+ // Wall-clock time of the previous watchdog tick. A gap of more than 2x
230
+ // HEARTBEAT_MS means the page was frozen; that is an extra, PROACTIVE probe
231
+ // trigger, never the gate (a 45-50 s freeze gap is not a >2x jump yet still
232
+ // crosses TURN_STALL_MS, which is why the probe itself decides).
233
+ lastLivenessTickAt = 0;
103
234
  isInitialConnect = true;
104
235
  // When set, the next successful (re)connection should rejoin the previously
105
236
  // active session instead of starting blank. Used by resume() so a backgrounded
@@ -116,8 +247,63 @@ export class WhereverClient {
116
247
  // null means "accept any" (e.g. session_new, whose target file is not known
117
248
  // until the reply). The latest tap always wins.
118
249
  pendingLoadFile = null;
250
+ // serverKey(config) of the socket currently open (captured by connect() next
251
+ // to the socket it opens). session_created stamps it on the store, so the
252
+ // stamp names the server that actually DELIVERED the session even if the
253
+ // settings are edited afterwards.
254
+ socketServerKey = null;
255
+ // The sessionFile painted by hydrateCachedSession(), until the server answers
256
+ // its rejoin with a session_created (or the hydration is abandoned). While
257
+ // set, an untagged session_error answering that load (pendingLoadFile ===
258
+ // hydratedFile) means the cached session is dead: see hydration_rejected.
259
+ hydratedFile = null;
119
260
  listeners = new Set();
261
+ // In-flight WebSocket uploads, keyed by uploadId. An upload is NOT bound to
262
+ // the socket it started on. On mobile, picking a file backgrounds the page and
263
+ // the socket is often lost within seconds; the upload then waits for the next
264
+ // connection (it is (re)sent once the rejoin is answered, since a reply owed
265
+ // by a dead socket never arrives). Without a server reply an upload is
266
+ // settled by: a full teardown (disconnect(true)), UPLOAD_TIMEOUT_MS of
267
+ // waiting, MAX_UPLOAD_SENDS attempts each lost with its socket (legacy only),
268
+ // cancellation, or a session change. The one unbounded case is by design: an
269
+ // upload on the wire of a socket that stays open is left to its replies (the
270
+ // server's handlers always answer), so a slow but healthy transfer is never
271
+ // cut off. Two protocols share this machinery (see PendingUpload).
120
272
  pendingUploads = new Map();
273
+ // Progress of every upload this client started, keyed by uploadId: the same
274
+ // value each upload's onProgress receives. Settled entries (done / failed /
275
+ // aborted) stay until forgetUpload(), so a late subscriber still sees how an
276
+ // upload ended.
277
+ uploadsStore = writable({});
278
+ // `connected.capabilities` of the CURRENT socket; null until its `connected`
279
+ // frame arrives. Uploads are HELD while null: sending one as legacy to a
280
+ // server that would have taken it chunked would throw resumability away.
281
+ socketCapabilities = null;
282
+ // An upload whose socket dies under it on every attempt (a frame too large
283
+ // for the server's maxPayload, which closes with 1009; or a slow uplink where
284
+ // the multi-MB frame starves the heartbeat) would otherwise be re-sent
285
+ // forever, kicking the live session into a resync each time. After this many
286
+ // sends lost with their socket, it fails. LEGACY frame only: a chunked upload
287
+ // resumes from the server's offset, so a lost socket costs it nothing.
288
+ static MAX_UPLOAD_SENDS = 3;
289
+ // `ws`'s default maxPayload is 100 MiB per frame; leave room for the JSON
290
+ // envelope. Larger base64 payloads are refused (~72 MB files). A backstop:
291
+ // the legacy path refuses `size > MAX_LEGACY_UPLOAD_BYTES` before reading.
292
+ static MAX_UPLOAD_BASE64_CHARS = 96 * 1024 * 1024;
293
+ // base64 of 72 MiB is exactly 96 MiB, MAX_UPLOAD_BASE64_CHARS.
294
+ static MAX_LEGACY_UPLOAD_BYTES = 72 * 1024 * 1024;
295
+ // Bounds the time an upload spends WAITING to be sent (no socket, or held for
296
+ // a rejoin), not its transmission: the clock is cleared whenever the frame
297
+ // actually goes out on an open socket, and re-armed when that socket closes.
298
+ // So a large, slow-but-healthy upload is never rejected mid-transfer.
299
+ static UPLOAD_TIMEOUT_MS = 10 * 60_000;
300
+ // True between a reconnect's rejoin session_load and its session_created.
301
+ // A fresh server socket starts attached to no session with readOnly=false;
302
+ // the server only sets this client's write verdict (readOnly) when it answers
303
+ // the session_load. Uploads sent in that window would bypass the read-only
304
+ // gate (and a multi-MB frame queued ahead of the rejoin could trip the load
305
+ // watchdog), so they are held until session_created lands.
306
+ uploadsHeldForRejoin = false;
121
307
  // Per-message confirmation watchdogs. A user message committed optimistically
122
308
  // is only proven delivered when the server echoes it back; if no echo lands
123
309
  // within CONFIRM_MS the watchdog flips it to delivery:'failed' so the UI can
@@ -145,6 +331,24 @@ export class WhereverClient {
145
331
  };
146
332
  }
147
333
  this.disconnect(false);
334
+ // A store stamped by ANOTHER server (host/port/token edited in Connection
335
+ // Settings, which saves without reconnecting, then this connect, including
336
+ // the automatic one from scheduleReconnect) must not be preserved or
337
+ // rejoined: it would paint, and the web would re-cache, one server's
338
+ // conversation under another's key, and the rejoin would ask the new
339
+ // server for a session it does not have. Wipe instead (which clears the
340
+ // stamp too), and drop every pending rejoin source.
341
+ const key = serverKey(this.config);
342
+ const stamped = get(this.stateStore).serverKey;
343
+ if (stamped !== null && stamped !== key) {
344
+ preserveState = false;
345
+ this.resumeSessionFile = null;
346
+ this.resumeCwd = undefined;
347
+ this.resumeModel = undefined;
348
+ this.pendingLoadFile = null;
349
+ this.hydratedFile = null;
350
+ }
351
+ this.socketServerKey = key;
148
352
  // preserveState keeps the cached session/messages in the store across a
149
353
  // reconnect (resume path), so the previous conversation stays visible while
150
354
  // we reconnect and resync. The default (fresh connect) clears to a blank
@@ -158,9 +362,7 @@ export class WhereverClient {
158
362
  hideTools: !!this.config.hideTools,
159
363
  });
160
364
  const protocol = this.config.secure ? "wss" : "ws";
161
- const host = this.config.host.startsWith('http')
162
- ? this.config.host.replace(/^https?:\/\//, '')
163
- : this.config.host;
365
+ const host = socketHost(this.config.host);
164
366
  // clientKey rides on the URL (not a post-connect frame) so the server can
165
367
  // evict this viewer's previous connection BEFORE any session traffic is
166
368
  // handled, closing the phantom-viewer window entirely.
@@ -178,6 +380,8 @@ export class WhereverClient {
178
380
  }));
179
381
  return;
180
382
  }
383
+ // A new socket: its capabilities are unknown until its `connected` frame.
384
+ this.socketCapabilities = null;
181
385
  try {
182
386
  const wsOptions = this.config.secure && this.config.WebSocketCtor ? { rejectUnauthorized: false } : undefined;
183
387
  this.ws = wsOptions ? new WebSocketImpl(wsUrl, wsOptions) : new WebSocketImpl(wsUrl);
@@ -237,12 +441,25 @@ export class WhereverClient {
237
441
  this.resumeSessionFile = null;
238
442
  this.resumeCwd = undefined;
239
443
  this.resumeModel = undefined;
444
+ // Uploads that were waiting for a socket (or whose reply died with the old
445
+ // one) go out only AFTER the rejoin has been answered (see
446
+ // uploadsHeldForRejoin): session_load first, uploads on session_created.
447
+ // With no session to rejoin there is no write verdict to wait for, and
448
+ // nothing to attribute the upload to any more, so they fail.
449
+ this.uploadsHeldForRejoin = !!rejoinFile;
450
+ if (!rejoinFile) {
451
+ this.rejectPendingUploads('The session was closed before the upload could be sent');
452
+ }
240
453
  if (rejoinFile) {
241
454
  // Keep the cached conversation on screen but mark it resyncing so the
242
455
  // "Reconnecting and syncing session..." banner shows and sending is
243
456
  // blocked until fresh history lands. resyncing is cleared by
244
457
  // message_history (or an error/conflict) via the reducer.
245
- this.stateStore.update(s => (s.resyncing ? s : { ...s, resyncing: true }));
458
+ // The history in the store (cached, or from the dropped socket) may be
459
+ // stale until this rejoin's message_history lands.
460
+ this.stateStore.update(s => s.resyncing && !s.historyAuthoritative
461
+ ? s
462
+ : { ...s, resyncing: true, historyAuthoritative: false });
246
463
  this.pendingLoadFile = rejoinFile;
247
464
  this.send({ type: 'session_load', sessionFile: rejoinFile, cwd: rejoinCwd, model: rejoinModel });
248
465
  this.armLoadWatchdog();
@@ -257,6 +474,8 @@ export class WhereverClient {
257
474
  // Any inbound frame (including the pong reply to our keepalive) proves the
258
475
  // socket is alive and resets the stale-socket watchdog.
259
476
  this.lastInboundAt = Date.now();
477
+ // ...and answers any pending probe, so it must not tear the socket down.
478
+ this.cancelLivenessProbe();
260
479
  try {
261
480
  const rawData = typeof event.data === 'string' ? event.data : event.data.toString();
262
481
  const msg = JSON.parse(rawData);
@@ -269,6 +488,7 @@ export class WhereverClient {
269
488
  const onClose = () => {
270
489
  if (this.ws !== currentWs)
271
490
  return;
491
+ this.uploadsLostSocket();
272
492
  this.stopLivenessWatchdog();
273
493
  this.clearLoadWatchdog();
274
494
  this.ws = null;
@@ -327,6 +547,8 @@ export class WhereverClient {
327
547
  // state, so cancel them here.
328
548
  this.clearLoadWatchdog();
329
549
  this.clearCreateWatchdog();
550
+ // suspend()/resume() close the socket through here, bypassing onClose.
551
+ this.uploadsLostSocket();
330
552
  if (this.ws) {
331
553
  const dyingWs = this.ws;
332
554
  try {
@@ -364,6 +586,11 @@ export class WhereverClient {
364
586
  for (const t of this.confirmTimers.values())
365
587
  clearTimeout(t);
366
588
  this.confirmTimers.clear();
589
+ // An explicit full disconnect abandons in-flight uploads (they would
590
+ // otherwise be re-sent to whatever server is connected next).
591
+ this.rejectPendingUploads('Disconnected before the upload completed');
592
+ this.uploadsHeldForRejoin = false;
593
+ this.hydratedFile = null;
367
594
  this.stateStore.set({
368
595
  ...defaultState,
369
596
  hideThinking: !!this.config.hideThinking,
@@ -422,12 +649,12 @@ export class WhereverClient {
422
649
  // cached active session from an unsolicited drop. In BOTH cases onOpen
423
650
  // re-issues session_load, so mark resyncing here to show the affordance and
424
651
  // block sending until fresh history lands.
652
+ // No load watchdog is armed here: connect() -> disconnect(false) would clear
653
+ // it at once, and onOpen arms one for the rejoin it actually issues. While
654
+ // the socket never opens (offline boot over a hydrated cache) there is no
655
+ // load in flight to time out, so no "timed out" error must appear.
425
656
  if (this.resumeSessionFile || s.activeSessionFile) {
426
657
  this.stateStore.update(st => ({ ...st, resyncing: true }));
427
- // Arm here too: if the socket never opens, onOpen never runs and the
428
- // resync affordance would otherwise hang. onClose also clears it, but the
429
- // watchdog covers the half-open / never-opens case.
430
- this.armLoadWatchdog();
431
658
  }
432
659
  this.connect(undefined, true);
433
660
  }
@@ -451,6 +678,7 @@ export class WhereverClient {
451
678
  startLivenessWatchdog() {
452
679
  this.stopLivenessWatchdog();
453
680
  this.lastInboundAt = Date.now();
681
+ this.lastLivenessTickAt = this.lastInboundAt;
454
682
  const sendBeat = () => {
455
683
  // Keep a healthy connection warm so the pong refreshes lastInboundAt even
456
684
  // during long, token-less model turns.
@@ -468,7 +696,17 @@ export class WhereverClient {
468
696
  const checkLiveness = () => {
469
697
  if (!this.ws)
470
698
  return;
471
- const silentFor = Date.now() - this.lastInboundAt;
699
+ const now = Date.now();
700
+ const sinceLastTick = now - this.lastLivenessTickAt;
701
+ this.lastLivenessTickAt = now;
702
+ // A wall-clock jump between ticks means the page was frozen: probe now
703
+ // rather than waiting for the silence threshold. Only a trigger; the
704
+ // probe's grace period still decides.
705
+ if (sinceLastTick > 2 * WhereverClient.HEARTBEAT_MS) {
706
+ this.startLivenessProbe('clock jump');
707
+ return;
708
+ }
709
+ const silentFor = now - this.lastInboundAt;
472
710
  const streaming = get(this.stateStore).isStreaming;
473
711
  // Per-turn stall timeout: while a turn is in flight the heartbeat pong (and,
474
712
  // normally, tokens) should keep traffic flowing, so a shorter deadline
@@ -480,38 +718,10 @@ export class WhereverClient {
480
718
  : WhereverClient.STALE_SOCKET_MS;
481
719
  if (silentFor < threshold)
482
720
  return;
483
- // The socket has been silent past the threshold: treat it as dead. Tearing
484
- // it down forcibly is what makes a half-open connection recover, since the
485
- // OS never produced a FIN/RST to trigger the normal close path.
486
- console.warn(`[wherever] relay connection stale: no inbound frame for ${silentFor}ms ` +
487
- `(threshold ${threshold}ms, ${streaming ? 'mid-turn' : 'idle'}); ` +
488
- `tearing down dead socket and reconnecting`);
489
- this.stopLivenessWatchdog();
490
- const deadWs = this.ws;
491
- this.ws = null;
492
- try {
493
- if (typeof deadWs.terminate === 'function') {
494
- deadWs.terminate();
495
- }
496
- else if (typeof deadWs.close === 'function') {
497
- deadWs.close();
498
- }
499
- }
500
- catch { }
501
- this.stateStore.update(s => ({
502
- ...s,
503
- connected: false,
504
- connecting: false,
505
- loadingSession: false,
506
- creatingSession: false,
507
- // If a turn was in flight, surface it as a recoverable error so the UI
508
- // shows "the transport stalled" rather than silently parking mid-stream.
509
- sessionError: streaming
510
- ? 'Connection to relay stalled mid-turn; reconnecting...'
511
- : s.sessionError,
512
- isStreaming: false,
513
- }));
514
- this.scheduleReconnect();
721
+ // Silent past the threshold: SUSPECT, not dead. Probe first (see
722
+ // PROBE_GRACE_MS); the teardown happens only if the probe goes unanswered.
723
+ this.startLivenessProbe(`no inbound frame for ${silentFor}ms ` +
724
+ `(threshold ${threshold}ms, ${streaming ? 'mid-turn' : 'idle'})`);
515
725
  };
516
726
  if (typeof setInterval === 'function') {
517
727
  this.livenessTimer = setInterval(checkLiveness, WhereverClient.HEARTBEAT_MS);
@@ -520,7 +730,104 @@ export class WhereverClient {
520
730
  }
521
731
  }
522
732
  }
733
+ // The page just became visible again (visibilitychange: visible, pageshow).
734
+ // The client has no `document` access, so the page calls this. If the current
735
+ // socket is OPEN and watched, probe it right away instead of waiting for the
736
+ // next tick, and reset the stale baseline so the time the page spent frozen is
737
+ // not counted as silence (the probe decides whether the socket is alive).
738
+ // A no-op otherwise: on a CONNECTING socket the ping would be dropped by
739
+ // send() and the grace check would tear down a socket still handshaking.
740
+ noteVisible() {
741
+ const ws = this.ws;
742
+ if (!ws || ws.readyState !== 1 /* OPEN */ || !this.livenessTimer)
743
+ return;
744
+ this.lastInboundAt = Date.now();
745
+ this.lastLivenessTickAt = this.lastInboundAt;
746
+ // Restart any pending probe: its grace may have been eaten by the freeze.
747
+ this.cancelLivenessProbe();
748
+ this.startLivenessProbe('page became visible');
749
+ }
750
+ // Send a ping and arm the grace check. Idempotent while a probe is pending.
751
+ startLivenessProbe(reason) {
752
+ if (this.probeTimer || !this.ws || typeof setTimeout !== 'function')
753
+ return;
754
+ const probedWs = this.ws;
755
+ try {
756
+ this.ping();
757
+ }
758
+ catch { }
759
+ const sentAt = Date.now();
760
+ this.probeTimer = setTimeout(() => {
761
+ this.probeTimer = null;
762
+ if (this.ws !== probedWs)
763
+ return;
764
+ // The grace check itself ran far too late: the page was frozen during
765
+ // the grace period, so the reply may still be queued behind this timer.
766
+ // Probe again rather than condemn the socket on frozen time.
767
+ // Decision (beyond the task's letter): this has no retry cap. Under heavy
768
+ // background timer throttling (timers batched to ~1/min in a long-hidden
769
+ // tab) every grace check is late, so the verdict on a dead socket is
770
+ // deferred until the page is visible again, where noteVisible() restarts
771
+ // an unthrottled probe and a dead socket goes ~5 s later. Accepted: a
772
+ // hidden page has no viewer, and a capped retry would reintroduce the
773
+ // false teardown on thaw this probe exists to prevent.
774
+ if (Date.now() - sentAt > 2 * WhereverClient.PROBE_GRACE_MS) {
775
+ this.startLivenessProbe(reason);
776
+ return;
777
+ }
778
+ this.tearDownStaleSocket(reason);
779
+ }, WhereverClient.PROBE_GRACE_MS);
780
+ if (this.probeTimer && typeof this.probeTimer.unref === 'function') {
781
+ this.probeTimer.unref();
782
+ }
783
+ }
784
+ cancelLivenessProbe() {
785
+ if (this.probeTimer) {
786
+ clearTimeout(this.probeTimer);
787
+ this.probeTimer = null;
788
+ }
789
+ }
790
+ // The probe went unanswered: treat the socket as dead. Tearing it down
791
+ // forcibly is what makes a half-open connection recover, since the OS never
792
+ // produced a FIN/RST to trigger the normal close path.
793
+ tearDownStaleSocket(reason) {
794
+ if (!this.ws)
795
+ return;
796
+ const streaming = get(this.stateStore).isStreaming;
797
+ console.warn(`[wherever] relay connection stale: ${reason}; probe unanswered for ` +
798
+ `${WhereverClient.PROBE_GRACE_MS}ms; tearing down dead socket and reconnecting`);
799
+ this.stopLivenessWatchdog();
800
+ const deadWs = this.ws;
801
+ this.ws = null;
802
+ // This path bypasses onClose (the socket is no longer current), so the
803
+ // uploads it carried must be marked waiting here.
804
+ this.uploadsLostSocket();
805
+ try {
806
+ if (typeof deadWs.terminate === 'function') {
807
+ deadWs.terminate();
808
+ }
809
+ else if (typeof deadWs.close === 'function') {
810
+ deadWs.close();
811
+ }
812
+ }
813
+ catch { }
814
+ this.stateStore.update(s => ({
815
+ ...s,
816
+ connected: false,
817
+ connecting: false,
818
+ loadingSession: false,
819
+ creatingSession: false,
820
+ // If a turn was in flight, surface it as a recoverable error so the UI
821
+ // shows "the transport stalled" rather than silently parking mid-stream.
822
+ sessionError: streaming
823
+ ? 'Connection to relay stalled mid-turn; reconnecting...'
824
+ : s.sessionError,
825
+ isStreaming: false,
826
+ }));
827
+ this.scheduleReconnect();
828
+ }
523
829
  stopLivenessWatchdog() {
830
+ this.cancelLivenessProbe();
524
831
  if (this.heartbeatTimer) {
525
832
  clearInterval(this.heartbeatTimer);
526
833
  this.heartbeatTimer = null;
@@ -541,6 +848,7 @@ export class WhereverClient {
541
848
  if (!s.loadingSession && !s.resyncing)
542
849
  return;
543
850
  console.warn('[wherever] session load timed out; clearing loading state');
851
+ this.failHeldUploads('Could not rejoin the session, so the upload was not sent');
544
852
  this.stateStore.update(st => ({
545
853
  ...st,
546
854
  loadingSession: false,
@@ -679,6 +987,12 @@ export class WhereverClient {
679
987
  serverVersion: msg.serverVersion ?? null,
680
988
  error: null,
681
989
  }));
990
+ // Uploads held for unknown capabilities can now choose their protocol
991
+ // (still subject to the rejoin hold).
992
+ this.socketCapabilities = Array.isArray(msg.capabilities)
993
+ ? msg.capabilities.filter((c) => typeof c === 'string')
994
+ : [];
995
+ this.resendPendingUploads();
682
996
  break;
683
997
  case 'connection_superseded':
684
998
  // A newer connection arrived carrying OUR clientKey, so the server is
@@ -695,22 +1009,15 @@ export class WhereverClient {
695
1009
  console.error('onClientKeyChange failed:', err);
696
1010
  }
697
1011
  break;
698
- case 'file_uploaded': {
699
- const pending = this.pendingUploads.get(msg.uploadId);
700
- if (pending) {
701
- pending.resolve({ savedPath: msg.savedPath, filename: msg.filename });
702
- this.pendingUploads.delete(msg.uploadId);
703
- }
1012
+ case 'file_uploaded':
1013
+ this.completeUpload(msg.uploadId, { savedPath: msg.savedPath, filename: msg.filename });
704
1014
  break;
705
- }
706
- case 'file_upload_error': {
707
- const pending = this.pendingUploads.get(msg.uploadId);
708
- if (pending) {
709
- pending.reject(new Error(msg.error));
710
- this.pendingUploads.delete(msg.uploadId);
711
- }
1015
+ case 'file_upload_error':
1016
+ this.failUpload(msg.uploadId, msg.error);
1017
+ break;
1018
+ case 'upload_offset':
1019
+ this.handleUploadOffset(msg);
712
1020
  break;
713
- }
714
1021
  case 'agent_start':
715
1022
  if (this.agentEndTimeout) {
716
1023
  clearTimeout(this.agentEndTimeout);
@@ -1140,6 +1447,21 @@ export class WhereverClient {
1140
1447
  // This reply matches the load we were waiting on (or the create we
1141
1448
  // requested): the load is resolved, so stop guarding against it.
1142
1449
  this.pendingLoadFile = null;
1450
+ // The server accepted the load: whatever follows (folder_missing, a
1451
+ // failed cold build) comes after an authoritative paint and must keep
1452
+ // the readable-but-blocked view, so it can no longer reject a hydration.
1453
+ this.hydratedFile = null;
1454
+ // The server has now applied this client's write verdict for the
1455
+ // session (it sets readOnly before sending session_created), so uploads
1456
+ // held across the reconnect can go out and be gated correctly.
1457
+ if (this.uploadsHeldForRejoin) {
1458
+ this.uploadsHeldForRejoin = false;
1459
+ // Release only uploads aimed at the session we actually rejoined. A
1460
+ // different session here means the user switched mid-hold; sending the
1461
+ // old target's upload now would be gated by THIS session's verdict.
1462
+ this.failUnsentUploads('The session changed before the upload could be sent', msg.sessionId);
1463
+ this.resendPendingUploads();
1464
+ }
1143
1465
  this.stateStore.update((s) => ({
1144
1466
  ...s,
1145
1467
  session: msg.sessionFile,
@@ -1147,6 +1469,11 @@ export class WhereverClient {
1147
1469
  activeSessionFile: msg.sessionFile,
1148
1470
  activeCwd: msg.cwd,
1149
1471
  activeModel: msg.model,
1472
+ // Stamp the server that delivered this session (ADR 0013).
1473
+ serverKey: this.socketServerKey,
1474
+ // Its message_history follows; until then the paging state in the
1475
+ // store is not this session's.
1476
+ historyAuthoritative: false,
1150
1477
  isStreaming: msg.isStreaming ?? false,
1151
1478
  creatingSession: false,
1152
1479
  // The server forces read-only for sessions in a configured
@@ -1273,6 +1600,9 @@ export class WhereverClient {
1273
1600
  });
1274
1601
  break;
1275
1602
  case 'session_destroyed':
1603
+ if (get(this.stateStore).sessionId === msg.sessionId) {
1604
+ this.failHeldUploads('The session ended before the upload could be sent');
1605
+ }
1276
1606
  this.stateStore.update((s) => {
1277
1607
  if (s.sessionId === msg.sessionId) {
1278
1608
  return {
@@ -1294,7 +1624,24 @@ export class WhereverClient {
1294
1624
  return s;
1295
1625
  });
1296
1626
  break;
1297
- case 'session_error':
1627
+ case 'session_error': {
1628
+ // While held, the only request in flight is the rejoin: it failed, so the
1629
+ // held uploads can never be gated and sent. Fail them now rather than
1630
+ // leaving them (and every new upload) parked for the full timeout.
1631
+ // The rejoin's own errors carry no sessionId (a failed session_load or
1632
+ // its exception path); an error tagged with a session belongs to some
1633
+ // other request and must not fail the held uploads.
1634
+ if (!msg.sessionId) {
1635
+ this.failHeldUploads('Could not rejoin the session, so the upload was not sent');
1636
+ }
1637
+ // The server refused the load of a HYDRATED session outright. Only the
1638
+ // reply to the rejoin's own session_load counts: with no session
1639
+ // attached, the server's catch-all sends EVERY handler error untagged,
1640
+ // so the error must arrive while that load is still the pending one and
1641
+ // before any session_created (which clears hydratedFile).
1642
+ const rejectedHydration = !msg.sessionId &&
1643
+ this.hydratedFile !== null &&
1644
+ this.pendingLoadFile === this.hydratedFile;
1298
1645
  this.stateStore.update((s) => ({
1299
1646
  ...s,
1300
1647
  sessionError: msg.error,
@@ -1307,7 +1654,10 @@ export class WhereverClient {
1307
1654
  // is surfaced. This is the degrade-to-read-only path.
1308
1655
  agentPending: false,
1309
1656
  }));
1657
+ if (rejectedHydration)
1658
+ this.rejectHydration();
1310
1659
  break;
1660
+ }
1311
1661
  case 'folder_missing':
1312
1662
  // The server states, authoritatively, that this session's working folder
1313
1663
  // is not usable -- it does not exist on this machine, or a restore is
@@ -1527,6 +1877,7 @@ export class WhereverClient {
1527
1877
  messages: [...mapped, ...undelivered],
1528
1878
  historyTotalCount: totalCount,
1529
1879
  historyOffset: offset,
1880
+ historyAuthoritative: true,
1530
1881
  loadingMoreHistory: false,
1531
1882
  loadingSession: false,
1532
1883
  resyncing: false,
@@ -1782,6 +2133,10 @@ export class WhereverClient {
1782
2133
  const s = get(this.stateStore);
1783
2134
  if (!s.sessionId)
1784
2135
  return;
2136
+ // The offset may come from the cache or a dropped socket: never page from
2137
+ // it until the server's own history has replaced it.
2138
+ if (!s.historyAuthoritative)
2139
+ return;
1785
2140
  if (s.loadingMoreHistory)
1786
2141
  return;
1787
2142
  if (s.historyOffset <= 0)
@@ -2224,6 +2579,79 @@ export class WhereverClient {
2224
2579
  return s;
2225
2580
  return { ...s, restore: mutate(current) };
2226
2581
  }
2582
+ /**
2583
+ * Paint a conversation from the web's on-device cache before the socket is up
2584
+ * (ADR 0013), so a reload after the OS killed the PWA shows it at once. Call
2585
+ * it, then `connect(cfg, true)`: onOpen's normal rejoin issues the
2586
+ * `session_load` and its `message_history` replaces the cached messages.
2587
+ *
2588
+ * A no-op unless the client holds nothing that could be clobbered: no active
2589
+ * session, no load in flight, not connected. The painted session is
2590
+ * `resyncing` (sending blocked) and NOT `historyAuthoritative`. `agentPending`,
2591
+ * `folderConflict`, `sudoPrompt` and `readOnly` stay at their defaults: they
2592
+ * are verdicts the server re-states on the rejoin. `pendingLoadFile` is NOT
2593
+ * set here (the rejoin sets it when it actually sends the load).
2594
+ *
2595
+ * Delivery-tagged user messages in the snapshot are dropped: undelivered
2596
+ * outbound messages are recovered only from localStorage on the history
2597
+ * reply (`loadPersistedPending`), so a cached copy would double-surface them.
2598
+ */
2599
+ hydrateCachedSession(snapshot) {
2600
+ const s = get(this.stateStore);
2601
+ if (s.activeSessionFile || this.pendingLoadFile !== null || s.connected)
2602
+ return;
2603
+ const messages = snapshot.messages.filter((m) => !(m.role === 'user' && m.delivery !== undefined));
2604
+ this.hydratedFile = snapshot.sessionFile;
2605
+ this.stateStore.update((st) => ({
2606
+ ...st,
2607
+ session: snapshot.sessionFile,
2608
+ sessionId: snapshot.sessionId,
2609
+ activeSessionFile: snapshot.sessionFile,
2610
+ activeCwd: snapshot.cwd,
2611
+ activeModel: snapshot.model,
2612
+ messages,
2613
+ historyTotalCount: snapshot.historyTotalCount ?? messages.length,
2614
+ historyOffset: snapshot.historyOffset ?? 0,
2615
+ historyAuthoritative: false,
2616
+ resyncing: true,
2617
+ isStreaming: false,
2618
+ serverKey: snapshot.serverKey ?? serverKey(this.config),
2619
+ }));
2620
+ }
2621
+ // The server refused the hydrated session's load: clear the cached view (the
2622
+ // session_error reducer already surfaced the error) and tell the listeners,
2623
+ // so the web evicts the record and drops the hash. Synthesized locally; it is
2624
+ // never a server frame.
2625
+ rejectHydration() {
2626
+ const sessionId = get(this.stateStore).sessionId;
2627
+ this.hydratedFile = null;
2628
+ this.pendingLoadFile = null;
2629
+ this.stateStore.update((s) => ({
2630
+ ...s,
2631
+ messages: [],
2632
+ session: null,
2633
+ sessionId: null,
2634
+ activeSessionFile: null,
2635
+ activeCwd: null,
2636
+ activeModel: null,
2637
+ historyTotalCount: 0,
2638
+ historyOffset: 0,
2639
+ historyAuthoritative: false,
2640
+ serverKey: null,
2641
+ resyncing: false,
2642
+ }));
2643
+ if (!sessionId)
2644
+ return;
2645
+ const event = { type: 'hydration_rejected', sessionId };
2646
+ for (const listener of this.listeners) {
2647
+ try {
2648
+ listener(event);
2649
+ }
2650
+ catch (err) {
2651
+ console.error("Error in message listener:", err);
2652
+ }
2653
+ }
2654
+ }
2227
2655
  joinSession(sessionFile, cwd, model) {
2228
2656
  this.stateStore.update((s) => ({
2229
2657
  ...s,
@@ -2255,6 +2683,7 @@ export class WhereverClient {
2255
2683
  if (s.activeSessionFile === sessionFile && !s.loadingSession && !s.resyncing) {
2256
2684
  return;
2257
2685
  }
2686
+ this.abandonUnsentUploads();
2258
2687
  if (s.sessionId) {
2259
2688
  this.send({ type: 'session_leave', sessionId: s.sessionId });
2260
2689
  }
@@ -2285,6 +2714,7 @@ export class WhereverClient {
2285
2714
  this.resumeSessionFile = null;
2286
2715
  this.resumeCwd = undefined;
2287
2716
  this.resumeModel = undefined;
2717
+ this.hydratedFile = null;
2288
2718
  // Switching supersedes any in-flight create; disarm its watchdog so it can't
2289
2719
  // later fire against the newly loaded session.
2290
2720
  this.clearCreateWatchdog();
@@ -2304,6 +2734,7 @@ export class WhereverClient {
2304
2734
  return this.send({ type: 'session_fork', sessionId, entryId });
2305
2735
  }
2306
2736
  createSession(cwd, model, gitInit, createRemote, repoVisibility, cloneRemote) {
2737
+ this.abandonUnsentUploads();
2307
2738
  this.stateStore.update((s) => ({
2308
2739
  ...s,
2309
2740
  folderConflict: null,
@@ -2319,6 +2750,7 @@ export class WhereverClient {
2319
2750
  // be rejected by a stale pendingLoadFile, and a late load reply for the old
2320
2751
  // target must not clobber the new session.
2321
2752
  this.pendingLoadFile = null;
2753
+ this.hydratedFile = null;
2322
2754
  this.send({
2323
2755
  type: 'session_new',
2324
2756
  cwd,
@@ -2333,6 +2765,7 @@ export class WhereverClient {
2333
2765
  this.armCreateWatchdog();
2334
2766
  }
2335
2767
  leaveSession() {
2768
+ this.abandonUnsentUploads();
2336
2769
  const s = get(this.stateStore);
2337
2770
  // Leaving abandons any in-flight create too, so disarm its watchdog even when
2338
2771
  // there is no sessionId yet (a create that has not resolved).
@@ -2369,6 +2802,7 @@ export class WhereverClient {
2369
2802
  }));
2370
2803
  this.clearLoadWatchdog();
2371
2804
  this.pendingLoadFile = null;
2805
+ this.hydratedFile = null;
2372
2806
  this.resumeSessionFile = null;
2373
2807
  this.resumeCwd = undefined;
2374
2808
  this.resumeModel = undefined;
@@ -2542,19 +2976,480 @@ export class WhereverClient {
2542
2976
  this.listeners.delete(cb);
2543
2977
  };
2544
2978
  }
2545
- uploadFileViaWebSocket(sessionId, filename, base64Data) {
2979
+ /**
2980
+ * Upload a file over the WebSocket. Resolves with the server's saved path;
2981
+ * rejects on failure (an `Error`, with `code: 'not_readable'` when the byte
2982
+ * source can no longer be read) or with "Upload cancelled" when
2983
+ * `options.signal` aborts. Progress (`{acked, size, state, error?}`) goes to
2984
+ * `options.onProgress` and to `uploadsStore`.
2985
+ *
2986
+ * The protocol is chosen when the upload is SENT, from that socket's
2987
+ * `connected.capabilities`: chunked (`upload.v1`) when advertised, else the
2988
+ * legacy base64 `file_upload` frame (see PendingUpload). The legacy path
2989
+ * refuses files over 72 MiB from `source.size`, before reading anything.
2990
+ */
2991
+ uploadFileViaWebSocket(sessionId, filename, source, options) {
2546
2992
  return new Promise((resolve, reject) => {
2547
- const uploadId = this.generateId();
2548
- this.pendingUploads.set(uploadId, { resolve, reject });
2549
- this.send({
2550
- type: 'file_upload',
2993
+ const signal = options?.signal;
2994
+ if (signal?.aborted) {
2995
+ options?.onProgress?.({ acked: 0, size: source.size, state: 'aborted' });
2996
+ reject(new Error('Upload cancelled'));
2997
+ return;
2998
+ }
2999
+ const uploadId = generateUploadId();
3000
+ const upload = {
2551
3001
  uploadId,
2552
3002
  sessionId,
2553
3003
  filename,
2554
- data: base64Data
2555
- });
3004
+ mime: options?.mime || undefined,
3005
+ source,
3006
+ onProgress: options?.onProgress,
3007
+ resolve,
3008
+ reject,
3009
+ timer: null,
3010
+ sentOn: null,
3011
+ protocol: null,
3012
+ state: 'queued',
3013
+ acked: 0,
3014
+ frame: null,
3015
+ preparing: false,
3016
+ sends: 0,
3017
+ begun: false,
3018
+ awaitingBegin: false,
3019
+ nextOffset: 0,
3020
+ inFlight: [],
3021
+ realigning: false,
3022
+ finishing: false,
3023
+ reading: false,
3024
+ readGen: 0,
3025
+ rate: null,
3026
+ lastAckAt: 0,
3027
+ };
3028
+ this.pendingUploads.set(uploadId, upload);
3029
+ this.reportUpload(upload);
3030
+ // Cancelling (e.g. the chip was removed) settles the promise and drops
3031
+ // the upload so it is not re-sent on the next reconnect. A chunked upload
3032
+ // the server knows about is told to drop its partial; a legacy frame
3033
+ // already handed to the socket cannot be recalled.
3034
+ signal?.addEventListener('abort', () => this.abortUpload(uploadId), { once: true });
3035
+ // Sent now when the socket is OPEN, its capabilities are known and it is
3036
+ // not mid-rejoin. Otherwise the upload waits in pendingUploads and is
3037
+ // sent once those hold.
3038
+ if (!this.trySendUpload(uploadId))
3039
+ this.ensureUploadTimer(uploadId);
2556
3040
  });
2557
3041
  }
3042
+ // Number of uploads still waiting for a server reply (sent or parked).
3043
+ pendingUploadCount() {
3044
+ return this.pendingUploads.size;
3045
+ }
3046
+ /** Drop a SETTLED upload's entry from uploadsStore (in-flight ones stay). */
3047
+ forgetUpload(uploadId) {
3048
+ if (this.pendingUploads.has(uploadId))
3049
+ return;
3050
+ this.uploadsStore.update((all) => {
3051
+ if (!(uploadId in all))
3052
+ return all;
3053
+ const next = { ...all };
3054
+ delete next[uploadId];
3055
+ return next;
3056
+ });
3057
+ }
3058
+ // Hand the upload to the current socket if it can go now. True when it is on
3059
+ // the wire (or settled: nothing left to wait for), false when it waits.
3060
+ trySendUpload(uploadId) {
3061
+ const upload = this.pendingUploads.get(uploadId);
3062
+ if (!upload || this.uploadsHeldForRejoin)
3063
+ return false;
3064
+ if (!this.ws || this.ws.readyState !== 1 /* OPEN */)
3065
+ return false;
3066
+ // Capabilities unknown: HOLD (see socketCapabilities).
3067
+ if (this.socketCapabilities === null)
3068
+ return false;
3069
+ const chunked = this.socketCapabilities.includes(UPLOAD_CAPABILITY);
3070
+ if (upload.protocol === null)
3071
+ upload.protocol = chunked ? 'chunked' : 'legacy';
3072
+ if (upload.protocol === 'chunked') {
3073
+ if (!chunked) {
3074
+ this.failUpload(uploadId, 'The server no longer supports resumable uploads, retry');
3075
+ return true;
3076
+ }
3077
+ return this.beginChunkedUpload(upload);
3078
+ }
3079
+ return this.sendLegacyUpload(upload);
3080
+ }
3081
+ sendLegacyUpload(upload) {
3082
+ if (upload.sends >= WhereverClient.MAX_UPLOAD_SENDS) {
3083
+ // Every previous attempt lost its socket mid-transfer: stop retrying.
3084
+ this.failUpload(upload.uploadId, 'Upload failed: the connection dropped during the transfer each time (the file may be too large or the connection too slow)');
3085
+ return true;
3086
+ }
3087
+ if (!upload.frame) {
3088
+ // Checked from the size BEFORE reading, so a huge video is never loaded
3089
+ // and encoded just to be refused (and never crashes the tab).
3090
+ if (upload.source.size > WhereverClient.MAX_LEGACY_UPLOAD_BYTES) {
3091
+ this.failUpload(upload.uploadId, 'File too large to upload over the WebSocket (max 72 MB)');
3092
+ return true;
3093
+ }
3094
+ if (!upload.preparing) {
3095
+ upload.preparing = true;
3096
+ this.prepareLegacyFrame(upload);
3097
+ }
3098
+ return false;
3099
+ }
3100
+ if (!this.send(upload.frame))
3101
+ return false;
3102
+ upload.sends++;
3103
+ upload.sentOn = this.ws;
3104
+ // On the wire: stop the waiting clock (transmission time is not bounded).
3105
+ this.stopUploadTimer(upload);
3106
+ this.reportUpload(upload, 'sending');
3107
+ return true;
3108
+ }
3109
+ // Read and base64-encode the whole file once, then send it if still wanted.
3110
+ prepareLegacyFrame(upload) {
3111
+ this.readLegacyBase64(upload.source).then((data) => {
3112
+ if (this.pendingUploads.get(upload.uploadId) !== upload)
3113
+ return;
3114
+ upload.preparing = false;
3115
+ upload.frame = {
3116
+ type: 'file_upload',
3117
+ uploadId: upload.uploadId,
3118
+ sessionId: upload.sessionId,
3119
+ filename: upload.filename,
3120
+ data,
3121
+ };
3122
+ if (!this.trySendUpload(upload.uploadId))
3123
+ this.ensureUploadTimer(upload.uploadId);
3124
+ }, (err) => {
3125
+ if (this.pendingUploads.get(upload.uploadId) !== upload)
3126
+ return;
3127
+ const e = err instanceof UploadReadError ? err : uploadReadError(err);
3128
+ this.failUpload(upload.uploadId, e.message, e.code);
3129
+ });
3130
+ }
3131
+ // base64 over reads of LEGACY_READ_BYTES (a multiple of 3, so no padding in
3132
+ // the middle), platform-neutral (btoa). MAX_UPLOAD_BASE64_CHARS is a
3133
+ // backstop for a source that yields more than its size claimed.
3134
+ async readLegacyBase64(source) {
3135
+ const parts = [];
3136
+ let chars = 0;
3137
+ for (let offset = 0; offset < source.size; offset += LEGACY_READ_BYTES) {
3138
+ const length = Math.min(LEGACY_READ_BYTES, source.size - offset);
3139
+ let bytes;
3140
+ try {
3141
+ bytes = await source.read(offset, length);
3142
+ }
3143
+ catch (err) {
3144
+ throw uploadReadError(err);
3145
+ }
3146
+ chars += 4 * Math.ceil(bytes.length / 3);
3147
+ if (chars > WhereverClient.MAX_UPLOAD_BASE64_CHARS) {
3148
+ throw new UploadReadError('File too large to upload over the WebSocket (max 72 MB)');
3149
+ }
3150
+ if (bytes.length !== length)
3151
+ throw shortReadError();
3152
+ parts.push(btoa(bytesToBinaryString(bytes)));
3153
+ }
3154
+ return parts.join('');
3155
+ }
3156
+ // (Re)start a chunked upload on the current socket: the begin's answer says
3157
+ // where to continue (or that it is already done).
3158
+ beginChunkedUpload(upload) {
3159
+ const sent = this.send({
3160
+ type: 'upload_begin',
3161
+ uploadId: upload.uploadId,
3162
+ sessionId: upload.sessionId,
3163
+ filename: upload.filename,
3164
+ size: upload.source.size,
3165
+ ...(upload.mime ? { mime: upload.mime } : {}),
3166
+ });
3167
+ if (!sent)
3168
+ return false;
3169
+ upload.begun = true;
3170
+ upload.sentOn = this.ws;
3171
+ upload.awaitingBegin = true;
3172
+ upload.inFlight = [];
3173
+ upload.realigning = false;
3174
+ upload.finishing = false;
3175
+ upload.readGen++;
3176
+ // Transmitting: the waiting clock stops (it bounds waiting, not sending).
3177
+ this.stopUploadTimer(upload);
3178
+ this.reportUpload(upload, 'sending');
3179
+ return true;
3180
+ }
3181
+ // `upload_offset`: the server's offset for a chunked upload, answering a begin
3182
+ // or a chunk. Progress is ONLY ever this value, never what was sent.
3183
+ handleUploadOffset(msg) {
3184
+ const upload = this.pendingUploads.get(msg.uploadId);
3185
+ if (!upload || upload.protocol !== 'chunked' || !this.isUploadOnWire(upload))
3186
+ return;
3187
+ if (msg.done) {
3188
+ this.completeUpload(upload.uploadId, { savedPath: msg.savedPath, filename: upload.filename });
3189
+ return;
3190
+ }
3191
+ const offset = msg.offset;
3192
+ const size = upload.source.size;
3193
+ if (!Number.isSafeInteger(offset) || offset < 0 || offset > size)
3194
+ return;
3195
+ const now = Date.now();
3196
+ if (upload.awaitingBegin) {
3197
+ upload.awaitingBegin = false;
3198
+ upload.nextOffset = offset;
3199
+ upload.lastAckAt = now;
3200
+ }
3201
+ else {
3202
+ const chunk = upload.inFlight.shift();
3203
+ if (!chunk)
3204
+ return; // nothing of ours is awaiting an answer
3205
+ if (!upload.realigning && offset === chunk.offset + chunk.length) {
3206
+ // Time this chunk from when it could start being serviced: its send, or
3207
+ // the previous ack if it was queued behind that one.
3208
+ const elapsed = Math.max(1, now - Math.max(chunk.sentAt, upload.lastAckAt));
3209
+ const sample = chunk.length / elapsed;
3210
+ upload.rate =
3211
+ upload.rate === null ? sample : upload.rate * (1 - UPLOAD_RATE_ALPHA) + sample * UPLOAD_RATE_ALPHA;
3212
+ upload.lastAckAt = now;
3213
+ }
3214
+ else if (!upload.realigning) {
3215
+ // Out of step with the server: discard any read meant for the old
3216
+ // position and wait for the rest of the in-flight acks.
3217
+ upload.realigning = true;
3218
+ upload.readGen++;
3219
+ }
3220
+ if (upload.realigning && upload.inFlight.length === 0) {
3221
+ upload.realigning = false;
3222
+ upload.nextOffset = offset;
3223
+ upload.lastAckAt = now;
3224
+ }
3225
+ }
3226
+ upload.acked = offset;
3227
+ this.reportUpload(upload);
3228
+ this.pumpUpload(upload);
3229
+ }
3230
+ uploadWindow(upload) {
3231
+ if (upload.rate === null)
3232
+ return UPLOAD_WINDOW_MIN;
3233
+ const bytes = upload.rate * 1000 * UPLOAD_WINDOW_SECONDS;
3234
+ return Math.min(UPLOAD_WINDOW_MAX, Math.max(UPLOAD_WINDOW_MIN, Math.floor(bytes)));
3235
+ }
3236
+ // Send the next chunk if the window allows, or finish once every byte is
3237
+ // acked. One source read at a time; each completed send pumps again.
3238
+ pumpUpload(upload) {
3239
+ if (this.pendingUploads.get(upload.uploadId) !== upload)
3240
+ return;
3241
+ if (upload.reading || upload.awaitingBegin || upload.realigning || upload.finishing)
3242
+ return;
3243
+ if (!this.isUploadOnWire(upload))
3244
+ return;
3245
+ const size = upload.source.size;
3246
+ if (upload.acked === size && upload.inFlight.length === 0) {
3247
+ if (!this.send({ type: 'upload_finish', uploadId: upload.uploadId, sessionId: upload.sessionId }))
3248
+ return;
3249
+ upload.finishing = true;
3250
+ this.reportUpload(upload, 'finishing');
3251
+ return;
3252
+ }
3253
+ if (upload.nextOffset >= size)
3254
+ return;
3255
+ const window = this.uploadWindow(upload);
3256
+ const length = Math.min(window, UPLOAD_CHUNK_MAX, size - upload.nextOffset);
3257
+ const inFlightBytes = upload.inFlight.reduce((n, c) => n + c.length, 0);
3258
+ if (inFlightBytes + length > window)
3259
+ return;
3260
+ const offset = upload.nextOffset;
3261
+ const gen = upload.readGen;
3262
+ const socket = this.ws;
3263
+ upload.reading = true;
3264
+ Promise.resolve()
3265
+ .then(() => upload.source.read(offset, length))
3266
+ .then((bytes) => {
3267
+ if (this.pendingUploads.get(upload.uploadId) !== upload)
3268
+ return;
3269
+ upload.reading = false;
3270
+ // The socket or the alignment changed while reading: drop the bytes.
3271
+ if (gen !== upload.readGen || socket !== this.ws || !this.isUploadOnWire(upload)) {
3272
+ this.pumpUpload(upload);
3273
+ return;
3274
+ }
3275
+ if (bytes.length !== length) {
3276
+ const e = shortReadError();
3277
+ this.failUpload(upload.uploadId, e.message, e.code);
3278
+ return;
3279
+ }
3280
+ // A socket that refuses the frame is closing; its close handler
3281
+ // pauses the upload.
3282
+ if (!this.sendBinary(encodeChunkFrame(upload.uploadId, offset, bytes)))
3283
+ return;
3284
+ upload.inFlight.push({ offset, length, sentAt: Date.now() });
3285
+ upload.nextOffset = offset + length;
3286
+ this.pumpUpload(upload);
3287
+ }, (err) => {
3288
+ if (this.pendingUploads.get(upload.uploadId) !== upload)
3289
+ return;
3290
+ const e = uploadReadError(err);
3291
+ this.failUpload(upload.uploadId, e.message, e.code);
3292
+ });
3293
+ }
3294
+ sendBinary(bytes) {
3295
+ if (this.ws && this.ws.readyState === 1 /* OPEN */) {
3296
+ try {
3297
+ this.ws.send(bytes);
3298
+ return true;
3299
+ }
3300
+ catch {
3301
+ return false;
3302
+ }
3303
+ }
3304
+ return false;
3305
+ }
3306
+ // Record (and announce) an upload's progress. `state` defaults to the current.
3307
+ reportUpload(upload, state, error) {
3308
+ if (state)
3309
+ upload.state = state;
3310
+ const progress = {
3311
+ acked: upload.acked,
3312
+ size: upload.source.size,
3313
+ state: upload.state,
3314
+ ...(error ? { error } : {}),
3315
+ };
3316
+ this.uploadsStore.update((all) => ({ ...all, [upload.uploadId]: progress }));
3317
+ if (upload.onProgress) {
3318
+ try {
3319
+ upload.onProgress({ ...progress });
3320
+ }
3321
+ catch (err) {
3322
+ console.error('Upload onProgress failed:', err);
3323
+ }
3324
+ }
3325
+ }
3326
+ completeUpload(uploadId, result) {
3327
+ const upload = this.takePendingUpload(uploadId);
3328
+ if (!upload)
3329
+ return;
3330
+ upload.acked = upload.source.size;
3331
+ this.reportUpload(upload, 'done');
3332
+ upload.resolve(result);
3333
+ }
3334
+ failUpload(uploadId, message, code) {
3335
+ const upload = this.takePendingUpload(uploadId);
3336
+ if (!upload)
3337
+ return;
3338
+ const err = new Error(message);
3339
+ if (code)
3340
+ err.code = code;
3341
+ this.reportUpload(upload, 'failed', code ? { message, code } : { message });
3342
+ upload.reject(err);
3343
+ }
3344
+ abortUpload(uploadId) {
3345
+ const upload = this.takePendingUpload(uploadId);
3346
+ if (!upload)
3347
+ return;
3348
+ // Best effort: with no open socket the partial is left to the server's GC.
3349
+ if (upload.protocol === 'chunked' && upload.begun) {
3350
+ this.send({ type: 'upload_abort', uploadId, sessionId: upload.sessionId });
3351
+ }
3352
+ this.reportUpload(upload, 'aborted');
3353
+ upload.reject(new Error('Upload cancelled'));
3354
+ }
3355
+ isUploadOnWire(pending) {
3356
+ return pending.sentOn !== null && pending.sentOn === this.ws;
3357
+ }
3358
+ // The socket carrying uploads went away (by close, suspend, or the liveness
3359
+ // teardown, the latter two bypassing onClose). Every upload is waiting again:
3360
+ // forget where it was sent, pause it, and restart its waiting clock, so no
3361
+ // upload can be left without a timer. A chunked upload forgets its in-flight
3362
+ // chunks: the next begin tells it what the server really has.
3363
+ uploadsLostSocket() {
3364
+ for (const [id, upload] of this.pendingUploads) {
3365
+ const wasOnWire = upload.sentOn !== null;
3366
+ upload.sentOn = null;
3367
+ if (upload.protocol === 'chunked') {
3368
+ upload.awaitingBegin = false;
3369
+ upload.inFlight = [];
3370
+ upload.realigning = false;
3371
+ upload.finishing = false;
3372
+ upload.readGen++;
3373
+ }
3374
+ if (wasOnWire && upload.state !== 'paused')
3375
+ this.reportUpload(upload, 'paused');
3376
+ // Arm only a clock that is not already running. Re-arming on every loss
3377
+ // restarted the deadline on each failed reconnect attempt (at most 15 s
3378
+ // apart), so an upload against an unreachable server waited forever.
3379
+ this.ensureUploadTimer(id);
3380
+ }
3381
+ }
3382
+ // Fail uploads that have not reached the current socket (parked or held),
3383
+ // optionally sparing those aimed at `keepSessionId`.
3384
+ failUnsentUploads(reason, keepSessionId) {
3385
+ for (const [id, upload] of [...this.pendingUploads]) {
3386
+ if (this.isUploadOnWire(upload))
3387
+ continue;
3388
+ if (keepSessionId && upload.sessionId === keepSessionId)
3389
+ continue;
3390
+ this.failUpload(id, reason);
3391
+ }
3392
+ }
3393
+ failHeldUploads(reason) {
3394
+ if (!this.uploadsHeldForRejoin)
3395
+ return;
3396
+ this.uploadsHeldForRejoin = false;
3397
+ this.failUnsentUploads(reason);
3398
+ }
3399
+ // Switching / creating / leaving a session: an upload not yet on the wire
3400
+ // would otherwise be released by the NEXT session's session_created and be
3401
+ // gated by the wrong session's verdict. One already on the wire is left to
3402
+ // its reply (the server answers on this socket regardless of attachment).
3403
+ abandonUnsentUploads() {
3404
+ this.uploadsHeldForRejoin = false;
3405
+ this.failUnsentUploads('The session changed before the upload could be sent');
3406
+ }
3407
+ // Start the waiting clock unless one is already running (keeps the deadline).
3408
+ ensureUploadTimer(uploadId) {
3409
+ const pending = this.pendingUploads.get(uploadId);
3410
+ if (pending && !pending.timer)
3411
+ this.armUploadTimer(uploadId);
3412
+ }
3413
+ stopUploadTimer(upload) {
3414
+ if (upload.timer)
3415
+ clearTimeout(upload.timer);
3416
+ upload.timer = null;
3417
+ }
3418
+ armUploadTimer(uploadId) {
3419
+ const pending = this.pendingUploads.get(uploadId);
3420
+ if (!pending || typeof setTimeout !== 'function')
3421
+ return;
3422
+ if (pending.timer)
3423
+ clearTimeout(pending.timer);
3424
+ pending.timer = setTimeout(() => {
3425
+ this.failUpload(uploadId, 'Upload timed out (no connection to the server)');
3426
+ }, WhereverClient.UPLOAD_TIMEOUT_MS);
3427
+ if (pending.timer && typeof pending.timer.unref === 'function') {
3428
+ pending.timer.unref();
3429
+ }
3430
+ }
3431
+ takePendingUpload(uploadId) {
3432
+ const pending = this.pendingUploads.get(uploadId);
3433
+ if (!pending)
3434
+ return undefined;
3435
+ this.pendingUploads.delete(uploadId);
3436
+ if (pending.timer)
3437
+ clearTimeout(pending.timer);
3438
+ return pending;
3439
+ }
3440
+ resendPendingUploads() {
3441
+ for (const [id, pending] of [...this.pendingUploads]) {
3442
+ if (this.isUploadOnWire(pending))
3443
+ continue;
3444
+ if (!this.trySendUpload(id))
3445
+ this.ensureUploadTimer(id);
3446
+ }
3447
+ }
3448
+ rejectPendingUploads(reason) {
3449
+ for (const id of [...this.pendingUploads.keys()]) {
3450
+ this.failUpload(id, reason);
3451
+ }
3452
+ }
2558
3453
  generateId() {
2559
3454
  return Math.random().toString(36).substring(2) + Date.now().toString(36);
2560
3455
  }