Control-plane endpoint consulted by Auto routing on every SQL call. Takes the current workspace/session context and returns a ranked list of healthy compute nodes. Consistent with the GUI's node selection.
GET /nodes/recommend?workspace=<w>&session=<s>## Overview `/nodes/recommend` is the control plane endpoint that powers Auto routing. Given the current workspace and session context, it returns a ranked list of healthy compute nodes. The CLI, the GUI, and the VS Code extension all call the same endpoint, which is what keeps node selection consistent across every DeltaForge client surface. ## Behavior - Called by the CLI on every SQL statement while Auto routing is active. The top-ranked entry's URL is used for that statement. - Ranking inputs include node health, current load, declared capabilities, workspace affinity, and active reservations. The ordering can change between consecutive calls. - Only healthy nodes are returned; nodes that have failed their heartbeat or are draining are excluded before ranking. - The endpoint is skipped entirely when the CLI is in explicit-URL mode (`--compute-url`, `DF_COMPUTE_URL`, or a profile `compute_url`) and when a `/use-node` pin is active. - Callers pass the active workspace identifier so that workspace-scoped reservations and affinity rules can be applied. ## Compatibility - Behaviour is identical across CLI, GUI, and VS Code extension. A node that the GUI considers the best choice is the node the CLI will also select under Auto routing at the same instant. - The endpoint is part of the control plane HTTP API and is not reachable directly from compute workers.
# Implicit, issued by the CLI under Auto routing
GET /nodes/recommend?workspace=analytics&session=cli-4c2f# Response shape (top node is selected for the statement)
{
"nodes": [
{ "name": "prod-worker-01", "url": "http://worker-01:3031", "score": 0.92 },
{ "name": "prod-worker-02", "url": "http://worker-02:3031", "score": 0.81 }
]
}