feat(workspace-sync): receiver-side .stop marker to pause subtree convergence

Author: root

README.md

@@ -23,8 +23,29 @@
 
 - 共享 token 鉴权
 - 加密传输（AES-GCM）
+- 分块传输（大文件 `upsert_begin/chunk/end`），降低单次内存峰值
+- 发送端长连接复用，减少高频事件下重复建连开销
 
-### 4) 运行模式
+### 4) 接收端本地保护（`.stop`）
+
+- 在**接收端本地目录**下创建 `.stop` 文件，可暂停该目录及子目录的收敛同步。
+- 生效语义：
+  - 忽略该目录下收到的 `upsert/delete/mkdir` 事件
+  - 快照收敛（`snapshot_end` prune）也会跳过该目录
+- 用法示例：
+
+```bash
+# 暂停 docs/ 的收敛
+cd /path/to/receive-dir
+touch docs/.stop
+
+# 恢复收敛
+rm docs/.stop
+```
+
+> 说明：`.stop` 仅作为接收端本地控制标记，不会被远端事件覆盖。
+
+### 5) 运行模式
 
 - `send`：仅发送
 - `receive`：仅接收

internal/syncer/app.go

@@ -189,6 +189,14 @@ func (a *App) applyEvent(evt fileEvent) error {
 	if isExcluded(rel, a.cfg.Excludes) {
 		return nil
 	}
+	if shouldIgnoreStopMarker(rel) {
+		// receiver-local control file; never mutate it from remote
+		return nil
+	}
+	if stopRoot, stopped := a.findStopRoot(rel); stopped {
+		logf("<- skipped by .stop (%s): %s %s\n", stopRoot, evt.Type, rel)
+		return nil
+	}
 	full := filepath.Join(a.cfg.Dir, rel)
 	if !pathWithinBase(full, a.cfg.Dir) {
 		return fmt.Errorf("path escape: %s", rel)
@@ -354,6 +362,50 @@ func pathWithinBase(path, base string) bool {
 	return true
 }
 
+// findStopRoot returns the nearest ancestor directory (or self, if dir)
+// that contains a ".stop" marker file on receiver side.
+func (a *App) findStopRoot(rel string) (string, bool) {
+	rel = filepath.ToSlash(filepath.Clean(rel))
+	if rel == "" || rel == "." {
+		if fileExists(filepath.Join(a.cfg.Dir, ".stop")) {
+			return ".", true
+		}
+		return "", false
+	}
+
+	parts := strings.Split(rel, "/")
+	for i := len(parts); i >= 1; i-- {
+		cand := strings.Join(parts[:i], "/")
+		full := filepath.Join(a.cfg.Dir, filepath.FromSlash(cand))
+		if st, err := os.Stat(full); err == nil && !st.IsDir() {
+			// if current candidate is a file path, check parent directory marker
+			if i == len(parts) {
+				continue
+			}
+		}
+		if fileExists(filepath.Join(full, ".stop")) {
+			return cand, true
+		}
+	}
+	if fileExists(filepath.Join(a.cfg.Dir, ".stop")) {
+		return ".", true
+	}
+	return "", false
+}
+
+func fileExists(path string) bool {
+	st, err := os.Stat(path)
+	return err == nil && !st.IsDir()
+}
+
+func shouldIgnoreStopMarker(rel string) bool {
+	rel = filepath.ToSlash(filepath.Clean(rel))
+	if rel == ".stop" {
+		return true
+	}
+	return strings.HasSuffix(rel, "/.stop")
+}
+
 func (a *App) suppress(rel string, d time.Duration) {
 	a.mu.Lock()
 	defer a.mu.Unlock()
@@ -424,6 +476,16 @@ func (a *App) snapshotEnd(id string) error {
 			}
 			return nil
 		}
+		if shouldIgnoreStopMarker(rel) {
+			// receiver-local stop markers should never be removed by reconcile
+			return nil
+		}
+		if stopRoot, stopped := a.findStopRoot(rel); stopped {
+			if d.IsDir() && rel == stopRoot {
+				return filepath.SkipDir
+			}
+			return nil
+		}
 		if d.IsDir() {
 			return nil
 		}