@nagoorkani/session-capture-core 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.
- package/LICENSE +25 -0
- package/README.md +42 -0
- package/dist/batcher.d.ts +58 -0
- package/dist/batcher.js +106 -0
- package/dist/breadcrumbs.d.ts +22 -0
- package/dist/breadcrumbs.js +45 -0
- package/dist/config.d.ts +60 -0
- package/dist/config.js +134 -0
- package/dist/container.d.ts +33 -0
- package/dist/container.js +48 -0
- package/dist/core.d.ts +175 -0
- package/dist/core.js +414 -0
- package/dist/dispatcher.d.ts +43 -0
- package/dist/dispatcher.js +74 -0
- package/dist/errors.d.ts +40 -0
- package/dist/errors.js +186 -0
- package/dist/ids.d.ts +29 -0
- package/dist/ids.js +58 -0
- package/dist/index.d.ts +39 -0
- package/dist/index.js +39 -0
- package/dist/network.d.ts +123 -0
- package/dist/network.js +510 -0
- package/dist/performance.d.ts +33 -0
- package/dist/performance.js +54 -0
- package/dist/queue.d.ts +70 -0
- package/dist/queue.js +105 -0
- package/dist/redact.d.ts +19 -0
- package/dist/redact.js +61 -0
- package/dist/replay-gate.d.ts +69 -0
- package/dist/replay-gate.js +78 -0
- package/dist/safe.d.ts +26 -0
- package/dist/safe.js +88 -0
- package/dist/session.d.ts +80 -0
- package/dist/session.js +111 -0
- package/dist/store.d.ts +44 -0
- package/dist/store.js +49 -0
- package/dist/transport.d.ts +62 -0
- package/dist/transport.js +84 -0
- package/dist/types.d.ts +92 -0
- package/dist/types.js +26 -0
- package/package.json +45 -0
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Drains the queue.
|
|
3
|
+
*
|
|
4
|
+
* Single-flight on purpose: only one drain runs at a time. Two concurrent
|
|
5
|
+
* drains would read the same oldest batches and deliver them twice — the
|
|
6
|
+
* backend deduplicates, but spending a user's data plan to send events the
|
|
7
|
+
* server will throw away is not something to rely on.
|
|
8
|
+
*/
|
|
9
|
+
import { backoffDelay, sendBatch } from "./transport.js";
|
|
10
|
+
export class Dispatcher {
|
|
11
|
+
constructor(options) {
|
|
12
|
+
this.draining = false;
|
|
13
|
+
/** Wall-clock time before which no send should be attempted. */
|
|
14
|
+
this.pausedUntil = 0;
|
|
15
|
+
this.queue = options.queue;
|
|
16
|
+
this.transport = options.transport;
|
|
17
|
+
this.batchesPerDrain = options.batchesPerDrain ?? 5;
|
|
18
|
+
this.now = options.now ?? Date.now;
|
|
19
|
+
this.onOutcome = options.onOutcome;
|
|
20
|
+
}
|
|
21
|
+
/** True while backpressure is in effect. */
|
|
22
|
+
get paused() {
|
|
23
|
+
return this.now() < this.pausedUntil;
|
|
24
|
+
}
|
|
25
|
+
get pausedForMs() {
|
|
26
|
+
return Math.max(0, this.pausedUntil - this.now());
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* Send what is queued.
|
|
30
|
+
*
|
|
31
|
+
* Returns the number of batches delivered. Stops early on the first batch
|
|
32
|
+
* that needs retrying: the queue is ordered, and a failure almost always
|
|
33
|
+
* means the network or the server is unavailable for the next one too.
|
|
34
|
+
* Continuing would just burn attempts on every queued batch at once.
|
|
35
|
+
*/
|
|
36
|
+
async drain() {
|
|
37
|
+
if (this.draining || this.paused)
|
|
38
|
+
return 0;
|
|
39
|
+
this.draining = true;
|
|
40
|
+
let sent = 0;
|
|
41
|
+
try {
|
|
42
|
+
const entries = await this.queue.peek(this.batchesPerDrain);
|
|
43
|
+
for (const entry of entries) {
|
|
44
|
+
const outcome = await sendBatch(this.transport, entry.batch);
|
|
45
|
+
this.onOutcome?.(outcome, entry);
|
|
46
|
+
if (outcome.kind === 'sent') {
|
|
47
|
+
await this.queue.remove(entry.name);
|
|
48
|
+
sent += 1;
|
|
49
|
+
continue;
|
|
50
|
+
}
|
|
51
|
+
if (outcome.kind === 'permanent') {
|
|
52
|
+
// The server will never take this. Keeping it would block every
|
|
53
|
+
// batch behind it forever.
|
|
54
|
+
await this.queue.remove(entry.name);
|
|
55
|
+
continue;
|
|
56
|
+
}
|
|
57
|
+
// Retryable. Honour an explicit Retry-After over our own backoff:
|
|
58
|
+
// the server knows more about when it will be ready than we do.
|
|
59
|
+
const delay = outcome.retryAfterMs ?? backoffDelay(entry.attempts);
|
|
60
|
+
this.pausedUntil = this.now() + delay;
|
|
61
|
+
await this.queue.recordFailure(entry);
|
|
62
|
+
break;
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
finally {
|
|
66
|
+
this.draining = false;
|
|
67
|
+
}
|
|
68
|
+
return sent;
|
|
69
|
+
}
|
|
70
|
+
/** Clear backpressure, e.g. when the app returns to the foreground. */
|
|
71
|
+
resume() {
|
|
72
|
+
this.pausedUntil = 0;
|
|
73
|
+
}
|
|
74
|
+
}
|
package/dist/errors.d.ts
ADDED
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Error capture.
|
|
3
|
+
*
|
|
4
|
+
* Errors are the reason people install this, so they bypass sampling entirely
|
|
5
|
+
* (section 35) and are the one event type worth capturing aggressively.
|
|
6
|
+
*
|
|
7
|
+
* The SDK sends type, message, and stack. Grouping happens server-side, so a
|
|
8
|
+
* fingerprinting change does not need an app release to take effect.
|
|
9
|
+
*/
|
|
10
|
+
export interface CapturedError {
|
|
11
|
+
type: string;
|
|
12
|
+
message: string;
|
|
13
|
+
stack?: string;
|
|
14
|
+
/** False for a global handler catch — the app did not expect this one. */
|
|
15
|
+
handled: boolean;
|
|
16
|
+
/** True when the platform considers the error fatal to the app. */
|
|
17
|
+
fatal?: boolean;
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* Normalize anything throwable into a capturable shape.
|
|
21
|
+
*
|
|
22
|
+
* JavaScript permits throwing any value — strings, objects, undefined — and a
|
|
23
|
+
* crash reporter that assumes `Error` will itself throw while handling the
|
|
24
|
+
* crash.
|
|
25
|
+
*/
|
|
26
|
+
export declare function describeError(value: unknown, handled: boolean): CapturedError;
|
|
27
|
+
export type ErrorHandler = (error: CapturedError) => void;
|
|
28
|
+
type Uninstall = () => void;
|
|
29
|
+
/**
|
|
30
|
+
* Install global error and rejection handlers.
|
|
31
|
+
*
|
|
32
|
+
* React Native exposes `ErrorUtils`; a browser fires an `error` event on
|
|
33
|
+
* `window` instead. The promise rejection path is the same `addEventListener`
|
|
34
|
+
* in both. All of it is optional — an environment providing none simply
|
|
35
|
+
* captures fewer errors, which is far better than failing to start.
|
|
36
|
+
*/
|
|
37
|
+
export declare function installErrorHandlers(onError: ErrorHandler): Uninstall;
|
|
38
|
+
/** Test-only. */
|
|
39
|
+
export declare function resetErrorHandlerState(): void;
|
|
40
|
+
export {};
|
package/dist/errors.js
ADDED
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Error capture.
|
|
3
|
+
*
|
|
4
|
+
* Errors are the reason people install this, so they bypass sampling entirely
|
|
5
|
+
* (section 35) and are the one event type worth capturing aggressively.
|
|
6
|
+
*
|
|
7
|
+
* The SDK sends type, message, and stack. Grouping happens server-side, so a
|
|
8
|
+
* fingerprinting change does not need an app release to take effect.
|
|
9
|
+
*/
|
|
10
|
+
/** Stacks are unbounded in principle and this rides on every error. */
|
|
11
|
+
const MAX_STACK_CHARS = 8 * 1024;
|
|
12
|
+
const MAX_MESSAGE_CHARS = 1024;
|
|
13
|
+
/**
|
|
14
|
+
* Normalize anything throwable into a capturable shape.
|
|
15
|
+
*
|
|
16
|
+
* JavaScript permits throwing any value — strings, objects, undefined — and a
|
|
17
|
+
* crash reporter that assumes `Error` will itself throw while handling the
|
|
18
|
+
* crash.
|
|
19
|
+
*/
|
|
20
|
+
export function describeError(value, handled) {
|
|
21
|
+
if (value instanceof Error) {
|
|
22
|
+
return {
|
|
23
|
+
type: value.name || 'Error',
|
|
24
|
+
message: (value.message || '').slice(0, MAX_MESSAGE_CHARS),
|
|
25
|
+
stack: value.stack?.slice(0, MAX_STACK_CHARS),
|
|
26
|
+
handled,
|
|
27
|
+
};
|
|
28
|
+
}
|
|
29
|
+
if (typeof value === 'string') {
|
|
30
|
+
return {
|
|
31
|
+
type: 'Error',
|
|
32
|
+
message: value.slice(0, MAX_MESSAGE_CHARS),
|
|
33
|
+
handled,
|
|
34
|
+
};
|
|
35
|
+
}
|
|
36
|
+
// Objects, numbers, null, undefined. Stringify defensively: a getter on the
|
|
37
|
+
// thrown object can itself throw.
|
|
38
|
+
let message;
|
|
39
|
+
try {
|
|
40
|
+
message = typeof value === 'object' && value !== null
|
|
41
|
+
? JSON.stringify(value)
|
|
42
|
+
: String(value);
|
|
43
|
+
}
|
|
44
|
+
catch {
|
|
45
|
+
message = '[unserializable]';
|
|
46
|
+
}
|
|
47
|
+
return {
|
|
48
|
+
type: 'UnknownError',
|
|
49
|
+
message: (message ?? 'undefined').slice(0, MAX_MESSAGE_CHARS),
|
|
50
|
+
handled,
|
|
51
|
+
};
|
|
52
|
+
}
|
|
53
|
+
let installed = false;
|
|
54
|
+
/**
|
|
55
|
+
* Install global error and rejection handlers.
|
|
56
|
+
*
|
|
57
|
+
* React Native exposes `ErrorUtils`; a browser fires an `error` event on
|
|
58
|
+
* `window` instead. The promise rejection path is the same `addEventListener`
|
|
59
|
+
* in both. All of it is optional — an environment providing none simply
|
|
60
|
+
* captures fewer errors, which is far better than failing to start.
|
|
61
|
+
*/
|
|
62
|
+
export function installErrorHandlers(onError) {
|
|
63
|
+
if (installed) {
|
|
64
|
+
// Double-installing would report every error twice and, worse, chain the
|
|
65
|
+
// previous handler into itself.
|
|
66
|
+
return () => { };
|
|
67
|
+
}
|
|
68
|
+
installed = true;
|
|
69
|
+
const uninstalls = [];
|
|
70
|
+
uninstalls.push(installGlobalErrorHandler(onError));
|
|
71
|
+
uninstalls.push(installRejectionHandler(onError));
|
|
72
|
+
return () => {
|
|
73
|
+
installed = false;
|
|
74
|
+
for (const fn of uninstalls) {
|
|
75
|
+
try {
|
|
76
|
+
fn();
|
|
77
|
+
}
|
|
78
|
+
catch {
|
|
79
|
+
// Teardown must never throw into the host app.
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
};
|
|
83
|
+
}
|
|
84
|
+
function installGlobalErrorHandler(onError) {
|
|
85
|
+
const errorUtils = globalThis.ErrorUtils;
|
|
86
|
+
if (!errorUtils?.setGlobalHandler || !errorUtils.getGlobalHandler) {
|
|
87
|
+
return installErrorEventHandler(onError);
|
|
88
|
+
}
|
|
89
|
+
const previous = errorUtils.getGlobalHandler();
|
|
90
|
+
errorUtils.setGlobalHandler((error, isFatal) => {
|
|
91
|
+
try {
|
|
92
|
+
const captured = describeError(error, false);
|
|
93
|
+
captured.fatal = isFatal ?? false;
|
|
94
|
+
onError(captured);
|
|
95
|
+
}
|
|
96
|
+
catch {
|
|
97
|
+
// Reporting must never suppress the app's own crash handling.
|
|
98
|
+
}
|
|
99
|
+
// Always chain. Swallowing this would break every other error reporter
|
|
100
|
+
// and React Native's own red-box, which is not ours to take away.
|
|
101
|
+
previous?.(error, isFatal);
|
|
102
|
+
});
|
|
103
|
+
return () => {
|
|
104
|
+
if (previous)
|
|
105
|
+
errorUtils.setGlobalHandler?.(previous);
|
|
106
|
+
};
|
|
107
|
+
}
|
|
108
|
+
/**
|
|
109
|
+
* The browser half of the same job.
|
|
110
|
+
*
|
|
111
|
+
* An uncaught throw reaches `window` as an `error` event carrying the original
|
|
112
|
+
* value on `event.error`. Listening rather than assigning `window.onerror`:
|
|
113
|
+
* that property holds one handler, so taking it would evict whatever the host
|
|
114
|
+
* already had there.
|
|
115
|
+
*
|
|
116
|
+
* A framework that catches its own errors — Vue does — never lets them reach
|
|
117
|
+
* here, which is why the Vue package also hangs off `app.config.errorHandler`.
|
|
118
|
+
*/
|
|
119
|
+
function installErrorEventHandler(onError) {
|
|
120
|
+
const target = globalThis;
|
|
121
|
+
if (typeof target.addEventListener !== 'function') {
|
|
122
|
+
return () => { };
|
|
123
|
+
}
|
|
124
|
+
const handler = (event) => {
|
|
125
|
+
try {
|
|
126
|
+
const thrown = event?.error;
|
|
127
|
+
// Some sources report only a message — a cross-origin script, or a
|
|
128
|
+
// `dispatchEvent` of a bare ErrorEvent. Better a typed message than
|
|
129
|
+
// dropping the error.
|
|
130
|
+
const value = thrown ?? event?.message ?? event;
|
|
131
|
+
onError(describeError(value, false));
|
|
132
|
+
}
|
|
133
|
+
catch {
|
|
134
|
+
// Never interfere with the host's own error handling.
|
|
135
|
+
}
|
|
136
|
+
};
|
|
137
|
+
try {
|
|
138
|
+
target.addEventListener('error', handler);
|
|
139
|
+
}
|
|
140
|
+
catch {
|
|
141
|
+
return () => { };
|
|
142
|
+
}
|
|
143
|
+
return () => {
|
|
144
|
+
try {
|
|
145
|
+
target.removeEventListener?.('error', handler);
|
|
146
|
+
}
|
|
147
|
+
catch {
|
|
148
|
+
// Ignore.
|
|
149
|
+
}
|
|
150
|
+
};
|
|
151
|
+
}
|
|
152
|
+
function installRejectionHandler(onError) {
|
|
153
|
+
const target = globalThis;
|
|
154
|
+
if (typeof target.addEventListener !== 'function') {
|
|
155
|
+
return () => { };
|
|
156
|
+
}
|
|
157
|
+
const handler = (event) => {
|
|
158
|
+
try {
|
|
159
|
+
const reason = event?.reason ?? event;
|
|
160
|
+
const captured = describeError(reason, false);
|
|
161
|
+
captured.type = captured.type === 'Error' ? 'UnhandledRejection' : captured.type;
|
|
162
|
+
onError(captured);
|
|
163
|
+
}
|
|
164
|
+
catch {
|
|
165
|
+
// Never interfere with the host's own rejection handling.
|
|
166
|
+
}
|
|
167
|
+
};
|
|
168
|
+
try {
|
|
169
|
+
target.addEventListener('unhandledrejection', handler);
|
|
170
|
+
}
|
|
171
|
+
catch {
|
|
172
|
+
return () => { };
|
|
173
|
+
}
|
|
174
|
+
return () => {
|
|
175
|
+
try {
|
|
176
|
+
target.removeEventListener?.('unhandledrejection', handler);
|
|
177
|
+
}
|
|
178
|
+
catch {
|
|
179
|
+
// Ignore.
|
|
180
|
+
}
|
|
181
|
+
};
|
|
182
|
+
}
|
|
183
|
+
/** Test-only. */
|
|
184
|
+
export function resetErrorHandlerState() {
|
|
185
|
+
installed = false;
|
|
186
|
+
}
|
package/dist/ids.d.ts
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Identifiers and hashing.
|
|
3
|
+
*
|
|
4
|
+
* ponytail: no uuid dependency. A UUID library costs bundle size for a
|
|
5
|
+
* guarantee this does not need — event IDs only have to be unique per device,
|
|
6
|
+
* and the backend deduplicates by `eventId` anyway (section 16).
|
|
7
|
+
*/
|
|
8
|
+
/**
|
|
9
|
+
* Generate a prefixed identifier.
|
|
10
|
+
*
|
|
11
|
+
* Timestamp gives ordering and uniqueness across restarts; the random suffix
|
|
12
|
+
* separates events created within the same millisecond, which happens
|
|
13
|
+
* constantly during a burst of captures.
|
|
14
|
+
*/
|
|
15
|
+
export declare function createId(prefix: string): string;
|
|
16
|
+
/**
|
|
17
|
+
* FNV-1a, 32-bit.
|
|
18
|
+
*
|
|
19
|
+
* Used only to turn a session ID into a stable sampling decision. Not a
|
|
20
|
+
* security primitive and never used as one.
|
|
21
|
+
*/
|
|
22
|
+
export declare function hashString(input: string): number;
|
|
23
|
+
/**
|
|
24
|
+
* Decide whether a session is captured.
|
|
25
|
+
*
|
|
26
|
+
* Deterministic in `sessionId`, so the same session always resolves the same
|
|
27
|
+
* way and the decision can be made once at session start (section 35).
|
|
28
|
+
*/
|
|
29
|
+
export declare function isSampled(sessionId: string, sampleRate: number): boolean;
|
package/dist/ids.js
ADDED
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Identifiers and hashing.
|
|
3
|
+
*
|
|
4
|
+
* ponytail: no uuid dependency. A UUID library costs bundle size for a
|
|
5
|
+
* guarantee this does not need — event IDs only have to be unique per device,
|
|
6
|
+
* and the backend deduplicates by `eventId` anyway (section 16).
|
|
7
|
+
*/
|
|
8
|
+
/**
|
|
9
|
+
* Generate a prefixed identifier.
|
|
10
|
+
*
|
|
11
|
+
* Timestamp gives ordering and uniqueness across restarts; the random suffix
|
|
12
|
+
* separates events created within the same millisecond, which happens
|
|
13
|
+
* constantly during a burst of captures.
|
|
14
|
+
*/
|
|
15
|
+
export function createId(prefix) {
|
|
16
|
+
const time = Date.now().toString(36);
|
|
17
|
+
const random = Math.random().toString(36).slice(2, 10);
|
|
18
|
+
return `${prefix}_${time}${random}`;
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* FNV-1a, 32-bit.
|
|
22
|
+
*
|
|
23
|
+
* Used only to turn a session ID into a stable sampling decision. Not a
|
|
24
|
+
* security primitive and never used as one.
|
|
25
|
+
*/
|
|
26
|
+
export function hashString(input) {
|
|
27
|
+
let hash = 0x811c9dc5;
|
|
28
|
+
for (let i = 0; i < input.length; i += 1) {
|
|
29
|
+
hash ^= input.charCodeAt(i);
|
|
30
|
+
// Math.imul, because a plain `hash * 16777619` exceeds 2^53 and silently
|
|
31
|
+
// loses precision.
|
|
32
|
+
hash = Math.imul(hash, 0x01000193);
|
|
33
|
+
}
|
|
34
|
+
// FNV-1a alone leaves the high bits poorly mixed for short, structurally
|
|
35
|
+
// similar inputs — and the sampling decision reads exactly those bits, so
|
|
36
|
+
// the bias shows up directly as capturing the wrong fraction of sessions.
|
|
37
|
+
// This is MurmurHash3's finalizer, which is the cheap standard fix.
|
|
38
|
+
hash ^= hash >>> 16;
|
|
39
|
+
hash = Math.imul(hash, 0x85ebca6b);
|
|
40
|
+
hash ^= hash >>> 13;
|
|
41
|
+
hash = Math.imul(hash, 0xc2b2ae35);
|
|
42
|
+
hash ^= hash >>> 16;
|
|
43
|
+
return hash >>> 0;
|
|
44
|
+
}
|
|
45
|
+
/**
|
|
46
|
+
* Decide whether a session is captured.
|
|
47
|
+
*
|
|
48
|
+
* Deterministic in `sessionId`, so the same session always resolves the same
|
|
49
|
+
* way and the decision can be made once at session start (section 35).
|
|
50
|
+
*/
|
|
51
|
+
export function isSampled(sessionId, sampleRate) {
|
|
52
|
+
if (sampleRate >= 1)
|
|
53
|
+
return true;
|
|
54
|
+
if (sampleRate <= 0)
|
|
55
|
+
return false;
|
|
56
|
+
// 32-bit space scaled to [0, 1).
|
|
57
|
+
return hashString(sessionId) / 0x100000000 < sampleRate;
|
|
58
|
+
}
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @nagoorkani/session-capture-core
|
|
3
|
+
*
|
|
4
|
+
* Everything the SDK does that is not about a platform: sessions, sampling,
|
|
5
|
+
* batching, the durable queue, redaction, remote config, transport, and the
|
|
6
|
+
* error/network/performance capture that hangs off globals a browser and a
|
|
7
|
+
* React Native runtime both provide.
|
|
8
|
+
*
|
|
9
|
+
* It installs nothing by itself and imports no platform module. A platform
|
|
10
|
+
* package — `@nagoorkani/session-capture-expo`, `@nagoorkani/session-capture-vue` — supplies the
|
|
11
|
+
* three things that genuinely differ: where bytes are stored, how the host
|
|
12
|
+
* signals foreground and background, and what the device is. Everything else
|
|
13
|
+
* living here rather than in each of them is the point: a second copy of the
|
|
14
|
+
* redaction and sampling rules is exactly the drift the privacy invariant
|
|
15
|
+
* exists to prevent.
|
|
16
|
+
*
|
|
17
|
+
* Re-exported wholesale rather than curated. The consumers are the platform
|
|
18
|
+
* packages in this repository, not the public — each of those exports its own
|
|
19
|
+
* narrow surface, and a hand-picked list here would be a third one to keep in
|
|
20
|
+
* step.
|
|
21
|
+
*/
|
|
22
|
+
export * from './batcher.ts';
|
|
23
|
+
export * from './breadcrumbs.ts';
|
|
24
|
+
export * from './config.ts';
|
|
25
|
+
export * from './container.ts';
|
|
26
|
+
export * from './core.ts';
|
|
27
|
+
export * from './dispatcher.ts';
|
|
28
|
+
export * from './errors.ts';
|
|
29
|
+
export * from './ids.ts';
|
|
30
|
+
export * from './network.ts';
|
|
31
|
+
export * from './performance.ts';
|
|
32
|
+
export * from './queue.ts';
|
|
33
|
+
export * from './redact.ts';
|
|
34
|
+
export * from './replay-gate.ts';
|
|
35
|
+
export * from './safe.ts';
|
|
36
|
+
export * from './session.ts';
|
|
37
|
+
export * from './store.ts';
|
|
38
|
+
export * from './transport.ts';
|
|
39
|
+
export * from './types.ts';
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @nagoorkani/session-capture-core
|
|
3
|
+
*
|
|
4
|
+
* Everything the SDK does that is not about a platform: sessions, sampling,
|
|
5
|
+
* batching, the durable queue, redaction, remote config, transport, and the
|
|
6
|
+
* error/network/performance capture that hangs off globals a browser and a
|
|
7
|
+
* React Native runtime both provide.
|
|
8
|
+
*
|
|
9
|
+
* It installs nothing by itself and imports no platform module. A platform
|
|
10
|
+
* package — `@nagoorkani/session-capture-expo`, `@nagoorkani/session-capture-vue` — supplies the
|
|
11
|
+
* three things that genuinely differ: where bytes are stored, how the host
|
|
12
|
+
* signals foreground and background, and what the device is. Everything else
|
|
13
|
+
* living here rather than in each of them is the point: a second copy of the
|
|
14
|
+
* redaction and sampling rules is exactly the drift the privacy invariant
|
|
15
|
+
* exists to prevent.
|
|
16
|
+
*
|
|
17
|
+
* Re-exported wholesale rather than curated. The consumers are the platform
|
|
18
|
+
* packages in this repository, not the public — each of those exports its own
|
|
19
|
+
* narrow surface, and a hand-picked list here would be a third one to keep in
|
|
20
|
+
* step.
|
|
21
|
+
*/
|
|
22
|
+
export * from "./batcher.js";
|
|
23
|
+
export * from "./breadcrumbs.js";
|
|
24
|
+
export * from "./config.js";
|
|
25
|
+
export * from "./container.js";
|
|
26
|
+
export * from "./core.js";
|
|
27
|
+
export * from "./dispatcher.js";
|
|
28
|
+
export * from "./errors.js";
|
|
29
|
+
export * from "./ids.js";
|
|
30
|
+
export * from "./network.js";
|
|
31
|
+
export * from "./performance.js";
|
|
32
|
+
export * from "./queue.js";
|
|
33
|
+
export * from "./redact.js";
|
|
34
|
+
export * from "./replay-gate.js";
|
|
35
|
+
export * from "./safe.js";
|
|
36
|
+
export * from "./session.js";
|
|
37
|
+
export * from "./store.js";
|
|
38
|
+
export * from "./transport.js";
|
|
39
|
+
export * from "./types.js";
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Network capture.
|
|
3
|
+
*
|
|
4
|
+
* This module monkey-patches `XMLHttpRequest` inside someone else's
|
|
5
|
+
* application. It is the most dangerous code in the SDK, so the rules from
|
|
6
|
+
* section 24 are non-negotiable:
|
|
7
|
+
*
|
|
8
|
+
* - patch once, idempotently — double-wrapping doubles every event
|
|
9
|
+
* - always call through to the original
|
|
10
|
+
* - never swallow an error the app expects to receive
|
|
11
|
+
* - never capture bodies by default
|
|
12
|
+
* - apply the header deny-list at capture time, not later
|
|
13
|
+
* - skip requests to the ingestion endpoint itself
|
|
14
|
+
*
|
|
15
|
+
* That last rule is not optional: without it the SDK observes its own uploads
|
|
16
|
+
* and generates telemetry about generating telemetry, forever.
|
|
17
|
+
*
|
|
18
|
+
* ## Both, because there is no single choke point
|
|
19
|
+
*
|
|
20
|
+
* Bare React Native's `fetch` is `whatwg-fetch`, which runs on top of
|
|
21
|
+
* `XMLHttpRequest` — so an XHR patch sees it. Expo replaces `globalThis.fetch`
|
|
22
|
+
* with a native implementation (`expo/src/winter/runtime.native.ts` installs
|
|
23
|
+
* `expo/fetch` unless `EXPO_PUBLIC_USE_RN_FETCH=1`), and that one never
|
|
24
|
+
* touches XHR. Patching only XHR makes every `fetch()` in an Expo app
|
|
25
|
+
* invisible; patching only `fetch` makes axios and every other XHR client
|
|
26
|
+
* invisible. Both get patched.
|
|
27
|
+
*
|
|
28
|
+
* The two hand off so nothing is reported twice. `whatwg-fetch` calls
|
|
29
|
+
* `xhr.open`/`xhr.send` synchronously inside the Promise executor, so the
|
|
30
|
+
* moment `fetch` returns its promise we already know whether an XHR served it.
|
|
31
|
+
* If one did, the XHR side reports — it has response headers and a buffered
|
|
32
|
+
* body — and the fetch side stays quiet. If none did, the request was native
|
|
33
|
+
* and the fetch side reports.
|
|
34
|
+
*
|
|
35
|
+
* A fetch polyfill that reached XHR *asynchronously* would defeat that and be
|
|
36
|
+
* counted twice. `whatwg-fetch` does not, and it is the only XHR-backed fetch
|
|
37
|
+
* in play.
|
|
38
|
+
*/
|
|
39
|
+
/**
|
|
40
|
+
* Minimal structural types for the fetch surface.
|
|
41
|
+
*
|
|
42
|
+
* The DOM lib is deliberately not enabled: React Native is not a browser, and
|
|
43
|
+
* pulling in `lib.dom` would declare hundreds of globals that do not exist at
|
|
44
|
+
* runtime. These cover exactly what is touched here.
|
|
45
|
+
*/
|
|
46
|
+
type HeaderPairs = readonly (readonly [string, string])[];
|
|
47
|
+
type HeaderLike = {
|
|
48
|
+
forEach: (cb: (value: string, key: string) => void) => void;
|
|
49
|
+
};
|
|
50
|
+
export type HeadersInput = HeaderPairs | HeaderLike | Record<string, string>;
|
|
51
|
+
export interface RequestOptions {
|
|
52
|
+
method?: string;
|
|
53
|
+
headers?: HeadersInput;
|
|
54
|
+
[key: string]: unknown;
|
|
55
|
+
}
|
|
56
|
+
export interface ResponseLike {
|
|
57
|
+
status: number;
|
|
58
|
+
/** WHATWG `Headers`. Reading it does not consume the body. */
|
|
59
|
+
headers?: HeaderLike;
|
|
60
|
+
/** Present on any WHATWG Response. Absent on a hand-rolled stub. */
|
|
61
|
+
clone?: () => {
|
|
62
|
+
text: () => Promise<string>;
|
|
63
|
+
};
|
|
64
|
+
}
|
|
65
|
+
export type FetchLike = (input: unknown, init?: RequestOptions) => Promise<ResponseLike>;
|
|
66
|
+
export interface NetworkEvent {
|
|
67
|
+
url: string;
|
|
68
|
+
method: string;
|
|
69
|
+
status?: number;
|
|
70
|
+
durationMs: number;
|
|
71
|
+
/** Set when the request failed before producing a response. */
|
|
72
|
+
error?: string;
|
|
73
|
+
requestHeaders?: Record<string, unknown>;
|
|
74
|
+
/** XHR only. The fetch fallback cannot see these without holding the response. */
|
|
75
|
+
responseHeaders?: Record<string, unknown>;
|
|
76
|
+
/** Only when `captureBodies` is on, and only for a shape that can be redacted. */
|
|
77
|
+
requestBody?: string;
|
|
78
|
+
responseBody?: string;
|
|
79
|
+
}
|
|
80
|
+
/**
|
|
81
|
+
* Minimal structural types for the XHR surface, for the same reason the fetch
|
|
82
|
+
* ones exist above: `lib.dom` is off.
|
|
83
|
+
*/
|
|
84
|
+
export interface XhrLike {
|
|
85
|
+
open(method: string, url: string, ...rest: unknown[]): void;
|
|
86
|
+
send(body?: unknown): void;
|
|
87
|
+
setRequestHeader(name: string, value: string): void;
|
|
88
|
+
addEventListener(type: string, listener: () => void): void;
|
|
89
|
+
getAllResponseHeaders(): string;
|
|
90
|
+
readonly status: number;
|
|
91
|
+
readonly responseType: string;
|
|
92
|
+
readonly responseText: string;
|
|
93
|
+
}
|
|
94
|
+
export interface NetworkOptions {
|
|
95
|
+
/** Requests to this origin are never captured. */
|
|
96
|
+
ingestEndpoint: string;
|
|
97
|
+
urlDenyList: readonly string[];
|
|
98
|
+
maskedKeys: readonly string[];
|
|
99
|
+
/**
|
|
100
|
+
* Per-project, from remote config, off by default (section 36).
|
|
101
|
+
*
|
|
102
|
+
* Optional on purpose: a caller that forgets it gets no body capture, which
|
|
103
|
+
* is the safe direction to fail in.
|
|
104
|
+
*/
|
|
105
|
+
captureBodies?: boolean;
|
|
106
|
+
onEvent: (event: NetworkEvent) => void;
|
|
107
|
+
now?: () => number;
|
|
108
|
+
}
|
|
109
|
+
type Uninstall = () => void;
|
|
110
|
+
/** Strip query strings before capture: they routinely carry tokens. */
|
|
111
|
+
export declare function sanitizeUrl(url: string): string;
|
|
112
|
+
export declare function shouldCapture(url: string, ingestEndpoint: string, denyList: readonly string[]): boolean;
|
|
113
|
+
/**
|
|
114
|
+
* Install network capture.
|
|
115
|
+
*
|
|
116
|
+
* XHR when the host has it, which in React Native it always does. The `fetch`
|
|
117
|
+
* path is the fallback for a host that does not, and the two are never
|
|
118
|
+
* installed together — see the note at the top of this file.
|
|
119
|
+
*
|
|
120
|
+
* Returns a function that restores the originals.
|
|
121
|
+
*/
|
|
122
|
+
export declare function installNetworkCapture(options: NetworkOptions): Uninstall;
|
|
123
|
+
export {};
|