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.

12.7 KB
Raw Blame
package pack

// 隔空传送的数据流:一串「帧」,整体经 zstd 压缩。与复制同步用的 tar 流不同,
// 它能从任意一个文件的任意位置接着发,断了以后不用从头再来。见 design/send-files.md 第 6.3 节。
//
//	file{index, path, size, offset, …}   ← 4 字节大端长度 + 序列化的 SendFrame
//	<size - offset 个字节的文件内容>       ← 目录和符号链接没有
//	file_end{sha256}                     ← 只有普通文件有,是整个文件的哈希
//	file{index+1, …}
//	…
//	end{}

import (
	"bufio"
	"context"
	"crypto/sha256"
	"encoding/binary"
	"errors"
	"fmt"
	"hash"
	"io"
	"io/fs"
	"os"
	"path"
	"path/filepath"
	"strings"

	"github.com/klauspost/compress/zstd"
	"golang.org/x/text/unicode/norm"
	"google.golang.org/protobuf/proto"

	pb "github.com/baiyuze/pasteferry/proto/gen/pasteferry/v1"
)

// maxFrameSize 是一个控制帧的上限。帧里只有路径和几个数字,远用不了这么多;
// 对端发来更大的长度说明数据流坏了,不能照着去分配内存。
const maxFrameSize = 64 << 10

var (
	// ErrSourceChanged 表示源文件在发起之后被改过(大小或修改时间变了)
	ErrSourceChanged = errors.New("源文件在发送过程中被修改了")
	// ErrSourceMissing 表示源文件已经不在了
	ErrSourceMissing = errors.New("源文件已经不在了")
)

// ReadError 是读源文件时出的错,与写数据通道出的错(连接断了)区分开。
type ReadError struct{ Err error }

func (e *ReadError) Error() string { return "读取源文件: " + e.Err.Error() }
func (e *ReadError) Unwrap() error { return e.Err }

// Entry 是隔空传送清单里的一项:一个文件、目录或符号链接。
type Entry struct {
	Path   string // 相对路径,正斜杠分隔,第一段是顶层项目的名字
	Source string // 本机的完整路径,只在发送方有意义
	Size   int64
	IsDir  bool
	Mode   uint32
	MTime  int64
	Link   string // 非空表示符号链接,值是它指向的位置
}

// Top 是一个顶层项目,也就是用户拖进来的一个文件或文件夹。
type Top struct {
	Name  string
	Size  int64 // 文件夹是里面所有文件的总大小
	IsDir bool
}

// BuildManifest 遍历用户选中的路径,按发送的顺序列出所有条目。
//
// 顶层是符号链接时发送它指向的内容(用户拖的是一个替身,要的是原件);
// 文件夹里面的符号链接按链接本身发送,不跟随,免得把整个外部目录卷进来。
// 打不开的文件跳过,与复制同步一致:尽量把能传的传过去。
// progress 每找到 500 个文件回调一次,可以为 nil。
func BuildManifest(ctx context.Context, paths []string, progress func(files int64)) ([]Entry, []Top, error) {
	var entries []Entry
	var tops []Top
	used := map[string]bool{}
	var files int64
	for _, root := range paths {
		info, err := os.Stat(root) // 跟随顶层的符号链接
		if err != nil {
			return nil, nil, fmt.Errorf("%w: %s", ErrSourceMissing, root)
		}
		name := uniqueTop(used, filepath.Base(root), info.IsDir())
		top := Top{Name: name, IsDir: info.IsDir()}
		if !info.IsDir() {
			if !readable(root) {
				return nil, nil, &ReadError{fmt.Errorf("打不开 %s", root)}
			}
			entries = append(entries, entryFor(name, root, info, ""))
			top.Size = info.Size()
			tops = append(tops, top)
			files++
			continue
		}
		resolved, err := filepath.EvalSymlinks(root)
		if err != nil {
			return nil, nil, &ReadError{err}
		}
		err = filepath.WalkDir(resolved, func(p string, d fs.DirEntry, err error) error {
			if err := ctx.Err(); err != nil {
				return err
			}
			if err != nil {
				if d != nil && d.IsDir() && p != resolved {
					return fs.SkipDir // 读不了的子文件夹跳过
				}
				return nil
			}
			if p != resolved && skipWhenPacking(d.Name()) {
				return nil
			}
			rel, err := filepath.Rel(resolved, p)
			if err != nil {
				return err
			}
			entryPath := name
			if rel != "." {
				entryPath = name + "/" + filepath.ToSlash(rel)
			}
			info, err := d.Info()
			if err != nil {
				return nil
			}
			var link string
			switch {
			case info.Mode()&os.ModeSymlink != 0:
				if link, err = os.Readlink(p); err != nil || link == "" {
					return nil
				}
			case info.Mode().IsRegular():
				if !readable(p) {
					return nil
				}
				top.Size += info.Size()
				files++
				if progress != nil && files%500 == 0 {
					progress(files)
				}
			case !info.IsDir():
				return nil // 设备文件、管道之类不传
			}
			entries = append(entries, entryFor(entryPath, p, info, link))
			return nil
		})
		if err != nil {
			return nil, nil, err
		}
		tops = append(tops, top)
	}
	if progress != nil {
		progress(files)
	}
	return entries, tops, nil
}

