Flows and dashboards are created by POST under an issued or superuser-pinned id; PUT only updates; deleted flows leave a tombstone with their key; the controller stores by id and runs by key, hooks live under /hooks/<flow id>; a key with state or queued work behind it is refused until cleared

This commit is contained in:
2026-11-02 17:41:23 +01:00
parent fae85f5ecb
commit 08a6376836
63 changed files with 2832 additions and 936 deletions
+92 -40
View File
@@ -72,6 +72,7 @@ from fluksio.flow.pipeline import (
ValueSource,
)
from fluksio.flow.placement import Placer
from fluksio.flow.queue import WorkItem, owned_by
from fluksio.flow.remote import RemoteWorkerHub
from fluksio.flow.resources import (
ResourceAccountant,
@@ -160,7 +161,10 @@ class LoadedNode:
"""
id: str
#: The flow's key, which ``id`` is qualified with.
flow: str
#: The flow's id, which its store paths and API routes use.
flow_id: str = ""
status: NodeStatus = NodeStatus.ACTIVE
node: Node | None = None
error: str | None = None
@@ -556,6 +560,9 @@ class FlowController:
self.disabled: set[str] = set()
#: Flows that only run when a run asks them to.
self.batch: set[str] = set()
#: The key each built flow runs under, by its id. What a rebuild of a
#: flow that is gone takes out, since its document can no longer say.
self._flow_keys: dict[str, str] = {}
#: Each flow's declared inputs, kept so rebuilding one flow can
#: validate the whole graph without re-reading every flow off the disk.
self._flow_inputs: dict[str, dict[str, bool]] = {}
@@ -642,15 +649,16 @@ class FlowController:
entry.last_error_ts = None
entry.failures_in_a_row = 0
async def set_enabled(self, flow: str, enabled: bool) -> None:
async def set_enabled(self, flow_id: str, flow: str, enabled: bool) -> None:
"""Stop or start one flow, without building anything.
Its nodes are built whether or not it runs — being stopped means
having no subscriptions, schedules or webhooks, not being absent — so
all this has to do is the lifecycle call and the gate that goes with
it. Nothing is compiled and no other flow is touched.
it. Nothing is compiled and no other flow is touched. *flow_id* is
where that is stored, *flow* the key the gate goes by.
"""
await run_in_threadpool(self.store.write_enabled, flow, enabled)
await run_in_threadpool(self.store.write_enabled, flow_id, enabled)
if self.pipeline is None:
# Nothing built yet, so there are no nodes to start or stop.
await self.reload()
@@ -726,10 +734,9 @@ class FlowController:
self.supervisor = Supervisor(self.events)
published = self.store.read_all()
self._flow_keys = {flow.id: flow.name for flow in published}
self.disabled = {
flow.name
for flow in published
if not self.store.read_enabled(flow.name)
flow.name for flow in published if not self.store.read_enabled(flow.id)
}
# A batch flow is built — the canvas draws it and validation covers
# it — but never activated: it runs when a run asks it to, and a
@@ -795,7 +802,7 @@ class FlowController:
self._rewired()
async def reload_flow(
self, name: str, wait: float | None = FLOW_REBUILD_WAIT
self, flow_id: str, wait: float | None = FLOW_REBUILD_WAIT
) -> None:
"""Rebuild one flow, leaving every other flow's nodes connected.
@@ -806,7 +813,8 @@ class FlowController:
on a populated instance is every node opening its socket again,
and only one flow's have changed.
A flow the store no longer has is taken out instead of replaced.
A flow the store no longer has is taken out instead of replaced. The
flow is named by its id; everything about running it goes by its key.
The failure shape is the whole-pipeline one narrowed to a flow, and
deliberately no better: a build that raises changes nothing, and
@@ -826,11 +834,14 @@ class FlowController:
# flow is not running is its own teardown and nothing more. Off
# the loop for the same reason the full build is: compiling a
# python node waits for a worker slot.
built = await run_in_threadpool(self._build_one, name)
built = await run_in_threadpool(self._build_one, flow_id)
# A flow never built has nothing to take out, so no key either.
name = built[0].name if built else self._flow_keys.pop(flow_id, "")
await self._teardown(name)
if built is None:
pipeline.remove_flow(name)
if name:
pipeline.remove_flow(name)
self.loaded = {
node_id: entry
for node_id, entry in self.loaded.items()
@@ -843,6 +854,7 @@ class FlowController:
self.batch = self.batch - {name}
else:
flow, nodes, loaded, initial_values, enabled = built
self._flow_keys[flow_id] = name
pipeline.replace_flow(name, nodes, initial_values)
# A rebuild is a fresh set of nodes, but not a fresh history:
@@ -953,7 +965,7 @@ class FlowController:
"""
broken = sorted(
{
entry.flow
entry.flow_id
for entry in self.loaded.values()
if entry.status is NodeStatus.ERROR
}
@@ -963,7 +975,10 @@ class FlowController:
return broken
async def reload_lib_users(self, ref: str) -> list[str]:
"""Rebuild the flows running a shared node whose source has changed."""
"""Rebuild the flows running a shared node whose source has changed.
Returns their ids, which is what `usages` qualifies with.
"""
usages = self.store.usages(ref, draft=False)
flows = sorted({usage.split(".", 1)[0] for usage in usages})
for flow in flows:
@@ -971,18 +986,18 @@ class FlowController:
return flows
def _build_one(
self, name: str
self, flow_id: str
) -> tuple[FlowDef, list[Node], dict[str, LoadedNode], dict[str, Any], bool] | None:
"""Read one published flow and build its nodes. None when it is gone.
Blocking: this is the part of a rebuild that talks to the worker pool.
"""
try:
flow = self.store.read_flow(name)
flow = self.store.read_flow(flow_id)
except FlowNotFound:
return None
nodes, loaded, initial_values, _ = self._build_flows([(flow, False)])
return flow, nodes, loaded, initial_values, self.store.read_enabled(name)
return flow, nodes, loaded, initial_values, self.store.read_enabled(flow_id)
def _all_flow_inputs(self) -> dict[str, bool]:
"""Every flow's declared inputs, merged the way one build would see them.
@@ -1145,7 +1160,7 @@ class FlowController:
for flow, draft in flows:
for node_def in flow.nodes:
entry = self._build_node(flow.name, node_def, draft=draft, run=run)
entry = self._build_node(flow, node_def, draft=draft, run=run)
loaded[entry.id] = entry
if entry.node is not None:
nodes.append(entry.node)
@@ -1157,13 +1172,16 @@ class FlowController:
def _build_node(
self,
flow: str,
flow_def: FlowDef,
node_def: NodeDef,
draft: bool = False,
run: RunContext | None = None,
) -> LoadedNode:
"""One node of *flow_def*: its code read by the flow's id, and run,
named and wired by its key."""
flow, flow_id = flow_def.name, flow_def.id
node_id = f"{flow}.{node_def.id}"
entry = LoadedNode(id=node_id, flow=flow)
entry = LoadedNode(id=node_id, flow=flow, flow_id=flow_id)
try:
node_type = NODE_TYPES.get(node_def.type)
if node_type is None:
@@ -1192,19 +1210,21 @@ class FlowController:
code = self.store.read_lib_source(node_def.source_ref)
else:
owner, local = flow, node_def.id
code = self.store.read_node_source(flow, node_def.id, draft=draft)
code = self.store.read_node_source(
flow_id, node_def.id, draft=draft
)
# The store answers the new-node template when nothing was
# written, which is what an editor should open with and not
# something to run. A draft legitimately has none yet.
entry.missing_source = not draft and not self.store.has_node_source(
flow, node_def.id
flow_id, node_def.id
)
# Only a body somebody wrote: the template a new node opens
# with takes nothing, and a node declared before it is written
# is reported as missing its source rather than as wrong.
written = bool(node_def.source_ref) or self.store.has_node_source(
flow, node_def.id, draft=draft
flow_id, node_def.id, draft=draft
)
if written:
gap = _signature_gap(
@@ -1376,8 +1396,10 @@ class FlowController:
node._on_health = self._health_changed
if _is_hook(node):
# Hooks live under their flow, away from the JSON API.
node.url = f"{HOOK_PREFIX}/{flow}/{node.url.lstrip('/')}"
# Hooks live under their flow, away from the JSON API: under
# its id, so a URL handed out keeps working when the key
# changes.
node.url = f"{HOOK_PREFIX}/{flow_id}/{node.url.lstrip('/')}"
entry.node = node
except (SecretNotFound, LibNotFound) as exc:
@@ -1493,7 +1515,7 @@ class FlowController:
issue for issue in self.issues if not issue.flow or issue.flow == flow
] + self._health_issues(flow)
def preview(self, name: str) -> Preview:
def preview(self, flow_id: str) -> Preview:
"""Build a flow's unpublished draft without deploying it.
The draft stands in for its published self among the other flows, so
@@ -1501,13 +1523,15 @@ class FlowController:
graph is thrown away afterwards and seeded into a throwaway state, so
nothing here touches what is running.
"""
flows: list[tuple[FlowDef, bool]] = [
(flow, False) for flow in self.store.read_all() if flow.name != name
]
try:
flows.append((self.store.read_flow(name, draft=True), True))
draft = self.store.read_flow(flow_id, draft=True)
except FlowNotFound:
return Preview(nodes=[], issues=[])
name = draft.name
flows: list[tuple[FlowDef, bool]] = [
(flow, False) for flow in self.store.read_all() if flow.id != flow_id
]
flows.append((draft, True))
nodes, loaded, initial_values, flow_inputs = self._build_flows(flows)
pipeline = Pipeline(
@@ -1856,21 +1880,35 @@ class FlowController:
return self.execution.stats() if self.execution is not None else {}
def forget_flow(self, flow: str) -> None:
"""Drop what a deleted flow left behind. Blocking."""
"""Drop what a deleted flow left behind, by its key. Blocking.
After its nodes are torn down, or they put some of it straight back.
"""
if self.execution is not None:
self.execution.queue.clear_flow(flow)
prefix = f"{flow}."
with self.state.lock():
stale = [
key
for key in self.state.keys()
# Both the messages themselves and the engine's own bookkeeping
# about them, which is keyed by message name too.
if key.startswith(prefix) or f":{prefix}" in key
]
for key in stale:
for key in [k for k in self.state.keys() if _in_namespace(k, flow)]:
self.state.delete(key)
def key_residue(self, flow: str) -> list[str]:
"""What still lives under the flow key *flow*. Blocking.
State and live queue work in its namespace: left by a flow that held
the key before, or put there by anything still writing to it. A new
flow taking the key would inherit it, so creating one is refused while
this is not empty, and so is renaming a flow onto it. Work that was
acknowledged, dead-lettered or marked done is history and not counted.
Names what it found, state keys first.
"""
found = [key for key in self.state.keys() if _in_namespace(key, flow)]
if self.execution is not None:
found += [
f"queued work of '{item.node}'"
for item in self.execution.queue.live_items()
if _touches(item, flow)
]
return found
def run_flow(self, flow: str, inputs: dict[str, Any] | None = None) -> None:
"""Run every node of one flow. Blocking — call from a worker thread."""
if self.pipeline is None:
@@ -1912,7 +1950,7 @@ class FlowController:
pipeline.history_limits = self.history_limits
return pipeline
def run_preview(self, flow_name: str, inputs: dict[str, Any] | None = None) -> None:
def run_preview(self, flow_id: str, inputs: dict[str, Any] | None = None) -> None:
"""Run a flow's unpublished draft once, as the editor shows it.
The nodes are built and run but never activated, so a draft never
@@ -1920,7 +1958,7 @@ class FlowController:
that. State and events are the live ones, so values land on the canvas
exactly as they do for a published run.
"""
flow = self.store.read_flow(flow_name, draft=True)
flow = self.store.read_flow(flow_id, draft=True)
nodes, _, initial_values, _ = self._build_flows([(flow, True)])
pipeline = Pipeline(
nodes=nodes,
@@ -1960,6 +1998,20 @@ class FlowController:
self.events.publish(event)
def _in_namespace(state_key: str, flow: str) -> bool:
"""Whether a state key is about the flow key *flow*: one of its messages,
or the engine's own bookkeeping on one of its messages or nodes, which is
keyed by those names too."""
prefix = f"{flow}."
return state_key.startswith(prefix) or f":{prefix}" in state_key
def _touches(item: WorkItem, flow: str) -> bool:
"""Whether a queued item names anything of the flow key *flow*: as its
flow, its node or one of the messages it carries."""
return owned_by(item, flow) or any(flow_of(name) == flow for name in item.outputs)
def _bound(specs: list[MessageSpec]) -> list[MessageSpec]:
"""Ports without a message name are not wired into the graph."""
return [spec for spec in specs if spec.name]