Read OSS
apple/container

XPC 通信层：进程间如何相互通信

•高级

前置知识

  • ›第 1 篇：架构与导读指南
  • ›熟悉 Swift actor 和 async/await
  • ›了解 macOS XPC 和 Mach 服务的基本概念

XPC 通信层：进程间如何相互通信

在第 1 篇中我们了解到，apple/container 并非单一进程，而是由五个相互协作的可执行文件组成。它们之间传递的每一条消息，都要经过位于 Sources/ContainerXPC/ 的自定义 XPC 抽象层。这一层主要承担三项职责：为 XPC 字典提供类型安全的访问方式、将 XPC 基于回调的 API 转换为 Swift async/await 风格、以及对每条传入消息执行基于 EUID 的安全校验。

本文将逐一剖析该层的各个组件，分析各服务目标如何在其之上构建类型化的 API 契约，并重点介绍 container runtime helper 中一个尤为精妙的安全设计模式。

XPCMessage：基于 xpc_object_t 的类型化字典

Apple 的 XPC 框架使用不透明的 xpc_object_t 值进行操作。要从 XPC 字典中读取一个字符串，需要调用 xpc_dictionary_get_string 并传入 C 字符串 key，返回值是 UnsafePointer<CChar>?，还需要手动转换类型。这不仅繁琐，也容易出错。

XPCMessage 对 xpc_object_t 进行了封装，为项目所需的每种类型都提供了类型安全的访问接口：

classDiagram
    class XPCMessage {
        +routeKey: String$
        +errorKey: String$
        -object: xpc_object_t
        -lock: NSLock
        +string(key) String?
        +set(key, String)
        +data(key) Data?
        +set(key, Data)
        +bool(key) Bool
        +uint64(key) UInt64
        +int64(key) Int64
        +date(key) Date
        +fileHandle(key) FileHandle?
        +set(key, FileHandle)
        +endpoint(key) xpc_endpoint_t?
        +reply() XPCMessage
        +error() throws
        +set(error: ContainerizationError)
    }

有两个细节值得重点关注。其一，所有对底层 xpc_object_t 的访问都通过 NSLock 串行化。该对象本身被标记为 nonisolated(unsafe)——这是 Swift 6 并发模型中的一个逃生舱口——但实际访问始终受锁保护。其二，错误处理遵循约定：错误信息以 ContainerXPCError 结构体的形式 JSON 编码，存储在一个固定 key 下（XPCMessage.swift#L78-L98）。客户端在每次收到响应后都会调用 message.error() 来检查服务端是否发生了错误。

fileHandle 访问器同样值得关注。XPC 支持在进程间传递文件描述符——内核会将描述符复制到接收进程的文件表中。这正是 stdin/stdout/stderr 管道从 CLI 经由 API server 传递到 container runtime 的方式。XPCMessage.swift#L218-L235 中的实现使用 xpc_fd_create 和 xpc_fd_dup 来管理描述符的生命周期。

提示： dataNoCopy(key:) 是一个性能优化接口，它返回直接指向 XPC 对象内存的 Data，避免了数据拷贝。适合在需要立即消费数据（例如 JSON 解码）时使用，但要注意：一旦 XPC 消息被释放，该数据也随之失效。

XPCServer：基于路由的分发与安全校验

XPCServer 初始化时接收一个 Mach 服务标识符，以及一个将路由字符串映射到处理闭包的字典。调用 listen() 后，它会创建一个 Mach 服务监听器，接受传入连接，并根据消息中内嵌的路由 key 将每条消息分发给对应的处理函数。

flowchart TD
    A[Incoming XPC Connection] --> B{xpc_get_type?}
    B -->|CONNECTION| C[handleClientConnection]
    B -->|ERROR| D[Finish Stream]
    C --> E[Receive Message]
    E --> F{Is Dictionary?}
    F -->|No| G[Reply Error]
    F -->|Yes| H{EUID Match?}
    H -->|No| I[Reply Unauthorized]
    H -->|Yes| J{Route Exists?}
    J -->|No| K[Reply Invalid]
    J -->|Yes| L[Call Handler]
    L --> M[Send Response]

安全校验的逻辑简洁却至关重要。在 XPCServer.swift#L166-L184 中，每条传入消息都会通过 xpc_dictionary_get_audit_token 提取 audit token，服务端再用 geteuid() 将客户端的有效 UID 与自身进行比对。若不匹配，请求会被立即拒绝。这一机制可防止同机器上的其他用户向你的 container daemon 发送指令。

连接处理使用 AsyncStream 将 XPC 的回调模型桥接到结构化并发中。外层的 listen() 方法将连接事件处理器封装为 AsyncStream<xpc_connection_t>，每个连接的消息流则封装为 AsyncStream<xpc_object_t>。两个 stream 均使用 withThrowingDiscardingTaskGroup 并发处理各自的元素。

XPCClient：将回调桥接为 Async/Await

在客户端，XPCClient 封装了 xpc_connection_create_mach_service，并提供了异步的 send 方法。其中最值得关注的是超时处理机制。

send(_:responseTimeout:) 使用 withThrowingTaskGroup 让两个任务竞速执行：一个是实际的 XPC 发送操作（通过 withCheckedThrowingContinuation 封装），另一个是超时后抛出错误的 sleep 任务。谁先完成谁获胜，另一个随即被取消：

sequenceDiagram
    participant Caller
    participant TaskGroup
    participant XPC as xpc_connection_send
    participant Timer as Task.sleep

    Caller->>TaskGroup: addTask(XPC send)
    Caller->>TaskGroup: addTask(sleep timeout)

    alt XPC responds first
        XPC-->>TaskGroup: XPCMessage
        TaskGroup->>Timer: cancel
        TaskGroup-->>Caller: response
    else Timeout fires first
        Timer-->>TaskGroup: throw timeout error
        TaskGroup->>XPC: cancel
        TaskGroup-->>Caller: throw error
    end

