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
+102 -33
View File
@@ -28,11 +28,15 @@ from fluksio.flow.messages import DType, qualify
from fluksio.flow.schemas import FlowDef, _validate_id, _validate_name
from fluksio.flow.store import (
FlowStore,
IdTaken,
StaleVersion,
_updated_at,
_version,
checked,
claim,
copy_name,
named,
new_id,
read_keys,
)
@@ -619,6 +623,27 @@ class DashboardDef(BaseModel):
return shapes
class DashboardCreate(BaseModel):
"""A new dashboard: one empty grid under a key, filled in by saves after."""
#: Empty for an id the server issues, or one a superuser pins, as for a
#: flow (`FlowCreate`). Dashboards keep no history, so it only has to be free.
id: str = ""
name: str
#: Empty reads the key as words.
title: str = ""
@field_validator("id")
@classmethod
def _check_id(cls, value: str) -> str:
return _validate_id(value)
@field_validator("name")
@classmethod
def _check_name(cls, value: str) -> str:
return _validate_name(value)
class DashboardSummary(BaseModel):
"""A dashboard in a list, without its contents."""
@@ -766,14 +791,17 @@ class DashboardStore:
self._keys = (at, keys)
return keys
def _claim(self, defn: DashboardDef) -> DashboardDef:
def _claim(self, defn: DashboardDef, create: bool = False) -> DashboardDef:
"""*defn* with its id, once it is certain to be a save the store allows.
Under the flow store's write lock; see `claim`. An id left out is the
key, which is how every dashboard is created for now.
Under the flow store's write lock; see `claim`. A save is to a
dashboard that exists, named by its id or, from before ids, its key.
Only *create* may make a new one.
"""
dash_id = checked(defn.id or defn.name)
current = self.read(dash_id, draft=True) if self.exists(dash_id) else None
if current is None and not create:
raise DashboardNotFound(dash_id)
claim(
dash_id,
defn.name,
@@ -807,21 +835,50 @@ class DashboardStore:
"""Publish a dashboard directly, skipping the draft.
The API never does: it creates a draft and promotes it. This is for a
caller that already has the finished document — a test, or a seed.
caller that already has the finished document, a test or a seed, and
creates one too, under the id it carries or else its key.
"""
with self._lock, self.flows._write_lock:
defn = self._claim(defn)
defn = self._claim(defn, create=True)
path = self._file(defn.id)
current = 0
if path.exists():
current = DashboardDef.model_validate_json(path.read_text()).version
current = _version(path)
if base_version is not None and base_version != current:
raise StaleVersion(defn.name, current)
saved = defn.model_copy(update={"version": current + 1, "has_draft": False})
# Above the draft too, which an editor may be holding.
top = max(current, _version(self._draft_file(defn.id)))
saved = defn.model_copy(update={"version": top + 1, "has_draft": False})
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(self._dump(saved))
self.flows._commit(f"Save dashboard '{defn.name}'")
self.flows._commit(f"Save dashboard {named(defn.name, defn.id)}")
return saved
def create(
self, defn: DashboardDef, pin: str = "", published: bool = False
) -> DashboardDef:
"""A new dashboard, only a draft unless *published* says otherwise.
Its id is issued here unless *pin* names one, a superuser's to ask for
as for a flow (`FlowStore.create`). Dashboards have no history to
adopt, so a pin only has to be free.
"""
with self._lock, self.flows._write_lock:
keys = self.key_index()
if pin:
dash_id = checked(pin)
if (self.root / dash_id).exists():
raise IdTaken(dash_id, "dashboard")
else:
dash_id = new_id("d", lambda c: (self.root / c).exists() or c in keys)
defn = self._claim(defn.model_copy(update={"id": dash_id}), create=True)
if keys.get(dash_id, dash_id) != dash_id:
raise IdTaken(dash_id, "dashboard")
saved = defn.model_copy(update={"version": 1, "has_draft": not published})
path = self._file(dash_id) if published else self._draft_file(dash_id)
path.parent.mkdir(parents=True)
path.write_text(self._dump(saved))
self.flows._commit(f"Create dashboard {named(defn.name, dash_id)}")
return saved
def write_draft(
@@ -829,23 +886,19 @@ class DashboardStore:
) -> DashboardDef:
"""Save unpublished changes, refusing to overwrite someone else's.
``base_version`` is the version the editor last saw — of the working
copy, which is the draft once there is one, and 0 for a dashboard that
does not exist yet: creating one is its first draft.
``base_version`` is the version the editor last saw, of the working
copy, which is the draft once there is one. The dashboard has to
exist: creating one is `create`.
"""
with self._lock, self.flows._write_lock:
defn = self._claim(defn)
current = 0
if self.exists(defn.id):
current = self.read(defn.id, draft=True).version
current = self.read(defn.id, draft=True).version
if base_version is not None and base_version != current:
raise StaleVersion(defn.name, current)
saved = defn.model_copy(update={"version": current + 1, "has_draft": True})
path = self._draft_file(defn.id)
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(self._dump(saved))
self.flows._commit(f"Update draft of dashboard '{defn.name}'")
self._draft_file(defn.id).write_text(self._dump(saved))
self.flows._commit(f"Update draft of dashboard {named(defn.name, defn.id)}")
return saved
def publish(self, name: str, base_version: int | None = None) -> DashboardDef:
@@ -859,14 +912,24 @@ class DashboardStore:
if draft.exists():
self._file(name).write_text(self._dump(current))
draft.unlink()
self.flows._commit(f"Publish dashboard '{name}'")
self.flows._commit(f"Publish dashboard {named(current.name, name)}")
return current.model_copy(update={"has_draft": False})
def discard_draft(self, name: str) -> DashboardDef:
"""Throw the unpublished changes away and go back to what is shown."""
"""Throw the unpublished changes away and go back to what is shown.
What is shown comes back a version above the draft, as a flow's does
(`FlowStore.discard_draft`).
"""
with self._lock, self.flows._write_lock:
draft = self._draft_file(name)
if draft.exists():
shown = self.read(name)
top = _version(draft)
if shown.version <= top:
self._file(name).write_text(
self._dump(shown.model_copy(update={"version": top + 1}))
)
draft.unlink()
self.flows._commit(f"Discard draft of dashboard '{name}'")
return self.read(name)
@@ -887,27 +950,32 @@ class DashboardStore:
def duplicate(self, name: str) -> DashboardDef:
"""Copy the working copy into a new dashboard, as a draft only.
Named ``{name}_copy``, then ``_copy_2`` and on. Unpublished like a new
dashboard, so no panel shows it until someone publishes it.
Under an id of its own and the key ``{name}_copy``, then ``_copy_2``
and on. Unpublished like a new dashboard, so no panel shows it until
someone publishes it.
"""
with self._lock, self.flows._write_lock:
source = self.read(name, draft=True)
# The copy's id is its key, so it has to be free as both.
keys = self.key_index()
new_name = copy_name(source.name, lambda n: self.exists(n) or n in keys)
new_name = copy_name(source.name, lambda n: n in keys)
copy_id = new_id("d", lambda c: (self.root / c).exists() or c in keys)
copy = source.model_copy(
update={
"id": new_name,
"id": copy_id,
"name": new_name,
"title": f"{source.title} (copy)" if source.title else "",
"version": 1,
"has_draft": True,
}
)
path = self._draft_file(new_name)
path.parent.mkdir(parents=True, exist_ok=True)
copy = self._claim(copy, create=True)
path = self._draft_file(copy_id)
path.parent.mkdir(parents=True)
path.write_text(self._dump(copy))
self.flows._commit(f"Duplicate dashboard '{name}' as '{new_name}'")
self.flows._commit(
f"Duplicate dashboard {named(source.name, name)} as "
f"{named(new_name, copy_id)}"
)
return copy
def bindings_for(self, flow: str) -> Bindings:
@@ -984,11 +1052,11 @@ class DashboardStore:
return limits
def default_dashboard(name: str) -> DashboardDef:
"""A new dashboard: one page, one section, nothing in it yet."""
def default_dashboard(name: str, title: str = "") -> DashboardDef:
"""A new dashboard: one empty grid, titled after its key unless told."""
return DashboardDef(
name=name,
title=name.replace("_", " ").capitalize(),
title=title or name.replace("_", " ").capitalize(),
)
@@ -1094,6 +1162,7 @@ __all__ = [
"INPUT_WIDGETS",
"SETTING_DTYPES",
"WIDGET_DTYPES",
"DashboardCreate",
"DashboardDef",
"DashboardExists",
"DashboardNotFound",