func entryFor(rel, source string, info os.FileInfo, link string) Entry {
	e := Entry{Path: rel, Source: source, IsDir: info.IsDir(), Mode: uint32(info.Mode().Perm()), MTime: info.ModTime().Unix(), Link: link}
	if info.Mode().IsRegular() {
		e.Size = info.Size()
	}
	return e
}

func readable(p string) bool {
	f, err := os.Open(p)
	if err != nil {
		return false
	}
	f.Close()
	return true
}

// uniqueTop 让两个同名的顶层项目(从不同文件夹拖进来的)各有各的名字。
func uniqueTop(used map[string]bool, name string, isDir bool) string {
	ext := path.Ext(name)
	stem := strings.TrimSuffix(name, ext)
	if isDir {
		stem, ext = name, ""
	}
	candidate := name
	for n := 2; used[strings.ToLower(candidate)]; n++ {
		candidate = fmt.Sprintf("%s (%d)%s", stem, n, ext)
	}
	used[strings.ToLower(candidate)] = true
	return candidate
}

// ─────────────────────── 发送方 ───────────────────────

// FrameWriter 把条目写成帧流。
type FrameWriter struct {
	enc  *zstd.Encoder
	sent func(n int64)
}

// NewFrameWriter 在 w 上开一个帧流。sent 在写出文件内容时收到字节数(未压缩),用来报进度,可以为 nil。
func NewFrameWriter(w io.Writer, sent func(n int64)) (*FrameWriter, error) {
	enc, err := zstd.NewWriter(w, zstd.WithEncoderLevel(zstd.SpeedFastest))
	if err != nil {
		return nil, fmt.Errorf("创建压缩流: %w", err)
	}
	return &FrameWriter{enc: enc, sent: sent}, nil
}

func (fw *FrameWriter) frame(f *pb.SendFrame) error {
	data, err := proto.Marshal(f)
	if err != nil {
		return err
	}
	var hdr [4]byte
	binary.BigEndian.PutUint32(hdr[:], uint32(len(data)))
	if _, err := fw.enc.Write(hdr[:]); err != nil {
		return err
	}
	_, err = fw.enc.Write(data)
	return err
}

// WriteEntry 发一个条目,普通文件从 offset 处接着发。
// 源文件的大小或修改时间与清单不一致时返回 ErrSourceChanged,读不了时返回 *ReadError,
// 其他错误来自数据流本身(多半是连接断了)。
func (fw *FrameWriter) WriteEntry(index int64, e Entry, offset int64) error {
	start := &pb.SendFileStart{
		Index: index, Path: e.Path, Size: e.Size, IsDir: e.IsDir,
		Mode: e.Mode, MtimeUnix: e.MTime, LinkTarget: e.Link,
	}
	if e.IsDir || e.Link != "" {
		return fw.frame(&pb.SendFrame{Payload: &pb.SendFrame_File{File: start}})
	}

	f, err := os.Open(e.Source)
	if err != nil {
		if errors.Is(err, fs.ErrNotExist) {
			return ErrSourceMissing
		}
		return &ReadError{err}
	}
	defer f.Close()
	info, err := f.Stat()
	if err != nil {
		return &ReadError{err}
	}
	if info.Size() != e.Size || info.ModTime().Unix() != e.MTime {
		return ErrSourceChanged
	}
	if offset < 0 || offset > e.Size {
		offset = 0
	}
	h := sha256.New()
	if offset > 0 {
		// 续传:哈希要覆盖整个文件,已经发过的那一段从磁盘再读一遍
		if _, err := io.CopyN(h, f, offset); err != nil {
			return &ReadError{err}
		}
	}
	start.Offset = offset
	if err := fw.frame(&pb.SendFrame{Payload: &pb.SendFrame_File{File: start}}); err != nil {
		return err
	}
	out := io.MultiWriter(fw.enc, h)
	if fw.sent != nil {
		out = io.MultiWriter(fw.enc, h, countWriter(fw.sent))
	}
	n, err := io.CopyN(out, readerOnly{f}, e.Size-offset)
	if err != nil {
		var re *readFailure
		if errors.As(err, &re) {
			if errors.Is(re.err, io.EOF) {
				return ErrSourceChanged // 文件变短了
			}
			return &ReadError{re.err}
		}
		if n < e.Size-offset && errors.Is(err, io.EOF) {
			return ErrSourceChanged
		}
		return err
	}
	return fw.frame(&pb.SendFrame{Payload: &pb.SendFrame_FileEnd{FileEnd: &pb.SendFileEnd{Sha256: h.Sum(nil)}}})
}

// Finish 写结束帧并刷出压缩流里剩下的数据。
func (fw *FrameWriter) Finish() error {
	if err := fw.frame(&pb.SendFrame{Payload: &pb.SendFrame_End{End: &pb.SendStreamEnd{}}}); err != nil {
		return err
	}
	return fw.enc.Close()
}

