anear-js-api 1.4.4 → 1.5.1

package/lib/state_machines/AnearCoreServiceMachine.js

@@ -61,6 +61,24 @@ const C = require('../utils/Constants')
 const CreateEventChannelNameTemplate = appId => `anear:${appId}:e`
 const DefaultTemplatesRootDir = "./views"
 
+// Process-wide signal handling.
+// We install exactly once per process to avoid duplicate handlers in reconnect/restart scenarios.
+let _sigtermHandlerInstalled = false
+let _exitScheduled = false
+
+function scheduleExit(code, message) {
+  if (_exitScheduled) return
+  _exitScheduled = true
+
+  if (message) logger.info(`${message} (pid=${process.pid})`)
+
+  // Give file logger a moment to flush (simple-node-logger writes to a stream).
+  // `process.exit()` exits immediately and can drop buffered writes.
+  const delayMs = 200
+  process.exitCode = code
+  setTimeout(() => process.exit(code), delayMs)
+}
+
 const AnearCoreServiceMachineContext = (appId, appEventMachineFactory, appParticipantMachineFactory) => ({
   appId,
   appData: null,
@@ -71,6 +89,7 @@ const AnearCoreServiceMachineContext = (appId, appEventMachineFactory, appPartic
   imageAssetsUrl: null,
   fontAssetsUrl: null,
   newEventCreationChannel: null,
+  shutdownRequested: false,          // First SIGTERM received; stop accepting new events
   retryDelay: 0
 })
 
@@ -78,11 +97,22 @@ const AnearCoreServiceMachineConfig = appId => ({
   id: `AnearCoreServiceMachine_${appId}`,
   initial: 'fetchAppDataWithRetry',
   context: ({ input }) => input,
+  on: {
+    SIGTERM: {
+      actions: [
+        'logSigtermReceived',
+        'hardExitIfSecondSigterm',
+        'markShutdownRequested',
+        'detachCreateEventChannel',
+        'exitIfNoActiveEvents'
+      ]
+    }
+  },
   states: {
     fetchAppDataWithRetry: {
       entry: ({ context }) => {
         const appId = context.appId || process.env.ANEARAPP_APP_ID || 'unknown'
-        logger.info(`[ACSM] ===== Booting App (${appId}) on anear-js-api version ${anearJsApiVersion} =====`)
+        logger.info(`[ACSM] ===== Booting App (${appId}) on anear-js-api version ${anearJsApiVersion} pid=${process.pid} =====`)
       },
       initial: 'fetchAppData',
       states: {
@@ -113,9 +143,15 @@ const AnearCoreServiceMachineConfig = appId => ({
       id: 'initRealtimeMessaging',
       entry: ['initRealtime'],
       on: {
-        CONNECTED: {
-          actions: ['createEventsCreationChannel', 'subscribeCreateEventMessages', ({ context }) => logger.info(`[ACSM] Realtime messaging connected for app ${context.appId}`)]
-        },
+        CONNECTED: [
+          {
+            guard: 'acceptLifecycleCommands',
+            actions: ['createEventsCreationChannel', 'subscribeCreateEventMessages', ({ context }) => logger.info(`[ACSM] Realtime messaging connected for app ${context.appId}`)]
+          },
+          {
+            actions: ({ context }) => logger.warn(`[ACSM] Realtime connected, but shutdown already requested for app ${context.appId}; not subscribing to CREATE/LOAD commands`)
+          }
+        ],
         ATTACHED: 'uploadNewImageAssets'
       }
     },
@@ -177,15 +213,18 @@ const AnearCoreServiceMachineConfig = appId => ({
         logger.debug(`Waiting on ${shortName} lifecycle command`)
       },
       on: {
-        CREATE_EVENT: {
-          actions: ['startNewEventMachine']
-        },
-        LOAD_EVENT: {
-          actions: ['startNewEventMachine']
-        },
+        CREATE_EVENT: [
+          { guard: 'acceptLifecycleCommands', actions: ['startNewEventMachine'] },
+          { actions: ['logIgnoredLifecycleCommand'] }
+        ],
+        LOAD_EVENT: [
+          { guard: 'acceptLifecycleCommands', actions: ['startNewEventMachine'] },
+          { actions: ['logIgnoredLifecycleCommand'] }
+        ],
         EVENT_MACHINE_EXIT: {
           actions: [
-            'cleanupEventMachine'
+            'cleanupEventMachine',
+            'exitIfNoActiveEvents'
           ]
         }
       }
@@ -275,7 +314,82 @@ const AnearCoreServiceMachineFunctions = {
         self,
         'LOAD_EVENT'
       )
-      logger.info(`[ACSM] Subscribed to CREATE_EVENT and LOAD_EVENT on events channel`)
+      logger.info(`[ACSM] Subscribed to CREATE_EVENT and LOAD_EVENT on events channel (pid=${process.pid})`)
+    },
+    logIgnoredLifecycleCommand: ({ event, context }) => {
+      logger.warn(`[ACSM] Ignoring ${event.type} because shutdown has been requested (appId=${context.appId} pid=${process.pid})`)
+    },
+    logSigtermReceived: ({ context, event }) => {
+      const count = event?.data?.count || 1
+      const activeIds = Object.keys(context.anearEventMachines || {})
+      const activeCount = activeIds.length
+
+      if (count === 1) {
+        if (activeCount === 0) {
+          logger.info(`[ACSM] SIGTERM received: detaching create/load channel and exiting cleanly (no active events) (pid=${process.pid})`)
+        } else {
+          logger.info(`[ACSM] SIGTERM received: detaching create/load channel; stopping all CREATE_EVENT/LOAD_EVENT requests; waiting for ${activeCount} active event(s) to terminate (pid=${process.pid})`)
+        }
+      } else {
+        logger.warn(`[ACSM] SIGTERM received again (count=${count}) while shutdown in progress (pid=${process.pid})`)
+      }
+    },
+    hardExitIfSecondSigterm: ({ context, event }) => {
+      const count = event?.data?.count || 1
+      if (context.shutdownRequested && count >= 2) {
+        const activeIds = Object.keys(context.anearEventMachines || {})
+        const activeCount = activeIds.length
+        if (activeCount > 0) {
+          logger.warn(`[ACSM] Second SIGTERM received; forcing shutdown with ${activeCount} active event(s) still running (pid=${process.pid})`)
+        } else {
+          logger.warn(`[ACSM] Second SIGTERM received; forcing shutdown (pid=${process.pid})`)
+        }
+        // Hard exit: do not wait for cleanup.
+        process.exit(1)
+      }
+    },
+    markShutdownRequested: assign({
+      shutdownRequested: () => true
+    }),
+    detachCreateEventChannel: ({ context }) => {
+      const ch = context.newEventCreationChannel
+      if (!ch) {
+        logger.info(`[ACSM] SIGTERM received before create-event channel existed; nothing to detach yet (pid=${process.pid})`)
+        return
+      }
+
+      try {
+        // Unsubscribe message listeners to prevent CREATE/LOAD callbacks firing.
+        if (typeof ch.unsubscribe === 'function') {
+          ch.unsubscribe('CREATE_EVENT')
+          ch.unsubscribe('LOAD_EVENT')
+        }
+      } catch (e) {
+        logger.warn('[ACSM] Error unsubscribing create-event channel listeners', e)
+      }
+
+      try {
+        // Detach to stop receiving messages from Ably for this channel.
+        const maybePromise = ch.detach()
+        if (maybePromise && typeof maybePromise.catch === 'function') {
+          maybePromise.catch(e => logger.warn('[ACSM] Error detaching create-event channel', e))
+        }
+      } catch (e) {
+        logger.warn('[ACSM] Error detaching create-event channel', e)
+      }
+
+      logger.info(`[ACSM] Detached from create-event channel; will not create/load any more events (pid=${process.pid})`)
+    },
+    exitIfNoActiveEvents: ({ context }) => {
+      if (!context.shutdownRequested) return
+
+      const activeCount = Object.keys(context.anearEventMachines || {}).length
+      if (activeCount === 0) {
+        scheduleExit(
+          0,
+          '[ACSM] SIGTERM shutdown complete: no active events remaining; exiting cleanly'
+        )
+      }
     },
     startNewEventMachine: assign(
       {
@@ -321,7 +435,8 @@ const AnearCoreServiceMachineFunctions = {
     retry_with_backoff_delay: ({ context }) => context.retryDelay
   },
   guards: {
-    noImageAssetFilesFound: ({ event }) => event.output === null
+    noImageAssetFilesFound: ({ event }) => event.output === null,
+    acceptLifecycleCommands: ({ context }) => !context.shutdownRequested
   }
 }
 
@@ -337,7 +452,26 @@ const AnearCoreServiceMachine = (appEventMachineFactory, appParticipantMachineFa
 
   const coreServiceMachine = createMachine(machineConfig, AnearCoreServiceMachineFunctions)
 
-  return createActor(coreServiceMachine, { input: anearCoreServiceMachineContext }).start()
+  const actor = createActor(coreServiceMachine, { input: anearCoreServiceMachineContext }).start()
+
+  if (!_sigtermHandlerInstalled) {
+    _sigtermHandlerInstalled = true
+    let sigtermCount = 0
+    process.on('SIGTERM', () => {
+      sigtermCount += 1
+      try {
+        // Log at the point we definitely caught the signal (even if the actor is wedged).
+        // This should land in the same log file as ACSM startup logs.
+        logger.info(`[ACSM] process SIGTERM caught (count=${sigtermCount}) pid=${process.pid}`)
+        actor.send({ type: 'SIGTERM', data: { count: sigtermCount } })
+      } catch (e) {
+        // If actor is gone or send fails, fall back to hard exit on second signal.
+        if (sigtermCount >= 2) process.exit(1)
+      }
+    })
+  }
+
+  return actor
 }
 
 module.exports = AnearCoreServiceMachine

package/lib/state_machines/AnearParticipantMachine.js

@@ -111,6 +111,12 @@ const AnearParticipantMachineContext = (anearParticipant, anearEvent, appPartici
   actionTimeoutMsecs: null,
   actionTimeoutStart: null,
   capturedTimeoutMsecs: null, // Captured timeout value for logging before clearing
+  // If the AppM emits rapid successive RENDER_DISPLAY events (e.g. dealing animation),
+  // a participant may still be in the middle of publishing the prior PRIVATE_DISPLAY.
+  // Without buffering, any new RENDER_DISPLAY arriving while in `live.renderDisplay`
+  // would be dropped (no handler in that state). We keep the latest and flush it
+  // immediately after the current publish completes.
+  queuedRenderDisplay: null,
   lastSeen: CurrentDateTimestamp()
 })
 
@@ -235,16 +241,21 @@ const AnearParticipantMachineConfig = participantId => ({
                 src: 'publishPrivateDisplay',
                 input: ({ context, event }) => ({ context, event }),
                 onDone: [
-                  { guard: 'hasActionTimeout', actions: 'updateActionTimeout', target: 'waitParticipantResponse' },
+                  { guard: 'hasActionTimeout', actions: ['updateActionTimeout', 'sendQueuedRenderDisplayIfAny', 'clearQueuedRenderDisplay'], target: 'waitParticipantResponse' },
                   // If this display does not configure a timeout, explicitly clear any
                   // previously-running action timeout.
-                  { actions: 'nullActionTimeout', target: 'idle' }
+                  { actions: ['nullActionTimeout', 'sendQueuedRenderDisplayIfAny', 'clearQueuedRenderDisplay'], target: 'idle' }
                 ],
                 onError: {
                   target: '#error'
                 }
               },
               on: {
+                // Buffer the latest render request if we are currently publishing.
+                // (Otherwise, RENDER_DISPLAY is unhandled in this state and gets dropped.)
+                RENDER_DISPLAY: {
+                  actions: 'queueRenderDisplay'
+                },
                 PARTICIPANT_EXIT: {
                   actions: 'logExit',
                   target: '#cleanupAndExit'
@@ -625,6 +636,28 @@ const AnearParticipantMachineFunctions = {
       logger.error(`[APM] ⚠️  Only after timers are cancelled (APM transitions to idle) can new RENDER_DISPLAY with timeouts be issued.`)
       logger.error(`[APM] ⚠️  This ${eventType} event is being IGNORED to prevent timer conflicts.`)
     }
+    ,
+    queueRenderDisplay: assign(({ context, event }) => {
+      // Keep only the latest queued render display.
+      // Event shape is already { type: 'RENDER_DISPLAY', content, timeout? }.
+      const participantId = context?.anearParticipant?.id
+      const replaced = !!context?.queuedRenderDisplay
+      logger.debug(`[APM] queueing RENDER_DISPLAY for ${participantId}${replaced ? ' (replacing prior queued render)' : ''}`)
+      return { queuedRenderDisplay: event }
+    }),
+    sendQueuedRenderDisplayIfAny: ({ context, self }) => {
+      const queued = context.queuedRenderDisplay
+      if (queued && queued.type === 'RENDER_DISPLAY') {
+        const participantId = context?.anearParticipant?.id
+        logger.debug(`[APM] flushing queued RENDER_DISPLAY for ${participantId}`)
+        try {
+          self.send(queued)
+        } catch (_e) {
+          // Best-effort; never interrupt the publish completion path.
+        }
+      }
+    },
+    clearQueuedRenderDisplay: assign(() => ({ queuedRenderDisplay: null }))
   },
   actors: {
     publishPrivateDisplay: fromPromise(async ({ input }) => {

package/lib/utils/AppMachineTransition.js

@@ -23,6 +23,36 @@ const REFRESH_EVENT_TYPES = new Set([
   'HOST_UPDATE'
 ])
 
+// JSON.stringify can throw on circular structures / BigInt.
+// For render-dedupe signatures we want a stable-ish representation, not perfection.
+const _safeSignatureStringify = (value) => {
+  const seen = new WeakSet()
+  return JSON.stringify(value, (key, val) => {
+    // Drop known non-serializable / noisy keys if they appear in context objects.
+    // (These can sneak in via app context depending on app patterns.)
+    if (
+      key === 'anearEvent' ||
+      key === 'appEventMachine' ||
+      key === 'service' ||
+      key === 'actor' ||
+      key === 'self' ||
+      key === 'parent'
+    ) {
+      return undefined
+    }
+
+    if (typeof val === 'bigint') return String(val)
+    if (typeof val === 'function') return `[function:${val.name || 'anonymous'}]`
+
+    if (val && typeof val === 'object') {
+      if (seen.has(val)) return '[Circular]'
+      seen.add(val)
+    }
+
+    return val
+  })
+}
+
 /**
  * AppMachineTransition:
  *  - Runs inside your appEventMachine onTransition.
@@ -73,7 +103,7 @@ const AppMachineTransition = (anearEvent) => {
       //   re-rendering even if the AppM state didn't change.
       let baseSignature
       try {
-        baseSignature = JSON.stringify({ stateName, meta: rawMeta, context: appContext })
+        baseSignature = _safeSignatureStringify({ stateName, meta: rawMeta, context: appContext })
       } catch (_e) {
         baseSignature = `${stateName}|${rawMeta ? Object.keys(rawMeta).join(',') : ''}`
       }

package/lib/utils/RealtimeMessaging.js

@@ -130,7 +130,7 @@ class RealtimeMessaging {
   }
 
   getChannel(channelName, actor, channelParams = {}) {
-    logger.debug(`[RTM] creating channel ${channelName} for ${actor.id}`)
+    logger.debug(`[RTM] creating channel ${channelName} for ${actor.id} pid=${process.pid}`)
 
     const channel = this.ablyRealtime.channels.get(channelName, channelParams)
     this.enableCallbacks(channel, actor)
@@ -198,7 +198,7 @@ class RealtimeMessaging {
           const type = data.type ? data.type : 'NONE'
           const channelShortName = getChannelShortName(channel.name)
           const channelLabel = channelShortName === 'actions' ? 'actions:presence' : channelShortName
-          logger.info(`[RTM] received presence ${eventName} participantId=${data.id} on channel ${channelLabel}`)
+          logger.info(`[RTM] received presence ${eventName} participantId=${data.id} on channel ${channelLabel} pid=${process.pid} actor=${actor.id}`)
           actor.send({ type: eventName, data })
         }
       )
@@ -269,7 +269,7 @@ class RealtimeMessaging {
         const participantId = message.data?.participantId || null
         const participantIdStr = participantId ? ` participantId=${participantId}` : ''
         const channelShortName = getChannelShortName(channel.name)
-        logger.info(`[RTM] received message ${message.name}${participantIdStr} on channel ${channelShortName}`)
+        logger.info(`[RTM] received message ${message.name}${participantIdStr} on channel ${channelShortName} pid=${process.pid} actor=${actor.id}`)
         actor.send({ type: message.name, data: message.data })
       }
     )

package/package.json

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