+260

backend/electron/tile-lazy-timeout.test.ts

reviewed

··· 1 1 + /** 2 2 + * Unit tests for tile-lazy load-on-dispatch failure UX (Phase 7). 3 3 + * 4 4 + * Exercises the two user-visible failure paths when a lazy tile can't 5 5 + * accept a dispatched command: 6 6 + * 1. Load timeout — waitForTileReady never resolves; the 10s timer 7 7 + * fires; a `notification:show` publish surfaces the failure and 8 8 + * the caller's result topic is published with `{error}` so the 9 9 + * cmd panel proxy promise settles immediately. 10 10 + * 2. Crashed during load — `tile:state-changed` fires a 11 11 + * `loading → crashed` transition while a dispatch is still in 12 12 + * flight; pending dispatches reject immediately (no 10s wait). 13 13 + * 14 14 + * See docs/pubsub-state-machine.md §Load-on-dispatch — timeout UX. 15 15 + */ 16 16 + 17 17 + import { describe, it, beforeEach, before, after } from 'node:test'; 18 18 + import * as assert from 'node:assert'; 19 19 + 20 20 + import { 21 21 + publish, subscribe, unsubscribe, 22 22 + getSystemAddress, 23 23 + __clearPrePublishHooksForTest, 24 24 + } from './pubsub.js'; 25 25 + import { 26 26 + registerLazyTile, 27 27 + installLoadOnDispatchHook, 28 28 + __setTileLazyLauncherForTest, 29 29 + __resetTileLazyStateForTest, 30 30 + } from './tile-lazy.js'; 31 31 + import type { TileManifestV2 } from './tile-manifest.js'; 32 32 + import type { TileLaunchOptions, TileLaunchResult } from './tile-launcher.js'; 33 33 + 34 34 + // ─── Fake launcher that never reaches ready ────────────────────────── 35 35 + 36 36 + interface FakeLauncherState { 37 37 + launchCalls: TileLaunchOptions[]; 38 38 + loaded: Set<string>; 39 39 + /** 40 40 + * Unresolved ready promises — the whole point is that we never resolve 41 41 + * these so the load timeout fires. Each `waitForTileReady` call 42 42 + * returns a fresh pending promise. 43 43 + */ 44 44 + pendingReady: Array<(value: void) => void>; 45 45 + } 46 46 + 47 47 + function makeFakeLauncher(state: FakeLauncherState) { 48 48 + return { 49 49 + launchTile: (options: TileLaunchOptions): TileLaunchResult | void => { 50 50 + state.launchCalls.push(options); 51 51 + const entryId = options.entryId || options.manifest.tiles[0]?.id || 'background'; 52 52 + queueMicrotask(() => { 53 53 + state.loaded.add(`${options.manifest.id}:${entryId}`); 54 54 + }); 55 55 + }, 56 56 + waitForTileReady: (_tileId: string, _entryId: string): Promise<void> => { 57 57 + // Return a promise that intentionally never resolves. The timeout 58 58 + // inside tile-lazy's `loadLazyTile` is responsible for racing this. 59 59 + return new Promise<void>((resolve) => { 60 60 + state.pendingReady.push(resolve); 61 61 + }); 62 62 + }, 63 63 + isTileLoaded: (tileId: string, entryId: string): boolean => { 64 64 + return state.loaded.has(`${tileId}:${entryId}`); 65 65 + }, 66 66 + }; 67 67 + } 68 68 + 69 69 + // ─── Manifest fixture ───────────────────────────────────────────────── 70 70 + 71 71 + function makeCommandManifest(id: string, cmdName: string): TileManifestV2 { 72 72 + return { 73 73 + manifestVersion: 2, 74 74 + id, 75 75 + name: id, 76 76 + builtin: true, 77 77 + tiles: [ 78 78 + { 79 79 + id: 'background', 80 80 + type: 'background', 81 81 + url: 'background.html', 82 82 + lazy: true, 83 83 + }, 84 84 + ], 85 85 + commands: [ 86 86 + { 87 87 + name: cmdName, 88 88 + description: `${cmdName} description`, 89 89 + action: { type: 'execute' }, 90 90 + }, 91 91 + ], 92 92 + capabilities: { 93 93 + pubsub: { scopes: ['self', 'global'] }, 94 94 + }, 95 95 + }; 96 96 + } 97 97 + 98 98 + function flushMicrotasks(): Promise<void> { 99 99 + return new Promise(resolve => setImmediate(resolve)); 100 100 + } 101 101 + 102 102 + // ─── Tests ──────────────────────────────────────────────────────────── 103 103 + 104 104 + describe('tile-lazy load-on-dispatch timeout UX (Phase 7)', () => { 105 105 + let launcherState: FakeLauncherState; 106 106 + // Collected notification:show publishes. 107 107 + const notifications: Array<{ 108 108 + type?: string; 109 109 + title?: string; 110 110 + body?: string; 111 111 + context?: { tileId?: string; cmdName?: string; reason?: string }; 112 112 + }> = []; 113 113 + const notifySource = 'peek://tile-lazy-timeout-test/notify-observer'; 114 114 + 115 115 + before(() => { 116 116 + subscribe(notifySource, 'notification:show', (msg: unknown) => { 117 117 + notifications.push(msg as typeof notifications[number]); 118 118 + }); 119 119 + }); 120 120 + 121 121 + after(() => { 122 122 + unsubscribe(notifySource, 'notification:show'); 123 123 + }); 124 124 + 125 125 + beforeEach(() => { 126 126 + __resetTileLazyStateForTest(); 127 127 + __clearPrePublishHooksForTest(); 128 128 + installLoadOnDispatchHook(); 129 129 + launcherState = { 130 130 + launchCalls: [], 131 131 + loaded: new Set(), 132 132 + pendingReady: [], 133 133 + }; 134 134 + __setTileLazyLauncherForTest(makeFakeLauncher(launcherState)); 135 135 + notifications.length = 0; 136 136 + }); 137 137 + 138 138 + it('publishes a structured notification and resolves the resultTopic with error on load timeout', async () => { 139 139 + const manifest = makeCommandManifest('tile-timeout-1', 'slow-cmd'); 140 140 + registerLazyTile(manifest, '/fake/path', '/fake/preload.js'); 141 141 + 142 142 + // Collect whatever comes back on the resultTopic so we can assert 143 143 + // the proxy's promise settles (rather than hanging 30s). 144 144 + const resultTopic = 'cmd:execute:slow-cmd:result:unit-test-1'; 145 145 + let resultPayload: unknown = null; 146 146 + subscribe('peek://test-dispatcher/result', resultTopic, (msg) => { 147 147 + resultPayload = msg; 148 148 + }); 149 149 + 150 150 + // Use node:test's mock timers so we can jump past LAZY_LOAD_TIMEOUT_MS 151 151 + // (10000ms) without waiting 10 real seconds. 152 152 + const { mock } = await import('node:test'); 153 153 + mock.timers.enable({ apis: ['setTimeout'] }); 154 154 + 155 155 + try { 156 156 + publish('peek://test-dispatcher', 'cmd:execute:slow-cmd', { 157 157 + expectResult: true, 158 158 + resultTopic, 159 159 + }); 160 160 + 161 161 + // Let the hook register the pending dispatch and kick off the 162 162 + // (pending, never-resolving) launch. 163 163 + for (let i = 0; i < 5; i++) await flushMicrotasks(); 164 164 + assert.strictEqual(launcherState.launchCalls.length, 1, 165 165 + 'tile should have been launched'); 166 166 + 167 167 + // Fire the load timer. reportDispatchFailure runs in the same tick, 168 168 + // so both the notification and the resultTopic publish happen 169 169 + // synchronously before the timeout handler's reject propagates. 170 170 + mock.timers.tick(11000); 171 171 + for (let i = 0; i < 10; i++) await flushMicrotasks(); 172 172 + } finally { 173 173 + mock.timers.reset(); 174 174 + } 175 175 + 176 176 + // Notification assertions — structured error shape the plan spec'd. 177 177 + assert.strictEqual(notifications.length, 1, 178 178 + `expected exactly one notification:show publish, got ${notifications.length}`); 179 179 + const n = notifications[0]; 180 180 + assert.strictEqual(n.type, 'error'); 181 181 + assert.ok(n.title && n.title.toLowerCase().includes("didn't load"), 182 182 + `notification title should signal load failure, got: ${n.title}`); 183 183 + assert.ok(n.body && n.body.includes('slow-cmd'), 184 184 + `notification body should name the command, got: ${n.body}`); 185 185 + assert.ok(n.body && /10000|10 second/.test(n.body), 186 186 + `notification body should mention the timeout duration, got: ${n.body}`); 187 187 + assert.strictEqual(n.context?.tileId, 'tile-timeout-1'); 188 188 + assert.strictEqual(n.context?.cmdName, 'slow-cmd'); 189 189 + assert.strictEqual(n.context?.reason, 'timeout'); 190 190 + 191 191 + // Proxy promise settlement — resultTopic must have been published 192 192 + // with a structured error payload, so the cmd panel's subscribe 193 193 + // resolves immediately instead of hanging on its 30s fallback timer. 194 194 + assert.ok(resultPayload, 195 195 + 'resultTopic should have been published (dispatcher promise hung otherwise)'); 196 196 + const rp = resultPayload as { error?: string }; 197 197 + assert.ok(typeof rp.error === 'string' && rp.error.length > 0, 198 198 + `resultTopic payload should carry an error message, got: ${JSON.stringify(rp)}`); 199 199 + 200 200 + unsubscribe('peek://test-dispatcher/result', resultTopic); 201 201 + }); 202 202 + 203 203 + it('rejects pending dispatches immediately when the tile transitions loading → crashed', async () => { 204 204 + const manifest = makeCommandManifest('tile-crash-2', 'crashy-cmd'); 205 205 + registerLazyTile(manifest, '/fake/path', '/fake/preload.js'); 206 206 + 207 207 + const resultTopic = 'cmd:execute:crashy-cmd:result:unit-test-2'; 208 208 + let resultPayload: unknown = null; 209 209 + subscribe('peek://test-dispatcher/result', resultTopic, (msg) => { 210 210 + resultPayload = msg; 211 211 + }); 212 212 + 213 213 + // Kick off the dispatch — the hook will register a pending entry 214 214 + // against `tile-crash-2` and begin awaiting waitForTileReady (which 215 215 + // never resolves in this fixture). 216 216 + publish('peek://test-dispatcher', 'cmd:execute:crashy-cmd', { 217 217 + expectResult: true, 218 218 + resultTopic, 219 219 + }); 220 220 + for (let i = 0; i < 5; i++) await flushMicrotasks(); 221 221 + 222 222 + assert.strictEqual(launcherState.launchCalls.length, 1); 223 223 + 224 224 + // Simulate the `loading → crashed` transition. The tile-lifecycle 225 225 + // engine publishes `tile:state-changed` as System when a render 226 226 + // process crashes during load; the crash observer in tile-lazy 227 227 + // subscribes to that topic and drains pending dispatches. Publish 228 228 + // directly here so we don't depend on wiring a real BrowserWindow. 229 229 + publish(getSystemAddress(), 'tile:state-changed', { 230 230 + tileId: 'tile-crash-2', 231 231 + entryId: 'background', 232 232 + from: 'loading', 233 233 + to: 'crashed', 234 234 + trigger: 'RENDER_GONE', 235 235 + ts: Date.now(), 236 236 + }); 237 237 + 238 238 + // Observer runs synchronously under the publish; a microtask flush 239 239 + // covers any async subscribe handlers elsewhere. 240 240 + for (let i = 0; i < 3; i++) await flushMicrotasks(); 241 241 + 242 242 + assert.strictEqual(notifications.length, 1, 243 243 + `expected one notification, got ${notifications.length}`); 244 244 + const n = notifications[0]; 245 245 + assert.strictEqual(n.type, 'error'); 246 246 + assert.ok(n.body && n.body.toLowerCase().includes('crashed'), 247 247 + `crashed-path body should mention 'crashed', got: ${n.body}`); 248 248 + assert.strictEqual(n.context?.reason, 'crashed'); 249 249 + assert.strictEqual(n.context?.tileId, 'tile-crash-2'); 250 250 + assert.strictEqual(n.context?.cmdName, 'crashy-cmd'); 251 251 + 252 252 + assert.ok(resultPayload, 253 253 + 'resultTopic should have been published on crash (pending dispatch otherwise still hung)'); 254 254 + const rp = resultPayload as { error?: string }; 255 255 + assert.ok(typeof rp.error === 'string' && rp.error.length > 0, 256 256 + `crashed-path resultTopic payload should carry an error, got: ${JSON.stringify(rp)}`); 257 257 + 258 258 + unsubscribe('peek://test-dispatcher/result', resultTopic); 259 259 + }); 260 260 + });

