@wherever-dev/client 0.6.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/src/client.ts CHANGED
@@ -1,8 +1,13 @@
1
1
  import { writable, get, type Writable } from "sveltore";
2
2
  import {
3
3
  type ChatMessage,
4
+ type HydrationSnapshot,
4
5
  type RestoreInfo,
5
6
  type RestoreJobInfo,
7
+ type UploadByteSource,
8
+ type UploadOptions,
9
+ type UploadProgress,
10
+ type UploadState,
6
11
  type WhereverState,
7
12
  skillInvocationIdentity,
8
13
  } from "./types.js";
@@ -53,6 +58,185 @@ function generateClientKey(): string {
53
58
  return `ck-${Math.random().toString(36).slice(2)}${Date.now().toString(36)}`;
54
59
  }
55
60
 
61
+ // --- Uploads (docs/adr/0012, frames in docs/USAGE.md) ----------------------
62
+
63
+ /** The capability a server advertises in `connected` for chunked uploads. */
64
+ export const UPLOAD_CAPABILITY = 'upload.v1';
65
+
66
+ const KiB = 1024;
67
+ /**
68
+ * Chunked-upload pacing. The window is the number of BYTES in flight (sent, not
69
+ * yet acked): about UPLOAD_WINDOW_SECONDS worth at the throughput measured from
70
+ * acks, clamped to [UPLOAD_WINDOW_MIN, UPLOAD_WINDOW_MAX]. Before any ack has
71
+ * been timed it is the minimum, so a slow uplink is never flooded (a queue of
72
+ * bytes ahead of the heartbeat pong is what used to kill the socket). Each chunk
73
+ * is `min(window, UPLOAD_CHUNK_MAX)`, well under the server's 1 MiB cap.
74
+ */
75
+ const UPLOAD_WINDOW_MIN = 64 * KiB;
76
+ const UPLOAD_WINDOW_MAX = 1024 * KiB;
77
+ const UPLOAD_CHUNK_MAX = 256 * KiB;
78
+ const UPLOAD_WINDOW_SECONDS = 2;
79
+ // Weight of the newest throughput sample in the moving average.
80
+ const UPLOAD_RATE_ALPHA = 0.3;
81
+ // Legacy base64 is built from reads of this many bytes: a multiple of 3, so
82
+ // each piece encodes without `=` padding and the pieces simply concatenate.
83
+ const LEGACY_READ_BYTES = 3 * 256 * KiB;
84
+
85
+ const NOT_READABLE_MESSAGE = 'The file is no longer readable, pick it again';
86
+
87
+ /**
88
+ * One upload in flight. The PROTOCOL is chosen when the upload is first SENT,
89
+ * from that socket's `connected.capabilities` (never at creation: the socket
90
+ * may change before then), and then stays fixed:
91
+ *
92
+ * - `chunked` (`upload.v1`): `upload_begin` -> binary chunks, each acked with
93
+ * `upload_offset` -> `upload_finish` -> `file_uploaded`. Every (re)send starts
94
+ * with a begin, whose offset says where to continue, so nothing acked is ever
95
+ * re-sent. Reconnecting to a server WITHOUT the capability fails it ("retry"):
96
+ * switching it to legacy would silently re-send the whole file.
97
+ * - `legacy`: one base64 `file_upload` frame, built once at the first send and
98
+ * re-sent whole after a lost socket (capped by MAX_UPLOAD_SENDS). A legacy
99
+ * upload is NOT upgraded to chunked on a newer server: the old server may
100
+ * already have saved it, and the frame is already built.
101
+ */
102
+ interface PendingUpload {
103
+ uploadId: string;
104
+ sessionId: string;
105
+ filename: string;
106
+ mime?: string;
107
+ source: UploadByteSource;
108
+ onProgress?: (progress: UploadProgress) => void;
109
+ resolve: (val: {savedPath: string; filename: string}) => void;
110
+ reject: (err: any) => void;
111
+ // The waiting clock (UPLOAD_TIMEOUT_MS); running only while not on the wire.
112
+ timer: ReturnType<typeof setTimeout> | null;
113
+ // The socket the upload was last handed to (null = never sent / lost). It
114
+ // only counts as sent for the socket that is still current.
115
+ sentOn: any;
116
+ protocol: 'legacy' | 'chunked' | null;
117
+ state: UploadState;
118
+ acked: number;
119
+ // Legacy: the frame once built, whether its read is running, and how many
120
+ // times it has been handed to a socket.
121
+ frame: any | null;
122
+ preparing: boolean;
123
+ sends: number;
124
+ // Chunked: an upload_begin has been sent at least once (so cancel must tell
125
+ // the server); waiting for the current begin's answer; the next byte to send;
126
+ // the chunks sent and not yet acked, in order (acks come back in order).
127
+ begun: boolean;
128
+ awaitingBegin: boolean;
129
+ nextOffset: number;
130
+ inFlight: Array<{offset: number; length: number; sentAt: number}>;
131
+ // An ack did not match its chunk: send nothing until every in-flight chunk is
132
+ // answered, then continue from the last (true) offset.
133
+ realigning: boolean;
134
+ finishing: boolean;
135
+ // A source read is running; readGen invalidates its result when the socket
136
+ // or the alignment changed meanwhile.
137
+ reading: boolean;
138
+ readGen: number;
139
+ // Measured throughput in bytes/ms (null until the first timed ack).
140
+ rate: number | null;
141
+ lastAckAt: number;
142
+ }
143
+
144
+ /** `[u8 kind=1][u8 version=1][u8 idLen][uploadId ascii][u64 offset BE][payload]` */
145
+ export function encodeChunkFrame(uploadId: string, offset: number, payload: Uint8Array): Uint8Array {
146
+ const head = 3 + uploadId.length;
147
+ const frame = new Uint8Array(head + 8 + payload.length);
148
+ frame[0] = 1;
149
+ frame[1] = 1;
150
+ frame[2] = uploadId.length;
151
+ for (let i = 0; i < uploadId.length; i++) frame[3 + i] = uploadId.charCodeAt(i);
152
+ const view = new DataView(frame.buffer);
153
+ view.setUint32(head, Math.floor(offset / 2 ** 32));
154
+ view.setUint32(head + 4, offset >>> 0);
155
+ frame.set(payload, head + 8);
156
+ return frame;
157
+ }
158
+
159
+ function bytesToBinaryString(bytes: Uint8Array): string {
160
+ let out = '';
161
+ for (let i = 0; i < bytes.length; i += 0x8000) {
162
+ out += String.fromCharCode.apply(null, bytes.subarray(i, i + 0x8000) as unknown as number[]);
163
+ }
164
+ return out;
165
+ }
166
+
167
+ /**
168
+ * 128 random bits, base64url without padding (22 characters, matching the
169
+ * server's `^[A-Za-z0-9_-]{22,64}$`). The id is what makes a resume
170
+ * unguessable, so it comes from `crypto.getRandomValues`; Math.random is only a
171
+ * last resort for a runtime without Web Crypto.
172
+ */
173
+ function generateUploadId(): string {
174
+ const bytes = new Uint8Array(16);
175
+ const c = (globalThis as any).crypto;
176
+ if (c && typeof c.getRandomValues === 'function') {
177
+ c.getRandomValues(bytes);
178
+ } else {
179
+ for (let i = 0; i < bytes.length; i++) bytes[i] = Math.floor(Math.random() * 256);
180
+ }
181
+ return btoa(bytesToBinaryString(bytes)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
182
+ }
183
+
184
+ class UploadReadError extends Error {
185
+ code?: 'not_readable';
186
+ }
187
+
188
+ // The error an upload fails with when its byte source cannot be read.
189
+ function uploadReadError(err: any): UploadReadError {
190
+ if (err instanceof UploadReadError) return err;
191
+ if (err && err.name === 'NotReadableError') {
192
+ const e = new UploadReadError(NOT_READABLE_MESSAGE);
193
+ e.code = 'not_readable';
194
+ return e;
195
+ }
196
+ return new UploadReadError(`Failed to read the file: ${(err && err.message) || err}`);
197
+ }
198
+
199
+ // A read that returned fewer (or other) bytes than asked: the file changed or
200
+ // was invalidated under us, which to the user is the same as unreadable.
201
+ function shortReadError(): UploadReadError {
202
+ const e = new UploadReadError(NOT_READABLE_MESSAGE);
203
+ e.code = 'not_readable';
204
+ return e;
205
+ }
206
+
207
+ // The host as it goes on the socket URL: a pasted `http(s)://` prefix is dropped.
208
+ function socketHost(host: string): string {
209
+ return host.startsWith('http') ? host.replace(/^https?:\/\//, '') : host;
210
+ }
211
+
212
+ // 32-bit FNV-1a over the UTF-16 code units, as 8 hex digits. NOT a security
213
+ // hash: it only keeps the raw token out of the key (and out of IndexedDB keys)
214
+ // while still telling two tokens apart.
215
+ function fnv1a(input: string): string {
216
+ let h = 0x811c9dc5;
217
+ for (let i = 0; i < input.length; i++) {
218
+ h ^= input.charCodeAt(i);
219
+ h = Math.imul(h, 0x01000193);
220
+ }
221
+ return (h >>> 0).toString(16).padStart(8, '0');
222
+ }
223
+
224
+ /**
225
+ * The identity of the server a config points at: `host:port#<fnv1a(token)>`.
226
+ * Two configured servers (or one server with a rotated token) never share a
227
+ * key, so the web's conversation cache can never show one server's
228
+ * conversation for another (ADR 0013).
229
+ *
230
+ * Synchronous and pure on purpose: `connect()` is synchronous and must compare
231
+ * it with the stamp before deciding whether to preserve the store, and
232
+ * `crypto.subtle` is both async and missing on plain-http LAN origins. The
233
+ * scheme (`secure`) is deliberately NOT part of the key: ws vs wss to the same
234
+ * host:port is the same server.
235
+ */
236
+ export function serverKey(config: Pick<WhereverClientConfig, 'host' | 'port' | 'token'>): string {
237
+ return `${socketHost(config.host)}:${config.port}#${fnv1a(config.token ?? '')}`;
238
+ }
239
+
56
240
  const defaultState: WhereverState = {
57
241
  connected: false,
58
242
  connecting: false,
@@ -83,6 +267,8 @@ const defaultState: WhereverState = {
83
267
  historyTotalCount: 0,
84
268
  historyOffset: 0,
85
269
  loadingMoreHistory: false,
270
+ historyAuthoritative: false,
271
+ serverKey: null,
86
272
  contextUsage: null,
87
273
  pendingSteering: [],
88
274
  skills: [],
@@ -149,6 +335,22 @@ export class WhereverClient {
149
335
  private static readonly TURN_STALL_MS = 45_000;
150
336
  // Send a keepalive well under STALE_SOCKET_MS so the pong refreshes liveness.
151
337
  private static readonly HEARTBEAT_MS = 25_000;
338
+ // Probe-before-teardown (docs/adr/0011): silence past the threshold never
339
+ // tears a socket down by itself. The watchdog pings and waits this long; ANY
340
+ // inbound frame in that window (onMessage) cancels the probe, and only a
341
+ // socket still silent when it expires is torn down. Needed because on a thaw
342
+ // the timers fire BEFORE the frames queued during the freeze are dispatched,
343
+ // so the raw silence verdict is routinely false on a phone.
344
+ private static readonly PROBE_GRACE_MS = 5_000;
345
+ // The pending probe's grace timer, and the socket it was started on. Cleared
346
+ // by any inbound frame, by stopLivenessWatchdog (every socket change), and
347
+ // ignored if the socket it belongs to is no longer current.
348
+ private probeTimer: ReturnType<typeof setTimeout> | null = null;
349
+ // Wall-clock time of the previous watchdog tick. A gap of more than 2x
350
+ // HEARTBEAT_MS means the page was frozen; that is an extra, PROACTIVE probe
351
+ // trigger, never the gate (a 45-50 s freeze gap is not a >2x jump yet still
352
+ // crosses TURN_STALL_MS, which is why the probe itself decides).
353
+ private lastLivenessTickAt = 0;
152
354
  private isInitialConnect = true;
153
355
  // When set, the next successful (re)connection should rejoin the previously
154
356
  // active session instead of starting blank. Used by resume() so a backgrounded
@@ -165,8 +367,63 @@ export class WhereverClient {
165
367
  // null means "accept any" (e.g. session_new, whose target file is not known
166
368
  // until the reply). The latest tap always wins.
167
369
  private pendingLoadFile: string | null = null;
370
+ // serverKey(config) of the socket currently open (captured by connect() next
371
+ // to the socket it opens). session_created stamps it on the store, so the
372
+ // stamp names the server that actually DELIVERED the session even if the
373
+ // settings are edited afterwards.
374
+ private socketServerKey: string | null = null;
375
+ // The sessionFile painted by hydrateCachedSession(), until the server answers
376
+ // its rejoin with a session_created (or the hydration is abandoned). While
377
+ // set, an untagged session_error answering that load (pendingLoadFile ===
378
+ // hydratedFile) means the cached session is dead: see hydration_rejected.
379
+ private hydratedFile: string | null = null;
168
380
  private listeners = new Set<(msg: any) => void>();
169
- private pendingUploads = new Map<string, {resolve: (val: any) => void, reject: (err: any) => void}>();
381
+ // In-flight WebSocket uploads, keyed by uploadId. An upload is NOT bound to
382
+ // the socket it started on. On mobile, picking a file backgrounds the page and
383
+ // the socket is often lost within seconds; the upload then waits for the next
384
+ // connection (it is (re)sent once the rejoin is answered, since a reply owed
385
+ // by a dead socket never arrives). Without a server reply an upload is
386
+ // settled by: a full teardown (disconnect(true)), UPLOAD_TIMEOUT_MS of
387
+ // waiting, MAX_UPLOAD_SENDS attempts each lost with its socket (legacy only),
388
+ // cancellation, or a session change. The one unbounded case is by design: an
389
+ // upload on the wire of a socket that stays open is left to its replies (the
390
+ // server's handlers always answer), so a slow but healthy transfer is never
391
+ // cut off. Two protocols share this machinery (see PendingUpload).
392
+ private pendingUploads = new Map<string, PendingUpload>();
393
+ // Progress of every upload this client started, keyed by uploadId: the same
394
+ // value each upload's onProgress receives. Settled entries (done / failed /
395
+ // aborted) stay until forgetUpload(), so a late subscriber still sees how an
396
+ // upload ended.
397
+ public uploadsStore: Writable<Record<string, UploadProgress>> = writable({});
398
+ // `connected.capabilities` of the CURRENT socket; null until its `connected`
399
+ // frame arrives. Uploads are HELD while null: sending one as legacy to a
400
+ // server that would have taken it chunked would throw resumability away.
401
+ private socketCapabilities: string[] | null = null;
402
+ // An upload whose socket dies under it on every attempt (a frame too large
403
+ // for the server's maxPayload, which closes with 1009; or a slow uplink where
404
+ // the multi-MB frame starves the heartbeat) would otherwise be re-sent
405
+ // forever, kicking the live session into a resync each time. After this many
406
+ // sends lost with their socket, it fails. LEGACY frame only: a chunked upload
407
+ // resumes from the server's offset, so a lost socket costs it nothing.
408
+ private static readonly MAX_UPLOAD_SENDS = 3;
409
+ // `ws`'s default maxPayload is 100 MiB per frame; leave room for the JSON
410
+ // envelope. Larger base64 payloads are refused (~72 MB files). A backstop:
411
+ // the legacy path refuses `size > MAX_LEGACY_UPLOAD_BYTES` before reading.
412
+ private static readonly MAX_UPLOAD_BASE64_CHARS = 96 * 1024 * 1024;
413
+ // base64 of 72 MiB is exactly 96 MiB, MAX_UPLOAD_BASE64_CHARS.
414
+ private static readonly MAX_LEGACY_UPLOAD_BYTES = 72 * 1024 * 1024;
415
+ // Bounds the time an upload spends WAITING to be sent (no socket, or held for
416
+ // a rejoin), not its transmission: the clock is cleared whenever the frame
417
+ // actually goes out on an open socket, and re-armed when that socket closes.
418
+ // So a large, slow-but-healthy upload is never rejected mid-transfer.
419
+ private static readonly UPLOAD_TIMEOUT_MS = 10 * 60_000;
420
+ // True between a reconnect's rejoin session_load and its session_created.
421
+ // A fresh server socket starts attached to no session with readOnly=false;
422
+ // the server only sets this client's write verdict (readOnly) when it answers
423
+ // the session_load. Uploads sent in that window would bypass the read-only
424
+ // gate (and a multi-MB frame queued ahead of the rejoin could trip the load
425
+ // watchdog), so they are held until session_created lands.
426
+ private uploadsHeldForRejoin = false;
170
427
  // Per-message confirmation watchdogs. A user message committed optimistically
171
428
  // is only proven delivered when the server echoes it back; if no echo lands
172
429
  // within CONFIRM_MS the watchdog flips it to delivery:'failed' so the UI can
@@ -198,6 +455,25 @@ export class WhereverClient {
198
455
 
199
456
  this.disconnect(false);
200
457
 
458
+ // A store stamped by ANOTHER server (host/port/token edited in Connection
459
+ // Settings, which saves without reconnecting, then this connect, including
460
+ // the automatic one from scheduleReconnect) must not be preserved or
461
+ // rejoined: it would paint, and the web would re-cache, one server's
462
+ // conversation under another's key, and the rejoin would ask the new
463
+ // server for a session it does not have. Wipe instead (which clears the
464
+ // stamp too), and drop every pending rejoin source.
465
+ const key = serverKey(this.config);
466
+ const stamped = get(this.stateStore).serverKey;
467
+ if (stamped !== null && stamped !== key) {
468
+ preserveState = false;
469
+ this.resumeSessionFile = null;
470
+ this.resumeCwd = undefined;
471
+ this.resumeModel = undefined;
472
+ this.pendingLoadFile = null;
473
+ this.hydratedFile = null;
474
+ }
475
+ this.socketServerKey = key;
476
+
201
477
  // preserveState keeps the cached session/messages in the store across a
202
478
  // reconnect (resume path), so the previous conversation stays visible while
203
479
  // we reconnect and resync. The default (fresh connect) clears to a blank
@@ -212,9 +488,7 @@ export class WhereverClient {
212
488
  });
213
489
 
214
490
  const protocol = this.config.secure ? "wss" : "ws";
215
- const host = this.config.host.startsWith('http')
216
- ? this.config.host.replace(/^https?:\/\//, '')
217
- : this.config.host;
491
+ const host = socketHost(this.config.host);
218
492
  // clientKey rides on the URL (not a post-connect frame) so the server can
219
493
  // evict this viewer's previous connection BEFORE any session traffic is
220
494
  // handled, closing the phantom-viewer window entirely.
@@ -234,6 +508,8 @@ export class WhereverClient {
234
508
  return;
235
509
  }
236
510
 
511
+ // A new socket: its capabilities are unknown until its `connected` frame.
512
+ this.socketCapabilities = null;
237
513
  try {
238
514
  const wsOptions = this.config.secure && this.config.WebSocketCtor ? { rejectUnauthorized: false } : undefined;
239
515
  this.ws = wsOptions ? new WebSocketImpl(wsUrl, wsOptions) : new WebSocketImpl(wsUrl);
@@ -295,12 +571,27 @@ export class WhereverClient {
295
571
  this.resumeSessionFile = null;
296
572
  this.resumeCwd = undefined;
297
573
  this.resumeModel = undefined;
574
+ // Uploads that were waiting for a socket (or whose reply died with the old
575
+ // one) go out only AFTER the rejoin has been answered (see
576
+ // uploadsHeldForRejoin): session_load first, uploads on session_created.
577
+ // With no session to rejoin there is no write verdict to wait for, and
578
+ // nothing to attribute the upload to any more, so they fail.
579
+ this.uploadsHeldForRejoin = !!rejoinFile;
580
+ if (!rejoinFile) {
581
+ this.rejectPendingUploads('The session was closed before the upload could be sent');
582
+ }
298
583
  if (rejoinFile) {
299
584
  // Keep the cached conversation on screen but mark it resyncing so the
300
585
  // "Reconnecting and syncing session..." banner shows and sending is
301
586
  // blocked until fresh history lands. resyncing is cleared by
302
587
  // message_history (or an error/conflict) via the reducer.
303
- this.stateStore.update(s => (s.resyncing ? s : {...s, resyncing: true}));
588
+ // The history in the store (cached, or from the dropped socket) may be
589
+ // stale until this rejoin's message_history lands.
590
+ this.stateStore.update(s =>
591
+ s.resyncing && !s.historyAuthoritative
592
+ ? s
593
+ : {...s, resyncing: true, historyAuthoritative: false},
594
+ );
304
595
  this.pendingLoadFile = rejoinFile;
305
596
  this.send({type: 'session_load', sessionFile: rejoinFile, cwd: rejoinCwd, model: rejoinModel});
306
597
  this.armLoadWatchdog();
@@ -314,6 +605,8 @@ export class WhereverClient {
314
605
  // Any inbound frame (including the pong reply to our keepalive) proves the
315
606
  // socket is alive and resets the stale-socket watchdog.
316
607
  this.lastInboundAt = Date.now();
608
+ // ...and answers any pending probe, so it must not tear the socket down.
609
+ this.cancelLivenessProbe();
317
610
  try {
318
611
  const rawData = typeof event.data === 'string' ? event.data : event.data.toString();
319
612
  const msg = JSON.parse(rawData);
@@ -325,6 +618,7 @@ export class WhereverClient {
325
618
 
326
619
  const onClose = () => {
327
620
  if (this.ws !== currentWs) return;
621
+ this.uploadsLostSocket();
328
622
  this.stopLivenessWatchdog();
329
623
  this.clearLoadWatchdog();
330
624
  this.ws = null;
@@ -384,6 +678,8 @@ export class WhereverClient {
384
678
  // state, so cancel them here.
385
679
  this.clearLoadWatchdog();
386
680
  this.clearCreateWatchdog();
681
+ // suspend()/resume() close the socket through here, bypassing onClose.
682
+ this.uploadsLostSocket();
387
683
 
388
684
  if (this.ws) {
389
685
  const dyingWs = this.ws as any;
@@ -419,6 +715,11 @@ export class WhereverClient {
419
715
  // load can still recover them.
420
716
  for (const t of this.confirmTimers.values()) clearTimeout(t);
421
717
  this.confirmTimers.clear();
718
+ // An explicit full disconnect abandons in-flight uploads (they would
719
+ // otherwise be re-sent to whatever server is connected next).
720
+ this.rejectPendingUploads('Disconnected before the upload completed');
721
+ this.uploadsHeldForRejoin = false;
722
+ this.hydratedFile = null;
422
723
  this.stateStore.set({
423
724
  ...defaultState,
424
725
  hideThinking: !!this.config.hideThinking,
@@ -477,12 +778,12 @@ export class WhereverClient {
477
778
  // cached active session from an unsolicited drop. In BOTH cases onOpen
478
779
  // re-issues session_load, so mark resyncing here to show the affordance and
479
780
  // block sending until fresh history lands.
781
+ // No load watchdog is armed here: connect() -> disconnect(false) would clear
782
+ // it at once, and onOpen arms one for the rejoin it actually issues. While
783
+ // the socket never opens (offline boot over a hydrated cache) there is no
784
+ // load in flight to time out, so no "timed out" error must appear.
480
785
  if (this.resumeSessionFile || s.activeSessionFile) {
481
786
  this.stateStore.update(st => ({...st, resyncing: true}));
482
- // Arm here too: if the socket never opens, onOpen never runs and the
483
- // resync affordance would otherwise hang. onClose also clears it, but the
484
- // watchdog covers the half-open / never-opens case.
485
- this.armLoadWatchdog();
486
787
  }
487
788
  this.connect(undefined, true);
488
789
  }
@@ -509,6 +810,7 @@ export class WhereverClient {
509
810
  private startLivenessWatchdog() {
510
811
  this.stopLivenessWatchdog();
511
812
  this.lastInboundAt = Date.now();
813
+ this.lastLivenessTickAt = this.lastInboundAt;
512
814
 
513
815
  const sendBeat = () => {
514
816
  // Keep a healthy connection warm so the pong refreshes lastInboundAt even
@@ -526,7 +828,17 @@ export class WhereverClient {
526
828
 
527
829
  const checkLiveness = () => {
528
830
  if (!this.ws) return;
529
- const silentFor = Date.now() - this.lastInboundAt;
831
+ const now = Date.now();
832
+ const sinceLastTick = now - this.lastLivenessTickAt;
833
+ this.lastLivenessTickAt = now;
834
+ // A wall-clock jump between ticks means the page was frozen: probe now
835
+ // rather than waiting for the silence threshold. Only a trigger; the
836
+ // probe's grace period still decides.
837
+ if (sinceLastTick > 2 * WhereverClient.HEARTBEAT_MS) {
838
+ this.startLivenessProbe('clock jump');
839
+ return;
840
+ }
841
+ const silentFor = now - this.lastInboundAt;
530
842
  const streaming = get(this.stateStore).isStreaming;
531
843
  // Per-turn stall timeout: while a turn is in flight the heartbeat pong (and,
532
844
  // normally, tokens) should keep traffic flowing, so a shorter deadline
@@ -537,38 +849,12 @@ export class WhereverClient {
537
849
  ? WhereverClient.TURN_STALL_MS
538
850
  : WhereverClient.STALE_SOCKET_MS;
539
851
  if (silentFor < threshold) return;
540
- // The socket has been silent past the threshold: treat it as dead. Tearing
541
- // it down forcibly is what makes a half-open connection recover, since the
542
- // OS never produced a FIN/RST to trigger the normal close path.
543
- console.warn(
544
- `[wherever] relay connection stale: no inbound frame for ${silentFor}ms ` +
545
- `(threshold ${threshold}ms, ${streaming ? 'mid-turn' : 'idle'}); ` +
546
- `tearing down dead socket and reconnecting`,
852
+ // Silent past the threshold: SUSPECT, not dead. Probe first (see
853
+ // PROBE_GRACE_MS); the teardown happens only if the probe goes unanswered.
854
+ this.startLivenessProbe(
855
+ `no inbound frame for ${silentFor}ms ` +
856
+ `(threshold ${threshold}ms, ${streaming ? 'mid-turn' : 'idle'})`,
547
857
  );
548
- this.stopLivenessWatchdog();
549
- const deadWs = this.ws;
550
- this.ws = null;
551
- try {
552
- if (typeof deadWs.terminate === 'function') {
553
- deadWs.terminate();
554
- } else if (typeof deadWs.close === 'function') {
555
- deadWs.close();
556
- }
557
- } catch {}
558
- this.stateStore.update(s => ({
559
- ...s,
560
- connected: false,
561
- connecting: false,
562
- loadingSession: false,
563
- creatingSession: false,
564
- // If a turn was in flight, surface it as a recoverable error so the UI
565
- // shows "the transport stalled" rather than silently parking mid-stream.
566
- sessionError: streaming
567
- ? 'Connection to relay stalled mid-turn; reconnecting...'
568
- : s.sessionError,
569
- isStreaming: false,
570
- }));
571
- this.scheduleReconnect();
572
858
  };
573
859
  if (typeof setInterval === 'function') {
574
860
  this.livenessTimer = setInterval(checkLiveness, WhereverClient.HEARTBEAT_MS);
@@ -578,7 +864,103 @@ export class WhereverClient {
578
864
  }
579
865
  }
580
866
 
867
+ // The page just became visible again (visibilitychange: visible, pageshow).
868
+ // The client has no `document` access, so the page calls this. If the current
869
+ // socket is OPEN and watched, probe it right away instead of waiting for the
870
+ // next tick, and reset the stale baseline so the time the page spent frozen is
871
+ // not counted as silence (the probe decides whether the socket is alive).
872
+ // A no-op otherwise: on a CONNECTING socket the ping would be dropped by
873
+ // send() and the grace check would tear down a socket still handshaking.
874
+ public noteVisible() {
875
+ const ws = this.ws as any;
876
+ if (!ws || ws.readyState !== 1 /* OPEN */ || !this.livenessTimer) return;
877
+ this.lastInboundAt = Date.now();
878
+ this.lastLivenessTickAt = this.lastInboundAt;
879
+ // Restart any pending probe: its grace may have been eaten by the freeze.
880
+ this.cancelLivenessProbe();
881
+ this.startLivenessProbe('page became visible');
882
+ }
883
+
884
+ // Send a ping and arm the grace check. Idempotent while a probe is pending.
885
+ private startLivenessProbe(reason: string) {
886
+ if (this.probeTimer || !this.ws || typeof setTimeout !== 'function') return;
887
+ const probedWs = this.ws;
888
+ try {
889
+ this.ping();
890
+ } catch {}
891
+ const sentAt = Date.now();
892
+ this.probeTimer = setTimeout(() => {
893
+ this.probeTimer = null;
894
+ if (this.ws !== probedWs) return;
895
+ // The grace check itself ran far too late: the page was frozen during
896
+ // the grace period, so the reply may still be queued behind this timer.
897
+ // Probe again rather than condemn the socket on frozen time.
898
+ // Decision (beyond the task's letter): this has no retry cap. Under heavy
899
+ // background timer throttling (timers batched to ~1/min in a long-hidden
900
+ // tab) every grace check is late, so the verdict on a dead socket is
901
+ // deferred until the page is visible again, where noteVisible() restarts
902
+ // an unthrottled probe and a dead socket goes ~5 s later. Accepted: a
903
+ // hidden page has no viewer, and a capped retry would reintroduce the
904
+ // false teardown on thaw this probe exists to prevent.
905
+ if (Date.now() - sentAt > 2 * WhereverClient.PROBE_GRACE_MS) {
906
+ this.startLivenessProbe(reason);
907
+ return;
908
+ }
909
+ this.tearDownStaleSocket(reason);
910
+ }, WhereverClient.PROBE_GRACE_MS);
911
+ if (this.probeTimer && typeof (this.probeTimer as any).unref === 'function') {
912
+ (this.probeTimer as any).unref();
913
+ }
914
+ }
915
+
916
+ private cancelLivenessProbe() {
917
+ if (this.probeTimer) {
918
+ clearTimeout(this.probeTimer);
919
+ this.probeTimer = null;
920
+ }
921
+ }
922
+
923
+ // The probe went unanswered: treat the socket as dead. Tearing it down
924
+ // forcibly is what makes a half-open connection recover, since the OS never
925
+ // produced a FIN/RST to trigger the normal close path.
926
+ private tearDownStaleSocket(reason: string) {
927
+ if (!this.ws) return;
928
+ const streaming = get(this.stateStore).isStreaming;
929
+ console.warn(
930
+ `[wherever] relay connection stale: ${reason}; probe unanswered for ` +
931
+ `${WhereverClient.PROBE_GRACE_MS}ms; tearing down dead socket and reconnecting`,
932
+ );
933
+ this.stopLivenessWatchdog();
934
+ const deadWs = this.ws;
935
+ this.ws = null;
936
+ // This path bypasses onClose (the socket is no longer current), so the
937
+ // uploads it carried must be marked waiting here.
938
+ this.uploadsLostSocket();
939
+ try {
940
+ if (typeof deadWs.terminate === 'function') {
941
+ deadWs.terminate();
942
+ } else if (typeof deadWs.close === 'function') {
943
+ deadWs.close();
944
+ }
945
+ } catch {}
946
+ this.stateStore.update(s => ({
947
+ ...s,
948
+ connected: false,
949
+ connecting: false,
950
+ loadingSession: false,
951
+ creatingSession: false,
952
+ // If a turn was in flight, surface it as a recoverable error so the UI
953
+ // shows "the transport stalled" rather than silently parking mid-stream.
954
+ sessionError: streaming
955
+ ? 'Connection to relay stalled mid-turn; reconnecting...'
956
+ : s.sessionError,
957
+ isStreaming: false,
958
+ }));
959
+ this.scheduleReconnect();
960
+ }
961
+
581
962
  private stopLivenessWatchdog() {
963
+ this.cancelLivenessProbe();
582
964
  if (this.heartbeatTimer) {
583
965
  clearInterval(this.heartbeatTimer);
584
966
  this.heartbeatTimer = null;
@@ -599,6 +981,7 @@ export class WhereverClient {
599
981
  const s = get(this.stateStore);
600
982
  if (!s.loadingSession && !s.resyncing) return;
601
983
  console.warn('[wherever] session load timed out; clearing loading state');
984
+ this.failHeldUploads('Could not rejoin the session, so the upload was not sent');
602
985
  this.stateStore.update(st => ({
603
986
  ...st,
604
987
  loadingSession: false,
@@ -751,6 +1134,12 @@ export class WhereverClient {
751
1134
  serverVersion: msg.serverVersion ?? null,
752
1135
  error: null,
753
1136
  }));
1137
+ // Uploads held for unknown capabilities can now choose their protocol
1138
+ // (still subject to the rejoin hold).
1139
+ this.socketCapabilities = Array.isArray(msg.capabilities)
1140
+ ? msg.capabilities.filter((c: unknown) => typeof c === 'string')
1141
+ : [];
1142
+ this.resendPendingUploads();
754
1143
  break;
755
1144
 
756
1145
  case 'connection_superseded':
@@ -768,23 +1157,17 @@ export class WhereverClient {
768
1157
  }
769
1158
  break;
770
1159
 
771
- case 'file_uploaded': {
772
- const pending = this.pendingUploads.get(msg.uploadId);
773
- if (pending) {
774
- pending.resolve({savedPath: msg.savedPath, filename: msg.filename});
775
- this.pendingUploads.delete(msg.uploadId);
776
- }
1160
+ case 'file_uploaded':
1161
+ this.completeUpload(msg.uploadId, {savedPath: msg.savedPath, filename: msg.filename});
777
1162
  break;
778
- }
779
1163
 
780
- case 'file_upload_error': {
781
- const pending = this.pendingUploads.get(msg.uploadId);
782
- if (pending) {
783
- pending.reject(new Error(msg.error));
784
- this.pendingUploads.delete(msg.uploadId);
785
- }
1164
+ case 'file_upload_error':
1165
+ this.failUpload(msg.uploadId, msg.error);
1166
+ break;
1167
+
1168
+ case 'upload_offset':
1169
+ this.handleUploadOffset(msg);
786
1170
  break;
787
- }
788
1171
 
789
1172
  case 'agent_start':
790
1173
  if (this.agentEndTimeout) {
@@ -1284,6 +1667,24 @@ export class WhereverClient {
1284
1667
  // This reply matches the load we were waiting on (or the create we
1285
1668
  // requested): the load is resolved, so stop guarding against it.
1286
1669
  this.pendingLoadFile = null;
1670
+ // The server accepted the load: whatever follows (folder_missing, a
1671
+ // failed cold build) comes after an authoritative paint and must keep
1672
+ // the readable-but-blocked view, so it can no longer reject a hydration.
1673
+ this.hydratedFile = null;
1674
+ // The server has now applied this client's write verdict for the
1675
+ // session (it sets readOnly before sending session_created), so uploads
1676
+ // held across the reconnect can go out and be gated correctly.
1677
+ if (this.uploadsHeldForRejoin) {
1678
+ this.uploadsHeldForRejoin = false;
1679
+ // Release only uploads aimed at the session we actually rejoined. A
1680
+ // different session here means the user switched mid-hold; sending the
1681
+ // old target's upload now would be gated by THIS session's verdict.
1682
+ this.failUnsentUploads(
1683
+ 'The session changed before the upload could be sent',
1684
+ msg.sessionId,
1685
+ );
1686
+ this.resendPendingUploads();
1687
+ }
1287
1688
  this.stateStore.update((s: WhereverState) => ({
1288
1689
  ...s,
1289
1690
  session: msg.sessionFile,
@@ -1291,6 +1692,11 @@ export class WhereverClient {
1291
1692
  activeSessionFile: msg.sessionFile,
1292
1693
  activeCwd: msg.cwd,
1293
1694
  activeModel: msg.model,
1695
+ // Stamp the server that delivered this session (ADR 0013).
1696
+ serverKey: this.socketServerKey,
1697
+ // Its message_history follows; until then the paging state in the
1698
+ // store is not this session's.
1699
+ historyAuthoritative: false,
1294
1700
  isStreaming: msg.isStreaming ?? false,
1295
1701
  creatingSession: false,
1296
1702
  // The server forces read-only for sessions in a configured
@@ -1363,6 +1769,17 @@ export class WhereverClient {
1363
1769
  }
1364
1770
  break;
1365
1771
 
1772
+ case 'session_reloading':
1773
+ // A `/reload` was accepted (by us or another viewer): the live agent is
1774
+ // being rebuilt. Block the composer exactly like a cold load; the
1775
+ // session_ready (or session_error) that ends the reload clears it and
1776
+ // re-requests the skill list. Ignore a frame for a session we left.
1777
+ this.stateStore.update((s: WhereverState) => {
1778
+ if (s.sessionId && msg.sessionId && s.sessionId !== msg.sessionId) return s;
1779
+ return { ...s, agentPending: true };
1780
+ });
1781
+ break;
1782
+
1366
1783
  case 'skills_list':
1367
1784
  // The set of `/skill:<name>` commands for the active session. Replace
1368
1785
  // outright; ignore a list for a session we already switched away from.
@@ -1408,6 +1825,9 @@ export class WhereverClient {
1408
1825
  break;
1409
1826
 
1410
1827
  case 'session_destroyed':
1828
+ if (get(this.stateStore).sessionId === msg.sessionId) {
1829
+ this.failHeldUploads('The session ended before the upload could be sent');
1830
+ }
1411
1831
  this.stateStore.update((s: WhereverState) => {
1412
1832
  if (s.sessionId === msg.sessionId) {
1413
1833
  return {
@@ -1430,7 +1850,25 @@ export class WhereverClient {
1430
1850
  });
1431
1851
  break;
1432
1852
 
1433
- case 'session_error':
1853
+ case 'session_error': {
1854
+ // While held, the only request in flight is the rejoin: it failed, so the
1855
+ // held uploads can never be gated and sent. Fail them now rather than
1856
+ // leaving them (and every new upload) parked for the full timeout.
1857
+ // The rejoin's own errors carry no sessionId (a failed session_load or
1858
+ // its exception path); an error tagged with a session belongs to some
1859
+ // other request and must not fail the held uploads.
1860
+ if (!msg.sessionId) {
1861
+ this.failHeldUploads('Could not rejoin the session, so the upload was not sent');
1862
+ }
1863
+ // The server refused the load of a HYDRATED session outright. Only the
1864
+ // reply to the rejoin's own session_load counts: with no session
1865
+ // attached, the server's catch-all sends EVERY handler error untagged,
1866
+ // so the error must arrive while that load is still the pending one and
1867
+ // before any session_created (which clears hydratedFile).
1868
+ const rejectedHydration =
1869
+ !msg.sessionId &&
1870
+ this.hydratedFile !== null &&
1871
+ this.pendingLoadFile === this.hydratedFile;
1434
1872
  this.stateStore.update((s: WhereverState) => ({
1435
1873
  ...s,
1436
1874
  sessionError: msg.error,
@@ -1443,7 +1881,9 @@ export class WhereverClient {
1443
1881
  // is surfaced. This is the degrade-to-read-only path.
1444
1882
  agentPending: false,
1445
1883
  }));
1884
+ if (rejectedHydration) this.rejectHydration();
1446
1885
  break;
1886
+ }
1447
1887
 
1448
1888
  case 'folder_missing':
1449
1889
  // The server states, authoritatively, that this session's working folder
@@ -1677,6 +2117,7 @@ export class WhereverClient {
1677
2117
  messages: [...mapped, ...undelivered],
1678
2118
  historyTotalCount: totalCount,
1679
2119
  historyOffset: offset,
2120
+ historyAuthoritative: true,
1680
2121
  loadingMoreHistory: false,
1681
2122
  loadingSession: false,
1682
2123
  resyncing: false,
@@ -1936,6 +2377,9 @@ export class WhereverClient {
1936
2377
  public loadMoreHistory() {
1937
2378
  const s = get(this.stateStore);
1938
2379
  if (!s.sessionId) return;
2380
+ // The offset may come from the cache or a dropped socket: never page from
2381
+ // it until the server's own history has replaced it.
2382
+ if (!s.historyAuthoritative) return;
1939
2383
  if (s.loadingMoreHistory) return;
1940
2384
  if (s.historyOffset <= 0) return;
1941
2385
  this.stateStore.update((st: WhereverState) => ({
@@ -2364,6 +2808,17 @@ export class WhereverClient {
2364
2808
  this.send({type: 'abort', sessionId: s.sessionId});
2365
2809
  }
2366
2810
 
2811
+ // The web `/reload`: ask the server to rebuild the active session's agent so
2812
+ // it re-reads settings, extensions, skills, prompts and context files. Nothing
2813
+ // is changed locally: the server answers session_reloading (block the
2814
+ // composer), then session_ready, or a session_notice when it refuses (the
2815
+ // agent is busy, a CLI bridge owns the session, read-only).
2816
+ public reloadResources(): void {
2817
+ const s = get(this.stateStore);
2818
+ if (!s.sessionId) return;
2819
+ this.send({type: 'session_reload', sessionId: s.sessionId});
2820
+ }
2821
+
2367
2822
  // Cancel the queued mid-stream steer messages for the active session without
2368
2823
  // aborting the in-flight turn. Optimistically clears our local pending-steer
2369
2824
  // set so the "Cancel" affordance disappears immediately; the server's fresh
@@ -2393,6 +2848,80 @@ export class WhereverClient {
2393
2848
  return {...s, restore: mutate(current)};
2394
2849
  }
2395
2850
 
2851
+ /**
2852
+ * Paint a conversation from the web's on-device cache before the socket is up
2853
+ * (ADR 0013), so a reload after the OS killed the PWA shows it at once. Call
2854
+ * it, then `connect(cfg, true)`: onOpen's normal rejoin issues the
2855
+ * `session_load` and its `message_history` replaces the cached messages.
2856
+ *
2857
+ * A no-op unless the client holds nothing that could be clobbered: no active
2858
+ * session, no load in flight, not connected. The painted session is
2859
+ * `resyncing` (sending blocked) and NOT `historyAuthoritative`. `agentPending`,
2860
+ * `folderConflict`, `sudoPrompt` and `readOnly` stay at their defaults: they
2861
+ * are verdicts the server re-states on the rejoin. `pendingLoadFile` is NOT
2862
+ * set here (the rejoin sets it when it actually sends the load).
2863
+ *
2864
+ * Delivery-tagged user messages in the snapshot are dropped: undelivered
2865
+ * outbound messages are recovered only from localStorage on the history
2866
+ * reply (`loadPersistedPending`), so a cached copy would double-surface them.
2867
+ */
2868
+ public hydrateCachedSession(snapshot: HydrationSnapshot) {
2869
+ const s = get(this.stateStore);
2870
+ if (s.activeSessionFile || this.pendingLoadFile !== null || s.connected) return;
2871
+ const messages = snapshot.messages.filter(
2872
+ (m) => !(m.role === 'user' && m.delivery !== undefined),
2873
+ );
2874
+ this.hydratedFile = snapshot.sessionFile;
2875
+ this.stateStore.update((st: WhereverState) => ({
2876
+ ...st,
2877
+ session: snapshot.sessionFile,
2878
+ sessionId: snapshot.sessionId,
2879
+ activeSessionFile: snapshot.sessionFile,
2880
+ activeCwd: snapshot.cwd,
2881
+ activeModel: snapshot.model,
2882
+ messages,
2883
+ historyTotalCount: snapshot.historyTotalCount ?? messages.length,
2884
+ historyOffset: snapshot.historyOffset ?? 0,
2885
+ historyAuthoritative: false,
2886
+ resyncing: true,
2887
+ isStreaming: false,
2888
+ serverKey: snapshot.serverKey ?? serverKey(this.config),
2889
+ }));
2890
+ }
2891
+
2892
+ // The server refused the hydrated session's load: clear the cached view (the
2893
+ // session_error reducer already surfaced the error) and tell the listeners,
2894
+ // so the web evicts the record and drops the hash. Synthesized locally; it is
2895
+ // never a server frame.
2896
+ private rejectHydration() {
2897
+ const sessionId = get(this.stateStore).sessionId;
2898
+ this.hydratedFile = null;
2899
+ this.pendingLoadFile = null;
2900
+ this.stateStore.update((s: WhereverState) => ({
2901
+ ...s,
2902
+ messages: [],
2903
+ session: null,
2904
+ sessionId: null,
2905
+ activeSessionFile: null,
2906
+ activeCwd: null,
2907
+ activeModel: null,
2908
+ historyTotalCount: 0,
2909
+ historyOffset: 0,
2910
+ historyAuthoritative: false,
2911
+ serverKey: null,
2912
+ resyncing: false,
2913
+ }));
2914
+ if (!sessionId) return;
2915
+ const event = {type: 'hydration_rejected', sessionId};
2916
+ for (const listener of this.listeners) {
2917
+ try {
2918
+ listener(event);
2919
+ } catch (err) {
2920
+ console.error("Error in message listener:", err);
2921
+ }
2922
+ }
2923
+ }
2924
+
2396
2925
  public joinSession(sessionFile: string, cwd?: string, model?: string) {
2397
2926
  this.stateStore.update((s: WhereverState) => ({
2398
2927
  ...s,
@@ -2425,6 +2954,7 @@ export class WhereverClient {
2425
2954
  if (s.activeSessionFile === sessionFile && !s.loadingSession && !s.resyncing) {
2426
2955
  return;
2427
2956
  }
2957
+ this.abandonUnsentUploads();
2428
2958
  if (s.sessionId) {
2429
2959
  this.send({type: 'session_leave', sessionId: s.sessionId});
2430
2960
  }
@@ -2455,6 +2985,7 @@ export class WhereverClient {
2455
2985
  this.resumeSessionFile = null;
2456
2986
  this.resumeCwd = undefined;
2457
2987
  this.resumeModel = undefined;
2988
+ this.hydratedFile = null;
2458
2989
  // Switching supersedes any in-flight create; disarm its watchdog so it can't
2459
2990
  // later fire against the newly loaded session.
2460
2991
  this.clearCreateWatchdog();
@@ -2482,6 +3013,7 @@ export class WhereverClient {
2482
3013
  repoVisibility?: 'private' | 'public',
2483
3014
  cloneRemote?: boolean,
2484
3015
  ) {
3016
+ this.abandonUnsentUploads();
2485
3017
  this.stateStore.update((s: WhereverState) => ({
2486
3018
  ...s,
2487
3019
  folderConflict: null,
@@ -2497,6 +3029,7 @@ export class WhereverClient {
2497
3029
  // be rejected by a stale pendingLoadFile, and a late load reply for the old
2498
3030
  // target must not clobber the new session.
2499
3031
  this.pendingLoadFile = null;
3032
+ this.hydratedFile = null;
2500
3033
  this.send({
2501
3034
  type: 'session_new',
2502
3035
  cwd,
@@ -2512,6 +3045,7 @@ export class WhereverClient {
2512
3045
  }
2513
3046
 
2514
3047
  public leaveSession() {
3048
+ this.abandonUnsentUploads();
2515
3049
  const s = get(this.stateStore);
2516
3050
  // Leaving abandons any in-flight create too, so disarm its watchdog even when
2517
3051
  // there is no sessionId yet (a create that has not resolved).
@@ -2548,6 +3082,7 @@ export class WhereverClient {
2548
3082
  }));
2549
3083
  this.clearLoadWatchdog();
2550
3084
  this.pendingLoadFile = null;
3085
+ this.hydratedFile = null;
2551
3086
  this.resumeSessionFile = null;
2552
3087
  this.resumeCwd = undefined;
2553
3088
  this.resumeModel = undefined;
@@ -2734,20 +3269,473 @@ export class WhereverClient {
2734
3269
  };
2735
3270
  }
2736
3271
 
2737
- public uploadFileViaWebSocket(sessionId: string, filename: string, base64Data: string): Promise<{savedPath: string; filename: string}> {
3272
+ /**
3273
+ * Upload a file over the WebSocket. Resolves with the server's saved path;
3274
+ * rejects on failure (an `Error`, with `code: 'not_readable'` when the byte
3275
+ * source can no longer be read) or with "Upload cancelled" when
3276
+ * `options.signal` aborts. Progress (`{acked, size, state, error?}`) goes to
3277
+ * `options.onProgress` and to `uploadsStore`.
3278
+ *
3279
+ * The protocol is chosen when the upload is SENT, from that socket's
3280
+ * `connected.capabilities`: chunked (`upload.v1`) when advertised, else the
3281
+ * legacy base64 `file_upload` frame (see PendingUpload). The legacy path
3282
+ * refuses files over 72 MiB from `source.size`, before reading anything.
3283
+ */
3284
+ public uploadFileViaWebSocket(
3285
+ sessionId: string,
3286
+ filename: string,
3287
+ source: UploadByteSource,
3288
+ options?: UploadOptions,
3289
+ ): Promise<{savedPath: string; filename: string}> {
2738
3290
  return new Promise((resolve, reject) => {
2739
- const uploadId = this.generateId();
2740
- this.pendingUploads.set(uploadId, {resolve, reject});
2741
- this.send({
2742
- type: 'file_upload',
3291
+ const signal = options?.signal;
3292
+ if (signal?.aborted) {
3293
+ options?.onProgress?.({acked: 0, size: source.size, state: 'aborted'});
3294
+ reject(new Error('Upload cancelled'));
3295
+ return;
3296
+ }
3297
+ const uploadId = generateUploadId();
3298
+ const upload: PendingUpload = {
2743
3299
  uploadId,
2744
3300
  sessionId,
2745
3301
  filename,
2746
- data: base64Data
2747
- });
3302
+ mime: options?.mime || undefined,
3303
+ source,
3304
+ onProgress: options?.onProgress,
3305
+ resolve,
3306
+ reject,
3307
+ timer: null,
3308
+ sentOn: null,
3309
+ protocol: null,
3310
+ state: 'queued',
3311
+ acked: 0,
3312
+ frame: null,
3313
+ preparing: false,
3314
+ sends: 0,
3315
+ begun: false,
3316
+ awaitingBegin: false,
3317
+ nextOffset: 0,
3318
+ inFlight: [],
3319
+ realigning: false,
3320
+ finishing: false,
3321
+ reading: false,
3322
+ readGen: 0,
3323
+ rate: null,
3324
+ lastAckAt: 0,
3325
+ };
3326
+ this.pendingUploads.set(uploadId, upload);
3327
+ this.reportUpload(upload);
3328
+ // Cancelling (e.g. the chip was removed) settles the promise and drops
3329
+ // the upload so it is not re-sent on the next reconnect. A chunked upload
3330
+ // the server knows about is told to drop its partial; a legacy frame
3331
+ // already handed to the socket cannot be recalled.
3332
+ signal?.addEventListener('abort', () => this.abortUpload(uploadId), {once: true});
3333
+ // Sent now when the socket is OPEN, its capabilities are known and it is
3334
+ // not mid-rejoin. Otherwise the upload waits in pendingUploads and is
3335
+ // sent once those hold.
3336
+ if (!this.trySendUpload(uploadId)) this.ensureUploadTimer(uploadId);
3337
+ });
3338
+ }
3339
+
3340
+ // Number of uploads still waiting for a server reply (sent or parked).
3341
+ public pendingUploadCount(): number {
3342
+ return this.pendingUploads.size;
3343
+ }
3344
+
3345
+ /** Drop a SETTLED upload's entry from uploadsStore (in-flight ones stay). */
3346
+ public forgetUpload(uploadId: string) {
3347
+ if (this.pendingUploads.has(uploadId)) return;
3348
+ this.uploadsStore.update((all) => {
3349
+ if (!(uploadId in all)) return all;
3350
+ const next = {...all};
3351
+ delete next[uploadId];
3352
+ return next;
2748
3353
  });
2749
3354
  }
2750
3355
 
3356
+ // Hand the upload to the current socket if it can go now. True when it is on
3357
+ // the wire (or settled: nothing left to wait for), false when it waits.
3358
+ private trySendUpload(uploadId: string): boolean {
3359
+ const upload = this.pendingUploads.get(uploadId);
3360
+ if (!upload || this.uploadsHeldForRejoin) return false;
3361
+ if (!this.ws || this.ws.readyState !== 1 /* OPEN */) return false;
3362
+ // Capabilities unknown: HOLD (see socketCapabilities).
3363
+ if (this.socketCapabilities === null) return false;
3364
+ const chunked = this.socketCapabilities.includes(UPLOAD_CAPABILITY);
3365
+ if (upload.protocol === null) upload.protocol = chunked ? 'chunked' : 'legacy';
3366
+ if (upload.protocol === 'chunked') {
3367
+ if (!chunked) {
3368
+ this.failUpload(uploadId, 'The server no longer supports resumable uploads, retry');
3369
+ return true;
3370
+ }
3371
+ return this.beginChunkedUpload(upload);
3372
+ }
3373
+ return this.sendLegacyUpload(upload);
3374
+ }
3375
+
3376
+ private sendLegacyUpload(upload: PendingUpload): boolean {
3377
+ if (upload.sends >= WhereverClient.MAX_UPLOAD_SENDS) {
3378
+ // Every previous attempt lost its socket mid-transfer: stop retrying.
3379
+ this.failUpload(
3380
+ upload.uploadId,
3381
+ 'Upload failed: the connection dropped during the transfer each time (the file may be too large or the connection too slow)',
3382
+ );
3383
+ return true;
3384
+ }
3385
+ if (!upload.frame) {
3386
+ // Checked from the size BEFORE reading, so a huge video is never loaded
3387
+ // and encoded just to be refused (and never crashes the tab).
3388
+ if (upload.source.size > WhereverClient.MAX_LEGACY_UPLOAD_BYTES) {
3389
+ this.failUpload(upload.uploadId, 'File too large to upload over the WebSocket (max 72 MB)');
3390
+ return true;
3391
+ }
3392
+ if (!upload.preparing) {
3393
+ upload.preparing = true;
3394
+ this.prepareLegacyFrame(upload);
3395
+ }
3396
+ return false;
3397
+ }
3398
+ if (!this.send(upload.frame)) return false;
3399
+ upload.sends++;
3400
+ upload.sentOn = this.ws;
3401
+ // On the wire: stop the waiting clock (transmission time is not bounded).
3402
+ this.stopUploadTimer(upload);
3403
+ this.reportUpload(upload, 'sending');
3404
+ return true;
3405
+ }
3406
+
3407
+ // Read and base64-encode the whole file once, then send it if still wanted.
3408
+ private prepareLegacyFrame(upload: PendingUpload) {
3409
+ this.readLegacyBase64(upload.source).then(
3410
+ (data) => {
3411
+ if (this.pendingUploads.get(upload.uploadId) !== upload) return;
3412
+ upload.preparing = false;
3413
+ upload.frame = {
3414
+ type: 'file_upload',
3415
+ uploadId: upload.uploadId,
3416
+ sessionId: upload.sessionId,
3417
+ filename: upload.filename,
3418
+ data,
3419
+ };
3420
+ if (!this.trySendUpload(upload.uploadId)) this.ensureUploadTimer(upload.uploadId);
3421
+ },
3422
+ (err) => {
3423
+ if (this.pendingUploads.get(upload.uploadId) !== upload) return;
3424
+ const e = err instanceof UploadReadError ? err : uploadReadError(err);
3425
+ this.failUpload(upload.uploadId, e.message, e.code);
3426
+ },
3427
+ );
3428
+ }
3429
+
3430
+ // base64 over reads of LEGACY_READ_BYTES (a multiple of 3, so no padding in
3431
+ // the middle), platform-neutral (btoa). MAX_UPLOAD_BASE64_CHARS is a
3432
+ // backstop for a source that yields more than its size claimed.
3433
+ private async readLegacyBase64(source: UploadByteSource): Promise<string> {
3434
+ const parts: string[] = [];
3435
+ let chars = 0;
3436
+ for (let offset = 0; offset < source.size; offset += LEGACY_READ_BYTES) {
3437
+ const length = Math.min(LEGACY_READ_BYTES, source.size - offset);
3438
+ let bytes: Uint8Array;
3439
+ try {
3440
+ bytes = await source.read(offset, length);
3441
+ } catch (err) {
3442
+ throw uploadReadError(err);
3443
+ }
3444
+ chars += 4 * Math.ceil(bytes.length / 3);
3445
+ if (chars > WhereverClient.MAX_UPLOAD_BASE64_CHARS) {
3446
+ throw new UploadReadError('File too large to upload over the WebSocket (max 72 MB)');
3447
+ }
3448
+ if (bytes.length !== length) throw shortReadError();
3449
+ parts.push(btoa(bytesToBinaryString(bytes)));
3450
+ }
3451
+ return parts.join('');
3452
+ }
3453
+
3454
+ // (Re)start a chunked upload on the current socket: the begin's answer says
3455
+ // where to continue (or that it is already done).
3456
+ private beginChunkedUpload(upload: PendingUpload): boolean {
3457
+ const sent = this.send({
3458
+ type: 'upload_begin',
3459
+ uploadId: upload.uploadId,
3460
+ sessionId: upload.sessionId,
3461
+ filename: upload.filename,
3462
+ size: upload.source.size,
3463
+ ...(upload.mime ? {mime: upload.mime} : {}),
3464
+ });
3465
+ if (!sent) return false;
3466
+ upload.begun = true;
3467
+ upload.sentOn = this.ws;
3468
+ upload.awaitingBegin = true;
3469
+ upload.inFlight = [];
3470
+ upload.realigning = false;
3471
+ upload.finishing = false;
3472
+ upload.readGen++;
3473
+ // Transmitting: the waiting clock stops (it bounds waiting, not sending).
3474
+ this.stopUploadTimer(upload);
3475
+ this.reportUpload(upload, 'sending');
3476
+ return true;
3477
+ }
3478
+
3479
+ // `upload_offset`: the server's offset for a chunked upload, answering a begin
3480
+ // or a chunk. Progress is ONLY ever this value, never what was sent.
3481
+ private handleUploadOffset(msg: any) {
3482
+ const upload = this.pendingUploads.get(msg.uploadId);
3483
+ if (!upload || upload.protocol !== 'chunked' || !this.isUploadOnWire(upload)) return;
3484
+ if (msg.done) {
3485
+ this.completeUpload(upload.uploadId, {savedPath: msg.savedPath, filename: upload.filename});
3486
+ return;
3487
+ }
3488
+ const offset = msg.offset;
3489
+ const size = upload.source.size;
3490
+ if (!Number.isSafeInteger(offset) || offset < 0 || offset > size) return;
3491
+ const now = Date.now();
3492
+ if (upload.awaitingBegin) {
3493
+ upload.awaitingBegin = false;
3494
+ upload.nextOffset = offset;
3495
+ upload.lastAckAt = now;
3496
+ } else {
3497
+ const chunk = upload.inFlight.shift();
3498
+ if (!chunk) return; // nothing of ours is awaiting an answer
3499
+ if (!upload.realigning && offset === chunk.offset + chunk.length) {
3500
+ // Time this chunk from when it could start being serviced: its send, or
3501
+ // the previous ack if it was queued behind that one.
3502
+ const elapsed = Math.max(1, now - Math.max(chunk.sentAt, upload.lastAckAt));
3503
+ const sample = chunk.length / elapsed;
3504
+ upload.rate =
3505
+ upload.rate === null ? sample : upload.rate * (1 - UPLOAD_RATE_ALPHA) + sample * UPLOAD_RATE_ALPHA;
3506
+ upload.lastAckAt = now;
3507
+ } else if (!upload.realigning) {
3508
+ // Out of step with the server: discard any read meant for the old
3509
+ // position and wait for the rest of the in-flight acks.
3510
+ upload.realigning = true;
3511
+ upload.readGen++;
3512
+ }
3513
+ if (upload.realigning && upload.inFlight.length === 0) {
3514
+ upload.realigning = false;
3515
+ upload.nextOffset = offset;
3516
+ upload.lastAckAt = now;
3517
+ }
3518
+ }
3519
+ upload.acked = offset;
3520
+ this.reportUpload(upload);
3521
+ this.pumpUpload(upload);
3522
+ }
3523
+
3524
+ private uploadWindow(upload: PendingUpload): number {
3525
+ if (upload.rate === null) return UPLOAD_WINDOW_MIN;
3526
+ const bytes = upload.rate * 1000 * UPLOAD_WINDOW_SECONDS;
3527
+ return Math.min(UPLOAD_WINDOW_MAX, Math.max(UPLOAD_WINDOW_MIN, Math.floor(bytes)));
3528
+ }
3529
+
3530
+ // Send the next chunk if the window allows, or finish once every byte is
3531
+ // acked. One source read at a time; each completed send pumps again.
3532
+ private pumpUpload(upload: PendingUpload) {
3533
+ if (this.pendingUploads.get(upload.uploadId) !== upload) return;
3534
+ if (upload.reading || upload.awaitingBegin || upload.realigning || upload.finishing) return;
3535
+ if (!this.isUploadOnWire(upload)) return;
3536
+ const size = upload.source.size;
3537
+ if (upload.acked === size && upload.inFlight.length === 0) {
3538
+ if (!this.send({type: 'upload_finish', uploadId: upload.uploadId, sessionId: upload.sessionId})) return;
3539
+ upload.finishing = true;
3540
+ this.reportUpload(upload, 'finishing');
3541
+ return;
3542
+ }
3543
+ if (upload.nextOffset >= size) return;
3544
+ const window = this.uploadWindow(upload);
3545
+ const length = Math.min(window, UPLOAD_CHUNK_MAX, size - upload.nextOffset);
3546
+ const inFlightBytes = upload.inFlight.reduce((n, c) => n + c.length, 0);
3547
+ if (inFlightBytes + length > window) return;
3548
+ const offset = upload.nextOffset;
3549
+ const gen = upload.readGen;
3550
+ const socket = this.ws;
3551
+ upload.reading = true;
3552
+ Promise.resolve()
3553
+ .then(() => upload.source.read(offset, length))
3554
+ .then(
3555
+ (bytes) => {
3556
+ if (this.pendingUploads.get(upload.uploadId) !== upload) return;
3557
+ upload.reading = false;
3558
+ // The socket or the alignment changed while reading: drop the bytes.
3559
+ if (gen !== upload.readGen || socket !== this.ws || !this.isUploadOnWire(upload)) {
3560
+ this.pumpUpload(upload);
3561
+ return;
3562
+ }
3563
+ if (bytes.length !== length) {
3564
+ const e = shortReadError();
3565
+ this.failUpload(upload.uploadId, e.message, e.code);
3566
+ return;
3567
+ }
3568
+ // A socket that refuses the frame is closing; its close handler
3569
+ // pauses the upload.
3570
+ if (!this.sendBinary(encodeChunkFrame(upload.uploadId, offset, bytes))) return;
3571
+ upload.inFlight.push({offset, length, sentAt: Date.now()});
3572
+ upload.nextOffset = offset + length;
3573
+ this.pumpUpload(upload);
3574
+ },
3575
+ (err) => {
3576
+ if (this.pendingUploads.get(upload.uploadId) !== upload) return;
3577
+ const e = uploadReadError(err);
3578
+ this.failUpload(upload.uploadId, e.message, e.code);
3579
+ },
3580
+ );
3581
+ }
3582
+
3583
+ private sendBinary(bytes: Uint8Array): boolean {
3584
+ if (this.ws && this.ws.readyState === 1 /* OPEN */) {
3585
+ try {
3586
+ this.ws.send(bytes);
3587
+ return true;
3588
+ } catch {
3589
+ return false;
3590
+ }
3591
+ }
3592
+ return false;
3593
+ }
3594
+
3595
+ // Record (and announce) an upload's progress. `state` defaults to the current.
3596
+ private reportUpload(upload: PendingUpload, state?: UploadState, error?: {message: string; code?: 'not_readable'}) {
3597
+ if (state) upload.state = state;
3598
+ const progress: UploadProgress = {
3599
+ acked: upload.acked,
3600
+ size: upload.source.size,
3601
+ state: upload.state,
3602
+ ...(error ? {error} : {}),
3603
+ };
3604
+ this.uploadsStore.update((all) => ({...all, [upload.uploadId]: progress}));
3605
+ if (upload.onProgress) {
3606
+ try {
3607
+ upload.onProgress({...progress});
3608
+ } catch (err) {
3609
+ console.error('Upload onProgress failed:', err);
3610
+ }
3611
+ }
3612
+ }
3613
+
3614
+ private completeUpload(uploadId: string, result: {savedPath: string; filename: string}) {
3615
+ const upload = this.takePendingUpload(uploadId);
3616
+ if (!upload) return;
3617
+ upload.acked = upload.source.size;
3618
+ this.reportUpload(upload, 'done');
3619
+ upload.resolve(result);
3620
+ }
3621
+
3622
+ private failUpload(uploadId: string, message: string, code?: 'not_readable') {
3623
+ const upload = this.takePendingUpload(uploadId);
3624
+ if (!upload) return;
3625
+ const err: Error & {code?: string} = new Error(message);
3626
+ if (code) err.code = code;
3627
+ this.reportUpload(upload, 'failed', code ? {message, code} : {message});
3628
+ upload.reject(err);
3629
+ }
3630
+
3631
+ private abortUpload(uploadId: string) {
3632
+ const upload = this.takePendingUpload(uploadId);
3633
+ if (!upload) return;
3634
+ // Best effort: with no open socket the partial is left to the server's GC.
3635
+ if (upload.protocol === 'chunked' && upload.begun) {
3636
+ this.send({type: 'upload_abort', uploadId, sessionId: upload.sessionId});
3637
+ }
3638
+ this.reportUpload(upload, 'aborted');
3639
+ upload.reject(new Error('Upload cancelled'));
3640
+ }
3641
+
3642
+ private isUploadOnWire(pending: {sentOn: any}): boolean {
3643
+ return pending.sentOn !== null && pending.sentOn === this.ws;
3644
+ }
3645
+
3646
+ // The socket carrying uploads went away (by close, suspend, or the liveness
3647
+ // teardown, the latter two bypassing onClose). Every upload is waiting again:
3648
+ // forget where it was sent, pause it, and restart its waiting clock, so no
3649
+ // upload can be left without a timer. A chunked upload forgets its in-flight
3650
+ // chunks: the next begin tells it what the server really has.
3651
+ private uploadsLostSocket() {
3652
+ for (const [id, upload] of this.pendingUploads) {
3653
+ const wasOnWire = upload.sentOn !== null;
3654
+ upload.sentOn = null;
3655
+ if (upload.protocol === 'chunked') {
3656
+ upload.awaitingBegin = false;
3657
+ upload.inFlight = [];
3658
+ upload.realigning = false;
3659
+ upload.finishing = false;
3660
+ upload.readGen++;
3661
+ }
3662
+ if (wasOnWire && upload.state !== 'paused') this.reportUpload(upload, 'paused');
3663
+ // Arm only a clock that is not already running. Re-arming on every loss
3664
+ // restarted the deadline on each failed reconnect attempt (at most 15 s
3665
+ // apart), so an upload against an unreachable server waited forever.
3666
+ this.ensureUploadTimer(id);
3667
+ }
3668
+ }
3669
+
3670
+ // Fail uploads that have not reached the current socket (parked or held),
3671
+ // optionally sparing those aimed at `keepSessionId`.
3672
+ private failUnsentUploads(reason: string, keepSessionId?: string) {
3673
+ for (const [id, upload] of [...this.pendingUploads]) {
3674
+ if (this.isUploadOnWire(upload)) continue;
3675
+ if (keepSessionId && upload.sessionId === keepSessionId) continue;
3676
+ this.failUpload(id, reason);
3677
+ }
3678
+ }
3679
+
3680
+ private failHeldUploads(reason: string) {
3681
+ if (!this.uploadsHeldForRejoin) return;
3682
+ this.uploadsHeldForRejoin = false;
3683
+ this.failUnsentUploads(reason);
3684
+ }
3685
+
3686
+ // Switching / creating / leaving a session: an upload not yet on the wire
3687
+ // would otherwise be released by the NEXT session's session_created and be
3688
+ // gated by the wrong session's verdict. One already on the wire is left to
3689
+ // its reply (the server answers on this socket regardless of attachment).
3690
+ private abandonUnsentUploads() {
3691
+ this.uploadsHeldForRejoin = false;
3692
+ this.failUnsentUploads('The session changed before the upload could be sent');
3693
+ }
3694
+
3695
+ // Start the waiting clock unless one is already running (keeps the deadline).
3696
+ private ensureUploadTimer(uploadId: string) {
3697
+ const pending = this.pendingUploads.get(uploadId);
3698
+ if (pending && !pending.timer) this.armUploadTimer(uploadId);
3699
+ }
3700
+
3701
+ private stopUploadTimer(upload: PendingUpload) {
3702
+ if (upload.timer) clearTimeout(upload.timer);
3703
+ upload.timer = null;
3704
+ }
3705
+
3706
+ private armUploadTimer(uploadId: string) {
3707
+ const pending = this.pendingUploads.get(uploadId);
3708
+ if (!pending || typeof setTimeout !== 'function') return;
3709
+ if (pending.timer) clearTimeout(pending.timer);
3710
+ pending.timer = setTimeout(() => {
3711
+ this.failUpload(uploadId, 'Upload timed out (no connection to the server)');
3712
+ }, WhereverClient.UPLOAD_TIMEOUT_MS);
3713
+ if (pending.timer && typeof (pending.timer as any).unref === 'function') {
3714
+ (pending.timer as any).unref();
3715
+ }
3716
+ }
3717
+
3718
+ private takePendingUpload(uploadId: string) {
3719
+ const pending = this.pendingUploads.get(uploadId);
3720
+ if (!pending) return undefined;
3721
+ this.pendingUploads.delete(uploadId);
3722
+ if (pending.timer) clearTimeout(pending.timer);
3723
+ return pending;
3724
+ }
3725
+
3726
+ private resendPendingUploads() {
3727
+ for (const [id, pending] of [...this.pendingUploads]) {
3728
+ if (this.isUploadOnWire(pending)) continue;
3729
+ if (!this.trySendUpload(id)) this.ensureUploadTimer(id);
3730
+ }
3731
+ }
3732
+
3733
+ private rejectPendingUploads(reason: string) {
3734
+ for (const id of [...this.pendingUploads.keys()]) {
3735
+ this.failUpload(id, reason);
3736
+ }
3737
+ }
3738
+
2751
3739
  private generateId() {
2752
3740
  return Math.random().toString(36).substring(2) + Date.now().toString(36);
2753
3741
  }