federation

Overview ¶

delivery.go — 跨站投递（联邦前台化，2026-11-01）。

形态（设计稿：docs/specs/2026-11-01-federation-frontend-delivery-design.md）：

访客 ──① 在发起柜（A 柜）前台填「对方柜 URL」+ 选文件
        A 柜 ──② 校验目标 ∈ 管理员登记的「可投递对端」
        A 柜 ──③ 带共享口令调对方柜（B 柜）铸投递槽位
        A 柜 ──④ 把文件**流式**转发到 B 柜的访客投递端点
                B 柜落库 ⇒ **B 柜的 share 域铸 6 位取件码**
        A 柜 ──⑤ 把 B 的 6 位码回给访客（访客转告取件人）
取件人 ──⑥ 在 **B 柜** 用该 6 位码取件

三条不变性（改代码前先读）：

1. **码由对方柜铸**：A 柜只透传 B 柜返回的 6 位码 ⇒ 码空间天然是对方的 （取件人站在对方柜取件）⇒ 不需要跨柜共享码空间。
2. **出站 URL 只来自 admin 配置**（conf.FederationConfig.DeliveryPeers）， 不是访客任意输入 ⇒ SSRF 面从「任意 URL」收窄到「admin 配的 URL」； 私网对端按**对端粒度**放行（allow_private），不动全局 SSRF 开关。
3. **口令即权限**（同现有联邦的「口令 bearer」信任级）：比对用常数时间 比较，防时序侧信道。

归属：本文件属联邦域（跨实例协作），出站面与铸槽位面都在这里； 访客投递的重管道（multipart 解析）留在 transport/http/handler 层。

directory.go — 联邦节点名录透传（2026-10-14 邀请信箱配套；2026-10-22 由 直传包搬入）。

名录端点无鉴权（零敏感，公开信息），registry URL 由宿主从管理端 SystemConfig 注入（已过 SSRF 校验）。直传未启用/二进制缺失不挡名录查询—— 名录可见性只取决于 registry 可达。

归属：名录是对端站点列表，属联邦域，不属直传域——本文件不依赖 p2pc 运行时。

命名（2026-10-22 L3）：PeerDirectory = 联邦节点名录，**无条件**构造 （可见性只取决于 registry 可达，与联邦运行时是否启用无关；见 invite.go 文件头的三类服务命名约定）。

Package federation 实现 PigeonBox 的 P2P 联邦面（跨实例口令路由 + 邀请交接）。

三个角色与构造条件（2026-10-22 命名统一） ¶

本包导出三个服务，**构造条件不同**，这是设计使然、不是遗漏：

Node          本机节点运行时：节点身份（ed25519）、注册中心心跳、分享公告。
              仅在 federation.enabled 时构造；配置不合法时 bootstrap 降级
              为非联邦模式（单站功能不受影响）。
PeerDirectory 在线名录：列出联邦内可发现的对端。**无条件构造**——联邦关闭时
              名录仍要能读出「为什么不可用」，且注册中心地址来自配置而非运行态。
InviteMailbox  邀请信箱：待收邀请的出箱/留痕。**无条件构造**——收件箱在联邦
              关闭时也必须可用（邀请可以先到、联邦后开）。

与设备直传的关系 ¶

2026-10-22 Wave B' 起，Box 侧**不再编排设备直传**（原 p2px 域已整包删除）， 直传本体归独立应用 PigeonBeam。本包只保留联邦面（口令路由 + 邀请信封交接）。

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）。

本包三类服务按**构造条件**分家（2026-10-22 L3 命名收口，读者一眼可辨）：

Service        联邦运行时（注册/心跳/公告/解析）——**仅联邦启用时**构造
               （NewService 在 !cfg.Enabled 时报错，由装配层降级为非联邦模式）。
InviteMailbox  联邦邀请收件箱——**无条件**构造：跨实例交接的凭证与状态机，
               与联邦运行时无关（联邦关闭时公开收件端点仍可用）。
PeerDirectory  联邦节点名录——**无条件**构造：可见性只取决于 registry 可达。

后两者的实例由装配层（bootstrap/wiring.go）构造，直传编排层只消费 （setter 注入）——删掉直传编排层时联邦能力不受影响（Wave B'）。

invite.go — 联邦信封管理（跨实例推送邀请；2026-10-22 由直传包搬入）。

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

归属：信封是跨实例交接的凭证与状态机，属联邦域，不属直传域——本文件不 依赖 p2pc 运行时（无 spawn / 子进程 / 任务环），Wave B 删直传包时 本包原样留存。

命名（2026-10-22 L3）：本包三类服务按"构造条件"分家，读者一眼可辨——

• Service：联邦运行时（注册/心跳/公告），**仅联邦启用时**构造；
• InviteMailbox：联邦邀请收件箱，**无条件**构造（联邦关闭时仍可用， 它是跨实例交接的凭证与状态机，与联邦运行时无关）；
• PeerDirectory：联邦节点名录，**无条件**构造（可见性只取决于 registry 可达，不取决于联邦是否启用）。

sync.go — 联邦邀请的定时同步（core#32）。

背景：联邦的「邀请推送」此前**只有手动触发**（POST /admin/p2p/invite-push ⇒ 实际 POST 对方站 /api/v1/p2p/invite），core/app/federation/ 下零调度面。 本文件补上**周期自动同步**面：定时把待推的邀请送给已配置的对端，并把 对端推来的邀请收进待收列表。

## 与既有语义一致（issue 硬要求：定时是补充不是替代）

手动推送走的是同一条链路（PushInvite → 对方站 POST /api/v1/p2p/invite）， 本调度器只是**周期地**驱动同一份逻辑 ⇒ 手动端点保留且行为不变。

## 幂等（issue 硬要求：重启后不重复推送）

两道幂等闸：

1. 收侧：InviteMailbox.AddInvite 对同 code 去重（收件箱既有语义）。
2. 发侧：Sync 器自身维护「已推送过的 code」集合（内存态）⇒ 同一进程内 周期重跑不重复推送；进程重启后集合丢失，但收侧闸仍生效（对方站 收件箱同码去重）⇒ 端到端不重复。

## 前置事实（2026-11-01 核代码，纠正 issue 原文两处前提）

① issue 称「core/app/federation/ 下零 cron / Ticker」——**不成立**：

federation.go 的 Node.loop 已有 30min 心跳 ticker（注册续租 + 全量
重公告）。本文件加的是**邀请同步**调度面，与心跳面职责不同（心跳管
registry 租约，同步管邀请递送），不重复造轮子。

② issue 称「定时任务必须只在 admin 副本跑（否则 N 个副本重复推送）」——

**前提不成立**：conf.FederationAllowedInMode 规定联邦**只在 standalone
模式可用**（多副本下节点身份是进程级 Ed25519，语义未定义）⇒ 多副本
部署里联邦运行时根本不启动，不存在 N 副本重复推送。
但「只在 admin 面跑」仍是本调度器**必须**满足的约束（与仓内其它
后台任务同一道门）：public 副本不跑 ⇒ 也不依赖上面的架构性禁用。

## 依赖方向

本包不 import 生态任何兄弟模块（叶子约束，core CI dep guard）。