Configuration Compiler

1. 定位

Configuration Compiler 将 Control Plane Desired State 编译成 runtime-specific configuration。

Compiler 不直接操作系统、不启动 runtime、不写本地文件。Edge Runtime 负责执行。

2. 输入

Compiler 输入：

• Node。
• CapabilityBinding。
• RuntimeBinding。
• Endpoint。
• Domain。
• Certificate。
• Subscription。
• TrafficPolicy route plan。
• Runtime parameter values。
• Secrets and certificate references。

3. 输出

Compiler 输出 RuntimeConfiguration：

{
  "node_id": "node_xxx",
  "runtime_binding_id": "rb_xxx",
  "runtime": "sing-box",
  "format": "json",
  "manifest": {
    "files": [
      {
        "path": "/etc/sing-box/config.json",
        "content": "{...}"
      }
    ],
    "reload": {
      "strategy": "reload"
    }
  },
  "checksum": "sha256:..."
}

4. Compile Unit

Compilation unit is Runtime Binding.

RuntimeBinding
  -> reads CapabilityBindings on same Node
  -> reads Endpoints owned by those capabilities
  -> reads subscriptions, policies, certificates
  -> emits one runtime manifest

Do not compile by old gateway type.

5. Traffic MVP

MVP compiler supports:

• traffic.entry with sing-box Trojan inbound.
• traffic.exit with sing-box internal mixed listener and direct outbound.
• subscription users.
• route plan from Traffic Policy Engine.
• certificate paths from Endpoint TLS binding.
• usage attribution metadata.

Traffic route plan uses match_json and target_json. The Traffic Policy Engine resolves target_json into a selected runtime endpoint before runtime compilation. Public entry endpoints and inter-node proxy endpoints are distinct endpoint purposes; the compiler must consume the resolved endpoint and must not infer inter-node connectivity from Node hostname, public_address, or reported_address.

For the current sing-box Traffic Exit path:

• Runtime adapter publishes an endpoint template for traffic.exit.
• Endpoint purpose is inter_node_proxy.
• Endpoint protocol is mixed.
• Endpoint network is tcp.
• Endpoint port is runtime.proxy.listen_port.
• sing-box compiler maps the mixed endpoint to a sing-box socks outbound internally because sing-box connects to its own mixed inbound with a SOCKS-compatible outbound.

socks is therefore a sing-box compiler detail, not the OrbitMesh endpoint protocol.

6. sing-box Traffic Entry Example

{
  "inbounds": [
    {
      "type": "trojan",
      "tag": "traffic-entry-trojan",
      "listen": "::",
      "listen_port": 443,
      "users": [
        {
          "name": "sub_001",
          "password": "secret"
        }
      ],
      "tls": {
        "enabled": true,
        "server_name": "tenant.example.com",
        "certificate_path": "/var/lib/orbitmesh/certs/cert_xxx/cert.pem",
        "key_path": "/var/lib/orbitmesh/certs/cert_xxx/key.pem"
      }
    }
  ],
  "outbounds": [
    {
      "type": "socks",
      "tag": "traffic-exit-tokyo",
      "server": "10.0.0.2",
      "server_port": 18080
    }
  ]
}

7. sing-box Traffic Exit Example

{
  "inbounds": [
    {
      "type": "mixed",
      "tag": "traffic-exit-listener",
      "listen": "0.0.0.0",
      "listen_port": 18080
    }
  ],
  "outbounds": [
    {
      "type": "direct",
      "tag": "direct"
    }
  ]
}

8. Certificate Handling

Compiler only consumes certificate references and local materialized paths.

Compiler must not:

• create ACME orders.
• write DNS records.
• read private key material from Control Plane database.
• generate certificates.

9. Quota Handling

When subscription quota is blocked, compiler excludes that subscription credential from runtime configuration and publishes a new desired state.

When quota is restored, compiler includes the subscription credential again and publishes a new desired state.

10. Validation

Compiler validation:

• selected runtime supports required capability roles.
• endpoint certificate is ready when TLS termination is required.
• subscription is active and not quota-blocked.
• route plan targets available traffic.exit binding.
• runtime parameter values satisfy JSON Schema.

11. Acceptance

• Can compile sing-box config for traffic.entry runtime binding.
• Can compile sing-box config for traffic.exit runtime binding.
• Can exclude revoked or quota-blocked subscriptions.
• Can include ready endpoint TLS paths.
• Can publish new RuntimeConfiguration when policy, endpoint, certificate, subscription, or quota state changes.