@oodle-ai/mobile-sdk-reactnative 0.0.0-stage → 0.1.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.
Files changed (166) hide show
  1. package/LICENSE +201 -0
  2. package/OodleMobileSdkReactNative.podspec +24 -0
  3. package/README.md +191 -2
  4. package/android/build.gradle +55 -0
  5. package/android/proguard-rules.pro +5 -0
  6. package/android/src/main/AndroidManifest.xml +4 -0
  7. package/android/src/main/java/ai/oodle/rum/Connectivity.kt +19 -0
  8. package/android/src/main/java/ai/oodle/rum/CrashReporter.kt +88 -0
  9. package/android/src/main/java/ai/oodle/rum/DeviceInfo.kt +50 -0
  10. package/android/src/main/java/ai/oodle/rum/ExitReasons.kt +104 -0
  11. package/android/src/main/java/ai/oodle/rum/NativeEvents.kt +24 -0
  12. package/android/src/main/java/ai/oodle/rum/OodleRumModule.kt +96 -0
  13. package/android/src/main/java/ai/oodle/rum/OodleRumPackage.kt +26 -0
  14. package/android/src/main/java/ai/oodle/rum/Storage.kt +84 -0
  15. package/android/src/main/java/ai/oodle/rum/Vitals.kt +188 -0
  16. package/android/src/main/java/ai/oodle/rum/Watchdog.kt +81 -0
  17. package/android/src/main/java/ai/oodle/rum/WireframeCapture.kt +398 -0
  18. package/bin/oodle-rum-upload.mjs +104 -0
  19. package/ios/OodleCrashReporter.h +16 -0
  20. package/ios/OodleCrashReporter.m +202 -0
  21. package/ios/OodleRum.h +18 -0
  22. package/ios/OodleRum.mm +129 -0
  23. package/ios/OodleRumImpl.swift +450 -0
  24. package/ios/WireframeWalker.swift +279 -0
  25. package/lib/core/clock.d.ts +19 -0
  26. package/lib/core/clock.js +47 -0
  27. package/lib/core/clock.js.map +1 -0
  28. package/lib/core/config.d.ts +142 -0
  29. package/lib/core/config.js +178 -0
  30. package/lib/core/config.js.map +1 -0
  31. package/lib/core/consent.d.ts +5 -0
  32. package/lib/core/consent.js +33 -0
  33. package/lib/core/consent.js.map +1 -0
  34. package/lib/core/context.d.ts +36 -0
  35. package/lib/core/context.js +172 -0
  36. package/lib/core/context.js.map +1 -0
  37. package/lib/core/flags.d.ts +3 -0
  38. package/lib/core/flags.js +20 -0
  39. package/lib/core/flags.js.map +1 -0
  40. package/lib/core/ids.d.ts +7 -0
  41. package/lib/core/ids.js +40 -0
  42. package/lib/core/ids.js.map +1 -0
  43. package/lib/core/internal.d.ts +6 -0
  44. package/lib/core/internal.js +10 -0
  45. package/lib/core/internal.js.map +1 -0
  46. package/lib/core/logger.d.ts +8 -0
  47. package/lib/core/logger.js +38 -0
  48. package/lib/core/logger.js.map +1 -0
  49. package/lib/core/native.d.ts +71 -0
  50. package/lib/core/native.js +156 -0
  51. package/lib/core/native.js.map +1 -0
  52. package/lib/core/rate-limiter.d.ts +7 -0
  53. package/lib/core/rate-limiter.js +31 -0
  54. package/lib/core/rate-limiter.js.map +1 -0
  55. package/lib/core/session.d.ts +51 -0
  56. package/lib/core/session.js +196 -0
  57. package/lib/core/session.js.map +1 -0
  58. package/lib/core/size.d.ts +15 -0
  59. package/lib/core/size.js +68 -0
  60. package/lib/core/size.js.map +1 -0
  61. package/lib/core/tags.d.ts +10 -0
  62. package/lib/core/tags.js +33 -0
  63. package/lib/core/tags.js.map +1 -0
  64. package/lib/core/telemetry.d.ts +6 -0
  65. package/lib/core/telemetry.js +37 -0
  66. package/lib/core/telemetry.js.map +1 -0
  67. package/lib/core/tracing.d.ts +9 -0
  68. package/lib/core/tracing.js +57 -0
  69. package/lib/core/tracing.js.map +1 -0
  70. package/lib/core/transport.d.ts +76 -0
  71. package/lib/core/transport.js +560 -0
  72. package/lib/core/transport.js.map +1 -0
  73. package/lib/core/user.d.ts +12 -0
  74. package/lib/core/user.js +41 -0
  75. package/lib/core/user.js.map +1 -0
  76. package/lib/events/actions.d.ts +13 -0
  77. package/lib/events/actions.js +147 -0
  78. package/lib/events/actions.js.map +1 -0
  79. package/lib/events/emit.d.ts +21 -0
  80. package/lib/events/emit.js +144 -0
  81. package/lib/events/emit.js.map +1 -0
  82. package/lib/events/errors.d.ts +19 -0
  83. package/lib/events/errors.js +257 -0
  84. package/lib/events/errors.js.map +1 -0
  85. package/lib/events/lifecycle.d.ts +7 -0
  86. package/lib/events/lifecycle.js +101 -0
  87. package/lib/events/lifecycle.js.map +1 -0
  88. package/lib/events/longtasks.d.ts +2 -0
  89. package/lib/events/longtasks.js +42 -0
  90. package/lib/events/longtasks.js.map +1 -0
  91. package/lib/events/resources.d.ts +15 -0
  92. package/lib/events/resources.js +156 -0
  93. package/lib/events/resources.js.map +1 -0
  94. package/lib/events/tap-target.d.ts +42 -0
  95. package/lib/events/tap-target.js +191 -0
  96. package/lib/events/tap-target.js.map +1 -0
  97. package/lib/events/view-state.d.ts +13 -0
  98. package/lib/events/view-state.js +25 -0
  99. package/lib/events/view-state.js.map +1 -0
  100. package/lib/events/views.d.ts +21 -0
  101. package/lib/events/views.js +347 -0
  102. package/lib/events/views.js.map +1 -0
  103. package/lib/index.d.ts +16 -0
  104. package/lib/index.js +24 -0
  105. package/lib/index.js.map +1 -0
  106. package/lib/navigation/react-navigation.d.ts +33 -0
  107. package/lib/navigation/react-navigation.js +61 -0
  108. package/lib/navigation/react-navigation.js.map +1 -0
  109. package/lib/react/OodlePrivacy.d.ts +15 -0
  110. package/lib/react/OodlePrivacy.js +13 -0
  111. package/lib/react/OodlePrivacy.js.map +1 -0
  112. package/lib/react/OodleProvider.d.ts +18 -0
  113. package/lib/react/OodleProvider.js +72 -0
  114. package/lib/react/OodleProvider.js.map +1 -0
  115. package/lib/replay/recorder.d.ts +22 -0
  116. package/lib/replay/recorder.js +317 -0
  117. package/lib/replay/recorder.js.map +1 -0
  118. package/lib/replay/rrweb.d.ts +105 -0
  119. package/lib/replay/rrweb.js +335 -0
  120. package/lib/replay/rrweb.js.map +1 -0
  121. package/lib/rum.d.ts +52 -0
  122. package/lib/rum.js +281 -0
  123. package/lib/rum.js.map +1 -0
  124. package/lib/specs/NativeOodleRum.d.ts +43 -0
  125. package/lib/specs/NativeOodleRum.js +5 -0
  126. package/lib/specs/NativeOodleRum.js.map +1 -0
  127. package/lib/version.d.ts +1 -0
  128. package/lib/version.js +6 -0
  129. package/lib/version.js.map +1 -0
  130. package/package.json +91 -4
  131. package/react-native.config.js +10 -0
  132. package/src/core/clock.ts +43 -0
  133. package/src/core/config.ts +344 -0
  134. package/src/core/consent.ts +32 -0
  135. package/src/core/context.ts +189 -0
  136. package/src/core/flags.ts +15 -0
  137. package/src/core/ids.ts +35 -0
  138. package/src/core/internal.ts +6 -0
  139. package/src/core/logger.ts +37 -0
  140. package/src/core/native.ts +201 -0
  141. package/src/core/rate-limiter.ts +34 -0
  142. package/src/core/session.ts +209 -0
  143. package/src/core/size.ts +79 -0
  144. package/src/core/tags.ts +30 -0
  145. package/src/core/telemetry.ts +35 -0
  146. package/src/core/tracing.ts +60 -0
  147. package/src/core/transport.ts +590 -0
  148. package/src/core/user.ts +45 -0
  149. package/src/events/actions.ts +157 -0
  150. package/src/events/emit.ts +131 -0
  151. package/src/events/errors.ts +283 -0
  152. package/src/events/lifecycle.ts +102 -0
  153. package/src/events/longtasks.ts +40 -0
  154. package/src/events/resources.ts +167 -0
  155. package/src/events/tap-target.ts +210 -0
  156. package/src/events/view-state.ts +30 -0
  157. package/src/events/views.ts +356 -0
  158. package/src/index.ts +34 -0
  159. package/src/navigation/react-navigation.ts +72 -0
  160. package/src/react/OodlePrivacy.tsx +25 -0
  161. package/src/react/OodleProvider.tsx +88 -0
  162. package/src/replay/recorder.ts +310 -0
  163. package/src/replay/rrweb.ts +460 -0
  164. package/src/rum.ts +295 -0
  165. package/src/specs/NativeOodleRum.ts +51 -0
  166. package/src/version.ts +2 -0
