anear-js-api 0.4.31 → 0.4.34

package/.env.test

@@ -1,7 +1,7 @@
 # connects with the machtest developer account
-ANEARAPP_API_KEY=a197d1e4da2bfd4bb5d85ca82553f14f4fad2c5c650c25f49c8514eb80ef4fe1
+ANEARAPP_API_KEY=abacdeaiefibiefieghtereijief
 ANEARAPP_API_VERSION=v1
-ANEARAPP_APP_ID=e64a78d8-48f5-44f7-8b89-af2d6977a8c2
+ANEARAPP_APP_ID=e6da7818-4825d43f7-8979-e1ad6977a8c2
 ANEARAPP_LOGGER_FILE=logs/development.log
 ANEARAPP_LOGGER_LEVEL=debug
 ANEARAPP_ABLY_LOG_LEVEL=2

package/lib/state_machines/AnearCoreServiceMachine.js

@@ -129,7 +129,9 @@ const AnearCoreServiceMachineConfig = appId => ({
           actions: ['startNewEventMachine']
         },
         EVENT_MACHINE_EXIT: {
-          actions: ['cleanupEventMachine']
+          actions: [
+            'cleanupEventMachine'
+          ]
         }
       }
     },
@@ -161,9 +163,6 @@ const AnearCoreServiceMachineFunctions = {
       return uploader.uploadCss()
     }
   },
