Clients take a flow's id or key: one resolver in the SDK, id first, explicit id:/key:, a warning for reads and a refusal for changes when a name means two flows, deleted flows found by their last key; sync creates by POST, retries a create race through the drift checks and reports the id; MCP gets create_flow and resolves every flow argument with the caller's token; displays show flow_name; an engine from before ids is named as such

This commit is contained in:
2026-11-02 19:39:14 +01:00
parent fd637e0f1e
commit 53916d869b
20 changed files with 816 additions and 147 deletions
+64
View File
@@ -213,6 +213,70 @@ def test_sync_refuses_a_flow_it_did_not_create(api, flows):
theirs.name = "train"
def test_two_first_syncs_of_one_key_end_with_one_flow(api, flows):
"""The second looked before the first had created the flow.
Its create is refused for the key, so it looks again and updates the
first one's flow, checked first as any stored flow is: a canvas edit made
in between is refused rather than overwritten.
"""
class Late(Client):
looked = False
def find_flow(self, key):
if self.looked:
return super().find_flow(key)
# What it saw before the other sync created the flow.
self.looked = True
return None
target = flows["train"]
target.name = "raced"
try:
first = sync([target], api, origin=ORIGIN)[0]
second = sync([target], Late(http=api.http, token=api.token), origin=ORIGIN)[0]
assert first.created and not second.created
assert second.id == first.id
assert [f["id"] for f in api.flows() if f["name"] == "raced"] == [first.id]
api.put_source(first.id, "fit", "def process(dataset, lr):\n return {}\n")
with pytest.raises(SyncError, match="edited on the canvas"):
sync([target], Late(http=api.http, token=api.token), origin=ORIGIN)
finally:
target.name = "train"
found = api.find_flow("raced")
if found:
api.http.delete(f"{PREFIX}/flows/{found['id']}")
def test_a_synced_flow_is_addressed_by_its_key_under_an_issued_id(api, flows):
"""The id is the engine's own, opaque; the client takes the key and
sends the id, and the history answers with both."""
report = sync([flows["train"]], api, origin=ORIGIN)[0]
train = flow_id(api, "train")
assert report.id == train
assert train != "train" and train.startswith("f_")
[made] = api.import_runs(
[
{
"flow": "train",
"external_id": "elsewhere:1",
"params": {"lr": 0.05},
"created_at": "2026-03-01T10:00:00Z",
"result": {"score": 0.9},
}
]
)
rows = api.runs(flow="train")
assert made["id"] in {row["id"] for row in rows}
assert {(row["flow"], row["flow_name"]) for row in rows} == {(train, "train")}
exported = api.export_runs(flow="train")
assert {(row["flow"], row["flow_name"]) for row in exported} == {(train, "train")}
def test_use_stores_the_rewiring_it_was_given(api, flows):
sync([flows["finetune"]], api, origin=ORIGIN)
+12 -2
View File
@@ -264,6 +264,13 @@ def test_an_agent_cannot_write_code_its_person_may_not(
).json()
assert me["is_superuser"] is False
token = mcp_token(uuid.UUID(me["id"]), agent)
# One they may create: the tool only reaches the route for a listed flow.
flows = f"{settings.API_V1_STR}/flows"
made = client.post(
f"{flows}/", headers=normal_user_token_headers, json={"name": "agent_gate"}
)
assert made.status_code == 201, made.text
flow_id = made.json()["definition"]["id"]
async def block(http: httpx.AsyncClient) -> httpx.Response:
return await http.post(
@@ -272,11 +279,14 @@ def test_an_agent_cannot_write_code_its_person_may_not(
token,
"tools/call",
name="save_node_source",
arguments={"name": "any", "node_id": "fn", "code": "import os"},
arguments={"flow": "agent_gate", "node_id": "fn", "code": "import os"},
),
)
answer = json.loads(over_mcp(block).json()["result"]["content"][0]["text"])
try:
answer = json.loads(over_mcp(block).json()["result"]["content"][0]["text"])
finally:
client.delete(f"{flows}/{flow_id}", headers=normal_user_token_headers)
assert answer == {"error": CODE_IS_SUPERUSERS, "status": 403}
+55 -13
View File
@@ -6,38 +6,80 @@ import httpx
from fluksio.mcp import server
#: What the engine lists: the grandfathered `heating`, now keyed `warmth`, and
#: the later flow that took its old key.
LISTED = [{"id": "heating", "name": "warmth"}, {"id": "f_heat0000", "name": "heating"}]
def test_a_name_cannot_climb_out_of_its_route() -> None:
"""httpx resolves ``..``, so ``save_flow("../ai/config")`` was ``PUT /ai/config``.
A prompt-injected assistant acting for a superuser could repoint the
provider that way while the stored key stayed.
"""
def _calls(*tools) -> list[str]:
"""What the tools sent past the flow listing, run against a recording
engine."""
seen: list[str] = []
def record(request: httpx.Request) -> httpx.Response:
if request.url.path == "/api/v1/flows/" and request.method == "GET":
return httpx.Response(200, json={"data": LISTED, "count": len(LISTED)})
seen.append(f"{request.method} {request.url.raw_path.decode()}")
return httpx.Response(200, json={})
async def calls() -> None:
async def calls() -> list:
previous = server._client
mock = httpx.AsyncClient(
transport=httpx.MockTransport(record), base_url="http://test"
)
server.set_client(mock)
try:
await server.save_flow("../ai/config", {})
await server.delete_flow("..")
await server.get_node_source("..", "../source")
return [await tool() for tool in tools]
finally:
server.set_client(previous)
await mock.aclose()
asyncio.run(calls())
answers = asyncio.run(calls())
return seen + [answer for answer in answers if answer != {}]
def test_a_name_cannot_climb_out_of_its_route() -> None:
"""httpx resolves ``..``, so ``save_flow("../ai/config")`` was ``PUT /ai/config``.
A prompt-injected assistant acting for a superuser could repoint the
provider that way while the stored key stayed. A flow is now only ever a
listed one, and what follows it is still one segment.
"""
seen = _calls(
lambda: server.save_flow("../ai/config", {}),
lambda: server.get_node_source("f_heat0000", "../source"),
)
assert seen == [
"PUT /api/v1/flows/%2E%2E%2Fai%2Fconfig",
"DELETE /api/v1/flows/%2E%2E",
"GET /api/v1/flows/%2E%2E/nodes/%2E%2E%2Fsource/source",
"GET /api/v1/flows/f_heat0000/nodes/%2E%2E%2Fsource/source",
{"error": "No flow with the id or key '../ai/config'."},
]
def test_a_flow_argument_goes_through_the_resolver() -> None:
"""Id first; a read of a name two flows answer to says so, a change of
it is refused, and the explicit forms say which."""
seen = _calls(
lambda: server.get_flow("heating"),
lambda: server.delete_flow("heating"),
lambda: server.delete_flow("key:heating"),
lambda: server.get_flow("warmth"),
)
warning = (
"'heating' is the id of 'warmth' and the key of 'f_heat0000'. "
"Using the id. Pass key:heating for the other."
)
refusal = (
"'heating' is the id of 'warmth' and the key of 'f_heat0000'. "
"Pass id:heating or key:heating."
)
assert seen == [
"GET /api/v1/flows/heating",
"DELETE /api/v1/flows/f_heat0000",
"GET /api/v1/flows/heating",
{"warning": warning},
{"error": refusal},
]
+71 -1
View File
@@ -3,7 +3,26 @@
import httpx
import pytest
from fluksio.sdk import SyncError
from fluksio.sdk.client import WAIT_TOLERANCE, ApiError, Client, RunHandle
from fluksio.sdk.resolve import Unresolved
#: What the engine lists: `train` under an issued id, and the grandfathered
#: `heating`, now keyed `warmth`, whose old key a later flow took.
LISTED = [
{"id": "f_train000", "name": "train"},
{"id": "heating", "name": "warmth"},
{"id": "f_heat0000", "name": "heating"},
]
def listing(request):
"""The engine's answer to the lookups a flow argument costs, else None."""
if request.url.path == "/api/v1/flows/":
return httpx.Response(200, json={"data": LISTED, "count": len(LISTED)})
if request.url.path == "/api/v1/runs/overview":
return httpx.Response(200, json=[])
return None
def a_client(handler, monkeypatch, **kwargs):
@@ -65,6 +84,9 @@ def test_submit_carries_one_key_across_its_retries(monkeypatch):
bodies = []
def handler(request):
if listed := listing(request):
return listed
assert request.url.path == "/api/v1/runs/flows/f_train000"
bodies.append(httpx.Response(200, content=request.content).json())
if len(bodies) < 3:
raise httpx.ConnectError("no route", request=request)
@@ -81,6 +103,8 @@ def test_a_sweep_keys_every_entry(monkeypatch):
seen = {}
def handler(request):
if listed := listing(request):
return listed
body = httpx.Response(200, content=request.content).json()
seen["runs"] = body["runs"]
return httpx.Response(202, json=[{"id": "r1"}, {"id": "r2"}])
@@ -137,6 +161,8 @@ def test_an_export_is_read_as_rows(monkeypatch):
seen = {}
def handler(request):
if listed := listing(request):
return listed
seen.update(request.url.params)
return httpx.Response(
200,
@@ -149,7 +175,8 @@ def test_an_export_is_read_as_rows(monkeypatch):
assert seen["format"] == "jsonl"
assert seen["ids"] == "r1,r2"
assert seen["flow"] == "train"
# The key, resolved: the API takes the id and only the id.
assert seen["flow"] == "f_train000"
assert seen["status"] == "ok"
assert [row["step"] for row in rows] == [0, 1]
@@ -201,3 +228,46 @@ def test_a_name_cannot_climb_out_of_its_route(monkeypatch):
"/api/v1/flows/%2E%2E/nodes/%2E%2E%2Fx/source",
"/api/v1/runs/%2E%2E",
]
def test_a_flow_argument_goes_through_the_resolver(monkeypatch):
"""A read of a name two flows answer to warns; a run of it is refused."""
asked = []
def handler(request):
if listed := listing(request):
return listed
asked.append(
f"{request.method} {request.url.path}?{request.url.query.decode()}"
)
return httpx.Response(200, json=[])
client = a_client(handler, monkeypatch)
with pytest.warns(UserWarning, match="Pass key:heating for the other"):
client.runs(flow="heating")
with pytest.raises(Unresolved, match="Pass id:heating or key:heating"):
client.submit("heating")
client.runs(flow="key:heating")
assert asked == [
"GET /api/v1/runs?limit=20&flow=heating",
"GET /api/v1/runs?limit=20&flow=f_heat0000",
]
def test_an_engine_from_before_ids_is_named_as_such(monkeypatch):
"""It lists flows without ids and has no route to create one by."""
def handler(request):
if request.method == "POST":
return httpx.Response(405, json={"detail": "Method Not Allowed"})
return httpx.Response(200, json={"data": [{"name": "train"}], "count": 1})
client = a_client(handler, monkeypatch)
for call in (
lambda: client.runs(flow="train"),
lambda: client.find_flow("train"),
lambda: client.create_flow({"name": "train"}),
):
with pytest.raises(SyncError, match="older than flow ids"):
call()
+4
View File
@@ -8,6 +8,7 @@ import pytest
from fluksio.sdk import FLOWS, SyncError, cli
from fluksio.sdk.declare import ImportFailed, declare, declare_module
from fluksio.sdk.resolve import Resolved
STUDY = """\
import os
@@ -131,6 +132,9 @@ def test_a_failing_import_is_reported_by_sync_and_warned_about_by_run(
assert "Traceback" in seen.err and "study.py" in seen.err
class Engine:
def resolve_flow(self, flow, **how):
return Resolved(flow, flow)
def get_flow(self, name):
return {
"definition": {"origin": {"declared_in": "study.py", "module": "study"}}
+74
View File
@@ -0,0 +1,74 @@
"""Which flow an argument names: the one matrix every client relies on."""
import pytest
from fluksio.sdk.resolve import Resolved, Unresolved, resolve
#: `heating` is the grandfathered id of the flow now keyed `warmth`; a later
#: flow took the key `heating` under an issued id.
FLOWS = [
("heating", "warmth"),
("f_k3q7m2xa", "heating"),
("train", "train"),
("f_aaaaaaaa", "lights"),
]
def test_an_id_alone_picks_its_flow():
assert resolve("f_aaaaaaaa", FLOWS) == Resolved("f_aaaaaaaa", "lights")
def test_a_key_alone_picks_its_flow():
assert resolve("lights", FLOWS) == Resolved("f_aaaaaaaa", "lights")
def test_an_id_that_is_its_own_key_is_no_ambiguity():
assert resolve("train", FLOWS, mutation=True) == Resolved("train", "train")
def test_one_flows_id_and_anothers_key_reads_the_id_with_a_warning():
found = resolve("heating", FLOWS)
assert (found.id, found.key) == ("heating", "warmth")
assert found.warning == (
"'heating' is the id of 'warmth' and the key of 'f_k3q7m2xa'. "
"Using the id. Pass key:heating for the other."
)
def test_a_change_refuses_a_name_two_flows_answer_to():
with pytest.raises(Unresolved, match="Pass id:heating or key:heating"):
resolve("heating", FLOWS, mutation=True)
def test_the_explicit_forms_say_which():
assert resolve("id:heating", FLOWS, mutation=True) == Resolved("heating", "warmth")
assert resolve("key:heating", FLOWS, mutation=True) == Resolved(
"f_k3q7m2xa", "heating"
)
def test_neither_names_the_closest_keys():
with pytest.raises(Unresolved) as caught:
resolve("lihgts", FLOWS)
assert str(caught.value) == (
"No flow with the id or key 'lihgts'. Closest keys: lights."
)
with pytest.raises(Unresolved, match="No flow with the key 'f_aaaaaaaa'"):
resolve("key:f_aaaaaaaa", FLOWS)
def test_an_explicit_id_outlives_its_flow():
"""History stays filed under a deleted flow's id, which nobody lists."""
assert resolve("id:f_gone0000", FLOWS) == Resolved("f_gone0000", "")
def test_a_key_history_holds_twice_is_refused_not_guessed():
"""A deleted flow and the later one that took its key."""
history = [("f_old00000", "train"), ("f_new00000", "train")]
for value in ("train", "key:train"):
with pytest.raises(Unresolved, match="f_old00000, f_new00000"):
resolve(value, history)
assert resolve("id:f_old00000", history) == Resolved("f_old00000", "train")
+62 -1
View File
@@ -7,6 +7,7 @@ from pathlib import Path
import pytest
from fluksio.cli import load_or_create_secret_key
from fluksio.sdk.resolve import Resolved
def test_importing_the_cli_does_not_build_the_settings() -> None:
@@ -242,6 +243,9 @@ def test_a_local_run_always_waits(monkeypatch) -> None:
return self
class FakeClient:
def resolve_flow(self, flow: str, **how: bool) -> Resolved:
return Resolved(flow, flow)
def get_flow(self, name: str) -> dict[str, object]:
return {"definition": {"inputs": []}}
@@ -264,7 +268,8 @@ def test_a_local_run_always_waits(monkeypatch) -> None:
assert cli.cmd_run(args, []) == 0
# "cli" rather than the SDK's default: the history says which asked.
assert submitted == {
"flow": "train",
# Resolved once, then named by id so the submit does not ask again.
"flow": "id:train",
"no_cache": True,
"waited": True,
"cause": "cli",
@@ -289,6 +294,9 @@ def test_ctrl_c_while_waiting_cancels_the_run(monkeypatch) -> None:
raise KeyboardInterrupt
class FakeClient:
def resolve_flow(self, flow: str, **how: bool) -> Resolved:
return Resolved(flow, flow)
def get_flow(self, name: str) -> dict[str, object]:
return {"definition": {"inputs": []}}
@@ -429,6 +437,9 @@ def test_a_failed_run_prints_what_each_node_said(monkeypatch, capsys) -> None:
return self
class FakeClient:
def resolve_flow(self, flow: str, **how: bool) -> Resolved:
return Resolved(flow, flow)
def get_flow(self, name: str) -> dict[str, object]:
return {"definition": {"inputs": []}}
@@ -699,6 +710,9 @@ def test_run_imports_the_module_that_declared_the_flow(tmp_path, monkeypatch):
class Engine:
origin: dict = {}
def resolve_flow(self, flow, **how):
return Resolved(flow, flow)
def get_flow(self, name):
return {"definition": {"origin": self.origin}}
@@ -1196,3 +1210,50 @@ def test_the_dashboard_subscribes_where_the_browser_does() -> None:
assert socket_url("http://127.0.0.1:8000") == "ws://127.0.0.1:8000/api/v1/flows/ws"
# TLS on the one side is TLS on the other.
assert socket_url("https://engine.example.com").startswith("wss://")
def test_a_flow_argument_goes_through_the_resolver(monkeypatch, capsys) -> None:
"""A run of a name two flows answer to is refused; a listing warns."""
from contextlib import contextmanager
import httpx
from fluksio.cli import _parser
from fluksio.sdk import cli
from fluksio.sdk.client import Client
listed = [
{"id": "heating", "name": "warmth"},
{"id": "f_heat0000", "name": "heating"},
]
asked: list[str] = []
def handler(request: httpx.Request) -> httpx.Response:
if request.url.path == "/api/v1/flows/":
return httpx.Response(200, json={"data": listed, "count": 2})
if request.url.path == "/api/v1/runs/overview":
return httpx.Response(200, json=[])
asked.append(f"{request.url.path}?{request.url.query.decode()}")
return httpx.Response(200, json=[])
@contextmanager
def engine():
http = httpx.Client(transport=httpx.MockTransport(handler), base_url="http://e")
yield Client(http=http, token="t")
monkeypatch.setattr(cli, "_engine_client", engine)
parser = _parser()
run = parser.parse_args(["run", "heating", "--local", "--no-sync"])
assert cli.cmd_run(run, []) == 1
assert "Pass id:heating or key:heating" in capsys.readouterr().err
assert asked == []
assert (
cli.cmd_runs(parser.parse_args(["runs", "--flow", "heating", "--local"])) == 0
)
assert (
"fluksio: warning: 'heating' is the id of 'warmth' and the key of "
"'f_heat0000'. Using the id. Pass key:heating for the other.\n"
) in capsys.readouterr().err
assert asked == ["/api/v1/runs?limit=20&flow=heating"]