@ndmspc/ndmspc-ui 1.4.8 → 1.4.10

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
@@ -2382,6 +2382,22 @@ export declare interface NdmspcRoomInfo {
2382
2382
  error: string;
2383
2383
  /** Failure code, e.g. `no_capacity` (a pending room reports it too). */
2384
2384
  code: string;
2385
+ /**
2386
+ * Whether an **idle** room could be started right now, as the router probed it (a room that is Ready
2387
+ * with no pod, which is the normal resting state). Absent when it was not probed.
2388
+ */
2389
+ wakeable?: boolean;
2390
+ /**
2391
+ * Whether an idle room is held up by **other rooms' terminating pods**: their reservations are still
2392
+ * held, so the cluster cannot place this room yet - it is waiting for them, not idle.
2393
+ */
2394
+ wakeWaiting?: boolean;
2395
+ /** Why an idle room cannot start now: the scheduler's message, or what the cluster is short of. */
2396
+ wakeError?: string;
2397
+ /** Epoch seconds the wake probe last ran. */
2398
+ wakeCheckedAt?: number;
2399
+ /** Epoch seconds a pending room started waiting for cluster resources (0/absent when it is not). */
2400
+ pendingSince?: number;
2385
2401
  /** Epoch seconds the creation began. */
2386
2402
  startedAt: number;
2387
2403
  /**
@@ -2487,6 +2503,21 @@ export declare interface NdmspcRoomList {
2487
2503
  rooms: NdmspcRoomInfo[];
2488
2504
  /** Idle TTL in seconds, after which a room is deleted. */
2489
2505
  ttl: number;
2506
+ /**
2507
+ * How long a room may wait for cluster resources before the router reports it failed (0 = for ever).
2508
+ * Absent for a router that does not bound the wait.
2509
+ */
2510
+ pendingTtl?: number;
2511
+ /**
2512
+ * The router process that answered, when it names itself.
2513
+ *
2514
+ * A push socket can outlive the rollout that replaced its router: the old pod keeps serving its
2515
+ * connections, and its registry can disagree with the one the polls reach (a room it still calls
2516
+ * pending may already be active in the new router). A view compares this with the last full list
2517
+ * and ignores a push from a different router rather than letting the row blink between the two.
2518
+ * Absent from a router that does not name itself.
2519
+ */
2520
+ instance?: string;
2490
2521
  /**
2491
2522
  * The pod profiles this deployment offers, by name, with what each one grants. Absent for a
2492
2523
  * deployment that offers none, in which case there is nothing to choose.
@@ -2539,6 +2570,14 @@ export declare interface NdmspcRoomOpen {
2539
2570
  session?: string;
2540
2571
  error?: string;
2541
2572
  code?: string;
2573
+ /** Whether an idle room could be started right now, and why not (see {@link NdmspcRoomInfo.wakeable}). */
2574
+ wakeable?: boolean;
2575
+ /** Whether the room is held up by other rooms' terminating pods (see {@link NdmspcRoomInfo.wakeWaiting}). */
2576
+ wakeWaiting?: boolean;
2577
+ wakeError?: string;
2578
+ wakeCheckedAt?: number;
2579
+ /** Epoch seconds a pending room started waiting for cluster resources (see {@link NdmspcRoomInfo.pendingSince}). */
2580
+ pendingSince?: number;
2542
2581
  /** The tokens that open the room; absent for a room that enforces nothing. */
2543
2582
  access?: NdmspcRoomAccess;
2544
2583
  /** Who the room belongs to, when the router knows (see {@link NdmspcRoomInfo.owner}). */
@@ -2805,6 +2844,19 @@ export declare class NdmspcRoomService {
2805
2844
  * remembered and the second call does nothing.
2806
2845
  */
2807
2846
  private sentTopics;
2847
+ /**
2848
+ * The router process the last full list came from ("" when it did not name itself).
2849
+ *
2850
+ * A push socket can outlive the rollout that replaced its router: the old pod keeps serving the
2851
+ * connections it already has, and its registry can disagree with the one the polls reach. The
2852
+ * view treats the poll as the truth and ignores pushes from any other process (see `applyPushed`).
2853
+ */
2854
+ private routerInstance;
2855
+ /**
2856
+ * The foreign router instances whose pushes have already been ignored and reconnected away from,
2857
+ * so a socket that lands on one again cannot make the view reconnect in a loop.
2858
+ */
2859
+ private readonly foreignPushes;
2808
2860
  /** The topics this view is showing: the rooms list, and the selected room's session. */
2809
2861
  private topics;
2810
2862
  /** The document listener that reads the list again when this view is shown (see below). */
@@ -2985,6 +3037,14 @@ export declare class NdmspcRoomService {
2985
3037
  private startWatcher;
2986
3038
  /** Closes the push socket (the interval carries on as the net under it). */
2987
3039
  private stopWatcher;
3040
+ /**
3041
+ * Closes a push socket that belongs to a router other than the one the polls reach, and opens a
3042
+ * new one through the route - which sends new connections to the router that is current now.
3043
+ *
3044
+ * The list is read first, so the view is right even if the socket cannot open; the interval is
3045
+ * scheduled as the net under it.
3046
+ */
3047
+ private reconnectWatcher;
2988
3048
  /**
2989
3049
  * Says what the view is showing, so the router pushes exactly that: the list, and one room's session.
2990
3050
  * Sent again when the set changes - the router replaces a socket's topics, so a room the view has
@@ -3034,12 +3094,12 @@ export declare class NdmspcRoomService {
3034
3094
  /**
3035
3095
  * How long to wait before reading the list again.
3036
3096
  *
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.
3097
+ * The push is registry-only: it reports a room being created or coming ready, but the **live** view
3098
+ * (replicas, active, and a pending room's convergence) comes from a full read. So a watching view
3099
+ * still needs a regular one, and while anything is unsettled it needs the configured interval:
3100
+ * a room waiting for resources is converged by the read, and an idle room the cluster could not
3101
+ * start changes the moment capacity frees. Otherwise 5s keeps a room that woke (or went idle) from
3102
+ * looking stuck for the old 20s floor.
3043
3103
  */
3044
3104
  private pollIntervalMs;
3045
3105
  private clearTimer;
@@ -3088,6 +3148,17 @@ export declare class NdmspcRoomSession {
3088
3148
  private sync;
3089
3149
  /** The wait recorded while the connection is being established (see `syncConnectionActivity`). */
3090
3150
  private connectionActivity;
3151
+ /**
3152
+ * Whether this room's socket has ever been ready. Until it has, a failed attempt is the room still
3153
+ * starting rather than a reconnect of one that was up, so the opening wait stays through the retries.
3154
+ */
3155
+ private connectionReady;
3156
+ /**
3157
+ * The last connection state the wait was synchronised against (`phase|reconnecting|exhausted`).
3158
+ * The socket's log updates notify the same subscribers without changing the connection, and those
3159
+ * must not re-open a wait the view just dismissed.
3160
+ */
3161
+ private lastConnectionState;
3091
3162
  /**
3092
3163
  * The ids of the requests this client has sent and the room may still be running. A remote `busy`
3093
3164
  * entry carrying one of them is this client's own work (its `activity` shows it), so it is left out of
@@ -3219,9 +3290,15 @@ export declare class NdmspcRoomSession {
3219
3290
  }>;
3220
3291
  /**
3221
3292
  * 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.
3293
+ * app-wide overlay covers loading a room the same way it covers a run.
3294
+ *
3295
+ * A room scaled to zero takes seconds to answer, and its ingress refuses the socket until the pod
3296
+ * is up: the client backs off and asks again. That refused first socket is still the room starting,
3297
+ * so the wait stays through those retries until the connection is ready. It ends when authentication
3298
+ * needs the user, when the client gives up retrying, or when the view disconnects.
3299
+ *
3300
+ * A **reconnect** of a room that was already up never raises it: the platform or the network took
3301
+ * the socket, the client is bringing it back, and the row's status chip already says "reconnecting".
3225
3302
  */
3226
3303
  private syncConnectionActivity;
3227
3304
  /**
@@ -3484,6 +3561,14 @@ export declare interface NdmspcRoomStatus {
3484
3561
  session?: string;
3485
3562
  error?: string;
3486
3563
  code?: string;
3564
+ /** Whether an idle room could be started right now, and why not (see {@link NdmspcRoomInfo.wakeable}). */
3565
+ wakeable?: boolean;
3566
+ /** Whether the room is held up by other rooms' terminating pods (see {@link NdmspcRoomInfo.wakeWaiting}). */
3567
+ wakeWaiting?: boolean;
3568
+ wakeError?: string;
3569
+ wakeCheckedAt?: number;
3570
+ /** Epoch seconds a pending room started waiting for cluster resources (see {@link NdmspcRoomInfo.pendingSince}). */
3571
+ pendingSince?: number;
3487
3572
  /** The tokens that open the room; absent for a room that enforces nothing. */
3488
3573
  access?: NdmspcRoomAccess;
3489
3574
  /** What the room's Service declares it may use (see {@link NdmspcRoomResources}). */
@@ -4597,6 +4682,11 @@ export declare class NdmspcWsClient {
4597
4682
  *
4598
4683
  * The delay doubles up to half a minute, and resets once a connection is open, so a restarted
4599
4684
  * router is picked up in a second or so while a long outage costs one attempt every 30s.
4685
+ *
4686
+ * It does not go on for ever. A room that was deleted, or one whose pod never comes back, answers
4687
+ * nothing however often it is asked, and retrying it silently leaves the user under a wait dialog
4688
+ * that only ever says "opening". After {@link MAX_RECONNECT_ATTEMPTS} the client stops and says so
4689
+ * (`reconnectExhausted`), which is what lets a view ask whether to try again.
4600
4690
  */
4601
4691
  private scheduleReconnect;
4602
4692
  private authenticate;
@@ -4728,6 +4818,15 @@ export declare interface NdmspcWsState {
4728
4818
  * is coming back — keep what is on screen — from one that is genuinely down.
4729
4819
  */
4730
4820
  reconnecting: boolean;
4821
+ /**
4822
+ * Whether the automatic reconnect has given up.
4823
+ *
4824
+ * A socket the platform closes is retried on its own; a room that was deleted, or one whose pod
4825
+ * never comes back, is retried just as often and never answers. Rather than reconnecting for ever
4826
+ * under a wait dialog that keeps saying "opening", the client stops after
4827
+ * {@link MAX_RECONNECT_ATTEMPTS} and sets this, so a view can ask whether to try again.
4828
+ */
4829
+ reconnectExhausted: boolean;
4731
4830
  /** Host:port the socket is pointed at, for display. */
4732
4831
  endpoint: string;
4733
4832
  /** Epoch-ms of the last heartbeat. */
@@ -4872,6 +4971,14 @@ export declare function renderers(): NdmspcRenderer[];
4872
4971
  /** The theme `preference` resolves to, given whether the OS currently prefers dark. */
4873
4972
  export declare function resolveTheme(preference: NdmspcTheme, systemPrefersDark: boolean): NdmspcResolvedTheme;
4874
4973
 
4974
+ /**
4975
+ * The window event the room pane raises when the room it showed was deleted.
4976
+ *
4977
+ * A `CustomEvent` on `window`, with `detail: { room }`. It is how the library tells the app to leave the
4978
+ * room: the library cannot know which views a build serves, and the room list is the app's.
4979
+ */
4980
+ export declare const ROOM_GONE_EVENT = "ndmspc:room-gone";
4981
+
4875
4982
  /** Normalises an `/api` URL to a bare base: trimmed, without trailing slashes. */
4876
4983
  export declare function roomApiBase(url: string): string;
4877
4984
 
@@ -4893,6 +5000,60 @@ export declare function roomBaseUrl(url: string): string;
4893
5000
  /** The room id a room's `/api` URL names (`?room=`); "" for one that names none. */
4894
5001
  export declare function roomIdOf(apiUrl: string): string;
4895
5002
 
5003
+ /** What was true at the previous successful read, so a change can be seen against it. */
5004
+ export declare interface RoomLifecycleBaseline {
5005
+ /** Whether the room existed then. */
5006
+ exists: boolean;
5007
+ /** The revision it served then ("" until the router reports one). */
5008
+ revision: string;
5009
+ /** Whether the router said it could not be started then (see the `blocked` event). */
5010
+ blocked: boolean;
5011
+ }
5012
+
5013
+ /** Something that happened to the room a viewer was in. */
5014
+ export declare type RoomLifecycleEvent =
5015
+ /** The room no longer exists: its Knative Service is gone. */
5016
+ {
5017
+ type: "gone";
5018
+ }
5019
+ /** The room is serving a different revision than before — it was rolled onto another image. */
5020
+ | {
5021
+ type: "rolled";
5022
+ revision: string;
5023
+ }
5024
+ /**
5025
+ * The room exists but cannot be started where it is: the router's wake probe found no room for it on
5026
+ * the cluster (or a wake already left a pod the scheduler refuses). This is why a socket that never
5027
+ * opened may be capacity, not deletion.
5028
+ */
5029
+ | {
5030
+ type: "blocked";
5031
+ code: string;
5032
+ error: string;
5033
+ }
5034
+ /** The room can be started again (the blocked state ended), so a reconnect may now work. */
5035
+ | {
5036
+ type: "resumed";
5037
+ };
5038
+
5039
+ declare interface RoomLifecycleOptions {
5040
+ /** The router client. `null` turns the watch off (no router to ask). */
5041
+ client: NdmspcRoomClient | null;
5042
+ /** The room to ask about. `""` turns it off (a room entered by its own `/api` URL). */
5043
+ room: string;
5044
+ /** How often to ask. Defaults to {@link DEFAULT_LIFECYCLE_POLL_MS}. */
5045
+ pollMs?: number;
5046
+ /**
5047
+ * Ask right now, whatever the timer is doing.
5048
+ *
5049
+ * Used when the room's socket gives up: "it did not answer" becomes "it was deleted" as soon as the
5050
+ * router says so.
5051
+ */
5052
+ checkNow?: boolean;
5053
+ /** Called for each change. `gone` is reported once; `rolled` may fire again on a later roll. */
5054
+ onEvent: (event: RoomLifecycleEvent) => void;
5055
+ }
5056
+
4896
5057
  /** The MCP endpoint the room actions are posted to. */
4897
5058
  export declare function roomMcpEndpoint(url: string): string;
4898
5059
 
@@ -5194,6 +5355,14 @@ export declare function useProvidedRoomTools(session: NdmspcRoomSession): Ndmspc
5194
5355
  /** The code the server uses to refuse an authenticated user who may not enter. */
5195
5356
  export declare const USER_NOT_ALLOWED_CODE = "user_not_allowed";
5196
5357
 
5358
+ /**
5359
+ * Watches the room for as long as the component is mounted.
5360
+ *
5361
+ * The callback is kept in a ref, so a host that passes an inline function does not restart the timer on
5362
+ * every render.
5363
+ */
5364
+ export declare function useRoomLifecycle({ client, room, pollMs, checkNow, onEvent, }: RoomLifecycleOptions): void;
5365
+
5197
5366
  /**
5198
5367
  * Flatten a tree into the rows to draw, hiding the children of every node that is not open.
5199
5368
  * A node is drawn whatever its state; its children only when its id is in `open`.