Documentation
¶
Overview ¶
Package files 是 Agent 侧的文件能力:stat / hash / 分块读取(拉取)/ 经网址写入(push_url)。
这里是文件能力的安全边界,Hub 只做形状校验与转发,真正的路径授权发生在这里:
- 路径必须落在请求携带的允许目录之内,并且用 os.Root 打开,符号链接 / .. 无法逃出允许目录;
- 只处理普通文件(FIFO / 设备 / 目录一律拒绝),且打开时不阻塞;
- 写入只发生在 push_url:先写同目录的临时文件,校验大小与摘要后再原子落位,不经符号链接写入;
- 网址访问受 SSRF 策略约束(见 ssrf.go)。
Index ¶
- type Config
- type Error
- type PushOpts
- type PushResult
- type Service
- func (s *Service) Close(id string)
- func (s *Service) Hash(ctx context.Context, roots []string, p string, max int64) (string, int64, *Error)
- func (s *Service) Open(roots []string, p string, max int64) (string, int64, *Error)
- func (s *Service) PushURL(ctx context.Context, roots []string, dest, rawURL string, o PushOpts) (PushResult, *Error)
- func (s *Service) Read(id string, off uint64, n int) (data []byte, eof bool, total uint64, e *Error)
- func (s *Service) Shutdown()
- func (s *Service) Stat(roots []string, p string) (termproto.FileStat, *Error)
- type URLPolicy
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
Home string // ~ 的展开目标;空则取 os.UserHomeDir
URL URLPolicy // push_url 的网络策略
Windows *bool // 测试覆盖路径语法;nil 按运行系统
HandleIdle time.Duration // 句柄空闲多久后自动关闭;0 取默认
}
Config 是文件服务的配置。零值可用(家目录取当前账户,网址策略为严格默认)。
type PushOpts ¶
type PushOpts struct {
Overwrite bool // 目标已存在时是否覆盖
SHA256 string // 期望摘要(可空):不一致则丢弃下载内容
Max int64 // 最大下载字节数;0 取默认上限
Timeout time.Duration // 整体超时;0 取默认
}
PushOpts 是 push_url 的参数。
type PushResult ¶
type PushResult struct {
Size int64
SHA256 string
Status int
Source string // 协议://主机[:端口],不含路径与查询串
Redirects int
}
PushResult 是 push_url 的结果。
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service 是 Agent 上的文件服务。并发安全。
func (*Service) Hash ¶
func (s *Service) Hash(ctx context.Context, roots []string, p string, max int64) (string, int64, *Error)
Hash 计算普通文件的 SHA-256。耗时操作,受并发上限与 ctx 约束。
func (*Service) PushURL ¶
func (s *Service) PushURL(ctx context.Context, roots []string, dest, rawURL string, o PushOpts) (PushResult, *Error)
PushURL 把网址的内容下载到允许目录内的目标文件:先写同目录的临时文件,校验后再落位。
type URLPolicy ¶
type URLPolicy struct {
// AllowPrivate 放开对回环 / 私网 / 链路本地地址的限制。只能由主机的拥有者在本机启动参数里打开,服务端无法设置。
AllowPrivate bool
// Lookup 解析主机名(测试可替换);nil 使用系统解析器。
Lookup func(ctx context.Context, host string) ([]netip.Addr, error)
// Dial 建立到「已校验的 IP:端口」的连接(测试可替换);nil 使用带 Control 校验的真实拨号。
Dial func(ctx context.Context, network, addr string) (net.Conn, error)
}
URLPolicy 是 push_url 的网络策略。零值是默认的严格策略。
Click to show internal directories.
Click to hide internal directories.