chore: directory migration - gateway→server, web→client/electron

server/internal/blob/list_test.go

@@ -0,0 +1,176 @@
+package blob
+
+// List() 的测试 —— 反向 GC 的前提。
+//
+// 事故背景：附件 GC 原先只从**库记录**出发（`WHERE mail_id IS NULL`），于是一旦
+// 记录本身消失（清库、手工 DELETE、迁移），对应文件就永远脱离了视野。本机实测
+// 磁盘 8 个 blob 里 7 个没有任何库记录，全部来自一次清库，之后一直占着盘。
+
+import (
+	"bytes"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestListReturnsStoredContents(t *testing.T) {
+	s, err := New(t.TempDir())
+	if err != nil {
+		t.Fatalf("new store: %v", err)
+	}
+
+	sumA, _, err := s.Put(bytes.NewReader([]byte("alpha")), 0)
+	if err != nil {
+		t.Fatalf("put a: %v", err)
+	}
+	sumB, _, err := s.Put(bytes.NewReader([]byte("beta")), 0)
+	if err != nil {
+		t.Fatalf("put b: %v", err)
+	}
+
+	got, err := s.List()
+	if err != nil {
+		t.Fatalf("list: %v", err)
+	}
+	if len(got) != 2 {
+		t.Fatalf("应列出 2 个内容，实际 %d：%v", len(got), got)
+	}
+	for _, sum := range []string{sumA, sumB} {
+		mod, ok := got[sum]
+		if !ok {
+			t.Errorf("缺少 %s", sum[:8])
+			continue
+		}
+		if mod.IsZero() {
+			t.Errorf("%s 的修改时间为零值 —— GC 靠它判断「是否可能正在上传」", sum[:8])
+		}
+	}
+}
+
+func TestListEmptyStore(t *testing.T) {
+	s, err := New(t.TempDir())
+	if err != nil {
+		t.Fatalf("new store: %v", err)
+	}
+	got, err := s.List()
+	if err != nil {
+		t.Fatalf("空库不该报错: %v", err)
+	}
+	if len(got) != 0 {
+		t.Fatalf("空库应返回空，实际 %v", got)
+	}
+}
+
+// **关键用例**：`.upload-*` 临时文件绝不能进列表。
+//
+// 报给调用方会让 GC 去删一个正在写入的文件 —— 上传是「先落盘再入库」，
+// 那一瞬间的临时文件既没有库记录也不是合法 sha256 命名。
+func TestListSkipsTempUploads(t *testing.T) {
+	root := t.TempDir()
+	s, err := New(root)
+	if err != nil {
+		t.Fatalf("new store: %v", err)
+	}
+	sum, _, err := s.Put(bytes.NewReader([]byte("real")), 0)
+	if err != nil {
+		t.Fatalf("put: %v", err)
+	}
+
+	// 模拟一个正在进行的上传
+	tmp, err := os.CreateTemp(root, ".upload-*")
+	if err != nil {
+		t.Fatalf("create temp: %v", err)
+	}
+	tmp.WriteString("half written")
+	tmp.Close()
+
+	got, err := s.List()
+	if err != nil {
+		t.Fatalf("list: %v", err)
+	}
+	if len(got) != 1 {
+		t.Fatalf("只该列出 1 个真实内容，实际 %d：%v", len(got), got)
+	}
+	if _, ok := got[sum]; !ok {
+		t.Errorf("真实内容 %s 应在列表里", sum[:8])
+	}
+	for k := range got {
+		if strings.HasPrefix(k, ".upload-") {
+			t.Errorf("临时文件 %q 不该出现在列表里 —— GC 会删掉一个正在写入的文件", k)
+		}
+	}
+}
+
+// 非 sha256 命名的异物一律忽略（人手工丢进去的、别的程序留下的）。
+func TestListSkipsForeignFiles(t *testing.T) {
+	root := t.TempDir()
+	s, err := New(root)
+	if err != nil {
+		t.Fatalf("new store: %v", err)
+	}
+	if _, _, err := s.Put(bytes.NewReader([]byte("real")), 0); err != nil {
+		t.Fatalf("put: %v", err)
+	}
+
+	// 放几个不合法命名的文件在两级目录里
+	for _, name := range []string{"README", "ABCDEF", "notasha256"} {
+		dir := filepath.Join(root, "ab", "cd")
+		if err := os.MkdirAll(dir, 0o700); err != nil {
+			t.Fatalf("mkdir: %v", err)
+		}
+		if err := os.WriteFile(filepath.Join(dir, name), []byte("x"), 0o600); err != nil {
+			t.Fatalf("write %s: %v", name, err)
+		}
+	}
+
+	got, err := s.List()
+	if err != nil {
+		t.Fatalf("list: %v", err)
+	}
+	if len(got) != 1 {
+		t.Fatalf("异物不该被列出，实际 %d：%v", len(got), got)
+	}
+}
+
+// 修改时间必须是真实的文件时间 —— GC 用它跳过「可能正在上传」的文件。
+func TestListReportsRealModTime(t *testing.T) {
+	s, err := New(t.TempDir())
+	if err != nil {
+		t.Fatalf("new store: %v", err)
+	}
+	before := time.Now().Add(-time.Second)
+	sum, _, err := s.Put(bytes.NewReader([]byte("timed")), 0)
+	if err != nil {
+		t.Fatalf("put: %v", err)
+	}
+	after := time.Now().Add(time.Second)
+
+	got, err := s.List()
+	if err != nil {
+		t.Fatalf("list: %v", err)
+	}
+	mod := got[sum]
+	if mod.Before(before) || mod.After(after) {
+		t.Fatalf("修改时间 %v 不在 [%v, %v] 内", mod, before, after)
+	}
+}
+
+// 根目录不存在时必须报错，不能返回空列表。
+//
+// 返回空会让调用方以为「库里什么都没有」—— 那个判断会传导到 GC 的计数上，
+// 让运维以为磁盘是干净的。
+func TestListFailsOnMissingRoot(t *testing.T) {
+	root := t.TempDir()
+	s, err := New(root)
+	if err != nil {
+		t.Fatalf("new store: %v", err)
+	}
+	if err := os.RemoveAll(root); err != nil {
+		t.Fatalf("rm root: %v", err)
+	}
+	if _, err := s.List(); err == nil {
+		t.Fatal("根目录不存在时必须报错，返回空列表会让调用方以为库是空的")
+	}
+}

server/internal/blob/store.go

@@ -0,0 +1,191 @@
+// Package blob 提供附件文件的内容寻址存储。
+//
+// 设计取舍：文件内容存磁盘、数据库只存元数据。
+// 不把附件塞进 SQLite 的 BLOB —— 附件是「写一次读多次」的冷数据，
+// 塞进库会让 .db 膨胀、WAL 变大、备份变慢，而这些代价换不来任何好处。
+//
+// 路径由内容的 sha256 派生（ab/cdef...），因此：
+//   - 相同内容天然去重，重复上传不占额外空间
+//   - 路径与用户提供的 filename 完全无关，杜绝 ../ 穿越
+//   - 两级目录前缀避免单目录塞进十万个文件
+package blob
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"io"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"regexp"
+	"time"
+)
+
+// Store 是附件的磁盘存储。
+type Store struct {
+	root string
+}
+
+// ErrTooLarge 表示写入的数据超过了给定上限。
+var ErrTooLarge = errors.New("attachment too large")
+
+var sha256Re = regexp.MustCompile(`^[0-9a-f]{64}$`)
+
+// New 打开（必要时创建）一个位于 root 的附件库。
+func New(root string) (*Store, error) {
+	if root == "" {
+		return nil, errors.New("blob: root 不能为空")
+	}
+	if err := os.MkdirAll(root, 0o700); err != nil {
+		return nil, fmt.Errorf("blob: 创建 %s: %w", root, err)
+	}
+	return &Store{root: root}, nil
+}
+
+// Root 返回存储根目录（用于日志与运维排查）。
+func (s *Store) Root() string { return s.root }
+
+// pathFor 由 sha256 推出磁盘路径。
+// 调用前必须确认 sum 是合法的 64 位十六进制，否则可能被拼出库外路径。
+func (s *Store) pathFor(sum string) (string, error) {
+	if !sha256Re.MatchString(sum) {
+		return "", fmt.Errorf("blob: 非法的 sha256 %q", sum)
+	}
+	return filepath.Join(s.root, sum[:2], sum[2:4], sum), nil
+}
+
+// Put 把 r 的内容写入存储，返回内容的 sha256 与字节数。
+//
+// maxBytes > 0 时超限即中止并清理临时文件（不会留下半个文件）。
+// 先写临时文件再按内容哈希 rename：写入过程中崩溃不会产生一个「哈希对不上内容」的文件。
+func (s *Store) Put(r io.Reader, maxBytes int64) (string, int64, error) {
+	tmp, err := os.CreateTemp(s.root, ".upload-*")
+	if err != nil {
+		return "", 0, fmt.Errorf("blob: 创建临时文件: %w", err)
+	}
+	tmpName := tmp.Name()
+	// 失败路径统一清理；成功时 rename 之后这个 Remove 是无害的 no-op
+	defer func() {
+		tmp.Close()
+		os.Remove(tmpName)
+	}()
+
+	h := sha256.New()
+	src := r
+	if maxBytes > 0 {
+		// 多读 1 字节用于判断是否超限：LimitReader 到达上限时只会 EOF，
+		// 无法区分「刚好等于上限」和「超过上限」。
+		src = io.LimitReader(r, maxBytes+1)
+	}
+
+	n, err := io.Copy(io.MultiWriter(tmp, h), src)
+	if err != nil {
+		return "", 0, fmt.Errorf("blob: 写入: %w", err)
+	}
+	if maxBytes > 0 && n > maxBytes {
+		return "", 0, ErrTooLarge
+	}
+	if err := tmp.Sync(); err != nil {
+		return "", 0, fmt.Errorf("blob: sync: %w", err)
+	}
+	if err := tmp.Close(); err != nil {
+		return "", 0, fmt.Errorf("blob: close: %w", err)
+	}
+
+	sum := hex.EncodeToString(h.Sum(nil))
+	dst, err := s.pathFor(sum)
+	if err != nil {
+		return "", 0, err
+	}
+	if err := os.MkdirAll(filepath.Dir(dst), 0o700); err != nil {
+		return "", 0, fmt.Errorf("blob: 创建目录: %w", err)
+	}
+
+	// 已存在同内容文件：内容寻址下这就是同一个文件，直接复用
+	if _, statErr := os.Stat(dst); statErr == nil {
+		return sum, n, nil
+	}
+	if err := os.Rename(tmpName, dst); err != nil {
+		return "", 0, fmt.Errorf("blob: rename: %w", err)
+	}
+	if err := os.Chmod(dst, 0o600); err != nil {
+		return "", 0, fmt.Errorf("blob: chmod: %w", err)
+	}
+	return sum, n, nil
+}
+
+// Open 打开某个内容的读取句柄。调用方负责 Close。
+func (s *Store) Open(sum string) (*os.File, error) {
+	p, err := s.pathFor(sum)
+	if err != nil {
+		return nil, err
+	}
+	return os.Open(p)
+}
+
+// Exists 判断某内容是否已在库中。
+func (s *Store) Exists(sum string) bool {
+	p, err := s.pathFor(sum)
+	if err != nil {
+		return false
+	}
+	_, err = os.Stat(p)
+	return err == nil
+}
+
+// List 枚举库中全部内容文件的 sha256 与修改时间。
+//
+// # 为什么需要它
+//
+// 附件 GC 原先只从**库记录**出发（`WHERE mail_id IS NULL`），于是一旦记录本身
+// 消失（清库、手工 DELETE、迁移），对应文件就永远脱离了视野：本机实测磁盘 8 个
+// blob 里 7 个没有任何库记录，全部来自 09-03 那次清库，之后一直占着盘。
+//
+// 反向清理必须能枚举磁盘，因此这个方法是 `repo.SweepUnreferencedBlobs` 的前提。
+//
+// 只认文件名是合法 sha256 的项：`.upload-*` 临时文件不属于内容库，
+// 把它们报给调用方会让 GC 去删一个正在写入的文件。
+func (s *Store) List() (map[string]time.Time, error) {
+	out := map[string]time.Time{}
+	err := filepath.WalkDir(s.root, func(path string, d fs.DirEntry, err error) error {
+		if err != nil {
+			// 单个子目录读不了不该让整次枚举失败 —— 但**根目录**读不了必须报：
+			// 那时返回空 map 会让调用方以为「库里什么都没有」，
+			// 于是把仍被引用的文件当成孤儿（这里不会删，但计数会骗人）。
+			if path == s.root {
+				return err
+			}
+			return nil
+		}
+		if d.IsDir() || !sha256Re.MatchString(d.Name()) {
+			return nil // .upload-* 临时文件与其他异物
+		}
+		info, iErr := d.Info()
+		if iErr != nil {
+			return nil
+		}
+		out[d.Name()] = info.ModTime()
+		return nil
+	})
+	if err != nil {
+		return nil, fmt.Errorf("blob: 枚举 %s: %w", s.root, err)
+	}
+	return out, nil
+}
+
+// Remove 删除某内容。
+//
+// 注意：内容寻址意味着多条附件记录可能指向同一个文件，
+// 因此调用方必须先确认没有其他记录引用该 sha256 才能删。
+func (s *Store) Remove(sum string) error {
+	p, err := s.pathFor(sum)
+	if err != nil {
+		return err
+	}
+	if err := os.Remove(p); err != nil && !os.IsNotExist(err) {
+		return err
+	}
+	return nil
+}