@@ -0,0 +1,590 @@
1
+ import { observeServerDate } from './clock';
2
+ import { gzipSync, strToU8 } from 'fflate';
3
+ import { Platform } from 'react-native';
4
+ import { SDK_VERSION } from '../version';
5
+ import { getConfig } from './config';
6
+ import { INTERNAL_REQUEST } from './internal';
7
+ import { logger } from './logger';
8
+ import { storage } from './native';
9
+ import { estimateJsonBytes } from './size';
10
+ import { incrTelemetry } from './telemetry';
11
+
12
+ type Payload = Record<string, unknown>;
13
+
14
+ export const INGEST_PATH = '/v1/rum/ingest';
15
+ export const EVENTS_BATCH_KEY = 'events';
16
+ export const REPLAY_BATCH_KEY = 'replay';
17
+ export const TELEMETRY_BATCH_KEY = 'sdk_telemetry';
18
+
19
+ const MAX_BATCH_ITEMS = 50;
20
+ const MAX_BATCH_BYTES = 500_000;
21
+ const MAX_ITEM_BYTES = 256_000;
22
+ const REPLAY_MEASURE_LIMIT = 64_000;
23
+ /** Items held while consent is pending, per batch key. */
24
+ const MAX_HELD_ITEMS = 1000;
25
+ const MAX_IN_FLIGHT = 4;
26
+ const MAX_RETRY_BYTES = 10_000_000;
27
+ const MAX_RETRY_ATTEMPTS = 8;
28
+ const INITIAL_BACKOFF_MS = 1000;
29
+ const MAX_BACKOFF_MS = 60_000;
30
+ const REQUEST_TIMEOUT_MS = 30_000;
31
+ /** Upper bound for the outbox that survives an app restart. */
32
+ const MAX_OUTBOX_CHARS = 4_000_000;
33
+ const OUTBOX_KEY = 'outbox';
34
+ const FLUSH_ORDER = [EVENTS_BATCH_KEY, REPLAY_BATCH_KEY, TELEMETRY_BATCH_KEY];
35
+
36
+ interface Queue {
37
+ items: Payload[];
38
+ upsertIndex: Map<string, number>;
39
+ bytes: number;
40
+ }
41
+
42
+ interface RetryItem {
43
+ body: string;
44
+ attempts: number;
45
+ carriesReplay: boolean;
46
+ /** Earliest time to send again, after a failure. */
47
+ notBefore: number;
48
+ }
49
+
50
+ export interface PostResult {
51
+ status: number;
52
+ rateLimits: string | null;
53
+ /** The response `Date` header, for the clock offset. */
54
+ date?: string | null;
55
+ }
56
+
57
+ export type Poster = (
58
+ url: string,
59
+ headers: Record<string, string>,
60
+ body: Uint8Array | string,
61
+ ) => Promise<PostResult>;
62
+
63
+ const queues = new Map<string, Queue>();
64
+ let retryQueue: RetryItem[] = [];
65
+ let retryBytes = 0;
66
+ let retryTimer: ReturnType<typeof setTimeout> | null = null;
67
+ let flushTimer: ReturnType<typeof setTimeout> | null = null;
68
+ let persistTimer: ReturnType<typeof setTimeout> | null = null;
69
+ /** True after this process wrote an outbox that it has not removed. */
70
+ let outboxOnDisk = false;
71
+ /** True when that outbox also holds items from the batch queues. */
72
+ let outboxHasHeld = false;
73
+ /** Bodies sent and not yet answered. The outbox keeps them, see persistOutbox. */
74
+ const inFlight = new Set<RetryItem>();
75
+ let canSend: () => boolean = () => true;
76
+ let replayDropHandler: (() => void) | null = null;
77
+ let authWarned = false;
78
+ const rateLimitedUntil = new Map<string, number>();
79
+
80
+ function xhrPost(
81
+ url: string,
82
+ headers: Record<string, string>,
83
+ body: Uint8Array | string,
84
+ ): Promise<PostResult> {
85
+ return new Promise((resolve, reject) => {
86
+ const xhr = new XMLHttpRequest();
87
+ (xhr as unknown as Record<string, boolean>)[INTERNAL_REQUEST] = true;
88
+ xhr.open('POST', url, true);
89
+ for (const [k, v] of Object.entries(headers)) xhr.setRequestHeader(k, v);
90
+ xhr.timeout = REQUEST_TIMEOUT_MS;
91
+ xhr.onload = () =>
92
+ resolve({
93
+ status: xhr.status,
94
+ rateLimits: xhr.getResponseHeader('X-Oodle-Rate-Limits'),
95
+ date: xhr.getResponseHeader('Date'),
96
+ });
97
+ xhr.onerror = () => reject(new Error('network error'));
98
+ xhr.ontimeout = () => reject(new Error('timeout'));
99
+ // React Native sends a typed array body as raw bytes.
100
+ xhr.send(body as unknown as string);
101
+ });
102
+ }
103
+
104
+ let poster: Poster = xhrPost;
105
+
106
+ /** Test hook: replace the HTTP client. */
107
+ export function setPoster(p: Poster | null) {
108
+ poster = p ?? xhrPost;
109
+ }
110
+
111
+ /** Events stay queued while this returns false (consent is pending). */
112
+ export function setCanSend(fn: () => boolean) {
113
+ canSend = fn;
114
+ }
115
+
116
+ /**
117
+ * Lets the replay recorder start a new full snapshot when a segment is
118
+ * lost. rrweb events are deltas, so a lost segment breaks every later
119
+ * event until the next full snapshot.
120
+ */
121
+ export function setReplayDropHandler(fn: (() => void) | null) {
122
+ replayDropHandler = fn;
123
+ }
124
+
125
+ function onDropped(carriesReplay: boolean) {
126
+ incrTelemetry('transport_drops');
127
+ if (carriesReplay && replayDropHandler) replayDropHandler();
128
+ }
129
+
130
+ function getQueue(key: string): Queue {
131
+ let q = queues.get(key);
132
+ if (!q) {
133
+ q = { items: [], upsertIndex: new Map(), bytes: 0 };
134
+ queues.set(key, q);
135
+ }
136
+ return q;
137
+ }
138
+
139
+ function measure(key: string, item: Payload, hint?: number) {
140
+ if (key === REPLAY_BATCH_KEY) {
141
+ // A full snapshot cannot be split, and the recorder already bounds
142
+ // segment size, so replay items are never rejected for size.
143
+ return {
144
+ bytes: hint ?? estimateJsonBytes(item, REPLAY_MEASURE_LIMIT),
145
+ oversized: false,
146
+ };
147
+ }
148
+ const bytes = estimateJsonBytes(item, MAX_ITEM_BYTES + 1);
149
+ return { bytes, oversized: bytes > MAX_ITEM_BYTES };
150
+ }
151
+
152
+ function trimHeld(key: string, q: Queue) {
153
+ if (canSend() || q.items.length <= MAX_HELD_ITEMS) return;
154
+ const drop = q.items.length - MAX_HELD_ITEMS;
155
+ q.items.splice(0, drop);
156
+ q.upsertIndex.clear();
157
+ q.bytes = 0;
158
+ incrTelemetry('events_should_send_dropped', drop);
159
+ if (key === REPLAY_BATCH_KEY && replayDropHandler) replayDropHandler();
160
+ }
161
+
162
+ function afterAdd(q: Queue) {
163
+ if (
164
+ canSend() &&
165
+ (q.items.length >= MAX_BATCH_ITEMS || q.bytes >= MAX_BATCH_BYTES)
166
+ ) {
167
+ flush();
168
+ return;
169
+ }
170
+ scheduleFlush();
171
+ }
172
+
173
+ export function enqueue(key: string, item: Payload, bytesHint?: number) {
174
+ const { bytes, oversized } = measure(key, item, bytesHint);
175
+ if (oversized) {
176
+ logger.warn(`Dropping a ${key} item of ${bytes} bytes`);
177
+ onDropped(key === REPLAY_BATCH_KEY);
178
+ return;
179
+ }
180
+ const q = getQueue(key);
181
+ q.items.push(item);
182
+ q.bytes += bytes;
183
+ trimHeld(key, q);
184
+ afterAdd(q);
185
+ }
186
+
187
+ /**
188
+ * Replaces the queued item with the same key, or adds it. `merge` sees the
189
+ * queued item and the new one, and returns what to keep.
190
+ */
191
+ export function upsert(
192
+ key: string,
193
+ itemKey: string,
194
+ item: Payload,
195
+ merge?: (previous: Payload, next: Payload) => Payload,
196
+ ) {
197
+ const { bytes, oversized } = measure(key, item);
198
+ if (oversized) {
199
+ onDropped(false);
200
+ return;
201
+ }
202
+ const q = getQueue(key);
203
+ const at = q.upsertIndex.get(itemKey);
204
+ if (at !== undefined) {
205
+ const kept = merge ? merge(q.items[at], item) : item;
206
+ q.bytes += bytes - measure(key, q.items[at]).bytes;
207
+ q.items[at] = kept;
208
+ } else {
209
+ q.upsertIndex.set(itemKey, q.items.length);
210
+ q.items.push(item);
211
+ q.bytes += bytes;
212
+ }
213
+ trimHeld(key, q);
214
+ afterAdd(q);
215
+ }
216
+
217
+ function scheduleFlush() {
218
+ if (flushTimer) return;
219
+ const interval = getConfig()?.flushIntervalMs ?? 5000;
220
+ flushTimer = setTimeout(() => {
221
+ flushTimer = null;
222
+ flush();
223
+ }, interval);
224
+ }
225
+
226
+ export function buildEnvelope(
227
+ sections: Array<{ type: string; items: Payload[] }>,
228
+ ): string {
229
+ let sessionId = '';
230
+ for (const s of sections) {
231
+ const first = s.items[0];
232
+ if (first && typeof first.session_id === 'string') {
233
+ sessionId = first.session_id;
234
+ break;
235
+ }
236
+ }
237
+ const lines = [JSON.stringify({ session_id: sessionId, sdk_version: SDK_VERSION })];
238
+ for (const s of sections) {
239
+ lines.push(JSON.stringify({ type: s.type, count: s.items.length }));
240
+ lines.push(JSON.stringify(s.items));
241
+ }
242
+ return lines.join('\n');
243
+ }
244
+
245
+ function takeSections(): Array<{ type: string; items: Payload[] }> {
246
+ const keys = Array.from(queues.keys()).sort((a, b) => {
247
+ const ai = FLUSH_ORDER.indexOf(a);
248
+ const bi = FLUSH_ORDER.indexOf(b);
249
+ return (ai < 0 ? 99 : ai) - (bi < 0 ? 99 : bi);
250
+ });
251
+ const sections: Array<{ type: string; items: Payload[] }> = [];
252
+ for (const key of keys) {
253
+ const q = queues.get(key)!;
254
+ if (q.items.length === 0) continue;
255
+ sections.push({ type: key, items: q.items.splice(0) });
256
+ q.upsertIndex.clear();
257
+ q.bytes = 0;
258
+ }
259
+ return sections;
260
+ }
261
+
262
+ /** Sends everything queued now. No-op while consent is pending. */
263
+ export function flush() {
264
+ if (flushTimer) {
265
+ clearTimeout(flushTimer);
266
+ flushTimer = null;
267
+ }
268
+ if (!getConfig() || !canSend()) return;
269
+ const sections = takeSections();
270
+ if (sections.length === 0) return;
271
+ const body = buildEnvelope(sections);
272
+ const carriesReplay = sections.some((s) => s.type === REPLAY_BATCH_KEY);
273
+ void sendBody({ body, attempts: 0, carriesReplay, notBefore: 0 });
274
+ }
275
+
276
+ function headers(): Record<string, string> {
277
+ const c = getConfig()!;
278
+ return {
279
+ 'X-OODLE-INSTANCE': c.instanceId,
280
+ 'X-API-KEY': c.apiKey,
281
+ 'Content-Type': 'application/json',
282
+ };
283
+ }
284
+
285
+ /**
286
+ * React Native on Android removes `Content-Encoding` from a request with
287
+ * a binary body, so a body compressed in JS arrives without the header
288
+ * and the collector cannot read it. For a string body with
289
+ * `Content-Encoding: gzip`, Android compresses the body itself, off the
290
+ * JS thread. iOS sends the body as given, so there it is compressed in JS.
291
+ */
292
+ function compress(raw: string): { body: Uint8Array | string; gzip: boolean } {
293
+ if (Platform.OS === 'android') return { body: raw, gzip: true };
294
+ try {
295
+ return { body: gzipSync(strToU8(raw)), gzip: true };
296
+ } catch {
297
+ incrTelemetry('compression_failures');
298
+ return { body: raw, gzip: false };
299
+ }
300
+ }
301
+
302
+ function parseRateLimits(header: string | null) {
303
+ if (!header) return;
304
+ const now = Date.now();
305
+ for (const part of header.split(',')) {
306
+ const [cat, secs] = part.trim().split(':');
307
+ const n = parseInt(secs ?? '', 10);
308
+ if (cat && Number.isFinite(n)) rateLimitedUntil.set(cat, now + n * 1000);
309
+ }
310
+ }
311
+
312
+ export function isServerRateLimited(category: string): boolean {
313
+ const until = rateLimitedUntil.get(category);
314
+ if (!until) return false;
315
+ if (Date.now() >= until) {
316
+ rateLimitedUntil.delete(category);
317
+ return false;
318
+ }
319
+ return true;
320
+ }
321
+
322
+ async function sendBody(item: RetryItem): Promise<void> {
323
+ const config = getConfig();
324
+ if (!config) return;
325
+ if (inFlight.size >= MAX_IN_FLIGHT) {
326
+ addRetry(item, false);
327
+ return;
328
+ }
329
+ inFlight.add(item);
330
+ try {
331
+ const { body, gzip } = compress(item.body);
332
+ const h = headers();
333
+ if (gzip) h['Content-Encoding'] = 'gzip';
334
+ const sentAt = Date.now();
335
+ const res = await poster(`${config.endpoint}${INGEST_PATH}`, h, body);
336
+ if (res.status > 0) observeServerDate(res.date, sentAt, Date.now());
337
+ parseRateLimits(res.rateLimits);
338
+ if (res.status === 429 || res.status >= 500 || res.status === 0) {
339
+ inFlight.delete(item);
340
+ addRetry(item, true);
341
+ } else {
342
+ if (res.status >= 400) {
343
+ // The request itself is wrong (bad key, bad body). Sending it
344
+ // again cannot succeed.
345
+ if ((res.status === 401 || res.status === 403) && !authWarned) {
346
+ authWarned = true;
347
+ logger.error(
348
+ `The collector rejected the API key (HTTP ${res.status}). ` +
349
+ 'Check apiKey and instanceId.',
350
+ );
351
+ }
352
+ onDropped(item.carriesReplay);
353
+ }
354
+ inFlight.delete(item);
355
+ syncOutboxAfterSend();
356
+ }
357
+ } catch {
358
+ inFlight.delete(item);
359
+ incrTelemetry('send_failures');
360
+ addRetry(item, true);
361
+ } finally {
362
+ drainRetries();
363
+ }
364
+ }
365
+
366
+ /**
367
+ * Called when a body has its final answer. The outbox on disk can still
368
+ * hold it, and the next start would send it again. When no other body
369
+ * waits for an answer, the outbox is removed now. Otherwise it is
370
+ * written again after the usual delay, so that a queue that drains after
371
+ * an outage is not serialized once per body.
372
+ *
373
+ * Items in the batch queues count only when the outbox holds them (after
374
+ * a fatal error, or a background while sending was paused). Usually they
375
+ * are not on disk, and writing them after each send would serialize the
376
+ * queue on every flush.
377
+ */
378
+ function syncOutboxAfterSend() {
379
+ if (!outboxOnDisk) return;
380
+ if (retryQueue.length > 0 || inFlight.size > 0 || outboxHasHeld) schedulePersist();
381
+ else removeOutbox();
382
+ }
383
+
384
+ function removeOutbox() {
385
+ if (persistTimer) {
386
+ clearTimeout(persistTimer);
387
+ persistTimer = null;
388
+ }
389
+ storage.remove(OUTBOX_KEY);
390
+ outboxOnDisk = false;
391
+ outboxHasHeld = false;
392
+ }
393
+
394
+ /**
395
+ * Returns the wait before retry number `attempts`, a random value
396
+ * between half and all of the exponential step.
397
+ *
398
+ * Without the random part, all devices that lost the collector at the
399
+ * same time retry at the same times, and each wave of retries can make
400
+ * the collector fail again when it comes back. The lower half stays fixed
401
+ * so that a collector that fails fast is not sent requests in a loop.
402
+ */
403
+ export function retryDelayMs(attempts: number, random: () => number = Math.random): number {
404
+ const step = Math.min(INITIAL_BACKOFF_MS * Math.pow(2, attempts - 1), MAX_BACKOFF_MS);
405
+ return Math.round(step / 2 + random() * (step / 2));
406
+ }
407
+
408
+ function addRetry(item: RetryItem, failed: boolean) {
409
+ const attempts = failed ? item.attempts + 1 : item.attempts;
410
+ if (attempts > MAX_RETRY_ATTEMPTS) {
411
+ incrTelemetry('retry_drops');
412
+ onDropped(item.carriesReplay);
413
+ return;
414
+ }
415
+ const next: RetryItem = {
416
+ ...item,
417
+ attempts,
418
+ notBefore: failed ? Date.now() + retryDelayMs(attempts) : 0,
419
+ };
420
+ while (retryBytes + next.body.length > MAX_RETRY_BYTES && retryQueue.length > 0) {
421
+ const old = retryQueue.shift()!;
422
+ retryBytes -= old.body.length;
423
+ incrTelemetry('retry_drops');
424
+ onDropped(old.carriesReplay);
425
+ }
426
+ // A failed body goes back to the front: replay segments must reach
427
+ // the server in the order they were recorded.
428
+ if (failed) retryQueue.unshift(next);
429
+ else retryQueue.push(next);
430
+ retryBytes += next.body.length;
431
+ schedulePersist();
432
+ }
433
+
434
+ function drainRetries() {
435
+ if (retryTimer) {
436
+ clearTimeout(retryTimer);
437
+ retryTimer = null;
438
+ }
439
+ if (!getConfig() || !canSend()) return;
440
+ while (retryQueue.length > 0 && inFlight.size < MAX_IN_FLIGHT) {
441
+ const head = retryQueue[0];
442
+ const wait = head.notBefore - Date.now();
443
+ if (wait > 0) {
444
+ retryTimer = setTimeout(() => {
445
+ retryTimer = null;
446
+ drainRetries();
447
+ }, wait);
448
+ return;
449
+ }
450
+ retryQueue.shift();
451
+ retryBytes -= head.body.length;
452
+ void sendBody(head);
453
+ }
454
+ }
455
+
456
+ // --- Outbox: queued data that survives an app restart ---
457
+
458
+ interface Outbox {
459
+ retry: RetryItem[];
460
+ held: Record<string, Payload[]>;
461
+ }
462
+
463
+ function schedulePersist() {
464
+ if (persistTimer) return;
465
+ persistTimer = setTimeout(() => {
466
+ persistTimer = null;
467
+ persistOutbox();
468
+ }, 2000);
469
+ }
470
+
471
+ /**
472
+ * Writes unsent data to disk. Called when the app goes to the background,
473
+ * after a failed send, and from the fatal error handler, so an app that
474
+ * is killed or crashes sends the data on its next start.
475
+ *
476
+ * Bodies in flight are written too: the app often goes to the background
477
+ * just after a flush, and the OS can end it before the answer comes.
478
+ * When the answer comes, syncOutboxAfterSend takes them out again.
479
+ *
480
+ * The file write runs on a native background thread, so a large queue
481
+ * does not block the JS thread. Only the fatal error handler uses
482
+ * `sync`, because the process can end as soon as it returns.
483
+ */
484
+ export function persistOutbox(opts: { sync?: boolean } = {}) {
485
+ if (persistTimer) {
486
+ clearTimeout(persistTimer);
487
+ persistTimer = null;
488
+ }
489
+ const held: Record<string, Payload[]> = {};
490
+ for (const [key, q] of queues) if (q.items.length > 0) held[key] = q.items.slice();
491
+ const retry = [...inFlight, ...retryQueue].map((r) => ({ ...r, notBefore: 0 }));
492
+ if (retry.length === 0 && Object.keys(held).length === 0) {
493
+ removeOutbox();
494
+ return;
495
+ }
496
+ // Drop the oldest retries by their body size first, so the queue is
497
+ // serialized once and not once per dropped item.
498
+ let retryChars = 0;
499
+ for (const r of retry) retryChars += r.body.length;
500
+ while (retry.length > 0 && retryChars > MAX_OUTBOX_CHARS) {
501
+ retryChars -= retry.shift()!.body.length;
502
+ incrTelemetry('outbox_drops');
503
+ }
504
+ let raw = JSON.stringify({ retry, held } satisfies Outbox);
505
+ while (raw.length > MAX_OUTBOX_CHARS && retry.length > 0) {
506
+ retry.shift();
507
+ incrTelemetry('outbox_drops');
508
+ raw = JSON.stringify({ retry, held } satisfies Outbox);
509
+ }
510
+ if (raw.length > MAX_OUTBOX_CHARS) {
511
+ incrTelemetry('outbox_drops');
512
+ return;
513
+ }
514
+ if (opts.sync) storage.set(OUTBOX_KEY, raw);
515
+ else storage.setAsync(OUTBOX_KEY, raw);
516
+ outboxOnDisk = true;
517
+ outboxHasHeld = Object.keys(held).length > 0;
518
+ }
519
+
520
+ /** Loads the outbox written by an earlier run and queues it to send. */
521
+ export function restoreOutbox() {
522
+ const box = storage.getJSON<Outbox | null>(OUTBOX_KEY, null);
523
+ removeOutbox();
524
+ if (!box) return;
525
+ for (const r of box.retry ?? []) {
526
+ if (typeof r.body !== 'string') continue;
527
+ retryQueue.push({
528
+ body: r.body,
529
+ attempts: 0,
530
+ carriesReplay: !!r.carriesReplay,
531
+ notBefore: 0,
532
+ });
533
+ retryBytes += r.body.length;
534
+ }
535
+ for (const [key, items] of Object.entries(box.held ?? {})) {
536
+ if (!Array.isArray(items)) continue;
537
+ const q = getQueue(key);
538
+ for (const item of items) {
539
+ q.items.push(item);
540
+ q.bytes += measure(key, item).bytes;
541
+ }
542
+ }
543
+ if (canSend()) {
544
+ flush();
545
+ drainRetries();
546
+ } else {
547
+ scheduleFlush();
548
+ }
549
+ }
550
+
551
+ /** Drops everything queued, held and persisted (consent withdrawn). */
552
+ export function clearAll() {
553
+ for (const q of queues.values()) {
554
+ q.items.length = 0;
555
+ q.upsertIndex.clear();
556
+ q.bytes = 0;
557
+ }
558
+ retryQueue = [];
559
+ retryBytes = 0;
560
+ removeOutbox();
561
+ }
562
+
563
+ /** Starts sending again after consent changes to granted. */
564
+ export function resume() {
565
+ flush();
566
+ drainRetries();
567
+ }
568
+
569
+ /** Test hook. */
570
+ export function resetTransport() {
571
+ for (const t of [retryTimer, flushTimer, persistTimer]) if (t) clearTimeout(t);
572
+ retryTimer = flushTimer = persistTimer = null;
573
+ queues.clear();
574
+ retryQueue = [];
575
+ retryBytes = 0;
576
+ outboxOnDisk = outboxHasHeld = false;
577
+ inFlight.clear();
578
+ canSend = () => true;
579
+ replayDropHandler = null;
580
+ authWarned = false;
581
+ rateLimitedUntil.clear();
582
+ poster = xhrPost;
583
+ }
584
+
585
+ /** Test hook. */
586
+ export function pendingCounts() {
587
+ const out: Record<string, number> = {};
588
+ for (const [k, q] of queues) out[k] = q.items.length;
589
+ return { queues: out, retries: retryQueue.length, inFlight: inFlight.size };
590
+ }
@@ -0,0 +1,45 @@
1
+ import type { TagValue } from './config';
2
+ import { removeTag, setTags } from './tags';
3
+
4
+ export interface UserInfo {
5
+ id: string;
6
+ name?: string;
7
+ email?: string;
8
+ /** Other user attributes. They are sent as `usr.<key>` tags. */
9
+ [key: string]: TagValue | undefined;
10
+ }
11
+
12
+ let user: UserInfo | null = null;
13
+ let extraKeys: string[] = [];
14
+
15
+ export function setUser(next: UserInfo) {
16
+ clearUser();
17
+ user = { ...next };
18
+ const extra: Record<string, TagValue> = {};
19
+ for (const [k, v] of Object.entries(next)) {
20
+ if (k === 'id' || k === 'name' || k === 'email') continue;
21
+ if (v === undefined || v === null) continue;
22
+ extra[`usr.${k}`] = v;
23
+ }
24
+ extraKeys = Object.keys(extra);
25
+ setTags(extra);
26
+ }
27
+
28
+ export function clearUser() {
29
+ user = null;
30
+ for (const k of extraKeys) removeTag(k);
31
+ extraKeys = [];
32
+ }
33
+
34
+ export function getUser(): UserInfo | null {
35
+ return user;
36
+ }
37
+
38
+ export function userFields(): Record<string, string> {
39
+ return {
40
+ user_id: user?.id ? String(user.id) : '',
41
+ user_name: user?.name ? String(user.name) : '',
42
+ user_email: user?.email ? String(user.email) : '',
43
+ user_status: user ? 'identified' : 'anonymous',
44
+ };
45
+ }