Edge Runtime Protocol

Authentication

After registration, every Edge Runtime request uses:

X-OrbitMesh-Node-Id
X-OrbitMesh-Edge-Runtime-Id
X-OrbitMesh-Installation-Id
X-OrbitMesh-Timestamp
X-OrbitMesh-Nonce
X-OrbitMesh-Body-SHA256
X-OrbitMesh-Signature

Signature payload:

method + "\n" +
path_and_query + "\n" +
body_sha256 + "\n" +
timestamp + "\n" +
nonce + "\n" +
node_id + "\n" +
edge_runtime_id + "\n" +
installation_id

Signature algorithm:

Ed25519(private_key, payload)

The Control Plane stores only the public key. The Edge Runtime private key stays on the host under /var/lib/orbitmesh/edge-runtime.

Register

Endpoint:

POST /api/v1/edge-runtime/register

The register endpoint is the only Edge Runtime API that uses deployment token instead of Runtime request signing.

The deployment token is enrollment authorization. It is not the runtime identity.

Register binds or refreshes a device identity:

installation_id
public_key
device_fingerprint_hash

Register may include reported_address and public_address.

reported_address is the Edge Runtime reported address. It can be a public IP, private IP, or mesh IP. The Control Plane validates only address syntax and must not assume the value is publicly reachable.

Register returns:

node_id
edge_runtime_id
control_plane_url

edge_secret is not part of the target protocol.

Heartbeat

Endpoint:

POST /api/v1/edge-runtime/heartbeat

Default interval:

15 seconds

Heartbeat reports runtime liveness and may include reported_address and public_address.

When reported_address is present, the Control Plane persists it as the Node reported address and reconciles system endpoint DNS records for eligible endpoints. Empty values do not clear the last known address.

For public Traffic Entry endpoints, the DNS provider writes A or AAAA records with proxied=false. Future mesh endpoint binding can use the same reported address field without requiring the address to be globally routable.

Certificates

Endpoints:

GET /api/v1/edge-runtime/certificates
POST /api/v1/edge-runtime/certificates/csr

Edge Runtime pulls certificate metadata and submits CSR material for certificates assigned to its Node endpoints. Certificate material is consumed by runtime adapters through local file paths in desired state.

System certificate issuance uses ACME DNS-01. The Control Plane creates the challenge TXT record and attempts to clean up the exact TXT value after the ACME flow completes.

Desired State Pull

Endpoint:

GET /api/v1/edge-runtime/desired-state

Edge Runtime should send current applied version:

X-OrbitMesh-Current-Version: 3

If no change, server may return:

304 Not Modified

current_version 只在全部 RuntimeConfiguration 成功应用并完成结果上报后前进。 如果最新 Desired State 曾进入 failed 或 rolled_back，但其版本仍高于 Edge Runtime 当前成功应用的版本，Control Plane 必须继续返回该版本，使临时故障修复或 Edge Runtime 升级后可以自动重试并收敛。

Apply Result

Endpoint:

POST /api/v1/edge-runtime/apply-result

Statuses:

• applied
• failed
• rolled_back