Skip to content

PasteFerry (隔空贴): clipboard and file sync across macOS, Windows and Linux. Direct-first, end-to-end encrypted. Optional official access: no server to host. Independent self-hosting remains available.

7.6 KB
Raw Blame
package clipboard

import (
	"context"
	"log/slog"
	"time"
)

// Watcher 监听本机剪贴板变化。
//
// macOS 不提供剪贴板变更通知,只能轮询 changeCount。好在 M-1 实测表明
// changeCount、类型列表、detectMetadata 这三项都免授权且合计不到 0.03 秒,
// 因此 300ms 的轮询既跟手又不会造成负担。
type Watcher struct {
	cb   Clipboard
	loop *MainLoop
	log  *slog.Logger

	interval time.Duration
	onChange func(Snapshot)
	// onPermission 在授权状态变化时回调,界面据此引导用户去系统设置
	onPermission func(Permission)

	lastChange     int64
	lastPermission Permission
	// selfWrites 记录本机主动写入剪贴板时的 changeCount,
	// 避免把"自己刚写进去的内容"当成用户的新复制再广播一遍。
	selfWrites map[int64]struct{}
}

type WatcherOptions struct {
	Clipboard    Clipboard
	MainLoop     *MainLoop
	Logger       *slog.Logger
	Interval     time.Duration
	OnChange     func(Snapshot)
	OnPermission func(Permission)
}

func NewWatcher(opts WatcherOptions) *Watcher {
	log := opts.Logger
	if log == nil {
		log = slog.Default()
	}
	interval := opts.Interval
	if interval <= 0 {
		interval = 300 * time.Millisecond
	}
	return &Watcher{
		cb:           opts.Clipboard,
		loop:         opts.MainLoop,
		log:          log,
		interval:     interval,
		onChange:     opts.OnChange,
		onPermission: opts.OnPermission,
		lastChange:   -1,
		selfWrites:   make(map[int64]struct{}),
	}
}

// SetOnChange 设置剪贴板变化的回调。
//
// 单独提供这个方法,是因为同步引擎需要在 Watcher 之后构造
// (引擎依赖 Watcher 读写剪贴板),无法在 NewWatcher 时就把回调传进去。
func (w *Watcher) SetOnChange(fn func(Snapshot)) { w.onChange = fn }

// Run 持续轮询直到 ctx 取消。可在任意 goroutine 中启动——
// 真正接触剪贴板的操作都会被投递到主线程执行。
func (w *Watcher) Run(ctx context.Context) {
	ticker := time.NewTicker(w.interval)
	defer ticker.Stop()

	// 系统主动通知剪贴板变化的平台(Windows)上立即探测,轮询只作兜底;
	// 其他平台这个通道为空,永远不会触发
	notify := changeNotify
	for {
		select {
		case <-ctx.Done():
			return
		case <-ticker.C:
			w.poll(ctx)
		case <-notify:
			settle(ctx, notify, settleDelay, settleMax)
			w.poll(ctx)
		}
	}
}

// 系统通知剪贴板变化后,等通知停下来再读。有的程序一次复制会分几次写剪贴板
// (PowerShell 的 Set-Clipboard、先放 OLE 数据对象再 OleFlushClipboard 的程序),
// 几毫秒内连着来好几个通知;每个都读一次的话,一次复制会记成好几条。
const (
	settleDelay = 100 * time.Millisecond
	settleMax   = 500 * time.Millisecond
)

// settle 等到 delay 内没有新通知为止,最多等 max:一直有通知也不能一直不读。
func settle(ctx context.Context, notify <-chan struct{}, delay, max time.Duration) {
	limit := time.NewTimer(max)
	defer limit.Stop()
	quiet := time.NewTimer(delay)
	defer quiet.Stop()
	for {
		select {
		case <-ctx.Done():
			return
		case <-limit.C:
			return
		case <-quiet.C:
			return
		case <-notify:
			quiet.Reset(delay)
		}
	}
}