server/internal/blob/store_test.go

@@ -0,0 +1,171 @@
+package blob
+
+import (
+	"bytes"
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func newStore(t *testing.T) *Store {
+	t.Helper()
+	s, err := New(t.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+	return s
+}
+
+func TestPutAndOpenRoundTrip(t *testing.T) {
+	s := newStore(t)
+	data := []byte("附件内容 with bytes \x00\x01")
+
+	sum, n, err := s.Put(bytes.NewReader(data), 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if n != int64(len(data)) {
+		t.Errorf("写入 %d 字节，报告 %d", len(data), n)
+	}
+
+	h := sha256.Sum256(data)
+	if sum != hex.EncodeToString(h[:]) {
+		t.Errorf("sha256 = %s，与内容不符", sum)
+	}
+
+	f, err := s.Open(sum)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer f.Close()
+	got, _ := io.ReadAll(f)
+	if !bytes.Equal(got, data) {
+		t.Error("读回的内容与写入不一致")
+	}
+}
+
+// 相同内容重复上传必须复用同一个文件，不占额外空间。
+func TestPutDeduplicates(t *testing.T) {
+	s := newStore(t)
+	data := []byte("same content")
+
+	sum1, _, err := s.Put(bytes.NewReader(data), 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	sum2, _, err := s.Put(bytes.NewReader(data), 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if sum1 != sum2 {
+		t.Fatalf("同内容得到不同哈希: %s vs %s", sum1, sum2)
+	}
+
+	// 目录里应当只有一个内容文件（外加两级目录）
+	var files int
+	filepath.Walk(s.Root(), func(_ string, info os.FileInfo, _ error) error {
+		if info != nil && !info.IsDir() {
+			files++
+		}
+		return nil
+	})
+	if files != 1 {
+		t.Errorf("去重后应只剩 1 个文件，实际 %d", files)
+	}
+}
+
+// 超限必须拒绝，且不能留下半个临时文件。
+func TestPutTooLargeLeavesNoGarbage(t *testing.T) {
+	s := newStore(t)
+	data := bytes.Repeat([]byte("x"), 1024)
+
+	_, _, err := s.Put(bytes.NewReader(data), 512)
+	if !errors.Is(err, ErrTooLarge) {
+		t.Fatalf("期望 ErrTooLarge，得到 %v", err)
+	}
+
+	entries, _ := os.ReadDir(s.Root())
+	for _, e := range entries {
+		if strings.HasPrefix(e.Name(), ".upload-") {
+			t.Errorf("超限后残留临时文件 %s", e.Name())
+		}
+	}
+}
+
+// 恰好等于上限应当通过 —— 边界不能误杀。
+func TestPutExactlyAtLimit(t *testing.T) {
+	s := newStore(t)
+	data := bytes.Repeat([]byte("y"), 512)
+
+	if _, n, err := s.Put(bytes.NewReader(data), 512); err != nil {
+		t.Fatalf("恰好等于上限被拒: %v", err)
+	} else if n != 512 {
+		t.Errorf("字节数 = %d，want 512", n)
+	}
+}
+
+// 路径完全由 sha256 派生，任何非法 sum 都不能落到库外。
+func TestPathTraversalRejected(t *testing.T) {
+	s := newStore(t)
+
+	for _, bad := range []string{
+		"../../etc/passwd",
+		"..",
+		"/etc/passwd",
+		"ABCDEF", // 大写非法
+		strings.Repeat("g", 64), // 非十六进制
+		strings.Repeat("a", 63), // 长度不足
+		"",
+	} {
+		if _, err := s.pathFor(bad); err == nil {
+			t.Errorf("pathFor(%q) 应报错", bad)
+		}
+		if _, err := s.Open(bad); err == nil {
+			t.Errorf("Open(%q) 应报错", bad)
+		}
+		if s.Exists(bad) {
+			t.Errorf("Exists(%q) 应为 false", bad)
+		}
+	}
+}
+
+// 生成的路径必须落在库根目录之内。
+func TestPathStaysInsideRoot(t *testing.T) {
+	s := newStore(t)
+	sum := strings.Repeat("ab", 32)
+
+	p, err := s.pathFor(sum)
+	if err != nil {
+		t.Fatal(err)
+	}
+	rel, err := filepath.Rel(s.Root(), p)
+	if err != nil || strings.HasPrefix(rel, "..") {
+		t.Errorf("路径逃出库根: %s", p)
+	}
+}
+
+func TestRemove(t *testing.T) {
+	s := newStore(t)
+	sum, _, err := s.Put(bytes.NewReader([]byte("z")), 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !s.Exists(sum) {
+		t.Fatal("写入后应存在")
+	}
+	if err := s.Remove(sum); err != nil {
+		t.Fatal(err)
+	}
+	if s.Exists(sum) {
+		t.Error("删除后仍存在")
+	}
+	// 重复删除应当幂等，不报错
+	if err := s.Remove(sum); err != nil {
+		t.Errorf("重复删除报错: %v", err)
+	}
+}