anear-js-api 0.4.1 → 0.4.3

package/lib/api/AnearApi.js

@@ -46,7 +46,7 @@ class AnearApi extends ApiService {
       const json = await this.post("transitions", {event_name: eventName}, relationships)
       const attrs = json.data.attributes
       logger.info(`API: newState is ${attrs.state}`)
-      return json
+      return attrs
     } catch(err) {
       logger.error(err)
     }

package/lib/index.js

@@ -2,7 +2,8 @@
 
 const JsonApiResource = require('./models/JsonApiResource')
 const JsonApiArrayResource = require('./models/JsonApiArrayResource')
-const {AnearEvent, logger} = require('./models/AnearEvent')
+const AnearEvent = require('./models/AnearEvent')
+const logger = require('./utils/Logger')
 const AnearParticipant = require('./models/AnearParticipant')
 const AnearMessaging = require('./messaging/AnearMessaging')
 const AnearApiService = require('./api/ApiService')

package/lib/messaging/AnearMessaging.js

@@ -1,9 +1,7 @@
 "use strict"
 const Ably = require('ably/promises')
 const AnearApi = require('../api/AnearApi')
-const ParticipantTimer = require('../utils/ParticipantTimer')
 const logger = require('../utils/Logger')
-const { Mutex } = require('async-mutex')
 
 const AppId = process.env.ANEARAPP_APP_ID
 
@@ -29,7 +27,6 @@ class AnearMessaging {
     this.api = new AnearApi()
     this.AnearEventClass = AnearEventClass
     this.AnearParticipantClass = AnearParticipantClass
-    this.mutex = new Mutex()
     this.anearEvents = {}
 
     const baseUrl          = this.api.api_base_url
@@ -53,7 +50,6 @@ class AnearMessaging {
     }
 
     this.eventChannels = {}
-    this.participantTimers = {}
 
     this.initRealtime(clientOptions)
   }
@@ -85,76 +81,12 @@ class AnearMessaging {
     return this.realtime.channels.get(channelName, channelParams)
   }
 
