@ndmspc/ndmspc-ui 0.0.1-rc.1 → 1.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +291 -1
- package/dist/index.d.ts +5155 -1
- package/dist/index.esm-BKHn5Ggt.js +22017 -0
- package/dist/keycloak-dpop-CdpifFv5.js +239 -0
- package/dist/ndmspc-ui.css +2 -2
- package/dist/ndmspc-ui.es.js +28712 -153
- package/package.json +33 -29
package/README.md
CHANGED
|
@@ -23,13 +23,296 @@ each WebSocket connection must authenticate before it can exchange traffic:
|
|
|
23
23
|
3. when the Keycloak token is refreshed, the UI re-authenticates on the same
|
|
24
24
|
connection (the refreshed token must keep the same JWT `sub`).
|
|
25
25
|
|
|
26
|
-
This handshake is implemented in `src/lib/
|
|
26
|
+
This handshake is implemented in `src/lib/room/NdmspcWsClient.ts`. A short grace
|
|
27
27
|
period distinguishes anonymous servers (they send `welcome` immediately) from
|
|
28
28
|
auth-enabled ones (they stay silent until authenticated), so servers started
|
|
29
29
|
without Keycloak keep working with no code change. When a server demands
|
|
30
30
|
sign-in and no valid session exists, the UI shows a **Sign in to connect**
|
|
31
31
|
action and starts the Keycloak login flow.
|
|
32
32
|
|
|
33
|
+
## Library authentication
|
|
34
|
+
|
|
35
|
+
`@ndmspc/ndmspc-ui` ships a modular authentication layer supporting Keycloak
|
|
36
|
+
(including **brokered** identity providers), **direct OIDC** providers and x509
|
|
37
|
+
client certificates. The parts can be imported independently:
|
|
38
|
+
|
|
39
|
+
- `NdmspcAuthService` — framework-agnostic service, usable without React via
|
|
40
|
+
`getState()` / `subscribe()`.
|
|
41
|
+
- `NdmspcAuthProvider` + `useNdmspcAuth()` — React bindings; the hook exposes
|
|
42
|
+
`options` (the sign-in choices) alongside the state.
|
|
43
|
+
- `NdmspcLogin` — full-page sign-in gate that lists the configured options.
|
|
44
|
+
- `NdmspcUserInfo` — component that renders the current user / sign-in actions.
|
|
45
|
+
- `NdmspcApp` — the Next app shell; pass it an `auth` config to gate it behind
|
|
46
|
+
`NdmspcLogin`.
|
|
47
|
+
|
|
48
|
+
The library reads **no** environment variables; the application passes its
|
|
49
|
+
configuration in. Provider setup (Keycloak brokering, direct CERN SSO, Google,
|
|
50
|
+
x509) is documented in [`src/lib/auth/README.md`](src/lib/auth/README.md).
|
|
51
|
+
|
|
52
|
+
```tsx
|
|
53
|
+
import { NdmspcAuthProvider, NdmspcLogin } from "@ndmspc/ndmspc-ui";
|
|
54
|
+
|
|
55
|
+
<NdmspcAuthProvider
|
|
56
|
+
config={{
|
|
57
|
+
providers: [
|
|
58
|
+
// Official ndmspc Keycloak. `identityProviders` are IdPs already brokered
|
|
59
|
+
// in the realm; each becomes an extra button (kc_idp_hint) and still
|
|
60
|
+
// yields a token issued by this Keycloak.
|
|
61
|
+
{
|
|
62
|
+
id: "ndmspc",
|
|
63
|
+
label: "NDMSPC",
|
|
64
|
+
kind: "keycloak",
|
|
65
|
+
url: "http://keycloak.127.0.0.1.sslip.io:8009",
|
|
66
|
+
realm: "ndmspc-dev",
|
|
67
|
+
clientId: "ndmspc-dev-client",
|
|
68
|
+
identityProviders: [
|
|
69
|
+
{ alias: "cern", label: "CERN" },
|
|
70
|
+
{ alias: "google", label: "Google" },
|
|
71
|
+
],
|
|
72
|
+
},
|
|
73
|
+
// Direct OIDC (e.g. CERN SSO), bypassing the broker. The code→token
|
|
74
|
+
// exchange happens in the browser, so the client must allow CORS for this
|
|
75
|
+
// app's origin.
|
|
76
|
+
{
|
|
77
|
+
id: "cern",
|
|
78
|
+
label: "CERN",
|
|
79
|
+
kind: "oidc",
|
|
80
|
+
issuer: "https://auth.cern.ch/auth/realms/cern",
|
|
81
|
+
clientId: "ndmspc-ui",
|
|
82
|
+
},
|
|
83
|
+
// x509: an HTTPS endpoint that requires the client certificate.
|
|
84
|
+
{ id: "x509", label: "X.509", kind: "x509", probeUrl: "https://host/api/auth/x509" },
|
|
85
|
+
],
|
|
86
|
+
}}
|
|
87
|
+
>
|
|
88
|
+
<NdmspcLogin />
|
|
89
|
+
</NdmspcAuthProvider>;
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
`init()` performs **no** automatic redirect (`keycloak.onLoad` is unset), so the
|
|
93
|
+
user signs in explicitly. Set `keycloak.onLoad` to `"check-sso"` (add
|
|
94
|
+
`silentCheckSsoRedirectUri` to avoid a full redirect) or `"login-required"` to
|
|
95
|
+
opt into automatic SSO. x509 is probed on load only when `x509.autoProbe` is
|
|
96
|
+
set. A direct-OIDC redirect is completed automatically when the browser returns
|
|
97
|
+
with a `?code=` / `?state=` callback — direct providers use the URL **query**
|
|
98
|
+
while Keycloak uses the **fragment**, so the two never interfere.
|
|
99
|
+
|
|
100
|
+
In this repo the demo derives that config from `.env.local`: `VITE_KEYCLOAK_*`
|
|
101
|
+
plus `VITE_KEYCLOAK_IDPS="cern|CERN,google|Google"` for brokered buttons, direct
|
|
102
|
+
CERN via `VITE_CERN_OIDC_ISSUER` / `VITE_CERN_OIDC_CLIENT` (optional
|
|
103
|
+
`VITE_CERN_OIDC_TOKEN_ENDPOINT` to route the exchange through a proxy), and
|
|
104
|
+
`VITE_X509_PROBE_URL`. The Next view (`NdmspcApp`) is gated behind
|
|
105
|
+
`NdmspcLogin`.
|
|
106
|
+
|
|
107
|
+
## Room management
|
|
108
|
+
|
|
109
|
+
`NdmspcApp` (the Next view) shows the **NDMSPC Rooms** management UI. It drives the
|
|
110
|
+
ndmspc room router over the same MCP endpoint as the `ndmspc-room-tui` client
|
|
111
|
+
(`POST {base}/api/mcp`, tools `room_list` / `room_open` / `room_status` /
|
|
112
|
+
`room_close` / `room_backup` / `room_restore`), so the two always show the same
|
|
113
|
+
registry — a room created in the TUI appears in the UI and vice versa. It lists the
|
|
114
|
+
router's rooms with their live state (`preparing`, `waiting` for cluster resources,
|
|
115
|
+
`idle`, `active`, `failed` / `killed`), creates and deletes rooms — a room it creates
|
|
116
|
+
is selected as soon as the router registers it, so the pane shows it while it is still
|
|
117
|
+
being prepared — shows each room's client (`?room=`) and WebSocket URLs, exports/imports
|
|
118
|
+
rooms (the whole set, or one room on its own), and polls every 2 s (pausable). A room the
|
|
119
|
+
cluster has no room for is `pending` on the wire and reads as **waiting** in the view (the router's vocabulary is the
|
|
120
|
+
API's; the view keeps one word per state, in the table and the panes alike): it is kept and
|
|
121
|
+
comes up on its own once there is room for its pod, and its **Enter** button stays disabled
|
|
122
|
+
until then.
|
|
123
|
+
|
|
124
|
+
**Restoring reviews the document before it creates anything.** Choosing a backup file opens a dialog
|
|
125
|
+
with what it holds — each room, whose it is, whether a session comes back with it, and the router it
|
|
126
|
+
was exported from — and the restore runs only when confirmed. A room the router already has is the one
|
|
127
|
+
choice worth making: `replace them` (the default when there is one) deletes it first, so the document's
|
|
128
|
+
session is what it comes back holding, while `keep them` leaves it as it is — a room in use keeps its
|
|
129
|
+
own session, and only the missing rooms are created. While it runs the dialog says so (the router
|
|
130
|
+
creates each room and waits for its revision, so it takes a while), and when it finishes each room is
|
|
131
|
+
marked `restored`, `live` (left alone) or `failed` with the router's own reason. Rooms the document
|
|
132
|
+
does not name are untouched either way.
|
|
133
|
+
|
|
134
|
+
**One room's configuration exports, and imports, on its own.** The selected room's pane carries
|
|
135
|
+
**Export** — writing that room's _configuration_: the file it opened, the steps that were run, the size
|
|
136
|
+
it was created at and what is on screen, and nothing at all about the room (no id, no owner, no link) —
|
|
137
|
+
and **Import**, which puts a configuration somebody handed you into the selected room. Since nothing in
|
|
138
|
+
the file reaches back into the room it came from, it is simply something to pass on: the person
|
|
139
|
+
importing it gets a room of their own, at the size the configuration names, holding that work.
|
|
140
|
+
|
|
141
|
+
An import is all or nothing: the room is deleted if it is there and created again carrying the
|
|
142
|
+
configuration, because a room takes its session once, as it starts, so there is nothing to merge into.
|
|
143
|
+
The dialog says as much before it runs, and a configuration can also be attached while creating a room,
|
|
144
|
+
which is the same operation — the room comes up holding that work rather than empty. Only a file is
|
|
145
|
+
read (nothing is fetched over the network), and a size the deployment does not offer is refused before
|
|
146
|
+
anything is deleted.
|
|
147
|
+
|
|
148
|
+
The library reads no environment variables, so the app supplies the router URL: set
|
|
149
|
+
`VITE_NDMSPC_ROOM_URL` (empty/omitted = the UI's own origin). A cross-origin router
|
|
150
|
+
must answer the CORS `OPTIONS` preflight for `POST /api/mcp`, including the
|
|
151
|
+
`Authorization` header — the istio front door in front of the ndmspc router does; a
|
|
152
|
+
bare ROOT server only sets `Access-Control-Allow-Origin`, so serve the UI from the
|
|
153
|
+
router's own origin in that case.
|
|
154
|
+
|
|
155
|
+
The parts are reusable on their own:
|
|
156
|
+
|
|
157
|
+
- `NdmspcRoomClient` — the MCP transport (list/open/status/close/backup/restore/import).
|
|
158
|
+
- `NdmspcRoomService` — framework-agnostic polling store (`getState()` / `subscribe()`).
|
|
159
|
+
- `useNdmspcRooms()` — React binding for the service.
|
|
160
|
+
- `NdmspcRooms` — the ready-made management component.
|
|
161
|
+
|
|
162
|
+
```tsx
|
|
163
|
+
import { NdmspcRooms } from "@ndmspc/ndmspc-ui";
|
|
164
|
+
|
|
165
|
+
// Same-origin, or point it at the router:
|
|
166
|
+
<NdmspcRooms baseUrl="http://localhost:8080" refreshSeconds={2} />;
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
**Room links carry an access token.** A room the router gave tokens to refuses traffic without one,
|
|
170
|
+
so the URLs the detail pane shows carry the token of the level being looked at: `read-write`
|
|
171
|
+
(anything) or `read-only` (GET only — a non-GET is refused with
|
|
172
|
+
`{"result": "failure", "code": "read_only"}`). The tokens arrive as `access` on a room (`rw` / `ro`),
|
|
173
|
+
and the pane's `link` switch picks which one is appended and labels the rows `(rw)` / `(ro)`, so the
|
|
174
|
+
link that gets handed on is chosen where it is copied. A room that reports no `access` — one created
|
|
175
|
+
before this existed — enforces nothing, and then the switch is not shown and the URLs stay as they
|
|
176
|
+
were; the same tokens and the same switch are in `ndmspc-room-tui`, so both views hand out the same
|
|
177
|
+
link.
|
|
178
|
+
|
|
179
|
+
**The links are absolute, and the page URL can be handed on.** The pane resolves a relative base
|
|
180
|
+
against the page's own origin, so with an empty `VITE_NDMSPC_ROOM_URL` — the UI served from the
|
|
181
|
+
router — the page URL reads `http://host/?room=…&token=…&access=…` instead of a bare `?room=…`, and
|
|
182
|
+
the api and websocket URLs carry that host too. The page URL is the room's _own_ page (the router
|
|
183
|
+
sends a request carrying `?room=` to that room, which serves this page), so opening it in another
|
|
184
|
+
browser lands in the room: `NdmspcRoomLink` reads the parameters on load, signs the visitor in first
|
|
185
|
+
when a sign-in method is configured (the link survives the provider redirect) and then opens the room
|
|
186
|
+
at the level the link names — a read-only link lists no tools rather than asking for them, and the
|
|
187
|
+
room refuses the page when `access` disagrees with `token`, so an edited level does not open. `Back`
|
|
188
|
+
returns to the app and drops the parameters, token included. Set `VITE_NDMSPC_ROOM_LINK_ENABLED=false`
|
|
189
|
+
to ignore a link and always open the app's own views; the component is exported for an app that
|
|
190
|
+
mounts its own shell:
|
|
191
|
+
|
|
192
|
+
```tsx
|
|
193
|
+
<NdmspcRoomLink authService={auth} baseUrl={routerUrl}>
|
|
194
|
+
<App />
|
|
195
|
+
</NdmspcRoomLink>
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
**The room's name shows what the router knows about it.** In the single-room view the name is a
|
|
199
|
+
button: it opens the router's account of that room — owner, revision, state, pods, profile, cpu/memory,
|
|
200
|
+
last seen, expiry, and why its container last died — the same fields the rooms pane shows, read from
|
|
201
|
+
the router (`room_list`) when the panel opens. The router answers with the rooms its caller may see
|
|
202
|
+
(its owner, or every room for an admin), so a room it does not list for you is said to be exactly
|
|
203
|
+
that rather than shown as empty. A room whose `/api` URL names no id (`?room=`) has nothing to ask
|
|
204
|
+
about, and there the name stays a plain title.
|
|
205
|
+
|
|
206
|
+
**Rooms belong to whoever creates them, and the view shows only what its user may see.** A room's
|
|
207
|
+
`owner` arrives with it (a user name, or an email when that is all a token carries; absent for a room
|
|
208
|
+
created before ownership existed), and it is part of the room's id — `mine` created by `alice` is
|
|
209
|
+
`alice-mine`, so the same id can be somebody else's room too. The view claims the identity it has with
|
|
210
|
+
every request, and claims _both_ names when it has both (the signed-in user's user name and email),
|
|
211
|
+
because the router matches a caller on either while the owner it sends is what names its rooms. The
|
|
212
|
+
router then answers with that owner's rooms only, so a non-admin sees the rooms they created — and the
|
|
213
|
+
detail pane refuses rather than offers anything else — while an admin sees every room, with an
|
|
214
|
+
`OWNER` column, an `owner` row to say whose each one is, and an `admin` badge in the toolbar. The badge
|
|
215
|
+
is the router's own answer (`room_list` reports `admin`), not a second copy of the list kept here: with
|
|
216
|
+
OIDC the router is the only one that can really know. `room_open` is ensure, so re-creating a room is
|
|
217
|
+
not an error: it answers with the id it used and whether it created the room. With nobody signed in the
|
|
218
|
+
view has no identity at all, which the router answers with every room, exactly as it answers a script;
|
|
219
|
+
an app that knows its user by some other means can say so:
|
|
220
|
+
|
|
221
|
+
```tsx
|
|
222
|
+
<NdmspcRooms
|
|
223
|
+
baseUrl="http://localhost:8080"
|
|
224
|
+
admins={["you@example.com"]} // VITE_NDMSPC_ROOM_ADMINS; emails or user names
|
|
225
|
+
currentUser="you@example.com" // VITE_NDMSPC_ANONYMOUS_USER; while nobody is signed in
|
|
226
|
+
/>
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
`currentUser` is the fallback for a view with no login: a claimed identity, since nothing verified it,
|
|
230
|
+
while a signed-in user always wins over it. It is what a deployment without OIDC sets so its rooms
|
|
231
|
+
still belong to someone — and what makes the owner column and the qualified ids appear at all there.
|
|
232
|
+
The router is what enforces everything (it holds the same list in `NDMSPC_ROOM_ADMINS`, and with no
|
|
233
|
+
OIDC configured an asserted owner is a convenience rather than a boundary); the view only shows what
|
|
234
|
+
comes back. `ndmspc-room-tui --owner <email>` acts the same way from a terminal.
|
|
235
|
+
|
|
236
|
+
### UI primitives (shadcn, on Base UI)
|
|
237
|
+
|
|
238
|
+
The library ships its own shadcn/ui primitives in `src/lib/components/ui/`
|
|
239
|
+
(`button`, `input`, `label`, `dialog`, `alert-dialog`, `tooltip`), generated for
|
|
240
|
+
**Base UI** (`@base-ui/react`); `radix-ui` backs only the ported `tabs` primitive.
|
|
241
|
+
They are **internal**: they back the library's components (the room dialogs and
|
|
242
|
+
tooltips) and are not exported from the package, so the public surface stays
|
|
243
|
+
small.
|
|
244
|
+
|
|
245
|
+
Consumers therefore need:
|
|
246
|
+
|
|
247
|
+
- `@ndmspc/ndmspc-ui/styles.css` loaded (the tokens and the Tailwind output live
|
|
248
|
+
there) and the `.dark` class on an ancestor for dark mode;
|
|
249
|
+
- the runtime dependencies declared by the package — `@base-ui/react`,
|
|
250
|
+
`class-variance-authority` and `lucide-react` are kept external, so they resolve
|
|
251
|
+
from your install rather than being duplicated inside the bundle.
|
|
252
|
+
|
|
253
|
+
`components.json` points the shadcn CLI at the library (`ui` →
|
|
254
|
+
`@/lib/components/ui`, `css` → `src/lib/index.css`, style `base-nova`), so
|
|
255
|
+
`npx shadcn add <component>` adds Base UI primitives next to the existing ones.
|
|
256
|
+
|
|
257
|
+
## Tutorial / Help
|
|
258
|
+
|
|
259
|
+
The library ships an in-app tutorial, `NdmspcTour`, mounted once near the app
|
|
260
|
+
root: a short **guided tour** that spotlights the real controls on a browser's
|
|
261
|
+
first visit, and a **Help panel** (opened from a corner button) that replays the
|
|
262
|
+
tour and carries a reference for **every tool the room offers**.
|
|
263
|
+
|
|
264
|
+
The tour never blocks the app — the spotlight highlights and explains, and the
|
|
265
|
+
user does the work (opening a dialog, filling it in, creating the room); the tour
|
|
266
|
+
follows along. A step may wait for something the user opens (`await`), move on by
|
|
267
|
+
itself once it appears (`advanceOn`), or run a tool (`run`).
|
|
268
|
+
|
|
269
|
+
The tool reference is generated from the room's own `tools/list` — its titles,
|
|
270
|
+
descriptions, HTTP methods, argument schemas and declared prerequisites — so a
|
|
271
|
+
tool the UI has never heard of appears in full with no UI change. Nothing about
|
|
272
|
+
any tool is written into the app.
|
|
273
|
+
|
|
274
|
+
```tsx
|
|
275
|
+
import { NdmspcTour } from "@ndmspc/ndmspc-ui";
|
|
276
|
+
|
|
277
|
+
// Mount once, beside the boot splash / activity overlay / notifications:
|
|
278
|
+
<NdmspcTour
|
|
279
|
+
showOn={["rooms"]} // offered only on the rooms view (the workflow it teaches)
|
|
280
|
+
availableViews={["room", "rooms", "tools"]} // steps of absent views are dropped
|
|
281
|
+
view={activeView}
|
|
282
|
+
onNavigate={(key) => setActiveView(key)} // lets a step switch to its own view
|
|
283
|
+
/>;
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
A step is plain data (`{ id, title, body, target, view, when, run }`): `target` is a
|
|
287
|
+
`data-tour` attribute on the control to spotlight, `view` the service it lives on,
|
|
288
|
+
and `when(context)` gates it (the default steps show the room-list ones while no
|
|
289
|
+
room is open and the in-room ones once one is). The store (`setTourContext`) is how
|
|
290
|
+
a mounted room tells the tour what it advertises — its tools, live form defaults and
|
|
291
|
+
combination — and `setTourRunner` gives the tour a way to invoke a tool.
|
|
292
|
+
|
|
293
|
+
**Per-tool guided tour.** A tool declares its own tour on the server
|
|
294
|
+
(`_meta["ndmspc.io/tutorial"]`): a **name**, a **description** of what it does, and the
|
|
295
|
+
steps to walk. The Help → Tools reference lists every tool that declares one with a
|
|
296
|
+
**Tour** button, and so does the Inspector when the shown group has no session yet —
|
|
297
|
+
offered by the tour's own name and description rather than by the tool's name, so what
|
|
298
|
+
you pick is what the tour does ("Browse hsimple.root file — Open the hsimple.root sample
|
|
299
|
+
and draw a few of its objects"). The UI walks the steps as declared: it points at
|
|
300
|
+
**Save & Run**
|
|
301
|
+
(or at the object to click, or at the pads) and the user runs each one — nothing is run
|
|
302
|
+
for them, and a step that names an object moves on when the object draws. Nothing about
|
|
303
|
+
any tool is written in the UI — a new tool gets a tour the moment it declares one.
|
|
304
|
+
|
|
305
|
+
The demo app wires it in `src/app/NdmspcAppSwitch.tsx`. Two environment
|
|
306
|
+
variables (documented in `.env.example`):
|
|
307
|
+
|
|
308
|
+
- `VITE_NDMSPC_TOUR_ENABLED` — offer the tutorial at all (default on);
|
|
309
|
+
- `VITE_NDMSPC_TOUR_FORCE` — show the guided tour on every load, ignoring the
|
|
310
|
+
browser's "already seen" memory (for testing).
|
|
311
|
+
|
|
312
|
+
First-access memory is per browser, under `localStorage`
|
|
313
|
+
`ndmspc:tour:<version>:done`, so bumping the tour's `version` shows it again to
|
|
314
|
+
everyone.
|
|
315
|
+
|
|
33
316
|
## Install dependencies
|
|
34
317
|
|
|
35
318
|
```bash
|
|
@@ -52,6 +335,13 @@ npm run dev
|
|
|
52
335
|
npm run build:page # -> page-dist/ (index.html, assets/, vite.svg)
|
|
53
336
|
```
|
|
54
337
|
|
|
338
|
+
The build stamps its version into `VITE_APP_VERSION` (from `package.json`, or from the environment
|
|
339
|
+
when a release pipeline sets it, e.g. `VITE_APP_VERSION=1.2.3 npm run build:page`). The **user menu**
|
|
340
|
+
shows that version under the token expiry (`UI v1.2.3`); the dev server shows `UI dev`, and a local
|
|
341
|
+
page build with no stamped version names the entry bundle it is running (`UI dev · index-….js`).
|
|
342
|
+
The room's **Server info** panel is
|
|
343
|
+
about the room, so it shows the ndmspc-server and ROOT versions there, never the UI version.
|
|
344
|
+
|
|
55
345
|
On every git tag the `build-page` job builds this page, tars it, and uploads it
|
|
56
346
|
to the Generic Package Registry under the tag; the `release-page` job then
|
|
57
347
|
attaches it to the tag's GitLab Release. ndmspc's CMake consumes it instead of
|