feat: add kernel plugin network timers by xyzuanli · Pull Request #18149 · siyuan-note/siyuan

xyzuanli · 2026-07-08T00:30:41Z

Description / 描述

Adds kernel plugin runtime capabilities for event-driven peer communication and safe coordination with SiYuan's built-in sync. Kernel plugins can now open guarded outbound WebSocket connections, use browser-compatible timers, and query or hold the official sync idle state before performing workspace writes.

Refs #17445
Related to #17487, #17670

Type of change / 变更类型

Bug fix
缺陷修复
Refactoring
代码重构
New feature
新功能
Text updates or new language additions
修改文案或增加新语言

Changes

Adds siyuan.net.ws(...) for kernel plugins, with trusted peer validation before dialing outbound WebSocket connections.
Adds setTimeout, clearTimeout, setInterval, and clearInterval to the kernel plugin sandbox.
Adds siyuan.sync.isSyncing() and siyuan.sync.tryLockIdle(ttlMs) so kernel plugins can avoid conflicting with official sync while performing workspace writes.
Exposes current sync activity from /api/sync/getSyncInfo as syncing for frontend/plugin coordination.
Refactors the existing siyuan.client.socket path into shared WebSocket helper code.
Adds tests for peer host normalization used by the outbound network guard.

Verification

cd kernel && go test -vet=off -run '^$' ./plugin ./api ./model
git diff --check origin/dev...origin/pr/18149
git merge-tree --write-tree origin/dev origin/pr/18149

Checklist / 检查清单

I have performed a self-review of my own code
I have full rights to the submitted code and agree to license it under this project's AGPL-3.0 license
PR is submitted to the dev branch and has no merge conflicts

88250 · 2026-07-09T12:07:12Z

请举例使用场景

xyzuanli · 2026-07-10T09:23:19Z

请举例使用场景

主要用于局域网同步，比如桌面跟docker

Copilot

Pull request overview

This PR extends the Go kernel-side plugin runtime with (1) guarded outbound WebSocket dialing for peer-to-peer/event-driven communication, (2) browser-compatible timer APIs in the goja sandbox, and (3) sync-idle coordination primitives so plugins can avoid racing with SiYuan’s official sync while performing workspace writes.

Changes:

