anear-js-api 1.4.3 → 1.5.0

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/utils/AssetFileCollector.js

@@ -42,12 +42,14 @@ class AssetFileCollector {
         await this.walkDirectory(fullPath, filesData);
       } else if (entry.isFile()) {
         const relativePath = path.relative(this.baseDir, fullPath).replace(/\\/g, '/'); // Ensure forward slashes
+        const stat = await fs.stat(fullPath)
         const contentHash = await this.computeFileHash(fullPath);
         const contentType = this.getContentType(fullPath);
         filesData.push({
           path: relativePath,
           content_hash: contentHash,
           content_type: contentType,
+          mtime_ms: stat.mtimeMs,
         });
       }
     }

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.3",
+  "version": "1.5.0",
   "description": "Javascript Developer API for Anear Apps",
   "main": "lib/index.js",
   "scripts": {