Documentation
¶
Overview ¶
Package federation 将本站点接入 PigeonBox P2P 联邦（github.com/pigeonbox/p2p）。
职责（M2，设计文档 docs/specs/2026-10-04-p2p-registry-service-design.md §5）：
- 节点注册/心跳：Ed25519 签名租约，断线自动重注册 + 全量补公告（自愈）；
- 口令联邦路由：share 生命周期钩子公告/撤销 SHA-256(code)→本节点；
- 解析代理：GET /api/v1/federation/resolve 转查 registry（浏览器免跨域）。
信任模型：本包只做"发现"，取件方直连源节点、源节点本地校验口令——零跨节点信任。 签名负载格式与 p2p 仓 README 契约逐字节一致（见 client.go 常量注释）。 依赖方向：本包不 import 生态任何兄弟模块（叶子约束，core CI dep guard）。
Index ¶
- type ResolveInfo
- type Service
- func (s *Service) Enabled() bool
- func (s *Service) Healthy() bool
- func (s *Service) NodeID() string
- func (s *Service) RegistryURLs() []string
- func (s *Service) Resolve(code string) (*ResolveInfo, error)
- func (s *Service) ShareCreated(code string, expiresAt *time.Time)
- func (s *Service) ShareDeleted(code string)
- func (s *Service) Start()
- func (s *Service) Stop()
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ResolveInfo ¶
type ResolveInfo struct {
NodeID string `json:"node_id"`
URL string `json:"url"`
Name string `json:"name"`
ExpiresAt time.Time `json:"expires_at"`
SizeHint int64 `json:"size_hint"`
}
ResolveInfo 解析结果：口令在联邦内的源节点。
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service federation 客户端服务。实现 share.FederationNotifier 窄接口 （ShareCreated/ShareDeleted），由 bootstrap 注入 share service。
func NewService ¶
func NewService(cfg conf.FederationConfig, nodeName string) (*Service, error)
NewService 构造并加载/生成节点身份密钥。仅在 federation.enabled 时调用； 配置不合法返回错误，由 bootstrap 降级为非联邦模式（不影响单站功能）。
func (*Service) Healthy ¶
Healthy 最近一次 registry 心跳是否成功（未启动/尚未跑首个周期时为 false）。 供管理面（MCP federation_status 等）展示联邦健康度。
func (*Service) RegistryURLs ¶
RegistryURLs 主备 registry 基址列表（配置逗号分隔项的副本）。
func (*Service) Resolve ¶
func (s *Service) Resolve(code string) (*ResolveInfo, error)
Resolve 转查 registry（读路径依次主→备,首个命中即返回）。 全部未接入返回 (nil, nil)——调用方（resolve 代理 handler）以 available:false 回给前端，不区分"未启用/不存在"（降探测面）。
func (*Service) ShareCreated ¶
ShareCreated share 生命周期钩子：新分享公告到联邦（异步，registry 抖动 不拖慢建分享；失败由心跳循环补发）。熵门槛不过则静默跳过——短数字码 不出站，防 registry 侧在线枚举（安全模型见 p2p README）。
func (*Service) ShareDeleted ¶
ShareDeleted share 生命周期钩子：撤销公告（best-effort，索引立即移除； 撤销失败时 registry 条目按公告 TTL 自动过期）。
Source Files