martino/uopi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8f50bc2498fe8c9543610a1b34637076d6f39ed3
uopi/docs/TECHNICAL_SPEC.md
T
Martino Ferrari c0f7e662be Testing
2026-06-24 01:39:15 +02:00

796 lines
46 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Technical Specification — uopi
## 1. Technology Choices
### 1.1 Backend — Go
**Rationale:**
- Compiles to a single static binary with no runtime dependencies, trivially portable to old Linux targets.
- `//go:embed` packs the compiled frontend assets into the binary at build time.
- Goroutine-per-connection model maps naturally onto the fan-out data broker pattern.
- CGo bindings to EPICS `libca` / `libCom` are straightforward.
- `gopher-lua` provides an embedded Lua 5.1-compatible interpreter for synthetic signals with zero additional dependencies.
- Strong standard library: `net/http`, `encoding/xml`, `encoding/json`.
**Go version:** 1.22+
**Key dependencies:**
| Package | Purpose |
| ---------------------------- | ------------------------------------------------------ |
| `nhooyr.io/websocket` | WebSocket server (no CGo, more ergonomic than gorilla) |
| CGo wrapper to `libca` | EPICS Channel Access |
| `yuin/gopher-lua` | Lua 5.1 runtime for synthetic signals |
| `BurntSushi/toml` | TOML config parsing |
| `encoding/xml` (stdlib) | Interface file serialisation |
| `net/http` (stdlib) | HTTP server and static file serving |
### 1.2 Frontend — Preact + TypeScript
**Rationale:**
- Preact is a 3 kB React-compatible virtual DOM library — small bundle, fast diffing, no extra framework overhead.
- esbuild (invoked via its Go API) bundles the TypeScript/TSX source in milliseconds with no Node.js or npm dependency at build time.
- TypeScript catches signal subscription and widget property type errors at build time.
- All vendor JS/CSS is checked into `web/vendor/` so the repo builds without internet access.
**Key dependencies (vendored):**
| Package | Purpose |
| ---------------- | --------------------------------------------------------------- |
| `preact` 10 | Virtual DOM UI framework |
| `uPlot` | Extremely fast time-series/line plot (canvas-based, < 40 kB) |
| `Apache ECharts` | FFT, waterfall, histogram, bar, logic analyser, waveform plots |
| `uplot.css` | uPlot default stylesheet |
**Intentionally excluded:** React, Vue, Svelte, Konva, WebGPU, jQuery, npm at runtime.
---
## 2. Repository Layout
```
uopi/
├── cmd/uopi/ # main package — CLI flags, wiring
├── internal/
│ ├── server/ # HTTP + WebSocket handlers
│ ├── broker/ # signal fan-out to clients
│ ├── datasource/
│ │ ├── iface.go # DataSource interface
│ │ ├── epics/ # EPICS CA implementation (CGo)
│ │ └── synthetic/ # synthetic signal engine + DSP bridge
│ ├── dsp/ # DSP node implementations (lowpass, MA, etc.)
│ ├── storage/ # interface XML read/write
│ └── api/ # REST handler functions
├── web/
│ ├── embed.go # //go:embed dist — exports FS to Go
│ ├── src/ # TypeScript/TSX source (Preact)
│ │ ├── lib/
│ │ │ ├── ws.ts # WebSocket client + subscription manager
│ │ │ ├── stores.ts # signal value + metadata stores
│ │ │ ├── types.ts # shared TypeScript interfaces
│ │ │ ├── xml.ts # interface XML parse/serialize
│ │ │ └── format.ts # value formatting helpers
│ │ ├── widgets/ # one .tsx file per widget type
│ │ ├── App.tsx # top-level component, mode routing
│ │ ├── ViewMode.tsx # view mode layout + tabs
│ │ ├── EditMode.tsx # edit mode layout + toolbar
│ │ ├── Canvas.tsx # live HMI canvas (view mode)
│ │ ├── EditCanvas.tsx # free-form widget editor canvas
│ │ ├── PlotPanel.tsx # live plot side-panel (Plot tab)
│ │ ├── InfoPanel.tsx # signal info side-panel
│ │ ├── ZoomControl.tsx # UI zoom A-/A+ control
│ │ ├── SyntheticWizard.tsx # new synthetic signal dialog
│ │ ├── SyntheticEditor.tsx # edit existing synthetic signal
│ │ ├── LuaEditor.tsx # Lua code editor with syntax highlight
│ │ └── styles.css # all component styles
│ ├── vendor/ # vendored JS/CSS (preact, uplot, echarts)
│ └── dist/ # built frontend — generated, not committed
├── tools/buildfrontend/ # esbuild Go API bundler (go generate)
├── docs/ # specs, work plan
├── CLAUDE.md
└── README.md
```
The embed package lives at `web/embed.go` (not in `cmd/`) because `//go:embed` paths cannot use `..`.
---
## 3. Backend Architecture
### 3.1 DataSource Interface
```go
type Value struct {
Timestamp time.Time
Data any // float64 | []float64 | string | int64 | bool
Quality Quality // Good | Bad | Uncertain
}
type Metadata struct {
Name string
Type DataType
Unit string
DisplayLow float64
DisplayHigh float64
DriveHigh float64
DriveLow float64
EnumStrings []string
Writable bool
}
type DataSource interface {
Name() string
Connect(ctx context.Context) error
ListSignals(ctx context.Context) ([]Metadata, error)
GetMetadata(ctx context.Context, signal string) (Metadata, error)
Subscribe(ctx context.Context, signal string, ch chan<- Value) (CancelFunc, error)
Write(ctx context.Context, signal string, value any) error
History(ctx context.Context, signal string, start, end time.Time, maxPoints int) ([]Value, error)
}
```
New data sources are registered at startup via `datasource.Register(name string, ds DataSource)`.
### 3.2 Signal Broker
The broker is the central fan-out component:
```
DataSource ──subscribe──► rawCh ──► Broker ──► [clientCh1, clientCh2, ...]
```
- One goroutine per active signal subscription to the underlying data source.
- Per-signal subscriber list protected by a sync.RWMutex.
- When the last client unsubscribes, the broker cancels the upstream subscription.
- No data is buffered in the broker; clients receive the latest value at the moment they subscribe and all subsequent updates.
### 3.3 WebSocket Protocol
Framing: JSON messages over a single persistent WebSocket connection per client.
**Client → Server messages:**
```jsonc
// Subscribe to one or more signals
{ "type": "subscribe", "signals": ["EPICS:PV1", "synth:mySignal"] }
// Unsubscribe
{ "type": "unsubscribe", "signals": ["EPICS:PV1"] }
// Write a value
{ "type": "write", "signal": "EPICS:PV1", "value": 3.14 }
// Request historical data
{ "type": "history", "signal": "EPICS:PV1", "start": "2026-01-01T00:00:00Z", "end": "2026-01-02T00:00:00Z", "maxPoints": 5000 }
// Start a control-logic live-debug session (one per client; replaces any prior).
// mode "live" — observe the running, enabled graph identified by graphId.
// mode "simulate" — dry-run the unsaved `graph` in a server sandbox (no real
// writes/config/dialogs); re-send on each edit to refresh it.
{ "type": "debugSubscribe", "mode": "live", "graphId": "g1" }
{ "type": "debugSubscribe", "mode": "simulate", "graph": { /* unsaved control-logic graph */ } }
// Stop the current debug session (tears down any simulate sandbox).
{ "type": "debugUnsubscribe" }
// Force a trigger node of the current debug session (live or simulate) to run
// now, as if it had fired. nodeId must be a trigger node of the watched graph;
// best-effort (dropped if the session is gone). Drives the editor's
// double-click-to-fire gesture on trigger nodes in debug mode.
{ "type": "fireTrigger", "nodeId": "t" }
```
**Server → Client messages:**
```jsonc
// Live value update
{ "type": "update", "signal": "EPICS:PV1", "ts": "2026-04-24T12:00:00.123Z", "value": 42.7, "quality": "good" }
// Metadata (sent once on first subscribe)
{ "type": "meta", "signal": "EPICS:PV1", "meta": { "unit": "A", "displayLow": 0, "displayHigh": 100, ... } }
// Historical data response
{ "type": "history", "signal": "EPICS:PV1", "points": [ { "ts": "...", "value": 1.2 }, ... ] }
// Control-logic node execution during a live-debug session. Emitted ~per node
// run for the watched graph (live) or sandbox (simulate); value is meaningful
// only when hasValue is true (e.g. an action.write's value, a flow.if branch 0/1).
{ "type": "debugNode", "graphId": "g1", "nodeId": "w", "value": 42, "hasValue": true, "ts": 1750000000000 }
// Error
{ "type": "error", "code": "NOT_FOUND", "message": "Signal not found" }
```
### 3.4 REST API
Base path: `/api/v1`
| 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, 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 |
| POST | `/synthetic/trace` | Stateless single-shot trace of an unsaved graph for the live-debug view — every node's value; stateful ops flagged `approx` |
| GET, POST | `/controllogic` | List or create server-side control-logic graphs |
| GET, PUT, DELETE| `/controllogic/{id}` | Read, update, or delete a control-logic graph |
| GET, POST | `/config/sets` | List or create configuration sets (schemas) |
| GET, PUT, DELETE| `/config/sets/{id}` | Read, update, or delete a config set |
| GET, POST | `/config/instances` | List or create configuration instances (values) |
| GET, PUT, DELETE| `/config/instances/{id}` | Read, update, or delete a config instance |
| POST | `/config/instances/{id}/apply` | Write an instance's values to their target signals |
| POST | `/config/instances/{id}/validate` | Run the set's CUE rules over the stored values; returns a structured `RuleResult` (no save) |
| GET | `/config/instances/{id}/livediff` | Diff the stored instance (resolved with defaults) against the current live signal values |
| POST | `/config/sets/{id}/snapshot` | Capture every target signal's current live value into a new instance (body: optional `{name}`) |
| GET | `/config/{sets\|instances}/diff` | Structural diff between two revisions (`a,av,b,bv`)|
| GET, POST | `/config/rules` | List or create CUE validation/transformation rules |
| GET, PUT, DELETE| `/config/rules/{id}` | Read, update, or delete a rule |
| POST | `/config/rules/check` | Compile an (unsaved) CUE source and evaluate it against sample values — powers the live editor |
**Versioning (shared).** Interfaces, synthetic signals, control-logic graphs and config
sets/instances all expose the same revision endpoints under their `{base}`:
| Method | Path | Description |
| ------ | ---- | ----------- |
| GET | `{base}/{id}/versions` | List revisions; `…/{version}` fetches one |
| POST | `{base}/{id}/versions/{v}/promote` | Promote a revision to current |
| POST | `{base}/{id}/versions/{v}/fork` | Fork a revision into a new document |
| PUT | `/interfaces/{id}/versions/{v}/tag` | Tag a panel version |
Mutating requests are gated by the access middleware (§3.10): 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. Config-set/instance
promote/fork are gated by the same write policy.
### 3.5 EPICS Data Source
- Uses CGo bindings to EPICS Base `libca` (Channel Access).
- Channel connections are lazy: connected on first Subscribe, disconnected when the broker releases it.
- On connect, a `ca_get` retrieves full DBR_CTRL metadata (units, limits, enum strings).
- `ca_add_event` sets up the monitor. Update callbacks push into the broker's raw channel.
- Multiple PV subscriptions share one CA context per data source instance (thread-safe with `ca_attach_context`).
- EPICS Archive Appliance is queried via its JSON HTTP API for history requests.
### 3.6 Synthetic Data Source
- Each synthetic signal is defined as a directed acyclic graph (DAG) of processing nodes.
- Processing nodes are re-evaluated whenever any upstream signal emits a new value.
- Definitions are stored in a configurable JSON/TOML file alongside server configuration.
- The `dsp_bridge.go` file maps node type names to `dsp.Node` implementations.
**Built-in node types:**
| Node type | Parameters | In→Out | Description |
| ---------------- | --------------------------- | -------------- | ----------------------------------------------- |
| `source` | `ds`, `name` | — | Reads a signal from any data source |
| `gain` | `gain` | elementwise | Multiplies by a constant |
| `offset` | `offset` | elementwise | Adds a constant |
| `add`/`subtract` | — | elementwise | Sum of inputs / `a − b` |
| `multiply`/`divide` | — | elementwise | Product of inputs / `a ÷ b` |
| `clamp` | `min`, `max` | elementwise | Constrains to a range |
| `threshold` | `threshold`, `high`, `low` | elementwise | Comparator output |
| `moving_average` | `window` (samples) | scalar-only | Rolling mean |
| `rms` | `window` (samples) | scalar-only | Rolling RMS |
| `derivative` | — | scalar-only | Time derivative (per-sample `dt`) |
| `integrate` | — | scalar-only | Trapezoidal integral |
| `lowpass` | `freq` (Hz), `order` (1–8) | scalar-only | Cascaded IIR Butterworth-style low-pass filter |
| `expr` | `expr`, `vars` | elementwise | Inline math expression (named inputs) |
| `lua` | `script`, `vars` | scalar-only | Arbitrary Lua 5.1 code with persistent state |
| `index` | `i` | array→scalar | Element `i` of a waveform (bounds-checked) |
| `slice` | `start`, `end` | array→array | Sub-range of a waveform (clamped) |
| `sum`/`mean` | — | array→scalar | Σ / average of a waveform |
| `min`/`max` | — | array→scalar | Reduction of a waveform |
| `length` | — | array→scalar | Element count of a waveform |
| `fft` | — | array→array | Magnitude spectrum (zero-padded to next pow-2) |
**Scalar vs waveform values:** A value flowing through the graph is a `dsp.Sample` — either a scalar `float64` or a `[]float64` waveform (the array-aware counterpart of EPICS `TypeFloat64Array`). *Elementwise* ops broadcast over arrays (scalar inputs act as constants; array inputs must share a length). *Reduction*/*producer* ops (`index`/`slice`/`sum`/…/`fft`) operate natively on waveforms. *Scalar-only* ops (stateful filters + `lua`) reject array inputs, since their per-evaluation state cannot be split across array lanes. `OpOutputType` (`internal/dsp/types.go`) propagates types statically at compile time to reject invalid wirings and to report the synthetic's metadata type; the editor mirrors these rules in `web/src/lib/synthTypes.ts` to colour wires by data type (scalar vs array) and flag type-incompatible links. Runtime `Sample` typing is authoritative.
**Low-pass filter implementation:** Cascaded first-order IIR sections. Each stage computes `y = y_prev + α·(x − y_prev)` where `α = dt / (RC + dt)` and `RC = 1/(2π·fc)`. `dt` is computed per sample from source timestamps so the filter is correct for event-driven (non-uniform) data.
**Lua node:** Receives `inputs` table (indexed by signal name) and a persistent `state` table across calls. The `os`, `io`, `package`, and `debug` libraries are disabled.
### 3.7 Interface Storage
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">
<widget id="w1" type="plot" x="100" y="200" w="600" h="300">
<signal ds="epics" name="EPICS:CURRENT" color="#ff0000"/>
<signal ds="epics" name="EPICS:VOLTAGE" color="#0000ff"/>
<option key="plotType" value="timeseries"/>
<option key="yMin" value="auto"/>
<option key="yMax" value="auto"/>
<option key="timeWindow" value="60"/>
<option key="legend" value="bottom"/>
</widget>
<widget id="w2" type="led" x="50" y="50" w="80" h="80">
<signal ds="epics" name="EPICS:STATUS"/>
<option key="condition" value="value &gt; 0"/>
<option key="colorTrue" value="#00ff00"/>
<option key="colorFalse" value="#ff0000"/>
<option key="label" value="OK"/>
</widget>
</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.
The engine also holds a `*confmgr.Store` (injected via `NewEngine`) for five config action
nodes: `action.config.apply` resolves an instance + its set and runs `confmgr.Apply` with a
broker-backed, audited write closure; `action.config.read` resolves a single parameter value
(`ConfigInstance.Resolve`), coerces it to float64 and writes it to the node's target;
`action.config.write` evaluates an expression and stores the (type-coerced, via
`coerceParamValue`) value into a parameter, creating a new instance revision;
`action.config.create` creates a new instance for a set, optionally seeding its values from
another instance; and `action.config.snapshot` reads every target signal's current live value
(via the one-shot `Broker.ReadNow`, type-coerced by `confmgr.Snapshot`) and stores them as a
new instance. All mutating nodes are audited. The panel-logic engine
(`web/src/lib/logic.ts`) mirrors all five client-side via the REST endpoints
(`/config/instances/{id}/apply`, GET/PUT `/config/instances/{id}`, POST `/config/instances`,
POST `/config/sets/{id}/snapshot`).
Panel-logic apply/read/write nodes additionally support an `instanceSource: 'var'` mode that
reads the target instance id (a string) from a panel-local variable rather than a fixed id —
fed by the **Config Selector** widget (`web/src/widgets/ConfigSelect.tsx`), which lists a
set's instances in a combo and writes the chosen id to that variable. Control-logic nodes use
fixed ids only (its variables are numeric, instance ids are strings). To let the selector
filter instances by set without a GET per instance, `confmgr.Store.List` now returns each
instance's `setId` in its `Meta`.
### 3.10 Access Control
Identity and global policy live in `internal/access` (`Policy`, `Role`, `Level`). The user
identity is read per request from `server.trusted_user_header` (with a `default_user`
fallback) and stored on the request context. Alternatively, **native SPNEGO/Kerberos**
authentication (`[server.kerberos]`) lets uopi identify users directly from their Kerberos
ticket without a reverse proxy: `internal/server/kerberos.go` wraps the REST and WebSocket
handlers, challenges API requests with `401 WWW-Authenticate: Negotiate`, validates the
ticket against the configured service keytab (`github.com/jcmturner/gokrb5`), and writes the
short principal name (realm stripped) into the same `userHeader` the access pipeline reads
— so downstream identity resolution is identical. Any client-supplied header value is
discarded before validation to prevent spoofing. WebSocket upgrades (where browsers cannot
attach an `Authorization` header) validate proactively-sent credentials best-effort and
otherwise fall back to `default_user`. Browsers must be configured to perform SPNEGO for the
server origin (Firefox: `network.negotiate-auth.trusted-uris`), which fixes the case where
Firefox would otherwise resolve to `default_user`. A third standalone option is **built-in
HTTP Basic authentication** (`[server.basic_auth]`, mutually exclusive with Kerberos):
`internal/server/basicauth.go` challenges with `401 WWW-Authenticate: Basic` and validates
credentials against the host PAM stack (`internal/pamauth`, `/etc/pam.d/<pam_service>`), so
on an SSSD/LDAP-joined host users authenticate with their normal login password and no
directory schema is needed in uopi. Successful logins are memoised in a short-TTL salted-hash
cache (`credCache`) to avoid a PAM round-trip per request, and the validated username is
written into the same `userHeader`. PAM requires a cgo build (`make backend-pam`, build tag
`pam`); the default static binary uses a stub that refuses Basic auth. As a **pure-Go**
alternative that keeps the fully-static (`CGO_ENABLED=0`) binary, `[server.ldap]`
(`internal/ldapauth`) validates the same Basic credentials against an LDAP directory with a
"search then bind" — anonymously (or via a service `bind_dn`) locate the user entry under
`search_base`, then bind as its DN with the supplied password — mirroring an SSSD/LDAP
client (defaults: `user_attr=uid`, `user_object_class=posixAccount`). Empty passwords are
rejected before any bind to avoid LDAP "unauthenticated bind", and the login name is
filter-escaped against injection. The challenge front-end is shared: both PAM and LDAP feed
the same `basicAuth` middleware, and the page load (`/`) is challenged too so the browser's
native login dialog actually appears (a background `fetch('/me')` 401 does not prompt).
Because Basic credentials are sent on every request, uopi can terminate **TLS** itself
(`[server.tls]` → `ListenAndServeTLS`) without a reverse proxy; an optional
`redirect_from` plain-HTTP listener 301-redirects `http://` visitors to the HTTPS service
so they are upgraded instead of hitting the TLS port with cleartext ("client sent an HTTP
request to an HTTPS server"). The four identity sources
(proxy header, Kerberos, PAM-Basic, LDAP-Basic) all resolve to the same `userHeader` and are
mutually exclusive where they overlap. Access is **role-based** through group
memberships: each `[[groups]]` block lists members by role along the cumulative ladder
`viewer < operator < logiceditor < auditor < admin`, and a user's **effective** global
capability is the highest role across all their memberships. Roles map to capabilities as:
operator+ → write (`Level` is derived, `LevelWrite` for operator+, else `LevelRead`);
logiceditor+ → `CanEditLogic`; auditor+ → `CanViewAudit`; admin → `CanAdmin`.
`accessMiddleware` gates mutating HTTP methods by the derived global level. Per-panel
ownership and ACL evaluation (with folder inheritance) live in `internal/panelacl`, backed
by the `acl.json` sidecar.
A built-in **public** group is always present: every user (and anonymous) is an implicit
viewer member, so an identified caller is at least read-only. Groups may **nest** via a
`parent` pointer (a forest rooted at top-level groups); a member of a parent group inherits
its role on every descendant group too, unless overridden lower. Cycles are rejected
(offending parent dropped to root), and the public group is protected from rename, reparent,
and delete. As a bootstrap convenience, a `Policy` with **no roles assigned anywhere** is
treated as unconfigured → fully open (everyone is admin), matching trusted-LAN/dev use;
assigning any role switches to strict mode where unlisted users are read-only viewers.
The capability checks (`CanEditLogic`, `CanViewAudit`, `CanAdmin`) are surfaced to the
frontend through `/api/v1/me` (`canEditLogic`, `canViewAudit`, `canAdmin`) so the UI can
hide affordances. The `Policy` is seeded from the TOML config at startup but is
**runtime-mutable** through the admin pane. `Policy.EnablePersistence(storageDir)` points
it at an `access.json` sidecar; once any admin mutation is made, that file is written (tmp +
atomic rename) and, on a later startup, supersedes the TOML access config (which then only
bootstraps an empty install). All policy state is guarded by an `RWMutex` (reads share,
mutations are exclusive and persist), keeping the shared `*Policy` pointer wiring intact.
The admin REST routes live under `/api/v1/admin/*` (all `requireAdmin`-gated):
`GET /admin/access` returns an `AccessSnapshot` (users with effective role + per-group
roles, groups with members and parents, the role ladder, and the configured flag);
`PUT /admin/users/{user}` replaces a user's full set of per-group roles (body
`{roles: {group: role}}`, creating missing groups); `POST|PUT|DELETE /admin/groups[/{name}]`
create (name + optional parent), rename + set parent and member roles, and delete groups;
and `GET /admin/stats` reports live server statistics (the `internal/metrics` counters via
`metrics.Snapshot`, the broker's observed-signal count and data-source list, Go runtime
stats, and the Linux `/proc/loadavg` load average). The frontend `AdminPane.tsx` (a modal
opened from the view-mode Tools dropdown when `canAdmin`) presents Users (per-group role
assignment with an effective-role badge), Groups (nesting + per-member roles), and
Server-stats tabs.
#### Visibility scope (selector-tree filtering)
Every user-owned, list-able object — panels, synthetic signals, config sets/instances, and
control-logic graphs — carries a uniform **visibility scope** so each selector tree can be
filtered by **Mine / Group / Global**. The model is `owner` (stamped server-side from the
trusted identity on create, immutable across updates) plus a scope token
`∈ {private, group, global}` and, for group scope, a list of group names. An empty or
unknown token resolves to **global**, so legacy objects with no scope stay visible to
everyone. This is a *visibility filter*, not a hard security boundary: an owner always sees
their own objects regardless of scope, and the per-panel ACL (§3.10) remains the real
access-control mechanism for panels.
The shared backend helper is `access.CanSee(user, owner, scope, itemGroups, userGroups)`
(`internal/access/scope.go`), with a `(*Policy).CanSee` method that resolves the caller's
groups via `GroupsOf`. Each list endpoint filters its results through it:
`internal/confmgr` stores `owner/scope/groups` on sets and instances (filtered by
`filterConfigMetas`); synthetic `SignalDef` gained a `group` visibility mode routed through
`synVisible`; control-logic `Graph` carries `owner/scope/scopeGroups` (named to avoid the
pre-existing cosmetic `Groups []NodeGroup`) filtered in `listControlLogic`. Panels reuse the
existing ACL rather than a new field: `panelScope` (`internal/api/api.go`) derives the
bucket from the ACL record (public → global, a group grant → group, otherwise → private;
unmanaged → global) and surfaces it on `InterfaceListItem.scope`/`groups`.
The shared frontend lib is `web/src/lib/scope.tsx`: `bucketOf` assigns an item to exactly
one bucket (owned → mine, else group-scoped → group, else global), `filterByScope` narrows a
list to the active bucket (with an optional groups-accessor for control-logic's
`scopeGroups`), `ScopeFilter` is the segmented `[Mine | Group ▾ | Global]` selector shown
above each tree (the Group segment carries a combo to pick a group when the user is in
several), and `ScopePicker` is the create/save visibility editor. `ConfigManager.tsx`,
`SyntheticGraphEditor.tsx`, and `ControlLogicEditor.tsx` use the picker to set scope on save;
panel visibility is instead edited through the existing Share dialog. `InterfaceList.tsx`
applies the filter to its folder tree, hiding folders that have no in-scope descendant.
### 3.11 Configuration Manager
The configuration manager is `internal/confmgr`: a two-tier model of **sets** (typed
parameter schemas binding target signals) and **instances** (values for a chosen set).
`model.go` defines `ConfigSet`/`Parameter`/`ConfigInstance`; `apply.go` validates an
instance against its set (`checkValue`) and writes each value to its target signal,
returning a per-parameter apply report; `diff.go` produces the structural per-parameter
diff used by the `/config/{sets,instances}/diff` endpoints.
`store.go` persists each object as `configs/{sets,instances,rules}/{id}.json`, with superseded
revisions backed up as `{id}.vN.json` alongside — the same git-style scheme as panels and
synthetic/control-logic, so `Versions`/`GetVersion`/`Promote`/`Fork` behave identically.
`Delete` is non-destructive: the object and all its backups are moved to a timestamped
`trash/configs/…` folder.
**CUE rules (`cue.go`, `KindRule`).** A third versioned object type carries a CUE source
(`cuelang.org/go`) bound to a set via `SetID`. `EvaluateRule` compiles the source, unifies it
with the instance values (`ctx.Encode`), and validates with `cue.Concrete(true)`: regular
fields whose key matches a parameter constrain its value (failures become `RuleViolation`s),
while concrete derivations whose value differs from the input are reported (and persisted) as
**transformations**; hidden fields `_x` and definitions `#X` are helpers, excluded from both.
`CreateInstance`/`UpdateInstance` call `applyRules` after the structural `ValidateAgainst`:
all rules bound to the set are run in order (`evaluateRules`), a violation aborts the save as
a `*RuleError`, and successful transformations are merged back into the stored values (set
parameters only). `ValidateInstanceRules` is the read-only counterpart behind
`/config/instances/{id}/validate`; `EvaluateRule` is exposed directly via
`/config/rules/check` for the live editor.
### 3.12 Document Versioning
Versioning is implemented per storage layer but follows one shared contract: the live
revision lives in the primary file; each save backs up the previous revision as
`{id}.v{N}.{ext}`; `VersionMeta{Version,Name,Tag,Current,SavedAt}` describes each. `Promote`
re-saves an older revision on top (creating a new current revision, never destroying
history); `Fork` writes the revision out under a fresh id with its version reset to 1. The
frontend `web/src/VersionHistory.tsx` (`VersionTree` + `DiffViewer`) consumes these
generically; line diffs are computed client-side in `web/src/lib/linediff.ts`, while
config sets/instances use the backend structural diff instead. Config **rules** reuse the
generic client-side `DiffViewer` (line diff over the source).
---
## 4. Frontend Architecture
### 4.1 WebSocket Client (`lib/ws.ts`)
- Singleton WebSocket connection, reconnects with exponential back-off.
- Subscription reference counting: multiple widgets subscribing to the same signal result in one server subscription message.
- Incoming updates are dispatched to per-signal stores.
- `wsClient.history(sig, start, end, maxPoints)` returns a Promise resolving to timestamped point arrays.
### 4.2 Signal Stores (`lib/stores.ts`)
```typescript
// One nanostores atom per subscribed signal
const signalStores = new Map<string, SignalStore>();
export function getSignalStore(ref: SignalRef): SignalStore { ... }
export function getMetaStore(ref: SignalRef): MetaStore { ... }
```
Widgets subscribe to stores directly; store updates trigger re-renders only in the consuming component.
### 4.3 Edit Mode Canvas (`EditCanvas.tsx`)
The edit canvas is a free-form HTML div with absolutely positioned widget components:
- Each widget renders as an absolutely positioned `<div>` at `(x, y)` with `(w, h)` dimensions.
- Selection shows a CSS-outlined bounding box with 8 resize handles rendered as small squares.
- Drag-and-drop from the signal tree uses the HTML Drag-and-Drop API; on drop, the canvas coordinate is computed from the drop event offset.
- Undo/redo uses an array of past interface snapshots (max depth 50).
- Align/distribute operations compute target positions geometrically and generate a single undo entry.
- Multi-select via Ctrl+click or rubber-band area select.
### 4.4 Widget Rendering in View Mode (`Canvas.tsx`)
View mode renders widgets as absolutely positioned Preact components on a scrollable canvas div:
- Each widget subscribes to its signal store(s) in a `useEffect` and re-renders only when values change.
- uPlot (time series) and ECharts (histogram, bar, FFT, waterfall, logic analyser, waveform) manage their own canvas elements inside their widget component. The `waveform` plot renders a waveform (array) signal's latest `[]float64` as an x-vs-index trace, replacing the trace on each update.
- 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 Panels (`SplitLayout.tsx`, `PlotPanelCanvas.tsx`)
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):
- 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
Both edit and view modes support mouse-drag panel resizing:
- **View mode**: drag handle between the interface list pane and the main content area.
- **Edit mode**: drag handles on both sides of the central canvas (signal tree ↔ canvas, canvas ↔ properties pane).
- Handle width: 5 px, cursor changes to `ew-resize` on hover.
- Minimum panel widths enforced to prevent collapse below usable size.
### 4.7 HiDPI / Zoom Support
- `html { font-size: clamp(13px, 1.5vh, 18px); }` — base font scales with viewport height, making the UI naturally larger on 4K screens where the browser zoom level is 100%.
- Key structural heights (toolbar, panel headers, tab bar, plot toolbar) are expressed in `rem` so they scale with the base font.
- **ZoomControl** (A− / % / A+) in the toolbar lets users manually override the zoom level in 11 steps from 50% to 250%. The preference is persisted in `localStorage` (`uopi:ui-zoom`) and applied by setting `document.documentElement.style.fontSize` on load.
- The root font-size also folds in `window.devicePixelRatio` (`applyZoom` → `16 × zoom × dpr`) so high-DPI displays auto-scale the UI by default; Firefox in particular does not enlarge the root px on its own, so the DPR must be applied explicitly. `watchDpr()` re-applies the zoom when the ratio changes (e.g. the window moves to a differently-scaled monitor).
- Canvas pixel rendering (uPlot, ECharts) reads `window.devicePixelRatio` and sizes canvases accordingly.
### 4.8 Lua Editor (`LuaEditor.tsx`)
A syntax-highlighted code editor for Lua scripts in the Synthetic signal wizard:
- Implemented as a `<textarea>` overlaid on a `<pre>` element; the textarea has `color: transparent; caret-color: #e2e8f0` so only the caret is visible — the `<pre>` provides the coloured text behind it.
- Tokeniser handles: `--` line comments, `"..."` / `'...'` string literals, `[[...]]` long strings, hex and float numeric literals, and all Lua 5.1 keywords.
- Scroll position is synchronised between textarea and pre on every scroll event.
---
## 5. Build System
### 5.1 Backend
```bash
# Full build (frontend then backend)
make all
# Backend only (frontend must already be built)
make backend
# All tests
make test
# Single Go test
go test ./internal/broker/... -run TestFanOut
# Go vet
go vet ./...
```
EPICS `libca.a` is statically linked via `CGO_LDFLAGS` in `internal/datasource/epics/cgo.go`.
### 5.2 Frontend
The frontend is built by a Go tool in `tools/buildfrontend/` that invokes the esbuild Go API:
```bash
make frontend
# or equivalently:
go generate ./web/...
```
No Node.js, npm, or any JS build tool is required on the host. The bundler:
- Reads entry point `web/src/main.tsx`.
- Resolves `preact`, `uplot`, and `echarts` imports from `web/vendor/`.
- Outputs `web/dist/main.js` and `web/dist/main.css`.
- Copies `web/dist/index.html`, vendor CSS, and other static assets.
### 5.3 Combined Build
```makefile
.PHONY: all frontend backend clean
all: frontend backend
frontend:
go run ./tools/buildfrontend
backend:
CGO_ENABLED=1 go build -ldflags="-s -w" -o dist/uopi ./cmd/uopi
test:
go test ./...
clean:
rm -rf dist/ web/dist/
```
The backend's `//go:embed dist` directive in `web/embed.go` picks up the built frontend automatically. `main.go` does `fs.Sub(web.FS, "dist")` to serve a clean root.
---
## 6. Configuration
Server is configured via a TOML file (default: `uopi.toml`, overridable via `--config` flag):
```toml
[server]
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)
# Native SPNEGO/Kerberos auth — alternative to a proxy; identifies users from
# their Kerberos ticket. Recommended when some browsers (e.g. Firefox) would
# otherwise fall through to default_user.
# [server.kerberos]
# enabled = true
# keytab = "/etc/uopi/http.keytab" # HTTP/host@REALM service key
# service_principal = "HTTP/host.example.com" # optional; empty = keytab default
# Built-in HTTP Basic auth (PAM) — standalone, mutually exclusive with Kerberos.
# Requires a PAM build: `make backend-pam`. Enable TLS below for production.
# [server.basic_auth]
# enabled = true
# pam_service = "uopi" # /etc/pam.d/<name>; empty = "uopi"
# Built-in HTTP Basic auth (LDAP) — pure-Go, works in the static binary; search
# then bind against the directory. Mutually exclusive with kerberos/basic_auth.
# [server.ldap]
# enabled = true
# uri = ["ldaps://ldap.example.com"]
# search_base = "dc=example,dc=com"
# user_attr = "uid" # "sAMAccountName" for AD; empty = uid
# bind_dn = "" # empty = anonymous search
# Built-in TLS/HTTPS — terminate HTTPS without a reverse proxy. Recommended
# whenever basic_auth is enabled. Both cert and key required when enabled.
# [server.tls]
# enabled = true
# cert = "/etc/uopi/tls/cert.pem"
# key = "/etc/uopi/tls/key.pem"
# Role-based access through group memberships. Roles (low→high):
# viewer < operator < logiceditor < auditor < admin
# Effective capability = highest role across all memberships. The built-in
# "public" group makes every user an implicit viewer. Groups may nest via
# "parent" (members inherit their role on descendants). No roles anywhere = open
# (everyone admin); once set, unlisted users are read-only viewers.
# [[groups]]
# name = "public"
# admins = ["alice"] # alice is a global admin
# [[groups]]
# name = "operations"
# operators = ["bob"]
# auditors = ["carol"]
# [[groups]]
# name = "engineers"
# parent = "operations" # bob inherits operator here
# logiceditors = ["dave"]
# viewers = ["erin"]
[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
```
All settings can also be overridden with `UOPI_*` environment variables (e.g.
`UOPI_SERVER_LISTEN`, `UOPI_EPICS_CA_ADDR_LIST`).
---
## 7. Testing Strategy
| Layer | Approach |
| ------------------ | --------------------------------------------------------------------------------- |
| Broker | Unit tests with mock data source; verify fan-out, subscribe/unsubscribe lifecycle |
| Synthetic DSP | Table-driven unit tests against known signal inputs/outputs |
| Low-pass filter | Unit tests: step response, frequency attenuation vs. analytical expectation |
| Lua sandbox | Unit tests for sandbox isolation and API surface |
| REST API | `httptest` integration tests |
| WebSocket protocol | Integration tests with a test client |
| EPICS data source | Integration tests against a local SoftIOC (optional, CI-gated) |
---
## 8. Security Considerations
- 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.
- **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.
Authorisation is role-based through group memberships (viewer/operator/logiceditor/
auditor/admin), with the highest role across memberships deciding global capability;
per-panel ACLs provide finer per-panel control. When **no** roles are assigned anywhere
the deployment is fully open (everyone admin), preserving the unproxied/SSH-tunnel/dev
model; once any role is set, unlisted and anonymous callers are read-only viewers.
---
## 9. Non-goals (v1)
- 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.
- Remote plugin loading (plugins compiled in at build time only).
Reference in New Issue View Git Blame Copy Permalink