Help us shape the future of Go! Take the 2026 Go Developer Survey

p2px

package
v0.21.2 Latest Latest
Warning

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

Go to latest
Published: Oct 15, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Overview

directory.go — p2pd 在线名录透传(2026-10-14 邀请信箱配套)。 p2px 侧轻量 HTTP 客户端:名录端点无鉴权(零敏感,公开信息), registry URL 来自 admin SystemConfig(已过 SSRF 校验)。

invite.go — 实例间推送邀请(P3,spec §14:免口令交接)。

语义:邀请 = 口令 bearer(与手工交接同信任级——口令本身即授权,通道只是 递送);收件箱内存态(cap 20 / TTL 10 分钟 = p2pc 配对窗口,进程重启丢弃 可接受,口令同样已失效);出站推送目标 URL 走 SSRF 守卫(与 registry_url 同策略,私网目标需 security.ssrf.allow_private_networks)。

Package p2px P2P 设备直传 supervisor(2026-10-14 对称节点 spec §7)。

职责切分:数据面走子进程(每任务 spawn p2pc,进程组 kill 即取消,与 desktop sidecar 语义一致——p2pc 协议层无 ctx 取消,kill 是唯一取消面); 控制面进程内:任务编排/口令与输出解析/配额监控/孤儿清扫。standalone 专属 (多副本语义未定义,与 federation 同约束)。

配置来源:SystemConfig p2p.direct 子段(DB 热生效),经 Deps.GetDirect 注入 (构造注入,棘轮规则 8:不直读全局 conf)。env/yaml 不参与直传段——后台即真相。

spawn.go — p2pc 子进程生命周期:spawn/输出解析/配额监控/进程组取消。

watcher.go — 信箱 watcher(2026-10-14 在线名录+邀请信箱):长驻 `p2pc mailbox --watch` 子进程 + 宿主侧守护。

生命周期:与传输任务解耦——非 Task(不占并发闸、无 specSnapshot 重派, 既有 task monitor 只认任务表);守护在 monitorLoop 每 tick 对账: 期望态 = 直传 enabled && discoverable(opt-in) && standalone && 二进制 在位;进程死 = 指数退避重启(1s 起、60s 封顶,tick 粒度),Stop = 杀进程。 stdout = NDJSON 邀请事件流({"event":"invite","code":...,"name":..., "note":...}) → AddInvite(P3 收件箱,UI/API 零改动复用);开箱验真在 p2pc 侧以名录 box_pub 完成,宿主只收验真后的口令。

Index

Constants

View Source
const (
	StateWaiting  = "waiting" // 已 spawn,等待对端接入/传输启动
	StateRunning  = "running" // 传输进行中(收到口令行之外的首个输出)
	StateDone     = "done"
	StateFailed   = "failed"
	StateCanceled = "canceled"
	StateRetrying = "retrying" // 失败退避中,稍后自动重派(断点续传环)
)

任务状态机。

Variables

This section is empty.

Functions

func PushInvite added in v0.20.0

func PushInvite(ctx context.Context, targetURL, code, fromName, note string) error