-  ensureParticipantTimer(anearEvent, participant, timeoutMsecs) {
-    // this is called when a new timer is being started for a privateMessage
-    // sent to a participant, or public message to all participants
-    // If the timer already exists and is paused, it is resumed with the timeRemaining
-    // [a starter function, timeRemaining] is returned 
-    let timeRemaining = timeoutMsecs
-    let timerStarter = () => {}
-
-    if (timeoutMsecs > 0) {
-      const timer = this.participantTimers[participant.id] || this.createTimer(anearEvent, participant, timeoutMsecs)
-
-      if (timer.isRunning) {
-        timeRemaining = timer.interrupt()
-      } else {
-        timerStarter = () => timer.start(timeoutMsecs)
-      }
-    }
-    logger.debug(`ensureParticipantTimer(timeRemaining: ${timeRemaining})`)
-
-    return [timerStarter, timeRemaining]
-  }
-
-  createTimer(anearEvent, participant, timeoutMsecs) {
-    const timer = new ParticipantTimer(
-      participant.id,
-      async () => await this.timerExpired(anearEvent, participant, timeoutMsecs)
-    )
-    this.participantTimers[participant.id] = timer
-
-    return timer
-  }
-
-  destroyParticipantTimer(participantId) {
-    // participant will not be receiving any more display messages
-    // so we close out and delete the ParticipantTimer
-    const timer = this.participantTimers[participantId]
-
-    if (timer) {
-      timer.reset()
-      delete this.participantTimers[participantId]
-    }
-  }
-
-  interruptParticipantTimer(participantId) {
-    const timer = this.participantTimers[participantId]
-
-    if (timer && timer.isRunning) timer.interrupt()
-  }
-
-  resetParticipantTimer(participantId) {
-    // called after participant takes Action before timer expires
-    const timer = this.participantTimers[participantId]
-    if (timer) timer.reset()
-  }
-
-  async timerExpired(anearEvent, participant, timeoutMsecs) {
-    logger.debug(`participant (${anearEvent.id}, ${participant.id}) TIMED OUT after ${timeoutMsecs} msecs`)
-
-    delete this.participantTimers[participant.id]
-
-    await anearEvent.participantTimedOut(participant)
-    await anearEvent.update()
-  }
-
   async getAnearEventFromStorage(eventId) {
     return await this.AnearEventClass.getFromStorage(eventId, this)
   }
 
   async getAnearParticipantFromStorage(participantId) {
-    return await this.AnearParticipantClass.getFromStorage(participantId)
+    return await this.AnearParticipantClass.getFromStorage(participantId, this)
   }
 
   async initEventRealtimeMessaging(anearEvent) {
@@ -195,41 +127,35 @@ class AnearMessaging {
       // if we are getting this event create message from history after a quick restart,
       // we just return if the event already exists
       //
-      await this.loadOrPersistEventAndInitialize(anearEvent)
-
-    } catch(err) {
-      logger.error(err)
-    }
-  }
-
-  async loadOrPersistEventAndInitialize(anearEvent) {
-    const eventExists = await anearEvent.exists()
+      const eventExists = await anearEvent.exists()
+
+      logger.info(`Event ${anearEvent.id} ${eventExists ? "already exists" : "does not exist"} in Storage`)
+
+      let loadedEvent = anearEvent
+
+      if (!eventExists) {
+        await anearEvent.runExclusive(`createEventCallback ${anearEvent.id}`, async () => {
+          await anearEvent.createdEventCallback()
+          await anearEvent.persist()
+          // start the state machine before initialiing Realtime Messaging
+          // as REFRESH events come in and the state machine should be ready
+          // to handle those XState events
+          anearEvent.startStateMachine()
+          await this.initEventRealtimeMessaging(anearEvent)
+        })
+      } else {
+        loadedEvent = await this.getAnearEventFromStorage(anearEvent.id)
+        await this.initEventRealtimeMessaging(loadedEvent)
+        loadedEvent.startStateMachine()
+      }
 
-    logger.info(`Event ${anearEvent.id} ${eventExists ? "already exists" : "does not exist"} in Storage`)
+      logger.info(`New ${loadedEvent.constructor.name} Event: `, loadedEvent.toJSON())
 
-    let loadedEvent = anearEvent
+      this.anearEvents[loadedEvent.id] = loadedEvent
 
-    if (!eventExists) {
-      await this.runExclusive("createEventCallback", async () => {
-        await anearEvent.createdEventCallback()
-        await anearEvent.persist()
-        // start the state machine before initialiing Realtime Messaging
-        // as REFRESH events come in and the state machine should be ready
-        // to handle those XState events
-        anearEvent.startStateMachine()
-        await this.initEventRealtimeMessaging(anearEvent)
-      })
-    } else {
-      loadedEvent = await this.getAnearEventFromStorage(anearEvent.id)
-      await this.initEventRealtimeMessaging(loadedEvent)
-      loadedEvent.startStateMachine()
+    } catch(err) {
+      logger.error(err)
     }
-
-    logger.info(`New ${loadedEvent.constructor.name} Event: `, loadedEvent.toJSON())
-
-    this.anearEvents[loadedEvent.id] = loadedEvent
-
-    return loadedEvent
   }
 
   async reloadAnyEventsInProgress(appId) {
@@ -242,11 +168,16 @@ class AnearMessaging {
         for (const eventData of events) {
           const eventJson = await this.api.getEvent(eventData.id)
           const anearEvent = new this.AnearEventClass(eventJson, this)
-          // THIS does NOT work yet.  This is logic that restarte events in progress
-          // if the nodeJS process crahsed during play
+          await this.initEventRealtimeMessaging(anearEvent)
+
+          const attachedParticipants = this.getPresentParticipants(anearEvent)
+          // TBD: might want to change the attach and presence logic on
+          // the actions channel.   The Ably docs show subscribing to the
+          // presence events on the actions channel, and instead of using History,
+          // it does a get() to fetch all of the current members.   This behavior
+          // is useful for both event start, and event restart within this function
+          // anearEvent.startStateMachine()
           //
-          // const loadedEvent = await this.loadOrPersistEventAndInitialize(anearEvent)
-          // await this.refreshActiveParticipants(loadedEvent) DOES NOT WORK YET
         }
       }
     } catch (err) {
@@ -254,20 +185,6 @@ class AnearMessaging {
     }
   }
 
-  async refreshActiveParticipants(anearEvent) {
-    const allParticipants = anearEvent.participants.active
-
-    return Promise.all(
-      allParticipants.map(
-        participant => this.processParticipantEnter(
-          anearEvent,
-          participant.id,
-          participant.geoLocation
-        )
-      )
-    )
-  }
-
   async setupCreateEventChannel() {
     logger.info(`attaching to channel ${AnearCreateEventChannelName}`)
 
@@ -307,6 +224,21 @@ class AnearMessaging {
     )
   }
 
