Skip to content

Commit

Permalink
apply highlight prettier config
Browse files Browse the repository at this point in the history
  • Loading branch information
Vadman97 committed Sep 29, 2022
1 parent 9ce20d2 commit 5694b69
Show file tree
Hide file tree
Showing 42 changed files with 300 additions and 359 deletions.
1 change: 0 additions & 1 deletion .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -21,4 +21,3 @@ jobs:
run: echo //registry.npmjs.org/:_authToken=${NPM_TOKEN} > ~/.npmrc
env:
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

2 changes: 1 addition & 1 deletion .release-it.json
Original file line number Diff line number Diff line change
Expand Up @@ -12,4 +12,4 @@
"release": true,
"releaseName": "Release ${version}"
}
}
}
6 changes: 3 additions & 3 deletions docs/observer.zh_CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,8 +57,8 @@ body

[序列化设计](./serialization.zh_CN.md)中已经介绍了我们需要维护一个 `id -> Node` 的映射,因此当出现新增节点时,我们需要将新节点序列化并加入映射中。但由于我们为了去重新增节点,选择在所有 mutation 记录遍历完毕之后才进行序列化,在以下示例中就会出现问题:

1. mutation 记录1,新增节点 n1。我们暂不处理,等待最终去重后序列化。
2. mutation 记录2,n1 新增属性 a1。我们试图将它记录成一次增量快照,但会发现无法从映射中找到 n1 对应的 id,因为此时它还未被序列化。
1. mutation 记录 1,新增节点 n1。我们暂不处理,等待最终去重后序列化。
2. mutation 记录 2,n1 新增属性 a1。我们试图将它记录成一次增量快照,但会发现无法从映射中找到 n1 对应的 id,因为此时它还未被序列化。

由此可见,由于我们对新增节点进行了延迟序列化的处理,所有 mutation 记录也都需要先收集,再新增节点去重并序列化之后再做处理。

Expand Down Expand Up @@ -119,4 +119,4 @@ function hookSetter<T>(
}
```

注意为了避免我们在 setter 中的逻辑阻塞被录制页面的正常交互,我们应该把逻辑放入 event loop 中异步执行。
注意为了避免我们在 setter 中的逻辑阻塞被录制页面的正常交互,我们应该把逻辑放入 event loop 中异步执行。
7 changes: 3 additions & 4 deletions docs/recipes/record-and-replay.zh_CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@
const stopFn = rrweb.record({
emit(event) {
// 保存获取到的 event 数据
}
})
},
});
```

