MailUI4Agents/gateway/internal/blob/store.go

// 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
}