+149 -7

backend/electron/tile-lazy.ts

reviewed

··· 28 28 */ 29 29 30 30 import { 31 31 - publish, registerPrePublishHook, getSystemAddress, 31 31 + publish, subscribe, registerPrePublishHook, getSystemAddress, 32 32 type PrePublishHookResult, 33 33 } from './pubsub.js'; 34 34 import { ··· 80 80 lazyTileRegistry.clear(); 81 81 loadingTiles.clear(); 82 82 declaredLazyEventTopics.clear(); 83 83 + pendingDispatchesByTile.clear(); 83 84 _hookInstalled = false; 85 85 + _crashObserverInstalled = false; 84 86 } 85 87 86 88 // ─── State ─────────────────────────────────────────────────────────── ··· 105 107 /** Timeout for lazy load (ms) */ 106 108 const LAZY_LOAD_TIMEOUT_MS = 10000; 107 109 110 110 + /** 111 111 + * Phase 7 — Timeout UX for load-on-dispatch. 112 112 + * 113 113 + * Each entry in this map tracks a `cmd:execute:{name}` publish that was 114 114 + * routed through the hook while its target tile was in `registered`. If 115 115 + * the tile never reaches `ready` — either because the load timer fires 116 116 + * or because the render process crashes during boot — we reject every 117 117 + * pending dispatch for that tile with a user-visible notification 118 118 + * instead of letting the cmd panel's 30s proxy timeout absorb the 119 119 + * failure silently. 120 120 + * 121 121 + * Keyed by tileId. A tile can have multiple concurrent dispatches 122 122 + * (user fires command, navigates, fires another while the first is 123 123 + * still loading); each one is a separate `PendingDispatch` entry. 124 124 + */ 125 125 + interface PendingDispatch { 126 126 + cmdName: string; 127 127 + resultTopic: string | null; 128 128 + } 129 129 + const pendingDispatchesByTile = new Map<string, Set<PendingDispatch>>(); 130 130 + 131 131 + function registerPendingDispatch(tileId: string, entry: PendingDispatch): void { 132 132 + let set = pendingDispatchesByTile.get(tileId); 133 133 + if (!set) { 134 134 + set = new Set(); 135 135 + pendingDispatchesByTile.set(tileId, set); 136 136 + } 137 137 + set.add(entry); 138 138 + } 139 139 + 140 140 + function clearPendingDispatch(tileId: string, entry: PendingDispatch): void { 141 141 + const set = pendingDispatchesByTile.get(tileId); 142 142 + if (!set) return; 143 143 + set.delete(entry); 144 144 + if (set.size === 0) pendingDispatchesByTile.delete(tileId); 145 145 + } 146 146 + 147 147 + function drainPendingDispatches(tileId: string): PendingDispatch[] { 148 148 + const set = pendingDispatchesByTile.get(tileId); 149 149 + if (!set) return []; 150 150 + const entries = Array.from(set); 151 151 + pendingDispatchesByTile.delete(tileId); 152 152 + return entries; 153 153 + } 154 154 + 155 155 + /** 156 156 + * Publish a user-visible error notification and resolve the caller's 157 157 + * result topic (if any) with a structured error — so the cmd panel's 158 158 + * proxy promise settles immediately and the state machine returns to 159 159 + * IDLE instead of hanging on the 30s proxy fallback timeout. 160 160 + * 161 161 + * The notification topic is `notification:show` per docs/pubsub-state-machine.md 162 162 + * §Load-on-dispatch — timeout UX. No dedicated notification subscriber 163 163 + * exists yet in Peek; any future notification surface (HUD overlay, 164 164 + * toast, OS notification) listens to this topic. 165 165 + */ 166 166 + function reportDispatchFailure( 167 167 + tileId: string, 168 168 + entry: PendingDispatch, 169 169 + reason: 'timeout' | 'crashed', 170 170 + timeoutMs: number, 171 171 + ): void { 172 172 + const body = 173 173 + reason === 'timeout' 174 174 + ? `Command "${entry.cmdName}" couldn't run because its tile failed to load within ${timeoutMs}ms.` 175 175 + : `Command "${entry.cmdName}" couldn't run because its tile crashed while loading.`; 176 176 + 177 177 + try { 178 178 + publish(getSystemAddress(), 'notification:show', { 179 179 + type: 'error', 180 180 + title: "Tile didn't load", 181 181 + body, 182 182 + context: { tileId, cmdName: entry.cmdName, reason }, 183 183 + }); 184 184 + } catch (err) { 185 185 + console.error('[tile-lazy] notification:show publish threw:', err); 186 186 + } 187 187 + 188 188 + // Resolve the proxy's result topic with an error shape so the cmd 189 189 + // panel returns to IDLE immediately. This mirrors the "error result" 190 190 + // contract other handlers use (see app/cmd/commands.js proxy 191 191 + // subscribe of `cmd:execute:{name}:result`). 192 192 + if (entry.resultTopic) { 193 193 + try { 194 194 + publish(getSystemAddress(), entry.resultTopic, { error: body }); 195 195 + } catch (err) { 196 196 + console.error( 197 197 + `[tile-lazy] resultTopic publish threw for ${entry.resultTopic}:`, 198 198 + err, 199 199 + ); 200 200 + } 201 201 + } 202 202 + } 203 203 + 108 204 // ─── Registration ──────────────────────────────────────────────────── 109 205 110 206 /** ··· 181 277 * Call once at app init, before any command can fire. Idempotent. 182 278 */ 183 279 let _hookInstalled = false; 280 280 + let _crashObserverInstalled = false; 184 281 export function installLoadOnDispatchHook(): void { 185 185 - if (_hookInstalled) return; 186 186 - registerPrePublishHook(dispatchHookPredicate, dispatchHookBody); 187 187 - _hookInstalled = true; 282 282 + if (!_hookInstalled) { 283 283 + registerPrePublishHook(dispatchHookPredicate, dispatchHookBody); 284 284 + _hookInstalled = true; 285 285 + } 286 286 + installCrashObserver(); 287 287 + } 288 288 + 289 289 + /** 290 290 + * Subscribe to the lifecycle observer topic `tile:state-changed` and 291 291 + * reject any pending dispatches when a tile transitions `loading → 292 292 + * crashed`. Rejecting eagerly (not waiting for the 10s timeout) is 293 293 + * the whole point of Phase 7's crashed-during-load path. 294 294 + */ 295 295 + function installCrashObserver(): void { 296 296 + if (_crashObserverInstalled) return; 297 297 + _crashObserverInstalled = true; 298 298 + subscribe('peek://tile-lazy/crash-observer', 'tile:state-changed', (msg: unknown) => { 299 299 + const t = msg as { tileId?: string; from?: string; to?: string } | null; 300 300 + if (!t || typeof t.tileId !== 'string') return; 301 301 + // Only the `loading → crashed` edge matters here. A crash from 302 302 + // ready/visible is not a load failure — those are regular runtime 303 303 + // crashes and aren't the concern of this path. 304 304 + if (t.from !== 'loading' || t.to !== 'crashed') return; 305 305 + const pending = drainPendingDispatches(t.tileId); 306 306 + for (const entry of pending) { 307 307 + reportDispatchFailure(t.tileId, entry, 'crashed', LAZY_LOAD_TIMEOUT_MS); 308 308 + } 309 309 + }); 188 310 } 189 311 190 312 /** ··· 266 388 // Programmatic command: load the tile (if needed), then let the 267 389 // publish continue — by which point the tile's background has 268 390 // subscribed its real handler. 391 391 + const typedMsg = msg as { resultTopic?: string } | null; 392 392 + const pending: PendingDispatch = { 393 393 + cmdName: name, 394 394 + resultTopic: typedMsg?.resultTopic ?? null, 395 395 + }; 396 396 + registerPendingDispatch(tileId, pending); 269 397 try { 270 398 await ensureTileLoaded(tileId); 399 399 + // Load succeeded — drop the pending entry so a later crash or 400 400 + // timeout on a sibling dispatch doesn't fire a stale notification 401 401 + // for this one. 402 402 + clearPendingDispatch(tileId, pending); 271 403 } catch (err) { 404 404 + // If the crash observer already drained this entry (loading → 405 405 + // crashed fired before the load timer), don't double-report. The 406 406 + // observer removes drained entries from the map. 407 407 + const set = pendingDispatchesByTile.get(tileId); 408 408 + const stillPending = set?.has(pending) === true; 409 409 + if (stillPending) { 410 410 + clearPendingDispatch(tileId, pending); 411 411 + reportDispatchFailure(tileId, pending, 'timeout', LAZY_LOAD_TIMEOUT_MS); 412 412 + } 272 413 console.error(`[tile-lazy] Failed to load tile ${tileId} for command ${name}:`, err); 273 273 - // Delivery continues anyway so that any already-registered 274 274 - // fallback subscriber sees the message. If none exist, the cmd 275 275 - // panel's result-timeout will eventually surface the failure. 414 414 + // Skip delivery of the original cmd:execute publish. No handler 415 415 + // is alive to receive it, and the notification + resultTopic 416 416 + // error publish above have already settled the caller's promise. 417 417 + return 'skip'; 276 418 } 277 419 return 'continue'; 278 420 }