@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 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/wsAuthManager.ts`. A short grace
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