-  delays: {
-    retry_with_backoff_delay: (context, event) => context.retryDelay
-  },
   actions: {
     updateContextWithMachineRef: assign(
       {
@@ -228,14 +227,18 @@ const AnearCoreServiceMachineFunctions = {
         }
       }
     ),
-    cleanupEventMachine: assign({
-      anearEventMachines: (context, event) => {
-        const { [event.eventId]: dropped, ...remaining } = context.anearEventMachines
-        logger.debug(`AEM ${event.eventId} is ${dropped ? "done → cleaning up" : "NOT FOUND"}`)
-        return remaining
+    cleanupEventMachine: assign((context, event) => {
+      const { [event.eventId]: dropped, ...remaining } = context.anearEventMachines
+      logger.debug(`ACSM ${event.eventId} is ${dropped ? "done → cleaning up" : "NOT FOUND"}`)
+
+      return {
+        anearEventMachines: remaining
       }
     })
   },
+  delays: {
+    retry_with_backoff_delay: (context, event) => context.retryDelay
+  },
   guards: {
     noImageAssetFilesFound: (_, event) => event.data === null
   }

package/lib/state_machines/AnearEventMachine.js

@@ -63,6 +63,8 @@ const AnearEventMachineContext = (
   }
 )
 
+const MinuteMsecs = minutes => minutes * (60 * 1000)
+
 const DeferredStates = [
   // do not process these if they arrive during an unresolved
   // invoke Promise service
@@ -181,12 +183,18 @@ const ActiveEventStatesConfig = {
       ],
       on: {
         RENDER_DISPLAY: {
-          target: '.rendering'
+          target: '#createdRendering'
         }
       },
       states: {
         waitingAnnounce: {
           id: 'waitingAnnounce',
+          after: {
+            timeoutEventAnnounce: {
+              actions: context => logger.info(`Event ${context.anearEvent.id} TIMED OUT waiting for ANNOUNCE`),
+              target: '#canceled'
+            }
+          },
           on: {
             ANNOUNCE: {
               target: '#activeEvent.announce'
@@ -196,7 +204,8 @@ const ActiveEventStatesConfig = {
             }
           }
         },
-        rendering: {
+        createdRendering: {
+          id: 'createdRendering',
           deferred: DeferredStatesPlus('ANNOUNCE', 'START'),
           invoke: {
             src: 'renderDisplay',
@@ -220,7 +229,7 @@ const ActiveEventStatesConfig = {
       initial: 'transitioning',
       on: {
         RENDER_DISPLAY: {
-          target: '.rendering'
+          target: '#announceRendering'
         },
         PARTICIPANT_LEAVE: {
           // creator browser refresh or MIA.  Send disconnect events
@@ -231,19 +240,15 @@ const ActiveEventStatesConfig = {
             // a participant could re-entering the event after above PARTICIPANT_LEAVE (browser refresh).
             // so look for existing participants and send reconnect events to interested machines
             cond: 'participantExists',
-            actions: 'sendParticipantReconnectEvents',
-            target: '#waitingToStart',
-            internal: true
+            actions: 'sendParticipantReconnectEvents'
           },
           {
             // spectator clicked JOIN
-            target: '#newParticipant'
+            target: '#newParticipantJoining'
           }
         ],
         SPECTATOR_ENTER: {
-          actions: 'sendSpectatorEnterToAppEventMachine',
-          target: '#waitingToStart',
-          internal: true
+          actions: 'sendSpectatorEnterToAppEventMachine'
         }
       },
       states: {
@@ -266,13 +271,20 @@ const ActiveEventStatesConfig = {
         waitingToStart: {
           id: 'waitingToStart',
           entry: (c, e) => logger.debug("announce state...waiting for event START"),
+          after: {
+            timeoutEventStart: {
+              actions: context => logger.info(`Event ${context.anearEvent.id} TIMED OUT waiting for START`),
+              target: '#canceled'
+            }
+          },
           on: {
             START: {
               target: '#activeEvent.live'
             }
           }
         },
-        rendering: {
+        announceRendering: {
+          id: 'announceRendering',
           deferred: DeferredStatesPlus('START'),
           invoke: {
             src: 'renderDisplay',
@@ -285,30 +297,56 @@ const ActiveEventStatesConfig = {
             }
           }
         },
-        newParticipant: {
+        newParticipantJoining: {
           // a PARTICIPANT_ENTER received from a new user JOIN click. create an AnearParticipantMachine instance.
           // This machine tracks presence, geo-location (when approved by mobile participant),
           // manages active/idle state for long-running events, and manages any ACTION timeouts.
-          id: 'newParticipant',
+          id: 'newParticipantJoining',
           deferred: DeferredStatesPlus('START'),
           invoke: {
             src: 'fetchParticipantData',
             onDone: {
-              actions: [
-                'startNewParticipantMachine',
-                'sendParticipantEnterToAppEventMachine'
-              ],
-              target: '#waitingToStart',
+              actions: ['startNewParticipantMachine'],
+              target: '#waitParticipantReady'
             },
             onError: {
               target: '#activeEvent.failure'
             }
           }
+        },
+        waitParticipantReady: {
+          id: 'waitParticipantReady',
+          deferred: DeferredStatesPlus('START'),
+          on: {
+            PARTICIPANT_MACHINE_READY: {
+              actions: ['sendParticipantEnterToAppEventMachine'],
+              target: '#waitingToStart',
+              internal: true
+            }
+          }
         }
       }
     },
     live: {
       initial: 'transitioning',
+      on: {
+        RENDER_DISPLAY: {
+          target: '#liveRendering'
+        },
+        SPECTATOR_ENTER: {
+          actions: 'sendSpectatorEnterToAppEventMachine'
+        },
+        PARTICIPANT_LEAVE: {
+          // mid-event browser refresh or MIA.  Send disconnect events
+          actions: ['sendParticipantDisconnectEvents']
+        },
+        PARTICIPANT_TIMEOUT: {
+          // TBD: A participant(s) who was required to take a click action has
+          // failed to do so
+        },
+        PAUSE: '#activeEvent.paused', // Currently no use-case for these
+        CLOSE: '#activeEvent.closed'
+      },
       states: {
         transitioning: {
           deferred: DeferredStates,
@@ -325,8 +363,72 @@ const ActiveEventStatesConfig = {
         waitingForActions: {
           id: 'waitingForActions',
           on: {
-            PAUSE: '#activeEvent.paused',
-            CLOSE: '#activeEvent.closed'
+            PARTICIPANT_ENTER: [
+              {
+                // a participant could re-entering the event after above PARTICIPANT_LEAVE (browser refresh).
+                // so look for existing participants and send reconnect events to interested machines
+                cond: 'participantExists',
+                actions: 'sendParticipantReconnectEvents'
+              },
+              {
+                // in the future, open house events allow spectators to join and leave freely
+                // during live.waitingForActions
+                cond: 'isOpenHouseEvent',
+                target: 'participantEntering'
+              },
+              {
+                // shouldn't receive these so log it and return to current state
+                actions: [(c, e) => logger.info("Error: Unexepected PARTICIPANT_ENTER")],
+                target: '#activeEvent.failure'
+              }
+            ],
+            ACTION: {
+              // A participant has clicked an anear-data-action
+              actions: ['processParticipantAction']
+            }
+          }
+        },
+        liveRendering: {
+          id: 'liveRendering',
+          deferred: DeferredStates,
+          invoke: {
+            src: 'renderDisplay',
+            onDone: {
+              target: '#waitingForActions',
+              internal: true
+            },
+            onError: {
+              target: '#activeEvent.failure'
+            }
+          }
+        },
+        participantEntering: {
+          // a PARTICIPANT_ENTER received from a new user JOIN click. Unless already exists,
+          // create an AnearParticipantMachine instance.
+          // This machine tracks presence, geo-location (when approved by mobile participant),
+          // manages active/idle state for long-running events, and manages any ACTION timeouts.
+          id: 'participantEntering',
+          deferred: DeferredStates,
+          invoke: {
+            src: 'fetchParticipantData',
+            onDone: {
+              actions: ['startNewParticipantMachine'],
+              target: '#waitParticipantJoined',
+            },
+            onError: {
+              target: '#activeEvent.failure'
+            }
+          }
+        },
+        waitParticipantJoined: {
+          id: 'waitParticipantJoined',
+          deferred: DeferredStates,
+          on: {
+            PARTICIPANT_MACHINE_READY: {
+              actions: ['sendParticipantEnterToAppEventMachine'],
+              target: '#waitingForActions',
+              internal: true
+            }
           }
         }
       }
@@ -685,6 +787,9 @@ const AnearEventMachineFunctions = ({
     sendParticipantEnterToAppEventMachine: (context, event) => {
       const { anearParticipant } = event.data
       const participantInfo = context.participants[anearParticipant.id]
+
+      logger.debug(`Participant machine ${participantInfo.id} is READY`)
+
       const startEvent = { participant: participantInfo }
 
       context.appEventMachine.send('PARTICIPANT_ENTER', startEvent)
@@ -786,7 +891,7 @@ const AnearEventMachineFunctions = ({
       }
     }),
     notifyCoreServiceMachineExit: context => {
-      logger.debug("sending EVENT_MACHINE_EXIT to ACSM")
+      logger.debug("sending EVENT_MACHINE_EXIT to coreServiceMachine")
       context.coreServiceMachine.send('EVENT_MACHINE_EXIT', {eventId: context.anearEvent.id})
     }
   },
@@ -860,7 +965,14 @@ const AnearEventMachineFunctions = ({
   },
   guards: {
     participantExists: (context, event) => !!context.participants[event.data.id],
-    eventCreatorIsHost: (context, event) => context.anearEvent.hosted
+    eventCreatorIsHost: (context, event) => context.anearEvent.hosted,
+    isOpenHouseEvent: (context, event) => false // TODO: need to have App open_house trait exposed in anear api
+  },
+  delays: {
+    // in the future, these delays should be goverened by the type of App and
+    // if there has been activity.
+    timeoutEventAnnounce: context => MinuteMsecs(C.TIMEOUT_MINUTES.ANNOUNCE),
+    timeoutEventStart: context => MinuteMsecs(C.TIMEOUT_MINUTES.START)
   }
 })
 

package/lib/utils/Constants.js

@@ -6,5 +6,9 @@ module.exports = {
   SpectatorPresenceEvents: ['enter'],
   ImagesDirPath: 'assets/images',
   CssDirPath: 'assets/css',
-  PugSuffix: '.pug'
+  PugSuffix: '.pug',
+  TIMEOUT_MINUTES: {
+    START: 60, // 1 hour
+    ANNOUNCE: 120 // 2 hours
+  }
 }

package/lib/utils/DisplayEventProcessor.js

@@ -4,15 +4,17 @@
  * Pug templates receive the following context at render:
  *
  * {
- *   displayType:       // 'participants' | 'spectators' | 'participant'
- *   context:           // AppEventMachine's XState context for this transition
- *   state:             // Stringified state name (e.g., 'live.registration.waitForOpponentToJoin')
- *   event:             // The triggering event for this transition
- *   participants:      // Map of all participants for this event
+ *   app: application XState context
+ *   meta: {
+ *     viewer:  // 'participant', 'participants', 'spectators'
+ *     state:   // Stringified state name (e.g., 'live.registration.waitForOpponentToJoin')
+ *     event:   // The triggering event for this transition ('PARTICIPANT_ENTER')
+ *     timeout: // null|| { msecs:, [participantId:]}
+ *   }
  *
  *   // When 'participant' displayType
- *   participant        // current participant
- *   participantContext // current participant private context if AppParticipantMachine
+ *   participants: // all: Map of all participants [info, context] for this event,  get(id) => info, context
+ *   participant:  // info, context
  *
  *   // PLUS all helpers from PugHelpers:
  *   cdnImg(filename)  // Resolves CDN image path
@@ -37,18 +39,28 @@ class DisplayEventProcessor {
   constructor(anearEventMachineContext) {
     this.pugTemplates = anearEventMachineContext.pugTemplates
     this.pugHelpers = anearEventMachineContext.pugHelpers
-    this.participants = anearEventMachineContext.participants
     this.participantMachines = anearEventMachineContext.participantMachines
     this.participantsDisplayChannel = anearEventMachineContext.participantsDisplayChannel
     this.spectatorsDisplayChannel = anearEventMachineContext.spectatorsDisplayChannel
+    this.participantsIndex = this._buildParticipantsIndex(anearEventMachineContext.participants)
   }
 
   processAndPublish(displayEvents) {
     return Promise.all(displayEvents.map(event => this._processSingle(event)))
   }
 
+  _buildParticipantsIndex(participants) {
+    const participantStructs = Object.fromEntries(
+      Object.entries(participants).map(([id, info]) => [ id, { info, context: null } ])
+    )
+    const all = Object.values(participantStructs)
+
+    return { all, get: id => participantStructs[id] }
+  }
+
   _processSingle(displayEvent) {
-    const { displayType, viewPath, timeout, appExecutionContext } = displayEvent
+    const { viewPath, appRenderContext } = displayEvent
+    const timeout = appRenderContext.meta.timeout
 
     const normalizedPath = viewPath.endsWith(C.PugSuffix) ? viewPath : `${viewPath}${C.PugSuffix}`
     const template = this.pugTemplates[normalizedPath]
@@ -57,61 +69,58 @@ class DisplayEventProcessor {
       throw new Error(`Template not found: ${normalizedPath}`)
     }
 
-    const renderContext = {
-      displayType,
-      ...appExecutionContext,
-      participants: this.participants,
+    const templateRenderContext = {
+      ...appRenderContext,
+      participants: this.participantsIndex,
       ...this.pugHelpers
     }
 
-    const renderedContent = template(renderContext)
-    const message = { content: renderedContent }
-    if (timeout) message.timeout = timeout
-
-    switch (displayType) {
+    switch (appRenderContext.meta.viewer) {
       case 'participants':
         logger.debug(`[DisplayEventProcessor] Publishing PARTICIPANTS_DISPLAY`)
+
         return RealtimeMessaging.publish(
           this.participantsDisplayChannel,
           'PARTICIPANTS_DISPLAY',
-          message.content
+          template(templateRenderContext)
         )
 
       case 'spectators':
         logger.debug(`[DisplayEventProcessor] Publishing SPECTATORS_DISPLAY`)
+
         return RealtimeMessaging.publish(
           this.spectatorsDisplayChannel,
           'SPECTATORS_DISPLAY',
-          message.content
+          template(templateRenderContext)
         )
 
       case 'participant':
         logger.debug(`[DisplayEventProcessor] Processing RENDER_DISPLAY for each participant`)
-        return this._processPrivateParticipantDisplays(template, renderContext, timeout)
+        return this._processPrivateParticipantDisplays(template, templateRenderContext, timeout)
 
       default:
-        throw new Error(`Unknown displayType: ${displayType}`)
+        throw new Error(`Unknown meta.viewer: ${appRenderContext.meta.viewer}`)
     }
   }
 
-  _processPrivateParticipantDisplays(template, renderContextBase, timeout) {
-    Object.values(this.participantMachines).forEach(participantMachine => {
-      const participantState = participantMachine.state
-      const { anearParticipant, appParticipantMachine } = participantState.context
-
-      const privateRenderContext = {
-        ...renderContextBase,
-        participant: anearParticipant.participantInfo,
-        participantContext: appParticipantMachine?.state?.context || {}
-      }
+  _processPrivateParticipantDisplays(template, templateRenderContext, timeout) {
+    Object.values(this.participantsIndex.all).forEach(
+      participantStruct => {
+        const participantId = participantStruct.info.id
+        const participantMachine = this.participantMachines[participantId]
+        const privateRenderContext = {
+          ...templateRenderContext,
+          participant: participantStruct
+        }
 
-      const privateHtml = template(privateRenderContext)
+        const privateHtml = template(privateRenderContext)
 
-      const renderMessage = { content: privateHtml }
-      if (timeout) renderMessage.timeout = timeout
+        const renderMessage = { content: privateHtml }
+        if (timeout) renderMessage.timeout = timeout
 
-      participantMachine.send('RENDER_DISPLAY', renderMessage)
-    })
+        participantMachine.send('RENDER_DISPLAY', renderMessage)
+      }
+    )
 
     return Promise.resolve()
   }

package/lib/utils/MetaProcessing.js

@@ -18,44 +18,47 @@ const MetaProcessing = (anearEvent) => {
 
     const appStateName = _stringifiedState(value)
 
-    const appExecutionContext = {
-      context: appContext,
-      state: appStateName,
-      event
-    }
+    const appRenderContext = (displayType, timeout = null) => (
+      {
+        app: appContext,
+        meta: {
+          state: appStateName,
+          event,
+          timeout,
+          viewer: displayType
+        }
+      }
+    )
 
     const displayEvents = []
 
     if (meta.participants) {
       const viewPath = _getViewPath(meta.participants)
-      const timeout = _buildTimeout(meta.participants.timeout, appExecutionContext)
-      displayEvents.push({
-        displayType: 'participants',
+      const timeout = _buildTimeout(meta.participants.timeout, appContext)
+      const displayEvent = {
         viewPath,
-        timeout,
-        appExecutionContext
-      })
+        appRenderContext: appRenderContext('participants', timeout)
+      }
+      displayEvents.push(displayEvent)
     }
 
     if (meta.participant) {
       const viewPath = _getViewPath(meta.participant)
-      const timeout = _buildTimeout(meta.participant.timeout, appExecutionContext)
-      displayEvents.push({
-        displayType: 'participant',
+      const timeout = _buildTimeout(meta.participant.timeout, appContext)
+      const displayEvent = {
         viewPath,
-        timeout,
-        appExecutionContext
-      })
+        appRenderContext: appRenderContext('participant', timeout)
+      }
+      displayEvents.push(displayEvent)
     }
 
     if (meta.spectators) {
       const viewPath = _getViewPath(meta.spectators)
-      displayEvents.push({
-        displayType: 'spectators',
+      const displayEvent = {
         viewPath,
-        timeout: null,
-        appExecutionContext
-      })
+        appRenderContext: appRenderContext('spectators')
+      }
+      displayEvents.push(displayEvent)
     }
 
     if (displayEvents.length > 0) {
@@ -72,11 +75,11 @@ const _getViewPath = (config) => {
   throw new Error(`Unknown meta format: ${JSON.stringify(config)}`)
 }
 
-const _buildTimeout = (timeoutConfig, appExecutionContext) => {
+const _buildTimeout = (timeoutConfig, appContext) => {
   if (!timeoutConfig) return null
 
   if (typeof timeoutConfig === 'function') {
-    const [msecs, participantId] = timeoutConfig(appExecutionContext)
+    const [msecs, participantId] = timeoutConfig(appContext)
     return { msecs, participantId }
   }
 

package/package.json

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