attachment

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 9 Imported by: 0

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

View Source
var ErrInvalidBase64 = errors.New("attachment: image upload is not canonical base64")

ErrInvalidBase64 载荷为空或不是规范 base64。

Functions

func DecodeCanonicalBase64

func DecodeCanonicalBase64(data string) ([]byte, error)

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 NewStore

func NewStore(dir string) *FileBackedStore

NewStore 创建附件存储。dir 非空时启用宿主文件后端。

func (*FileBackedStore) ImageHostPath

func (s *FileBackedStore) ImageHostPath(ref ImageAttachmentRef) (string, bool)

ImageHostPath 返回宿主对象路径(dir 模式)或 ok=false。

func (*FileBackedStore) ReadImage

ReadImage 读取并校验字节仍匹配记录的引用。

func (*FileBackedStore) SaveImage

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

func NewLimiter(concurrency int) *Limiter

NewLimiter 创建并发上限为 concurrency 的限流器;非正值按 1 处理。

func (*Limiter) Acquire

func (l *Limiter) Acquire()

Acquire 获取一个槽位(阻塞直到有空位),Release 归还。

func (*Limiter) Active

func (l *Limiter) Active() int

Active 返回当前占用槽位数。

func (*Limiter) Release

func (l *Limiter) Release()

Release 归还一个槽位。

func (*Limiter) Run

func (l *Limiter) Run(task func())

Run 获取槽位后执行 task,结束(无论成败)归还槽位。

func (*Limiter) TryAcquire

func (l *Limiter) TryAcquire() bool

TryAcquire 尝试非阻塞获取。

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/宿主路径中即可解析成功,绝不失效。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL