Press n or j to go to the next uncovered block, b, p or k for the previous block.
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 | 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 5x 5x 5x 1x 1x 1x 14x 14x 1x 2x 2x 2x 1x 1x 18x 18x 18x 18x 1x 2x 2x 2x 1x 18x 18x 3x 18x 1x 1x 18x 18x 1x 1x 8x 8x 5x 5x 5x 5x 5x 3x 3x 1x 1x 1x 41x 41x 41x 41x 41x 41x 1x 1x 1x 36x 36x 36x 36x 36x 36x 1x 1x 36x 36x 36x 1x 1x 1x 1x 1x 1x 1x 1x 38x 38x 30x 30x 3x 3x 3x 3x 3x 3x 3x 3x 3x 3x 30x 5x 5x 1x 1x 1x 1x 5x 5x 30x | import { errorBuffer as errorBufferConfig } from '@/../config.json';
import { CACHE } from '@/constants/common';
import { getErrorMessage, isExpectedAbort } from '@/helpers/exceptions';
import { Logger } from '@/utils/Logger';
import { cstorage } from '@/utils/storage';
const logger = new Logger('errorBuffer');
/**
* A persistent, bounded ring buffer of the most recent runtime exceptions,
* shared across the popup, options page, and service worker via
* `chrome.storage.session`. It feeds the "recent exceptions" section of a bug
* report when the user opens one without a specific error in hand.
*
* Session-scoped on purpose: entries survive a service-worker restart but are
* dropped when the browser closes, so nothing lingers on disk.
*
* @module errorBuffer
* @category Helpers
* @source
*/
/**
* Where a captured error originated: a global window/worker hook, an unhandled
* promise rejection, React's error hooks, an aggregated supplier-search failure,
* or a callback-style `chrome.*` API call that set `chrome.runtime.lastError`.
* @category Helpers
* @group Bug reporting
*/
export type ErrorSource = 'window' | 'unhandledrejection' | 'react' | 'search' | 'chrome-api';
/**
* A single captured exception, trimmed to what a bug report needs.
* @category Helpers
* @group Bug reporting
*/
export interface CapturedError {
/** Capture time, epoch milliseconds. */
ts: number;
/** Which global hook (or React) surfaced the error. */
source: ErrorSource;
/** The error message. */
message: string;
/** The stack trace, already truncated. */
stack?: string;
/** The React component stack that was rendering when the error was thrown, if known. */
componentStack?: string;
}
/**
* Maximum number of exceptions retained; older entries are discarded. From
* `config.json` (`errorBuffer.maxErrors`).
*/
const MAX_ERRORS = errorBufferConfig.maxErrors;
/** `chrome.storage.session` key holding the serialized ring buffer. */
const STORAGE_KEY = CACHE.ERROR_RING_BUFFER;
/**
* Cap on a single stored stack trace, so one huge trace can't dominate. From
* `config.json` (`errorBuffer.stackLimit`).
*/
const STACK_LIMIT = errorBufferConfig.stackLimit;
/** Serializes concurrent writes so a read-modify-write can't lose entries. */
let writeChain: Promise<void> = Promise.resolve();
/** Guards {@link installErrorCapture} against double-registration. */
let captureInstalled = false;
/**
* Truncates a string to `limit` characters, appending an ellipsis marker when cut.
* @param text - The text to bound.
* @param limit - Maximum length to keep.
* @returns The original text, or a truncated copy with a marker.
* @example
* ```ts
* truncate("abcdef", 3); // => "abc…"
* ```
* @source
*/
function truncate(text: string, limit: number): string {
return text.length <= limit ? text : `${text.slice(0, limit)}…`;
}
/**
* Renders an `Error` together with its `cause` chain (ES2022) into a single
* stack string, so a wrapped error's root cause isn't lost. Non-`Error` causes
* are stringified; the walk is depth-limited to guard against cyclic or
* pathologically deep chains.
* @param error - The error to render.
* @returns The stack (or `name: message`) plus each `Caused by:` link.
* @example
* ```ts
* formatErrorChain(new Error("outer", { cause: new Error("inner") }));
* // => "Error: outer\n…\nCaused by: Error: inner\n…"
* ```
* @source
*/
export function formatErrorChain(error: Error): string {
return renderErrorChain(error, 0);
}
/** Indents every line of `text` by two spaces (for nested error rendering). */
function indentLines(text: string): string {
return text.replace(/\n/g, '\n ');
}
/**
* Recursive worker for {@link formatErrorChain}: renders an error's stack, then
* its aggregated sub-errors (`AggregateError.errors`) and its `cause`, each
* indented and depth-limited to guard against cyclic or very deep chains.
* @param error - The error to render.
* @param depth - Current recursion depth.
* @returns The rendered stack plus nested sub-errors and causes.
* @source
*/
function renderErrorChain(error: Error, depth: number): string {
const parts = [error.stack ?? `${error.name}: ${error.message}`];
if (depth >= 5) return parts.join('\n');
if (error instanceof AggregateError && Array.isArray(error.errors)) {
error.errors.forEach((sub: unknown, index) => {
const rendered = sub instanceof Error ? renderErrorChain(sub, depth + 1) : String(sub);
parts.push(indentLines(`[${index}] ${rendered}`));
});
}
const cause: unknown = Reflect.get(error, 'cause');
if (cause instanceof Error) {
parts.push(`Caused by: ${renderErrorChain(cause, depth + 1)}`);
} else if (cause != null) {
parts.push(`Caused by: ${String(cause)}`);
}
return parts.join('\n');
}
/**
* Normalizes an arbitrary thrown value (or rejection reason) into a
* `{ message, stack }` pair, folding any `cause` chain into the stack. Non-`Error`
* values are coerced to a string message.
* @param reason - The thrown value or rejection reason.
* @returns The extracted message and truncated stack.
* @example
* ```ts
* describeError(new Error("boom")); // => { message: "boom", stack: "Error: boom\n…" }
* describeError("nope"); // => { message: "nope" }
* ```
* @source
*/
function describeError(reason: unknown): { message: string; stack?: string } {
if (reason instanceof Error) {
return {
message: reason.message,
stack: truncate(formatErrorChain(reason), STACK_LIMIT),
};
}
return { message: String(reason) };
}
/**
* Reads the current ring buffer from session storage, tolerating a missing or
* malformed value by returning an empty list.
* @returns The stored exceptions, oldest first.
* @example
* ```ts
* const errors = await getRecentErrors();
* errors.length; // 0..MAX_ERRORS
* ```
* @source
*/
export async function getRecentErrors(): Promise<CapturedError[]> {
try {
const stored = await cstorage.session.get(STORAGE_KEY);
const value: unknown = stored[STORAGE_KEY];
return Array.isArray(value) ? value : [];
} catch {
return [];
}
}
/**
* Appends one exception to the ring buffer, trimming to the most recent
* `MAX_ERRORS`. Never throws — a failure to record must not cascade into
* the code path that raised the original error. Writes are serialized so
* concurrent captures don't clobber each other.
* @param entry - The exception to record, minus its timestamp.
* @returns A promise that resolves once the write settles.
* @example
* ```ts
* await recordError({ source: "react", message: "render failed" });
* ```
* @source
*/
export async function recordError(entry: Omit<CapturedError, 'ts'>): Promise<void> {
writeChain = writeChain.then(async () => {
try {
const current = await getRecentErrors();
const next = [...current, { ...entry, ts: Date.now() }].slice(-MAX_ERRORS);
await cstorage.session.set({ [STORAGE_KEY]: next });
} catch {
// Best-effort: a diagnostic buffer must never surface its own failures.
}
});
return writeChain;
}
/**
* Records an arbitrary thrown value into the ring buffer, folding its `cause`
* chain (and any `AggregateError` sub-errors) into the stored stack. Convenience
* over {@link recordError} for callers that hold the raw error.
* @param reason - The thrown value or rejection reason.
* @param source - Where the error originated.
* @returns A promise that resolves once the write settles.
* @example
* ```ts
* await recordException(new AggregateError(errs, "search failed"), "search");
* ```
* @source
*/
export async function recordException(reason: unknown, source: ErrorSource): Promise<void> {
return recordError({ source, ...describeError(reason) });
}
/**
* Registers global `error` and `unhandledrejection` listeners that push captured
* exceptions into the ring buffer. Idempotent, and safe in both window and
* service-worker contexts (both expose `self` with `addEventListener`).
* @returns Nothing.
* @example
* ```ts
* installErrorCapture(); // call once per context, before the app runs
* ```
* @source
*/
export function installErrorCapture(): void {
if (captureInstalled) return;
if (typeof self === 'undefined' || typeof self.addEventListener !== 'function') return;
captureInstalled = true;
self.addEventListener('error', (event: ErrorEvent) => {
const described = event.error ? describeError(event.error) : { message: event.message };
// An exception nothing caught: this page's work stops, so it is fatal.
logger.fatal(`Uncaught exception: ${described.message}`, {
error: event.error,
filename: event.filename,
lineno: event.lineno,
colno: event.colno,
});
void recordError({ source: 'window', ...described });
});
self.addEventListener('unhandledrejection', (event: PromiseRejectionEvent) => {
// A stopped search rejects with its abort reason; that is expected, not a bug.
if (!isExpectedAbort(event.reason)) {
logger.error(`Unhandled promise rejection: ${getErrorMessage(event.reason)}`, {
error: event.reason,
});
}
void recordError({ source: 'unhandledrejection', ...describeError(event.reason) });
});
}
|