Added siyuan.net (trusted-peer outbound ws) and siyuan.sync (sync state + idle lock token) namespaces to the kernel plugin sandbox.
Introduced shared WebSocket client object builder and refactored siyuan.client.socket to reuse it.
Added setTimeout / setInterval (and clear variants) to the plugin global runtime, plus normalization tests for trusted peer hosts.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
kernel/plugin/websocket_client.go	New shared builder for browser-like WebSocket JS objects used by both `siyuan.client.socket` and `siyuan.net.ws`.
kernel/plugin/timers.go	Adds timer APIs to the goja plugin sandbox and ties timer lifecycle to plugin context.
kernel/plugin/sandbox.go	Wires new `net`, `sync`, and timer injections into the plugin runtime bootstrap.
kernel/plugin/api_sync.go	Exposes `siyuan.sync.isSyncing()` and `siyuan.sync.tryLockIdle(ttlMs)` to plugins.
kernel/plugin/api_net.go	Adds `siyuan.net.setTrustedPeers()` and guarded outbound `siyuan.net.ws()`.
kernel/plugin/api_net_test.go	Tests peer host normalization used by the trusted-peer guard.
kernel/plugin/api_client.go	Refactors `siyuan.client.socket` to reuse the shared WebSocket builder.
kernel/model/sync.go	Adds `IsSyncing()` and a TTL-based `TryLockSyncIdle()` lock token for coordination.
kernel/api/sync.go	Exposes `syncing` in `/api/sync/getSyncInfo` response for frontend/plugin coordination.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+		}, func(rt *goja.Runtime, result any, err error) {
+			if lo.IsNil(err) {
+				if opening, ok := result.(bool); !ok || !opening {
+					if resolveErr := openResolve(nil); resolveErr != nil {
+						logging.LogErrorf("[plugin:%s] ws.open resolve: %v", p.Name, resolveErr)
+					}
+				}
+			} else {


+		closeRunErr := p.worker.Run(func(rt *goja.Runtime) (result any, err error) {
+			if c := gwsConn.Load(); c != nil {
+				setReadyState(rt, WebSocketReadyStateClosing)
+				err = c.WriteClose(code, reason)
+			}
+			return
+		}, func(rt *goja.Runtime, result any, err error) {


+		delay := time.Duration(call.Argument(1).ToInteger()) * time.Millisecond
+		if delay < 0 {
+			delay = 0
+		}


+		delay := time.Duration(call.Argument(1).ToInteger()) * time.Millisecond
+		if delay < 0 {
+			delay = 0
+		}


Zuoqiu-Yingyi · 2026-07-14T04:10:57Z

审查结论 (不包含 Copilot 已报告的问题)

高风险：siyuan.net.setTrustedPeers() 的“白名单”完全由插件自己设置，siyuan.net.ws() 只校验这个插件自声明列表；因此任意 kernel plugin 都可以先信任任意 host:port 再发起出站 WebSocket。若目标是 SSRF/内网访问防护，这不是安全边界，且实现显式绕过 SSRFSafeDialer。建议改为 manifest/用户授权/配对流程生成的受信列表，或默认继续使用 SSRF-safe dialer。位置：kernel/plugin/api_net.go:55、kernel/plugin/api_net.go:88、kernel/plugin/websocket_client.go:102
高风险：injectTimers() 注入了 setTimeout, clearTimeout, setInterval 与 clearInterval，但这些定时器 API 在通过 eventloop.NewEventLoop() 创建 goja 运行时中已经注入。位置：kernel/plugin/plugin.go:190、kernel/model/timers.go:65
中风险：tryLockIdle() 获取的同步锁没有绑定插件生命周期；插件卸载、崩溃或 runtime 停止后，锁只能等 TTL 自动释放，最长可阻塞官方同步 10 分钟。建议在 p.context.Done() 时自动 lock.Unlock()，或把插件生命周期传入 model.TryLockSyncIdle。位置：kernel/plugin/api_sync.go:48、kernel/model/sync.go:180
中风险：PR 描述里的验证命令 go test -vet=off -run '^$' ./plugin ./api ./model 不会运行新增的 TestNormalizePeerHost，因为 -run '^$' 匹配不到该测试。建议 PR 验证改为至少运行 go test -vet=off ./plugin -run TestNormalizePeerHost 或相关包全量测试。位置：kernel/plugin/api_net_test.go:21

已验证

git diff --check upstream/dev...HEAD：通过
cd kernel && go test -vet=off -run '^$' ./plugin ./api ./model：通过
cd kernel && go test -vet=off ./plugin -run TestNormalizePeerHost -count=1：通过

Zuoqiu-Yingyi · 2026-07-14T04:24:50Z

@88250
目前看需要先在本体中实现一个用户可配置的信任列表, 命中信任列表中的请求可以逃过代理的 SSRF 检查

GitHub Copilot 报告的现存问题我在 #18220 处理一下

88250 · 2026-07-14T04:31:52Z

SSRF 检查已经在安全政策中放弃了 https://github.com/siyuan-note/siyuan/security/policy 所以不用考虑

Zuoqiu-Yingyi · 2026-07-14T04:46:36Z

SSRF 检查已经在安全政策中放弃了 https://github.com/siyuan-note/siyuan/security/policy 所以不用考虑

是要移除现有的对于正向代理的 SSRF 检查吗？
还是将相关请求更改为仅日志审计而不阻止

88250 · 2026-07-14T05:14:24Z

已有的不用移除，只是在安全政策中说明 ssrf 不要报告了，后续代码也不用考虑解决 ssrf。

Zuoqiu-Yingyi · 2026-07-14T05:41:57Z

已有的不用移除，只是在安全政策中说明 ssrf 不要报告了，后续代码也不用考虑解决 ssrf。

该 PR 受现存 SSRF 策略影响引入了大量冗余代码 (新增了绕过 SSRF 策略的 API), 同时导致现有的 SSRF 策略形同虚设, 不如直接将现有策略更改为日志审计

Zuoqiu-Yingyi · 2026-07-14T05:47:09Z

我看现在也有个安全模式, 可以在安全模式下使用 SSRF 阻止策略, 普通模式下使用日志审计策略

TCOTC · 2026-07-14T05:49:04Z

安全模式是自动关插件，不是有个专门的模式状态

Zuoqiu-Yingyi · 2026-07-14T05:54:00Z

安全模式是自动关插件，不是有个专门的模式状态

安全模式可以使用命令行参数 --safe-mode 启用, 虽然不会持久化, 但确实是个模式状态
安全模式启用 SSRF 阻止策略也符合预期, 毕竟正向代理 API 可能由外部调用

TCOTC · 2026-07-14T05:57:58Z

感觉价值好像不大

88250 · 2026-07-14T06:18:45Z

新增的代码不用考虑 ssrf 阻止，不然好麻烦。

Zuoqiu-Yingyi · 2026-07-14T06:21:56Z

感觉价值好像不大

目前看没有其他比较好的方案了
维护一个全局信任列表的方案对攻击者来说也是形同虚设, 因为攻击者完全可以调用修改信任列表的 API 将攻击目标添加到名单中

Zuoqiu-Yingyi · 2026-07-14T06:22:49Z

@88250
目前有个方案

默认模式下 SSRF 只审计不阻止
安全模式下 SSRF 审计且阻止

如果这个方案可接受的话我在 #18220 中修改

88250 · 2026-07-14T06:29:37Z

我觉得没有必要，完全放弃 SSRF 防御吧

Zuoqiu-Yingyi · 2026-07-14T06:30:51Z

我觉得没有必要，完全放弃 SSRF 防御吧

我这个方便比直接移除 SSRF 变更与影响更小😏

88250 · 2026-07-14T06:49:02Z

直接移掉吧

Zuoqiu-Yingyi · 2026-07-14T09:53:04Z

@88250
在 #18220 中修复了本 PR 中 GitHub Copilot 报告的问题, 并调整了 ./kernel/util/net.go 中 SSRFSafeDialer() 实现 (默认模式下 SSRF 只审计不阻止, 安全模式下 SSRF 审计且阻止)
若需要完成移除 SSRF, 直接删除其中的 Control 字段即可

@xyzuanli
等 #18220 合并后本 PR 可能需要重构

88250 · 2026-07-14T09:55:32Z

#18220 已经合并

xyzuanli · 2026-07-14T10:18:44Z

已经重构大半了，不过是在有SSRF的情况下hhh，后面我再改改

TCOTC · 2026-07-14T13:05:51Z

新增两万五千行代码看起来好夸张

xyzuanli · 2026-07-14T13:08:28Z

用ai粗暴合并了下，好多还是之前的东西

Zuoqiu-Yingyi · 2026-07-14T17:26:36Z

用ai粗暴合并了下，好多还是之前的东西

还是重新从 dev 分支分叉再修改提交 PR 吧

88250 requested a review from Copilot July 13, 2026 15:43

Copilot started reviewing on behalf of 88250 July 13, 2026 15:43 View session

Copilot AI reviewed Jul 13, 2026

View reviewed changes

xyzuanli force-pushed the codex/kernel-plugin-net-timers-dev branch from 930277d to b732a0f Compare July 14, 2026 13:02

xyzuanli force-pushed the codex/kernel-plugin-net-timers-dev branch 2 times, most recently from 858d182 to 930277d Compare July 14, 2026 13:29

♻️ Centralize plugin sync consistency in kernel

68b9c29

xyzuanli force-pushed the codex/kernel-plugin-net-timers-dev branch from 930277d to 68b9c29 Compare July 15, 2026 07:43

xyzuanli added 3 commits July 16, 2026 08:41

🎨 Add persistent recovery WAL for kernel sync commits #18149

923ad4c

♻️ Refactor kernel sync commit transactions #18149

b04c815

Refactor kernel plugin sync architecture

bf83e1a

xyzuanli closed this Jul 16, 2026

Uh oh!

Uh oh!

Conversation

xyzuanli commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description / 描述

Type of change / 变更类型

Changes

Verification

Checklist / 检查清单

Uh oh!

88250 commented Jul 9, 2026

Uh oh!

xyzuanli commented Jul 10, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Zuoqiu-Yingyi commented Jul 14, 2026

Uh oh!

Zuoqiu-Yingyi commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

88250 commented Jul 14, 2026

Uh oh!

Zuoqiu-Yingyi commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

88250 commented Jul 14, 2026

Uh oh!

Zuoqiu-Yingyi commented Jul 14, 2026

Uh oh!

Zuoqiu-Yingyi commented Jul 14, 2026

Uh oh!

TCOTC commented Jul 14, 2026

Uh oh!

Zuoqiu-Yingyi commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

TCOTC commented Jul 14, 2026

Uh oh!

88250 commented Jul 14, 2026

Uh oh!

Zuoqiu-Yingyi commented Jul 14, 2026

Uh oh!

Zuoqiu-Yingyi commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

88250 commented Jul 14, 2026

Uh oh!

Zuoqiu-Yingyi commented Jul 14, 2026

Uh oh!

88250 commented Jul 14, 2026

Uh oh!

Zuoqiu-Yingyi commented Jul 14, 2026

Uh oh!

88250 commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

xyzuanli commented Jul 14, 2026

Uh oh!

TCOTC commented Jul 14, 2026

Uh oh!

xyzuanli commented Jul 14, 2026

Uh oh!

Zuoqiu-Yingyi commented Jul 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

xyzuanli commented Jul 8, 2026 •

edited

Loading

Zuoqiu-Yingyi commented Jul 14, 2026 •

edited

Loading

Zuoqiu-Yingyi commented Jul 14, 2026 •

edited

Loading

Zuoqiu-Yingyi commented Jul 14, 2026 •

edited

Loading

Zuoqiu-Yingyi commented Jul 14, 2026 •

edited

Loading

88250 commented Jul 14, 2026 •

edited

Loading