convertersvc

type File struct {
	Name string `json:"name"`
	Size int64  `json:"size"`
}

type Input struct {
	// Kind 为 InputUpload 或 InputURL。
	Kind string `json:"kind"`
	// Format 可选的显式输入格式。为空时按文件名扩展名与魔数识别。
	Format string `json:"format,omitempty"`
	// FileName 是上传的原始文件名，仅用于识别格式，不直接用于转换。
	FileName string `json:"file_name,omitempty"`
	// Bytes 是 Kind 为 InputUpload 时的内容。
	Bytes []byte `json:"bytes,omitempty"`
	// URL 是 Kind 为 InputURL 时的地址，必须通过服务端白名单。
	URL string `json:"url,omitempty"`
}

type Lane string

type Output struct {
	// Kind 为 OutputStream、OutputDir，或某个远端目标类型。
	Kind string `json:"kind"`
	// Format 输出格式，如 "pdf"、"markdown"、"png"。
	Format string `json:"format"`
	// FileName 是产物文件名的基名，不含扩展名——扩展名由 Format 决定。
	//
	// 为什么给基名而不是完整文件名：扩展名本来就是格式决定的，让调用方也能
	// 指定就多了一处可能自相矛盾的地方（声明 pdf 却起名 .txt）。基名已经能
	// 表达调用方的意图（发票号、客户编号），又不与之冲突。
	//
	// 为空时用默认值：单文件是 "output"，逐页输出是 "page"。
	//
	// 必须是单个路径组件，不含分隔符——否则就等于给了调用方一条穿越到
	// output_dir 之外的路径。完整路径仍由服务端决定（output_dir 之下、
	// 每个任务一个子目录），这一层隔离不受影响。
	FileName string `json:"file_name"`
	// Dir 是 Kind 为 OutputDir 时 output_dir 之下的相对子路径。
	Dir string `json:"dir"`
	// MaxStreamBytes 限制 stream 输出的内存占用，0 时取 DefaultStreamLimit。
	MaxStreamBytes int64 `json:"max_stream_bytes,omitempty"`
	// Remote 指向一个服务端预注册的远端目标，Kind 为远端类型时必填。
	Remote RemoteOutput `json:"remote,omitempty"`
}

type RemoteOutput struct {
	// Target 是服务端配置里注册的目标名。调用方不能直接给地址与凭据——那等于
	// 让它往任意主机上传、往任意账号写数据。
	Target string `json:"target"`
	// Path 是该目标下的子路径，语义由目标自身的配置决定：FTP/SFTP/WebDAV 是
	// 远端 base_dir，S3 是桶内 prefix。调用方不必、也无法区分。
	Path string `json:"path,omitempty"`
}

type Result struct {
	// Kind 与 Spec.Output.Kind 一致。
	Kind string `json:"kind"`
	// InputFormat 实际判定的输入格式（已归一化），不是 Spec.Input.Format
	// 那个声明值。统计按类型分布必须用这个：用声明值会把"内容是 OFD、
	// 文件名是 .html"这类任务记成 ofd→pdf。
	InputFormat string `json:"input_format"`
	// InputBytes 实际读入的输入字节数，取落盘后文件的尺寸。
	// 输入一律先 materialize 成文件，所以这个值对上传、URL 与未来的
	// 其他来源口径一致。
	InputBytes int64 `json:"input_bytes"`
	// Format 实际使用的输出格式名（已归一化）。
	Format string `json:"format"`
	// MIME 输出的 MIME 类型。
	MIME string `json:"mime"`
	// FileName 输出文件名，stream 时有值。
	FileName string `json:"file_name,omitempty"`
	// Bytes stream 输出的内容。
	Bytes []byte `json:"-"`
	// Dir 目录输出的根路径。
	Dir string `json:"dir,omitempty"`
	// Files 目录输出里的文件清单。
	Files []File `json:"files,omitempty"`
	// TookMs 转换耗时（毫秒）。不用 time.Duration 直接序列化——那是纳秒。
	TookMs int64 `json:"took_ms"`
}

type Service struct {
	// Allowlist 限定 input.kind=url 可以拉取的主机。为 nil 时 URL 输入一律拒绝。
	Allowlist *allowlist.List
	// TempDir 是转换期间的临时目录。转换器需要真实文件路径（LibreOffice、
	// Chrome 都如此），所以输入总是落盘一次。
	TempDir string
	// URLTimeout 是拉取远程输入的整体超时。
	URLTimeout time.Duration
	// DefaultOptions 是每个任务都会附加的可选项。
	DefaultOptions []converter.Option
	// FTPTargets 是服务端预注册的 FTP 目标，按名字索引。
	FTPTargets map[string]*transfer.FTPSink
	// S3Targets 是预注册的对象存储目标。
	S3Targets map[string]*transfer.MinioSink
	// WebDAVTargets 是预注册的 WebDAV 目标。
	WebDAVTargets map[string]*transfer.WebDAVSink
	// SFTPTargets 是预注册的 SFTP 目标。
	SFTPTargets map[string]*transfer.SFTPSink
}

type Spec struct {
	Input  Input
	Output Output
	// Options 传给 pkg/converter 的可选项（DPI、纸张、外部程序路径等）。
	Options []converter.Option
}