anear-js-api 1.2.2 → 1.3.0

package/lib/state_machines/AnearEventMachine.js

@@ -166,7 +166,9 @@ const AnearEventMachineContext = (
   suppressParticipantTimeouts: false,  // Flag to suppress PARTICIPANT_TIMEOUT events (cleared when new timers are set up via render)
   eachParticipantCancelActionType: null,  // ACTION type that triggers cancellation for eachParticipant timeouts
   pendingCancelConfirmations: null,  // Set of participantIds waiting for TIMER_CANCELED confirmation
-  pendingCancelAction: null  // ACTION to forward after cancellation completes: { participantId, appEventName, payload }
+  pendingCancelAction: null,  // ACTION to forward after cancellation completes: { participantId, appEventName, payload }
+  consecutiveTimeoutCount: 0,  // Global counter tracking consecutive timeouts across all participants for dead-man switch
+  consecutiveAllParticipantsTimeoutCount: 0  // Counter tracking consecutive allParticipants timeouts where ALL participants timed out
 })
 
 const ActiveEventGlobalEvents = {
@@ -278,7 +280,7 @@ const ActiveEventStatesConfig = {
       ],
       on: {
         ACTION: {
-          actions: ['processParticipantAction']
+          actions: ['resetParticipantTimeoutCount', 'processParticipantAction']
         },
         RENDER_DISPLAY: {
           target: '#createdRendering'
@@ -447,7 +449,7 @@ const ActiveEventStatesConfig = {
       initial: 'transitioning',
       on: {
         ACTION: {
-          actions: ['processParticipantAction']
+          actions: ['resetParticipantTimeoutCount', 'processParticipantAction']
         },
         RENDER_DISPLAY: {
           target: '#announceRendering'
@@ -629,6 +631,11 @@ const ActiveEventStatesConfig = {
         },
         CANCEL_ALL_PARTICIPANT_TIMEOUTS: {
           actions: 'cancelAllParticipantTimeouts'
+        },
+        // Handle PARTICIPANT_TIMEOUT even when in liveRendering state
+        // (events bubble up from child states, so we need to handle them here)
+        PARTICIPANT_TIMEOUT: {
+          actions: ['trackParticipantTimeout', 'processParticipantTimeout']
         }
       },
       states: {
@@ -677,11 +684,11 @@ const ActiveEventStatesConfig = {
           },
           on: {
             ACTION: {
-              actions: ['processParticipantAction']
+              actions: ['resetParticipantTimeoutCount', 'processParticipantAction']
             },
             // Forward per-participant timeouts (from APM) to the AppM
             PARTICIPANT_TIMEOUT: {
-              actions: ['processParticipantTimeout'],
+              actions: ['trackParticipantTimeout', 'processParticipantTimeout'],
               // v5 note: internal transitions are the default (v4 had `internal: true`)
             },
             TRIGGER_CANCEL_SEQUENCE: {
@@ -735,7 +742,7 @@ const ActiveEventStatesConfig = {
           always: {
             guard: 'allParticipantsResponded',
             target: 'waitingForActions',
-            actions: ['clearParticipantsTimeout']
+            actions: ['sendActionsCompleteToAppM', 'clearParticipantsTimeout']
           },
           after: {
             participantsActionTimeout: {
@@ -794,7 +801,7 @@ const ActiveEventStatesConfig = {
                 target: 'handleParticipantsTimeoutCanceled'
               },
               {
-                actions: ['processAndForwardAction', 'processParticipantResponse'],
+                actions: ['resetParticipantTimeoutCount', 'processAndForwardAction', 'processParticipantResponse'],
                 // v5 note: internal transitions are the default (v4 had `internal: true`)
               }
             ],
@@ -1831,6 +1838,20 @@ const AnearEventMachineFunctions = ({
       const eventName = getPresenceEventName(participant, 'UPDATE');
       context.appEventMachine.send({ type: eventName, data: event.data });
     },
+    resetParticipantTimeoutCount: assign(({ context, event }) => {
+      const participantId = event.data.participantId
+      // Reset global consecutive timeout counts when ANY participant sends an action
+      const updates = {}
+      if (context.consecutiveTimeoutCount > 0) {
+        logger.debug(`[AEM] Resetting global timeout count from ${context.consecutiveTimeoutCount} to 0 (action received from ${participantId})`)
+        updates.consecutiveTimeoutCount = 0
+      }
+      if (context.consecutiveAllParticipantsTimeoutCount > 0) {
+        logger.debug(`[AEM] Resetting allParticipants timeout count from ${context.consecutiveAllParticipantsTimeoutCount} to 0 (action received from ${participantId})`)
+        updates.consecutiveAllParticipantsTimeoutCount = 0
+      }
+      return updates
+    }),
     processParticipantAction: ({ context, event, self }) => {
       // event.data.participantId,
       // event.data.payload: {"appEventMachineACTION": {action event keys and values}}
@@ -1916,7 +1937,18 @@ const AnearEventMachineFunctions = ({
         }
       }
     }),
-    processParticipantTimeout: ({ context, event }) => {
+    trackParticipantTimeout: assign(({ context, event }) => {
+      const participantId = event.participantId
+      const currentCount = context.consecutiveTimeoutCount || 0
+      const newCount = currentCount + 1
+
+      logger.debug(`[AEM] Global timeout count (any participant): ${currentCount} -> ${newCount} (timeout from ${participantId})`)
+
+      return {
+        consecutiveTimeoutCount: newCount
+      }
+    }),
+    processParticipantTimeout: ({ context, event, self }) => {
       // Suppress PARTICIPANT_TIMEOUT events after cancelAllParticipantTimeouts() until new timers
       // are set up via render. This handles race conditions where an APM's timer fires just
       // before receiving CANCEL_TIMEOUT. The flag is cleared when renders complete (new timers set up).
@@ -1924,7 +1956,20 @@ const AnearEventMachineFunctions = ({
         logger.debug(`[AEM] Suppressing PARTICIPANT_TIMEOUT from ${event.participantId} (cancelled timers, waiting for new render)`)
         return
       }
-      context.appEventMachine.send({ type: 'PARTICIPANT_TIMEOUT', participantId: event.participantId })
+
+      const participantId = event.participantId
+      const timeoutCount = context.consecutiveTimeoutCount || 0
+      const maxConsecutiveTimeouts = C.DEAD_MAN_SWITCH.MAX_CONSECUTIVE_PARTICIPANT_TIMEOUTS
+
+      // Check dead-man switch: if global consecutive timeout threshold reached, cancel event
+      // This detects when the game is "dead" (no actions happening) across all participants
+      if (timeoutCount >= maxConsecutiveTimeouts) {
+        logger.warn(`[AEM] Dead-man switch triggered: ${timeoutCount} consecutive timeouts across all participants (threshold: ${maxConsecutiveTimeouts}). Auto-canceling event.`)
+        self.send({ type: 'CANCEL' })
+        return
+      }
+
+      context.appEventMachine.send({ type: 'PARTICIPANT_TIMEOUT', participantId })
     },
     setupParticipantsTimeout: assign(({ context, event }) => {
       // Only set up a new timeout if one is provided by the display render workflow
@@ -2001,21 +2046,70 @@ const AnearEventMachineFunctions = ({
         }
       };
     }),
-    sendActionsTimeoutToAppM: ({ context }) => {
+    sendActionsCompleteToAppM: assign(({ context }) => {
+      // When all participants respond, the final ACTION already has finalAction: true
+      // No need to send a separate ACTIONS_COMPLETE event - the finalAction flag handles it
+      // Reset allParticipants timeout counter when all participants respond
+      if (context.consecutiveAllParticipantsTimeoutCount > 0) {
+        logger.debug(`[AEM] Resetting allParticipants timeout count from ${context.consecutiveAllParticipantsTimeoutCount} to 0 (all participants responded)`)
+        return { consecutiveAllParticipantsTimeoutCount: 0 }
+      }
+      return {}
+    }),
+    sendActionsTimeoutToAppM: assign(({ context, self }) => {
       const { nonResponders, msecs } = context.participantsActionTimeout
       const nonResponderIds = [...nonResponders]
+      const allActiveParticipantIds = getActiveParticipantIds(context)
+
       logger.info(`[AEM] allParticipants timeout expired after ${msecs}ms. Non-responders: ${nonResponderIds.join(', ')}`)
 
+      // Track consecutive allParticipants timeouts where ALL participants timed out
+      const allTimedOut = nonResponders.size === allActiveParticipantIds.length && allActiveParticipantIds.length > 0
+      const updates = {}
+
+      if (allTimedOut) {
+        const currentCount = context.consecutiveAllParticipantsTimeoutCount || 0
+        const newCount = currentCount + 1
+        logger.debug(`[AEM] All participants timed out in allParticipants timeout. Count: ${currentCount} -> ${newCount}`)
+        updates.consecutiveAllParticipantsTimeoutCount = newCount
+
+        // Dead-man switch: if 4 consecutive allParticipants timeouts where all timed out, cancel event
+        const maxConsecutiveTimeouts = C.DEAD_MAN_SWITCH.MAX_CONSECUTIVE_PARTICIPANT_TIMEOUTS
+        if (newCount >= maxConsecutiveTimeouts) {
+          logger.warn(`[AEM] Dead-man switch triggered: ${maxConsecutiveTimeouts} consecutive allParticipants timeouts where all participants timed out. Auto-canceling event.`)
+          self.send({ type: 'CANCEL' })
+          return updates
+        }
+      } else {
+        // Not all timed out - reset the counter
+        if (context.consecutiveAllParticipantsTimeoutCount > 0) {
+          logger.debug(`[AEM] Resetting allParticipants timeout count from ${context.consecutiveAllParticipantsTimeoutCount} to 0 (not all participants timed out)`)
+          updates.consecutiveAllParticipantsTimeoutCount = 0
+        }
+      }
+
       if (context.appEventMachine) {
+        // Send ACTIONS_TIMEOUT when timeout expires
+        logger.info(`[AEM] Sending ACTIONS_TIMEOUT (timeout expired)`)
         context.appEventMachine.send({ type: 'ACTIONS_TIMEOUT', timeout: msecs, nonResponderIds })
       }
-    },
+
+      return updates
+    }),
     sendActionsTimeoutToAppMCanceled: ({ context }) => {
       const { nonResponders, msecs } = context.participantsActionTimeout
       const nonResponderIds = [...nonResponders]
       logger.info(`[AEM] allParticipants timeout cancelled after ${msecs}ms. Non-responders at cancellation: ${nonResponderIds.join(', ')}`)
 
       if (context.appEventMachine) {
+        // Send ACTIONS_TIMEOUT when timeout is canceled (backward compatibility)
+        context.appEventMachine.send({
+          type: 'ACTIONS_TIMEOUT',
+          timeout: msecs,
+          nonResponderIds,
+          canceled: true
+        })
+        // Keep ACTIONS_TIMEOUT for backward compatibility (deprecated)
         context.appEventMachine.send({ type: 'ACTIONS_TIMEOUT', timeout: msecs, nonResponderIds, canceled: true })
       }
     },

package/lib/utils/Constants.js

@@ -16,6 +16,10 @@ module.exports = {
     RECONNECT: 30 * 1000, // 30 seconds
     BOOT_EXIT: 2 * 1000 // 5 seconds
   },
+  DEAD_MAN_SWITCH: {
+    // Maximum consecutive timeouts per participant before auto-canceling event
+    MAX_CONSECUTIVE_PARTICIPANT_TIMEOUTS: 4
+  },
   EventStates: {
     CREATED: 'created',
     STARTED: 'started',

package/lib/utils/DisplayEventProcessor.js

@@ -365,9 +365,20 @@ class DisplayEventProcessor {
     if (timeoutFn) {
       // For participant displays, any non-null / positive timeout value should
       // start a real per-participant timer on that participant's APM.
-      const msecs = timeoutFn(appCtx, participantStruct)
-      if (typeof msecs === 'number' && msecs > 0) {
-        timeout = msecs
+      if (!participantStruct) {
+        logger.warn(`[DisplayEventProcessor] Participant struct not found for ${participantId}, skipping timeout calculation`)
+      } else {
+        try {
+          const msecs = timeoutFn(appCtx, participantStruct)
+          if (typeof msecs === 'number' && msecs > 0) {
+            timeout = msecs
+          } else {
+            // Log when timeout function returns null/undefined to help diagnose issues
+            logger.debug(`[DisplayEventProcessor] Timeout function returned ${msecs === null ? 'null' : msecs === undefined ? 'undefined' : `non-numeric value: ${msecs}`} for ${participantId}`)
+          }
+        } catch (error) {
+          logger.warn(`[DisplayEventProcessor] Error calculating timeout for ${participantId}: ${error.message}`)
+        }
       }
     }
     const privateRenderContext = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anear-js-api",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "Javascript Developer API for Anear Apps",
   "main": "lib/index.js",
   "scripts": {