Add control logic engine, panel logic dialogs, logic-edit restriction
Introduce server-side control-logic flow graphs (cron/alarm triggers, Lua blocks) with CRUD endpoints, panel-logic lifecycle triggers and user-interaction dialog nodes, and a synthetic node-graph editor. Add an optional logic-editor allowlist (server.logic_editors) gating who may add/edit panel logic and control logic, surfaced via /api/v1/me and enforced in the API; hide logic affordances in the UI accordingly. Update README, example config, and functional/technical specs to cover all current features (plot panels, panel/control logic, local variables, access control) and refresh the in-app manual and contextual help. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Martino Ferrari
+105
-24
@@ -186,17 +186,35 @@ Framing: JSON messages over a single persistent WebSocket connection per client.
|
||||
|
||||
Base path: `/api/v1`
|
||||
|
||||
| Method | Path | Description |
|
||||
| ------ | ------------------------- | -------------------------------------------- |
|
||||
| GET | `/datasources` | List connected data sources and their status |
|
||||
| GET | `/signals?ds=epics` | List signals for a data source |
|
||||
| GET | `/signals/:ds/:name/meta` | Get full metadata for a signal |
|
||||
| GET | `/interfaces` | List saved interfaces |
|
||||
| POST | `/interfaces` | Create a new interface (body: XML) |
|
||||
| GET | `/interfaces/:id` | Download interface XML |
|
||||
| PUT | `/interfaces/:id` | Update interface XML |
|
||||
| DELETE | `/interfaces/:id` | Delete interface |
|
||||
| POST | `/interfaces/:id/clone` | Clone an interface |
|
||||
| Method | Path | Description |
|
||||
| --------------- | ------------------------------------- | ------------------------------------------------- |
|
||||
| GET | `/me` | Caller identity, global level, groups, `canEditLogic` |
|
||||
| GET | `/datasources` | List connected data sources and their status |
|
||||
| GET | `/signals?ds=epics` | List signals for a data source |
|
||||
| GET | `/signals/search?q=` | Search signals across all sources |
|
||||
| GET | `/channel-finder?q=` | Proxy to EPICS Channel Finder |
|
||||
| GET | `/archiver/search?q=` | Search the EPICS archiver for PV names |
|
||||
| GET, POST | `/interfaces` | List saved interfaces / create one (body: XML) |
|
||||
| POST | `/interfaces/reorder` | Reorder panels / move between folders |
|
||||
| GET, PUT, DELETE| `/interfaces/{id}` | Download, update, or delete an interface |
|
||||
| POST | `/interfaces/{id}/clone` | Clone an interface |
|
||||
| GET | `/interfaces/{id}/versions` | List saved versions; `…/{version}` to fetch one |
|
||||
| PUT | `/interfaces/{id}/versions/{v}/tag` | Tag a version |
|
||||
| POST | `/interfaces/{id}/versions/{v}/promote` | Promote a version to current |
|
||||
| POST | `/interfaces/{id}/versions/{v}/fork` | Fork a version into a new panel |
|
||||
| GET, PUT | `/interfaces/{id}/acl` | Read or set a panel's sharing rules |
|
||||
| GET, POST | `/folders` | List or create panel folders |
|
||||
| PUT, DELETE | `/folders/{id}` | Rename/reparent or delete a folder |
|
||||
| GET | `/usergroups` | List configured users and groups (for sharing) |
|
||||
| GET, PUT | `/groups` | Read or set group definitions |
|
||||
| GET, POST | `/synthetic` | List or create synthetic signal definitions |
|
||||
| GET, PUT, DELETE| `/synthetic/{name}` | Read, update, or delete a synthetic definition |
|
||||
| GET, POST | `/controllogic` | List or create server-side control-logic graphs |
|
||||
| GET, PUT, DELETE| `/controllogic/{id}` | Read, update, or delete a control-logic graph |
|
||||
|
||||
Mutating requests are gated by the access middleware (§8): global level for writes,
|
||||
per-panel ACL for interface endpoints, and the logic-editor allowlist for control-logic
|
||||
endpoints and for any change to a panel's `<logic>` block.
|
||||
|
||||
### 3.5 EPICS Data Source
|
||||
|
||||
@@ -232,7 +250,15 @@ Base path: `/api/v1`
|
||||
|
||||
### 3.7 Interface Storage
|
||||
|
||||
Interfaces are stored as XML files in a configurable directory on the server.
|
||||
Interfaces are stored as XML files in a configurable directory on the server. The
|
||||
`<interface>` element carries an optional `kind` attribute (`panel` default, or `plot`);
|
||||
plot panels add a nested `<layout>` split tree referencing plot widgets by id. Beyond
|
||||
widgets, an interface may also contain panel-local variables and a `<logic>` flow graph
|
||||
(`<node>` + `<param>` + `<wire>`), all round-tripping through the same XML.
|
||||
|
||||
Per-panel access rules and folder placement are kept in a sidecar `acl.json` in the same
|
||||
directory (not in the interface XML), and prior versions of each panel are retained for the
|
||||
version history endpoints.
|
||||
|
||||
```xml
|
||||
<interface name="My Panel" version="1" created="2026-04-24T12:00:00Z">
|
||||
@@ -255,6 +281,39 @@ Interfaces are stored as XML files in a configurable directory on the server.
|
||||
</interface>
|
||||
```
|
||||
|
||||
### 3.8 Panel Logic Engine
|
||||
|
||||
Panel logic is a client-side flow engine (`web/src/lib/logic.ts`, singleton `logicEngine`).
|
||||
The graph is built/edited in the panel editor's Logic tab (`LogicEditor.tsx`) and serialized
|
||||
into the interface XML. In View mode, `Canvas` calls `logicEngine.load(iface.logic)` on
|
||||
mount and `clear()` on unmount. The engine subscribes to every referenced signal into a live
|
||||
cache, then on each trigger activation walks the wired graph (gates, if/loop, actions),
|
||||
evaluating expression fields via a small safe recursive-descent evaluator (no `eval`).
|
||||
Triggers include button/threshold/change/timer/loop and On-open/On-close lifecycle; actions
|
||||
include signal writes, delay, log, in-memory data arrays (accumulate/export-CSV/clear) and
|
||||
user dialogs (info/error/set-point). The engine runs entirely in the browser — no backend
|
||||
component.
|
||||
|
||||
### 3.9 Control Logic Engine
|
||||
|
||||
Control logic is server-side (`internal/controllogic`): always-on flow graphs that run under
|
||||
the root context, independent of any client. The engine subscribes to the broker, fires on
|
||||
cron schedules and signal alarm/threshold conditions, executes a Lua block for custom logic,
|
||||
and writes results back to signals. Graphs are persisted by a store and managed via
|
||||
`/api/v1/controllogic`; each mutation calls `Engine.Reload()` to apply changes live. Graphs
|
||||
can be individually enabled/disabled.
|
||||
|
||||
### 3.10 Access Control
|
||||
|
||||
Identity and global policy live in `internal/access` (`Policy`, `Level`). The user identity
|
||||
is read per request from `server.trusted_user_header` (with a `default_user` fallback) and
|
||||
stored on the request context. `accessMiddleware` gates mutating HTTP methods by the user's
|
||||
global level. Per-panel ownership and ACL evaluation (with folder inheritance) live in
|
||||
`internal/panelacl`, backed by the `acl.json` sidecar. `Policy.CanEditLogic(user)` enforces
|
||||
the optional `server.logic_editors` allowlist over control-logic endpoints and over any
|
||||
change to a panel's `<logic>` block; it is surfaced to the frontend through `/api/v1/me`
|
||||
(`canEditLogic`) so the UI can hide logic-editing affordances.
|
||||
|
||||
---
|
||||
|
||||
## 4. Frontend Architecture
|
||||
@@ -298,16 +357,17 @@ View mode renders widgets as absolutely positioned Preact components on a scroll
|
||||
- Plot widgets maintain a rolling ring buffer of 200,000 samples per signal for smooth long-window display.
|
||||
- Step-hold interpolation: when multiple signals at different update rates share a plot, the most recent value is carried forward to fill the shared time axis correctly.
|
||||
|
||||
### 4.5 Plot Panel (`PlotPanel.tsx`)
|
||||
### 4.5 Plot Panels (`SplitLayout.tsx`, `PlotPanelCanvas.tsx`)
|
||||
|
||||
A live multi-signal plot panel accessible from the "Plot" tab in View mode:
|
||||
Plot panels are interfaces of `kind === 'plot'` whose plots fill the viewport in a recursive
|
||||
split layout (`lib/plotLayout.ts` holds the pure tree helpers; `SplitLayout.tsx` is the
|
||||
shared presentational renderer with draggable dividers):
|
||||
|
||||
- Signals are added by right-clicking any widget and choosing "Plot".
|
||||
- Supports configurable time window (10s to 1h).
|
||||
- Per-signal style editor: color picker, line width (0 = hidden), line dash (solid/dashed/dotted), marker size (none/S/M/L).
|
||||
- Statistics table per signal: last, min, max, mean over the current time window.
|
||||
- Uses a `requestAnimationFrame` loop limited to ≤1 redraw/second when data is not changing.
|
||||
- Chart fills its container; `ResizeObserver` keeps the uPlot canvas sized correctly.
|
||||
- In View mode, `Canvas` renders the saved layout read-only with live `PlotWidget`s.
|
||||
- In Edit mode, `PlotPanelCanvas.tsx` adds per-pane overlays: split (⬌/⬍), close (✕), click
|
||||
to select, and signal-drop to add a signal to that pane's plot.
|
||||
- Each pane reuses the standard `PlotWidget`, so all plot sub-types and options apply.
|
||||
- Layout edits (split/close/resize) participate in the editor's undo/redo.
|
||||
|
||||
### 4.6 Resizable Panels
|
||||
|
||||
@@ -407,17 +467,31 @@ Server is configured via a TOML file (default: `uopi.toml`, overridable via `--c
|
||||
listen = ":8080"
|
||||
storage_dir = "./interfaces"
|
||||
|
||||
# Access control (all optional)
|
||||
trusted_user_header = "" # header carrying the proxy-authenticated user
|
||||
default_user = "" # identity when the header is absent (LAN/dev)
|
||||
logic_editors = [] # users/groups allowed to edit panel & control logic
|
||||
|
||||
# [[server.blacklist]] # downgrade users: level = "readonly" | "noaccess"
|
||||
# user = "guest"
|
||||
# level = "readonly"
|
||||
|
||||
# [[groups]] # named user sets for per-panel sharing
|
||||
# name = "operators"
|
||||
# members = ["alice", "bob"]
|
||||
|
||||
[datasource.epics]
|
||||
enabled = true
|
||||
ca_addr_list = "" # EPICS_CA_ADDR_LIST override
|
||||
archive_url = "" # EPICS Archive Appliance URL
|
||||
channel_finder_url = "" # EPICS Channel Finder URL
|
||||
|
||||
[datasource.synthetic]
|
||||
enabled = true
|
||||
definitions_file = "./synthetic.toml"
|
||||
```
|
||||
|
||||
All settings can also be overridden with `UOPI_*` environment variables (e.g. `UOPI_SERVER_LISTEN`, `UOPI_EPICS_CA_ADDR_LIST`).
|
||||
All settings can also be overridden with `UOPI_*` environment variables (e.g.
|
||||
`UOPI_SERVER_LISTEN`, `UOPI_SERVER_LOGIC_EDITORS`, `UOPI_EPICS_CA_ADDR_LIST`).
|
||||
|
||||
---
|
||||
|
||||
@@ -440,13 +514,20 @@ All settings can also be overridden with `UOPI_*` environment variables (e.g. `U
|
||||
- Lua sandbox: disable `os`, `io`, `package`, `debug` libraries; restrict `math` and `string` to safe subsets.
|
||||
- WebSocket write operations: validate that the target signal is writable before forwarding to the data source.
|
||||
- Interface XML parsing: use strict schema validation to prevent XXE.
|
||||
- No authentication in v1; intended for trusted LAN / SSH-tunnel deployment.
|
||||
- **Identity & access control:** the end-user identity is taken from a header set by a
|
||||
trusted authenticating reverse proxy (`trusted_user_header`), never from client-supplied
|
||||
values — the proxy MUST strip any inbound copy of that header or it can be spoofed. A
|
||||
global blacklist downgrades users (read-only/no-access); per-panel ACLs and the optional
|
||||
`logic_editors` allowlist provide finer control. An unidentified caller (no header, no
|
||||
`default_user`) is treated as a trusted-LAN user with full write access, preserving the
|
||||
unproxied/SSH-tunnel deployment model.
|
||||
|
||||
---
|
||||
|
||||
## 9. Non-goals (v1)
|
||||
|
||||
- User authentication and authorisation.
|
||||
- Built-in user authentication (a login page / credential store) — identity is delegated to
|
||||
the front-end reverse proxy; authorisation (levels, ACLs, logic allowlist) is implemented.
|
||||
- TLS termination (expected to be handled by SSH tunnel or a reverse proxy).
|
||||
- Windows or macOS server binary.
|
||||
- Mobile-optimised frontend layout.
|
||||
|
||||
Reference in New Issue
Block a user