@ndmspc/ndmspc-ui 1.4.9 → 1.4.11

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/dist/index.d.ts CHANGED
@@ -873,6 +873,16 @@ export declare interface NdmspcDialog {
873
873
  options?: Record<string, unknown>;
874
874
  /** The action that previews this dialog's macro; the tab's own when the active tab names one. */
875
875
  macro?: string;
876
+ /**
877
+ * The action that **rebuilds this dialog from the form as it stands** — a field marked `refresh` was
878
+ * changed and the tool derives the rest again (a path's folder and the objects it holds, say). The
879
+ * form's values are sent with it.
880
+ */
881
+ refresh?: NdmspcRenderAction;
882
+ /** What the rebuilt form is: a client remounts on it rather than keeping values it no longer owns. */
883
+ revision?: string;
884
+ /** The tab to open on, by label: a refresh leaves the user on the tab they were working in. */
885
+ active?: string;
876
886
  /**
877
887
  * The combination the dialog was opened from, as the tool that opened it named it. Its form is submitted
878
888
  * into **that** session rather than whichever the room is showing: a redirect into another tool changes
@@ -2382,6 +2392,22 @@ export declare interface NdmspcRoomInfo {
2382
2392
  error: string;
2383
2393
  /** Failure code, e.g. `no_capacity` (a pending room reports it too). */
2384
2394
  code: string;
2395
+ /**
2396
+ * Whether an **idle** room could be started right now, as the router probed it (a room that is Ready
2397
+ * with no pod, which is the normal resting state). Absent when it was not probed.
2398
+ */
2399
+ wakeable?: boolean;
2400
+ /**
2401
+ * Whether an idle room is held up by **other rooms' terminating pods**: their reservations are still
2402
+ * held, so the cluster cannot place this room yet - it is waiting for them, not idle.
2403
+ */
2404
+ wakeWaiting?: boolean;
2405
+ /** Why an idle room cannot start now: the scheduler's message, or what the cluster is short of. */
2406
+ wakeError?: string;
2407
+ /** Epoch seconds the wake probe last ran. */
2408
+ wakeCheckedAt?: number;
2409
+ /** Epoch seconds a pending room started waiting for cluster resources (0/absent when it is not). */
2410
+ pendingSince?: number;
2385
2411
  /** Epoch seconds the creation began. */
2386
2412
  startedAt: number;
2387
2413
  /**
@@ -2487,6 +2513,21 @@ export declare interface NdmspcRoomList {
2487
2513
  rooms: NdmspcRoomInfo[];
2488
2514
  /** Idle TTL in seconds, after which a room is deleted. */
2489
2515
  ttl: number;
2516
+ /**
2517
+ * How long a room may wait for cluster resources before the router reports it failed (0 = for ever).
2518
+ * Absent for a router that does not bound the wait.
2519
+ */
2520
+ pendingTtl?: number;
2521
+ /**
2522
+ * The router process that answered, when it names itself.
2523
+ *
2524
+ * A push socket can outlive the rollout that replaced its router: the old pod keeps serving its
2525
+ * connections, and its registry can disagree with the one the polls reach (a room it still calls
2526
+ * pending may already be active in the new router). A view compares this with the last full list
2527
+ * and ignores a push from a different router rather than letting the row blink between the two.
2528
+ * Absent from a router that does not name itself.
2529
+ */
2530
+ instance?: string;
2490
2531
  /**
2491
2532
  * The pod profiles this deployment offers, by name, with what each one grants. Absent for a
2492
2533
  * deployment that offers none, in which case there is nothing to choose.
@@ -2539,6 +2580,14 @@ export declare interface NdmspcRoomOpen {
2539
2580
  session?: string;
2540
2581
  error?: string;
2541
2582
  code?: string;
2583
+ /** Whether an idle room could be started right now, and why not (see {@link NdmspcRoomInfo.wakeable}). */
2584
+ wakeable?: boolean;
2585
+ /** Whether the room is held up by other rooms' terminating pods (see {@link NdmspcRoomInfo.wakeWaiting}). */
2586
+ wakeWaiting?: boolean;
2587
+ wakeError?: string;
2588
+ wakeCheckedAt?: number;
2589
+ /** Epoch seconds a pending room started waiting for cluster resources (see {@link NdmspcRoomInfo.pendingSince}). */
2590
+ pendingSince?: number;
2542
2591
  /** The tokens that open the room; absent for a room that enforces nothing. */
2543
2592
  access?: NdmspcRoomAccess;
2544
2593
  /** Who the room belongs to, when the router knows (see {@link NdmspcRoomInfo.owner}). */
@@ -2805,6 +2854,19 @@ export declare class NdmspcRoomService {
2805
2854
  * remembered and the second call does nothing.
2806
2855
  */
2807
2856
  private sentTopics;
2857
+ /**
2858
+ * The router process the last full list came from ("" when it did not name itself).
2859
+ *
2860
+ * A push socket can outlive the rollout that replaced its router: the old pod keeps serving the
2861
+ * connections it already has, and its registry can disagree with the one the polls reach. The
2862
+ * view treats the poll as the truth and ignores pushes from any other process (see `applyPushed`).
2863
+ */
2864
+ private routerInstance;
2865
+ /**
2866
+ * The foreign router instances whose pushes have already been ignored and reconnected away from,
2867
+ * so a socket that lands on one again cannot make the view reconnect in a loop.
2868
+ */
2869
+ private readonly foreignPushes;
2808
2870
  /** The topics this view is showing: the rooms list, and the selected room's session. */
2809
2871
  private topics;
2810
2872
  /** The document listener that reads the list again when this view is shown (see below). */
@@ -2985,6 +3047,14 @@ export declare class NdmspcRoomService {
2985
3047
  private startWatcher;
2986
3048
  /** Closes the push socket (the interval carries on as the net under it). */
2987
3049
  private stopWatcher;
3050
+ /**
3051
+ * Closes a push socket that belongs to a router other than the one the polls reach, and opens a
3052
+ * new one through the route - which sends new connections to the router that is current now.
3053
+ *
3054
+ * The list is read first, so the view is right even if the socket cannot open; the interval is
3055
+ * scheduled as the net under it.
3056
+ */
3057
+ private reconnectWatcher;
2988
3058
  /**
2989
3059
  * Says what the view is showing, so the router pushes exactly that: the list, and one room's session.
2990
3060
  * Sent again when the set changes - the router replaces a socket's topics, so a room the view has
@@ -3034,12 +3104,12 @@ export declare class NdmspcRoomService {
3034
3104
  /**
3035
3105
  * How long to wait before reading the list again.
3036
3106
  *
3037
- * The push, when it is live, is what makes a change appear - so a watching view only needs the net
3038
- * under it. A room still being created is the exception: the push is one publish tick behind, and a
3039
- * create is the one moment its row matters, so the configured interval carries it even while
3040
- * watching. Without the push the same interval covers a room waiting for cluster resources; the
3041
- * list rarely changes by itself otherwise, and polling it hard spends the router's requests for
3042
- * nothing.
3107
+ * The push is registry-only: it reports a room being created or coming ready, but the **live** view
3108
+ * (replicas, active, and a pending room's convergence) comes from a full read. So a watching view
3109
+ * still needs a regular one, and while anything is unsettled it needs the configured interval:
3110
+ * a room waiting for resources is converged by the read, and an idle room the cluster could not
3111
+ * start changes the moment capacity frees. Otherwise 5s keeps a room that woke (or went idle) from
3112
+ * looking stuck for the old 20s floor.
3043
3113
  */
3044
3114
  private pollIntervalMs;
3045
3115
  private clearTimer;
@@ -3088,6 +3158,17 @@ export declare class NdmspcRoomSession {
3088
3158
  private sync;
3089
3159
  /** The wait recorded while the connection is being established (see `syncConnectionActivity`). */
3090
3160
  private connectionActivity;
3161
+ /**
3162
+ * Whether this room's socket has ever been ready. Until it has, a failed attempt is the room still
3163
+ * starting rather than a reconnect of one that was up, so the opening wait stays through the retries.
3164
+ */
3165
+ private connectionReady;
3166
+ /**
3167
+ * The last connection state the wait was synchronised against (`phase|reconnecting|exhausted`).
3168
+ * The socket's log updates notify the same subscribers without changing the connection, and those
3169
+ * must not re-open a wait the view just dismissed.
3170
+ */
3171
+ private lastConnectionState;
3091
3172
  /**
3092
3173
  * The ids of the requests this client has sent and the room may still be running. A remote `busy`
3093
3174
  * entry carrying one of them is this client's own work (its `activity` shows it), so it is left out of
@@ -3219,9 +3300,15 @@ export declare class NdmspcRoomSession {
3219
3300
  }>;
3220
3301
  /**
3221
3302
  * Records the connection itself as a wait while the socket is opening or authenticating, so the
3222
- * app-wide overlay covers loading a room the same way it covers a run. It ends the moment the
3223
- * connection is ready (or fails); a reconnect starts a fresh one, and the overlay's own short
3224
- * delay keeps a brief blip from flashing.
3303
+ * app-wide overlay covers loading a room the same way it covers a run.
3304
+ *
3305
+ * A room scaled to zero takes seconds to answer, and its ingress refuses the socket until the pod
3306
+ * is up: the client backs off and asks again. That refused first socket is still the room starting,
3307
+ * so the wait stays through those retries until the connection is ready. It ends when authentication
3308
+ * needs the user, when the client gives up retrying, or when the view disconnects.
3309
+ *
3310
+ * A **reconnect** of a room that was already up never raises it: the platform or the network took
3311
+ * the socket, the client is bringing it back, and the row's status chip already says "reconnecting".
3225
3312
  */
3226
3313
  private syncConnectionActivity;
3227
3314
  /**
@@ -3484,6 +3571,14 @@ export declare interface NdmspcRoomStatus {
3484
3571
  session?: string;
3485
3572
  error?: string;
3486
3573
  code?: string;
3574
+ /** Whether an idle room could be started right now, and why not (see {@link NdmspcRoomInfo.wakeable}). */
3575
+ wakeable?: boolean;
3576
+ /** Whether the room is held up by other rooms' terminating pods (see {@link NdmspcRoomInfo.wakeWaiting}). */
3577
+ wakeWaiting?: boolean;
3578
+ wakeError?: string;
3579
+ wakeCheckedAt?: number;
3580
+ /** Epoch seconds a pending room started waiting for cluster resources (see {@link NdmspcRoomInfo.pendingSince}). */
3581
+ pendingSince?: number;
3487
3582
  /** The tokens that open the room; absent for a room that enforces nothing. */
3488
3583
  access?: NdmspcRoomAccess;
3489
3584
  /** What the room's Service declares it may use (see {@link NdmspcRoomResources}). */
@@ -4597,6 +4692,11 @@ export declare class NdmspcWsClient {
4597
4692
  *
4598
4693
  * The delay doubles up to half a minute, and resets once a connection is open, so a restarted
4599
4694
  * router is picked up in a second or so while a long outage costs one attempt every 30s.
4695
+ *
4696
+ * It does not go on for ever. A room that was deleted, or one whose pod never comes back, answers
4697
+ * nothing however often it is asked, and retrying it silently leaves the user under a wait dialog
4698
+ * that only ever says "opening". After {@link MAX_RECONNECT_ATTEMPTS} the client stops and says so
4699
+ * (`reconnectExhausted`), which is what lets a view ask whether to try again.
4600
4700
  */
4601
4701
  private scheduleReconnect;
4602
4702
  private authenticate;
@@ -4728,6 +4828,15 @@ export declare interface NdmspcWsState {
4728
4828
  * is coming back — keep what is on screen — from one that is genuinely down.
4729
4829
  */
4730
4830
  reconnecting: boolean;
4831
+ /**
4832
+ * Whether the automatic reconnect has given up.
4833
+ *
4834
+ * A socket the platform closes is retried on its own; a room that was deleted, or one whose pod
4835
+ * never comes back, is retried just as often and never answers. Rather than reconnecting for ever
4836
+ * under a wait dialog that keeps saying "opening", the client stops after
4837
+ * {@link MAX_RECONNECT_ATTEMPTS} and sets this, so a view can ask whether to try again.
4838
+ */
4839
+ reconnectExhausted: boolean;
4731
4840
  /** Host:port the socket is pointed at, for display. */
4732
4841
  endpoint: string;
4733
4842
  /** Epoch-ms of the last heartbeat. */
@@ -4872,6 +4981,14 @@ export declare function renderers(): NdmspcRenderer[];
4872
4981
  /** The theme `preference` resolves to, given whether the OS currently prefers dark. */
4873
4982
  export declare function resolveTheme(preference: NdmspcTheme, systemPrefersDark: boolean): NdmspcResolvedTheme;
4874
4983
 
4984
+ /**
4985
+ * The window event the room pane raises when the room it showed was deleted.
4986
+ *
4987
+ * A `CustomEvent` on `window`, with `detail: { room }`. It is how the library tells the app to leave the
4988
+ * room: the library cannot know which views a build serves, and the room list is the app's.
4989
+ */
4990
+ export declare const ROOM_GONE_EVENT = "ndmspc:room-gone";
4991
+
4875
4992
  /** Normalises an `/api` URL to a bare base: trimmed, without trailing slashes. */
4876
4993
  export declare function roomApiBase(url: string): string;
4877
4994
 
@@ -4893,6 +5010,60 @@ export declare function roomBaseUrl(url: string): string;
4893
5010
  /** The room id a room's `/api` URL names (`?room=`); "" for one that names none. */
4894
5011
  export declare function roomIdOf(apiUrl: string): string;
4895
5012
 
5013
+ /** What was true at the previous successful read, so a change can be seen against it. */
5014
+ export declare interface RoomLifecycleBaseline {
5015
+ /** Whether the room existed then. */
5016
+ exists: boolean;
5017
+ /** The revision it served then ("" until the router reports one). */
5018
+ revision: string;
5019
+ /** Whether the router said it could not be started then (see the `blocked` event). */
5020
+ blocked: boolean;
5021
+ }
5022
+
5023
+ /** Something that happened to the room a viewer was in. */
5024
+ export declare type RoomLifecycleEvent =
5025
+ /** The room no longer exists: its Knative Service is gone. */
5026
+ {
5027
+ type: "gone";
5028
+ }
5029
+ /** The room is serving a different revision than before — it was rolled onto another image. */
5030
+ | {
5031
+ type: "rolled";
5032
+ revision: string;
5033
+ }
5034
+ /**
5035
+ * The room exists but cannot be started where it is: the router's wake probe found no room for it on
5036
+ * the cluster (or a wake already left a pod the scheduler refuses). This is why a socket that never
5037
+ * opened may be capacity, not deletion.
5038
+ */
5039
+ | {
5040
+ type: "blocked";
5041
+ code: string;
5042
+ error: string;
5043
+ }
5044
+ /** The room can be started again (the blocked state ended), so a reconnect may now work. */
5045
+ | {
5046
+ type: "resumed";
5047
+ };
5048
+
5049
+ declare interface RoomLifecycleOptions {
5050
+ /** The router client. `null` turns the watch off (no router to ask). */
5051
+ client: NdmspcRoomClient | null;
5052
+ /** The room to ask about. `""` turns it off (a room entered by its own `/api` URL). */
5053
+ room: string;
5054
+ /** How often to ask. Defaults to {@link DEFAULT_LIFECYCLE_POLL_MS}. */
5055
+ pollMs?: number;
5056
+ /**
5057
+ * Ask right now, whatever the timer is doing.
5058
+ *
5059
+ * Used when the room's socket gives up: "it did not answer" becomes "it was deleted" as soon as the
5060
+ * router says so.
5061
+ */
5062
+ checkNow?: boolean;
5063
+ /** Called for each change. `gone` is reported once; `rolled` may fire again on a later roll. */
5064
+ onEvent: (event: RoomLifecycleEvent) => void;
5065
+ }
5066
+
4896
5067
  /** The MCP endpoint the room actions are posted to. */
4897
5068
  export declare function roomMcpEndpoint(url: string): string;
4898
5069
 
@@ -5194,6 +5365,14 @@ export declare function useProvidedRoomTools(session: NdmspcRoomSession): Ndmspc
5194
5365
  /** The code the server uses to refuse an authenticated user who may not enter. */
5195
5366
  export declare const USER_NOT_ALLOWED_CODE = "user_not_allowed";
5196
5367
 
5368
+ /**
5369
+ * Watches the room for as long as the component is mounted.
5370
+ *
5371
+ * The callback is kept in a ref, so a host that passes an inline function does not restart the timer on
5372
+ * every render.
5373
+ */
5374
+ export declare function useRoomLifecycle({ client, room, pollMs, checkNow, onEvent, }: RoomLifecycleOptions): void;
5375
+
5197
5376
  /**
5198
5377
  * Flatten a tree into the rows to draw, hiding the children of every node that is not open.
5199
5378
  * A node is drawn whatever its state; its children only when its id is in `open`.