func (w *Watcher) poll(ctx context.Context) {
	// 给足超时:万一主线程正卡在授权弹窗上,这里要能干净退出而不是堆积
	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()

	// 探测与比对要在同一个主线程任务里做:write 也在主线程上更新 lastChange、selfWrites。
	// 分开做的话,本机写入正好插在探测与比对之间时,比对拿的是写入前的值,
	// 会把自己写进去的内容当成用户的新复制,再记一条、再发一遍
	type result struct {
		snap        Snapshot
		changed     bool
		first, mine bool
	}
	r, err := CallResult(ctx, w.loop, func() (result, error) {
		snap, err := w.cb.Peek()
		if err != nil || snap.ChangeCount == w.lastChange {
			return result{snap: snap}, err
		}
		r := result{snap: snap, changed: true, first: w.lastChange < 0}
		w.lastChange = snap.ChangeCount
		if _, mine := w.selfWrites[snap.ChangeCount]; mine {
			delete(w.selfWrites, snap.ChangeCount)
			r.mine = true
		}
		return r, nil
	})
	if err != nil {
		w.log.Debug("探测剪贴板失败", "err", err)
		return
	}

	if perm, err := CallResult(ctx, w.loop, func() (Permission, error) {
		return w.cb.Permission(), nil
	}); err == nil && perm != w.lastPermission {
		w.lastPermission = perm
		w.log.Info("剪贴板授权状态变化", "state", perm)
		if w.onPermission != nil {
			w.onPermission(perm)
		}
	}

	snap := r.snap
	switch {
	case !r.changed:
		return
	case r.first:
		// 首轮只记录基线,不把启动前就存在的内容当作新复制广播出去
		w.log.Debug("剪贴板监听已就绪", "changeCount", snap.ChangeCount)
		return
	case r.mine:
		// 本机刚写进去的内容不该被当成用户的新复制再同步一轮
		w.log.Debug("跳过本机写入触发的变化", "changeCount", snap.ChangeCount)
		return
	case snap.Sensitive:
		// 密码等敏感内容:不同步,也不进复制记录
		w.log.Debug("跳过标记为敏感的内容", "changeCount", snap.ChangeCount)
		return
	}

	w.log.Debug("检测到剪贴板变化",
		"changeCount", snap.ChangeCount, "kind", snap.Kind,
		"type", snap.ContentType, "types", snap.Types)
	if w.onChange != nil {
		w.onChange(snap)
	}
}

// Read 在主线程读取剪贴板内容,并先行检查授权状态。
func (w *Watcher) Read(ctx context.Context) (Content, error) {
	perm, err := CallResult(ctx, w.loop, func() (Permission, error) {
		return w.cb.Permission(), nil
	})
	if err != nil {
		return Content{}, err
	}
	// 未授权时不要贸然读取:会阻塞在一个对后台进程可能不可见的弹窗上
	if !perm.CanReadSilently() {
		return Content{}, ErrPermissionRequired
	}
	return CallResult(ctx, w.loop, w.cb.Read)
}

// Write 在主线程写入剪贴板,并记下由此产生的 changeCount,
// 使下一轮轮询不会把它误判为用户的新复制。
func (w *Watcher) Write(ctx context.Context, content Content) error {
	_, err := w.write(ctx, content, nil)
	return err
}

// Revision reads metadata only. A failed read must never authorize a later write.
func (w *Watcher) Revision(ctx context.Context) (int64, error) {
	snap, err := CallResult(ctx, w.loop, w.cb.Peek)
	return snap.ChangeCount, err
}

// WriteIfUnchanged checks and writes in the same main-loop task, including
// changes made by other remote transfers and copies of sensitive content.
func (w *Watcher) WriteIfUnchanged(ctx context.Context, content Content, revision int64) (bool, error) {
	return w.write(ctx, content, &revision)
}

func (w *Watcher) write(ctx context.Context, content Content, revision *int64) (bool, error) {
	return CallResult(ctx, w.loop, func() (bool, error) {
		if revision != nil {
			snap, err := w.cb.Peek()
			if err != nil {
				return false, err
			}
			if snap.ChangeCount != *revision {
				return false, nil
			}
		}
		if err := w.cb.Write(content); err != nil {
			return false, err
		}
		if snap, err := w.cb.Peek(); err == nil {
			w.selfWrites[snap.ChangeCount] = struct{}{}
			w.lastChange = snap.ChangeCount
		}
		return true, nil
	})
}

func (w *Watcher) Permission(ctx context.Context) Permission {
	perm, err := CallResult(ctx, w.loop, func() (Permission, error) {
		return w.cb.Permission(), nil
	})
	if err != nil {
		return PermissionNotApplicable
	}
	return perm
}

func (w *Watcher) OpenPermissionSettings(ctx context.Context) error {
	return w.loop.Call(ctx, func() {
		if err := w.cb.OpenPermissionSettings(); err != nil {
			w.log.Warn("打开授权设置失败", "err", err)
		}
	})
}