@g9tm/app-diagnostic 0.2.0 → 0.2.2

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.
@@ -1,175 +1,175 @@
1
- // The resumable bundle upload over the device hub (G9AppDiagnostic.Maui DiagnosticBundleUploader): BackupUploadInit →
2
- // one or more BackupUploadStream calls → BackupUploadComplete (the gateway re-hashes the blob against the SHA-256 the
3
- // device announced).
4
- //
5
- // SEGMENTED on purpose: the gateway sends no acknowledgement while a stream runs, and a native WebSocket under SignalR
6
- // (OkHttp on Android) CLOSES the socket once 16 MiB are queued. So every stream call carries at most 4 MiB and waits for
7
- // its ack before the next one — in-flight data stays bounded whatever the bundle's size. The gateway starts every stream
8
- // at the bytes it already holds, so a segment boundary, a dropped connection and an app restart all resume the same way:
9
- // from `receivedOffset`.
10
- import type { DiagnosticFiles } from '../host.ts';
11
- import { DeviceHubMethods, TRANSFER } from '../wire.ts';
12
- import type { BackupUploadChunksAck, BackupUploadCompleteResponse, BackupUploadInitRequest, BackupUploadInitResponse } from './models.ts';
13
-
14
- /** What the uploader needs of the hub client. */
15
- export interface HubInvoker {
16
- invoke<T = unknown>(method: string, ...args: unknown[]): Promise<T>;
17
- }
18
-
19
- /**
20
- * A client-to-server stream SignalR accepts as an argument: anything with `subscribe(observer)` (the JS client checks
21
- * for that, not for its own class), so the package needs no SignalR import.
22
- */
23
- export class StreamSubject<T> {
24
- private observer: { next(v: T): void; complete(): void; error(e: unknown): void } | null = null;
25
- private readonly buffer: T[] = [];
26
- private done = false;
27
-
28
- subscribe(observer: { next(v: T): void; complete(): void; error(e: unknown): void }): { dispose(): void } {
29
- this.observer = observer;
30
- for (const v of this.buffer.splice(0)) observer.next(v);
31
- if (this.done) observer.complete();
32
- return { dispose: () => (this.observer = null) };
33
- }
34
-
35
- next(value: T): void {
36
- if (this.observer) this.observer.next(value);
37
- else this.buffer.push(value);
38
- }
39
-
40
- complete(): void {
41
- this.done = true;
42
- this.observer?.complete();
43
- }
44
-
45
- error(e: unknown): void {
46
- this.done = true;
47
- this.observer?.error(e);
48
- }
49
- }
50
-
51
- export interface BundleUploadRequest {
52
- readonly clientId: string;
53
- readonly path: string;
54
- readonly filename: string;
55
- /** BackupSource: 0 an operator's backup, 1 the user's full report. */
56
- readonly source: number;
57
- readonly note?: string | null;
58
- readonly isPasswordProtected: boolean;
59
- readonly isSensitive: boolean;
60
- readonly include: {
61
- readonly sqlite: boolean;
62
- readonly logs: boolean;
63
- readonly attachments: boolean;
64
- readonly geoDatabase?: boolean;
65
- readonly preferences?: boolean;
66
- readonly secureStorage?: boolean;
67
- };
68
- /** A token from an earlier, interrupted run of the SAME file. */
69
- readonly resumeToken?: string | null;
70
- }
71
-
72
- export type BundleUploadOutcome =
73
- | { readonly ok: true; readonly token: string; readonly bytes: number }
74
- | { readonly ok: false; readonly error: string; readonly token: string | null; readonly cancelledByOperator: boolean; readonly retryable: boolean };
75
-
76
- export interface BundleUploadHooks {
77
- readonly onProgress?: (sent: number, total: number) => void;
78
- /** The token is known (persist it: a later run resumes with it). */
79
- readonly onToken?: (token: string) => void;
80
- readonly signal?: { readonly aborted: boolean };
81
- readonly sleep?: (ms: number) => Promise<void>;
82
- /** Bytes per stream call (tests); default 4 MiB. */
83
- readonly segmentBytes?: number;
84
- }
85
-
86
- const defaultSleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
87
-
88
- export async function uploadBundle(hub: HubInvoker, files: DiagnosticFiles, request: BundleUploadRequest, hooks: BundleUploadHooks = {}): Promise<BundleUploadOutcome> {
89
- const sleep = hooks.sleep ?? defaultSleep;
90
- const segment = hooks.segmentBytes ?? TRANSFER.segmentBytes;
91
- const total = await files.size(request.path);
92
- const sha256Hex = await files.sha256(request.path);
93
- const fail = (error: string, token: string | null, extra: { cancelledByOperator?: boolean; retryable?: boolean } = {}): BundleUploadOutcome => ({
94
- ok: false,
95
- error,
96
- token,
97
- cancelledByOperator: extra.cancelledByOperator ?? false,
98
- retryable: extra.retryable ?? false,
99
- });
100
-
101
- let resumeToken = request.resumeToken ?? null;
102
- // Two independent one-time recoveries: a resume token the gateway forgot, and a copy it could not verify.
103
- let forgotToken = false;
104
- let restarted = false;
105
- for (;;) {
106
- const init: BackupUploadInitRequest = {
107
- clientId: request.clientId,
108
- sha256Hex,
109
- sizeBytes: total,
110
- isPasswordProtected: request.isPasswordProtected,
111
- resumeToken,
112
- filename: request.filename,
113
- isSensitive: request.isSensitive,
114
- note: request.note ?? null,
115
- includeSqlite: request.include.sqlite,
116
- includeGeoDatabase: request.include.geoDatabase ?? false,
117
- includeAttachments: request.include.attachments,
118
- includeLogs: request.include.logs,
119
- includePreferences: request.include.preferences ?? false,
120
- includeSecureStorage: request.include.secureStorage ?? false,
121
- source: request.source,
122
- };
123
- const answer = await hub.invoke<BackupUploadInitResponse>(DeviceHubMethods.backupUploadInit, init);
124
- if (answer.unknownResumeToken && resumeToken && !forgotToken) {
125
- forgotToken = true;
126
- resumeToken = null; // the gateway forgot it (expired): start over once
127
- continue;
128
- }
129
- if (!answer.accepted) return fail(answer.rejectionReason ?? 'rejected', null, { cancelledByOperator: answer.cancelledByOperator === true });
130
- const token = answer.token;
131
- hooks.onToken?.(token);
132
-
133
- let offset = Math.max(0, Math.min(answer.resumeFromOffset, total));
134
- hooks.onProgress?.(offset, total);
135
- let busy = 0;
136
- while (offset < total) {
137
- if (hooks.signal?.aborted) return fail('cancelled', token);
138
- const end = Math.min(total, offset + segment);
139
- const subject = new StreamSubject<string>();
140
- const ackPromise = hub.invoke<BackupUploadChunksAck>(DeviceHubMethods.backupUploadStream, token, subject);
141
- try {
142
- for (let pos = offset; pos < end; pos += TRANSFER.chunkBytes) {
143
- if (hooks.signal?.aborted) break;
144
- subject.next(await files.readChunk(request.path, pos, Math.min(TRANSFER.chunkBytes, end - pos)));
145
- hooks.onProgress?.(Math.min(end, pos + TRANSFER.chunkBytes), total);
146
- }
147
- } finally {
148
- subject.complete();
149
- }
150
- const ack = await ackPromise;
151
- if (!ack.accepted) {
152
- if (ack.cancelledByOperator) return fail(ack.rejectionReason ?? 'cancelled by the operator', token, { cancelledByOperator: true });
153
- if (ack.streamBusy && busy++ < TRANSFER.busyRetries) {
154
- await sleep(TRANSFER.busyDelayMs);
155
- offset = ack.receivedOffset;
156
- continue;
157
- }
158
- return fail(ack.rejectionReason ?? 'stream rejected', token, { retryable: true });
159
- }
160
- busy = 0;
161
- if (ack.receivedOffset <= offset && end > offset) return fail('the gateway did not take the segment', token, { retryable: true });
162
- offset = ack.receivedOffset;
163
- hooks.onProgress?.(offset, total);
164
- }
165
-
166
- const complete = await hub.invoke<BackupUploadCompleteResponse>(DeviceHubMethods.backupUploadComplete, { token, sha256Hex });
167
- if (complete.accepted) return { ok: true, token, bytes: complete.finalSizeBytes || total };
168
- if (complete.restartFromZero && !restarted) {
169
- restarted = true;
170
- resumeToken = null; // the gateway's copy is unusable: one fresh run
171
- continue;
172
- }
173
- return fail(complete.rejectionReason ?? 'the gateway refused the archive', token, { retryable: true });
174
- }
175
- }
1
+ // The resumable bundle upload over the device hub (G9AppDiagnostic.Maui DiagnosticBundleUploader): BackupUploadInit →
2
+ // one or more BackupUploadStream calls → BackupUploadComplete (the gateway re-hashes the blob against the SHA-256 the
3
+ // device announced).
4
+ //
5
+ // SEGMENTED on purpose: the gateway sends no acknowledgement while a stream runs, and a native WebSocket under SignalR
6
+ // (OkHttp on Android) CLOSES the socket once 16 MiB are queued. So every stream call carries at most 4 MiB and waits for
7
+ // its ack before the next one — in-flight data stays bounded whatever the bundle's size. The gateway starts every stream
8
+ // at the bytes it already holds, so a segment boundary, a dropped connection and an app restart all resume the same way:
9
+ // from `receivedOffset`.
10
+ import type { DiagnosticFiles } from '../host.ts';
11
+ import { DeviceHubMethods, TRANSFER } from '../wire.ts';
12
+ import type { BackupUploadChunksAck, BackupUploadCompleteResponse, BackupUploadInitRequest, BackupUploadInitResponse } from './models.ts';
13
+
14
+ /** What the uploader needs of the hub client. */
15
+ export interface HubInvoker {
16
+ invoke<T = unknown>(method: string, ...args: unknown[]): Promise<T>;
17
+ }
18
+
19
+ /**
20
+ * A client-to-server stream SignalR accepts as an argument: anything with `subscribe(observer)` (the JS client checks
21
+ * for that, not for its own class), so the package needs no SignalR import.
22
+ */
23
+ export class StreamSubject<T> {
24
+ private observer: { next(v: T): void; complete(): void; error(e: unknown): void } | null = null;
25
+ private readonly buffer: T[] = [];
26
+ private done = false;
27
+
28
+ subscribe(observer: { next(v: T): void; complete(): void; error(e: unknown): void }): { dispose(): void } {
29
+ this.observer = observer;
30
+ for (const v of this.buffer.splice(0)) observer.next(v);
31
+ if (this.done) observer.complete();
32
+ return { dispose: () => (this.observer = null) };
33
+ }
34
+
35
+ next(value: T): void {
36
+ if (this.observer) this.observer.next(value);
37
+ else this.buffer.push(value);
38
+ }
39
+
40
+ complete(): void {
41
+ this.done = true;
42
+ this.observer?.complete();
43
+ }
44
+
45
+ error(e: unknown): void {
46
+ this.done = true;
47
+ this.observer?.error(e);
48
+ }
49
+ }
50
+
51
+ export interface BundleUploadRequest {
52
+ readonly clientId: string;
53
+ readonly path: string;
54
+ readonly filename: string;
55
+ /** BackupSource: 0 an operator's backup, 1 the user's full report. */
56
+ readonly source: number;
57
+ readonly note?: string | null;
58
+ readonly isPasswordProtected: boolean;
59
+ readonly isSensitive: boolean;
60
+ readonly include: {
61
+ readonly sqlite: boolean;
62
+ readonly logs: boolean;
63
+ readonly attachments: boolean;
64
+ readonly geoDatabase?: boolean;
65
+ readonly preferences?: boolean;
66
+ readonly secureStorage?: boolean;
67
+ };
68
+ /** A token from an earlier, interrupted run of the SAME file. */
69
+ readonly resumeToken?: string | null;
70
+ }
71
+
72
+ export type BundleUploadOutcome =
73
+ | { readonly ok: true; readonly token: string; readonly bytes: number }
74
+ | { readonly ok: false; readonly error: string; readonly token: string | null; readonly cancelledByOperator: boolean; readonly retryable: boolean };
75
+
76
+ export interface BundleUploadHooks {
77
+ readonly onProgress?: (sent: number, total: number) => void;
78
+ /** The token is known (persist it: a later run resumes with it). */
79
+ readonly onToken?: (token: string) => void;
80
+ readonly signal?: { readonly aborted: boolean };
81
+ readonly sleep?: (ms: number) => Promise<void>;
82
+ /** Bytes per stream call (tests); default 4 MiB. */
83
+ readonly segmentBytes?: number;
84
+ }
85
+
86
+ const defaultSleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
87
+
88
+ export async function uploadBundle(hub: HubInvoker, files: DiagnosticFiles, request: BundleUploadRequest, hooks: BundleUploadHooks = {}): Promise<BundleUploadOutcome> {
89
+ const sleep = hooks.sleep ?? defaultSleep;
90
+ const segment = hooks.segmentBytes ?? TRANSFER.segmentBytes;
91
+ const total = await files.size(request.path);
92
+ const sha256Hex = await files.sha256(request.path);
93
+ const fail = (error: string, token: string | null, extra: { cancelledByOperator?: boolean; retryable?: boolean } = {}): BundleUploadOutcome => ({
94
+ ok: false,
95
+ error,
96
+ token,
97
+ cancelledByOperator: extra.cancelledByOperator ?? false,
98
+ retryable: extra.retryable ?? false,
99
+ });
100
+
101
+ let resumeToken = request.resumeToken ?? null;
102
+ // Two independent one-time recoveries: a resume token the gateway forgot, and a copy it could not verify.
103
+ let forgotToken = false;
104
+ let restarted = false;
105
+ for (;;) {
106
+ const init: BackupUploadInitRequest = {
107
+ clientId: request.clientId,
108
+ sha256Hex,
109
+ sizeBytes: total,
110
+ isPasswordProtected: request.isPasswordProtected,
111
+ resumeToken,
112
+ filename: request.filename,
113
+ isSensitive: request.isSensitive,
114
+ note: request.note ?? null,
115
+ includeSqlite: request.include.sqlite,
116
+ includeGeoDatabase: request.include.geoDatabase ?? false,
117
+ includeAttachments: request.include.attachments,
118
+ includeLogs: request.include.logs,
119
+ includePreferences: request.include.preferences ?? false,
120
+ includeSecureStorage: request.include.secureStorage ?? false,
121
+ source: request.source,
122
+ };
123
+ const answer = await hub.invoke<BackupUploadInitResponse>(DeviceHubMethods.backupUploadInit, init);
124
+ if (answer.unknownResumeToken && resumeToken && !forgotToken) {
125
+ forgotToken = true;
126
+ resumeToken = null; // the gateway forgot it (expired): start over once
127
+ continue;
128
+ }
129
+ if (!answer.accepted) return fail(answer.rejectionReason ?? 'rejected', null, { cancelledByOperator: answer.cancelledByOperator === true });
130
+ const token = answer.token;
131
+ hooks.onToken?.(token);
132
+
133
+ let offset = Math.max(0, Math.min(answer.resumeFromOffset, total));
134
+ hooks.onProgress?.(offset, total);
135
+ let busy = 0;
136
+ while (offset < total) {
137
+ if (hooks.signal?.aborted) return fail('cancelled', token);
138
+ const end = Math.min(total, offset + segment);
139
+ const subject = new StreamSubject<string>();
140
+ const ackPromise = hub.invoke<BackupUploadChunksAck>(DeviceHubMethods.backupUploadStream, token, subject);
141
+ try {
142
+ for (let pos = offset; pos < end; pos += TRANSFER.chunkBytes) {
143
+ if (hooks.signal?.aborted) break;
144
+ subject.next(await files.readChunk(request.path, pos, Math.min(TRANSFER.chunkBytes, end - pos)));
145
+ hooks.onProgress?.(Math.min(end, pos + TRANSFER.chunkBytes), total);
146
+ }
147
+ } finally {
148
+ subject.complete();
149
+ }
150
+ const ack = await ackPromise;
151
+ if (!ack.accepted) {
152
+ if (ack.cancelledByOperator) return fail(ack.rejectionReason ?? 'cancelled by the operator', token, { cancelledByOperator: true });
153
+ if (ack.streamBusy && busy++ < TRANSFER.busyRetries) {
154
+ await sleep(TRANSFER.busyDelayMs);
155
+ offset = ack.receivedOffset;
156
+ continue;
157
+ }
158
+ return fail(ack.rejectionReason ?? 'stream rejected', token, { retryable: true });
159
+ }
160
+ busy = 0;
161
+ if (ack.receivedOffset <= offset && end > offset) return fail('the gateway did not take the segment', token, { retryable: true });
162
+ offset = ack.receivedOffset;
163
+ hooks.onProgress?.(offset, total);
164
+ }
165
+
166
+ const complete = await hub.invoke<BackupUploadCompleteResponse>(DeviceHubMethods.backupUploadComplete, { token, sha256Hex });
167
+ if (complete.accepted) return { ok: true, token, bytes: complete.finalSizeBytes || total };
168
+ if (complete.restartFromZero && !restarted) {
169
+ restarted = true;
170
+ resumeToken = null; // the gateway's copy is unusable: one fresh run
171
+ continue;
172
+ }
173
+ return fail(complete.rejectionReason ?? 'the gateway refused the archive', token, { retryable: true });
174
+ }
175
+ }