refactor+feat(documents,channelbridge): 共享存储核心 + IM 入站附件摄取（主人 2.3）
- 抽共享存储核心：internal/runtime/documents/store.go（22 项白名单 + 字节嗅探唯一裁决 + 内容寻址 sha256[:32]+ext + 去重 + 限额 + 路径双检）+ store_meta.go（documents 表唯一写入实现）。
- gateway 改为调用 store，**对外行为零变化**（机器证明：既有 documents_test/chat_documents_test/chat_documents_bounds_test 三个文件 0 行改动且全绿；状态码/响应字段/错误码/审计动作名/限额文档口径全部逐字保留；maxChatDocuments 改为引用 documents.MaxPerMessage）。
- IM 入站附件摄取（channelbridge）：文件类媒体 → store.Save → 挂 model.DocumentMessage(RoleUser) 部件 ⇒ 后续 resolveDocuments 自动抽取/注入/清单；挂载点在「会话解析 + 黑白名单 + 最小打扰」三重闸门之后（被拦消息绝不在盘上留文件）；**不支持的格式不静默**（诚实提示行 + 带来源日志，只记 name/mime/size，名字做展示净化防伪造行）；图片/语音保持既有链路。
- 主会话独立验收：隔离 worktree（M1 的 12 文件）build/vet 绿、全树 59 包 0 FAIL、双平台交叉编译绿、12 条 Inbound 用例 PASS；变异独立复现（关闭 IM 摄取 ⇒ 5 条红，含「落盘文件数 = [] want 1」）。
- ⚠️ 真机边界（需裁决）：现网四个适配器上报的文件媒体**只带 URL**（telegram FileID / qq-obv11 file|url / weixin·kook CDN URL），Media.Data 恒空 ⇒ 本切片只摄**内联字节**，URL 一律「诚实提示，不代取远程」（避免第三份 SSRF 实现）。真机要让「她读到 IM 文件」，需各适配器入站时下载并内联（凭据在各自渠道里，推荐）或新增共享受守卫抓取器。
- 另登记：IM 附件暂未写 chat_messages.document 列（二手回合看不到引用，建议并入 S7）；channelbridge 既有测试夹具在 -race 下有数据竞争（stubSessions.GetOrCreate，与本次无关）。
This commit is contained in:
AskaEth committed
1 parent
51c1672355
commit
2a43035f5d
12 files changed
+1743
-158
No files matched your search
@@ -0,0 +1,349 @@
|
||||
package documents
|
||||
|
||||
// 本文件归属**文档存储核心**（design/24 §3.2；切片 M1）：把 S1 原本长在网关
|
||||
// `internal/services/gateway/documents.go` 里的存储规则（字节嗅探唯一裁决 +
|
||||
// 扩展名白名单 + 内容寻址 + 去重 + 限额 + 元数据）抽成本包的**一份**实现，
|
||||
// 供两条来源路径共用：
|
||||
//
|
||||
// - Web 上传（`POST /api/v1/documents`，网关调用）；
|
||||
// - IM 入站附件（channelbridge 把消息里的文件类媒体交给这里，切片 M1）。
|
||||
//
|
||||
// 为什么必须先抽出来：规则里有安全裁决（嗅探否决、白名单、路径双检），在桥接器
|
||||
// 里再写一套必然漂移；而 `<DataDir>/uploads/documents` 与 `documents` 元数据表
|
||||
// 也必须是**唯一写入面**，S7 的引用计数与 GC 才有单一事实来源。
|
||||
//
|
||||
// 落盘规则与 S1 逐字同源：客户端原始文件名**永不参与路径**，落盘名是
|
||||
// `sha256(bytes)[:32] + ext`，同字节同扩展名必然同名、天然去重；目录 0700、
|
||||
// 文件 0600（继承临时文件）。读侧（`GET /api/v1/documents/{name}`）与装配期
|
||||
// 摄取（Resolver）不改，仍旧只认这个形态的名字。
|
||||
|
||||
import (
|
||||
"context"
|
||||
"crypto/sha256"
|
||||
"encoding/hex"
|
||||
"errors"
|
||||
"fmt"
|
||||
"log/slog"
|
||||
"net/http"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
)
|
||||
|
||||
const (
|
||||
// DefaultMaxBytes 是文档单文件字节的**默认上限**（20 MiB，即
|
||||
// `CHAT_DOCUMENT_MAX_BYTES` 的默认值）。它只在这里定义一次：网关的
|
||||
// `maxDocumentBytes`、配置的 default 标签与 IM 入站附件都从它派生，绝不
|
||||
// 在别处再写一个数（design/24 §3.3：文档上限与图片上限刻意解耦）。
|
||||
DefaultMaxBytes = 20 << 20
|
||||
|
||||
// MaxPerMessage 是**单条消息**（一个回合）可携带的附件数上限
|
||||
// （design/24 §9.4-3 的定稿值 5）。网关的单回合引用上限与 IM 入站附件
|
||||
// 的上限同源于它。
|
||||
MaxPerMessage = 5
|
||||
|
||||
// HashHexLen 是内容寻址落盘名使用的小写十六进制主名长度（32 位十六进制
|
||||
// = 128 位）。读侧的名字形态校验与 sidecar 的键同名同宽。
|
||||
HashHexLen = 32
|
||||
|
||||
// SniffOKMIME 是唯一放行的嗅探结果**基类型**。白名单里每一种文档（文本、
|
||||
// 代码、CSV、JSON、YAML…）经 `http.DetectContentType` 嗅探后都落在
|
||||
// `text/plain`；HTML/XML/SVG/压缩包/可执行文件/判不定者各有自己的签名，
|
||||
// 因此「不是 text/plain」即「拒绝」。
|
||||
SniffOKMIME = "text/plain"
|
||||
|
||||
// tempPattern 是原子落盘用的临时文件前缀（点前缀，绝不与内容寻址名混淆）。
|
||||
tempPattern = ".document-*"
|
||||
|
||||
// dirMode 是文档目录权限；文件权限继承 `os.CreateTemp` 的 0600。
|
||||
dirMode = 0o700
|
||||
|
||||
// uploadsSubDir / documentSubDir 是 `<DataDir>` 之下的默认布局：
|
||||
// `<DataDir>/uploads/documents`。与网关的 `documentSubDir`、组合根给摄取层
|
||||
// 的 UploadsDir 同源，改一处必须同步（否则装配期会去读一个不存在的目录）。
|
||||
uploadsSubDir = "uploads"
|
||||
documentSubDir = "documents"
|
||||
)
|
||||
|
||||
// 存储侧的哨兵错误。调用方一律用 `errors.Is` 分类，**绝不按错误文本匹配**：
|
||||
// 网关把它们映射为既有的 415 / 413 / 400 契约错误码，IM 侧映射为诚实提示。
|
||||
var (
|
||||
// ErrExtNotAllowed 报告原始文件名的扩展名不在白名单内（deny-by-default）。
|
||||
ErrExtNotAllowed = errors.New("documents: 扩展名不在白名单内")
|
||||
// ErrContentNotText 报告字节嗅探否决了这份内容（基类型不是 text/plain）。
|
||||
ErrContentNotText = errors.New("documents: 内容不是纯文本类（字节嗅探否决）")
|
||||
// ErrTooLarge 报告内容超过生效的单文件字节上限。
|
||||
ErrTooLarge = errors.New("documents: 内容超过字节上限")
|
||||
// ErrEmpty 报告内容为空（空文件没有落盘意义，也不该产生元数据行）。
|
||||
ErrEmpty = errors.New("documents: 内容为空")
|
||||
// ErrNoDir 报告文档落盘目录未配置（组合根/网关都没给出 UploadsDir 与 DataDir）。
|
||||
ErrNoDir = errors.New("documents: 文档落盘目录未配置")
|
||||
// ErrBadPath 报告拼出的落盘路径逃出了文档目录（内容寻址名由本包签发，
|
||||
// 因此这是防御性的第二道门）。
|
||||
ErrBadPath = errors.New("documents: 落盘路径逃出文档目录")
|
||||
// ErrMetadata 报告元数据写入失败。它与「文件已经落盘」是两个事实：调用方
|
||||
// 据它把 500 文案分开（S1 的「记录文档元数据失败」），并知道盘上那份文件
|
||||
// 需要 S7 的 GC 容忍或清理（design/24 §9.2-5）。
|
||||
ErrMetadata = errors.New("documents: 元数据写入失败")
|
||||
)
|
||||
|
||||
// Ref 是一次成功落盘的结果：服务端签发的引用 + 落盘路径。前五个字段是调用方
|
||||
// 对外呈现的事实（网关的响应字段、IM 侧的展示身份），Path 只给服务端自己用
|
||||
// （日志/清理），**绝不进模型上下文、绝不回给客户端**。
|
||||
type Ref struct {
|
||||
// Name 是内容寻址的存储名（`sha256(bytes)[:32] + ext`）。
|
||||
Name string
|
||||
// MIME 是字节嗅探所得的基类型（去参数、小写）。
|
||||
MIME string
|
||||
// Size 是落盘字节数。
|
||||
Size int64
|
||||
// SHA256 是完整内容的十六进制摘要（落盘名只取前 HashHexLen 位）。
|
||||
SHA256 string
|
||||
// Deduped 报告这次写入命中了盘上已有的同一份内容（同字节同扩展名）。
|
||||
Deduped bool
|
||||
// Path 是落盘绝对/相对路径（按构造方给的 UploadsDir 决定形态）。
|
||||
Path string
|
||||
}
|
||||
|
||||
// Record 是写入 `documents` 表（迁移 0014）的一行元数据。列与 S1 逐字一致。
|
||||
type Record struct {
|
||||
// Name 是内容寻址的存储名（表上的唯一键）。
|
||||
Name string
|
||||
// SHA256 是完整内容的十六进制摘要。
|
||||
SHA256 string
|
||||
// MIME 是嗅探所得的基类型。
|
||||
MIME string
|
||||
// Size 是字节数。
|
||||
Size int64
|
||||
// Uploader 是上传者身份：网关给请求 claims 的 sub，IM 给渠道来源标签。
|
||||
// 身份**只由构造方给出**，store 绝不从文件名/内容里猜（项目红线）。
|
||||
Uploader string
|
||||
}
|
||||
|
||||
// MetadataWriter 是元数据写入的**可选注入面**（design/24 §9.2-5 的技术债：
|
||||
// 网关当前每次上传 `db.Open` 开新连接，本切片不把它改成连接注入）。
|
||||
// 未注入时 Save 照旧成功，只跳过写表并留一条 DEBUG 痕迹。
|
||||
type MetadataWriter interface {
|
||||
// WriteDocument 写入一行文档元数据。同一存储名重复上传由实现方
|
||||
// `ON CONFLICT(name) DO NOTHING`（首次的 uploader/created_at 是权威）。
|
||||
WriteDocument(ctx context.Context, rec Record) error
|
||||
}
|
||||
|
||||
// StoreConfig 是文档存储核心的接线参数。路径口径由调用方给出，本包不猜数据
|
||||
// 目录布局（与摄取层 Config 同一理由）。
|
||||
type StoreConfig struct {
|
||||
// DataDir 是数据目录。UploadsDir 留空时文档落进
|
||||
// `<DataDir>/uploads/documents`（网关与组合根用的是同一布局）。
|
||||
DataDir string
|
||||
// UploadsDir 是文档落盘的**完整目录**。非空时优先于 DataDir 推导。
|
||||
UploadsDir string
|
||||
// MaxBytes 是单文件字节上限；≤0 时取 DefaultMaxBytes。口径是
|
||||
// 「≤0 = 用默认」而不是「禁用上限」，与网关的 documentLimitBytes 一致。
|
||||
MaxBytes int
|
||||
// Uploader 是写进元数据的上传者身份（见 Record.Uploader）。
|
||||
Uploader string
|
||||
// Meta 是元数据写入的可选注入面；nil 时跳过写表并留痕。
|
||||
Meta MetadataWriter
|
||||
// Log 是基础 logger；nil 时替换为标记来源 runtime/documents 的丢弃 logger。
|
||||
Log *slog.Logger
|
||||
}
|
||||
|
||||
// Store 是文档落盘的唯一实现。它可安全并发使用（无可变状态，落盘的竞态由
|
||||
// 「临时文件 + rename」与「已存在即去重」处理）。
|
||||
type Store struct {
|
||||
dir string
|
||||
maxBytes int
|
||||
uploader string
|
||||
meta MetadataWriter
|
||||
log *slog.Logger
|
||||
}
|
||||
|
||||
// NewStore 构造文档存储。UploadsDir 与 DataDir 都为空 ⇒ 每次 Save 都返回
|
||||
// ErrNoDir（宁可明确失败，也不猜一个目录出来）。
|
||||
func NewStore(cfg StoreConfig) *Store {
|
||||
dir := strings.TrimSpace(cfg.UploadsDir)
|
||||
if dir == "" {
|
||||
if root := strings.TrimSpace(cfg.DataDir); root != "" {
|
||||
dir = filepath.Join(root, uploadsSubDir, documentSubDir)
|
||||
}
|
||||
}
|
||||
return &Store{
|
||||
dir: dir,
|
||||
maxBytes: cfg.MaxBytes,
|
||||
uploader: strings.TrimSpace(cfg.Uploader),
|
||||
meta: cfg.Meta,
|
||||
log: sourcedLog(cfg.Log),
|
||||
}
|
||||
}
|
||||
|
||||
// Dir 返回生效的文档落盘目录（未配置时为空串）。它给测试与日志用，不参与落盘。
|
||||
func (s *Store) Dir() string { return s.dir }
|
||||
|
||||
// Limit 返回本次生效的单文件字节上限（≤0 归一为 DefaultMaxBytes）。
|
||||
func (s *Store) Limit() int {
|
||||
if s.maxBytes <= 0 {
|
||||
return DefaultMaxBytes
|
||||
}
|
||||
return s.maxBytes
|
||||
}
|
||||
|
||||
// Save 把一份原始文件落进文档存储，返回服务端签发的引用。规则与 S1 逐字同源，
|
||||
// 判定顺序也刻意保持（扩展名 → 空 → 上限 → 嗅探），因为「同一次上传里两条规则
|
||||
// 都不过时给哪个错误」是对外可见的行为：
|
||||
//
|
||||
// 1. **扩展名白名单**（deny-by-default）：原始文件名的扩展名不在放行集合内一律
|
||||
// 拒绝（`ErrExtNotAllowed`）—— 嗅探成 `text/plain` 的 `.js`/`.py` 也在此列；
|
||||
// 2. **空内容**拒绝（`ErrEmpty`）；
|
||||
// 3. **字节上限**拒绝（`ErrTooLarge`，上限见 Limit）；
|
||||
// 4. **字节嗅探唯一裁决**：`http.DetectContentType` 的基类型必须是 `text/plain`，
|
||||
// 否则拒绝（`ErrContentNotText`）—— 客户端声明的 MIME 与文件名只作参考、
|
||||
// 可被否决；
|
||||
// 5. 内容寻址落盘 + 路径双检 + 去重（同字节同扩展名 ⇒ 同名 ⇒ `Deduped=true`），
|
||||
// 随后（可选）写一行 `documents` 元数据。
|
||||
//
|
||||
// 元数据写入失败时返回的错误同时满足 `errors.Is(err, ErrMetadata)`，且**已落盘的
|
||||
// 引用照旧返回**：文件确实在盘上，调用方据此如实上报（S1 的行为）。
|
||||
func (s *Store) Save(ctx context.Context, origName string, data []byte) (Ref, error) {
|
||||
sniffed := http.DetectContentType(data)
|
||||
ref, err := s.prepare(origName, sniffed, data)
|
||||
if err != nil {
|
||||
return Ref{}, err
|
||||
}
|
||||
committed, err := s.commit(ref, data)
|
||||
if err != nil {
|
||||
return Ref{}, err
|
||||
}
|
||||
if err := s.record(ctx, committed); err != nil {
|
||||
return committed, err
|
||||
}
|
||||
return committed, nil
|
||||
}
|
||||
|
||||
// prepare 执行落盘之前的全部裁决并算出内容寻址引用（不触盘、不建目录）。
|
||||
// sniffed 由调用方传入，使「嗅探发生在任何磁盘动作之前」这一顺序在代码里可见。
|
||||
func (s *Store) prepare(origName, sniffed string, data []byte) (Ref, error) {
|
||||
ext := ExtOf(origName)
|
||||
if !ExtAllowed(ext) {
|
||||
return Ref{}, fmt.Errorf("documents: save: %w", ErrExtNotAllowed)
|
||||
}
|
||||
if len(data) == 0 {
|
||||
return Ref{}, fmt.Errorf("documents: save: %w", ErrEmpty)
|
||||
}
|
||||
if limit := s.Limit(); len(data) > limit {
|
||||
return Ref{}, fmt.Errorf("documents: save: 上限 %d 字节，本次 %d 字节: %w", limit, len(data), ErrTooLarge)
|
||||
}
|
||||
if !SniffAllowed(sniffed) {
|
||||
return Ref{}, fmt.Errorf("documents: save: 嗅探 %q 非纯文本: %w", baseMIME(sniffed), ErrContentNotText)
|
||||
}
|
||||
sum := sha256.Sum256(data)
|
||||
return Ref{
|
||||
Name: hashName(sum[:], ext),
|
||||
MIME: baseMIME(sniffed),
|
||||
Size: int64(len(data)),
|
||||
SHA256: hex.EncodeToString(sum[:]),
|
||||
}, nil
|
||||
}
|
||||
|
||||
// commit 把字节落进 `<dir>/<name>`：先写点前缀临时文件再 rename（部分写入绝不会
|
||||
// 以可读的名字露面），目标名已存在时丢弃临时文件并报告 deduped —— 盘上只留一份。
|
||||
func (s *Store) commit(ref Ref, data []byte) (Ref, error) {
|
||||
if s.dir == "" {
|
||||
return Ref{}, fmt.Errorf("documents: commit: %w", ErrNoDir)
|
||||
}
|
||||
path, err := targetPath(s.dir, ref.Name)
|
||||
if err != nil {
|
||||
return Ref{}, err
|
||||
}
|
||||
if info, serr := os.Stat(path); serr == nil && !info.IsDir() {
|
||||
ref.Path, ref.Deduped = path, true
|
||||
return ref, nil
|
||||
}
|
||||
if err := os.MkdirAll(s.dir, dirMode); err != nil {
|
||||
return Ref{}, fmt.Errorf("documents: 建目录: %w", err)
|
||||
}
|
||||
tmp, err := os.CreateTemp(s.dir, tempPattern)
|
||||
if err != nil {
|
||||
return Ref{}, fmt.Errorf("documents: 建临时文件: %w", err)
|
||||
}
|
||||
tmpName := tmp.Name()
|
||||
if _, err := tmp.Write(data); err != nil {
|
||||
_ = tmp.Close()
|
||||
_ = os.Remove(tmpName)
|
||||
return Ref{}, fmt.Errorf("documents: 写临时文件: %w", err)
|
||||
}
|
||||
if err := tmp.Close(); err != nil {
|
||||
_ = os.Remove(tmpName)
|
||||
return Ref{}, fmt.Errorf("documents: 关临时文件: %w", err)
|
||||
}
|
||||
if err := os.Rename(tmpName, path); err != nil {
|
||||
_ = os.Remove(tmpName)
|
||||
return Ref{}, fmt.Errorf("documents: 提交落盘: %w", err)
|
||||
}
|
||||
ref.Path = path
|
||||
return ref, nil
|
||||
}
|
||||
|
||||
// record 写入一行 `documents` 元数据（可选注入面）。未注入时跳过并留痕：
|
||||
// 文件已经落盘，元数据留待接线（S1 在 `dbPath == ""` 时的行为）。
|
||||
func (s *Store) record(ctx context.Context, ref Ref) error {
|
||||
if s.meta == nil {
|
||||
s.log.Debug("document metadata skipped: writer not wired",
|
||||
"name", ref.Name, "size", ref.Size, "deduped", ref.Deduped)
|
||||
return nil
|
||||
}
|
||||
rec := Record{
|
||||
Name: ref.Name, SHA256: ref.SHA256, MIME: ref.MIME,
|
||||
Size: ref.Size, Uploader: s.uploader,
|
||||
}
|
||||
if err := s.meta.WriteDocument(ctx, rec); err != nil {
|
||||
return fmt.Errorf("documents: 元数据 %q: %w: %w", ref.Name, ErrMetadata, err)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// targetPath 按落盘名拼出路径并做 S1 的**路径双检**：拼出的路径必须仍在文档
|
||||
// 目录内。名字由本包签发（内容寻址），因此这是防御性的第二道门 —— 与读侧
|
||||
// `filepath.Dir(path) != filepath.Clean(dir)` 是同一手法。
|
||||
func targetPath(dir, name string) (string, error) {
|
||||
path := filepath.Join(dir, name)
|
||||
if filepath.Dir(path) != filepath.Clean(dir) {
|
||||
return "", fmt.Errorf("documents: 落盘名 %q: %w", name, ErrBadPath)
|
||||
}
|
||||
return path, nil
|
||||
}
|
||||
|
||||
// ExtOf 从原始文件名取出小写扩展名（含点）。它只作**参考**：结果必须同时通过
|
||||
// 扩展名白名单与字节嗅探，客户端因此无法靠改扩展名换类型。
|
||||
func ExtOf(filename string) string {
|
||||
return strings.ToLower(filepath.Ext(filename))
|
||||
}
|
||||
|
||||
// ExtAllowed 报告扩展名是否在放行集合内。deny-by-default：集合之外的一切
|
||||
// （`.html`/`.svg`/`.xml`/`.zip`/`.docx`/`.xlsx`/`.exe`/`.dll`/`.bat`/`.cmd`/
|
||||
// `.ps1`/`.js`/`.mjs`/`.sh`/`.py`…）一律拒绝。注意 `.js`/`.py` 即便嗅探成
|
||||
// `text/plain` 也必须拒绝 —— 判定以扩展名与嗅探的**合取**为准。
|
||||
//
|
||||
// 这 22 项是 design/24 §9.2-2 的定稿集合，全仓只此一份（网关的名字形态校验
|
||||
// 与 IM 入站附件都经它判定）。
|
||||
func ExtAllowed(ext string) bool {
|
||||
switch ext {
|
||||
case ".txt", ".md", ".markdown", ".csv", ".tsv", ".json", ".jsonl",
|
||||
".yaml", ".yml", ".log", ".ini", ".cfg", ".toml",
|
||||
".go", ".ts", ".tsx", ".java", ".c", ".h", ".cpp", ".rs", ".sql":
|
||||
return true
|
||||
default:
|
||||
return false
|
||||
}
|
||||
}
|
||||
|
||||
// SniffAllowed 报告嗅探所得类型是否落在放行的文本类内。它是「类型裁决的唯一
|
||||
// 裁决者」在代码里的落点：客户端声明的 `Content-Type` 从不参与决定。
|
||||
func SniffAllowed(sniffed string) bool {
|
||||
return baseMIME(sniffed) == SniffOKMIME
|
||||
}
|
||||
|
||||
// hashName 返回内容寻址的落盘名：sha256 十六进制的前 HashHexLen 位 + ext。
|
||||
// 同一份字节配同一个扩展名必然得到同一个名字，去重因此是「同名」的自然结果。
|
||||
func hashName(sum []byte, ext string) string {
|
||||
return hex.EncodeToString(sum)[:HashHexLen] + ext
|
||||
}
|
||||
Reference in new issue
Block a user