transfer

type BufferSink struct {
	Limit int64
	// contains filtered or unexported fields
}

type BytesSource struct {
	Data []byte
	File string
	// contains filtered or unexported fields
}

type DirSink struct {
	// Root 是允许写入的根目录。Put 会拒绝任何逃出该目录的 name。
	Root string
	// MaxBytes 单文件上限，0 时用 DefaultMaxBytes。
	MaxBytes int64
	// Overwrite 为真时允许覆盖已存在的普通文件。默认只新建：既避免误覆盖，也
	// 顺带杜绝了"目标是指向目录外的符号链接"这一类写入劫持。
	Overwrite bool
}

type FTPSink struct {
	// Addr 是服务器地址，形如 "ftp.example.com:21"。
	Addr string
	// User 与 Password 是登录凭据。不会出现在任何日志里。
	User     string
	Password string
	// BaseDir 是允许写入的远端根目录。留空表示远端用户登录后的家目录。
	BaseDir string
	// TLSConfig 非 nil 时使用隐式 FTPS（连上直接握手）。默认使用显式 FTPS
	// （先读 220，再用 AUTH TLS 升级），这是更常见地部署形态。
	TLSConfig *tls.Config
	// Implicit 为真时使用隐式 FTPS；为假时使用显式 FTPS。
	Implicit bool
	// Insecure 允许明文 FTP。留空 TLSConfig 且置真时使用。生产环境不应开启。
	Insecure bool
	// Timeout 是连接、登录与单个操作的超时，0 时取 DefaultFTPTimeout。
	Timeout time.Duration
	// MaxBytes 单文件上限，0 时用 DefaultMaxBytes。
	MaxBytes int64
	// Overwrite 为真时允许覆盖远端同名文件。默认拒绝，避免误覆盖别人的文件。
	Overwrite bool
	// DisableEPSV 强制只用 PASV。少数服务器没实现 EPSV，而客户端默认优先
	// 试它，失败后能否回落到 PASV 取决于服务器实现。
	DisableEPSV bool

	// OwnsPool 区分注册目标与 WithBaseDir 派生的实例。只有前者关池。
	//
	// 外部（cmd/ofd-server）从配置构造注册目标时置 true；派生实例不带它。
	OwnsPool bool

	// MaxIdle 与 IdleTTL 覆盖池的默认参数，0 表示用默认值。
	//
	// 这个结构体不参与序列化（配置类型在 cmd/ofd-server），所以不带 json 标签。
	MaxIdle int
	IdleTTL time.Duration
	// contains filtered or unexported fields
}

type FileSource struct {
	Path string
	// Keep 为真时 Close 不删除文件，用于复用已存在的样本文件。
	Keep bool
}

type HTTPAudit struct {
	// Requested 是调用方给出的原始地址。
	Requested string
	// Fetched 是最终请求的地址（跟随重定向后会变）。
	Fetched string
	// Resolved 是拨号时校验通过的 IP 列表。
	Resolved []string
	// StatusCode 是响应状态。
	StatusCode int
	// Bytes 是读取到的字节数。
	Bytes int64
}

type HTTPSource struct {
	// URL 是要拉取的地址。
	URL string
	// Allowlist 限定允许访问的主机与网段。空白名单下 Open 恒返回错误。
	Allowlist *allowlist.List
	// MaxBytes 响应体上限，0 时用 DefaultMaxBytes。
	MaxBytes int64
	// Timeout 整体超时，0 时用 30s。
	Timeout time.Duration
	// AllowRedirect 为真时跟随重定向。每跳仍会经过拨号时的白名单校验，因此不会
	// 绕过限制；但重定向会把原始地址泄露给第三方，默认关闭。
	AllowRedirect bool
	// FileName 覆盖推导出的文件名。为空时从 Content-Disposition 与 URL 路径取。
	FileName string
	// UserAgent 供部分站点识别客户端。
	UserAgent string
	// Log 记录实际拉取的地址与解析结果，便于审计。
	Log *slog.Logger
	// contains filtered or unexported fields
}

type LimitedSink interface {
	Sink
	MaxBytesLimit() int64
}

type Location struct {
	// Kind 为 "stream"、"dir" 或后续实现的 "s3"、"ftp"。
	Kind string `json:"kind"`
	// Path 是本地绝对路径（Kind 为 "dir" 时）。
	Path string `json:"path,omitempty"`
	// Bucket 与 Key 用于对象存储。
	Bucket string `json:"bucket,omitempty"`
	Key    string `json:"key,omitempty"`
	// URL 是可直接访问的地址，由具体后端可选地填充。
	URL string `json:"url,omitempty"`
	// Size 是写入的字节数。
	Size int64 `json:"size"`
}

