Documentation
¶
Overview ¶
admission.go 复刻官方 attachment/admission 的上传准入:解码 base64 载荷时拒绝 非规范形式(解码后再编码必须与原串一致),防止同一字节的多种编码绕过校验。
Package attachment 提供持久化图片附件(Durable Image Attachment)接缝。
对齐上游:packages/attachment/attachment
本文件对应任务 M29:Attachment 图片引用模式。
设计要点:
- 二进制图片的所有权与会话日志解耦:生产者先给已校验的编码字节, 服务只在对象持久化后才发布一个不可变的 content-addressed 引用(AttachmentID);
- 会话事件与模型可见的 ImageBlock 携带的是该引用 + 元数据,绝不含浏览器对象 URL、宿主临时路径、provider URL 或 base64 载荷;
- AttachmentID 是不透明品牌串(本实现取 "sha256:<digest>"),消费者既不可解析其 表示,也不可从它推导文件系统路径 —— 必须通过 Store.ReadImage 做权威读取;
- durable 延伸语义:store 是保留无关的(retention-neutral),resumed / forked 会话 可共享同一对象,因此「会话压缩 / 跨会话引用」通过 content-addressed 路径解析不失效。
limiter.go 复刻官方 attachment-local/compression-limiter:实例级 FIFO 并发上限, 限制同时进行的原生图像变换数量,超出的任务排队等待空位。
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidBase64 = errors.New("attachment: image upload is not canonical base64")
ErrInvalidBase64 载荷为空或不是规范 base64。
Functions ¶
func DecodeCanonicalBase64 ¶
DecodeCanonicalBase64 解码并校验规范 base64;非规范返回 ErrInvalidBase64。
Types ¶
type AttachmentID ¶
type AttachmentID = brand.AttachmentID
AttachmentID 是可持久化的不透明附件标识(别名自 pkg/brand)。
type FileBackedStore ¶
type FileBackedStore struct {
// contains filtered or unexported fields
}
FileBackedStore 是 content-addressed 附件存储实现。
- 主存储为内存 map(id → bytes);可选 dir 时同时落盘到 <dir>/<digest> 作宿主路径, 以支持「跨会话 / resume / fork」时的持久引用解析;
- AttachmentID = "sha256:<hex(digest)>",读取时重算摘要校验,杜绝内容漂移;
- 图片尺寸本实现不强制解析(保存时可按字节校验媒体类型前缀)。
func (*FileBackedStore) ImageHostPath ¶
func (s *FileBackedStore) ImageHostPath(ref ImageAttachmentRef) (string, bool)
ImageHostPath 返回宿主对象路径(dir 模式)或 ok=false。
func (*FileBackedStore) ReadImage ¶
func (s *FileBackedStore) ReadImage(ref ImageAttachmentRef) (StoredImageAttachment, error)
ReadImage 读取并校验字节仍匹配记录的引用。
func (*FileBackedStore) SaveImage ¶
func (s *FileBackedStore) SaveImage(input SaveImageAttachment) (ImageAttachmentRef, error)
SaveImage 校验并持久化一张图片,返回 content-addressed 引用。
type ImageAttachmentRef ¶
type ImageAttachmentRef struct {
// AttachmentID 附件 ID(content-addressed:"sha256:<digest>")。
AttachmentID AttachmentID `json:"attachmentId"`
// MediaType 由存储字节校验出的媒体类型。
MediaType ImageMediaType `json:"mediaType"`
// Bytes 编码字节精确长度。
Bytes int `json:"bytes"`
// Width 编码像素宽。
Width int `json:"width,omitempty"`
// Height 编码像素高。
Height int `json:"height,omitempty"`
// Name 可选显示名(已剥离本地路径信息)。
Name string `json:"name,omitempty"`
}
ImageAttachmentRef 是不可变归一化图片的持久化、可序列化引用。 它是不透明存储标识,绝不是一个文件系统路径或承载 URL。
type ImageMediaType ¶
type ImageMediaType string
ImageMediaType 是 v1 附件路径接受的图像格式。
const ( MediaPNG ImageMediaType = "image/png" MediaJPEG ImageMediaType = "image/jpeg" MediaWebP ImageMediaType = "image/webp" MediaGIF ImageMediaType = "image/gif" )
支持的图像媒体类型。
type Limiter ¶
type Limiter struct {
// contains filtered or unexported fields
}
Limiter 是固定并发度的 FIFO 限流器。
func NewLimiter ¶
NewLimiter 创建并发上限为 concurrency 的限流器;非正值按 1 处理。
type SaveImageAttachment ¶
type SaveImageAttachment struct {
// Data 编码字节。
Data []byte
// MediaType 调用方声明的媒体类型(与完整解码字节核对)。
MediaType ImageMediaType
// Name 可选显示名(绝不被解释为路径)。
Name string
// Width/Height 可选固有尺寸;0 表示未提供。
Width int
Height int
}
SaveImageAttachment 是提交一张图片的请求。
type Store ¶
type Store interface {
// SaveImage 校验并持久化一张图片;返回 content-addressed 引用。
SaveImage(input SaveImageAttachment) (ImageAttachmentRef, error)
// ReadImage 读取一张图片并校验字节仍匹配记录的引用。
ReadImage(ref ImageAttachmentRef) (StoredImageAttachment, error)
// ImageHostPath 返回 provider 持有的宿主对象路径;无宿主文件后端时 ok=false。
ImageHostPath(ref ImageAttachmentRef) (string, bool)
}
Store 是不可变二进制附件服务(ctx.attachments)。
type StoredImageAttachment ¶
type StoredImageAttachment struct {
Ref ImageAttachmentRef `json:"ref"`
Data []byte `json:"data"`
}
StoredImageAttachment 是经过引用+摘要校验后返回的存储字节与引用。
func ResolveFileBacked ¶
func ResolveFileBacked(dir string, ref ImageAttachmentRef) (StoredImageAttachment, error)
ResolveFileBacked 供无 store 但有宿主目录场景:直接从 <dir>/<digest> 读取。
func ResolveReference ¶
func ResolveReference(store Store, ref ImageAttachmentRef) (StoredImageAttachment, error)
ResolveReference 从一张 SessionLog 记录的附件引用解析出权威字节。
- 若调用方提供 Store,则走 Store.ReadImage(重算摘要校验);
- 否则在有宿主文件后端时从文件读取;两者都失败返回错误。
durable 语义:因为引用是 content-addressed(不依赖创建它的会话),无论会话被压缩 或从另一个会话引用,只要对象仍在 Store/宿主路径中即可解析成功,绝不失效。