Device node: a device's ports are wired in flows

- flow/nodes/device.py: `device` node with params `device` and `config`;
  provides the device's `in` ports, requires its `out` ports without
  waking anything, never run (Node.passive), down "Offline" from presence
- DeviceDef.io and DevicePort go; GET /devices/{id} computes `io` and
  `bindings` from the device nodes of published flows, in a fixed order,
  cached by FlowStore.revision; the credential's scope comes from them
- issues `unknown_device` and `device_port` (wired twice; against a report
  the wrong direction or dtype, or unlisted as advisory), rechecked when a
  device is created or deleted; ValidationIssue.advisory is a field
- a device publishing on a bound port is credited to its node by the
  server; the panel endpoint kind is gone from `_endpoints` and the canvas
- a rebuild that moves a device's bindings sends `dashboard_changed` with
  an empty name, which the firmware refetches on
- startup moves each device's `io` rows into device nodes in the flows
  declaring their messages, draft and published, one commit; rows no
  flow declares are logged and left out
- frontend: Device node settings (device, Publishes, Follows, a port
  picker from a report), palette shortcuts per reported port, DeviceDetail
  lists bindings with "Use in flow" in place of the I/O editor
- docs: devices, flow editor, node types, issues, API
This commit is contained in:
Melvin Strobl
2026-10-16 16:40:31 +02:00
parent 91e3b703f9
commit 29d3ec467f
35 changed files with 2195 additions and 494 deletions
+150 -8
View File
@@ -22,6 +22,7 @@ import logging
import threading
import time
import traceback
from collections import Counter
from collections.abc import Callable
from contextlib import suppress
from dataclasses import dataclass, field
@@ -42,6 +43,7 @@ from fluksio.flow.nodes import (
ChangeNode,
DebounceNode,
DelayNode,
DeviceNode,
ExecNode,
FileNode,
HttpNode,
@@ -58,7 +60,6 @@ from fluksio.flow.nodes import (
WrenNode,
)
from fluksio.flow.pipeline import (
ADVISORY_ISSUES,
NodeOutcome,
Pipeline,
RunCacheLookup,
@@ -435,6 +436,12 @@ NODE_TYPES: dict[str, NodeType] = {
cls=NtfyNode,
params_schema=_schema_of(NtfyNode),
),
"device": NodeType(
title="Device",
description="A paired device's own ports: what it publishes, what it follows.",
cls=DeviceNode,
params_schema=_schema_of(DeviceNode),
),
}
@@ -492,9 +499,12 @@ class FlowController:
# Set by the lifespan once the store exists; the canvas asks the
# controller which dashboards are wired into a flow.
self.dashboards: Any = None
#: The device store, for the same reason: a device's own ports are
#: drawn on the canvas of the flow they wire into.
#: The device store, for the same reason: validation checks a device
#: node against the device it names.
self.devices: Any = None
#: Every device's bound ports as of the last build, so a rebuild that
#: moves them can tell the devices to read theirs again.
self._device_wiring: Any = None
self.pipeline: Pipeline | None = None
self.loaded: dict[str, LoadedNode] = {}
@@ -696,7 +706,9 @@ class FlowController:
self.pipeline.history_limits = self.history_limits
if self.execution is not None:
self.execution.bind(self.pipeline)
self.issues = _collect_issues(loaded, self.pipeline, flow_inputs)
self.issues = _collect_issues(
loaded, self.pipeline, flow_inputs, self.devices
)
await self._activate()
@@ -718,6 +730,7 @@ class FlowController:
"paused": self.paused_flows(),
}
)
self._rewired()
async def reload_flow(
self, name: str, wait: float | None = FLOW_REBUILD_WAIT
@@ -800,7 +813,7 @@ class FlowController:
# Over the whole graph, because it has to be: taking a producer out
# of one flow is what leaves another flow's input unconnected.
self.issues = _collect_issues(
self.loaded, pipeline, self._all_flow_inputs()
self.loaded, pipeline, self._all_flow_inputs(), self.devices
)
await self._activate(name)
@@ -821,6 +834,47 @@ class FlowController:
"paused": self.paused_flows(),
}
)
self._rewired()
async def recheck(self) -> None:
"""Validate the built graph again without rebuilding anything.
For what validation reads from outside the flows: a device created or
deleted changes whether a device node names one that exists.
"""
if self.pipeline is None:
return
await self._acquire(FLOW_REBUILD_WAIT)
try:
self.issues = _collect_issues(
self.loaded, self.pipeline, self._all_flow_inputs(), self.devices
)
finally:
self._lock.release()
self._publish(
{
"type": "pipeline_rebuilt",
"issues": [issue.model_dump() for issue in self.issues],
"nodes": [status.model_dump() for status in self.node_statuses()],
"paused": self.paused_flows(),
}
)
def _rewired(self) -> None:
"""Tell the devices when a rebuild moved what their ports are wired to.
An empty dashboard name is what a device refetches its own document
on, and what its socket rescopes on. The first build only takes note:
a device connecting later reads the document as it is.
"""
if self.devices is None:
return
wiring = self.devices.wiring()
known, self._device_wiring = self._device_wiring, wiring
if known is not None and known != wiring:
self._publish(
{"type": "dashboard_changed", "dashboard": "", "ts": time.time()}
)
async def reload_failed_flows(self) -> list[str]:
"""Rebuild only the flows holding a node that would not load.
@@ -1375,7 +1429,7 @@ class FlowController:
max_workers=self.max_workers,
initial_values=initial_values,
)
issues = _collect_issues(loaded, pipeline, flow_inputs)
issues = _collect_issues(loaded, pipeline, flow_inputs, self.devices)
return Preview(
nodes=[
NodeStatusPublic(
@@ -1591,7 +1645,7 @@ class FlowController:
# it, so all of them are marked rather than an arbitrary one.
troubled: dict[str, str] = {}
for issue in self.issues + self._health_issues():
if issue.code in ADVISORY_ISSUES:
if issue.advisory:
continue
for member in (*issue.nodes, *filter(None, [issue.node])):
troubled.setdefault(member, issue.message)
@@ -1983,9 +2037,10 @@ def _collect_issues(
loaded: dict[str, LoadedNode],
pipeline: Pipeline,
flow_inputs: dict[str, bool],
devices: Any = None,
) -> list[ValidationIssue]:
"""Everything wrong with a built graph, whether it is running or not."""
issues = pipeline.validate(flow_inputs)
issues = pipeline.validate(flow_inputs) + _device_issues(loaded, devices)
issues += [
ValidationIssue(
code="node_error",
@@ -2046,6 +2101,93 @@ def _collect_issues(
return issues
def _device_issues(
loaded: dict[str, LoadedNode], devices: Any
) -> list[ValidationIssue]:
"""Device nodes naming no device, and ports that cannot be what they say.
A port is wired to one message in one place, so one bound twice across
the graph is an error on each. Against a report, a port in the wrong
direction or of another dtype is an error too, and one the device does not
list is a warning: the device may know it all the same. Without a report
a port is the device's business and nothing is said about it.
"""
if devices is None:
return []
nodes = [
(entry, entry.node)
for entry in loaded.values()
if isinstance(entry.node, DeviceNode)
]
if not nodes:
return []
known = {device.id for device in devices.list()}
bound = Counter(
(node.cfg.device, spec.port)
for _, node in nodes
for spec in (*node.input_ports, *node.output_ports)
if spec.name
)
issues: list[ValidationIssue] = []
for entry, node in nodes:
device = node.cfg.device
if device not in known:
issues.append(
ValidationIssue(
code="unknown_device",
message=(
f"'{node.local_id}' names device '{device}', which does "
"not exist."
if device
else f"Pick the device '{node.local_id}' stands for."
),
flow=entry.flow,
node=entry.id,
)
)
continue
reported = devices.reported_ports(device)
for direction, specs in (("in", node.output_ports), ("out", node.input_ports)):
for spec in specs:
if not spec.name:
continue
problem, advisory = "", False
said = reported.get(spec.port) if reported is not None else None
if bound[(device, spec.port)] > 1:
problem = (
f"Port '{spec.port}' of '{device}' is wired more than "
"once. A port carries one message, in one flow."
)
elif reported is None:
pass
elif said is None:
problem = f"'{device}' does not report a port '{spec.port}'."
advisory = True
elif said.get("direction") and said["direction"] != direction:
problem = (
f"'{spec.port}' of '{device}' is an {said['direction']} "
f"port, wired here as {direction}."
)
elif said.get("dtype") and said["dtype"] != spec.dtype.value:
problem = (
f"'{spec.port}' of '{device}' carries {said['dtype']}, "
f"wired here to a {spec.dtype.value} message."
)
if problem:
issues.append(
ValidationIssue(
code="device_port",
message=problem,
flow=entry.flow,
node=entry.id,
port=spec.port,
message_name=spec.name,
advisory=advisory,
)
)
return issues
def _short_error(exc: Exception) -> str:
"""One line a node author can act on: what broke, and where in their code.