51 lines
3.1 KiB
Go
51 lines
3.1 KiB
Go
// Package transcode 是 design/25「转码能力」的本地能力包实现：一条
|
|
// 「字节 + 源格式 + 目标格式 → 字节 + 目标格式 + 元信息」的进程内、同步、
|
|
// 纯函数式转换（不触网、不落盘、不读数据库）。它被设计为可被其它模块、
|
|
// 编译期系统插件与工具面（agent / MCP）复用，落地方式见 design/25 §1.3.2
|
|
// 的「两层注册」。
|
|
//
|
|
// 本包的所有失败一律是 errors.go 里的具名哨兵（或包裹它），绝不返回部分
|
|
// 结果假装成功（design/25 §2.4 / §5.4）。
|
|
package transcode
|
|
|
|
import "errors"
|
|
|
|
// design/25 §2.4 的八个哨兵。调用方用 errors.Is 判定；一律 %w 包裹，
|
|
// 绝不静默吞掉。错误文案是哨兵 + 可读短句：上游/解码器的错误原文只进日志，
|
|
// 不进用户可见正文（与 channelbridge 的「原因短语不含上游回显」同一条纪律）。
|
|
var (
|
|
// ErrUnsupportedFormat 源或目标格式未知 / 魔数嗅不出 / 注册表里没有这条路。
|
|
// 调用方应诚实提示；按内容发生的失败不熔断。
|
|
ErrUnsupportedFormat = errors.New("transcode: unsupported format")
|
|
// ErrInputTooLarge 输入字节超过 MaxInputBytes，或可确证的时长超过
|
|
// MaxDuration。在解码前拒绝（一行都不解）。
|
|
ErrInputTooLarge = errors.New("transcode: input too large")
|
|
// ErrOutputTooLarge 解码产物超过 MaxOutputBytes。在解码前即可确证时先拒绝，
|
|
// 否则边走边计数、命中即停。
|
|
ErrOutputTooLarge = errors.New("transcode: output too large")
|
|
// ErrDecodeFailed 字节损坏 / 头非法 / 帧截断。与「格式不支持」分开：
|
|
// 一个是「不会」，一个是「坏了」。
|
|
ErrDecodeFailed = errors.New("transcode: decode failed")
|
|
// ErrEncodeFailed 目标侧构造失败（如 WAV 头写不出）。
|
|
ErrEncodeFailed = errors.New("transcode: encode failed")
|
|
// ErrTimeout ctx 超时被检出。记 WARN、诚实提示、不重试（同步路径由调用方决定）。
|
|
ErrTimeout = errors.New("transcode: timeout")
|
|
// ErrBusy 并发槽已满，快速失败、不排队（绝不入无界队列）。
|
|
ErrBusy = errors.New("transcode: busy")
|
|
// ErrNoBackend 选了外部后端但主机上找不到 / 不可用。本期默认路径是进程内
|
|
// 纯 Go，故暂无触发点；哨兵先行登记，供 design/25 §4.3 的可选后端复用。
|
|
ErrNoBackend = errors.New("transcode: no backend")
|
|
)
|
|
|
|
// 以下两个不是 design/25 §2.4 的八个转码哨兵：它们描述的是「注册表里放进了
|
|
// 不合法的东西」和「工具面的入参不合法」，属包内自有的构造期/入参错误。
|
|
var (
|
|
// ErrDuplicate 同一个「源→目标」被注册了两次（与 registry.Register 的
|
|
// 「重名报错」纪律同源）。
|
|
ErrDuplicate = errors.New("transcode: codec already registered")
|
|
// ErrInvalidCodec 注册项不合法：nil、源或目标格式为空、或源等于目标。
|
|
ErrInvalidCodec = errors.New("transcode: invalid codec")
|
|
// ErrBadArgs 工具面入参不合法（非对象、缺字段、类型不对）。
|
|
ErrBadArgs = errors.New("transcode: bad arguments")
|
|
)
|