PushInvite 把口令推送到目标实例的邀请收件端点(P3 免口令交接)。 targetURL = 目标实例基址(如 https://b.example.com); 实际 POST <target>/api/v1/p2p/invite,10s 超时。

Types

type Deps

type Deps struct {
	// Standalone 部署形态判定(棘轮规则 8:构造注入,不直读全局 conf)
	Standalone func() bool
	// DataDir 服务数据目录(默认收件区/任务工作区基准)
	DataDir string
	// GetDirect 读当前直传配置(DB 热生效;bool=false 表示未配置)
	GetDirect func(ctx context.Context) (conf.P2PDirectConfig, bool)
	// MonitorInterval 配额监控周期(缺省 5s;测试可压到毫秒级)
	MonitorInterval time.Duration
	// MaxAttempts 自动续传最大重试次数(缺省 8;0=缺省)
	MaxAttempts int
	// GhostPairTimeout 收端零字节配对看门狗(缺省 90s;测试可调)
	GhostPairTimeout time.Duration
	// InboxTTL 收件区文件存活期(缺省 7 天;终态/已发布/无属主目录超期即清扫,spec §7.3)
	InboxTTL time.Duration
	// NodeName 名录显示名(站点名;信箱 watcher --name 注入,缺省 p2pc)
	NodeName string
}

Deps supervisor 依赖注入(生产由 bootstrap/wiring 装配;测试注入桩)。

func (Deps) MaxAttemptsFor added in v0.21.0

func (d Deps) MaxAttemptsFor(_ *Task) int

MaxAttemptsFor 生效重试预算(Deps 覆盖 > 缺省)。

type DirectoryPeer added in v0.21.0

type DirectoryPeer struct {
	NodeID      string `json:"node_id"`
	Name        string `json:"name"`
	URL         string `json:"url"`          // 对外基址(NAT 后可为空)
	BoxPub      string `json:"box_pub"`      // X25519 密封公钥 hex
	OnlineSince int64  `json:"online_since"` // 租约起始 unix 秒
}

DirectoryPeer 名录对端(与 p2pd GET /v1/directory 条目同形)。

type Invite added in v0.20.0

type Invite struct {
	ID         string
	Code       string
	FromName   string
	Note       string
	ReceivedAt time.Time
}

Invite 待收邀请(收件箱条目)。

type InviteSnapshot added in v0.20.0

type InviteSnapshot struct {
	ID         string    `json:"id"`
	Code       string    `json:"code"`
	FromName   string    `json:"from_name"`
	Note       string    `json:"note"`
	ReceivedAt time.Time `json:"received_at"`
	ExpiresIn  int64     `json:"expires_in"` // 秒
}

InviteSnapshot 对外快照(含过期倒计时,前端渲染用)。

type SendOption added in v0.21.0

type SendOption func(*sendOpts)

SendOption 发送任务可选参数。

func WithInvite added in v0.21.0

func WithInvite(toNode, note string) SendOption

WithInvite 发送后向名录对端投递密封邀请(2026-10-14 在线名录: p2pc send --invite-to;发邀请=发端自愿入名录;失败仅 WARN 不影响发送)。

type Service

type Service struct {
	// contains filtered or unexported fields
}

Service supervisor 服务。

func NewService

func NewService(deps Deps) *Service

NewService 构造(幂等清扫孤儿 + 起配额监控协程)。

func (*Service) AddInvite added in v0.20.0

func (s *Service) AddInvite(code, fromName, note string) (Invite, error)

AddInvite 邀请入箱(口令格式校验 + 同码去重 + 满箱拒绝)。

func (*Service) Cancel

func (s *Service) Cancel(ctx context.Context, taskID string) error

Cancel 取消任务(kill 进程组)。

func (*Service) DirectoryPeers added in v0.21.0

func (s *Service) DirectoryPeers(ctx context.Context) ([]DirectoryPeer, error)

DirectoryPeers 拉取在线名录(admin 目录对端选择器消费)。 直传未启用/二进制缺失不挡名录查询——名录可见性只取决于 registry 可达。

func (*Service) List

func (s *Service) List(ctx context.Context) []*TaskSnapshot

List 任务列表(创建时间倒序)。

func (*Service) ListInvites added in v0.20.0

func (s *Service) ListInvites() []InviteSnapshot

ListInvites 未过期邀请(新到在前)。

func (*Service) MarkPublished

func (s *Service) MarkPublished(taskID string)

MarkPublished 置发布标记(handler 在全部文件铸分享成功后调用)。

func (*Service) PublishPaths

func (s *Service) PublishPaths(ctx context.Context, taskID string) ([]string, error)

PublishPaths 收件任务的可发布绝对路径(三层防穿越:任务态校验+目录归属+symlink 归一)。 只列顶层常规文件(目录由 share 侧逐文件递归处理不在本期范围)。 幂等闸:已发布过的任务拒绝(重复/并发 publish 会重复铸分享+重复拷存储)。

func (*Service) Recv

func (s *Service) Recv(ctx context.Context, code string) (*Task, error)

Recv 发起接收任务(口令 → spawn p2pc recv --yes --out <收件区>/<taskID>)。

func (*Service) Send

func (s *Service) Send(ctx context.Context, paths []string, opts ...SendOption) (*Task, error)

Send 发起发送任务(白名单校验 → spawn p2pc send → 口令行异步解析进任务)。

func (*Service) Status

func (s *Service) Status(ctx context.Context) (Status, error)

Status 状态面:二进制探测 + 生效配置 + 收件区用量。

func (*Service) Stop

func (s *Service) Stop() error

Stop 停机(Cleanup 调用;幂等):杀全部在途子进程 + 停监控。

func (*Service) TakeInvite added in v0.20.0

func (s *Service) TakeInvite(id string) (Invite, error)

TakeInvite 认领(出箱);不存在/已过期报错。

type Status

type Status struct {
	Available     bool
	BinaryPath    string
	Enabled       bool
	RegistryURL   string
	RecvDir       string
	InboxUsed     int64
	InboxQuota    int64
	DeployAllowed bool
}

Status admin 状态面。

type Task

type Task struct {
	ID        string
	Kind      string // send | recv
	Code      string
	Paths     []string
	BytesDone int64
	CreatedAt time.Time
	// contains filtered or unexported fields
}

Task 直传任务(内存态;重启即 expired 语义——pid 文件清扫兜底)。

func (*Task) Snapshot

func (t *Task) Snapshot() TaskSnapshot

Snapshot 并发安全快照。

type TaskSnapshot

type TaskSnapshot struct {
	ID         string
	Kind       string
	State      string
	Code       string
	Paths      []string
	BytesDone  int64
	Error      string
	Attempts   int
	CreatedAt  time.Time
	FinishedAt time.Time
}

TaskSnapshot 对外只读快照(handler 消费)。

Jump to

Keyboard shortcuts

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