Documentation
¶
Overview ¶
Package uploadkit 提供多来源、安全检查和多存储适配的流式文件上传能力。
Index ¶
- Variables
- func DefaultKeyGenerator(input KeyInput) (objectKey string, err error)
- func ValidateObjectKey(objectKey string) error
- func ValidatePutObject(object PutObject) error
- type BatchItem
- type BatchResult
- type ErrorHandler
- type FileInfo
- type HealthChecker
- type Inspector
- type InspectorFunc
- type KeyGenerator
- type KeyInput
- type Option
- func WithCleanupErrorHandler(handler ErrorHandler) Option
- func WithDefaultPolicy(policy Policy) Option
- func WithInspector(inspector Inspector) Option
- func WithKeyGenerator(generator KeyGenerator) Option
- func WithMaxConcurrency(maxConcurrency int) Option
- func WithScanner(scanner Scanner) Option
- func WithTempDir(directory string) Option
- type Policy
- type PolicyOptions
- type PutObject
- type Request
- type Result
- type ScanResult
- type Scanner
- type ScannerFunc
- type Source
- func FromBytes(name string, data []byte) Source
- func FromFS(fileSystem fs.FS, fileName string) (result Source, err error)
- func FromFile(file *os.File) (result Source, err error)
- func FromMultipart(file *multipart.FileHeader) (result Source, err error)
- func FromPath(filePath string) (result Source, err error)
- func FromReadSeeker(name string, size int64, reader io.ReadSeeker) (result Source, err error)
- func FromReader(name string, size int64, reader io.Reader) (result Source, err error)
- type Store
- type StoredObject
- type URLSigner
- type Uploader
- func (u *Uploader) Delete(ctx context.Context, objectKey string) error
- func (u *Uploader) Ping(ctx context.Context) error
- func (u *Uploader) SignedURL(ctx context.Context, objectKey string, expires time.Duration) (result string, err error)
- func (u *Uploader) Upload(ctx context.Context, source Source) (result Result, err error)
- func (u *Uploader) UploadBatch(ctx context.Context, requests []Request) (result BatchResult, err error)
- func (u *Uploader) UploadMany(ctx context.Context, sources []Source) (result BatchResult, err error)
- func (u *Uploader) UploadManyWithPolicy(ctx context.Context, sources []Source, policy Policy) (result BatchResult, err error)
- func (u *Uploader) UploadRequest(ctx context.Context, request Request) (result Result, err error)
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNilStore 表示没有提供对象存储适配器。 ErrNilStore = errors.New("uploadkit: store is nil") // ErrNilSource 表示没有提供上传内容来源。 ErrNilSource = errors.New("uploadkit: source is nil") // ErrInvalidSource 表示上传来源返回了无效的大小或内容流。 ErrInvalidSource = errors.New("uploadkit: invalid source") // ErrNilContext 表示调用方没有提供上下文。 ErrNilContext = errors.New("uploadkit: context is nil") // ErrInvalidConfig 表示上传器初始化配置无效。 ErrInvalidConfig = errors.New("uploadkit: invalid config") // ErrInvalidPolicy 表示文件策略配置无效。 ErrInvalidPolicy = errors.New("uploadkit: invalid policy") // ErrSourceConsumed 表示一次性 Reader 来源已经被打开过。 ErrSourceConsumed = errors.New("uploadkit: source has already been consumed") // ErrEmptyFile 表示文件没有任何内容。 ErrEmptyFile = errors.New("uploadkit: file is empty") // ErrFileTooLarge 表示文件实际大小超过策略限制。 ErrFileTooLarge = errors.New("uploadkit: file is too large") // ErrMIMETypeNotAllowed 表示真实文件类型不在策略允许列表中。 ErrMIMETypeNotAllowed = errors.New("uploadkit: MIME type is not allowed") // ErrExtensionMismatch 表示文件扩展名与真实内容类型不一致。 ErrExtensionMismatch = errors.New("uploadkit: file extension does not match content") // ErrUnsafeSVG 表示 SVG 包含脚本、事件或外部资源。 ErrUnsafeSVG = errors.New("uploadkit: unsafe SVG content") // ErrUnsafeArchive 表示压缩包结构、大小或内容不安全。 ErrUnsafeArchive = errors.New("uploadkit: unsafe archive content") // ErrImageDimensions 表示图片尺寸超过策略限制或结构无法解析。 ErrImageDimensions = errors.New("uploadkit: invalid or oversized image dimensions") // ErrScannerRequired 表示策略要求病毒扫描,但上传器没有注册扫描器。 ErrScannerRequired = errors.New("uploadkit: malware scanner is required") // ErrThreatDetected 表示扫描器发现病毒或其他威胁。 ErrThreatDetected = errors.New("uploadkit: malware or threat detected") // ErrInvalidObjectKey 表示生成的对象键为空或尝试越过存储目录。 ErrInvalidObjectKey = errors.New("uploadkit: invalid object key") // ErrObjectExists 表示对象键已经存在,存储拒绝覆盖。 ErrObjectExists = errors.New("uploadkit: object already exists") // ErrTooManyFiles 表示批量上传文件数超过策略限制。 ErrTooManyFiles = errors.New("uploadkit: too many files") // ErrBatchFailed 表示批量上传中至少有一个文件处理失败。 ErrBatchFailed = errors.New("uploadkit: batch contains failed uploads") // ErrSignedURLUnsupported 表示当前存储不支持临时签名地址。 ErrSignedURLUnsupported = errors.New("uploadkit: signed URL is not supported") // ErrHealthCheckUnsupported 表示当前存储没有提供主动健康检查。 ErrHealthCheckUnsupported = errors.New("uploadkit: health check is not supported") )
Functions ¶
func DefaultKeyGenerator ¶
DefaultKeyGenerator 使用日期、随机值和可信 MIME 扩展名创建对象键。 @param input KeyInput 对象键信息 @return objectKey string 对象键 @return err error 随机数或前缀错误
func ValidateObjectKey ¶
ValidateObjectKey 校验适配器收到的对象键。 @param objectKey string 对象键 @return err error 非法对象键
func ValidatePutObject ¶
ValidatePutObject 校验对象存储适配器收到的完整写入参数。 @param object PutObject 待保存对象 @return err error 对象键、内容事实或元数据错误
Types ¶
type BatchItem ¶
type BatchItem struct {
Index int // Index 请求下标
Result Result // Result 成功结果
Err error // Err 独立失败原因
}
BatchItem 描述批量上传中一个文件的执行结果。
type BatchResult ¶
type BatchResult struct {
Items []BatchItem // Items 每个请求的执行结果
Succeeded int // Succeeded 成功数量
Failed int // Failed 失败数量
}
BatchResult 描述保持请求顺序的批量上传结果。
type FileInfo ¶
type FileInfo struct {
OriginalName string // OriginalName 清理后的原始名称
MIMEType string // MIMEType 真实文件类型
Size int64 // Size 实际文件大小
ChecksumSHA256 string // ChecksumSHA256 十六进制 SHA-256
}
FileInfo 描述扫描器和检查器可使用的可信文件信息。
type HealthChecker ¶
HealthChecker 是支持主动连接检查的可选存储能力。
type Inspector ¶
type Inspector interface {
// Inspect 检查一个从起点开始的文件流。
Inspect(ctx context.Context, file FileInfo, content io.Reader) error
}
Inspector 定义调用方特有文件结构的检查扩展。
type InspectorFunc ¶
InspectorFunc 将普通方法适配为 Inspector。
type KeyInput ¶
type KeyInput struct {
Prefix string // Prefix 调用方指定的受信任目录前缀
OriginalName string // OriginalName 清理后的原始名称
MIMEType string // MIMEType 真实文件类型
Size int64 // Size 实际文件大小
ChecksumSHA256 string // ChecksumSHA256 文件 SHA-256
CreatedAt time.Time // CreatedAt 当前 UTC 时间
}
KeyInput 描述对象键生成需要的可信信息。
type Option ¶
type Option func(*uploaderConfig) error
Option 修改 Uploader 初始化配置。
func WithCleanupErrorHandler ¶
func WithCleanupErrorHandler(handler ErrorHandler) Option
WithCleanupErrorHandler 设置临时文件清理错误处理器。 @description 对象写入成功后,临时文件清理失败不会改变上传结果,可通过该处理器记录异常 @param handler ErrorHandler 错误处理器 @return option Option 配置项
func WithDefaultPolicy ¶
WithDefaultPolicy 设置当前 Uploader 的默认上传策略。 @param policy Policy 默认上传策略 @return option Option 配置项
func WithInspector ¶
WithInspector 注册自定义文件结构检查器。 @param inspector Inspector 内容检查器 @return option Option 配置项
func WithKeyGenerator ¶
func WithKeyGenerator(generator KeyGenerator) Option
WithKeyGenerator 设置对象键生成方法。 @param generator KeyGenerator 对象键生成器 @return option Option 配置项
func WithMaxConcurrency ¶
WithMaxConcurrency 设置单个 Uploader 最大并行任务数。 @param maxConcurrency int 最大并行数 @return option Option 配置项
func WithScanner ¶
WithScanner 注册病毒或恶意内容扫描器。 @param scanner Scanner 扫描器 @return option Option 配置项
func WithTempDir ¶
WithTempDir 设置隔离文件目录。 @param directory string 临时目录,空值使用系统目录 @return option Option 配置项
type Policy ¶
type Policy struct {
// contains filtered or unexported fields
}
Policy 保存已经校验和编译完成的只读上传规则。
func DefaultPolicy ¶
func DefaultPolicy() Policy
DefaultPolicy 返回 uploadkit 的保守默认上传策略。 @return result Policy 默认上传策略
func NewPolicy ¶
func NewPolicy(options PolicyOptions) (result Policy, err error)
NewPolicy 创建不可变上传策略。 @param options PolicyOptions 策略参数 @return result Policy 上传策略 @return err error 参数错误
type PolicyOptions ¶
type PolicyOptions struct {
MaxFileSize int64 // MaxFileSize 单文件最大实际字节数
MaxFiles int // MaxFiles 单次批量上传最大文件数
AllowedMIMETypes []string // AllowedMIMETypes 允许的真实 MIME 类型
DeniedMIMETypes []string // DeniedMIMETypes 禁止的真实 MIME 类型,优先于允许规则
IgnoreExtensionMismatch bool // IgnoreExtensionMismatch 是否忽略名称扩展名不一致
AllowNestedArchives bool // AllowNestedArchives 是否允许 ZIP 内再次包含归档文件
RequireMalwareScanner bool // RequireMalwareScanner 是否强制执行病毒扫描
MaxImagePixels uint64 // MaxImagePixels 图片最大像素数
MaxArchiveFiles int // MaxArchiveFiles ZIP 最大文件数
MaxArchiveExpandedBytes int64 // MaxArchiveExpandedBytes ZIP 最大解压字节数
MaxCompressionRatio float64 // MaxCompressionRatio ZIP 最大压缩比
}
PolicyOptions 定义一个可复用上传策略。
type PutObject ¶
type PutObject struct {
Key string // Key 对象存储键
Body io.ReadSeeker // Body 可回退的隔离文件流
Size int64 // Size 实际文件字节数
ContentType string // ContentType 真实 MIME 类型
ContentDisposition string // ContentDisposition 下载展示方式
ChecksumSHA256 string // ChecksumSHA256 十六进制 SHA-256
Metadata map[string]string // Metadata 调用方提供的对象元数据副本
}
PutObject 描述一个已经通过检查、等待持久化的对象。
type Request ¶
type Request struct {
Source Source // Source 文件数据来源
Policy Policy // Policy 可选的本次上传策略,零值使用 Uploader 默认策略
ObjectKey string // ObjectKey 可选的本次上传固定对象键
Prefix string // Prefix 调用方确认可信的对象目录
ContentDisposition string // ContentDisposition 对象展示方式,默认 attachment
Metadata map[string]string // Metadata 对象存储元数据
}
Request 描述一次文件上传。
type Result ¶
type Result struct {
OriginalName string // OriginalName 清理后的原始文件名
ObjectKey string // ObjectKey 最终对象键
MIMEType string // MIMEType 真实文件类型
Size int64 // Size 实际文件大小
ChecksumSHA256 string // ChecksumSHA256 十六进制 SHA-256
ETag string // ETag 存储服务对象标识
VersionID string // VersionID 对象版本号
}
Result 描述一次成功上传。
type ScanResult ¶
ScanResult 描述一次病毒扫描结论。
type Scanner ¶
type Scanner interface {
// Scan 检查一个从起点开始的文件流。
Scan(ctx context.Context, file FileInfo, content io.Reader) (ScanResult, error)
}
Scanner 定义病毒和恶意内容扫描扩展。
type ScannerFunc ¶
ScannerFunc 将普通方法适配为 Scanner。
func (ScannerFunc) Scan ¶
func (f ScannerFunc) Scan(ctx context.Context, file FileInfo, content io.Reader) (result ScanResult, err error)
Scan 执行适配后的扫描方法。 @param ctx context.Context 调用上下文 @param file FileInfo 文件信息 @param content io.Reader 文件内容 @return result ScanResult 扫描结果 @return err error 扫描错误
type Source ¶
type Source interface {
// Name 返回用于审计和扩展名校验的原始名称。
Name() string
// Size 返回已知字节数;未知时返回 -1。
Size() int64
// Open 打开一个从内容起点开始读取的数据流。
Open(ctx context.Context) (io.ReadCloser, error)
}
Source 表示一次上传的数据来源。 Source 只保证单次 Upload 调用期间可打开,不要求支持并发复用。
func FromBytes ¶
FromBytes 将内存字节适配为可重复打开的 Source。 @param name string 文件名称 @param data []byte 文件内容 @return result Source 文件来源
func FromFS ¶
FromFS 将 fs.FS 中的文件适配为可重复打开的 Source。 @param fileSystem fs.FS 文件系统 @param fileName string 文件名称 @return result Source 文件来源 @return err error 文件检查错误
func FromFile ¶
FromFile 将本地文件对象适配为 Source。 @description 文件必须拥有可重新打开的真实路径,调用方仍负责关闭原始文件。 @param file *os.File 本地文件 @return result Source 文件来源 @return err error 文件检查错误
func FromMultipart ¶
func FromMultipart(file *multipart.FileHeader) (result Source, err error)
FromMultipart 将标准 multipart 文件头适配为 Source。 @param file *multipart.FileHeader multipart 文件头 @return result Source 文件来源 @return err error 参数错误
func FromPath ¶
FromPath 将本地文件路径适配为可重复打开的 Source。 @param filePath string 本地文件路径 @return result Source 文件来源 @return err error 文件检查错误
func FromReadSeeker ¶
FromReadSeeker 将可回退 Reader 适配为 Source。 @param name string 文件名称 @param size int64 声明大小,未知传 -1 @param reader io.ReadSeeker 数据来源 @return result Source 文件来源 @return err error 参数错误
func FromReader ¶
FromReader 将一次性 Reader 适配为 Source。 @description 同一个返回值只能执行一次 Upload;已实现 io.Closer 的 Reader 由上传器关闭。 @param name string 文件名称 @param size int64 声明大小,未知传 -1 @param reader io.Reader 数据来源 @return result Source 文件来源 @return err error 参数错误
type Store ¶
type Store interface {
// Put 保存已经通过检查的对象。
Put(ctx context.Context, object PutObject) (StoredObject, error)
// Delete 删除指定对象;对象不存在应视为成功。
Delete(ctx context.Context, objectKey string) error
}
Store 定义本地和云对象存储统一适配接口。
type StoredObject ¶
type StoredObject struct {
ETag string // ETag 存储服务返回的对象标识
VersionID string // VersionID 开启版本控制时的对象版本
}
StoredObject 描述 Store 返回的持久化结果。
type URLSigner ¶
type URLSigner interface {
// SignedURL 为指定对象创建临时访问地址。
SignedURL(ctx context.Context, objectKey string, expires time.Duration) (string, error)
}
URLSigner 是支持临时签名访问地址的可选存储能力。
type Uploader ¶
type Uploader struct {
// contains filtered or unexported fields
}
Uploader 组织来源隔离、安全检查和对象存储写入。 Uploader 初始化完成后只读,可以被多个 goroutine 并发复用。
func New ¶
New 创建并发安全的上传器。 @param store Store 对象存储适配器 @param options ...Option 初始化选项 @return result *Uploader 上传器 @return err error 配置错误
func (*Uploader) Delete ¶
Delete 删除指定对象。 @param ctx context.Context 调用上下文 @param objectKey string 对象键 @return err error 参数或存储错误
func (*Uploader) Ping ¶
Ping 主动检查对象存储是否可用。 @param ctx context.Context 调用上下文 @return err error 不支持或存储错误
func (*Uploader) SignedURL ¶
func (u *Uploader) SignedURL(ctx context.Context, objectKey string, expires time.Duration) (result string, err error)
SignedURL 创建对象临时访问地址。 @param ctx context.Context 调用上下文 @param objectKey string 对象键 @param expires time.Duration 有效时间 @return result string 临时访问地址 @return err error 参数、不支持或存储错误
func (*Uploader) Upload ¶
Upload 使用默认策略上传一个文件来源。 @param ctx context.Context 调用上下文 @param source Source 文件数据来源 @return result Result 上传结果 @return err error 来源、检查或存储错误
func (*Uploader) UploadBatch ¶
func (u *Uploader) UploadBatch(ctx context.Context, requests []Request) (result BatchResult, err error)
UploadBatch 并发执行不同策略的上传请求并保持输入顺序。 @param ctx context.Context 调用上下文 @param requests []Request 上传请求列表 @return result BatchResult 有序批量结果 @return err error 整体参数、上下文或批量部分失败错误
func (*Uploader) UploadMany ¶
func (u *Uploader) UploadMany(ctx context.Context, sources []Source) (result BatchResult, err error)
UploadMany 使用 Uploader 默认策略批量上传多个来源。 @param ctx context.Context 调用上下文 @param sources []Source 文件来源列表 @return result BatchResult 有序批量结果 @return err error 批量参数、上下文或批量部分失败错误
func (*Uploader) UploadManyWithPolicy ¶
func (u *Uploader) UploadManyWithPolicy(ctx context.Context, sources []Source, policy Policy) (result BatchResult, err error)
UploadManyWithPolicy 使用指定策略批量上传多个来源。 @param ctx context.Context 调用上下文 @param sources []Source 文件来源列表 @param policy Policy 上传策略 @return result BatchResult 有序批量结果 @return err error 批量参数、上下文或批量部分失败错误
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
examples
|
|
|
basic
command
|
|
|
scanner
|
|
|
clamav
Package clamav 通过 ClamAV INSTREAM 协议实现文件内容扫描器。
|
Package clamav 通过 ClamAV INSTREAM 协议实现文件内容扫描器。 |
|
store
|
|
|
aliyunoss
Package aliyunoss 实现阿里云 OSS 对象存储适配器。
|
Package aliyunoss 实现阿里云 OSS 对象存储适配器。 |
|
huaweiobs
Package huaweiobs 实现华为云 OBS 对象存储适配器。
|
Package huaweiobs 实现华为云 OBS 对象存储适配器。 |
|
local
Package local 实现受目录边界保护的本地文件系统存储适配器。
|
Package local 实现受目录边界保护的本地文件系统存储适配器。 |
|
s3
Package s3 实现 AWS S3 及兼容对象存储服务的适配器。
|
Package s3 实现 AWS S3 及兼容对象存储服务的适配器。 |
|
tencentcos
Package tencentcos 实现腾讯云 COS 对象存储适配器。
|
Package tencentcos 实现腾讯云 COS 对象存储适配器。 |