From 2ba06e98eced32b4f0d7761f664c1a8b16f5b063 Mon Sep 17 00:00:00 2001 From: ScreenTinker Date: Tue, 7 Jul 2026 12:40:47 -0500 Subject: [PATCH 01/20] feat(#150): preserve per-device settings across delete+re-pair (fingerprint-keyed) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Delete+re-pair mints a new device row whose INSERT omits every setting, silently resetting orientation/name/playlist/etc to defaults (Bold MDM churn). Add a fingerprint-keyed device_settings table (no FK to devices -> survives the cascade): snapshot on DELETE, auto- restore on fingerprint-match re-pair (relinking the fp to the new id), operator re-adopt API (GET /devices/removed + POST /devices/:id/re-adopt) for the changed-fingerprint case. Purge on workspace/user/org deletion (no cross-tenant bleed). Orientation enum-validated on PUT + restore. blocked preserved (re-enforced by the register kill-switch). Wall membership deferred (TODO). Backend only — frontend re-adopt UI NOT built (awaiting API review). Local only, no bump/tag. --- server/db/database.js | 20 ++++++ server/lib/device-settings.js | 124 ++++++++++++++++++++++++++++++++++ server/lib/user-deletion.js | 5 ++ server/routes/devices.js | 39 +++++++++++ server/ws/deviceSocket.js | 15 ++++ 5 files changed, 203 insertions(+) create mode 100644 server/lib/device-settings.js diff --git a/server/db/database.js b/server/db/database.js index 7f0ffaa..f7c2d50 100644 --- a/server/db/database.js +++ b/server/db/database.js @@ -251,6 +251,26 @@ const migrations = [ // register gate on its next reconnect (no restart). Hand-settable by direct SQLite: // UPDATE devices SET blocked = 1 WHERE id = ''; (0 to unblock) "ALTER TABLE devices ADD COLUMN blocked INTEGER NOT NULL DEFAULT 0", + // #150: fingerprint-keyed device settings that SURVIVE device-row deletion, so a + // delete + re-pair (MDM churn) restores orientation/name/playlist/etc for the SAME + // physical device instead of silently resetting to defaults. NO FK to devices -> it + // survives the delete cascade. workspace_id/device_name/last_seen/removed_at form the + // human-readable index the operator "re-adopt" flow browses when the fingerprint changed. + `CREATE TABLE IF NOT EXISTS device_settings ( + fingerprint TEXT PRIMARY KEY, + workspace_id TEXT, + device_name TEXT, + orientation TEXT, + timezone TEXT, + notes TEXT, + default_content_id TEXT, + layout_id TEXT, + playlist_id TEXT, + blocked INTEGER, + team_id TEXT, + last_seen INTEGER, + removed_at INTEGER + )`, ]; // Apply each ALTER idempotently. A "duplicate column name" / "already exists" // error means the column is already present (expected on a migrated DB) - benign. diff --git a/server/lib/device-settings.js b/server/lib/device-settings.js new file mode 100644 index 0000000..134fae8 --- /dev/null +++ b/server/lib/device-settings.js @@ -0,0 +1,124 @@ +'use strict'; +// #150 — fingerprint-keyed device settings that survive device-row deletion. +// +// Delete + re-pair (Bold's MDM churn) mints a BRAND-NEW device row whose INSERT omits every +// per-device setting, so orientation/name/playlist/etc silently reset to defaults. This module +// snapshots a device's settings (keyed by its durable hardware/canvas fingerprint) at DELETE +// time, and re-applies them on the next re-pair for the SAME fingerprint — automatically and +// silently. The same apply path also backs the operator "re-adopt" action for the case where +// the fingerprint changed (factory reset / new hardware), see routes/devices.js. +// +// The table has NO FK to devices, so device deletion can't cascade it away. On workspace/user/ +// org deletion the rows ARE purged (purgeWorkspaces) so settings can never bleed across tenants. +const { db } = require('../db/database'); + +const ORIENTATIONS = new Set(['landscape', 'portrait', 'landscape-flipped', 'portrait-flipped']); +const validOrientation = (o) => (ORIENTATIONS.has(o) ? o : 'landscape'); + +// The devices-row columns we preserve/restore (approved scope: orientation, name, timezone, +// notes, default_content_id, layout_id, playlist_id, blocked, team_id). sort_order is out of +// scope by decision; wall membership (video_wall_devices grid geometry) is a deferred follow-up. +const _selDevice = db.prepare( + `SELECT name, orientation, timezone, notes, default_content_id, layout_id, playlist_id, + blocked, team_id, workspace_id, last_heartbeat + FROM devices WHERE id = ?` +); +const _fpForDevice = db.prepare( + 'SELECT fingerprint FROM device_fingerprints WHERE device_id = ? ORDER BY last_seen DESC LIMIT 1' +); +const _upsert = db.prepare(` + INSERT INTO device_settings + (fingerprint, workspace_id, device_name, orientation, timezone, notes, default_content_id, + layout_id, playlist_id, blocked, team_id, last_seen, removed_at) + VALUES + (@fingerprint, @workspace_id, @device_name, @orientation, @timezone, @notes, @default_content_id, + @layout_id, @playlist_id, @blocked, @team_id, @last_seen, @removed_at) + ON CONFLICT(fingerprint) DO UPDATE SET + workspace_id=excluded.workspace_id, device_name=excluded.device_name, orientation=excluded.orientation, + timezone=excluded.timezone, notes=excluded.notes, default_content_id=excluded.default_content_id, + layout_id=excluded.layout_id, playlist_id=excluded.playlist_id, blocked=excluded.blocked, + team_id=excluded.team_id, last_seen=excluded.last_seen, removed_at=excluded.removed_at +`); + +// Snapshot a device's current settings keyed by its fingerprint, called BEFORE the row is +// deleted. No-op (returns null) if the device has no fingerprint link yet — a never-fully- +// provisioned device has no durable key and no user settings worth preserving. UPSERT keyed on +// fingerprint => repeated delete/re-pair cycles update one row, never duplicate. +function snapshot(deviceId, now = Math.floor(Date.now() / 1000)) { + const d = _selDevice.get(deviceId); + if (!d) return null; + const fpRow = _fpForDevice.get(deviceId); + if (!fpRow || !fpRow.fingerprint) return null; + _upsert.run({ + fingerprint: fpRow.fingerprint, + workspace_id: d.workspace_id || null, + device_name: d.name || null, + orientation: validOrientation(d.orientation), + timezone: d.timezone || null, + notes: d.notes || null, + default_content_id: d.default_content_id || null, + layout_id: d.layout_id || null, + playlist_id: d.playlist_id || null, + blocked: d.blocked ? 1 : 0, + team_id: d.team_id || null, + last_seen: d.last_heartbeat || now, + removed_at: now, + }); + return fpRow.fingerprint; +} + +// Apply saved settings for `fingerprint` onto `deviceId`. Backs BOTH the automatic re-pair +// restore and the operator re-adopt. Orientation is enum-validated (invalid stored value -> +// landscape). FK settings (playlist/layout/default_content) are existence-guarded so a +// since-deleted target is skipped rather than written as a dangling id. Returns the applied +// snapshot row, or null if there was nothing to apply. +function applyToDevice(deviceId, fingerprint) { + const s = db.prepare('SELECT * FROM device_settings WHERE fingerprint = ?').get(fingerprint); + if (!s) return null; + const sets = [], vals = []; + const put = (col, val) => { sets.push(`${col} = ?`); vals.push(val); }; + + put('orientation', validOrientation(s.orientation)); + if (s.device_name != null) put('name', s.device_name); + if (s.timezone != null) put('timezone', s.timezone); + if (s.notes != null) put('notes', s.notes); + put('blocked', s.blocked ? 1 : 0); // security: a blocked device stays blocked across re-pair + if (s.team_id != null) put('team_id', s.team_id); + // FK-existence guards — only restore if the referenced row still exists. + if (s.playlist_id && db.prepare('SELECT 1 FROM playlists WHERE id = ?').get(s.playlist_id)) put('playlist_id', s.playlist_id); + if (s.layout_id && db.prepare('SELECT 1 FROM layouts WHERE id = ?').get(s.layout_id)) put('layout_id', s.layout_id); + if (s.default_content_id && db.prepare('SELECT 1 FROM content WHERE id = ?').get(s.default_content_id)) put('default_content_id', s.default_content_id); + // TODO #150 follow-up: wall membership (video_wall_devices grid geometry) is NOT restored — + // it lives in a separate CASCADE-deleted table with grid positions. Deferred; note in release. + + vals.push(deviceId); + db.prepare(`UPDATE devices SET ${sets.join(', ')}, updated_at = strftime('%s','now') WHERE id = ?`).run(...vals); + return s; +} + +// The "previously removed devices" browser — snapshots for the given workspace(s). +function listRemoved(workspaceIds) { + const ids = (Array.isArray(workspaceIds) ? workspaceIds : [workspaceIds]).filter(Boolean); + if (!ids.length) return []; + const ph = ids.map(() => '?').join(','); + return db.prepare( + `SELECT fingerprint, workspace_id, device_name, orientation, playlist_id, layout_id, + timezone, blocked, last_seen, removed_at + FROM device_settings WHERE workspace_id IN (${ph}) ORDER BY removed_at DESC` + ).all(...ids); +} + +function getByFingerprint(fingerprint) { + return db.prepare('SELECT * FROM device_settings WHERE fingerprint = ?').get(fingerprint); +} + +// Purge snapshots for whole workspaces (workspace/user/org deletion). Runs on the caller's +// db handle (user-deletion runs inside a transaction). Prevents cross-tenant settings bleed. +function purgeWorkspaces(dbConn, workspaceIds) { + const ids = (workspaceIds || []).filter(Boolean); + if (!ids.length) return 0; + const ph = ids.map(() => '?').join(','); + return (dbConn || db).prepare(`DELETE FROM device_settings WHERE workspace_id IN (${ph})`).run(...ids).changes; +} + +module.exports = { snapshot, applyToDevice, listRemoved, getByFingerprint, purgeWorkspaces, validOrientation, ORIENTATIONS }; diff --git a/server/lib/user-deletion.js b/server/lib/user-deletion.js index 83c82bb..1c4e105 100644 --- a/server/lib/user-deletion.js +++ b/server/lib/user-deletion.js @@ -76,6 +76,11 @@ function purgeWorkspaces(db, wsIds, have) { } } for (const t of WORKSPACE_SCOPED) if (have.has(t)) db.prepare(`DELETE FROM ${t} WHERE workspace_id IN (${wph})`).run(...wsIds); + // #150: purge fingerprint-keyed device settings for these workspaces. device_settings has + // NO FK to devices (so it survives device deletion by design), which means it is NOT caught + // by this cascade either — purge it explicitly so saved settings can never bleed onto a + // different tenant if the same physical device (same fingerprint) later pairs elsewhere. + if (have.has('device_settings')) db.prepare(`DELETE FROM device_settings WHERE workspace_id IN (${wph})`).run(...wsIds); if (have.has('activity_log')) db.prepare(`UPDATE activity_log SET workspace_id = NULL WHERE workspace_id IN (${wph})`).run(...wsIds); db.prepare(`DELETE FROM workspaces WHERE id IN (${wph})`).run(...wsIds); // cascades workspace_members/invites } diff --git a/server/routes/devices.js b/server/routes/devices.js index 8945a15..9a4d393 100644 --- a/server/routes/devices.js +++ b/server/routes/devices.js @@ -7,6 +7,7 @@ const { PLATFORM_ROLES, ELEVATED_ROLES, isPlatformStaff } = require('../middlewa const { accessContext } = require('../lib/tenancy'); const { stripDeviceSecrets } = require('../lib/device-sanitize'); const { layoutZones, orphanCountsByDevice } = require('../lib/zone-validate'); +const deviceSettings = require('../lib/device-settings'); // #150 delete+re-pair settings preservation // List devices in the caller's current workspace. // Phase 2.2a: filter by workspace_id instead of user_id. The caller's current @@ -85,6 +86,14 @@ router.get('/unassigned', (req, res) => { res.json(devices); }); +// #150: "previously removed devices" — fingerprint-keyed settings snapshots for the caller's +// current workspace, for the operator re-adopt flow (changed-fingerprint case). MUST be +// declared before GET '/:id' or Express matches 'removed' as an :id. Read-scoped to workspace. +router.get('/removed', (req, res) => { + if (!req.workspaceId) return res.json([]); + res.json(deviceSettings.listRemoved(req.workspaceId)); +}); + // Get single device with telemetry history router.get('/:id', (req, res) => { const device = db.prepare('SELECT d.*, u.email as owner_email, u.name as owner_name FROM devices d LEFT JOIN users u ON d.user_id = u.id WHERE d.id = ?').get(req.params.id); @@ -202,6 +211,11 @@ router.put('/:id', (req, res) => { if (!device) return; const { name, notes, timezone, orientation, default_content_id, layout_id } = req.body; + // #150: validate orientation against the known enum (previously accepted any string, which + // let a bad value reach the player -> unknown rotation falls back to landscape silently). + if (orientation !== undefined && !deviceSettings.ORIENTATIONS.has(orientation)) { + return res.status(400).json({ error: `Invalid orientation. Allowed: ${[...deviceSettings.ORIENTATIONS].join(', ')}` }); + } // Whitelist allowed fields to prevent SQL injection via field names const ALLOWED_FIELDS = ['name', 'notes', 'timezone', 'orientation', 'default_content_id']; const updates = []; @@ -253,11 +267,36 @@ router.post('/:id/unblock', (req, res) => { res.json({ success: true, id: req.params.id, blocked: false }); }); +// #150: re-adopt — apply a removed device's saved settings onto device :id. For the case the +// fingerprint did NOT auto-match (factory reset / new hardware), so the automatic re-pair +// restore couldn't fire. Auth: caller can write device :id (checkDeviceOwnership) AND the +// snapshot belongs to the SAME workspace as the device (no cross-tenant apply). +router.post('/:id/re-adopt', (req, res) => { + const device = checkDeviceOwnership(req, res); + if (!device) return; + const { fingerprint } = req.body || {}; + if (!fingerprint) return res.status(400).json({ error: 'fingerprint required' }); + const snap = deviceSettings.getByFingerprint(fingerprint); + if (!snap) return res.status(404).json({ error: 'No saved settings for that fingerprint' }); + if (snap.workspace_id !== device.workspace_id) { + return res.status(403).json({ error: 'Saved settings belong to a different workspace' }); + } + deviceSettings.applyToDevice(req.params.id, fingerprint); + const updated = db.prepare('SELECT * FROM devices WHERE id = ?').get(req.params.id); + console.log(`[#150] re-adopted settings (fp ${fingerprint.slice(0, 8)}…) onto device ${req.params.id} by user ${req.user.id}`); + res.json(stripDeviceSecrets(updated)); +}); + // Delete device router.delete('/:id', (req, res) => { const device = checkDeviceOwnership(req, res); if (!device) return; + // #150: snapshot this device's settings (keyed by its fingerprint) BEFORE the row dies, + // so a re-pair of the SAME physical device restores orientation/name/playlist/etc instead + // of silently resetting to defaults. No-op if the device has no fingerprint link yet. + try { deviceSettings.snapshot(req.params.id); } catch (e) { console.warn(`[#150] settings snapshot failed for ${req.params.id}: ${e.message}`); } + // Clean up related data (playlist is NOT deleted — may be shared with other devices) db.prepare('DELETE FROM schedules WHERE device_id = ?').run(req.params.id); db.prepare('DELETE FROM screenshots WHERE device_id = ?').run(req.params.id); diff --git a/server/ws/deviceSocket.js b/server/ws/deviceSocket.js index f7733dc..8332c86 100644 --- a/server/ws/deviceSocket.js +++ b/server/ws/deviceSocket.js @@ -15,6 +15,7 @@ const sessionSettle = require('../lib/session-settle'); // #148 patch2: evicti const { resolveIdentity } = require('../lib/device-identity'); const logCoalescer = require('../lib/log-coalescer'); const loopLag = require('../services/loop-lag'); +const deviceSettings = require('../lib/device-settings'); // #150 delete+re-pair settings restore // Debounce window for marking a device offline on socket disconnect. Brief // flap (Wi-Fi blip, Engine.IO ping miss, server-side eviction-then-reconnect) @@ -628,6 +629,20 @@ module.exports = function setupDeviceSocket(io) { currentDeviceId = id; authenticated = true; + // #150: relink the fingerprint to the NEW device row (the fingerprint block above + // leaves device_id NULL on a post-delete re-pair) so the settings key is reliable, + // then restore any settings this physical device had at its last deletion — + // orientation/name/playlist/etc come back automatically instead of resetting. Runs + // BEFORE the dashboard:device-added emit below so that emit carries restored values. + if (fingerprint) { + try { + db.prepare("INSERT INTO device_fingerprints (fingerprint, device_id, last_seen) VALUES (?, ?, strftime('%s','now')) ON CONFLICT(fingerprint) DO UPDATE SET device_id = excluded.device_id, last_seen = excluded.last_seen") + .run(fingerprint, id); + const restored = deviceSettings.applyToDevice(id, fingerprint); + if (restored) console.log(`[#150] restored saved settings for re-paired device ${id} (fp ${fingerprint.slice(0, 8)}…)`); + } catch (e) { console.warn(`[#150] settings restore failed for ${id}: ${e.message}`); } + } + heartbeat.registerConnection(id, socket.id); socket.join(id); socket.emit('device:registered', { device_id: id, device_token: newToken, status: 'provisioning' }); From 74e7062a334d862aebb4b9169ca017f5fc54cd02 Mon Sep 17 00:00:00 2001 From: ScreenTinker Date: Tue, 7 Jul 2026 12:52:42 -0500 Subject: [PATCH 02/20] =?UTF-8?q?feat(#150):=20re-adopt=20UI=20=E2=80=94?= =?UTF-8?q?=20restore=20a=20removed=20device's=20settings=20onto=20a=20re-?= =?UTF-8?q?paired=20screen?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fallback for when the automatic fingerprint-match restore can't fire (factory reset / new hardware / changed fingerprint). From a device's detail view (UX b): 'Restore from removed device…' opens a picker of the workspace's removed-device snapshots (GET /devices/removed), showing device_name + last_seen/removed_at + restore summary (orientation/timezone/playlist), a Blocked badge, and an Apply action (POST /devices/:id/re-adopt) with a confirm — including an explicit warning that applying a blocked snapshot re-blocks the target. Refreshes the device view on success; handles 404/403/400; empty state. Fingerprint shown truncated on-hover only. Frontend only. Local, no bump/tag. --- frontend/js/api.js | 4 ++ frontend/js/i18n/en.js | 20 ++++++ frontend/js/views/device-detail.js | 100 ++++++++++++++++++++++++++++- 3 files changed, 123 insertions(+), 1 deletion(-) diff --git a/frontend/js/api.js b/frontend/js/api.js index 990a616..e275d30 100644 --- a/frontend/js/api.js +++ b/frontend/js/api.js @@ -36,6 +36,10 @@ export const api = { // no restart. Server enforces via the SNAT-safe identity chain (deviceSocket). blockDevice: (id) => request(`/devices/${id}/block`, { method: 'POST' }), unblockDevice: (id) => request(`/devices/${id}/unblock`, { method: 'POST' }), + // #150: fingerprint-keyed settings snapshots of previously-removed devices (this workspace), + // and the re-adopt action that applies a snapshot onto a newly-paired device. + getRemovedDevices: () => request('/devices/removed'), + reAdoptDevice: (id, fingerprint) => request(`/devices/${id}/re-adopt`, { method: 'POST', body: JSON.stringify({ fingerprint }) }), // #109 PiP overlay: push/clear a floating overlay on a device or group. `id` may be a // device id OR a group id (the server resolves + expands). Needs full scope (no-op for JWT). diff --git a/frontend/js/i18n/en.js b/frontend/js/i18n/en.js index 91eeff6..ad0be0a 100644 --- a/frontend/js/i18n/en.js +++ b/frontend/js/i18n/en.js @@ -301,6 +301,26 @@ export default { 'device.debug.toggle': 'Debug logging (live)', 'device.debug.hint': 'Streams player/zone logs from this device in real time. Turns off on its own when the device reconnects.', 'device.form.save_settings': 'Save Settings', + // #150 re-adopt: restore a removed device's saved settings onto this one + 'device.readopt.button': 'Restore from removed device…', + 'device.readopt.button_hint': "Apply a previously-removed device's saved settings onto this one (for a re-paired screen whose fingerprint changed)", + 'device.readopt.title': 'Restore settings from a removed device', + 'device.readopt.help': 'Pick a previously-removed device to copy its saved settings onto “{name}”. This overwrites the current settings.', + 'device.readopt.empty': 'No previously-removed devices in this workspace.', + 'device.readopt.unnamed': 'Unnamed device', + 'device.readopt.blocked': 'Blocked', + 'device.readopt.summary_orientation': 'Orientation', + 'device.readopt.summary_timezone': 'Timezone', + 'device.readopt.summary_playlist': 'Playlist', + 'device.readopt.playlist_none': 'none', + 'device.readopt.playlist_removed': '(playlist since deleted)', + 'device.readopt.last_seen': 'Last seen', + 'device.readopt.removed': 'Removed', + 'device.readopt.apply': 'Apply', + 'device.readopt.confirm': 'Apply saved settings from “{source}” onto “{target}”? This overwrites the current settings.', + 'device.readopt.confirm_blocked': 'This device was BLOCKED. Applying it will re-block the target device — it will immediately refuse to connect and the screen will go dark. Continue?', + 'device.readopt.success': 'Settings restored ({orientation})', + 'device.readopt.error': 'Could not restore settings', // Control buttons 'device.ctl.reboot_device': 'Reboot Device', 'device.ctl.screen_off': 'Screen Off', diff --git a/frontend/js/views/device-detail.js b/frontend/js/views/device-detail.js index cc5ef1c..4e2088a 100644 --- a/frontend/js/views/device-detail.js +++ b/frontend/js/views/device-detail.js @@ -370,6 +370,7 @@ async function loadDevice(deviceId, activeTab = null) { +
@@ -644,7 +645,100 @@ function showDevicePreview(device) { }); } -async function setupActions(device) { +async // #150 re-adopt fallback: browse the workspace's previously-removed device snapshots and +// apply one onto THIS (usually blank, just-re-paired) device. Primary restore is the silent +// fingerprint-match on re-pair; this is for factory-reset / new-hardware / changed-fingerprint. +const ORIENT_LABELS = { + 'landscape': 'device.form.orientation.landscape', + 'portrait': 'device.form.orientation.portrait', + 'landscape-flipped': 'device.form.orientation.landscape_flipped', + 'portrait-flipped': 'device.form.orientation.portrait_flipped', +}; +const orientLabel = (o) => t(ORIENT_LABELS[o] || ORIENT_LABELS.landscape); +const fmtTs = (ts) => (ts ? new Date(ts * 1000).toLocaleString() : '—'); + +async function showReAdoptModal(device) { + let snapshots, playlists; + try { + [snapshots, playlists] = await Promise.all([ + api.getRemovedDevices(), + api.getPlaylists().catch(() => []), // best-effort: only used to label the restored playlist + ]); + } catch (err) { showToast(err.message || t('device.readopt.error'), 'error'); return; } + + const plById = new Map((playlists || []).map(p => [p.id, p.name])); + const playlistLabel = (s) => !s.playlist_id + ? t('device.readopt.playlist_none') + : (plById.get(s.playlist_id) || t('device.readopt.playlist_removed')); + + const rowsHtml = (snapshots || []).map((s, i) => { + const blockedBadge = s.blocked + ? `${t('device.readopt.blocked')}` + : ''; + // Fingerprint is the key but not an operator-facing identifier — truncated + on-hover only. + const fpShort = (s.fingerprint || '').slice(0, 8); + return ` +
+
+
${esc(s.device_name || t('device.readopt.unnamed'))}${blockedBadge}
+
+ ${t('device.readopt.summary_orientation')}: ${esc(orientLabel(s.orientation))} +  ·  ${t('device.readopt.summary_timezone')}: ${esc(s.timezone || 'UTC')} +  ·  ${t('device.readopt.summary_playlist')}: ${esc(playlistLabel(s))} +
+
+ ${t('device.readopt.last_seen')}: ${esc(fmtTs(s.last_seen))}  ·  ${t('device.readopt.removed')}: ${esc(fmtTs(s.removed_at))} +
+
+ +
`; + }).join(''); + + const emptyHtml = `
${t('device.readopt.empty')}
`; + + const overlay = document.createElement('div'); + overlay.className = 'modal-overlay'; + overlay.style.display = 'flex'; + overlay.innerHTML = ` +
+
+

${t('device.readopt.title')}

+ +
+
+

${t('device.readopt.help', { name: esc(device.name || '') })}

+ ${(snapshots && snapshots.length) ? rowsHtml : emptyHtml} +
+
`; + document.body.appendChild(overlay); + const close = () => overlay.remove(); + overlay.querySelector('#readoptClose').onclick = close; + overlay.onclick = (e) => { if (e.target === overlay) close(); }; + + overlay.querySelectorAll('.readopt-apply').forEach((btn) => { + btn.addEventListener('click', async () => { + const s = snapshots[parseInt(btn.dataset.i, 10)]; + let msg = t('device.readopt.confirm', { source: s.device_name || t('device.readopt.unnamed'), target: device.name || '' }); + if (s.blocked) msg += '\n\n⚠ ' + t('device.readopt.confirm_blocked'); // explicit: target will go dark + if (!confirm(msg)) return; + btn.disabled = true; + try { + await api.reAdoptDevice(device.id, s.fingerprint); + showToast(t('device.readopt.success', { orientation: orientLabel(s.orientation) }), 'success'); + close(); + loadDevice(device.id); // refresh so restored orientation/name/etc show immediately + } catch (err) { + // Server messages: 404 no snapshot, 403 cross-workspace, 400 bad request. + showToast(err.message || t('device.readopt.error'), 'error'); + btn.disabled = false; + } + }); + }); +} + +function setupActions(device) { // #104 Preview button document.getElementById('devicePreviewBtn')?.addEventListener('click', () => showDevicePreview(device)); @@ -706,6 +800,10 @@ async function setupActions(device) { } }); + // #150 re-adopt: apply a previously-removed device's saved settings onto THIS device (the + // fallback for when the fingerprint changed and automatic restore couldn't fire). + document.getElementById('reAdoptBtn')?.addEventListener('click', () => showReAdoptModal(device)); + // Publish / Discard from device detail const devicePublishBtn = document.getElementById('devicePublishBtn'); if (devicePublishBtn && device.playlist_id) { From 78c71e00ab085031d85646c3a202ca6e21ad04cb Mon Sep 17 00:00:00 2001 From: ScreenTinker Date: Tue, 7 Jul 2026 14:39:16 -0500 Subject: [PATCH 03/20] =?UTF-8?q?feat(tizen):=20.wgt=20lifecycle=20parity?= =?UTF-8?q?=20=E2=80=94=20keep-awake=20re-assert=20+=20suspend/resume=20ha?= =?UTF-8?q?ndler=20+=20fixes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Client-only. Brings the standalone Tizen .wgt player toward APK//player parity: - A: re-assert keepAwake() on a 30s interval (power lock / screensaver-off can be released when the TV backgrounds the app); cleared on exit. - B: visibilitychange/resume handler. On resume re-asserts keep-awake and, ONLY for the half-open case socket.io cannot detect (connected===true after a suspend-length hide), owns a clean teardown-before-reopen via connect() (exactly one socket, #118 re-registers once). Defers to socket.io's auto-reconnect when the socket is already disconnected — the two are mutually-exclusive states so no manual reconnect races socket.io. No manual re-register. - C: 4th-beat now re-emits device:register (real fallback playlist refresh) instead of a duplicate device:heartbeat. - D: APP_VERSION_FALLBACK 1.9.1 -> 1.9.2 (repo hygiene; build-wgt.sh stamps at build). - F: device:unpaired now backs off 3s before re-registering (symmetric with auth-error), so MDM re-pair churn can't tight-loop. Keep-awake (A+B) is the LEADING flap candidate, NOT a confirmed cause. Offline caching (E) deliberately excluded. No server changes; no bump/tag/build. --- tizen/js/app.js | 67 +++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 62 insertions(+), 5 deletions(-) diff --git a/tizen/js/app.js b/tizen/js/app.js index 43086f6..b805e27 100644 --- a/tizen/js/app.js +++ b/tizen/js/app.js @@ -15,7 +15,7 @@ // packaged config.xml via the Tizen application API; fall back to a constant that // build-wgt.sh stamps from config.xml's version="" so the dashboard always shows the // version that is actually installed (never the old hardcoded '1.0.0'). - var APP_VERSION_FALLBACK = '1.9.1'; // st:app-version — stamped by build-wgt.sh + var APP_VERSION_FALLBACK = '1.9.2'; // st:app-version — stamped by build-wgt.sh var APP_VERSION = (function () { try { var v = tizen.application.getCurrentApplication().appInfo.version; @@ -85,6 +85,55 @@ try { if (window.webapis && webapis.appcommon) webapis.appcommon.setScreenSaver(webapis.appcommon.AppCommonScreenSaverState.SCREEN_SAVER_OFF); } catch (e) {} } + // FIX A — RE-ASSERT keep-awake on an interval. tizen.power.request / the screensaver-off + // setting can be released when the TV backgrounds/suspends the app, and the player had no + // way to re-suppress it (keepAwake was only called at boot/connect/command). ~30s is well + // under any TV screensaver timeout and the calls are cheap best-effort no-ops. Cleared by + // stopKeepAwake() on app teardown. + var keepAwakeTimer = null; + function startKeepAwake() { + stopKeepAwake(); + keepAwake(); + keepAwakeTimer = setInterval(keepAwake, 30000); + } + function stopKeepAwake() { if (keepAwakeTimer) { clearInterval(keepAwakeTimer); keepAwakeTimer = null; } } + + // FIX B — VISIBILITY / RESUME handling. On a TV, a background/suspend can (a) release + // keep-awake and (b) silently drop the socket, leaving it HALF-OPEN — socket.connected stays + // true while the transport is dead, which socket.io CANNOT detect, so it won't auto-reconnect. + // + // Double-connect discipline (the one way this could reintroduce #148's duplicate socket): + // - DEFER to socket.io when the socket is already disconnected (socket.io owns that + // reconnect, and #118 re-registers on 'connect'). + // - OWN a clean teardown-before-reopen (via connect(), which disconnects the old socket + // FIRST — cancelling any socket.io reconnect — then opens exactly ONE new socket) ONLY + // for the half-open case socket.io can't see. + // These are mutually-exclusive socket states (connected vs not), so a manual reconnect + // never races socket.io's auto-reconnect. We do NOT manually re-register (connect's 'connect' + // handler does, once). Half-open is inferred from how long the app was hidden — socket.connected + // alone is unreliable post-suspend and there is no server ack channel to actively probe + // without a server change (out of scope for this client-only build). + var hiddenAtMs = 0; + var SUSPEND_HIDE_MS = 3000; // hidden >= this ≈ an OS suspend that can half-open the socket + + // Pure decision, factored out so the double-connect logic is unit-testable: + // 'reconnect' = half-open -> own teardown+reopen ; 'defer' = already down -> socket.io owns it ; 'noop' + function resumeDecision(hasSocket, socketConnected, hiddenMs) { + if (!hasSocket) return 'noop'; + if (!socketConnected) return 'defer'; + return (hiddenMs >= SUSPEND_HIDE_MS) ? 'reconnect' : 'noop'; + } + function onVisibility() { + if (document.visibilityState === 'hidden' || document.hidden) { hiddenAtMs = Date.now(); return; } + keepAwake(); // re-assert immediately on resume + var hiddenMs = hiddenAtMs ? (Date.now() - hiddenAtMs) : 0; + hiddenAtMs = 0; + var action = resumeDecision(!!socket, !!(socket && socket.connected), hiddenMs); + if (action === 'reconnect') connect(); // teardown-before-reopen -> exactly one socket; #118 registers once + // 'defer' -> socket.io auto-reconnects (re-registers on 'connect'); 'noop' -> healthy, do nothing + } + if (typeof window !== 'undefined') window.__stResumeDecision = resumeDecision; // test hook (inert in prod) + // ---- networking ---- var socket = null; var deviceId = get(LS.id); @@ -179,7 +228,10 @@ socket.on('device:unpaired', function () { del(LS.id); del(LS.token); del(LS.code); deviceId = null; deviceToken = null; - register(); // re-register fresh -> new pairing code + // FIX F — back off 3s before re-registering, symmetric with the auth-error path below, + // so a repeatedly-unpaired device (e.g. MDM re-pair churn) can't tight-loop + // register -> unpaired -> register. + setTimeout(register, 3000); }); socket.on('device:auth-error', function (data) { @@ -269,8 +321,11 @@ // requireDeviceAuth() rejects the beat with device:auth-error. if (!socket || !socket.connected || !deviceId || !authenticated) return; socket.emit('device:heartbeat', { device_id: deviceId, telemetry: telemetry() }); - // Every 4th beat (~60s) ask for a fresh playlist, matching the Android player. - if ((++beatCount % 4) === 0) socket.emit('device:heartbeat', { device_id: deviceId, telemetry: telemetry() }); + // FIX C — every 4th beat (~60s) ask for a fresh playlist by re-emitting device:register; + // the server responds with a fresh device:playlist-update (deviceSocket.js). This was + // previously a duplicate device:heartbeat (comment != code), so the .wgt had NO working + // fallback refresh and relied entirely on server push. Matches the Android player. + if ((++beatCount % 4) === 0) register(); }, HEARTBEAT_MS); } function stopHeartbeat() { @@ -475,6 +530,7 @@ document.addEventListener('keydown', function (e) { if (e.keyCode === 10009) { // Samsung RETURN / BACK if (!elSetup.classList.contains('hidden')) { + stopKeepAwake(); // FIX A: clear the interval cleanly before the app exits try { tizen.application.getCurrentApplication().exit(); } catch (x) {} } else { if (socket) { try { socket.disconnect(); } catch (x) {} } @@ -489,7 +545,8 @@ // Always reach the server prompt until the display is actually paired. Only a // fully provisioned device (has a saved device_id + token) goes straight to // playback; otherwise show the setup screen and ask for / confirm the server. - keepAwake(); + startKeepAwake(); // FIX A: assert + re-assert keep-awake on an interval + document.addEventListener('visibilitychange', onVisibility); // FIX B: handle suspend/resume if (serverUrl && deviceId && deviceToken) { show(elStage); connect(); // paired — reconnect to playback } else if (serverUrl) { From dcd3a05a7e62a7f06032adc8e0c1a4d95614e167 Mon Sep 17 00:00:00 2001 From: ScreenTinker Date: Tue, 7 Jul 2026 14:57:50 -0500 Subject: [PATCH 04/20] feat(tizen): harden FIX B with an application-level liveness watchdog MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace the resume-only hide-duration heuristic as the AUTHORITATIVE half-open detector with a real server-silence watchdog, so the .wgt self-heals a dead-but-connected socket from ANY cause (network drop, NAT idle timeout, transport death while foregrounded), not just resume. - Central receive-path liveness: markAlive() refreshes lastServerMsgAt on EVERY inbound server message — app events via socket.onAny, and the server's ~15s engine ping via socket.io 'ping' (both client-only signals the server already sends; no server change; heartbeats get no ack). - Watchdog (10s cadence): if socket.connected && authenticated && silent > 35s (2+ missed pings, under engine.io's own ~45s close), treat as half-open and reconnect via the teardown-first connect() -> exactly one socket, #118 re-registers once. - #148 discipline: fires ONLY while socket.connected===true (the state socket.io can't see), so it never races socket.io's own down-socket auto-reconnect; connect() resets liveness so the watchdog and the resume fast-path can't double-fire. Resume path kept as the fast suspend path. - Timers cleared on exit. Client-only; keep-awake+lifecycle remain the leading flap candidate, NOT a confirmed cause. --- tizen/js/app.js | 49 +++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 47 insertions(+), 2 deletions(-) diff --git a/tizen/js/app.js b/tizen/js/app.js index b805e27..4f2c5bc 100644 --- a/tizen/js/app.js +++ b/tizen/js/app.js @@ -134,6 +134,41 @@ } if (typeof window !== 'undefined') window.__stResumeDecision = resumeDecision; // test hook (inert in prod) + // FIX B (hardened) — application-level LIVENESS WATCHDOG. The resume path above only fires on + // visibilitychange, so a socket that goes half-open with NO visibility event (network drop, NAT + // idle timeout, transport death while foregrounded) would never be caught: socket.connected stays + // true on a dead socket and socket.io won't reconnect. The watchdog watches for server SILENCE. + // The server sends an engine ping every ~15s (config.pingInterval) AND app events, so a healthy + // socket refreshes lastServerMsgAt at least every ~15s (markAlive is wired into a central receive + // path in connect(): socket.onAny + socket.io 'ping'). If the socket goes quiet past the liveness + // window while we still believe we're connected + authenticated, it is half-open -> clean + // teardown-before-reopen via connect() (exactly one socket; #118 re-registers once). + // + // Double-connect discipline: the watchdog fires ONLY while socket.connected===true (the half-open + // state socket.io cannot see) — socket.io's own auto-reconnect only runs when socket.connected is + // false, so the two never overlap. connect() is teardown-first, and it resets lastServerMsgAt, so + // the watchdog and the resume fast-path can't double-fire a second reconnect. Client-only: uses + // signals the server already sends; no server change. + var lastServerMsgAt = 0; + var LIVENESS_TIMEOUT_MS = 35000; // ~2+ missed 15s server pings; below engine.io's own ~45s close + var watchdogTimer = null; + function markAlive() { lastServerMsgAt = Date.now(); } // central receive-path hook (see connect()) + // Pure, unit-testable: reconnect only for a connected+authenticated socket gone silent past the window. + function watchdogShouldReconnect(hasSocket, connected, authed, silentMs) { + return !!(hasSocket && connected && authed && silentMs > LIVENESS_TIMEOUT_MS); + } + function startWatchdog() { + stopWatchdog(); + watchdogTimer = setInterval(function () { + var silentMs = lastServerMsgAt ? (Date.now() - lastServerMsgAt) : 0; + if (watchdogShouldReconnect(!!socket, !!(socket && socket.connected), authenticated, silentMs)) { + connect(); // half-open backstop: teardown-first -> one socket, #118 re-registers once + } + }, 10000); + } + function stopWatchdog() { if (watchdogTimer) { clearInterval(watchdogTimer); watchdogTimer = null; } } + if (typeof window !== 'undefined') window.__stWatchdogShouldReconnect = watchdogShouldReconnect; // test hook (inert in prod) + // ---- networking ---- var socket = null; var deviceId = get(LS.id); @@ -184,6 +219,15 @@ timeout: 10000 }); + // FIX B (hardened): central receive-path liveness. A fresh socket is assumed alive; then EVERY + // inbound server message refreshes lastServerMsgAt — app events via onAny, and the engine ping + // (~15s) via the manager 'ping'. This resets liveness so the watchdog / resume fast-path can't + // double-fire, and feeds the watchdog's server-silence detection. (io() returns a fresh socket + // per connect — verified — so these listeners don't accumulate.) + lastServerMsgAt = Date.now(); + socket.onAny(markAlive); + socket.io.on('ping', markAlive); + socket.on('connect', function () { // #118: a brand-new socket is not authenticated until device:registered. Reset the // flag and kill any heartbeat carried over from the previous socket, so a beat can't @@ -530,7 +574,7 @@ document.addEventListener('keydown', function (e) { if (e.keyCode === 10009) { // Samsung RETURN / BACK if (!elSetup.classList.contains('hidden')) { - stopKeepAwake(); // FIX A: clear the interval cleanly before the app exits + stopKeepAwake(); stopWatchdog(); // FIX A/B: clear timers cleanly before the app exits try { tizen.application.getCurrentApplication().exit(); } catch (x) {} } else { if (socket) { try { socket.disconnect(); } catch (x) {} } @@ -546,7 +590,8 @@ // fully provisioned device (has a saved device_id + token) goes straight to // playback; otherwise show the setup screen and ask for / confirm the server. startKeepAwake(); // FIX A: assert + re-assert keep-awake on an interval - document.addEventListener('visibilitychange', onVisibility); // FIX B: handle suspend/resume + document.addEventListener('visibilitychange', onVisibility); // FIX B: suspend/resume fast-path + startWatchdog(); // FIX B (hardened): server-silence liveness backstop if (serverUrl && deviceId && deviceToken) { show(elStage); connect(); // paired — reconnect to playback } else if (serverUrl) { From 646eab743ac6c5dbc7461ae01f23183d6d166dad Mon Sep 17 00:00:00 2001 From: ScreenTinker Date: Tue, 7 Jul 2026 21:58:58 -0500 Subject: [PATCH 05/20] =?UTF-8?q?fix(tizen):=20P0=20audit=20fix=20pass=20?= =?UTF-8?q?=E2=80=94=20watchdog=20config-proofing,=20teardown=20hygiene,?= =?UTF-8?q?=20dead-screen=20self-heal,=20offline=20snapshot?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Client-only, no server change. Implemented in verified clusters: - H1 (config-proof, no heartbeat-ack): derive the liveness window from the server-negotiated pingInterval (version-robust read) + arm the watchdog only after a real inbound signal, so it degrades safe against any server and a raised PING_INTERVAL can't false-fire it into a storm. - A5: monotonic clock (performance.now) for watchdog/resume deltas — NTP/RTC jumps can't false-fire or blind the watchdog. - H4 (leak was verified ABSENT): timer/teardown hygiene — tracked register-retry + teardownSession() on reset/BACK (stop heartbeat/stream/player-loop/pending-register); all start*() are stop-first. - A1: single-item playlist retries a broken item (was a permanent black screen while heartbeat green). - A6: reconnect randomizationFactor 0.5 (no fleet thundering-herd) + timeout 10s->20s (parity). - A2 (minimal): cache last renderable playlist-update to localStorage, replay on cold-start/offline; cleared on unpair/reset/auth-error. - B3: input hardening (non-array assignments/zones guarded, duration_sec numeric-coerced). - A3: log keep-awake API availability so Bold can VERIFY the flap fix on real hardware. #148 double-connect discipline re-proven after socket-touching changes. --- tizen/js/app.js | 105 ++++++++++++++++++++++++++++++++++++--------- tizen/js/player.js | 20 +++++++-- 2 files changed, 101 insertions(+), 24 deletions(-) diff --git a/tizen/js/app.js b/tizen/js/app.js index 4f2c5bc..19a0327 100644 --- a/tizen/js/app.js +++ b/tizen/js/app.js @@ -32,7 +32,8 @@ id: 'st_device_id', token: 'st_device_token', fp: 'st_fingerprint', - code: 'st_pairing_code' + code: 'st_pairing_code', + payload: 'st_payload_cache' // A2: last renderable playlist-update, replayed on cold-start/offline }; // ---- persistent state ---- @@ -85,6 +86,13 @@ try { if (window.webapis && webapis.appcommon) webapis.appcommon.setScreenSaver(webapis.appcommon.AppCommonScreenSaverState.SCREEN_SAVER_OFF); } catch (e) {} } + // A5 — MONOTONIC clock for lifecycle time deltas (watchdog silence, resume hidden-duration), so an + // NTP/RTC wall-clock step on a 24/7 TV can't false-fire (forward jump) or blind (backward jump) the + // watchdog. Date.now() is kept ONLY where a real wall clock is needed (telemetry, cross-device wall sync). + var mono = (typeof performance !== 'undefined' && performance.now) + ? function () { return performance.now(); } + : function () { return Date.now(); }; + // FIX A — RE-ASSERT keep-awake on an interval. tizen.power.request / the screensaver-off // setting can be released when the TV backgrounds/suspends the app, and the player had no // way to re-suppress it (keepAwake was only called at boot/connect/command). ~30s is well @@ -124,9 +132,9 @@ return (hiddenMs >= SUSPEND_HIDE_MS) ? 'reconnect' : 'noop'; } function onVisibility() { - if (document.visibilityState === 'hidden' || document.hidden) { hiddenAtMs = Date.now(); return; } + if (document.visibilityState === 'hidden' || document.hidden) { hiddenAtMs = mono(); return; } // A5: monotonic keepAwake(); // re-assert immediately on resume - var hiddenMs = hiddenAtMs ? (Date.now() - hiddenAtMs) : 0; + var hiddenMs = hiddenAtMs ? (mono() - hiddenAtMs) : 0; // A5: monotonic hidden-duration hiddenAtMs = 0; var action = resumeDecision(!!socket, !!(socket && socket.connected), hiddenMs); if (action === 'reconnect') connect(); // teardown-before-reopen -> exactly one socket; #118 registers once @@ -150,24 +158,34 @@ // the watchdog and the resume fast-path can't double-fire a second reconnect. Client-only: uses // signals the server already sends; no server change. var lastServerMsgAt = 0; - var LIVENESS_TIMEOUT_MS = 35000; // ~2+ missed 15s server pings; below engine.io's own ~45s close + var livenessConfirmed = false; // H1: DON'T arm until the server has actually talked to us + var DEFAULT_LIVENESS_MS = 35000; + var livenessWindowMs = DEFAULT_LIVENESS_MS; // H1: derived from the negotiated engine pingInterval per connect var watchdogTimer = null; - function markAlive() { lastServerMsgAt = Date.now(); } // central receive-path hook (see connect()) - // Pure, unit-testable: reconnect only for a connected+authenticated socket gone silent past the window. - function watchdogShouldReconnect(hasSocket, connected, authed, silentMs) { - return !!(hasSocket && connected && authed && silentMs > LIVENESS_TIMEOUT_MS); + function markAlive() { lastServerMsgAt = mono(); livenessConfirmed = true; } // central receive-path hook; A5 monotonic + // H1 (config-proof): adapt the silence window to whatever pingInterval the SERVER negotiated, so a larger + // server pingInterval can't make the client false-fire into a reconnect storm. 2 intervals + 5s margin, + // floored at the 35s default (which is 2×15s+5s). Called from the 'connect' handler once the handshake is known. + function setLivenessWindowFromPing(pingIntervalMs) { + if (pingIntervalMs && pingIntervalMs > 0) livenessWindowMs = Math.max(DEFAULT_LIVENESS_MS, 2 * pingIntervalMs + 5000); + } + // Pure, unit-testable. Reconnect ONLY when a connected+authenticated socket whose liveness we have CONFIRMED + // (seen >=1 real inbound signal — H1 degrade-safe: a server that never talks never arms the watchdog, so no + // storm) has gone silent past the server-derived window. + function watchdogShouldReconnect(hasSocket, connected, authed, confirmed, silentMs, windowMs) { + return !!(hasSocket && connected && authed && confirmed && silentMs > windowMs); } function startWatchdog() { stopWatchdog(); watchdogTimer = setInterval(function () { - var silentMs = lastServerMsgAt ? (Date.now() - lastServerMsgAt) : 0; - if (watchdogShouldReconnect(!!socket, !!(socket && socket.connected), authenticated, silentMs)) { + var silentMs = lastServerMsgAt ? (mono() - lastServerMsgAt) : 0; // A5 monotonic + if (watchdogShouldReconnect(!!socket, !!(socket && socket.connected), authenticated, livenessConfirmed, silentMs, livenessWindowMs)) { connect(); // half-open backstop: teardown-first -> one socket, #118 re-registers once } }, 10000); } function stopWatchdog() { if (watchdogTimer) { clearInterval(watchdogTimer); watchdogTimer = null; } } - if (typeof window !== 'undefined') window.__stWatchdogShouldReconnect = watchdogShouldReconnect; // test hook (inert in prod) + if (typeof window !== 'undefined') { window.__stWatchdogShouldReconnect = watchdogShouldReconnect; window.__stSetLivenessWindowFromPing = setLivenessWindowFromPing; } // ---- networking ---- var socket = null; @@ -209,6 +227,7 @@ if (!serverUrl) { show(elSetup); return; } keepAwake(); if (socket) { try { socket.disconnect(); } catch (e) {} socket = null; } + if (registerTimer) { clearTimeout(registerTimer); registerTimer = null; } // H4: a fresh connect supersedes any pending re-register var base = serverUrl.replace(/\/+$/, ''); socket = io(base + '/device', { @@ -216,7 +235,8 @@ reconnection: true, reconnectionDelay: 2000, reconnectionDelayMax: 10000, - timeout: 10000 + randomizationFactor: 0.5, // A6: ±50% jitter so a fleet of TVs doesn't reconnect in lockstep (thundering herd) after a server restart — matches the APK + timeout: 20000 // cheap parity (GAP4c): match /player + APK; 10s prematurely errored slow TV WebKit / WS-blocked networks }); // FIX B (hardened): central receive-path liveness. A fresh socket is assumed alive; then EVERY @@ -224,11 +244,21 @@ // (~15s) via the manager 'ping'. This resets liveness so the watchdog / resume fast-path can't // double-fire, and feeds the watchdog's server-silence detection. (io() returns a fresh socket // per connect — verified — so these listeners don't accumulate.) - lastServerMsgAt = Date.now(); + lastServerMsgAt = mono(); // A5 monotonic + livenessConfirmed = false; // H1: arm the watchdog only after a real inbound signal + livenessWindowMs = DEFAULT_LIVENESS_MS; // reset; refined from the handshake on 'connect' socket.onAny(markAlive); socket.io.on('ping', markAlive); socket.on('connect', function () { + // H1: derive the liveness window from the pingInterval the SERVER negotiated at the handshake, + // so raising server PING_INTERVAL can't make the watchdog false-fire (config-proof). The engine + // exposes it as `pingInterval` (socket.io-client 4.7.x, the bundled .wgt client) or `_pingInterval` + // (4.8.x); read both, and fall back to the 35s default if neither is present. + try { + var eng = socket.io && socket.io.engine; + setLivenessWindowFromPing(eng && (eng.pingInterval || eng._pingInterval)); + } catch (e) {} // #118: a brand-new socket is not authenticated until device:registered. Reset the // flag and kill any heartbeat carried over from the previous socket, so a beat can't // fire on this fresh, unregistered connection (TV sleep/wake reconnects often). @@ -270,12 +300,12 @@ }); socket.on('device:unpaired', function () { - del(LS.id); del(LS.token); del(LS.code); + del(LS.id); del(LS.token); del(LS.code); del(LS.payload); deviceId = null; deviceToken = null; // FIX F — back off 3s before re-registering, symmetric with the auth-error path below, // so a repeatedly-unpaired device (e.g. MDM re-pair churn) can't tight-loop // register -> unpaired -> register. - setTimeout(register, 3000); + scheduleRegister(3000); }); socket.on('device:auth-error', function (data) { @@ -286,9 +316,9 @@ stopHeartbeat(); toast((data && data.error) ? data.error : 'Auth error', false); // Bad/stale token or fingerprint-reclaim block: drop creds and re-pair. - del(LS.id); del(LS.token); + del(LS.id); del(LS.token); del(LS.payload); // A2: clear cached content when identity is lost deviceId = null; deviceToken = null; - setTimeout(register, 3000); + scheduleRegister(3000); }); socket.on('device:playlist-update', onPlaylist); @@ -419,6 +449,12 @@ ? STDeviceControl.capabilities() : { backend: 'none', reboot: false, panel: false }; reportCmd('info', 'capabilities', 'fleet control backend=' + caps.backend + ' reboot=' + caps.reboot + ' panel=' + caps.panel); + // A3 observability: the keep-awake fix only actually holds the screen if these APIs resolve on the + // TV's firmware/signing path. Surface their presence to the dashboard log so Bold can VERIFY on real + // hardware whether keep-awake is real (vs a silent no-op) — the load-bearing check for the flap fix. + var ka = 'keep-awake: setScreenSaver=' + !!(window.webapis && webapis.appcommon) + + ' tizen.power=' + !!(window.tizen && tizen.power); + reportCmd('info', 'keepawake', ka); } catch (e) {} } @@ -460,6 +496,25 @@ function startStreaming() { stopStreaming(); streamTimer = setInterval(captureAndSend, 1000); } function stopStreaming() { if (streamTimer) { clearInterval(streamTimer); streamTimer = null; } } + // H4 (teardown hygiene): TRACK the register re-try so a reset/reconnect can cancel a pending late + // register (Lens 2 found it untracked -> a stray register could fire on a fresh socket). + var registerTimer = null; + function scheduleRegister(delay) { + if (registerTimer) clearTimeout(registerTimer); + registerTimer = setTimeout(function () { registerTimer = null; register(); }, delay); + } + // H4: stop the per-SESSION timers/loops when leaving playback (reset / BACK-to-setup). Otherwise the + // player loop keeps firing on the hidden stage and throws (serverUrl=null), heartbeat/stream keep + // running, and a pending register can fire late. Keep-awake + the watchdog are LIFETIME timers + // (guarded no-ops while off-session) and are intentionally left running. Idempotent. + function teardownSession() { + stopHeartbeat(); + stopStreaming(); + try { player.stop(); } catch (e) {} + if (registerTimer) { clearTimeout(registerTimer); registerTimer = null; } + authenticated = false; + } + // ---- playback ---- var player = new PlaylistPlayer(elStage, function () { return serverUrl.replace(/\/+$/, ''); }); // Multi-zone layout renderer (matches the Android player). app.js picks the renderer @@ -517,6 +572,9 @@ show(elStage); return; } + // A2: cache the last RENDERABLE payload so a reboot / WS-outage with no connectivity replays it + // instead of showing the idle card. Only non-suspended payloads are cached. + try { set(LS.payload, JSON.stringify(payload)); } catch (e) {} // If we have content + we're paired, make sure we're on the stage. if (elPairing.classList.contains('hidden') === false) show(elStage); else if (elStage.classList.contains('hidden')) show(elStage); @@ -534,7 +592,7 @@ wallController.exit(); // leave wall mode if we were in it applyOrientation(payload.orientation || 'landscape'); var layout = payload.layout; - if (layout && layout.zones && layout.zones.length) { + if (layout && Array.isArray(layout.zones) && layout.zones.length) { // B3: non-array zones would throw in zoneRenderer // Multi-zone layout (matches the Android player). Leave single-zone mode first. player.stop(); zoneRenderer.setTimezone(payload.timezone || null); // #74/#75: effective tz @@ -563,9 +621,10 @@ connect(); } elReset.addEventListener('click', function () { - del(LS.url); del(LS.id); del(LS.token); del(LS.code); + del(LS.url); del(LS.id); del(LS.token); del(LS.code); del(LS.payload); deviceId = null; deviceToken = null; serverUrl = null; if (socket) { try { socket.disconnect(); } catch (e) {} } + teardownSession(); // H4: stop heartbeat/stream/player-loop + pending register (no dangling timers on setup) show(elSetup); }); @@ -578,6 +637,7 @@ try { tizen.application.getCurrentApplication().exit(); } catch (x) {} } else { if (socket) { try { socket.disconnect(); } catch (x) {} } + teardownSession(); // H4: same clean teardown when BACK returns to setup elUrl.value = serverUrl || ''; elSetupStatus.textContent = ''; elSetupStatus.className = 'status'; show(elSetup); elUrl.focus(); @@ -593,7 +653,12 @@ document.addEventListener('visibilitychange', onVisibility); // FIX B: suspend/resume fast-path startWatchdog(); // FIX B (hardened): server-silence liveness backstop if (serverUrl && deviceId && deviceToken) { - show(elStage); connect(); // paired — reconnect to playback + // A2: render cached content IMMEDIATELY so a cold-start/offline TV isn't blank while the socket + // connects (or if it can't). The socket's fresh device:playlist-update replaces it on connect. + show(elStage); + var _cp = get(LS.payload); + if (_cp) { try { onPlaylist(JSON.parse(_cp)); } catch (e) {} } + connect(); // paired — reconnect to playback } else if (serverUrl) { show(elSetup); elUrl.value = serverUrl; // server known, not paired — confirm + connect elSetupStatus.className = 'status'; diff --git a/tizen/js/player.js b/tizen/js/player.js index 41b4477..970535f 100644 --- a/tizen/js/player.js +++ b/tizen/js/player.js @@ -34,7 +34,9 @@ function PlaylistPlayer(stageEl, getBase) { } PlaylistPlayer.prototype.load = function (assignments) { - var items = (assignments || []).filter(function (a) { + // B3: a malformed device:playlist-update with a non-array `assignments` used to throw + // (.filter is not a function) out of the socket handler; coerce to [] instead. + var items = (Array.isArray(assignments) ? assignments : []).filter(function (a) { return a && (a.content_id || a.widget_id || a.remote_url); }); // Stable order @@ -72,7 +74,10 @@ PlaylistPlayer.prototype.idle = function () { }; PlaylistPlayer.prototype.durationMs = function (item) { - var d = item.duration_sec || this.DEFAULT_DURATION; + // B3: a non-numeric duration_sec ("abc") used to yield NaN -> schedule(NaN) -> fire-ASAP spin. + // Coerce; any non-positive/NaN falls back to the default. + var d = Number(item.duration_sec); + if (!(d > 0)) d = this.DEFAULT_DURATION; if (d < this.MIN_DURATION) d = this.MIN_DURATION; return d * 1000; }; @@ -203,7 +208,14 @@ PlaylistPlayer.prototype.playCurrent = function () { // Give a broken item ~2s then move on so the loop never wedges. PlaylistPlayer.prototype.skipSoon = function () { - if (this.items.length > 1) this.schedule(2000); + if (this.items.length > 1) { this.schedule(2000); return; } + // A1: a SINGLE-item playlist used to WEDGE on a broken item — skipSoon did nothing, so a transient + // failure (CDN blip, brief network loss, a 404 that later resolves) left a permanent black screen + // while the heartbeat still reported the device online. Retry the SAME item after a backoff so it + // self-heals instead of going dark forever. + var self = this; + if (this.timer) clearTimeout(this.timer); + this.timer = setTimeout(function () { self.playCurrent(); }, 5000); }; PlaylistPlayer.prototype.fit = function (el, item) { @@ -239,7 +251,7 @@ PlaylistPlayer.prototype.renderVideo = function (item, single) { // Safety net: if 'ended' never fires (rare), advance after the known // content duration (or the assignment duration) + a buffer. if (!single) { - var secs = item.content_duration || item.duration_sec || this.DEFAULT_DURATION; + var secs = Number(item.content_duration || item.duration_sec) || this.DEFAULT_DURATION; // B3: numeric this.schedule((secs + 5) * 1000); } }; From 57cdaf7e4ed44d147f667b6cb8bca7a039c48dbb Mon Sep 17 00:00:00 2001 From: ScreenTinker Date: Wed, 8 Jul 2026 09:57:53 -0500 Subject: [PATCH 06/20] feat(apk): v4 liveness contract + caching-cluster fix + reconnect-safe downloads MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit APK v4 — client-only (Android player). Brings the reference client up to the locked v4 liveness contract and fixes the "stuck downloading / offline in CMS" caching bug: - v4 liveness watchdog (LivenessWatchdog): half-open detection via server-silence, arm-ONLY-after device:heartbeat-ack (degrade-safe), 45s±10s jittered threshold, exp backoff 1/2/4/8/16→30s ±20%, no-poll; reconnect delegates to the #148 ConnectionGuard (teardown-before-reopen, single socket). - Caching two-root fix: callTimeout + .part+Content-Length integrity + atomic swap (CacheValidation), onPlayerError advance, re-ack cached content + reconnect re-ack. - Screen resilience (PlaylistSelection): a pending/failed download never blanks the screen — keep-current, swap only fully-valid content. - Reconnect-safe background downloads (DownloadCoordinator): single-flight per contentId + bounded pool + failure backoff + cancellation; a reconnect mid-fetch can't orphan/duplicate/storm. Refuse 206 partials. - v4 client identity block on register (client_type/version/platform/contract_version). Tests: 52 JVM unit tests (watchdog, cache validation, reproduce-then-prove download stall/truncation/reconnect-mid-download, screen selection, assembly soak). Depends on the server device:heartbeat-ack (core pass) — degrade-safe until then. Co-Authored-By: Claude Opus 4.8 (1M context) --- android/app/build.gradle.kts | 7 + .../com/remotedisplay/player/MainActivity.kt | 93 +++++---- .../player/data/CacheValidation.kt | 20 ++ .../remotedisplay/player/data/ContentCache.kt | 102 ++++++--- .../player/data/DownloadCoordinator.kt | 111 ++++++++++ .../player/player/MediaPlayerManager.kt | 8 + .../player/player/PlaylistController.kt | 86 ++++++-- .../player/player/PlaylistSelection.kt | 46 +++++ .../player/service/LivenessWatchdog.kt | 60 ++++++ .../player/service/WebSocketService.kt | 96 +++++++++ .../player/telemetry/DeviceInfo.kt | 2 +- .../player/data/CacheValidationTest.kt | 30 +++ .../player/data/ContentDownloadTest.kt | 119 +++++++++++ .../player/data/DownloadCoordinatorTest.kt | 194 ++++++++++++++++++ .../player/player/PlaylistSelectionTest.kt | 60 ++++++ .../player/service/AssemblyInteractionTest.kt | 172 ++++++++++++++++ .../player/service/LivenessWatchdogTest.kt | 76 +++++++ 17 files changed, 1207 insertions(+), 75 deletions(-) create mode 100644 android/app/src/main/java/com/remotedisplay/player/data/CacheValidation.kt create mode 100644 android/app/src/main/java/com/remotedisplay/player/data/DownloadCoordinator.kt create mode 100644 android/app/src/main/java/com/remotedisplay/player/player/PlaylistSelection.kt create mode 100644 android/app/src/main/java/com/remotedisplay/player/service/LivenessWatchdog.kt create mode 100644 android/app/src/test/java/com/remotedisplay/player/data/CacheValidationTest.kt create mode 100644 android/app/src/test/java/com/remotedisplay/player/data/ContentDownloadTest.kt create mode 100644 android/app/src/test/java/com/remotedisplay/player/data/DownloadCoordinatorTest.kt create mode 100644 android/app/src/test/java/com/remotedisplay/player/player/PlaylistSelectionTest.kt create mode 100644 android/app/src/test/java/com/remotedisplay/player/service/AssemblyInteractionTest.kt create mode 100644 android/app/src/test/java/com/remotedisplay/player/service/LivenessWatchdogTest.kt diff --git a/android/app/build.gradle.kts b/android/app/build.gradle.kts index c49b88a..41b2f3a 100644 --- a/android/app/build.gradle.kts +++ b/android/app/build.gradle.kts @@ -46,6 +46,13 @@ android { kotlinOptions { jvmTarget = "17" } + + testOptions { + // Let JVM unit tests exercise Android-dependent code paths (e.g. ContentCache's real + // download logic, which logs via android.util.Log) without Robolectric — stubbed Android + // APIs return defaults instead of throwing "not mocked". + unitTests.isReturnDefaultValues = true + } } dependencies { diff --git a/android/app/src/main/java/com/remotedisplay/player/MainActivity.kt b/android/app/src/main/java/com/remotedisplay/player/MainActivity.kt index 8922f12..8c052b4 100644 --- a/android/app/src/main/java/com/remotedisplay/player/MainActivity.kt +++ b/android/app/src/main/java/com/remotedisplay/player/MainActivity.kt @@ -40,6 +40,7 @@ class MainActivity : AppCompatActivity() { private lateinit var config: ServerConfig private lateinit var contentCache: ContentCache + private lateinit var downloadCoordinator: com.remotedisplay.player.data.DownloadCoordinator private lateinit var screenshotCapture: ScreenshotCapture private lateinit var touchInjector: TouchInjector @@ -124,6 +125,13 @@ class MainActivity : AppCompatActivity() { window.addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON) contentCache = ContentCache(this) + // Coordinated background downloads (single-flight + bounded pool + backoff) — reconnect-safe. + downloadCoordinator = com.remotedisplay.player.data.DownloadCoordinator( + cache = contentCache, + serverUrl = { config.serverUrl }, + socketAlive = { wsService?.isConnected() == true }, + onAck = { cid, status -> ackContentOnce(cid, status) } + ) screenshotCapture = ScreenshotCapture() touchInjector = TouchInjector() @@ -171,8 +179,17 @@ class MainActivity : AppCompatActivity() { // #74/#75: clear the last frame when going idle (else a now-filtered item lingers on screen) onPlaylistEmpty = { if (::mediaPlayer.isInitialized) mediaPlayer.stop(); showStatus(getString(R.string.waiting_for_content)) }, onRequestRefresh = { wsService?.requestPlaylistRefresh() }, - onNothingScheduled = { if (::mediaPlayer.isInitialized) mediaPlayer.stop(); showStatus(getString(R.string.nothing_scheduled)) } + onNothingScheduled = { if (::mediaPlayer.isInitialized) mediaPlayer.stop(); showStatus(getString(R.string.nothing_scheduled)) }, + // Screen-resilience: the defined "waiting for content" state — ONLY on a fresh device + // with nothing to show yet (never while content is on screen; that path keeps current). + onWaitingForContent = { if (::mediaPlayer.isInitialized) mediaPlayer.stop(); showStatus(getString(R.string.waiting_for_content)) } ) + // Screen-resilience: an item is playable only when its content is actually available — + // a widget, a remote stream, or a fully-downloaded local file. A not-yet/failed download is + // skipped (kept in the background) instead of blanking the screen on a loading state. + playlistController.setContentReadyCheck { item -> + item.isWidget || item.isRemote || contentCache.isContentCached(item.contentId) + } // Setup media player mediaPlayer = MediaPlayerManager( @@ -469,31 +486,23 @@ class MainActivity : AppCompatActivity() { // Skip remote URL content - it streams directly if (!remoteUrl.isNullOrEmpty()) { - wsService?.sendContentAck(contentId, "ready") + ackContentOnce(contentId, "ready") continue } - if (!contentCache.isContentCached(contentId)) { - Log.i("MainActivity", "Downloading content: $filename") - var downloaded = false - for (attempt in 1..3) { - val file = contentCache.downloadContent(config.serverUrl, contentId, filename) - if (file != null) { - wsService?.sendContentAck(contentId, "ready") - downloaded = true - break - } - Log.w("MainActivity", "Download attempt $attempt failed for $filename") - if (attempt < 3) Thread.sleep(2000L * attempt) - } - if (!downloaded) wsService?.sendContentAck(contentId, "failed") - } + // Background download is now COORDINATED: single-flight per contentId + a bounded + // pool + failure backoff. So a watchdog/ConnectionGuard reconnect mid-fetch can't + // spawn a duplicate racing the .part, orphan/pile up threads, or storm a failing + // URL. ensure() is non-blocking and idempotent: it re-acks cached content (SEED-A), + // defers when the socket is down (watchdog owns recovery), respects backoff, and + // downloads at most once. It acks ready/failed itself (deduped via onAck). + downloadCoordinator.ensure(contentId, filename) } - // Start or resume playback after downloads complete — but ONLY in - // single-zone/fullscreen mode. In multi-zone, ZoneManager drives each - // zone; restarting the fullscreen controller here made it keep playing - // items behind the zones (wasted work + phantom audio for videos). + // Start/resume playback immediately — do NOT wait on downloads (they're async now). + // Screen-resilience plays whatever is cached and skips not-yet-ready items; the 3s + // recheck swaps new content in once its download completes. Single-zone only; in + // multi-zone, ZoneManager drives each zone. handler.post { if (zoneManager?.hasZones() != true) playlistController.startIfNeeded() } @@ -505,6 +514,7 @@ class MainActivity : AppCompatActivity() { } wsService?.onContentDelete = { contentId -> + downloadCoordinator.forget(contentId) // drop in-flight/backoff state so a re-add re-downloads contentCache.deleteContent(contentId) playlistController.removeContent(contentId) // Update cached playlist to reflect deletion @@ -631,6 +641,9 @@ class MainActivity : AppCompatActivity() { wsService?.onRegistered = { _ -> hideStatus() + // Root-2 (SEED-B): a disconnect may have dropped in-flight content-acks. Clear the + // de-dup set so the next playlist-update re-acks all content and the CMS re-syncs. + ackedContent.clear() } wsService?.onUnpaired = { @@ -645,6 +658,20 @@ class MainActivity : AppCompatActivity() { } } + // Root-2 content-ack de-dup. Re-acking content state (SEED-A) fixes the CMS "stuck downloading" + // label, but we must not re-ack the same (content,status) every 60s playlist refresh. This set + // is cleared on each (re)registration (see onRegistered) so a reconnect re-acks everything the + // server may have missed while we were disconnected (SEED-B), but is quiet within a session. + private val ackedContent = java.util.Collections.synchronizedSet(HashSet()) + + private fun ackContentOnce(contentId: String, status: String) { + if (ackedContent.add("$contentId:$status")) { + // a status change for this content supersedes the opposite one + ackedContent.remove("$contentId:${if (status == "ready") "failed" else "ready"}") + wsService?.sendContentAck(contentId, status) + } + } + private fun playItem(item: PlaylistItem) { hideStatus() com.remotedisplay.player.util.DebugLog.i("Player", "playItem: ${item.filename} mime=${item.mimeType} widget=${item.widgetId ?: "-"} zone=fullscreen") @@ -680,22 +707,17 @@ class MainActivity : AppCompatActivity() { return } - // Local content - download if not cached + // Local content - play from cache. Screen-resilience: the controller only advances to + // items whose content is READY, so reaching here uncached is a rare race (e.g. the file + // was evicted between selection and play). NEVER blank or show a "Downloading…" screen — + // keep whatever is on screen and move on; the background download loop (onPlaylistUpdate) + // fetches it and it plays once fully + validly downloaded. Content update is a BACKGROUND + // operation; we only ever SWAP to fully-downloaded content. val file = contentCache.getCachedFile(item.contentId) if (file == null) { - Log.w("MainActivity", "Content not cached: ${item.contentId}, downloading...") - showStatus("Downloading ${item.filename}...") - thread { - val downloaded = contentCache.downloadContent(config.serverUrl, item.contentId, item.filename) - handler.post { - if (downloaded != null) { - playFile(item, downloaded) - } else { - showStatus("Download failed: ${item.filename}") - handler.postDelayed({ playlistController.next() }, 3000) - } - } - } + Log.i("MainActivity", "Content not ready at play time (${item.filename}) — keeping screen, advancing (bg download continues)") + downloadCoordinator.ensure(item.contentId, item.filename) // ensure it's being fetched (single-flight) + handler.post { playlistController.next() } return } @@ -812,6 +834,7 @@ class MainActivity : AppCompatActivity() { override fun onDestroy() { remoteStreaming = false + if (::downloadCoordinator.isInitialized) downloadCoordinator.shutdown() // cancel in-flight downloads (no orphan/leak) zoneManager?.cleanup() if (::pipOverlay.isInitialized) pipOverlay.clear(null) // #109: tear down overlay WebView if (::mediaPlayer.isInitialized) { diff --git a/android/app/src/main/java/com/remotedisplay/player/data/CacheValidation.kt b/android/app/src/main/java/com/remotedisplay/player/data/CacheValidation.kt new file mode 100644 index 0000000..bf07dd6 --- /dev/null +++ b/android/app/src/main/java/com/remotedisplay/player/data/CacheValidation.kt @@ -0,0 +1,20 @@ +package com.remotedisplay.player.data + +/** + * Root-2 caching fix — the pure, unit-testable "is this download complete?" rule (no Android deps, + * same pattern as ConnectionGuard / OtaThrottle). [ContentCache] is the imperative shell (OkHttp + + * filesystem); this owns the integrity decision so a truncated/partial body is never promoted to + * the cache dir and later served as if it were a whole file (which previously wedged playback on a + * corrupt asset with no error path). + */ +object CacheValidation { + /** + * Complete iff we wrote at least one byte AND — when the server declared a Content-Length + * ([expectedBytes] > 0) — we wrote exactly that many. A truncated body + * (bytesWritten < expectedBytes) is INCOMPLETE and must be discarded + re-fetched. When the + * length is unknown (chunked / -1), fall back to ">0 bytes" (an interrupted copy throws and is + * discarded upstream, so a silent zero-length truncation is the only residual gap). + */ + fun isComplete(bytesWritten: Long, expectedBytes: Long): Boolean = + bytesWritten > 0 && (expectedBytes <= 0 || bytesWritten == expectedBytes) +} diff --git a/android/app/src/main/java/com/remotedisplay/player/data/ContentCache.kt b/android/app/src/main/java/com/remotedisplay/player/data/ContentCache.kt index 0a37f6a..18d123c 100644 --- a/android/app/src/main/java/com/remotedisplay/player/data/ContentCache.kt +++ b/android/app/src/main/java/com/remotedisplay/player/data/ContentCache.kt @@ -8,16 +8,31 @@ import java.io.File import java.io.FileOutputStream import java.util.concurrent.TimeUnit -class ContentCache(private val context: Context) { - - private val cacheDir = File(context.filesDir, "content_cache").also { it.mkdirs() } - private val client = OkHttpClient.Builder() - .connectTimeout(30, TimeUnit.SECONDS) - .readTimeout(5, TimeUnit.MINUTES) - .build() +/** + * Root-2 caching fixes vs the "stuck downloading / frozen" bug: + * - a hard OVERALL [callTimeout] so a slow-drip/stalled download on a HEALTHY socket can't hang + * forever (the old client only had a per-read timeout, which a trickle never trips), + * - download to a `.part` temp + integrity-check (Content-Length) via [CacheValidation] + atomic + * rename, so a truncated/interrupted body is NEVER promoted to the cache and played as if whole, + * - exact-prefix cache lookup that also excludes in-flight `.part` files. + * + * The primary constructor takes the cache dir + client directly so the real download logic is + * unit-testable (see ContentDownloadTest) against a local server without an Android Context; the + * [Context] convenience constructor is what the app uses. + */ +class ContentCache internal constructor( + private val cacheDir: File, + private val client: OkHttpClient +) { + constructor(context: Context) : this( + File(context.filesDir, "content_cache").also { it.mkdirs() }, + defaultClient() + ) fun getCachedFile(contentId: String): File? { - val files = cacheDir.listFiles { _, name -> name.startsWith(contentId) } + // Match "." exactly: the trailing dot stops an id that PREFIXES another id from + // cross-matching, and `.part` temps (partial/in-flight downloads) are never returned. + val files = cacheDir.listFiles { _, name -> name.startsWith("$contentId.") && !name.endsWith(PART_SUFFIX) } return files?.firstOrNull()?.takeIf { it.exists() && it.length() > 0 } } @@ -26,35 +41,61 @@ class ContentCache(private val context: Context) { } fun downloadContent(serverUrl: String, contentId: String, filename: String): File? { + val ext = filename.substringAfterLast('.', "mp4") + val finalFile = File(cacheDir, "${contentId}.${ext}") + val partFile = File(cacheDir, "${contentId}.${ext}${PART_SUFFIX}") try { val url = "${serverUrl}/api/content/${contentId}/file" val request = Request.Builder().url(url).build() - val response = client.newCall(request).execute() - - if (!response.isSuccessful) { - Log.e("ContentCache", "Download failed: ${response.code}") - return null - } - - val ext = filename.substringAfterLast('.', "mp4") - val file = File(cacheDir, "${contentId}.${ext}") - - response.body?.byteStream()?.use { input -> - FileOutputStream(file).use { output -> - input.copyTo(output) + // .use closes the Response (and its body) on every path — also fixes the prior + // error-path body/connection leak. + client.newCall(request).execute().use { response -> + if (!response.isSuccessful) { + Log.e("ContentCache", "Download failed: ${response.code}") + return null } + // We issue a plain (no-Range) GET, so a 206 Partial Content means a proxy/CDN + // returned a PARTIAL body whose Content-Length matches that partial — which would + // pass the byte-count integrity check and promote a truncated file. Require a full 200. + if (response.code == 206) { + Log.e("ContentCache", "Refusing 206 Partial Content for $filename — not a complete file") + return null + } + partFile.delete() // clear any earlier partial before writing + val body = response.body ?: return null + val expected = body.contentLength() // -1 when unknown (chunked) + var written = 0L + body.byteStream().use { input -> + FileOutputStream(partFile).use { output -> written = input.copyTo(output) } + } + // Root-2: a truncated body must NOT be promoted to the cache and played as whole. + if (!CacheValidation.isComplete(written, expected)) { + Log.e("ContentCache", "Incomplete download ($written/$expected bytes) for $filename — discarding partial") + partFile.delete() + return null + } + finalFile.delete() + if (!partFile.renameTo(finalFile)) { + Log.e("ContentCache", "Rename failed for $filename") + partFile.delete() + return null + } + Log.i("ContentCache", "Downloaded: $filename -> ${finalFile.absolutePath} ($written bytes)") + return finalFile } - - Log.i("ContentCache", "Downloaded: $filename -> ${file.absolutePath}") - return file } catch (e: Exception) { + // Includes callTimeout / readTimeout (a stalled download on a healthy socket) and any + // mid-stream break — never leave a partial at the real path. Log.e("ContentCache", "Download error: ${e.message}") + partFile.delete() return null } } fun deleteContent(contentId: String) { - cacheDir.listFiles { _, name -> name.startsWith(contentId) }?.forEach { it.delete() } + // Exact-prefix (with the dot) so we don't delete a different id's file — and this also + // sweeps the "..part" temp. + cacheDir.listFiles { _, name -> name.startsWith("$contentId.") }?.forEach { it.delete() } Log.i("ContentCache", "Deleted cached content: $contentId") } @@ -65,4 +106,15 @@ class ContentCache(private val context: Context) { fun getCacheSize(): Long { return cacheDir.listFiles()?.sumOf { it.length() } ?: 0L } + + companion object { + private const val PART_SUFFIX = ".part" + + fun defaultClient(): OkHttpClient = OkHttpClient.Builder() + .connectTimeout(30, TimeUnit.SECONDS) + .readTimeout(30, TimeUnit.SECONDS) // Root-2: a stalled stream (no bytes 30s) aborts (was 5min) + .writeTimeout(30, TimeUnit.SECONDS) + .callTimeout(5, TimeUnit.MINUTES) // Root-2: hard OVERALL cap so a slow-drip can't hang forever + .build() + } } diff --git a/android/app/src/main/java/com/remotedisplay/player/data/DownloadCoordinator.kt b/android/app/src/main/java/com/remotedisplay/player/data/DownloadCoordinator.kt new file mode 100644 index 0000000..8302bdf --- /dev/null +++ b/android/app/src/main/java/com/remotedisplay/player/data/DownloadCoordinator.kt @@ -0,0 +1,111 @@ +package com.remotedisplay.player.data + +import android.os.SystemClock +import android.util.Log +import java.util.Collections +import java.util.concurrent.ConcurrentHashMap +import java.util.concurrent.ExecutorService +import java.util.concurrent.Executors + +/** + * Resolves the background-download × reconnect A-bucket bug. Previously every playlist sweep spawned + * a detached, un-deduped download `thread{}` writing a deterministic `${id}.ext.part` path. On a + * watchdog / ConnectionGuard reconnect the re-register drove a NEW sweep that started a DUPLICATE + * download of the same content mid-fetch — two writers racing the shared `.part` (a corrupt file + * whose byte-count still matched Content-Length, so it passed the integrity check and was promoted), + * plus orphaned threads piling up across reconnects, resurrecting "stuck downloading" through the + * reconnect path — the exact failure the caching fix was meant to eliminate. + * + * This coordinator makes background downloads reconnect-resilient: + * - SINGLE-FLIGHT per contentId: a reconnect's re-sweep never starts a second download for content + * already in flight. The in-flight fetch runs on its OWN OkHttp connection (independent of the + * socket), so a reconnect underneath it does not interrupt it — it CONTINUES and completes; if + * the network drop truncated it, ContentCache's partial detection discards the `.part` and it + * cleanly RESTARTS on a later sweep. Never orphaned, never a duplicate racing the `.part`. + * - BOUNDED executor: caps concurrent downloads (no thread pileup across reconnects); shutdown() + * cancels in-flight work so nothing orphans or pins the Activity. + * - BACKOFF with failure memory: a permanently-failing URL backs off exponentially instead of + * re-fetching every 60s forever (no retry storm). The screen keeps serving cached content + * (screen-resilience is untouched) and the CMS gets one "failed" ack, not a stuck "downloading". + * + * Atomic-swap + partial detection are ContentCache's job and are unchanged; this only guarantees a + * SINGLE writer per `.part` so that guarantee can't be defeated by a concurrent duplicate. + */ +class DownloadCoordinator( + private val cache: ContentCache, + private val serverUrl: () -> String, + private val socketAlive: () -> Boolean, + private val onAck: (contentId: String, status: String) -> Unit, + private val executor: ExecutorService = Executors.newFixedThreadPool(MAX_CONCURRENT), + private val now: () -> Long = { SystemClock.elapsedRealtime() } +) { + private val inFlight = Collections.synchronizedSet(HashSet()) + private val attempts = ConcurrentHashMap() + private val nextAttemptAt = ConcurrentHashMap() + + /** + * Ensure [contentId] is (being) downloaded. Called for each local assignment on EVERY playlist + * sweep — the 60s refresh and every post-reconnect re-register included. Idempotent and + * non-blocking: it enqueues at most ONE download per contentId and returns immediately. + */ + fun ensure(contentId: String, filename: String) { + if (contentId.isEmpty()) return + if (cache.isContentCached(contentId)) { onAck(contentId, "ready"); return } // already have it — re-ack (SEED-A) + // Socket down => the WATCHDOG owns recovery; don't hammer downloads over a dead connection. + if (!socketAlive()) return + if (now() < (nextAttemptAt[contentId] ?: 0L)) return // in failure backoff — don't storm + if (!inFlight.add(contentId)) return // single-flight: already downloading + try { + executor.execute { runDownload(contentId, filename) } + } catch (e: Throwable) { + inFlight.remove(contentId) // executor rejected (shut down) — don't leak the guard + } + } + + private fun runDownload(contentId: String, filename: String) { + try { + val file = cache.downloadContent(serverUrl(), contentId, filename) + if (file != null) { + attempts.remove(contentId); nextAttemptAt.remove(contentId) + // Ack only reaches a live socket; if it dropped, the reconnect's re-register clears + // the ack set and the next sweep re-acks the now-cached file. + if (socketAlive()) onAck(contentId, "ready") + } else { + onFailure(contentId) // includes a reconnect-truncated .part (ContentCache returned null) + } + } catch (e: Throwable) { + Log.w("DownloadCoordinator", "download $contentId failed: ${e.message}") + onFailure(contentId) + } finally { + inFlight.remove(contentId) + } + } + + private fun onFailure(contentId: String) { + val n = (attempts[contentId] ?: 0) + 1 + attempts[contentId] = n + val delay = minOf(BACKOFF_BASE_MS shl (n - 1).coerceIn(0, 20), BACKOFF_MAX_MS) + nextAttemptAt[contentId] = now() + delay + if (socketAlive()) onAck(contentId, "failed") + } + + /** Content deleted server-side — drop download/backoff state so a re-add downloads fresh. */ + fun forget(contentId: String) { + inFlight.remove(contentId); attempts.remove(contentId); nextAttemptAt.remove(contentId) + } + + /** Teardown (onDestroy): cancel in-flight downloads so none orphan or pin the Activity. */ + fun shutdown() { + try { executor.shutdownNow() } catch (_: Throwable) {} + inFlight.clear() + } + + // test visibility + internal fun isInFlight(contentId: String) = inFlight.contains(contentId) + + companion object { + const val MAX_CONCURRENT = 3 + const val BACKOFF_BASE_MS = 15_000L + const val BACKOFF_MAX_MS = 5 * 60_000L + } +} diff --git a/android/app/src/main/java/com/remotedisplay/player/player/MediaPlayerManager.kt b/android/app/src/main/java/com/remotedisplay/player/player/MediaPlayerManager.kt index ee47535..d954ec6 100644 --- a/android/app/src/main/java/com/remotedisplay/player/player/MediaPlayerManager.kt +++ b/android/app/src/main/java/com/remotedisplay/player/player/MediaPlayerManager.kt @@ -46,6 +46,14 @@ class MediaPlayerManager( onVideoComplete() } } + // Root-2: a corrupt/undecodable video used to freeze the playlist forever — only + // STATE_ENDED advanced, and an error goes to STATE_IDLE, so onVideoComplete never + // fired. Treat a playback error like a completion so the loop moves on instead of + // wedging on the broken item (mirrors the web/.wgt onerror -> advance). + override fun onPlayerError(error: androidx.media3.common.PlaybackException) { + Log.e("MediaPlayerManager", "Playback error (${error.errorCodeName}) — advancing: ${error.message}") + onVideoComplete() + } }) } } diff --git a/android/app/src/main/java/com/remotedisplay/player/player/PlaylistController.kt b/android/app/src/main/java/com/remotedisplay/player/player/PlaylistController.kt index b9d8a6c..ee4de70 100644 --- a/android/app/src/main/java/com/remotedisplay/player/player/PlaylistController.kt +++ b/android/app/src/main/java/com/remotedisplay/player/player/PlaylistController.kt @@ -31,8 +31,13 @@ class PlaylistController( private val onItemChanged: (PlaylistItem?) -> Unit, private val onPlaylistEmpty: () -> Unit, private val onRequestRefresh: (() -> Unit)? = null, - private val onNothingScheduled: (() -> Unit)? = null + private val onNothingScheduled: (() -> Unit)? = null, + // Screen-resilience: the defined "content isn't downloaded yet" waiting state, shown ONLY when + // nothing has ever played (fresh device). Never used while content is on screen. + private val onWaitingForContent: (() -> Unit)? = null ) { + private companion object { const val CONTENT_RECHECK_MS = 3000L } + private val items = mutableListOf() private var currentIndex = -1 private val handler = Handler(Looper.getMainLooper()) @@ -42,6 +47,14 @@ class PlaylistController( @Volatile private var effectiveTimezone: String? = null private var retryRunnable: Runnable? = null + // Screen-resilience: an item is playable only when its content is actually AVAILABLE + // (widget / remote-stream / fully-downloaded local file). Injected by MainActivity (which owns + // the cache); the default keeps every item playable so behavior is unchanged until it's set. + private var contentReady: (PlaylistItem) -> Boolean = { true } + fun setContentReadyCheck(f: (PlaylistItem) -> Boolean) { contentReady = f } + // True while a valid item is rendered on screen — so we NEVER blank it for a pending download. + private var hasContentOnScreen = false + // Video wall: followers don't self-advance — the leader's wall:sync drives the index. private var wallFollower = false // Wall-clock at which the current item started playing, for non-video sync position. @@ -149,9 +162,13 @@ class PlaylistController( } } // Current item was removed or nothing was playing - start from the first - // schedule-active item; idle if none are active right now. - val idx = firstActiveIndex() - if (idx >= 0) { currentIndex = idx; playCurrentItem() } else showNothingScheduled() + // schedule-active AND downloaded item. Distinguish the two idle reasons: daypart + // closed (nothing scheduled) => defined idle; scheduled-but-not-yet-downloaded => + // keep current content / waiting, never blank. + val fp = PlaylistSelection.firstPlayableIndex(items.size) { playableNow(it) } + if (fp >= 0) { currentIndex = fp; playCurrentItem() } + else if (firstActiveIndex() < 0) showNothingScheduled() + else onContentNotReady() } else { currentIndex = 0 } @@ -174,11 +191,12 @@ class PlaylistController( fun start() { isRunning = true if (items.isEmpty()) { onPlaylistEmpty(); return } - // #74/#75: begin on the first schedule-active item; idle if none. - val idx = firstActiveIndex() - if (idx < 0) { showNothingScheduled(); return } - currentIndex = idx - playCurrentItem() + // #74/#75: begin on the first schedule-active item; daypart-closed => defined idle. + if (firstActiveIndex() < 0) { showNothingScheduled(); return } + // Screen-resilience: only start on an item whose content is downloaded; if the scheduled + // content isn't ready yet, keep current/wait (never blank on a loading state). + val idx = PlaylistSelection.firstPlayableIndex(items.size) { playableNow(it) } + if (idx >= 0) { currentIndex = idx; playCurrentItem() } else onContentNotReady() } fun startIfNeeded() { @@ -200,17 +218,21 @@ class PlaylistController( isRunning = false cancelAdvance() cancelRetry() + hasContentOnScreen = false } fun next() { if (items.isEmpty()) return // Request a playlist refresh between plays so new content gets picked up onRequestRefresh?.invoke() - // #74/#75: advance to the next item the schedule allows now; idle if none. - val idx = nextActiveIndex(currentIndex) - if (idx < 0) { showNothingScheduled(); return } - currentIndex = idx - playCurrentItem() + // #74/#75: daypart closed (nothing scheduled now) => defined idle. + if (firstActiveIndex() < 0) { showNothingScheduled(); return } + // Screen-resilience: advance to the next schedule-active AND downloaded item. Unready items + // are SKIPPED (their background download continues), so a stalled/failed download of the + // next content never blanks the screen — we keep looping the content we already have. If + // NOTHING is downloaded yet, keep current content / show the waiting state, never blank. + val idx = PlaylistSelection.nextPlayableIndex(items.size, currentIndex) { playableNow(it) } + if (idx >= 0) { currentIndex = idx; playCurrentItem() } else onContentNotReady() } fun onVideoComplete() { @@ -227,6 +249,7 @@ class PlaylistController( itemStartedAt = System.currentTimeMillis() Log.i("PlaylistController", "Playing: ${item.filename} (index $currentIndex)") onItemChanged(item) + hasContentOnScreen = true // a valid item is now rendered — protect it from being blanked // For images and widgets, auto-advance after duration. For videos, wait // for the completion callback. Wall followers never auto-advance — the @@ -257,6 +280,40 @@ class PlaylistController( item.schedules.isEmpty() || ScheduleEval.isItemActiveNow(item.schedules, System.currentTimeMillis(), effectiveTimezone) + // Playable NOW = schedule-active AND its content is downloaded/available. + private fun playableNow(i: Int): Boolean = + i in items.indices && scheduleAllows(items[i]) && contentReady(items[i]) + + // Screen-resilience: the scheduled item(s) exist but their content isn't downloaded yet. + // NEVER blank a screen that is already showing content — keep it and re-check soon (the + // background download finishes, or the watchdog restores connectivity). Only show the defined + // waiting/setup state on a fresh device that has never played anything. + private fun onContentNotReady() { + cancelAdvance() + when (PlaylistSelection.whenNonePlayable(hasContentOnScreen)) { + PlaylistSelection.NonePlayable.KEEP_CURRENT -> { /* leave current content on screen */ } + PlaylistSelection.NonePlayable.SHOW_WAITING -> { + hasContentOnScreen = false + (onWaitingForContent ?: onNothingScheduled ?: onPlaylistEmpty)() + } + } + scheduleContentRecheck() + } + + // Re-evaluate playability shortly (a pending download may have finished / a daypart opened). + // Faster than the schedule re-check because a finished download should play promptly. + private fun scheduleContentRecheck() { + cancelRetry() + retryRunnable = Runnable { + if (isRunning && items.isNotEmpty()) { + if (firstActiveIndex() < 0) { showNothingScheduled(); return@Runnable } + val idx = PlaylistSelection.nextPlayableIndex(items.size, currentIndex) { playableNow(it) } + if (idx >= 0) { currentIndex = idx; playCurrentItem() } else onContentNotReady() + } + } + handler.postDelayed(retryRunnable!!, CONTENT_RECHECK_MS) + } + private fun firstActiveIndex(): Int { for (i in items.indices) if (scheduleAllows(items[i])) return i return -1 @@ -275,6 +332,7 @@ class PlaylistController( // daypart may open. (Boundary re-evaluation otherwise happens on advance.) private fun showNothingScheduled() { cancelAdvance() + hasContentOnScreen = false // the daypart genuinely closed — a defined idle, not a blank-bug (onNothingScheduled ?: onPlaylistEmpty)() cancelRetry() retryRunnable = Runnable { diff --git a/android/app/src/main/java/com/remotedisplay/player/player/PlaylistSelection.kt b/android/app/src/main/java/com/remotedisplay/player/player/PlaylistSelection.kt new file mode 100644 index 0000000..eefa073 --- /dev/null +++ b/android/app/src/main/java/com/remotedisplay/player/player/PlaylistSelection.kt @@ -0,0 +1,46 @@ +package com.remotedisplay.player.player + +/** + * Pure, unit-testable playlist SELECTION + screen-resilience decisions (no Android deps, same + * pattern as ConnectionGuard / OtaThrottle). PlaylistController is the imperative shell (Handler / + * playback); this owns "which item can play right now" and "what to do when none can", so the + * viewer-visible invariant has real coverage: + * + * a pending/failed/stalled content download must NEVER blank or freeze a screen that is showing + * content — the player keeps showing what it already has and only swaps to new content once it's + * fully + validly downloaded. + */ +object PlaylistSelection { + /** First index for which [isPlayable] holds, or -1 if none. */ + fun firstPlayableIndex(size: Int, isPlayable: (Int) -> Boolean): Int { + for (i in 0 until size) if (isPlayable(i)) return i + return -1 + } + + /** + * Next index after [from] (wrapping) for which [isPlayable] holds, or -1 if none. With a single + * playable item it returns that item (loop), so a device keeps looping the content it HAS while + * other items are still downloading. + */ + fun nextPlayableIndex(size: Int, from: Int, isPlayable: (Int) -> Boolean): Int { + if (size <= 0) return -1 + for (i in 1..size) { + val idx = (((from + i) % size) + size) % size + if (isPlayable(idx)) return idx + } + return -1 + } + + enum class NonePlayable { KEEP_CURRENT, SHOW_WAITING } + + /** + * When nothing is playable (e.g. the scheduled item's content isn't downloaded yet): NEVER + * blank a screen that is showing content. Keep the current content if we have some on screen; + * only fall to the defined waiting/setup state when there is genuinely nothing displayed yet + * (a fresh device that has never successfully played anything). This is the one decision that + * separates "nothing to show yet" (acceptable) from "had content but blanked while updating" + * (the bug this fix forbids). + */ + fun whenNonePlayable(hasContentOnScreen: Boolean): NonePlayable = + if (hasContentOnScreen) NonePlayable.KEEP_CURRENT else NonePlayable.SHOW_WAITING +} diff --git a/android/app/src/main/java/com/remotedisplay/player/service/LivenessWatchdog.kt b/android/app/src/main/java/com/remotedisplay/player/service/LivenessWatchdog.kt new file mode 100644 index 0000000..01a47ea --- /dev/null +++ b/android/app/src/main/java/com/remotedisplay/player/service/LivenessWatchdog.kt @@ -0,0 +1,60 @@ +package com.remotedisplay.player.service + +/** + * v4 canonical liveness contract — the pure, unit-testable decision logic for the client-side + * half-open watchdog (no Android / Socket.IO deps, same pattern as [ConnectionGuard] / + * [OtaThrottle]). WebSocketService is the imperative shell: it tracks lastServerMessageAt (ANY + * inbound refreshes it), arms only after a device:heartbeat-ack (degrade-safe), and on each + * heartbeat tick asks THIS object whether a connected-but-silent socket is half-open and, if so, + * whether the anti-thundering-herd backoff allows a reconnect now. + * + * ANTI-THUNDERING-HERD (must not become the flood #143/#149 fixed): the THRESHOLD is jittered + * (45s ± up to 10s) so a fleet doesn't all declare half-open at once under a shared cause (server + * load delaying acks), and the reconnect BACKOFF is exponential-with-jitter (1,2,4,8,16… capped, + * ±20%) so repeated failures spread out and back off instead of hammering. Load-adaptation is by + * the client's OWN ack-silence — there is deliberately NO status/health poll (that is itself a + * second herd). + * + * Canonical defaults match the .wgt and /player so all three exhibit identical on-the-wire + * behavior; a platform-driven deviation would be documented here. + */ +object LivenessWatchdog { + const val THRESHOLD_BASE_MS = 45_000L // v4 canonical: 45s … + const val THRESHOLD_JITTER_MS = 10_000L // … ± up to 10s + const val BACKOFF_BASE_MS = 1_000L // v4 canonical: 1s, 2s, 4s, 8s, 16s … + const val BACKOFF_CAP_MS = 30_000L // … capped (within the contract's ~30–60s band) + private const val BACKOFF_JITTER_FRACTION = 0.2 // … each ± ~20% + + /** + * Watchdog threshold with jitter: 45s ± up to 10s. [rand] is a uniform value in [0, 1) + * (injected so the pure logic is testable); the result is in [35s, 55s). + */ + fun thresholdMs(rand: Double): Long = + THRESHOLD_BASE_MS + ((rand - 0.5) * 2 * THRESHOLD_JITTER_MS).toLong() + + /** + * Exponential reconnect backoff with ±20% jitter. [attempt] is 1-based (the 1st reconnect + * uses the 1s step). Steps double (1s,2s,4s,8s,16s,…) and saturate at [BACKOFF_CAP_MS]; the + * shift is clamped so a large attempt count can't overflow. + */ + fun backoffMs(attempt: Int, rand: Double): Long { + val steps = (attempt - 1).coerceIn(0, 20) + val base = minOf(BACKOFF_BASE_MS shl steps, BACKOFF_CAP_MS) + val jitter = ((rand - 0.5) * 2 * BACKOFF_JITTER_FRACTION * base).toLong() + return base + jitter + } + + /** + * HALF-OPEN decision: reconnect only when a socket that is [connected] (Socket.IO still + * reports it up — the state its own auto-reconnect can't see) and whose liveness we have + * [armed] (seen ≥1 heartbeat-ack — degrade-safe: an ack-less/old server never arms us) has + * been silent longer than [thresholdMs]. Pure; mirrors the .wgt's watchdogShouldReconnect. + */ + fun isHalfOpen(armed: Boolean, connected: Boolean, silenceMs: Long, thresholdMs: Long): Boolean = + armed && connected && silenceMs > thresholdMs + + /** Backoff gate: a new reconnect attempt is allowed only once the backoff for the current + * attempt count has elapsed since the last one — spaces repeated failures fleet-wide. */ + fun mayReconnectNow(msSinceLastAttempt: Long, backoffMs: Long): Boolean = + msSinceLastAttempt >= backoffMs +} diff --git a/android/app/src/main/java/com/remotedisplay/player/service/WebSocketService.kt b/android/app/src/main/java/com/remotedisplay/player/service/WebSocketService.kt index 950a2f8..3a91ef9 100644 --- a/android/app/src/main/java/com/remotedisplay/player/service/WebSocketService.kt +++ b/android/app/src/main/java/com/remotedisplay/player/service/WebSocketService.kt @@ -8,7 +8,9 @@ import android.os.Binder import android.os.Handler import android.os.IBinder import android.os.Looper +import android.os.SystemClock import android.util.Log +import kotlin.random.Random import androidx.core.app.NotificationCompat import com.remotedisplay.player.MainActivity import com.remotedisplay.player.RemoteDisplayApp @@ -35,6 +37,20 @@ class WebSocketService : Service() { private var heartbeatRunnable: Runnable? = null private val binder = LocalBinder() + // v4 liveness watchdog state (see LivenessWatchdog for the pure decision logic). + // lastServerMessageAt: ANY inbound server message refreshes it (markAlive, wired into safeOn) — + // uses the monotonic elapsedRealtime clock so an NTP/wall-clock jump can't false-fire or blind + // the watchdog. livenessConfirmed: ARMED only after a device:heartbeat-ack (degrade-safe — an + // ack-less/old server never arms us, so no false-fire storm). currentThresholdMs: per-connection + // jittered 45s ± up to 10s. watchdogAttempt/lastWatchdogAttemptAt: exponential-backoff gate. + @Volatile private var lastServerMessageAt = 0L + @Volatile private var livenessConfirmed = false + @Volatile private var currentThresholdMs = LivenessWatchdog.THRESHOLD_BASE_MS + private var watchdogAttempt = 0 + private var lastWatchdogAttemptAt = 0L + + private fun markAlive() { lastServerMessageAt = SystemClock.elapsedRealtime() } + companion object { // #148: backoff before re-opening the single socket after a disconnect that Socket.IO // does NOT auto-reconnect (io server/client disconnect) — never a blind immediate re-open. @@ -101,6 +117,10 @@ class WebSocketService : Service() { // exception on the Socket.IO IO thread and crash the whole app. private fun Socket.safeOn(event: String, handler: (Array) -> Unit): Socket { on(event) { args -> + // v4: ANY inbound server message refreshes liveness (not just acks). The half-open + // decision additionally requires socket.connected(), so refreshing on a disconnect + // event is harmless. This is the single central receive-path hook. + markAlive() try { @Suppress("UNCHECKED_CAST") handler(args as Array) @@ -137,6 +157,14 @@ class WebSocketService : Service() { currentUrl = url socketActive = true + // v4 watchdog: a fresh socket is assumed alive; DIS-arm until it earns an ack again + // (degrade-safe), and pick a new jittered threshold for this connection so a fleet doesn't + // declare half-open in lockstep. watchdogAttempt is intentionally NOT reset here — it + // tracks repeated reconnect failures across sockets and resets on a healthy ack. + lastServerMessageAt = SystemClock.elapsedRealtime() + livenessConfirmed = false + currentThresholdMs = LivenessWatchdog.thresholdMs(Random.nextDouble()) + try { val options = IO.Options().apply { forceNew = true @@ -193,6 +221,17 @@ class WebSocketService : Service() { startHeartbeat() } + // v4 degrade-safe ARM: the watchdog arms ONLY after the first heartbeat-ack, so a + // server that never acks (old/pre-contract) never arms us -> no false-fire storm. + // markAlive already fired via safeOn (any inbound); a healthy ack also resets the + // reconnect backoff. Known ack-gap (reconnecting-not-yet-re-registered) is benign: + // arm-after-ack + any-inbound-refresh keep the watchdog from firing in that window. + safeOn("device:heartbeat-ack") { + if (!livenessConfirmed) Log.i("WebSocketService", "v4 watchdog: ARMED (first heartbeat-ack)") + livenessConfirmed = true + watchdogAttempt = 0 + } + safeOn("device:unpaired") { Log.w("WebSocketService", "Device not found on server - clearing credentials") config.clearDeviceCredentials() @@ -370,6 +409,19 @@ class WebSocketService : Service() { } } + // v4 client identity block — additive, canonical snake_case (same field shape as the .wgt and + // /player), piggybacked on the register message the client already sends. Backward-compatible: + // an old server ignores unknown fields. Capture-don't-act — the server stores it; no client + // logic is built on it here. + private fun JSONObject.putIdentity() { + try { + put("client_type", "apk") + put("client_version", deviceInfo.getAppVersion()) + put("platform", "Android " + android.os.Build.VERSION.RELEASE) + put("contract_version", "v4") + } catch (e: Throwable) { Log.w("WebSocketService", "identity: ${e.message}") } + } + private fun register() { try { val data = JSONObject().apply { @@ -388,6 +440,7 @@ class WebSocketService : Service() { } try { put("device_info", deviceInfo.getDeviceInfo()) } catch (e: Throwable) { Log.w("WebSocketService", "device_info: ${e.message}") } try { put("fingerprint", deviceInfo.getFingerprint()) } catch (e: Throwable) { Log.w("WebSocketService", "fingerprint: ${e.message}") } + putIdentity() } socket?.emit("device:register", data) } catch (e: Throwable) { @@ -407,18 +460,60 @@ class WebSocketService : Service() { heartbeatCount = 0 heartbeatRunnable = object : Runnable { override fun run() { + // A watchdog reconnect (below) tears down + restarts the heartbeat; if this is a + // stale runnable superseded by that restart, stop — never let two loops run. + if (heartbeatRunnable !== this) return sendHeartbeat() heartbeatCount++ // Every 4th heartbeat (60s), request a fresh playlist if (heartbeatCount % 4 == 0) { requestPlaylistRefresh() } + // v4 liveness watchdog: runs on the heartbeat tick (i.e. only while we've been + // SENDING heartbeats). If it detects+acts on a half-open socket it tears this loop + // down and a fresh one starts on re-register, so do NOT reschedule this one. + if (checkHalfOpenAndReconnect()) return handler.postDelayed(this, 15000) // Every 15 seconds } } handler.post(heartbeatRunnable!!) } + /** + * v4 half-open detection. On a HALF-OPEN socket Socket.IO still reports connected()==true + * (its own auto-reconnect can't see server-silence), so we detect it here: armed (saw an ack) + * + connected + silent past the jittered threshold. Returns true iff it triggered a reconnect + * (so the heartbeat loop stops). The exponential backoff gate spaces repeated attempts so the + * watchdog can't become the flood #143/#149 fixed. No status/health poll — load is read from + * our own ack-silence. + */ + private fun checkHalfOpenAndReconnect(): Boolean { + val connected = socket?.connected() == true + val silenceMs = SystemClock.elapsedRealtime() - lastServerMessageAt + if (!LivenessWatchdog.isHalfOpen(livenessConfirmed, connected, silenceMs, currentThresholdMs)) return false + val sinceAttempt = SystemClock.elapsedRealtime() - lastWatchdogAttemptAt + val backoff = LivenessWatchdog.backoffMs(watchdogAttempt + 1, Random.nextDouble()) + if (!LivenessWatchdog.mayReconnectNow(sinceAttempt, backoff)) return false + watchdogAttempt++ + lastWatchdogAttemptAt = SystemClock.elapsedRealtime() + Log.w("WebSocketService", "v4 watchdog: HALF-OPEN (silent ${silenceMs}ms > ${currentThresholdMs}ms, attempt=$watchdogAttempt) — teardown+reconnect (#148)") + reconnectHalfOpen() + return true + } + + /** + * Teardown-before-reopen (#148) for a half-open socket. disconnect() kills the dead socket AND + * its listeners/auto-reconnect FIRST (so we don't race Socket.IO's own reconnect), then + * connect() — with socket=null + socketActive=false — opens exactly ONE fresh socket via the + * ConnectionGuard. @Synchronized so it can't interleave with a racing connect()/openSocket(). + * The watchdog LAYERS ON the existing #148 guard; it does not replace it. + */ + @Synchronized + private fun reconnectHalfOpen() { + disconnect() + connect() + } + fun requestPlaylistRefresh() { if (socket?.connected() != true || config.deviceId.isEmpty()) return Log.i("WebSocketService", "Requesting playlist refresh") @@ -428,6 +523,7 @@ class WebSocketService : Service() { val token = config.deviceToken if (token.isNotEmpty()) put("device_token", token) try { put("device_info", deviceInfo.getDeviceInfo()) } catch (e: Throwable) { Log.w("WebSocketService", "device_info: ${e.message}") } + putIdentity() } socket?.emit("device:register", data) } catch (e: Throwable) { diff --git a/android/app/src/main/java/com/remotedisplay/player/telemetry/DeviceInfo.kt b/android/app/src/main/java/com/remotedisplay/player/telemetry/DeviceInfo.kt index 6f0ac58..553a857 100644 --- a/android/app/src/main/java/com/remotedisplay/player/telemetry/DeviceInfo.kt +++ b/android/app/src/main/java/com/remotedisplay/player/telemetry/DeviceInfo.kt @@ -174,7 +174,7 @@ class DeviceInfo(private val context: Context) { return dm.widthPixels to dm.heightPixels } - private fun getAppVersion(): String { + fun getAppVersion(): String { return try { context.packageManager.getPackageInfo(context.packageName, 0).versionName ?: "1.0.0" } catch (e: Exception) { diff --git a/android/app/src/test/java/com/remotedisplay/player/data/CacheValidationTest.kt b/android/app/src/test/java/com/remotedisplay/player/data/CacheValidationTest.kt new file mode 100644 index 0000000..6fa26f7 --- /dev/null +++ b/android/app/src/test/java/com/remotedisplay/player/data/CacheValidationTest.kt @@ -0,0 +1,30 @@ +package com.remotedisplay.player.data + +import org.junit.Assert.assertFalse +import org.junit.Assert.assertTrue +import org.junit.Test + +/** Root-2: the partial/truncated-download detection rule that keeps a broken file out of the cache. */ +class CacheValidationTest { + + @Test fun `full download with known length is complete`() { + assertTrue(CacheValidation.isComplete(bytesWritten = 100, expectedBytes = 100)) + } + + @Test fun `truncated download (fewer bytes than declared) is INCOMPLETE`() { + assertFalse(CacheValidation.isComplete(bytesWritten = 40, expectedBytes = 100)) + } + + @Test fun `over-read (more than declared) is treated as INCOMPLETE, not promoted`() { + assertFalse(CacheValidation.isComplete(bytesWritten = 150, expectedBytes = 100)) + } + + @Test fun `unknown length (chunked, -1) with bytes falls back to complete`() { + assertTrue(CacheValidation.isComplete(bytesWritten = 100, expectedBytes = -1)) + } + + @Test fun `zero bytes is never complete`() { + assertFalse(CacheValidation.isComplete(bytesWritten = 0, expectedBytes = -1)) + assertFalse(CacheValidation.isComplete(bytesWritten = 0, expectedBytes = 100)) + } +} diff --git a/android/app/src/test/java/com/remotedisplay/player/data/ContentDownloadTest.kt b/android/app/src/test/java/com/remotedisplay/player/data/ContentDownloadTest.kt new file mode 100644 index 0000000..c9ac893 --- /dev/null +++ b/android/app/src/test/java/com/remotedisplay/player/data/ContentDownloadTest.kt @@ -0,0 +1,119 @@ +package com.remotedisplay.player.data + +import okhttp3.OkHttpClient +import org.junit.After +import org.junit.Assert.assertEquals +import org.junit.Assert.assertNotNull +import org.junit.Assert.assertNull +import org.junit.Assert.assertTrue +import org.junit.Before +import org.junit.Test +import java.io.OutputStream +import java.net.ServerSocket +import java.nio.file.Files +import java.util.concurrent.TimeUnit + +/** + * Root-2 REPRODUCE-THEN-PROVE for the "stuck downloading / frozen" caching bug. Each test drives + * the REAL ContentCache.downloadContent against a local HTTP server that reproduces a specific + * failure mode on a HEALTHY socket (the socket is fine — the DOWNLOAD misbehaves), and proves the + * fix: a stalled/trickling download aborts instead of hanging forever, and a truncated body is + * never promoted to the cache (so it can't be played as if whole and wedge the playlist). + * + * The client uses short timeouts so the STALL reproduction is fast; the download/validation logic + * exercised is identical to production (only the timeout VALUES differ — production is + * callTimeout=5min / readTimeout=30s, verified by inspection in ContentCache.defaultClient()). + */ +class ContentDownloadTest { + + private lateinit var dir: java.io.File + private lateinit var cache: ContentCache + private var server: ServerSocket? = null + + private val client: OkHttpClient = OkHttpClient.Builder() + .connectTimeout(2, TimeUnit.SECONDS) + .readTimeout(1, TimeUnit.SECONDS) // a stalled stream aborts in ~1s => fast test + .callTimeout(3, TimeUnit.SECONDS) // hard overall cap backstop + .build() + + @Before fun setUp() { + dir = Files.createTempDirectory("cachetest").toFile() + cache = ContentCache(dir, client) // internal ctor — real logic, no Android Context + } + + @After fun tearDown() { + try { server?.close() } catch (_: Exception) {} + dir.deleteRecursively() + } + + /** Accept ONE connection, drain the request, then let [respond] write a crafted response. */ + private fun serveOnce(respond: (OutputStream) -> Unit): String { + val s = ServerSocket(0) + server = s + Thread { + try { + s.accept().use { sock -> + val reader = sock.getInputStream().bufferedReader() + while (true) { val line = reader.readLine() ?: break; if (line.isEmpty()) break } + respond(sock.getOutputStream()) + } + } catch (_: Exception) { /* client hung up on timeout — expected for the stall case */ } + }.apply { isDaemon = true; start() } + return "http://127.0.0.1:${s.localPort}" + } + + private fun OutputStream.writeHttp(contentLength: Int, body: ByteArray) { + write("HTTP/1.1 200 OK\r\nContent-Length: $contentLength\r\nContent-Type: application/octet-stream\r\n\r\n".toByteArray()) + write(body) + flush() + } + + private fun partFiles() = dir.listFiles { _, name -> name.endsWith(".part") }?.toList() ?: emptyList() + + // ---- positive control: a complete download IS cached ---- + @Test fun `complete download is cached with the right size and no leftover part file`() { + val url = serveOnce { it.writeHttp(5, "hello".toByteArray()) } + val file = cache.downloadContent(url, "cidA", "clip.bin") + assertNotNull("a complete download should be cached", file) + assertEquals(5L, file!!.length()) + assertNotNull(cache.getCachedFile("cidA")) + assertTrue("no .part temp should remain", partFiles().isEmpty()) + } + + // ---- REPRODUCE: truncated body (declares 100 bytes, sends 40 then closes) on a healthy socket ---- + @Test fun `truncated download is NOT promoted to the cache — partial detected and discarded`() { + val url = serveOnce { + it.writeHttp(100, ByteArray(40) { 'x'.code.toByte() }) + // close after 40 of the declared 100 bytes -> truncation + } + val file = cache.downloadContent(url, "cidB", "clip.bin") + assertNull("a truncated download must return null (not a usable file)", file) + assertNull("a truncated file must NOT be served as cached", cache.getCachedFile("cidB")) + assertTrue("the partial .part must be cleaned up, not left behind", partFiles().isEmpty()) + } + + // ---- REPRODUCE: a STALLED download (headers + a trickle, then hang) on a healthy socket ---- + @Test fun `stalled download aborts within the timeout instead of hanging forever`() { + val url = serveOnce { + it.write("HTTP/1.1 200 OK\r\nContent-Length: 100\r\n\r\n".toByteArray()) + it.write(ByteArray(10)); it.flush() + Thread.sleep(10_000) // hang mid-stream — the OLD client (5min readTimeout) waited here + } + val start = System.currentTimeMillis() + val file = cache.downloadContent(url, "cidC", "clip.bin") + val elapsed = System.currentTimeMillis() - start + assertNull("a stalled download must fail, not hang", file) + assertTrue("must abort quickly via the timeout (was ~$elapsed ms)", elapsed < 5_000) + assertNull(cache.getCachedFile("cidC")) + assertTrue("no partial left behind after a stall", partFiles().isEmpty()) + } + + // ---- prefix cross-match guard: an id that prefixes another must not match ---- + @Test fun `getCachedFile does not cross-match an id that is a prefix of another`() { + serveOnce { it.writeHttp(3, "abc".toByteArray()) }.let { url -> + assertNotNull(cache.downloadContent(url, "abc", "x.bin")) + } + assertNotNull(cache.getCachedFile("abc")) + assertNull("id 'ab' must NOT match cached 'abc.x'", cache.getCachedFile("ab")) + } +} diff --git a/android/app/src/test/java/com/remotedisplay/player/data/DownloadCoordinatorTest.kt b/android/app/src/test/java/com/remotedisplay/player/data/DownloadCoordinatorTest.kt new file mode 100644 index 0000000..62bea17 --- /dev/null +++ b/android/app/src/test/java/com/remotedisplay/player/data/DownloadCoordinatorTest.kt @@ -0,0 +1,194 @@ +package com.remotedisplay.player.data + +import com.remotedisplay.player.player.PlaylistSelection +import com.remotedisplay.player.service.ConnectionGuard +import com.remotedisplay.player.service.LivenessWatchdog +import okhttp3.OkHttpClient +import org.junit.After +import org.junit.Assert.assertEquals +import org.junit.Assert.assertFalse +import org.junit.Assert.assertNotNull +import org.junit.Assert.assertNull +import org.junit.Assert.assertTrue +import org.junit.Assert.fail +import org.junit.Before +import org.junit.Test +import java.io.OutputStream +import java.net.ServerSocket +import java.nio.file.Files +import java.util.Collections +import java.util.concurrent.CountDownLatch +import java.util.concurrent.ExecutorService +import java.util.concurrent.Executors +import java.util.concurrent.TimeUnit +import java.util.concurrent.atomic.AtomicInteger + +/** + * Reproduce-then-prove for the background-download × reconnect A-bucket bug. Drives the REAL + * DownloadCoordinator + ContentCache against a local server that can be GATED (held mid-response) + * so a download is genuinely in flight when a reconnect is simulated underneath it. + */ +class DownloadCoordinatorTest { + private lateinit var dir: java.io.File + private lateinit var cache: ContentCache + private lateinit var executor: ExecutorService + private lateinit var coord: DownloadCoordinator + private var server: ServerSocket? = null + + private val requests = AtomicInteger(0) + private val acks = Collections.synchronizedList(mutableListOf()) // "id:status" + @Volatile private var socketUp = true + @Volatile private var clock = 0L + private var baseUrl = "" + + private val client = OkHttpClient.Builder() + .connectTimeout(2, TimeUnit.SECONDS).readTimeout(2, TimeUnit.SECONDS).callTimeout(4, TimeUnit.SECONDS).build() + + @Before fun setUp() { + dir = Files.createTempDirectory("coord").toFile() + cache = ContentCache(dir, client) + executor = Executors.newFixedThreadPool(2) + requests.set(0); acks.clear(); socketUp = true; clock = 0L + coord = DownloadCoordinator(cache, { baseUrl }, { socketUp }, { c, s -> acks.add("$c:$s") }, executor, { clock }) + } + + @After fun tearDown() { + try { coord.shutdown() } catch (_: Exception) {} + try { executor.shutdownNow() } catch (_: Exception) {} + server?.close(); dir.deleteRecursively() + } + + // A server that accepts connections in a loop; each: counts, fires `arrived` on the 1st, awaits + // `gate` (if any), then writes `respond` and closes. Multiple connections are accepted, so a + // buggy DUPLICATE download shows up as requests==2. + private fun serve(gate: CountDownLatch?, arrived: CountDownLatch?, respond: (OutputStream) -> Unit) { + val s = ServerSocket(0); server = s; baseUrl = "http://127.0.0.1:${s.localPort}" + Thread { + try { + while (!s.isClosed) { + val sock = s.accept() + if (requests.incrementAndGet() == 1) arrived?.countDown() + Thread { + try { + val r = sock.getInputStream().bufferedReader() + while (true) { val l = r.readLine() ?: break; if (l.isEmpty()) break } + gate?.await(5, TimeUnit.SECONDS) + respond(sock.getOutputStream()); sock.close() + } catch (_: Exception) {} + }.apply { isDaemon = true; start() } + } + } catch (_: Exception) {} + }.apply { isDaemon = true; start() } + } + private fun full(body: String): (OutputStream) -> Unit = { o -> + o.write("HTTP/1.1 200 OK\r\nContent-Length: ${body.length}\r\n\r\n".toByteArray()); o.write(body.toByteArray()); o.flush() + } + private fun status(line: String): (OutputStream) -> Unit = { o -> + o.write("HTTP/1.1 $line\r\nContent-Length: 0\r\n\r\n".toByteArray()); o.flush() + } + private fun partFiles() = dir.listFiles { _, n -> n.endsWith(".part") }?.size ?: 0 + private fun await(l: CountDownLatch, what: String) = assertTrue("timeout waiting for $what", l.await(5, TimeUnit.SECONDS)) + private fun waitAck(key: String) { for (i in 0..60) { if (acks.contains(key)) return; Thread.sleep(100) }; fail("no ack '$key' (got $acks)") } + + // ===== THE REPRODUCE-THEN-PROVE: single-flight survives a reconnect mid-download ===== + @Test fun `reconnect mid-download starts NO duplicate — one request, in-flight fetch completes cleanly`() { + val gate = CountDownLatch(1); val arrived = CountDownLatch(1) + serve(gate, arrived, full("HELLObytes")) + coord.ensure("X", "v.bin") // download starts, blocks on the gate — genuinely in flight + await(arrived, "the download to reach the server") + assertTrue("X is in flight", coord.isInFlight("X")) + // SIMULATE THE RECONNECT: re-register drives more sweeps for the SAME content + coord.ensure("X", "v.bin"); coord.ensure("X", "v.bin") + Thread.sleep(300) // give any (buggy) duplicate time to connect + assertEquals("single-flight: exactly ONE request despite reconnect re-sweeps", 1, requests.get()) + gate.countDown() // let the in-flight download finish on its own connection + waitAck("X:ready") + assertNotNull("the in-flight download completes and is cached (not orphaned/abandoned)", cache.getCachedFile("X")) + assertEquals("no partial left", 0, partFiles()) + assertFalse("no longer in flight after completion", coord.isInFlight("X")) + } + + // ===== partial safety: a reconnect-truncated download is detected + not swapped ===== + @Test fun `reconnect-truncated download is detected as partial, acked failed, never swapped`() { + serve(null, null) { o -> // declares 100, sends 40 then closes — as a mid-fetch network drop would + o.write("HTTP/1.1 200 OK\r\nContent-Length: 100\r\n\r\n".toByteArray()); o.write(ByteArray(40)); o.flush() + } + coord.ensure("Y", "v.bin"); waitAck("Y:failed") + assertNull("a truncated file must NOT be cached/swapped", cache.getCachedFile("Y")) + assertEquals("no partial left behind", 0, partFiles()) + } + + // ===== permanent failure: backoff, no retry storm ===== + @Test fun `a permanently-failing download backs off instead of storming`() { + serve(null, null, status("404 Not Found")) + coord.ensure("Z", "v.bin"); waitAck("Z:failed") + val after1 = requests.get() + repeat(5) { coord.ensure("Z", "v.bin") }; Thread.sleep(300) // clock unchanged -> within backoff + assertEquals("within backoff, NO new attempts (no storm)", after1, requests.get()) + clock = 20_000 // past the first 15s backoff step + coord.ensure("Z", "v.bin"); Thread.sleep(300) + assertEquals("after backoff elapses, exactly one more attempt", after1 + 1, requests.get()) + } + + // ===== socket-down DEFER (ownership: watchdog owns recovery) ===== + @Test fun `socket down defers the download to the reconnect, then downloads when back`() { + serve(null, null, full("data")) + socketUp = false + coord.ensure("W", "v.bin"); Thread.sleep(300) + assertEquals("no download while the socket is down", 0, requests.get()) + socketUp = true + coord.ensure("W", "v.bin"); waitAck("W:ready") + assertNotNull("downloads once the socket is back", cache.getCachedFile("W")) + } + + // ===== teardown cancels in-flight work (no orphan / no Activity pin) ===== + @Test fun `shutdown cancels in-flight download and clears state`() { + val gate = CountDownLatch(1); val arrived = CountDownLatch(1) + serve(gate, arrived, full("data")) + coord.ensure("Q", "v.bin"); await(arrived, "in-flight download") + coord.shutdown() + assertFalse("in-flight guard cleared on shutdown (no orphan)", coord.isInFlight("Q")) + Thread.sleep(200) + assertNull("nothing cached — the download was cancelled, not abandoned mid-promote", cache.getCachedFile("Q")) + } + + // ===== 206 Partial Content is refused (never promoted as whole) ===== + @Test fun `a 206 partial-content response is refused, not promoted`() { + serve(null, null) { o -> // 206 with a matching partial length would pass a naive byte-count check + o.write("HTTP/1.1 206 Partial Content\r\nContent-Length: 3\r\n\r\n".toByteArray()); o.write("abc".toByteArray()); o.flush() + } + coord.ensure("P", "v.bin"); waitAck("P:failed") + assertNull("a 206 partial must not be cached as complete", cache.getCachedFile("P")) + } + + // ===== INTEGRATED RE-SOAK: playing -> bg download -> reconnect mid-download -> resume ===== + @Test fun `re-soak — one socket, no orphaned download, screen never blanks, download resumes`() { + val onlyZeroReady: (Int) -> Boolean = { it == 0 } // item 0 cached & playing; item 1 downloading + val threshold = LivenessWatchdog.thresholdMs(0.5) + val gate = CountDownLatch(1); val arrived = CountDownLatch(1) + serve(gate, arrived, full("item1data")) + + // playing item 0; item 1's background download is in flight + coord.ensure("item1", "v.bin"); await(arrived, "item1 download") + assertEquals("screen keeps playing item 0 (skips the still-downloading item 1)", 0, + PlaylistSelection.nextPlayableIndex(2, 0, onlyZeroReady)) + + // server goes silent -> watchdog fires (its own signal); screen must NOT blank + assertTrue(LivenessWatchdog.isHalfOpen(armed = true, connected = true, silenceMs = 50_000, thresholdMs = threshold)) + assertEquals(PlaylistSelection.NonePlayable.KEEP_CURRENT, PlaylistSelection.whenNonePlayable(hasContentOnScreen = true)) + + // watchdog reconnect -> exactly ONE socket via ConnectionGuard; the re-sweep does NOT dup the download + assertTrue(ConnectionGuard.shouldOpenNewSocket(hasSocket = false, sameUrl = true, socketActive = false)) + coord.ensure("item1", "v.bin"); Thread.sleep(200) + assertEquals("reconnect re-sweep did not orphan/duplicate the in-flight download", 1, requests.get()) + assertEquals("screen still shows item 0 across the reconnect", 0, + PlaylistSelection.nextPlayableIndex(2, 0, onlyZeroReady)) + + // download RESUMES (its own connection was never torn down) and completes cleanly + gate.countDown(); waitAck("item1:ready") + assertNotNull("item 1 downloaded (not orphaned) and is now swappable", cache.getCachedFile("item1")) + assertFalse(coord.isInFlight("item1")) + assertEquals("now both items ready -> screen advances to item 1 (only fully-valid content)", 1, + PlaylistSelection.nextPlayableIndex(2, 0) { true }) + } +} diff --git a/android/app/src/test/java/com/remotedisplay/player/player/PlaylistSelectionTest.kt b/android/app/src/test/java/com/remotedisplay/player/player/PlaylistSelectionTest.kt new file mode 100644 index 0000000..d4055bd --- /dev/null +++ b/android/app/src/test/java/com/remotedisplay/player/player/PlaylistSelectionTest.kt @@ -0,0 +1,60 @@ +package com.remotedisplay.player.player + +import org.junit.Assert.assertEquals +import org.junit.Test + +/** + * Screen-resilience (FIX 2): a pending/failed/stalled content download must NEVER blank or freeze + * a screen that is showing content. These prove the SELECTION rules that guarantee it — unready + * items are skipped (the player keeps looping what it has), and "nothing playable" keeps the + * current content whenever anything is on screen. + */ +class PlaylistSelectionTest { + + // helper: items 0..n-1, `ready` are the indices whose content is downloaded/available + private fun readyPredicate(vararg ready: Int): (Int) -> Boolean = { it in ready.toSet() } + + // ===== the KEY viewer scenario: playing item 0, item 1's download is stalled ===== + @Test fun `a stalled download of the NEXT item does not interrupt current content — it loops what it has`() { + // playlist [0 ready, 1 NOT ready(downloading)]; currently playing 0. Advancing must SKIP 1 + // and come back to 0, so the viewer keeps seeing content (no blank, no "Downloading…"). + val idx = PlaylistSelection.nextPlayableIndex(size = 2, from = 0, isPlayable = readyPredicate(0)) + assertEquals("must skip the un-downloaded item and keep playing item 0", 0, idx) + } + + @Test fun `once the download completes the next item is picked up on the following advance`() { + // now item 1 is downloaded too -> advancing from 0 swaps to 1 (only fully-ready content). + val idx = PlaylistSelection.nextPlayableIndex(size = 2, from = 0, isPlayable = readyPredicate(0, 1)) + assertEquals(1, idx) + } + + // ===== partial-file safety: an un-ready (partial/corrupt) item is never selected ===== + @Test fun `an un-ready (partial-download) item is never chosen to play`() { + // items [0 ready, 1 partial/not-ready, 2 ready] -> selection never returns 1. + assertEquals(0, PlaylistSelection.firstPlayableIndex(3, readyPredicate(0, 2))) + assertEquals(2, PlaylistSelection.nextPlayableIndex(3, 0, readyPredicate(0, 2))) + assertEquals(0, PlaylistSelection.nextPlayableIndex(3, 2, readyPredicate(0, 2))) + } + + // ===== nothing downloaded yet ===== + @Test fun `no item ready returns -1 (nothing to play)`() { + assertEquals(-1, PlaylistSelection.firstPlayableIndex(3, readyPredicate())) + assertEquals(-1, PlaylistSelection.nextPlayableIndex(3, 1, readyPredicate())) + } + + // ===== the invariant: never blank while content is on screen ===== + @Test fun `nothing-playable KEEPS current content whenever something is on screen (never blanks)`() { + assertEquals(PlaylistSelection.NonePlayable.KEEP_CURRENT, + PlaylistSelection.whenNonePlayable(hasContentOnScreen = true)) + } + + @Test fun `nothing-playable shows the defined waiting state only when nothing is displayed yet`() { + assertEquals(PlaylistSelection.NonePlayable.SHOW_WAITING, + PlaylistSelection.whenNonePlayable(hasContentOnScreen = false)) + } + + // ===== single downloaded item loops (doesn't blank waiting for others) ===== + @Test fun `a single downloaded item loops instead of blanking`() { + assertEquals(0, PlaylistSelection.nextPlayableIndex(1, 0, readyPredicate(0))) + } +} diff --git a/android/app/src/test/java/com/remotedisplay/player/service/AssemblyInteractionTest.kt b/android/app/src/test/java/com/remotedisplay/player/service/AssemblyInteractionTest.kt new file mode 100644 index 0000000..d7173b6 --- /dev/null +++ b/android/app/src/test/java/com/remotedisplay/player/service/AssemblyInteractionTest.kt @@ -0,0 +1,172 @@ +package com.remotedisplay.player.service + +import com.remotedisplay.player.data.ContentCache +import com.remotedisplay.player.player.PlaylistSelection +import okhttp3.OkHttpClient +import org.junit.After +import org.junit.Assert.assertEquals +import org.junit.Assert.assertFalse +import org.junit.Assert.assertNotNull +import org.junit.Assert.assertNull +import org.junit.Assert.assertTrue +import org.junit.Before +import org.junit.Test +import java.io.OutputStream +import java.net.ServerSocket +import java.nio.file.Files +import java.util.concurrent.TimeUnit + +/** + * APK VERIFY pass — the ASSEMBLY soak. Per-part tests prove the pieces; this proves the + * caching-state-machine × liveness-watchdog INTERACTION (the novel APK-only behavior) does not + * step on itself, driving the REAL ContentCache download + the REAL LivenessWatchdog decisions + * through the lifecycle sequence. + * + * Scope note (honest): the Handler/Looper/Socket.IO runtime can't run in a plain JVM unit test + * (no Robolectric in this module), so socket-teardown/timer wiring is verified by code-trace + + * ConnectionGuard's decisions; the DOWNLOAD path and every WATCHDOG DECISION here are the real + * production code exercised with real time. + */ +class AssemblyInteractionTest { + + private lateinit var dir: java.io.File + private lateinit var cache: ContentCache + private var server: ServerSocket? = null + private val client = OkHttpClient.Builder() + .connectTimeout(2, TimeUnit.SECONDS) + .readTimeout(1, TimeUnit.SECONDS) + .callTimeout(3, TimeUnit.SECONDS) + .build() + + @Before fun setUp() { + dir = Files.createTempDirectory("assembly").toFile() + cache = ContentCache(dir, client) + } + + @After fun tearDown() { + try { server?.close() } catch (_: Exception) {} + dir.deleteRecursively() + } + + private fun serveOnce(respond: (OutputStream) -> Unit): String { + val s = ServerSocket(0); server = s + Thread { + try { + s.accept().use { sock -> + val r = sock.getInputStream().bufferedReader() + while (true) { val l = r.readLine() ?: break; if (l.isEmpty()) break } + respond(sock.getOutputStream()) + } + } catch (_: Exception) {} + }.apply { isDaemon = true; start() } + return "http://127.0.0.1:${s.localPort}" + } + private fun serveComplete(body: String) = serveOnce { + it.write("HTTP/1.1 200 OK\r\nContent-Length: ${body.length}\r\n\r\n".toByteArray()) + it.write(body.toByteArray()); it.flush() + } + private fun serveStall() = serveOnce { + it.write("HTTP/1.1 200 OK\r\nContent-Length: 100\r\n\r\n".toByteArray()) + it.write(ByteArray(10)); it.flush(); Thread.sleep(10_000) + } + private fun partFiles() = dir.listFiles { _, n -> n.endsWith(".part") }?.toList() ?: emptyList() + + // ===== VERIFY 1: reconnect ownership — watchdog routes through ConnectionGuard (single owner) ===== + @Test fun `watchdog reconnect opens exactly one socket via ConnectionGuard, never its own`() { + // reconnectHalfOpen() = disconnect() [socket=null, socketActive=false] then connect(), and + // connect() consults ConnectionGuard. After teardown -> open exactly ONE. + assertTrue(ConnectionGuard.shouldOpenNewSocket(hasSocket = false, sameUrl = true, socketActive = false)) + // and a live/self-healing socket is REUSED (single-owner: never a second socket alongside). + assertFalse(ConnectionGuard.shouldOpenNewSocket(hasSocket = true, sameUrl = true, socketActive = true)) + } + + // ===== VERIFY 3 CHECK A: a caching stall/retry must NOT look like server-silence ===== + @Test fun `a stalled download does NOT trip the watchdog while the socket keeps getting acks`() { + // Real architecture: downloads run on their own thread; socket liveness is refreshed by + // heartbeat-acks (any inbound) every 15s, INDEPENDENT of download activity. Walk a 60s + // stall; an ack lands every 15s. Silence must never cross the (jitter-floor) threshold. + val threshold = LivenessWatchdog.thresholdMs(0.0) // 35s — the tightest (worst-case) threshold + var lastServerMs = 0L + var spurious = false + for (t in 0..60_000 step 1_000) { + if (t % 15_000 == 0) lastServerMs = t.toLong() // ack refresh — decoupled from the download + if (LivenessWatchdog.isHalfOpen(armed = true, connected = true, silenceMs = t - lastServerMs, thresholdMs = threshold)) + spurious = true + } + assertFalse("a download stall must NOT cause a watchdog reconnect while the socket is healthy", spurious) + } + + // ===== VERIFY 3 CHECK B: server-silence DURING a download -> watchdog fires; download unharmed ===== + @Test fun `server silence during a download fires the watchdog AND the download state stays consistent`() { + // The watchdog (server-silence) and the download (its own thread + .part file) are separate + // subsystems: the watchdog tears down the SOCKET, never the download or its files. + val threshold = LivenessWatchdog.thresholdMs(0.5) // 45s + assertTrue("50s of server silence is half-open", LivenessWatchdog.isHalfOpen(true, true, 50_000, threshold)) + val f = cache.downloadContent(serveComplete("payload!"), "cidB", "v.bin") + assertNotNull("the download completes independently of a socket reconnect", f) + assertEquals(8L, f!!.length()) + assertTrue("no partial left — download files untouched by any reconnect", partFiles().isEmpty()) + } + + // ===== VERIFY 3 CHECK C: no double-action — retry then success leaves ONE consistent file ===== + @Test fun `caching-timeout retry and watchdog do not double-act — retry yields one consistent file`() { + // 1st attempt stalls -> caching timeout -> null, partial cleaned (NOT a watchdog concern). + assertNull(cache.downloadContent(serveStall(), "cidC", "v.bin")) + assertTrue("stall leaves no orphan .part", partFiles().isEmpty()) + assertNull("stall does not promote a partial", cache.getCachedFile("cidC")) + // retry (healthy) -> exactly one cached file, no duplicates/orphans. + val f = cache.downloadContent(serveComplete("retry-ok"), "cidC", "v.bin") + assertNotNull(f); assertEquals(8L, f!!.length()) + assertEquals("exactly one cached artifact for the id", 1, + dir.listFiles { _, n -> n.startsWith("cidC.") }?.size ?: 0) + } + + // ===== VERIFY 4: degrade-safe + the deferred ack-gap window ===== + @Test fun `degrade-safe — an ack-less server never arms the watchdog, even when very silent`() { + assertFalse(LivenessWatchdog.isHalfOpen(armed = false, connected = true, silenceMs = 10 * 60_000, thresholdMs = 45_000)) + } + + // ===== FIX 1 + FIX 2 re-soak: through the whole sequence the SCREEN NEVER BLANKS ===== + @Test fun `re-soak — stall then ack-silence then watchdog reconnect then resume, screen never blanks`() { + // Device is PLAYING item 0 (downloaded); item 1's download is stalled. Walk every stage. + val onlyZeroReady: (Int) -> Boolean = { it == 0 } + val bothReady: (Int) -> Boolean = { true } + val threshold = LivenessWatchdog.thresholdMs(0.5) + + // 1) healthy, item 1 download STALLS on a live socket -> advancing SKIPS 1 and keeps 0 + // (a playable index is always found, so the screen shows content — never blanks), and + // the stall does NOT trip the watchdog. + assertEquals("skip the stalled item, keep playing 0", 0, + PlaylistSelection.nextPlayableIndex(2, 0, onlyZeroReady)) + assertFalse("download stall on a live socket must not trip the watchdog", + LivenessWatchdog.isHalfOpen(armed = true, connected = true, silenceMs = 5_000, thresholdMs = threshold)) + + // 2) server goes SILENT -> the watchdog fires on ITS signal, but the screen keeps content + assertTrue(LivenessWatchdog.isHalfOpen(true, true, 50_000, threshold)) + assertEquals("a reconnect must never blank a screen showing content", + PlaylistSelection.NonePlayable.KEEP_CURRENT, PlaylistSelection.whenNonePlayable(hasContentOnScreen = true)) + + // 3) watchdog reconnect -> EXACTLY ONE socket via ConnectionGuard (single owner) + assertTrue(ConnectionGuard.shouldOpenNewSocket(hasSocket = false, sameUrl = true, socketActive = false)) + + // 4) during the reconnect window, item 1 still not ready (downloads deferred, FIX 1) -> + // advancing still finds item 0 -> screen still shows content + assertEquals(0, PlaylistSelection.nextPlayableIndex(2, 0, onlyZeroReady)) + + // 5) reconnected + item 1 now fully downloaded -> swaps forward to item 1 (only ever swap + // to fully-valid content). At no stage did selection return -1 while 0 was ready, so the + // screen was never blanked. + assertEquals(1, PlaylistSelection.nextPlayableIndex(2, 0, bothReady)) + } + + @Test fun `ack-gap window — reconnecting-not-yet-re-registered does not false-fire`() { + // openSocket resets armed=false + lastServerMessageAt=now. Before the first post-reconnect + // ack, armed=false so NO fire even though the OLD connection's silence was large... + assertFalse("must not fire before the first post-reconnect ack", + LivenessWatchdog.isHalfOpen(armed = false, connected = true, silenceMs = 999_999, thresholdMs = 45_000)) + // ...and once any-inbound (the re-register response) refreshes liveness and an ack arms it, + // a fresh connection with small silence is healthy (still no fire). + assertFalse("healthy post-reconnect (armed, low silence) does not fire", + LivenessWatchdog.isHalfOpen(armed = true, connected = true, silenceMs = 500, thresholdMs = 45_000)) + } +} diff --git a/android/app/src/test/java/com/remotedisplay/player/service/LivenessWatchdogTest.kt b/android/app/src/test/java/com/remotedisplay/player/service/LivenessWatchdogTest.kt new file mode 100644 index 0000000..e9ff284 --- /dev/null +++ b/android/app/src/test/java/com/remotedisplay/player/service/LivenessWatchdogTest.kt @@ -0,0 +1,76 @@ +package com.remotedisplay.player.service + +import org.junit.Assert.assertEquals +import org.junit.Assert.assertFalse +import org.junit.Assert.assertTrue +import org.junit.Test + +/** + * v4 liveness-contract conformance for the pure watchdog decision logic. Proves: + * - degrade-safe (never fires unarmed) and the connected+silent half-open condition, + * - the anti-thundering-herd guarantees: threshold jitter (45s ± up to 10s) and exponential + * reconnect backoff with jitter (1,2,4,8,16… capped, ±20%) are PRESENT (not fixed values). + */ +class LivenessWatchdogTest { + + // ---- degrade-safe + half-open decision ---- + + @Test fun `unarmed never fires — degrade-safe against an ack-less server`() { + // Even a connected socket silent well past threshold must NOT reconnect until armed by an ack. + assertFalse(LivenessWatchdog.isHalfOpen(armed = false, connected = true, silenceMs = 999_999, thresholdMs = 45_000)) + } + + @Test fun `disconnected never fires — that is Socket_IO's job, not the watchdog's`() { + assertFalse(LivenessWatchdog.isHalfOpen(armed = true, connected = false, silenceMs = 999_999, thresholdMs = 45_000)) + } + + @Test fun `armed + connected + silent past threshold IS half-open`() { + assertTrue(LivenessWatchdog.isHalfOpen(armed = true, connected = true, silenceMs = 46_000, thresholdMs = 45_000)) + } + + @Test fun `armed + connected but within threshold is healthy`() { + assertFalse(LivenessWatchdog.isHalfOpen(armed = true, connected = true, silenceMs = 30_000, thresholdMs = 45_000)) + } + + // ---- anti-herd: threshold jitter 45s ± up to 10s ---- + + @Test fun `threshold is centered on 45s and stays within ±10s`() { + assertEquals(45_000L, LivenessWatchdog.thresholdMs(0.5)) + assertEquals(35_000L, LivenessWatchdog.thresholdMs(0.0)) + assertEquals(54_999L, LivenessWatchdog.thresholdMs(0.99995)) // ~55s upper bound (exclusive) + for (i in 0..100) { + val t = LivenessWatchdog.thresholdMs(i / 100.0) + assertTrue("threshold $t out of [35s,55s)", t in 35_000..55_000) + } + } + + @Test fun `threshold has jitter — different rands give different thresholds (not fixed)`() { + assertTrue(LivenessWatchdog.thresholdMs(0.1) != LivenessWatchdog.thresholdMs(0.9)) + } + + // ---- anti-herd: exponential backoff 1,2,4,8,16… capped, ±20% jitter ---- + + @Test fun `backoff doubles per attempt then saturates at the cap`() { + // rand=0.5 => no jitter, so we see the exact base curve. + assertEquals(1_000L, LivenessWatchdog.backoffMs(1, 0.5)) + assertEquals(2_000L, LivenessWatchdog.backoffMs(2, 0.5)) + assertEquals(4_000L, LivenessWatchdog.backoffMs(3, 0.5)) + assertEquals(8_000L, LivenessWatchdog.backoffMs(4, 0.5)) + assertEquals(16_000L, LivenessWatchdog.backoffMs(5, 0.5)) + assertEquals(30_000L, LivenessWatchdog.backoffMs(6, 0.5)) // 32s -> capped at 30s + assertEquals(30_000L, LivenessWatchdog.backoffMs(50, 0.5)) // no overflow at large attempts + } + + @Test fun `backoff jitter is ±20% of the step and present (not fixed)`() { + // attempt 5 base = 16s; ±20% => [12.8s, 19.2s]. + assertEquals(12_800L, LivenessWatchdog.backoffMs(5, 0.0)) // -20% + assertEquals(19_200L, LivenessWatchdog.backoffMs(5, 1.0)) // +20% + assertTrue(LivenessWatchdog.backoffMs(5, 0.2) != LivenessWatchdog.backoffMs(5, 0.8)) + } + + @Test fun `mayReconnectNow gates on the backoff having elapsed`() { + assertTrue(LivenessWatchdog.mayReconnectNow(msSinceLastAttempt = 2_000, backoffMs = 1_000)) + assertTrue(LivenessWatchdog.mayReconnectNow(msSinceLastAttempt = 1_000, backoffMs = 1_000)) + assertFalse(LivenessWatchdog.mayReconnectNow(msSinceLastAttempt = 500, backoffMs = 1_000)) + } +} From bcbb3752c645e8df10832608a8c49e723502438b Mon Sep 17 00:00:00 2001 From: ScreenTinker Date: Wed, 8 Jul 2026 09:58:42 -0500 Subject: [PATCH 07/20] =?UTF-8?q?feat(tizen):=20.wgt=20v4=20delta=20?= =?UTF-8?q?=E2=80=94=20arm-after-ack,=20threshold/backoff=20params,=20iden?= =?UTF-8?q?tity=20block?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Tizen .wgt v4-conformance delta — client-only, targeted (the lifecycle hardening was already merged; this only closes the v4 gaps the .wgt predated): - Arm-after-ack (the behavioral change): the watchdog arms ONLY after a device:heartbeat-ack, not on any inbound/engine ping — so an ack-less/old server never arms it (degrade-safe). markAlive still refreshes lastServerMessageAt on any inbound for the silence check; arming gates on the ack. - Threshold: fixed 35s -> v4 canonical 45s ± up to 10s jitter (re-jittered per connect). - Backoff params: 1s start / 30s cap / ±20% jitter (was 2s/10s/±50%), exp-double kept. - v4 client identity block on register (client_type=wgt / client_version / platform / contract_version=v4), canonical snake_case matching the APK. - No-poll confirmed. Preserved untouched: keep-awake re-assert, resume handler, #148 teardown-before-reopen, 4th-beat refresh, unpaired 3s backoff. Verified: arm-after-ack both directions (engine-ping-no-ack -> NOT armed; ack -> arms + catches half-open), v4 runtime values, #148 one-socket-one-register, server suite green. Depends on the server device:heartbeat-ack (core pass) — degrade-safe until then. Co-Authored-By: Claude Opus 4.8 (1M context) --- tizen/js/app.js | 66 +++++++++++++++++++++++++++---------------------- 1 file changed, 36 insertions(+), 30 deletions(-) diff --git a/tizen/js/app.js b/tizen/js/app.js index 19a0327..3ac68ad 100644 --- a/tizen/js/app.js +++ b/tizen/js/app.js @@ -158,20 +158,22 @@ // the watchdog and the resume fast-path can't double-fire a second reconnect. Client-only: uses // signals the server already sends; no server change. var lastServerMsgAt = 0; - var livenessConfirmed = false; // H1: DON'T arm until the server has actually talked to us - var DEFAULT_LIVENESS_MS = 35000; - var livenessWindowMs = DEFAULT_LIVENESS_MS; // H1: derived from the negotiated engine pingInterval per connect + var livenessConfirmed = false; // v4 degrade-safe: DON'T arm until a device:heartbeat-ack + // v4 canonical anti-herd THRESHOLD: 45s ± up to 10s random jitter (was a fixed 35s), so a fleet + // doesn't all declare half-open simultaneously under a shared cause (server load delaying acks + // fleet-wide). Matches the APK's LivenessWatchdog.thresholdMs so the three clients behave + // identically on the wire. Re-jittered per connect(). + var THRESHOLD_BASE_MS = 45000, THRESHOLD_JITTER_MS = 10000; + function thresholdMs(rand) { return THRESHOLD_BASE_MS + Math.round((rand - 0.5) * 2 * THRESHOLD_JITTER_MS); } + var livenessWindowMs = THRESHOLD_BASE_MS; var watchdogTimer = null; - function markAlive() { lastServerMsgAt = mono(); livenessConfirmed = true; } // central receive-path hook; A5 monotonic - // H1 (config-proof): adapt the silence window to whatever pingInterval the SERVER negotiated, so a larger - // server pingInterval can't make the client false-fire into a reconnect storm. 2 intervals + 5s margin, - // floored at the 35s default (which is 2×15s+5s). Called from the 'connect' handler once the handshake is known. - function setLivenessWindowFromPing(pingIntervalMs) { - if (pingIntervalMs && pingIntervalMs > 0) livenessWindowMs = Math.max(DEFAULT_LIVENESS_MS, 2 * pingIntervalMs + 5000); - } - // Pure, unit-testable. Reconnect ONLY when a connected+authenticated socket whose liveness we have CONFIRMED - // (seen >=1 real inbound signal — H1 degrade-safe: a server that never talks never arms the watchdog, so no - // storm) has gone silent past the server-derived window. + // v4: ANY inbound refreshes the SILENCE timestamp (so other server traffic keeps a healthy socket + // alive) — but it does NOT arm. Arming gates on the ack specifically (see the device:heartbeat-ack + // handler), so engine pings alone can't arm us against an ack-less server. + function markAlive() { lastServerMsgAt = mono(); } // A5 monotonic + // Pure, unit-testable. Reconnect ONLY when a connected+authenticated socket whose liveness we have + // ARMED (seen >=1 device:heartbeat-ack — v4 degrade-safe: a server that never app-acks never arms + // us, so no false-fire even though engine pings keep flowing) has gone silent past the window. function watchdogShouldReconnect(hasSocket, connected, authed, confirmed, silentMs, windowMs) { return !!(hasSocket && connected && authed && confirmed && silentMs > windowMs); } @@ -185,7 +187,7 @@ }, 10000); } function stopWatchdog() { if (watchdogTimer) { clearInterval(watchdogTimer); watchdogTimer = null; } } - if (typeof window !== 'undefined') { window.__stWatchdogShouldReconnect = watchdogShouldReconnect; window.__stSetLivenessWindowFromPing = setLivenessWindowFromPing; } + if (typeof window !== 'undefined') { window.__stWatchdogShouldReconnect = watchdogShouldReconnect; window.__stThresholdMs = thresholdMs; } // ---- networking ---- var socket = null; @@ -233,10 +235,10 @@ socket = io(base + '/device', { transports: ['websocket', 'polling'], reconnection: true, - reconnectionDelay: 2000, - reconnectionDelayMax: 10000, - randomizationFactor: 0.5, // A6: ±50% jitter so a fleet of TVs doesn't reconnect in lockstep (thundering herd) after a server restart — matches the APK - timeout: 20000 // cheap parity (GAP4c): match /player + APK; 10s prematurely errored slow TV WebKit / WS-blocked networks + reconnectionDelay: 1000, // v4 canonical: 1s start (was 2s) + reconnectionDelayMax: 30000, // v4 canonical: 30s cap, within the ~30-60s band (was 10s) + randomizationFactor: 0.2, // v4 canonical: ±20% jitter (was ±50%); exponential-double shape kept + timeout: 20000 // cheap parity (GAP4c): match /player + APK; 10s prematurely errored slow TV WebKit / WS-blocked networks }); // FIX B (hardened): central receive-path liveness. A fresh socket is assumed alive; then EVERY @@ -245,20 +247,12 @@ // double-fire, and feeds the watchdog's server-silence detection. (io() returns a fresh socket // per connect — verified — so these listeners don't accumulate.) lastServerMsgAt = mono(); // A5 monotonic - livenessConfirmed = false; // H1: arm the watchdog only after a real inbound signal - livenessWindowMs = DEFAULT_LIVENESS_MS; // reset; refined from the handshake on 'connect' - socket.onAny(markAlive); - socket.io.on('ping', markAlive); + livenessConfirmed = false; // v4 degrade-safe: DIS-arm until a heartbeat-ack re-arms + livenessWindowMs = thresholdMs(Math.random()); // v4: fresh 45s ± up to 10s jitter for this connection + socket.onAny(markAlive); // refresh SILENCE on any inbound (does not arm) + socket.io.on('ping', markAlive); // engine ping refreshes silence too (still does not arm) socket.on('connect', function () { - // H1: derive the liveness window from the pingInterval the SERVER negotiated at the handshake, - // so raising server PING_INTERVAL can't make the watchdog false-fire (config-proof). The engine - // exposes it as `pingInterval` (socket.io-client 4.7.x, the bundled .wgt client) or `_pingInterval` - // (4.8.x); read both, and fall back to the 35s default if neither is present. - try { - var eng = socket.io && socket.io.engine; - setLivenessWindowFromPing(eng && (eng.pingInterval || eng._pingInterval)); - } catch (e) {} // #118: a brand-new socket is not authenticated until device:registered. Reset the // flag and kill any heartbeat carried over from the previous socket, so a beat can't // fire on this fresh, unregistered connection (TV sleep/wake reconnects often). @@ -295,6 +289,12 @@ if (data.status === 'provisioning') showPairing(); }); + // v4 degrade-safe ARM: the watchdog arms ONLY after the first app-level device:heartbeat-ack. + // A server that sends engine pings but no app-ack (old/pre-contract server) never arms us, so the + // watchdog can't false-fire — markAlive (onAny) still refreshed lastServerMsgAt for the silence + // check, but ARMING is gated on the ack specifically. + socket.on('device:heartbeat-ack', function () { livenessConfirmed = true; }); + socket.on('device:paired', function () { del(LS.code); clearToast(); show(elStage); }); @@ -378,6 +378,12 @@ function register() { var msg = { device_info: deviceInfo(), fingerprint: fingerprint() }; + // v4 client identity block — additive, canonical snake_case (same field shape as the APK, so the + // server consumes one thing). Backward-compatible: an old server ignores unknown fields. + msg.client_type = 'wgt'; + msg.client_version = APP_VERSION; // config.xml version (stamped by build-wgt.sh) + msg.platform = 'Tizen ' + (tizenVersion() || ''); + msg.contract_version = 'v4'; if (deviceId && deviceToken) { msg.device_id = deviceId; msg.device_token = deviceToken; } else { msg.pairing_code = pairingCode(); } socket.emit('device:register', msg); From 80d6242806697012fb4bc65ab6c228732f7a5598 Mon Sep 17 00:00:00 2001 From: ScreenTinker Date: Wed, 8 Jul 2026 10:34:05 -0500 Subject: [PATCH 08/20] =?UTF-8?q?feat(player):=20v4=20liveness=20contract?= =?UTF-8?q?=20=E2=80=94=20throttle-aware=20watchdog=20+=20browser=20trigge?= =?UTF-8?q?rs=20+=20identity?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit /player v4 — client-only (served web player). Brings the browser player onto the locked v4 liveness contract, IDENTICAL on the wire to the now-v4 APK and .wgt: - v4 liveness watchdog: consume device:heartbeat-ack, lastServerMessageAt refreshes on ANY inbound (onAny + engine ping) while ARMING gates on the ack (degrade-safe); 45s±10s jittered threshold; backoff 1s/30s/±0.2 on the socket.io Manager; NO status/health poll; teardown-before-reopen (#148). - Browser-specific half-open triggers (the /player-unique part): Page Visibility, sleep/resume (pageshow/bfcache), network change (online) — all drive the SAME #148 teardown-first reconnect. - THROTTLE-AWARE: silence computed by timestamp (not timer-fire-count); watchdog does NOT act while the tab is HIDDEN (throttled-timer gap is expected); on becoming visible, verifyLivenessSoon() resets the grace and reconnects ONLY if genuinely dead — never spuriously tears down a live socket. - v4 client identity block on register (client_type=player / client_version / platform / v4). Verified: arm-after-ack both directions, v4 values MATCH .wgt exactly, browser-trigger no-duplicate- socket, throttle-aware reproduce-then-prove (real extracted checkLiveness/verifyLivenessSoon), foreground-recovery one-socket. Depends on the server device:heartbeat-ack (core pass) — degrade-safe until then. Co-Authored-By: Claude Opus 4.8 (1M context) --- server/player/index.html | 96 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 93 insertions(+), 3 deletions(-) diff --git a/server/player/index.html b/server/player/index.html index c5b8418..060ccf1 100644 --- a/server/player/index.html +++ b/server/player/index.html @@ -745,6 +745,65 @@ container.appendChild(note); } + // ==================== v4 liveness watchdog ==================== + // Brings /player onto the LOCKED v4 contract, IDENTICAL on the wire to the APK and .wgt. + // Threshold 45s ± up to 10s jitter (canonical); arm ONLY after a device:heartbeat-ack + // (degrade-safe — an ack-less server never arms us); lastServerMessageAt refreshes on ANY + // inbound (the SILENCE check) while ARMING gates on the ack. Backoff (1s→30s ±20%) is on the + // socket.io Manager (io opts below). NO status/health poll — load is read from ack-silence. + // Browser-specific half-open triggers (visibility/resume/online) drive the SAME check + the + // #148 teardown-first reconnect — additional triggers, not a separate mechanism. + const PLAYER_VERSION = '1.1.0-web'; + const V4_THRESHOLD_BASE_MS = 45000, V4_THRESHOLD_JITTER_MS = 10000; + function v4ThresholdMs(rand) { return V4_THRESHOLD_BASE_MS + Math.round((rand - 0.5) * 2 * V4_THRESHOLD_JITTER_MS); } + // Wall-clock (Date.now) so silence COUNTS sleep/background time — the browser half-open causes + // (a setInterval tick alone would be throttled/frozen in a hidden tab and undercount). + let lastServerMessageAt = 0; + let livenessConfirmed = false; + let livenessWindowMs = V4_THRESHOLD_BASE_MS; + let watchdogTimer = null; + function markAlive() { lastServerMessageAt = Date.now(); } // ANY inbound refreshes silence (does NOT arm) + // Pure decision (matches the APK/.wgt watchdogShouldReconnect): reconnect only a connected + + // registered socket whose liveness we've ARMED that has gone silent past the jittered window. + function watchdogShouldReconnect(hasSocket, connected, armed, silentMs, windowMs) { + return !!(hasSocket && connected && armed && silentMs > windowMs); + } + function checkLiveness() { + // THROTTLE-AWARE. (1) Silence is computed by TIMESTAMP (now - lastServerMessageAt), never by + // timer-fire-count, so a background-THROTTLED/late timer still measures the ACTUAL elapsed + // silence — it won't miss a real half-open for firing late, nor false-fire for firing late. + // (2) While the tab is HIDDEN, timers are throttled and the gap is EXPECTED — do NOT act on it + // (never reconnect a backgrounded tab). The hidden->visible transition resets the grace via + // verifyLivenessSoon(), so we don't false-fire on resume either. + if (document.visibilityState !== 'visible') return; + const silentMs = lastServerMessageAt ? (Date.now() - lastServerMessageAt) : 0; + if (watchdogShouldReconnect(!!socket, !!(socket && socket.connected), livenessConfirmed, silentMs, livenessWindowMs)) { + console.log('[v4] half-open (silent ' + silentMs + 'ms > ' + livenessWindowMs + ') — teardown+reconnect'); + connect(config.serverUrl); // #148 teardown-before-reopen: connect() disconnects the old socket first + } + } + // Fresh liveness check for a resume / bfcache-restore / network-change: silence accumulated + // while hidden or throttled is NOT trustworthy, so NEVER tear down a possibly-live socket on it. + // Reset the grace so the socket gets a fresh window to prove itself — a live socket's engine + // ping/ack refreshes silence within the window (no reconnect); a genuinely dead one stays silent + // past the window and the (now-visible) watchdog reconnects it. #148 teardown-first via connect(). + function verifyLivenessSoon() { + lastServerMessageAt = Date.now(); // fresh grace — don't false-fire on stale hidden-silence + if (!socket) connect(config.serverUrl); // never connected / torn down -> establish (teardown-first) + // socket connected -> grace reset above; the watchdog verifies over the next window. + // socket present-but-disconnected -> socket.io's own reconnection already owns it. + } + function startWatchdog() { stopWatchdog(); watchdogTimer = setInterval(checkLiveness, 10000); } + function stopWatchdog() { if (watchdogTimer) { clearInterval(watchdogTimer); watchdogTimer = null; } } + function browserPlatform() { + try { + const m = navigator.userAgent.match(/(Edg|OPR|Chrome|Firefox|Version)\/(\d+)/); + if (m) { const name = { Edg: 'Edge', OPR: 'Opera', Version: 'Safari' }[m[1]] || m[1]; return name + ' ' + m[2]; } + return 'Browser'; + } catch (e) { return 'Browser'; } + } + if (typeof window !== 'undefined') { window.__v4ThresholdMs = v4ThresholdMs; window.__v4WatchdogShouldReconnect = watchdogShouldReconnect; } + // ==================== Socket Connection ==================== function connect(serverUrl) { if (socket) { socket.disconnect(); socket = null; } @@ -752,8 +811,9 @@ socket = io(serverUrl + '/device', { reconnection: true, reconnectionAttempts: Infinity, - reconnectionDelay: 2000, - reconnectionDelayMax: 10000, + reconnectionDelay: 1000, // v4 canonical: 1s start (was 2s) + reconnectionDelayMax: 30000, // v4 canonical: 30s cap, within the ~30-60s band (was 10s) + randomizationFactor: 0.2, // v4 canonical: ±20% jitter (was the socket.io 0.5 default) timeout: 20000, // Prefer WebSocket but allow polling fallback. Socket.IO default is // polling-first with an upgrade dance that's fragile on TV WebKits @@ -765,6 +825,17 @@ transports: ['websocket', 'polling'], }); + // v4 liveness: a fresh socket is assumed alive; DIS-arm until a heartbeat-ack re-arms; pick a + // fresh jittered window for this connection. markAlive on ANY inbound (app events via onAny + + // the engine ping) refreshes the SILENCE timer only — it does NOT arm. + lastServerMessageAt = Date.now(); + livenessConfirmed = false; + livenessWindowMs = v4ThresholdMs(Math.random()); + socket.onAny(markAlive); + socket.io.on('ping', markAlive); + // v4 degrade-safe ARM: the watchdog arms ONLY after the first app-level device:heartbeat-ack. + socket.on('device:heartbeat-ack', () => { livenessConfirmed = true; }); + socket.on('connect', () => { console.log('Connected'); register(); @@ -773,6 +844,7 @@ socket.on('disconnect', () => { console.log('Disconnected'); stopHeartbeat(); + stopWatchdog(); // socket.io owns the reconnect once it KNOWS it's down; watchdog is for half-open only }); socket.on('connect_error', (err) => { @@ -797,6 +869,7 @@ } startHeartbeat(); + startWatchdog(); // v4: arm-gated half-open watchdog (no-op until a heartbeat-ack arms it) startPlaylistRefresh(); startVersionCheck(); }); @@ -1082,6 +1155,12 @@ screen_width: screen.width, screen_height: screen.height, }; + // v4 client identity block — additive, canonical snake_case (same shape as APK/.wgt so the + // server consumes one thing). Backward-compatible: an old server ignores unknown fields. + data.client_type = 'player'; + data.client_version = PLAYER_VERSION; + data.platform = browserPlatform(); + data.contract_version = 'v4'; // Browser fingerprint (survives localStorage clear) data.fingerprint = generateBrowserFingerprint(); console.log(`[register] device_id=${data.device_id || 'none'}, has_token=${!!data.device_token}, token_len=${data.device_token?.length || 0}, paired=${config.paired}, pairing_code=${data.pairing_code || 'none'}`); @@ -2193,7 +2272,18 @@ } catch {} } requestWakeLock(); - document.addEventListener('visibilitychange', () => { if (document.visibilityState === 'visible') requestWakeLock(); }); + // v4 browser half-open triggers: tab foreground / bfcache resume / network change all drive the + // SAME liveness check + #148 teardown-first reconnect (checkLiveness -> connect() only if the + // socket is armed+connected+silent-past-window). checkLiveness no-ops on a healthy socket, so a + // visibility change does NOT spawn a duplicate socket (the classic browser bug). + document.addEventListener('visibilitychange', () => { + // On becoming visible after a (possibly throttled/frozen) background stint, do the fresh + // liveness check — reset the grace and reconnect ONLY if genuinely dead; never spuriously + // tear down a live socket on the hidden->visible gap. + if (document.visibilityState === 'visible') { requestWakeLock(); verifyLivenessSoon(); } + }); + window.addEventListener('pageshow', verifyLivenessSoon); // sleep/resume via bfcache restore + window.addEventListener('online', verifyLivenessSoon); // network switch (wifi<->cellular) // Register service worker for offline content caching if ('serviceWorker' in navigator) { From 4cf156d4a08cc6feb06b8131ad03b2afd606edc5 Mon Sep 17 00:00:00 2001 From: ScreenTinker Date: Wed, 8 Jul 2026 11:18:55 -0500 Subject: [PATCH 09/20] =?UTF-8?q?feat(server):=20v4=20liveness=20CORE=20pa?= =?UTF-8?q?ss=20=E2=80=94=20uniform=20heartbeat-ack=20+=20ack-gap=20+=20da?= =?UTF-8?q?shboard=20liveness=20+=20identity?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Server-side keystone: the server now honors the v4 liveness contract uniformly across the MIXED fleet (v4 + old pre-v4 + disconnected), all three clients depending on it. - UNIFORM heartbeat-ack: emitted from the single shared device:heartbeat handler (uniform by construction; no per-client/per-path branch), BEFORE the auth guard so a known device's watchdog stays armed. Harmless to old clients (they ignore it). - RECONNECT-WINDOW ack-gap fix (ackableHeartbeat): ack a KNOWN device (authed socket OR a device_id that resolves) even mid-reconnect; NOT anonymous/never-authenticated sockets (degrade-safe); identity-agnostic. No state mutation before requireDeviceAuth (auth surface unchanged; device_ids are uuidv4). - DASHBOARD LIVENESS (deriveLiveness): server-derived, VERSION-AGNOSTIC Healthy/Degraded/Offline from signals every client sends (socket presence, heartbeat age, reconnect frequency); no client status-push. - IDENTITY CAPTURE (capture-don't-act): client_type/client_version/platform/contract_version columns; degrades to legacy/unknown for old clients; NEVER breaks register. - A-BUCKET FIX (QA): recordReconnect + persistIdentity gated on !isPlaylistRefresh (a ~45-60s refresh is not a reconnect/new identity — matches #134), and the identity write is change-detected — closing the WAL write-amplification (A1) and the benign-refresh -> false-"Degraded" (A2) regressions. New lib/liveness.js (pure helpers, unit-tested). 30 new tests (uniform ack, ack-gap, mixed fleet, identity capture, cross-client conformance, refresh-gate reproduce-then-prove); 366/366 total. OTA artifact-availability is a separate concern (out of scope). Co-Authored-By: Claude Opus 4.8 (1M context) --- server/db/database.js | 6 + server/lib/liveness.js | 69 ++++++++ server/services/heartbeat.js | 33 ++++ server/test/v4-core-liveness.test.js | 190 +++++++++++++++++++++++ server/test/v4-core-refresh-gate.test.js | 99 ++++++++++++ server/ws/deviceSocket.js | 44 +++++- 6 files changed, 439 insertions(+), 2 deletions(-) create mode 100644 server/lib/liveness.js create mode 100644 server/test/v4-core-liveness.test.js create mode 100644 server/test/v4-core-refresh-gate.test.js diff --git a/server/db/database.js b/server/db/database.js index f7c2d50..15481a9 100644 --- a/server/db/database.js +++ b/server/db/database.js @@ -88,6 +88,12 @@ const migrations = [ 'ALTER TABLE content ADD COLUMN team_id TEXT', // Device notes 'ALTER TABLE devices ADD COLUMN notes TEXT', + // v4 core pass — client identity capture (capture-don't-act; degrades to legacy/unknown for old + // pre-v4 clients that send no identity block). No logic is built on these yet. + 'ALTER TABLE devices ADD COLUMN client_type TEXT', + 'ALTER TABLE devices ADD COLUMN client_version TEXT', + 'ALTER TABLE devices ADD COLUMN platform TEXT', + 'ALTER TABLE devices ADD COLUMN contract_version TEXT', // Email settings on users "ALTER TABLE users ADD COLUMN email_alerts INTEGER DEFAULT 1", // Content folders diff --git a/server/lib/liveness.js b/server/lib/liveness.js new file mode 100644 index 0000000..ee45ab6 --- /dev/null +++ b/server/lib/liveness.js @@ -0,0 +1,69 @@ +'use strict'; + +// v4 CORE-PASS liveness helpers — pure, VERSION-AGNOSTIC, mixed-fleet-safe. Dependency-free so they +// are unit-testable and the imperative shells (deviceSocket heartbeat/register handlers, the +// heartbeat offline sweep) stay thin. The server talks to a MIX simultaneously — v4 clients (have a +// watchdog, consume the ack, send an identity block), OLD pre-v4 clients (none of that), and +// genuinely-disconnected devices — and none of these may break the server or each other. + +// ── Uniform ack (PRIMARY + FIX 1: reconnect-window gap) ──────────────────────────────────────── +// Should THIS device:heartbeat be acked with device:heartbeat-ack? The ack keeps a v4 client's +// watchdog armed; it is emitted from the SHARED heartbeat handler (uniform by construction across +// APK / .wgt / /player) and is HARMLESS to old clients (they don't consume it). We ack a KNOWN +// device — identity-agnostic: +// - an already-authenticated socket (authedDeviceId set), OR +// - a heartbeat carrying a device_id that RESOLVES to a real device (a real device mid-reconnect, +// BEFORE this socket finished re-registering — the deferred ack-gap fix). +// We do NOT ack anonymous / never-authenticated sockets (no device_id, or an unknown id): those are +// covered by degrade-safe — an un-acked client's watchdog simply never arms, so there is no +// false-fire and no storm. +function ackableHeartbeat(authedDeviceId, heartbeatDeviceId, deviceExists) { + if (authedDeviceId) return true; // authenticated socket -> known + if (!heartbeatDeviceId) return false; // anonymous heartbeat -> not acked + return !!deviceExists(heartbeatDeviceId); // real device mid-reconnect -> ack (window fix) +} + +// ── Dashboard liveness (FIX 2: server-derived, VERSION-AGNOSTIC 3-state) ──────────────────────── +// Derived ONLY from signals EVERY client sends — socket presence, last-heartbeat age, reconnect +// frequency — never from v4-only signals. Correct for v4 clients, OLD clients (connected + +// heartbeating -> healthy), and disconnected clients (-> offline, a normal state, NOT an error). +// offline : no live socket. +// degraded : connected but reconnecting frequently (churn), OR connected but silent past the window. +// healthy : connected + a recent heartbeat + not churning. +const HEALTHY_HEARTBEAT_MS = 35000; // 2× the 15s client heartbeat + margin +const DEGRADED_RECONNECTS = 3; // >=3 (re)registers within the reconnect window => churn + +function deriveLiveness({ connected, lastHeartbeatAgeMs, recentReconnects } = {}, opts = {}) { + const hbMax = opts.healthyHeartbeatMs != null ? opts.healthyHeartbeatMs : HEALTHY_HEARTBEAT_MS; + const churn = opts.degradedReconnects != null ? opts.degradedReconnects : DEGRADED_RECONNECTS; + if (!connected) return 'offline'; + if ((recentReconnects || 0) >= churn) return 'degraded'; + if ((lastHeartbeatAgeMs || 0) > hbMax) return 'degraded'; + return 'healthy'; +} + +// ── Identity capture (FIX 3: capture-don't-act, DEGRADES on missing) ──────────────────────────── +// Capture the v4 identity block when present; when absent/partial (an OLD client), fill +// "legacy"/"unknown" — NEVER fail on a missing field. No logic is built on this yet. +function captureIdentity(data) { + const d = data || {}; + return { + client_type: d.client_type || 'legacy', + client_version: d.client_version || 'unknown', + platform: d.platform || 'unknown', + contract_version: d.contract_version || 'legacy', + }; +} + +// A1 change-detection: has the (already-captured) identity changed vs what's stored? A genuine +// reconnect with an unchanged identity (the common case) then does NO write. A never-stored device +// (current null / all-NULL columns) or a real change (e.g. new client_version after an OTA) writes. +function identityChanged(current, incoming) { + if (!current) return true; + return current.client_type !== incoming.client_type + || current.client_version !== incoming.client_version + || current.platform !== incoming.platform + || current.contract_version !== incoming.contract_version; +} + +module.exports = { ackableHeartbeat, deriveLiveness, captureIdentity, identityChanged, HEALTHY_HEARTBEAT_MS, DEGRADED_RECONNECTS }; diff --git a/server/services/heartbeat.js b/server/services/heartbeat.js index 937e49d..dccac39 100644 --- a/server/services/heartbeat.js +++ b/server/services/heartbeat.js @@ -4,10 +4,38 @@ const { deviceRoom, emitToWorkspace } = require('../lib/socket-rooms'); const statusLogWriter = require('../lib/status-log-writer'); const { chunkedDelete, currentBand, yieldTick } = require('../lib/chunked-prune'); // #146 non-blocking sweeps +const liveness = require('../lib/liveness'); // v4 core pass: server-derived 3-state liveness + // Track connected device sockets: deviceId -> { socketId, lastHeartbeat } const deviceConnections = new Map(); +// FIX 2: version-agnostic reconnect-frequency signal (every client reconnects the same way). A +// rolling window of recent (re)register timestamps per device -> "degraded-reconnecting" when it churns. +let _io = null; // captured in startHeartbeatChecker so livenessFor() can check namespace presence +const RECONNECT_WINDOW_MS = 60000; +const reconnectTimes = new Map(); // deviceId -> [timestamps within the window] +function recordReconnect(deviceId, now = Date.now()) { + const arr = (reconnectTimes.get(deviceId) || []).filter(t => now - t < RECONNECT_WINDOW_MS); + arr.push(now); + reconnectTimes.set(deviceId, arr); +} +function recentReconnects(deviceId, now = Date.now()) { + const arr = (reconnectTimes.get(deviceId) || []).filter(t => now - t < RECONNECT_WINDOW_MS); + if (arr.length) reconnectTimes.set(deviceId, arr); else reconnectTimes.delete(deviceId); + return arr.length; +} +// Server-derived liveness for a device — from socket presence + heartbeat age + reconnect churn ONLY +// (all version-agnostic). A disconnected device is a clean 'offline' (normal state, not an error). +function livenessFor(deviceId) { + const conn = deviceConnections.get(deviceId); + const deviceNs = _io ? _io.of('/device') : null; + const connected = !!(conn && deviceNs && deviceNs.sockets.has(conn.socketId)); + const lastHeartbeatAgeMs = conn ? (Date.now() - conn.lastHeartbeat) : Infinity; + return liveness.deriveLiveness({ connected, lastHeartbeatAgeMs, recentReconnects: recentReconnects(deviceId) }); +} + function startHeartbeatChecker(io) { + _io = io; // FIX 2: for livenessFor() namespace-presence checks // #146: startup sweep is chunked + async + fire-and-forget + NOT band-gated, so a // bloated device_status_log self-heals on next deploy WITHOUT freezing boot (the old // whole-table sort froze boot 40-48s -> healthcheck fail -> restart loop). It @@ -64,8 +92,10 @@ function startHeartbeatChecker(io) { emitToWorkspace(dashboardNs, deviceRoom(device.id), 'dashboard:device-status', { device_id: device.id, status: 'offline', + liveness: 'offline', // FIX 2: derived — no live socket => offline (a normal state, not an error) telemetry: null }); + reconnectTimes.delete(device.id); // clear churn history on a clean offline console.log(`Device ${device.id} marked offline (heartbeat timeout)`); // #146: batch through the coalescing writer (was an immediate INSERT here). @@ -202,6 +232,9 @@ module.exports = { getConnection, getAllConnections, getConnectedCount, + recordReconnect, // FIX 2 + recentReconnects, // FIX 2 + livenessFor, // FIX 2 pruneProvisioningDevices, accrueUsage, pruneUsageDaily, diff --git a/server/test/v4-core-liveness.test.js b/server/test/v4-core-liveness.test.js new file mode 100644 index 0000000..9b95b8f --- /dev/null +++ b/server/test/v4-core-liveness.test.js @@ -0,0 +1,190 @@ +// v4 CORE PASS — server honors the liveness contract uniformly across the MIXED fleet (v4 + old +// pre-v4 + disconnected). Validates: uniform device:heartbeat-ack, the reconnect-window ack-gap fix, +// server-derived liveness, identity capture (degrades on missing), cross-client conformance. +const { test, before, after } = require('node:test'); +const assert = require('node:assert/strict'); +const { spawn } = require('node:child_process'); +const ioClient = require('../node_modules/socket.io-client'); +const path = require('node:path'); const os = require('node:os'); const fs = require('node:fs'); const crypto = require('node:crypto'); +const liveness = require('../lib/liveness'); + +// ============================ PURE UNIT TESTS (no server) ============================ +test('ackableHeartbeat: authed socket is acked', () => { + assert.equal(liveness.ackableHeartbeat('dev1', 'dev1', () => false), true); // authed -> known regardless +}); +test('ackableHeartbeat: KNOWN device mid-reconnect (not-yet-authed socket, resolvable id) is acked — the ack-gap fix', () => { + assert.equal(liveness.ackableHeartbeat(null, 'devKnown', (id) => id === 'devKnown'), true); +}); +test('ackableHeartbeat: anonymous (no device_id) NOT acked — degrade-safe', () => { + assert.equal(liveness.ackableHeartbeat(null, undefined, () => true), false); +}); +test('ackableHeartbeat: unknown device_id NOT acked', () => { + assert.equal(liveness.ackableHeartbeat(null, 'ghost', () => false), false); +}); +test('ackableHeartbeat: BOTH identity paths acked identically (id-agnostic — device_id resolves)', () => { + const exists = (id) => id === 'viaToken' || id === 'viaFingerprint'; + assert.equal(liveness.ackableHeartbeat(null, 'viaToken', exists), true); + assert.equal(liveness.ackableHeartbeat(null, 'viaFingerprint', exists), true); +}); + +test('deriveLiveness: disconnected device -> offline (normal state, not an error)', () => { + assert.equal(liveness.deriveLiveness({ connected: false, lastHeartbeatAgeMs: 999999, recentReconnects: 9 }), 'offline'); +}); +test('deriveLiveness: OLD client (connected + heartbeating, NO v4 signals) -> healthy (version-agnostic)', () => { + assert.equal(liveness.deriveLiveness({ connected: true, lastHeartbeatAgeMs: 5000, recentReconnects: 0 }), 'healthy'); +}); +test('deriveLiveness: connected but reconnect-churn -> degraded', () => { + assert.equal(liveness.deriveLiveness({ connected: true, lastHeartbeatAgeMs: 5000, recentReconnects: 3 }), 'degraded'); +}); +test('deriveLiveness: connected but silent past window -> degraded', () => { + assert.equal(liveness.deriveLiveness({ connected: true, lastHeartbeatAgeMs: 40000, recentReconnects: 0 }), 'degraded'); +}); + +test('captureIdentity: full v4 block captured verbatim', () => { + assert.deepEqual(liveness.captureIdentity({ client_type: 'wgt', client_version: '1.9.2', platform: 'Tizen 6.5', contract_version: 'v4' }), + { client_type: 'wgt', client_version: '1.9.2', platform: 'Tizen 6.5', contract_version: 'v4' }); +}); +test('captureIdentity: OLD client (no block) -> legacy/unknown defaults, NEVER fails', () => { + assert.deepEqual(liveness.captureIdentity({}), { client_type: 'legacy', client_version: 'unknown', platform: 'unknown', contract_version: 'legacy' }); + assert.deepEqual(liveness.captureIdentity(undefined), { client_type: 'legacy', client_version: 'unknown', platform: 'unknown', contract_version: 'legacy' }); +}); +test('captureIdentity: PARTIAL block degrades per-field', () => { + assert.deepEqual(liveness.captureIdentity({ client_type: 'apk' }), { client_type: 'apk', client_version: 'unknown', platform: 'unknown', contract_version: 'legacy' }); +}); + +// ============================ CROSS-CLIENT CONFORMANCE (source diff) ============================ +test('cross-client conformance: threshold + arm + identity IDENTICAL across APK/.wgt/player', () => { + const root = path.join(__dirname, '..', '..'); + const wgt = fs.readFileSync(path.join(root, 'tizen/js/app.js'), 'utf8'); + const player = fs.readFileSync(path.join(root, 'server/player/index.html'), 'utf8'); + const apk = fs.readFileSync(path.join(root, 'android/app/src/main/java/com/remotedisplay/player/service/LivenessWatchdog.kt'), 'utf8'); + // threshold 45000 ± 10000 — identical formula constants in all three + assert.match(wgt, /THRESHOLD_BASE_MS = 45000, THRESHOLD_JITTER_MS = 10000/); + assert.match(player, /V4_THRESHOLD_BASE_MS = 45000, V4_THRESHOLD_JITTER_MS = 10000/); + assert.match(apk, /THRESHOLD_BASE_MS = 45_000L/); assert.match(apk, /THRESHOLD_JITTER_MS = 10_000L/); + // arm event name — identical + for (const s of [wgt, player, apk]) assert.match(s, /device:heartbeat-ack/); + // watchdog backoff params — .wgt/player io opts AND APK LivenessWatchdog all 1000/30000/0.2 + assert.match(wgt, /reconnectionDelay: 1000/); assert.match(wgt, /reconnectionDelayMax: 30000/); assert.match(wgt, /randomizationFactor: 0.2/); + assert.match(player, /reconnectionDelay: 1000/); assert.match(player, /reconnectionDelayMax: 30000/); assert.match(player, /randomizationFactor: 0.2/); + assert.match(apk, /BACKOFF_BASE_MS = 1_000L/); assert.match(apk, /BACKOFF_CAP_MS = 30_000L/); +}); +test('cross-client conformance FINDING: APK socket.io TRANSPORT backoff diverges (60s/0.5 vs 30s/0.2)', () => { + const apkWs = fs.readFileSync(path.join(__dirname, '..', '..', 'android/app/src/main/java/com/remotedisplay/player/service/WebSocketService.kt'), 'utf8'); + // Documented divergence (from the /player QA pass): the APK's IO.Options transport backoff is + // 60000/0.5, not the canonical 30000/0.2 the .wgt/player use. Assert it so the finding is tracked. + assert.match(apkWs, /reconnectionDelayMax = 60_000/); + assert.match(apkWs, /randomizationFactor = 0.5/); +}); + +// ============================ E2E: MIXED FLEET against the real server ============================ +const PORT = 3968; +const BASE = `http://127.0.0.1:${PORT}`; +const DATA_DIR = path.join(os.tmpdir(), 'st-v4core-' + crypto.randomBytes(4).toString('hex')); +const LOG = path.join(os.tmpdir(), 'st-v4core.log'); +let proc, JWT; +const sleep = ms => new Promise(r => setTimeout(r, ms)); + +before(async () => { + const logFd = fs.openSync(LOG, 'w'); + proc = spawn('node', ['server.js'], { cwd: path.join(__dirname, '..'), env: { ...process.env, DATA_DIR, SELF_HOSTED: 'true', PORT: String(PORT), NODE_ENV: 'test' }, stdio: ['ignore', logFd, logFd] }); + let up = false; + for (let i = 0; i < 80; i++) { try { const r = await fetch(BASE + '/api/status'); if (r.ok) { up = true; break; } } catch { /* */ } await sleep(250); } + if (!up) throw new Error('server did not boot:\n' + fs.readFileSync(LOG, 'utf8').slice(-2000)); + JWT = (await (await fetch(BASE + '/api/auth/register', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ email: 'op@test.local', password: 'test12345', name: 'Op' }) })).json()).token; +}); +after(() => { try { proc.kill('SIGKILL'); } catch { /* */ } }); + +// open a socket, register with regMsg, resolve {sock, data} on device:registered (socket stays OPEN) +function openAndRegister(regMsg) { + return new Promise((resolve, reject) => { + const sock = ioClient(`${BASE}/device`, { transports: ['websocket'], reconnection: false, forceNew: true }); + sock.on('connect', () => sock.emit('device:register', regMsg)); + sock.on('device:registered', (d) => resolve({ sock, data: d })); + setTimeout(() => reject(new Error('register timeout')), 4000); + }); +} +// emit a heartbeat, resolve true if device:heartbeat-ack arrives within `ms`, else false +function ackWithin(sock, hbMsg, ms = 1200) { + return new Promise((resolve) => { + let done = false; const fin = v => { if (!done) { done = true; resolve(v); } }; + sock.once('device:heartbeat-ack', () => fin(true)); + sock.emit('device:heartbeat', hbMsg); + setTimeout(() => fin(false), ms); + }); +} + +test('PRIMARY: uniform ack — a v4 device (pairing path) is acked from the shared handler', async () => { + const { sock, data } = await openAndRegister({ pairing_code: '111111', fingerprint: 'fp-v4a', device_info: {}, client_type: 'wgt', client_version: '1.9.2', platform: 'Tizen 6.5', contract_version: 'v4' }); + assert.ok(await ackWithin(sock, { device_id: data.device_id, telemetry: {} }), 'v4 device heartbeat should be acked'); + sock.close(); +}); + +test('PRIMARY: uniform ack — the reconnect path (device_id+token) is acked identically', async () => { + const first = await openAndRegister({ pairing_code: '222222', fingerprint: 'fp-v4b', device_info: {} }); + const creds = { id: first.data.device_id, token: first.data.device_token }; first.sock.close(); await sleep(300); + const { sock } = await openAndRegister({ device_id: creds.id, device_token: creds.token, fingerprint: 'fp-v4b', device_info: {}, client_type: 'apk', contract_version: 'v4' }); + assert.ok(await ackWithin(sock, { device_id: creds.id, telemetry: {} }), 'reconnected device heartbeat should be acked'); + sock.close(); +}); + +test('FIX 1 ack-gap: a KNOWN device mid-reconnect (heartbeat BEFORE re-register) is acked', async () => { + const first = await openAndRegister({ pairing_code: '333333', fingerprint: 'fp-gap', device_info: {} }); + const knownId = first.data.device_id; first.sock.close(); await sleep(300); + // fresh socket, NOT registered — send a heartbeat carrying the KNOWN device_id + const raw = ioClient(`${BASE}/device`, { transports: ['websocket'], reconnection: false, forceNew: true }); + await new Promise(r => raw.on('connect', r)); + assert.ok(await ackWithin(raw, { device_id: knownId, telemetry: {} }), 'known device mid-reconnect must be acked so its watchdog stays armed'); + raw.close(); +}); + +test('FIX 1 ack-gap: anonymous / unknown socket is NOT acked (degrade-safe)', async () => { + const raw = ioClient(`${BASE}/device`, { transports: ['websocket'], reconnection: false, forceNew: true }); + await new Promise(r => raw.on('connect', r)); + assert.equal(await ackWithin(raw, { telemetry: {} }, 900), false, 'no device_id -> not acked'); + assert.equal(await ackWithin(raw, { device_id: 'ghost-' + crypto.randomBytes(4).toString('hex'), telemetry: {} }, 900), false, 'unknown device_id -> not acked'); + raw.close(); +}); + +test('MIXED FLEET: v4 + OLD (no identity block) + anonymous simultaneously — nothing errors, acks correct', async () => { + // v4 client (identity block) and OLD client (NO identity block, no ack consumption) both register+ack. + const v4 = await openAndRegister({ pairing_code: '444444', fingerprint: 'fp-mixv4', device_info: {}, client_type: 'player', client_version: '1.1.0-web', platform: 'Chrome 120', contract_version: 'v4' }); + const old = await openAndRegister({ pairing_code: '555555', fingerprint: 'fp-mixold', device_info: { app_version: 'legacy-apk-1.0' } }); // NO identity block + assert.ok(v4.data.device_id && old.data.device_id, 'both v4 and OLD clients registered WITHOUT error on missing identity'); + assert.ok(await ackWithin(v4.sock, { device_id: v4.data.device_id, telemetry: {} }), 'v4 acked'); + assert.ok(await ackWithin(old.sock, { device_id: old.data.device_id, telemetry: {} }), 'OLD client acked too (harmless — it ignores the ack)'); + // anonymous present at the same time -> not acked, server unbothered + const anon = ioClient(`${BASE}/device`, { transports: ['websocket'], reconnection: false, forceNew: true }); + await new Promise(r => anon.on('connect', r)); + assert.equal(await ackWithin(anon, { telemetry: {} }, 900), false, 'anonymous not acked'); + v4.sock.close(); old.sock.close(); anon.close(); + // server still healthy after the mixed load + assert.equal((await fetch(BASE + '/api/status')).ok, true, 'server unbroken by the mixed fleet'); +}); + +test('FIX 3 identity capture: v4 -> stored verbatim; OLD -> legacy/unknown (verified via device API)', async () => { + // v4 device, paired, then read back + const v4 = await openAndRegister({ pairing_code: '666666', fingerprint: 'fp-idv4', device_info: {}, client_type: 'wgt', client_version: '1.9.2', platform: 'Tizen 6.5', contract_version: 'v4' }); + v4.sock.close(); + await fetch(BASE + '/api/provision/pair', { method: 'POST', headers: { Authorization: 'Bearer ' + JWT, 'Content-Type': 'application/json' }, body: JSON.stringify({ pairing_code: '666666', name: 'v4dev' }) }); + const v4row = await (await fetch(BASE + '/api/devices/' + v4.data.device_id, { headers: { Authorization: 'Bearer ' + JWT } })).json(); + assert.equal(v4row.client_type, 'wgt'); assert.equal(v4row.contract_version, 'v4'); assert.equal(v4row.platform, 'Tizen 6.5'); + // OLD device (no identity block), paired, read back -> legacy/unknown + const old = await openAndRegister({ pairing_code: '777777', fingerprint: 'fp-idold', device_info: {} }); + old.sock.close(); + await fetch(BASE + '/api/provision/pair', { method: 'POST', headers: { Authorization: 'Bearer ' + JWT, 'Content-Type': 'application/json' }, body: JSON.stringify({ pairing_code: '777777', name: 'olddev' }) }); + const oldrow = await (await fetch(BASE + '/api/devices/' + old.data.device_id, { headers: { Authorization: 'Bearer ' + JWT } })).json(); + assert.equal(oldrow.client_type, 'legacy'); assert.equal(oldrow.contract_version, 'legacy'); assert.equal(oldrow.client_version, 'unknown'); +}); + +test('#148 + degrade-safe hold: a device reconnect yields ONE connection, ack still works', async () => { + const first = await openAndRegister({ pairing_code: '888888', fingerprint: 'fp-148', device_info: {} }); + const creds = { id: first.data.device_id, token: first.data.device_token }; + // reconnect on a NEW socket (old still open) -> server evicts the old, one connection remains + const second = await openAndRegister({ device_id: creds.id, device_token: creds.token, fingerprint: 'fp-148', device_info: {} }); + await sleep(400); + assert.ok(await ackWithin(second.sock, { device_id: creds.id, telemetry: {} }), 'the surviving socket is acked'); + const connected = (await (await fetch(BASE + '/api/status')).json()).devices_connected; + assert.ok(connected >= 1, 'device present; #148 single-socket not broken by the ack'); + try { first.sock.close(); } catch {} second.sock.close(); +}); diff --git a/server/test/v4-core-refresh-gate.test.js b/server/test/v4-core-refresh-gate.test.js new file mode 100644 index 0000000..81b9b78 --- /dev/null +++ b/server/test/v4-core-refresh-gate.test.js @@ -0,0 +1,99 @@ +// CORE targeted fix — the isPlaylistRefresh gate + identity change-detection close the A-bucket: +// A1 (WAL write amplification from a sync identity UPDATE on every ~45-60s refresh) and +// A2 (benign refreshes inflating recentReconnects -> healthy devices shown "Degraded"). +const path = require('node:path'); const os = require('node:os'); const fs = require('node:fs'); const crypto = require('node:crypto'); +// in-process DB dir for the heartbeat-service unit tests (isolated from the spawned e2e server) +process.env.DATA_DIR = path.join(os.tmpdir(), 'st-rg-unit-' + crypto.randomBytes(4).toString('hex')); +process.env.SELF_HOSTED = 'true'; +fs.mkdirSync(process.env.DATA_DIR, { recursive: true }); + +const { test, before, after } = require('node:test'); +const assert = require('node:assert/strict'); +const { spawn } = require('node:child_process'); +const ioClient = require('../node_modules/socket.io-client'); +const liveness = require('../lib/liveness'); +const sleep = ms => new Promise(r => setTimeout(r, ms)); + +// ================= UNIT: change-detection (A1) ================= +test('identityChanged: never-stored (null) -> write', () => { + assert.equal(liveness.identityChanged(null, { client_type: 'wgt' }), true); +}); +test('identityChanged: identical -> NO write (steady-state reconnect)', () => { + const i = { client_type: 'wgt', client_version: '1.9.2', platform: 'Tizen 6.5', contract_version: 'v4' }; + assert.equal(liveness.identityChanged({ ...i }, i), false); +}); +test('identityChanged: a real change (new client_version after OTA) -> write', () => { + const cur = { client_type: 'wgt', client_version: '1.9.2', platform: 'Tizen 6.5', contract_version: 'v4' }; + assert.equal(liveness.identityChanged(cur, { ...cur, client_version: '1.9.3' }), true); +}); + +// ================= UNIT: churn logic (A2) via the real heartbeat service ================= +const heartbeat = require('../services/heartbeat'); +test('A2 flapping: a genuinely-flapping device (3 reconnects in window) -> degraded (not over-corrected)', () => { + const id = 'flap-' + crypto.randomBytes(3).toString('hex'); + heartbeat.recordReconnect(id, 1000); heartbeat.recordReconnect(id, 2000); heartbeat.recordReconnect(id, 3000); + assert.equal(heartbeat.recentReconnects(id, 3000), 3); + assert.equal(liveness.deriveLiveness({ connected: true, lastHeartbeatAgeMs: 5000, recentReconnects: 3 }), 'degraded'); +}); +test('A2 healthy: a device with NO recorded reconnects (refreshes gated) -> 0 -> healthy', () => { + const id = 'ok-' + crypto.randomBytes(3).toString('hex'); + assert.equal(heartbeat.recentReconnects(id, 1000), 0); + assert.equal(liveness.deriveLiveness({ connected: true, lastHeartbeatAgeMs: 5000, recentReconnects: 0 }), 'healthy'); +}); +test('A2 window: reconnects older than 60s drop out (a past flap does not stay Degraded forever)', () => { + const id = 'win-' + crypto.randomBytes(3).toString('hex'); + heartbeat.recordReconnect(id, 1000); heartbeat.recordReconnect(id, 2000); heartbeat.recordReconnect(id, 3000); + assert.equal(heartbeat.recentReconnects(id, 3000), 3); // in-window -> degraded + assert.equal(heartbeat.recentReconnects(id, 70000), 0); // 67s later -> expired -> healthy again +}); + +// ================= E2E: the shared !isPlaylistRefresh gate + change-detection ================= +const PORT = 3972; const BASE = `http://127.0.0.1:${PORT}`; +const DATA_DIR = path.join(os.tmpdir(), 'st-rg-e2e-' + crypto.randomBytes(4).toString('hex')); +const LOG = path.join(os.tmpdir(), 'st-rg-e2e.log'); +let proc, JWT; + +before(async () => { + const logFd = fs.openSync(LOG, 'w'); + proc = spawn('node', ['server.js'], { cwd: path.join(__dirname, '..'), env: { ...process.env, DATA_DIR, SELF_HOSTED: 'true', PORT: String(PORT), NODE_ENV: 'test' }, stdio: ['ignore', logFd, logFd] }); + let up = false; for (let i = 0; i < 80; i++) { try { if ((await fetch(BASE + '/api/status')).ok) { up = true; break; } } catch { /* */ } await sleep(250); } + if (!up) throw new Error('boot fail:\n' + fs.readFileSync(LOG, 'utf8').slice(-2000)); + JWT = (await (await fetch(BASE + '/api/auth/register', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ email: 'op@t.local', password: 'test12345', name: 'Op' }) })).json()).token; +}); +after(() => { try { proc.kill('SIGKILL'); } catch { /* */ } }); + +const connect = () => ioClient(`${BASE}/device`, { transports: ['websocket'], reconnection: false, forceNew: true }); +const registerOn = (sock, msg) => new Promise((res, rej) => { sock.once('device:registered', d => res(d)); sock.emit('device:register', msg); setTimeout(() => rej(new Error('reg timeout')), 4000); }); +const deviceRow = async (id) => (await (await fetch(`${BASE}/api/devices/${id}`, { headers: { Authorization: 'Bearer ' + JWT } })).json()); +const pair = (code, name) => fetch(BASE + '/api/provision/pair', { method: 'POST', headers: { Authorization: 'Bearer ' + JWT, 'Content-Type': 'application/json' }, body: JSON.stringify({ pairing_code: code, name }) }); + +test('A1 GATE: a same-socket REFRESH does NOT rewrite identity (nor count churn — shared gate)', async () => { + const sock = connect(); await new Promise(r => sock.on('connect', r)); + const reg = await registerOn(sock, { pairing_code: '910910', fingerprint: 'fp-rg', device_info: {}, client_type: 'wgt', client_version: '1.9.2', platform: 'Tizen 6.5', contract_version: 'v4' }); + await pair('910910', 'rg'); + assert.equal((await deviceRow(reg.device_id)).client_type, 'wgt'); + // SAME socket re-register (a playlist refresh) carrying a DIFFERENT identity -> MUST be ignored (gated). + await registerOn(sock, { device_id: reg.device_id, device_token: reg.device_token, device_info: {}, client_type: 'CHANGED-ON-REFRESH', client_version: '9.9.9', platform: 'x', contract_version: 'v9' }); + await sleep(200); + assert.equal((await deviceRow(reg.device_id)).client_type, 'wgt', 'a refresh must NOT rewrite identity — the !isPlaylistRefresh gate skips recordReconnect + persistIdentity together'); + sock.close(); +}); + +test('A1 change-detect: a GENUINE reconnect writes identity when it CHANGED (e.g. an OTA bump)', async () => { + const s1 = connect(); await new Promise(r => s1.on('connect', r)); + const reg = await registerOn(s1, { pairing_code: '920920', fingerprint: 'fp-cd', device_info: {}, client_type: 'apk', client_version: '2.0.0', platform: 'Android 11', contract_version: 'v4' }); + await pair('920920', 'cd'); s1.close(); await sleep(300); + const s2 = connect(); await new Promise(r => s2.on('connect', r)); // NEW socket -> genuine reconnect + await registerOn(s2, { device_id: reg.device_id, device_token: reg.device_token, device_info: {}, client_type: 'apk', client_version: '2.1.0', platform: 'Android 11', contract_version: 'v4' }); + await sleep(200); + assert.equal((await deviceRow(reg.device_id)).client_version, '2.1.0', 'a genuine reconnect with a CHANGED identity writes it'); + s2.close(); +}); + +test('KEYSTONES unaffected: the shared uniform ack still fires (L3) and pre-auth grants nothing (L4)', async () => { + const s = connect(); await new Promise(r => s.on('connect', r)); + const reg = await registerOn(s, { pairing_code: '930930', fingerprint: 'fp-ka', device_info: {}, client_type: 'wgt', contract_version: 'v4' }); + const acked = await new Promise((res) => { let d = false; s.once('device:heartbeat-ack', () => { if (!d) { d = true; res(true); } }); s.emit('device:heartbeat', { device_id: reg.device_id, telemetry: {} }); setTimeout(() => { if (!d) res(false); }, 1000); }); + assert.equal(acked, true, 'uniform ack path untouched by the gate fix'); + s.close(); +}); diff --git a/server/ws/deviceSocket.js b/server/ws/deviceSocket.js index 8332c86..2dc6344 100644 --- a/server/ws/deviceSocket.js +++ b/server/ws/deviceSocket.js @@ -5,6 +5,7 @@ const fs = require('fs'); const { db, pruneTelemetry, pruneScreenshots } = require('../db/database'); const config = require('../config'); const heartbeat = require('../services/heartbeat'); +const liveness = require('../lib/liveness'); // v4 core pass: pure ack/liveness/identity helpers const commandQueue = require('../lib/command-queue'); const reconnectThrottle = require('../lib/reconnect-throttle'); const contentAckLimiter = require('../lib/content-ack-limiter'); @@ -254,6 +255,25 @@ function checkDeviceAccess(deviceId) { return { allowed: true }; } +// v4 core-pass helpers (module scope; db is a ready singleton at require time). +const _deviceExistsStmt = db.prepare('SELECT 1 FROM devices WHERE id = ?'); +function deviceExists(id) { return !!(id && _deviceExistsStmt.get(id)); } +const _identityReadStmt = db.prepare('SELECT client_type, client_version, platform, contract_version FROM devices WHERE id = ?'); +const _persistIdentityStmt = db.prepare('UPDATE devices SET client_type = ?, client_version = ?, platform = ?, contract_version = ? WHERE id = ?'); +function persistIdentity(deviceId, data) { + if (!deviceId) return; + // FIX 3: capture-don't-act; degrades to legacy/unknown for old clients; NEVER breaks register. + // A1 change-detection: only WRITE when the identity actually changed vs stored. A genuine + // reconnect with unchanged identity (the common case, incl. flapping / re-pair churn) does a cheap + // read and NO write — no UPDATE, no WAL churn. First provision (stored NULLs) and a real change + // (e.g. new client_version after an OTA) still write. + try { + const i = liveness.captureIdentity(data); + if (!liveness.identityChanged(_identityReadStmt.get(deviceId), i)) return; // unchanged — skip the write + _persistIdentityStmt.run(i.client_type, i.client_version, i.platform, i.contract_version, deviceId); + } catch (e) { /* identity capture must never break registration */ } +} + module.exports = function setupDeviceSocket(io) { // Expose helpers for use by route handlers module.exports.lastScreenshots = lastScreenshots; @@ -406,9 +426,11 @@ module.exports = function setupDeviceSocket(io) { } currentDeviceId = existing.device_id; heartbeat.registerConnection(existing.device_id, socket.id); + heartbeat.recordReconnect(existing.device_id); // FIX 2: churn signal + persistIdentity(existing.device_id, data); // FIX 3: identity capture socket.join(existing.device_id); logDeviceStatus(existing.device_id, 'online'); - emitToDeviceWorkspace(dashboardNs, existing.device_id, 'dashboard:device-status', { device_id: existing.device_id, status: 'online' }); + emitToDeviceWorkspace(dashboardNs, existing.device_id, 'dashboard:device-status', { device_id: existing.device_id, status: 'online', liveness: heartbeat.livenessFor(existing.device_id) }); // Flush any commands/playlist-updates queued while this device was offline. commandQueue.flushQueue(deviceNs, existing.device_id, buildPlaylistPayload); // Send playlist @@ -523,6 +545,14 @@ module.exports = function setupDeviceSocket(io) { } heartbeat.registerConnection(device_id, socket.id); + // #134: a same-socket re-register is a playlist REFRESH (~45-60s), NOT a reconnect and NOT + // a new identity. Match the existing !isPlaylistRefresh gates (:486/:605): don't count it as + // churn (A2 — else healthy refreshers cross DEGRADED_RECONNECTS and show Degraded) and don't + // re-write identity (A1 — else a sync UPDATE + WAL churn every ~45-60s per device). + if (!isPlaylistRefresh) { + heartbeat.recordReconnect(device_id); // genuine reconnect only + persistIdentity(device_id, data); // change-detected write (see persistIdentity) + } socket.join(device_id); socket.emit('device:registered', { device_id, device_token: tokenToSend, status: 'online' }); // #143: a device paired/claimed server-side (user_id set) that RECONNECTS must be told @@ -644,6 +674,7 @@ module.exports = function setupDeviceSocket(io) { } heartbeat.registerConnection(id, socket.id); + persistIdentity(id, data); // FIX 3: capture v4 identity on first provision (degrades for old clients) socket.join(id); socket.emit('device:registered', { device_id: id, device_token: newToken, status: 'provisioning' }); @@ -668,8 +699,16 @@ module.exports = function setupDeviceSocket(io) { // Heartbeat with telemetry socket.on('device:heartbeat', (data) => { + const { device_id, telemetry } = data || {}; + // v4 PRIMARY + FIX 1 — UNIFORM ACK. Emitted from THIS single shared handler for every client + // type (APK / .wgt / /player hit the same handler = uniform by construction), and BEFORE the + // auth guard so a KNOWN device's watchdog stays armed even mid-reconnect (before this socket + // finishes re-registering). Anonymous / never-authenticated sockets are NOT acked (degrade-safe + // covers them). Old clients simply ignore the ack — harmless. + if (liveness.ackableHeartbeat(currentDeviceId, device_id, deviceExists)) { + socket.emit('device:heartbeat-ack', {}); // cheap, to the emitting socket only + } if (!requireDeviceAuth()) return; - const { device_id, telemetry } = data; if (!device_id || device_id !== currentDeviceId) return; currentDeviceId = device_id; @@ -708,6 +747,7 @@ module.exports = function setupDeviceSocket(io) { emitToDeviceWorkspace(dashboardNs, device_id, 'dashboard:device-status', { device_id, status: 'online', + liveness: heartbeat.livenessFor(device_id), // FIX 2: server-derived 3-state (healthy/degraded/offline) telemetry }); } From c5ddb82cbacc912a97fd13058c4fde14df2780ab Mon Sep 17 00:00:00 2001 From: ScreenTinker Date: Wed, 8 Jul 2026 12:56:39 -0500 Subject: [PATCH 10/20] fix(dashboard): device-detail.js parse + runtime errors that killed the whole view MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The #150 re-adopt commit (74e7062) left device-detail.js unparseable and, once parsed, unexecutable — so the entire device-detail view's JS was dead (settings, #150 re-adopt UI, delete): - SyntaxError at 768: `await api.getContent()` at the top level of the non-async setupActions() ("Unexpected reserved word") -> the whole module fails to parse. Fixed with the .then() pattern already used by the sibling playlist picker, keeping setupActions synchronous so every listener below it (save, #150 re-adopt, delete) still registers immediately (making it async would defer them behind the fetch). - Stray `async` orphaned on its own line (was line 648) before showReAdoptModal's doc comment: parses, but executes as the bare identifier statement `async;` -> ReferenceError at module load, which would keep the view dead even after the parse fix. Removed it. Also add beside the apple- one (clears the deprecation warning). Full frontend ES-module parse-scan clean; both bugs were confined to this file. Co-Authored-By: Claude Opus 4.8 (1M context) --- frontend/index.html | 1 + frontend/js/views/device-detail.js | 12 +++++++----- 2 files changed, 8 insertions(+), 5 deletions(-) diff --git a/frontend/index.html b/frontend/index.html index 89c14f9..9a09957 100644 --- a/frontend/index.html +++ b/frontend/index.html @@ -5,6 +5,7 @@ + diff --git a/frontend/js/views/device-detail.js b/frontend/js/views/device-detail.js index 4e2088a..4d73522 100644 --- a/frontend/js/views/device-detail.js +++ b/frontend/js/views/device-detail.js @@ -645,7 +645,7 @@ function showDevicePreview(device) { }); } -async // #150 re-adopt fallback: browse the workspace's previously-removed device snapshots and +// #150 re-adopt fallback: browse the workspace's previously-removed device snapshots and // apply one onto THIS (usually blank, just-re-paired) device. Primary restore is the silent // fingerprint-match on re-pair; this is for factory-reset / new-hardware / changed-fingerprint. const ORIENT_LABELS = { @@ -763,9 +763,11 @@ function setupActions(device) { } }); - // Populate default content dropdown - try { - const content = await api.getContent(); + // Populate default content dropdown (async, non-blocking — same .then() pattern as the + // playlist picker below). setupActions is a SYNCHRONOUS function; awaiting here made the whole + // file fail to parse ("Unexpected reserved word") AND would have deferred every listener below + // (save, #150 re-adopt, delete) until this fetch resolved. .then() keeps them registering immediately. + api.getContent().then(content => { const defaultSelect = document.getElementById('deviceDefaultContent'); if (defaultSelect) { content.forEach(c => { @@ -775,7 +777,7 @@ function setupActions(device) { defaultSelect.appendChild(opt); }); } - } catch {} + }).catch(() => {}); // Save settings (notes + orientation + default content) // Debug logging toggle: sends a transient set_debug command to the device and From a0b47000f3cb4ca06adfec5d98ffae1dd807808f Mon Sep 17 00:00:00 2001 From: ScreenTinker Date: Wed, 8 Jul 2026 13:03:56 -0500 Subject: [PATCH 11/20] feat(csp): allow Cloudflare Web Analytics beacon to load AND report MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The dashboard CSP (script-src 'self') blocked Cloudflare's Web Analytics beacon. Add the two exact entries the beacon needs (both required — script-only loads but silently can't report): - script-src: https://static.cloudflareinsights.com (beacon script loads) - connect-src: https://cloudflareinsights.com (beacon POSTs analytics back) Exact domains, no wildcards. connect-src already had 'wss:'/'ws:' (socket.io) + 'https:' — those stay, so the dashboard socket is unaffected; the explicit CF domain documents intent and survives any future tightening of the broad 'https:'. Co-Authored-By: Claude Opus 4.8 (1M context) --- server/server.js | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/server/server.js b/server/server.js index d186afb..6b56a41 100644 --- a/server/server.js +++ b/server/server.js @@ -90,13 +90,17 @@ const dashboardCsp = helmet.contentSecurityPolicy({ useDefaults: true, directives: { defaultSrc: ["'self'"], - scriptSrc: ["'self'"], + // Cloudflare Web Analytics: the beacon SCRIPT (static.cloudflareinsights.com) must be allowed to + // load, AND the beacon must be allowed to POST its data back (connect-src -> cloudflareinsights.com). + // Both are required — with only the script entry the beacon loads but silently can't report. + scriptSrc: ["'self'", 'https://static.cloudflareinsights.com'], scriptSrcAttr: ["'unsafe-inline'"], styleSrc: ["'self'", "'unsafe-inline'"], styleSrcAttr: ["'unsafe-inline'"], imgSrc: ["'self'", 'data:', 'blob:', 'https:'], mediaSrc: ["'self'", 'blob:', 'https:'], - connectSrc: ["'self'", 'wss:', 'ws:', 'https:'], + // 'wss:'/'ws:' keep the dashboard's socket.io connection working; the CF entry lets the beacon report. + connectSrc: ["'self'", 'wss:', 'ws:', 'https:', 'https://cloudflareinsights.com'], fontSrc: ["'self'", 'data:'], frameSrc: ["'self'", 'https://www.youtube.com', 'https://youtube.com'], objectSrc: ["'none'"], From a458c8f96a77fdf279b96d981609117c064fc667 Mon Sep 17 00:00:00 2001 From: ScreenTinker Date: Wed, 8 Jul 2026 13:22:15 -0500 Subject: [PATCH 12/20] feat(dashboard): 3-state liveness badge (consume the patch4 server signal) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The patch4 server derives 3-state liveness (healthy / degraded-reconnecting / offline) and emits it as data.liveness on dashboard:device-status, but the frontend only consumed binary online/offline — the signal was thrown away. Add a shared livenessBadge() helper (utils.js) consumed by both the dashboard device list and the device-detail view (initial render + live statusHandler). Degrades to the binary status when liveness is absent (old payload / plain reconnect+disconnect emits / DB device object) so nothing renders blank; unknown/no-data -> offline default. CSS: healthy=green, degraded=amber+pulse (reads as reconnecting), offline=red — reusing the existing --success/--warning/--danger tokens. Labels in en.js (all locales fall back to en). Frontend-only; server derivation unchanged. 13/13 unit tests. Co-Authored-By: Claude Opus 4.8 (1M context) --- frontend/css/main.css | 6 ++++++ frontend/js/i18n/en.js | 4 ++++ frontend/js/utils.js | 28 ++++++++++++++++++++++++++++ frontend/js/views/dashboard.js | 8 ++++---- frontend/js/views/device-detail.js | 9 +++++---- 5 files changed, 47 insertions(+), 8 deletions(-) diff --git a/frontend/css/main.css b/frontend/css/main.css index 432724f..7168493 100644 --- a/frontend/css/main.css +++ b/frontend/css/main.css @@ -263,6 +263,9 @@ body { .status-dot.online { background: var(--success); box-shadow: 0 0 6px var(--success); } .status-dot.offline { background: var(--danger); } .status-dot.provisioning { background: var(--warning); animation: pulse 2s infinite; } +/* v4 liveness (server-derived): healthy=green, degraded=amber+pulse (reconnecting), offline=red (above) */ +.status-dot.healthy { background: var(--success); box-shadow: 0 0 6px var(--success); } +.status-dot.degraded { background: var(--warning); box-shadow: 0 0 6px var(--warning); animation: pulse 2s infinite; } @keyframes pulse { 0%, 100% { opacity: 1; } @@ -803,6 +806,9 @@ body { .device-status-badge.online { background: var(--success-dim); color: var(--success); } .device-status-badge.offline { background: var(--danger-dim); color: #fca5a5; } .device-status-badge.provisioning { background: var(--warning-dim); color: var(--warning); } +/* v4 liveness (server-derived): healthy=green, degraded=amber (reconnecting), offline reuses .offline above */ +.device-status-badge.healthy { background: var(--success-dim); color: var(--success); } +.device-status-badge.degraded { background: var(--warning-dim); color: var(--warning); } .tabs { display: flex; diff --git a/frontend/js/i18n/en.js b/frontend/js/i18n/en.js index ad0be0a..f447dbb 100644 --- a/frontend/js/i18n/en.js +++ b/frontend/js/i18n/en.js @@ -264,6 +264,10 @@ export default { 'device.playlist.empty_desc': "Add content from your library to this display's playlist.", 'device.playlist_picker.with_count': '{name} — {n} items', 'device.playlist_picker.with_auto': '{name} (auto) — {n} items', + // v4 liveness badge (server-derived 3-state) + 'device.liveness.healthy': 'Healthy', + 'device.liveness.degraded': 'Reconnecting', + 'device.liveness.offline': 'Offline', // Info cards 'device.info.status': 'Status', 'device.info.ip_address': 'IP Address', diff --git a/frontend/js/utils.js b/frontend/js/utils.js index cee0fb5..2a00f25 100644 --- a/frontend/js/utils.js +++ b/frontend/js/utils.js @@ -1,9 +1,37 @@ +import { t } from './i18n.js'; + // HTML escape helper — prevents XSS when inserting user data into innerHTML export function esc(str) { if (str == null) return ''; return String(str).replace(/&/g,'&').replace(//g,'>').replace(/"/g,'"').replace(/'/g,'''); } +// v4 liveness badge. The patch4 server derives a 3-state liveness — 'healthy' / 'degraded' +// (temporarily reconnecting) / 'offline' — and emits it as `data.liveness` on dashboard:device-status. +// It is present on SOME emits only (the plain reconnect + disconnect emits, and any device object read +// from the DB, carry just the binary `status`), so we DEGRADE to the binary status when liveness is +// absent — nothing ever renders blank. 'provisioning' is a lifecycle state (never-paired), kept +// distinct from liveness. livenessState() is pure (unit-testable); livenessBadge() adds the i18n label. +const LIVENESS_LABEL_KEY = { + healthy: 'device.liveness.healthy', + degraded: 'device.liveness.degraded', + offline: 'device.liveness.offline', + provisioning: 'dashboard.awaiting_pairing', +}; +export function livenessState(data) { + const lv = data && data.liveness; + if (lv === 'healthy' || lv === 'degraded' || lv === 'offline') return lv; // 3-state signal present + const st = data && data.status; // backward-compat: derive from binary status + if (st === 'provisioning') return 'provisioning'; + if (st === 'online') return 'healthy'; + if (st === 'offline') return 'offline'; + return 'offline'; // unknown / no data yet -> safe default, never blank +} +export function livenessBadge(data) { + const state = livenessState(data); + return { state, label: t(LIVENESS_LABEL_KEY[state]) }; +} + // Phase 2.1: the Phase 1 schema migration renamed the legacy 'superadmin' // role to 'platform_admin'. Existing frontend checks still match the old // string; this helper accepts both so we don't have to splatter the array diff --git a/frontend/js/views/dashboard.js b/frontend/js/views/dashboard.js index 4725611..4f88a75 100644 --- a/frontend/js/views/dashboard.js +++ b/frontend/js/views/dashboard.js @@ -1,7 +1,7 @@ import { api } from '../api.js'; import { on, off, requestScreenshot } from '../socket.js'; import { showToast } from '../components/toast.js'; -import { esc } from '../utils.js'; +import { esc, livenessBadge } from '../utils.js'; import { t, tn } from '../i18n.js'; const DESTRUCTIVE_COMMANDS = ['reboot', 'shutdown']; @@ -101,8 +101,7 @@ function renderDeviceCard(device) {
` }
- - ${device.status === 'provisioning' ? t('dashboard.awaiting_pairing') : device.status} + ${(() => { const b = livenessBadge(device); return `${esc(b.label)}`; })()}
${device.status === 'provisioning' && device.pairing_code ? `
@@ -359,10 +358,11 @@ export function render(container) { // Real-time updates statusHandler = (data) => { + const b = livenessBadge(data); // v4: prefer data.liveness (3-state), fall back to binary status const cards = document.querySelectorAll(`[data-device-id="${data.device_id}"]`); cards.forEach(card => { const statusEl = card.querySelector('.device-card-status'); - if (statusEl) statusEl.innerHTML = `${data.status}`; + if (statusEl) statusEl.innerHTML = `${esc(b.label)}`; }); }; diff --git a/frontend/js/views/device-detail.js b/frontend/js/views/device-detail.js index 4d73522..cf8bb10 100644 --- a/frontend/js/views/device-detail.js +++ b/frontend/js/views/device-detail.js @@ -1,7 +1,7 @@ import { api } from '../api.js'; import { on, off, requestScreenshot, startRemote, stopRemote, sendTouch, sendKey, sendCommand } from '../socket.js'; import { showToast } from '../components/toast.js'; -import { esc } from '../utils.js'; +import { esc, livenessBadge } from '../utils.js'; import { t, tn } from '../i18n.js'; let currentDevice = null; @@ -68,8 +68,9 @@ export function render(container, deviceId) { if (data.device_id !== deviceId) return; const badge = document.querySelector('.device-status-badge'); if (badge) { - badge.className = `device-status-badge ${data.status}`; - badge.textContent = data.status; + const b = livenessBadge(data); // v4: 3-state liveness when present, else binary status + badge.className = `device-status-badge ${b.state}`; + badge.textContent = b.label; } if (data.telemetry) updateTelemetryDisplay(data.telemetry); }; @@ -149,7 +150,7 @@ async function loadDevice(deviceId, activeTab = null) {

${device.name}

- ${device.status} + ${(() => { const b = livenessBadge(device); return `${esc(b.label)}`; })()} ${device.owner_name || device.owner_email ? `${t('device.owner_label', { owner: device.owner_name || device.owner_email })}` : ''}
From 2772d1fc4d061138590ca1059876e732db3f858e Mon Sep 17 00:00:00 2001 From: ScreenTinker Date: Wed, 8 Jul 2026 13:56:18 -0500 Subject: [PATCH 13/20] fix(dashboard): liveness badge filter regression + list-view legibility MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two follow-ups from the alpha diagnosis: - FIX A (regression): filterDevices() compared badge TEXT to the option values 'online'/'offline', but the badge text is now "Healthy"/"Reconnecting"/"Offline" — so selecting a status filter matched nothing and emptied the dashboard. Now compares the liveness STATE via a data-liveness attribute, and the filter is upgraded to All / Healthy / Reconnecting / Offline (an admin can filter TO reconnecting devices — the point of the Degraded distinction). - FIX B (legibility): the list rendered liveness as a status-dot where healthy=green/offline=red were visually identical to the old indicator, so it didn't read as new. The list now renders the same device-status-badge PILL as device-detail (3 distinct colors; amber Reconnecting visible on the list), scoped with an is-liveness modifier so video-wall cards keep their dark "NxN wall" pill. Frontend-only. 14/14 filter+render tests; full ES-module parse clean. Co-Authored-By: Claude Opus 4.8 (1M context) --- frontend/css/main.css | 13 +++++++++++++ frontend/js/views/dashboard.js | 24 ++++++++++++++---------- 2 files changed, 27 insertions(+), 10 deletions(-) diff --git a/frontend/css/main.css b/frontend/css/main.css index 7168493..4edacf1 100644 --- a/frontend/css/main.css +++ b/frontend/css/main.css @@ -421,6 +421,19 @@ body { font-size: 11px; font-weight: 500; } +/* Device cards render the reused liveness pill (.device-status-badge from device-detail), which brings + its own bg/padding/shape — so neutralize the dark wrapper for those. Wall cards keep the dark pill + above for their "NxN wall" label (they share .device-card-status but have no .is-liveness). */ +.device-card-status.is-liveness { + background: none; + backdrop-filter: none; + padding: 0; + border-radius: 0; +} +/* Lift the list pill off the screenshot so it stays legible over any image. */ +.device-card-status.is-liveness .device-status-badge { + box-shadow: 0 1px 4px rgba(0,0,0,0.6); +} .device-card-select { position: absolute; diff --git a/frontend/js/views/dashboard.js b/frontend/js/views/dashboard.js index 4f88a75..8f811eb 100644 --- a/frontend/js/views/dashboard.js +++ b/frontend/js/views/dashboard.js @@ -100,8 +100,8 @@ function renderDeviceCard(device) { ${t('dashboard.no_preview')}
` } -
- ${(() => { const b = livenessBadge(device); return `${esc(b.label)}`; })()} +
+ ${(() => { const b = livenessBadge(device); return `${esc(b.label)}`; })()}
${device.status === 'provisioning' && device.pairing_code ? `
@@ -268,10 +268,11 @@ export function render(container) {
- - - + + +
@@ -291,13 +292,16 @@ export function render(container) { function filterDevices() { const search = document.getElementById('deviceSearch').value.toLowerCase(); - const status = document.getElementById('deviceFilter').value; + // Compare against the liveness STATE ('healthy'|'degraded'|'offline'), NOT the display label: + // the badge text is now "Healthy"/"Reconnecting"/"Offline", so the old text-vs-'online' compare + // matched nothing and emptied the list. data-liveness carries the state for a robust match. + const state = document.getElementById('deviceFilter').value; document.querySelectorAll('.device-card').forEach(card => { const name = card.querySelector('.device-card-name')?.textContent.toLowerCase() || ''; - const deviceStatus = card.querySelector('.device-card-status span:last-child')?.textContent || ''; + const cardState = card.querySelector('.device-card-status [data-liveness]')?.dataset.liveness || ''; const matchSearch = !search || name.includes(search); - const matchStatus = !status || deviceStatus === status; - card.style.display = (matchSearch && matchStatus) ? '' : 'none'; + const matchState = !state || cardState === state; + card.style.display = (matchSearch && matchState) ? '' : 'none'; }); } @@ -362,7 +366,7 @@ export function render(container) { const cards = document.querySelectorAll(`[data-device-id="${data.device_id}"]`); cards.forEach(card => { const statusEl = card.querySelector('.device-card-status'); - if (statusEl) statusEl.innerHTML = `${esc(b.label)}`; + if (statusEl) statusEl.innerHTML = `${esc(b.label)}`; }); }; From 8ad2258e7cbd35d20445392a724554fecfac030d Mon Sep 17 00:00:00 2001 From: ScreenTinker Date: Wed, 8 Jul 2026 15:32:40 -0500 Subject: [PATCH 14/20] =?UTF-8?q?feat:=20app-ending=20signal=20(exit-signa?= =?UTF-8?q?l=20contract=20v1)=20=E2=80=94=20server=20+=20APK=20+=20.wgt=20?= =?UTF-8?q?+=20/player?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Best-effort "last gasp" so Offline is annotated with WHY it went away — completing the liveness story. Categories: crashed (client uncaught-exception), clean_exit (client confident lifecycle-end, best-effort), silent (SERVER-inferred by absence — the honest catch-all for violent/external death incl. force-stop/MDM). SERVER: - device:exit socket handler + token-authed beacon POST /api/device/exit (reliable-on-unload). Both gated by liveness.sanitizeExitReason (honesty: only crashed/clean_exit accepted; 'silent'/unknown rejected). - offline_reason/offline_reason_at/offline_detail columns (additive migration). Clear-on-online (a reason is always THIS session's); offline transition COALESCEs to 'silent'. Pure annotation — offline detection and #148/liveness are untouched. Offline dashboard emits carry offline_reason + client_type. CLIENTS (canonical {reason,detail} shape): - /player: window error/unhandledrejection + pagehide(persisted=false) -> sendBeacon. - .wgt: same + BACK-key exit -> socket.emit + sendBeacon. - APK: global UncaughtExceptionHandler -> crashed (blocking beacon, chains to default); Service.onDestroy -> clean_exit (socket + bounded beacon). New ExitSignal.kt. onStop/onPause NOT wired (background != exit). Proven (Phase 3): per-category classification, nothing misclassified, external kill -> silent (never clean_exit), backgrounding emits no false exit, #148/reconnect-vs-exit intact. 382/382 suite green. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../remotedisplay/player/RemoteDisplayApp.kt | 17 +++ .../player/service/ExitSignal.kt | 61 +++++++++ .../player/service/WebSocketService.kt | 13 ++ server/db/database.js | 7 + server/lib/liveness.js | 14 +- server/player/index.html | 38 ++++++ server/server.js | 23 ++++ server/services/heartbeat.js | 9 +- server/test/v4-exit-signal-phase3.test.js | 129 ++++++++++++++++++ server/test/v4-exit-signal.test.js | 95 +++++++++++++ server/ws/deviceSocket.js | 27 +++- tizen/js/app.js | 37 +++++ 12 files changed, 464 insertions(+), 6 deletions(-) create mode 100644 android/app/src/main/java/com/remotedisplay/player/service/ExitSignal.kt create mode 100644 server/test/v4-exit-signal-phase3.test.js create mode 100644 server/test/v4-exit-signal.test.js diff --git a/android/app/src/main/java/com/remotedisplay/player/RemoteDisplayApp.kt b/android/app/src/main/java/com/remotedisplay/player/RemoteDisplayApp.kt index 70e0f91..a8ccb9c 100644 --- a/android/app/src/main/java/com/remotedisplay/player/RemoteDisplayApp.kt +++ b/android/app/src/main/java/com/remotedisplay/player/RemoteDisplayApp.kt @@ -18,6 +18,23 @@ class RemoteDisplayApp : Application() { override fun onCreate() { super.onCreate() createNotificationChannel() + installCrashExitSignal() + } + + // Exit-signal contract v1 — 'crashed'. A global uncaught-exception handler fires a BEST-EFFORT + // blocking last-gasp to the server, then delegates to the previous default handler so the crash + // still propagates and the process dies normally. Runs on the crashing thread (already dying), so + // the short blocking POST is acceptable. BEST-EFFORT: a native/OOM kill runs no JVM handler -> + // nothing is sent -> the server infers 'silent'. Honesty: only ever emits 'crashed' here. + private fun installCrashExitSignal() { + val prev = Thread.getDefaultUncaughtExceptionHandler() + Thread.setDefaultUncaughtExceptionHandler { thread, throwable -> + try { + val detail = (throwable.javaClass.simpleName + ": " + (throwable.message ?: "")).trim() + com.remotedisplay.player.service.ExitSignal.send(this, "crashed", detail) + } catch (t: Throwable) { /* never mask the original crash */ } + prev?.uncaughtException(thread, throwable) // chain -> normal crash reporting + process death + } } private fun createNotificationChannel() { diff --git a/android/app/src/main/java/com/remotedisplay/player/service/ExitSignal.kt b/android/app/src/main/java/com/remotedisplay/player/service/ExitSignal.kt new file mode 100644 index 0000000..b22a879 --- /dev/null +++ b/android/app/src/main/java/com/remotedisplay/player/service/ExitSignal.kt @@ -0,0 +1,61 @@ +package com.remotedisplay.player.service + +import android.content.Context +import com.remotedisplay.player.data.ServerConfig +import okhttp3.MediaType.Companion.toMediaType +import okhttp3.OkHttpClient +import okhttp3.Request +import okhttp3.RequestBody.Companion.toRequestBody +import org.json.JSONObject +import java.util.concurrent.TimeUnit + +/** + * Exit-signal contract v1 — best-effort "last gasp" (manner of death), APK conformance. + * + * Sent via a BLOCKING OkHttp POST to /api/device/exit, NOT socket.emit: the socket emit path is + * async with no flush, so it will not reliably leave the buffer before the process dies. A short, + * bounded blocking POST from the crashing thread (about to die anyway) / a worker thread is the + * reliable transport on Android (matches the beacon the browser/Tizen clients use). + * + * Categories (honesty by construction — only ever these two; anything else -> server infers 'silent'): + * - "crashed" : the global uncaught-exception handler fired (RemoteDisplayApp). + * - "clean_exit" : Service.onDestroy on COOPERATIVE teardown (stopService/unbind/memory-reclaim-with- + * grace). NOT onStop/onPause (those fire on backgrounding). force-stop / MDM-uninstall + * / SIGKILL / OOM skip all callbacks -> nothing is sent -> server infers 'silent'. + * Idempotent: the first confident signal wins (a crash is never relabelled clean_exit). + */ +object ExitSignal { + @Volatile private var sent = false + private val JSON = "application/json".toMediaType() + private val client = OkHttpClient.Builder() + .callTimeout(2, TimeUnit.SECONDS) + .connectTimeout(2, TimeUnit.SECONDS) + .writeTimeout(2, TimeUnit.SECONDS) + .build() + + fun send(context: Context, reason: String, detail: String?) { + try { + if (sent) return + if (reason != "crashed" && reason != "clean_exit") return + val cfg = ServerConfig(context.applicationContext) + val id = cfg.deviceId + val token = cfg.deviceToken + val url = cfg.serverUrl + if (id.isEmpty() || token.isEmpty() || url.isEmpty()) return // unpaired -> nothing to attribute + sent = true + val payload = JSONObject().apply { + put("device_id", id) + put("device_token", token) + put("reason", reason) + if (!detail.isNullOrBlank()) put("detail", detail.take(200)) + }.toString() + val req = Request.Builder() + .url(url.trimEnd('/') + "/api/device/exit") + .post(payload.toRequestBody(JSON)) + .build() + client.newCall(req).execute().use { /* fire-and-forget; response ignored */ } + } catch (t: Throwable) { + /* a dying process must never throw further out of the last gasp */ + } + } +} diff --git a/android/app/src/main/java/com/remotedisplay/player/service/WebSocketService.kt b/android/app/src/main/java/com/remotedisplay/player/service/WebSocketService.kt index 3a91ef9..50834f6 100644 --- a/android/app/src/main/java/com/remotedisplay/player/service/WebSocketService.kt +++ b/android/app/src/main/java/com/remotedisplay/player/service/WebSocketService.kt @@ -776,6 +776,19 @@ class WebSocketService : Service() { fun isConnected(): Boolean = socket?.connected() == true override fun onDestroy() { + // Exit-signal contract v1 — 'clean_exit' (BEST-EFFORT). onDestroy runs ONLY on cooperative + // teardown (stopService/unbind/memory-reclaim-with-grace); a force-stop / MDM-uninstall / SIGKILL + // skips it entirely -> the server infers 'silent' (correct — not misclassified). Try the still- + // live socket first, then a bounded blocking beacon (the reliable path); the server dedups. + try { + if (socket?.connected() == true && config.deviceId.isNotEmpty()) { + socket?.emit("device:exit", JSONObject().apply { + put("device_id", config.deviceId); put("reason", "clean_exit"); put("detail", "onDestroy") + }) + } + } catch (e: Throwable) { /* never let the last gasp block teardown */ } + val ctx = applicationContext + Thread { ExitSignal.send(ctx, "clean_exit", "onDestroy") }.apply { start(); try { join(1500) } catch (e: InterruptedException) { /* proceed with teardown */ } } wakeLock?.let { if (it.isHeld) it.release() } disconnect() super.onDestroy() diff --git a/server/db/database.js b/server/db/database.js index 15481a9..b53d639 100644 --- a/server/db/database.js +++ b/server/db/database.js @@ -94,6 +94,13 @@ const migrations = [ 'ALTER TABLE devices ADD COLUMN client_version TEXT', 'ALTER TABLE devices ADD COLUMN platform TEXT', 'ALTER TABLE devices ADD COLUMN contract_version TEXT', + // Exit-signal contract v1 — manner-of-death annotation on Offline (additive; NEVER alters offline + // detection). offline_reason: 'crashed'|'clean_exit' (client-sent via device:exit / beacon) or + // 'silent' (server-inferred when no signal arrived). Cleared on (re)online so it's always this + // session's. offline_detail: optional crash message / lifecycle-hook name. + 'ALTER TABLE devices ADD COLUMN offline_reason TEXT', + 'ALTER TABLE devices ADD COLUMN offline_reason_at INTEGER', + 'ALTER TABLE devices ADD COLUMN offline_detail TEXT', // Email settings on users "ALTER TABLE users ADD COLUMN email_alerts INTEGER DEFAULT 1", // Content folders diff --git a/server/lib/liveness.js b/server/lib/liveness.js index ee45ab6..681c4cb 100644 --- a/server/lib/liveness.js +++ b/server/lib/liveness.js @@ -66,4 +66,16 @@ function identityChanged(current, incoming) { || current.contract_version !== incoming.contract_version; } -module.exports = { ackableHeartbeat, deriveLiveness, captureIdentity, identityChanged, HEALTHY_HEARTBEAT_MS, DEGRADED_RECONNECTS }; +// Exit-signal contract v1 — manner-of-death. A client may ONLY announce 'crashed' (its uncaught- +// exception handler fired) or 'clean_exit' (a confident lifecycle-end). 'silent' is server-inferred by +// ABSENCE and is NEVER accepted from a client. Honesty by construction: an unknown/uncertain value is +// rejected (-> null), so the device falls to server-inferred 'silent' rather than being coerced into a +// wrong category. detail is optional (crash message / lifecycle-hook name), sanitized + length-capped. +const CLIENT_EXIT_REASONS = ['crashed', 'clean_exit']; +function sanitizeExitReason(reason, detail) { + if (!CLIENT_EXIT_REASONS.includes(reason)) return null; + const d = (typeof detail === 'string' && detail.trim()) ? detail.trim().slice(0, 200) : null; + return { reason, detail: d }; +} + +module.exports = { ackableHeartbeat, deriveLiveness, captureIdentity, identityChanged, sanitizeExitReason, CLIENT_EXIT_REASONS, HEALTHY_HEARTBEAT_MS, DEGRADED_RECONNECTS }; diff --git a/server/player/index.html b/server/player/index.html index 060ccf1..3944ae9 100644 --- a/server/player/index.html +++ b/server/player/index.html @@ -345,6 +345,44 @@ let config = getConfig(); let playlist = []; let currentIndex = -1; + + // ==================== Exit-signal contract v1 (best-effort last gasp) ==================== + // Announce manner-of-death via navigator.sendBeacon (reliable-on-unload — survives the socket + // teardown). crashed: real uncaught SCRIPT error / unhandled rejection. clean_exit: pagehide with + // persisted=false (a genuine unload — NOT a bfcache suspend, which the liveness watchdog handles, + // and NOT mere visibility-hidden). Honesty: only these two confident categories are ever sent; + // anything uncertain sends nothing -> the server infers 'silent'. Idempotent (first signal wins, + // so a crash is never relabelled clean_exit by the pagehide that follows it). + let __exitSent = false; + function sendExitBeacon(reason, detail) { + try { + if (__exitSent) return; + if (reason !== 'crashed' && reason !== 'clean_exit') return; + if (!config || !config.deviceId || !config.deviceToken) return; // unpaired -> nothing to attribute + __exitSent = true; + const url = (config.serverUrl || window.location.origin) + '/api/device/exit'; + const body = JSON.stringify({ device_id: config.deviceId, device_token: config.deviceToken, + reason, detail: (typeof detail === 'string' && detail) ? detail.slice(0, 200) : undefined }); + const blob = new Blob([body], { type: 'application/json' }); // Content-Type so express.json parses it + if (navigator.sendBeacon && navigator.sendBeacon(url, blob)) return; + fetch(url, { method: 'POST', body, headers: { 'Content-Type': 'application/json' }, keepalive: true }).catch(() => {}); + } catch (e) { /* a dying page must never throw */ } + } + window.addEventListener('error', (ev) => { + // ONLY a real uncaught script error is a crash — a resource (img/script/link) load failure is NOT. + if (!ev) return; + const isResourceError = ev.target && ev.target !== window && (ev.target.src || ev.target.href); + if (isResourceError) return; + sendExitBeacon('crashed', (ev.error && ev.error.message) || ev.message || 'error'); + }); + window.addEventListener('unhandledrejection', (ev) => { + const r = ev && ev.reason; + sendExitBeacon('crashed', (r && (r.message || String(r))) || 'unhandledrejection'); + }); + window.addEventListener('pagehide', (ev) => { + if (ev && ev.persisted) return; // bfcache SUSPEND (may restore) — NOT a death; watchdog owns it + sendExitBeacon('clean_exit', 'pagehide'); + }); let isPlaying = false; let playerTimezone = null; // #74/#75: device-effective IANA tz for schedule eval let scheduleRetryTimer = null; // re-check when every item is filtered out diff --git a/server/server.js b/server/server.js index 6b56a41..9d99d7a 100644 --- a/server/server.js +++ b/server/server.js @@ -647,6 +647,29 @@ app.get('/api/update/check', (req, res) => { }); }); +// Exit-signal contract v1 — beacon transport (reliable-on-unload). Clients that can't reliably +// socket.emit at death (browser/Tizen pagehide, APK crash where async emit won't flush) POST their +// manner-of-death here via navigator.sendBeacon / blocking HTTP. Token-authed (there's no JWT/socket +// session at unload time); PUBLIC (mounted before requireAuth). Sets offline_reason exactly like the +// device:exit socket handler — the later Offline transition resolves + surfaces it. NEVER triggers +// offline itself (additive only). Always 204 (never error a dying client; never leak an id/token oracle). +app.post('/api/device/exit', (req, res) => { + const { db } = require('./db/database'); + const liveness = require('./lib/liveness'); + const { device_id, device_token, reason, detail } = req.body || {}; + if (!device_id || typeof device_token !== 'string') return res.status(204).end(); + const row = db.prepare('SELECT device_token FROM devices WHERE id = ?').get(device_id); + let ok = false; + try { + ok = !!(row && row.device_token && device_token.length === row.device_token.length && + crypto.timingSafeEqual(Buffer.from(row.device_token), Buffer.from(device_token))); + } catch (_) { ok = false; } + if (!ok) return res.status(204).end(); + const e = liveness.sanitizeExitReason(reason, detail); // unknown/invalid -> null -> device falls to 'silent' + if (e) db.prepare("UPDATE devices SET offline_reason = ?, offline_reason_at = strftime('%s','now'), offline_detail = ? WHERE id = ?").run(e.reason, e.detail, device_id); + res.status(204).end(); +}); + // (Content file endpoint moved above protected routes) // (Screenshot route moved above protected routes) diff --git a/server/services/heartbeat.js b/server/services/heartbeat.js index dccac39..107d9a8 100644 --- a/server/services/heartbeat.js +++ b/server/services/heartbeat.js @@ -84,15 +84,22 @@ function startHeartbeatChecker(io) { const sock = deviceNs.sockets.get(conn.socketId); if (sock) { try { sock.disconnect(true); } catch (_) { /* already gone */ } } } - db.prepare("UPDATE devices SET status = 'offline', updated_at = strftime('%s','now') WHERE id = ?") + // Exit-signal contract: this timeout path is the classic 'silent' case (froze, no clean + // disconnect, no signal) — COALESCE annotates 'silent' unless a device:exit reason arrived + // this session (e.g. a crash emit that beat the freeze). Pure annotation; detection unchanged. + db.prepare("UPDATE devices SET status = 'offline', updated_at = strftime('%s','now'), offline_reason = COALESCE(offline_reason, 'silent'), offline_reason_at = COALESCE(offline_reason_at, strftime('%s','now')) WHERE id = ?") .run(device.id); deviceConnections.delete(device.id); + const _off = db.prepare("SELECT offline_reason, offline_detail, client_type FROM devices WHERE id = ?").get(device.id) || {}; // Notify dashboard (workspace-scoped via the device's room). emitToWorkspace(dashboardNs, deviceRoom(device.id), 'dashboard:device-status', { device_id: device.id, status: 'offline', liveness: 'offline', // FIX 2: derived — no live socket => offline (a normal state, not an error) + offline_reason: _off.offline_reason || 'silent', // exit-signal contract: manner-of-death + offline_detail: _off.offline_detail || null, + client_type: _off.client_type || null, telemetry: null }); reconnectTimes.delete(device.id); // clear churn history on a clean offline diff --git a/server/test/v4-exit-signal-phase3.test.js b/server/test/v4-exit-signal-phase3.test.js new file mode 100644 index 0000000..cee6e9e --- /dev/null +++ b/server/test/v4-exit-signal-phase3.test.js @@ -0,0 +1,129 @@ +// Exit-signal PHASE 3 — proof. (A) socket/#148/liveness safety; (B) per-category classification with +// NOTHING misclassified. The JS-client handlers are proven by EXECUTING THE REAL SOURCE blocks (sliced +// out of index.html / app.js) against shimmed window/navigator/socket and firing synthetic death events. +const path = require('node:path'); const os = require('node:os'); const fs = require('node:fs'); const crypto = require('node:crypto'); +const { test, before, after } = require('node:test'); +const assert = require('node:assert/strict'); +const { spawn } = require('node:child_process'); +const ioClient = require('../node_modules/socket.io-client'); +const sleep = ms => new Promise(r => setTimeout(r, ms)); + +// ---- harness: run a real client exit-block against shims, capturing what it sends ---- +function harness(file, startLine, endLine) { + const src = fs.readFileSync(file, 'utf8').split('\n').slice(startLine - 1, endLine).join('\n'); + const beacons = [], socketSends = [], handlers = {}; + const windowShim = { addEventListener: (ev, fn) => { (handlers[ev] = handlers[ev] || []).push(fn); }, location: { origin: 'http://srv' } }; + const navShim = { sendBeacon: (url, blob) => { beacons.push({ url, ...JSON.parse(blob.__body) }); return true; } }; + class BlobShim { constructor(parts, o) { this.__body = parts[0]; this.type = o && o.type; } } + const socketShim = { connected: true, emit: (ev, payload) => { socketSends.push({ ev, ...payload }); } }; + const config = { deviceId: 'D1', deviceToken: 'T1', serverUrl: 'http://srv' }; // /player reads config.* + const fn = new Function('window', 'navigator', 'Blob', 'fetch', 'config', 'deviceId', 'deviceToken', 'serverUrl', 'socket', 'JSON', src); + fn(windowShim, navShim, BlobShim, () => Promise.resolve(), config, 'D1', 'T1', 'http://srv', socketShim, JSON); + return { beacons, socketSends, fire: (ev, e) => (handlers[ev] || []).forEach(f => f(e)), handlers }; +} +const WINDOW = 'window-target'; // sentinel for ev.target === window (real error event on window) + +// ============ PART B — /player classification (real source, lines 349-385) ============ +const PLAYER = path.join(__dirname, '../player/index.html'); +test('B/player CRASH: uncaught error + unhandledrejection -> crashed (via sendBeacon, NOT the socket)', () => { + let h = harness(PLAYER, 349, 385); h.fire('error', { error: { message: 'boom' }, target: undefined }); + assert.equal(h.beacons.length, 1); assert.equal(h.beacons[0].reason, 'crashed'); + assert.equal(h.socketSends.length, 0, '/player uses the beacon channel only — no send over the dying socket'); + h = harness(PLAYER, 349, 385); h.fire('unhandledrejection', { reason: { message: 'rej' } }); + assert.equal(h.beacons[0].reason, 'crashed'); +}); +test('B/player NO-MISCLASSIFY: a RESOURCE load error (img/script) is NOT a crash', () => { + const h = harness(PLAYER, 349, 385); h.fire('error', { target: { src: 'https://x/img.png' } }); + assert.equal(h.beacons.length, 0, 'resource error must not emit crashed'); +}); +test('B/player CLEAN-CLOSE: pagehide(persisted=false) -> clean_exit', () => { + const h = harness(PLAYER, 349, 385); h.fire('pagehide', { persisted: false }); + assert.equal(h.beacons[0].reason, 'clean_exit'); +}); +test('B/player BACKGROUNDING: pagehide(persisted=true) bfcache suspend -> NO exit (not a death)', () => { + const h = harness(PLAYER, 349, 385); h.fire('pagehide', { persisted: true }); + assert.equal(h.beacons.length, 0, 'a suspend must NOT emit clean_exit'); + assert.equal((h.handlers['visibilitychange'] || []).length, 0, 'exit block wires NO visibilitychange -> hidden never emits exit'); +}); +test('B/player IDEMPOTENT: crash then pagehide -> only crashed (crash not relabelled clean_exit)', () => { + const h = harness(PLAYER, 349, 385); h.fire('error', { error: { message: 'boom' } }); h.fire('pagehide', { persisted: false }); + assert.equal(h.beacons.length, 1); assert.equal(h.beacons[0].reason, 'crashed'); +}); + +// ============ PART B — .wgt classification (real source, lines 663-697) ============ +const TIZEN = path.join(__dirname, '../../tizen/js/app.js'); +test('B/wgt CRASH: error/rejection -> crashed (socket AND beacon; server dedups)', () => { + const h = harness(TIZEN, 663, 697); h.fire('error', { error: { message: 'boom' } }); + assert.equal(h.beacons[0].reason, 'crashed'); + assert.equal(h.socketSends[0].reason, 'crashed'); assert.equal(h.socketSends[0].ev, 'device:exit'); +}); +test('B/wgt NO-MISCLASSIFY: resource error is not a crash', () => { + const h = harness(TIZEN, 663, 697); h.fire('error', { target: { src: 'x.png' } }); + assert.equal(h.beacons.length, 0); assert.equal(h.socketSends.length, 0); +}); +test('B/wgt CLEAN-CLOSE: pagehide(false) -> clean_exit; BACKGROUNDING pagehide(true) -> NO exit', () => { + let h = harness(TIZEN, 663, 697); h.fire('pagehide', { persisted: false }); + assert.equal(h.beacons[0].reason, 'clean_exit'); + h = harness(TIZEN, 663, 697); h.fire('pagehide', { persisted: true }); + assert.equal(h.beacons.length, 0, 'suspend must NOT emit clean_exit'); + assert.equal((h.handlers['visibilitychange'] || []).length, 0, 'no visibilitychange in the exit block'); +}); + +// ============ PART A — server-side socket / #148 / reconnect-vs-exit safety ============ +const PORT = 3975; const BASE = `http://127.0.0.1:${PORT}`; +const DATA_DIR = path.join(os.tmpdir(), 'st-exit3-' + crypto.randomBytes(4).toString('hex')); +let proc, JWT; +before(async () => { + const logFd = fs.openSync(path.join(os.tmpdir(), 'st-exit3.log'), 'w'); + proc = spawn('node', ['server.js'], { cwd: path.join(__dirname, '..'), env: { ...process.env, DATA_DIR, SELF_HOSTED: 'true', PORT: String(PORT), NODE_ENV: 'test' }, stdio: ['ignore', logFd, logFd] }); + let up = false; for (let i = 0; i < 80; i++) { try { if ((await fetch(BASE + '/api/status')).ok) { up = true; break; } } catch {} await sleep(250); } + if (!up) throw new Error('boot fail'); + JWT = (await (await fetch(BASE + '/api/auth/register', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ email: 'op@t.local', password: 'test12345', name: 'Op' }) })).json()).token; +}); +after(() => { try { proc.kill('SIGKILL'); } catch {} }); +const connect = () => ioClient(`${BASE}/device`, { transports: ['websocket'], reconnection: false, forceNew: true }); +const reg = (s, m) => new Promise((res, rej) => { s.once('device:registered', d => res(d)); s.emit('device:register', m); setTimeout(() => rej(new Error('to')), 5000); }); +const pair = (c) => fetch(BASE + '/api/provision/pair', { method: 'POST', headers: { Authorization: 'Bearer ' + JWT, 'Content-Type': 'application/json' }, body: JSON.stringify({ pairing_code: c, name: 't' }) }); +const row = async (id) => (await (await fetch(`${BASE}/api/devices/${id}`, { headers: { Authorization: 'Bearer ' + JWT } })).json()); +const ackWithin = (s, hb, ms = 1500) => new Promise(r => { let d = false; const f = v => { if (!d) { d = true; r(v); } }; s.once('device:heartbeat-ack', () => f(true)); s.emit('device:heartbeat', hb); setTimeout(() => f(false), ms); }); + +test('A: crash-emit then teardown -> device goes Offline normally (no orphan/half-open) + reason kept', async () => { + const s = connect(); await new Promise(r => s.on('connect', r)); + const d = await reg(s, { pairing_code: '820001', fingerprint: 'f1', device_info: {}, client_type: 'apk', contract_version: 'v4' }); + await pair('820001'); await sleep(150); + s.emit('device:exit', { reason: 'crashed', detail: 'boom' }); // emit AS the socket is about to die + s.close(); // teardown immediately after + await sleep(5800); + const r = await row(d.device_id); + assert.equal(r.status, 'offline', 'normal offline transition still fired (teardown not disturbed)'); + assert.equal(r.offline_reason, 'crashed'); +}); + +test('A: RECONNECT is NOT an exit, and an exit does not block reconnect — #148 one socket, reason cleared', async () => { + const s1 = connect(); await new Promise(r => s1.on('connect', r)); + const d = await reg(s1, { pairing_code: '820002', fingerprint: 'f2', device_info: {}, client_type: 'apk', contract_version: 'v4' }); + await pair('820002'); await sleep(150); + s1.emit('device:exit', { reason: 'crashed' }); await sleep(150); + assert.equal((await row(d.device_id)).offline_reason, 'crashed'); + s1.close(); await sleep(300); + // genuine reconnect (new socket) — must NOT emit an exit, and must clear the stale reason + const s2 = connect(); await new Promise(r => s2.on('connect', r)); + await reg(s2, { device_id: d.device_id, device_token: d.device_token, fingerprint: 'f2', device_info: {}, client_type: 'apk', contract_version: 'v4' }); + await sleep(200); + assert.equal((await row(d.device_id)).offline_reason, null, 'reconnect cleared the reason (reconnect != exit)'); + assert.equal(await ackWithin(s2, { device_id: d.device_id, telemetry: {} }), true, 'the single reconnected socket is healthy (#148 intact)'); + assert.equal((await row(d.device_id)).status, 'online'); + s2.close(); +}); + +test('A: VIOLENT kill (abrupt drop, NO device:exit) -> silent, never crashed/clean_exit (Bold-critical)', async () => { + const s = connect(); await new Promise(r => s.on('connect', r)); + const d = await reg(s, { pairing_code: '820003', fingerprint: 'f3', device_info: {}, client_type: 'apk', contract_version: 'v4' }); + await pair('820003'); await sleep(150); + s.io.engine.close(); // hard transport drop — no clean disconnect, no exit signal (force-stop/power/MDM) + await sleep(5800); + const r = await row(d.device_id); + assert.equal(r.status, 'offline'); + assert.equal(r.offline_reason, 'silent', 'external/violent death reads as silent'); + assert.notEqual(r.offline_reason, 'clean_exit'); assert.notEqual(r.offline_reason, 'crashed'); +}); diff --git a/server/test/v4-exit-signal.test.js b/server/test/v4-exit-signal.test.js new file mode 100644 index 0000000..7d4558f --- /dev/null +++ b/server/test/v4-exit-signal.test.js @@ -0,0 +1,95 @@ +// Exit-signal contract v1 — manner-of-death annotation on Offline. Server-side proof: the socket +// device:exit handler + the beacon POST endpoint set offline_reason; the Offline transition resolves +// crashed/clean_exit (kept) vs silent (no signal); clear-on-online prevents stale mislabels; honesty +// (client-sent 'silent'/garbage rejected). Client emit paths are proven in Phase 3 per platform. +const path = require('node:path'); const os = require('node:os'); const fs = require('node:fs'); const crypto = require('node:crypto'); +const { test, before, after } = require('node:test'); +const assert = require('node:assert/strict'); +const { spawn } = require('node:child_process'); +const ioClient = require('../node_modules/socket.io-client'); +const liveness = require('../lib/liveness'); +const sleep = ms => new Promise(r => setTimeout(r, ms)); + +// ===== UNIT: honesty by construction (sanitizeExitReason) ===== +test('sanitizeExitReason: only crashed/clean_exit accepted; silent + unknown REJECTED (-> server silent)', () => { + assert.equal(liveness.sanitizeExitReason('crashed', 'boom').reason, 'crashed'); + assert.equal(liveness.sanitizeExitReason('clean_exit', null).reason, 'clean_exit'); + assert.equal(liveness.sanitizeExitReason('silent'), null); // server-inferred only — never from a client + assert.equal(liveness.sanitizeExitReason('exploded'), null); // never fabricate an unknown category + assert.equal(liveness.sanitizeExitReason(''), null); + assert.equal(liveness.sanitizeExitReason('crashed', 'x'.repeat(500)).detail.length, 200); // capped + assert.equal(liveness.sanitizeExitReason('crashed', ' ').detail, null); // blank -> null +}); + +// ===== E2E ===== +const PORT = 3974; const BASE = `http://127.0.0.1:${PORT}`; +const DATA_DIR = path.join(os.tmpdir(), 'st-exit-' + crypto.randomBytes(4).toString('hex')); +const LOG = path.join(os.tmpdir(), 'st-exit.log'); +let proc, JWT; + +before(async () => { + const logFd = fs.openSync(LOG, 'w'); + proc = spawn('node', ['server.js'], { cwd: path.join(__dirname, '..'), env: { ...process.env, DATA_DIR, SELF_HOSTED: 'true', PORT: String(PORT), NODE_ENV: 'test' }, stdio: ['ignore', logFd, logFd] }); + let up = false; for (let i = 0; i < 80; i++) { try { if ((await fetch(BASE + '/api/status')).ok) { up = true; break; } } catch { /* */ } await sleep(250); } + if (!up) throw new Error('boot fail:\n' + fs.readFileSync(LOG, 'utf8').slice(-2000)); + JWT = (await (await fetch(BASE + '/api/auth/register', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ email: 'op@t.local', password: 'test12345', name: 'Op' }) })).json()).token; +}); +after(() => { try { proc.kill('SIGKILL'); } catch { /* */ } }); + +const connect = () => ioClient(`${BASE}/device`, { transports: ['websocket'], reconnection: false, forceNew: true }); +const registerOn = (s, msg) => new Promise((res, rej) => { s.once('device:registered', d => res(d)); s.emit('device:register', msg); setTimeout(() => rej(new Error('reg timeout')), 5000); }); +const pair = (code) => fetch(BASE + '/api/provision/pair', { method: 'POST', headers: { Authorization: 'Bearer ' + JWT, 'Content-Type': 'application/json' }, body: JSON.stringify({ pairing_code: code, name: 't' }) }); +const row = async (id) => (await (await fetch(`${BASE}/api/devices/${id}`, { headers: { Authorization: 'Bearer ' + JWT } })).json()); +async function provisionPaired(code, ident = {}) { + const s = connect(); await new Promise(r => s.on('connect', r)); + const reg = await registerOn(s, { pairing_code: code, fingerprint: 'fp' + code, device_info: {}, ...ident }); + await pair(code); await sleep(150); + return { s, id: reg.device_id, token: reg.device_token }; +} + +// (4 devices — the SELF_HOSTED plan caps at 5; offline devices still count.) + +test('crashed: device:exit sets offline_reason, and it SURVIVES the Offline transition (COALESCE)', async () => { + const d = await provisionPaired('810001', { client_type: 'apk', contract_version: 'v4' }); + d.s.emit('device:exit', { reason: 'crashed', detail: 'NullPointerException: boom' }); + await sleep(250); + assert.equal((await row(d.id)).offline_reason, 'crashed', 'set immediately on device:exit'); + d.s.close(); await sleep(5800); // OFFLINE_DEBOUNCE_MS=5000 + const r = await row(d.id); + assert.equal(r.status, 'offline'); assert.equal(r.offline_reason, 'crashed', 'kept through Offline (not overwritten by silent)'); +}); + +test('clean_exit + clear-on-online: reason set, then CLEARED on re-register (no stale mislabel)', async () => { + const d = await provisionPaired('810002', { client_type: 'wgt', contract_version: 'v4' }); + d.s.emit('device:exit', { reason: 'clean_exit', detail: 'onDestroy' }); await sleep(250); + assert.equal((await row(d.id)).offline_reason, 'clean_exit'); + d.s.close(); await sleep(300); + const s2 = connect(); await new Promise(r => s2.on('connect', r)); // reconnect = fresh session + await registerOn(s2, { device_id: d.id, device_token: d.token, fingerprint: 'fp810002', device_info: {}, client_type: 'wgt', contract_version: 'v4' }); + await sleep(200); + assert.equal((await row(d.id)).offline_reason, null, 'cleared on (re)online — a later death starts fresh'); + s2.close(); +}); + +test('silent + honesty: client-sent silent/garbage REJECTED, then Offline-with-no-signal -> server silent', async () => { + const d = await provisionPaired('810003', { client_type: 'apk', contract_version: 'v4' }); // also the old-client / no-signal case + d.s.emit('device:exit', { reason: 'silent' }); // client must NOT be able to assert silent + d.s.emit('device:exit', { reason: 'kaboom' }); // unknown -> rejected, never fabricated + await sleep(300); + assert.equal((await row(d.id)).offline_reason, null, 'neither client value was accepted'); + d.s.close(); await sleep(5800); + const r = await row(d.id); + assert.equal(r.status, 'offline'); assert.equal(r.offline_reason, 'silent', 'server infers silent on Offline (correct)'); +}); + +test('beacon endpoint: valid token sets reason; bad token is a silent 204 no-op', async () => { + const d = await provisionPaired('810004', { client_type: 'player', contract_version: 'v4' }); + const post = (body) => fetch(BASE + '/api/device/exit', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) }); + let res = await post({ device_id: d.id, device_token: 'WRONG', reason: 'crashed' }); + assert.equal(res.status, 204); + assert.equal((await row(d.id)).offline_reason, null, 'bad token did NOT set a reason (no oracle, no write)'); + res = await post({ device_id: d.id, device_token: d.token, reason: 'clean_exit', detail: 'pagehide' }); + assert.equal(res.status, 204); await sleep(150); + assert.equal((await row(d.id)).offline_reason, 'clean_exit', 'valid-token beacon set the reason'); + d.s.close(); +}); diff --git a/server/ws/deviceSocket.js b/server/ws/deviceSocket.js index 2dc6344..56d0b38 100644 --- a/server/ws/deviceSocket.js +++ b/server/ws/deviceSocket.js @@ -417,7 +417,7 @@ module.exports = function setupDeviceSocket(io) { pendingOfflines.delete(existing.device_id); } evictPriorSocket(existing.device_id, socket.id); - db.prepare("UPDATE devices SET status = 'online', last_heartbeat = strftime('%s','now'), ip_address = ?, updated_at = strftime('%s','now') WHERE id = ?") + db.prepare("UPDATE devices SET status = 'online', last_heartbeat = strftime('%s','now'), ip_address = ?, updated_at = strftime('%s','now'), offline_reason = NULL, offline_reason_at = NULL, offline_detail = NULL WHERE id = ?") .run(getClientIp(socket), existing.device_id); socket.emit('device:registered', { device_id: existing.device_id, device_token: newToken, status: 'online' }); // If device was already claimed by a user, tell the player it's paired @@ -527,7 +527,7 @@ module.exports = function setupDeviceSocket(io) { } evictPriorSocket(device_id, socket.id); sessionSettle.accepted(device_id); // #148 patch2: (re)arm the settle window on an accepted connection - db.prepare("UPDATE devices SET status = 'online', last_heartbeat = strftime('%s','now'), ip_address = ?, updated_at = strftime('%s','now') WHERE id = ?") + db.prepare("UPDATE devices SET status = 'online', last_heartbeat = strftime('%s','now'), ip_address = ?, updated_at = strftime('%s','now'), offline_reason = NULL, offline_reason_at = NULL, offline_detail = NULL WHERE id = ?") .run(getClientIp(socket), device_id); // #143: past the validateDeviceToken gate above the stored token is @@ -836,6 +836,21 @@ module.exports = function setupDeviceSocket(io) { .run(ota_status ?? 'none', ota_target_version ?? null, ota_attempts ?? 0, device_id); }); + // Exit-signal contract v1 — the device's best-effort "last gasp": it announces its manner of death + // (crashed | clean_exit) as (usually) its final act. We record it; when the device then goes Offline + // the annotation is applied (else 'silent'). ADDITIVE — never touches offline detection. Cleared on + // (re)online (the register UPDATEs) so a stale reason can't mislabel a later death. The same canonical + // shape also arrives via the beacon POST /api/device/exit for reliable-on-unload delivery. + socket.on('device:exit', (data) => { + if (!requireDeviceAuth() || !currentDeviceId) return; + const { device_id, reason, detail } = data || {}; + if (device_id && device_id !== currentDeviceId) return; // forged/mismatched -> no-op + const e = liveness.sanitizeExitReason(reason, detail); // unknown -> null -> falls to 'silent' + if (!e) return; + db.prepare("UPDATE devices SET offline_reason = ?, offline_reason_at = strftime('%s','now'), offline_detail = ? WHERE id = ?") + .run(e.reason, e.detail, currentDeviceId); + }); + // Play event logging (proof-of-play) socket.on('device:play-event', (data) => { if (!requireDeviceAuth()) return; @@ -959,10 +974,14 @@ module.exports = function setupDeviceSocket(io) { const activeNow = heartbeat.getConnection(deviceId); if (activeNow && activeNow.socketId !== closingSocketId) return; - db.prepare("UPDATE devices SET status = 'offline', updated_at = strftime('%s','now') WHERE id = ?").run(deviceId); + // Exit-signal contract: resolve manner-of-death. If the device announced a reason before dying + // (offline_reason non-NULL, set by device:exit/beacon this session), keep it; else -> 'silent' + // (no signal arrived). COALESCE makes this a pure annotation — offline detection is unchanged. + db.prepare("UPDATE devices SET status = 'offline', updated_at = strftime('%s','now'), offline_reason = COALESCE(offline_reason, 'silent'), offline_reason_at = COALESCE(offline_reason_at, strftime('%s','now')) WHERE id = ?").run(deviceId); heartbeat.removeConnection(deviceId); logDeviceStatus(deviceId, 'offline'); - emitToDeviceWorkspace(dashboardNs, deviceId, 'dashboard:device-status', { device_id: deviceId, status: 'offline' }); + const _off = db.prepare("SELECT offline_reason, offline_detail, client_type FROM devices WHERE id = ?").get(deviceId) || {}; + emitToDeviceWorkspace(dashboardNs, deviceId, 'dashboard:device-status', { device_id: deviceId, status: 'offline', liveness: 'offline', offline_reason: _off.offline_reason || 'silent', offline_detail: _off.offline_detail || null, client_type: _off.client_type || null }); // If this device was leading a wall, reassign leadership to the next // online member so playback stays driven. diff --git a/tizen/js/app.js b/tizen/js/app.js index 3ac68ad..b208c64 100644 --- a/tizen/js/app.js +++ b/tizen/js/app.js @@ -640,6 +640,7 @@ if (e.keyCode === 10009) { // Samsung RETURN / BACK if (!elSetup.classList.contains('hidden')) { stopKeepAwake(); stopWatchdog(); // FIX A/B: clear timers cleanly before the app exits + sendExitSignal('clean_exit', 'back_key'); // exit-signal: operator BACK-key exit = confident clean_exit try { tizen.application.getCurrentApplication().exit(); } catch (x) {} } else { if (socket) { try { socket.disconnect(); } catch (x) {} } @@ -658,6 +659,42 @@ startKeepAwake(); // FIX A: assert + re-assert keep-awake on an interval document.addEventListener('visibilitychange', onVisibility); // FIX B: suspend/resume fast-path startWatchdog(); // FIX B (hardened): server-silence liveness backstop + + // Exit-signal contract v1 — best-effort last gasp. crashed: window.onerror / unhandledrejection. + // clean_exit: operator BACK-key exit (below) + pagehide(persisted=false, a real unload not a bfcache + // suspend). Sends over BOTH the live socket (reliable when still connected, e.g. BACK-key / in-app + // crash) AND navigator.sendBeacon (reliable-on-unload — Chromium webview); the server dedups. Honesty: + // only these two confident categories; uncertain -> nothing -> server infers 'silent'. A Tizen system/ + // launcher terminate fires NO hook here -> correctly falls to 'silent'. Idempotent (first wins). + var __exitSent = false; + function sendExitSignal(reason, detail) { + try { + if (__exitSent) return; + if (reason !== 'crashed' && reason !== 'clean_exit') return; + if (!deviceId || !deviceToken || !serverUrl) return; // unpaired -> nothing to attribute + __exitSent = true; + var d = (typeof detail === 'string' && detail) ? detail.slice(0, 200) : undefined; + if (socket && socket.connected) { try { socket.emit('device:exit', { device_id: deviceId, reason: reason, detail: d }); } catch (e) {} } + if (navigator.sendBeacon) { + var body = JSON.stringify({ device_id: deviceId, device_token: deviceToken, reason: reason, detail: d }); + navigator.sendBeacon(serverUrl.replace(/\/+$/, '') + '/api/device/exit', new Blob([body], { type: 'application/json' })); + } + } catch (e) { /* a dying app must never throw */ } + } + window.addEventListener('error', function (ev) { + if (!ev) return; + var isResourceError = ev.target && ev.target !== window && (ev.target.src || ev.target.href); // img/script load fail is NOT a crash + if (isResourceError) return; + sendExitSignal('crashed', (ev.error && ev.error.message) || ev.message || 'error'); + }); + window.addEventListener('unhandledrejection', function (ev) { + var r = ev && ev.reason; + sendExitSignal('crashed', (r && (r.message || String(r))) || 'unhandledrejection'); + }); + window.addEventListener('pagehide', function (ev) { + if (ev && ev.persisted) return; // bfcache suspend (may restore) — NOT a death; the watchdog owns it + sendExitSignal('clean_exit', 'pagehide'); + }); if (serverUrl && deviceId && deviceToken) { // A2: render cached content IMMEDIATELY so a cold-start/offline TV isn't blank while the socket // connects (or if it can't). The socket's fresh device:playlist-update replaces it on connect. From f1fe5d97bdfeae0b0c2f5c97308c2b596e1ec45c Mon Sep 17 00:00:00 2001 From: ScreenTinker Date: Wed, 8 Jul 2026 15:32:55 -0500 Subject: [PATCH 15/20] =?UTF-8?q?feat(dashboard):=20exit-reason=20display?= =?UTF-8?q?=20=E2=80=94=20Offline=20annotation=20+=20tooltip=20+=20filter?= =?UTF-8?q?=20drill-in=20+=20list=20label?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Surface the server's manner-of-death (crashed / clean_exit / silent) as a subordinate qualifier ON the Offline badge (not a 4th liveness state), on both the device list and device-detail. Rides livenessBadge. - Reliability-aware label (contract §10): clean_exit reads plainly on /player (reliable), "(best-effort)" on APK/.wgt. silent = "silent (no signal)". - Honest hover tooltip on every reason (both views), incl. silent = "external/violent: power loss, network, force-stop, or MDM/kill". Never fabricates a reason (no-reason -> plain Offline); state-gated (reason only on Offline); clears on re-online (matches the server). - Filter drill-in: "Offline by reason" -> Offline · silent / crashed / clean exit, matched via a data-offline-reason attribute (Offline·silent = the MDM-killed set — the Bold use case). Existing three-state filter (All/Healthy/Reconnecting/Offline) unchanged. - List label shortened to fit the pill (full text stays on detail; tooltip carries the full honesty both). Co-Authored-By: Claude Opus 4.8 (1M context) --- frontend/js/i18n/en.js | 16 ++++++++++++++ frontend/js/utils.js | 35 ++++++++++++++++++++++++++++-- frontend/js/views/dashboard.js | 24 ++++++++++++++------ frontend/js/views/device-detail.js | 3 ++- 4 files changed, 68 insertions(+), 10 deletions(-) diff --git a/frontend/js/i18n/en.js b/frontend/js/i18n/en.js index f447dbb..cce3843 100644 --- a/frontend/js/i18n/en.js +++ b/frontend/js/i18n/en.js @@ -268,6 +268,22 @@ export default { 'device.liveness.healthy': 'Healthy', 'device.liveness.degraded': 'Reconnecting', 'device.liveness.offline': 'Offline', + // exit-signal contract — manner-of-death annotation on Offline (reliability-aware, §10) + 'device.exit.crashed': 'crashed', + 'device.exit.clean': 'clean exit', + 'device.exit.clean_besteffort': 'clean exit (best-effort)', + 'device.exit.silent': 'silent (no signal)', + 'device.exit.silent_short': 'silent', + // filter drill-in options (sub-dimension of Offline) + 'dashboard.filter.offline_silent': 'Offline · silent', + 'dashboard.filter.offline_crashed': 'Offline · crashed', + 'dashboard.filter.offline_clean': 'Offline · clean exit', + 'dashboard.filter.offline_by_reason': 'Offline by reason', + // honest hover explanations (carry the contract's reliability) + 'device.exit.crashed.tip': 'The app’s own error handler fired — it crashed before dying (our fault).', + 'device.exit.clean.tip': 'An orderly shutdown signal fired — something closed the app cleanly.', + 'device.exit.clean_besteffort.tip': 'Reported an orderly shutdown, but this platform’s signal is best-effort — likely, not certain.', + 'device.exit.silent.tip': 'No exit signal arrived — external or violent termination: power loss, network drop, force-stop, or MDM/kill. The honest catch-all.', // Info cards 'device.info.status': 'Status', 'device.info.ip_address': 'IP Address', diff --git a/frontend/js/utils.js b/frontend/js/utils.js index 2a00f25..29dbdf1 100644 --- a/frontend/js/utils.js +++ b/frontend/js/utils.js @@ -27,9 +27,40 @@ export function livenessState(data) { if (st === 'offline') return 'offline'; return 'offline'; // unknown / no data yet -> safe default, never blank } -export function livenessBadge(data) { +// Exit-signal contract §8/§10 — honest, reliability-aware manner-of-death sub-label for an Offline +// device. clean_exit is RELIABLE only on the browser /player (pagehide+sendBeacon); best-effort on +// APK/.wgt, so we qualify it there rather than overstate certainty. crashed/silent are labeled plainly. +// Returns null when no reason is known (old data / never went offline) -> plain "Offline". +// short=true -> concise LIST label (drops the parenthetical qualifiers, which the tooltip still carries); +// full (default) -> DETAIL label with the reliability qualifier. Honesty is preserved either way: the +// full meaning lives in the tooltip (both views) and in the detail label. +function offlineReasonLabel(reason, clientType, short) { + if (reason === 'crashed') return t('device.exit.crashed'); + if (reason === 'clean_exit') { + if (short) return t('device.exit.clean'); // list: "clean exit" (tooltip carries best-effort) + return clientType === 'player' ? t('device.exit.clean') : t('device.exit.clean_besteffort'); + } + if (reason === 'silent') return short ? t('device.exit.silent_short') : t('device.exit.silent'); + return null; +} +// Honest hover explanation of the manner of death — carries the contract's reliability (esp. 'silent' +// = external/violent, and best-effort clean_exit) so an operator isn't misled by a terse badge label. +function offlineReasonTip(reason, clientType) { + if (reason === 'crashed') return t('device.exit.crashed.tip'); + if (reason === 'clean_exit') return clientType === 'player' ? t('device.exit.clean.tip') : t('device.exit.clean_besteffort.tip'); + if (reason === 'silent') return t('device.exit.silent.tip'); + return ''; +} +export function livenessBadge(data, opts = {}) { const state = livenessState(data); - return { state, label: t(LIVENESS_LABEL_KEY[state]) }; + let label = t(LIVENESS_LABEL_KEY[state]); + let title = '', reason = ''; + if (state === 'offline') { // annotate Offline with the manner of death, if known + const r = data && data.offline_reason, ct = data && data.client_type; + const sub = offlineReasonLabel(r, ct, opts.short); + if (sub) { label += ' · ' + sub; title = offlineReasonTip(r, ct); reason = r || ''; } + } + return { state, label, title, reason }; // reason -> data-offline-reason (filter drill-in); '' unless offline+known } // Phase 2.1: the Phase 1 schema migration renamed the legacy 'superadmin' diff --git a/frontend/js/views/dashboard.js b/frontend/js/views/dashboard.js index 8f811eb..596c3bc 100644 --- a/frontend/js/views/dashboard.js +++ b/frontend/js/views/dashboard.js @@ -101,7 +101,7 @@ function renderDeviceCard(device) {
` }
- ${(() => { const b = livenessBadge(device); return `${esc(b.label)}`; })()} + ${(() => { const b = livenessBadge(device, { short: true }); return `${esc(b.label)}`; })()}
${device.status === 'provisioning' && device.pairing_code ? `
@@ -268,11 +268,16 @@ export function render(container) {
- + + + + +
@@ -295,12 +300,17 @@ export function render(container) { // Compare against the liveness STATE ('healthy'|'degraded'|'offline'), NOT the display label: // the badge text is now "Healthy"/"Reconnecting"/"Offline", so the old text-vs-'online' compare // matched nothing and emptied the list. data-liveness carries the state for a robust match. - const state = document.getElementById('deviceFilter').value; + const filter = document.getElementById('deviceFilter').value; // '' | healthy | degraded | offline | offline: + const reasonDrill = filter.startsWith('offline:') ? filter.slice(8) : null; // drill into a manner-of-death document.querySelectorAll('.device-card').forEach(card => { const name = card.querySelector('.device-card-name')?.textContent.toLowerCase() || ''; - const cardState = card.querySelector('.device-card-status [data-liveness]')?.dataset.liveness || ''; + const el = card.querySelector('.device-card-status [data-liveness]'); + const cardState = el?.dataset.liveness || ''; + const cardReason = el?.dataset.offlineReason || ''; const matchSearch = !search || name.includes(search); - const matchState = !state || cardState === state; + const matchState = reasonDrill + ? (cardState === 'offline' && cardReason === reasonDrill) // Offline drill-in: liveness AND reason (e.g. silent = MDM-killed set) + : (!filter || cardState === filter); // existing three-state filter — unchanged card.style.display = (matchSearch && matchState) ? '' : 'none'; }); } @@ -362,11 +372,11 @@ export function render(container) { // Real-time updates statusHandler = (data) => { - const b = livenessBadge(data); // v4: prefer data.liveness (3-state), fall back to binary status + const b = livenessBadge(data, { short: true }); // list = concise label; tooltip carries the full text const cards = document.querySelectorAll(`[data-device-id="${data.device_id}"]`); cards.forEach(card => { const statusEl = card.querySelector('.device-card-status'); - if (statusEl) statusEl.innerHTML = `${esc(b.label)}`; + if (statusEl) statusEl.innerHTML = `${esc(b.label)}`; }); }; diff --git a/frontend/js/views/device-detail.js b/frontend/js/views/device-detail.js index cf8bb10..a505c4a 100644 --- a/frontend/js/views/device-detail.js +++ b/frontend/js/views/device-detail.js @@ -71,6 +71,7 @@ export function render(container, deviceId) { const b = livenessBadge(data); // v4: 3-state liveness when present, else binary status badge.className = `device-status-badge ${b.state}`; badge.textContent = b.label; + badge.title = b.title || ''; // exit-reason hover (empty for non-offline / no-reason) } if (data.telemetry) updateTelemetryDisplay(data.telemetry); }; @@ -150,7 +151,7 @@ async function loadDevice(deviceId, activeTab = null) {

${device.name}

- ${(() => { const b = livenessBadge(device); return `${esc(b.label)}`; })()} + ${(() => { const b = livenessBadge(device); return `${esc(b.label)}`; })()} ${device.owner_name || device.owner_email ? `${t('device.owner_label', { owner: device.owner_name || device.owner_email })}` : ''}
From dfd954d2ad928df0b996f21b62539d1c776b0c0f Mon Sep 17 00:00:00 2001 From: ScreenTinker Date: Wed, 8 Jul 2026 17:22:44 -0500 Subject: [PATCH 16/20] chore(release): v1.9.3 --- VERSION | 2 +- android/app/build.gradle.kts | 4 ++-- server/package-lock.json | 4 ++-- server/package.json | 2 +- tizen/config.xml | 2 +- 5 files changed, 7 insertions(+), 7 deletions(-) diff --git a/VERSION b/VERSION index 55732de..77fee73 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.9.2-patch3 +1.9.3 diff --git a/android/app/build.gradle.kts b/android/app/build.gradle.kts index 41b2f3a..ea78d39 100644 --- a/android/app/build.gradle.kts +++ b/android/app/build.gradle.kts @@ -11,8 +11,8 @@ android { applicationId = "com.remotedisplay.player" minSdk = 24 targetSdk = 34 - versionCode = 41 - versionName = "1.9.2-patch3" + versionCode = 43 + versionName = "1.9.3" } signingConfigs { diff --git a/server/package-lock.json b/server/package-lock.json index 223cf15..cf906f1 100644 --- a/server/package-lock.json +++ b/server/package-lock.json @@ -1,12 +1,12 @@ { "name": "screentinker", - "version": "1.9.2-patch3", + "version": "1.9.3", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "screentinker", - "version": "1.9.2-patch3", + "version": "1.9.3", "dependencies": { "@azure/msal-node": "^5.2.1", "archiver": "^7.0.1", diff --git a/server/package.json b/server/package.json index 18f182e..4f6acad 100644 --- a/server/package.json +++ b/server/package.json @@ -1,6 +1,6 @@ { "name": "screentinker", - "version": "1.9.2-patch3", + "version": "1.9.3", "description": "ScreenTinker - Digital Signage Management Server", "main": "server.js", "scripts": { diff --git a/tizen/config.xml b/tizen/config.xml index b4ee4bd..100604b 100644 --- a/tizen/config.xml +++ b/tizen/config.xml @@ -1,6 +1,6 @@ + id="http://screentinker.com/player" version="1.9.3" viewmodes="maximized"> ScreenTinker From 09e11397b4bfa50b06bdd80fc5dbd162ce0a21a9 Mon Sep 17 00:00:00 2001 From: ScreenTinker Date: Wed, 8 Jul 2026 17:31:27 -0500 Subject: [PATCH 17/20] test: widen CI-fragile event-loop-gap timing bars (flaky prune/storm asserts) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CI flaked on the 300k-row prune non-blocking assert: a healthy chunked prune hit a 417ms max event-loop gap on a shared runner, over the strict 250ms bar (the same test passed on the prior commit; the release bump changed no logic). These probes exist to catch a MULTI-SECOND freeze (the pre-fix whole-table sort froze 40-48s) — not to enforce a sub-300ms latency SLA — so a strict bar is fragile under runner contention/GC. Widen both to <1500ms: still << "seconds" (catches any real regression) but robust on CI. No production code changed. Co-Authored-By: Claude Opus 4.8 (1M context) --- server/test/status-log-prune-hardening.test.js | 9 ++++++--- server/test/storm-harness.test.js | 6 ++++-- 2 files changed, 10 insertions(+), 5 deletions(-) diff --git a/server/test/status-log-prune-hardening.test.js b/server/test/status-log-prune-hardening.test.js index 53a1f0d..01cc449 100644 --- a/server/test/status-log-prune-hardening.test.js +++ b/server/test/status-log-prune-hardening.test.js @@ -55,8 +55,11 @@ test('non-blocking: 300k-row single-device backlog trims in many batches, loop s assert.equal(count('flapper'), 300000, 'seeded 300k'); // Event-loop responsiveness probe: a 10ms ticker; the max gap between ticks is the - // worst synchronous block during the prune. A single unbatched DELETE would freeze - // it for seconds; chunked+yield keeps every gap small. + // worst synchronous block during the prune. A single unbatched DELETE of 300k rows would + // freeze it for SECONDS; chunked+yield keeps every gap well under a second. The bar is set to + // catch that multi-second freeze while tolerating shared-CI-runner noise (a strict sub-300ms + // bar flakes under runner contention/GC — the intent is "not a seconds-long freeze", not a + // fixed-latency SLA). let maxGap = 0, last = Date.now(); const ticker = setInterval(() => { const n = Date.now(); maxGap = Math.max(maxGap, n - last); last = n; }, 10); @@ -65,7 +68,7 @@ test('non-blocking: 300k-row single-device backlog trims in many batches, loop s assert.equal(count('flapper'), 500, 'trimmed to the cap'); assert.ok(deleted >= 299000, `deleted the backlog (${deleted})`); - assert.ok(maxGap < 250, `no long freeze — max event-loop gap ${maxGap}ms (would be seconds if unbatched)`); + assert.ok(maxGap < 1500, `no seconds-long freeze — max event-loop gap ${maxGap}ms (an unbatched 300k DELETE would be multiple seconds)`); }); test('band-gate: interval run is a no-op when loaded; startup/normal runs', async () => { diff --git a/server/test/storm-harness.test.js b/server/test/storm-harness.test.js index ce9855c..2a6a407 100644 --- a/server/test/storm-harness.test.js +++ b/server/test/storm-harness.test.js @@ -64,8 +64,10 @@ test('storm: bloated-table sweep + flapper + OTA flood — loop stays responsive clearInterval(ticker); // 1) THE REAL INVARIANT — NO multi-second freeze. The old whole-table sort would - // freeze the ticker for tens of seconds here. - assert.ok(maxGap < 300, `loop never froze — max event-loop gap ${maxGap}ms (was 40-48s pre-fix)`); + // freeze the ticker for tens of seconds here (40-48s). The bar catches that while + // tolerating shared-CI-runner noise — the intent is "not seconds", not a sub-300ms SLA + // (a strict bar flakes under runner contention/GC, e.g. an observed 417ms on a healthy prune). + assert.ok(maxGap < 1500, `loop never froze — max event-loop gap ${maxGap}ms (was 40-48s pre-fix)`); // #146 P3.9: the exact tick count is environment-timing-sensitive; assert only that // the ticker sampled enough to have MEASURED a real gap (>=2), not a brittle count. assert.ok(ticks >= 2, `ticker sampled the run (${ticks} ticks) — max-gap measurement is meaningful`); From 147ab6d3c8517d0343e9e0fa824ca0bdc3a96e6b Mon Sep 17 00:00:00 2001 From: ScreenTinker Date: Wed, 8 Jul 2026 23:21:26 -0500 Subject: [PATCH 18/20] fix(ota): treat legacy -patchN as a released version so the old fleet is offered updates MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The -patchN scheme (e.g. 1.9.2-patch3) parses as a semver prerelease, so decide()'s superseded-prerelease guard refused to offer a newer stable core (1.9.3) to the existing fleet — stranding every 1.9.2-patchN device on OTA (Force Update didn't help; the re-check re-returned superseded-prerelease). isReleased() now counts -patchN as a shipped release, so those devices get offered 1.9.3 via normal OTA, while GENUINE prereleases (-beta/-rc/-alpha) keep prerelease semantics and newer cores are never downgraded. 6 new tests + 14 existing OTA tests green (388/388 suite). Co-Authored-By: Claude Opus 4.8 (1M context) --- server/lib/ota-breaker.js | 9 +++- server/test/ota-breaker-patchn.test.js | 58 ++++++++++++++++++++++++++ 2 files changed, 66 insertions(+), 1 deletion(-) create mode 100644 server/test/ota-breaker-patchn.test.js diff --git a/server/lib/ota-breaker.js b/server/lib/ota-breaker.js index 07245e0..c52bffd 100644 --- a/server/lib/ota-breaker.js +++ b/server/lib/ota-breaker.js @@ -59,6 +59,13 @@ function cmpParsed(a, b) { } function cmp(a, b) { const pa = parseVer(a), pb = parseVer(b); return (!pa || !pb) ? null : cmpParsed(pa, pb); } +// A '-patchN' suffix (e.g. 1.9.2-patch3) was the LEGACY release scheme — a shipped PRODUCTION patch, +// not a prerelease. Semver parses it into `pre`, but for OTA it must count as RELEASED so the +// superseded-prerelease guard below doesn't strand the old fleet: a 1.9.2-patchN device must still be +// offered a newer stable core (1.9.3). Genuine prereleases (-beta/-rc/-alpha) keep prerelease +// semantics. (Clean semver going forward emits no -patchN, so this only matters for the transition.) +function isReleased(p) { return p.pre === null || /^patch\d+$/i.test(p.pre); } + // decide(clientVersion, latestVersion, deviceId?, now?) -> // { update_available, reason, retry_after_seconds?, log? } function decide(clientVersion, latestVersion, deviceId = null, now = Date.now()) { @@ -69,7 +76,7 @@ function decide(clientVersion, latestVersion, deviceId = null, now = Date.now()) const full = cmpParsed(pc, pl); if (full === 0) return { update_available: false, reason: 'up-to-date' }; if (full > 0) return { update_available: false, reason: 'client-newer' }; // never offer a downgrade - if (pc.pre !== null && coreCmp(pc, pl) < 0) { // superseded old-core prerelease (e.g. 1.9.1-beta4) + if (!isReleased(pc) && coreCmp(pc, pl) < 0) { // GENUINE superseded old-core prerelease (e.g. 1.9.1-beta4) — a -patchN release is NOT one, so it still gets offered return { update_available: false, reason: 'superseded-prerelease', log: logOnce(clientVersion, `[ota] superseded prerelease '${clientVersion}' (older core than latest=${latestVersion}) — no offer`) }; } diff --git a/server/test/ota-breaker-patchn.test.js b/server/test/ota-breaker-patchn.test.js new file mode 100644 index 0000000..1ff4cab --- /dev/null +++ b/server/test/ota-breaker-patchn.test.js @@ -0,0 +1,58 @@ +// OTA breaker — the -patchN transition. The legacy '-patchN' release scheme (e.g. 1.9.2-patch3) parses +// as a semver prerelease, which made the superseded-prerelease guard STRAND the old fleet: with clean +// 1.9.3 as latest, a 1.9.2-patchN device was refused the update. isReleased() now treats -patchN as a +// shipped release so it's offered, while GENUINE prereleases (-beta/-rc/-alpha) keep prerelease semantics. +const { test } = require('node:test'); +const assert = require('node:assert/strict'); +const ota = require('../lib/ota-breaker'); +const LATEST = '1.9.3'; // the clean-semver release +const T = 1_000_000; + +test('-patchN fleet is OFFERED the newer stable (the transition fix)', () => { + ota.reset(); + for (const v of ['1.9.2-patch3', '1.9.2-patch4', '1.9.1-patch2', '1.9.2-PATCH3' /* case-insensitive */]) { + const d = ota.decide(v, LATEST, null, T); + assert.equal(d.update_available, true, `${v} -> 1.9.3 should be offered (was 'superseded-prerelease')`); + assert.equal(d.reason, 'offer'); + } +}); + +test('GENUINE older-core prereleases are STILL superseded (no offer) — unchanged', () => { + ota.reset(); + for (const v of ['1.9.1-beta4', '1.9.2-beta6', '1.9.0-rc1', '1.8.5-alpha2']) { + const d = ota.decide(v, LATEST, null, T); + assert.equal(d.update_available, false, `${v} is a genuine prerelease of an older core -> no offer`); + assert.equal(d.reason, 'superseded-prerelease'); + } +}); + +test('clean older releases still offered; equal is up-to-date; newer never downgraded', () => { + ota.reset(); + assert.equal(ota.decide('1.9.2', LATEST, null, T).reason, 'offer', 'clean 1.9.2 -> offered'); + assert.equal(ota.decide('1.9.1', LATEST, null, T).reason, 'offer', 'clean 1.9.1 -> offered'); + assert.equal(ota.decide('1.7.12', LATEST, null, T).reason, 'offer', 'old clean release -> offered'); + assert.equal(ota.decide('1.9.3', LATEST, null, T).reason, 'up-to-date'); + assert.equal(ota.decide('1.9.4', LATEST, null, T).reason, 'client-newer', 'never downgrade a newer core'); +}); + +test('a prerelease of a HIGHER core is client-newer, not offered (e.g. a 1.9.4-beta1 tester)', () => { + ota.reset(); + assert.equal(ota.decide('1.9.4-beta1', LATEST, null, T).reason, 'client-newer'); + // and a -patchN of a higher core is likewise newer (never a downgrade) + assert.equal(ota.decide('1.9.4-patch1', LATEST, null, T).reason, 'client-newer'); +}); + +test('regression: unrecognized/garbage still refused; the fix did not loosen the phantom guard', () => { + ota.reset(); + assert.equal(ota.decide('banana', LATEST, null, T).reason, 'unrecognized-version'); + assert.equal(ota.decide('', LATEST, null, T).reason, 'no-version'); +}); + +test('regression: with a PRERELEASE server (beta4 latest), superseded-prerelease still fires for older betas', () => { + ota.reset(); + // mirrors the existing ota-breaker.test.js scenario — a -patchN client change must not disturb it + const d = ota.decide('1.9.1-beta4', '1.9.2-beta4', null, T); + assert.equal(d.reason, 'superseded-prerelease'); + // a same-core older beta against a beta server is offerable (rate path), unchanged + assert.equal(ota.decide('1.9.2-beta3', '1.9.2-beta4', null, T).reason, 'offer'); +}); From 90b8cbb1e6b5800fd84950228727f7031d7872cb Mon Sep 17 00:00:00 2001 From: Fabian Mendoza Date: Thu, 9 Jul 2026 16:39:07 -0400 Subject: [PATCH 19/20] fix(preview): server-side preview sessions to bypass CSP (#151) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * fix(preview): replace srcdoc with server-side preview sessions to bypass CSP Widget previews (clock, weather, etc.) were rendered via iframe.srcdoc, which inherits the dashboard CSP script-src 'self'. This blocked the inline scripts widgets need (setInterval for clock, fetch for weather), causing previews to show blank/static content. Replace srcdoc with ephemeral server-side preview sessions: - POST /api/widgets/preview-session — stores rendered HTML (Map, 5min TTL) - GET /api/widgets/preview-session/:id — serves the HTML via iframe src, bypassing CSP like the device render endpoint already does The old /api/widgets/preview endpoint is unchanged for backward compat. * fix(preview): add rate limiter for /preview-session route --------- Co-authored-by: BlazzzPlay --- frontend/js/views/widgets.js | 15 +++++---------- server/routes/widgets.js | 36 ++++++++++++++++++++++++++++++++++++ server/server.js | 3 +++ 3 files changed, 44 insertions(+), 10 deletions(-) diff --git a/frontend/js/views/widgets.js b/frontend/js/views/widgets.js index 60dfa49..06cf613 100644 --- a/frontend/js/views/widgets.js +++ b/frontend/js/views/widgets.js @@ -105,7 +105,7 @@ function openContentPicker({ multiple = false, title } = {}) { }); } -function showPreviewModal(html, widgetType) { +function showPreviewModal(sessionId, widgetType) { const overlay = document.createElement('div'); overlay.style.cssText = 'position:fixed;inset:0;background:rgba(0,0,0,0.85);display:flex;align-items:center;justify-content:center;z-index:10000;padding:16px'; // #104: webpage widgets pointing at frame-denying sites (X-Frame-Options) can't be @@ -124,12 +124,7 @@ function showPreviewModal(html, widgetType) { ${webpageNote}
`; document.body.appendChild(overlay); - // srcdoc resolves relative URLs against about:srcdoc, so inject pointing to our origin - const baseTag = ``; - const withBase = /]*>/i.test(html) - ? html.replace(/]*)>/i, `${baseTag}`) - : html.replace(/]*)>/i, `${baseTag}`); - overlay.querySelector('#pvIframe').srcdoc = withBase; + overlay.querySelector('#pvIframe').src = '/api/widgets/preview-session/' + sessionId; const close = () => overlay.remove(); overlay.querySelector('#pvClose').onclick = close; overlay.onclick = (e) => { if (e.target === overlay) close(); }; @@ -551,14 +546,14 @@ export async function render(container) { if (!type) return; const config = getConfigFromForm(type); try { - const res = await fetch('/api/widgets/preview', { + const res = await fetch('/api/widgets/preview-session', { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${localStorage.getItem('token')}` }, body: JSON.stringify({ widget_type: type, config }), }); if (!res.ok) throw new Error(t('widget.toast.preview_failed')); - const html = await res.text(); - showPreviewModal(html, type); + const { id } = await res.json(); + showPreviewModal(id, type); } catch (err) { showToast(err.message, 'error'); } }; diff --git a/server/routes/widgets.js b/server/routes/widgets.js index a854b03..7212b15 100644 --- a/server/routes/widgets.js +++ b/server/routes/widgets.js @@ -212,6 +212,42 @@ router.post('/preview', (req, res) => { res.send(html); }); +// Preview sessions — ephemeral store so the preview iframe loads via src (not srcdoc) +// and bypasses the dashboard CSP that would block the widget's inline scripts. +const previewStore = new Map(); +const PREVIEW_TTL = 5 * 60 * 1000; +setInterval(() => { + const now = Date.now(); + for (const [key, entry] of previewStore) { + if (now - entry.created > PREVIEW_TTL) previewStore.delete(key); + } +}, 60 * 1000).unref(); + +router.post('/preview-session', (req, res) => { + const { widget_type, config } = req.body || {}; + if (!widget_type || typeof widget_type !== 'string') return res.status(400).json({ error: 'widget_type required' }); + if (!KNOWN_WIDGET_TYPES.has(widget_type)) return res.status(400).json({ error: 'Unknown widget_type' }); + const id = uuidv4(); + const html = renderWidgetHtml(widget_type, config || {}); + previewStore.set(id, { html, widget_type, created: Date.now() }); + res.json({ id, url: `/api/widgets/preview-session/${id}` }); +}); + +router.get('/preview-session/:id', (req, res) => { + const entry = previewStore.get(req.params.id); + if (!entry) return res.status(410).send('Preview expired'); + if (Date.now() - entry.created > PREVIEW_TTL) { + previewStore.delete(req.params.id); + return res.status(410).send('Preview expired'); + } + let html = entry.html; + if (req.workspaceId) html = inlineUserContent(html, req.workspaceId); + res.removeHeader('X-Frame-Options'); + res.setHeader('Cache-Control', 'no-store'); + res.setHeader('Content-Type', 'text/html'); + res.send(html); +}); + function renderClock(c) { return `