type MinioSink struct {
	// Endpoint 是 S3 端点的主机名（不含协议），如 "minio.internal:9000"。
	Endpoint string
	// Secure 为真时用 https。为假时用 http——S3 的签名本身防篡改，但
	// 流量与凭据仍是明文，仅适用于内网。
	Secure bool
	// Region 是区域标识。多数自建部署可留空。
	Region string
	// AccessKey 与 SecretKey 是访问凭据。
	AccessKey string
	SecretKey string
	// SessionToken 是临时凭据的令牌，永久凭据留空。
	SessionToken string
	// Bucket 是目标桶。
	Bucket string
	// BasePrefix 是桶内的前缀，等价于 FTP 的 BaseDir。
	BasePrefix string
	// Timeout 是单次请求超时，0 时取 DefaultMinioTimeout。
	Timeout time.Duration
	// MaxBytes 单对象上限，0 时用 DefaultMaxBytes。
	MaxBytes int64
	// Overwrite 为真时允许覆盖同名对象。默认拒绝。
	Overwrite bool
	// contains filtered or unexported fields
}

type SFTPAuth struct {
	// PrivateKeyFile 是私钥文件路径（PEM 或 OpenSSH 新格式）。
	PrivateKeyFile string
	// PrivateKeyPassphrase 是私钥口令。留空表示私钥未加密。
	// 加密私钥且这里留空时连接会失败——这是有意的：不想把口令写进配置文件，
	// 就该走 AgentSocket。
	PrivateKeyPassphrase string
	// AgentSocket 是 ssh-agent 的 socket 路径。配置里只有这个路径，
	// 私钥与已解密的口令都由 agent 持有，是最干净的一种。
	AgentSocket string
	// Password 是口令认证的密码。
	Password string
}

type SFTPSink struct {
	// Addr 是服务器地址，形如 "sftp.example.com:22"。
	Addr string
	// User 是登录用户名。
	User string
	// Auth 是认证方式。三种可叠加，客户端会按顺序尝试。
	Auth SFTPAuth
	// BaseDir 是允许写入的远端目录，空表示登录用户的家目录。
	BaseDir string
	// HostKeySHA256 是预期的主机密钥指纹（SHA256:...），与 OpenSSH 一致。
	HostKeySHA256 string
	// HostKeyFile 是 known_hosts 文件路径。
	HostKeyFile string
	// InsecureIgnoreHostKey 跳过主机密钥校验。仅供一次性排查。
	InsecureIgnoreHostKey bool
	// Timeout 是连接、认证与单次操作的超时，0 时取 DefaultSFTPTimeout。
	Timeout time.Duration
	// MaxBytes 单文件上限，0 时用 DefaultMaxBytes。
	MaxBytes int64
	// Overwrite 为真时允许覆盖远端同名文件。默认拒绝。
	Overwrite bool

	// OwnsPool 区分注册目标与 WithBaseDir 派生的实例，只有前者关池。
	OwnsPool bool

	// MaxIdle 与 IdleTTL 覆盖池的默认参数，0 表示用默认值。
	MaxIdle int
	IdleTTL time.Duration
	// contains filtered or unexported fields
}

type Sink interface {
	// Put 把 r 的内容写入名为 name 的目标，返回可定位的结果。
	Put(ctx context.Context, name string, r io.Reader) (Location, error)
}

type Source interface {
	// Name 返回带扩展名的文件名。转换库按扩展名识别输入格式（docx/xlsx/html 等
	// 无法靠魔数区分），因此这里的扩展名必须是可信的、由服务端按已解析的格式
	// 派生，而不是直接采信调用方的原始文件名。
	Name() string
	// Open 打开内容供读取。调用方负责关闭返回的 ReadCloser。
	Open(ctx context.Context) (io.ReadCloser, error)
	// Close 释放来源占用的资源，对内存来源是空操作。
	Close() error
}

type WebDAVSink struct {
	// Endpoint 是服务地址，如 "https://dav.example.com/remote.php/dav/files/user"。
	Endpoint string
	// User 与 Password 是凭据。不会出现在任何日志里。
	User     string
	Password string
	// BaseDir 是允许写入的远端目录（相对 endpoint 根）。
	BaseDir string

	// Timeout 是单次请求超时，0 时取 DefaultWebDAVTimeout。
	Timeout time.Duration
	// MaxBytes 单文件上限，0 时用 DefaultMaxBytes。
	MaxBytes int64
	// Overwrite 为真时允许覆盖同名文件。默认拒绝。
	Overwrite bool
	// contains filtered or unexported fields
}