192 lines
5.8 KiB
Go
192 lines
5.8 KiB
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
|
||
}
|