files

package
v2.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 4, 2026 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Overview

Package files 是 Agent 侧的文件能力:stat / hash / 分块读取(拉取)/ 经网址写入(push_url)。

这里是文件能力的安全边界,Hub 只做形状校验与转发,真正的路径授权发生在这里:

  • 路径必须落在请求携带的允许目录之内,并且用 os.Root 打开,符号链接 / .. 无法逃出允许目录;
  • 只处理普通文件(FIFO / 设备 / 目录一律拒绝),且打开时不阻塞;
  • 写入只发生在 push_url:先写同目录的临时文件,校验大小与摘要后再原子落位,不经符号链接写入;
  • 网址访问受 SSRF 策略约束(见 ssrf.go)。

Index

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 Error

type Error struct {
	Code string
	Msg  string
}

Error 是带稳定错误码(termproto.FileErr*)的文件操作错误。

func (*Error) Error

func (e *Error) Error() string

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 New

func New(cfg Config) *Service

New 创建文件服务并启动空闲句柄的回收。用完调用 Shutdown。

func (*Service) Close

func (s *Service) Close(id string)

Close 关闭句柄。重复关闭与未知句柄无害。

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) Open

func (s *Service) Open(roots []string, p string, max int64) (string, int64, *Error)

Open 打开普通文件用于分块读取,返回句柄与文件大小。

func (*Service) PushURL

func (s *Service) PushURL(ctx context.Context, roots []string, dest, rawURL string, o PushOpts) (PushResult, *Error)

PushURL 把网址的内容下载到允许目录内的目标文件:先写同目录的临时文件,校验后再落位。

func (*Service) Read

func (s *Service) Read(id string, off uint64, n int) (data []byte, eof bool, total uint64, e *Error)

Read 从句柄读取 [off, off+n)。返回的 eof 在读到打开时记录的文件大小时为真; 文件在传输中被截短时,返回的数据会少于期望,由调用方(Hub)按总大小核对并中止。

func (*Service) Shutdown

func (s *Service) Shutdown()

Shutdown 关闭全部句柄并停止回收协程。

func (*Service) Stat

func (s *Service) Stat(roots []string, p string) (termproto.FileStat, *Error)

Stat 查询路径的类型 / 大小 / 权限位 / 修改时间。路径不存在不是错误,返回 Exists=false。 符号链接本身按链接报告(不跟随)。

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 的网络策略。零值是默认的严格策略。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL