Skip to content

An open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间,让人与智能体在此协作

:zap: Wait for submitted editing transactions without a fixed delay https://github.com/siyuan-note/siyuan/issues/20252

Danielf385afe883cd
diff --git a/kernel/api/contract_block_transaction_test.go b/kernel/api/contract_block_transaction_test.go
index 4608eb032d..60805a903c 100644
--- a/kernel/api/contract_block_transaction_test.go
+++ b/kernel/api/contract_block_transaction_test.go
@@ -143,6 +143,7 @@ func TestAPIContractHeadingTransactions(t *testing.T) {
testAPIContractRemainingBlockQueries(t, engine, box.ID, docID, heading.ID)
testAPIContractMindmapMigration(t, engine, box.ID, docID)
testAPIContractListConversion(t, engine, docID)
+ testAPIContractTransactionCompletion(t, engine, docID, paragraphID)
for _, entry := range []struct {
path, id, scope string
code int
diff --git a/kernel/api/contract_transaction_completion_test.go b/kernel/api/contract_transaction_completion_test.go
new file mode 100644
index 0000000000..5a2502444c
--- /dev/null
+++ b/kernel/api/contract_transaction_completion_test.go
@@ -0,0 +1,169 @@
+package api
+
+import (
+ "encoding/json"
+ "fmt"
+ "net/http"
+ "net/http/httptest"
+ "reflect"
+ "strings"
+ "testing"
+ "time"
+ "unsafe"
+
+ "github.com/88250/lute/parse"
+ "github.com/gin-gonic/gin"
+ "github.com/gorilla/websocket"
+ "github.com/olahol/melody"
+ "github.com/siyuan-note/siyuan/kernel/filesys"
+ "github.com/siyuan-note/siyuan/kernel/model"
+ "github.com/siyuan-note/siyuan/kernel/sql"
+ "github.com/siyuan-note/siyuan/kernel/treenode"
+ "github.com/siyuan-note/siyuan/kernel/util"
+)
+
+// 复用真实 HTTP 事务的隔离工作区,验证完成等待、广播元数据及无关事务不会阻塞已完成批次。
+func testAPIContractTransactionCompletion(t *testing.T, engine *gin.Engine, docID, paragraphID string) {
+ t.Helper()
+ push := melody.New()
+ connected := make(chan *melody.Session, 1)
+ push.HandleConnect(func(session *melody.Session) {
+ util.AddPushChan(session)
+ connected <- session
+ })
+ push.HandleDisconnect(util.RemovePushChan)
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, request *http.Request) {
+ _ = push.HandleRequest(w, request)
+ }))
+ defer server.Close()
+ defer push.Close()
+ connection, response, err := websocket.DefaultDialer.Dial("ws"+strings.TrimPrefix(server.URL, "http")+
+ "/?app=completion-observer&id=main&type=main", nil)
+ if err != nil {
+ t.Fatal(err)
+ }
+ response.Body.Close()
+ defer connection.Close()
+ select {
+ case session := <-connected:
+ defer util.RemovePushChan(session)
+ case <-time.After(5 * time.Second):
+ t.Fatal("transaction observer did not connect")
+ }
+ dom := func(content string) string {
+ return fmt.Sprintf(`<div data-node-id="%s" data-type="NodeParagraph"><div contenteditable="true">%s</div></div>`, paragraphID, content)
+ }
+ completed := &model.Transaction{DoOperations: []*model.Operation{{Action: "plugin-completion-test"}}}
+ if err = model.PerformTxSync(completed); err != nil {
+ t.Fatal(err)
+ }
+ blocked := &model.Transaction{
+ DoOperations: []*model.Operation{{Action: "update", ID: paragraphID, Data: dom("Queued edit")}},
+ UndoOperations: []*model.Operation{{Action: "update", ID: paragraphID, Data: dom("Original")}},
+ }
+ blocked.MarkFromAPI()
+ writeStarted, allowWrite := make(chan struct{}), make(chan struct{})
+ writeField := reflect.ValueOf(blocked).Elem().FieldByName("writeTransactionTree")
+ reflect.NewAt(writeField.Type(), unsafe.Pointer(writeField.UnsafeAddr())).Elem().Set(reflect.ValueOf(func(tree *parse.Tree) error {
+ close(writeStarted)
+ <-allowWrite
+ if _, err := filesys.WriteTree(tree); err != nil {
+ return err
+ }
+ sql.UpsertTreeQueue(tree)
+ return nil
+ }))
+ queued := []*model.Transaction{blocked}
+ model.PerformTransactions(&queued)
+ defer func() {
+ select {
+ case <-allowWrite:
+ default:
+ close(allowWrite)
+ }
+ model.FlushTxQueue()
+ }()
+ select {
+ case <-writeStarted:
+ case <-time.After(5 * time.Second):
+ t.Fatal("queued transaction did not reach its write boundary")
+ }
+ completedPush := make(chan struct{})
+ go func() {
+ pushTransactions("completion-source", "source", []*model.Transaction{completed})
+ close(completedPush)
+ }()
+ select {
+ case <-completedPush:
+ case <-time.After(5 * time.Second):
+ t.Fatal("completed transaction broadcast waited for an unrelated queued transaction")
+ }
+ blockedPush := make(chan struct{})
+ go func() {
+ pushTransactions("completion-source", "source", queued)
+ close(blockedPush)
+ }()
+ select {
+ case <-blockedPush:
+ t.Fatal("transaction broadcast returned before its write finished")
+ case <-time.After(20 * time.Millisecond):
+ }
+ close(allowWrite)
+ select {
+ case <-blockedPush:
+ case <-time.After(5 * time.Second):
+ t.Fatal("completed queued transaction was not broadcast")
+ }
+ if err = connection.SetReadDeadline(time.Now().Add(5 * time.Second)); err != nil {
+ t.Fatal(err)
+ }
+ for {
+ var event struct {
+ Cmd string `json:"cmd"`
+ Data json.RawMessage `json:"data"`
+ Context struct {
+ RootIDs []string `json:"rootIDs"`
+ UndoState map[string]map[string]bool `json:"undoState"`
+ } `json:"context"`
+ }
+ if err = connection.ReadJSON(&event); err != nil {
+ t.Fatal(err)
+ }
+ if event.Cmd != "transactions" {
+ continue
+ }
+ var transactions []*model.Transaction
+ if err = json.Unmarshal(event.Data, &transactions); err != nil {
+ t.Fatal(err)
+ }
+ if len(transactions) != 1 || len(transactions[0].DoOperations) == 0 ||
+ transactions[0].DoOperations[0].ID != paragraphID {
+ continue
+ }
+ if len(event.Context.RootIDs) != 1 || event.Context.RootIDs[0] != docID || !event.Context.UndoState[docID]["canUndo"] {
+ t.Fatalf("broadcast preceded committed document and undo metadata: %+v", event.Context)
+ }
+ break
+ }
+ body, err := json.Marshal(map[string]any{"transactions": []*model.Transaction{{
+ DoOperations: []*model.Operation{{Action: "update", ID: paragraphID, Data: dom("HTTP edit")}},
+ UndoOperations: []*model.Operation{{Action: "update", ID: paragraphID, Data: dom("Queued edit")}},
+ }}, "reqId": 456, "app": "contract", "session": "contract"})
+ if err != nil {
+ t.Fatal(err)
+ }
+ recorder := httptest.NewRecorder()
+ engine.ServeHTTP(recorder, httptest.NewRequest(http.MethodPost, "/api/transactions", strings.NewReader(string(body))))
+ requireAPIContract(t, http.MethodPost, "/api/transactions", recorder)
+ var result struct {
+ Code int `json:"code"`
+ }
+ if err = json.Unmarshal(recorder.Body.Bytes(), &result); err != nil || result.Code != 0 {
+ t.Fatalf("editing request failed: %s, %v", recorder.Body.String(), err)
+ }
+ tree, err := model.LoadTreeByBlockID(paragraphID)
+ if err != nil || treenode.GetNodeInTree(tree, paragraphID).Text() != "HTTP edit" {
+ t.Fatalf("editing response preceded persisted content: %v", err)
+ }
+ t.Logf("isolated editing request Server-Timing: %s", recorder.Header().Get("Server-Timing"))
+}
diff --git a/kernel/api/transaction.go b/kernel/api/transaction.go
index 46234b41b0..39d2b81227 100644
--- a/kernel/api/transaction.go
+++ b/kernel/api/transaction.go
@@ -185,10 +185,13 @@ func holdTransactionEncryptedBoxRequests(c *gin.Context, transactions []*model.T
}
func pushTransactions(app, session string, transactions []*model.Transaction) {
+ // 等待本批事务执行完毕,再读取变更文档和撤销状态并广播。
+ for _, tx := range transactions {
+ tx.WaitForCommit()
+ }
+
pushMode := util.PushModeBroadcastExcludeSelf
if 0 < len(transactions) && 0 < len(transactions[0].DoOperations) {
- model.FlushTxQueue() // 等待文件写入完成,后续渲染才能读取到最新的数据
-
if shouldBroadcastAttrViewTransactions(transactions) {
pushMode = util.PushModeBroadcast
}
@@ -205,10 +208,6 @@ func pushTransactions(app, session string, transactions []*model.Transaction) {
}
rootIDs = gulu.Str.RemoveDuplicatedElem(rootIDs)
- for _, tx := range transactions {
- tx.WaitForCommit()
- }
-
// 附带每个 rootID 的撤销/重做可用状态,供前端本地镜像同步(多窗口/多端按钮态)
// 必须在 WaitForCommit 之后读取,确保 Record 已完成,状态含最新条目
undoStates := map[string]map[string]bool{}
diff --git a/kernel/model/transaction.go b/kernel/model/transaction.go
index b5e0b19cd9..c8590ff280 100644
--- a/kernel/model/transaction.go
+++ b/kernel/model/transaction.go
@@ -70,6 +70,8 @@ func FlushTxQueue() {
// 与异步入队的 PerformTransactions 不同,这里直接持有 flushLock 串行执行 performTx,
// 失败时返回原始错误(不转成推送消息),调用方可以保留待处理数据或回滚状态。
func PerformTxSync(tx *Transaction) (err error) {
+ completion := tx.prepareCommitWait()
+ defer close(completion.done)
defer logging.Recover()
flushLock.Lock()
isFlushing.Store(true)
@@ -124,6 +126,9 @@ func flushQueue() {
}
func flushTx(tx *Transaction) {
+ if completion := tx.completion.Load(); completion != nil {
+ defer close(completion.done)
+ }
defer logging.Recover()
start := time.Now()
@@ -179,6 +184,7 @@ func PerformTransactions(transactions *[]*Transaction) {
defer txQueueLock.Unlock()
for _, tx := range *transactions {
tx.m = &sync.Mutex{}
+ tx.prepareCommitWait()
txQueue = append(txQueue, tx)
}
sort.SliceStable(txQueue, func(i, j int) bool {
@@ -189,6 +195,8 @@ func PerformTransactions(transactions *[]*Transaction) {
// PerformTransactionSync 先执行已排队编辑,再同步执行事务并返回实际错误,同时发送事务错误通知。
// 主动跳过的操作保持成功语义,结构校验或提交失败仍返回错误。
func PerformTransactionSync(transaction *Transaction) (err error) {
+ completion := transaction.prepareCommitWait()
+ defer close(completion.done)
flushLock.Lock()
isFlushing.Store(true)
defer func() {
@@ -2706,6 +2714,10 @@ func (tx *Transaction) recordCrossTreeMoveRefRefresh(srcTree, targetTree *parse.
})
}
+type transactionCompletion struct {
+ done chan struct{}
+}
+
type Transaction struct {
Timestamp int64 `json:"timestamp"`
DoOperations []*Operation `json:"doOperations"`
@@ -2753,6 +2765,7 @@ type Transaction struct {
luteEngine *lute.Lute
m *sync.Mutex
state atomic.Int32 // 0: 初始化,1:未提交,:2: 已提交,3: 已回滚
+ completion atomic.Pointer[transactionCompletion]
}
func (tx *Transaction) GetChangedRootIDs() (ret []string) {
@@ -2786,7 +2799,19 @@ func (tx *Transaction) GetMutatedRootIDs() (ret []string) {
return
}
+// 每次入队或同步执行前建立独立完成信号,执行入口在提交、回滚及后续处理结束后关闭。
+func (tx *Transaction) prepareCommitWait() *transactionCompletion {
+ completion := &transactionCompletion{done: make(chan struct{})}
+ tx.completion.Store(completion)
+ return completion
+}
+
func (tx *Transaction) WaitForCommit() {
+ if completion := tx.completion.Load(); completion != nil {
+ <-completion.done
+ return
+ }
+ // 未经过执行入口的内部事务保留按执行状态等待的行为。
for {
if 1 == tx.state.Load() {
time.Sleep(10 * time.Millisecond)
diff --git a/kernel/model/transaction_completion_fts5_test.go b/kernel/model/transaction_completion_fts5_test.go
new file mode 100644
index 0000000000..83ae64e517
--- /dev/null
+++ b/kernel/model/transaction_completion_fts5_test.go
@@ -0,0 +1,58 @@
+//go:build fts5
+
+package model
+
+import (
+ "fmt"
+ "slices"
+ "testing"
+ "time"
+
+ "github.com/siyuan-note/siyuan/kernel/treenode"
+)
+
+func TestTransactionCompletionWaitsForUndoRecordAndCleanup(t *testing.T) {
+ fixture := setupStructureTransactionTest(t)
+ setupFoldTransactionDatabase(t, fixture)
+ previous := GlobalUndoLog
+ log := newUndoLog(64)
+ GlobalUndoLog = log
+ t.Cleanup(func() { GlobalUndoLog = previous })
+ log.mu.Lock()
+ locked := true
+ defer func() {
+ if locked {
+ log.mu.Unlock()
+ }
+ FlushTxQueue()
+ }()
+ tx := &Transaction{
+ DoOperations: []*Operation{{Action: "update", ID: fixture.childID,
+ Data: fmt.Sprintf(`<div data-node-id="%s" data-type="NodeParagraph"><div contenteditable="true">Committed text</div></div>`, fixture.childID)}},
+ UndoOperations: []*Operation{{Action: "update", ID: fixture.childID, Data: "Original text"}},
+ }
+ tx.MarkFromAPI()
+ transactions := []*Transaction{tx}
+ PerformTransactions(&transactions)
+ waiter := waitForTransactionInTest(tx)
+ deadline := time.Now().Add(5 * time.Second)
+ for tx.state.Load() != 2 {
+ if time.Now().After(deadline) {
+ t.Fatal("transaction did not reach its committed state")
+ }
+ time.Sleep(time.Millisecond)
+ }
+ // 写盘成功但撤销日志尚未记录时,完成等待不能放行。
+ requireTransactionWaiting(t, waiter)
+ log.mu.Unlock()
+ locked = false
+ requireTransactionFinished(t, waiter)
+ canUndo, _, _ := log.State(fixture.sourceID)
+ if !canUndo || !slices.Equal(tx.GetChangedRootIDs(), []string{fixture.sourceID}) || tx.trees != nil || tx.nodes != nil {
+ t.Fatal("completion was published before undo state and released resources were ready")
+ }
+ tree, err := LoadTreeByBlockID(fixture.childID)
+ if err != nil || treenode.GetNodeInTree(tree, fixture.childID).Text() != "Committed text" {
+ t.Fatalf("completed transaction did not persist its content: %v", err)
+ }
+}
diff --git a/kernel/model/transaction_completion_test.go b/kernel/model/transaction_completion_test.go
new file mode 100644
index 0000000000..c52ce53748
--- /dev/null
+++ b/kernel/model/transaction_completion_test.go
@@ -0,0 +1,151 @@
+package model
+
+import (
+ "testing"
+ "time"
+
+ "github.com/88250/lute/ast"
+ "github.com/88250/lute/parse"
+)
+
+func waitForTransactionInTest(tx *Transaction) <-chan struct{} {
+ done := make(chan struct{})
+ go func() {
+ tx.WaitForCommit()
+ close(done)
+ }()
+ return done
+}
+
+func requireTransactionWaiting(t *testing.T, done <-chan struct{}) {
+ t.Helper()
+ select {
+ case <-done:
+ t.Fatal("transaction wait returned before execution finished")
+ case <-time.After(20 * time.Millisecond):
+ }
+}
+
+func requireTransactionFinished(t *testing.T, done <-chan struct{}) {
+ t.Helper()
+ select {
+ case <-done:
+ case <-time.After(5 * time.Second):
+ t.Fatal("transaction wait did not return after execution finished")
+ }
+}
+
+func TestQueuedTransactionWaitForCommit(t *testing.T) {
+ FlushTxQueue()
+ flushLock.Lock()
+ defer func() {
+ for _, tx := range takeQueuedTransactions() {
+ flushTx(tx)
+ }
+ flushLock.Unlock()
+ }()
+ first := &Transaction{Timestamp: 1}
+ second := &Transaction{Timestamp: 2}
+ transactions := []*Transaction{second, first}
+ PerformTransactions(&transactions)
+ firstWaiters := []<-chan struct{}{waitForTransactionInTest(first), waitForTransactionInTest(first)}
+ secondWaiter := waitForTransactionInTest(second)
+ for _, done := range firstWaiters {
+ requireTransactionWaiting(t, done)
+ }
+ requireTransactionWaiting(t, secondWaiter)
+ queued := takeQueuedTransactions()
+ if len(queued) != 2 || queued[0] != first || queued[1] != second {
+ t.Fatalf("transaction timestamp order changed: %v", queued)
+ }
+ // 队列已取走但仍未执行时,完成等待必须继续阻塞。
+ requireTransactionWaiting(t, firstWaiters[0])
+ flushTx(first)
+ for _, done := range firstWaiters {
+ requireTransactionFinished(t, done)
+ }
+ requireTransactionWaiting(t, secondWaiter)
+ flushTx(second)
+ requireTransactionFinished(t, secondWaiter)
+ requireTransactionFinished(t, waitForTransactionInTest(first))
+}
+
+func TestTransactionCompletionOnAllExecutionExits(t *testing.T) {
+ fixture := setupStructureTransactionTest(t)
+ for _, mode := range []string{"sync", "queue", "sync-notify"} {
+ for _, kind := range []string{"empty", "invalid", "panic", "begin-error"} {
+ t.Run(mode+"/"+kind, func(t *testing.T) {
+ tx := &Transaction{}
+ switch kind {
+ case "invalid":
+ tx.DoOperations = []*Operation{{Action: "update", ID: fixture.childID, Data: 1}}
+ case "panic":
+ tx.DoOperations = []*Operation{nil}
+ case "begin-error":
+ tx.templateDocTreeRootSnapshot = &parse.Tree{ID: "different-parent"}
+ tx.DoOperations = []*Operation{{Action: "restoreCreatedDoc", templateDocTreeRootID: fixture.sourceID,
+ Tree: &parse.Tree{Box: fixture.box.ID, Root: &ast.Node{ID: "created"}}}}
+ }
+ if mode != "queue" {
+ run := PerformTxSync
+ if mode == "sync-notify" {
+ run = PerformTransactionSync
+ }
+ err := run(tx)
+ if (err == nil) != (kind == "empty" || (kind == "panic" && mode == "sync")) {
+ t.Fatalf("unexpected %s result: %v", kind, err)
+ }
+ } else {
+ transactions := []*Transaction{tx}
+ PerformTransactions(&transactions)
+ }
+ requireTransactionFinished(t, waitForTransactionInTest(tx))
+ if state := tx.state.Load(); state == 1 {
+ t.Fatal("transaction wait returned while a transaction remained active")
+ }
+ })
+ }
+ }
+}
+
+func TestTransactionCompletionRepeatedSyncExecution(t *testing.T) {
+ tx := &Transaction{}
+ for i := 0; i < 2; i++ {
+ if err := PerformTxSync(tx); err != nil {
+ t.Fatal(err)
+ }
+ requireTransactionFinished(t, waitForTransactionInTest(tx))
+ }
+}
+
+func TestTransactionCompletionWaitsForSyncExecution(t *testing.T) {
+ for _, run := range []func(*Transaction) error{PerformTxSync, PerformTransactionSync} {
+ tx := &Transaction{}
+ flushLock.Lock()
+ unlocked := false
+ func() {
+ defer func() {
+ if !unlocked {
+ flushLock.Unlock()
+ }
+ }()
+ result := make(chan error, 1)
+ go func() { result <- run(tx) }()
+ deadline := time.Now().Add(5 * time.Second)
+ for tx.completion.Load() == nil {
+ if time.Now().After(deadline) {
+ t.Fatal("synchronous transaction did not register its pending completion")
+ }
+ time.Sleep(time.Millisecond)
+ }
+ waiter := waitForTransactionInTest(tx)
+ requireTransactionWaiting(t, waiter)
+ flushLock.Unlock()
+ unlocked = true
+ requireTransactionFinished(t, waiter)
+ if err := <-result; err != nil {
+ t.Fatal(err)
+ }
+ }()
+ }
+}