Infra Protocol

中文 / English

Infra Protocol 为个人基础设施服务维护协议。目前包含 Infra Discovery，用于发布和查找本机 服务入口。

当前 Discovery 文档版本：infra.discovery.registration@20260812.1

Infra Discovery

服务在共享运行目录中发布 registration manifest。每份 manifest 包含：

• service.kind、service.instance_id 和 service.generation；
• 一组 (protocol, protocol_versions, binding, endpoint) offer。

消费者扫描 manifest，选择它支持的协议、精确版本和 binding，然后直接连接 endpoint。连接后 的请求、响应和错误格式由所选应用协议定义，不属于 Discovery。

manifest 只提供候选入口，不表示服务仍在运行。Discovery 不使用 lease 或 heartbeat；连接失败 表示该入口当前不可用，消费者可以重新扫描 manifest 后重试。

运行目录

环境	默认目录
macOS 非沙箱进程	<_CS_DARWIN_USER_TEMP_DIR>/infra-protocol
Linux	$XDG_RUNTIME_DIR/infra-protocol
Windows 非 packaged 桌面进程	<FOLDERID_LocalAppData>\Infra Protocol\Runtime

沙箱或 packaged 应用必须使用所有参与者都能访问的共享目录。可以使用共同的绝对 INFRA_PROTOCOL_RUNTIME_DIR；macOS App Sandbox 也可以使用 <App Group container>/infra-protocol。没有共享目录时，Discovery 不可用。

发布要求

• 同一个 service.kind + service.instance_id 同时只能有一个发布者。
• 每次进程启动或 offer 变化时必须生成新的 service.generation。
• endpoint 就绪后，再以原子替换方式发布仅当前用户可访问的 manifest；无需周期刷新。
• Unix Socket endpoint 使用 sockets/<opaque>.sock，其中 opaque ID 最多 16 个安全 ASCII 字符。发布者和消费者都必须检查最终绝对路径是否符合平台的 sockaddr_un 长度限制。
• Unix Socket 和 Windows Named Pipe 服务端都必须验证连接方属于同一操作系统用户。

完整要求见 SPEC.md。

仓库

路径	内容
SPEC.md	Discovery 规范和本机 binding
schemas/	registration JSON Schema
fixtures/	有效和无效 manifest 样例
conformance/	参考校验器及 Schema 外的检查
MIGRATION.md	从 infra-observer.* 迁移

验证

python3 -m unittest discover -s tests -v

许可证：MIT。