Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 30 additions & 1 deletion docs/references/architecture-gm-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,8 @@ across contexts to a privileged handler, then streams the result back. The imple
— the privileged half: permission verification, cross-origin requests, DNR rule building.
- **Offscreen side** ([`src/app/service/offscreen/gm_api.ts`](../../src/app/service/offscreen/gm_api.ts)) —
DOM-dependent operations for background scripts (page-context XHR, `window.open`, clipboard).
- **Values** flow through `ValueService` and are broadcast so every tab running the same script sees updates.
- **Values** flow through `ValueService` and are pushed to every frame running a script with the same storage
name; see [Value updates](#value-updates).

### Registration: the `@GMContext.API` decorator

Expand Down Expand Up @@ -54,6 +55,34 @@ The **persistent connection** (`MessageConnect`, opened via `connect()`) matters
back in chunks rather than returned by a single request/reply, which is how progress events and large bodies
work.

### Value updates

`GM_setValue` / `GM_setValues` are saved by `ValueService.setValues`
([`service_worker/value.ts`](../../src/app/service/service_worker/value.ts)) under a per-storage-name lock. Each
save gets a new, increasing `revision`, stored on the `Value` record and sent with the update. Updates reach
other frames over one value Port per content-script frame
([`content/value_port.ts`](../../src/app/service/content/value_port.ts) ↔
[`service_worker/value_port.ts`](../../src/app/service/service_worker/value_port.ts)); the SW keeps the
storage-name → Port index in memory only.

- **Writer receipt.** The writer's own update comes back in the `GM_setValue` RPC response, not only through
the Port. The Port push for the same update id is then ignored, so the writer neither waits on a lost push
nor fires its listeners twice.
- **Subscription and resync.** The Port is dropped whenever the SW stops, and is reopened when a page is
restored from bfcache. On every (re)connect the frame sends, per storage name, the last `revision` it knows and the script uuids it
runs. `ValueService.subscribeSnapshot` registers the Port and reads the stored revision inside the same
write lock, so a concurrent save is either included in the reply or pushed to the newly registered Port.
If the revisions differ, the reply carries a snapshot of each script's values. The frame buffers pushes
until that reply arrives and drops any push whose revision is not newer than what it already has.
- **Listener semantics after a gap.** If the scripts are still loading, the snapshot replaces the values they
will start with. Once they are running, `runtime/valueSync` compares the snapshot with the cached values key
by key and fires `GM_addValueChangeListener` once per changed key with `remote = true`. Intermediate values
missed during the gap are not replayed.
- **Reconnect policy.** A Port that was acknowledged and stayed up for at least a second reconnects
immediately when it drops. Otherwise the frame retries with backoff, so a SW that keeps failing cannot cause
a tight reconnect loop. Once the extension context is invalidated (reload, update, uninstall), the frame
stops reconnecting.

### Adding a GM API (sketch)

1. Add the method to the content `GMApi` with `@GMContext.API({ alias: "GM.foo" })`.
Expand Down
1 change: 1 addition & 0 deletions src/app/repo/scripts.ts
Original file line number Diff line number Diff line change
Expand Up @@ -105,6 +105,7 @@ export type PageScriptResource = Record<string, { base64?: string; content: stri
export interface ScriptRunResource extends Script {
code: string; // 原始代码
value: ValueStore;
valueRevision?: number; // 读取 value 时该存储的版本,页面据此在重订阅时判断是否漏收了更新
flag: string;
resource: ScriptResource; // 资源列表,包含脚本需要的资源
resourceByType?: ScriptResourceByType;
Expand Down
2 changes: 2 additions & 0 deletions src/app/repo/value.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ export interface Value {
data: { [key: string]: any };
createtime: number;
updatetime: number;
// 每次保存递增,见 ValueService.setValues;页面据此判断重订阅时是否漏收了更新。旧记录没有此字段,按 0 处理
revision?: number;
}

export class ValueDAO extends Repo<Value> {
Expand Down
25 changes: 25 additions & 0 deletions src/app/service/content/create_context.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -413,6 +413,31 @@ describe("createContext: capability and lifecycle contract", () => {
expect(contextValues.loadScriptResolve).toBeUndefined();
});

it("valueSync 只对变化的键更新缓存并以 remote=true 触发监听,删除的键也会通知", () => {
const script = createScriptInfo();
script.value = { same: 1, changed: "old", removed: { a: 1 } };
const context = createContext(
script,
{},
"vitest",
undefined as any,
undefined as any,
new Set(["GM_addValueChangeListener", "GM_getValue"])
);
const listener = vi.fn();
for (const key of ["same", "changed", "removed", "added"]) context.GM_addValueChangeListener(key, listener);

context.valueSync({ same: 1, changed: "new", added: [1] });

expect(listener.mock.calls).toEqual([
["changed", "old", "new", true, undefined],
["removed", { a: 1 }, undefined, true, undefined],
["added", undefined, [1], true, undefined],
]);
expect(context.GM_getValue("changed")).toBe("new");
expect(context.GM_getValue("removed")).toBeUndefined();
});

it("失效清理是 idempotent,且舊 value listener 不再收到更新", () => {
const script = createScriptInfo();
const context = createContext(
Expand Down
4 changes: 4 additions & 0 deletions src/app/service/content/exec_script.ts
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,10 @@ export default class ExecScript {
this.sandboxContext?.valueUpdate(data);
}

valueSync(values: Record<string, unknown>) {
this.sandboxContext?.valueSync(values);
}

execContext: any;

/**
Expand Down
64 changes: 64 additions & 0 deletions src/app/service/content/gm_api/gm_api.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1212,6 +1212,70 @@ return { value1, value2, value3, values1,values2, allValues1, allValues2, value4
const ret2 = await retPromise;
expect(ret2).toEqual({ name: "param2", oldValue: undefined, newValue: 456, remote: true });
});
// SW 处理写入后把同一份更新数据作为 RPC 响应返回;按 Port 推送的那份可能因 SW 重启而丢失
const createReceiptExec = (code: string, holdResponse = false) => {
const script = Object.assign({ uuid: uuidv4() }, scriptRes) as ScriptLoadInfo;
script.value = {};
script.metadata = { ...scriptRes.metadata, grant: ["GM.setValue", "GM_addValueChangeListener"] };
script.code = code;
const responses: any[] = [];
let release: () => void = () => undefined;
const held = new Promise<void>((resolve) => (release = resolve));
const mockSendMessage = vi.fn().mockImplementation(async (msg: any) => {
const [id, key, value] = msg.data.params;
const data = {
id,
entries: [[key, encodeRValue(value), encodeRValue(undefined)]],
uuid: script.uuid,
storageName: script.uuid,
sender: { runFlag: msg.data.runFlag, tabId: 3 },
valueUpdated: true,
};
responses.push(data);
if (holdResponse) await held;
return { code: 0, data };
});
const exec = new ExecScript(script, {
envPrefix: "scripting",
message: { sendMessage: mockSendMessage } as unknown as Message,
contentMsg: undefined as any,
code: nilFn,
envInfo,
});
exec.scriptFunc = compileScript(compileScriptCode(script));
return { exec, responses, release };
};
const listenAndSet = `
const calls = [];
GM_addValueChangeListener("k", (name, oldValue, newValue, remote) => calls.push([oldValue, newValue, remote]));
await GM.setValue("k", 1);
await new Promise((resolve) => setTimeout(resolve, 50));
return calls;
`;

it.concurrent("GM.setValue 没有收到推送时,凭 SW 的响应完成,并触发自身监听一次", async () => {
const { exec } = createReceiptExec(listenAndSet);
expect(await exec.exec()).toEqual([[undefined, 1, false]]);
});

it.concurrent("推送晚于响应到达时只处理一次", async () => {
const { exec, responses } = createReceiptExec(listenAndSet);
const ret = exec.exec();
await vi.waitFor(() => expect(responses).toHaveLength(1));
await Promise.resolve();
exec.valueUpdate(responses[0]);
expect(await ret).toEqual([[undefined, 1, false]]);
});

it.concurrent("推送早于响应到达时只处理一次", async () => {
const { exec, responses, release } = createReceiptExec(listenAndSet, true);
const ret = exec.exec();
await vi.waitFor(() => expect(responses).toHaveLength(1));
exec.valueUpdate(responses[0]);
release();
expect(await ret).toEqual([[undefined, 1, false]]);
});

it.concurrent("异步GM.setValue,等待回调", async () => {
const script = Object.assign({}, scriptRes) as ScriptLoadInfo;
script.metadata.grant = ["GM.getValue", "GM.setValue"];
Expand Down
39 changes: 32 additions & 7 deletions src/app/service/content/gm_api/gm_api.ts
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@ export interface IGM_Base {
sendMessage(api: string, params: any[]): Promise<any>;
connect(api: string, params: any[]): Promise<any>;
valueUpdate(data: ValueUpdateDataEncoded): void;
valueSync(values: Record<string, unknown>): void;
emitEvent(event: string, eventId: string, data: any): void;
}

Expand All @@ -61,6 +62,11 @@ let valChangeRandomId = `${randNum(8e11, 2e12).toString(36)}`;

const valueChangePromiseMap = new Map<string, any>();

// 本 world 发起的写入,其更新会经 RPC 响应和 Port 推送各到达一次,谁先到谁处理,后到的按 id 跳过。
// 只记录处理过一次的 id;推送丢失时第二份永远不会到,所以限制数量,淘汰最早的。
const handledOwnValueIds = new Set<string>();
const HANDLED_OWN_VALUE_IDS_LIMIT = 1024;

const execEnvInit = (execEnv: GMApi) => {
if (!execEnv.contentEnvKey) {
execEnv.contentEnvKey = randomMessageFlag(); // 不重复识别字串。用于区分 mainframe subframe 等执行环境
Expand Down Expand Up @@ -176,6 +182,11 @@ class GM_Base implements IGM_Base {
const valueStore = scriptRes.value;
const remote = sender.runFlag !== this.runFlag;
if (!remote && id) {
if (handledOwnValueIds.delete(id)) return;
handledOwnValueIds.add(id);
if (handledOwnValueIds.size > HANDLED_OWN_VALUE_IDS_LIMIT) {
handledOwnValueIds.delete(handledOwnValueIds.values().next().value!);
}
const fn = valueChangePromiseMap.get(id);
if (fn) {
valueChangePromiseMap.delete(id);
Expand All @@ -201,6 +212,22 @@ class GM_Base implements IGM_Base {
}
}

// 重订阅补齐:快照只有最终值,逐键对比本地缓存,对变化的键更新并以 remote=true 触发监听
@GMContext.protected()
public valueSync(values: Record<string, unknown>) {
if (!this.scriptRes || !this.valueChangeListener) return;
const valueStore = this.scriptRes.value;
const encode = (value: unknown) => JSON.stringify(encodeRValue(value));
for (const key of new Set([...Object.keys(valueStore), ...Object.keys(values)])) {
const oldValue = valueStore[key];
const value = values[key];
if (encode(oldValue) === encode(value)) continue;
if (value === undefined) delete valueStore[key];
else valueStore[key] = value;
this.valueChangeListener.execute(key, oldValue, value, true, undefined);
}
}

@GMContext.protected()
emitEvent(event: string, eventId: string, data: any) {
if (!this.EE) return;
Expand Down Expand Up @@ -292,22 +319,20 @@ export default class GMApi extends GM_Base {
if (promise) {
valueChangePromiseMap.set(id, promise);
}
let params: [string, string] | [string, string, unknown];
if (value === undefined) {
delete a.scriptRes.value[key];
a.sendMessage("GM_setValue", [id, key]);
params = [id, key];
} else {
// 对object的value进行一次转化
if (value && typeof value === "object") {
value = customClone(value);
}
// customClone 可能返回 undefined
a.scriptRes.value[key] = value;
if (value === undefined) {
a.sendMessage("GM_setValue", [id, key]);
} else {
a.sendMessage("GM_setValue", [id, key, value]);
}
params = value === undefined ? [id, key] : [id, key, value];
}
a.sendMessage("GM_setValue", params).then((ret) => ret && a.valueUpdate(ret));
return id;
}

Expand Down Expand Up @@ -339,7 +364,7 @@ export default class GMApi extends GM_Base {
// 避免undefined 等空值流失,先进行映射处理
keyValuePairs.push([key, encodeRValue(value_)]);
}
a.sendMessage("GM_setValues", [id, keyValuePairs]);
a.sendMessage("GM_setValues", [id, keyValuePairs]).then((ret) => ret && a.valueUpdate(ret));
return id;
}

Expand Down
1 change: 1 addition & 0 deletions src/app/service/content/page_load_contract.ts
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ const PAGE_LOAD_SCRIPT_OPTIONAL_KEYS = [
"requireCssResource",
"userConfig",
"scriptUrlPatterns",
"valueRevision",
] as const;

type PageLoadScriptRequiredKey = (typeof PAGE_LOAD_SCRIPT_REQUIRED_KEYS)[number];
Expand Down
14 changes: 14 additions & 0 deletions src/app/service/content/script_executor.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ import type { Message } from "@Packages/message/types";
import type { ScriptLoadInfo } from "../service_worker/types";
import type { TScriptInfo } from "@App/app/repo/scripts";
import { initEnvInfo, ScriptExecutor } from "./script_executor";
import type ExecScript from "./exec_script";

const styleUrl = "https://example.com/style.css";
const secondStyleUrl = "https://example.com/second-style.css";
Expand Down Expand Up @@ -129,4 +130,17 @@ describe("ScriptExecutor", () => {
expect((adoptedSheets[0] as CSSStyleSheet & { cssText: string }).cssText).toBe("body { color: green; }");
});
});

it("valueSync 只把快照交给 uuid 对应的脚本", () => {
const executor = new ScriptExecutor({} as Message, {} as Message);
const target = { scriptRes: { uuid: "a" }, valueSync: vi.fn() };
const other = { scriptRes: { uuid: "b" }, valueSync: vi.fn() };
executor.execScriptMap.set("a", target as unknown as ExecScript);
executor.execScriptMap.set("b", other as unknown as ExecScript);

executor.valueSync({ storageName: "s", values: { a: { k: 1 } } });

expect(target.valueSync).toHaveBeenCalledExactlyOnceWith({ k: 1 });
expect(other.valueSync).not.toHaveBeenCalled();
});
});
10 changes: 9 additions & 1 deletion src/app/service/content/script_executor.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ import type { Message } from "@Packages/message/types";
import { getStorageName } from "@App/pkg/utils/utils";
import type { EmitEventRequest } from "../service_worker/types";
import ExecScript from "./exec_script";
import type { GMInfoEnv, ScriptFunc, ValueUpdateDataEncoded } from "./types";
import type { GMInfoEnv, ScriptFunc, ValueSyncData, ValueUpdateDataEncoded } from "./types";
import { addStyleSheet, definePropertyListener, waitBody } from "./utils";
import type { ScriptLoadInfo, TScriptInfo } from "@App/app/repo/scripts";
import { DefinedFlags } from "../service_worker/runtime.consts";
Expand Down Expand Up @@ -58,6 +58,14 @@ export class ScriptExecutor {
}
}

valueSync(data: ValueSyncData) {
// runtime/valueSync
for (const val of this.execScriptMap.values()) {
const values = data.values[val.scriptRes.uuid];
if (values) val.valueSync(values);
}
}

startScripts(scripts: TScriptInfo[], envInfo: GMInfoEnv) {
const loadExec = (script: TScriptInfo, scriptFunc: any) => {
this.execScriptEntry({
Expand Down
5 changes: 4 additions & 1 deletion src/app/service/content/script_runtime.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ import type { Message } from "@Packages/message/types";
import { initEnvInfo, type ScriptExecutor } from "./script_executor";
import type { TScriptInfo } from "@App/app/repo/scripts";
import type { EmitEventRequest } from "../service_worker/types";
import type { GMInfoEnv, ValueUpdateDataEncoded } from "./types";
import type { GMInfoEnv, ValueSyncData, ValueUpdateDataEncoded } from "./types";
import type { ScriptEnvTag } from "@Packages/message/consts";
import { onInjectPageLoaded } from "./external";
import type { CustomEventMessage } from "@Packages/message/custom_event_message";
Expand Down Expand Up @@ -62,6 +62,9 @@ export class ScriptRuntime {
this.server.on("runtime/valueUpdate", (data: ValueUpdateDataEncoded) => {
this.scriptExecutor.valueUpdate(data);
});
this.server.on("runtime/valueSync", (data: ValueSyncData) => {
this.scriptExecutor.valueSync(data);
});

this.server.on("pageLoad", (data: { scripts: TScriptInfo[]; envInfo: GMInfoEnv }) => {
// 监听事件
Expand Down
Loading
Loading