+  async getSpectatorCount(anearEvent) {
+    if (!anearEvent.allowsSpectators()) return 0
+
+    const channel = this.eventChannels[anearEvent.id].spectators
+    const members = await channel.presence.get()
+    return members.length
+  }
+
+  async getPresentParticipants(anearEvent) {
+    // returns the participant presence data for each member who is present on
+    // the event's actions channel
+    const channel = this.eventChannels[anearEvent.id].actions
+    return await channel.presence.get()
+  }
+
   async setupActionsChannel(anearEvent) {
     const actionsChannel = this.getChannel(anearEvent.actionsChannelName())
 
@@ -372,7 +304,9 @@ class AnearMessaging {
     await this.closeParticipant(
       anearEvent,
       participantId,
-      (anearEvent, participant) => anearEvent.participantClose(participant)
+      async (anearEvent, participant) => {
+        await anearEvent.participantExit(participant)
+      }
     )
   }
 
@@ -391,7 +325,7 @@ class AnearMessaging {
     await this.processParticipantEnter(anearEvent, participantId, geoLocation)
   }
 
-  async processParticipantEnter(anearEvent, participantId, geoLocation) {
+  async processParticipantEnter(anearEvent, participantId, geoLocation = null) {
 
     logger.debug(`processing Participant Enter for event: ${anearEvent.id}, participant: ${participantId}`)
     //
@@ -401,17 +335,17 @@ class AnearMessaging {
     //
     try {
       const participantJson = await this.api.getEventParticipantJson(participantId)
-      const participant = new this.AnearParticipantClass(participantJson)
+      const participant = new this.AnearParticipantClass(participantJson, anearEvent)
 
-      participant.geoLocation = geoLocation
-
-      const persistedAnearParticipant = await this.AnearParticipantClass.getFromStorage(participantId)
+      const persistedAnearParticipant = await this.AnearParticipantClass.getFromStorage(participantId, anearEvent)
 
       if (persistedAnearParticipant) {
         participant.context = persistedAnearParticipant.context
       }
 
-      await this.runExclusive("participantEnterCallback", async () => {
+      await anearEvent.runExclusive(`participantEnterCallback ${participant.id}`, async () => {
+        participant.geoLocation = geoLocation
+
         await this.setupPrivatePublishingChannel(participant)
         await anearEvent.participantEnter(participant)
         await anearEvent.update()
@@ -438,27 +372,32 @@ class AnearMessaging {
   }
 
   async participantLeaveMessagingCallback(anearEvent, message) {
-    // this can be just a temporary leave (refresh browser for example), so pause any participant timers
+    // this can be just a temporary leave from a participant refreshing their browser.
+    // currently, no action taken
     const userId = message.clientId
     const participantId = message.data.id
 
     logger.debug(`**** LEAVE PARTICIPANT ****  participantLeaveMessagingCallback(participant: ${participantId})`)
-
-    this.interruptParticipantTimer(participantId)
   }
 
-  async closeParticipant(anearEvent, participantId, callback) {
+  async closeParticipant(anearEvent, participantId, callback = null) {
+    // closes out a single Participant.   This is invoked when a single
+    // participant leaves an event, and the event may possibly continue,
+    // or possibly exit.  Or this may be called by the event when exiting
+    // and cleaning out any remaining participants.
     logger.debug(`closeParticipant(${participantId})`)
 
-    this.destroyParticipantTimer(participantId)
-
-    const participant = await this.getAnearParticipantFromStorage(participantId)
+    const participant = anearEvent.participants.getById(participantId)
 
     if (participant) {
+      participant.destroyTimer()
+
       await this.detachParticipantPrivateChannel(anearEvent.id, participant)
 
-      await this.runExclusive("closeParticipant", async () => {
-        await callback(anearEvent, participant)
+      await anearEvent.runExclusive(`closeParticipant ${participant.id}`, async () => {
+        if (callback) {
+          await callback(anearEvent, participant)
+        }
         await anearEvent.update()
       })
     }
@@ -487,16 +426,16 @@ class AnearMessaging {
     const participantId = message.data.participantId
     const payload = message.data.payload
 
-    this.resetParticipantTimer(participantId) // participant responded in time, reset any running timer
+    const participant = anearEvent.participants.getById(participantId)
+
+    participant.resetTimer() // participant responded in time, reset any running timer
 
     logger.debug(`participantActionMessagingCallback(${anearEvent.id}, ${participantId})`)
 
     const actionJSON = JSON.parse(payload)
     const [actionEventName, actionPayload] = Object.entries(actionJSON)[0]
 
-    const participant = await this.getAnearParticipantFromStorage(participantId)
-
-    await this.runExclusive("participantActionCallback", async () => {
+    await anearEvent.runExclusive(`participantActionCallback ${participant.id}`, async () => {
       await anearEvent.participantAction(participant, actionEventName, actionPayload)
       await anearEvent.update()
       await participant.update()
@@ -526,18 +465,6 @@ class AnearMessaging {
     }
   }
 
-  async runExclusive(name, callback) {
-    logger.debug(`waiting for ${name} mutex`)
-
-    await this.mutex.runExclusive(
-      async () => {
-        logger.debug(`mutex ${name} locked!`)
-        await callback()
-      }
-    )
-    logger.debug(`mutex ${name} released!`)
-  }
-
   subscribeEventMessages(channel, messageType, callback) {
     channel.subscribe(messageType, callback)
     logger.debug(`subscribed to ${messageType} messages on ${channel.name}`)
@@ -579,14 +506,14 @@ class AnearMessaging {
     )
   }
 
-  setMultipleParticipantTimers(anearEvent, participants, timeoutMsecs) {
+  setMultipleParticipantTimers(participants, timeoutMsecs) {
     if (timeoutMsecs === 0) return [() => {}, 0]
 
     const participantTimers = []
 
     participants.forEach(
       participant => {
-        const [startTimer, _timeRemaining] = this.ensureParticipantTimer(anearEvent, participant, timeoutMsecs)
+        const [startTimer, _timeRemaining] = participant.ensureTimer(timeoutMsecs)
         participantTimers.push(startTimer)
       }
     )
@@ -598,7 +525,7 @@ class AnearMessaging {
     const eventId = anearEvent.id
     const channel = this.eventChannels[eventId].participants
 
-    const [startTimers, timeRemaining] = this.setMultipleParticipantTimers(eventId, participants, timeoutMsecs)
+    const [startTimers, timeRemaining] = this.setMultipleParticipantTimers(participants, timeoutMsecs)
 
     await this.publishMessage(
       channel,
@@ -623,7 +550,7 @@ class AnearMessaging {
     const channel = this.eventChannels[anearEvent.id].privates[userId]
     if (!channel) throw new Error(`private channel not found.  invalid user id ${userId}`)
 
-    const [startTimer, timeRemaining] = this.ensureParticipantTimer(anearEvent, participant, timeoutMsecs)
+    const [startTimer, timeRemaining] = participant.ensureTimer(timeoutMsecs)
 
     await this.publishMessage(
       channel,
@@ -659,10 +586,9 @@ class AnearMessaging {
     )
   }
 
-  async publishEventTransitionMessage(anearEvent, eventJson) {
+  async publishEventTransitionMessage(anearEvent, newState) {
     const channel = this.eventChannels[anearEvent.id].events
-    const newState = eventJson.attributes.state
-    const payload = {content: {state: newState, event: eventJson}}
+    const payload = {content: {state: newState}}
 
     logger.debug(`publishEventTransitionMessage: event ${anearEvent.id} transitioning to ${newState}`)
 

package/lib/messaging/__mocks__/AnearMessaging.js

@@ -13,6 +13,10 @@ class AnearMessaging {
   async publishEventTransitionMessage(eventId, newState, callback) {
     return
   }
+
+  resetAllParticipantTimers() {
+    return
+  }
 }
 
 module.exports = AnearMessaging

package/lib/models/AnearEvent.js

@@ -1,5 +1,7 @@
 "use strict"
 
+const { Mutex } = require('async-mutex')
+
 const AnearXstate = require('../utils/AnearXstate')
 const { DefaultConfigFunc, DefaultOptionsFunc } = require('../utils/AnearXstateDefaults')
 
@@ -13,19 +15,19 @@ class AnearEvent extends JsonApiResource {
 
   constructor(json, messaging) {
     super(json)
-
-    this.messaging = messaging
     this.zone = this.findIncluded(this.relationships.zone)
     this.app = this.findIncluded(this.zone.relationships.app)
-    this.participants = new Participants(json.participants)
+    this.messaging = messaging
     this.anearStateMachine = this.initStateMachine(json.previousState)
+    this.participants = new Participants(this, json.participants)
+    this.mutex = new Mutex()
   }
 
   toJSON() {
     return {
       ...super.toJSON(),
-      context: this.stateMachineContext,
       participants: this.participants.toJSON(),
+      context: this.stateMachineContext,
       previousState: this.anearStateMachine.currentState
     }
   }
@@ -120,6 +122,10 @@ class AnearEvent extends JsonApiResource {
     return !this.hasFlag("no_spectators")
   }
 
+  async spectatorCount() {
+    return await this.messaging.getSpectatorCount(this)
+  }
+
   async createdEventCallback(participantCreator) {
     // You may implement createdEventCallback() in your AnearEvent sub-class
   }
@@ -136,8 +142,8 @@ class AnearEvent extends JsonApiResource {
     // You may implement an async spectatorRefreshEventCallback() in your AnearEvent sub-class
   }
 
-  async participantCloseEventCallback(participant) {
-    throw new Error('You must implement an async participantCloseEventCallback() in your AnearEvent sub-class');
+  async participantExitEventCallback(participant) {
+    throw new Error('You must implement an async participantExitEventCallback() in your AnearEvent sub-class');
   }
 
   async participantActionEventCallback(participant, actionEventName, message) {
@@ -173,6 +179,18 @@ class AnearEvent extends JsonApiResource {
     )
   }
 
+  async runExclusive(name, callback) {
+    logger.debug(`waiting for ${name} mutex`)
+
+    await this.mutex.runExclusive(
+      async () => {
+        logger.debug(`mutex ${name} locked!`)
+        await callback()
+      }
+    )
+    logger.debug(`mutex ${name} released!`)
+  }
+
   async publishEventSpectatorsMessage(message) {
     await this.messaging.publishEventSpectatorsMessage(this, this.css, message)
   }
@@ -203,13 +221,13 @@ class AnearEvent extends JsonApiResource {
     if (this.participants.exists(participant)) {
       logger.info(`AnearEvent: participant ${participant.id} exists.  Refreshing...`)
 
-      this.participants.add(this, participant) // update the participants entry
+      this.participants.add(participant) // update the participants entry
 
       this.anearStateMachine.sendRefreshEvent({ participant })
 
       await participant.update()
     } else {
-      this.participants.add(this, participant) // add the participants entry
+      this.participants.add(participant) // add the participants entry
 
       this.anearStateMachine.sendJoinEvent({ participant })
 
@@ -217,11 +235,15 @@ class AnearEvent extends JsonApiResource {
     }
   }
 
-  async participantClose(participant) {
-    this.participants.purge(participant)
-
-    this.anearStateMachine.sendCloseEvent({ participant })
+  async participantExit(participant) {
+    // this informs the state machine that the participant has exited the event
+    // and removes that participant completely
+    this.anearStateMachine.sendParticipantExitEvent({ participant })
+    await this.participantPurge(participant)
+  }
 
+  async participantPurge(participant) {
+    this.participants.purge(participant)
     await participant.remove()
   }
 
@@ -250,11 +272,10 @@ class AnearEvent extends JsonApiResource {
     logger.debug(`AnearEvent: transitionEvent(${eventName})`)
 
     try {
-      const eventJson = await this.messaging.api.transitionEvent(this.id, eventName)
-      const newState = eventJson.attributes.state
-
-      await this.messaging.publishEventTransitionMessage(this, eventJson)
+      const responseAttributes = await this.messaging.api.transitionEvent(this.id, eventName)
+      const newState = responseAttributes.state
       this.attributes.state = newState
+      await this.messaging.publishEventTransitionMessage(this, newState)
     } catch(err) {
       logger.error(`AnearEvent: transitionEvent error: ${err}`)
     }
@@ -285,6 +306,33 @@ class AnearEvent extends JsonApiResource {
     await this.transitionEvent('cancel')
   }
 
+  async closeOutParticipants() {
+    // upon exiting the event, this will clean up any participants remaining
+    return Promise.all(
+      this.participants.all.map(
+        async p => {
+          await this.messaging.closeParticipant(
+            this,
+            p.id,
+            async (anearEvent, participant) => {
+              await anearEvent.participantPurge(participant)
+            }
+          )
+        }
+      )
+    )
+  }
+
+  async purgeParticipants() {
+    // remove participants from Participants class and from Storage
+    const all = this.participants.all
+    if (this.participants.host) all.push(this.participants.host)
+
+    await Promise.all(
+      all.map(p => this.participantPurge(p))
+    )
+  }
+
   eventChannelName () {
     return this.getChannelName('event')
   }
@@ -305,6 +353,11 @@ class AnearEvent extends JsonApiResource {
     return this.attributes[`${key}-channel-name`]
   }
 
+  async closeEvent() {
+    await this.closeOutParticipants()
+    await this.closeMessaging()
+  }
+
   async closeMessaging () {
     await this.messaging.detachAll(this.id)
   }
@@ -318,7 +371,4 @@ class AnearEvent extends JsonApiResource {
   }
 }
 
-module.exports = {
-  AnearEvent,
-  logger
-}
+module.exports = AnearEvent