anear-js-api 0.3.4 → 0.3.7

package/lib/messaging/AnearMessaging.js

@@ -1,6 +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')
 
@@ -25,7 +26,6 @@ const AblyLogLevel = process.env.ANEARAPP_ABLY_LOG_LEVEL || 0 // 0 - no logging,
 const AnearCreateEventChannelName = `anear:${AppId}:e`
 
 class AnearMessaging {
-
   constructor(AnearEventClass, AnearParticipantClass) {
     this.api = new AnearApi()
     this.AnearEventClass = AnearEventClass
@@ -86,31 +86,64 @@ class AnearMessaging {
     return this.realtime.channels.get(channelName, channelParams)
   }
 
-  clearParticipantTimer(participantId) {
-    const timerId = this.participantTimers[participantId]
-    if (timerId) {
-      clearTimeout(timerId)
-      this.participantTimers[participantId] = null
+  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) {
+      let timer = this.participantTimers[participant.id] || createTimer(anearEvent, participant, timeoutMsecs)
+
+      if (timer.isPaused) {
+        timerRemaining = this.timeRemaining
+        timerStarter = () => timer.resume()
+      } else {
+        timerStarter = () => timer.start(timeoutMsecs)
+      }
     }
+    return [timerStarter, timeRemaining]
   }
 
-  setParticipantTimer(anearEvent, participant, timeoutMilliseconds) {
-    const participantId = participant.id
+  createTimer(anearEvent, participant, timeoutMsecs) {
+    const timer = new ParticipantTimer(
+      participant.id,
+      async () => await this.timerExpired(anearEvent, participant, timeoutMsecs)
+    )
+    this.participantTimers[participant.id] = timer
 
-    this.clearParticipantTimer(participantId)
+    return timer
+  }
 
-    if (timeoutMilliseconds === 0) return
+  destroyParticipantTimer(participantId) {
+    // participant will not be receiving any more display messages
+    // so we close out and delete the ParticipantTimer
+    const timer = this.participantTimers[participantId]
 
-    logger.debug(`setting ${timeoutMilliseconds} msec timer for event ${anearEvent.id}, participant ${participant.id}`)
+    if (timer) {
+      timer.reset()
+      delete this.participantTimers[participantId]
+    }
+  }
 
-    this.participantTimers[participantId] = setTimeout(
-      async () => await this.timerExpired(anearEvent, participant, timeoutMilliseconds),
-      timeoutMilliseconds
-    )
+  pauseParticipantTimer(participantId) {
+    const timer = this.participantTimers[particpantId]
+    
+    if (timer && timer.isRunning) timer.pause()
+  }
+
+  resetParticipantTimer(participantId) {
+    // called after participant takes Action before timer expires
+    const timer = this.participantTimers[particpantId]
+    if (timer) timer.reset()
   }
 
-  async timerExpired(anearEvent, participant, timeoutMilliseconds) {
-    logger.debug(`participant (${anearEvent.id}, ${participant.id}) TIMED OUT after ${timeoutMilliseconds} msecs`)
+  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()
@@ -222,7 +255,7 @@ class AnearMessaging {
   }
 
   async refreshActiveParticipants(anearEvent) {
-    const allParticipants = anearEvent.participants.active(false)
+    const allParticipants = anearEvent.participants.active
 
     return Promise.all(
       allParticipants.map(
@@ -406,12 +439,16 @@ class AnearMessaging {
     const participantId = message.data.participantId
 
     logger.debug(`**** LEAVE PARTICIPANT ****  participantLeaveMessagingCallback(user: ${participantId})`)
+
+    // pause the participant timer if one was active.   The participant may return shortly
+    // and we can resume this timer
+    this.pauseParticipantTimer(participantId)
   }
 
   async closeParticipant(anearEvent, participantId, callback) {
     logger.debug(`closeParticipant(${participantId})`)
 
-    this.clearParticipantTimer(participantId)
+    this.destroyParticipantTimer(participantId)
 
     const participant = await this.getAnearParticipantFromStorage(participantId)
 
@@ -425,9 +462,8 @@ class AnearMessaging {
     }
   }
 
-  async detachParticipantPrivateChannel(anearEvent, participant) {
+  async detachParticipantPrivateChannel(eventId, participant) {
     const userId = participant.userId
-    const eventId = anearEvent.id
     const channel = this.eventChannels[eventId].privates[userId]
 
     if (channel) {
@@ -446,12 +482,12 @@ class AnearMessaging {
     //   actionEventName => "reviewResponse"
     //   actionPayload => {questionId: "ab88373ccf", decision:"approved"}
     //
-    const payload = message.data.payload
     const participantId = message.data.participantId
+    const payload = message.data.payload
 
-    logger.debug(`participantActionMessagingCallback(${anearEvent.id}, ${participantId})`)
+    this.resetParticipantTimer(participantId) // participant responded in time, reset any running timer
 
-    this.clearParticipantTimer(participantId)
+    logger.debug(`participantActionMessagingCallback(${anearEvent.id}, ${participantId})`)
 
     const actionJSON = JSON.parse(payload)
     const [actionEventName, actionPayload] = Object.entries(actionJSON)[0]
@@ -528,39 +564,46 @@ class AnearMessaging {
     }
   }
 
-  async publishEventParticipantsMessage(anearEvent, participants, css, message, timeoutMilliseconds=0, timeoutCallback=null) {
-    const eventId = anearEvent.id
-    const channel = this.eventChannels[eventId].participants
-
-    const setTimerFunction = () => this.setMultipleParticipantTimers(eventId, participants, timeoutMilliseconds)
+  async publishEventSpectatorsMessage(anearEvent, css, message, messageType = PublicDisplayMessageType) {
+    const channel = this.eventChannels[anearEvent.id].spectators
+    const payload = {
+      css: css,
+      content: message
+    }
 
-    await this.publishChannelMessageWithTimeout(
-      channel,
-      PublicDisplayMessageType,
-      css,
-      message,
-      timeoutMilliseconds,
-      setTimerFunction,
-      timeoutCallback
-    )
+    await this.publishChannelMessage(channel, messageType, payload)
   }
 
-  setMultipleParticipantTimers(anearEvent, participants, timeoutMilliseconds) {
-    if (timeoutMilliseconds === 0) return
+  setMultipleParticipantTimers(anearEvent, participants, timeoutMsecs) {
+    if (timeoutMsecs === 0) return [() => {}, 0]
+
+    const participantTimers = []
 
     participants.forEach(
-      participant => this.setParticipantTimer(anearEvent, participant, timeoutMilliseconds)
+      participant => {
+        const [startTimer, _timeRemaining] = this.ensureParticipantTimer(anearEvent, participant, timeoutMsecs)
+        participantTimers.push(startTimer)
+      }
     )
+    const startTimers = () => participantTimers.forEach(startTimer => startTimer())
+    return [startTimers, timeoutMsecs]
   }
 
-  async publishEventSpectatorsMessage(anearEvent, css, message, messageType = PublicDisplayMessageType) {
-    const channel = this.eventChannels[anearEvent.id].spectators
-    const payload = {
-      css: css,
-      content: message
-    }
+  async publishEventParticipantsMessage(anearEvent, participants, css, message, timeoutMsecs=0) {
+    const eventId = anearEvent.id
+    const channel = this.eventChannels[eventId].participants
 
-    await this.publishChannelMessage(channel, messageType, payload)
+    const [startTimers, timeRemaining] = this.setMultipleParticipantTimers(eventId, participants, timeoutMsecs)
+
+    await this.publishMessage(
+      channel,
+      PublicDisplayMessageType,
+      css,
+      message,
+      timeoutMsecs,
+      timeRemaining
+    )
+    startTimers()
   }
 
   async publishEventPrivateMessage(
@@ -569,44 +612,37 @@ class AnearMessaging {
           messageType,
           css,
           message,
-          timeoutMilliseconds=0,
-          timeoutCallback=null) {
+          timeoutMsecs=0) {
 
     const userId = participant.userId
     const channel = this.eventChannels[anearEvent.id].privates[userId]
     if (!channel) throw new Error(`private channel not found.  invalid user id ${userId}`)
 
-    const setTimerFunction = () => this.setParticipantTimer(anearEvent, participant, timeoutMilliseconds)
+    const [startTimer, timeRemaining] = this.ensureParticipantTimer(anearEvent, participant, timeoutMsecs)
 
-    await this.publishChannelMessageWithTimeout(
+    await this.publishMessage(
       channel,
       messageType,
       css,
       message,
-      timeoutMilliseconds,
-      setTimerFunction,
-      timeoutCallback
+      timeoutMsecs,
+      timeRemaining
     )
+    startTimer()
   }
 
-  async publishChannelMessageWithTimeout(
+  async publishMessage(
           channel,
           messageType,
           css,
           message,
-          timeoutMilliseconds=0,
-          setTimerFunction,
-          timeoutCallback=null) {
-
-    const timerCallback = async () => {
-      if (timeoutMilliseconds > 0) setTimerFunction()
-      if (timeoutCallback) await timeoutCallback()
-    }
+          timeoutMsecs,
+          timeRemaining) {
 
     const payload = {
       css: css,
       content: message,
-      timeout: timeoutMilliseconds
+      timeout: { timeoutMsecs, timeRemaining }
     }
 
     await this.publishChannelMessage(
@@ -614,7 +650,6 @@ class AnearMessaging {
       messageType,
       payload
     )
-    await timerCallback()
   }
 
   async publishEventTransitionMessage(anearEvent, newState) {

package/lib/models/AnearEvent.js

@@ -128,7 +128,7 @@ class AnearEvent extends JsonApiResource {
     throw new Error('You must implement an async participantEnterEventCallback() in your AnearEvent sub-class');
   }
 
-  async participantRefreshEventCallback(participant) {
+  async participantRefreshEventCallback(participant, remainingTimeout = null) {
     // You may implement an async participantRefreshEventCallback() in your AnearEvent sub-class
   }
 
@@ -163,14 +163,13 @@ class AnearEvent extends JsonApiResource {
     await this.spectatorRefreshEventCallback()
   }
 
-  async publishEventParticipantsMessage(message, timeoutMilliseconds=0, timeoutCallback=null) {
+  async publishEventParticipantsMessage(message, timeoutMilliseconds=0) {
     await this.messaging.publishEventParticipantsMessage(
       this,
-      this.activeParticipants,
+      this.participants.active,
       this.css,
       message,
-      timeoutMilliseconds,
-      timeoutCallback
+      timeoutMilliseconds
     )
   }
 
@@ -178,15 +177,14 @@ class AnearEvent extends JsonApiResource {
     await this.messaging.publishEventSpectatorsMessage(this, this.css, message)
   }
 
-  async publishEventPrivateMessage(participant, message, timeoutMilliseconds=0, timeoutCallback=null) {
+  async publishEventPrivateMessage(participant, message, timeoutMilliseconds=0) {
     await this.messaging.publishEventPrivateMessage(
       this,
       participant,
       PrivateDisplayMessageType,
       this.css,
       message,
-      timeoutMilliseconds,
-      timeoutCallback
+      timeoutMilliseconds
     )
   }
 
@@ -252,7 +250,7 @@ class AnearEvent extends JsonApiResource {
     logger.debug(`AnearEvent: transitionEvent(${eventName})`)
 
     try {
-      const responseAttributes = await this.messaging.api.transitionEvent(this, eventName)
+      const responseAttributes = await this.messaging.api.transitionEvent(this.id, eventName)
       const newState = responseAttributes.state
       await this.messaging.publishEventTransitionMessage(this, newState)
     } catch(err) {

package/lib/utils/AnearXstateDefaults.js

@@ -94,7 +94,7 @@ const DefaultOptionsFunc = anearEvent => {
     },
     services: {
       joinEventHandler: (context, event) => anearEvent.participantEnterEventCallback(event.participant),
-      refreshEventHandler: (context, event) => anearEvent.participantRefreshEventCallback(event.participant),
+      refreshEventHandler: (context, event) => anearEvent.participantRefreshEventCallback(event.participant, event.remainingTimeout),
       closeEventHandler: (context, event) => anearEvent.participantCloseEventCallback(event.participant),
       timeoutEventHandler: (context, event) => anearEvent.participantTimedOutEventCallback(event.participant),
       actionEventHandler: (context, event) => anearEvent.participantActionEventCallback(event.participant, event.type, event.payload)

package/lib/utils/ParticipantTimer.js

@@ -0,0 +1,87 @@
+"use strict"
+
+const logger = require('./Logger')
+
+const Off = "off"
+const Running = "running"
+const Paused = "paused"
+const Expired = "expired"
+
+class ParticipantTimer {
+  constructor(participantId, expireCallback) {
+    this.participantId = participantId
+    this.expireCallback = expireCallback
+
+    this.turnOff()
+  }
+  
+  start(timeoutMsecs, now = Date.now()) {
+    this.startedAt = now
+    logger.debug(`starting ${timeoutMsecs} msec timer for participant ${this.participantId}`)
+    this.runTimer(timeoutMsecs)
+  }
+
+  runTimer(timeoutMsecs) {
+    const timerExpired = () => {
+      this.state = Expired
+      this.expireCallback()
+    }
+    this.state = Running
+    this.id = setTimeout(timerExpired, timeoutMsecs)
+  }
+
+  pause(now = Date.now()) {
+    // if running, stop the timer
+    if (!this.isRunning) throw new Error("timer not running")
+
+    clearTimeout(this.id)
+    this.id = null
+    this.timeRemaining = now - this.startedAt
+
+    logger.debug(`pausing timer for participant ${this.participantId}. Time remaining: ${this.timeRemaining}`)
+    this.state = Paused
+  }
+
+  resume() {
+    // if paused, restarts the timer with the timeRemaining
+    if (!this.isPaused) throw new Error("timer not paused")
+
+    if (this.timeRemaining > 0) {
+      logger.debug(`resuming ${this.timeRemaining} msec timer for participant ${this.participantId}`)
+      this.runTimer(this.timeRemaining)
+    }
+  }
+
+  reset() {
+    // if running, stops the timer and/or sets the timer state to Off
+    logger.debug(`resetting timer for participant ${this.participantId}`)
+
+    if (this.id) clearTimeout(this.id)
+
+    this.turnOff()
+  }
+
+  turnOff() {
+    this.id = null
+    this.state = Off
+    this.startedAt = null
+  }
+
+  get isRunning() {
+    return this.state === Running
+  }
+
+  get isPaused() {
+    return this.state === Paused
+  }
+
+  get isOff() {
+    return this.state === Off
+  }
+
+  get isExpired() {
+    return this.state === Expired
+  }
+}
+
+module.exports = ParticipantTimer

package/lib/utils/Participants.js

@@ -132,6 +132,8 @@ class Participants {
       this._host = rec
     } else {
       this._participants[anearParticipant.id] = rec
+      anearParticipant.timestamp = this.currentTimestamp
+      anearParticipant.state = ActiveState
     }
     return rec
   }

package/package.json

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

package/tests/ParticipantTimer.test.js

@@ -0,0 +1,49 @@
+"use strict"
+
+const ParticipantTimer = require('../lib/utils/ParticipantTimer')
+const ParticipantId = "machvee"
+const Now = Date.now()
+
+jest.useFakeTimers();
+
+afterEach(() => jest.clearAllTimers)
+
+test('constructor with callback basic usage', () => {
+  const callback = jest.fn()
+  const t = new ParticipantTimer(ParticipantId, callback)
+  expect(t).toBeDefined()
+  expect(t.isRunning).toBe(false)
+  expect(t.isPaused).toBe(false)
+  t.start(500, Now)
+  expect(t.isRunning).toBe(true)
+  jest.runAllTimers()
+  expect(callback).toHaveBeenCalledTimes(1)
+  expect(t.isExpired).toBe(true)
+})
+
+test('start and then pause does not invoke callback', () => {
+  const callback = jest.fn()
+  const t = new ParticipantTimer(ParticipantId, callback)
+  t.start(1000, Now)
+  jest.advanceTimersByTime(500);
+  t.pause(Now + 500)
+  expect(t.isPaused).toBe(true)
+  expect(t.timeRemaining).toEqual(500)
+  jest.advanceTimersByTime(501);
+  expect(callback).toHaveBeenCalledTimes(0)
+  expect(t.isPaused).toBe(true)
+})
+
+test('start, pause, then resume', () => {
+  const callback = jest.fn()
+  const t = new ParticipantTimer(ParticipantId, callback)
+  t.start(1000, Now)
+  jest.advanceTimersByTime(500);
+  t.pause(Now + 500)
+  expect(t.isPaused).toBe(true)
+  expect(t.timeRemaining).toEqual(500)
+
+  t.resume(Now + 1001)
+  jest.advanceTimersByTime(501);
+  expect(callback).toHaveBeenCalledTimes(1)
+})