// Close 在出错时释放压缩流,不再写任何东西。
func (fw *FrameWriter) Close() { fw.enc.Reset(io.Discard) }

// readFailure 标出「读源文件」时的错误,与 io.CopyN 里写数据流的错误区分开。
type readFailure struct{ err error }

func (e *readFailure) Error() string { return e.err.Error() }

type readerOnly struct{ f *os.File }

func (r readerOnly) Read(p []byte) (int, error) {
	n, err := r.f.Read(p)
	if err != nil && n == 0 {
		return 0, &readFailure{err}
	}
	return n, nil
}

type countWriter func(int64)

func (c countWriter) Write(p []byte) (int, error) {
	c(int64(len(p)))
	return len(p), nil
}

// ─────────────────────── 接收方 ───────────────────────

// FrameReader 从数据流里依次读出帧和文件内容。
type FrameReader struct {
	dec *zstd.Decoder
	r   *bufio.Reader
}

func NewFrameReader(r io.Reader) (*FrameReader, error) {
	dec, err := zstd.NewReader(r)
	if err != nil {
		return nil, fmt.Errorf("创建解压流: %w", err)
	}
	return &FrameReader{dec: dec, r: bufio.NewReaderSize(dec, 256<<10)}, nil
}

// Next 读下一个帧。数据流在帧中间断开时返回 io.ErrUnexpectedEOF。
func (fr *FrameReader) Next() (*pb.SendFrame, error) {
	var hdr [4]byte
	if _, err := io.ReadFull(fr.r, hdr[:]); err != nil {
		if errors.Is(err, io.EOF) {
			return nil, io.ErrUnexpectedEOF // end 帧之前就没了
		}
		return nil, err
	}
	n := binary.BigEndian.Uint32(hdr[:])
	if n > maxFrameSize {
		return nil, fmt.Errorf("帧长度 %d 超出上限", n)
	}
	buf := make([]byte, n)
	if _, err := io.ReadFull(fr.r, buf); err != nil {
		if errors.Is(err, io.EOF) {
			return nil, io.ErrUnexpectedEOF
		}
		return nil, err
	}
	var f pb.SendFrame
	if err := proto.Unmarshal(buf, &f); err != nil {
		return nil, fmt.Errorf("解析帧: %w", err)
	}
	return &f, nil
}

// CopyContent 把紧跟在 file 帧后面的 n 个字节写进 w,同时算进哈希。
// 数据流提前结束时返回 io.ErrUnexpectedEOF。
func (fr *FrameReader) CopyContent(w io.Writer, h hash.Hash, n int64) (int64, error) {
	got, err := io.CopyN(io.MultiWriter(w, h), fr.r, n)
	if err != nil && errors.Is(err, io.EOF) {
		err = io.ErrUnexpectedEOF
	}
	return got, err
}

func (fr *FrameReader) Close() { fr.dec.Close() }

// Names 决定收到的每个条目在本机落盘时的相对路径。
// Windows 上按 names.go 的规则把名字改成合法的,并处理只差大小写的重名;
// 其他平台原样使用。含 .. 或绝对路径的条目一律拒绝。
type Names struct{ d *destNames }

func NewNames() *Names { return &Names{d: newDestNames()} }

// Rel 返回条目 name(正斜杠分隔)落盘的相对路径(正斜杠分隔)。
func (n *Names) Rel(name string, isDir bool) (string, error) {
	clean := path.Clean(strings.TrimSuffix(name, "/"))
	if clean == "." || clean == ".." || strings.HasPrefix(clean, "../") || strings.HasPrefix(clean, "/") ||
		strings.Contains(clean, "\\") || strings.ContainsRune(clean, 0) {
		return "", fmt.Errorf("数据流中含非法路径: %q", name)
	}
	if !windowsNames {
		return clean, nil
	}
	return n.d.rel(clean, isDir)
}

// Restore 在续传时登记已经落盘的条目,让后面的条目沿用同样的映射、不撞名。
func (n *Names) Restore(name, mapped string, isDir bool) {
	if !windowsNames {
		return
	}
	n.d.used[strings.ToLower(mapped)] = usedName{mapped, isDir}
	if isDir {
		n.d.dirs[path.Clean(name)] = mapped
	}
}

// Renamed 判断一个条目落盘时名字是不是改过(Windows 上替换了不允许的字符,或者与只差大小写的同名条目错开)。
// Mac 上的分解形式统一成组合形式看不出区别,不算改名。
func Renamed(name, local string) bool {
	return path.Base(local) != norm.NFC.String(path.Base(strings.TrimSuffix(name, "/")))
}

// Skip 表示这个条目在本机不该落盘:Windows 上的 .DS_Store 与 AppleDouble 文件。
func Skip(name string) bool { return windowsNames && skipOnWindows(path.Base(name)) }

// SafeJoin 把相对路径接到 base 下面,拒绝逃出 base 的路径。
func SafeJoin(base, rel string) (string, error) { return safeJoin(base, rel) }