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.
Dart airdrop-alternativeclipboardclipboard-sharingclipboard-synccopy-pastecross-platformend-to-end-encryptionfile-syncfile-transferfluttergolanglinuxmacosnat-traversalp2pself-hostedtailscaleuniversal-clipboardwebrtcwindows
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)
}
})
}