From 8341fdf8466ba236270faeb4ed1aeb91ed10b502 Mon Sep 17 00:00:00 2001 From: Greg Darke Date: Fri, 12 Sep 2025 12:14:43 +1000 Subject: [PATCH 1/4] Add wakelock support Add a new configuration option `keep_device_awake` to allow noVNC to stop the local display from going to sleep. This is especially useful with view-only sessions. This new option has been added to the configuration UI, making it easier for users to configure. When this option is changed at runtime, we will request/release the wake lock. We only hold the view lock while connected to a server. We will also attempt to reacquire the wakelock if we lost it due to a visibility change (the tab becoming inactive, or during the transition into/from fullscreen). All existing unittests have been run, and the change has been manually tested in Firefox 145. Additional tests will be added later. --- app/ui.js | 21 ++++++ app/wakelock.js | 178 ++++++++++++++++++++++++++++++++++++++++++++++ docs/EMBEDDING.md | 4 ++ vnc.html | 7 ++ 4 files changed, 210 insertions(+) create mode 100644 app/wakelock.js diff --git a/app/ui.js b/app/ui.js index bbdea60d..cc435efe 100644 --- a/app/ui.js +++ b/app/ui.js @@ -16,6 +16,7 @@ import KeyTable from "../core/input/keysym.js"; import keysyms from "../core/input/keysymdef.js"; import Keyboard from "../core/input/keyboard.js"; import RFB from "../core/rfb.js"; +import WakeLockManager from './wakelock.js'; import * as WebUtil from "./webutil.js"; const PAGE_TITLE = "noVNC"; @@ -46,6 +47,8 @@ const UI = { reconnectCallback: null, reconnectPassword: null, + wakeLockManager: new WakeLockManager(), + async start(options={}) { UI.customSettings = options.settings || {}; if (UI.customSettings.defaults === undefined) { @@ -189,6 +192,7 @@ const UI = { UI.initSetting('repeaterID', ''); UI.initSetting('reconnect', false); UI.initSetting('reconnect_delay', 5000); + UI.initSetting('keep_device_awake', false); }, // Adds a link to the label elements on the corresponding input elements setupSettingLabels() { @@ -371,6 +375,8 @@ const UI = { UI.addSettingChangeHandler('view_only', UI.updateViewOnly); UI.addSettingChangeHandler('show_dot'); UI.addSettingChangeHandler('show_dot', UI.updateShowDotCursor); + UI.addSettingChangeHandler('keep_device_awake'); + UI.addSettingChangeHandler('keep_device_awake', UI.updateRequestWakelock); UI.addSettingChangeHandler('host'); UI.addSettingChangeHandler('port'); UI.addSettingChangeHandler('path'); @@ -1072,6 +1078,10 @@ const UI = { url.protocol = (window.location.protocol === "https:") ? 'wss:' : 'ws:'; } + if (UI.getSetting('keep_device_awake')) { + UI.wakeLockManager.acquire(); + } + try { UI.rfb = new RFB(document.getElementById('noVNC_container'), url.href, @@ -1171,6 +1181,7 @@ const UI = { UI.connected = false; UI.rfb = undefined; + UI.wakeLockManager.release(); if (!e.detail.clean) { UI.updateVisualState('disconnected'); @@ -1819,6 +1830,16 @@ const UI = { document.title = e.detail.name + " - " + PAGE_TITLE; }, + updateRequestWakelock() { + if (!UI.rfb) return; + if (UI.getSetting('keep_device_awake')) { + UI.wakeLockManager.acquire(); + } else { + UI.wakeLockManager.release(); + } + }, + + bell(e) { if (UI.getSetting('bell') === 'on') { const promise = document.getElementById('noVNC_bell').play(); diff --git a/app/wakelock.js b/app/wakelock.js new file mode 100644 index 00000000..1dce96c7 --- /dev/null +++ b/app/wakelock.js @@ -0,0 +1,178 @@ +/* + * noVNC: HTML5 VNC client + * Copyright (C) 2025 The noVNC authors + * Licensed under MPL 2.0 or any later version (see LICENSE.txt) + * + * Wrapper around the `navigator.wakeLock` api that handles reacquiring the + * lock on visiblility changes. + * + * The `acquire` and `release` methods may be called any number of times. The + * most recent call dictates the desired end-state (if `acquire` was most + * recently called, then we will try to acquire and hold the wake lock). + */ + +import * as Log from '../core/util/logging.js'; + +const _STATES = { + /* No wake lock. + * + * Can transition to: + * - AWAITING_VISIBLE: `acquire` called when document is hidden. + * - ACQUIRING: `acquire` called. + * - RELEASED: `acquired` called when the api is not available. + */ + RELEASED: 'released', + /* Wake lock requested, waiting for browser. + * + * Can transition to: + * - ACQUIRED: success + * - ACQUIRING_WANT_RELEASE: `release` called while waiting + * - RELEASED: On error + */ + ACQUIRING: 'acquiring', + /* Wake lock requested, release called, still waiting for browser. + * + * Can transition to: + * - ACQUIRING: `acquire` called (but promise has not resolved yet) + * - RELEASED: success + */ + ACQUIRING_WANT_RELEASE: 'releasing', + /* Wake lock held. + * + * Can transition to: + * - AWAITING_VISIBLE: wakelock lost due to visibility change + * - RELEASED: success + */ + ACQUIRED: 'acquired', + /* Caller wants wakelock, but we can not get it due to visibility. + * + * Can transition to: + * - ACQUIRING: document is now visible, attempting to get wakelock. + * - RELEASED: when release is called. + */ + AWAITING_VISIBLE: 'awaiting_visible', +}; + +export default class WakeLockManager { + constructor() { + this._state = _STATES.RELEASED; + this._wakelock = null; + + this._eventHandlers = { + wakelockAcquired: this._wakelockAcquired.bind(this), + wakelockReleased: this._wakelockReleased.bind(this), + documentVisibilityChange: this._documentVisibilityChange.bind(this), + }; + } + + acquire() { + switch (this._state) { + case _STATES.ACQUIRING_WANT_RELEASE: + // We are currently waiting to acquire the wakelock. While + // waiting, `release()` was called. By transitioning back to + // ACQUIRING, we will keep the lock after we receive it. + this._transitionTo(_STATES.ACQUIRING); + break; + case _STATES.AWAITING_VISIBLE: + case _STATES.ACQUIRING: + case _STATES.ACQUIRED: + break; + case _STATES.RELEASED: + if (document.hidden) { + // We can not acquire the wakelock while the document is + // hidden (eg, not the active tab). Wait until it is + // visible, then acquire the wakelock. + this._awaitVisible(); + break; + } + this._acquireWakelockNow(); + break; + } + } + + release() { + switch (this._state) { + case _STATES.RELEASED: + case _STATES.ACQUIRING_WANT_RELEASE: + break; + case _STATES.ACQUIRING: + // We are have requested (but not yet received) the wakelock. + // Give it up as soon as we acquire it. + this._transitionTo(_STATES.ACQUIRING_WANT_RELEASE); + break; + case _STATES.ACQUIRED: + // We remove the event listener first, as we don't want to be + // notified about this release (it is expected). + this._wakelock.removeEventListener("release", this._eventHandlers.wakelockReleased); + this._wakelock.release(); + this._wakelock = null; + this._transitionTo(_STATES.RELEASED); + break; + case _STATES.AWAITING_VISIBLE: + // We don't currently have the lock, but are waiting for the + // document to become visible. By removing the event listener, + // we will not attempt to get the wakelock in the future. + document.removeEventListener("visibilitychange", this._eventHandlers.documentVisibilityChange); + this._transitionTo(_STATES.RELEASED); + break; + } + } + + _transitionTo(newState) { + let oldState = this._state; + Log.Debug(`WakelockManager transitioning ${oldState} -> ${newState}`); + this._state = newState; + } + + _awaitVisible() { + document.addEventListener("visibilitychange", this._eventHandlers.documentVisibilityChange); + this._transitionTo(_STATES.AWAITING_VISIBLE); + } + + _acquireWakelockNow() { + if (!("wakeLock" in navigator)) { + Log.Warn("Unable to request wakeLock, Browser does not have wakeLock api"); + this._transitionTo(_STATES.RELEASED); + return; + } + navigator.wakeLock.request("screen") + .then(this._eventHandlers.wakelockAcquired) + .catch((err) => { + Log.Warn("Error occurred while acquiring wakelock: " + err); + this._transitionTo(_STATES.RELEASED); + }); + this._transitionTo(_STATES.ACQUIRING); + } + + + _wakelockAcquired(wakelock) { + if (this._state === _STATES.ACQUIRING_WANT_RELEASE) { + // We were requested to release the wakelock while we were trying to + // acquire it. Now that we have acquired it, immediatly release it. + wakelock.release(); + this._transitionTo(_STATES.RELEASED); + return; + } + this._wakelock = wakelock; + this._wakelock.addEventListener("release", this._eventHandlers.wakelockReleased); + this._transitionTo(_STATES.ACQUIRED); + } + + _wakelockReleased(event) { + this._wakelock = null; + if (document.visibilityState === "visible") { + Log.Warn("Lost wakelock, but document is still visible. Not reacquiring"); + this._transitionTo(_STATES.RELEASED); + return; + } + this._awaitVisible(); + } + + _documentVisibilityChange(event) { + if (document.visibilityState !== "visible") { + return; + } + document.removeEventListener("visibilitychange", this._eventHandlers.documentVisibilityChange); + this._acquireWakelockNow(); + } +} diff --git a/docs/EMBEDDING.md b/docs/EMBEDDING.md index 26bcce3f..3019218d 100644 --- a/docs/EMBEDDING.md +++ b/docs/EMBEDDING.md @@ -92,6 +92,10 @@ Currently, the following options are available: * `logging` - The console log level. Can be one of `error`, `warn`, `info` or `debug`. +* `keep_device_awake` - Should we prevent the (local) display from going into + sleep mode while a connection is active? Useful for view-only sessions where + there unlikely to be any keyboard/mouse activity to keep the device active. + ## HTTP serving considerations ### Browser cache issue diff --git a/vnc.html b/vnc.html index 82cacd58..c36a0f07 100644 --- a/vnc.html +++ b/vnc.html @@ -296,6 +296,13 @@ Show dot when no cursor +
  • + +
  • From 077c54f312e2bc5d85bc8ba40151676328e7db68 Mon Sep 17 00:00:00 2001 From: Greg Darke Date: Fri, 12 Sep 2025 12:18:22 +1000 Subject: [PATCH 2/4] Add error state for wakelock testing. Add an error state to the WakeLockManager state machine. This adds a transition that can be detected from tests (it otherwise serves no purpose, and the system immediatly transitions back into the released state). --- app/wakelock.js | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/app/wakelock.js b/app/wakelock.js index 1dce96c7..398f5f24 100644 --- a/app/wakelock.js +++ b/app/wakelock.js @@ -19,7 +19,7 @@ const _STATES = { * Can transition to: * - AWAITING_VISIBLE: `acquire` called when document is hidden. * - ACQUIRING: `acquire` called. - * - RELEASED: `acquired` called when the api is not available. + * - ERROR: `acquired` called when the api is not available. */ RELEASED: 'released', /* Wake lock requested, waiting for browser. @@ -27,7 +27,7 @@ const _STATES = { * Can transition to: * - ACQUIRED: success * - ACQUIRING_WANT_RELEASE: `release` called while waiting - * - RELEASED: On error + * - ERROR */ ACQUIRING: 'acquiring', /* Wake lock requested, release called, still waiting for browser. @@ -51,6 +51,12 @@ const _STATES = { * - RELEASED: when release is called. */ AWAITING_VISIBLE: 'awaiting_visible', + /* An error has occurred. + * + * Can transition to: + * - RELEASED: will happen immediately. + */ + ERROR: 'error', }; export default class WakeLockManager { @@ -77,6 +83,7 @@ export default class WakeLockManager { case _STATES.ACQUIRING: case _STATES.ACQUIRED: break; + case _STATES.ERROR: case _STATES.RELEASED: if (document.hidden) { // We can not acquire the wakelock while the document is @@ -92,6 +99,7 @@ export default class WakeLockManager { release() { switch (this._state) { + case _STATES.ERROR: case _STATES.RELEASED: case _STATES.ACQUIRING_WANT_RELEASE: break; @@ -132,6 +140,7 @@ export default class WakeLockManager { _acquireWakelockNow() { if (!("wakeLock" in navigator)) { Log.Warn("Unable to request wakeLock, Browser does not have wakeLock api"); + this._transitionTo(_STATES.ERROR); this._transitionTo(_STATES.RELEASED); return; } @@ -139,6 +148,7 @@ export default class WakeLockManager { .then(this._eventHandlers.wakelockAcquired) .catch((err) => { Log.Warn("Error occurred while acquiring wakelock: " + err); + this._transitionTo(_STATES.ERROR); this._transitionTo(_STATES.RELEASED); }); this._transitionTo(_STATES.ACQUIRING); @@ -148,7 +158,7 @@ export default class WakeLockManager { _wakelockAcquired(wakelock) { if (this._state === _STATES.ACQUIRING_WANT_RELEASE) { // We were requested to release the wakelock while we were trying to - // acquire it. Now that we have acquired it, immediatly release it. + // acquire it. Now that we have acquired it, immediately release it. wakelock.release(); this._transitionTo(_STATES.RELEASED); return; From f4f2f8d725700fa75a7af581164b0ae56fae5711 Mon Sep 17 00:00:00 2001 From: Greg Darke Date: Fri, 12 Sep 2025 16:01:49 +1000 Subject: [PATCH 3/4] Expose WakeLockManager state transitions for tests Dispatch an event on each state transition inside the WakeLockManager. This gives the unit tests something to synchronise on, allowing us to write fast, flake-free tests. --- app/wakelock.js | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/app/wakelock.js b/app/wakelock.js index 398f5f24..2eae408f 100644 --- a/app/wakelock.js +++ b/app/wakelock.js @@ -59,8 +59,18 @@ const _STATES = { ERROR: 'error', }; -export default class WakeLockManager { +class TestOnlyWakeLockManagerStateChangeEvent extends Event { + constructor(oldState, newState) { + super("testOnlyStateChange"); + this.oldState = oldState; + this.newState = newState; + } +} + +export default class WakeLockManager extends EventTarget { constructor() { + super(); + this._state = _STATES.RELEASED; this._wakelock = null; @@ -130,6 +140,7 @@ export default class WakeLockManager { let oldState = this._state; Log.Debug(`WakelockManager transitioning ${oldState} -> ${newState}`); this._state = newState; + this.dispatchEvent(new TestOnlyWakeLockManagerStateChangeEvent(oldState, newState)); } _awaitVisible() { From 988e9da7fa9f4161bfacd52a725879552949a083 Mon Sep 17 00:00:00 2001 From: Greg Darke Date: Fri, 12 Sep 2025 10:32:18 +1000 Subject: [PATCH 4/4] Add tests for the wakelock feature. Add tests to for both the `rfb` side (calling into the new wakelock code), and the new wakelock class (which tracks the desired state and how to get there). --- karma.conf.cjs | 1 + tests/test.wakelock.js | 197 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 198 insertions(+) create mode 100644 tests/test.wakelock.js diff --git a/karma.conf.cjs b/karma.conf.cjs index 54380ebd..7d6dbe1a 100644 --- a/karma.conf.cjs +++ b/karma.conf.cjs @@ -37,6 +37,7 @@ module.exports = (config) => { { pattern: 'node_modules/sinon-chai/**', included: false }, // modules to test { pattern: 'app/localization.js', included: false, type: 'module' }, + { pattern: 'app/wakelock.js', included: false, type: 'module' }, { pattern: 'app/webutil.js', included: false, type: 'module' }, { pattern: 'core/**/*.js', included: false, type: 'module' }, { pattern: 'vendor/pako/**/*.js', included: false, type: 'module' }, diff --git a/tests/test.wakelock.js b/tests/test.wakelock.js new file mode 100644 index 00000000..b6544e73 --- /dev/null +++ b/tests/test.wakelock.js @@ -0,0 +1,197 @@ +/* jshint expr: true */ + +import WakeLockManager from '../app/wakelock.js'; + +class FakeWakeLockSentinal extends EventTarget { + constructor() { + super(); + this.released = false; + } + + async release() { + if (this.released) { + return; + } + this.released = true; + this.dispatchEvent(new Event("release")); + } +} + +function waitForStateTransition(wakelockManager, newState) { + const {promise, resolve} = Promise.withResolvers(); + + const eventListener = (event) => { + if (event.newState !== newState) { + return; + } + wakelockManager.removeEventListener("testOnlyStateChange", eventListener); + resolve(); + }; + wakelockManager.addEventListener("testOnlyStateChange", eventListener); + + return promise; +} + +describe('WakeLockManager', function () { + "use strict"; + + let wakelockRequest; + beforeEach(function () { + wakelockRequest = sinon.stub(navigator.wakeLock, 'request'); + }); + afterEach(function () { + wakelockRequest.restore(); + }); + + it('can acquire and release lock', async function () { + let wakeLockSentinal = new FakeWakeLockSentinal(); + wakelockRequest.onFirstCall().resolves(wakeLockSentinal); + + let wlm = new WakeLockManager(); + expect(wakelockRequest).to.not.have.been.called; + + let done = waitForStateTransition(wlm, 'acquired'); + wlm.acquire(); + await done; + expect(wakelockRequest).to.have.been.calledOnce; + expect(wakeLockSentinal.released).to.be.false; + + done = waitForStateTransition(wlm, 'released'); + wlm.release(); + await done; + expect(wakelockRequest).to.have.been.calledOnce; + expect(wakeLockSentinal.released).to.be.true; + }); + + it('can release without holding wakelock', async function () { + let wlm = new WakeLockManager(); + wlm.release(); + expect(wakelockRequest).to.not.have.been.called; + }); + + it('can release while waiting for wakelock', async function () { + let wakeLockSentinal = new FakeWakeLockSentinal(); + let {promise, resolve} = Promise.withResolvers(); + + wakelockRequest.onFirstCall().returns(promise); + + let wlm = new WakeLockManager(); + expect(wakelockRequest).to.not.have.been.called; + + let seenAcquiring = waitForStateTransition(wlm, 'acquiring'); + let seenReleasing = waitForStateTransition(wlm, 'releasing'); + let seenReleased = waitForStateTransition(wlm, 'released'); + + wlm.acquire(); + await seenAcquiring; + expect(wakelockRequest).to.have.been.calledOnce; + + // We can call acquire multiple times, while waiting for the promise + // to resolve. + wlm.acquire(); + // It should not request a second wakelock. + expect(wakelockRequest).to.have.been.calledOnce; + + wlm.release(); + await seenReleasing; + + expect(wakeLockSentinal.released).to.be.false; + + // Now return the wake lock, we should immediately release it. + resolve(wakeLockSentinal); + await seenReleased; + expect(wakeLockSentinal.released).to.be.true; + }); + + it('handles visibility loss', async function () { + let documentHidden = sinon.stub(document, 'hidden'); + let documentVisibility = sinon.stub(document, 'visibilityState'); + afterEach(function () { + documentHidden.restore(); + documentVisibility.restore(); + }); + documentHidden.value(false); + documentVisibility.value('visible'); + + let wakeLockSentinal1 = new FakeWakeLockSentinal(); + let wakeLockSentinal2 = new FakeWakeLockSentinal(); + wakelockRequest.onFirstCall().resolves(wakeLockSentinal1); + wakelockRequest.onSecondCall().resolves(wakeLockSentinal2); + + let wlm = new WakeLockManager(); + let seenAcquired = waitForStateTransition(wlm, 'acquired'); + let seenAwaitingVisible = waitForStateTransition(wlm, 'awaiting_visible'); + + wlm.acquire(); + await seenAcquired; + expect(wakelockRequest).to.have.been.calledOnce; + + // Fake a visibility change. + documentHidden.value(true); + documentVisibility.value('hidden'); + wakeLockSentinal1.release(); + + await seenAwaitingVisible; + seenAcquired = waitForStateTransition(wlm, 'acquired'); + + // Fake a visibility change back + documentHidden.value(false); + documentVisibility.value('visible'); + document.dispatchEvent(new Event('visibilitychange')); + await seenAcquired; + + expect(wakelockRequest).to.have.been.calledTwice; + expect(wakeLockSentinal2.released).to.be.false; + }); + + it('can start hidden', async function () { + let documentHidden = sinon.stub(document, 'hidden'); + let documentVisibility = sinon.stub(document, 'visibilityState'); + afterEach(function () { + documentHidden.restore(); + documentVisibility.restore(); + }); + documentHidden.value(true); + documentVisibility.value('hidden'); + + let wakeLockSentinal = new FakeWakeLockSentinal(); + wakelockRequest.onFirstCall().resolves(wakeLockSentinal); + + let wlm = new WakeLockManager(); + let seenAwaitingVisible = waitForStateTransition(wlm, 'awaiting_visible'); + let seenAcquired = waitForStateTransition(wlm, 'acquired'); + + wlm.acquire(); + await seenAwaitingVisible; + expect(wakelockRequest).to.not.have.been.called; + + // Fake a visibility change. + documentHidden.value(false); + documentVisibility.value('visible'); + document.dispatchEvent(new Event('visibilitychange')); + await seenAcquired; + + expect(wakelockRequest).to.have.been.calledOnce; + expect(wakeLockSentinal.released).to.be.false; + }); + + it('handles acquire errors', async function () { + wakelockRequest.onFirstCall().rejects('WakeLockError'); + let wakeLockSentinal = new FakeWakeLockSentinal(); + wakelockRequest.onSecondCall().resolves(wakeLockSentinal); + + let wlm = new WakeLockManager(); + + let seenError = waitForStateTransition(wlm, 'error'); + wlm.acquire(); + await seenError; + expect(wakelockRequest).to.have.been.calledOnce; + + // Even though we saw an error previously, it will retry when + // requested. + let seenAcquired = waitForStateTransition(wlm, 'acquired'); + wlm.acquire(); + await seenAcquired; + expect(wakelockRequest).to.have.been.calledTwice; + }); +});