Panels become devices: per-device documents in the flow repo, a Devices tab

- flow/devices.py: DeviceDef in FLOWS_DIR/_devices/<id>.json, committed under
  the flow store's write lock, 409 on a stale version; nonces in DEVICES_FILE
  outside git; in-memory presence announced as device_status
- api/routes/devices.py: CRUD, pairing with an optional {name, board,
  firmware}, a pending list adopted without a code from the LAN only, unpair;
  /panels/pair, /panels/pair/{code} and GET /panels/{id} kept as aliases,
  PUT /panels/ gone
- _device_may replaces _panel_may, JWT claims unchanged
- panels.json moves into devices once at startup, then .migrated
- MCP list_devices, get_device; search category device
- Devices tab (list, detail with presence, pairing, ordered dashboards,
  touch, I/O), PanelsDialog removed, serialised optimistic saves
This commit is contained in:
Melvin Strobl
2026-10-16 15:48:36 +02:00
parent 3c0912a3fe
commit 28a565e501
56 changed files with 3539 additions and 2404 deletions
+96 -61
View File
@@ -15,10 +15,11 @@ from fluksio.cloud import enroll
from fluksio.core import security
from fluksio.core.config import settings
from fluksio.core.db import engine
from fluksio.flow import panels
from fluksio.flow import devices
from fluksio.flow.artifacts import is_reference
from fluksio.flow.controller import FlowController
from fluksio.flow.dashboards import DashboardDef, DashboardStore
from fluksio.flow.devices import DeviceDef, DeviceStore, presence
from fluksio.flow.workers import PythonWorkerPool
from fluksio.models import OAuthClient, TokenPayload, User, WorkerToken
@@ -40,35 +41,46 @@ TokenDep = Annotated[str, Depends(reusable_oauth2)]
#: literals; anything else is refused rather than guessed at.
_NOT_DRAFT = {"false", "0", "off", "f", "n", "no", ""}
#: The one route under a message name a panel reads.
#: The one route under a message name a device reads.
_HISTORY = "/history"
def _panel_for(payload: dict[str, Any]) -> panels.PanelDef:
"""The panel a credential names, if that credential still stands.
def _device_for(payload: dict[str, Any], app: Any) -> DeviceDef:
"""The device a credential names, if that credential still stands.
Two ways it stops standing. The panel was deleted, which revokes every
credential ever minted for it — read from disk on each call, so it takes
effect at once. Or the panel's nonce moved on, which revokes exactly one
screen's and leaves the panel, its dashboards and their arrangement alone.
Two ways it stops standing. The device was deleted, which revokes every
credential ever minted for it, read from disk on each call so it takes
effect at once. Or the device's nonce moved on, which revokes exactly one
screen's and leaves the device and its dashboards alone.
The nonce is only held against a credential this instance signed. One
the portal minted for a remote screen carries none — the portal names the
panel and nothing else — and is revoked at the hub instead.
The nonce is only held against a credential this instance signed. One the
portal minted for a remote screen carries none, the portal names the
device and nothing else, and is revoked at the hub instead.
The claim is still called ``panel``: tokens in circulation say it, and
nothing pairs again for a rename.
"""
panel = panels.find(str(payload.get("panel", "")))
if panel is None:
raise InvalidTokenError("This panel no longer exists")
if (
payload.get("aud") == security.PANEL_AUDIENCE
and int(payload.get("pnc") or 0) != panel.nonce
):
raise InvalidTokenError("This panel was paired with another device")
return panel
store: DeviceStore | None = (
getattr(app.state, "device_store", None) if app else None
)
if store is None:
raise InvalidTokenError("The device store is not running")
device = store.find(str(payload.get("panel", "")))
if device is None:
raise InvalidTokenError("This device no longer exists")
if payload.get("aud") == security.PANEL_AUDIENCE:
try:
nonce = store.nonce(device.id)
except (OSError, ValueError) as exc:
raise InvalidTokenError(f"The device nonces are unreadable: {exc}")
if int(payload.get("pnc") or 0) != nonce:
raise InvalidTokenError("This device was paired again")
presence.seen(device.id)
return device
def _panel_messages(panel_id: str, request: Request) -> set[str]:
"""Every message this panel's widgets read or write.
def _device_messages(device: DeviceDef, request: Request) -> set[str]:
"""Every message this device's widgets and ports read or write.
The same walk that bounds its socket, so the two surfaces a screen has
agree on what it is entitled to. No store means nothing resolves, which is
@@ -77,7 +89,7 @@ def _panel_messages(panel_id: str, request: Request) -> set[str]:
store: DashboardStore | None = getattr(request.app.state, "dashboard_store", None)
if store is None:
return set()
return panels.messages_for(panel_id, store)
return devices.messages_for(device, store)
def _locked(defn: DashboardDef, live: dict[str, Any]) -> bool:
@@ -96,8 +108,8 @@ def _locked(defn: DashboardDef, live: dict[str, Any]) -> bool:
return (setting.value if value is None else value) is True
def _panel_writable(panel_id: str, request: Request) -> set[str]:
"""The messages this panel may publish to.
def _device_writable(device: DeviceDef, request: Request) -> set[str]:
"""The messages this device may publish to.
What its dashboards' inputs target, which is narrower than what it may
read: a chart, a reading or a bound setting is something a screen shows,
@@ -109,7 +121,7 @@ def _panel_writable(panel_id: str, request: Request) -> set[str]:
that asked anyway. Not nothing, though: a querying chart publishes the
request it reads by, and a locked dashboard whose charts cannot ask goes
blank rather than read-only. That request is the exception
``panels.requests_of`` names.
``devices.requests_of`` names.
Union, exactly as the allowlist itself is: a message one dashboard on this
panel displays and another controls stays writable, because the unlocked
@@ -123,8 +135,8 @@ def _panel_writable(panel_id: str, request: Request) -> set[str]:
store: DashboardStore | None = getattr(request.app.state, "dashboard_store", None)
if store is None:
return set()
writable = panels.io_in(panel_id)
defns = panels.dashboards_for(panel_id, store)
writable = devices.io_in(device)
defns = devices.dashboards_for(device, store)
bound = sorted(
{s.message for d in defns if (s := d.settings.get("locked")) and s.message}
)
@@ -134,12 +146,14 @@ def _panel_writable(panel_id: str, request: Request) -> set[str]:
live = controller.state.get_present(bound) if bound and controller else {}
for defn in defns:
writable |= (
panels.requests_of(defn) if _locked(defn, live) else panels.targets_of(defn)
devices.requests_of(defn)
if _locked(defn, live)
else devices.targets_of(defn)
)
return writable
def _panel_digests(panel_id: str, request: Request) -> set[str]:
def _device_digests(device: DeviceDef, request: Request) -> set[str]:
"""The artifacts this panel's messages are pointing at right now.
A media tile fetches the bytes its message names, so the messages already
@@ -151,7 +165,7 @@ def _panel_digests(panel_id: str, request: Request) -> set[str]:
)
if controller is None:
return set()
names = _panel_messages(panel_id, request)
names = _device_messages(device, request)
if not names:
return set()
found: set[str] = set()
@@ -161,7 +175,7 @@ def _panel_digests(panel_id: str, request: Request) -> set[str]:
return found
def _panel_may(payload: dict[str, Any], request: Request) -> None:
def _device_may(payload: dict[str, Any], request: Request) -> None:
"""Refuse anything a wall panel has no business asking for.
A panel credential names the account that approved the pairing, so without
@@ -183,11 +197,11 @@ def _panel_may(payload: dict[str, Any], request: Request) -> None:
a panel to read every message it names and to publish to none of them but
the requests its own charts ask by.
# ponytail: the panel file and the published dashboards are re-read per
# request. Cache them behind the store's version if this shows up in a
# profile.
# ponytail: the device file, its nonce and the published dashboards are
# re-read per request. Cache them behind the store's revision if this
# shows up in a profile.
"""
panel = _panel_for(payload)
device = _device_for(payload, request.app)
api = settings.API_V1_STR
path = request.url.path
@@ -203,8 +217,12 @@ def _panel_may(payload: dict[str, Any], request: Request) -> None:
# fail-closed, so a spelling neither side recognises is a draft.
draft = request.query_params.get("draft")
published = draft is None or draft.lower() in _NOT_DRAFT
allowed = "/" not in name and name in panel.dashboards and published
elif method == "GET" and path == f"{api}/panels/{panel.id}":
allowed = "/" not in name and name in device.dashboards and published
elif method == "GET" and path in (
f"{api}/devices/{device.id}",
# What firmware from before devices reads.
f"{api}/panels/{device.id}",
):
allowed = True
elif method == "POST" and path == f"{api}/flows/ws-ticket":
# How its live socket opens; the socket applies the panel's own scope.
@@ -214,36 +232,38 @@ def _panel_may(payload: dict[str, Any], request: Request) -> None:
# value in. Percent-decoded, because a message name is a path segment
# here and the client encodes it as one.
rest = unquote(path[len(f"{api}/messages/") :])
scope = _panel_messages
scope = _device_messages
if method == "GET" and rest.endswith(_HISTORY):
name = rest[: -len(_HISTORY)]
elif method == "POST":
name = rest
# A locked dashboard entitles the panel to nothing it can publish.
scope = _panel_writable
scope = _device_writable
else:
name = ""
allowed = bool(name) and name in scope(panel.id, request)
allowed = bool(name) and name in scope(device, request)
elif method == "GET" and path.startswith(f"{api}/artifacts/"):
# The bytes behind a media message a tile on this panel is drawing.
# Scoped to what those messages hold *now*, which is exactly what a
# live widget asks for — a screen has no business reading an artifact
# off an old run because it happens to know the digest.
digest = unquote(path[len(f"{api}/artifacts/") :])
allowed = "/" not in digest and digest in _panel_digests(panel.id, request)
allowed = "/" not in digest and digest in _device_digests(device, request)
elif method == "PUT" and path == f"{api}/artifacts":
# What the device's own sensor recorded — a microphone's utterance —
# uploaded under the ``in`` message it is about to publish it to.
allowed = request.query_params.get("name", "") in panels.io_in(panel.id)
allowed = request.query_params.get("name", "") in devices.io_in(device)
if not allowed:
raise HTTPException(
status_code=status.HTTP_403_FORBIDDEN,
detail="A panel credential cannot do that",
detail="A device credential cannot do that",
)
def decode_token(token: str, request: Request | None = None) -> dict[str, Any]:
def decode_token(
token: str, request: Request | None = None, app: Any = None
) -> dict[str, Any]:
"""Read a bearer token, whichever channel issued it.
A browser session is signed with the app's own secret; an agent's token is
@@ -254,8 +274,9 @@ def decode_token(token: str, request: Request | None = None) -> dict[str, Any]:
A paired wall panel's token is signed with the app's secret too, and is
told apart from a session by its audience: the session decode above
refuses it outright, so the only door it fits is the one ``_panel_may``
guards.
refuses it outright, so the only door it fits is the one ``_device_may``
guards. Where there is no request to scope (a socket handshake, the
tunnel), ``app`` is what a device credential is checked against.
An agent's token is held to one thing more: the client it names has to
still be registered, which is what makes revoking an agent take effect now
@@ -286,11 +307,11 @@ def decode_token(token: str, request: Request | None = None) -> dict[str, Any]:
else:
if not panel_token.get("panel"):
raise InvalidTokenError("a panel token must name its panel")
return _gate_panel(panel_token, request)
return _gate_panel(panel_token, request, app)
try:
agent = security.decode_oauth_token(token)
except InvalidTokenError:
return _gate_panel(cloud_config.decode_portal_token(token), request)
return _gate_panel(cloud_config.decode_portal_token(token), request, app)
return _gate_agent(agent)
@@ -304,7 +325,7 @@ def oauth_client_lives(client_id: str) -> bool:
One primary-key read per agent request, against a table with a row per
registered agent. The request it gates goes on to look its user up the
same way, and the panel gate next door re-reads the panels file and every
same way, and the device gate next door re-reads the device's file and every
published dashboard from disk, so this is the cheapest check in here.
"""
try:
@@ -341,19 +362,22 @@ def _gate_agent(payload: dict[str, Any]) -> dict[str, Any]:
return payload
def _gate_panel(payload: dict[str, Any], request: Request | None) -> dict[str, Any]:
"""Scope a payload that names a panel; pass anything else through.
def _gate_panel(
payload: dict[str, Any], request: Request | None, app: Any = None
) -> dict[str, Any]:
"""Scope a payload that names a device; pass anything else through.
Without a request — from the websocket, which has no route to scope — the
check is only that the credential still stands, which is what makes
deleting a panel, or bumping its nonce, revoke one.
Without a request (the websocket, which has no route to scope) the check
is only that the credential still stands, which is what makes deleting a
device, or bumping its nonce, revoke one. Without an app either there is
nothing to check it against, and it is refused.
"""
if not payload.get("panel"):
return payload
if request is not None:
_panel_may(payload, request)
_device_may(payload, request)
else:
_panel_for(payload)
_device_for(payload, app)
return payload
@@ -393,17 +417,18 @@ def _user_for(session: Session, token_data: TokenPayload) -> User | None:
def user_from_token(
session: Session, token: str, request: Request | None = None
session: Session, token: str, request: Request | None = None, app: Any = None
) -> User | None:
"""Resolve a bearer token to its user, or None if it does not hold up.
Shared with the websocket, which cannot use the HTTP security scheme, and
with the artifact endpoint, which accepts a worker's credential as well as
a person's. Pass the request wherever there is one: a panel's credential is
scoped by route, and without it the scope check cannot run.
a person's. Pass the request wherever there is one: a device's credential is
scoped by route, and without it the scope check cannot run. Without one,
pass the app, or a device credential is refused.
"""
try:
token_data = TokenPayload(**decode_token(token, request))
token_data = TokenPayload(**decode_token(token, request, app))
except (InvalidTokenError, ValidationError):
return None
user = _user_for(session, token_data)
@@ -462,6 +487,16 @@ def get_dashboard_store(request: Request) -> DashboardStore:
DashboardStoreDep = Annotated[DashboardStore, Depends(get_dashboard_store)]
def get_device_store(request: Request) -> DeviceStore:
store: DeviceStore | None = getattr(request.app.state, "device_store", None)
if store is None:
raise HTTPException(status_code=503, detail="The flow engine is not running")
return store
DeviceStoreDep = Annotated[DeviceStore, Depends(get_device_store)]
def get_worker_pool(request: Request) -> PythonWorkerPool:
pool: PythonWorkerPool | None = getattr(request.app.state, "worker_pool", None)
if pool is None: