Node Report Protocol

Ithiltir-node calls Dash /api/node/* endpoints in push mode. The node process itself does not serve these paths.

Target URL

The target URL in config must point to:

https://dash.example.com/api/node/metrics

Derived URLs:

Purpose	URL
Runtime metrics	<target>
Static info	Replace /metrics with /static
Dash identity	Replace /metrics with /identity

report install requires the target path to end with /metrics.

Headers

X-Node-Secret: <node-secret>
Content-Type: application/json

/api/node/identity

Request:

POST /api/node/identity
X-Node-Secret: <secret>

Body:

{}

Response:

{
  "install_id": "dashboard-install-id",
  "created": false
}

If Dash has no install_id, it creates one and returns created=true.

/api/node/metrics

The request body is NodeReport. See runtime metrics schema.

Response:

{
  "ok": true,
  "update": null
}

update can be an update manifest:

{
  "id": "release-id",
  "version": "1.2.3",
  "url": "https://dash.example.com/deploy/windows/node_windows_amd64.exe?upgrade_token=...",
  "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "size": 12345678
}

url may include a short-lived upgrade_token for protected /deploy/* asset access. Nodes must use the returned URL unchanged.

/api/node/static

The request body is Static. See runtime metrics schema.

Static info is reported once after node startup. If static collection is incomplete, the node keeps retrying. It also resends static info after suppressed push failures recover.

Success Rules

The node treats only 200 OK as success. Non-200 responses affect only the current target and do not block other targets.

The /api/node/metrics response body only affects updates:

• Non-JSON or empty body: ignored.
• Content-Type other than application/json: ignored.
• Other top-level JSON fields: ignored.
• ok is not required.

Receive Constraints

• Bytes, capacities, counters, and uptime are non-negative signed 64-bit JSON integers.
• Process and connection counts use signed 32-bit ranges.
• Static report interval uses signed 32-bit range; CPU topology counts use signed 16-bit range.
• Out-of-range JSON integers return 400 invalid_request; negative values or invalid ratios/rates return 422 invalid_metrics or 422 invalid_static_payload.
• Node version is limited to 64 characters; hostname and disk names to 255; disk ref to 320; disk kind/role and RAID health to 16; interface names to 64; filesystem type and logical health/level to 32.
• Static OS/platform/arch is limited to 32 characters; platform/kernel version to 255. Paths, mount points, and hardware descriptions are text columns.

Concurrent reports use server receive order for the current projection. An older receive that finishes later still enters history but cannot overwrite current metrics, frontend cache, or newer alert evaluation. Node timestamp does not select the current projection.

HTTPS Fallback

By default, HTTPS targets can fall back to HTTP according to client rules. This covers misconfiguration, IP access, certificate errors, and similar cases.

With --require-https:

• Non-HTTPS targets are rejected.
• HTTP fallback is disabled.

Node Update

Only managed install layouts process update manifests:

• Windows: started by runner with ITHILTIR_NODE_RUNNER=1.
• Linux/macOS: current process is /var/lib/ithiltir-node/current/ithiltir-node or /var/lib/ithiltir-node/releases/<version>/ithiltir-node.

Direct binaries outside the managed install layout ignore update manifests.

Automatic update delivery from the Dash admin console applies only to nodes currently reporting 0.2.3 or later. Older versions must be updated manually.

Manifest requirements:

• version is non-empty, not . or .., and contains no path separators.
• url is an absolute HTTP or HTTPS URL with a host.
• sha256 is a 64-character SHA-256 hex digest.
• size is positive and must equal the downloaded byte count.

Manifests matching the currently reported version are ignored first. If multiple remaining targets return update manifests in one cycle, id, version, url, sha256, and size must match exactly. Otherwise the update is skipped.

Dash clears the pending upgrade task after the node reports the exact target version or a higher SemVer precedence. Different build metadata at the same SemVer precedence is treated as a distinct node binary and can still be delivered.

After a successful update, Windows runner replaces %ProgramData%\Ithiltir-node\bin\ithiltir-node.exe. Linux/macOS atomically switches /var/lib/ithiltir-node/current, then the existing runtime manager restarts Node.