你可以使用任何方式保存录制的数据,例如通过网络请求将数据传入至后端持久化保存,但请确保:
Expand All @@ -22,9 +22,8 @@ const stopFn = rrweb.record({
回放时只需要获取一段录制数据,并传入 rrweb 提供的 Replayer:

```js
const events = GET_YOUR_EVENTS
const events = GET_YOUR_EVENTS;

const replayer = new rrweb.Replayer(events);
replayer.play();
```

5 changes: 5 additions & 0 deletions docs/replay.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,9 @@
# Replay

A design principle of rrweb is to process as little as possible on the recording side, minimizing the impact on the recorded page. This means we need to do some special processing on the replay side.

## High precision timer

During replay, we will get the complete snapshot chain at one time. If all the snapshots are executed in sequence, we can directly get the last state of the recorded page, but what we need is to synchronously initialize the first full snapshot, and then apply the remaining incremental snapshots asynchronously. Using a time interval we replay each incremental snapshot one after the other, which requires a high-precision timer.

The reason why **high precision** is emphasized is because the native `setTimeout` does not guarantee accurate execution after the set delay time, for example, when the main thread is blocked.
Expand All @@ -11,6 +13,7 @@ For our replay function, this imprecise delay is unacceptable and can lead to va
At the same time, the custom timer is also the basis for our "fast forward" function.

## Completing missing nodes

The delay serialization strategy when rrweb uses MutationObserver is mentioned in the [incremental snapshot design](./observer.md), which may result in the following scenarios where we cannot record a full incremental snapshot:

```
Expand All @@ -29,6 +32,7 @@ During replay, when we process the incremental snapshot of the new `foo`, we kno
After processing the incremental snapshot of the new n1, we normally process and insert `bar`. After the replay is completed, we check whether the neighbor node id of `foo` points to a node which is in the missing node pool. If it matches, then it will be removed from the pool and be inserted into the DOM tree.

## Simulation Hover

CSS styles for the `:hover` selector are present in many web pages, but we can't trigger the hover state via JavaScript. So when playing back we need to simulate the hover state to make the style display correctly.

The specific method includes two parts:
Expand All @@ -37,6 +41,7 @@ The specific method includes two parts:
2. When playing back the mouse up mouse interaction event, add the `.:hover` class name to the event target and all its ancestors, and remove it when the mouse moves away again.

## Play from any point in time

In addition to the basic replay features, we also want players like `rrweb-player` to provide similar functionality to video players, such as dragging and dropping to the progress bar to any point in time.

In actual implementation, we pass a start time to the method. We can then divide the snapshot chain into two parts: The parts before and the part after the start time. Then, the snapshot chain before the start time is executed synchronously, and then the snapshot chain after the starting times uses the normal asynchronous execution. This way we can achieve starting replay from any point in time.
3 changes: 3 additions & 0 deletions docs/sandbox.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ In the [serialization design](./serialization.md) we mentioned the "de-scripting
There are many kinds of scripting behaviors. A filtering approach to getting rid of these scripts will never be a complete solution, and once a script slips through and is executed, it may cause irreversible unintended consequences. So we use the iframe sandbox feature provided by HTML for browser-level restrictions.

## iframe sandbox

We reconstruct the recorded DOM in an `iframe` element when we rebuild the snapshot. By setting its `sandbox` attribute, we can disable the following behavior:

- Form submission
Expand All @@ -14,13 +15,15 @@ We reconstruct the recorded DOM in an `iframe` element when we rebuild the snaps
This is in line with our expectations, especially when dealing with JS scripts is safer and more reliable than implementing this security ourselves.

## Avoid link jumps

When you click the a element link, the default event is to jump to the URL corresponding to its href attribute. During replay, we will ensure visually correct replay by rebuilding the page DOM after the jump, and the original jump should be prohibited.

Usually we will capture all an elements click events through the event handler proxy and disable the default event via `event.preventDefault()`. But when we put the replay page in the sandbox, all the event handlers will not be executed, and we will not be able to implement the event delegation.

When replaying interactive events, note that replaying the JS `click` event is not nessecary because click events do not have any impact when JS is disabled. However, in order to optimize the replay effect, we can add special animation effects to visualize elements being clicked with the mouse, to clearly show the viewer that a click has occurred.

## iframe style settings

Since we're rebuilding the DOM in an iframe, we can't affect the elements in the iframe through the CSS stylesheet of the parent page. But if JS scripts are not allowed to execute, the `noscript` tag will be displayed, and we want to hide it. So we need to dynamically add styles to the iframe. The sample code is as follows:

```typescript
Expand Down
2 changes: 1 addition & 1 deletion docs/sandbox.zh_CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,4 +42,4 @@ for (let idx = 0; idx < injectStyleRules.length; idx++) {
}
```

需要注意的是这个插入的 style 元素在被录制页面中并不存在,所以我们不能将其序列化,否则 `id -> Node` 的映射将出现错误。
需要注意的是这个插入的 style 元素在被录制页面中并不存在,所以我们不能将其序列化,否则 `id -> Node` 的映射将出现错误。
16 changes: 9 additions & 7 deletions docs/serialization.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
# Serialization

If you only need to record and replay changes within the browser locally, then we can simply save the current view by deep copying the DOM object. For example, the following code implementation (simplified example with jQuery, saves only the body part):

```javascript
Expand All @@ -18,6 +19,7 @@ We do not use an existing open source solutions such as [parse5](https://github.
2. This part of the code needs to run on the recorded page, and we want to control the amount of code as much as possible, only retaining the necessary functions.

## Special handling in serialization

The reason why our serialization method is non-standard is because we still need to do the following parts:

1. Output needs to be descriptive. All JavaScript in the original recorded page should not be executed on replay. In rrweb we do this by replacing `script` tags with placeholder `noscript` tags in snapshots. The content inside the script is no longer important. We instead record any changes to the DOM that scripts cause, and we ​​do not need to fully record large amounts of script content that may be present on the original web page.
Expand All @@ -26,15 +28,15 @@ The reason why our serialization method is non-standard is because we still need
4. We want to record the contents of the CSS style sheet. If the recorded page links to external style sheets, we can get its parsed CSS rules from the browser, generate an inline style sheet containing all these rules. This way stylesheets that are not always accessible (for example, because they are located on an intranet or localhost) are included in the recording and can be replayed correctly.

## Uniquely identifies

At the same time, our serialization should also include both full and incremental types. Full serialization can transform a DOM tree into a corresponding tree data structure.

For example, the following DOM tree:

```html
<html>
<body>
<header>
</header>
<header></header>
</body>
</html>
```
Expand Down Expand Up @@ -100,10 +102,10 @@ Imagine if we recorded the click of a button on the same page and played it back

```javascript
type clickSnapshot = {
source: 'MouseInteraction';
type: 'Click';
node: HTMLButtonElement;
}
source: 'MouseInteraction',
type: 'Click',
node: HTMLButtonElement,
};
```

The operation can be executed again by `snapshot.node.click()`.
Expand All @@ -119,5 +121,5 @@ type clickSnapshot = {
source: 'MouseInteraction';
type: 'Click';
id: Number;
}
};
```
16 changes: 7 additions & 9 deletions docs/serialization.zh_CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ $('body').replaceWith(snapshot);

1. 去脚本化。被录制页面中的所有 JavaScript 都不应该被执行,例如我们会在重建快照时将 `script` 标签改为 `noscript` 标签,此时 script 内部的内容就不再重要,录制时可以简单记录一个标记值而不需要将可能存在的大量脚本内容全部记录。
2. 记录没有反映在 HTML 中的视图状态。例如 `<input type="text" />` 输入后的值不会反映在其 HTML 中,而是通过 `value` 属性记录,我们在序列化时就需要读出该值并且以属性的形式回放成 `<input type="text" value="recordValue" />`
3. 相对路径转换为绝对路径。回放时我们会将被录制的页面放置在一个 `<iframe>` 中,此时的页面 URL为重放页面的地址,如果被录制页面中有一些相对路径就会产生错误,所以在录制时就要将相对路径进行转换,同样的 CSS 样式表中的相对路径也需要转换。
3. 相对路径转换为绝对路径。回放时我们会将被录制的页面放置在一个 `<iframe>` 中,此时的页面 URL 为重放页面的地址,如果被录制页面中有一些相对路径就会产生错误,所以在录制时就要将相对路径进行转换,同样的 CSS 样式表中的相对路径也需要转换。
4. 尽量记录 CSS 样式表的内容。如果被录制页面加载了一些同源的 样式表,我们则可以获取到解析好的 CSS rules,录制时将能获取到的样式都 inline 化,这样可以让一些内网环境(如 localhost)的录制也有比较好的效果。

## 唯一标识
Expand All @@ -34,8 +34,7 @@ $('body').replaceWith(snapshot);
```html
<html>
<body>
<header>
</header>
<header></header>
</body>
</html>
```
Expand Down Expand Up @@ -101,10 +100,10 @@ $('body').replaceWith(snapshot);

```javascript
type clickSnapshot = {
source: 'MouseInteraction';
type: 'Click';
node: HTMLButtonElement;
}
source: 'MouseInteraction',
type: 'Click',
node: HTMLButtonElement,
};
```

再通过 `snapshot.node.click()` 就能将操作再执行一次。
Expand All @@ -120,6 +119,5 @@ type clickSnapshot = {
source: 'MouseInteraction';
type: 'Click';
id: Number;
}
};
```
Loading

0 comments on commit 5694b69

Please sign in to comment.