plugin API (#598)

* temp: plugin API

* fix a bug in the replay handler and rename some type names.

* update integration test

* improve plugin types and handle legacy log data

* use different naming in record and replay bundles

* delete unreferenced types

Co-authored-by: Lucky Feng <294889365@qq.com>
This commit is contained in:
yz-yu
2026-04-01 12:00:00 +08:00
committed by GitHub
parent e7583f71b2
commit c550a4b088
20 changed files with 753 additions and 579 deletions

View File

@@ -0,0 +1,255 @@
// tslint:disable
/**
* Class StackFrame is a fork of https://github.com/stacktracejs/stackframe/blob/master/stackframe.js
* I fork it because:
* 1. There are some build issues when importing this package.
* 2. Rewrites into typescript give us a better type interface.
* 3. StackFrame contains some functions we don't need.
*/
export class StackFrame {
private fileName: string;
private functionName: string;
private lineNumber?: number;
private columnNumber?: number;
constructor(obj: {
fileName?: string;
functionName?: string;
lineNumber?: number;
columnNumber?: number;
}) {
this.fileName = obj.fileName || '';
this.functionName = obj.functionName || '';
this.lineNumber = obj.lineNumber;
this.columnNumber = obj.columnNumber;
}
toString() {
const lineNumber = this.lineNumber || '';
const columnNumber = this.columnNumber || '';
if (this.functionName) {
return (
this.functionName +
' (' +
this.fileName +
':' +
lineNumber +
':' +
columnNumber +
')'
);
}
return this.fileName + ':' + lineNumber + ':' + columnNumber;
}
}
/**
* ErrorStackParser is a fork of https://github.com/stacktracejs/error-stack-parser/blob/master/error-stack-parser.js
* I fork it because:
* 1. There are some build issues when importing this package.
* 2. Rewrites into typescript give us a better type interface.
*/
const FIREFOX_SAFARI_STACK_REGEXP = /(^|@)\S+:\d+/;
const CHROME_IE_STACK_REGEXP = /^\s*at .*(\S+:\d+|\(native\))/m;
const SAFARI_NATIVE_CODE_REGEXP = /^(eval@)?(\[native code])?$/;
export const ErrorStackParser = {
/**
* Given an Error object, extract the most information from it.
*
* @param {Error} error object
* @return {Array} of StackFrames
*/
parse: function (error: Error): StackFrame[] {
if (
// @ts-ignore
typeof error.stacktrace !== 'undefined' ||
// @ts-ignore
typeof error['opera#sourceloc'] !== 'undefined'
) {
return this.parseOpera(
error as {
stacktrace?: string;
message: string;
stack?: string;
},
);
} else if (error.stack && error.stack.match(CHROME_IE_STACK_REGEXP)) {
return this.parseV8OrIE(error as { stack: string });
} else if (error.stack) {
return this.parseFFOrSafari(error as { stack: string });
} else {
throw new Error('Cannot parse given Error object');
}
},
// Separate line and column numbers from a string of the form: (URI:Line:Column)
extractLocation: function (urlLike: string) {
// Fail-fast but return locations like "(native)"
if (urlLike.indexOf(':') === -1) {
return [urlLike];
}
const regExp = /(.+?)(?::(\d+))?(?::(\d+))?$/;
const parts = regExp.exec(urlLike.replace(/[()]/g, ''));
if (!parts) throw new Error(`Cannot parse given url: ${urlLike}`);
return [parts[1], parts[2] || undefined, parts[3] || undefined];
},
parseV8OrIE: function (error: { stack: string }) {
const filtered = error.stack.split('\n').filter(function (line) {
return !!line.match(CHROME_IE_STACK_REGEXP);
}, this);
return filtered.map(function (line) {
if (line.indexOf('(eval ') > -1) {
// Throw away eval information until we implement stacktrace.js/stackframe#8
line = line
.replace(/eval code/g, 'eval')
.replace(/(\(eval at [^()]*)|(\),.*$)/g, '');
}
let sanitizedLine = line.replace(/^\s+/, '').replace(/\(eval code/g, '(');
// capture and preseve the parenthesized location "(/foo/my bar.js:12:87)" in
// case it has spaces in it, as the string is split on \s+ later on
const location = sanitizedLine.match(/ (\((.+):(\d+):(\d+)\)$)/);
// remove the parenthesized location from the line, if it was matched
sanitizedLine = location
? sanitizedLine.replace(location[0], '')
: sanitizedLine;
const tokens = sanitizedLine.split(/\s+/).slice(1);
// if a location was matched, pass it to extractLocation() otherwise pop the last token
const locationParts = this.extractLocation(
location ? location[1] : tokens.pop(),
);
const functionName = tokens.join(' ') || undefined;
const fileName =
['eval', '<anonymous>'].indexOf(locationParts[0]) > -1
? undefined
: locationParts[0];
return new StackFrame({
functionName,
fileName,
lineNumber: locationParts[1],
columnNumber: locationParts[2],
});
}, this);
},
parseFFOrSafari: function (error: { stack: string }) {
const filtered = error.stack.split('\n').filter(function (line) {
return !line.match(SAFARI_NATIVE_CODE_REGEXP);
}, this);
return filtered.map(function (line) {
// Throw away eval information until we implement stacktrace.js/stackframe#8
if (line.indexOf(' > eval') > -1) {
line = line.replace(
/ line (\d+)(?: > eval line \d+)* > eval:\d+:\d+/g,
':$1',
);
}
if (line.indexOf('@') === -1 && line.indexOf(':') === -1) {
// Safari eval frames only have function names and nothing else
return new StackFrame({
functionName: line,
});
} else {
const functionNameRegex = /((.*".+"[^@]*)?[^@]*)(?:@)/;
const matches = line.match(functionNameRegex);
const functionName = matches && matches[1] ? matches[1] : undefined;
const locationParts = this.extractLocation(
line.replace(functionNameRegex, ''),
);
return new StackFrame({
functionName,
fileName: locationParts[0],
lineNumber: locationParts[1],
columnNumber: locationParts[2],
});
}
}, this);
},
parseOpera: function (e: {
stacktrace?: string;
message: string;
stack?: string;
}): StackFrame[] {
if (
!e.stacktrace ||
(e.message.indexOf('\n') > -1 &&
e.message.split('\n').length > e.stacktrace.split('\n').length)
) {
return this.parseOpera9(e as { message: string });
} else if (!e.stack) {
return this.parseOpera10(e as { stacktrace: string });
} else {
return this.parseOpera11(e as { stack: string });
}
},
parseOpera9: function (e: { message: string }) {
const lineRE = /Line (\d+).*script (?:in )?(\S+)/i;
const lines = e.message.split('\n');
const result = [];
for (let i = 2, len = lines.length; i < len; i += 2) {
const match = lineRE.exec(lines[i]);
if (match) {
result.push(
new StackFrame({
fileName: match[2],
lineNumber: parseFloat(match[1]),
}),
);
}
}
return result;
},
parseOpera10: function (e: { stacktrace: string }) {
const lineRE = /Line (\d+).*script (?:in )?(\S+)(?:: In function (\S+))?$/i;
const lines = e.stacktrace.split('\n');
const result = [];
for (let i = 0, len = lines.length; i < len; i += 2) {
const match = lineRE.exec(lines[i]);
if (match) {
result.push(
new StackFrame({
functionName: match[3] || undefined,
fileName: match[2],
lineNumber: parseFloat(match[1]),
}),
);
}
}
return result;
},
// Opera 10.65+ Error.stack very similar to FF/Safari
parseOpera11: function (error: { stack: string }) {
const filtered = error.stack.split('\n').filter(function (line) {
return (
!!line.match(FIREFOX_SAFARI_STACK_REGEXP) &&
!line.match(/^Error created at/)
);
}, this);
return filtered.map(function (line: string) {
const tokens = line.split('@');
const locationParts = this.extractLocation(tokens.pop());
const functionCall = tokens.shift() || '';
const functionName =
functionCall
.replace(/<anonymous function(: (\w+))?>/, '$2')
.replace(/\([^)]*\)/g, '') || undefined;
return new StackFrame({
functionName,
fileName: locationParts[0],
lineNumber: locationParts[1],
columnNumber: locationParts[2],
});
}, this);
},
};

View File

@@ -0,0 +1,203 @@
import { listenerHandler, RecordPlugin } from '../../../types';
import { stringify } from './stringify';
import { StackFrame, ErrorStackParser } from './error-stack-parser';
import { patch } from '../../../utils';
export type StringifyOptions = {
// limit of string length
stringLengthLimit?: number;
/**
* limit of number of keys in an object
* if an object contains more keys than this limit, we would call its toString function directly
*/
numOfKeysLimit: number;
};
type LogRecordOptions = {
level?: LogLevel[] | undefined;
lengthThreshold?: number;
stringifyOptions?: StringifyOptions;
logger?: Logger;
};
const defaultLogOptions: LogRecordOptions = {
level: [
'assert',
'clear',
'count',
'countReset',
'debug',
'dir',
'dirxml',
'error',
'group',
'groupCollapsed',
'groupEnd',
'info',
'log',
'table',
'time',
'timeEnd',
'timeLog',
'trace',
'warn',
],
lengthThreshold: 1000,
logger: console,
};
export type LogData = {
level: LogLevel;
trace: string[];
payload: string[];
};
type logCallback = (p: LogData) => void;
export type LogLevel =
| 'assert'
| 'clear'
| 'count'
| 'countReset'
| 'debug'
| 'dir'
| 'dirxml'
| 'error'
| 'group'
| 'groupCollapsed'
| 'groupEnd'
| 'info'
| 'log'
| 'table'
| 'time'
| 'timeEnd'
| 'timeLog'
| 'trace'
| 'warn';
/* fork from interface Console */
// all kinds of console functions
export type Logger = {
assert?: typeof console.assert;
clear?: typeof console.clear;
count?: typeof console.count;
countReset?: typeof console.countReset;
debug?: typeof console.debug;
dir?: typeof console.dir;
dirxml?: typeof console.dirxml;
error?: typeof console.error;
group?: typeof console.group;
groupCollapsed?: typeof console.groupCollapsed;
groupEnd?: () => void;
info?: typeof console.info;
log?: typeof console.log;
table?: typeof console.table;
time?: typeof console.time;
timeEnd?: typeof console.timeEnd;
timeLog?: typeof console.timeLog;
trace?: typeof console.trace;
warn?: typeof console.warn;
};
function initLogObserver(
cb: logCallback,
logOptions: LogRecordOptions,
): listenerHandler {
const logger = logOptions.logger;
if (!logger) {
return () => {};
}
let logCount = 0;
const cancelHandlers: listenerHandler[] = [];
// add listener to thrown errors
if (logOptions.level!.includes('error')) {
if (window) {
const originalOnError = window.onerror;
window.onerror = (
msg: Event | string,
file: string,
line: number,
col: number,
error: Error,
) => {
if (originalOnError) {
originalOnError.apply(this, [msg, file, line, col, error]);
}
const trace: string[] = ErrorStackParser.parse(
error,
).map((stackFrame: StackFrame) => stackFrame.toString());
const payload = [stringify(msg, logOptions.stringifyOptions)];
cb({
level: 'error',
trace,
payload,
});
};
cancelHandlers.push(() => {
window.onerror = originalOnError;
});
}
}
for (const levelType of logOptions.level!) {
cancelHandlers.push(replace(logger, levelType));
}
return () => {
cancelHandlers.forEach((h) => h());
};
/**
* replace the original console function and record logs
* @param logger the logger object such as Console
* @param level the name of log function to be replaced
*/
function replace(_logger: Logger, level: LogLevel) {
if (!_logger[level]) {
return () => {};
}
// replace the logger.{level}. return a restore function
return patch(_logger, level, (original) => {
return (...args: Array<unknown>) => {
original.apply(this, args);
try {
const trace = ErrorStackParser.parse(new Error())
.map((stackFrame: StackFrame) => stackFrame.toString())
.splice(1); // splice(1) to omit the hijacked log function
const payload = args.map((s) =>
stringify(s, logOptions.stringifyOptions),
);
logCount++;
if (logCount < logOptions.lengthThreshold!) {
cb({
level,
trace,
payload,
});
} else if (logCount === logOptions.lengthThreshold) {
// notify the user
cb({
level: 'warn',
trace: [],
payload: [
stringify('The number of log records reached the threshold.'),
],
});
}
} catch (error) {
original('rrweb logger error:', error, ...args);
}
};
});
}
}
export const PLUGIN_NAME = 'rrweb/console@1';
export const getRecordConsolePlugin: (
options?: LogRecordOptions,
) => RecordPlugin = (options) => ({
name: PLUGIN_NAME,
observer: initLogObserver,
options: options
? Object.assign({}, defaultLogOptions, options)
: defaultLogOptions,
});

View File

@@ -0,0 +1,143 @@
// tslint:disable:no-any no-bitwise forin
/**
* this file is used to serialize log message to string
*
*/
import { StringifyOptions } from './index';
/**
* transfer the node path in Event to string
* @param node the first node in a node path array
*/
function pathToSelector(node: HTMLElement): string | '' {
if (!node || !node.outerHTML) {
return '';
}
let path = '';
while (node.parentElement) {
let name = node.localName;
if (!name) {
break;
}
name = name.toLowerCase();
let parent = node.parentElement;
let domSiblings = [];
if (parent.children && parent.children.length > 0) {
// tslint:disable-next-line:prefer-for-of
for (let i = 0; i < parent.children.length; i++) {
let sibling = parent.children[i];
if (sibling.localName && sibling.localName.toLowerCase) {
if (sibling.localName.toLowerCase() === name) {
domSiblings.push(sibling);
}
}
}
}
if (domSiblings.length > 1) {
name += ':eq(' + domSiblings.indexOf(node) + ')';
}
path = name + (path ? '>' + path : '');
node = parent;
}
return path;
}
/**
* stringify any js object
* @param obj the object to stringify
*/
export function stringify(
obj: any,
stringifyOptions?: StringifyOptions,
): string {
const options: StringifyOptions = {
numOfKeysLimit: 50,
};
Object.assign(options, stringifyOptions);
const stack: any[] = [];
const keys: any[] = [];
return JSON.stringify(obj, function (key, value) {
/**
* forked from https://github.com/moll/json-stringify-safe/blob/master/stringify.js
* to deCycle the object
*/
if (stack.length > 0) {
const thisPos = stack.indexOf(this);
~thisPos ? stack.splice(thisPos + 1) : stack.push(this);
~thisPos ? keys.splice(thisPos, Infinity, key) : keys.push(key);
if (~stack.indexOf(value)) {
if (stack[0] === value) {
value = '[Circular ~]';
} else {
value =
'[Circular ~.' +
keys.slice(0, stack.indexOf(value)).join('.') +
']';
}
}
} else {
stack.push(value);
}
/* END of the FORK */
if (value === null || value === undefined) {
return value;
}
if (shouldToString(value)) {
return toString(value);
}
if (value instanceof Event) {
const eventResult: any = {};
for (const eventKey in value) {
const eventValue = (value as any)[eventKey];
if (Array.isArray(eventValue)) {
eventResult[eventKey] = pathToSelector(
eventValue.length ? eventValue[0] : null,
);
} else {
eventResult[eventKey] = eventValue;
}
}
return eventResult;
} else if (value instanceof Node) {
if (value instanceof HTMLElement) {
return value ? value.outerHTML : '';
}
return value.nodeName;
}
return value;
});
/**
* whether we should call toString function of this object
*/
function shouldToString(_obj: object): boolean {
if (
typeof _obj === 'object' &&
Object.keys(_obj).length > options.numOfKeysLimit
) {
return true;
}
if (typeof _obj === 'function') {
return true;
}
return false;
}
/**
* limit the toString() result according to option
*/
function toString(_obj: object): string {
let str = _obj.toString();
if (options.stringLengthLimit && str.length > options.stringLengthLimit) {
str = `${str.slice(0, options.stringLengthLimit)}...`;
}
return str;
}
}

View File

@@ -0,0 +1,144 @@
import { LogLevel, LogData, PLUGIN_NAME } from '../record';
import {
eventWithTime,
EventType,
IncrementalSource,
ReplayPlugin,
} from '../../../types';
/**
* define an interface to replay log records
* (data: logData) => void> function to display the log data
*/
type ReplayLogger = Partial<Record<LogLevel, (data: LogData) => void>>;
type LogReplayConfig = {
level?: LogLevel[] | undefined;
replayLogger: ReplayLogger | undefined;
};
const ORIGINAL_ATTRIBUTE_NAME = '__rrweb_original__';
type PatchedConsoleLog = {
[ORIGINAL_ATTRIBUTE_NAME]: typeof console.log;
};
const defaultLogConfig: LogReplayConfig = {
level: [
'assert',
'clear',
'count',
'countReset',
'debug',
'dir',
'dirxml',
'error',
'group',
'groupCollapsed',
'groupEnd',
'info',
'log',
'table',
'time',
'timeEnd',
'timeLog',
'trace',
'warn',
],
replayLogger: undefined,
};
class LogReplayPlugin {
private config: LogReplayConfig;
constructor(config?: LogReplayConfig) {
this.config = Object.assign(defaultLogConfig, config);
}
/**
* generate a console log replayer which implement the interface ReplayLogger
*/
public getConsoleLogger(): ReplayLogger {
const replayLogger: ReplayLogger = {};
for (const level of this.config.level!) {
if (level === 'trace') {
replayLogger[level] = (data: LogData) => {
const logger = ((console.log as unknown) as PatchedConsoleLog)[
ORIGINAL_ATTRIBUTE_NAME
]
? ((console.log as unknown) as PatchedConsoleLog)[
ORIGINAL_ATTRIBUTE_NAME
]
: console.log;
logger(
...data.payload.map((s) => JSON.parse(s)),
this.formatMessage(data),
);
};
} else {
replayLogger[level] = (data: LogData) => {
const logger = ((console[level] as unknown) as PatchedConsoleLog)[
ORIGINAL_ATTRIBUTE_NAME
]
? ((console[level] as unknown) as PatchedConsoleLog)[
ORIGINAL_ATTRIBUTE_NAME
]
: console[level];
logger(
...data.payload.map((s) => JSON.parse(s)),
this.formatMessage(data),
);
};
}
}
return replayLogger;
}
/**
* format the trace data to a string
* @param data the log data
*/
private formatMessage(data: LogData): string {
if (data.trace.length === 0) {
return '';
}
const stackPrefix = '\n\tat ';
let result = stackPrefix;
result += data.trace.join(stackPrefix);
return result;
}
}
export const getLogReplayPlugin: (options?: LogReplayConfig) => ReplayPlugin = (
options,
) => {
const replayLogger =
options?.replayLogger || new LogReplayPlugin(options).getConsoleLogger();
return {
handler(event: eventWithTime, _isSync, context) {
let logData: LogData | null = null;
if (
event.type === EventType.IncrementalSnapshot &&
event.data.source === (IncrementalSource.Log as IncrementalSource)
) {
logData = (event.data as unknown) as LogData;
} else if (
event.type === EventType.Plugin &&
event.data.plugin === PLUGIN_NAME
) {
logData = event.data.payload as LogData;
}
if (logData) {
try {
if (typeof replayLogger[logData.level] === 'function') {
replayLogger[logData.level]!(logData);
}
} catch (error) {
if (context.replayer.config.showWarning) {
console.warn(error);
}
}
}
},
};
};