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"
	"os"
	"path/filepath"
	"regexp"
)

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

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