@livedesk/hub 0.1.51 → 0.1.53

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livedesk/hub",
-  "version": "0.1.51",
+  "version": "0.1.53",
   "description": "VuvoDesk local Hub API and browser frame bridge",
   "type": "module",
   "main": "src/server.js",

package/src/remote-hub.js

@@ -320,11 +320,14 @@ function serializeRemoteInputWrite(socket, payload) {
  * - Ordered transitions: keyboard and pointer-button events are never
  *   coalesced. If their bounded queue cannot retain order, the input socket is
  *   closed so the Agent releases native pressed state.
- * - High-rate input: only adjacent pointermove/mousemove/wheel samples from the
- *   same binding may replace an older queued sample.
- * - Bounds: one drain listener, one drain deadline, at most 16 userland items,
- *   32 KiB queued bytes, and 64 KiB socket writableLength.
- */
+ * - High-rate input: only adjacent pointermove/mousemove/wheel samples from the
+ *   same binding may replace an older queued sample.
+ * - Acknowledgement health: an acknowledged sample becomes a deadline
+ *   checkpoint only after that exact message is accepted by the socket write.
+ *   A sample replaced or dropped in the userland queue owns no timer.
+ * - Bounds: one drain listener, one drain deadline, at most 16 userland items,
+ *   32 KiB queued bytes, and 64 KiB socket writableLength.
+ */
 export function createBoundedRemoteInputWriter(options = {}) {
     const socket = options.socket;
     const connectionId = safeString(options.connectionId, 128);
@@ -357,9 +360,12 @@ export function createBoundedRemoteInputWriter(options = {}) {
     const isOwnerCurrent = typeof options.isOwnerCurrent === 'function'
         ? options.isOwnerCurrent
         : () => true;
-    const onFailClosed = typeof options.onFailClosed === 'function'
-        ? options.onFailClosed
-        : () => {};
+    const onFailClosed = typeof options.onFailClosed === 'function'
+        ? options.onFailClosed
+        : () => {};
+    const onAcknowledgedWrite = typeof options.onAcknowledgedWrite === 'function'
+        ? options.onAcknowledgedWrite
+        : () => {};
 
     let closed = false;
     let closeReason = '';
@@ -501,16 +507,23 @@ export function createBoundedRemoteInputWriter(options = {}) {
         if (writableLength() > maxWritableBytes) {
             return failClosed('input-writable-length-exceeded');
         }
-        if (writable === false && !armDrainOwner()) {
-            return {
-                ok: false,
-                error: closeReason || 'INPUT_CHANNEL_RECONNECTING',
-                failClosed: true
-            };
-        }
-        return {
-            ok: true,
-            queued: false,
+        if (writable === false && !armDrainOwner()) {
+            return {
+                ok: false,
+                error: closeReason || 'INPUT_CHANNEL_RECONNECTING',
+                failClosed: true
+            };
+        }
+        if (item.ackRequested) {
+            try {
+                onAcknowledgedWrite(item.payload, item.bindingKey);
+            } catch {
+                return failClosed('input-ack-write-observer-failed');
+            }
+        }
+        return {
+            ok: true,
+            queued: false,
             backpressured: writable === false
         };
     }
@@ -613,12 +626,14 @@ export function createBoundedRemoteInputWriter(options = {}) {
             return failClosed('input-transition-message-too-large');
         }
 
-        const item = {
-            payload,
-            bindingKey: normalizedBindingKey,
-            serialized,
-            coalescible
-        };
+        const item = {
+            payload,
+            bindingKey: normalizedBindingKey,
+            serialized,
+            coalescible,
+            ackRequested: payload?.payload?.requestAck === true
+                || payload?.requestAck === true
+        };
         if (blocked || queue.length > 0 || writableLength() >= maxWritableBytes) {
             const queued = queueItem(item);
             if (queued.ok && !blocked && !armDrainOwner()) {
@@ -4288,13 +4303,14 @@ export function createRemoteHub(options = {}) {
         }
     }
 
-    function closeInputSocket(device, reason = 'input-socket-closed') {
+    function closeInputSocket(device, reason = 'input-socket-closed') {
         const socket = device?.inputSocket;
         if (!socket) {
             return;
         }
 
-        const writeOwner = device.inputWriteOwner;
+        const writeOwner = device.inputWriteOwner;
+        clearPendingDedicatedInputAcks(device);
         clearClipboardOperationsForDevice(device, reason);
         device.inputSocket = null;
         device.inputWriteOwner = null;
@@ -4317,7 +4333,7 @@ export function createRemoteHub(options = {}) {
         }
     }
 
-    function detachInputSocket(socket, reason = 'input-socket-closed') {
+    function detachInputSocket(socket, reason = 'input-socket-closed') {
         const deviceId = inputSockets.get(socket);
         inputSockets.delete(socket);
         if (!deviceId) {
@@ -4329,7 +4345,8 @@ export function createRemoteHub(options = {}) {
             return;
         }
 
-        const writeOwner = device.inputWriteOwner;
+        const writeOwner = device.inputWriteOwner;
+        clearPendingDedicatedInputAcks(device);
         clearClipboardOperationsForDevice(device, reason);
         device.inputSocket = null;
         device.inputWriteOwner = null;
@@ -4948,7 +4965,8 @@ export function createRemoteHub(options = {}) {
             return null;
         }
 
-        closeInputSocket(device, 'replaced-by-new-input-socket');
+        closeInputSocket(device, 'replaced-by-new-input-socket');
+        clearPendingDedicatedInputAcks(device);
 
         const now = new Date().toISOString();
         const inputSocketConnectionId = crypto.randomUUID();
@@ -4979,22 +4997,38 @@ export function createRemoteHub(options = {}) {
                 && device.inputSocket === socket
                 && device.inputSocketConnectionId === inputSocketConnectionId
                 && device.inputWriteOwner === writeOwner,
-            onFailClosed: reason => {
-                if (device.inputWriteOwner !== writeOwner
-                    || device.inputSocket !== socket
-                    || device.inputSocketConnectionId !== inputSocketConnectionId) {
-                    return;
-                }
-                device.inputWriteOwner = null;
-                device.inputSocket = null;
-                device.inputSocketConnectionId = '';
+            onFailClosed: reason => {
+                if (device.inputWriteOwner !== writeOwner
+                    || device.inputSocket !== socket
+                    || device.inputSocketConnectionId !== inputSocketConnectionId) {
+                    return;
+                }
+                clearPendingDedicatedInputAcks(device);
+                device.inputWriteOwner = null;
+                device.inputSocket = null;
+                device.inputSocketConnectionId = '';
                 device.inputOwnerConnectionId = '';
                 device.inputOwnerBindingKey = '';
                 inputSockets.delete(socket);
-                device.inputLastSeenAt = new Date().toISOString();
-                emitRemoteEvent('RemoteInputSocketDisconnected', device, { reason });
-            }
-        });
+                device.inputLastSeenAt = new Date().toISOString();
+                emitRemoteEvent('RemoteInputSocketDisconnected', device, { reason });
+            },
+            onAcknowledgedWrite: (message, bindingKey) => {
+                if (device.inputWriteOwner !== writeOwner
+                    || device.inputSocket !== socket
+                    || device.inputSocketConnectionId !== inputSocketConnectionId) {
+                    return;
+                }
+                const pending = message?.payload && typeof message.payload === 'object'
+                    ? message.payload
+                    : message;
+                schedulePendingDedicatedInputAck(device, {
+                    ...pending,
+                    inputSocketConnectionId,
+                    bindingKey
+                });
+            }
+        });
         device.inputWriteOwner = writeOwner;
 
         emitRemoteEvent('RemoteInputSocketConnected', device);
@@ -5392,7 +5426,7 @@ export function createRemoteHub(options = {}) {
         return failed;
     }
 
-    function ensurePendingInputFallbacks(device) {
+    function ensurePendingInputFallbacks(device) {
         if (!(device?.pendingInputFallbacks instanceof Map)) {
             Object.defineProperty(device, 'pendingInputFallbacks', {
                 value: new Map(),
@@ -5409,8 +5443,151 @@ export function createRemoteHub(options = {}) {
                 writable: true
             });
         }
-        return device.pendingInputFallbacks;
-    }
+        return device.pendingInputFallbacks;
+    }
+
+    function ensurePendingDedicatedInputAckState(device) {
+        if (!device?.pendingDedicatedInputAckState) {
+            Object.defineProperty(device, 'pendingDedicatedInputAckState', {
+                value: { current: null, next: null, timeoutTimer: null },
+                enumerable: false,
+                configurable: true,
+                writable: true
+            });
+        }
+        return device.pendingDedicatedInputAckState;
+    }
+
+    function clearPendingDedicatedInputAcks(device) {
+        if (!device?.pendingDedicatedInputAckState) {
+            return;
+        }
+        const state = device.pendingDedicatedInputAckState;
+        if (state.timeoutTimer) {
+            clearTimeout(state.timeoutTimer);
+        }
+        state.timeoutTimer = null;
+        state.current = null;
+        state.next = null;
+    }
+
+    function dedicatedInputAckMatches(pending, message = {}) {
+        if (!pending) {
+            return false;
+        }
+        const result = message?.result && typeof message.result === 'object'
+            ? message.result
+            : {};
+        const inputEventId = safeString(
+            message.inputEventId
+            || message.InputEventId
+            || result.inputEventId
+            || result.InputEventId,
+            128);
+        const hubConnectionId = safeString(
+            message.hubConnectionId
+            || message.HubConnectionId
+            || result.hubConnectionId
+            || result.HubConnectionId,
+            128);
+        const inputSeq = Number(
+            message.inputSeq
+            ?? message.InputSeq
+            ?? result.inputSeq
+            ?? result.InputSeq
+            ?? 0) || 0;
+        if (pending.inputEventId && inputEventId) {
+            return pending.inputEventId === inputEventId
+                && pending.hubConnectionId === hubConnectionId;
+        }
+        return pending.inputSeq > 0
+            && pending.inputSeq === inputSeq
+            && pending.hubConnectionId === hubConnectionId;
+    }
+
+    function armPendingDedicatedInputAck(device) {
+        const state = ensurePendingDedicatedInputAckState(device);
+        if (state.timeoutTimer) {
+            clearTimeout(state.timeoutTimer);
+            state.timeoutTimer = null;
+        }
+        const pending = state.current;
+        if (!pending) {
+            return;
+        }
+        const remainingMs = Math.max(0, pending.deadlineAtEpochMs - Date.now());
+        state.timeoutTimer = setTimeout(() => {
+            state.timeoutTimer = null;
+            if (state.current !== pending) {
+                return;
+            }
+            state.current = null;
+            state.next = null;
+            if (device.inputSocketConnectionId !== pending.inputSocketConnectionId) {
+                return;
+            }
+            emitRemoteInputError(
+                device,
+                { error: 'remote-input-timeout' },
+                pending,
+                'remote-input-timeout');
+            closeInputSocket(device, 'input-ack-timeout');
+        }, remainingMs);
+        state.timeoutTimer.unref?.();
+    }
+
+    function schedulePendingDedicatedInputAck(device, pending) {
+        if (pending?.requestAck !== true
+            || !Number.isSafeInteger(pending.inputSeq)
+            || pending.inputSeq <= 0) {
+            return;
+        }
+        const state = ensurePendingDedicatedInputAckState(device);
+        const record = {
+            ...pending,
+            deadlineAtEpochMs: Date.now() + inputAckTimeoutMs
+        };
+        if (!state.current) {
+            state.current = record;
+            state.next = null;
+            armPendingDedicatedInputAck(device);
+            return;
+        }
+        if (state.current.inputSocketConnectionId !== record.inputSocketConnectionId
+            || state.current.bindingKey !== record.bindingKey) {
+            clearPendingDedicatedInputAcks(device);
+            state.current = record;
+            armPendingDedicatedInputAck(device);
+            return;
+        }
+        // Keep only one later checkpoint. If the current acknowledgement
+        // arrives, this latest sampled input becomes the next exact deadline.
+        state.next = record;
+    }
+
+    function acknowledgePendingDedicatedInput(device, message = {}) {
+        const state = device?.pendingDedicatedInputAckState;
+        if (!state?.current) {
+            return false;
+        }
+        if (dedicatedInputAckMatches(state.current, message)) {
+            if (state.timeoutTimer) {
+                clearTimeout(state.timeoutTimer);
+                state.timeoutTimer = null;
+            }
+            state.current = state.next;
+            state.next = null;
+            armPendingDedicatedInputAck(device);
+            return true;
+        }
+        if (dedicatedInputAckMatches(state.next, message)) {
+            // A later ordered acknowledgement proves that the input reader is
+            // still draining, even if an earlier diagnostic response vanished.
+            clearPendingDedicatedInputAcks(device);
+            return true;
+        }
+        return false;
+    }
 
     function pruneCompletedInputFallbacks(device, now = Date.now()) {
         ensurePendingInputFallbacks(device);
@@ -5611,11 +5788,17 @@ export function createRemoteHub(options = {}) {
         });
     }
 
-    function emitRemoteInputError(device, message = {}, pending = null, fallbackError = 'remote-input-failed') {
-        const outcome = buildRemoteInputOutcome(device, message, pending);
-        emitEvent('RemoteInputError', {
-            ...outcome,
-            error: safeString(
+    function emitRemoteInputError(
+        device,
+        message = {},
+        pending = null,
+        fallbackError = 'remote-input-failed',
+        errorKind = 'route') {
+        const outcome = buildRemoteInputOutcome(device, message, pending);
+        emitEvent('RemoteInputError', {
+            ...outcome,
+            errorKind: errorKind === 'native-apply' ? 'native-apply' : 'route',
+            error: safeString(
                 message.error
                 || message.Error
                 || message.result?.error
@@ -5645,9 +5828,9 @@ export function createRemoteHub(options = {}) {
         // session cannot acknowledge input from the current control session.
         if (!pending && source === 'main') {
             return false;
-        }
-        if (message.type === 'input.error') {
-            emitRemoteInputError(device, message, pending);
+        }
+        if (message.type === 'input.error') {
+            emitRemoteInputError(device, message, pending, 'remote-input-failed', 'native-apply');
         } else {
             emitRemoteInputApplied(device, message, pending);
         }
@@ -5667,8 +5850,13 @@ export function createRemoteHub(options = {}) {
             || !!error
             || result.ok === false
             || safeString(result.status, 40).toLowerCase() === 'failed';
-        if (failed) {
-            emitRemoteInputError(device, { ...message, error: error || 'remote-input-failed' }, completed);
+        if (failed) {
+            emitRemoteInputError(
+                device,
+                { ...message, error: error || 'remote-input-failed' },
+                completed,
+                'remote-input-failed',
+                'native-apply');
         } else {
             emitRemoteInputApplied(device, message, completed);
         }
@@ -7866,10 +8054,14 @@ export function createRemoteHub(options = {}) {
             return;
         }
 
-        if (state.inputOnly) {
-            device.inputLastSeenAt = new Date().toISOString();
-            if (message.type === 'input.applied' || message.type === 'input.error') {
-                handleRemoteInputOutcome(device, {
+        if (state.inputOnly) {
+            if (device.inputSocket !== socket) {
+                return;
+            }
+            device.inputLastSeenAt = new Date().toISOString();
+            if (message.type === 'input.applied' || message.type === 'input.error') {
+                acknowledgePendingDedicatedInput(device, message);
+                handleRemoteInputOutcome(device, {
                     ...message,
                     agentApplyMs: Number(message.agentApplyMs || 0) || 0
                 }, 'input');
@@ -9265,9 +9457,10 @@ export function createRemoteHub(options = {}) {
                 && normalized.hubConnectionId !== previousOwnerConnectionId;
             const bindingChanged = previousInputBindingKey
                 && previousInputBindingKey !== activeInputBindingKey;
-            const writeBindingChanged = inputWriteOwner.getBindingKey() !== activeInputBindingKey;
-            if (ownerChanged || bindingChanged || writeBindingChanged) {
-                if (ownerChanged) {
+            const writeBindingChanged = inputWriteOwner.getBindingKey() !== activeInputBindingKey;
+            if (ownerChanged || bindingChanged || writeBindingChanged) {
+                clearPendingDedicatedInputAcks(device);
+                if (ownerChanged) {
                     clearClipboardOperationsForDevice(
                         device,
                         'browser-input-owner-changed',
@@ -9292,11 +9485,12 @@ export function createRemoteHub(options = {}) {
                     return { ok: false, error: 'INPUT_CHANNEL_RECONNECTING' };
                 }
             }
-            const sent = inputWriteOwner.enqueue({
-                type: 'input.control',
-                payload: {
-                    ...normalized,
-                    hubForwardedAtEpochMs: Date.now(),
+            const hubForwardedAtEpochMs = Date.now();
+            const sent = inputWriteOwner.enqueue({
+                type: 'input.control',
+                payload: {
+                    ...normalized,
+                    hubForwardedAtEpochMs,
                     issuedAt: normalized.issuedAt || new Date().toISOString()
                 }
             }, activeInputBindingKey);
@@ -9304,10 +9498,10 @@ export function createRemoteHub(options = {}) {
                 if (normalized.hubConnectionId) {
                     device.inputOwnerConnectionId = normalized.hubConnectionId;
                 }
-                device.inputOwnerBindingKey = activeInputBindingKey;
-                device.counters.commandsSent += 1;
-                device.inputLastSeenAt = new Date().toISOString();
-                if (clipboardOperationKey) {
+                device.inputOwnerBindingKey = activeInputBindingKey;
+                device.counters.commandsSent += 1;
+                device.inputLastSeenAt = new Date().toISOString();
+                if (clipboardOperationKey) {
                     const operation = clipboardOperations.get(clipboardOperationKey);
                     if (operation) {
                         operation.status = 'pasting';
@@ -9397,7 +9591,8 @@ export function createRemoteHub(options = {}) {
             return { ok: false, error: 'input-owner-not-current' };
         }
 
-        clearClipboardOperationsForDevice(device, reason, owner);
+        clearClipboardOperationsForDevice(device, reason, owner);
+        clearPendingDedicatedInputAcks(device);
         device.inputOwnerConnectionId = '';
         device.inputOwnerBindingKey = '';
         const inputSocket = device.inputSocket;

package/src/server.js

@@ -5927,13 +5927,13 @@ inputWss.on('connection', ws => {
     try {
       payload = JSON.parse(Buffer.isBuffer(data) ? data.toString('utf8') : String(data || ''));
     } catch {
-      sendJson(ws, { type: 'RemoteInputError', error: 'invalid-json' });
+      sendJson(ws, { type: 'RemoteInputError', errorKind: 'route', error: 'invalid-json' });
       return;
     }
     const deviceId = String(payload?.deviceId || '').trim();
     if (payload?.type === 'watch') {
       if (!deviceId) {
-        sendJson(ws, { type: 'RemoteInputError', error: 'device-id-required' });
+        sendJson(ws, { type: 'RemoteInputError', errorKind: 'route', error: 'device-id-required' });
         return;
       }
       for (const previousDeviceId of ws.liveDeskInputDeviceIds) {
@@ -5970,7 +5970,8 @@ inputWss.on('connection', ws => {
       return;
     }
     sendJson(ws, {
-      type: result?.ok ? 'RemoteInputQueued' : 'RemoteInputError',
+      type: result?.ok ? 'RemoteInputQueued' : 'RemoteInputError',
+      errorKind: result?.ok ? '' : 'route',
       requestId: payload?.requestId || '',
       deviceId,
       inputSeq: Number(input?.inputSeq || 0) || 0,