# Infra Protocol

面向个人基础设施的本机协议；当前包含 Infra Discovery，用于发布和查找服务入口。

## Metadata

- HTML: https://glenzli.com/projects/infra-protocol/
- Markdown: https://glenzli.com/projects/infra-protocol.md
- Collection: Projects
- Language: zh-CN
- Published: 2026-08-11
- Updated: 2026-08-27
- Status: active
- Tags: personal-infra, protocol, discovery, local-services

## Content

Infra Protocol 为个人基础设施服务维护本机协议。当前包含 **Infra Discovery**：服务把协议版本、binding 与 endpoint 发布到共享运行目录，消费者找到自己支持的组合后直接连接。

Discovery 只负责找到入口。连接后的请求、响应、错误和权限仍由对应的应用协议定义。

  ![服务发布 endpoint，消费者发现并选择兼容入口](/images/projects/infra-protocol-banner.webp)

## Infra Discovery

每个服务发布一份 registration manifest，其中包含稳定的服务身份、当前进程的 `generation`，以及一组 `(protocol, protocol_versions, binding, endpoint)` offer。

```text
Service -> registration manifest
Consumer -> exact protocol version + binding
Consumer ---------------------------> endpoint
```

    **精确匹配**
    消费者按明确支持的协议版本和 binding 选择入口。

    **候选入口**
    manifest 提供候选 endpoint，消费者通过实际连接确认其当前状态；连接失败后可以重新扫描。

    **Generation 更新**
    服务重启或 offer 变化时生成新的 generation，并在 endpoint 就绪后原子更新 manifest。

    **当前用户边界**
    manifest 仅允许当前用户访问；Unix socket 与 Windows named pipe 服务端还需要验证连接方属于同一操作系统用户。

## 运行目录

macOS、Linux 与 Windows 各有默认的当前用户运行目录。沙箱或 packaged 应用必须显式使用所有参与者都能访问的共享目录；没有共享目录时，Discovery 不可用。

Unix socket endpoint 使用运行目录下的相对路径，并受平台路径长度限制。最终路径与访问权限需要由发布者和消费者共同校验。

## 边界

Infra Discovery 的 schema 到 endpoint 为止。请求格式、权限、健康状态和 Console 地址由对应的应用协议定义。仓库保存当前规范、JSON Schema、有效与无效 fixtures，以及 Schema 之外的 conformance 检查。

当前 Discovery 文档版本是 `infra.discovery.registration@20260812.1`。