默认超时时间为 60 秒（XPCClient.xpcRegistrationTimeout），这是有意设置得较为宽裕的。当 container runtime helper 首次向 launchd 注册时，macOS 实际启动该进程可能需要数秒时间。服务运行起来之后，XPC 请求的响应时间通常只需毫秒级。

Route 与 Key 枚举：类型化的 API 契约

原始的 XPCMessage 使用字符串 key 进行操作。各服务层在此之上通过枚举构建了类型安全的契约。ContainerAPIClient 中的 XPC+.swift 定义了两个枚举：

XPCKeys — 流经 API server 的所有数据字段名，包括容器配置、进程 ID、stdio 文件描述符、网络状态、volume 数据、进度更新等。

XPCRoute — API server 处理的所有路由，如 containerList、containerCreate、containerBootstrap、networkCreate、pluginLoad、ping 等数十个路由。

该文件还为 XPCMessage 提供了类型化的扩展方法，接受 XPCKeys 和 XPCRoute 值而非原始字符串，从而将 message.string(key: "id") 升级为 message.string(key: .id)。

sandbox 服务在 SandboxRoutes.swift 中定义了一套平行的枚举。每个路由都以 com.apple.container.sandbox/ 为命名空间前缀，例如 com.apple.container.sandbox/bootstrap 或 com.apple.container.sandbox/createProcess。

classDiagram
    class XPCRoute {
        <<enumeration>>
        containerList
        containerCreate
        containerBootstrap
        containerStop
        networkCreate
        pluginLoad
        ping
        ...
    }
    class SandboxRoutes {
        <<enumeration>>
        createEndpoint
        bootstrap
        createProcess
        start
        stop
        wait
        dial
        shutdown
        ...
    }
    class XPCKeys {
        <<enumeration>>
        id
        containerConfig
        stdin
        stdout
        stderr
        exitCode
        ...
    }
    XPCRoute ..> XPCMessage : used with
    SandboxRoutes ..> XPCMessage : used with
    XPCKeys ..> XPCMessage : used with

提示： 如果你要为 apple/container 新增一个操作，第一步应该是在对应的枚举中添加路由，以及为所有新数据字段添加 key。先确立契约，再编写业务逻辑。

Service/Harness 模式

代码库中所有服务端服务都遵循一个统一的双结构体模式：

  1. Service（通常是 actor）持有业务逻辑和可变状态。
  2. Harness（通常是 struct）负责反序列化 XPC 消息、调用 service，并将响应序列化后返回。

Harness 的方法在 API server 启动时注册为路由处理函数。查看 APIServer+Start.swift#L264-L292 可以看到：ContainersService 是 actor，ContainersHarness 是 struct，而 XPCRoute.containerCreate 等路由则映射到 harness.create。

这种分离设计非常清晰：service 层完全不接触 XPCMessage，因此可以脱离 XPC 独立测试。harness 只是薄薄的胶水代码——解码请求、调用 service、编码响应。API server 中的所有服务都遵循这一模式：PluginsService/PluginsHarness、NetworksService/NetworksHarness、VolumesService/VolumesHarness、HealthCheckService/HealthCheckHarness。

container-runtime-linux 中的双服务器安全模式

runtime helper 使用了整个代码库中最有趣的 XPC 模式。它并非将所有操作暴露在单一 Mach 服务上，而是运行两个 XPC server。

查看 RuntimeLinuxHelper+Start.swift#L74-L122：

sequenceDiagram
    participant Client as API Server / CLI
    participant EP as Endpoint Server<br/>(public Mach service)
    participant Main as Main Server<br/>(anonymous connection)

    Note over EP: Only exposes createEndpoint route
    Client->>EP: createEndpoint
    EP->>EP: xpc_endpoint_create(anonymousConnection)
    EP-->>Client: XPC endpoint token
    Client->>Client: xpc_connection_create_from_endpoint
    Client->>Main: bootstrap, createProcess, wait...
    Main-->>Client: responses

endpoint server 以公开的 Mach 服务名（例如 com.apple.container.runtime.container-runtime-linux.{uuid}）向 launchd 注册，仅暴露一个路由：createEndpoint。该路由从匿名连接创建一个 XPC endpoint 并将其返回。

main server 在该匿名连接上监听，暴露所有真正的操作：bootstrap、createProcess、start、stop、kill、resize、wait、dial、shutdown 和 statistics。

为什么要这样拆分？公开的 Mach 服务名可被系统上任意进程发现。通过将公开接口限制为单一的 createEndpoint 操作，即便攻击者能够连接到该服务，其能做的事情也极为有限。真正的 sandbox 操作只能通过匿名 endpoint 访问——而获取该 endpoint 的前提，是成功调用 createEndpoint 并通过 EUID 校验。

这次握手的客户端逻辑位于 SandboxClient.swift#L50-L75。静态方法 create 连接到公开的 Mach 服务，调用 createEndpoint，从响应中提取 endpoint，基于该 endpoint 创建新连接，最终返回一个由此直连支撑的 SandboxClient。

下一步

理解了通信层之后，我们就可以端到端地追踪一次完整的操作流程了。下一篇文章将跟随 container run 从你按下回车的那一刻出发——经过 CLI 解析、向 API server 发起 XPC 调用、向 launchd 注册 plugin、执行我们刚才介绍的 endpoint 握手、创建 VM、启动 Linux、传递 stdio 管道，直到进程退出。