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
- func PushInvite(ctx context.Context, targetURL, code, fromName, note string) error
- type Deps
- type DirectoryPeer
- type Invite
- type InviteSnapshot
- type SendOption
- type Service
- func (s *Service) AddInvite(code, fromName, note string) (Invite, error)
- func (s *Service) Cancel(ctx context.Context, taskID string) error
- func (s *Service) DirectoryPeers(ctx context.Context) ([]DirectoryPeer, error)
- func (s *Service) List(ctx context.Context) []*TaskSnapshot
- func (s *Service) ListInvites() []InviteSnapshot
- func (s *Service) MarkPublished(taskID string)
- func (s *Service) PublishPaths(ctx context.Context, taskID string) ([]string, error)
- func (s *Service) Recv(ctx context.Context, code string) (*Task, error)
- func (s *Service) Send(ctx context.Context, paths []string, opts ...SendOption) (*Task, error)
- func (s *Service) Status(ctx context.Context) (Status, error)
- func (s *Service) Stop() error
- func (s *Service) TakeInvite(id string) (Invite, error)
- type Status
- type Task
- type TaskSnapshot
Constants ¶
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
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
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 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 (*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 ¶
MarkPublished 置发布标记(handler 在全部文件铸分享成功后调用)。
func (*Service) PublishPaths ¶
PublishPaths 收件任务的可发布绝对路径(三层防穿越:任务态校验+目录归属+symlink 归一)。 只列顶层常规文件(目录由 share 侧逐文件递归处理不在本期范围)。 幂等闸:已发布过的任务拒绝(重复/并发 publish 会重复铸分享+重复拷存储)。
type Status ¶
type Status struct {
Available bool
BinaryPath string
Enabled bool
RegistryURL string
RecvDir string
InboxUsed int64
InboxQuota int64
DeployAllowed bool
}
Status admin 状态面。